SDK Surface Map

This page answers: “What can I use from the SDK?”

For full signatures and one-line descriptions of every export, see WIDGET_SDK.md.

Main Export Groups

Group	Use It For	Key Exports
Widget definition	Registering widgets and deriving config fields	`makeWidgetDef`, `deriveConfigFields`
Data hooks	GraphQL stream, polling, and mutation workflows	`useStream`, `usePolling`, `useMutation`, `useStreamHistory`
Host state hooks	Reading shared dashboard state	`useBrush`, `useVariables`, `useWorkspace`, `useUserTimeRange`, `useEffectiveTimeRange`, `useWidgetRefreshRate`, `useWidgetLayout`, `useThemeMode`, `useHostVariables`, `useReplayMode`, `useRoleLevelAccess`, `useWidgetConfigPersistence`
Config helpers	Schema shortcuts and input formatting	`INPUT_*`, `WORKSPACES`/`VARIABLES`, `formatInputFormattedTemplate`
Table toolkit	Shared table rendering and table state	`InteractiveTable`, `useInteractiveTableState`, `fitColumnWidths`, `normalizeColumnOrder`, `normalizeColumnWidths`
UI components	Standardized status and empty/error UI	`DataLoadFailed`, `NoResults`, `RefreshingBadge`, `CommandResultAlert`, `StateChip`, `HoverCard`, `BaseSunburst`, `HoverPortal`
Plotly utilities	Responsive Plotly charts with consistent theming	`canonicalAttr`, `buildAxisTitle`, `parseMargins`, `formatLegendName`, `dedupeLegendLabels`, `getPlotlyLegendConfig`, `applyVerticalColorRanking`, `applyThresholdEmphasis`, `isThresholdActive`, `classifyThresholdValue`, `readTheme`, `ThemeVars`, `usePlotlyResize`, `useThemeObserver`
Utilities	Expression parsing, brush parsing, normalization	`parseBrush`, `makeMatcher`, `tokenize`, `parse`, `buildMatcher`, `parseExpression`, `evaluateExpression`, tango input helpers
Dev + testing	Local host simulation and test mocks	`createMockHost`, `DevProviders`, `@ska-octopus-widget-sdk/widget-sdk/testing`

Common Import Patterns

Definition + schema shortcuts

import {
  makeWidgetDef,
  INPUT_TANGO_ATTRIBUTES,
  INPUT_FORMATED_SCHEMA_TYPE,
  WORKSPACES,
  VARIABLES,
} from "@ska-octopus-widget-sdk/widget-sdk";

Data + global state

import {
  useStream,
  useWidgetRefreshRate,
  useBrush,
  useVariables,
  useWorkspace,
} from "@ska-octopus-widget-sdk/widget-sdk";

Table-heavy widgets

import {
  InteractiveTable,
  StateChip,
  useInteractiveTableState,
  fitColumnWidths,
} from "@ska-octopus-widget-sdk/widget-sdk";

Plotly chart widgets

import {
  usePlotlyResize,
  useThemeObserver,
  canonicalAttr,
  buildAxisTitle,
  parseMargins,
  formatLegendName,
  dedupeLegendLabels,
  getPlotlyLegendConfig,
  applyVerticalColorRanking,
  applyThresholdEmphasis,
  classifyThresholdValue,
  isThresholdActive,
} from "@ska-octopus-widget-sdk/widget-sdk";

Threshold emphasis

applyThresholdEmphasis(trace, range, options?) fades the points of a Plotly trace whose values fall inside a nominal { min?, max? } range, leaving out-of-range points at full opacity so they stand out. In-range points are recoloured to options.nominalColor (the series colour by default; pass a neutral grey to mute them) at options.nominalOpacity (default 0.18), and the connecting line is faded to match when fadeLine is set. It reads values from options.valuesFrom ("y" by default, "x" when values are plotted on X) and returns the trace unchanged when the range is inactive.

Helpers: isThresholdActive(range) reports whether a finite bound is set, and classifyThresholdValue(value, range) returns "below" | "nominal" | "above" (or null for non-finite values). Per-point marker.color arrays and rgba() colours work for both scatter (SVG) and scattergl (WebGL).

const emphasised = applyThresholdEmphasis(
  trace,
  { min: 38, max: 42 },
  { nominalColor: "#888888", nominalOpacity: 0.18, valuesFrom: "y" },
);

Local dev + tests

import { createMockHost, DevProviders } from "@ska-octopus-widget-sdk/widget-sdk";
import { installSdkWidgetTestMocks } from "@ska-octopus-widget-sdk/widget-sdk/testing";