@glasshome/widget-sdk 0.1.0

package/dist/framework/utils/format-value.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Value Formatting Utility
+ *
+ * Formats numeric values with units, applying smart scaling for large numbers.
+ *
+ * @example
+ * ```tsx
+ * formatValue(22, "°C")      // "22°C"
+ * formatValue(1234, "W")     // "1.2kW"
+ * formatValue(0.5, "")       // "0.5"
+ * formatValue(1500000, "W")  // "1.5MW"
+ * ```
+ */
+/**
+ * Format a numeric value with optional unit and smart scaling
+ */
+export declare function formatValue(value: number | string, unit?: string, options?: {
+    /** Number of decimal places (default: auto) */
+    decimals?: number;
+    /** Enable smart scaling for large numbers (default: true) */
+    scale?: boolean;
+}): string;

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

@@ -0,0 +1,12 @@
+/**
+ * Framework Utilities - Barrel Export
+ *
+ * Helper functions for value formatting, entity state management,
+ * and class name composition.
+ */
+export { cn } from "./cn";
+export { createEmptyStateConfig, type EmptyStateConfigOptions, type WidgetEmptyStateConfig, } from "./empty-state";
+export { calculateLightGroup, calculateSensorGroup, type LightGroupResult, type SensorGroupResult, type SensorGroupType, } from "./entity-aggregation";
+export { allEntitiesInState, anyEntityInState, countActiveEntities, countAvailableEntities, countEntitiesByState, getEntityAttribute, getEntityState, isEntityActive, isEntityAvailable, } from "./entity-state";
+export { formatValue } from "./format-value";
+export { interpretValue } from "./interpret-value";

package/dist/framework/utils/interpret-value.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Value Interpretation Utility
+ *
+ * Provides semantic interpretation of numeric values based on unit.
+ *
+ * @example
+ * ```tsx
+ * interpretValue(22, "°C")   // "Warm"
+ * interpretValue(5, "°C")    // "Cold"
+ * interpretValue(75, "%")    // "High"
+ * interpretValue(400, "ppm") // "Good" (for CO2)
+ * ```
+ */
+/**
+ * Interpret a numeric value semantically
+ */
+export declare function interpretValue(value: number, unit?: string): string | null;

package/dist/framework/variants/built-in-variants.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Built-in Widget Variants
+ *
+ * Simplified set of pre-built variant definitions that ship with the framework.
+ * These variants can be used as-is or extended/composed.
+ *
+ * Includes 3 core variants (classic-glass, minimal, compact-horizontal).
+ * Additional variants can be added later or created by widget authors
+ * using the variant composition utilities.
+ */
+import type { VariantRegistry, WidgetVariantConfig } from "../types";
+export declare const classicGlass: WidgetVariantConfig;
+export declare const minimal: WidgetVariantConfig;
+export declare const compactHorizontal: WidgetVariantConfig;
+/**
+ * Built-in variant registry
+ * Maps variant IDs to their configurations
+ */
+export declare const builtInVariants: VariantRegistry;
+/**
+ * Get a variant by ID from the built-in registry
+ *
+ * @param id Variant ID
+ * @returns Variant configuration or undefined if not found
+ */
+export declare function getBuiltInVariant(id: string): WidgetVariantConfig | undefined;
+/**
+ * Check if a variant ID is a built-in variant
+ *
+ * @param id Variant ID to check
+ * @returns True if the variant is built-in
+ */
+export declare function isBuiltInVariant(id: string): boolean;
+/**
+ * Get all built-in variant IDs
+ *
+ * @returns Array of built-in variant IDs
+ */
+export declare function getBuiltInVariantIds(): string[];

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

@@ -0,0 +1,7 @@
+/**
+ * Variant System - Barrel Export
+ *
+ * Built-in variant presets and composition utilities.
+ */
+export { builtInVariants, classicGlass, compactHorizontal, getBuiltInVariant, getBuiltInVariantIds, isBuiltInVariant, minimal, } from "./built-in-variants";
+export { applyCssVars, applyLayout, composeVariants, createFlexLayout, extendVariant, mergeVariants, } from "./variant-utils";

package/dist/framework/variants/variant-utils.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Variant Composition Utilities
+ *
+ * Utilities for creating, merging, extending, and composing widget variants.
+ * Enables flexible variant system with type safety and composability.
+ */
+import type { FlexLayoutStrategy, LayoutStrategy, WidgetVariantConfig } from "../types";
+/**
+ * Merge two complete variant configurations
+ *
+ * Deep merges all properties, with `override` taking precedence.
+ * Layout strategies are replaced, not merged (since they have different shapes).
+ *
+ * @example
+ * ```tsx
+ * const customVariant = mergeVariants(classicGlass, {
+ *   styles: {
+ *     cssVars: {
+ *       "--widget-bg": "rgba(0, 0, 0, 0.5)"
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export declare function mergeVariants(base: WidgetVariantConfig, override: Partial<WidgetVariantConfig>): WidgetVariantConfig;
+/**
+ * Extend a base variant with partial overrides
+ *
+ * Similar to mergeVariants but returns a new variant that references the base
+ * via the `extends` property. Useful for variant inheritance chains.
+ *
+ * @example
+ * ```tsx
+ * const darkGlass = extendVariant("classic-glass", {
+ *   id: "dark-glass",
+ *   name: "Dark Glass",
+ *   styles: {
+ *     cssVars: {
+ *       "--widget-bg": "rgba(0, 0, 0, 0.5)"
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export declare function extendVariant(baseId: string, override: Partial<WidgetVariantConfig> & {
+    id: string;
+    name: string;
+}): WidgetVariantConfig;
+/**
+ * Compose multiple variants together (left to right precedence)
+ *
+ * Merges multiple variants in sequence, with later variants taking precedence.
+ * Useful for combining layout + styling + interaction variants.
+ *
+ * @example
+ * ```tsx
+ * const custom = composeVariants(
+ *   minimal,           // Base: minimal styling
+ *   centeredLayout,    // Add: centered layout
+ *   largeIcons         // Add: large icon sizing
+ * );
+ * ```
+ */
+export declare function composeVariants(...variants: WidgetVariantConfig[]): WidgetVariantConfig;
+/**
+ * Apply a layout strategy override to a variant
+ *
+ * Convenience function for changing just the layout of a variant.
+ *
+ * @example
+ * ```tsx
+ * const centered = applyLayout(minimal, {
+ *   type: "flex",
+ *   direction: "column",
+ *   align: "center",
+ *   justify: "center"
+ * });
+ * ```
+ */
+export declare function applyLayout(variant: WidgetVariantConfig, layout: LayoutStrategy): WidgetVariantConfig;
+/**
+ * Apply CSS variable overrides to a variant
+ *
+ * Convenience function for changing just the CSS variables of a variant.
+ *
+ * @example
+ * ```tsx
+ * const blueTinted = applyCssVars(classicGlass, {
+ *   "--widget-bg": "rgba(59, 130, 246, 0.2)",
+ *   "--widget-border": "rgba(59, 130, 246, 0.3)"
+ * });
+ * ```
+ */
+export declare function applyCssVars(variant: WidgetVariantConfig, cssVars: Record<`--widget-${string}`, string | number>): WidgetVariantConfig;
+/**
+ * Create a flex layout strategy
+ *
+ * Convenience function for creating common flex layouts.
+ *
+ * @example
+ * ```tsx
+ * const layout = createFlexLayout("column", "center", "center");
+ * ```
+ */
+export declare function createFlexLayout(direction?: FlexLayoutStrategy["direction"], align?: FlexLayoutStrategy["align"], justify?: FlexLayoutStrategy["justify"], options?: Partial<FlexLayoutStrategy>): FlexLayoutStrategy;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export type { Entity } from "./create-entity";
+export { createEntity } from "./create-entity";
+export { defineWidget } from "./define-widget";
+export * from "./framework";
+export { getThemeToken, isDark } from "./theme";
+export type { GridSize, WidgetContext, WidgetDefinition, WidgetManifest, } from "./types";
+export { SDK_VERSION } from "./version";