@glasshome/widget-sdk 1.18.1 → 1.20.0

package/dist/framework/gestures/use-widget-gestures.d.ts

@@ -26,6 +26,8 @@ export interface GestureHandlers {
     dispose: () => void;
     /** Where a hold is filling from, relative to the element; `fired` once it opened. */
     hold?: () => HoldFlood | null;
+    /** True while a hold does something. */
+    holds?: () => boolean;
     /** Keyboard door: Enter or Space taps, the context-menu key or Shift+F10 holds. */
     onKeyDown?: (e: KeyboardEvent) => void;
 }

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

@@ -50,6 +50,10 @@ export interface ReactiveWidgetContext {
     developer?: () => boolean;
     /** The tile's box on the page, so a held tile's sheet opens beside it. Absent: it opens centred. */
     anchor?: () => HTMLElement | undefined;
+    /** Host hook: whether holding this widget opens anything. Absent on hosts that predate this field. */
+    onHoldable?: (holds: boolean) => void;
+    /** Host hook: a hold on this widget fired. Absent on hosts that predate this field. */
+    onHeld?: () => void;
 }
 export declare const WidgetCtx: import("solid-js").Context<ReactiveWidgetContext | undefined>;
 export declare function useWidgetContext(): ReactiveWidgetContext;

package/dist/index.js

@@ -331,20 +331,20 @@ function xn(e, t) {
 		let t = i();
 		if (t.tap || t.hold || t.slide) {
 			if (a.isDown = !0, a.isTouch = e.pointerType === "touch", a.element = e.currentTarget, p(a.element), a.startX = e.clientX, a.startY = e.clientY, a.startTime = Date.now(), a.hasMoved = !1, a.sliding = !1, t.hold) {
-				let n = t.hold.delay ?? 550, r = a.element.getBoundingClientRect(), i = e.clientX - r.left, o = e.clientY - r.top, c = Math.hypot(Math.max(i, r.width - i), Math.max(o, r.height - o));
+				let r = t.hold.delay ?? 550, i = a.element.getBoundingClientRect(), o = e.clientX - i.left, c = e.clientY - i.top, l = Math.hypot(Math.max(o, i.width - o), Math.max(c, i.height - c));
 				a.graceTimer = setTimeout(() => {
 					a.graceTimer = null, s({
-						x: i,
-						y: o,
-						r: c,
+						x: o,
+						y: c,
+						r: l,
 						fired: !1
 					});
-				}, Math.min(150, n)), a.holdTimer = setTimeout(() => {
+				}, Math.min(150, r)), a.holdTimer = setTimeout(() => {
 					a.holdTimer = null, a.isDown && !a.hasMoved && (s((e) => e && {
 						...e,
 						fired: !0
-					}), bn.bump(), a.element && h(a.element), t.hold?.action(), a.isDown = !1);
-				}, n);
+					}), bn.bump(), a.element && h(a.element), t.hold?.action(), n?.onHeld?.(), a.isDown = !1);
+				}, r);
 			}
 			if (!a.isTouch && t.slide) try {
 				e.currentTarget.setPointerCapture(e.pointerId);
@@ -388,7 +388,7 @@ function xn(e, t) {
 		onKeyDown: (e) => {
 			if (e.target !== e.currentTarget) return;
 			let t = i();
-			(e.key === "Enter" || e.key === " ") && t.tap ? (e.preventDefault(), t.tap()) : (e.key === "ContextMenu" || e.shiftKey && e.key === "F10") && t.hold && (e.preventDefault(), t.hold.action());
+			(e.key === "Enter" || e.key === " ") && t.tap ? (e.preventDefault(), t.tap()) : (e.key === "ContextMenu" || e.shiftKey && e.key === "F10") && t.hold && (e.preventDefault(), t.hold.action(), n?.onHeld?.());
 		},
 		onPointerDown: v,
 		onPointerMove: y,
@@ -410,6 +410,7 @@ function xn(e, t) {
 			return e.tap || e.hold ? "manipulation" : "auto";
 		},
 		hold: o,
+		holds: () => !!i().hold,
 		dispose: () => {
 			m(), u &&= (u.disconnect(), null), l = null, c = null;
 		}
@@ -1120,7 +1121,7 @@ function Vr(t) {
 	let i = rn(n), a = xn(() => ({ hold: i?.hasSheet() ? { action: () => (q.get(n ?? {}) ?? q.get(d))?.() } : void 0 }));
 	k(a.dispose);
 	let o = () => t.emptyState && n ? r : t.gestures ?? (i?.hasSheet() ? a : void 0);
-	E(() => i?.setTone(t.color ?? (t.tone ? `var(--tone-${t.tone})` : void 0)));
+	n && !(tn in n) && (E(() => n?.onHoldable?.(!t.emptyState && !!o()?.holds?.())), k(() => n?.onHoldable?.(!1))), E(() => i?.setTone(t.color ?? (t.tone ? `var(--tone-${t.tone})` : void 0)));
 	let [s, c] = O(), [l, u] = O({
 		width: 0,
 		height: 0
@@ -1286,35 +1287,35 @@ Z.Content = fr, Z.Icon = kn, Z.Title = _r, Z.Status = mr, Z.Value = Nr, Z.Slider
 //#region src/framework/panel/panel.tsx
 var Ur = /*#__PURE__*/ B("<section class=glasshome-panel-section><h3 class=glasshome-panel-label>"), Wr = /*#__PURE__*/ B("<div class=glasshome-panel-rows>"), Gr = /*#__PURE__*/ B("<span class=\"glasshome-widget-slider-fill glasshome-panel-row-fill\">"), Kr = /*#__PURE__*/ B("<span class=\"glasshome-widget-icon glass glasshome-panel-row-icon\">"), qr = /*#__PURE__*/ B("<span class=glasshome-panel-row-state>"), Jr = /*#__PURE__*/ B("<span class=glasshome-panel-row-text><span class=glasshome-panel-row-name>"), Yr = /*#__PURE__*/ B("<span class=glasshome-panel-row-trailing>"), Xr = /*#__PURE__*/ B("<div class=glasshome-panel-row-wrap>"), Zr = /*#__PURE__*/ B("<div>"), Qr = /*#__PURE__*/ B("<div class=\"glasshome-panel-facts glass\">"), $r = /*#__PURE__*/ B("<div class=glasshome-panel-fact><span class=glasshome-panel-row-text><span class=glasshome-panel-fact-label></span><span class=glasshome-panel-fact-value>"), ei = 450, ti = 8, ni = (e, t, n) => Math.min(n, Math.max(t, e)), ri = "button, a, input, select, textarea, [role=\"slider\"], [role=\"radio\"], [role=\"switch\"]";
 function ii(e) {
-	let t, n = !1, r = !1, i, a = 0, o = (t, n) => {
+	let t = A(W), n, r = !1, i = !1, a, o = 0, s = (t, n) => {
 		let r = e.slide?.();
 		if (!r) return 0;
 		let i = t.getBoundingClientRect(), a = e.axis === "x" ? (n.clientX - i.left) / i.width : 1 - (n.clientY - i.top) / i.height, o = r.min ?? 0, s = r.max ?? 100;
 		return Math.round(ni(o + a * (s - o), o, s));
-	}, s = () => {
-		clearTimeout(i), t = void 0;
+	}, c = () => {
+		clearTimeout(a), n = void 0;
 	};
-	return k(() => clearTimeout(i)), {
-		onPointerDown: (a) => {
-			if (a.button !== 0 || t) return;
-			let o = a.target instanceof Element ? a.target.closest(ri) : null;
-			o && o !== a.currentTarget || (t = {
-				x: a.clientX,
-				y: a.clientY,
-				id: a.pointerId
-			}, a.currentTarget.setPointerCapture?.(a.pointerId), n = !1, r = !1, e.onHold && (i = setTimeout(() => {
-				r = !0, e.onHold?.();
+	return k(() => clearTimeout(a)), {
+		onPointerDown: (o) => {
+			if (o.button !== 0 || n) return;
+			let s = o.target instanceof Element ? o.target.closest(ri) : null;
+			s && s !== o.currentTarget || (n = {
+				x: o.clientX,
+				y: o.clientY,
+				id: o.pointerId
+			}, o.currentTarget.setPointerCapture?.(o.pointerId), r = !1, i = !1, e.onHold && (a = setTimeout(() => {
+				i = !0, e.onHold?.(), t?.onHeld?.();
 			}, ei)));
 		},
-		onPointerMove: (s) => {
-			if (!t || s.pointerId !== t.id || r) return;
-			let c = s.currentTarget, l = e.axis === "x" ? Math.abs(s.clientX - t.x) : Math.abs(s.clientY - t.y);
-			!n && e.slide?.() && l > ti && (n = !0, clearTimeout(i)), n ? (a = o(c, s), e.slide?.()?.onChange(a)) : Math.hypot(s.clientX - t.x, s.clientY - t.y) > ti && clearTimeout(i);
+		onPointerMove: (t) => {
+			if (!n || t.pointerId !== n.id || i) return;
+			let c = t.currentTarget, l = e.axis === "x" ? Math.abs(t.clientX - n.x) : Math.abs(t.clientY - n.y);
+			!r && e.slide?.() && l > ti && (r = !0, clearTimeout(a)), r ? (o = s(c, t), e.slide?.()?.onChange(o)) : Math.hypot(t.clientX - n.x, t.clientY - n.y) > ti && clearTimeout(a);
 		},
-		onPointerUp: (i) => {
-			t && i.pointerId === t.id && (n ? e.slide?.()?.onCommit?.(a) : r || e.onTap?.(), s());
+		onPointerUp: (t) => {
+			n && t.pointerId === n.id && (r ? e.slide?.()?.onCommit?.(o) : i || e.onTap?.(), c());
 		},
-		onPointerCancel: s
+		onPointerCancel: c
 	};
 }
 function ai(e) {
@@ -2778,7 +2779,7 @@ function Qa() {
 //#region src/version.ts
 var $a = {
 	name: "@glasshome/widget-sdk",
-	version: "1.18.1",
+	version: "1.20.0",
 	description: "SDK for building GlassHome dashboard widgets with SolidJS",
 	keywords: [
 		"dashboard",
@@ -2801,7 +2802,8 @@ var $a = {
 	files: [
 		"dist",
 		"preview",
-		"tailwind-sources.css"
+		"tailwind-sources.css",
+		"guide"
 	],
 	type: "module",
 	sideEffects: !1,

package/guide/widgets.md

@@ -0,0 +1,74 @@
+# GlassHome widgets
+
+Matches the installed `@glasshome/widget-sdk`. Wins over memory and older docs.
+
+## Loop
+
+1. `bun widget add --name <name>`: `src/<name>/` with a working sensor tile (`index.tsx`, `manifest.json`). Start from it.
+2. Write it. `examples` in `defineWidget` (label, size, config) are what preview renders. Demo entity ids: `node_modules/@glasshome/sync-layer/dist/demo/ids.d.ts`; a wrong id renders the empty state. Missing a kind of entity: use a stand-in and config to show each state.
+3. `bun widget build`: typecheck, bundle, validate. Fix every error before previewing.
+4. `bun widget preview <name> --sizes grid`: every example at common tile sizes, light and dark, into `preview/sweep/` with a contact sheet each. Open the images and look. First run: `bun add -d playwright && bunx playwright install chromium`. A crash fails the render with its error.
+   - Narrow: `--sizes 150x156,340x242`, `--theme dark`, `--example 0`.
+   - Change state: `--config '<json>'`, `--service '<domain.service>|<entity_id>|<json>'`, `--at 2026-06-15T21:00:00`, `--click '<selector>'`.
+   - Inspect: `--eval '<expr>'` prints per render (`root` = shadow root).
+5. Repeat 3-4 until 1×1, 2×2 and a big tile read right in both themes.
+6. Live: `bun widget connect <dashboard-url>`.
+7. Ship: `bun widget publish --name <name> --bump patch|minor|major`. Version lives in `manifest.json`.
+
+## Imports
+
+- Everything from `@glasshome/widget-sdk`, UI primitives included.
+- Never `@glasshome/ui` (unchecked version, dead tile on mismatch) or `@glasshome/sync-layer` (second store). Keep `@glasshome/ui` installed; the build reads its CSS.
+- Home Assistant only via SDK hooks (`useEntity`, `useEntities`, `useService`, `useToggle`, …). Declare every read/controlled domain in manifest capabilities.
+- SDK too old for something in the docs: `bun widget upgrade`.
+- Edit the inline `manifest` in `defineWidget`; build copies it into `manifest.json` (name, icon, sizes, capabilities, examples, schema). `version` and `sdkVersion` live only in `manifest.json`.
+- Config: `defineConfig` + `field.*`. `field.entity(domain)` stores a one-item array: read `config.entityIds[0]`.
+
+## Tile
+
+Parts inside `Widget.Content`; they lay out and resize themselves. Never measure to lay out.
+
+| Need | Part |
+|---|---|
+| Colour | `tone` (`accent info success warning danger neutral`) or `color` on `Widget`; `accent` on `Widget.Content` for state colour |
+| Icon, name, eyebrow, chips | `Widget.Head` (`active`, `count`, `aside`) |
+| Big value, unit, art | `Widget.Hero` |
+| Control row | `Widget.Controls` with `Widget.Stepper`, `Widget.Choice`, `Widget.Action` |
+| Stateless action | `Widget.Action`; `useConfirm()` + `<Widget confirmed>` when the whole tile runs it |
+| Small fact | `Widget.Chip` |
+| Photo behind tile | `Widget.Backdrop` |
+| Own full-bleed layer | `Widget.Layer` |
+| Faint corner icon | `Widget.Glyph` |
+| Controllable continuous value | `Widget.SliderFill` |
+
+## Sizes
+
+1×1 to 8×8. Under 130px tall or 140px wide the tile is compact: `eyebrow` and `sub` hide, so carry state in `tone` and the icon. Tokens, never px: `--widget-text-value`, `--widget-text-name`, `--widget-text-meta`, `--widget-text-sub`, `--widget-text-caption`, `--widget-control-h`, `--widget-grid-pad`, `--widget-grid-gap`, `--widget-icon-box`, `--widget-icon-glyph`. Layout by container query (`@[150px]:…`, `@container widget (…)`). What renders by `useWidgetDimensions()`, inside `<Widget>` only.
+
+## Sheet
+
+Render `<WidgetDialog>` next to `<Widget>`, spreading the dialog parts (`ResponsiveDialog*`, `Button`, `SchemaForm`, `Tabs*`, see the scaffold) and `useWidgetDialog().dialogProps`. Hold opens the sheet on its own once `sheet` is passed; no gesture wiring. Only what the tile lacks (group members, colours, modes, forecast). Pass `sheet` only when there is something: `{...(extras() ? { sheet: () => <MySheet /> } : {})}`. Build from `PanelSection`, `PanelRows`, `PanelRow`, `PanelEntityRow`, `PanelFacts`, `ToggleGroup`, `SwatchPicker`, `TemperatureBar`, `ColorDisc`. Never repeat the tile's value, name or art. Widget CSS does not reach it.
+
+## Primitives
+
+`Badge`, `Button`, `ButtonGroup`, `CountPill`, `Icon`, `Input`, `Label`, `Progress`, `SchemaForm`, `SectionIcon`, `SectionTitle`, `Select`, `Slider`, `Switch`, `Tabs`, `Toggle`, `ToggleGroup`, `Carousel`, `ColorWheel`, `ColorSlider`, `ResponsiveDialog` + parts. `Icon`, never `iconify-icon`. Never restyle with own classes.
+
+## Rules
+
+- No hand-rolling what the SDK has: sliders, steppers, dialogs, sheets, hold gestures, loading/error states.
+- Theme vars only (`--foreground`, `--muted-foreground`, `--card`, `--primary`, `--border`, `--success`, `--warning`, `--destructive`, `--radius`). Never declare them on `:host`; no own colour/radius tokens; no `--color-*`.
+- Own CSS = layout and bespoke art. No custom panel/row/chip/button chrome.
+- Tailwind classes literal in source, never concatenated. `dark:` works; `isDark()` for the boolean.
+- No dot status lamps. No thin vertical bars (read as a text caret). No all-caps. Separator ` · `.
+- One icon per item, not per line. Icons, fills and pictures before text.
+- Lead with the answer (value + unit, or a verdict); one small line explains it. Never show a value twice. States per device class (Open/Closed, Detected/Clear).
+- Continuous values keep the full-tile slider; buttons beside it. A stepper never stands alone.
+- Dialog content scrolls in `ResponsiveDialogBody`; no own `overflow`/`max-height` in a dialog.
+- Groups: one tap brings all members to one state; locks never unlock in one tap; doors, gates, garage doors never join bulk actions.
+- Readings update text in place; never rebuild DOM. `Index` for lists of readings. Over 20 s of changing demo data a widget adds and removes no DOM nodes.
+- Everything sits on an edge; text left, values/actions right. One accent per view; defaults quiet. No card in a card.
+- Motion: colours morph, never snap; time transitions with `--duration-state` / `--ease-morph` (zeroed under reduced motion). Decorative loops scale by `var(--motion-ambient, 0)`. Gate on `useReducedMotion()`; pause offscreen with `useIntersectionPause()`.
+
+## More
+
+Docs as markdown: https://glasshome.app/llms.txt, `https://glasshome.app/md/widgets/<page>` (`widget-sheets`, `widget-styling`, `widget-sdk`, `widget-api-reference`, `widget-capabilities`, `widget-previews`). Official widgets as worked examples: https://github.com/glasshome/widgets (`src/button`, `src/sensor`); where they differ from this guide, the guide wins.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glasshome/widget-sdk",
-  "version": "1.18.1",
+  "version": "1.20.0",
   "description": "SDK for building GlassHome dashboard widgets with SolidJS",
   "keywords": [
     "dashboard",
@@ -25,7 +25,8 @@
   "files": [
     "dist",
     "preview",
-    "tailwind-sources.css"
+    "tailwind-sources.css",
+    "guide"
   ],
   "type": "module",
   "sideEffects": false,