MarkArea

trait:
  name: MarkArea
  version: 0.2.0
  description: |
    Canonical area mark for cumulative totals and ranges. Fills the region
    between the series baseline and value curve with configurable opacity and
    interpolation.
  category: viz.mark
  tags:
    - viz
    - mark
    - area
    - band

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.", "default": "Payment amounts"}
  - {"name": "description", "type": "string", "required": false, "description": "Description of the bound chart measurements and units.", "default": "Values recorded for this record."}
  - {"name":"previewSvg","type":"string","required":false,"description":"Static SVG returned by viz.render for the authored sample."}
  - {"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: curve
    type: string
    required: false
    description: Curve interpolation strategy applied between samples.
    default: linear
    validation:
      enum:
        - linear
        - monotone
        - step
  - name: opacity
    type: number
    required: false
    description: Fill opacity used for the area band.
    default: 0.65
    validation:
      minimum: 0.2
      maximum: 1
  - name: baseline
    type: string
    required: false
    description: Baseline reference for filling the region (zero, min, or custom).
    default: zero
    validation:
      enum:
        - zero
        - min
  - name: tension
    type: number
    required: false
    description: Curve tension applied when using monotone interpolation.
    default: 0.3
    validation:
      minimum: 0
      maximum: 1

schema:
  viz_mark_type:
    type: string
    required: true
    description: Normalized mark identifier consumed by renderer adapters.
    default: area
    validation:
      enum:
        - area
  viz_area_curve:
    type: string
    required: false
    description: Interpolation strategy applied between samples.
    defaultFromParameter: curve
    validation:
      enum:
        - linear
        - monotone
        - step
  viz_area_opacity:
    type: number
    required: false
    description: Fill opacity used for the area band.
    defaultFromParameter: opacity
    validation:
      minimum: 0.2
      maximum: 1
  viz_area_baseline:
    type: string
    required: false
    description: Baseline reference for filling the region.
    defaultFromParameter: baseline
    validation:
      enum:
        - zero
        - min
  viz_area_tension:
    type: number
    required: false
    description: Curve tension applied when smoothing.
    defaultFromParameter: tension
    validation:
      minimum: 0
      maximum: 1
  viz_mark_role:
    type: string
    required: true
    description: Semantic role for heuristics and docs.
    default: band
  viz_mark_a11y_label:
    type: string
    required: true
    description: Accessible description fragment for describing area marks.
    default: Area mark representing cumulative or range-based values.

semantics:
  viz_mark_type:
    semantic_type: viz.mark.type
    token_mapping: tokenMap(viz.mark.type)
    ui_hints:
      component: VizMarkSummary
  viz_area_curve:
    semantic_type: viz.mark.curve
    token_mapping: tokenMap(viz.mark.curve)
    ui_hints:
      component: VizCurveHint
  viz_area_opacity:
    semantic_type: viz.mark.opacity
    token_mapping: tokenMap(viz.mark.opacity)
    ui_hints:
      component: NumericPreview
      unit: opacity
  viz_area_baseline:
    semantic_type: viz.mark.baseline
    token_mapping: tokenMap(viz.mark.baseline)
    ui_hints:
      component: TextBadge
  viz_mark_a11y_label:
    semantic_type: a11y.description
    token_mapping: tokenMap(a11y.chart.description)
    ui_hints:
      component: ScreenReaderHint

view_extensions:
  detail:
    - component: VizAreaPreview
      position: top
      priority: 55
      props:
        curveField: viz_area_curve
        opacityField: viz_area_opacity
        svgParameter: previewSvg
        baselineField: viz_area_baseline
  form:
    - component: VizAreaControls
      position: top
      props:
        intentParameter: renderIntent
        curveField: viz_area_curve
        opacityField: viz_area_opacity
        baselineField: viz_area_baseline
        tensionField: viz_area_tension
  list:
    - component: VizRoleBadge
      props:
        intentParameter: renderIntent
        labelField: viz_mark_role

tokens:
  # Fill color for the area band between baseline and value curve
  viz.mark.area.fill.default: "var(--cmp-viz-mark-area-fill)"
  # Default opacity for the filled region — semi-transparent to allow layering
  viz.mark.area.opacity.default: "var(--cmp-viz-mark-area-opacity)"
  # Stroke color for the baseline reference line
  viz.mark.area.baseline.stroke: "var(--cmp-viz-axis-base)"

events:
  mark.hovered:
    description: Fired when the area band is hovered. Payload includes the nearest datum along the curve.
    payload: [datum, index, curvePosition]
  mark.selected:
    description: Fired when the area band is clicked. Used by InteractionHighlight.
    payload: [datum, index]
  mark.focused:
    description: Fired when the area receives keyboard focus via point-of-interest 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:
    - MarkBar
    - MarkLine
    - MarkPoint
  accessibility:
    rule_reference: A11Y-R-06
    notes: Convey baseline reference in descriptive text output.
  regionsUsed:
    - detail
    - form
    - list
  examples:
    - ForecastRange
    - BurnDownVariance
  references:
    - RDS.7 Trait-Driven Visualization System Specification (v0.1)