Architecture

IIFE Build and Registration

  • Built as an IIFE bundle via Vite/Rollup (see vite.config.lib.ts).

    • Entry: src/index.ts

    • Format: iife

    • Output: dist/index.iife.js

  • Self-registers with the Octopus host by polling globalThis.Octopus.registerWidget.

  • Types emitted to dist/src/index.d.ts.

Runtime Data Flow

  • Polls the GraphQL API for the configured attributes at the dashboard refresh rate.

  • Supports per-attribute endpoint routing using <endpoint-selector>://<attribute-fullname>.

  • Attributes without a prefix use the default route and do not send the GraphQL endpoint variable.

  • Maps numeric enums to labels using enumLabels when appropriate.

Importing in octopus-frontend

  • Load dist/index.iife.js and the widget auto-registers under key graph.

SDK Utilities

Chart plumbing is delegated to @ska-octopus-widget-sdk/widget-sdk to avoid re-implementing boilerplate:

  • usePlotlyResize — ResizeObserver + rAF + 48 ms debounce; exposes containerRef, containerBox, and schedulePlotResize.

  • useThemeObserver — MutationObserver on document.body; re-reads CSS custom properties (--widget-bg, --text-color, etc.) on class/style changes.

  • canonicalAttr, parseMargins, buildAxisTitle — normalisation and formatting helpers shared with the timeline widget.

  • formatLegendName, dedupeLegendLabels — legend label resolution with {fullname}, {lastname}, {number}, {station}, {split(n)}, {label} placeholder support.

  • getPlotlyLegendConfig — returns Plotly legend anchor/orientation config for a named position; getLegendAndMargin in src/utils/legend.ts adds compact-mode margin adjustments on top.

  • applyVerticalColorRanking — re-exported via src/utils/traces.ts; assigns palette colors ranked by trace peak value.

  • readTheme / ThemeVars — re-exported via src/plot/theme.ts.

Full SDK API reference: WIDGET_SDK.md