@devicechain/dashboards 0.24.0-rc.1 → 0.25.0-rc.2

package/README.md

@@ -124,7 +124,11 @@ overlap, so there is no stacking order to manage.
 
 A board has a time range: `TIME_RANGE_PRESETS` (15 minutes to 7 days),
 `initialTimeRange`, `pauseRange` / `resumeRange` and `rangeWindow` manage it, and
-`timeRangeFromSearch` reads the `range` and `paused` URL parameters. Its density
+`timeRangeLinkFromSearch` reads the `range`, `paused` and `from` / `to` URL parameters
+(`timeRangeFromSearch` reads only `range` and `paused`, for a host that knows no fixed window). A fixed
+from-to window is an additive variant of the same state: `absoluteRange` builds it and
+`TimeRangeState.absolute` marks it, while `paused`, `pausedAt` and `spanSeconds` still describe the
+window as a frozen rolling range, so code that only knows rolling ranges keeps working. Its density
 (`CANVAS_DENSITIES`: `compact`, `comfortable`, `wall`) scales every text and
 spacing size by `DENSITY_SCALE`; a host may override the board's own value at
 view time.

package/dist/hub.d.ts

@@ -12,6 +12,7 @@ export interface DeviceResolver {
         total: number;
     }>;
     declaredMetrics?(deviceType: string): Promise<string[] | null>;
+    deviceType?(deviceToken: string): Promise<string | null>;
 }
 export interface WidgetStreamSink {
     next: (sample: MeasurementSample) => void;
@@ -98,6 +99,7 @@ export interface WidgetDataSource {
     subscribeMembers?(datasource: DatasourceSelector, sink: MemberSink): () => void;
     readMemberSeeds?(deviceTokens: readonly string[], plan: MemberSeedPlan, onSeed: (deviceToken: string, seed: MemberSeed | null, failure?: SeedFailure) => void, cancelled?: () => boolean): Promise<void>;
     declaredMetrics?(deviceType: string): Promise<readonly string[] | null>;
+    declaredMetricsForDevice?(deviceToken: string): Promise<readonly string[] | null>;
     subscribePresence?(datasource: DatasourceSelector, sink: PresenceSink): () => void;
 }
 export declare class DashboardHub implements WidgetDataSource, WidgetActions {
@@ -120,6 +122,7 @@ export declare class DashboardHub implements WidgetDataSource, WidgetActions {
     private resolveRoster;
     private readonly declared;
     declaredMetrics(deviceType: string): Promise<readonly string[] | null>;
+    declaredMetricsForDevice(deviceToken: string): Promise<readonly string[] | null>;
     private readonly seedLimiter;
     private readonly seedReads;
     readMemberSeeds(deviceTokens: readonly string[], plan: MemberSeedPlan, onSeed: (deviceToken: string, seed: MemberSeed | null, failure?: SeedFailure) => void, cancelled?: () => boolean): Promise<void>;

package/dist/index.d.ts

@@ -23,7 +23,7 @@ export type { MeasurementBucket } from './queries';
 export { ANCHOR_PAGE_SIZE } from './resolver';
 export type { MemberBucketCriteria, MemberBucketRead, MemberRef, MemberRoster, MemberSeed, MemberSeedPlan, MemberSink, PresenceSink, SeedFailure, } from './members';
 export { defaultHistoryWindow, fetchWidgetHistory, historyWindowFor, type HistoryWindow } from './history';
-export { DEFAULT_TIME_RANGE_SECONDS, MAX_SEED_BUCKETS, MAX_TIME_RANGE_SECONDS, MIN_TIME_RANGE_SECONDS, TIME_RANGE_PRESETS, bucketSecondsFor, initialTimeRange, isValidSpanSeconds, parsePausedParam, parseRangeParam, pauseRange, presetIdOf, rangeEnd, rangeWindow, resumeRange, seedBucketCount, setBoardTimeRange, spanLabel, timeRangeFromSearch, withSpan, type RangeWindow, type TimeRangePresetId, type TimeRangeState, } from './time-range';
+export { ABSOLUTE_FUTURE_SKEW_MS, DEFAULT_TIME_RANGE_SECONDS, EARLIEST_ABSOLUTE_MS, MAX_ABSOLUTE_SPAN_SECONDS, MIN_ABSOLUTE_SPAN_SECONDS, MAX_SEED_BUCKETS, MAX_TIME_RANGE_SECONDS, MIN_TIME_RANGE_SECONDS, TIME_RANGE_PRESETS, absoluteRange, absoluteRangeProblem, absoluteToParams, bucketSecondsFor, isAbsolute, leaveAbsolute, parseAbsoluteParams, parseInstantParam, initialTimeRange, isValidSpanSeconds, parsePausedParam, parseRangeParam, pauseRange, presetIdOf, rangeEnd, rangeWindow, resumeRange, seedBucketCount, setBoardTimeRange, spanLabel, timeRangeFromSearch, timeRangeLinkFromSearch, withSpan, type AbsoluteLinkRejection, type AbsoluteRange, type AbsoluteRangeProblem, type RangeWindow, type TimeRangeLink, type TimeRangePresetId, type TimeRangeState, } from './time-range';
 export type { AggregateResult, AggregateSpan, AggregateTrendPoint, AggregateStreamState, AlarmStreamState, AlarmTypeTab, AlarmTypeTabs, CommandStreamState, FleetMember, FleetState, MemberPresence, LocationStreamState, MeasurementAggregate, MeasurementStreamState, } from './channel-snapshots';
 export { applyOptionPatch, clampNumberOption, enumValues, numberSpec, validateOptions, HOST_OPTION_CONTROLS, type HostOptionControl, type BooleanOptionSpec, type DefaultsOf, type EnumOptionSpec, type ListItemFieldSpec, type ListOptionSpec, type GreaterThanConstraint, type NumberOptionSpec, type OptionConstraint, type OptionIssue, type OptionIssueCode, type OptionKeysOfKind, type OptionSpec, type OptionsOf, type RequiredOptionKeys, type SpecValue, type StringOptionSpec, type ValidateOptionsContext, type WidgetOptionSpecs, } from './option-schema';
 export { SDK_API_VERSION, defineWidgetDescriptor, isBuiltinWidgetId, isNamespacedWidgetId, type AckOptionRef, type BuiltinWidgetId, type ChannelBindingPolicy, type ChannelSnapshot, type ConstBinding, type DatasourcePolicy, type DatasourcePolicyFor, type DatasourceSelectorKind, type InteractionsFor, type NamespacedWidgetId, type NumberOptionRef, type StringOptionRef, type WidgetChannel, type WidgetDescriptor, type WidgetDisplay, type WidgetId, type WidgetInteractionDeclaration, FALLBACK_DEFAULT_SPAN, pinnedAxes, type WidgetLayoutSpec, type WidgetResizeMode, type WidgetSpan, } from './widget-descriptor';

package/dist/index.js

@@ -76,7 +76,8 @@ var WIDGET_TYPES = [
   "fleet-table",
   "fleet-count",
   "device-status",
-  "online-doughnut"
+  "online-doughnut",
+  "history-table"
 ];
 var PLACEMENT_ANCHORS = [
   "top-left",
@@ -536,7 +537,41 @@ var MAX_TIME_RANGE_SECONDS = 7 * 24 * 60 * 60;
 function isValidSpanSeconds(v) {
   return typeof v === "number" && Number.isInteger(v) && v >= MIN_TIME_RANGE_SECONDS && v <= MAX_TIME_RANGE_SECONDS;
 }
+var MIN_ABSOLUTE_SPAN_SECONDS = 60;
+var MAX_ABSOLUTE_SPAN_SECONDS = 31 * 24 * 60 * 60;
+var EARLIEST_ABSOLUTE_MS = Date.UTC(2e3, 0, 1);
+var ABSOLUTE_FUTURE_SKEW_MS = 60 * 1e3;
+function absoluteRangeProblem(fromMs, toMs, now) {
+  if (!Number.isFinite(fromMs) || !Number.isFinite(toMs)) return "unparseable";
+  if (fromMs >= toMs) return "order";
+  if (fromMs < EARLIEST_ABSOLUTE_MS) return "tooEarly";
+  if (toMs > now + ABSOLUTE_FUTURE_SKEW_MS) return "future";
+  const seconds = (Math.floor(toMs / 1e3) * 1e3 - Math.floor(fromMs / 1e3) * 1e3) / 1e3;
+  if (seconds < MIN_ABSOLUTE_SPAN_SECONDS) return "tooShort";
+  if (seconds > MAX_ABSOLUTE_SPAN_SECONDS) return "tooLong";
+  return void 0;
+}
+function isAbsolute(state) {
+  return state.absolute !== void 0;
+}
+function absoluteRange(fromMs, toMs, now = Date.now()) {
+  const problem = absoluteRangeProblem(fromMs, toMs, now);
+  if (problem) return { problem };
+  const from = Math.floor(fromMs / 1e3) * 1e3;
+  const to = Math.floor(toMs / 1e3) * 1e3;
+  return {
+    state: { spanSeconds: (to - from) / 1e3, paused: true, pausedAt: to, absolute: { fromMs: from, toMs: to } }
+  };
+}
+function leaveAbsolute(state) {
+  if (!state.absolute) return state;
+  return { spanSeconds: Math.min(state.spanSeconds, MAX_TIME_RANGE_SECONDS), paused: false };
+}
 function initialTimeRange(defaultSeconds, link = {}, now = Date.now()) {
+  if (link.absolute) {
+    const made = absoluteRange(link.absolute.fromMs, link.absolute.toMs, now);
+    if ("state" in made) return made.state;
+  }
   const spanSeconds = link.spanSeconds ?? (isValidSpanSeconds(defaultSeconds) ? defaultSeconds : DEFAULT_TIME_RANGE_SECONDS);
   return link.paused ? { spanSeconds, paused: true, pausedAt: now } : { spanSeconds, paused: false };
 }
@@ -544,9 +579,11 @@ function pauseRange(state, now) {
   return state.paused ? state : { spanSeconds: state.spanSeconds, paused: true, pausedAt: now };
 }
 function resumeRange(state) {
+  if (state.absolute) return leaveAbsolute(state);
   return state.paused ? { spanSeconds: state.spanSeconds, paused: false } : state;
 }
 function withSpan(state, spanSeconds) {
+  if (state.absolute) return state;
   return isValidSpanSeconds(spanSeconds) ? { ...state, spanSeconds } : state;
 }
 function rangeEnd(state, now) {
@@ -575,6 +612,26 @@ function parseRangeParam(value) {
 function parsePausedParam(value) {
   return value === "1";
 }
+var RFC3339_WITH_ZONE = /^\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}(:\d{2}(\.\d{1,9})?)?([Zz]|[+-]\d{2}:\d{2})$/;
+function parseInstantParam(value) {
+  if (!value || !RFC3339_WITH_ZONE.test(value)) return void 0;
+  const ms = Date.parse(value);
+  return Number.isNaN(ms) ? void 0 : ms;
+}
+function parseAbsoluteParams(from, to, now = Date.now()) {
+  if (from == null && to == null) return {};
+  const raw = { from: from ?? "", to: to ?? "" };
+  if (!from || !to) return { rejected: { reason: "incomplete", ...raw } };
+  const fromMs = parseInstantParam(from);
+  const toMs = parseInstantParam(to);
+  if (fromMs === void 0 || toMs === void 0) return { rejected: { reason: "unparseable", ...raw } };
+  const made = absoluteRange(fromMs, toMs, now);
+  if ("problem" in made) return { rejected: { reason: made.problem, ...raw } };
+  return { absolute: made.state.absolute };
+}
+function absoluteToParams(a) {
+  return { from: new Date(a.fromMs).toISOString(), to: new Date(a.toMs).toISOString() };
+}
 function timeRangeFromSearch(search) {
   let params;
   try {
@@ -588,6 +645,19 @@ function timeRangeFromSearch(search) {
   if (parsePausedParam(params.get("paused"))) link.paused = true;
   return link;
 }
+function timeRangeLinkFromSearch(search, now = Date.now()) {
+  let params;
+  try {
+    params = new URLSearchParams(search);
+  } catch {
+    return {};
+  }
+  const abs = parseAbsoluteParams(params.get("from"), params.get("to"), now);
+  if (abs.absolute) return { absolute: abs.absolute };
+  const link = timeRangeFromSearch(search);
+  if (abs.rejected) link.rejected = abs.rejected;
+  return link;
+}
 function presetIdOf(spanSeconds) {
   return TIME_RANGE_PRESETS.find((p) => p.seconds === spanSeconds)?.id;
 }
@@ -2309,6 +2379,16 @@ var DashboardHub = class {
     }
     return pending;
   }
+  async declaredMetricsForDevice(deviceToken) {
+    const typeOf = this.resolver.deviceType;
+    if (!typeOf) return null;
+    try {
+      const type = await typeOf.call(this.resolver, deviceToken);
+      return type ? await this.declaredMetrics(type) : null;
+    } catch {
+      return null;
+    }
+  }
   async readMemberSeeds(deviceTokens, plan, onSeed, cancelled = () => false) {
     await Promise.all(
       deviceTokens.map(async (token) => {
@@ -2971,6 +3051,7 @@ var DashboardHub = class {
 // src/synthetic.ts
 var SYNTHETIC_GENERATORS = ["sine", "ramp", "random-walk"];
 var DEFAULT_NAME = "value";
+var MAX_PREVIEW_BUCKETS = 500;
 var SYNTHETIC_DEVICE_TYPES = {
   "thermostat-01": { token: "thermostat", name: "Thermostat" },
   "sensor-14": { token: "sensor", name: "Sensor" },
@@ -3232,6 +3313,22 @@ var SyntheticDataSource = class {
     const names = datasource.measurements.length > 0 ? datasource.measurements : [DEFAULT_NAME];
     const from = Date.parse(window2.startTime);
     const to = Date.parse(window2.endTime);
+    const width = window2.intervalSeconds * 1e3;
+    if (width > 0 && width < to - from) {
+      const aligned = Math.floor(from / width) * width;
+      const total = Math.ceil((to - aligned) / width);
+      const count = Math.min(total, MAX_PREVIEW_BUCKETS);
+      const first = aligned + (total - count) * width;
+      return names.flatMap((name) => {
+        const walk = /* @__PURE__ */ new Map();
+        return Array.from({ length: count }, (_, i) => {
+          const start = first + i * width;
+          const values = Array.from({ length: 6 }, (_v, j) => this.valueFor(name, start + width * j / 6, walk));
+          const sum = values.reduce((a, v) => a + v, 0);
+          return { bucketStart: new Date(start).toISOString(), name, avg: sum / values.length, min: Math.min(...values), max: Math.max(...values), sum, count: values.length };
+        });
+      });
+    }
     return names.map((name) => {
       const walk = /* @__PURE__ */ new Map();
       const values = Array.from({ length: 120 }, (_, i) => this.valueFor(name, from + (to - from) * i / 119, walk));
@@ -4178,6 +4275,11 @@ var RecordedDataSource = class {
     const declared = this.rec.declaredMetrics;
     return declared && Object.prototype.hasOwnProperty.call(declared, kind) ? declared[kind] : null;
   }
+  // The same for one device, through its recorded kind.
+  async declaredMetricsForDevice(deviceToken) {
+    const kind = this.kinds.get(deviceToken);
+    return kind === void 0 ? null : this.declaredMetrics(kind);
+  }
   // Each device's seed comes from the recording itself, with no read to make: its newest reading per
   // measurement inside the history window, and every measurement it reported in that window, which
   // is how "does not report this" (a dozer's tyres) is told from "sent nothing".
@@ -5170,6 +5272,7 @@ function createDeviceResolver() {
   const anchorCache = /* @__PURE__ */ new Map();
   const memberCache = /* @__PURE__ */ new Map();
   const existsCache = /* @__PURE__ */ new Map();
+  const typeCache = /* @__PURE__ */ new Map();
   let declaredBatch = null;
   function anchorKey(anchor) {
     return `${anchor.relationship}|${anchor.targetType}|${anchor.targetToken}`;
@@ -5257,6 +5360,19 @@ function createDeviceResolver() {
         batch.set(deviceType, waiting);
       });
     },
+    // The device type's token, from the same names read the roster uses. A failed read rejects (the
+    // caller treats that as unknown) and is not cached.
+    deviceType(deviceToken) {
+      let pending = typeCache.get(deviceToken);
+      if (!pending) {
+        pending = gql3("device-management", DEVICE_NAMES, { tokens: [deviceToken] }).then((r) => r.devicesByToken.find((d) => d.token === deviceToken)?.deviceType?.token ?? null).catch((err) => {
+          typeCache.delete(deviceToken);
+          throw err;
+        });
+        typeCache.set(deviceToken, pending);
+      }
+      return pending;
+    },
     // deviceExists caches only a POSITIVE result (a live device is stable for the
     // session); a negative and an error both drop the entry so a later check re-queries.
     // ADR-042 frees a token on delete, so a deleted-then-recreated device must be able to
@@ -5318,7 +5434,8 @@ async function fetchWidgetHistory(widget, window2, options = {}) {
       occurredTime: b.bucketStart,
       name: b.name,
       value: b.avg,
-      classifier: null
+      classifier: null,
+      bucketSeconds: window2.intervalSeconds
     })).sort((a, b) => a.occurredTime < b.occurredTime ? -1 : 1);
   } catch (err) {
     if (options.rethrow) throw err;
@@ -5541,7 +5658,7 @@ var CHANNELS = ["measurement", "alarm", "control", "selection", "location", "agg
 var SEMVER2 = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
 var SELECTOR_KINDS = ["device", "anchor", "slot"];
 var BINDING_KEYS = {
-  measurement: ["window", "windowSeconds", "members", "presence"],
+  measurement: ["window", "windowSeconds", "members", "presence", "history"],
   alarm: ["pageSize", "state", "severity", "acknowledged", "groupBy", "countBySeverity", "deviceType"],
   control: ["pageSize"],
   location: [],
@@ -5877,9 +5994,11 @@ function checkBinding(binding, channel, specs, add) {
       }
     }
   };
-  const presence = binding.presence;
-  if (presence !== void 0 && !(isRecord(presence) && presence.const === true && Object.keys(presence).length === 1)) {
-    add("binding.presence", "must be { const: true }");
+  for (const key of ["presence", "history"]) {
+    const flag = binding[key];
+    if (flag !== void 0 && !(isRecord(flag) && flag.const === true && Object.keys(flag).length === 1)) {
+      add(`binding.${key}`, "must be { const: true }");
+    }
   }
   modeBinding("members");
   modeBinding("groupBy");
@@ -6061,6 +6180,7 @@ function effectiveLayout(def, containerWidth, options = {}) {
   return { ...shape, grid };
 }
 export {
+  ABSOLUTE_FUTURE_SKEW_MS,
   ANCHOR_PAGE_SIZE,
   BASE_BREAKPOINT,
   BIND_PARAM_PREFIX,
@@ -6075,6 +6195,7 @@ export {
   DENSITY_SCALE,
   DashboardDefinitionError,
   DashboardHub,
+  EARLIEST_ABSOLUTE_MS,
   FALLBACK_DEFAULT_SPAN,
   FRAME_BORDER_WIDTHS,
   FRAME_HEADERS,
@@ -6082,8 +6203,10 @@ export {
   FRAME_VARIANTS,
   HOST_OPTION_CONTROLS,
   LEGACY_REFERENCE_WIDTH,
+  MAX_ABSOLUTE_SPAN_SECONDS,
   MAX_SEED_BUCKETS,
   MAX_TIME_RANGE_SECONDS,
+  MIN_ABSOLUTE_SPAN_SECONDS,
   MIN_TIME_RANGE_SECONDS,
   NotInRecordingError,
   OFFLINE_AFTER_MS,
@@ -6114,6 +6237,9 @@ export {
   WIDGET_CLIPBOARD_VERSION,
   WIDGET_TYPES,
   WidgetCatalogError,
+  absoluteRange,
+  absoluteRangeProblem,
+  absoluteToParams,
   activeBreakpoint,
   addWidget,
   anchorFraction,
@@ -6171,6 +6297,7 @@ export {
   hasScopedSlots,
   historyWindowFor,
   initialTimeRange,
+  isAbsolute,
   isBuiltinWidget,
   isBuiltinWidgetId,
   isCancellableCommandStatus,
@@ -6184,16 +6311,19 @@ export {
   layoutBreakpoints,
   layoutRects,
   layoutShape,
+  leaveAbsolute,
   lintLayout,
   liveColumns,
   migrateToSlots,
   moveWidget,
   numberSpec,
   paddingPx,
+  parseAbsoluteParams,
   parseBindParams,
   parseBindingManifest,
   parseBoardRecording,
   parseDashboardDefinition,
+  parseInstantParam,
   parsePausedParam,
   parseRangeParam,
   parseSlotBinding,
@@ -6250,6 +6380,7 @@ export {
   storedDefinition,
   stripDefaultBindings,
   timeRangeFromSearch,
+  timeRangeLinkFromSearch,
   undoEdit,
   unresolvedWidgets,
   updateWidget,