[Traits](https://oods-foundry.com/traits) / MarkBar

# MarkBar

Canonical rectangular mark for magnitude comparisons.

Generated from @oods/foundry 0.10.1

- Group

  viz.mark

- Maturity

  alpha

- Contexts

  dashboard, detail, form, list

Supports stacked or grouped categories and enforces RDS.7 accessibility requirements for redundant encodings.

## Fields it adds

| Field | Type | Required | Description |
| - | - | - | - |
| `viz_mark_type` | `string` (bar) | yes | Normalized mark identifier consumed by renderer adapters. |
| `viz_mark_orientation` | `string` (vertical, horizontal) | yes | Orientation flag for aligning axes and fallbacks. |
| `viz_mark_band_padding` | `number` | no | Fractional padding between bars within a category. |
| `viz_mark_corner_radius` | `number` | no | Corner radius applied to rendered bars. |
| `viz_mark_stacking` | `string` (auto, normalize, none) | no | Stacking semantics applied to grouped series. |
| `viz_mark_role` | `string` | yes | Semantic role used by heuristics, docs, and filtering. |
| `viz_mark_a11y_label` | `string` | yes | Accessible description fragment for assistive tech fallbacks. |

## What it shows in each context

- [detail](https://oods-foundry.com/contexts/detail)

  `VizMarkPreview`

- dashboard

  `VizMarkPreview`

- [form](https://oods-foundry.com/contexts/form)

  `VizMarkControls`

- [list](https://oods-foundry.com/contexts/list)

  `VizRoleBadge`

dashboard isn't one of the 7 contexts screens are composed in, so it has no page of its own here.

## Parameters

- `chart` `object`

  Optional read-only chart declaration binding existing domain fields; projects into supported detail and dashboard views.

- `title` `string`

  Title for the bound chart and its accessible figure.

- `description` `string`

  Description of the bound chart measurements and units.

- `renderIntent` `string`

  JSON-encoded Cartesian viz.render input fragment for the governed authoring recipes. Data rows remain a consumer operand.

- `previewSvg` `string`

  Static SVG returned by viz.render for the authored sample; omitted until a chart is rendered.

- `orientation` `string`, required

  Axis orientation used for laying out bar rectangles.

- `bandPadding` `number`

  Fractional padding between category bands (0-0.5).

- `cornerRadius` `number`

  Pixel radius applied to bar corners.

- `stacking` `string`

  Aggregation strategy when multiple series share the mark.

## Objects that use it

- [Invoice](https://oods-foundry.com/objects/invoice)
- [Subscription](https://oods-foundry.com/objects/subscription)

## The trait file

`traits/viz/mark-bar.trait.yaml`

```
trait:
  name: MarkBar
  version: 0.2.0
  description: |
    Canonical rectangular mark for magnitude comparisons. Supports stacked
    or grouped categories and enforces RDS.7 accessibility requirements for
    redundant encodings.
  category: viz.mark
  tags:
    - viz
    - mark
    - bar
    - comparison

parameters:
  - {"name": "chart", "type": "object", "required": false, "description": "Optional read-only chart declaration binding existing domain fields; projects into supported detail and dashboard views."}
  - {"name": "title", "type": "string", "required": false, "description": "Title for the bound chart and its accessible figure."}
  - {"name": "description", "type": "string", "required": false, "description": "Description of the bound chart measurements and units."}
  - {"name": "renderIntent", "type": "string", "required": false, "default": "{}", "description": "JSON-encoded Cartesian viz.render input fragment for the governed authoring recipes. Data rows remain a consumer operand."}
  - {"name": "previewSvg", "type": "string", "required": false, "description": "Static SVG returned by viz.render for the authored sample; omitted until a chart is rendered."}
  - name: orientation
    type: string
    required: true
    description: Axis orientation used for laying out bar rectangles.
    default: vertical
    validation:
      enum:
        - vertical
        - horizontal
  - name: bandPadding
    type: number
    required: false
    description: Fractional padding between category bands (0-0.5).
    default: 0.1
    validation:
      minimum: 0
      maximum: 0.5
  - name: cornerRadius
    type: number
    required: false
    description: Pixel radius applied to bar corners.
    default: 2
    validation:
      minimum: 0
      maximum: 12
  - name: stacking
    type: string
    required: false
    description: Aggregation strategy when multiple series share the mark.
    default: auto
    validation:
      enum:
        - auto
        - normalize
        - none

schema:
  viz_mark_type:
    type: string
    required: true
    description: Normalized mark identifier consumed by renderer adapters.
    default: bar
    validation:
      enum:
        - bar
  viz_mark_orientation:
    type: string
    required: true
    description: Orientation flag for aligning axes and fallbacks.
    defaultFromParameter: orientation
    validation:
      enum:
        - vertical
        - horizontal
  viz_mark_band_padding:
    type: number
    required: false
    description: Fractional padding between bars within a category.
    defaultFromParameter: bandPadding
    validation:
      minimum: 0
      maximum: 0.5
  viz_mark_corner_radius:
    type: number
    required: false
    description: Corner radius applied to rendered bars.
    defaultFromParameter: cornerRadius
    validation:
      minimum: 0
      maximum: 12
  viz_mark_stacking:
    type: string
    required: false
    description: Stacking semantics applied to grouped series.
    defaultFromParameter: stacking
    validation:
      enum:
        - auto
        - normalize
        - none
  viz_mark_role:
    type: string
    required: true
    description: Semantic role used by heuristics, docs, and filtering.
    default: comparison
  viz_mark_a11y_label:
    type: string
    required: true
    description: Accessible description fragment for assistive tech fallbacks.
    default: Bar mark showing magnitude per category.

semantics:
  viz_mark_type:
    semantic_type: viz.mark.type
    token_mapping: tokenMap(viz.mark.type)
    ui_hints:
      component: VizMarkSummary
  viz_mark_orientation:
    semantic_type: viz.mark.orientation
    token_mapping: tokenMap(viz.mark.orientation)
    ui_hints:
      component: VizOrientationBadge
  viz_mark_band_padding:
    semantic_type: viz.mark.spacing
    token_mapping: tokenMap(viz.mark.spacing)
    ui_hints:
      component: NumericPreview
      unit: fraction
  viz_mark_corner_radius:
    semantic_type: viz.mark.corner_radius
    token_mapping: tokenMap(viz.mark.corner_radius)
    ui_hints:
      component: NumericPreview
      unit: px
  viz_mark_stacking:
    semantic_type: viz.mark.stacking
    token_mapping: tokenMap(viz.mark.stacking)
    ui_hints:
      component: VizStackingHint
  viz_mark_a11y_label:
    semantic_type: a11y.description
    token_mapping: tokenMap(a11y.chart.description)
    ui_hints:
      component: ScreenReaderHint

view_extensions:
  detail:
    - component: VizMarkPreview
      position: top
      priority: 60
      props:
        svgParameter: previewSvg
        typeField: viz_mark_type
        orientationField: viz_mark_orientation
        stackingField: viz_mark_stacking
  dashboard:
    - component: VizMarkPreview
      position: top
      priority: 60
      props:
        svgParameter: previewSvg
        typeField: viz_mark_type
        orientationField: viz_mark_orientation
        stackingField: viz_mark_stacking
  form:
    - component: VizMarkControls
      position: top
      props:
        intentParameter: renderIntent
        orientationField: viz_mark_orientation
        paddingField: viz_mark_band_padding
        stackingField: viz_mark_stacking
        cornerRadiusField: viz_mark_corner_radius
  list:
    - component: VizRoleBadge
      props:
        intentParameter: renderIntent
        labelField: viz_mark_role

tokens:
  # Primary fill color for bar rectangles — maps to the active palette
  viz.mark.bar.fill.default: "var(--cmp-viz-mark-bar-fill)"
  # Stroke outline for bar edges — provides contrast against adjacent bars
  viz.mark.bar.stroke.default: "var(--cmp-viz-mark-bar-stroke)"
  # Spacing token governing gap between category bands
  viz.mark.bar.spacing: "var(--cmp-viz-mark-spacing)"

events:
  mark.hovered:
    description: Fired when a bar is hovered. Payload includes datum values and bar index.
    payload: [datum, index, tone]
  mark.selected:
    description: Fired when a bar is clicked/tapped. Used by InteractionHighlight.
    payload: [datum, index]
  mark.focused:
    description: Fired when a bar receives keyboard focus for accessibility navigation.
    payload: [datum, index]

dependencies:
  - EncodingPositionX
  - EncodingPositionY

metadata:
  created: "2025-11-15"
  updated: "2026-02-28"
  owners:
    - viz@oods.systems
    - design@oods.systems
  maturity: alpha
  conflicts_with:
    - MarkLine
    - MarkPoint
    - MarkArea
  accessibility:
    rule_reference: A11Y-R-04
    notes: Requires redundant text/table fallback in paired specs.
  regionsUsed:
    - detail
    - dashboard
    - form
    - list
  examples:
    - RevenueByRegion
    - TicketVolumeByQueue
  references:
    - RDS.7 Trait-Driven Visualization System Specification (v0.1)
```