@easemate/web-kit 0.2.0 → 0.3.0

package/build/react/use-web-kit.d.ts

@@ -1,80 +0,0 @@
-/**
- * React hook for initializing @easemate/web-kit
- *
- * This module provides hooks for React integration.
- * React is a peer dependency - users must install it separately.
- *
- * @module
- */
-import type { InitWebKitOptions, WebKitController } from '../init';
-/**
- * Options for useWebKit hook
- */
-export interface UseWebKitOptions extends InitWebKitOptions {
-    /**
-     * Skip initialization (useful for conditional rendering)
-     * @default false
-     */
-    skip?: boolean;
-}
-/**
- * Return type for useWebKit hook
- */
-export interface UseWebKitReturn {
-    /** Whether the web kit is ready */
-    ready: boolean;
-    /** Theme controller (if theme was configured) */
-    theme?: WebKitController['theme'];
-    /** Dispose function for cleanup */
-    dispose: () => void;
-}
-/**
- * React hook for initializing @easemate/web-kit.
- *
- * This hook handles initialization and cleanup of the web kit,
- * ensuring components are registered before rendering.
- *
- * **Important for Next.js App Router:**
- * - Use this hook in a client component (`'use client'`)
- * - Place it at the top of your component tree (e.g., in a layout)
- * - The hook is SSR-safe and will only initialize on the client
- *
- * **Note:** This hook requires React to be installed. Import React hooks
- * directly in your component and pass them to this function, or use the
- * imperative `initWebKit()` function directly.
- *
- * @example
- * ```tsx
- * // app/providers.tsx
- * 'use client';
- *
- * import { useEffect, useState, useRef } from '../react';
- * import { initWebKit } from '@easemate/web-kit';
- *
- * export function Providers({ children }: { children: React.ReactNode }) {
- *   const [ready, setReady] = useState(false);
- *   const controllerRef = useRef<WebKitController | null>(null);
- *
- *   useEffect(() => {
- *     const controller = initWebKit({
- *       theme: 'default',
- *       styles: 'main',
- *       fonts: 'default'
- *     });
- *     controllerRef.current = controller;
- *     controller.ready.then(() => setReady(true));
- *
- *     return () => controller.dispose();
- *   }, []);
- *
- *   return <>{children}</>;
- * }
- * ```
- */
-export declare function useWebKit(options: UseWebKitOptions, hooks: {
-    useState: <T>(initial: T) => [T, (value: T) => void];
-    useEffect: (effect: () => (() => void) | undefined, deps?: unknown[]) => void;
-    useRef: <T>(initial: T) => {
-        current: T;
-    };
-}): UseWebKitReturn;

package/build/react/use-web-kit.js

@@ -1,114 +0,0 @@
-/**
- * React hook for initializing @easemate/web-kit
- *
- * This module provides hooks for React integration.
- * React is a peer dependency - users must install it separately.
- *
- * @module
- */
-// Singleton to track if web-kit has been initialized globally
-let globalController = null;
-let initCount = 0;
-/**
- * React hook for initializing @easemate/web-kit.
- *
- * This hook handles initialization and cleanup of the web kit,
- * ensuring components are registered before rendering.
- *
- * **Important for Next.js App Router:**
- * - Use this hook in a client component (`'use client'`)
- * - Place it at the top of your component tree (e.g., in a layout)
- * - The hook is SSR-safe and will only initialize on the client
- *
- * **Note:** This hook requires React to be installed. Import React hooks
- * directly in your component and pass them to this function, or use the
- * imperative `initWebKit()` function directly.
- *
- * @example
- * ```tsx
- * // app/providers.tsx
- * 'use client';
- *
- * import { useEffect, useState, useRef } from '../react';
- * import { initWebKit } from '@easemate/web-kit';
- *
- * export function Providers({ children }: { children: React.ReactNode }) {
- *   const [ready, setReady] = useState(false);
- *   const controllerRef = useRef<WebKitController | null>(null);
- *
- *   useEffect(() => {
- *     const controller = initWebKit({
- *       theme: 'default',
- *       styles: 'main',
- *       fonts: 'default'
- *     });
- *     controllerRef.current = controller;
- *     controller.ready.then(() => setReady(true));
- *
- *     return () => controller.dispose();
- *   }, []);
- *
- *   return <>{children}</>;
- * }
- * ```
- */
-export function useWebKit(options, hooks) {
-    const isSSR = typeof window === 'undefined';
-    const { useState, useEffect, useRef } = hooks;
-    const { skip = false, ...initOptions } = options;
-    const [ready, setReady] = useState(false);
-    const controllerRef = useRef(null);
-    const optionsRef = useRef(initOptions);
-    useEffect(() => {
-        // Skip on SSR or if explicitly skipped
-        if (isSSR || skip) {
-            return;
-        }
-        let isMounted = true;
-        const initialize = async () => {
-            // If already initialized globally, reuse the controller
-            if (globalController) {
-                initCount++;
-                controllerRef.current = globalController;
-                await globalController.ready;
-                if (isMounted) {
-                    setReady(true);
-                }
-                return;
-            }
-            // Dynamic import to ensure this only runs on client
-            const { initWebKit } = await import('../init');
-            const controller = initWebKit(optionsRef.current);
-            globalController = controller;
-            initCount++;
-            controllerRef.current = controller;
-            await controller.ready;
-            if (isMounted) {
-                setReady(true);
-            }
-        };
-        initialize();
-        return () => {
-            isMounted = false;
-            initCount--;
-            // Only dispose if this was the last user of the global controller
-            if (initCount <= 0 && globalController) {
-                globalController.dispose();
-                globalController = null;
-                initCount = 0;
-            }
-        };
-    }, [skip]);
-    return {
-        ready,
-        theme: controllerRef.current?.theme,
-        dispose: () => {
-            controllerRef.current?.dispose();
-            if (controllerRef.current === globalController) {
-                globalController = null;
-                initCount = 0;
-            }
-            controllerRef.current = null;
-        }
-    };
-}

package/build/theme/index.cjs

@@ -1,452 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.followSystemTheme = exports.getSystemThemeMode = exports.applyTheme = exports.getThemeName = exports.setThemeName = exports.createDarkTheme = exports.mergeTheme = exports.EASE_THEME_ATTRIBUTE = exports.setThemeValue = exports.getThemeValue = exports.removeTheme = exports.defineTheme = exports.createTheme = void 0;
-const tokens_1 = require("./tokens.cjs");
-__exportStar(require("./presets.cjs"), exports);
-__exportStar(require("./registry.cjs"), exports);
-__exportStar(require("./tokens.cjs"), exports);
-/**
- * CSS variable prefix
- */
-const CSS_PREFIX = '--color';
-const RADII_PREFIX = '--radii';
-const SPACING_PREFIX = '--spacing';
-const TYPOGRAPHY_PREFIX = '--font';
-/**
- * Convert a nested object path to CSS variable name
- * e.g., ['gray', '100'] -> '--color-gray-100'
- */
-const toVarName = (prefix, ...parts) => `${prefix}-${parts.join('-')}`;
-/**
- * Generate CSS variables from a color scale
- */
-const generateColorScaleVars = (name, scale) => {
-    const vars = {};
-    for (const [level, value] of Object.entries(scale)) {
-        if (value !== undefined) {
-            vars[toVarName(CSS_PREFIX, name, level)] = value;
-        }
-    }
-    return vars;
-};
-/**
- * Add alpha to an OKLab/OKLCH color string.
- * Falls back to `color-mix()` for non-oklab/oklch formats.
- */
-const withAlpha = (color, alpha) => {
-    const trimmed = color.trim();
-    const match = /^(oklab|oklch)\((.+)\)$/.exec(trimmed);
-    if (match) {
-        const fn = match[1];
-        const innerRaw = match[2];
-        if (fn && innerRaw) {
-            const inner = innerRaw.trim();
-            // If the color already has an alpha, keep it as-is.
-            if (inner.includes('/')) {
-                return `${fn}(${inner})`;
-            }
-            return `${fn}(${inner} / ${alpha})`;
-        }
-    }
-    // Fallback: approximate alpha using color-mix
-    const pct = Math.round(alpha * 1000) / 10;
-    return `color-mix(in oklab, ${trimmed} ${pct}%, transparent)`;
-};
-/**
- * Generate CSS variables from a color palette
- */
-const generateColorVars = (colors) => {
-    const vars = {};
-    if (colors.gray) {
-        Object.assign(vars, generateColorScaleVars('gray', colors.gray));
-    }
-    if (colors.blue) {
-        Object.assign(vars, generateColorScaleVars('blue', colors.blue));
-    }
-    // Derived convenience tokens used by some components
-    const blue = colors.blue;
-    if (blue?.['200']) {
-        vars[toVarName(CSS_PREFIX, 'blue', '100-50')] = withAlpha(blue['200'], 0.5);
-    }
-    if (blue?.['300']) {
-        vars[toVarName(CSS_PREFIX, 'blue', '300-40')] = withAlpha(blue['300'], 0.4);
-    }
-    if (colors.green) {
-        Object.assign(vars, generateColorScaleVars('green', colors.green));
-    }
-    if (colors.red) {
-        Object.assign(vars, generateColorScaleVars('red', colors.red));
-    }
-    if (colors.orange) {
-        Object.assign(vars, generateColorScaleVars('orange', colors.orange));
-    }
-    if (colors.yellow) {
-        Object.assign(vars, generateColorScaleVars('yellow', colors.yellow));
-    }
-    if (colors.white) {
-        vars[toVarName(CSS_PREFIX, 'white')] = colors.white;
-    }
-    if (colors.black) {
-        vars[toVarName(CSS_PREFIX, 'black')] = colors.black;
-    }
-    if (colors.whiteAlpha) {
-        for (const [level, value] of Object.entries(colors.whiteAlpha)) {
-            if (value !== undefined) {
-                vars[toVarName(CSS_PREFIX, 'white', level)] = value;
-            }
-        }
-    }
-    // Ensure `--color-white-0` exists (used by slider thumb gradients)
-    if (!vars[toVarName(CSS_PREFIX, 'white', 0)] && colors.white) {
-        vars[toVarName(CSS_PREFIX, 'white', 0)] = withAlpha(colors.white, 0);
-    }
-    if (colors.blackAlpha) {
-        for (const [level, value] of Object.entries(colors.blackAlpha)) {
-            if (value !== undefined) {
-                vars[toVarName(CSS_PREFIX, 'black', level)] = value;
-            }
-        }
-    }
-    if (colors.foreground) {
-        vars[toVarName(CSS_PREFIX, 'foreground')] = colors.foreground;
-    }
-    return vars;
-};
-/**
- * Resolve the theme target element.
- * This keeps the theme API SSR-safe (no-ops when `document` is not available).
- */
-const resolveThemeTarget = (element) => {
-    if (element) {
-        return element;
-    }
-    if (typeof document === 'undefined') {
-        return null;
-    }
-    return document.documentElement;
-};
-/**
- * Generate CSS variables from radii config
- */
-const generateRadiiVars = (radii) => {
-    const vars = {};
-    for (const [name, value] of Object.entries(radii)) {
-        if (value !== undefined) {
-            vars[toVarName(RADII_PREFIX, name)] = value;
-        }
-    }
-    return vars;
-};
-/**
- * Generate CSS variables from spacing config
- */
-const generateSpacingVars = (spacing) => {
-    const vars = {};
-    for (const [name, value] of Object.entries(spacing)) {
-        if (value !== undefined) {
-            vars[toVarName(SPACING_PREFIX, name)] = value;
-        }
-    }
-    return vars;
-};
-/**
- * Generate CSS variables from typography config
- */
-const generateTypographyVars = (typography) => {
-    const vars = {};
-    if (typography.fontFamily) {
-        vars[toVarName(TYPOGRAPHY_PREFIX, 'family')] = typography.fontFamily;
-    }
-    if (typography.fontMono) {
-        vars[toVarName(TYPOGRAPHY_PREFIX, 'mono')] = typography.fontMono;
-    }
-    if (typography.fontSize) {
-        vars[toVarName(TYPOGRAPHY_PREFIX, 'size')] = typography.fontSize;
-    }
-    if (typography.lineHeight) {
-        vars[toVarName(TYPOGRAPHY_PREFIX, 'line-height')] = typography.lineHeight;
-    }
-    return vars;
-};
-const normalizeCustomVarName = (name) => {
-    const trimmed = name.trim();
-    if (!trimmed) {
-        return null;
-    }
-    return trimmed.startsWith('--') ? trimmed : `--${trimmed}`;
-};
-const generateCustomVars = (vars) => {
-    const out = {};
-    for (const [key, value] of Object.entries(vars)) {
-        if (value === null || value === undefined) {
-            continue;
-        }
-        const name = normalizeCustomVarName(key);
-        if (!name) {
-            continue;
-        }
-        out[name] = String(value);
-    }
-    return out;
-};
-/**
- * Generate all CSS variables from a theme config
- */
-const generateThemeVars = (config) => {
-    const vars = {};
-    if (config.colors) {
-        Object.assign(vars, generateColorVars(config.colors));
-    }
-    if (config.radii) {
-        Object.assign(vars, generateRadiiVars(config.radii));
-    }
-    if (config.spacing) {
-        Object.assign(vars, generateSpacingVars(config.spacing));
-    }
-    if (config.typography) {
-        Object.assign(vars, generateTypographyVars(config.typography));
-    }
-    if (config.vars) {
-        Object.assign(vars, generateCustomVars(config.vars));
-    }
-    return vars;
-};
-/**
- * Create a CSS string from theme configuration
- *
- * @param config - Theme configuration object
- * @param selector - CSS selector to apply variables to (default: ':root')
- * @returns CSS string with variables
- *
- * @example
- * ```typescript
- * const css = createTheme({
- *   colors: {
- *     blue: { 500: '#3b82f6' }
- *   }
- * });
- * // Returns: ':root { --color-blue-500: #3b82f6; }'
- * ```
- */
-const createTheme = (config, selector = ':root') => {
-    const vars = generateThemeVars(config);
-    const declarations = Object.entries(vars)
-        .map(([name, value]) => `  ${name}: ${value};`)
-        .join('\n');
-    return `${selector} {\n${declarations}\n}`;
-};
-exports.createTheme = createTheme;
-/**
- * Apply theme configuration to an element (default: document root)
- *
- * @param config - Theme configuration object
- * @param element - Target element (default: document.documentElement)
- *
- * @example
- * ```typescript
- * // Apply to document root
- * defineTheme({
- *   colors: {
- *     blue: { 500: '#3b82f6' }
- *   }
- * });
- *
- * // Apply to specific element
- * defineTheme({ colors: { gray: { 900: '#111' } } }, myElement);
- * ```
- */
-const defineTheme = (config, element) => {
-    const target = resolveThemeTarget(element);
-    if (!target) {
-        return;
-    }
-    const vars = generateThemeVars(config);
-    for (const [name, value] of Object.entries(vars)) {
-        target.style.setProperty(name, value);
-    }
-};
-exports.defineTheme = defineTheme;
-/**
- * Remove theme configuration from an element
- *
- * @param config - Theme configuration object (to know which variables to remove)
- * @param element - Target element (default: document.documentElement)
- */
-const removeTheme = (config, element) => {
-    const target = resolveThemeTarget(element);
-    if (!target) {
-        return;
-    }
-    const vars = generateThemeVars(config);
-    for (const name of Object.keys(vars)) {
-        target.style.removeProperty(name);
-    }
-};
-exports.removeTheme = removeTheme;
-/**
- * Get the current value of a CSS theme variable
- *
- * @param token - Variable name (with or without '--' prefix)
- * @param element - Element to read from (default: document.documentElement)
- * @returns The computed value or empty string if not found
- *
- * @example
- * ```typescript
- * const blue500 = getThemeValue('color-blue-500');
- * const radius = getThemeValue('--radii-md');
- * ```
- */
-const getThemeValue = (token, element) => {
-    const target = resolveThemeTarget(element);
-    if (!target || typeof getComputedStyle === 'undefined') {
-        return '';
-    }
-    const varName = token.startsWith('--') ? token : `--${token}`;
-    return getComputedStyle(target).getPropertyValue(varName).trim();
-};
-exports.getThemeValue = getThemeValue;
-/**
- * Set a single theme variable
- *
- * @param token - Variable name (with or without '--' prefix)
- * @param value - Value to set
- * @param element - Target element (default: document.documentElement)
- *
- * @example
- * ```typescript
- * setThemeValue('color-blue-500', '#3b82f6');
- * ```
- */
-const setThemeValue = (token, value, element) => {
-    const target = resolveThemeTarget(element);
-    if (!target) {
-        return;
-    }
-    const varName = token.startsWith('--') ? token : `--${token}`;
-    target.style.setProperty(varName, value);
-};
-exports.setThemeValue = setThemeValue;
-/** Attribute used for CSS-based theme switching */
-exports.EASE_THEME_ATTRIBUTE = 'data-ease-theme';
-/**
- * Merge a theme with the library defaults (dark baseline).
- * Use this when you want to start from the built-in design tokens and override a few values.
- */
-const mergeTheme = (overrides = {}) => {
-    return {
-        colors: {
-            ...tokens_1.defaultColors,
-            ...overrides.colors,
-            gray: { ...tokens_1.defaultColors.gray, ...overrides.colors?.gray },
-            blue: { ...tokens_1.defaultColors.blue, ...overrides.colors?.blue },
-            green: { ...tokens_1.defaultColors.green, ...overrides.colors?.green },
-            red: { ...tokens_1.defaultColors.red, ...overrides.colors?.red },
-            orange: { ...tokens_1.defaultColors.orange, ...overrides.colors?.orange },
-            yellow: { ...tokens_1.defaultColors.yellow, ...overrides.colors?.yellow },
-            whiteAlpha: { ...tokens_1.defaultColors.whiteAlpha, ...overrides.colors?.whiteAlpha },
-            blackAlpha: { ...tokens_1.defaultColors.blackAlpha, ...overrides.colors?.blackAlpha }
-        },
-        radii: { ...tokens_1.defaultRadii, ...overrides.radii },
-        spacing: { ...tokens_1.defaultSpacing, ...overrides.spacing },
-        typography: { ...tokens_1.defaultTypography, ...overrides.typography },
-        vars: overrides.vars ? { ...overrides.vars } : undefined
-    };
-};
-exports.mergeTheme = mergeTheme;
-/**
- * Alias for `mergeTheme()`.
- * This package ships a dark baseline theme; light/custom themes should be provided by the consumer.
- */
-const createDarkTheme = (overrides = {}) => (0, exports.mergeTheme)(overrides);
-exports.createDarkTheme = createDarkTheme;
-/**
- * Set the active theme name on an element via `[data-ease-theme="<name>"]`.
- * Useful for CSS-scoped themes.
- */
-const setThemeName = (name, options = {}) => {
-    const target = resolveThemeTarget(options.element);
-    if (!target) {
-        return;
-    }
-    const attribute = options.attribute ?? exports.EASE_THEME_ATTRIBUTE;
-    target.setAttribute(attribute, name);
-    if (options.colorScheme && options.setColorScheme !== false) {
-        target.style.colorScheme = options.colorScheme;
-    }
-};
-exports.setThemeName = setThemeName;
-const getThemeName = (element, attribute = exports.EASE_THEME_ATTRIBUTE) => {
-    const target = resolveThemeTarget(element);
-    if (!target) {
-        return null;
-    }
-    return target.getAttribute(attribute);
-};
-exports.getThemeName = getThemeName;
-/**
- * Apply a theme config (and optional theme name + color-scheme) to an element.
- * This is SSR-safe: it becomes a no-op when `document` is not available.
- */
-const applyTheme = (theme, options = {}) => {
-    const target = resolveThemeTarget(options.element);
-    const attribute = options.attribute ?? exports.EASE_THEME_ATTRIBUTE;
-    const config = options.mergeWithDefaults ? (0, exports.mergeTheme)(theme) : theme;
-    (0, exports.defineTheme)(config, target);
-    if (!target) {
-        return config;
-    }
-    if (options.name && options.setAttribute !== false) {
-        target.setAttribute(attribute, options.name);
-    }
-    if (options.colorScheme && options.setColorScheme !== false) {
-        target.style.colorScheme = options.colorScheme;
-    }
-    return config;
-};
-exports.applyTheme = applyTheme;
-const getSystemThemeMode = () => {
-    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
-        return 'dark';
-    }
-    return window.matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark';
-};
-exports.getSystemThemeMode = getSystemThemeMode;
-/**
- * Follow `prefers-color-scheme` and apply the provided themes.
- *
- * This package does NOT ship a light theme preset; you supply both themes.
- * Returns a cleanup function to remove the media query listener.
- */
-const followSystemTheme = (themes, options = {}) => {
-    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
-        return () => { };
-    }
-    const media = window.matchMedia('(prefers-color-scheme: light)');
-    const apply = () => {
-        const mode = media.matches ? 'light' : 'dark';
-        const theme = mode === 'light' ? themes.light : themes.dark;
-        (0, exports.applyTheme)(theme, {
-            ...options,
-            name: mode === 'light' ? (options.lightName ?? 'light') : (options.darkName ?? 'dark'),
-            colorScheme: mode
-        });
-    };
-    apply();
-    media.addEventListener('change', apply);
-    return () => media.removeEventListener('change', apply);
-};
-exports.followSystemTheme = followSystemTheme;