@easemate/web-kit 0.1.4 → 0.2.0

package/build/react/provider.js

@@ -0,0 +1,98 @@
+/**
+ * React context provider for @easemate/web-kit
+ *
+ * This module provides a simple way to initialize the web kit in a React context.
+ * For simpler use cases, consider using `initWebKit()` directly in a useEffect.
+ */
+/**
+ * Creates a WebKit provider and context hook.
+ *
+ * This function creates a React context and provider component
+ * that initializes the web kit and provides access to its state.
+ *
+ * @example
+ * ```tsx
+ * // providers.tsx
+ * 'use client';
+ *
+ * import * as React from '../react';
+ * import { createWebKitProvider } from '@easemate/web-kit/react';
+ *
+ * const { WebKitProvider, useWebKitContext } = createWebKitProvider(React);
+ *
+ * export { WebKitProvider, useWebKitContext };
+ *
+ * // layout.tsx
+ * import { WebKitProvider } from './providers';
+ *
+ * export default function Layout({ children }) {
+ *   return (
+ *     <WebKitProvider options={{ theme: 'default', styles: 'main' }}>
+ *       {children}
+ *     </WebKitProvider>
+ *   );
+ * }
+ * ```
+ */
+export function createWebKitProvider(React) {
+    const defaultValue = {
+        ready: false,
+        theme: undefined
+    };
+    const WebKitContext = React.createContext(defaultValue);
+    function WebKitProvider(props) {
+        const { options = {}, immediate = true, children } = props;
+        const isSSR = typeof window === 'undefined';
+        const { useState, useEffect, useMemo, createElement } = React;
+        const [ready, setReady] = useState(false);
+        const [controller, setController] = useState(null);
+        useEffect(() => {
+            // Skip initialization on SSR
+            if (isSSR) {
+                return;
+            }
+            let isMounted = true;
+            const initialize = async () => {
+                const { initWebKit } = await import('../init');
+                const ctrl = initWebKit(options);
+                if (isMounted) {
+                    setController(ctrl);
+                }
+                await ctrl.ready;
+                if (isMounted) {
+                    setReady(true);
+                }
+            };
+            initialize();
+            return () => {
+                isMounted = false;
+                controller?.dispose();
+                return undefined;
+            };
+        }, []);
+        const value = useMemo(() => {
+            return {
+                ready,
+                theme: controller?.theme
+            };
+        }, [ready, controller]);
+        // On SSR, just render children directly
+        if (isSSR) {
+            return children;
+        }
+        // Don't render children until ready if immediate is false
+        if (!immediate && !ready) {
+            return null;
+        }
+        return createElement(WebKitContext.Provider, { value }, children);
+    }
+    function useWebKitContext() {
+        const context = React.useContext(WebKitContext);
+        // On SSR, context will be the default value anyway
+        return context;
+    }
+    return {
+        WebKitProvider,
+        useWebKitContext
+    };
+}

package/build/react/types.cjs

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * React type definitions for @easemate/web-kit
+ *
+ * These types are provided for consumers using React/Next.js with this library.
+ * React is NOT a dependency of this package - these are interface definitions only.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/react/types.d.cts

@@ -0,0 +1,55 @@
+/**
+ * React type definitions for @easemate/web-kit
+ *
+ * These types are provided for consumers using React/Next.js with this library.
+ * React is NOT a dependency of this package - these are interface definitions only.
+ */
+import type { TabChangeEventDetail } from '../elements/panel';
+import type { StateChangeEventDetail } from '../elements/state';
+/**
+ * Ref type for the ease-state web component
+ */
+export interface EaseStateRef extends HTMLElement {
+    /** Get the current state object */
+    readonly state: Record<string, unknown>;
+    /** Get a specific control value */
+    get(name: string): unknown;
+    /** Set a specific control value */
+    set(name: string, value: unknown): void;
+    /** Subscribe to state changes */
+    subscribe(callback: (value: unknown, name: string) => void): {
+        unsubscribe: () => void;
+    };
+    subscribe(name: string, callback: (value: unknown, name: string) => void): {
+        unsubscribe: () => void;
+    };
+    /** Reset all controls to initial values */
+    reset(): void;
+}
+/**
+ * Ref type for the ease-panel web component
+ */
+export interface EasePanelRef extends HTMLElement {
+    /** Current active tab index */
+    activeTab: number;
+    /** Get the tab configuration */
+    readonly tabs: ReadonlyArray<{
+        id: string;
+        label: string;
+    }>;
+    /** Switch to a specific tab */
+    setTab(index: number): void;
+}
+/**
+ * Event detail types re-exported for React usage
+ */
+export type { StateChangeEventDetail, TabChangeEventDetail };
+/**
+ * Generic control element interface
+ */
+export interface EaseControlElement extends HTMLElement {
+    name?: string;
+    value?: unknown;
+    checked?: boolean;
+    disabled?: boolean;
+}

package/build/react/types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * React type definitions for @easemate/web-kit
+ *
+ * These types are provided for consumers using React/Next.js with this library.
+ * React is NOT a dependency of this package - these are interface definitions only.
+ */
+import type { TabChangeEventDetail } from '../elements/panel';
+import type { StateChangeEventDetail } from '../elements/state';
+/**
+ * Ref type for the ease-state web component
+ */
+export interface EaseStateRef extends HTMLElement {
+    /** Get the current state object */
+    readonly state: Record<string, unknown>;
+    /** Get a specific control value */
+    get(name: string): unknown;
+    /** Set a specific control value */
+    set(name: string, value: unknown): void;
+    /** Subscribe to state changes */
+    subscribe(callback: (value: unknown, name: string) => void): {
+        unsubscribe: () => void;
+    };
+    subscribe(name: string, callback: (value: unknown, name: string) => void): {
+        unsubscribe: () => void;
+    };
+    /** Reset all controls to initial values */
+    reset(): void;
+}
+/**
+ * Ref type for the ease-panel web component
+ */
+export interface EasePanelRef extends HTMLElement {
+    /** Current active tab index */
+    activeTab: number;
+    /** Get the tab configuration */
+    readonly tabs: ReadonlyArray<{
+        id: string;
+        label: string;
+    }>;
+    /** Switch to a specific tab */
+    setTab(index: number): void;
+}
+/**
+ * Event detail types re-exported for React usage
+ */
+export type { StateChangeEventDetail, TabChangeEventDetail };
+/**
+ * Generic control element interface
+ */
+export interface EaseControlElement extends HTMLElement {
+    name?: string;
+    value?: unknown;
+    checked?: boolean;
+    disabled?: boolean;
+}

package/build/react/types.js

@@ -0,0 +1,7 @@
+/**
+ * React type definitions for @easemate/web-kit
+ *
+ * These types are provided for consumers using React/Next.js with this library.
+ * React is NOT a dependency of this package - these are interface definitions only.
+ */
+export {};

package/build/react/use-ease-state.cjs

@@ -0,0 +1,129 @@
+"use strict";
+/**
+ * React hook for working with ease-state component
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useEaseState = useEaseState;
+/**
+ * React hook for working with ease-state components.
+ *
+ * Provides a reactive state object and methods for interacting
+ * with the ease-state web component.
+ *
+ * @example
+ * ```tsx
+ * import { useState, useCallback, useRef } from '../react';
+ * import { useEaseState } from '@easemate/web-kit/react';
+ *
+ * function AnimationControls() {
+ *   const {
+ *     stateRef,
+ *     panelRef,
+ *     state,
+ *     set,
+ *     reset
+ *   } = useEaseState<{ duration: number; easing: string; loop: boolean }>(
+ *     {
+ *       onChange: ({ name, value }) => {
+ *         console.log(`${name} changed to ${value}`);
+ *       }
+ *     },
+ *     { useState, useCallback, useRef }
+ *   );
+ *
+ *   return (
+ *     <ease-panel ref={panelRef}>
+ *       <span slot="headline">Animation</span>
+ *       <ease-state ref={stateRef}>
+ *         <ease-field label="Duration">
+ *           <ease-slider name="duration" value="1" min="0" max="5" />
+ *         </ease-field>
+ *       </ease-state>
+ *     </ease-panel>
+ *   );
+ * }
+ * ```
+ */
+function useEaseState(options, hooks) {
+    const { useState, useCallback, useRef } = hooks;
+    const { initialState, onChange, onTabChange } = options;
+    const stateElementRef = useRef(null);
+    const panelElementRef = useRef(null);
+    const [state, setState] = useState((initialState ?? {}));
+    const [activeTab, setActiveTab] = useState(0);
+    // Handle state changes
+    const handleStateChange = useCallback((e) => {
+        const customEvent = e;
+        const { name, value } = customEvent.detail;
+        setState((prev) => {
+            return { ...prev, [name]: value };
+        });
+        onChange?.(customEvent.detail);
+    }, [onChange]);
+    // Handle tab changes
+    const handleTabChange = useCallback((e) => {
+        const customEvent = e;
+        setActiveTab(customEvent.detail.index);
+        onTabChange?.(customEvent.detail);
+    }, [onTabChange]);
+    // Ref callback for the ease-state element
+    const stateRef = useCallback((element) => {
+        // Cleanup previous element
+        if (stateElementRef.current) {
+            stateElementRef.current.removeEventListener('state-change', handleStateChange);
+        }
+        stateElementRef.current = element;
+        if (element) {
+            // Add event listeners
+            element.addEventListener('state-change', handleStateChange);
+            // Set initial state values
+            if (initialState) {
+                for (const [name, value] of Object.entries(initialState)) {
+                    element.set(name, value);
+                }
+            }
+            // Sync current state from element
+            const currentState = element.state;
+            if (Object.keys(currentState).length > 0) {
+                setState(currentState);
+            }
+        }
+    }, [handleStateChange, initialState]);
+    // Ref callback for the ease-panel element
+    const panelRef = useCallback((element) => {
+        // Cleanup previous element
+        if (panelElementRef.current) {
+            panelElementRef.current.removeEventListener('tab-change', handleTabChange);
+        }
+        panelElementRef.current = element;
+        if (element) {
+            // Add event listeners
+            element.addEventListener('tab-change', handleTabChange);
+            setActiveTab(element.activeTab);
+        }
+    }, [handleTabChange]);
+    // Get a specific value
+    const get = useCallback((name) => state[name], [state]);
+    // Set a specific value
+    const set = useCallback((name, value) => {
+        stateElementRef.current?.set(name, value);
+    }, []);
+    // Reset all values
+    const reset = useCallback(() => {
+        stateElementRef.current?.reset();
+    }, []);
+    // Set active tab
+    const setTab = useCallback((index) => {
+        panelElementRef.current?.setTab(index);
+    }, []);
+    return {
+        stateRef,
+        panelRef,
+        state,
+        get,
+        set,
+        reset,
+        setTab,
+        activeTab
+    };
+}

package/build/react/use-ease-state.d.cts

@@ -0,0 +1,95 @@
+/**
+ * React hook for working with ease-state component
+ */
+import type { EasePanelRef, EaseStateRef, StateChangeEventDetail, TabChangeEventDetail } from "./types.cjs";
+/**
+ * Options for useEaseState hook
+ */
+export interface UseEaseStateOptions {
+    /**
+     * Initial state values to set when the component mounts
+     */
+    initialState?: Record<string, unknown>;
+    /**
+     * Callback fired when any control value changes
+     */
+    onChange?: (detail: StateChangeEventDetail) => void;
+    /**
+     * Callback fired when the active tab changes (requires ease-panel)
+     */
+    onTabChange?: (detail: TabChangeEventDetail) => void;
+}
+type AnyFunction = (...args: any[]) => any;
+/**
+ * React hooks interface - compatible with React's hook signatures
+ */
+export interface ReactHooksLike {
+    useState: <S>(initial: S) => [S, (value: S | ((prev: S) => S)) => void];
+    useCallback: <F extends AnyFunction>(callback: F, deps: unknown[]) => F;
+    useRef: <R>(initial: R) => {
+        current: R;
+    };
+}
+/**
+ * Return type for useEaseState hook
+ */
+export interface UseEaseStateReturn<T extends Record<string, unknown> = Record<string, unknown>> {
+    /** Ref callback to attach to the ease-state element */
+    stateRef: (element: EaseStateRef | null) => void;
+    /** Ref callback to attach to the ease-panel element (optional) */
+    panelRef: (element: EasePanelRef | null) => void;
+    /** Current state values (reactive) */
+    state: T;
+    /** Get a specific control value */
+    get: <K extends keyof T>(name: K) => T[K] | undefined;
+    /** Set a specific control value */
+    set: <K extends keyof T>(name: K, value: T[K]) => void;
+    /** Reset all controls to initial values */
+    reset: () => void;
+    /** Switch to a specific tab (requires ease-panel) */
+    setTab: (index: number) => void;
+    /** Current active tab index (requires ease-panel) */
+    activeTab: number;
+}
+/**
+ * React hook for working with ease-state components.
+ *
+ * Provides a reactive state object and methods for interacting
+ * with the ease-state web component.
+ *
+ * @example
+ * ```tsx
+ * import { useState, useCallback, useRef } from '../react';
+ * import { useEaseState } from '@easemate/web-kit/react';
+ *
+ * function AnimationControls() {
+ *   const {
+ *     stateRef,
+ *     panelRef,
+ *     state,
+ *     set,
+ *     reset
+ *   } = useEaseState<{ duration: number; easing: string; loop: boolean }>(
+ *     {
+ *       onChange: ({ name, value }) => {
+ *         console.log(`${name} changed to ${value}`);
+ *       }
+ *     },
+ *     { useState, useCallback, useRef }
+ *   );
+ *
+ *   return (
+ *     <ease-panel ref={panelRef}>
+ *       <span slot="headline">Animation</span>
+ *       <ease-state ref={stateRef}>
+ *         <ease-field label="Duration">
+ *           <ease-slider name="duration" value="1" min="0" max="5" />
+ *         </ease-field>
+ *       </ease-state>
+ *     </ease-panel>
+ *   );
+ * }
+ * ```
+ */
+export declare function useEaseState<T extends Record<string, unknown> = Record<string, unknown>>(options: UseEaseStateOptions, hooks: ReactHooksLike): UseEaseStateReturn<T>;
+export {};

package/build/react/use-ease-state.d.ts

@@ -0,0 +1,95 @@
+/**
+ * React hook for working with ease-state component
+ */
+import type { EasePanelRef, EaseStateRef, StateChangeEventDetail, TabChangeEventDetail } from "./types.js";
+/**
+ * Options for useEaseState hook
+ */
+export interface UseEaseStateOptions {
+    /**
+     * Initial state values to set when the component mounts
+     */
+    initialState?: Record<string, unknown>;
+    /**
+     * Callback fired when any control value changes
+     */
+    onChange?: (detail: StateChangeEventDetail) => void;
+    /**
+     * Callback fired when the active tab changes (requires ease-panel)
+     */
+    onTabChange?: (detail: TabChangeEventDetail) => void;
+}
+type AnyFunction = (...args: any[]) => any;
+/**
+ * React hooks interface - compatible with React's hook signatures
+ */
+export interface ReactHooksLike {
+    useState: <S>(initial: S) => [S, (value: S | ((prev: S) => S)) => void];
+    useCallback: <F extends AnyFunction>(callback: F, deps: unknown[]) => F;
+    useRef: <R>(initial: R) => {
+        current: R;
+    };
+}
+/**
+ * Return type for useEaseState hook
+ */
+export interface UseEaseStateReturn<T extends Record<string, unknown> = Record<string, unknown>> {
+    /** Ref callback to attach to the ease-state element */
+    stateRef: (element: EaseStateRef | null) => void;
+    /** Ref callback to attach to the ease-panel element (optional) */
+    panelRef: (element: EasePanelRef | null) => void;
+    /** Current state values (reactive) */
+    state: T;
+    /** Get a specific control value */
+    get: <K extends keyof T>(name: K) => T[K] | undefined;
+    /** Set a specific control value */
+    set: <K extends keyof T>(name: K, value: T[K]) => void;
+    /** Reset all controls to initial values */
+    reset: () => void;
+    /** Switch to a specific tab (requires ease-panel) */
+    setTab: (index: number) => void;
+    /** Current active tab index (requires ease-panel) */
+    activeTab: number;
+}
+/**
+ * React hook for working with ease-state components.
+ *
+ * Provides a reactive state object and methods for interacting
+ * with the ease-state web component.
+ *
+ * @example
+ * ```tsx
+ * import { useState, useCallback, useRef } from '../react';
+ * import { useEaseState } from '@easemate/web-kit/react';
+ *
+ * function AnimationControls() {
+ *   const {
+ *     stateRef,
+ *     panelRef,
+ *     state,
+ *     set,
+ *     reset
+ *   } = useEaseState<{ duration: number; easing: string; loop: boolean }>(
+ *     {
+ *       onChange: ({ name, value }) => {
+ *         console.log(`${name} changed to ${value}`);
+ *       }
+ *     },
+ *     { useState, useCallback, useRef }
+ *   );
+ *
+ *   return (
+ *     <ease-panel ref={panelRef}>
+ *       <span slot="headline">Animation</span>
+ *       <ease-state ref={stateRef}>
+ *         <ease-field label="Duration">
+ *           <ease-slider name="duration" value="1" min="0" max="5" />
+ *         </ease-field>
+ *       </ease-state>
+ *     </ease-panel>
+ *   );
+ * }
+ * ```
+ */
+export declare function useEaseState<T extends Record<string, unknown> = Record<string, unknown>>(options: UseEaseStateOptions, hooks: ReactHooksLike): UseEaseStateReturn<T>;
+export {};

package/build/react/use-ease-state.js

@@ -0,0 +1,126 @@
+/**
+ * React hook for working with ease-state component
+ */
+/**
+ * React hook for working with ease-state components.
+ *
+ * Provides a reactive state object and methods for interacting
+ * with the ease-state web component.
+ *
+ * @example
+ * ```tsx
+ * import { useState, useCallback, useRef } from '../react';
+ * import { useEaseState } from '@easemate/web-kit/react';
+ *
+ * function AnimationControls() {
+ *   const {
+ *     stateRef,
+ *     panelRef,
+ *     state,
+ *     set,
+ *     reset
+ *   } = useEaseState<{ duration: number; easing: string; loop: boolean }>(
+ *     {
+ *       onChange: ({ name, value }) => {
+ *         console.log(`${name} changed to ${value}`);
+ *       }
+ *     },
+ *     { useState, useCallback, useRef }
+ *   );
+ *
+ *   return (
+ *     <ease-panel ref={panelRef}>
+ *       <span slot="headline">Animation</span>
+ *       <ease-state ref={stateRef}>
+ *         <ease-field label="Duration">
+ *           <ease-slider name="duration" value="1" min="0" max="5" />
+ *         </ease-field>
+ *       </ease-state>
+ *     </ease-panel>
+ *   );
+ * }
+ * ```
+ */
+export function useEaseState(options, hooks) {
+    const { useState, useCallback, useRef } = hooks;
+    const { initialState, onChange, onTabChange } = options;
+    const stateElementRef = useRef(null);
+    const panelElementRef = useRef(null);
+    const [state, setState] = useState((initialState ?? {}));
+    const [activeTab, setActiveTab] = useState(0);
+    // Handle state changes
+    const handleStateChange = useCallback((e) => {
+        const customEvent = e;
+        const { name, value } = customEvent.detail;
+        setState((prev) => {
+            return { ...prev, [name]: value };
+        });
+        onChange?.(customEvent.detail);
+    }, [onChange]);
+    // Handle tab changes
+    const handleTabChange = useCallback((e) => {
+        const customEvent = e;
+        setActiveTab(customEvent.detail.index);
+        onTabChange?.(customEvent.detail);
+    }, [onTabChange]);
+    // Ref callback for the ease-state element
+    const stateRef = useCallback((element) => {
+        // Cleanup previous element
+        if (stateElementRef.current) {
+            stateElementRef.current.removeEventListener('state-change', handleStateChange);
+        }
+        stateElementRef.current = element;
+        if (element) {
+            // Add event listeners
+            element.addEventListener('state-change', handleStateChange);
+            // Set initial state values
+            if (initialState) {
+                for (const [name, value] of Object.entries(initialState)) {
+                    element.set(name, value);
+                }
+            }
+            // Sync current state from element
+            const currentState = element.state;
+            if (Object.keys(currentState).length > 0) {
+                setState(currentState);
+            }
+        }
+    }, [handleStateChange, initialState]);
+    // Ref callback for the ease-panel element
+    const panelRef = useCallback((element) => {
+        // Cleanup previous element
+        if (panelElementRef.current) {
+            panelElementRef.current.removeEventListener('tab-change', handleTabChange);
+        }
+        panelElementRef.current = element;
+        if (element) {
+            // Add event listeners
+            element.addEventListener('tab-change', handleTabChange);
+            setActiveTab(element.activeTab);
+        }
+    }, [handleTabChange]);
+    // Get a specific value
+    const get = useCallback((name) => state[name], [state]);
+    // Set a specific value
+    const set = useCallback((name, value) => {
+        stateElementRef.current?.set(name, value);
+    }, []);
+    // Reset all values
+    const reset = useCallback(() => {
+        stateElementRef.current?.reset();
+    }, []);
+    // Set active tab
+    const setTab = useCallback((index) => {
+        panelElementRef.current?.setTab(index);
+    }, []);
+    return {
+        stateRef,
+        panelRef,
+        state,
+        get,
+        set,
+        reset,
+        setTab,
+        activeTab
+    };
+}