@glasshome/widget-sdk 1.3.0 → 1.4.0

package/dist/deprecations.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Reusable deprecation mechanism: one registry drives all three channels
+ * (runtime warn-once, JSDoc `@deprecated`, and the widget-cli source lint) plus the
+ * generated docs table. Every future deprecation is one registry entry + one
+ * `deprecate()` wrapper call, giving widget developers a timed window to migrate.
+ */
+export interface DeprecationEntry {
+    /** Stable identifier, e.g. `widgetFields.title`. Used for warn-once and lint matching. */
+    id: string;
+    /** Version the symbol/pattern was deprecated in. */
+    since: string;
+    /** Version it is removed in. */
+    removeIn: string;
+    /** Human-readable replacement, e.g. `field.title()`. */
+    replacement: string;
+    /** Public docs URL for the migration. */
+    docsUrl: string;
+    /**
+     * Regex source matched against widget files by the CLI lint. Present for patterns
+     * with no wrappable runtime symbol (e.g. the raw-zod config pattern).
+     */
+    sourcePattern?: string;
+}
+export declare const deprecations: readonly DeprecationEntry[];
+/** Format a registry entry into the one-line notice shared by every channel. */
+export declare function formatDeprecation(d: DeprecationEntry): string;
+/** Reset warn-once state. Test-only. */
+export declare function _resetDeprecationWarnings(): void;
+/**
+ * Wrap a deprecated export. On its first call in a dev build, emits a `console.warn`
+ * once per id (formatted from the registry); production builds are silent and add no
+ * overhead beyond a Set lookup. The wrapped function's signature is preserved.
+ */
+export declare function deprecate<A extends unknown[], R>(fn: (...args: A) => R, id: string): (...args: A) => R;

package/dist/deprecations.js

@@ -0,0 +1,65 @@
+//#region src/deprecations.ts
+var e = "https://glasshome.app/docs/widget-sdk/config", t = [
+	{
+		id: "widgetFields.title",
+		since: "1.4.0",
+		removeIn: "2.0.0",
+		replacement: "field.title()",
+		docsUrl: e,
+		sourcePattern: "widgetFields\\.title\\b"
+	},
+	{
+		id: "widgetFields.entityIds",
+		since: "1.4.0",
+		removeIn: "2.0.0",
+		replacement: "field.entities(domain, options?)",
+		docsUrl: e,
+		sourcePattern: "widgetFields\\.entityIds\\b"
+	},
+	{
+		id: "widgetFields.singleEntity",
+		since: "1.4.0",
+		removeIn: "2.0.0",
+		replacement: "field.entity(domain, options?)",
+		docsUrl: e,
+		sourcePattern: "widgetFields\\.singleEntity\\b"
+	},
+	{
+		id: "widgetFields.areaId",
+		since: "1.4.0",
+		removeIn: "2.0.0",
+		replacement: "field.area()",
+		docsUrl: e,
+		sourcePattern: "widgetFields\\.areaId\\b"
+	},
+	{
+		id: "raw-zod-config",
+		since: "1.4.0",
+		removeIn: "2.0.0",
+		replacement: "defineConfig({ ... })",
+		docsUrl: e,
+		sourcePattern: "configSchema\\s*=\\s*z\\.object\\("
+	}
+];
+function n(e) {
+	return `[@glasshome/widget-sdk] ${e.id} is deprecated since ${e.since}, removed in ${e.removeIn}. Use ${e.replacement}. See ${e.docsUrl}`;
+}
+var r = /* @__PURE__ */ new Set();
+function i() {
+	r.clear();
+}
+function a() {
+	return typeof process < "u" && process.env.NODE_ENV !== "production";
+}
+function o(e, i) {
+	return (...o) => {
+		if (a() && !r.has(i)) {
+			r.add(i);
+			let e = t.find((e) => e.id === i);
+			e && console.warn(n(e));
+		}
+		return e(...o);
+	};
+}
+//#endregion
+export { i as _resetDeprecationWarnings, o as deprecate, t as deprecations, n as formatDeprecation };

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

@@ -0,0 +1,96 @@
+import { z, type ZodType } from "zod";
+/**
+ * Widget config API: declare a widget's configSchema without importing zod.
+ *
+ * `field.*` produce config fields; `defineConfig` composes them into a schema
+ * accepted by `defineWidget.configSchema` and rendered by SchemaForm. zod stays a
+ * hidden implementation detail (a field IS a zod schema, but widgets never name it).
+ * For refinements/unions the API can't express, the raw `z` re-export is the escape
+ * hatch (couples the widget to the SDK's zod version).
+ *
+ * Fields return their concrete zod schema type (`ZodOptional`/`ZodDefault`/…) rather
+ * than an erased `Field<T>`, because `z.object` reads that brand to decide whether a
+ * key is optional. Erasing it silently diverges `Infer` from raw `z.infer` (a key
+ * becomes `x: T | undefined` instead of `x?: T`), so the concrete types are load-bearing.
+ *
+ * SchemaForm renders a FLAT object only; `field.group` is the sole nested exception.
+ */
+/** A single config field. Structurally a zod schema producing `T`. */
+export type Field<T> = ZodType<T>;
+/** A map of field name → field, accepted by `defineConfig` and `field.group`. */
+export type ConfigShape = Record<string, ZodType>;
+/** Infer a widget's config type from its schema, without naming zod. */
+export type Infer<C extends ZodType> = z.infer<C>;
+type TextOpts = {
+    title: string;
+    description?: string;
+    default?: string;
+};
+type NumberOpts = {
+    title: string;
+    description?: string;
+    min?: number;
+    max?: number;
+    default?: number;
+};
+type ToggleOpts = {
+    title: string;
+    description?: string;
+    default?: boolean;
+};
+type ChoiceOpts<T extends string> = {
+    title: string;
+    description?: string;
+    default?: T;
+};
+type EntitiesOpts = {
+    title?: string;
+    description?: string;
+    deviceClass?: string;
+};
+declare function title(): z.ZodOptional<z.ZodString>;
+declare function text(o: TextOpts & {
+    default: string;
+}): z.ZodDefault<z.ZodString>;
+declare function text(o: TextOpts): z.ZodOptional<z.ZodString>;
+declare function number(o: NumberOpts & {
+    default: number;
+}): z.ZodDefault<z.ZodNumber>;
+declare function number(o: NumberOpts): z.ZodOptional<z.ZodNumber>;
+declare function toggle(o: ToggleOpts): z.ZodDefault<z.ZodBoolean>;
+declare function choice<const T extends string>(values: readonly T[], o: ChoiceOpts<T> & {
+    default: T;
+}): z.ZodDefault<z.ZodEnum<{
+    [K in T]: K;
+}>>;
+declare function choice<const T extends string>(values: readonly T[], o: ChoiceOpts<T>): z.ZodOptional<z.ZodEnum<{
+    [K in T]: K;
+}>>;
+declare function entities(domain: string, o?: EntitiesOpts): z.ZodDefault<z.ZodArray<z.ZodString>>;
+declare function entity(domain: string, o?: EntitiesOpts): z.ZodDefault<z.ZodArray<z.ZodString>>;
+declare function area(o?: {
+    title?: string;
+}): z.ZodOptional<z.ZodString>;
+declare function stringList(o: {
+    title: string;
+    description?: string;
+}): z.ZodDefault<z.ZodArray<z.ZodString>>;
+declare function group<S extends ConfigShape>(shape: S, o: {
+    title: string;
+}): Field<{
+    [K in keyof S]: Infer<S[K]>;
+}>;
+export declare const field: {
+    title: typeof title;
+    text: typeof text;
+    number: typeof number;
+    toggle: typeof toggle;
+    choice: typeof choice;
+    entities: typeof entities;
+    entity: typeof entity;
+    area: typeof area;
+    stringList: typeof stringList;
+    group: typeof group;
+};
+export declare function defineConfig<S extends ConfigShape>(shape: S): z.ZodObject<{ -readonly [P in keyof S]: S[P]; }, z.core.$strip>;
+export {};

package/dist/framework/fields.d.ts

@@ -1,20 +1,34 @@
 import { z } from "zod";
 /**
  * Pre-built Zod field helpers for common widget config patterns.
- * Each helper returns a Zod schema with `.meta()` annotations that
- * SchemaForm uses to render the appropriate UI (entity picker, area picker, etc.).
+ *
+ * @deprecated since 1.4.0, removed in 2.0.0. Use the config API instead:
+ * `defineConfig` + `field.*` (`field.title()`, `field.entities()`, `field.entity()`,
+ * `field.area()`). See https://glasshome.app/docs/widget-sdk/config
  */
 export declare const widgetFields: {
-    /** Optional display name override (renders as text input) */
+    /**
+     * Optional display name override (renders as text input).
+     * @deprecated since 1.4.0, removed in 2.0.0. Use `field.title()`.
+     */
     title: () => z.ZodOptional<z.ZodString>;
-    /** Multi-select entity picker for a HA domain */
+    /**
+     * Multi-select entity picker for a HA domain.
+     * @deprecated since 1.4.0, removed in 2.0.0. Use `field.entities(domain, options?)`.
+     */
     entityIds: (domain: string, options?: {
         deviceClass?: string;
-    }) => z.ZodDefault<z.ZodArray<z.ZodString>>;
-    /** Single-select entity picker for a HA domain */
+    } | undefined) => z.ZodDefault<z.ZodArray<z.ZodString>>;
+    /**
+     * Single-select entity picker for a HA domain.
+     * @deprecated since 1.4.0, removed in 2.0.0. Use `field.entity(domain, options?)`.
+     */
     singleEntity: (domain: string, options?: {
         deviceClass?: string;
-    }) => z.ZodDefault<z.ZodArray<z.ZodString>>;
-    /** Area picker dropdown */
+    } | undefined) => z.ZodDefault<z.ZodArray<z.ZodString>>;
+    /**
+     * Area picker dropdown.
+     * @deprecated since 1.4.0, removed in 2.0.0. Use `field.area()`.
+     */
     areaId: () => z.ZodOptional<z.ZodString>;
 };

package/dist/framework/index.d.ts

@@ -41,5 +41,6 @@ export { type AggregationPreset, type ReactiveWidgetContext, type ServiceCallFn,
 export { type GestureHandlers, useWidgetGestures } from "./gestures/use-widget-gestures";
 export { injectTokens, type SvgColorKey, svgColors, type Tone, ToneSchema, } from "./theming";
 export { widgetFields } from "./fields";
+export { type ConfigShape, defineConfig, field, type Field, type Infer, } from "./config";
 export { calculateLightGroup, calculateSensorGroup, countActiveEntities, getEntityAttribute, isEntityActive, type LightGroupResult, type SensorGroupResult, type SensorGroupType, } from "./utils";
 export type { EntityView, WidgetStyles, WidgetVariantConfig, } from "./types";

package/dist/index.d.ts

@@ -6,3 +6,5 @@ export { formatSchemaError, WidgetManifestSchema } from "./schemas";
 export { isDark } from "./theme";
 export type { GridSize, WidgetContext, WidgetDefinition, WidgetManifest, } from "./types";
 export { SDK_VERSION } from "./version";
+export { type DeprecationEntry, deprecations, formatDeprecation } from "./deprecations";
+export { z } from "zod";