Widget Definition

Widgets are registered through makeWidgetDef(...).

Required Shape

import { makeWidgetDef } from "@ska-octopus-widget-sdk/widget-sdk";

export const definition = makeWidgetDef({
  key: "my-widget",
  label: "My Widget",
  component: MyWidget,
  layout: { w: 6, h: 4, minW: 4, minH: 3 },
  config: { schema: mySchema },
  polls: true,
  docsUrl: "https://developer.skao.int/projects/my-widget/",
});

Field Guide

Field	Required	Notes
key	Yes	Stable unique identifier for the widget
label	Yes (recommended)	Display name in dashboard UI
component	Yes	React component rendered by host
layout	Yes (recommended)	Default size and constraints
config.schema	Yes (recommended)	Source for config form and defaults
polls	No	Signals polling/subscription behavior
requiredStreams	No	Backend stream dependencies
docsUrl	No	Link to widget docs
version	No	Usually inherited from package version

Real Examples

From ska-octopus-components-table-widget/src/index.ts:

• Uses INPUT_DEVICES, INPUT_ATTRIBUTES, and INPUT_STRINGS

• Persists table config (columnOrder, columnWidths, sortKey, sortDir)

• Sets polls: true and a widget specific docsUrl

From ska-octopus-grid-widget/src/index.ts:

• Uses INPUT_TANGO_ATTRIBUTES and INPUT_MULTIPLE_TANGO_ATTRIBUTES

• Uses dynamic selectors with WORKSPACES and VARIABLES

• Exposes click driven workspace and variable behavior

Host Registration

Many widgets use a guard loop so registration waits for Octopus.registerWidget:

(function wait(h: any) {
  if (typeof h.registerWidget === "function") {
    h.registerWidget(definition as any);
  } else {
    setTimeout(wait, 50, h);
  }
})((globalThis as any).Octopus || ((globalThis as any).Octopus = {}));

Recommendations

• Keep all defaults in schema fields whenever possible.

• Keep key immutable after release.

• Use docsUrl for user support and discoverability.

• Use deriveConfigFields(schema) only when you need explicit inspection/debugging.