npm - @glasshome/widget-sdk - Versions diffs - 0.3.7 → 0.4.1 - Mend

@glasshome/widget-sdk 0.3.7 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (36) hide show

package/README.md +18 -0
package/dist/framework/backgrounds/WidgetSliderFill.d.ts +24 -13
package/dist/framework/components/WidgetContent.d.ts +2 -1
package/dist/framework/components/WidgetIcon.d.ts +22 -24
package/dist/framework/components/WidgetStatus.d.ts +2 -1
package/dist/framework/components/WidgetTitle.d.ts +2 -1
package/dist/framework/components/WidgetValue.d.ts +2 -1
package/dist/framework/core/Widget.d.ts +30 -31
package/dist/framework/gestures/cursors.d.ts +2 -1
package/dist/framework/hooks/index.d.ts +2 -9
package/dist/framework/hooks/use-widget-context.d.ts +0 -5
package/dist/framework/index.d.ts +4 -16
package/dist/framework/theming/index.d.ts +4 -5
package/dist/framework/theming/tokens.d.ts +24 -0
package/dist/framework/theming/tone.d.ts +10 -0
package/dist/framework/types.d.ts +0 -67
package/dist/framework/utils/entity-state.d.ts +0 -62
package/dist/framework/utils/index.d.ts +5 -5
package/dist/index.d.ts +2 -4
package/dist/index.js +820 -1479
package/dist/theme.d.ts +0 -12
package/package.json +1 -2
package/dist/create-entity.d.ts +0 -22
package/dist/framework/backgrounds/Glow.d.ts +0 -24
package/dist/framework/components/WidgetEmptyState.d.ts +0 -34
package/dist/framework/components/WidgetMetrics.d.ts +0 -47
package/dist/framework/components/WidgetSubtitle.d.ts +0 -28
package/dist/framework/design-system/index.d.ts +0 -8
package/dist/framework/hooks/use-debug-data.d.ts +0 -46
package/dist/framework/hooks/use-widget-config.d.ts +0 -48
package/dist/framework/hooks/use-widget-entity.d.ts +0 -53
package/dist/framework/hooks/use-widget-form.d.ts +0 -79
package/dist/framework/hooks/use-widget-responsive.d.ts +0 -41
package/dist/framework/layout/WidgetStack.d.ts +0 -28
package/dist/framework/theming/adaptive-color.d.ts +0 -28
package/dist/framework/theming/colors.d.ts +0 -59

package/dist/theme.d.ts CHANGED Viewed

@@ -1,19 +1,7 @@
 /**
  * Theme utilities — plain DOM reads.
  * Framework-agnostic: no SolidJS imports.
- *
- * These functions read CSS custom properties and class state from the
- * document root. They are synchronous and work in any browser environment.
  */
-/**
- * Read a CSS custom property (theme token) from the document root.
- * Automatically prepends "--" if not already present.
- *
- * @example
- * getThemeToken("color-primary")  // reads --color-primary
- * getThemeToken("--color-primary") // also works
- */
-export declare function getThemeToken(name: string): string;
 /**
  * Check whether the current theme is dark mode.
  * Reads the presence of the "dark" class on <html>.

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@glasshome/widget-sdk",
-  "version": "0.3.7",
+  "version": "0.4.1",
   "description": "SDK for building GlassHome dashboard widgets with SolidJS",
   "keywords": [
     "glasshome",
@@ -59,7 +59,6 @@
     "@types/node": "^25.2.2",
     "typescript": "^5",
     "vite": "^7.3.1",
-    "vite-plugin-externalize-deps": "^0.8.0",
     "vite-plugin-solid": "^2.11.10"
   },
   "repository": {

package/dist/create-entity.d.ts DELETED Viewed

@@ -1,22 +0,0 @@
-/**
- * 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/framework/backgrounds/Glow.d.ts DELETED Viewed

@@ -1,24 +0,0 @@
-/**
- * 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/components/WidgetEmptyState.d.ts DELETED Viewed

@@ -1,34 +0,0 @@
-/**
- * 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/WidgetMetrics.d.ts DELETED Viewed

@@ -1,47 +0,0 @@
-/**
- * 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/WidgetSubtitle.d.ts DELETED Viewed

@@ -1,28 +0,0 @@
-/**
- * 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/design-system/index.d.ts DELETED Viewed

@@ -1,8 +0,0 @@
-/**
- * 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/hooks/use-debug-data.d.ts DELETED Viewed

@@ -1,46 +0,0 @@
-/**
- * Debug Data Hook
- *
- * Generates standardized debug data structure for widget dialogs.
- * Provides a consistent format for troubleshooting widget configuration and entity state.
- *
- * @example
- * ```tsx
- * const debugData = useDebugData({
- *   widgetConfig: {
- *     id: config.id,
- *     type: config.type,
- *     title: config.title,
- *     entityIds: config.entityIds,
- *   },
- *   entities: () => coverEntities,
- *   customEntityFields: (entity) => ({
- *     current_position: entity.attributes?.current_position,
- *   }),
- * });
- * ```
- */
-import { type Accessor } from "solid-js";
-import type { EntityView } from "../types";
-export interface UseDebugDataOptions {
-    /** Widget configuration summary */
-    widgetConfig: {
-        id: string;
-        type: string;
-        title?: string;
-        entityIds?: string[];
-    };
-    /** Reactive entities accessor */
-    entities: Accessor<EntityView[]>;
-    /** Additional data to include in debug output */
-    additionalData?: Record<string, unknown>;
-    /** Custom entity fields to include per entity */
-    customEntityFields?: (entity: EntityView) => Record<string, unknown>;
-}
-/**
- * Hook for generating standardized debug data structure
- *
- * @param options - Debug data configuration
- * @returns Reactive debug data object or undefined if no entities
- */
-export declare function useDebugData(options: UseDebugDataOptions): Accessor<Record<string, unknown> | undefined>;

package/dist/framework/hooks/use-widget-config.d.ts DELETED Viewed

@@ -1,48 +0,0 @@
-/**
- * Widget Config Hook
- *
- * Generalized config management that accepts save/delete callbacks.
- * Host-agnostic: the host application provides the actual persistence logic.
- *
- * @example
- * ```tsx
- * const { save, remove, isSaving, isDeleting } = useWidgetConfig({
- *   onSave: async (config) => {
- *     await api.saveWidgetConfig(widgetId, config);
- *   },
- *   onDelete: async () => {
- *     await api.deleteWidget(widgetId);
- *   },
- * });
- *
- * // In a form submit handler:
- * save({ title: "My Widget", entityIds: ["sensor.temp"] });
- * ```
- */
-export interface UseWidgetConfigOptions<TConfig = Record<string, unknown>> {
-    /** Callback to save widget configuration */
-    onSave?: (config: TConfig) => void | Promise<void>;
-    /** Callback to delete widget */
-    onDelete?: () => void | Promise<void>;
-    /** Callback after successful save */
-    onSaveSuccess?: () => void;
-    /** Callback after successful delete */
-    onDeleteSuccess?: () => void;
-}
-export interface UseWidgetConfigReturn<TConfig = Record<string, unknown>> {
-    /** Save widget configuration */
-    save: (config: TConfig) => Promise<void>;
-    /** Delete widget */
-    remove: () => Promise<void>;
-    /** Whether save is in progress */
-    isSaving: () => boolean;
-    /** Whether delete is in progress */
-    isDeleting: () => boolean;
-}
-/**
- * Hook for managing widget configuration save/delete operations
- *
- * @param options - Configuration with save/delete callbacks
- * @returns Save and delete functions with loading states
- */
-export declare function useWidgetConfig<TConfig = Record<string, unknown>>(options?: UseWidgetConfigOptions<TConfig>): UseWidgetConfigReturn<TConfig>;

package/dist/framework/hooks/use-widget-entity.d.ts DELETED Viewed

@@ -1,53 +0,0 @@
-/**
- * Widget Entity Hook
- *
- * Generalized single-entity data binding that accepts a signal-based data source.
- * The SDK does NOT import sync-layer -- the host provides entity data via Accessor.
- *
- * @example
- * ```tsx
- * // Host provides entity data as a signal
- * const entity = () => syncLayer.getEntity("sensor.temperature");
- *
- * const { data, emptyState, hasEntity } = useWidgetEntity({
- *   entity,
- *   calculateData: (e) => ({
- *     temperature: parseFloat(e.state),
- *     unit: e.unitOfMeasurement ?? "C",
- *   }),
- *   emptyStateConfig: {
- *     icon: <Thermometer />,
- *     title: "No climate entity",
- *     message: "Configure this widget to add a climate device",
- *   },
- * });
- * ```
- */
-import { type Accessor } from "solid-js";
-import type { EntityView } from "../types";
-import type { WidgetEmptyStateConfig } from "../utils/empty-state";
-export interface UseWidgetEntityOptions<TData> {
-    /** Reactive entity accessor (null when not available) */
-    entity: Accessor<EntityView | null>;
-    /** Function to calculate widget-specific data from entity */
-    calculateData: (entity: EntityView) => TData;
-    /** Empty state configuration when entity is not available */
-    emptyStateConfig: WidgetEmptyStateConfig;
-}
-export interface UseWidgetEntityResult<TData> {
-    /** The entity (null if not found) */
-    entity: Accessor<EntityView | null>;
-    /** Calculated widget data (null if no entity) */
-    data: Accessor<TData | null>;
-    /** Empty state config (undefined if entity exists) */
-    emptyState: Accessor<WidgetEmptyStateConfig | undefined>;
-    /** Whether entity exists */
-    hasEntity: Accessor<boolean>;
-}
-/**
- * Hook for single-entity widgets with integrated empty state support
- *
- * @param options - Entity source, data calculation, and empty state config
- * @returns Reactive entity data, empty state, and existence check
- */
-export declare function useWidgetEntity<TData>(options: UseWidgetEntityOptions<TData>): UseWidgetEntityResult<TData>;

package/dist/framework/hooks/use-widget-form.d.ts DELETED Viewed

@@ -1,79 +0,0 @@
-/**
- * Widget Form Hook
- *
- * Wraps @modular-forms/solid with zodForm validation for widget configuration forms.
- * This is the SolidJS equivalent of the React useWidgetForm that used react-hook-form.
- *
- * @example
- * ```tsx
- * import { z } from "zod";
- *
- * const schema = z.object({
- *   title: z.string().optional(),
- *   entityIds: z.array(z.string()).min(1),
- *   showIcon: z.boolean(),
- * });
- *
- * type FormValues = z.infer<typeof schema>;
- *
- * function MyWidgetSettings() {
- *   const { form, Form, Field, isDirty, handleSubmit } = useWidgetForm<FormValues>({
- *     schema,
- *     initialValues: {
- *       title: config.title ?? "",
- *       entityIds: config.entityIds ?? [],
- *       showIcon: true,
- *     },
- *     onSubmit: async (values) => {
- *       await saveConfig(values);
- *     },
- *   });
- *
- *   return (
- *     <Form onSubmit={handleSubmit}>
- *       <Field name="title">
- *         {(field, props) => (
- *           <input {...props} value={field.value} />
- *         )}
- *       </Field>
- *     </Form>
- *   );
- * }
- * ```
- */
-import { type FieldValues, type FormStore, getValue, reset, type SubmitHandler, setValue } from "@modular-forms/solid";
-import type { z } from "zod";
-export interface UseWidgetFormOptions<TValues extends FieldValues> {
-    /** Zod schema for form validation */
-    schema: z.ZodType<TValues, any, any>;
-    /** Initial form values */
-    initialValues: TValues;
-    /** Submit handler */
-    onSubmit?: (values: TValues) => void | Promise<void>;
-}
-export interface UseWidgetFormReturn<TValues extends FieldValues> {
-    /** The form store */
-    form: FormStore<TValues, undefined>;
-    /** Whether form has unsaved changes */
-    isDirty: () => boolean;
-    /** Whether form is currently submitting */
-    isSubmitting: () => boolean;
-    /** Handle form submission */
-    handleSubmit: SubmitHandler<TValues>;
-    /** Get a field value */
-    getValue: typeof getValue;
-    /** Set a field value */
-    setValue: typeof setValue;
-    /** Reset form to initial values */
-    reset: typeof reset;
-}
-/**
- * Hook for widget configuration forms using @modular-forms/solid
- *
- * Callers use the returned form store with `<Form>` and `<Field>` components
- * imported directly from @modular-forms/solid.
- *
- * @param options - Form configuration with schema, initial values, and submit handler
- * @returns Form store, derived state, and utility functions
- */
-export declare function useWidgetForm<TValues extends FieldValues>(options: UseWidgetFormOptions<TValues>): UseWidgetFormReturn<TValues>;

package/dist/framework/hooks/use-widget-responsive.d.ts DELETED Viewed

@@ -1,41 +0,0 @@
-/**
- * Widget Responsive Hook
- *
- * Provides convenience utilities for responsive behavior based on widget size.
- * Uses createMemo for each derived boolean to avoid unnecessary recalculation.
- *
- * @example
- * ```tsx
- * const responsive = useWidgetResponsive();
- *
- * return (
- *   <div>
- *     <Show when={responsive.showDetail()}>
- *       <DetailedMetrics />
- *     </Show>
- *     <Show when={responsive.isCompact()}>
- *       <CompactView />
- *     </Show>
- *   </div>
- * );
- * ```
- */
-import type { WidgetSize } from "../types";
-export interface WidgetResponsiveUtils {
-    /** xs or sm */
-    isCompact: () => boolean;
-    /** lg or xl */
-    isLarge: () => boolean;
-    /** md or larger */
-    showDetail: () => boolean;
-    /** Check if current size matches any of the provided sizes */
-    showOn: (sizes: WidgetSize[]) => boolean;
-    /** Check if current size does NOT match any of the provided sizes */
-    hideOn: (sizes: WidgetSize[]) => boolean;
-    /** Check if a size condition matches (e.g., "md+", "sm-") */
-    matches: (condition: string) => boolean;
-}
-/**
- * Get responsive utilities based on widget context size
- */
-export declare function useWidgetResponsive(): WidgetResponsiveUtils;

package/dist/framework/layout/WidgetStack.d.ts DELETED Viewed

@@ -1,28 +0,0 @@
-/**
- * WidgetStack Component
- *
- * Vertical flex layout with automatic responsive spacing.
- *
- * @example
- * ```tsx
- * <WidgetStack spacing="S2">
- *   <Widget.Icon icon={<Power />} />
- *   <Widget.Title>{title}</Widget.Title>
- *   <Widget.Status>{status}</Widget.Status>
- * </WidgetStack>
- * ```
- */
-import type { JSX } from "solid-js";
-import type { SpacingScale } from "../types";
-export interface WidgetStackProps {
-    /** Spacing between items (default: "S2") */
-    spacing?: SpacingScale;
-    /** Additional CSS classes */
-    class?: string;
-    /** Child elements */
-    children: JSX.Element;
-}
-/**
- * Vertical stack layout with responsive spacing
- */
-export declare function WidgetStack(props: WidgetStackProps): JSX.Element;

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

@@ -1,28 +0,0 @@
-/**
- * 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 DELETED Viewed

@@ -1,59 +0,0 @@
-/**
- * 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;
-};