ComposableChart (Next)

A layout-driven chart widget that stacks multiple UI slices in one container. Time-synced slices share a primary x-domain and interaction state (zoom, pan, hover scrubber). Non-synced slices (legend, static, playback placeholder) sit in the stack but do not participate in x-axis sync.

Use this widget when a design needs mixed chart types (area + event lanes + comms ranges), synchronized scrubbing, per-series legend toggles, and per-slice fault isolation in one panel.

Full support (recommended)

Current state and limitations

General limitations

• Rendering is SVG + D3 (not ApexCharts). Very large series may need channel downsampling upstream.
• Slice channel binding uses URI strings on each element, not the top-level configuration.channels mapping.
• Multiple widgets of the same type in one layout are supported via distinct configuration.name and element channel URIs.
• Empty label: "" on a slice suppresses the lane title (used for combined area + external legend).

Dashboard generation

Layout component identifier

ComposableChart , configuration.component in v2 layout rows.

Layout configuration

Typical fields on the row configuration object:

Each element in composableChartItem.elements:

Playback for this widget

• Set enableGlobalPlaybackControls or row enablePlaybackControls on the session layout to show PlayBackControlDS.
• The chart draws a yellow vertical cursor at xDomain[0] + clock.elapsedMs when anchor is "time".
• Do not add a playback element to layouts until the slice is marked ready in docs.

Layout excerpt (terrain-style timeline)

{
  "component": "ComposableChart",
  "colspan": 12,
  "configuration": {
    "name": "TerrainTimeline",
    "titleContent": "Terrain Timeline",
    "channels": [],
    "defaultRealm": "circuit-03",
    "enablePlaybackControls": true,
    "composableChartItem": {
      "anchor": "time",
      "xAxis": { "ticks": [0, 300000, 600000, 900000] },
      "elements": [
        {
          "type": "legend",
          "order": 0,
          "height": 40,
          "legendItems": [
            { "id": "speed", "label": "Speed", "color": "#81842C", "swatch": "line" }
          ]
        },
        {
          "type": "area",
          "order": 1,
          "label": "",
          "height": 160,
          "yAxis": {
            "domain": [0, 100],
            "bandLabels": [
              { "label": "LOW", "value": 16.66 },
              { "label": "MEDIUM", "value": 50 },
              { "label": "HIGH", "value": 83.33 }
            ],
            "gridLines": [33.33, 66.66]
          },
          "series": [
            {
              "id": "speed",
              "label": "Speed",
              "channel": "circuit-03:timeline-speed:Air Speed",
              "color": "#81842C",
              "render": "line_gradient",
              "unit": " km/h"
            }
          ]
        },
        {
          "type": "ranges_lane",
          "order": 2,
          "label": "Comms",
          "height": 32,
          "channels": ["circuit-03:timeline-comms:Comms Events"],
          "style": { "color": "#0B5370", "visibilityKey": "comms" }
        },
        {
          "type": "events_lane",
          "order": 3,
          "label": "Commander",
          "height": 32,
          "eventSeries": [
            { "id": "cmdr_rep", "label": "Reports", "color": "#666666" }
          ]
        }
      ]
    }
  }
}

Slice reference

Slices render top-to-bottom by order. Synced slices share zoom, pan, hover scrubber, and (when enabled) the yellow playback cursor. Non-synced slices are legend, static, playback placeholder, and spanning lines overlay (zero height band).

legend

Toggle row for series visibility. Each legendItems[] entry needs a unique id matching series ids (area series[].id, eventSeries[].id, style.visibilityKey, or spanning line key).

area

Primary time-series band. Supports multiple series in one slice via series[].

scatter

Points plotted by time (x) and value (y).

events_lane

Horizontal lane of event dots at fixed y. Supports multiple event types per lane via eventSeries[] (e.g. Commander Reports + Commands).

ranges_lane

Horizontal bars for intervals (e.g. comms active periods).

spanning_lines

Vertical lines spanning the synced stack (e.g. hits received). Not a visible slice band (height: 0).

static

Non-chart content block (typically StatsCard weather summary).

playback (not ready)

Reserved slice type for future in-chart play/pause + scrubber wired to the realm TimelineClock.

Data contract

Publish canonical $heat-dataservice with realms, groups, and channels per the dashboard-v2 upstream contract.

Channel shapes summary

Example channels

Series (area / scatter):

{
  "id": "timeline-speed",
  "name": "Air Speed",
  "groupId": "timeline",
  "shape": "series",
  "data": [
    { "timeMs": 0, "value": 50 },
    { "timeMs": 60000, "value": 70 }
  ]
}

Events lane:

{
  "id": "timeline-hits-taken",
  "name": "Hits Taken",
  "groupId": "timeline",
  "shape": "events",
  "data": [
    { "timeMs": 198000, "occurred": true }
  ]
}

Ranges lane:

{
  "id": "timeline-comms",
  "name": "Comms Events",
  "groupId": "timeline",
  "shape": "ranges",
  "data": [
    { "startTimeMs": 72000, "endTimeMs": 120000, "durationMs": 48000 }
  ]
}

Interactions

Fault isolation

Each slice is wrapped in an error boundary. Invalid config or missing data shows an inline empty state for that slice only.

Anchor modes

Storybook

• TerrainTimelineMock , reference-aligned legend, combined area, comms, commander/gunner/driver lanes, time grid
• TerrainTimelineWithSummary , above plus StatsCard static slice
• Per-slice , Organisms/ComposableChart/Slices/* (area, scatter, events, ranges, legend, static)
• DataService , live mock client when loaded

The playback slice is intentionally omitted from Storybook mocks until it is product-ready.

Related

• Next components index
• Dataservice migration status
• ComposableChart (Legacy) , v1 combined-custom-charts bridge for ui/legacy
• TimelineChart , legacy Apex-based timeline (partial migration)
• dashboard-v2 upstream contract
• Reference JSON: tools/arbex/reference/next/ComposableChart.json
• Arbex RAG: tools/arbex/rag/reference/components/ComposableChart.md, composable-chart-channel-keys.md
• Source: ui/dashboard/src/components/organisms/composable-chart/