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).

Static times cannot follow a realm filter

times[] is resolved when the layout is composed, on the runner, before any realm exists. On a dashboard with a realm filter the selection is made in the browser and passed to widgets at render time, so a static array shows the same lines under every realm. A hit-marker lane built this way will show every aircraft’s hits no matter which aircraft is selected.

Bind a channel instead and the markers follow the dropdown, the same way area series already do:

{
  "type": "spanning_lines",
  "order": 2,
  "height": 0,
  "label": "Hits Taken",
  "channels": ["timeline-hits"],
  "style": { "color": "#C13D40", "visibilityKey": "hits_taken" }
}

The channel must carry shape: "events"; entries with occurred: true inside the current x-domain become lines. Other shapes fall back to the same truthy-value rule events_lane uses. Static times[] remains supported for layouts with no realm filter, and takes effect only when no channel is bound.

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.

Offline terrain (flightTracks.terrain)

Aircraft in real-world space can be drawn over a ground image, a low-resolution heightmap, and mission-planning overlays. The dashboard bundles none of it: the slice points at a manifest JSON that an operator publishes through Cluster Manager env-assets (a .heatpatch with target env-assets, or the hxefs API), so terrain varies per project and customer.

{
  "type": "flight_tracks",
  "flightTracks": {
    "terrain": { "manifestUrl": "/env-assets/terrain/ol-gulf/v1/terrain.json" }
  }
}

The manifest (relative URLs resolve against it) declares:

• bounds: { minLat, maxLat, minLon, maxLon } in degrees, EPSG:4326 (plate carree). Keep rasters in plain lat/lon, not Web Mercator, so the pixel grid maps linearly onto the viewer.
• ground: { url, opacity }, a north-up image draped over the bounds. Opacity defaults to 0.5 so bright imagery sits behind the trails; raise it per manifest or per slice with terrain.opacity.
• height: { url, minM, maxM, verticalOffsetM }, a greyscale heightmap. verticalOffsetM reconciles an orthometric DEM with the ellipsoidal track altitudes.
• groundLevelM: flat ground altitude when no heightmap is used (default 0).
• overlays: { type: "image", url, bounds, opacity } or { type: "polygons", url | geojson, color, lineWidth, labels }. The GeoJSON may hold Polygon / MultiPolygon rings (closed outlines), LineString / MultiLineString paths (open), and Point / MultiPoint markers. Simplestyle properties on each feature (stroke, stroke-width, stroke-opacity, marker-color, Name) override the overlay defaults, so a geojson.io style mission-planning export keeps its authored colours and names. labels: false hides feature names. Fills are parsed but not drawn yet. A third overlay type, { type: "scenario-auto", url: "index.json" }, points at a catalogue { scenarios: [{ slug, title, overlayUrl }] } of per-scenario GeoJSON. By default (mode: "common") the widget draws only the features present in every scenario, such as corridors and boundaries, and never a scenario-specific one, so nothing that could be wrong is shown and no per-session configuration is needed. mode: "auto" opts into detection: each scenario is scored by how much of the flown track lies inside its polygons or within 8 km of its lines (shared features carry no weight) and its specific features draw only when it leads the runner-up by minLead (default 1.25) and clears minScore (default 0.05). mode: "off" draws nothing from the catalogue. An operator switches modes by editing terrain.json on the cluster; the slice’s terrain.scenarioSelection can override it from the template.

Slice-side options: manifest (inline instead of manifestUrl), showHeight, showOverlays, opacity, segments (drape subdivisions, default 96), and verticalExaggeration (terrain relief only, default 1). To lift the aircraft and the terrain together so climb, descent and relief read in the perspective view, set flightTracks.verticalScale (default 1, true scale; 6 works well over flat country). The two multiply. Terrain is placed through the same centre and scale transform as the tracks, so it stays aligned with them, and the whole terrain group renders beneath the flight paths so trails and markers are never hidden by the ground, an image overlay, or mission vectors.

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; gaze_points is the gaze-points value channel, id and name identical):

{
  "component": "ComposableChart",
  "colspan": 12,
  "configuration": {
    "name": "EyeTracking",
    "titleContent": "Eye Tracking",
    "channels": ["video_atlas", "gaze_points", "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", "vignette-01:gaze_points:gaze_points"],
          "videoPlayback": { "gazeChannel": "vignette-01:gaze_points:gaze_points" }
        },
        { "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/