@devicechain/widgets 0.19.0 → 0.20.0

package/README.md

@@ -34,14 +34,24 @@ acknowledge, command send — render without their controls. That is the whole
 opt-in: a viewer that never passes `actions` cannot write, regardless of what the
 board contains.
 
-Or drive a single widget yourself with `ConnectedWidget`, and look components up
-by type through `WIDGET_REGISTRY` and its per-channel siblings.
+A templated board takes its slot bindings on the renderer, not the hub:
+`<DashboardRenderer bindings={bindings} … />`. Keep one hub for the board
+(`useDashboardHub(resolver, authorities)` builds and disposes it); a new
+`bindings` map re-subscribes only the widgets whose slot moved.
+
+Or drive a single widget yourself with `ConnectedWidget`; it resolves the widget's
+component, channel and binding policy through a registry (the built-ins by default,
+or the one you pass as `registry`; see `createBuiltinWidgetRegistry` and
+`builtinWidgetDefinitions`, and `@devicechain/widget-sdk` to add your own). A widget
+bound to a slot needs its datasource resolved first (`resolveWidgets` or
+`resolveWidgetDatasource`).
 
 ## The widgets
 
 | channel | widgets |
 | --- | --- |
-| measurement | `timeseries-chart`, `gauge`, `latest-card`, `table`, `label`, `image` |
+| measurement | `timeseries-chart`, `gauge`, `latest-card`, `table` |
+| none (static) | `label`, `image` |
 | alarm | `alarm-table`, `alarm-count` |
 | control | `command-button` |
 | selection | `entity-selector` |

package/dist/binding-policy.d.ts

@@ -0,0 +1,4 @@
+import type { AlarmSubscription, CommandSubscription, WidgetDescriptor, WidgetInstance } from '@devicechain/dashboards';
+export declare function measurementWindow(descriptor: WidgetDescriptor, widget: WidgetInstance): number | undefined;
+export declare function alarmSubscription(descriptor: WidgetDescriptor, widget: WidgetInstance): AlarmSubscription;
+export declare function commandSubscription(descriptor: WidgetDescriptor, widget: WidgetInstance): CommandSubscription;

package/dist/builtin-descriptors.d.ts

@@ -0,0 +1,390 @@
+import { type WidgetDescriptor } from '@devicechain/dashboards';
+export declare const builtinWidgetDescriptors: {
+    readonly 'timeseries-chart': WidgetDescriptor<"measurement", {
+        readonly title: {
+            readonly kind: 'string';
+            readonly labelId: 'widgetLabelTitle';
+            readonly doc: 'Heading shown in the widget frame. Blank hides the frame heading.';
+        };
+        readonly window: {
+            readonly kind: 'number';
+            readonly integer: true;
+            readonly min: 1;
+            readonly labelId: 'widgetLabelWindow';
+            readonly helpId: 'widgetHintWindow';
+            readonly doc: 'Samples retained across ALL of the widget\'s measurements before the oldest are dropped. Bounds memory; only the chart draws them. Default 300.';
+        };
+    }>;
+    readonly 'latest-card': WidgetDescriptor<"measurement", {
+        readonly title: {
+            readonly kind: 'string';
+            readonly labelId: 'widgetLabelTitle';
+            readonly doc: 'Heading shown in the widget frame. Defaults to the displayed measurement name.';
+        };
+        readonly measurement: {
+            readonly kind: "string";
+            readonly labelId: "widgetLabelMeasurement";
+            readonly helpId: "widgetHintMeasurement";
+            readonly doc: "Which measurement to display. Defaults to the first the datasource selects.";
+        };
+        readonly unit: {
+            readonly kind: 'string';
+            readonly labelId: 'widgetLabelUnit';
+            readonly doc: 'Unit suffix shown beside the value.';
+        };
+        readonly precision: {
+            readonly kind: 'number';
+            readonly integer: true;
+            readonly min: 0;
+            readonly max: 100;
+            readonly labelId: 'widgetLabelPrecision';
+            readonly helpId: 'widgetHintPrecision';
+            readonly doc: 'Decimal places to round displayed values to. Unset shows the raw value.';
+        };
+        readonly flashOnChange: {
+            readonly kind: 'boolean';
+            readonly labelId: 'widgetFlashOnChange';
+            readonly helpId: 'widgetFlashOnChangeHint';
+            readonly doc: 'Briefly tint a value green on a rise and red on a fall when it changes.';
+        };
+        readonly window: {
+            readonly kind: 'number';
+            readonly integer: true;
+            readonly min: 1;
+            readonly labelId: 'widgetLabelWindow';
+            readonly helpId: 'widgetHintWindow';
+            readonly doc: 'Samples retained across ALL of the widget\'s measurements before the oldest are dropped. Bounds memory; only the chart draws them. Default 300.';
+        };
+    }>;
+    readonly gauge: WidgetDescriptor<"measurement", {
+        readonly title: {
+            readonly kind: 'string';
+            readonly labelId: 'widgetLabelTitle';
+            readonly doc: 'Heading shown in the widget frame. Defaults to the displayed measurement name.';
+        };
+        readonly measurement: {
+            readonly kind: "string";
+            readonly labelId: "widgetLabelMeasurement";
+            readonly helpId: "widgetHintMeasurement";
+            readonly doc: "Which measurement to display. Defaults to the first the datasource selects.";
+        };
+        readonly min: {
+            readonly kind: "number";
+            readonly labelId: "widgetLabelMin";
+            readonly doc: "Low end of the gauge scale. Default 0.";
+        };
+        readonly max: {
+            readonly kind: "number";
+            readonly labelId: "widgetLabelMax";
+            readonly doc: "High end of the gauge scale. Default 100.";
+        };
+        readonly unit: {
+            readonly kind: 'string';
+            readonly labelId: 'widgetLabelUnit';
+            readonly doc: 'Unit suffix shown beside the value.';
+        };
+        readonly flashOnChange: {
+            readonly kind: 'boolean';
+            readonly labelId: 'widgetFlashOnChange';
+            readonly helpId: 'widgetFlashOnChangeHint';
+            readonly doc: 'Briefly tint a value green on a rise and red on a fall when it changes.';
+        };
+        readonly window: {
+            readonly kind: 'number';
+            readonly integer: true;
+            readonly min: 1;
+            readonly labelId: 'widgetLabelWindow';
+            readonly helpId: 'widgetHintWindow';
+            readonly doc: 'Samples retained across ALL of the widget\'s measurements before the oldest are dropped. Bounds memory; only the chart draws them. Default 300.';
+        };
+    }>;
+    readonly table: WidgetDescriptor<"measurement", {
+        readonly title: {
+            readonly kind: 'string';
+            readonly labelId: 'widgetLabelTitle';
+            readonly doc: 'Heading shown in the widget frame. Blank hides the frame heading.';
+        };
+        readonly precision: {
+            readonly kind: 'number';
+            readonly integer: true;
+            readonly min: 0;
+            readonly max: 100;
+            readonly labelId: 'widgetLabelPrecision';
+            readonly helpId: 'widgetHintPrecision';
+            readonly doc: 'Decimal places to round displayed values to. Unset shows the raw value.';
+        };
+        readonly flashOnChange: {
+            readonly kind: 'boolean';
+            readonly labelId: 'widgetFlashOnChange';
+            readonly helpId: 'widgetFlashOnChangeHint';
+            readonly doc: 'Briefly tint a value green on a rise and red on a fall when it changes.';
+        };
+        readonly window: {
+            readonly kind: 'number';
+            readonly integer: true;
+            readonly min: 1;
+            readonly labelId: 'widgetLabelWindow';
+            readonly helpId: 'widgetHintWindow';
+            readonly doc: 'Samples retained across ALL of the widget\'s measurements before the oldest are dropped. Bounds memory; only the chart draws them. Default 300.';
+        };
+    }>;
+    readonly label: WidgetDescriptor<"none", {
+        readonly title: {
+            readonly kind: 'string';
+            readonly labelId: 'widgetLabelTitle';
+            readonly doc: 'Heading shown in the widget frame. Blank hides the frame heading.';
+        };
+        readonly text: {
+            readonly kind: "string";
+            readonly required: true;
+            readonly labelId: "widgetLabelText";
+            readonly doc: "The text to show. Rendered as plain text — markup is never interpreted.";
+        };
+        readonly align: {
+            readonly kind: "enum";
+            readonly values: readonly ["left", "center", "right"];
+            readonly labelId: "widgetLabelAlign";
+            readonly valueLabelIds: {
+                readonly left: "widgetAlignLeft";
+                readonly center: "widgetAlignCenter";
+                readonly right: "widgetAlignRight";
+            };
+            readonly placeholderId: "widgetPlaceholderDefault";
+            readonly doc: "Horizontal alignment of the text. Default center.";
+        };
+        readonly fontSize: {
+            readonly kind: "number";
+            readonly min: 1;
+            readonly labelId: "widgetLabelFontSize";
+            readonly helpId: "widgetHintFontSize";
+            readonly doc: "Text size in pixels. Default 16.";
+        };
+    }>;
+    readonly image: WidgetDescriptor<"none", {
+        readonly title: {
+            readonly kind: 'string';
+            readonly labelId: 'widgetLabelTitle';
+            readonly doc: 'Heading shown in the widget frame. Blank hides the frame heading.';
+        };
+        readonly url: {
+            readonly kind: "string";
+            readonly required: true;
+            readonly labelId: "widgetLabelImageUrl";
+            readonly doc: "Source URL of the image.";
+        };
+        readonly alt: {
+            readonly kind: "string";
+            readonly labelId: "widgetLabelAltText";
+            readonly doc: "Alternative text describing the image for assistive technology.";
+        };
+        readonly fit: {
+            readonly kind: "enum";
+            readonly values: readonly ["contain", "cover", "fill"];
+            readonly labelId: "widgetLabelFit";
+            readonly valueLabelIds: {
+                readonly contain: "widgetFitContain";
+                readonly cover: "widgetFitCover";
+                readonly fill: "widgetFitFill";
+            };
+            readonly placeholderId: "widgetPlaceholderDefault";
+            readonly doc: "How the image fills its box. Default contain.";
+        };
+    }>;
+    readonly 'alarm-table': WidgetDescriptor<"alarm", {
+        readonly title: {
+            readonly kind: 'string';
+            readonly labelId: 'widgetLabelTitle';
+            readonly doc: 'Heading shown in the widget frame. Blank hides the frame heading.';
+        };
+        readonly state: {
+            readonly kind: 'enum';
+            readonly values: readonly ["ACTIVE", "CLEARED"];
+            readonly labelId: 'widgetLabelState';
+            readonly helpId: 'widgetStateHint';
+            readonly valueLabelIds: {
+                readonly ACTIVE: 'widgetAlarmStateActive';
+                readonly CLEARED: 'widgetAlarmStateCleared';
+            };
+            readonly placeholderId: 'widgetPlaceholderAny';
+            readonly doc: 'Show only alarms in this state. Unset shows every state.';
+        };
+        readonly severity: {
+            readonly kind: 'enum';
+            readonly values: readonly ["CRITICAL", "MAJOR", "MINOR", "WARNING", "INDETERMINATE"];
+            readonly labelId: 'widgetLabelSeverity';
+            readonly helpId: 'widgetSeverityHint';
+            readonly valueLabelIds: {
+                readonly CRITICAL: 'widgetAlarmSeverityCritical';
+                readonly MAJOR: 'widgetAlarmSeverityMajor';
+                readonly MINOR: 'widgetAlarmSeverityMinor';
+                readonly WARNING: 'widgetAlarmSeverityWarning';
+                readonly INDETERMINATE: 'widgetAlarmSeverityIndeterminate';
+            };
+            readonly placeholderId: 'widgetPlaceholderAny';
+            readonly doc: 'Show only alarms at this severity. Unset shows every severity.';
+        };
+        readonly acknowledged: {
+            readonly kind: 'enum';
+            readonly values: readonly ["true", "false"];
+            readonly labelId: 'widgetLabelAcknowledged';
+            readonly helpId: 'widgetAcknowledgedHint';
+            readonly valueLabelIds: {
+                readonly true: 'widgetAlarmAckAcknowledged';
+                readonly false: 'widgetAlarmAckUnacknowledged';
+            };
+            readonly placeholderId: 'widgetPlaceholderAny';
+            readonly doc: "Show only acknowledged ('true') or unacknowledged ('false') alarms. Unset shows both.";
+        };
+        readonly maxRows: {
+            readonly kind: "number";
+            readonly integer: true;
+            readonly min: 1;
+            readonly labelId: "widgetLabelMaxRows";
+            readonly helpId: "widgetMaxRowsAlarmHint";
+            readonly doc: "Alarms loaded into the table. Default 50.";
+        };
+        readonly precision: {
+            readonly kind: 'number';
+            readonly integer: true;
+            readonly min: 0;
+            readonly max: 100;
+            readonly labelId: 'widgetLabelPrecision';
+            readonly helpId: 'widgetHintPrecision';
+            readonly doc: 'Decimal places to round displayed values to. Unset shows the raw value.';
+        };
+        readonly flashOnChange: {
+            readonly kind: 'boolean';
+            readonly labelId: 'widgetFlashOnChange';
+            readonly helpId: 'widgetFlashOnChangeHint';
+            readonly doc: 'Briefly tint a value green on a rise and red on a fall when it changes.';
+        };
+        readonly selectionTarget: {
+            readonly kind: 'string';
+            readonly labelId: 'widgetLabelTargetSlot';
+            readonly helpId: 'widgetTargetSlotHint';
+            readonly control: 'slot-target';
+            readonly doc: 'Name of the slot this widget re-points when the viewer picks an entity.';
+        };
+    }>;
+    readonly 'alarm-count': WidgetDescriptor<"alarm", {
+        readonly title: {
+            readonly kind: 'string';
+            readonly labelId: 'widgetLabelTitle';
+            readonly doc: 'Heading shown in the widget frame. Blank hides the frame heading.';
+        };
+        readonly state: {
+            readonly kind: 'enum';
+            readonly values: readonly ["ACTIVE", "CLEARED"];
+            readonly labelId: 'widgetLabelState';
+            readonly helpId: 'widgetStateHint';
+            readonly valueLabelIds: {
+                readonly ACTIVE: 'widgetAlarmStateActive';
+                readonly CLEARED: 'widgetAlarmStateCleared';
+            };
+            readonly placeholderId: 'widgetPlaceholderAny';
+            readonly doc: 'Show only alarms in this state. Unset shows every state.';
+        };
+        readonly severity: {
+            readonly kind: 'enum';
+            readonly values: readonly ["CRITICAL", "MAJOR", "MINOR", "WARNING", "INDETERMINATE"];
+            readonly labelId: 'widgetLabelSeverity';
+            readonly helpId: 'widgetSeverityHint';
+            readonly valueLabelIds: {
+                readonly CRITICAL: 'widgetAlarmSeverityCritical';
+                readonly MAJOR: 'widgetAlarmSeverityMajor';
+                readonly MINOR: 'widgetAlarmSeverityMinor';
+                readonly WARNING: 'widgetAlarmSeverityWarning';
+                readonly INDETERMINATE: 'widgetAlarmSeverityIndeterminate';
+            };
+            readonly placeholderId: 'widgetPlaceholderAny';
+            readonly doc: 'Show only alarms at this severity. Unset shows every severity.';
+        };
+        readonly acknowledged: {
+            readonly kind: 'enum';
+            readonly values: readonly ["true", "false"];
+            readonly labelId: 'widgetLabelAcknowledged';
+            readonly helpId: 'widgetAcknowledgedHint';
+            readonly valueLabelIds: {
+                readonly true: 'widgetAlarmAckAcknowledged';
+                readonly false: 'widgetAlarmAckUnacknowledged';
+            };
+            readonly placeholderId: 'widgetPlaceholderAny';
+            readonly doc: "Show only acknowledged ('true') or unacknowledged ('false') alarms. Unset shows both.";
+        };
+    }>;
+    readonly 'command-button': WidgetDescriptor<"control", {
+        readonly title: {
+            readonly kind: 'string';
+            readonly labelId: 'widgetLabelTitle';
+            readonly doc: 'Heading shown in the widget frame. Blank hides the frame heading.';
+        };
+        readonly commandName: {
+            readonly kind: "string";
+            readonly required: true;
+            readonly labelId: "widgetCommandHeading";
+            readonly helpId: "widgetCommandFieldHint";
+            readonly control: "command-vocabulary";
+            readonly doc: "Command key issued to the target device. Without it the widget cannot send.";
+        };
+        readonly commandLabel: {
+            readonly kind: "string";
+            readonly labelId: "widgetCommandHeading";
+            readonly helpId: "widgetCommandFieldHint";
+            readonly control: "command-vocabulary";
+            readonly doc: "Text on the send button. Defaults to the command key.";
+        };
+        readonly parameterSchema: {
+            readonly kind: "string";
+            readonly format: "json";
+            readonly labelId: "widgetCommandHeading";
+            readonly helpId: "widgetCommandFieldHint";
+            readonly control: "command-vocabulary";
+            readonly doc: "The command's parameter descriptors, baked in as JSON at author time. Drives the typed form.";
+        };
+        readonly maxRows: {
+            readonly kind: "number";
+            readonly integer: true;
+            readonly min: 1;
+            readonly labelId: "widgetLabelMaxRows";
+            readonly helpId: "widgetMaxRowsCommandHint";
+            readonly doc: "Recent commands shown in the history. Default 20.";
+        };
+    }>;
+    readonly 'entity-selector': WidgetDescriptor<"selection", {
+        readonly title: {
+            readonly kind: 'string';
+            readonly labelId: 'widgetLabelTitle';
+            readonly doc: 'Heading shown in the widget frame. Blank hides the frame heading.';
+        };
+        readonly selectionTarget: {
+            readonly kind: 'string';
+            readonly labelId: 'widgetLabelTargetSlot';
+            readonly helpId: 'widgetTargetSlotHint';
+            readonly control: 'slot-target';
+            readonly doc: 'Name of the slot this widget re-points when the viewer picks an entity.';
+            readonly required: true;
+        };
+    }>;
+    readonly map: WidgetDescriptor<"location", {
+        readonly title: {
+            readonly kind: 'string';
+            readonly labelId: 'widgetLabelTitle';
+            readonly doc: 'Heading shown in the widget frame. Blank hides the frame heading.';
+        };
+        readonly tileUrl: {
+            readonly kind: "string";
+            readonly labelId: "widgetLabelTileUrl";
+            readonly helpId: "widgetTileUrlHint";
+            readonly control: "basemap";
+            readonly doc: "Raster tile URL template, e.g. https://tiles.example.com/{z}/{x}/{y}.png. Leave empty to inherit the tenant's basemap; setting one overrides it for this board only.";
+        };
+        readonly attribution: {
+            readonly kind: "string";
+            readonly labelId: "widgetLabelAttribution";
+            readonly helpId: "widgetAttributionHint";
+            readonly control: "basemap";
+            readonly doc: "Credit line the tile source requires, shown on the map. Set whatever the provider you chose asks for.";
+        };
+    }>;
+};
+export declare const builtinWidgetCatalog: import("@devicechain/dashboards").WidgetCatalog;