@devicechain/widget-sdk 0.0.0-stage → 0.20.0

package/dist/echarts.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/chart/echart.tsx", "../src/chart/chart-options.ts", "../src/chart/chart-theme.ts"],
+  "sourcesContent": ["// Copyright The DeviceChain Authors\n// SPDX-License-Identifier: Apache-2.0\n\n// A thin React wrapper over Apache ECharts (ADR-039 chart engine).\n//\n// It imports from echarts/core and registers ONLY the chart types + components the\n// widgets use (line + gauge, grid/tooltip, canvas renderer) \u2014 tree-shaking away the\n// rest of ECharts so the bundle carries only what a dashboard needs. The wrapper\n// owns the imperative lifecycle: init on mount, setOption on change, resize with the\n// container, dispose on unmount.\n\nimport { GaugeChart, LineChart } from 'echarts/charts';\nimport { GridComponent, TooltipComponent } from 'echarts/components';\nimport * as echarts from 'echarts/core';\nimport { CanvasRenderer } from 'echarts/renderers';\nimport { useEffect, useRef } from 'react';\n\necharts.use([LineChart, GaugeChart, GridComponent, TooltipComponent, CanvasRenderer]);\n\n// A resolved ECharts option object (the shape echarts.setOption accepts). Widgets\n// build these with the pure builders in chart-options.ts.\nexport type EChartOption = echarts.EChartsCoreOption;\n\nexport interface EChartProps {\n  option: EChartOption;\n  className?: string;\n  style?: React.CSSProperties;\n}\n\n// EChart fills its parent; the dashboard canvas sizes the parent, and a\n// ResizeObserver keeps the chart matched to it.\nexport function EChart({ option, className, style }: EChartProps) {\n  const containerRef = useRef<HTMLDivElement>(null);\n  const chartRef = useRef<echarts.ECharts | null>(null);\n\n  // Init + teardown once for the element's lifetime.\n  useEffect(() => {\n    const el = containerRef.current;\n    if (!el) return;\n\n    const chart = echarts.init(el);\n    chartRef.current = chart;\n\n    const observer = new ResizeObserver(() => chart.resize());\n    observer.observe(el);\n\n    return () => {\n      observer.disconnect();\n      chart.dispose();\n      chartRef.current = null;\n    };\n  }, []);\n\n  // Re-apply the option whenever it changes. notMerge:true so a shrinking series\n  // (rolling window) doesn't leave stale points behind.\n  useEffect(() => {\n    chartRef.current?.setOption(option, { notMerge: true });\n  }, [option]);\n\n  return (\n    <div ref={containerRef} className={className} style={{ width: '100%', height: '100%', ...style }} />\n  );\n}\n", "// Copyright The DeviceChain Authors\n// SPDX-License-Identifier: Apache-2.0\n\n// Pure ECharts option builders. Kept free of React/DOM so the data\u2192chart mapping\n// is unit-testable without a canvas: a widget resolves a ChartTheme + samples and\n// hands the result straight to <EChart>.\n\nimport type { MeasurementSample } from '@devicechain/dashboards';\n\nimport type { ElementSize } from '../hooks';\n\nimport type { ChartTheme } from './chart-theme';\nimport type { EChartOption } from './echart';\n\n// distinctNames returns the measurement names present in `samples`, in first-seen\n// order \u2014 used when a chart's datasource doesn't pin an explicit series list.\nfunction distinctNames(samples: MeasurementSample[]): string[] {\n  const seen: string[] = [];\n  for (const s of samples) {\n    if (!seen.includes(s.name)) seen.push(s.name);\n  }\n  return seen;\n}\n\nconst clamp = (v: number, lo: number, hi: number): number => Math.max(lo, Math.min(hi, v));\n\n// gauge/line fonts and tick counts scale with the smaller container dimension so a\n// widget stays legible when resized. A zero/absent size (before first measure, or\n// in a non-DOM test) falls back to a nominal medium size.\nfunction shortSide(size?: ElementSize): number {\n  const s = Math.min(size?.width ?? 0, size?.height ?? 0);\n  return s > 0 ? s : 200;\n}\n\nexport interface LineChartOptions {\n  // Measurement names to plot, one series each. Empty \u2192 every name seen in the\n  // window (first-seen order).\n  measurements?: string[];\n}\n\n// buildLineOption maps a rolling window of samples to a multi-series time chart,\n// one line per measurement name, coloured from the theme's chart palette.\nexport function buildLineOption(\n  samples: MeasurementSample[],\n  theme: ChartTheme,\n  options: LineChartOptions = {},\n  size?: ElementSize,\n): EChartOption {\n  const names = options.measurements?.length ? options.measurements : distinctNames(samples);\n  const axisFont = clamp(Math.round(shortSide(size) / 22), 8, 12);\n\n  const series = names.map((name, i) => {\n    const color = theme.series[i % theme.series.length];\n    return {\n      name,\n      type: 'line' as const,\n      showSymbol: false,\n      lineStyle: { color },\n      itemStyle: { color },\n      data: samples\n        .filter((s) => s.name === name && s.value != null && s.occurredTime != null)\n        .map((s) => [s.occurredTime as string, s.value as number]),\n    };\n  });\n\n  return {\n    animation: false,\n    textStyle: { color: theme.foreground, fontSize: axisFont },\n    grid: { left: 8, right: 12, top: names.length > 1 ? 28 : 12, bottom: 8, containLabel: true },\n    tooltip: { trigger: 'axis' },\n    legend:\n      names.length > 1 ? { textStyle: { color: theme.mutedForeground, fontSize: axisFont }, top: 0 } : undefined,\n    xAxis: {\n      type: 'time',\n      axisLine: { lineStyle: { color: theme.border } },\n      axisLabel: { color: theme.mutedForeground, fontSize: axisFont, hideOverlap: true },\n    },\n    yAxis: {\n      type: 'value',\n      splitLine: { lineStyle: { color: theme.border } },\n      axisLabel: { color: theme.mutedForeground, fontSize: axisFont },\n    },\n    series,\n  };\n}\n\nexport interface GaugeChartOptions {\n  min?: number;\n  max?: number;\n  unit?: string;\n}\n\n// buildGaugeOption maps a single latest value to a gauge. A null value (nothing\n// received yet) shows an em dash and rests the needle at the minimum. Ticks, fonts,\n// and the arc width scale with the widget size so it stays legible when resized\n// (ECharts' default gauge crams ~10 labels at fixed fonts on a small canvas).\nexport function buildGaugeOption(\n  value: number | null,\n  theme: ChartTheme,\n  options: GaugeChartOptions = {},\n  size?: ElementSize,\n): EChartOption {\n  const min = options.min ?? 0;\n  const max = options.max ?? 100;\n  const accent = theme.series[0];\n  const unitSuffix = options.unit ? ` ${options.unit}` : '';\n\n  const s = shortSide(size);\n  const arcWidth = clamp(Math.round(s / 26), 4, 12);\n  const labelFont = clamp(Math.round(s / 20), 8, 13);\n  const valueFont = clamp(Math.round(s / 7), 14, 40);\n\n  return {\n    animation: false,\n    series: [\n      {\n        type: 'gauge',\n        min,\n        max,\n        splitNumber: s < 160 ? 4 : 5, // fewer ticks than the default 10 \u2192 no cram\n        radius: '95%',\n        center: ['50%', '58%'],\n        progress: { show: true, width: arcWidth, itemStyle: { color: accent } },\n        pointer: { itemStyle: { color: accent }, length: '55%', width: clamp(Math.round(s / 50), 2, 6) },\n        anchor: { show: false },\n        axisLine: { lineStyle: { width: arcWidth, color: [[1, theme.border]] } },\n        axisTick: { show: false },\n        splitLine: { length: arcWidth, lineStyle: { color: theme.border, width: 1 } },\n        axisLabel: { color: theme.mutedForeground, fontSize: labelFont, distance: arcWidth + 2 },\n        detail: {\n          valueAnimation: false,\n          color: theme.foreground,\n          fontSize: valueFont,\n          offsetCenter: [0, '30%'],\n          formatter: (v: number) => (value == null ? '\u2014' : `${v}${unitSuffix}`),\n        },\n        data: [{ value: value ?? min }],\n      },\n    ],\n  };\n}\n", "// Copyright The DeviceChain Authors\n// SPDX-License-Identifier: Apache-2.0\n\n// The chart colour theme: concrete colours resolved from the host's CSS custom properties,\n// because an ECharts canvas cannot resolve `var(--x)`. Pure DOM + React, no echarts import,\n// but it lives on the `/echarts` subpath with the rest of the chart helpers so the SDK root\n// stays chart-free.\n\nimport { useMemo, useSyncExternalStore } from 'react';\n\nimport { useWidgetThemeRoot } from '../context';\n\n// Concrete colors for an ECharts canvas, resolved from the CSS variables in scope\n// at a given element (charts can't use CSS vars directly).\nexport interface ChartTheme {\n  foreground: string;\n  mutedForeground: string;\n  border: string;\n  series: string[];\n}\n\n// Fallbacks used when a variable is absent (e.g. jsdom, or a host that hasn't set\n// the token) so a chart still renders in sensible default colors.\nconst FALLBACK: ChartTheme = {\n  foreground: 'hsl(240 10% 3.9%)',\n  mutedForeground: 'hsl(240 3.8% 46.1%)',\n  border: 'hsl(240 5.9% 90%)',\n  series: [\n    'hsl(220 70% 50%)',\n    'hsl(160 60% 45%)',\n    'hsl(30 80% 55%)',\n    'hsl(280 65% 60%)',\n    'hsl(340 75% 55%)',\n  ],\n};\n\nfunction readVar(style: CSSStyleDeclaration, name: string, fallback: string): string {\n  const raw = style.getPropertyValue(`--${name}`).trim();\n  return raw ? `hsl(${raw})` : fallback;\n}\n\n// resolveChartTheme reads the theme tokens in scope at `el` into concrete colors\n// for ECharts. Reading at the element (not the document root) means a widget\n// nested under a re-themed subtree picks up the local override.\nexport function resolveChartTheme(el: Element): ChartTheme {\n  const style = getComputedStyle(el);\n  return {\n    foreground: readVar(style, 'foreground', FALLBACK.foreground),\n    mutedForeground: readVar(style, 'muted-foreground', FALLBACK.mutedForeground),\n    border: readVar(style, 'border', FALLBACK.border),\n    series: FALLBACK.series.map((fallback, i) => readVar(style, `chart-${i + 1}`, fallback)),\n  };\n}\n\n// --- shared chart-theme store ------------------------------------------------\n//\n// Charts need concrete colors resolved from the CSS-variable theme. Rather than\n// have every chart widget mount its own MutationObserver on <html> and recompute\n// the same theme, one page-wide observer resolves it once per change and every\n// widget reads the shared, memoized value via useSyncExternalStore \u2014 so a busy\n// dashboard pays O(1), not O(number of charts), per theme toggle.\n\nlet sharedTheme: ChartTheme | null = null;\nconst themeListeners = new Set<() => void>();\nlet themeObserver: MutationObserver | null = null;\n\nfunction recomputeTheme(): void {\n  sharedTheme = resolveChartTheme(document.documentElement);\n}\n\nfunction subscribeTheme(listener: () => void): () => void {\n  if (!themeObserver) {\n    recomputeTheme();\n    themeObserver = new MutationObserver(() => {\n      recomputeTheme();\n      for (const l of themeListeners) l();\n    });\n    themeObserver.observe(document.documentElement, {\n      attributes: true,\n      attributeFilter: ['class', 'style'],\n    });\n  }\n  themeListeners.add(listener);\n  return () => {\n    themeListeners.delete(listener);\n    if (themeListeners.size === 0 && themeObserver) {\n      themeObserver.disconnect();\n      themeObserver = null;\n      sharedTheme = null;\n    }\n  };\n}\n\nfunction getThemeSnapshot(): ChartTheme {\n  if (!sharedTheme) recomputeTheme();\n  return sharedTheme as ChartTheme;\n}\n\n// useChartTheme returns the current chart colors and re-renders the caller when\n// the document theme changes (a light/dark class or inline-style swap on <html>).\nexport function useChartTheme(): ChartTheme {\n  const shared = useSyncExternalStore(subscribeTheme, getThemeSnapshot, getThemeSnapshot);\n  // A host that scopes its tokens to a container says so (WidgetThemeRoot); its tokens are\n  // fixed for the container's life, so they are read once there rather than observed.\n  const root = useWidgetThemeRoot();\n  const scoped = useMemo(() => (root ? resolveChartTheme(root) : null), [root]);\n  return scoped ?? shared;\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/flash.d.ts

@@ -0,0 +1,13 @@
+import { type CSSProperties } from 'react';
+export type FlashDirection = 'up' | 'down' | null;
+export declare function useFlashOnChange(value: number | null | undefined, enabled: boolean, identity?: string | number): FlashDirection;
+export declare function flashTextStyle(direction: FlashDirection, fadeMs?: number): CSSProperties;
+export declare function flashBackgroundStyle(direction: FlashDirection, fadeMs?: number): CSSProperties;
+export declare function FlashValue({ value, precision, enabled, identity, baseColor, style, }: {
+    value: number | null | undefined;
+    precision?: number;
+    enabled: boolean;
+    identity?: string | number;
+    baseColor?: string;
+    style?: CSSProperties;
+}): import("react").JSX.Element;

package/dist/format.d.ts

@@ -0,0 +1,3 @@
+export declare function formatTimestamp(iso: string | null, timeZone?: string): string;
+export declare function formatDateTime(iso: string | null, timeZone?: string): string;
+export declare function formatValue(value: number | null | undefined, precision?: number): string;

package/dist/frame.d.ts

@@ -0,0 +1,8 @@
+import { type CSSProperties, type ReactNode } from 'react';
+export interface WidgetFrameProps {
+    title?: string;
+    subtitle?: string;
+    children: ReactNode;
+    bodyStyle?: CSSProperties;
+}
+export declare function WidgetFrame({ title, subtitle, children, bodyStyle }: WidgetFrameProps): import("react").JSX.Element;

package/dist/hooks.d.ts

@@ -0,0 +1,31 @@
+import type { AlarmSubscription, CommandSubscription, DashboardDefinition, DatasourceSelector, DeviceResolver, EntityCandidateLister, LocationSubscription, MemberResolver, MeasurementSample, SelectionCandidate, SlotBinding, WidgetDataSource } from '@devicechain/dashboards';
+import type { AlarmStreamState, CommandStreamState, LocationStreamState, MeasurementStreamState } from '@devicechain/dashboards';
+import { DashboardHub } from '@devicechain/dashboards';
+import { type RefObject } from 'react';
+import { type WidgetCandidates } from './context';
+export type { AlarmStreamState, CommandStreamState, LocationStreamState, MeasurementStreamState };
+export declare function useDashboardHub(resolver: DeviceResolver, authorities: string[] | undefined): DashboardHub;
+export declare function useResolvedBindings(definition: DashboardDefinition, base: Record<string, SlotBinding>, selection: Record<string, SlotBinding>, resolver: MemberResolver): Record<string, SlotBinding>;
+export declare function useSlotCandidates(definition: DashboardDefinition, bindings: Record<string, SlotBinding>, resolver: MemberResolver, lister: EntityCandidateLister | undefined): WidgetCandidates | undefined;
+export interface CandidatesState {
+    candidates: SelectionCandidate[];
+    loading: boolean;
+    error: unknown | null;
+    wired: boolean;
+}
+export declare function useCandidates(slot: string | undefined): CandidatesState;
+export interface MeasurementStreamOptions {
+    window?: number;
+    initialSamples?: MeasurementSample[];
+}
+export declare function useMeasurementStream(hub: WidgetDataSource, datasource: DatasourceSelector | undefined, options?: MeasurementStreamOptions): MeasurementStreamState;
+export declare function useAlarmStream(hub: WidgetDataSource, subscription: AlarmSubscription): AlarmStreamState;
+export declare function useCommandStream(hub: WidgetDataSource, subscription: CommandSubscription): CommandStreamState;
+export declare function useLocationStream(hub: WidgetDataSource, subscription: LocationSubscription): LocationStreamState;
+export type DatasourceAvailability = 'unknown' | 'available' | 'unavailable';
+export declare function useDatasourceAvailability(hub: WidgetDataSource, datasource: DatasourceSelector | undefined): DatasourceAvailability;
+export interface ElementSize {
+    width: number;
+    height: number;
+}
+export declare function useElementSize<T extends HTMLElement>(): [RefObject<T | null>, ElementSize];

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { defineWidget } from './define-widget';
+export type { ErasedComponent, ErasedWidgetDefinition, WidgetDefinition, WidgetImplementation } from './define-widget';
+export { createWidgetRegistry, WidgetRegistryError, type WidgetRegistry } from './registry';
+export type { EditorCommandChoice, EditorCommandChoices, WidgetComponent, WidgetEditorProps, WidgetEditorServices, WidgetProps, } from './widget';
+export { WidgetCandidatesProvider, WidgetSelectProvider, WidgetSubjectProvider, WidgetThemeRootProvider, WidgetTimeZoneProvider, useWidgetCandidates, useWidgetSelect, useWidgetSubject, useWidgetThemeRoot, useWidgetTimeZone, type WidgetCandidates, type WidgetSelect, } from './context';
+export { WidgetFrame, type WidgetFrameProps } from './frame';
+export { css, type ThemeVar } from './theme';
+export { formatDateTime, formatTimestamp, formatValue } from './format';
+export { FlashValue, flashBackgroundStyle, flashTextStyle, useFlashOnChange, type FlashDirection, } from './flash';
+export { optBoolean, optNumber, optString, pickSample, primaryMeasurementName } from './widget-options';
+export { useAlarmStream, useCandidates, useCommandStream, useDashboardHub, useDatasourceAvailability, useElementSize, useLocationStream, useMeasurementStream, useResolvedBindings, useSlotCandidates, type AlarmStreamState, type CandidatesState, type CommandStreamState, type DatasourceAvailability, type ElementSize, type LocationStreamState, type MeasurementStreamOptions, type MeasurementStreamState, } from './hooks';
+export { SDK_API_VERSION, WidgetCatalogError, defineWidgetDescriptor, isBuiltinWidgetId, isNamespacedWidgetId, validateWidgetDescriptor, type AckOptionRef, type BooleanOptionSpec, type BuiltinWidgetId, type ChannelBindingPolicy, type ChannelSnapshot, type ConstBinding, type DatasourcePolicy, type DatasourceSelectorKind, type DefaultsOf, type DescriptorIssue, type EnumOptionSpec, type GreaterThanConstraint, type NamespacedWidgetId, type NumberOptionRef, type NumberOptionSpec, type OptionConstraint, type OptionSpec, type OptionsOf, type StringOptionRef, type StringOptionSpec, type WidgetCatalog, type WidgetChannel, type WidgetDescriptor, type WidgetDisplay, type WidgetId, type WidgetInteractionDeclaration, type WidgetOptionSpecs, } from '@devicechain/dashboards';

package/dist/index.js

@@ -0,0 +1,546 @@
+import {
+  WidgetCandidatesProvider,
+  WidgetSelectProvider,
+  WidgetSubjectProvider,
+  WidgetThemeRootProvider,
+  WidgetTimeZoneProvider,
+  useWidgetCandidates,
+  useWidgetSelect,
+  useWidgetSubject,
+  useWidgetThemeRoot,
+  useWidgetTimeZone
+} from "./chunks/chunk-CC2V7LVI.js";
+
+// src/define-widget.ts
+function defineWidget(definition) {
+  return definition;
+}
+
+// src/registry.ts
+import {
+  WidgetCatalogError,
+  collectCatalogIssues,
+  createWidgetCatalog
+} from "@devicechain/dashboards";
+var WidgetRegistryError = class extends WidgetCatalogError {
+  constructor(issues) {
+    super(issues, "widget registry");
+    this.name = "WidgetRegistryError";
+  }
+};
+function isComponent(value) {
+  if (typeof value === "function") return true;
+  return typeof value === "object" && value !== null && "$$typeof" in value;
+}
+function createWidgetRegistry(definitions) {
+  if (!Array.isArray(definitions)) {
+    throw new WidgetRegistryError([{ id: "#?", path: "", message: "definitions must be an array" }]);
+  }
+  const issues = collectCatalogIssues(definitions.map((d) => d?.descriptor));
+  definitions.forEach((definition, index) => {
+    const id = definition?.descriptor?.id;
+    const label = typeof id === "string" && id !== "" ? id : `#${index}`;
+    const add = (path, message) => {
+      issues.push({ id: label, path, message });
+    };
+    const impl = definition?.implementation;
+    if (typeof impl !== "object" || impl === null) {
+      add("implementation", "a definition needs an implementation");
+      return;
+    }
+    if (impl.kind !== "trusted-react") {
+      add("implementation.kind", `kind must be "trusted-react", got ${JSON.stringify(impl.kind)}`);
+    }
+    if (!isComponent(impl.component)) add("implementation.component", "component must be a React component");
+    if (impl.editor !== void 0 && !isComponent(impl.editor)) {
+      add("implementation.editor", "editor, when given, must be a React component");
+    }
+  });
+  if (issues.length > 0) throw new WidgetRegistryError(issues);
+  const catalog = createWidgetCatalog(definitions.map((d) => d.descriptor));
+  const byId = /* @__PURE__ */ new Map();
+  for (const definition of definitions) {
+    byId.set(
+      definition.descriptor.id,
+      Object.freeze({
+        descriptor: catalog.get(definition.descriptor.id),
+        implementation: Object.freeze({ ...definition.implementation })
+      })
+    );
+  }
+  const ordered = Object.freeze([...byId.values()]);
+  return Object.freeze({
+    catalog,
+    descriptor: (id) => catalog.get(id),
+    implementation: (id) => byId.get(id)?.implementation,
+    list: () => ordered
+  });
+}
+
+// src/theme.ts
+function css(name) {
+  return `hsl(var(--${name}))`;
+}
+
+// src/frame.tsx
+import { jsx, jsxs } from "react/jsx-runtime";
+function WidgetFrame({ title, subtitle, children, bodyStyle }) {
+  const subject = useWidgetSubject();
+  const sub = subtitle ?? subject;
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      style: {
+        display: "flex",
+        flexDirection: "column",
+        width: "100%",
+        height: "100%",
+        boxSizing: "border-box",
+        background: css("card"),
+        color: css("card-foreground"),
+        border: `1px solid ${css("border")}`,
+        borderRadius: "var(--radius, 8px)",
+        overflow: "hidden"
+      },
+      children: [
+        title || sub ? /* @__PURE__ */ jsxs(
+          "div",
+          {
+            style: {
+              padding: "8px 12px",
+              borderBottom: `1px solid ${css("border")}`
+            },
+            children: [
+              title ? /* @__PURE__ */ jsx("div", { style: { fontSize: 12, fontWeight: 600, color: css("muted-foreground") }, children: title }) : null,
+              sub ? /* @__PURE__ */ jsx(
+                "div",
+                {
+                  title: sub,
+                  style: {
+                    fontSize: 11,
+                    fontWeight: 400,
+                    color: css("muted-foreground"),
+                    opacity: 0.75,
+                    marginTop: title ? 2 : 0,
+                    whiteSpace: "nowrap",
+                    overflow: "hidden",
+                    textOverflow: "ellipsis"
+                  },
+                  children: sub
+                }
+              ) : null
+            ]
+          }
+        ) : null,
+        /* @__PURE__ */ jsx("div", { style: { flex: 1, minHeight: 0, ...bodyStyle }, children })
+      ]
+    }
+  );
+}
+
+// src/format.ts
+function formatTimestamp(iso, timeZone) {
+  if (!iso) return "";
+  const date = new Date(iso);
+  if (Number.isNaN(date.getTime())) return iso;
+  return timeZone ? date.toLocaleTimeString(void 0, { timeZone, timeZoneName: "short" }) : date.toLocaleTimeString();
+}
+function formatDateTime(iso, timeZone) {
+  if (!iso) return "";
+  const date = new Date(iso);
+  if (Number.isNaN(date.getTime())) return iso;
+  return timeZone ? date.toLocaleString(void 0, { timeZone, timeZoneName: "short" }) : date.toLocaleString();
+}
+function formatValue(value, precision) {
+  if (value == null) return "\u2014";
+  if (precision == null) return String(value);
+  const places = Math.min(100, Math.max(0, Math.trunc(precision)));
+  return value.toFixed(places);
+}
+
+// src/flash.tsx
+import { useEffect, useRef, useState } from "react";
+import { jsx as jsx2 } from "react/jsx-runtime";
+var UP = {
+  fg: "var(--flash-up, hsl(142 72% 40%))",
+  bg: "var(--flash-up-bg, hsl(142 72% 45% / 0.16))"
+};
+var DOWN = {
+  fg: "var(--flash-down, hsl(0 72% 51%))",
+  bg: "var(--flash-down-bg, hsl(0 72% 55% / 0.16))"
+};
+var HOLD_MS = 400;
+var FADE_MS = 600;
+function useFlashOnChange(value, enabled, identity) {
+  const prev = useRef(value);
+  const prevIdentity = useRef(identity);
+  const [direction, setDirection] = useState(null);
+  useEffect(() => {
+    const before = prev.current;
+    const sameEntity = prevIdentity.current === identity;
+    prev.current = value;
+    prevIdentity.current = identity;
+    if (!enabled || !sameEntity || typeof value !== "number" || typeof before !== "number" || !Number.isFinite(value) || !Number.isFinite(before) || value === before) {
+      setDirection(null);
+      return;
+    }
+    setDirection(value > before ? "up" : "down");
+    const timer = setTimeout(() => setDirection(null), HOLD_MS);
+    return () => clearTimeout(timer);
+  }, [value, enabled, identity]);
+  return enabled ? direction : null;
+}
+function flashTextStyle(direction, fadeMs = FADE_MS) {
+  if (direction) return { color: direction === "up" ? UP.fg : DOWN.fg, transition: "none" };
+  return { transition: `color ${fadeMs}ms ease-out` };
+}
+function flashBackgroundStyle(direction, fadeMs = FADE_MS) {
+  if (direction) {
+    return { backgroundColor: direction === "up" ? UP.bg : DOWN.bg, transition: "none" };
+  }
+  return { transition: `background-color ${fadeMs}ms ease-out` };
+}
+function FlashValue({
+  value,
+  precision,
+  enabled,
+  identity,
+  baseColor = "inherit",
+  style
+}) {
+  const direction = useFlashOnChange(value, enabled, identity);
+  return /* @__PURE__ */ jsx2("span", { style: { color: baseColor, ...style, ...flashTextStyle(direction) }, children: formatValue(value, precision) });
+}
+
+// src/widget-options.ts
+function pickSample(latest, name) {
+  return name ? latest[name] : Object.values(latest)[0];
+}
+function optString(options, key) {
+  const value = options?.[key];
+  return typeof value === "string" ? value : void 0;
+}
+function optNumber(options, key) {
+  const value = options?.[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function optBoolean(options, key) {
+  return options?.[key] === true;
+}
+function primaryMeasurementName(widget) {
+  const explicit = optString(widget.options, "measurement");
+  if (explicit) return explicit;
+  const ds = widget.datasource;
+  if (ds && ds.measurements.length > 0) return ds.measurements[0];
+  return void 0;
+}
+
+// src/hooks.ts
+import {
+  bindingsWithoutScopedSlots,
+  DashboardHub,
+  hasScopedSlots,
+  resolveContextBindings,
+  resolveSlotCandidates
+} from "@devicechain/dashboards";
+import { useEffect as useEffect2, useMemo, useRef as useRef2, useState as useState2 } from "react";
+function useDashboardHub(resolver, authorities) {
+  const authoritiesKey = JSON.stringify(authorities ?? []);
+  const hub = useMemo(
+    () => new DashboardHub({ resolver, authorities }),
+    // authorities read via authoritiesKey (value identity), not reference.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [resolver, authoritiesKey]
+  );
+  useEffect2(() => () => hub.disposeAll(), [hub]);
+  return hub;
+}
+function useResolvedBindings(definition, base, selection, resolver) {
+  const scoped = useMemo(() => hasScopedSlots(definition), [definition]);
+  const overlaid = useMemo(() => ({ ...base, ...selection }), [base, selection]);
+  const [resolved, setResolved] = useState2(() => bindingsWithoutScopedSlots(definition, overlaid));
+  const genRef = useRef2(0);
+  useEffect2(() => {
+    if (!scoped) {
+      setResolved((prev) => sameBindings(prev, overlaid) ? prev : overlaid);
+      return;
+    }
+    const gen = ++genRef.current;
+    let live = true;
+    resolveContextBindings(definition, base, selection, resolver).then((next) => {
+      if (!live || gen !== genRef.current) return;
+      setResolved((prev) => sameBindings(prev, next) ? prev : next);
+    }).catch(() => {
+    });
+    return () => {
+      live = false;
+    };
+  }, [scoped, definition, base, selection, resolver, overlaid]);
+  return scoped ? resolved : overlaid;
+}
+function sameBindings(a, b) {
+  const ak = Object.keys(a).sort();
+  const bk = Object.keys(b).sort();
+  if (ak.length !== bk.length) return false;
+  for (let i = 0; i < ak.length; i += 1) {
+    if (ak[i] !== bk[i]) return false;
+    if (JSON.stringify(a[ak[i]]) !== JSON.stringify(b[bk[i]])) return false;
+  }
+  return true;
+}
+function useSlotCandidates(definition, bindings, resolver, lister) {
+  const bindingsKey = JSON.stringify(bindings);
+  return useMemo(
+    () => {
+      if (!lister) return void 0;
+      return (slot) => resolveSlotCandidates(definition, slot, bindings, resolver, lister);
+    },
+    // bindings read via bindingsKey (value identity), not reference.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [definition, bindingsKey, resolver, lister]
+  );
+}
+function useCandidates(slot) {
+  const provider = useWidgetCandidates();
+  const wired = !!provider;
+  const [state, setState] = useState2(() => ({
+    candidates: [],
+    loading: Boolean(provider && slot),
+    error: null
+  }));
+  const genRef = useRef2(0);
+  useEffect2(() => {
+    if (!provider || !slot) {
+      setState({ candidates: [], loading: false, error: null });
+      return;
+    }
+    const gen = ++genRef.current;
+    let live = true;
+    setState((prev) => ({ ...prev, loading: true, error: null }));
+    provider(slot).then((candidates) => {
+      if (live && gen === genRef.current) setState({ candidates, loading: false, error: null });
+    }).catch((error) => {
+      if (live && gen === genRef.current) setState({ candidates: [], loading: false, error });
+    });
+    return () => {
+      live = false;
+    };
+  }, [provider, slot]);
+  return { ...state, wired };
+}
+var EMPTY = { latest: {}, samples: [], error: null };
+function latestOf(samples) {
+  const latest = {};
+  for (const s of samples) latest[s.name] = s;
+  return latest;
+}
+function useMeasurementStream(hub, datasource, options = {}) {
+  const windowSize = options.window ?? 300;
+  const initialSamples = options.initialSamples;
+  const key = datasource ? JSON.stringify(datasource) : null;
+  const [tagged, setTagged] = useState2({
+    key,
+    state: EMPTY
+  });
+  const live = tagged.key === key ? tagged.state : EMPTY;
+  useEffect2(() => {
+    setTagged({ key, state: EMPTY });
+    if (!datasource) return;
+    const update = (fn) => setTagged((prev) => prev.key === key ? { key, state: fn(prev.state) } : prev);
+    return hub.subscribeWidget(datasource, {
+      next: (sample) => update((prev) => {
+        const samples = prev.samples.concat(sample);
+        if (samples.length > windowSize) samples.splice(0, samples.length - windowSize);
+        return { latest: { ...prev.latest, [sample.name]: sample }, samples, error: null };
+      }),
+      error: (err) => update((prev) => ({ ...prev, error: err }))
+    });
+  }, [hub, key, windowSize]);
+  return useMemo(() => {
+    if (!initialSamples || initialSamples.length === 0) return live;
+    const merged = initialSamples.concat(live.samples);
+    const samples = merged.length > windowSize ? merged.slice(merged.length - windowSize) : merged;
+    return {
+      latest: { ...latestOf(initialSamples), ...live.latest },
+      samples,
+      error: live.error
+    };
+  }, [initialSamples, live, windowSize]);
+}
+var EMPTY_ALARMS = { alarms: [], total: 0, loading: true, error: null };
+function useAlarmStream(hub, subscription) {
+  const [state, setState] = useState2(EMPTY_ALARMS);
+  const key = JSON.stringify(subscription);
+  useEffect2(() => {
+    setState(EMPTY_ALARMS);
+    return hub.subscribeAlarms(subscription, {
+      next: (snapshot) => setState({ alarms: snapshot.alarms, total: snapshot.total, loading: false, error: null }),
+      error: (err) => setState((prev) => ({ ...prev, loading: false, error: err }))
+    });
+  }, [hub, key]);
+  return state;
+}
+var EMPTY_COMMANDS = {
+  deviceToken: null,
+  commands: [],
+  total: 0,
+  loading: true,
+  error: null
+};
+function useCommandStream(hub, subscription) {
+  const [state, setState] = useState2(EMPTY_COMMANDS);
+  const key = JSON.stringify(subscription);
+  useEffect2(() => {
+    setState(EMPTY_COMMANDS);
+    return hub.subscribeCommands(subscription, {
+      next: (snapshot) => setState({
+        deviceToken: snapshot.deviceToken,
+        commands: snapshot.commands,
+        total: snapshot.total,
+        loading: false,
+        error: null
+      }),
+      error: (err) => setState((prev) => ({ ...prev, loading: false, error: err }))
+    });
+  }, [hub, key]);
+  return state;
+}
+var EMPTY_LOCATIONS = {
+  locations: [],
+  deviceTokens: [],
+  forbidden: false,
+  loading: true,
+  error: null
+};
+function useLocationStream(hub, subscription) {
+  const [state, setState] = useState2(EMPTY_LOCATIONS);
+  const key = JSON.stringify(subscription);
+  useEffect2(() => {
+    setState(EMPTY_LOCATIONS);
+    return hub.subscribeLocations(subscription, {
+      next: (snapshot) => setState(
+        snapshot.kind === "forbidden" ? { locations: [], deviceTokens: [], forbidden: true, loading: false, error: null } : {
+          locations: snapshot.locations,
+          deviceTokens: snapshot.deviceTokens,
+          forbidden: false,
+          loading: false,
+          error: null
+        }
+      ),
+      error: (err) => setState((prev) => ({ ...prev, loading: false, error: err }))
+    });
+  }, [hub, key]);
+  return state;
+}
+var AVAILABILITY_REVALIDATE_MS = 6e4;
+function useDatasourceAvailability(hub, datasource) {
+  const [state, setState] = useState2("unknown");
+  const key = datasource ? JSON.stringify(datasource) : null;
+  useEffect2(() => {
+    if (!datasource) {
+      setState("available");
+      return;
+    }
+    setState("unknown");
+    let cancelled = false;
+    let timer;
+    const stopTimer = () => {
+      if (timer) {
+        clearInterval(timer);
+        timer = void 0;
+      }
+    };
+    const check = () => {
+      hub.isDatasourceAvailable(datasource).then((ok) => {
+        if (cancelled) return;
+        setState(ok ? "available" : "unavailable");
+        if (ok) stopTimer();
+      }).catch(() => {
+        if (cancelled) return;
+        setState("available");
+        stopTimer();
+      });
+    };
+    check();
+    timer = setInterval(check, AVAILABILITY_REVALIDATE_MS);
+    return () => {
+      cancelled = true;
+      stopTimer();
+    };
+  }, [hub, key]);
+  return state;
+}
+function useElementSize() {
+  const ref = useRef2(null);
+  const [size, setSize] = useState2({ width: 0, height: 0 });
+  useEffect2(() => {
+    const el = ref.current;
+    if (!el || typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver((entries) => {
+      const rect = entries[0]?.contentRect;
+      if (!rect) return;
+      setSize(
+        (prev) => prev.width === rect.width && prev.height === rect.height ? prev : { width: rect.width, height: rect.height }
+      );
+    });
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, []);
+  return [ref, size];
+}
+
+// src/index.ts
+import {
+  SDK_API_VERSION,
+  WidgetCatalogError as WidgetCatalogError2,
+  defineWidgetDescriptor,
+  isBuiltinWidgetId,
+  isNamespacedWidgetId,
+  validateWidgetDescriptor
+} from "@devicechain/dashboards";
+export {
+  FlashValue,
+  SDK_API_VERSION,
+  WidgetCandidatesProvider,
+  WidgetCatalogError2 as WidgetCatalogError,
+  WidgetFrame,
+  WidgetRegistryError,
+  WidgetSelectProvider,
+  WidgetSubjectProvider,
+  WidgetThemeRootProvider,
+  WidgetTimeZoneProvider,
+  createWidgetRegistry,
+  css,
+  defineWidget,
+  defineWidgetDescriptor,
+  flashBackgroundStyle,
+  flashTextStyle,
+  formatDateTime,
+  formatTimestamp,
+  formatValue,
+  isBuiltinWidgetId,
+  isNamespacedWidgetId,
+  optBoolean,
+  optNumber,
+  optString,
+  pickSample,
+  primaryMeasurementName,
+  useAlarmStream,
+  useCandidates,
+  useCommandStream,
+  useDashboardHub,
+  useDatasourceAvailability,
+  useElementSize,
+  useFlashOnChange,
+  useLocationStream,
+  useMeasurementStream,
+  useResolvedBindings,
+  useSlotCandidates,
+  useWidgetCandidates,
+  useWidgetSelect,
+  useWidgetSubject,
+  useWidgetThemeRoot,
+  useWidgetTimeZone,
+  validateWidgetDescriptor
+};
+//# sourceMappingURL=index.js.map