@easemate/web-kit 0.2.0 → 0.3.0

package/build/react.d.cts

@@ -0,0 +1,356 @@
+import { T as TabChangeEventDetail } from './index-NzGpn7ai.cjs';
+import { C as ControlEventDetail, S as StateChangeEventDetail } from './index-qZoNKsHn.cjs';
+export { ButtonElement, ButtonProps, CheckboxElement, CheckboxProps, CodeProps, ColorInputElement, ColorInputProps, ControlEventDetail, CurveElement, CurveProps, DropdownElement, DropdownProps, EaseElements, FieldElement, FieldProps, InputElement, InputProps, LogoLoaderProps, MonitorFpsProps, MonitorProps, NumberInputElement, NumberInputProps, OriginElement, OriginProps, PanelElement, PanelProps, PopoverElement, PopoverProps, RadioGroupElement, RadioGroupProps, RadioInputProps, SliderElement, SliderProps, StateElement, StateProps, TabChangeEventDetail, ToggleElement, ToggleProps, TooltipElement, TooltipProps, __JSX_TYPES_LOADED__ } from './jsx.cjs';
+import { I as InitWebKitOptions, d as WebKitController } from './init-DwVGVxkx.cjs';
+import 'lit-html';
+import './registry-9GX9KTG1.cjs';
+
+/**
+ * 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.
+ */
+
+/**
+ * Ref type for the ease-state web component
+ */
+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
+ */
+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;
+}
+
+/**
+ * Generic control element interface
+ */
+interface EaseControlElement extends HTMLElement {
+    name?: string;
+    value?: unknown;
+    checked?: boolean;
+    disabled?: boolean;
+}
+
+/**
+ * React event handling utilities for @easemate/web-kit
+ */
+
+/**
+ * Control change event type for React
+ */
+interface ControlChangeEvent<T = unknown> extends CustomEvent<ControlEventDetail<T>> {
+    detail: ControlEventDetail<T>;
+}
+/**
+ * State change event type for React
+ */
+interface StateChangeEvent extends CustomEvent<StateChangeEventDetail> {
+    detail: StateChangeEventDetail;
+}
+/**
+ * Tab change event type for React
+ */
+interface TabChangeEvent extends CustomEvent<TabChangeEventDetail> {
+    detail: TabChangeEventDetail;
+}
+/**
+ * Creates a type-safe event handler for control-change events.
+ *
+ * @example
+ * ```tsx
+ * <ease-slider
+ *   name="opacity"
+ *   value={0.5}
+ *   onControlChange={createEventHandler<number>((value, name) => {
+ *     console.log(`${name} changed to ${value}`);
+ *   })}
+ * />
+ * ```
+ */
+declare function createEventHandler<T = unknown>(callback: (value: T, name: string | undefined, event: Event) => void): (e: CustomEvent<ControlEventDetail<T>>) => void;
+
+/**
+ * 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.
+ */
+
+/**
+ * WebKit context value
+ */
+interface WebKitContextValue {
+    /** Whether the web kit is ready */
+    ready: boolean;
+    /** Theme controller */
+    theme?: WebKitController['theme'];
+}
+/**
+ * Props for createWebKitProvider
+ */
+interface WebKitProviderProps {
+    /** Initialization options */
+    options?: InitWebKitOptions;
+    /**
+     * Render children even before ready
+     * @default true
+     */
+    immediate?: boolean;
+}
+/**
+ * React hooks interface for provider creation
+ */
+interface ReactHooksForProvider {
+    useState: <S>(initial: S) => [S, (value: S) => void];
+    useEffect: (effect: () => (() => void) | undefined, deps?: unknown[]) => void;
+    useMemo: <T>(factory: () => T, deps: unknown[]) => T;
+    createContext: <T>(defaultValue: T) => {
+        Provider: unknown;
+        Consumer: unknown;
+    };
+    useContext: <T>(context: {
+        Provider: unknown;
+        Consumer: unknown;
+    }) => T;
+    createElement: (type: unknown, props: Record<string, unknown> | null, ...children: unknown[]) => unknown;
+}
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
+declare function createWebKitProvider(React: ReactHooksForProvider): {
+    WebKitProvider: (props: WebKitProviderProps & {
+        children: unknown;
+    }) => unknown;
+    useWebKitContext: () => WebKitContextValue;
+};
+
+/**
+ * React hook for working with ease-state component
+ */
+
+/**
+ * Options for useEaseState hook
+ */
+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
+ */
+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
+ */
+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>
+ *   );
+ * }
+ * ```
+ */
+declare function useEaseState<T extends Record<string, unknown> = Record<string, unknown>>(options: UseEaseStateOptions, hooks: ReactHooksLike): UseEaseStateReturn<T>;
+
+/**
+ * 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
+ */
+
+/**
+ * Options for useWebKit hook
+ */
+interface UseWebKitOptions extends InitWebKitOptions {
+    /**
+     * Skip initialization (useful for conditional rendering)
+     * @default false
+     */
+    skip?: boolean;
+}
+/**
+ * Return type for useWebKit hook
+ */
+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}</>;
+ * }
+ * ```
+ */
+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;
+
+export { type ControlChangeEvent, type EaseControlElement, type EasePanelRef, type EaseStateRef, type ReactHooksForProvider, type ReactHooksLike, type StateChangeEvent, StateChangeEventDetail, type TabChangeEvent, type UseEaseStateOptions, type UseEaseStateReturn, type UseWebKitOptions, type UseWebKitReturn, type WebKitContextValue, type WebKitProviderProps, createEventHandler, createWebKitProvider, useEaseState, useWebKit };

package/build/react.d.ts

@@ -0,0 +1,356 @@
+import { T as TabChangeEventDetail } from './index-NzGpn7ai.js';
+import { C as ControlEventDetail, S as StateChangeEventDetail } from './index-qZoNKsHn.js';
+export { ButtonElement, ButtonProps, CheckboxElement, CheckboxProps, CodeProps, ColorInputElement, ColorInputProps, ControlEventDetail, CurveElement, CurveProps, DropdownElement, DropdownProps, EaseElements, FieldElement, FieldProps, InputElement, InputProps, LogoLoaderProps, MonitorFpsProps, MonitorProps, NumberInputElement, NumberInputProps, OriginElement, OriginProps, PanelElement, PanelProps, PopoverElement, PopoverProps, RadioGroupElement, RadioGroupProps, RadioInputProps, SliderElement, SliderProps, StateElement, StateProps, TabChangeEventDetail, ToggleElement, ToggleProps, TooltipElement, TooltipProps, __JSX_TYPES_LOADED__ } from './jsx.js';
+import { I as InitWebKitOptions, d as WebKitController } from './init-B7gNNyTd.js';
+import 'lit-html';
+import './registry-9GX9KTG1.js';
+
+/**
+ * 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.
+ */
+
+/**
+ * Ref type for the ease-state web component
+ */
+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
+ */
+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;
+}
+
+/**
+ * Generic control element interface
+ */
+interface EaseControlElement extends HTMLElement {
+    name?: string;
+    value?: unknown;
+    checked?: boolean;
+    disabled?: boolean;
+}
+
+/**
+ * React event handling utilities for @easemate/web-kit
+ */
+
+/**
+ * Control change event type for React
+ */
+interface ControlChangeEvent<T = unknown> extends CustomEvent<ControlEventDetail<T>> {
+    detail: ControlEventDetail<T>;
+}
+/**
+ * State change event type for React
+ */
+interface StateChangeEvent extends CustomEvent<StateChangeEventDetail> {
+    detail: StateChangeEventDetail;
+}
+/**
+ * Tab change event type for React
+ */
+interface TabChangeEvent extends CustomEvent<TabChangeEventDetail> {
+    detail: TabChangeEventDetail;
+}
+/**
+ * Creates a type-safe event handler for control-change events.
+ *
+ * @example
+ * ```tsx
+ * <ease-slider
+ *   name="opacity"
+ *   value={0.5}
+ *   onControlChange={createEventHandler<number>((value, name) => {
+ *     console.log(`${name} changed to ${value}`);
+ *   })}
+ * />
+ * ```
+ */
+declare function createEventHandler<T = unknown>(callback: (value: T, name: string | undefined, event: Event) => void): (e: CustomEvent<ControlEventDetail<T>>) => void;
+
+/**
+ * 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.
+ */
+
+/**
+ * WebKit context value
+ */
+interface WebKitContextValue {
+    /** Whether the web kit is ready */
+    ready: boolean;
+    /** Theme controller */
+    theme?: WebKitController['theme'];
+}
+/**
+ * Props for createWebKitProvider
+ */
+interface WebKitProviderProps {
+    /** Initialization options */
+    options?: InitWebKitOptions;
+    /**
+     * Render children even before ready
+     * @default true
+     */
+    immediate?: boolean;
+}
+/**
+ * React hooks interface for provider creation
+ */
+interface ReactHooksForProvider {
+    useState: <S>(initial: S) => [S, (value: S) => void];
+    useEffect: (effect: () => (() => void) | undefined, deps?: unknown[]) => void;
+    useMemo: <T>(factory: () => T, deps: unknown[]) => T;
+    createContext: <T>(defaultValue: T) => {
+        Provider: unknown;
+        Consumer: unknown;
+    };
+    useContext: <T>(context: {
+        Provider: unknown;
+        Consumer: unknown;
+    }) => T;
+    createElement: (type: unknown, props: Record<string, unknown> | null, ...children: unknown[]) => unknown;
+}
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
+declare function createWebKitProvider(React: ReactHooksForProvider): {
+    WebKitProvider: (props: WebKitProviderProps & {
+        children: unknown;
+    }) => unknown;
+    useWebKitContext: () => WebKitContextValue;
+};
+
+/**
+ * React hook for working with ease-state component
+ */
+
+/**
+ * Options for useEaseState hook
+ */
+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
+ */
+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
+ */
+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>
+ *   );
+ * }
+ * ```
+ */
+declare function useEaseState<T extends Record<string, unknown> = Record<string, unknown>>(options: UseEaseStateOptions, hooks: ReactHooksLike): UseEaseStateReturn<T>;
+
+/**
+ * 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
+ */
+
+/**
+ * Options for useWebKit hook
+ */
+interface UseWebKitOptions extends InitWebKitOptions {
+    /**
+     * Skip initialization (useful for conditional rendering)
+     * @default false
+     */
+    skip?: boolean;
+}
+/**
+ * Return type for useWebKit hook
+ */
+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}</>;
+ * }
+ * ```
+ */
+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;
+
+export { type ControlChangeEvent, type EaseControlElement, type EasePanelRef, type EaseStateRef, type ReactHooksForProvider, type ReactHooksLike, type StateChangeEvent, StateChangeEventDetail, type TabChangeEvent, type UseEaseStateOptions, type UseEaseStateReturn, type UseWebKitOptions, type UseWebKitReturn, type WebKitContextValue, type WebKitProviderProps, createEventHandler, createWebKitProvider, useEaseState, useWebKit };