@devicechain/widget-sdk 0.21.1-rc.1 → 0.22.0-rc.1

package/dist/index.js

@@ -1,15 +1,45 @@
 import {
+  ALARM_LEVELS,
+  FIT_MIN_FONT_PX,
+  SEVERITY_LEVELS,
+  SEVERITY_TOKENS,
+  WidgetBodySizeProvider,
   WidgetCandidatesProvider,
+  WidgetDensityProvider,
+  WidgetFrameStyleProvider,
+  WidgetFreshnessProvider,
   WidgetSelectProvider,
   WidgetSubjectProvider,
   WidgetThemeRootProvider,
+  WidgetTimeRangeProvider,
   WidgetTimeZoneProvider,
+  bandAt,
+  fitValueFont,
+  fitValueFontCss,
+  formatDateTime,
+  formatTimestamp,
+  formatValue,
+  isAlarmLevel,
+  isSeverityLevel,
+  levelColor,
+  optThresholds,
+  parseThresholds,
+  severityTokenCss,
+  severityVar,
+  stickyChars,
+  thresholdBands,
+  useSeverityColors,
+  useWidgetBodySize,
   useWidgetCandidates,
+  useWidgetDensityScale,
+  useWidgetFrameStyle,
+  useWidgetFreshness,
   useWidgetSelect,
   useWidgetSubject,
   useWidgetThemeRoot,
+  useWidgetTimeRange,
   useWidgetTimeZone
-} from "./chunks/chunk-CC2V7LVI.js";
+} from "./chunks/chunk-A5BJ2ALW.js";
 
 // src/define-widget.ts
 function defineWidget(definition) {
@@ -77,140 +107,12 @@ function createWidgetRegistry(definitions) {
   });
 }
 
-// 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 })
-      ]
-    }
-  );
-}
+import { resolveFrame, sameLabel } from "@devicechain/dashboards";
+import { useMemo as useMemo3 } from "react";
 
-// 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/freshness-readout.tsx
+import { useEffect, useState } from "react";
 
 // src/widget-options.ts
 function pickSample(latest, name) {
@@ -235,6 +137,208 @@ function primaryMeasurementName(widget) {
   return void 0;
 }
 
+// src/freshness.ts
+function resolveStaleAfterSeconds(options) {
+  const configured = optNumber(options, "staleAfterSeconds");
+  return configured !== void 0 && configured > 0 ? configured : void 0;
+}
+function newestSampleTime(latest, names) {
+  let newest;
+  for (const [name, sample] of Object.entries(latest)) {
+    if (names && names.length > 0 && !names.includes(name)) continue;
+    if (!sample.occurredTime) continue;
+    const at = Date.parse(sample.occurredTime);
+    if (Number.isNaN(at)) continue;
+    if (newest === void 0 || at > newest) newest = at;
+  }
+  return newest;
+}
+function ageSeconds(at, now) {
+  return Math.max(0, Math.floor((now - at) / 1e3));
+}
+function isStale(age, staleAfter) {
+  return staleAfter !== void 0 && age > staleAfter;
+}
+function viewerLocale() {
+  if (typeof document !== "undefined" && document.documentElement.lang) return document.documentElement.lang;
+  if (typeof navigator !== "undefined" && navigator.language) return navigator.language;
+  return void 0;
+}
+var formatters = /* @__PURE__ */ new Map();
+function relativeTimeFormat(locale) {
+  const key = locale ?? "";
+  let formatter = formatters.get(key);
+  if (!formatter) {
+    try {
+      formatter = new Intl.RelativeTimeFormat(locale, { numeric: "auto", style: "short" });
+    } catch {
+      formatter = new Intl.RelativeTimeFormat(void 0, { numeric: "auto", style: "short" });
+    }
+    formatters.set(key, formatter);
+  }
+  return formatter;
+}
+function formatAge(age, locale = viewerLocale()) {
+  const formatter = relativeTimeFormat(locale);
+  if (age < 60) return formatter.format(-age, "second");
+  if (age < 3600) return formatter.format(-Math.floor(age / 60), "minute");
+  if (age < 86400) return formatter.format(-Math.floor(age / 3600), "hour");
+  return formatter.format(-Math.floor(age / 86400), "day");
+}
+var FRESHNESS_STRINGS = {
+  en: { stale: "stale", ageLabel: "Last sample" },
+  es: { stale: "obsoleto", ageLabel: "\xDAltima muestra" }
+};
+function freshnessStrings(locale = viewerLocale()) {
+  const base = locale?.toLowerCase().split("-")[0];
+  return base === "es" ? FRESHNESS_STRINGS.es : FRESHNESS_STRINGS.en;
+}
+
+// src/theme.ts
+function css(name) {
+  return `hsl(var(--${name}))`;
+}
+
+// src/tokens.tsx
+import { DENSITY_SCALE, SPACE_TOKEN_PX } from "@devicechain/dashboards";
+import { jsx } from "react/jsx-runtime";
+var FONT_TOKENS = {
+  xs: 11,
+  sm: 12,
+  md: 13,
+  lg: 16,
+  xl: 20,
+  display: 28
+};
+var SPACE_TOKENS = {
+  1: SPACE_TOKEN_PX["space-1"],
+  2: SPACE_TOKEN_PX["space-2"],
+  3: SPACE_TOKEN_PX["space-3"],
+  4: SPACE_TOKEN_PX["space-4"]
+};
+function densityScale(density) {
+  return DENSITY_SCALE[density ?? "comfortable"];
+}
+function fontVar(token) {
+  return `var(--dc-font-${token}, ${FONT_TOKENS[token]}px)`;
+}
+function spaceVar(token) {
+  return `var(--dc-space-${token}, ${SPACE_TOKENS[token]}px)`;
+}
+function tokenPx(token, scale = 1) {
+  const [kind, name] = token.split("-");
+  const base = kind === "font" ? FONT_TOKENS[name] : SPACE_TOKENS[Number(name)];
+  return Math.round(base * scale * 100) / 100;
+}
+function tokenStyle(scale) {
+  const vars = { "--dc-scale": String(scale) };
+  for (const [name, px] of Object.entries(FONT_TOKENS)) vars[`--dc-font-${name}`] = `calc(${px}px * var(--dc-scale))`;
+  for (const [name, px] of Object.entries(SPACE_TOKENS)) vars[`--dc-space-${name}`] = `calc(${px}px * var(--dc-scale))`;
+  return vars;
+}
+function WidgetTokenStyles() {
+  return /* @__PURE__ */ jsx("style", { "data-dc-tokens": "", children: severityTokenCss({ hostWins: true }) });
+}
+
+// src/freshness-readout.tsx
+import { jsx as jsx2, jsxs } from "react/jsx-runtime";
+var tickers = /* @__PURE__ */ new Map();
+function subscribeTick(everyMs, listener) {
+  let ticker = tickers.get(everyMs);
+  if (!ticker) {
+    const listeners = /* @__PURE__ */ new Set();
+    const timer = setInterval(() => {
+      const now = Date.now();
+      for (const l of [...listeners]) l(now);
+    }, everyMs);
+    ticker = { timer, listeners };
+    tickers.set(everyMs, ticker);
+  }
+  ticker.listeners.add(listener);
+  const owned = ticker;
+  return () => {
+    owned.listeners.delete(listener);
+    if (owned.listeners.size === 0 && tickers.get(everyMs) === owned) {
+      clearInterval(owned.timer);
+      tickers.delete(everyMs);
+    }
+  };
+}
+function useNow(everyMs = 1e3, enabled = true) {
+  const [now, setNow] = useState(() => Date.now());
+  useEffect(() => {
+    if (!enabled) return;
+    setNow(Date.now());
+    return subscribeTick(everyMs, setNow);
+  }, [everyMs, enabled]);
+  return now;
+}
+function useFreshness(at, staleAfterSeconds) {
+  const now = useNow(1e3, at !== void 0);
+  const [seen, setSeen] = useState(void 0);
+  let current = seen;
+  if (at !== void 0 && seen?.at !== at) {
+    current = { at, seenAt: Math.max(now, Date.now()) };
+    setSeen(current);
+  }
+  if (at === void 0 || current === void 0) return void 0;
+  const age = ageSeconds(Math.min(at, current.seenAt), now);
+  return { age, stale: isStale(age, staleAfterSeconds) };
+}
+function StaleBadge({ label }) {
+  return /* @__PURE__ */ jsx2(
+    "span",
+    {
+      "data-stale-badge": "",
+      style: {
+        fontSize: fontVar("xs"),
+        fontWeight: 600,
+        textTransform: "uppercase",
+        letterSpacing: 0.4,
+        padding: "0 5px",
+        borderRadius: 4,
+        border: `1px dashed ${css("muted-foreground")}`,
+        color: css("foreground"),
+        background: css("muted"),
+        whiteSpace: "nowrap"
+      },
+      children: label ?? freshnessStrings().stale
+    }
+  );
+}
+function Freshness({ at, staleAfterSeconds, staleLabel, style }) {
+  const reading = useFreshness(at, staleAfterSeconds);
+  if (!reading) return null;
+  return /* @__PURE__ */ jsx2(FreshnessReadout, { reading, staleLabel, style });
+}
+function FreshnessReadout({
+  reading,
+  staleLabel,
+  style
+}) {
+  return /* @__PURE__ */ jsxs(
+    "span",
+    {
+      "data-freshness": "",
+      "data-stale": reading.stale ? "true" : void 0,
+      title: freshnessStrings().ageLabel,
+      style: {
+        display: "inline-flex",
+        alignItems: "center",
+        gap: 6,
+        fontSize: fontVar("xs"),
+        color: css("muted-foreground"),
+        fontVariantNumeric: "tabular-nums",
+        ...style
+      },
+      children: [
+        /* @__PURE__ */ jsx2("time", { children: formatAge(reading.age) }),
+        reading.stale ? /* @__PURE__ */ jsx2(StaleBadge, { label: staleLabel }) : null
+      ]
+    }
+  );
+}
+
 // src/hooks.ts
 import {
   bindingsWithoutScopedSlots,
@@ -243,7 +347,7 @@ import {
   resolveContextBindings,
   resolveSlotCandidates
 } from "@devicechain/dashboards";
-import { useEffect as useEffect2, useMemo, useRef as useRef2, useState as useState2 } from "react";
+import { useEffect as useEffect2, useMemo, useRef, useState as useState2, useSyncExternalStore } from "react";
 function useDashboardHub(resolver, authorities) {
   const authoritiesKey = JSON.stringify(authorities ?? []);
   const hub = useMemo(
@@ -259,7 +363,7 @@ 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);
+  const genRef = useRef(0);
   useEffect2(() => {
     if (!scoped) {
       setResolved((prev) => sameBindings(prev, overlaid) ? prev : overlaid);
@@ -308,7 +412,7 @@ function useCandidates(slot) {
     loading: Boolean(provider && slot),
     error: null
   }));
-  const genRef = useRef2(0);
+  const genRef = useRef(0);
   useEffect2(() => {
     if (!provider || !slot) {
       setState({ candidates: [], loading: false, error: null });
@@ -328,16 +432,49 @@ function useCandidates(slot) {
   }, [provider, slot]);
   return { ...state, wired };
 }
+var MAX_SPAN_SAMPLES = 2e3;
 var EMPTY = { latest: {}, samples: [], error: null };
 function latestOf(samples) {
   const latest = {};
   for (const s of samples) latest[s.name] = s;
   return latest;
 }
+function evictOldest(samples, max, evicted) {
+  if (samples.length <= max) return samples;
+  const cut = samples.length - max;
+  for (let i = 0; i < cut; i++) {
+    const at = Date.parse(samples[i].occurredTime ?? "");
+    if (at > evicted.current) evicted.current = at;
+  }
+  return samples.slice(cut);
+}
+function withinSpan(samples, spanSeconds, end) {
+  const from = end - spanSeconds * 1e3;
+  return samples.filter((s) => {
+    if (!s.occurredTime) return true;
+    const at = Date.parse(s.occurredTime);
+    return Number.isNaN(at) || at >= from;
+  });
+}
 function useMeasurementStream(hub, datasource, options = {}) {
-  const windowSize = options.window ?? 300;
+  const { windowSeconds, pausedAt } = options;
+  const windowSize = options.window ?? (windowSeconds !== void 0 ? MAX_SPAN_SAMPLES : 300);
   const initialSamples = options.initialSamples;
+  const paused = pausedAt !== void 0;
   const key = datasource ? JSON.stringify(datasource) : null;
+  const spanRef = useRef(windowSeconds);
+  const clockRef = useRef(options.now ?? Date.now);
+  const pausedRef = useRef(paused);
+  const queueRef = useRef([]);
+  const queueLatestRef = useRef({});
+  const evictedRef = useRef(-Infinity);
+  const flushRef = useRef(() => {
+  });
+  const clock = options.now ?? Date.now;
+  useEffect2(() => {
+    spanRef.current = windowSeconds;
+    clockRef.current = clock;
+  }, [windowSeconds, clock]);
   const [tagged, setTagged] = useState2({
     key,
     state: EMPTY
@@ -345,40 +482,79 @@ function useMeasurementStream(hub, datasource, options = {}) {
   const live = tagged.key === key ? tagged.state : EMPTY;
   useEffect2(() => {
     setTagged({ key, state: EMPTY });
+    queueRef.current = [];
+    queueLatestRef.current = {};
+    evictedRef.current = -Infinity;
+    flushRef.current = () => {
+    };
     if (!datasource) return;
     const update = (fn) => setTagged((prev) => prev.key === key ? { key, state: fn(prev.state) } : prev);
+    const fold = (prev, incoming, newest = latestOf(incoming)) => {
+      let samples = prev.samples.concat(incoming);
+      const span = spanRef.current;
+      if (span !== void 0) samples = withinSpan(samples, span, clockRef.current());
+      samples = evictOldest(samples, windowSize, evictedRef);
+      return { latest: { ...prev.latest, ...newest }, samples, error: null };
+    };
+    flushRef.current = () => {
+      const queued = queueRef.current;
+      if (queued.length === 0) return;
+      const newest = queueLatestRef.current;
+      queueRef.current = [];
+      queueLatestRef.current = {};
+      update((prev) => fold(prev, queued, newest));
+    };
     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 };
-      }),
+      next: (sample) => {
+        if (pausedRef.current) {
+          queueRef.current = evictOldest([...queueRef.current, sample], windowSize, evictedRef);
+          queueLatestRef.current[sample.name] = sample;
+          return;
+        }
+        update((prev) => fold(prev, [sample]));
+      },
       error: (err) => update((prev) => ({ ...prev, error: err }))
     });
   }, [hub, key, windowSize]);
+  useEffect2(() => {
+    pausedRef.current = paused;
+    if (!paused) flushRef.current();
+  }, [paused]);
   return useMemo(() => {
-    if (!initialSamples || initialSamples.length === 0) return live;
-    const merged = initialSamples.concat(live.samples);
+    const end = pausedAt ?? clock();
+    if (windowSeconds === void 0) {
+      if (!initialSamples || initialSamples.length === 0) return live;
+      const merged2 = initialSamples.concat(live.samples);
+      return {
+        latest: { ...latestOf(initialSamples), ...live.latest },
+        samples: merged2.length > windowSize ? merged2.slice(merged2.length - windowSize) : merged2,
+        error: live.error
+      };
+    }
+    const from = end - windowSeconds * 1e3;
+    const merged = withinSpan(initialSamples ? initialSamples.concat(live.samples) : live.samples, windowSeconds, end);
     const samples = merged.length > windowSize ? merged.slice(merged.length - windowSize) : merged;
-    return {
-      latest: { ...latestOf(initialSamples), ...live.latest },
-      samples,
-      error: live.error
-    };
-  }, [initialSamples, live, windowSize]);
+    const cut = samples.length < merged.length || evictedRef.current >= from;
+    const truncatedBefore = cut ? samples[0]?.occurredTime ?? void 0 : void 0;
+    const latest = initialSamples ? { ...latestOf(initialSamples), ...live.latest } : live.latest;
+    if (!truncatedBefore && latest === live.latest && samples.length === live.samples.length) return live;
+    const state = { latest, samples, error: live.error };
+    if (truncatedBefore) state.truncatedBefore = truncatedBefore;
+    return state;
+  }, [initialSamples, live, windowSize, windowSeconds, pausedAt, clock]);
 }
 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);
+  const [[at, state], setState] = useState2([key, EMPTY_ALARMS]);
   useEffect2(() => {
-    setState(EMPTY_ALARMS);
+    setState([key, 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 }))
+      next: (snapshot) => setState([key, { alarms: snapshot.alarms, total: snapshot.total, loading: false, error: null }]),
+      error: (err) => setState(([, prev]) => [key, { ...prev, loading: false, error: err }])
     });
   }, [hub, key]);
-  return state;
+  return at === key ? state : EMPTY_ALARMS;
 }
 var EMPTY_COMMANDS = {
   deviceToken: null,
@@ -413,12 +589,13 @@ var EMPTY_LOCATIONS = {
   error: null
 };
 function useLocationStream(hub, subscription) {
-  const [state, setState] = useState2(EMPTY_LOCATIONS);
   const key = JSON.stringify(subscription);
+  const [[at, state], setState] = useState2([key, EMPTY_LOCATIONS]);
   useEffect2(() => {
-    setState(EMPTY_LOCATIONS);
+    setState([key, EMPTY_LOCATIONS]);
     return hub.subscribeLocations(subscription, {
-      next: (snapshot) => setState(
+      next: (snapshot) => setState([
+        key,
         snapshot.kind === "forbidden" ? { locations: [], deviceTokens: [], forbidden: true, loading: false, error: null } : {
           locations: snapshot.locations,
           deviceTokens: snapshot.deviceTokens,
@@ -426,11 +603,11 @@ function useLocationStream(hub, subscription) {
           loading: false,
           error: null
         }
-      ),
-      error: (err) => setState((prev) => ({ ...prev, loading: false, error: err }))
+      ]),
+      error: (err) => setState(([, prev]) => [key, { ...prev, loading: false, error: err }])
     });
   }, [hub, key]);
-  return state;
+  return at === key ? state : EMPTY_LOCATIONS;
 }
 var AVAILABILITY_REVALIDATE_MS = 6e4;
 function useDatasourceAvailability(hub, datasource) {
@@ -470,8 +647,8 @@ function useDatasourceAvailability(hub, datasource) {
   }, [hub, key]);
   return state;
 }
-function useElementSize() {
-  const ref = useRef2(null);
+function useElementSize(step = 1) {
+  const ref = useRef(null);
   const [size, setSize] = useState2({ width: 0, height: 0 });
   useEffect2(() => {
     const el = ref.current;
@@ -479,15 +656,314 @@ function useElementSize() {
     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 }
-      );
+      const width = step > 1 ? Math.floor(rect.width / step) * step : rect.width;
+      const height = step > 1 ? Math.floor(rect.height / step) * step : rect.height;
+      setSize((prev) => prev.width === width && prev.height === height ? prev : { width, height });
     });
     observer.observe(el);
     return () => observer.disconnect();
-  }, []);
+  }, [step]);
   return [ref, size];
 }
+var NO_CONNECTION_SOURCE = {
+  connectionState: "live",
+  onConnectionState: () => () => {
+  }
+};
+function useHubConnectionState(hub) {
+  const source = hub && typeof hub.onConnectionState === "function" ? hub : NO_CONNECTION_SOURCE;
+  return useSyncExternalStore(
+    (listener) => source.onConnectionState(listener),
+    () => source.connectionState
+  );
+}
+
+// src/scale.ts
+import { useEffect as useEffect3, useMemo as useMemo2, useReducer, useRef as useRef2 } from "react";
+var SIZE_CLASS_BREAKS = {
+  compactWidth: 120,
+  compactHeight: 72,
+  largeWidth: 420,
+  largeHeight: 220
+};
+function sizeClassOf(size, scale = 1) {
+  if (!(size.width > 0) || !(size.height > 0)) return "regular";
+  const b = SIZE_CLASS_BREAKS;
+  if (size.width < b.compactWidth * scale || size.height < b.compactHeight * scale) return "compact";
+  if (size.width >= b.largeWidth * scale && size.height >= b.largeHeight * scale) return "large";
+  return "regular";
+}
+function makeWidgetScale(size, scale) {
+  return { sizeClass: sizeClassOf(size, scale), scale, size, px: (token) => tokenPx(token, scale) };
+}
+function useWidgetScale() {
+  const size = useWidgetBodySize();
+  const scale = useWidgetDensityScale();
+  return useMemo2(() => makeWidgetScale(size, scale), [size, scale]);
+}
+var STICKY_HOLD_MS = 6e4;
+function useStickyChars(chars, holdMs = STICKY_HOLD_MS) {
+  const held = useRef2(void 0);
+  const [tick, wake] = useReducer((n) => n + 1, 0);
+  held.current = stickyChars(held.current, chars, Date.now(), holdMs);
+  const { value, since } = held.current;
+  useEffect3(() => {
+    if (value <= chars) return;
+    const timer = setTimeout(wake, Math.max(0, since + holdMs - Date.now()));
+    return () => clearTimeout(timer);
+  }, [value, since, chars, holdMs, tick]);
+  return value;
+}
+
+// src/frame.tsx
+import { jsx as jsx3, jsxs as jsxs2 } from "react/jsx-runtime";
+var FRESHNESS_MIN_WIDTH = 150;
+var FRESHNESS_MIN_HEIGHT = 110;
+var FRAME_SUBTITLE_MIN_HEIGHT = 120;
+var FRAME_TITLE_MIN_HEIGHT = 76;
+var BODY_SIZE_STEP = 4;
+var DEFAULT_FRAME = resolveFrame(void 0, void 0);
+var RADIUS = {
+  none: "0px",
+  sm: "calc(var(--radius, 8px) / 2)",
+  md: "var(--radius, 8px)",
+  lg: "calc(var(--radius, 8px) * 1.5)"
+};
+function spaceTokenVar(token) {
+  return token === "space-0" ? "0px" : spaceVar(Number(token.slice("space-".length)));
+}
+function parseSampleTime(time) {
+  if (!time) return void 0;
+  const at = Date.parse(time);
+  return Number.isNaN(at) ? void 0 : at;
+}
+function WidgetFrame({ title, subtitle, children, bodyStyle, flush, sampleTime }) {
+  const subject = useWidgetSubject();
+  const rawSub = subtitle ?? subject;
+  const dupSub = rawSub && sameLabel(rawSub, title) ? void 0 : rawSub;
+  const freshness = useWidgetFreshness();
+  const at = freshness === void 0 ? void 0 : sampleTime === void 0 ? freshness.at : parseSampleTime(sampleTime);
+  const reading = useFreshness(at, freshness?.staleAfterSeconds);
+  const [rootRef, size] = useElementSize();
+  const [columnRef, columnSize] = useElementSize(BODY_SIZE_STEP);
+  const scale = useWidgetDensityScale();
+  const frame = useWidgetFrameStyle() ?? DEFAULT_FRAME;
+  const measured = size.height > 0;
+  const header = frame.header;
+  const showSub = header === "show" || header === "auto" && (!measured || size.height >= FRAME_SUBTITLE_MIN_HEIGHT * scale);
+  const showTitle = header === "show" || header === "auto" && (!measured || size.height >= FRAME_TITLE_MIN_HEIGHT * scale);
+  const rule = frame.border.width > 0 ? `${frame.border.width}px solid ${css(frame.border.color)}` : "none";
+  const sub = showSub ? dupSub : void 0;
+  const shownTitle = showTitle ? title : void 0;
+  const widgetScale = useMemo3(() => makeWidgetScale(columnSize, scale), [columnSize, scale]);
+  const compact = size.width > 0 && (size.width < FRESHNESS_MIN_WIDTH || size.height < FRESHNESS_MIN_HEIGHT);
+  const stale = reading?.stale === true;
+  return /* @__PURE__ */ jsxs2(
+    "div",
+    {
+      ref: rootRef,
+      "data-stale": stale ? "true" : void 0,
+      role: title && !showTitle ? "group" : void 0,
+      "aria-label": title && !showTitle ? title : void 0,
+      style: {
+        position: "relative",
+        display: "flex",
+        flexDirection: "column",
+        width: "100%",
+        height: "100%",
+        boxSizing: "border-box",
+        background: frame.background === "transparent" ? "transparent" : css(frame.background),
+        color: css("card-foreground"),
+        border: rule,
+        borderRadius: RADIUS[frame.border.radius],
+        overflow: "hidden"
+      },
+      children: [
+        shownTitle || sub ? /* @__PURE__ */ jsxs2(
+          "div",
+          {
+            style: {
+              padding: `${spaceVar(2)} ${spaceVar(3)}`,
+              borderBottom: rule
+            },
+            children: [
+              shownTitle ? /* @__PURE__ */ jsx3(
+                "div",
+                {
+                  title: shownTitle,
+                  style: {
+                    fontSize: fontVar("sm"),
+                    fontWeight: 600,
+                    color: css("muted-foreground"),
+                    whiteSpace: "nowrap",
+                    overflow: "hidden",
+                    textOverflow: "ellipsis"
+                  },
+                  children: shownTitle
+                }
+              ) : null,
+              sub ? /* @__PURE__ */ jsx3(
+                "div",
+                {
+                  title: sub,
+                  style: {
+                    fontSize: fontVar("xs"),
+                    fontWeight: 400,
+                    color: css("muted-foreground"),
+                    opacity: 0.75,
+                    marginTop: shownTitle ? 2 : 0,
+                    whiteSpace: "nowrap",
+                    overflow: "hidden",
+                    textOverflow: "ellipsis"
+                  },
+                  children: sub
+                }
+              ) : null
+            ]
+          }
+        ) : null,
+        /* @__PURE__ */ jsx3(
+          "div",
+          {
+            "data-widget-body": "",
+            style: {
+              position: "relative",
+              flex: 1,
+              minHeight: 0,
+              minWidth: 0,
+              overflow: "hidden",
+              ...bodyStyle,
+              ...stale ? { opacity: 0.45, filter: "grayscale(1)" } : null
+            },
+            children: /* @__PURE__ */ jsx3(
+              "div",
+              {
+                ref: columnRef,
+                "data-widget-content": "",
+                style: {
+                  position: "absolute",
+                  inset: 0,
+                  boxSizing: "border-box",
+                  containerType: "size",
+                  overflow: "hidden",
+                  padding: flush ? 0 : spaceTokenVar(frame.padding)
+                },
+                children: /* @__PURE__ */ jsx3(WidgetBodySizeProvider, { size: columnSize, children: typeof children === "function" ? children(widgetScale) : children })
+              }
+            )
+          }
+        ),
+        reading && !compact ? /* @__PURE__ */ jsx3(
+          "div",
+          {
+            "data-widget-freshness": "",
+            style: { padding: `${spaceVar(1)} ${spaceVar(3)}`, borderTop: rule, flex: "0 0 auto" },
+            children: /* @__PURE__ */ jsx3(FreshnessReadout, { reading })
+          }
+        ) : null,
+        reading && compact && stale ? /* @__PURE__ */ jsx3("div", { style: { position: "absolute", top: spaceVar(1), right: spaceVar(1) }, children: /* @__PURE__ */ jsx3(StaleBadge, {}) }) : null
+      ]
+    }
+  );
+}
+
+// src/connection-badge.tsx
+import { jsx as jsx4, jsxs as jsxs3 } from "react/jsx-runtime";
+var DOT = {
+  live: "primary",
+  reconnecting: "muted-foreground",
+  offline: "destructive"
+};
+function HubConnectionBadge({ state, labels }) {
+  return /* @__PURE__ */ jsxs3(
+    "span",
+    {
+      role: "status",
+      "data-connection-state": state,
+      style: {
+        display: "inline-flex",
+        alignItems: "center",
+        gap: 6,
+        fontSize: fontVar("sm"),
+        padding: "2px 8px",
+        borderRadius: 999,
+        border: `1px solid ${css("border")}`,
+        color: state === "offline" ? css("destructive") : css("muted-foreground"),
+        whiteSpace: "nowrap"
+      },
+      children: [
+        /* @__PURE__ */ jsx4(
+          "span",
+          {
+            "aria-hidden": true,
+            style: {
+              width: 8,
+              height: 8,
+              borderRadius: "50%",
+              background: css(DOT[state]),
+              opacity: state === "reconnecting" ? 0.6 : 1
+            }
+          }
+        ),
+        labels[state]
+      ]
+    }
+  );
+}
+
+// src/flash.tsx
+import { useEffect as useEffect4, useRef as useRef3, useState as useState3 } from "react";
+import { jsx as jsx5 } 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 = useRef3(value);
+  const prevIdentity = useRef3(identity);
+  const [direction, setDirection] = useState3(null);
+  useEffect4(() => {
+    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__ */ jsx5("span", { style: { color: baseColor, ...style, ...flashTextStyle(direction) }, children: formatValue(value, precision) });
+}
 
 // src/index.ts
 import {
@@ -499,32 +975,71 @@ import {
   validateWidgetDescriptor
 } from "@devicechain/dashboards";
 export {
+  ALARM_LEVELS,
+  FIT_MIN_FONT_PX,
+  FONT_TOKENS,
   FlashValue,
+  Freshness,
+  FreshnessReadout,
+  HubConnectionBadge,
+  MAX_SPAN_SAMPLES,
   SDK_API_VERSION,
+  SEVERITY_LEVELS,
+  SEVERITY_TOKENS,
+  SIZE_CLASS_BREAKS,
+  SPACE_TOKENS,
+  StaleBadge,
   WidgetCandidatesProvider,
   WidgetCatalogError2 as WidgetCatalogError,
+  WidgetDensityProvider,
   WidgetFrame,
+  WidgetFrameStyleProvider,
+  WidgetFreshnessProvider,
   WidgetRegistryError,
   WidgetSelectProvider,
   WidgetSubjectProvider,
   WidgetThemeRootProvider,
+  WidgetTimeRangeProvider,
   WidgetTimeZoneProvider,
+  WidgetTokenStyles,
+  ageSeconds,
+  bandAt,
   createWidgetRegistry,
   css,
   defineWidget,
   defineWidgetDescriptor,
+  densityScale,
+  fitValueFont,
+  fitValueFontCss,
   flashBackgroundStyle,
   flashTextStyle,
+  fontVar,
+  formatAge,
   formatDateTime,
   formatTimestamp,
   formatValue,
+  freshnessStrings,
+  isAlarmLevel,
   isBuiltinWidgetId,
   isNamespacedWidgetId,
+  isSeverityLevel,
+  isStale,
+  levelColor,
+  newestSampleTime,
   optBoolean,
   optNumber,
   optString,
+  optThresholds,
+  parseThresholds,
   pickSample,
   primaryMeasurementName,
+  resolveStaleAfterSeconds,
+  severityTokenCss,
+  severityVar,
+  spaceVar,
+  thresholdBands,
+  tokenPx,
+  tokenStyle,
   useAlarmStream,
   useCandidates,
   useCommandStream,
@@ -532,15 +1047,26 @@ export {
   useDatasourceAvailability,
   useElementSize,
   useFlashOnChange,
+  useFreshness,
+  useHubConnectionState,
   useLocationStream,
   useMeasurementStream,
+  useNow,
   useResolvedBindings,
+  useSeverityColors,
   useSlotCandidates,
+  useStickyChars,
   useWidgetCandidates,
+  useWidgetFrameStyle,
+  useWidgetFreshness,
+  useWidgetScale,
   useWidgetSelect,
   useWidgetSubject,
   useWidgetThemeRoot,
+  useWidgetTimeRange,
   useWidgetTimeZone,
-  validateWidgetDescriptor
+  validateWidgetDescriptor,
+  viewerLocale,
+  withinSpan
 };
 //# sourceMappingURL=index.js.map