@devicechain/widgets 0.21.1 → 0.22.0

package/README.md

@@ -6,8 +6,8 @@ SPDX-License-Identifier: Apache-2.0
 # @devicechain/widgets
 
 React dashboard widgets for DeviceChain, plus the renderer that lays a board out.
-Eleven widgets across five channels — charts, gauges, tables, alarm views, a
-command button, an entity selector and a map — all bound to live data through
+Twenty-four widgets — charts, gauges, tables, a fleet table, alarm views,
+command controls, an entity selector and a map — all bound to live data through
 [`@devicechain/dashboards`](https://www.npmjs.com/package/@devicechain/dashboards).
 
 Themed entirely with CSS custom properties. No Tailwind, no global styles, no
@@ -50,16 +50,23 @@ bound to a slot needs its datasource resolved first (`resolveWidgets` or
 
 | channel | widgets |
 | --- | --- |
-| measurement | `timeseries-chart`, `gauge`, `latest-card`, `table` |
+| measurement | `timeseries-chart`, `latest-card`, `gauge`, `linear-gauge`, `level-gauge`, `battery`, `status-light`, `signal-bars`, `compass`, `progress-ring`, `table`, `bar-chart`, `pie-chart`, `fleet-table` |
+| aggregate | `stat-card` |
 | none (static) | `label`, `image` |
 | alarm | `alarm-table`, `alarm-count` |
-| control | `command-button` |
+| control | `command-button`, `command-slider`, `command-toggle` |
 | selection | `entity-selector` |
 | location | `map` |
 
-Charts and gauges are [Apache ECharts](https://echarts.apache.org); the map is
-[MapLibre GL](https://maplibre.org), loaded lazily so a board with no map on it
-downloads none of it.
+`fleet-table`, and `bar-chart` in its one-bar-per-device mode, read a device
+group member by member. The other measurement widgets, and `stat-card`, show one
+device and refuse a group. `stat-card` shows one figure (average, minimum, maximum, sum, count or
+latest) over the board's time range.
+
+The time-series chart, the dial gauge and the compass are drawn with
+[Apache ECharts](https://echarts.apache.org); the other widgets are plain DOM
+and SVG. The map is [MapLibre GL](https://maplibre.org), loaded lazily so a board
+with no map on it downloads none of it.
 
 `WIDGET_OPTIONS` is the typed schema for every widget's options bag —
 `validateWidgetOptions` reports exactly where a stored bag disagrees with what the
@@ -158,6 +165,20 @@ widgets by setting variables on any ancestor. The DeviceChain values ship as
 [`@devicechain/brand`](https://www.npmjs.com/package/@devicechain/brand); nothing
 here requires them.
 
+## Upgrading from 0.21
+
+- `severityColor(severity)` is now `severityColor(colors, severity)`; the
+  colours come from `useSeverityColors()` in `@devicechain/widget-sdk`.
+- The `timeseries-chart` option `window` (a sample count) is replaced by
+  `windowSeconds` (a time span), and the chart's options version moves from 1 to
+  2. A stored board converts when it is parsed: the sample count is dropped and
+  the chart follows the board's time range.
+- Thirteen widgets are new, so `WidgetChannel` and the widget id unions gained
+  members; an exhaustive `switch` over them needs new cases.
+
+See [If you build against the npm packages](https://docs.devicechain.io/deployment/releases-and-upgrades#v0220-packages)
+in the release's upgrade guide.
+
 ## Compatibility
 
 React 19, ESM only, built for bundler resolution (Vite, webpack, Rollup, esbuild).

package/dist/aggregate-feed.d.ts

@@ -0,0 +1,14 @@
+import { type WidgetActions, type WidgetDataSource, type WidgetDescriptor, type WidgetInstance } from '@devicechain/dashboards';
+import { type ComponentType } from 'react';
+export interface AggregateFeedProps {
+    hub: WidgetDataSource;
+    widget: WidgetInstance;
+    descriptor: WidgetDescriptor;
+    Component: ComponentType<any>;
+    actions: WidgetActions | undefined;
+    ErrorFrame: ComponentType<{
+        widget: WidgetInstance;
+        error: unknown;
+    }>;
+}
+export default function AggregateFeed({ hub, widget, descriptor, Component, actions, ErrorFrame }: AggregateFeedProps): import("react").JSX.Element;

package/dist/aggregate-fold.d.ts

@@ -0,0 +1,11 @@
+import { type HistoryWindow, type MeasurementAggregate, type MeasurementBucket } from '@devicechain/dashboards';
+export declare class AggregateFieldsError extends Error {
+    constructor(message: string);
+}
+export declare function aggregateBuckets(buckets: readonly MeasurementBucket[]): Record<string, MeasurementAggregate>;
+export declare function aggregateRefreshMs(spanSeconds: number): number;
+export interface AggregateWindow {
+    window: HistoryWindow;
+    spanSeconds: number;
+}
+export declare function aggregateWindow(spanSeconds: number, at: number): AggregateWindow;

package/dist/aggregate-reading.d.ts

@@ -0,0 +1,19 @@
+import type { AggregateStreamState, WidgetInstance } from '@devicechain/dashboards';
+import { type AggregateStat } from './aggregate-strings';
+export type EmptyReason = 'loading' | 'unsupported' | 'failed' | 'noReadings' | 'noData' | 'unbound';
+export type StatReading = {
+    kind: 'value';
+    stat: AggregateStat;
+    name: string | undefined;
+    value: number;
+    spanSeconds: number | undefined;
+    time?: string | null;
+} | {
+    kind: 'empty';
+    reason: EmptyReason;
+    name: string | undefined;
+    message?: string;
+    spanSeconds?: number;
+};
+export declare function parseStat(v: unknown): AggregateStat;
+export declare function statReading(widget: WidgetInstance, data: AggregateStreamState, stat: AggregateStat): StatReading;

package/dist/aggregate-strings.d.ts

@@ -0,0 +1,16 @@
+export declare const AGGREGATE_STATS: readonly ['avg', 'min', 'max', 'sum', 'count', 'last'];
+export type AggregateStat = (typeof AGGREGATE_STATS)[number];
+export interface AggregateStrings {
+    stats: Record<AggregateStat, string>;
+    loading: string;
+    unsupported: string;
+    failed: (message: string | undefined) => string;
+    noReadings: (span: string) => string;
+    noData: string;
+    unbound: string;
+    noCategories: string;
+    pieNegative: string;
+    pieNoShare: string;
+}
+export declare const AGGREGATE_STRINGS: Record<'en' | 'es', AggregateStrings>;
+export declare function aggregateStrings(locale?: string | undefined): AggregateStrings;

package/dist/binding-policy.d.ts

@@ -1,4 +1,6 @@
-import type { AlarmSubscription, CommandSubscription, WidgetDescriptor, WidgetInstance } from '@devicechain/dashboards';
+import { type AlarmSubscription, type CommandSubscription, type WidgetDescriptor, type WidgetInstance } from '@devicechain/dashboards';
 export declare function measurementWindow(descriptor: WidgetDescriptor, widget: WidgetInstance): number | undefined;
+export declare function measurementSpan(descriptor: WidgetDescriptor, widget: WidgetInstance, boardSpan: number | undefined): number | undefined;
+export declare function membersMode(descriptor: WidgetDescriptor, widget: WidgetInstance): boolean;
 export declare function alarmSubscription(descriptor: WidgetDescriptor, widget: WidgetInstance): AlarmSubscription;
 export declare function commandSubscription(descriptor: WidgetDescriptor, widget: WidgetInstance): CommandSubscription;