@devicechain/dashboards 0.19.0 → 0.20.0

package/dist/option-schema.d.ts

@@ -0,0 +1,86 @@
+interface OptionSpecBase {
+    doc: string;
+    required?: true;
+    label?: string;
+    help?: string;
+    labelId?: string;
+    helpId?: string;
+    control?: string;
+}
+export declare const HOST_OPTION_CONTROLS: readonly ['command-vocabulary', 'slot-target', 'basemap'];
+export type HostOptionControl = (typeof HOST_OPTION_CONTROLS)[number];
+export interface StringOptionSpec extends OptionSpecBase {
+    kind: 'string';
+    format?: 'json';
+}
+export interface NumberOptionSpec extends OptionSpecBase {
+    kind: 'number';
+    min?: number;
+    max?: number;
+    integer?: true;
+}
+export interface BooleanOptionSpec extends OptionSpecBase {
+    kind: 'boolean';
+}
+export interface EnumOptionSpec<V extends string = string> extends OptionSpecBase {
+    kind: 'enum';
+    values: readonly V[];
+    valueLabels?: Readonly<Record<string, string>>;
+    valueLabelIds?: Readonly<Record<string, string>>;
+    placeholder?: string;
+    placeholderId?: string;
+}
+export type OptionSpec = StringOptionSpec | NumberOptionSpec | BooleanOptionSpec | EnumOptionSpec;
+export type WidgetOptionSpecs = Record<string, OptionSpec>;
+export interface GreaterThanConstraint<K extends string = string> {
+    kind: 'greater-than';
+    key: K;
+    than: K;
+}
+export type OptionConstraint<K extends string = string> = GreaterThanConstraint<K>;
+export type SpecValue<S> = S extends {
+    kind: 'enum';
+    values: readonly (infer V)[];
+} ? V extends string ? V : never : S extends {
+    kind: 'number';
+} ? number : S extends {
+    kind: 'boolean';
+} ? boolean : S extends {
+    kind: 'string';
+} ? string : never;
+export type RequiredOptionKeys<S> = {
+    [K in keyof S]: S[K] extends {
+        required: true;
+    } ? K : never;
+}[keyof S];
+export type OptionsOf<S> = {
+    [K in RequiredOptionKeys<S>]: SpecValue<S[K]>;
+} & {
+    [K in Exclude<keyof S, RequiredOptionKeys<S>>]?: SpecValue<S[K]>;
+};
+export type DefaultsOf<S> = {
+    [K in keyof S]?: SpecValue<S[K]>;
+};
+export type OptionKeysOfKind<S, Kind extends OptionSpec['kind']> = {
+    [K in keyof S & string]: S[K] extends infer X ? (X extends {
+        kind: Kind;
+    } ? K : never) : never;
+}[keyof S & string];
+export type OptionIssueCode = 'unknown' | 'type' | 'enum' | 'range' | 'missing' | 'json' | 'invariant';
+export interface OptionIssue {
+    widgetId: string;
+    key: string;
+    code: OptionIssueCode;
+    message: string;
+}
+export interface ValidateOptionsContext {
+    constraints?: readonly OptionConstraint[];
+    label: string;
+}
+export declare function hasOwn(obj: object, key: string): boolean;
+export declare function validateOptions(specs: WidgetOptionSpecs, options: Record<string, unknown> | undefined, context: ValidateOptionsContext): OptionIssue[];
+export declare function numberSpec(specs: WidgetOptionSpecs, key: string): NumberOptionSpec | undefined;
+export declare function clampNumberOption(spec: NumberOptionSpec | undefined, value: number): number | undefined;
+export declare function enumValues(specs: WidgetOptionSpecs, key: string): readonly string[] | undefined;
+export declare function applyOptionPatch(specs: WidgetOptionSpecs, options: Readonly<Record<string, unknown>> | undefined, patch: Readonly<Record<string, unknown>>, label?: string): Record<string, unknown>;
+export {};

package/dist/recorded.d.ts

@@ -0,0 +1,80 @@
+import type { AlarmStreamSink, AlarmSubscription, CommandStreamSink, CommandSubscription, DeviceResolver, LocationStreamSink, LocationSubscription, WidgetDataSource, WidgetStreamSink } from './hub';
+import type { AnchorTarget, DatasourceSelector, EntityCandidateLister } from './types';
+import { type BoardRecording } from './recording';
+export declare const RECORDED_HISTORY_WINDOW_MS: number;
+export type RecordedChannel = 'measurements' | 'alarms' | 'locations' | 'commands';
+export declare class NotInRecordingError extends Error {
+    readonly channel: RecordedChannel;
+    readonly detail: string;
+    constructor(channel: RecordedChannel, detail?: string);
+    toString(): string;
+}
+export declare const PLAYBACK_RATES: readonly [1, 4, 16];
+export type PlaybackRate = (typeof PLAYBACK_RATES)[number];
+export interface ClockEvent {
+    timeMs: number;
+    reason: 'tick' | 'seek' | 'state';
+}
+export interface ClockTicker {
+    start(onFrame: (wallDeltaMs: number) => void): () => void;
+}
+export declare class RecordedClock {
+    readonly durationMs: number;
+    readonly minMs: number;
+    private time;
+    private isPlaying;
+    private playbackRate;
+    private stopTicker;
+    private readonly ticker;
+    private readonly listeners;
+    constructor(durationMs: number, options?: {
+        ticker?: ClockTicker;
+        startMs?: number;
+        minMs?: number;
+    });
+    get timeMs(): number;
+    get playing(): boolean;
+    get rate(): PlaybackRate;
+    get ended(): boolean;
+    play(): void;
+    pause(): void;
+    seek(tMs: number): void;
+    setRate(rate: PlaybackRate): void;
+    advance(wallDeltaMs: number): void;
+    subscribe(listener: (ev: ClockEvent) => void): () => void;
+    private halt;
+    private clampTime;
+    private emit;
+}
+export declare function createRecordedClock(rec: BoardRecording, options?: {
+    ticker?: ClockTicker;
+}): RecordedClock;
+export interface RecordedSiteOptions {
+    siteAnchors?: readonly AnchorTarget[];
+}
+export declare function createRecordedResolver(rec: BoardRecording, options?: RecordedSiteOptions): DeviceResolver;
+export declare function createRecordedLister(rec: BoardRecording, options?: RecordedSiteOptions): EntityCandidateLister;
+export declare class RecordedDataSource implements WidgetDataSource {
+    private readonly rec;
+    private readonly site;
+    private readonly index;
+    private readonly startMs;
+    private readonly devices;
+    private readonly subs;
+    private readonly unlisten;
+    private cursor;
+    private stale;
+    constructor(rec: BoardRecording, clock: RecordedClock, options?: RecordedSiteOptions);
+    get isStale(): boolean;
+    private onClock;
+    private iso;
+    private open;
+    private resolve;
+    private failLater;
+    subscribeWidget(datasource: DatasourceSelector, sink: WidgetStreamSink): () => void;
+    subscribeAlarms(subscription: AlarmSubscription, sink: AlarmStreamSink): () => void;
+    subscribeCommands(_subscription: CommandSubscription, sink: CommandStreamSink): () => void;
+    subscribeLocations(subscription: LocationSubscription, sink: LocationStreamSink): () => void;
+    isDatasourceAvailable(datasource: DatasourceSelector | undefined): Promise<boolean>;
+    disposeAll(): void;
+}

package/dist/recording.d.ts

@@ -0,0 +1,104 @@
+export declare const RECORDING_FORMAT_VERSION = 1;
+export declare const RECORDING_KIND = "sitepulse-board-recording";
+declare const ALARM_STATES: readonly ['ACTIVE', 'CLEARED'];
+declare const ALARM_SEVERITIES: readonly ['CRITICAL', 'MAJOR', 'MINOR', 'WARNING'];
+export declare class RecordingFormatError extends Error {
+    readonly path: string;
+    constructor(path: string, reason: string);
+}
+export interface RecordedClockSegment {
+    fromMs: number;
+    mode: string;
+    scale: number;
+}
+export interface RecordedDevice {
+    id: string;
+    token: string;
+    kind: string;
+}
+export interface RecordedChannels {
+    measurements: string[];
+    alarms: boolean;
+    locations: false;
+    commands: false;
+}
+export interface RecordedChapter {
+    tMs: number;
+    name: string;
+    note: string;
+}
+export interface RecordedMeasurementColumns {
+    d: number[];
+    n: number[];
+    t: number[];
+    v: number[];
+    s: Array<0 | 1>;
+}
+export interface RecordedAlarm {
+    id: string;
+    dev: string;
+    key: string;
+    metric: string;
+    state: (typeof ALARM_STATES)[number];
+    sev: (typeof ALARM_SEVERITIES)[number];
+    occ: string;
+    ack?: true;
+}
+export interface RecordedAlarmSnapshot {
+    tMs: number;
+    requestedAtMs: number;
+    total: number;
+    alarms: RecordedAlarm[];
+}
+export interface RecordedAlarmEvent extends RecordedAlarm {
+    tMs: number;
+}
+export interface BoardRecording {
+    kind: typeof RECORDING_KIND;
+    formatVersion: typeof RECORDING_FORMAT_VERSION;
+    runId: string;
+    startedAtUtc: string;
+    durationMs: number;
+    platformVersion: string;
+    instance: string;
+    tenant: string;
+    build: {
+        gitSha: string;
+        sdkCommit: string;
+    };
+    clock: RecordedClockSegment[];
+    devices: RecordedDevice[];
+    channels: RecordedChannels;
+    board: {
+        path: string;
+        sourceCommit: string;
+        sha256: string;
+    };
+    sourceHashes: Record<string, string>;
+    converter: {
+        version: number;
+    };
+    chapters: RecordedChapter[];
+    excerpt?: {
+        fromMs: number;
+        toMs: number;
+    };
+    measurements: RecordedMeasurementColumns;
+    alarms: {
+        snapshots: RecordedAlarmSnapshot[];
+        events: RecordedAlarmEvent[];
+    };
+    locations: [];
+}
+export declare function recordingBounds(rec: BoardRecording): {
+    fromMs: number;
+    toMs: number;
+};
+export declare function recordedWallTimeMs(rec: BoardRecording, tMs: number): number;
+export declare function simulationScaleAt(rec: BoardRecording, tMs: number): {
+    mode: string;
+    scale: number;
+} | null;
+export declare function compareInstants(a: string, b: string): number;
+export declare function parseBoardRecording(input: unknown): BoardRecording;
+export {};

package/dist/slots.d.ts

@@ -1,4 +1,4 @@
-import type { AnchorTarget, DashboardDefinition, LocationSelection, SlotBinding, SlotScope, WidgetInstance } from './types';
+import { type AnchorTarget, type DashboardDefinition, type LocationSelection, type SlotBinding, type SlotScope, type WidgetInstance } from './types';
 export declare function sameBinding(a: SlotBinding | undefined, b: SlotBinding | undefined): boolean;
 export declare function migrateToSlots(def: DashboardDefinition): DashboardDefinition;
 export declare function bindWidgetSlot(def: DashboardDefinition, widgetId: string, binding: SlotBinding, measurements: string[], location?: LocationSelection): DashboardDefinition;

package/dist/types.d.ts

@@ -43,7 +43,12 @@ export interface SlotSelector {
     measurements: string[];
     location?: LocationSelection;
 }
-export type DatasourceSelector = DeviceSelector | AnchorSelector | DevicesSelector | RelatedTraversalSelector | SlotSelector;
+export interface UnboundSelector {
+    kind: 'unbound';
+    measurements: string[];
+    location?: LocationSelection;
+}
+export type DatasourceSelector = DeviceSelector | AnchorSelector | DevicesSelector | RelatedTraversalSelector | SlotSelector | UnboundSelector;
 export declare const WIDGET_TYPES: readonly ['timeseries-chart', 'latest-card', 'gauge', 'table', 'label', 'image', 'alarm-table', 'alarm-count', 'command-button', 'entity-selector', 'map'];
 export type WidgetType = (typeof WIDGET_TYPES)[number];
 export interface WidgetBox {
@@ -58,13 +63,51 @@ export interface WidgetBox {
     };
 }
 export type WidgetLayout = Record<string, WidgetBox>;
-export interface WidgetInstance {
+export declare const UNKNOWN_WIDGET_TYPE = "unknown-widget";
+export type UnknownWidgetType = typeof UNKNOWN_WIDGET_TYPE;
+export interface WidgetImplementationRef {
+    version: string;
+    optionsVersion: number;
+    sdkApiVersion?: number;
+}
+export type ExtensionWidgetType = `${string}/${string}`;
+export interface KnownWidgetInstance {
     id: string;
     type: WidgetType;
+    widget?: WidgetImplementationRef;
     layout: WidgetLayout;
     datasource?: DatasourceSelector;
     options?: Record<string, unknown>;
+    raw?: undefined;
+    reason?: undefined;
 }
+export interface ExtensionWidgetInstance {
+    id: string;
+    type: ExtensionWidgetType;
+    widget: WidgetImplementationRef;
+    layout: WidgetLayout;
+    datasource?: DatasourceSelector;
+    options?: Record<string, unknown>;
+    raw?: undefined;
+    reason?: undefined;
+}
+export type UnresolvedWidgetCode = 'unregistered' | 'unversioned' | 'invalid-metadata' | 'options-version' | 'sdk-incompatible';
+export interface UnresolvedWidgetReason {
+    code: UnresolvedWidgetCode;
+    message: string;
+}
+export interface UnknownWidgetInstance {
+    id: string;
+    type: UnknownWidgetType;
+    layout: WidgetLayout;
+    raw: Record<string, unknown>;
+    reason?: UnresolvedWidgetReason;
+    widget?: undefined;
+    datasource?: undefined;
+    options?: undefined;
+}
+export type WidgetInstance = KnownWidgetInstance | ExtensionWidgetInstance | UnknownWidgetInstance;
+export type ResolvedWidgetInstance = KnownWidgetInstance | ExtensionWidgetInstance;
 export interface CanvasBackground {
     color?: string | null;
     imageUrl?: string | null;

package/dist/widget-catalog.d.ts

@@ -0,0 +1,19 @@
+import { type WidgetDescriptor } from './widget-descriptor';
+export interface DescriptorIssue {
+    id: string;
+    path: string;
+    message: string;
+}
+export interface WidgetCatalog {
+    has(id: string): boolean;
+    get(id: string): WidgetDescriptor | undefined;
+    list(): readonly WidgetDescriptor[];
+}
+export declare class WidgetCatalogError extends Error {
+    readonly issues: readonly DescriptorIssue[];
+    constructor(issues: readonly DescriptorIssue[], subject?: string);
+}
+export declare function describeIssues(subject: string, issues: readonly DescriptorIssue[]): string;
+export declare function validateWidgetDescriptor(descriptor: unknown): DescriptorIssue[];
+export declare function createWidgetCatalog(descriptors: readonly WidgetDescriptor[]): WidgetCatalog;
+export declare function collectCatalogIssues(descriptors: readonly unknown[]): DescriptorIssue[];

package/dist/widget-compat.d.ts

@@ -0,0 +1,16 @@
+import type { WidgetCatalog } from './widget-catalog';
+import type { WidgetDescriptor } from './widget-descriptor';
+import type { DashboardDefinition, ResolvedWidgetInstance, UnresolvedWidgetReason, WidgetImplementationRef, WidgetInstance } from './types';
+import { type KnownWidgetInstance } from './types';
+export declare function isBuiltinWidget(widget: WidgetInstance): widget is KnownWidgetInstance;
+export declare function isResolvedWidget(widget: WidgetInstance): widget is ResolvedWidgetInstance;
+export declare function parseWidgetRef(raw: unknown): WidgetImplementationRef | undefined | null;
+export declare function checkWidgetCompatibility(id: string, ref: WidgetImplementationRef, descriptor: WidgetDescriptor): UnresolvedWidgetReason | undefined;
+export declare function widgetVersionNotice(id: string, ref: WidgetImplementationRef | undefined, descriptor: WidgetDescriptor): string | undefined;
+export declare function unresolvedReason(type: string, rawRef: unknown, catalog: WidgetCatalog | undefined, builtin: boolean): UnresolvedWidgetReason | undefined;
+export interface UnresolvedWidgetReport {
+    widgetId: string;
+    type: string;
+    reason: UnresolvedWidgetReason;
+}
+export declare function unresolvedWidgets(definition: Pick<DashboardDefinition, 'widgets'>): UnresolvedWidgetReport[];

package/dist/widget-descriptor.d.ts

@@ -0,0 +1,91 @@
+import type { AlarmStreamState, CommandStreamState, LocationStreamState, MeasurementStreamState } from './channel-snapshots';
+import type { DefaultsOf, OptionConstraint, OptionKeysOfKind, WidgetOptionSpecs } from './option-schema';
+import { type WidgetType } from './types';
+export type WidgetChannel = 'measurement' | 'alarm' | 'control' | 'selection' | 'location' | 'none';
+export type ChannelSnapshot<C extends WidgetChannel> = C extends 'measurement' ? MeasurementStreamState : C extends 'alarm' ? AlarmStreamState : C extends 'control' ? CommandStreamState : C extends 'location' ? LocationStreamState : null;
+export type BuiltinWidgetId = WidgetType;
+export type NamespacedWidgetId = `${string}/${string}`;
+export type WidgetId = BuiltinWidgetId | NamespacedWidgetId;
+export declare function isBuiltinWidgetId(id: unknown): id is BuiltinWidgetId;
+export declare function isNamespacedWidgetId(id: unknown): id is NamespacedWidgetId;
+export type DatasourceSelectorKind = 'device' | 'anchor' | 'slot';
+export type DatasourcePolicy = {
+    mode: 'none';
+} | {
+    mode: 'optional' | 'required';
+    selectors: readonly DatasourceSelectorKind[];
+};
+type ControlDatasourcePolicy = {
+    mode: 'none';
+} | {
+    mode: 'optional' | 'required';
+    selectors: readonly ('device' | 'slot')[];
+};
+export type DatasourcePolicyFor<C extends WidgetChannel> = C extends 'none' | 'selection' ? {
+    mode: 'none';
+} : C extends 'control' ? ControlDatasourcePolicy : DatasourcePolicy;
+export interface ConstBinding<T> {
+    const: T;
+}
+export interface NumberOptionRef<S extends WidgetOptionSpecs = WidgetOptionSpecs> {
+    option: OptionKeysOfKind<S, 'number'>;
+    default?: number;
+    min?: number;
+}
+export interface StringOptionRef<S extends WidgetOptionSpecs = WidgetOptionSpecs> {
+    option: OptionKeysOfKind<S, 'string' | 'enum'>;
+    default?: string;
+}
+export interface AckOptionRef<S extends WidgetOptionSpecs = WidgetOptionSpecs> {
+    option: OptionKeysOfKind<S, 'enum'>;
+    default?: 'true' | 'false';
+}
+type PageSize<S extends WidgetOptionSpecs> = ConstBinding<number> | NumberOptionRef<S>;
+export type ChannelBindingPolicy<C extends WidgetChannel, S extends WidgetOptionSpecs = WidgetOptionSpecs> = C extends 'measurement' ? {
+    window?: NumberOptionRef<S>;
+} : C extends 'alarm' ? {
+    pageSize: PageSize<S>;
+    state?: StringOptionRef<S>;
+    severity?: StringOptionRef<S>;
+    acknowledged?: AckOptionRef<S>;
+} : C extends 'control' ? {
+    pageSize: PageSize<S>;
+} : Record<string, never>;
+export interface WidgetInteractionDeclaration {
+    alarmActions?: true;
+    commandSend?: true;
+    selection?: true;
+    candidates?: true;
+}
+export type InteractionsFor<C extends WidgetChannel> = {
+    selection?: true;
+    candidates?: true;
+} & ('alarm' extends C ? {
+    alarmActions?: true;
+} : unknown) & ('control' extends C ? {
+    commandSend?: true;
+} : unknown);
+export interface WidgetDisplay {
+    title: string;
+    description?: string;
+    category?: string;
+    titleId?: string;
+    categoryId?: string;
+}
+export declare const SDK_API_VERSION = 1;
+export interface WidgetDescriptor<C extends WidgetChannel = WidgetChannel, S extends WidgetOptionSpecs = WidgetOptionSpecs> {
+    id: WidgetId;
+    version: string;
+    sdkApiVersion: 1;
+    optionsVersion: number;
+    display: WidgetDisplay;
+    channel: C;
+    datasource: DatasourcePolicyFor<C>;
+    binding: ChannelBindingPolicy<C, S>;
+    options: S;
+    constraints?: readonly OptionConstraint<OptionKeysOfKind<S, 'number'>>[];
+    defaults: DefaultsOf<S>;
+    interactions: InteractionsFor<C>;
+}
+export declare function defineWidgetDescriptor<const C extends WidgetChannel, const S extends WidgetOptionSpecs>(descriptor: WidgetDescriptor<C, S>): WidgetDescriptor<C, S>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devicechain/dashboards",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "DeviceChain dashboard runtime — the DashboardHub (telemetry subscription multiplexing over the client wire, plus the alarm, command and location channels) and the dashboard-definition, selector, slot, and binding-manifest types.",
   "keywords": [
     "devicechain",
@@ -46,14 +46,14 @@
     "@graphql-typed-document-node/core": "^3.2.0"
   },
   "peerDependencies": {
-    "@devicechain/client": "0.19.0",
+    "@devicechain/client": "0.20.0",
     "graphql": "^16.0.0 || ^17.0.0"
   },
   "devDependencies": {
-    "@devicechain/client": "0.19.0",
-    "@types/node": "^26.4.1",
+    "@devicechain/client": "0.20.0",
+    "@types/node": "^26.6.4",
     "graphql": "^17.0.2",
     "typescript": "~7.0.2",
-    "vitest": "^5.0.0"
+    "vitest": "^5.0.3"
   }
 }