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, transcript, playback controls, flight tracks, video playback) 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".
• Add a playback element for the in-chart seek bar (no play button). Page-level PlayBackControlDS remains optional.

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", "isLabel": false }
          ]
        },
        {
          "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, transcript, playback placeholder, flight tracks, video playback, 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). Supports single-series and multi-series modes.

Single-series — one ranges channel, one colour:

Multi-series — multiple named, individually coloured series sharing the same lane row:

engagement

One per-target row combining overlaid range bars and an event marker stream, used with composableChartItem.isTargetEngagement: true to build a stacked multi-target Target Engagement panel (one engagement element per target).

spanning_lines

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

markdown

Inline Markdown text block rendered inside the chart stack. Content is embedded directly in the layout element via markdownContent — no channel or runner payload is required.

static

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

transcript

Out-of-band scrollable transcript list synced to the shared realm clock. Use under a ranges_lane (for example Comms occupancy) when you need utterance text.

playback

In-chart seek bar wired to the realm TimelineClock. No play/pause button and no duration readout. Page-level PlayBackControlDS remains available when a design needs those controls.

flight_tracks

Dual-pane spatial slice: left is a lat/lon trail canvas, right is an altitude strip. Both panes share the same named tracks, the chart legend, and the realm clock.

video_playback

Video-atlas seat tiles inside the chart stack. Renders the same N-up seat view as the standalone VideoPlayback column, but follows the chart’s realm clock and plays only the window the chart is looking at.

Layout excerpt (eye tracking, one vignette realm; the default window is the vignette clock span, so no bounds are set):

{
  "component": "ComposableChart",
  "colspan": 12,
  "configuration": {
    "name": "EyeTracking",
    "titleContent": "Eye Tracking",
    "channels": ["video_atlas", "gaze-seat-1", "gaze-seat-2", "gaze-seat-3", "gaze-seat-4"],
    "defaultRealm": "vignette-01",
    "composableChartItem": {
      "anchor": "time",
      "elements": [
        {
          "type": "legend",
          "order": 0,
          "height": 40,
          "legendItems": [
            { "id": "fixation", "label": "Fixation", "color": "#7EB8DA", "swatch": "dot" }
          ]
        },
        {
          "type": "video_playback",
          "order": 1,
          "height": 240,
          "channels": ["vignette-01:video_atlas:video_atlas"]
        },
        { "type": "playback", "order": 2, "height": 40 },
        {
          "type": "events_lane",
          "order": 3,
          "height": 36,
          "label": "Seat 1",
          "eventSeries": [
            { "id": "fixation", "label": "Fixation", "channel": "vignette-01:gaze-seat-1:Fixation", "color": "#7EB8DA", "shape": "dot" }
          ]
        },
        {
          "type": "events_lane",
          "order": 4,
          "height": 36,
          "label": "Seat 2",
          "eventSeries": [
            { "id": "fixation", "label": "Fixation", "channel": "vignette-01:gaze-seat-2:Fixation", "color": "#7EB8DA", "shape": "dot" }
          ]
        },
        {
          "type": "events_lane",
          "order": 5,
          "height": 36,
          "label": "Seat 3",
          "eventSeries": [
            { "id": "fixation", "label": "Fixation", "channel": "vignette-01:gaze-seat-3:Fixation", "color": "#7EB8DA", "shape": "dot" }
          ]
        },
        {
          "type": "events_lane",
          "order": 6,
          "height": 36,
          "label": "Seat 4",
          "eventSeries": [
            { "id": "fixation", "label": "Fixation", "channel": "vignette-01:gaze-seat-4:Fixation", "color": "#7EB8DA", "shape": "dot" }
          ]
        }
      ]
    }
  }
}

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 }
  ]
}

Engagement (one channel per target row):

{
  "id": "engagement-target-1",
  "name": "engagement-target-1",
  "groupId": "targets",
  "shape": "value",
  "data": {
    "value": {
      "kind": "engagement",
      "series": [],
      "engagementData": {
        "title": "Target 1",
        "events": [
          { "id": "hit", "times": [1500, 2500] },
          { "id": "neutralised", "times": [12000] }
        ],
        "ranges": [
          { "id": "exposed", "data": [{ "startX": 1000, "endX": 12000 }] }
        ]
      }
    }
  }
}

events[].id and ranges[].id must match the element’s eventSeries[].id and rangeSeries[].id. See the full example in tools/arbex/reference/next/ComposableChart-target-engagement-example.json.

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
• CommsWithTranscript , Pilot ranges lane plus transcript viewer
• 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)
• VideoPlayback , standalone column and the manifest contract behind the video_playback slice
• 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/