@devicechain/dashboards 0.19.0-rc.1 → 0.20.0-rc.4

package/README.md

@@ -29,20 +29,24 @@ device" into what reads like an outage.
 One hub serves a whole board. Widgets subscribe to it; it does the deduplication.
 
 ```ts
-import { DashboardHub } from '@devicechain/dashboards';
+import { DashboardHub, resolveWidgetDatasource } from '@devicechain/dashboards';
 
 const hub = new DashboardHub({
   resolver,                 // how a selector becomes device tokens
-  bindings,                 // slot name -> concrete entity, for templated boards
   authorities: user.scopes, // what this viewer may do; drives hub.can(...)
 });
 
-const stop = hub.subscribeWidget(widget.datasource, {
+// The hub holds no slot bindings: resolve a widget's `slot` selector through them
+// first. A slot with no binding resolves to an explicit `unbound` selector, which the
+// hub answers with no data; a raw `slot` selector is an error.
+// It is undefined only for a widget that declares no datasource at all.
+const datasource = resolveWidgetDatasource(widget.datasource, bindings);
+const stop = datasource && hub.subscribeWidget(datasource, {
   next: (sample) => setLatest(sample),
 });
 
 // later
-stop();
+stop?.();
 hub.disposeAll();
 ```
 
@@ -84,8 +88,16 @@ and the `editor-model` transforms (`addWidget`, `setWidgetBox`, `deleteWidget`,
 A board can be written once and pointed at many entities. A widget's datasource
 may name a **slot** instead of a device, and the host supplies a binding for that
 slot at view time — `effectiveBindings`, `resolveContextBindings`,
-`applySelection` and `resolveSlotCandidates` are the machinery, and
-`hub.setBindings()` rebinds a live board.
+`applySelection` and `resolveSlotCandidates` are the machinery.
+
+The hub holds no bindings. A slot is resolved to a concrete selector before it
+is subscribed — `resolveWidgetDatasource(datasource, bindings)`, which the
+`DashboardRenderer` in `@devicechain/widgets` calls for every widget — so one
+hub serves a board for its whole life, and re-pointing a slot re-subscribes only
+the widgets bound to it. A slot with no binding resolves to `{ kind: 'unbound' }`,
+which every channel treats as zero devices; it is never turned into an absent
+datasource, which the alarm channel reads as tenant-wide. A raw `slot` selector
+handed straight to the hub is an error.
 
 ## Synthetic data
 

package/dist/bindings.d.ts

@@ -1,4 +1,4 @@
-import type { DashboardDefinition, SlotBinding } from './types';
+import type { DashboardDefinition, DatasourceSelector, SlotBinding } from './types';
 export declare function effectiveBindings(definition: DashboardDefinition, manifest?: Record<string, SlotBinding>): Record<string, SlotBinding>;
 export interface ParsedBindingManifest {
     bindings: Record<string, SlotBinding>;
@@ -6,3 +6,4 @@ export interface ParsedBindingManifest {
 }
 export declare function parseBindingManifest(raw: unknown): ParsedBindingManifest;
 export declare function stripDefaultBindings(def: DashboardDefinition): DashboardDefinition;
+export declare function resolveWidgetDatasource(datasource: DatasourceSelector | undefined, bindings: Record<string, SlotBinding> | undefined): DatasourceSelector | undefined;

package/dist/channel-snapshots.d.ts

@@ -0,0 +1,26 @@
+import type { AlarmRow, CommandRow, LocationSample, MeasurementSample } from './types';
+export interface MeasurementStreamState {
+    latest: Record<string, MeasurementSample>;
+    samples: MeasurementSample[];
+    error: unknown | null;
+}
+export interface AlarmStreamState {
+    alarms: AlarmRow[];
+    total: number;
+    loading: boolean;
+    error: unknown | null;
+}
+export interface CommandStreamState {
+    deviceToken: string | null;
+    commands: CommandRow[];
+    total: number;
+    loading: boolean;
+    error: unknown | null;
+}
+export interface LocationStreamState {
+    locations: LocationSample[];
+    deviceTokens: string[];
+    forbidden: boolean;
+    loading: boolean;
+    error: unknown | null;
+}

package/dist/definition.d.ts

@@ -1,11 +1,19 @@
-import { type Breakpoints, type DashboardDefinition, type SlotBinding, type SlotDefinition, type WidgetBox, type WidgetLayout } from './types';
+import { type Breakpoints, type DashboardDefinition, type ExtensionWidgetInstance, type KnownWidgetInstance, type SlotBinding, type SlotDefinition, type WidgetBox, type WidgetLayout } from './types';
+import type { WidgetCatalog } from './widget-catalog';
 export declare const BASE_BREAKPOINT = "base";
 export declare class DashboardDefinitionError extends Error {
     constructor(message: string);
 }
-export declare function parseDashboardDefinition(raw: unknown): DashboardDefinition;
+export interface ParseDefinitionOptions {
+    catalog?: WidgetCatalog;
+}
+export declare function parseDashboardDefinition(raw: unknown, options?: ParseDefinitionOptions): DashboardDefinition;
 export declare function canScopeSlot(slots: Record<string, SlotDefinition>, child: string, parentName: string): boolean;
 export declare function parseSlotBinding(raw: unknown): SlotBinding | undefined;
+export type StoredDashboardDefinition = Omit<DashboardDefinition, 'widgets'> & {
+    widgets: Array<KnownWidgetInstance | ExtensionWidgetInstance | Record<string, unknown>>;
+};
+export declare function storedDefinition(def: DashboardDefinition): StoredDashboardDefinition;
 export declare function serializeDefinition(def: DashboardDefinition): string;
 export declare function isDirty(a: DashboardDefinition, b: DashboardDefinition): boolean;
 export declare function resolveWidgetBox(layout: WidgetLayout, breakpoint: string): WidgetBox;

package/dist/editor-model.d.ts

@@ -1,4 +1,5 @@
-import type { CanvasGrid, CanvasSizing, DashboardDefinition, WidgetBox, WidgetInstance, WidgetType } from './types';
+import type { CanvasGrid, CanvasSizing, DashboardDefinition, WidgetBox, WidgetInstance } from './types';
+import type { WidgetDescriptor } from './widget-descriptor';
 export declare function baseBox(widget: WidgetInstance): WidgetBox;
 export declare function setWidgetBox(def: DashboardDefinition, id: string, box: WidgetBox): DashboardDefinition;
 export declare function deleteWidget(def: DashboardDefinition, id: string): DashboardDefinition;
@@ -7,7 +8,7 @@ export declare function setTitle(def: DashboardDefinition, title: string): Dashb
 export declare function setCanvasGrid(def: DashboardDefinition, patch: Partial<CanvasGrid>): DashboardDefinition;
 export declare function setCanvasSizing(def: DashboardDefinition, sizing: CanvasSizing): DashboardDefinition;
 export declare function updateWidget(def: DashboardDefinition, id: string, next: WidgetInstance): DashboardDefinition;
-export declare function addWidget(def: DashboardDefinition, type: WidgetType): {
+export declare function addWidget(def: DashboardDefinition, descriptor: Pick<WidgetDescriptor, 'id' | 'defaults' | 'version' | 'optionsVersion' | 'sdkApiVersion'>): {
     definition: DashboardDefinition;
     id: string;
 };

package/dist/history.d.ts

@@ -1,8 +1,8 @@
-import type { MeasurementSample, SlotBinding, WidgetInstance } from './types';
+import type { MeasurementSample, WidgetInstance } from './types';
 export interface HistoryWindow {
     startTime: string;
     endTime: string;
     intervalSeconds: number;
 }
 export declare function defaultHistoryWindow(): HistoryWindow;
-export declare function fetchWidgetHistory(widget: WidgetInstance, window: HistoryWindow, bindings?: Record<string, SlotBinding>): Promise<MeasurementSample[]>;
+export declare function fetchWidgetHistory(widget: WidgetInstance, window: HistoryWindow): Promise<MeasurementSample[]>;

package/dist/hub.d.ts

@@ -1,4 +1,4 @@
-import type { AlarmRow, AnchorTarget, CommandRow, DatasourceSelector, LocationSample, MeasurementSample, SlotBinding } from './types';
+import type { AlarmRow, AnchorTarget, CommandRow, DatasourceSelector, LocationSample, MeasurementSample } from './types';
 export interface DeviceResolver {
     devicesForAnchor(anchor: AnchorTarget): Promise<string[]>;
     deviceExists(deviceToken: string): Promise<boolean>;
@@ -65,7 +65,6 @@ export interface WidgetActions {
 }
 export interface DashboardHubConfig {
     resolver: DeviceResolver;
-    bindings?: Record<string, SlotBinding>;
     authorities?: string[];
 }
 export interface WidgetDataSource {
@@ -84,9 +83,7 @@ export declare class DashboardHub implements WidgetDataSource, WidgetActions {
     private readonly alarmDisposers;
     private readonly commandDisposers;
     private readonly locationDisposers;
-    private bindings;
     constructor(config: DashboardHubConfig);
-    setBindings(bindings: Record<string, SlotBinding>): void;
     subscribeWidget(datasource: DatasourceSelector, sink: WidgetStreamSink): () => void;
     subscribeAlarms(subscription: AlarmSubscription, sink: AlarmStreamSink): () => void;
     private resolveAlarmScope;

package/dist/index.d.ts

@@ -1,14 +1,21 @@
-export type { DashboardDefinition, Canvas, CanvasBackground, CanvasGrid, CanvasSizing, Breakpoints, WidgetInstance, WidgetType, WidgetLayout, WidgetBox, DatasourceSelector, DeviceSelector, AnchorSelector, AnchorTarget, AnchorAggregation, DevicesSelector, RelatedTraversalSelector, SlotSelector, SlotDefinition, SlotScope, SlotBinding, SelectionTarget, SelectionCandidate, EntityCandidateLister, EntityListKind, MeasurementSample, LocationSample, LocationSeries, LocationSelection, AlarmRow, CommandRow, CommandParameter, CommandParamDataType, } from './types';
+export type { DashboardDefinition, Canvas, CanvasBackground, CanvasGrid, CanvasSizing, Breakpoints, WidgetInstance, KnownWidgetInstance, ExtensionWidgetInstance, ExtensionWidgetType, ResolvedWidgetInstance, UnknownWidgetInstance, UnknownWidgetType, UnresolvedWidgetCode, UnresolvedWidgetReason, WidgetImplementationRef, WidgetType, WidgetLayout, WidgetBox, DatasourceSelector, DeviceSelector, AnchorSelector, AnchorTarget, AnchorAggregation, DevicesSelector, RelatedTraversalSelector, SlotSelector, UnboundSelector, SlotDefinition, SlotScope, SlotBinding, SelectionTarget, SelectionCandidate, EntityCandidateLister, EntityListKind, MeasurementSample, LocationSample, LocationSeries, LocationSelection, AlarmRow, CommandRow, CommandParameter, CommandParamDataType, } from './types';
 export { COMMAND_STATUSES, isTerminalCommandStatus, isCancellableCommandStatus, type CommandStatus, } from './command-status';
-export { effectiveBindings, parseBindingManifest, stripDefaultBindings, type ParsedBindingManifest, } from './bindings';
+export { effectiveBindings, parseBindingManifest, resolveWidgetDatasource, stripDefaultBindings, type ParsedBindingManifest, } from './bindings';
 export { resolveContextBindings, hasScopedSlots, applySelection, bindingsWithoutScopedSlots, type MemberResolver, } from './context';
 export { migrateToSlots, bindWidgetSlot, clearWidgetDatasource, pruneSlots, widgetBinding, widgetSlotName, sameBinding, resolveConcrete, setSlotScope, anchorSlotNames, type ConcreteSelector, } from './slots';
 export { resolveSlotCandidates } from './candidates';
 export { createEntityLister } from './entity-lister';
-export { WIDGET_TYPES } from './types';
+export { WIDGET_TYPES, UNKNOWN_WIDGET_TYPE } from './types';
 export { DashboardHub, type DashboardHubConfig, type DeviceResolver, type WidgetStreamSink, type WidgetDataSource, type AlarmSubscription, type AlarmSnapshot, type AlarmStreamSink, type CommandSubscription, type CommandSnapshot, type CommandStreamSink, type CommandDispatch, type LocationSubscription, type LocationSnapshot, type LocationStreamSink, type WidgetActions, } from './hub';
 export { SyntheticDataSource, SYNTHETIC_GENERATORS, type SyntheticGenerator, type SyntheticDataSourceConfig, } from './synthetic';
-export { parseDashboardDefinition, parseSlotBinding, serializeDefinition, isDirty, resolveWidgetBox, activeBreakpoint, generateWidgetId, canScopeSlot, DashboardDefinitionError, BASE_BREAKPOINT, } from './definition';
+export { RECORDING_FORMAT_VERSION, RECORDING_KIND, RecordingFormatError, parseBoardRecording, recordedWallTimeMs, recordingBounds, simulationScaleAt, type BoardRecording, type RecordedAlarm, type RecordedAlarmEvent, type RecordedAlarmSnapshot, type RecordedChannels, type RecordedChapter, type RecordedClockSegment, type RecordedDevice, type RecordedMeasurementColumns, } from './recording';
+export { PLAYBACK_RATES, RECORDED_HISTORY_WINDOW_MS, NotInRecordingError, RecordedClock, RecordedDataSource, createRecordedClock, createRecordedLister, createRecordedResolver, type ClockEvent, type ClockTicker, type PlaybackRate, type RecordedChannel, type RecordedSiteOptions, } from './recorded';
+export { parseDashboardDefinition, type ParseDefinitionOptions, parseSlotBinding, serializeDefinition, storedDefinition, isDirty, resolveWidgetBox, activeBreakpoint, generateWidgetId, canScopeSlot, DashboardDefinitionError, BASE_BREAKPOINT, } from './definition';
 export { baseBox, setWidgetBox, deleteWidget, bringToFront, setTitle, setCanvasGrid, setCanvasSizing, updateWidget, addWidget, gridBoxToPx, pxToGridBox, type PixelRect, type GridGeometry, } from './editor-model';
 export { createDeviceResolver } from './resolver';
 export { defaultHistoryWindow, fetchWidgetHistory, type HistoryWindow } from './history';
+export type { AlarmStreamState, CommandStreamState, LocationStreamState, MeasurementStreamState, } from './channel-snapshots';
+export { applyOptionPatch, clampNumberOption, enumValues, numberSpec, validateOptions, HOST_OPTION_CONTROLS, type HostOptionControl, type BooleanOptionSpec, type DefaultsOf, type EnumOptionSpec, type GreaterThanConstraint, type NumberOptionSpec, type OptionConstraint, type OptionIssue, type OptionIssueCode, type OptionKeysOfKind, type OptionSpec, type OptionsOf, type RequiredOptionKeys, type SpecValue, type StringOptionSpec, type ValidateOptionsContext, type WidgetOptionSpecs, } from './option-schema';
+export { SDK_API_VERSION, defineWidgetDescriptor, isBuiltinWidgetId, isNamespacedWidgetId, type AckOptionRef, type BuiltinWidgetId, type ChannelBindingPolicy, type ChannelSnapshot, type ConstBinding, type DatasourcePolicy, type DatasourcePolicyFor, type DatasourceSelectorKind, type InteractionsFor, type NamespacedWidgetId, type NumberOptionRef, type StringOptionRef, type WidgetChannel, type WidgetDescriptor, type WidgetDisplay, type WidgetId, type WidgetInteractionDeclaration, } from './widget-descriptor';
+export { WidgetCatalogError, collectCatalogIssues, createWidgetCatalog, describeIssues, validateWidgetDescriptor, type DescriptorIssue, type WidgetCatalog, } from './widget-catalog';
+export { isBuiltinWidget, isResolvedWidget, parseWidgetRef, checkWidgetCompatibility, widgetVersionNotice, unresolvedWidgets, type UnresolvedWidgetReport, } from './widget-compat';