@devicechain/widget-sdk 0.0.0-stage → 0.20.0-rc.4

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright The DeviceChain Authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,84 @@
-# Temporary Holding Version
+<!--
+Copyright The DeviceChain Authors
+SPDX-License-Identifier: Apache-2.0
+-->
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @devicechain/widget-sdk
+
+The typed contract for writing a DeviceChain dashboard widget as a React component, and the
+sealed registry that makes it available to a host application. The built-in widgets are
+declared through exactly this interface.
+
+```bash
+npm install @devicechain/widget-sdk @devicechain/dashboards react
+```
+
+`@devicechain/dashboards` and `react` are **peer dependencies**: the SDK defines the React
+contexts a widget reads (selection, candidate lookup, time zone, theme root), and a context is
+identified by the object that created it, so every widget package and the host must resolve
+the same single copy of this package. Declare it as a peer in your own widget package too,
+never as a dependency.
+
+## What is in the box
+
+The root entry is chart-free and map-free: the card frame (`WidgetFrame`), theme-variable
+references (`css`), formatters, the change-flash cue, option readers (`optString`,
+`optNumber`, ...) and the React hooks that bind a hub channel to widget state. A widget
+that only draws DOM imports from here and pulls in neither Apache ECharts nor MapLibre nor
+the built-in widgets.
+
+Chart helpers live on a separate entry, `@devicechain/widget-sdk/echarts`: the `EChart`
+wrapper, `buildLineOption` / `buildGaugeOption` and the chart colour theme. `echarts` is an
+**optional peer dependency**, needed only by a widget that imports that entry.
+
+## Declare a widget
+
+```tsx
+import { defineWidget } from '@devicechain/widget-sdk';
+
+export const tankLevelWidget = defineWidget({
+  descriptor: {
+    id: 'acme/tank-level',
+    version: '1.0.0',
+    sdkApiVersion: 1,
+    optionsVersion: 1,
+    display: { title: 'Tank level', category: 'Telemetry' },
+    channel: 'measurement',
+    datasource: { mode: 'required', selectors: ['device', 'slot'] },
+    binding: { window: { option: 'window', min: 1 } },
+    options: {
+      unit: { kind: 'string', doc: 'Unit shown beside the level.' },
+      window: { kind: 'number', integer: true, min: 1, doc: 'Samples retained.' },
+    },
+    defaults: { unit: '%' },
+    interactions: {},
+  },
+  implementation: {
+    kind: 'trusted-react',
+    // `data` is typed from the channel: a measurement widget receives measurement data.
+    component: ({ data }) => <span>{Object.values(data.latest)[0]?.value}</span>,
+  },
+});
+```
+
+The descriptor is plain JSON-serializable data: no component, callback or URL. A descriptor
+that disagrees with its channel, or whose defaults or bindings disagree with its option
+schema, fails type checking, and `createWidgetRegistry` checks the same rules again at
+runtime.
+
+## Register it
+
+```ts
+import { createWidgetRegistry } from '@devicechain/widget-sdk';
+
+const registry = createWidgetRegistry([tankLevelWidget]);
+```
+
+A registry is validated and sealed when it is created: duplicate ids, malformed descriptors,
+an unsupported `sdkApiVersion` and invalid bindings or defaults are all reported together in
+one `WidgetRegistryError`. There is no global registration; two registries on one page are
+independent. Extension ids are namespaced (`scope/name`); the un-namespaced ids are reserved
+for the built-in widgets.
+
+Trusted widget code runs with the host page's privileges. The declarations in a descriptor
+shape the API; they are not a security boundary.

package/dist/chart/chart-options.d.ts

@@ -0,0 +1,14 @@
+import type { MeasurementSample } from '@devicechain/dashboards';
+import type { ElementSize } from '../hooks';
+import type { ChartTheme } from './chart-theme';
+import type { EChartOption } from './echart';
+export interface LineChartOptions {
+    measurements?: string[];
+}
+export declare function buildLineOption(samples: MeasurementSample[], theme: ChartTheme, options?: LineChartOptions, size?: ElementSize): EChartOption;
+export interface GaugeChartOptions {
+    min?: number;
+    max?: number;
+    unit?: string;
+}
+export declare function buildGaugeOption(value: number | null, theme: ChartTheme, options?: GaugeChartOptions, size?: ElementSize): EChartOption;

package/dist/chart/chart-theme.d.ts

@@ -0,0 +1,8 @@
+export interface ChartTheme {
+    foreground: string;
+    mutedForeground: string;
+    border: string;
+    series: string[];
+}
+export declare function resolveChartTheme(el: Element): ChartTheme;
+export declare function useChartTheme(): ChartTheme;

package/dist/chart/echart.d.ts

@@ -0,0 +1,8 @@
+import * as echarts from 'echarts/core';
+export type EChartOption = echarts.EChartsCoreOption;
+export interface EChartProps {
+    option: EChartOption;
+    className?: string;
+    style?: React.CSSProperties;
+}
+export declare function EChart({ option, className, style }: EChartProps): import("react").JSX.Element;

package/dist/chunks/chunk-CC2V7LVI.js

@@ -0,0 +1,67 @@
+// src/context.tsx
+import { createContext, useContext } from "react";
+import { jsx } from "react/jsx-runtime";
+var WidgetSubjectContext = createContext(void 0);
+function useWidgetSubject() {
+  return useContext(WidgetSubjectContext);
+}
+function WidgetSubjectProvider({
+  label,
+  children
+}) {
+  return /* @__PURE__ */ jsx(WidgetSubjectContext.Provider, { value: label, children });
+}
+var WidgetTimeZoneContext = createContext(void 0);
+function WidgetTimeZoneProvider({
+  timeZone,
+  children
+}) {
+  return /* @__PURE__ */ jsx(WidgetTimeZoneContext.Provider, { value: timeZone, children });
+}
+function useWidgetTimeZone() {
+  return useContext(WidgetTimeZoneContext);
+}
+var WidgetThemeRootContext = createContext(void 0);
+function WidgetThemeRootProvider({
+  root,
+  children
+}) {
+  return /* @__PURE__ */ jsx(WidgetThemeRootContext.Provider, { value: root, children });
+}
+function useWidgetThemeRoot() {
+  return useContext(WidgetThemeRootContext);
+}
+var WidgetSelectContext = createContext(void 0);
+function WidgetSelectProvider({
+  select,
+  children
+}) {
+  return /* @__PURE__ */ jsx(WidgetSelectContext.Provider, { value: select, children });
+}
+function useWidgetSelect() {
+  return useContext(WidgetSelectContext);
+}
+var WidgetCandidatesContext = createContext(void 0);
+function WidgetCandidatesProvider({
+  candidates,
+  children
+}) {
+  return /* @__PURE__ */ jsx(WidgetCandidatesContext.Provider, { value: candidates, children });
+}
+function useWidgetCandidates() {
+  return useContext(WidgetCandidatesContext);
+}
+
+export {
+  useWidgetSubject,
+  WidgetSubjectProvider,
+  WidgetTimeZoneProvider,
+  useWidgetTimeZone,
+  WidgetThemeRootProvider,
+  useWidgetThemeRoot,
+  WidgetSelectProvider,
+  useWidgetSelect,
+  WidgetCandidatesProvider,
+  useWidgetCandidates
+};
+//# sourceMappingURL=chunk-CC2V7LVI.js.map

package/dist/chunks/chunk-CC2V7LVI.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/context.tsx"],
+  "sourcesContent": ["// Copyright The DeviceChain Authors\n// SPDX-License-Identifier: Apache-2.0\n\n// The ambient host context a widget reads: the resolved subject, the display time zone, the\n// theme root, the selection callback and the candidate provider.\n//\n// \uD83D\uDD34 THESE CONTEXTS ARE DEFINED HERE AND NOWHERE ELSE. A React context is identified by the\n// OBJECT createContext returned, so two copies of this module \u2014 one bundled into a widget\n// package, one in the host \u2014 are two unrelated contexts: the host's provider writes to one\n// and the widget reads the other, and the selector silently does nothing. Exactly one\n// definition, in this package, which `@devicechain/widgets` and every third-party widget\n// package depend on as a PEER (never a dependency) so the host's install supplies the\n// single copy.\n\nimport { createContext, useContext, type ReactNode } from 'react';\n\nimport type { SelectionCandidate, SelectionTarget } from '@devicechain/dashboards';\n\n// WidgetSubjectContext carries the resolved entity a widget shows (its datasource's\n// bound device/anchor), computed once by the renderer and provided per widget. The\n// frame reads it as a subtitle so every board answers \"which asset is this?\" \u2014 and,\n// because it reads the RESOLVED binding, it updates for free once selection re-points a\n// slot (ADR-039 selection-overlay amendment). Kept as ambient context, not a widget\n// prop, so the pure widget contract (widget, data) stays untouched and no widget needs\n// to know how a subject is resolved.\nconst WidgetSubjectContext = createContext<string | undefined>(undefined);\n\n// useWidgetSubject reads the resolved subject line (the frame's fallback subtitle).\nexport function useWidgetSubject(): string | undefined {\n  return useContext(WidgetSubjectContext);\n}\n\nexport function WidgetSubjectProvider({\n  label,\n  children,\n}: {\n  label: string | undefined;\n  children: ReactNode;\n}) {\n  return <WidgetSubjectContext.Provider value={label}>{children}</WidgetSubjectContext.Provider>;\n}\n\n// WidgetTimeZone is the zone widgets print instants in. Undefined (the default) means the\n// viewer's own zone, which is what every live host wants; a host replaying a recording\n// pins one so the board's times agree with the recording's own clock.\nconst WidgetTimeZoneContext = createContext<string | undefined>(undefined);\n\nexport function WidgetTimeZoneProvider({\n  timeZone,\n  children,\n}: {\n  timeZone: string | undefined;\n  children: ReactNode;\n}) {\n  return <WidgetTimeZoneContext.Provider value={timeZone}>{children}</WidgetTimeZoneContext.Provider>;\n}\n\nexport function useWidgetTimeZone(): string | undefined {\n  return useContext(WidgetTimeZoneContext);\n}\n\n// WidgetThemeRoot is the element chart colors are read from. Undefined (the default) means\n// the document root, which is where a console or dashboard app sets its tokens. A host that\n// scopes its tokens to a container (an embed on a page whose own stylesheet owns the root)\n// provides that container, and charts resolve their colors there instead.\nconst WidgetThemeRootContext = createContext<Element | undefined>(undefined);\n\nexport function WidgetThemeRootProvider({\n  root,\n  children,\n}: {\n  root: Element | undefined;\n  children: ReactNode;\n}) {\n  return <WidgetThemeRootContext.Provider value={root}>{children}</WidgetThemeRootContext.Provider>;\n}\n\nexport function useWidgetThemeRoot(): Element | undefined {\n  return useContext(WidgetThemeRootContext);\n}\n\n// WidgetSelect is a view-interaction callback (ADR-039 selection amendment): a widget\n// drives a slot selection (an alarm-table originator drill, a context-selector pick) by\n// naming its target slot + the entity to bind. Kept DISTINCT from WidgetActions (the\n// write seam) \u2014 selection changes only the view's binding overlay, never the backend.\n// Provided by the renderer from the host; absent (undefined) in edit mode and any host\n// that wires no selection, so a widget feature-detects it before offering a drill.\nexport type WidgetSelect = (target: SelectionTarget) => void;\n\nconst WidgetSelectContext = createContext<WidgetSelect | undefined>(undefined);\n\nexport function WidgetSelectProvider({\n  select,\n  children,\n}: {\n  select: WidgetSelect | undefined;\n  children: ReactNode;\n}) {\n  return <WidgetSelectContext.Provider value={select}>{children}</WidgetSelectContext.Provider>;\n}\n\n// useWidgetSelect returns the ambient selection callback, or undefined where selection is\n// not wired (edit mode, a read-only embedder). A widget renders its drill affordance only\n// when this is defined.\nexport function useWidgetSelect(): WidgetSelect | undefined {\n  return useContext(WidgetSelectContext);\n}\n\n// WidgetCandidates is the ambient companion to WidgetSelect (ADR-039 selection amendment): a\n// context/entity-selector widget asks it for the options a target slot may bind to. The host\n// computes candidates from the definition's scope + resolved bindings (useSlotCandidates), so\n// the widget stays presentational and the pure widget contract stays untouched. Distinct from\n// the hub's data channels \u2014 candidates are a fetch-on-open list, not a live stream. Undefined\n// where not wired (edit/preview, a host that supplies no selection) \u2192 the selector is inert.\nexport type WidgetCandidates = (slot: string) => Promise<SelectionCandidate[]>;\n\nconst WidgetCandidatesContext = createContext<WidgetCandidates | undefined>(undefined);\n\nexport function WidgetCandidatesProvider({\n  candidates,\n  children,\n}: {\n  candidates: WidgetCandidates | undefined;\n  children: ReactNode;\n}) {\n  return <WidgetCandidatesContext.Provider value={candidates}>{children}</WidgetCandidatesContext.Provider>;\n}\n\n// useWidgetCandidates returns the ambient candidate provider, or undefined where selection is\n// not wired. A selector widget renders its picker only when both this and useWidgetSelect are\n// defined.\nexport function useWidgetCandidates(): WidgetCandidates | undefined {\n  return useContext(WidgetCandidatesContext);\n}\n"],
+  "mappings": ";AAcA,SAAS,eAAe,kBAAkC;AAyBjD;AAdT,IAAM,uBAAuB,cAAkC,MAAS;AAGjE,SAAS,mBAAuC;AACrD,SAAO,WAAW,oBAAoB;AACxC;AAEO,SAAS,sBAAsB;AAAA,EACpC;AAAA,EACA;AACF,GAGG;AACD,SAAO,oBAAC,qBAAqB,UAArB,EAA8B,OAAO,OAAQ,UAAS;AAChE;AAKA,IAAM,wBAAwB,cAAkC,MAAS;AAElE,SAAS,uBAAuB;AAAA,EACrC;AAAA,EACA;AACF,GAGG;AACD,SAAO,oBAAC,sBAAsB,UAAtB,EAA+B,OAAO,UAAW,UAAS;AACpE;AAEO,SAAS,oBAAwC;AACtD,SAAO,WAAW,qBAAqB;AACzC;AAMA,IAAM,yBAAyB,cAAmC,MAAS;AAEpE,SAAS,wBAAwB;AAAA,EACtC;AAAA,EACA;AACF,GAGG;AACD,SAAO,oBAAC,uBAAuB,UAAvB,EAAgC,OAAO,MAAO,UAAS;AACjE;AAEO,SAAS,qBAA0C;AACxD,SAAO,WAAW,sBAAsB;AAC1C;AAUA,IAAM,sBAAsB,cAAwC,MAAS;AAEtE,SAAS,qBAAqB;AAAA,EACnC;AAAA,EACA;AACF,GAGG;AACD,SAAO,oBAAC,oBAAoB,UAApB,EAA6B,OAAO,QAAS,UAAS;AAChE;AAKO,SAAS,kBAA4C;AAC1D,SAAO,WAAW,mBAAmB;AACvC;AAUA,IAAM,0BAA0B,cAA4C,MAAS;AAE9E,SAAS,yBAAyB;AAAA,EACvC;AAAA,EACA;AACF,GAGG;AACD,SAAO,oBAAC,wBAAwB,UAAxB,EAAiC,OAAO,YAAa,UAAS;AACxE;AAKO,SAAS,sBAAoD;AAClE,SAAO,WAAW,uBAAuB;AAC3C;",
+  "names": []
+}

package/dist/context.d.ts

@@ -0,0 +1,29 @@
+import { type ReactNode } from 'react';
+import type { SelectionCandidate, SelectionTarget } from '@devicechain/dashboards';
+export declare function useWidgetSubject(): string | undefined;
+export declare function WidgetSubjectProvider({ label, children, }: {
+    label: string | undefined;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function WidgetTimeZoneProvider({ timeZone, children, }: {
+    timeZone: string | undefined;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function useWidgetTimeZone(): string | undefined;
+export declare function WidgetThemeRootProvider({ root, children, }: {
+    root: Element | undefined;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function useWidgetThemeRoot(): Element | undefined;
+export type WidgetSelect = (target: SelectionTarget) => void;
+export declare function WidgetSelectProvider({ select, children, }: {
+    select: WidgetSelect | undefined;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function useWidgetSelect(): WidgetSelect | undefined;
+export type WidgetCandidates = (slot: string) => Promise<SelectionCandidate[]>;
+export declare function WidgetCandidatesProvider({ candidates, children, }: {
+    candidates: WidgetCandidates | undefined;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function useWidgetCandidates(): WidgetCandidates | undefined;

package/dist/define-widget.d.ts

@@ -0,0 +1,22 @@
+import type { ChannelSnapshot, OptionsOf, WidgetChannel, WidgetDescriptor, WidgetOptionSpecs } from '@devicechain/dashboards';
+import type { ComponentType } from 'react';
+import type { WidgetEditorProps, WidgetProps } from './widget';
+export interface WidgetImplementation<C extends WidgetChannel, S extends WidgetOptionSpecs> {
+    kind: 'trusted-react';
+    component: ComponentType<WidgetProps<ChannelSnapshot<C>>>;
+    editor?: ComponentType<WidgetEditorProps<OptionsOf<S>>>;
+}
+export interface WidgetDefinition<C extends WidgetChannel = WidgetChannel, S extends WidgetOptionSpecs = WidgetOptionSpecs> {
+    descriptor: WidgetDescriptor<C, S>;
+    implementation: WidgetImplementation<C, S>;
+}
+export type ErasedComponent = ComponentType<any>;
+export interface ErasedWidgetDefinition {
+    descriptor: WidgetDescriptor;
+    implementation: {
+        kind: 'trusted-react';
+        component: ErasedComponent;
+        editor?: ErasedComponent;
+    };
+}
+export declare function defineWidget<const C extends WidgetChannel, const S extends WidgetOptionSpecs>(definition: WidgetDefinition<C, S>): WidgetDefinition<C, S>;

package/dist/echarts.d.ts

@@ -0,0 +1,3 @@
+export { EChart, type EChartOption, type EChartProps } from './chart/echart';
+export { buildGaugeOption, buildLineOption, type GaugeChartOptions, type LineChartOptions, } from './chart/chart-options';
+export { resolveChartTheme, useChartTheme, type ChartTheme } from './chart/chart-theme';

package/dist/echarts.js

@@ -0,0 +1,193 @@
+import {
+  useWidgetThemeRoot
+} from "./chunks/chunk-CC2V7LVI.js";
+
+// src/chart/echart.tsx
+import { GaugeChart, LineChart } from "echarts/charts";
+import { GridComponent, TooltipComponent } from "echarts/components";
+import * as echarts from "echarts/core";
+import { CanvasRenderer } from "echarts/renderers";
+import { useEffect, useRef } from "react";
+import { jsx } from "react/jsx-runtime";
+echarts.use([LineChart, GaugeChart, GridComponent, TooltipComponent, CanvasRenderer]);
+function EChart({ option, className, style }) {
+  const containerRef = useRef(null);
+  const chartRef = useRef(null);
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    const chart = echarts.init(el);
+    chartRef.current = chart;
+    const observer = new ResizeObserver(() => chart.resize());
+    observer.observe(el);
+    return () => {
+      observer.disconnect();
+      chart.dispose();
+      chartRef.current = null;
+    };
+  }, []);
+  useEffect(() => {
+    chartRef.current?.setOption(option, { notMerge: true });
+  }, [option]);
+  return /* @__PURE__ */ jsx("div", { ref: containerRef, className, style: { width: "100%", height: "100%", ...style } });
+}
+
+// src/chart/chart-options.ts
+function distinctNames(samples) {
+  const seen = [];
+  for (const s of samples) {
+    if (!seen.includes(s.name)) seen.push(s.name);
+  }
+  return seen;
+}
+var clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
+function shortSide(size) {
+  const s = Math.min(size?.width ?? 0, size?.height ?? 0);
+  return s > 0 ? s : 200;
+}
+function buildLineOption(samples, theme, options = {}, size) {
+  const names = options.measurements?.length ? options.measurements : distinctNames(samples);
+  const axisFont = clamp(Math.round(shortSide(size) / 22), 8, 12);
+  const series = names.map((name, i) => {
+    const color = theme.series[i % theme.series.length];
+    return {
+      name,
+      type: "line",
+      showSymbol: false,
+      lineStyle: { color },
+      itemStyle: { color },
+      data: samples.filter((s) => s.name === name && s.value != null && s.occurredTime != null).map((s) => [s.occurredTime, s.value])
+    };
+  });
+  return {
+    animation: false,
+    textStyle: { color: theme.foreground, fontSize: axisFont },
+    grid: { left: 8, right: 12, top: names.length > 1 ? 28 : 12, bottom: 8, containLabel: true },
+    tooltip: { trigger: "axis" },
+    legend: names.length > 1 ? { textStyle: { color: theme.mutedForeground, fontSize: axisFont }, top: 0 } : void 0,
+    xAxis: {
+      type: "time",
+      axisLine: { lineStyle: { color: theme.border } },
+      axisLabel: { color: theme.mutedForeground, fontSize: axisFont, hideOverlap: true }
+    },
+    yAxis: {
+      type: "value",
+      splitLine: { lineStyle: { color: theme.border } },
+      axisLabel: { color: theme.mutedForeground, fontSize: axisFont }
+    },
+    series
+  };
+}
+function buildGaugeOption(value, theme, options = {}, size) {
+  const min = options.min ?? 0;
+  const max = options.max ?? 100;
+  const accent = theme.series[0];
+  const unitSuffix = options.unit ? ` ${options.unit}` : "";
+  const s = shortSide(size);
+  const arcWidth = clamp(Math.round(s / 26), 4, 12);
+  const labelFont = clamp(Math.round(s / 20), 8, 13);
+  const valueFont = clamp(Math.round(s / 7), 14, 40);
+  return {
+    animation: false,
+    series: [
+      {
+        type: "gauge",
+        min,
+        max,
+        splitNumber: s < 160 ? 4 : 5,
+        // fewer ticks than the default 10 → no cram
+        radius: "95%",
+        center: ["50%", "58%"],
+        progress: { show: true, width: arcWidth, itemStyle: { color: accent } },
+        pointer: { itemStyle: { color: accent }, length: "55%", width: clamp(Math.round(s / 50), 2, 6) },
+        anchor: { show: false },
+        axisLine: { lineStyle: { width: arcWidth, color: [[1, theme.border]] } },
+        axisTick: { show: false },
+        splitLine: { length: arcWidth, lineStyle: { color: theme.border, width: 1 } },
+        axisLabel: { color: theme.mutedForeground, fontSize: labelFont, distance: arcWidth + 2 },
+        detail: {
+          valueAnimation: false,
+          color: theme.foreground,
+          fontSize: valueFont,
+          offsetCenter: [0, "30%"],
+          formatter: (v) => value == null ? "\u2014" : `${v}${unitSuffix}`
+        },
+        data: [{ value: value ?? min }]
+      }
+    ]
+  };
+}
+
+// src/chart/chart-theme.ts
+import { useMemo, useSyncExternalStore } from "react";
+var FALLBACK = {
+  foreground: "hsl(240 10% 3.9%)",
+  mutedForeground: "hsl(240 3.8% 46.1%)",
+  border: "hsl(240 5.9% 90%)",
+  series: [
+    "hsl(220 70% 50%)",
+    "hsl(160 60% 45%)",
+    "hsl(30 80% 55%)",
+    "hsl(280 65% 60%)",
+    "hsl(340 75% 55%)"
+  ]
+};
+function readVar(style, name, fallback) {
+  const raw = style.getPropertyValue(`--${name}`).trim();
+  return raw ? `hsl(${raw})` : fallback;
+}
+function resolveChartTheme(el) {
+  const style = getComputedStyle(el);
+  return {
+    foreground: readVar(style, "foreground", FALLBACK.foreground),
+    mutedForeground: readVar(style, "muted-foreground", FALLBACK.mutedForeground),
+    border: readVar(style, "border", FALLBACK.border),
+    series: FALLBACK.series.map((fallback, i) => readVar(style, `chart-${i + 1}`, fallback))
+  };
+}
+var sharedTheme = null;
+var themeListeners = /* @__PURE__ */ new Set();
+var themeObserver = null;
+function recomputeTheme() {
+  sharedTheme = resolveChartTheme(document.documentElement);
+}
+function subscribeTheme(listener) {
+  if (!themeObserver) {
+    recomputeTheme();
+    themeObserver = new MutationObserver(() => {
+      recomputeTheme();
+      for (const l of themeListeners) l();
+    });
+    themeObserver.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ["class", "style"]
+    });
+  }
+  themeListeners.add(listener);
+  return () => {
+    themeListeners.delete(listener);
+    if (themeListeners.size === 0 && themeObserver) {
+      themeObserver.disconnect();
+      themeObserver = null;
+      sharedTheme = null;
+    }
+  };
+}
+function getThemeSnapshot() {
+  if (!sharedTheme) recomputeTheme();
+  return sharedTheme;
+}
+function useChartTheme() {
+  const shared = useSyncExternalStore(subscribeTheme, getThemeSnapshot, getThemeSnapshot);
+  const root = useWidgetThemeRoot();
+  const scoped = useMemo(() => root ? resolveChartTheme(root) : null, [root]);
+  return scoped ?? shared;
+}
+export {
+  EChart,
+  buildGaugeOption,
+  buildLineOption,
+  resolveChartTheme,
+  useChartTheme
+};
+//# sourceMappingURL=echarts.js.map