@glasshome/widget-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GlassHome Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# @glasshome/widget-sdk
+
+SDK for building GlassHome dashboard widgets with SolidJS.
+
+Provides `defineWidget`, reactive entity bindings, framework components/hooks, a Vite plugin for widget development, and Tailwind v4 source paths — everything you need to build, preview, and ship dashboard widgets.
+
+## Install
+
+```bash
+npm install @glasshome/widget-sdk solid-js
+# or
+bun add @glasshome/widget-sdk solid-js
+```
+
+> `solid-js ^1.9.11` is a required peer dependency.
+
+## Subpath Imports
+
+### `@glasshome/widget-sdk` — SDK API
+
+Core widget API: define widgets, create reactive entity bindings, and use framework components/hooks.
+
+```tsx
+import { defineWidget, createEntity, SDK_VERSION } from "@glasshome/widget-sdk";
+
+const entity = createEntity("light.living_room");
+
+export default defineWidget({
+  manifest: {
+    tag: "glasshome-my-widget",
+    type: "status",
+    name: "My Widget",
+    size: "small",
+    sdkVersion: "^0.1.0",
+    defaultConfig: { label: "Hello" },
+  },
+  component: (props) => <div>{props.config.label}</div>,
+});
+```
+
+### `@glasshome/widget-sdk/vite` — Vite Plugin
+
+Vite plugin for widget development. Handles widget bundling, preview server, and registry generation.
+
+```typescript
+// vite.config.ts
+import { defineConfig } from "vite";
+import { glasshomeWidget } from "@glasshome/widget-sdk/vite";
+
+export default defineConfig({
+  plugins: [glasshomeWidget()],
+});
+```
+
+The plugin accepts an optional `entry` option (defaults to `"src/index.tsx"`):
+
+```typescript
+glasshomeWidget({ entry: "src/my-widget.tsx" });
+```
+
+### `@glasshome/widget-sdk/tailwind-sources` — Tailwind v4 CSS Source
+
+Provides a `@source` directive for Tailwind v4 so the compiler scans widget SDK source files for class names.
+
+```css
+/* In your widget's CSS entrypoint */
+@import "tailwindcss";
+@source "@glasshome/widget-sdk/tailwind-sources";
+```
+
+## Peer Dependencies
+
+| Package    | Required | Notes                                       |
+| ---------- | -------- | ------------------------------------------- |
+| `solid-js` | Yes      | SolidJS reactive primitives and JSX runtime |
+
+## License
+
+MIT

package/dist/create-entity.d.ts

@@ -0,0 +1,22 @@
+/**
+ * SolidJS-specific utility — NOT part of the framework-agnostic SDK contract.
+ * This module uses SolidJS signals for reactive entity state management.
+ * It is exported from the SDK as a convenience for SolidJS widget authors.
+ */
+import { type Accessor } from "solid-js";
+export interface Entity {
+    id: string;
+    state: string;
+    attributes: Record<string, unknown>;
+    last_updated?: string;
+}
+/**
+ * Create a reactive entity signal. Returns a signal accessor that tracks
+ * entity state changes.
+ *
+ * NOTE: The setter from `createSignal` is intentionally destructured away.
+ * The signal infrastructure is kept in place so that when the sync-layer is
+ * ported, the runtime can update entity state reactively without changing
+ * the public API surface. Until then the accessor behaves as a constant.
+ */
+export declare function createEntity(initialState: Entity): Accessor<Entity>;

package/dist/define-widget.d.ts

@@ -0,0 +1,10 @@
+import type { WidgetDefinition } from "./types";
+/**
+ * Define a widget and return its definition for registration with the dashboard.
+ *
+ * The dashboard renders widgets as plain SolidJS components via <Dynamic>,
+ * so no Web Component registration is needed.
+ *
+ * @template C - Widget configuration type
+ */
+export declare function defineWidget<C = Record<string, unknown>>(definition: WidgetDefinition<C>): WidgetDefinition<C>;

package/dist/framework/backgrounds/Glow.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Glow Component
+ *
+ * Background glow effect for widgets.
+ * Renders a radial gradient background at the BACKGROUND z-index layer.
+ *
+ * @example
+ * ```tsx
+ * <Glow color="blue" />
+ * ```
+ */
+import type { JSX } from "solid-js";
+import type { ColorVariant } from "../types";
+export interface GlowProps {
+    /** Glow color (Tailwind color name or CSS color) */
+    color: ColorVariant;
+    /** Additional CSS classes */
+    class?: string;
+}
+/**
+ * Glow effect component
+ * Applies a blurred radial gradient background effect
+ */
+export declare function Glow(props: GlowProps): JSX.Element;

package/dist/framework/backgrounds/WidgetSliderFill.d.ts

@@ -0,0 +1,33 @@
+/**
+ * WidgetSliderFill Component
+ *
+ * Animated fill overlay that follows a slider value.
+ * Automatically adapts direction based on widget orientation.
+ *
+ * @example
+ * ```tsx
+ * <Widget gestures={{ slide: { value, onChange } }}>
+ *   <Widget.SliderFill value={brightness} color="rgb(255, 200, 0)" />
+ *   <Widget.Content>...</Widget.Content>
+ * </Widget>
+ * ```
+ */
+import type { JSX } from "solid-js";
+export interface WidgetSliderFillProps {
+    /** Current value (0-100) */
+    value: number;
+    /** Fill color (CSS color string) */
+    color?: string;
+    /** Show glow effect */
+    glow?: boolean;
+    /** Opacity of the fill (0-1) */
+    opacity?: number;
+    /** Whether slider is currently being dragged (disables transition) */
+    isDragging?: boolean;
+    /** Additional CSS classes */
+    class?: string;
+}
+/**
+ * Animated slider fill that adapts to widget orientation
+ */
+export declare function WidgetSliderFill(props: WidgetSliderFillProps): JSX.Element;

package/dist/framework/components/WidgetContent.d.ts

@@ -0,0 +1,29 @@
+/**
+ * WidgetContent Component
+ *
+ * Standard content container for widgets with consistent padding, gap, and layout direction.
+ *
+ * Uses contentLayout (not orientation) for UI arrangement:
+ * - Tall widgets (150px+) -> vertical layout (stacked)
+ * - Other widgets -> follows aspect ratio
+ *
+ * @example
+ * ```tsx
+ * <Widget.Content>
+ *   <Widget.Icon icon={<Power />} />
+ *   <Widget.Title>Living Room</Widget.Title>
+ * </Widget.Content>
+ * ```
+ */
+import type { JSX } from "solid-js";
+export interface WidgetContentProps {
+    /** Additional CSS classes */
+    class?: string;
+    /** Content children */
+    children: JSX.Element;
+}
+/**
+ * Widget content container with auto-responsive layout
+ * Ensures proper z-index layering for title, status, and controls
+ */
+export declare function WidgetContent(props: WidgetContentProps): JSX.Element;

package/dist/framework/components/WidgetEmptyState.d.ts

@@ -0,0 +1,34 @@
+/**
+ * WidgetEmptyState Component
+ *
+ * Placeholder component for widgets with no data or content.
+ * Shows a centered message with optional icon and action.
+ *
+ * @example
+ * ```tsx
+ * <Widget.EmptyState
+ *   icon={<AlertCircle />}
+ *   title="No devices found"
+ *   message="Add devices to see them here"
+ *   action={<Button>Add Device</Button>}
+ * />
+ * ```
+ */
+import type { JSX } from "solid-js";
+export interface WidgetEmptyStateProps {
+    /** Icon to display (optional) */
+    icon?: JSX.Element;
+    /** Main title/heading */
+    title?: string;
+    /** Descriptive message */
+    message?: string;
+    /** Optional action button */
+    action?: JSX.Element;
+    /** Additional CSS classes */
+    class?: string;
+}
+/**
+ * Widget empty state component
+ * Shows centered placeholder when widget has no content
+ */
+export declare function WidgetEmptyState(props: WidgetEmptyStateProps): JSX.Element;

package/dist/framework/components/WidgetIcon.d.ts

@@ -0,0 +1,48 @@
+/**
+ * WidgetIcon Component
+ *
+ * Icon component with automatic sizing and glow effect.
+ * Supports both Tailwind classes and dynamic CSS colors for background/glow.
+ *
+ * @example Static color (Tailwind classes)
+ * ```tsx
+ * <Widget.Icon
+ *   icon={<Power />}
+ *   color="bg-blue-500 dark:bg-blue-400"
+ *   glow="shadow-blue-500/50 dark:shadow-blue-400/50"
+ * />
+ * ```
+ *
+ * @example Dynamic color (CSS color string — adaptive contrast)
+ * ```tsx
+ * <Widget.Icon
+ *   icon={<Lightbulb />}
+ *   dynamicColor="hsl(320, 100%, 50%)"
+ * />
+ * ```
+ */
+import type { JSX } from "solid-js";
+export interface WidgetIconProps {
+    /** Icon component (JSX.Element) */
+    icon: JSX.Element;
+    /** Background color as Tailwind class (e.g. "bg-blue-500 dark:bg-blue-400") */
+    color?: string;
+    /** Glow/shadow effect as Tailwind class (e.g. "shadow-blue-500/50") */
+    glow?: string;
+    /**
+     * Dynamic CSS color string (rgb, hsl, hex).
+     * When provided, icon background and glow are derived adaptively from this color.
+     * Takes precedence over `color` and `glow` props.
+     */
+    dynamicColor?: string;
+    /** Reduce opacity */
+    dimmed?: boolean;
+    /** Number of entities - creates stacked background effect (1 = single, 2+ = stacked backgrounds) */
+    entityCount?: number;
+    /** Additional CSS classes */
+    class?: string;
+}
+/**
+ * Widget icon component with auto-responsive sizing
+ */
+export declare function WidgetIcon(props: WidgetIconProps): JSX.Element;

package/dist/framework/components/WidgetMetrics.d.ts

@@ -0,0 +1,47 @@
+/**
+ * WidgetMetrics Component
+ *
+ * Small data displays for showing multiple stats/values.
+ * Automatically arranges metrics based on widget size.
+ *
+ * @example
+ * ```tsx
+ * <Widget.Metrics>
+ *   <Widget.Metrics.Item label="Temp" value="72F" />
+ *   <Widget.Metrics.Item label="Humidity" value="45%" />
+ *   <Widget.Metrics.Item label="Battery" value="87%" />
+ * </Widget.Metrics>
+ * ```
+ */
+import type { JSX } from "solid-js";
+export interface WidgetMetricsProps {
+    /** Layout direction (default: "auto" - horizontal for horizontal widgets, vertical for others) */
+    direction?: "horizontal" | "vertical" | "auto";
+    /** Additional CSS classes */
+    class?: string;
+    /** Metric items */
+    children: JSX.Element;
+}
+export interface WidgetMetricsComponent {
+    (props: WidgetMetricsProps): JSX.Element;
+    Item: typeof WidgetMetricsItem;
+}
+export interface WidgetMetricsItemProps {
+    /** Metric label */
+    label: string;
+    /** Metric value */
+    value: string | number;
+    /** Optional unit */
+    unit?: string;
+    /** Optional icon */
+    icon?: JSX.Element;
+    /** Whether to dim the metric */
+    dimmed?: boolean;
+    /** Additional CSS classes */
+    class?: string;
+}
+/**
+ * Individual metric item
+ */
+export declare function WidgetMetricsItem(props: WidgetMetricsItemProps): JSX.Element;
+export declare const WidgetMetrics: WidgetMetricsComponent;

package/dist/framework/components/WidgetStatus.d.ts

@@ -0,0 +1,26 @@
+/**
+ * WidgetStatus Component
+ *
+ * Status text component with auto-responsive typography.
+ *
+ * @example
+ * ```tsx
+ * <Widget.Status>{entity.state}</Widget.Status>
+ * ```
+ */
+import type { JSX } from "solid-js";
+export interface WidgetStatusProps {
+    /** Reduce opacity further */
+    dimmed?: boolean;
+    /** Additional CSS classes */
+    class?: string;
+    /** Show "Unavailable" text instead of children */
+    isUnavailable?: boolean;
+    /** Status text */
+    children: JSX.Element;
+}
+/**
+ * Widget status component with auto-responsive typography
+ * Positioned above other content with proper z-index
+ */
+export declare function WidgetStatus(props: WidgetStatusProps): JSX.Element;

package/dist/framework/components/WidgetSubtitle.d.ts

@@ -0,0 +1,28 @@
+/**
+ * WidgetSubtitle Component
+ *
+ * Secondary text component below the title with automatic typography scaling.
+ *
+ * @example
+ * ```tsx
+ * <Widget.Subtitle>Living Room</Widget.Subtitle>
+ * ```
+ *
+ * @example With dimmed style
+ * ```tsx
+ * <Widget.Subtitle dimmed>2 devices offline</Widget.Subtitle>
+ * ```
+ */
+import type { JSX } from "solid-js";
+export interface WidgetSubtitleProps {
+    /** Whether to dim the subtitle */
+    dimmed?: boolean;
+    /** Additional CSS classes */
+    class?: string;
+    /** Subtitle text */
+    children: JSX.Element;
+}
+/**
+ * Widget subtitle component with auto-responsive typography
+ */
+export declare function WidgetSubtitle(props: WidgetSubtitleProps): JSX.Element;

package/dist/framework/components/WidgetTitle.d.ts

@@ -0,0 +1,29 @@
+/**
+ * WidgetTitle Component
+ *
+ * Title component with automatic typography scaling and optional badge.
+ *
+ * @example
+ * ```tsx
+ * <Widget.Title>{config.title}</Widget.Title>
+ * ```
+ *
+ * @example With badge
+ * ```tsx
+ * <Widget.Title badge={3}>Living Room</Widget.Title>
+ * ```
+ */
+import type { JSX } from "solid-js";
+export interface WidgetTitleProps {
+    /** Optional badge count */
+    badge?: number;
+    /** Additional CSS classes */
+    class?: string;
+    /** Title text */
+    children: JSX.Element;
+}
+/**
+ * Widget title component with auto-responsive typography
+ * Positioned above other content with proper z-index
+ */
+export declare function WidgetTitle(props: WidgetTitleProps): JSX.Element;

package/dist/framework/components/WidgetValue.d.ts

@@ -0,0 +1,31 @@
+/**
+ * WidgetValue Component
+ *
+ * Numeric value display with optional unit and semantic interpretation.
+ *
+ * @example
+ * ```tsx
+ * <Widget.Value value={22} unit="C" />
+ * ```
+ *
+ * @example With interpretation
+ * ```tsx
+ * <Widget.Value value={22} unit="C" interpret />
+ * // Displays: "22C Warm"
+ * ```
+ */
+import type { JSX } from "solid-js";
+export interface WidgetValueProps {
+    /** The value to display */
+    value: number | string;
+    /** Unit of measurement */
+    unit?: string;
+    /** Show semantic interpretation */
+    interpret?: boolean;
+    /** Additional CSS classes */
+    class?: string;
+}
+/**
+ * Widget value component with auto-formatting and interpretation
+ */
+export declare function WidgetValue(props: WidgetValueProps): JSX.Element;

package/dist/framework/core/Widget.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Widget - Main Container Component
+ *
+ * The primary container for all widgets. Provides context, gesture handling,
+ * and base styling.
+ *
+ * @example Simple widget
+ * ```tsx
+ * <Widget gestures={{ tap: handleTap }}>
+ *   <Widget.Icon icon={<Power />} />
+ *   <Widget.Title>{title}</Widget.Title>
+ * </Widget>
+ * ```
+ *
+ * @example With gradient and loading
+ * ```tsx
+ * <Widget gradient="bg-gradient-to-br from-blue-500/40 to-blue-700/40" loading={isLoading}>
+ *   {children}
+ * </Widget>
+ * ```
+ */
+import { type JSX } from "solid-js";
+import type { WidgetSliderFill as WidgetSliderFillType } from "../backgrounds/WidgetSliderFill";
+import type { WidgetContent as WidgetContentType } from "../components/WidgetContent";
+import type { WidgetEmptyState as WidgetEmptyStateType } from "../components/WidgetEmptyState";
+import type { WidgetIcon as WidgetIconType } from "../components/WidgetIcon";
+import type { WidgetMetrics as WidgetMetricsType } from "../components/WidgetMetrics";
+import type { WidgetStatus as WidgetStatusType } from "../components/WidgetStatus";
+import type { WidgetSubtitle as WidgetSubtitleType } from "../components/WidgetSubtitle";
+import type { WidgetTitle as WidgetTitleType } from "../components/WidgetTitle";
+import type { WidgetValue as WidgetValueType } from "../components/WidgetValue";
+import type { WidgetOrientation, WidgetSize, WidgetVariantConfig } from "../types";
+export interface WidgetEmptyStateConfig {
+    /** Icon to display */
+    icon?: JSX.Element;
+    /** Main title/heading */
+    title?: string;
+    /** Descriptive message */
+    message?: string;
+}
+export interface WidgetProps {
+    /** Widget variant (string ID or inline config) */
+    variant?: string | WidgetVariantConfig;
+    /** Gradient background (Tailwind classes like "bg-gradient-to-br from-cyan-600/40 to-blue-700/40") */
+    gradient?: string;
+    /** Show loading overlay */
+    loading?: boolean;
+    /** Background glow color (Tailwind color like "bg-blue-500") (runtime override) */
+    backgroundGlow?: string;
+    /** Additional CSS classes */
+    class?: string;
+    /** Is edit mode (disables gestures) */
+    isEditMode?: boolean;
+    /** Called when delete button is clicked (only shown in edit mode) */
+    onDelete?: () => void;
+    /** Empty state configuration - when provided, shows empty state and applies gray gradient */
+    emptyState?: WidgetEmptyStateConfig;
+    /** Child elements */
+    children?: JSX.Element;
+}
+export interface WidgetComponent {
+    (props: WidgetProps): JSX.Element;
+    Content: typeof WidgetContentType;
+    Icon: typeof WidgetIconType;
+    Title: typeof WidgetTitleType;
+    Subtitle: typeof WidgetSubtitleType;
+    Status: typeof WidgetStatusType;
+    Value: typeof WidgetValueType;
+    Metrics: typeof WidgetMetricsType;
+    EmptyState: typeof WidgetEmptyStateType;
+    SliderFill: typeof WidgetSliderFillType;
+}
+/**
+ * Classify widget size based on grid dimensions
+ */
+export declare function classifySize(gridWidth: number, gridHeight: number): WidgetSize;
+/**
+ * Detect orientation from dimensions based on aspect ratio
+ * Used for gesture direction (slide horizontal vs vertical)
+ */
+export declare function detectOrientation(width: number, height: number): WidgetOrientation;
+/**
+ * Detect content layout direction
+ * Used for UI arrangement (stack vertically vs horizontally)
+ * Considers height threshold - tall widgets benefit from vertical stacking
+ */
+export declare function detectContentLayout(width: number, height: number): WidgetOrientation;
+export declare const Widget: WidgetComponent;

package/dist/framework/design-system/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Design System - Barrel Export
+ *
+ * Responsive design tokens for widget sizing, typography, and layering.
+ */
+export { getSpacingClass, spacing } from "./spacing";
+export { typography } from "./typography";
+export { WIDGET_Z, type WidgetZIndex } from "./z-index";

package/dist/framework/design-system/spacing.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Spacing System
+ *
+ * Provides responsive spacing that adapts to widget size.
+ *
+ * @example
+ * ```tsx
+ * const { size } = useWidgetContext();
+ *
+ * <div style={{ "margin-top": spacing.iconToTitle(size) }}>
+ *   <Widget.Title>{title}</Widget.Title>
+ * </div>
+ * ```
+ */
+import type { SpacingScale, WidgetSize } from "../types";
+/**
+ * Get spacing value based on widget size
+ */
+export declare const spacing: {
+    /** Extra small spacing (4-8px) */
+    S1: (size: WidgetSize) => string;
+    /** Small spacing (6-14px) - default for most layouts */
+    S2: (size: WidgetSize) => string;
+    /** Medium spacing (8-16px) */
+    S3: (size: WidgetSize) => string;
+    /** Large spacing (12-20px) */
+    S4: (size: WidgetSize) => string;
+    /** Icon container size in pixels */
+    icon: (size: WidgetSize) => number;
+    /** Icon stroke size for lucide icons */
+    iconSize: (size: WidgetSize) => number;
+    /** Spacing between icon and title */
+    iconToTitle: (size: WidgetSize) => string;
+    /** Container padding */
+    container: (size: WidgetSize) => string;
+};
+/**
+ * Get Tailwind spacing class name for layout components
+ */
+export declare function getSpacingClass(scale: SpacingScale, size: WidgetSize): string;

package/dist/framework/design-system/typography.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Typography System
+ *
+ * Provides responsive typography classes that adapt to widget size.
+ *
+ * @example
+ * ```tsx
+ * const { size } = useWidgetContext();
+ *
+ * <h3 class={cn("font-bold text-white", typography.title(size))}>
+ *   {title}
+ * </h3>
+ * ```
+ */
+import type { WidgetSize } from "../types";
+/**
+ * Typography utilities based on current widget patterns
+ * Matches existing container query breakpoints from LockWidget:
+ * - text-sm @[300px]:text-base @[400px]:text-lg
+ */
+export declare const typography: {
+    /** Container base text sizing */
+    container: (size: WidgetSize) => string;
+    /** Title text sizing (main heading) */
+    title: (size: WidgetSize) => string;
+    /** Subtitle/secondary text sizing */
+    subtitle: (size: WidgetSize) => string;
+    /** Value display text sizing (large numbers) */
+    value: (size: WidgetSize) => string;
+    /** Badge text sizing (entity count badges) */
+    badge: (size: WidgetSize) => string;
+    /** Metric label text sizing */
+    metricLabel: (size: WidgetSize) => string;
+    /** Metric value text sizing */
+    metricValue: (size: WidgetSize) => string;
+    /** Status text (same as subtitle but semantic) */
+    status: (size: WidgetSize) => string;
+    /** Empty state message text */
+    emptyState: (size: WidgetSize) => string;
+};

package/dist/framework/design-system/z-index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Z-Index Constants
+ *
+ * Provides consistent z-index layering for widget elements.
+ *
+ * @example
+ * ```tsx
+ * <div style={{ "z-index": WIDGET_Z.BACKGROUND }}>
+ *   <CustomBackground />
+ * </div>
+ * ```
+ */
+export declare const WIDGET_Z: {
+    /** Background layer (gradients, images, glows) */
+    readonly BACKGROUND: 0;
+    /** Main content layer (icon, title, text) */
+    readonly CONTENT: 10;
+    /** Overlay layer (loading states, volume indicators) */
+    readonly OVERLAY: 20;
+    /** Action layer (buttons, edit controls) */
+    readonly ACTIONS: 30;
+};
+export type WidgetZIndex = (typeof WIDGET_Z)[keyof typeof WIDGET_Z];