@glasshome/widget-sdk 0.1.0

package/dist/framework/theming/adaptive-color.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Adaptive Color Utilities
+ *
+ * Derives icon background and glow colors from a dynamic CSS color (rgb, hsl, hex).
+ * Used by widgets like lights where the color changes at runtime based on entity state.
+ */
+/**
+ * Adaptive icon colors derived from a dynamic CSS color.
+ */
+export interface AdaptiveIconColors {
+    /** Icon container background — contrasts against the widget fill */
+    background: string;
+    /** Box-shadow glow color */
+    glow: string;
+}
+/**
+ * Derive icon background and glow from a CSS color string.
+ *
+ * Strategy:
+ * - The widget fill is typically the color at ~30% opacity, so the perceived
+ *   background sits around 15-25% lightness on a dark dashboard.
+ * - For the icon container we want a darker, richer version of the color that
+ *   "pops" against that fill. We clamp lightness to a low range and boost
+ *   saturation slightly so it reads as a tinted dark square.
+ * - For very dark colors (e.g. deep blues) we lift lightness a bit instead.
+ * - The glow uses the original color at moderate opacity.
+ */
+export declare function deriveAdaptiveIconColors(cssColor: string): AdaptiveIconColors | null;

package/dist/framework/theming/colors.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Gradient preset type
+ */
+export type GradientPreset = "ocean" | "sunset" | "forest" | "lavender" | "golden" | "midnight" | "rose" | "mint" | "slate" | "coral" | "aurora" | "ember" | "steel" | "twilight" | "sage" | "copper" | "dusk";
+/**
+ * 17 gradient presets as Tailwind class strings
+ * Using 20% opacity for subtle background that doesn't overpower content
+ */
+export declare const GRADIENT_PRESETS: Record<GradientPreset, string>;
+/** Human-readable gradient names for UI display */
+export declare const GRADIENT_NAMES: Record<GradientPreset, string>;
+/** Array of all gradient preset keys */
+export declare const GRADIENT_PRESET_KEYS: GradientPreset[];
+/**
+ * Get a consistent gradient preset for any string input
+ * Uses a simple hash to deterministically select a gradient
+ */
+export declare function getGradientFromString(input: string): GradientPreset;
+/**
+ * Get gradient string
+ * @param gradient - Preset name or gradient string
+ * @param fallbackString - String to hash for default gradient selection
+ */
+export declare function getGradient(gradient: GradientPreset | string | undefined, fallbackString: string): string;
+/**
+ * Widget color preset with gradient, icon, glow, and text colors
+ */
+export interface WidgetColorPreset {
+    /** Gradient string (Tailwind classes) */
+    gradient: string;
+    /** Simple background color for pills/badges (Tailwind class) */
+    bg: string;
+    /** Icon background with dark: classes */
+    icon: string;
+    /** Glow/shadow with dark: classes */
+    glow: string | undefined;
+    /** Text colors */
+    text: {
+        primary: string;
+        muted: string;
+    };
+}
+/**
+ * Map gradient presets to full color presets
+ * Each preset includes gradient, icon, glow, and text colors
+ */
+export declare const gradientColorPresets: Record<GradientPreset, WidgetColorPreset>;
+/**
+ * Shared color palette for entity states
+ * Uses gradient presets for consistency
+ */
+export declare const stateColors: {
+    readonly unavailable: WidgetColorPreset;
+    readonly active: WidgetColorPreset;
+    readonly inactive: WidgetColorPreset;
+    readonly success: WidgetColorPreset;
+    readonly warning: WidgetColorPreset;
+    readonly error: WidgetColorPreset;
+};

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

@@ -0,0 +1,8 @@
+/**
+ * Widget Theming - Shared Colors
+ *
+ * Simple color palette for entity states.
+ * Widgets can use these or define their own logic.
+ */
+export { type AdaptiveIconColors, deriveAdaptiveIconColors } from "./adaptive-color";
+export { GRADIENT_NAMES, GRADIENT_PRESET_KEYS, GRADIENT_PRESETS, type GradientPreset, getGradient, getGradientFromString, gradientColorPresets, stateColors, type WidgetColorPreset, } from "./colors";

package/dist/framework/types.d.ts

@@ -0,0 +1,335 @@
+/** Core type definitions for the Widget Framework. */
+import type { JSX } from "solid-js";
+/**
+ * Widget size classification based on grid dimensions
+ * - xs: Small widgets (1x1, 1x2)
+ * - sm: Medium-small widgets (2x1, 2x2)
+ * - md: Medium widgets (2x3, 2x4)
+ * - lg: Large widgets (2x6, 3x6, 4x2)
+ * - xl: Extra large widgets (4x4)
+ */
+export type WidgetSize = "xs" | "sm" | "md" | "lg" | "xl";
+/**
+ * Widget orientation based on aspect ratio
+ * - horizontal: width > height
+ * - vertical: height > width
+ * - square: width === height
+ */
+export type WidgetOrientation = "horizontal" | "vertical" | "square";
+/**
+ * Widget dimensions in both pixels and grid units
+ */
+export interface WidgetDimensions {
+    /** Pixel width */
+    width: number;
+    /** Pixel height */
+    height: number;
+    /** Grid columns (1-4) */
+    gridWidth: number;
+    /** Grid rows (1-6) */
+    gridHeight: number;
+}
+/**
+ * Widget context provided to all child components.
+ * Values are plain (not accessors) -- the context provider
+ * will supply reactive accessors wrapping these.
+ */
+export interface WidgetContextValue {
+    /** Widget size classification */
+    size: WidgetSize;
+    /** Widget orientation (for gestures - pure aspect ratio) */
+    orientation: WidgetOrientation;
+    /** Content layout direction (for UI arrangement - considers height) */
+    contentLayout: WidgetOrientation;
+    /** Widget dimensions */
+    dimensions: WidgetDimensions;
+    /** Whether widget is in edit mode */
+    isEditMode: boolean;
+}
+/**
+ * Gradient configuration
+ */
+export interface GradientConfig {
+    /** Tailwind gradient from class (e.g., "from-blue-500") */
+    from: string;
+    /** Tailwind gradient to class (e.g., "to-blue-700") */
+    to: string;
+}
+/**
+ * Slide gesture configuration
+ */
+export interface SlideGestureConfig {
+    /** Current value */
+    value: number;
+    /** Value change handler */
+    onChange: (value: number) => void;
+    /** Minimum value (default: 0) */
+    min?: number;
+    /** Maximum value (default: 100) */
+    max?: number;
+    /** Slide orientation (default: "auto" - detects from widget orientation) */
+    orientation?: "auto" | "horizontal" | "vertical";
+    /** Delay before slide activates in ms (prevents scroll conflicts, default: 0) */
+    activationDelay?: number;
+}
+/**
+ * Hold gesture configuration
+ */
+export interface HoldGestureConfig {
+    /** Action to perform on hold */
+    action: () => void;
+    /** Hold delay in ms (default: 300) */
+    delay?: number;
+}
+/**
+ * Combined gesture configuration
+ */
+export interface GestureConfig {
+    /** Simple tap handler */
+    tap?: () => void;
+    /** Hold gesture configuration */
+    hold?: HoldGestureConfig;
+    /** Slide gesture configuration */
+    slide?: SlideGestureConfig;
+}
+/**
+ * Spacing scale
+ */
+export type SpacingScale = "S1" | "S2" | "S3" | "S4";
+/**
+ * Color variants for common components
+ */
+export type ColorVariant = "blue" | "green" | "red" | "yellow" | "purple" | "gray" | string;
+/**
+ * Image overlay types
+ */
+export type ImageOverlay = "gradient" | "dark" | "none";
+/**
+ * Base props that all framework components accept
+ */
+export interface BaseComponentProps {
+    /** Additional CSS classes (SolidJS uses `class` instead of `className`) */
+    class?: string;
+    /** Child elements */
+    children?: JSX.Element;
+}
+/**
+ * CSS variable-based styling configuration
+ * Replaces brittle Tailwind class strings with type-safe CSS variables
+ */
+export interface WidgetStyles {
+    /** Inline CSS properties applied to widget container */
+    container?: JSX.CSSProperties;
+    /** Tailwind utility classes (for simple styling) */
+    class?: string;
+    /** CSS custom properties for themeable values */
+    cssVars?: Record<`--widget-${string}`, string | number>;
+}
+/**
+ * Flex layout strategy with type-safe configuration
+ */
+export interface FlexLayoutStrategy {
+    type: "flex";
+    /** Flex direction */
+    direction: "row" | "column" | "row-reverse" | "column-reverse";
+    /** Align items */
+    align: "start" | "center" | "end" | "stretch";
+    /** Justify content */
+    justify: "start" | "center" | "end" | "between" | "around";
+    /** Flex wrap */
+    wrap?: boolean;
+    /** Gap between items (CSS value) */
+    gap?: string;
+    /** Custom order for specific elements */
+    order?: Partial<Record<WidgetElement, number>>;
+}
+/**
+ * Grid layout strategy with type-safe configuration
+ */
+export interface GridLayoutStrategy {
+    type: "grid";
+    /** Grid template areas string */
+    areas: string;
+    /** Grid template columns */
+    columns?: string;
+    /** Grid template rows */
+    rows?: string;
+    /** Gap between items (CSS value) */
+    gap?: string;
+    /** Grid area assignments for elements */
+    elementAreas: Partial<Record<WidgetElement, string>>;
+}
+/**
+ * Absolute positioning strategy with type-safe configuration
+ */
+export interface AbsoluteLayoutStrategy {
+    type: "absolute";
+    /** Position configurations for specific elements */
+    positions: Partial<Record<WidgetElement, PositionConfig>>;
+}
+/**
+ * Custom layout strategy (escape hatch)
+ */
+export interface CustomLayoutStrategy {
+    type: "custom";
+    /** Custom render function or component */
+    renderer: string;
+}
+/**
+ * Discriminated union of all layout strategies
+ * Ensures type safety - can't use gridArea with flex, etc.
+ */
+export type LayoutStrategy = FlexLayoutStrategy | GridLayoutStrategy | AbsoluteLayoutStrategy | CustomLayoutStrategy;
+/**
+ * Position configuration for absolute layout
+ */
+export interface PositionConfig {
+    top?: string;
+    right?: string;
+    bottom?: string;
+    left?: string;
+    transform?: string;
+}
+/**
+ * Widget element identifiers for layout configuration
+ */
+export type WidgetElement = "icon" | "title" | "subtitle" | "status" | "value" | "metrics" | "content" | "background" | "overlay" | "decorations";
+/**
+ * Element-specific configuration
+ */
+export interface ElementConfig {
+    /** Show/hide specific elements */
+    visible?: Partial<Record<WidgetElement, boolean>>;
+    /** Element-specific styling */
+    styles?: Partial<Record<WidgetElement, JSX.CSSProperties>>;
+    /** Element-specific CSS classes */
+    classNames?: Partial<Record<WidgetElement, string>>;
+}
+/**
+ * Plugin system configuration (serializable)
+ * Uses string IDs instead of JSX.Element for serializability
+ */
+export interface VariantPlugins {
+    /** Background plugin ID */
+    background?: string;
+    /** Overlay plugin ID */
+    overlay?: string;
+    /** Decoration plugin IDs */
+    decorations?: string[];
+}
+/**
+ * Interaction configuration
+ */
+export interface InteractionConfig {
+    /** Enable hover effects */
+    hover?: boolean;
+    /** Enable active/pressed state */
+    active?: boolean;
+    /** Enable focus ring */
+    focus?: boolean;
+    /** Custom hover scale (e.g., 1.02) */
+    hoverScale?: number;
+    /** Custom active scale (e.g., 0.98) */
+    activeScale?: number;
+}
+/**
+ * Complete variant configuration
+ * This is the core of the variant system
+ */
+export interface WidgetVariantConfig {
+    /** Unique variant identifier */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Description of variant purpose/style */
+    description?: string;
+    /** Styling configuration */
+    styles?: WidgetStyles;
+    /** Layout strategy */
+    layout?: LayoutStrategy;
+    /** Element-specific configuration */
+    elements?: ElementConfig;
+    /** Plugin configurations */
+    plugins?: VariantPlugins;
+    /** Interaction behavior */
+    interactions?: InteractionConfig;
+    /** Base variant to extend (enables composition) */
+    extends?: string;
+}
+/**
+ * Variant type union (built-in + custom)
+ */
+export type WidgetVariant = "classic-glass" | "minimal" | "compact-horizontal" | (string & {});
+/**
+ * Variant registry type
+ */
+export type VariantRegistry = Record<string, WidgetVariantConfig>;
+/** Unique entity identifier (e.g., "light.living_room") */
+export type EntityId = string;
+/** Entity domain (e.g., "light", "sensor", "switch") */
+export type EntityDomain = string;
+/** Area identifier */
+export type AreaId = string;
+/** Device identifier */
+export type DeviceId = string;
+/** Label identifier */
+export type LabelId = string;
+/** Entity category for filtering */
+export type EntityCategory = "config" | "diagnostic" | null;
+/**
+ * Full entity view interface representing a Home Assistant entity.
+ * This is the canonical type used by SDK framework utils and widgets.
+ * sync-layer produces EntityView objects; widgets consume them.
+ */
+export interface EntityView {
+    /** Unique entity identifier (e.g., "light.living_room") */
+    id: EntityId;
+    /** Entity domain (e.g., "light", "sensor") */
+    domain: EntityDomain;
+    /** Current state value */
+    state: string;
+    /** Entity attributes */
+    attributes: Record<string, any>;
+    /** When the state last changed */
+    lastChanged: Date;
+    /** When the state was last updated (even if unchanged) */
+    lastUpdated: Date;
+    /** Context of the last state change */
+    context: {
+        id: string;
+        parentId: string | null;
+        userId: string | null;
+    };
+    /** Internal entity name (object_id) */
+    name: string;
+    /** Friendly display name */
+    friendlyName: string;
+    /** Area this entity belongs to */
+    areaId: AreaId | null;
+    /** Device this entity belongs to */
+    deviceId: DeviceId | null;
+    /** Integration platform (e.g., "hue", "zwave") */
+    platform: string;
+    /** Unique ID from the integration */
+    uniqueId: string | null;
+    /** Whether the entity is disabled */
+    isDisabled: boolean;
+    /** Whether the entity is hidden from the UI */
+    isHidden: boolean;
+    /** Icon identifier (e.g., "mdi:lightbulb") */
+    icon: string | null;
+    /** Source of the icon */
+    iconSource: "registry" | "attribute" | "default";
+    /** Entity category for filtering */
+    entityCategory: EntityCategory;
+    /** Labels assigned to this entity */
+    labels: LabelId[];
+    /** User-defined aliases */
+    aliases: string[];
+    /** Device class (e.g., "temperature", "motion") */
+    deviceClass?: string | null;
+    /** Unit of measurement (for sensors) */
+    unitOfMeasurement?: string | null;
+    /** Bitmask of supported features */
+    supportedFeatures?: number;
+}

package/dist/framework/utils/cn.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Class Name Utility
+ *
+ * Combines clsx and tailwind-merge for conditional class management.
+ * This is a pure function of its inputs -- it does no internal caching.
+ *
+ * **Memoization guidance for callers:** In hot render paths where inputs
+ * change frequently (e.g., reactive signals driving class names), wrap
+ * the call in `createMemo` to avoid redundant `twMerge` computation:
+ *
+ * ```tsx
+ * const classes = createMemo(() => cn("base", dynamicSignal()));
+ * ```
+ *
+ * In static JSX expressions with constant strings, no memoization is needed
+ * since Solid's fine-grained reactivity only re-evaluates when dependencies change.
+ *
+ * @example
+ * ```tsx
+ * <div class={cn(
+ *   "base-class",
+ *   condition && "conditional-class",
+ *   customClass
+ * )}>
+ * ```
+ */
+import { type ClassValue } from "clsx";
+export declare function cn(...inputs: ClassValue[]): string;

package/dist/framework/utils/empty-state.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Empty State Utilities
+ *
+ * Helper functions for creating consistent empty state configurations across widgets.
+ */
+import type { JSX } from "solid-js";
+/**
+ * Empty state configuration for a widget
+ */
+export interface WidgetEmptyStateConfig {
+    /** Icon to display */
+    icon: JSX.Element;
+    /** Main title/heading */
+    title: string;
+    /** Descriptive message */
+    message: string;
+}
+export interface EmptyStateConfigOptions {
+    /** Icon to display */
+    icon: JSX.Element;
+    /** Main title/heading */
+    title: string;
+    /** Descriptive message (optional - uses default template if not provided) */
+    message?: string;
+    /** Entity type for default message template (e.g., "a light", "a lock") */
+    entityType?: string;
+}
+/**
+ * Creates a consistent empty state configuration for widgets
+ *
+ * @example
+ * ```typescript
+ * // Custom message
+ * const config = createEmptyStateConfig({
+ *   icon: <Thermometer />,
+ *   title: "No climate entity",
+ *   message: "Configure this widget to add a climate device",
+ * });
+ *
+ * // Default message template
+ * const config = createEmptyStateConfig({
+ *   icon: <Lock />,
+ *   title: "No lock entity",
+ *   entityType: "a lock",
+ * });
+ * // Result: message = "Configure this widget to add a lock"
+ * ```
+ */
+export declare function createEmptyStateConfig(options: EmptyStateConfigOptions): WidgetEmptyStateConfig;

package/dist/framework/utils/entity-aggregation.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Entity Aggregation Utilities
+ *
+ * Generic entity aggregation patterns for multi-entity widgets.
+ * These utilities aggregate state across multiple entities to produce
+ * a single representative state for the group.
+ */
+import type { EntityView } from "../types";
+/**
+ * Sensor group calculation modes
+ */
+export type SensorGroupType = "min" | "max" | "mean" | "median" | "sum" | "last" | "range" | "product" | "std_dev";
+/**
+ * Light/switch/binary-sensor group aggregation result
+ */
+export interface LightGroupResult {
+    /** Is this a group or single entity */
+    isGroup: boolean;
+    /** Collective state */
+    state: string;
+    /** Is on */
+    isOn: boolean;
+    /** Is unavailable */
+    isUnavailable: boolean;
+    /** Average brightness (0-255) */
+    brightness: number;
+    /** Brightness percentage (0-100) */
+    brightnessPercent: number;
+    /** RGB color for display */
+    color: string;
+    /** Number of entities on */
+    onCount: number;
+    /** Total entities */
+    totalCount: number;
+    /** Human readable description */
+    description: string;
+}
+/**
+ * Sensor group aggregation result
+ */
+export interface SensorGroupResult {
+    /** Is this a group or single entity */
+    isGroup: boolean;
+    /** Collective state/value */
+    state: string;
+    /** Numeric value (if applicable) */
+    numericValue: number | null;
+    /** Is unavailable */
+    isUnavailable: boolean;
+    /** Unit of measurement */
+    unit?: string;
+    /** Human readable description */
+    description: string;
+    /** All member values (for debugging/display) */
+    memberValues?: Array<{
+        entityId: string;
+        value: string | number;
+        friendly_name?: string;
+    }>;
+}
+/**
+ * Calculate light/switch/binary-sensor group state and properties
+ *
+ * Works for any binary state entities (lights, switches, binary sensors)
+ * Aggregates on/off state, brightness (if applicable), and color.
+ */
+export declare function calculateLightGroup(entities: EntityView[], allEntitiesMode?: boolean): LightGroupResult;
+/**
+ * Calculate sensor group state and value
+ *
+ * Aggregates numeric sensor values using various calculation modes.
+ */
+export declare function calculateSensorGroup(entities: EntityView[], groupType?: SensorGroupType, ignoreNonNumeric?: boolean): SensorGroupResult;

package/dist/framework/utils/entity-state.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Entity State Utilities
+ *
+ * Common entity state calculations that widgets repeatedly implement.
+ * These utilities provide domain-agnostic state checking and counting.
+ *
+ * For aggregation of multiple entities, see entity-aggregation.ts utilities
+ * (calculateLightGroup, calculateSensorGroup).
+ */
+import type { EntityView } from "../types";
+/**
+ * Check if entity is available (not unavailable/unknown)
+ *
+ * @example
+ * ```typescript
+ * const isAvailable = isEntityAvailable(entity);
+ * if (isAvailable) {
+ *   // Entity is available, can display state
+ * }
+ * ```
+ */
+export declare function isEntityAvailable(entity: EntityView | null | undefined): boolean;
+/**
+ * Check if entity is active (on, open, locked, etc.)
+ * Domain-aware state checking
+ *
+ * @example
+ * ```typescript
+ * const isActive = isEntityActive(entity);
+ * const statusColor = isActive ? "green" : "gray";
+ * ```
+ */
+export declare function isEntityActive(entity: EntityView | null | undefined): boolean;
+/**
+ * Get entity state with fallback
+ *
+ * @example
+ * ```typescript
+ * const state = getEntityState(entity, "unknown");
+ * return <Widget.Status>{state}</Widget.Status>;
+ * ```
+ */
+export declare function getEntityState(entity: EntityView | null | undefined, fallback?: string): string;
+/**
+ * Get entity attribute with type safety
+ *
+ * @example
+ * ```typescript
+ * const brightness = getEntityAttribute<number>(entity, "brightness", 0);
+ * const temperature = getEntityAttribute<number>(entity, "current_temperature");
+ * ```
+ */
+export declare function getEntityAttribute<T = unknown>(entity: EntityView | null | undefined, attributeName: string, fallback?: T): T | undefined;
+/**
+ * Count entities by state
+ *
+ * @example
+ * ```typescript
+ * const onCount = countEntitiesByState(entities, "on");
+ * return <Widget.Status>{onCount} lights on</Widget.Status>;
+ * ```
+ */
+export declare function countEntitiesByState(entities: EntityView[], state: string): number;
+/**
+ * Count available entities (excludes unavailable/unknown)
+ *
+ * @example
+ * ```typescript
+ * const availableCount = countAvailableEntities(entities);
+ * const unavailableCount = entities.length - availableCount;
+ * ```
+ */
+export declare function countAvailableEntities(entities: EntityView[]): number;
+/**
+ * Count active entities (on, open, etc.)
+ *
+ * @example
+ * ```typescript
+ * const activeCount = countActiveEntities(entities);
+ * return <Widget.Status>{activeCount} active</Widget.Status>;
+ * ```
+ */
+export declare function countActiveEntities(entities: EntityView[]): number;
+/**
+ * Check if all entities match state
+ *
+ * @example
+ * ```typescript
+ * const allOn = allEntitiesInState(entities, "on");
+ * const statusText = allOn ? "All on" : "Mixed";
+ * ```
+ */
+export declare function allEntitiesInState(entities: EntityView[], state: string): boolean;
+/**
+ * Check if any entity matches state
+ *
+ * @example
+ * ```typescript
+ * const anyOpen = anyEntityInState(entities, "open");
+ * const iconColor = anyOpen ? "red" : "green";
+ * ```
+ */
+export declare function anyEntityInState(entities: EntityView[], state: string): boolean;