@easemate/web-kit 0.1.0

package/build/theme/presets.js

@@ -0,0 +1,51 @@
+import { defaultColors, defaultRadii, defaultSpacing, defaultTypography } from "./tokens.js";
+/**
+ * Default ease UI kit CSS variables (--ease-*).
+ * These are component-level design tokens that components consume.
+ */
+export const defaultEaseVars = {
+    // Typography aliases
+    '--ease-font-family': 'var(--font-family)',
+    '--ease-font-mono': 'var(--font-mono)',
+    '--ease-font-size': 'var(--font-size)',
+    '--ease-font-size-sm': '12px',
+    '--ease-line-height': 'var(--font-line-height)',
+    // Panel (ease-state)
+    '--ease-panel-max-width': '332px',
+    '--ease-panel-padding': 'var(--spacing-md)',
+    '--ease-panel-radius': 'var(--radii-lg)',
+    '--ease-panel-border-color': 'var(--color-white-6)',
+    '--ease-panel-background': 'var(--color-gray-1000)',
+    '--ease-panel-shadow': '0 0 40px 0 var(--color-white-2) inset',
+    '--ease-panel-title-font-size': '14px',
+    '--ease-panel-title-font-weight': '500',
+    '--ease-panel-title-line-height': '24px',
+    '--ease-panel-title-color': 'var(--color-blue-100)',
+    // Field (ease-field)
+    '--ease-field-label-width': '36%',
+    '--ease-field-column-gap': 'var(--spacing-md)',
+    '--ease-field-row-gap': '6px',
+    '--ease-field-min-height': '30px',
+    '--ease-field-label-font-size': 'var(--ease-font-size-sm)',
+    '--ease-field-label-color': 'var(--color-gray-600)',
+    '--ease-field-label-padding-left': '4px'
+};
+/**
+ * The complete default (dark) theme configuration.
+ * Includes colors, radii, spacing, typography, and component-level --ease-* vars.
+ */
+export const defaultThemeConfig = {
+    colors: defaultColors,
+    radii: defaultRadii,
+    spacing: defaultSpacing,
+    typography: defaultTypography,
+    vars: defaultEaseVars
+};
+/**
+ * Default built-in theme name.
+ */
+export const DEFAULT_THEME_NAME = 'default';
+/**
+ * Legacy alias for the built-in dark theme.
+ */
+export const DARK_THEME_ALIAS = 'dark';

package/build/theme/registry.cjs

@@ -0,0 +1,204 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isThemeConfig = exports.isThemeRef = void 0;
+exports.registerTheme = registerTheme;
+exports.getTheme = getTheme;
+exports.hasTheme = hasTheme;
+exports.getThemeNames = getThemeNames;
+exports.themeRef = themeRef;
+const presets_1 = require("./presets.cjs");
+// --------------------------
+// Registry implementation
+// --------------------------
+const registry = new Map();
+/**
+ * Deep merge two theme configs.
+ */
+const mergeConfigs = (base, overrides) => {
+    return {
+        colors: {
+            ...base.colors,
+            ...overrides.colors,
+            gray: { ...base.colors?.gray, ...overrides.colors?.gray },
+            blue: { ...base.colors?.blue, ...overrides.colors?.blue },
+            green: { ...base.colors?.green, ...overrides.colors?.green },
+            red: { ...base.colors?.red, ...overrides.colors?.red },
+            orange: { ...base.colors?.orange, ...overrides.colors?.orange },
+            yellow: { ...base.colors?.yellow, ...overrides.colors?.yellow },
+            whiteAlpha: { ...base.colors?.whiteAlpha, ...overrides.colors?.whiteAlpha },
+            blackAlpha: { ...base.colors?.blackAlpha, ...overrides.colors?.blackAlpha }
+        },
+        radii: { ...base.radii, ...overrides.radii },
+        spacing: { ...base.spacing, ...overrides.spacing },
+        typography: { ...base.typography, ...overrides.typography },
+        vars: { ...base.vars, ...overrides.vars }
+    };
+};
+/**
+ * Resolve a theme by name, following base chain.
+ */
+const resolveThemeConfig = (name, visited = new Set()) => {
+    if (visited.has(name)) {
+        throw new Error(`[web-kit] Circular theme dependency detected: ${Array.from(visited).join(' -> ')} -> ${name}`);
+    }
+    const entry = registry.get(name);
+    if (!entry) {
+        throw new Error(`[web-kit] Theme "${name}" is not registered.`);
+    }
+    // Return cached resolution
+    if (entry.resolved) {
+        return entry.resolved;
+    }
+    visited.add(name);
+    let resolved;
+    if (entry.base === null) {
+        // No base - use config as-is
+        resolved = entry.config;
+    }
+    else {
+        // Resolve base first
+        const baseConfig = resolveThemeConfig(entry.base, visited);
+        resolved = mergeConfigs(baseConfig, entry.config);
+    }
+    // Cache the resolution
+    entry.resolved = resolved;
+    return resolved;
+};
+/**
+ * Initialize built-in themes.
+ */
+const initBuiltInThemes = () => {
+    if (registry.has(presets_1.DEFAULT_THEME_NAME)) {
+        return;
+    }
+    // Register 'default' theme
+    registry.set(presets_1.DEFAULT_THEME_NAME, {
+        name: presets_1.DEFAULT_THEME_NAME,
+        base: null,
+        config: presets_1.defaultThemeConfig,
+        resolved: presets_1.defaultThemeConfig
+    });
+    // Register 'dark' as alias to 'default'
+    registry.set(presets_1.DARK_THEME_ALIAS, {
+        name: presets_1.DARK_THEME_ALIAS,
+        base: presets_1.DEFAULT_THEME_NAME,
+        config: {},
+        resolved: null
+    });
+};
+// Initialize on module load
+initBuiltInThemes();
+// --------------------------
+// Public API
+// --------------------------
+/**
+ * Check if a value is a theme ref.
+ */
+const isThemeRef = (value) => typeof value === 'object' && value !== null && '__brand' in value && value.__brand === 'WebKitThemeRef';
+exports.isThemeRef = isThemeRef;
+/**
+ * Check if a value is a theme config object.
+ */
+const isThemeConfig = (value) => {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    if ((0, exports.isThemeRef)(value)) {
+        return false;
+    }
+    // Check if it looks like a ThemeConfig
+    const obj = value;
+    return (obj.colors !== undefined ||
+        obj.radii !== undefined ||
+        obj.spacing !== undefined ||
+        obj.typography !== undefined ||
+        obj.vars !== undefined);
+};
+exports.isThemeConfig = isThemeConfig;
+/**
+ * Register a custom theme.
+ *
+ * @param name - Theme name (must be unique)
+ * @param options - Theme options (base + config)
+ * @returns A typed theme reference
+ *
+ * @example
+ * ```ts
+ * const custom = registerTheme('custom', {
+ *   base: 'default',
+ *   config: {
+ *     vars: { '--ease-panel-radius': '14px' }
+ *   }
+ * });
+ *
+ * initWebKit({ theme: custom });
+ * ```
+ */
+function registerTheme(name, options = {}) {
+    const { base = presets_1.DEFAULT_THEME_NAME, config = {} } = options;
+    // Resolve base name
+    let baseName = null;
+    if (base !== null) {
+        baseName = (0, exports.isThemeRef)(base) ? base.name : base;
+        // Validate base exists
+        if (!registry.has(baseName)) {
+            throw new Error(`[web-kit] Base theme "${baseName}" is not registered.`);
+        }
+    }
+    // Invalidate cache for themes that depend on this one (if re-registering)
+    if (registry.has(name)) {
+        for (const entry of registry.values()) {
+            if (entry.base === name) {
+                entry.resolved = null;
+            }
+        }
+    }
+    registry.set(name, {
+        name,
+        base: baseName,
+        config,
+        resolved: null
+    });
+    return {
+        __brand: 'WebKitThemeRef',
+        name
+    };
+}
+/**
+ * Get a theme's resolved configuration.
+ *
+ * @param theme - Theme name, ref, or inline config
+ * @returns Resolved theme configuration
+ */
+function getTheme(theme) {
+    if ((0, exports.isThemeConfig)(theme)) {
+        return theme;
+    }
+    const name = (0, exports.isThemeRef)(theme) ? theme.name : theme;
+    return resolveThemeConfig(name);
+}
+/**
+ * Check if a theme is registered.
+ */
+function hasTheme(name) {
+    return registry.has(name);
+}
+/**
+ * Get all registered theme names.
+ */
+function getThemeNames() {
+    return Array.from(registry.keys());
+}
+/**
+ * Create a theme ref for a registered theme name.
+ * Useful for type-safe references without module augmentation.
+ */
+function themeRef(name) {
+    if (!registry.has(name)) {
+        throw new Error(`[web-kit] Theme "${name}" is not registered.`);
+    }
+    return {
+        __brand: 'WebKitThemeRef',
+        name
+    };
+}

package/build/theme/registry.d.cts

@@ -0,0 +1,99 @@
+import type { ThemeConfig } from "./tokens.cjs";
+/**
+ * Augmentable interface for theme names.
+ * Consumers can extend this via module augmentation to add custom theme names:
+ *
+ * @example
+ * ```ts
+ * declare module '@easemate/web-kit' {
+ *   interface WebKitThemeRegistry {
+ *     custom: true;
+ *     brand: true;
+ *   }
+ * }
+ * ```
+ */
+export interface WebKitThemeRegistry {
+    default: true;
+    dark: true;
+}
+/**
+ * Union of all registered theme names.
+ */
+export type WebKitThemeName = keyof WebKitThemeRegistry;
+/**
+ * A strongly-typed theme reference.
+ * Use this for type-safe theme references without module augmentation.
+ */
+export interface WebKitThemeRef<Name extends string = string> {
+    readonly __brand: 'WebKitThemeRef';
+    readonly name: Name;
+}
+/**
+ * Valid theme input for APIs: a registered theme name, a theme ref, or an inline config.
+ */
+export type ThemeInput = WebKitThemeName | WebKitThemeRef | ThemeConfig;
+/**
+ * Options for registering a theme.
+ */
+export interface RegisterThemeOptions {
+    /**
+     * Base theme to extend from.
+     * - `'default'` (or any registered name) - extends that theme
+     * - `null` - no base, starts from scratch
+     * - `undefined` - defaults to `'default'`
+     */
+    base?: WebKitThemeName | WebKitThemeRef | null;
+    /**
+     * Theme configuration (overrides on top of base).
+     */
+    config?: ThemeConfig;
+}
+/**
+ * Check if a value is a theme ref.
+ */
+export declare const isThemeRef: (value: unknown) => value is WebKitThemeRef;
+/**
+ * Check if a value is a theme config object.
+ */
+export declare const isThemeConfig: (value: unknown) => value is ThemeConfig;
+/**
+ * Register a custom theme.
+ *
+ * @param name - Theme name (must be unique)
+ * @param options - Theme options (base + config)
+ * @returns A typed theme reference
+ *
+ * @example
+ * ```ts
+ * const custom = registerTheme('custom', {
+ *   base: 'default',
+ *   config: {
+ *     vars: { '--ease-panel-radius': '14px' }
+ *   }
+ * });
+ *
+ * initWebKit({ theme: custom });
+ * ```
+ */
+export declare function registerTheme<Name extends string>(name: Name, options?: RegisterThemeOptions): WebKitThemeRef<Name>;
+/**
+ * Get a theme's resolved configuration.
+ *
+ * @param theme - Theme name, ref, or inline config
+ * @returns Resolved theme configuration
+ */
+export declare function getTheme(theme: ThemeInput): ThemeConfig;
+/**
+ * Check if a theme is registered.
+ */
+export declare function hasTheme(name: string): boolean;
+/**
+ * Get all registered theme names.
+ */
+export declare function getThemeNames(): string[];
+/**
+ * Create a theme ref for a registered theme name.
+ * Useful for type-safe references without module augmentation.
+ */
+export declare function themeRef<Name extends WebKitThemeName>(name: Name): WebKitThemeRef<Name>;

package/build/theme/registry.d.ts

@@ -0,0 +1,99 @@
+import type { ThemeConfig } from "./tokens.js";
+/**
+ * Augmentable interface for theme names.
+ * Consumers can extend this via module augmentation to add custom theme names:
+ *
+ * @example
+ * ```ts
+ * declare module '@easemate/web-kit' {
+ *   interface WebKitThemeRegistry {
+ *     custom: true;
+ *     brand: true;
+ *   }
+ * }
+ * ```
+ */
+export interface WebKitThemeRegistry {
+    default: true;
+    dark: true;
+}
+/**
+ * Union of all registered theme names.
+ */
+export type WebKitThemeName = keyof WebKitThemeRegistry;
+/**
+ * A strongly-typed theme reference.
+ * Use this for type-safe theme references without module augmentation.
+ */
+export interface WebKitThemeRef<Name extends string = string> {
+    readonly __brand: 'WebKitThemeRef';
+    readonly name: Name;
+}
+/**
+ * Valid theme input for APIs: a registered theme name, a theme ref, or an inline config.
+ */
+export type ThemeInput = WebKitThemeName | WebKitThemeRef | ThemeConfig;
+/**
+ * Options for registering a theme.
+ */
+export interface RegisterThemeOptions {
+    /**
+     * Base theme to extend from.
+     * - `'default'` (or any registered name) - extends that theme
+     * - `null` - no base, starts from scratch
+     * - `undefined` - defaults to `'default'`
+     */
+    base?: WebKitThemeName | WebKitThemeRef | null;
+    /**
+     * Theme configuration (overrides on top of base).
+     */
+    config?: ThemeConfig;
+}
+/**
+ * Check if a value is a theme ref.
+ */
+export declare const isThemeRef: (value: unknown) => value is WebKitThemeRef;
+/**
+ * Check if a value is a theme config object.
+ */
+export declare const isThemeConfig: (value: unknown) => value is ThemeConfig;
+/**
+ * Register a custom theme.
+ *
+ * @param name - Theme name (must be unique)
+ * @param options - Theme options (base + config)
+ * @returns A typed theme reference
+ *
+ * @example
+ * ```ts
+ * const custom = registerTheme('custom', {
+ *   base: 'default',
+ *   config: {
+ *     vars: { '--ease-panel-radius': '14px' }
+ *   }
+ * });
+ *
+ * initWebKit({ theme: custom });
+ * ```
+ */
+export declare function registerTheme<Name extends string>(name: Name, options?: RegisterThemeOptions): WebKitThemeRef<Name>;
+/**
+ * Get a theme's resolved configuration.
+ *
+ * @param theme - Theme name, ref, or inline config
+ * @returns Resolved theme configuration
+ */
+export declare function getTheme(theme: ThemeInput): ThemeConfig;
+/**
+ * Check if a theme is registered.
+ */
+export declare function hasTheme(name: string): boolean;
+/**
+ * Get all registered theme names.
+ */
+export declare function getThemeNames(): string[];
+/**
+ * Create a theme ref for a registered theme name.
+ * Useful for type-safe references without module augmentation.
+ */
+export declare function themeRef<Name extends WebKitThemeName>(name: Name): WebKitThemeRef<Name>;

package/build/theme/registry.js

@@ -0,0 +1,194 @@
+import { DARK_THEME_ALIAS, DEFAULT_THEME_NAME, defaultThemeConfig } from "./presets.js";
+// --------------------------
+// Registry implementation
+// --------------------------
+const registry = new Map();
+/**
+ * Deep merge two theme configs.
+ */
+const mergeConfigs = (base, overrides) => {
+    return {
+        colors: {
+            ...base.colors,
+            ...overrides.colors,
+            gray: { ...base.colors?.gray, ...overrides.colors?.gray },
+            blue: { ...base.colors?.blue, ...overrides.colors?.blue },
+            green: { ...base.colors?.green, ...overrides.colors?.green },
+            red: { ...base.colors?.red, ...overrides.colors?.red },
+            orange: { ...base.colors?.orange, ...overrides.colors?.orange },
+            yellow: { ...base.colors?.yellow, ...overrides.colors?.yellow },
+            whiteAlpha: { ...base.colors?.whiteAlpha, ...overrides.colors?.whiteAlpha },
+            blackAlpha: { ...base.colors?.blackAlpha, ...overrides.colors?.blackAlpha }
+        },
+        radii: { ...base.radii, ...overrides.radii },
+        spacing: { ...base.spacing, ...overrides.spacing },
+        typography: { ...base.typography, ...overrides.typography },
+        vars: { ...base.vars, ...overrides.vars }
+    };
+};
+/**
+ * Resolve a theme by name, following base chain.
+ */
+const resolveThemeConfig = (name, visited = new Set()) => {
+    if (visited.has(name)) {
+        throw new Error(`[web-kit] Circular theme dependency detected: ${Array.from(visited).join(' -> ')} -> ${name}`);
+    }
+    const entry = registry.get(name);
+    if (!entry) {
+        throw new Error(`[web-kit] Theme "${name}" is not registered.`);
+    }
+    // Return cached resolution
+    if (entry.resolved) {
+        return entry.resolved;
+    }
+    visited.add(name);
+    let resolved;
+    if (entry.base === null) {
+        // No base - use config as-is
+        resolved = entry.config;
+    }
+    else {
+        // Resolve base first
+        const baseConfig = resolveThemeConfig(entry.base, visited);
+        resolved = mergeConfigs(baseConfig, entry.config);
+    }
+    // Cache the resolution
+    entry.resolved = resolved;
+    return resolved;
+};
+/**
+ * Initialize built-in themes.
+ */
+const initBuiltInThemes = () => {
+    if (registry.has(DEFAULT_THEME_NAME)) {
+        return;
+    }
+    // Register 'default' theme
+    registry.set(DEFAULT_THEME_NAME, {
+        name: DEFAULT_THEME_NAME,
+        base: null,
+        config: defaultThemeConfig,
+        resolved: defaultThemeConfig
+    });
+    // Register 'dark' as alias to 'default'
+    registry.set(DARK_THEME_ALIAS, {
+        name: DARK_THEME_ALIAS,
+        base: DEFAULT_THEME_NAME,
+        config: {},
+        resolved: null
+    });
+};
+// Initialize on module load
+initBuiltInThemes();
+// --------------------------
+// Public API
+// --------------------------
+/**
+ * Check if a value is a theme ref.
+ */
+export const isThemeRef = (value) => typeof value === 'object' && value !== null && '__brand' in value && value.__brand === 'WebKitThemeRef';
+/**
+ * Check if a value is a theme config object.
+ */
+export const isThemeConfig = (value) => {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    if (isThemeRef(value)) {
+        return false;
+    }
+    // Check if it looks like a ThemeConfig
+    const obj = value;
+    return (obj.colors !== undefined ||
+        obj.radii !== undefined ||
+        obj.spacing !== undefined ||
+        obj.typography !== undefined ||
+        obj.vars !== undefined);
+};
+/**
+ * Register a custom theme.
+ *
+ * @param name - Theme name (must be unique)
+ * @param options - Theme options (base + config)
+ * @returns A typed theme reference
+ *
+ * @example
+ * ```ts
+ * const custom = registerTheme('custom', {
+ *   base: 'default',
+ *   config: {
+ *     vars: { '--ease-panel-radius': '14px' }
+ *   }
+ * });
+ *
+ * initWebKit({ theme: custom });
+ * ```
+ */
+export function registerTheme(name, options = {}) {
+    const { base = DEFAULT_THEME_NAME, config = {} } = options;
+    // Resolve base name
+    let baseName = null;
+    if (base !== null) {
+        baseName = isThemeRef(base) ? base.name : base;
+        // Validate base exists
+        if (!registry.has(baseName)) {
+            throw new Error(`[web-kit] Base theme "${baseName}" is not registered.`);
+        }
+    }
+    // Invalidate cache for themes that depend on this one (if re-registering)
+    if (registry.has(name)) {
+        for (const entry of registry.values()) {
+            if (entry.base === name) {
+                entry.resolved = null;
+            }
+        }
+    }
+    registry.set(name, {
+        name,
+        base: baseName,
+        config,
+        resolved: null
+    });
+    return {
+        __brand: 'WebKitThemeRef',
+        name
+    };
+}
+/**
+ * Get a theme's resolved configuration.
+ *
+ * @param theme - Theme name, ref, or inline config
+ * @returns Resolved theme configuration
+ */
+export function getTheme(theme) {
+    if (isThemeConfig(theme)) {
+        return theme;
+    }
+    const name = isThemeRef(theme) ? theme.name : theme;
+    return resolveThemeConfig(name);
+}
+/**
+ * Check if a theme is registered.
+ */
+export function hasTheme(name) {
+    return registry.has(name);
+}
+/**
+ * Get all registered theme names.
+ */
+export function getThemeNames() {
+    return Array.from(registry.keys());
+}
+/**
+ * Create a theme ref for a registered theme name.
+ * Useful for type-safe references without module augmentation.
+ */
+export function themeRef(name) {
+    if (!registry.has(name)) {
+        throw new Error(`[web-kit] Theme "${name}" is not registered.`);
+    }
+    return {
+        __brand: 'WebKitThemeRef',
+        name
+    };
+}