@glasshome/widget-sdk 1.27.1 → 1.29.0

package/README.md

@@ -38,6 +38,8 @@ export default defineWidget({
 });
 ```
 
+Small values a widget keeps across reloads (recent picks, the last tab) go through `useWidgetState(key, schema, fallback)`, kept by the host for this widget and this person. `localStorage` is in memory and empty after a reload.
+
 ### `@glasshome/widget-sdk/vite` — Vite Plugin
 
 Vite plugin for widget development. Handles widget bundling, preview server, and registry generation.

package/dist/export-history.json

@@ -5710,5 +5710,295 @@
     "useWidgetViewer",
     "widgetFields",
     "z"
+  ],
+  "1.28.0": [
+    "Badge",
+    "Button",
+    "ButtonGroup",
+    "Carousel",
+    "CarouselContent",
+    "CarouselDots",
+    "CarouselItem",
+    "CarouselNext",
+    "CarouselPrevious",
+    "ColorDisc",
+    "ColorSlider",
+    "ColorWheel",
+    "CountPill",
+    "Icon",
+    "Input",
+    "Label",
+    "PanelEntityRow",
+    "PanelFacts",
+    "PanelRow",
+    "PanelRows",
+    "PanelSection",
+    "Progress",
+    "ResponsiveDialog",
+    "ResponsiveDialogBody",
+    "ResponsiveDialogClose",
+    "ResponsiveDialogContent",
+    "ResponsiveDialogDescription",
+    "ResponsiveDialogFooter",
+    "ResponsiveDialogHeader",
+    "ResponsiveDialogTitle",
+    "SDK_VERSION",
+    "SchemaForm",
+    "SectionIcon",
+    "SectionTitle",
+    "Select",
+    "SelectContent",
+    "SelectItem",
+    "SelectTrigger",
+    "SelectValue",
+    "Slider",
+    "SwatchPicker",
+    "Switch",
+    "Tabs",
+    "TabsContent",
+    "TabsList",
+    "TabsTrigger",
+    "TemperatureBar",
+    "Toggle",
+    "ToggleGroup",
+    "ToggleGroupItem",
+    "ToneSchema",
+    "Widget",
+    "WidgetAction",
+    "WidgetBackdrop",
+    "WidgetChip",
+    "WidgetChoice",
+    "WidgetContent",
+    "WidgetControls",
+    "WidgetCtx",
+    "WidgetDebugTab",
+    "WidgetDebugView",
+    "WidgetDialog",
+    "WidgetGlyph",
+    "WidgetHead",
+    "WidgetHero",
+    "WidgetIcon",
+    "WidgetLayer",
+    "WidgetManifestSchema",
+    "WidgetSizeCtx",
+    "WidgetSliderFill",
+    "WidgetStatus",
+    "WidgetStepper",
+    "WidgetTitle",
+    "WidgetValue",
+    "buildDebugData",
+    "byDomain",
+    "calculateLightGroup",
+    "calculateSensorGroup",
+    "copyText",
+    "countActiveEntities",
+    "defineConfig",
+    "defineWidget",
+    "deprecations",
+    "field",
+    "formatDeprecation",
+    "formatSchemaError",
+    "getEntityAttribute",
+    "getForecasts",
+    "getStream",
+    "getWebRtcClientConfig",
+    "hassMediaUrl",
+    "imagePreset",
+    "imageSrc",
+    "imageUrl",
+    "injectTokens",
+    "isDark",
+    "isEntityActive",
+    "isPanelControllable",
+    "mediaUrl",
+    "monotoneCubicPath",
+    "parseColor",
+    "presetValue",
+    "sendWebRtcCandidate",
+    "startWebRtcSession",
+    "state",
+    "svgColors",
+    "trackEntityHistory",
+    "untrackEntityHistory",
+    "useArea",
+    "useCalendarEvents",
+    "useCamera",
+    "useConfirm",
+    "useConnection",
+    "useCopyText",
+    "useCurrency",
+    "useDaylight",
+    "useEntities",
+    "useEntity",
+    "useEntityHistory",
+    "useEntityStatistics",
+    "useForecast",
+    "useHassConfig",
+    "useIntersectionPause",
+    "useLocale",
+    "useMaterial",
+    "useReducedMotion",
+    "useService",
+    "useStore",
+    "useTemperatureUnit",
+    "useToggle",
+    "useTurnOff",
+    "useTurnOn",
+    "useUnitSystem",
+    "useWidgetContext",
+    "useWidgetDashboard",
+    "useWidgetDialog",
+    "useWidgetDimensions",
+    "useWidgetEntityGroup",
+    "useWidgetGestures",
+    "useWidgetState",
+    "useWidgetViewer",
+    "widgetFields",
+    "z"
+  ],
+  "1.29.0": [
+    "Badge",
+    "Button",
+    "ButtonGroup",
+    "Carousel",
+    "CarouselContent",
+    "CarouselDots",
+    "CarouselItem",
+    "CarouselNext",
+    "CarouselPrevious",
+    "ColorDisc",
+    "ColorSlider",
+    "ColorWheel",
+    "CountPill",
+    "Icon",
+    "Input",
+    "Label",
+    "PanelEntityRow",
+    "PanelFacts",
+    "PanelRow",
+    "PanelRows",
+    "PanelSection",
+    "Progress",
+    "ResponsiveDialog",
+    "ResponsiveDialogBody",
+    "ResponsiveDialogClose",
+    "ResponsiveDialogContent",
+    "ResponsiveDialogDescription",
+    "ResponsiveDialogFooter",
+    "ResponsiveDialogHeader",
+    "ResponsiveDialogTitle",
+    "SDK_VERSION",
+    "SchemaForm",
+    "SectionIcon",
+    "SectionTitle",
+    "Select",
+    "SelectContent",
+    "SelectItem",
+    "SelectTrigger",
+    "SelectValue",
+    "Slider",
+    "SwatchPicker",
+    "Switch",
+    "Tabs",
+    "TabsContent",
+    "TabsList",
+    "TabsTrigger",
+    "TemperatureBar",
+    "Toggle",
+    "ToggleGroup",
+    "ToggleGroupItem",
+    "ToneSchema",
+    "Widget",
+    "WidgetAction",
+    "WidgetBackdrop",
+    "WidgetChip",
+    "WidgetChoice",
+    "WidgetContent",
+    "WidgetControls",
+    "WidgetCtx",
+    "WidgetDebugTab",
+    "WidgetDebugView",
+    "WidgetDialog",
+    "WidgetGlyph",
+    "WidgetHead",
+    "WidgetHero",
+    "WidgetIcon",
+    "WidgetLayer",
+    "WidgetManifestSchema",
+    "WidgetSizeCtx",
+    "WidgetSliderFill",
+    "WidgetStatus",
+    "WidgetStepper",
+    "WidgetTitle",
+    "WidgetValue",
+    "buildDebugData",
+    "byDomain",
+    "calculateLightGroup",
+    "calculateSensorGroup",
+    "copyText",
+    "countActiveEntities",
+    "defineConfig",
+    "defineWidget",
+    "deprecations",
+    "field",
+    "formatDeprecation",
+    "formatSchemaError",
+    "getEntityAttribute",
+    "getForecasts",
+    "getStream",
+    "getWebRtcClientConfig",
+    "hassMediaUrl",
+    "imagePreset",
+    "imageSrc",
+    "imageUrl",
+    "injectTokens",
+    "isDark",
+    "isEntityActive",
+    "isPanelControllable",
+    "mediaUrl",
+    "monotoneCubicPath",
+    "parseColor",
+    "presetValue",
+    "sendWebRtcCandidate",
+    "startWebRtcSession",
+    "state",
+    "svgColors",
+    "trackEntityHistory",
+    "untrackEntityHistory",
+    "useArea",
+    "useCalendarEvents",
+    "useCamera",
+    "useConfirm",
+    "useConnection",
+    "useCopyText",
+    "useCurrency",
+    "useDaylight",
+    "useEntities",
+    "useEntity",
+    "useEntityHistory",
+    "useEntityStatistics",
+    "useForecast",
+    "useHassConfig",
+    "useIntersectionPause",
+    "useLocale",
+    "useMaterial",
+    "useReducedMotion",
+    "useService",
+    "useStore",
+    "useTemperatureUnit",
+    "useToggle",
+    "useTurnOff",
+    "useTurnOn",
+    "useUnitSystem",
+    "useWidgetContext",
+    "useWidgetDashboard",
+    "useWidgetDialog",
+    "useWidgetDimensions",
+    "useWidgetEntityGroup",
+    "useWidgetGestures",
+    "useWidgetState",
+    "useWidgetViewer",
+    "widgetFields",
+    "z"
   ]
 }

package/dist/framework/hooks/index.d.ts

@@ -3,7 +3,9 @@
  *
  * Hooks for widget development: context, dialog, entity group.
  */
-export { type ReactiveWidgetContext, type ServiceCallFn, useWidgetContext, WidgetCtx, type WidgetDashboard, type WidgetMaterial, type WidgetViewer, type WidgetDimensions, } from "./use-widget-context";
+export { type ReactiveWidgetContext, type ServiceCallFn, useWidgetContext, WidgetCtx, type WidgetDashboard, type WidgetMaterial, type WidgetViewer, type WidgetDimensions, type WidgetStateStore, } from "./use-widget-context";
+export { useWidgetState } from "./use-widget-state";
+export type { WidgetStateVerdict } from "@glasshome/widget-contract/state";
 export { useWidgetDashboard } from "./use-widget-dashboard";
 export { useWidgetViewer } from "./use-widget-viewer";
 export { useMaterial } from "./use-material";

package/dist/framework/hooks/use-widget-context.d.ts

@@ -1,4 +1,5 @@
 import type { MaterialTerms } from "@glasshome/ui/tokens";
+import type { WidgetStateVerdict } from "@glasshome/widget-contract/state";
 /**
  * Reactive widget context.
  *
@@ -34,6 +35,11 @@ export interface WidgetMaterial {
     id: string;
     terms: MaterialTerms;
 }
+/** Values a widget keeps across reloads. `read` is reactive; `write(key, undefined)` deletes; a refused write changes nothing. */
+export interface WidgetStateStore {
+    read(key: string): unknown;
+    write(key: string, value: unknown): WidgetStateVerdict;
+}
 export interface ReactiveWidgetContext {
     updateConfig: (config: Record<string, unknown>) => void;
     /**
@@ -48,6 +54,9 @@ export interface ReactiveWidgetContext {
     /** Present when the host mounts the widget; the service hooks route
         through it. Absent in previews/tests (direct sync-layer fallback). */
     callService?: ServiceCallFn;
+    /** Whether the widget's own grant lets it make this call, so a control it cannot run is never drawn.
+        Absent on hosts that predate this field: draw the control and let the call answer. */
+    canCall?: (domain: string, service: string, entityIds: string[]) => boolean;
     /** The dashboard this instance sits on. Absent on hosts that predate this field. */
     dashboard?: () => WidgetDashboard;
     /** Who is looking. Absent on hosts that predate this field. */
@@ -67,6 +76,8 @@ export interface ReactiveWidgetContext {
         tone: string | null;
         lift: number | null;
     } | null) => void;
+    /** Kept by the host across reloads, for this widget and this person. Absent on hosts that predate this field. */
+    state?: WidgetStateStore;
 }
 export declare const WidgetCtx: import("solid-js").Context<ReactiveWidgetContext | undefined>;
 export declare function useWidgetContext(): ReactiveWidgetContext;

package/dist/framework/hooks/use-widget-state.d.ts

@@ -0,0 +1,10 @@
+import { type WidgetStateVerdict } from "@glasshome/widget-contract/state";
+import { type Accessor } from "solid-js";
+import type { z } from "zod";
+/**
+ * A small value this widget keeps across reloads, for this widget on this board and this person.
+ * The stored value is read through `schema`; anything it refuses reads as `fallback`.
+ * The setter returns the host's verdict: anything but "ok" changed nothing. A value that would not read back
+ * through `schema` after a JSON round trip (a Date, NaN) is refused as "value".
+ */
+export declare function useWidgetState<T>(key: string, schema: z.ZodType<T>, fallback: T): [Accessor<T>, (next: T | ((prev: T) => T)) => WidgetStateVerdict];

package/dist/framework/index.d.ts

@@ -36,7 +36,7 @@ export { WidgetSliderFill } from "./backgrounds/WidgetSliderFill";
 export { type PanelFact, PanelFacts, PanelRow, type PanelRowProps, PanelRows, PanelSection, type PanelSlide, } from "./panel/panel";
 export { isPanelControllable, PanelEntityRow } from "./panel/panel-entity";
 export { buildDebugData, WidgetDebugTab, type WidgetDebugData, type WidgetDebugEntity, WidgetDebugView, WidgetDialog, type SheetTile, type WidgetDialogProps, type WidgetDialogTab, } from "./dialogs";
-export { type AggregationPreset, type ReactiveWidgetContext, type ServiceCallFn, type UseWidgetEntityGroupOptions, type UseWidgetEntityGroupResult, type Daylight, type DaylightPhase, useDaylight, useIntersectionPause, useReducedMotion, useWidgetContext, useWidgetDashboard, useMaterial, useWidgetViewer, useWidgetDialog, useWidgetDimensions, useWidgetEntityGroup, WidgetCtx, type WidgetDashboard, type WidgetMaterial, type WidgetViewer, type WidgetDialogReturn, type WidgetDimensions, type WidgetDimensionsAccessor, WidgetSizeCtx, } from "./hooks";
+export { type AggregationPreset, type ReactiveWidgetContext, type ServiceCallFn, type UseWidgetEntityGroupOptions, type UseWidgetEntityGroupResult, type Daylight, type DaylightPhase, useDaylight, useIntersectionPause, useReducedMotion, useWidgetContext, useWidgetDashboard, useMaterial, useWidgetViewer, useWidgetState, useWidgetDialog, useWidgetDimensions, useWidgetEntityGroup, WidgetCtx, type WidgetDashboard, type WidgetMaterial, type WidgetViewer, type WidgetStateStore, type WidgetStateVerdict, type WidgetDialogReturn, type WidgetDimensions, type WidgetDimensionsAccessor, WidgetSizeCtx, } from "./hooks";
 export { type GestureHandlers, useWidgetGestures } from "./gestures/use-widget-gestures";
 export { injectTokens, type SvgColorKey, svgColors, type Tone, ToneSchema } from "./theming";
 export { widgetFields } from "./fields";

package/dist/framework/panel/panel-entity.d.ts

@@ -4,6 +4,7 @@ export declare function isPanelControllable(domain: string): boolean;
 /**
  * A row for any entity, drawn and wired from its domain: a light dims, a cover
  * opens, a lock locks. The same row the area panel and every group panel use.
+ * A call the widget's grant refuses draws no control; the row still reads.
  */
 export declare function PanelEntityRow(props: {
     entityId: string;

package/dist/framework/panel/panel.d.ts

@@ -9,7 +9,7 @@ export interface PanelSlide {
     onCommit?: (value: number) => void;
     /** Names the value for screen readers and the keyboard handle ("Brightness"). */
     label?: string;
-    /** Keyboard step; the drag reports whole numbers. */
+    /** The value moves in steps of this size, by drag and by keyboard. Unset: the drag reports whole numbers and a key moves 5. */
     step?: number;
 }
 /** A labelled group in the panel's aside ("Lights", "Playing on"). */