@coxwave/tap-kit 2.0.0 → 2.0.2

package/dist/react.d.cts

@@ -1,57 +1,201 @@
-import { TapKitConfig, TapKitElement } from '@coxwave/tap-kit-types';
+import { TapKitElement } from '@coxwave/tap-kit-types';
+import React from 'react';
 
 /**
- * useTapKit Hook - Advanced imperative control of TapKit Web Component
+ * React-specific type definitions for TapKit
  *
- * This hook provides direct access to the TapKitElement instance and full
- * control over its lifecycle. Use this when you need:
- * - Direct element manipulation
- * - Custom rendering logic
- * - Imperative control over Web Component behavior
+ * Defines event handler types and control patterns for React integration.
+ */
+
+/**
+ * Event handler type definitions for TapKit Web Component
+ *
+ * Maps CustomEvent types to React callback signatures.
+ */
+interface TapKitEventHandlers {
+    /**
+     * Called when TapKit SDK is ready
+     * @example onReady={() => console.log('TapKit ready!')}
+     */
+    onReady?: () => void;
+    /**
+     * Called when initialization or runtime error occurs
+     * @example onError={(error) => console.error('TapKit error:', error)}
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Called when timeline seek event occurs
+     * @example onTimelineSeek={(clipPlayHead, clipId) => console.log('Seek:', clipPlayHead)}
+     */
+    onTimelineSeek?: (clipPlayHead: number, clipId: string) => void;
+    /**
+     * Called when alarm fade-in occurs
+     * @example onAlarmFadeIn={(messageInfo) => console.log('Alarm:', messageInfo)}
+     */
+    onAlarmFadeIn?: (messageInfo: unknown) => void;
+}
+/**
+ * Control object pattern for managing TapKit instance
  *
- * For most use cases, prefer the `<TapKit />` component which provides a
- * simpler declarative API.
+ * Separates instance management (setInstance) from configuration (options)
+ * and event handling (handlers). Inspired by ChatKit's control pattern.
+ *
+ * @example
+ * ```tsx
+ * const tapkit = useTapKit({ apiKey: 'key', onReady: () => {} });
+ * <TapKit control={tapkit.control} />
+ * ```
+ */
+interface TapKitControl<T> {
+    /**
+     * Set the TapKit element instance reference
+     *
+     * Called by TapKit component to register the element instance.
+     * Enables imperative control via useTapKit methods.
+     */
+    setInstance: (instance: TapKitElement | null) => void;
+    /**
+     * Configuration options (non-function values)
+     *
+     * All options except event handlers.
+     */
+    options: T;
+    /**
+     * Event handler callbacks (function values)
+     *
+     * Separated from options for easier event listener management.
+     */
+    handlers: TapKitEventHandlers;
+    /**
+     * Whether CDN is loaded and Web Component is available
+     *
+     * @internal Used by TapKit component to delay rendering
+     */
+    isCdnLoaded: boolean;
+}
+
+/**
+ * TapKit React Component
  *
- * @param options - TapKit configuration
- * @returns Object with element reference, state, and control methods
+ * Declarative React wrapper for <tap-kit> Web Component.
+ * Use this with useTapKit hook for a clean separation of control and rendering.
  *
- * @example Advanced control with custom rendering
+ * @example
  * ```tsx
  * 'use client';
  *
- * import { useTapKit } from '@coxwave/tap-kit/react';
+ * import { TapKit, useTapKit } from '@coxwave/tap-kit/react';
  *
- * function MyComponent() {
- *   const { element, elementRef, show, hide, isReady, error } = useTapKit({
+ * function MyApp() {
+ *   const tapkit = useTapKit({
  *     apiKey: 'your-key',
  *     userId: 'user-123',
  *     courseId: 'course-456',
  *     clipId: 'clip-789',
+ *     onReady: () => console.log('TapKit ready!'),
+ *     onError: (error) => console.error('Error:', error),
  *   });
  *
- *   // Direct element access for advanced operations
- *   useEffect(() => {
- *     if (element) {
- *       // Direct manipulation of TapKitElement
- *       console.log('Element mounted:', element);
- *     }
- *   }, [element]);
- *
  *   return (
  *     <div>
- *       <button onClick={show} disabled={!isReady}>Show Chat</button>
- *       <button onClick={hide}>Hide Chat</button>
- *       {error && <p>Error: {error.message}</p>}
- *       <div ref={elementRef} /> // Container for Web Component
+ *       <button onClick={tapkit.show} disabled={!tapkit.isReady}>
+ *         Show Chat
+ *       </button>
+ *       <TapKit control={tapkit.control} style={{ height: '600px' }} />
  *     </div>
  *   );
  * }
  * ```
  *
- * @see TapKit - Use this component for simpler declarative API
+ * **Note for Next.js App Router users:**
+ * Make sure to add 'use client' at the top of your component file.
+ *
+ * @see https://edutap-ai-docs.vercel.app/docs/guides/react
  */
 
-interface UseTapKitOptions extends TapKitConfig {
+/**
+ * Props for TapKit React component
+ */
+interface TapKitProps extends Omit<React.HTMLAttributes<TapKitElement>, "children" | "dangerouslySetInnerHTML"> {
+    /**
+     * Control object from useTapKit hook
+     *
+     * Provides instance management, configuration, and event handlers.
+     */
+    control: TapKitControl<any>;
+}
+declare global {
+    namespace JSX {
+        interface IntrinsicElements {
+            "tap-kit": React.DetailedHTMLProps<React.HTMLAttributes<TapKitElement>, TapKitElement> & {
+                "api-key"?: string;
+                "user-id"?: string;
+                "course-id"?: string;
+                "clip-id"?: string;
+                "clip-play-head"?: number;
+                language?: "ko" | "en";
+                "button-id"?: string;
+                mode?: "inline" | "floating" | "sidebar";
+                debug?: boolean;
+                "tap-url"?: string;
+                "api-url"?: string;
+                environment?: "dev" | "prod" | "staging" | "demo";
+            };
+        }
+    }
+}
+/**
+ * TapKit React Component
+ *
+ * Renders <tap-kit> Web Component with React integration.
+ * Automatically manages instance lifecycle and event listeners.
+ *
+ * **Ref Access**: The forwarded ref provides direct access to the TapKitElement:
+ * ```tsx
+ * const tapkitRef = useRef<TapKitElement>(null);
+ * <TapKit ref={tapkitRef} control={...} />
+ * // tapkitRef.current?.show()
+ * ```
+ */
+declare const TapKit: React.ForwardRefExoticComponent<TapKitProps & React.RefAttributes<TapKitElement>>;
+
+/**
+ * useTapKit Hook - ChatKit-style control for TapKit Web Component
+ *
+ * This hook provides a control object to manage TapKit through the
+ * <TapKit /> component. Inspired by OpenAI's ChatKit pattern.
+ *
+ * @example
+ * ```tsx
+ * 'use client';
+ *
+ * import { TapKit, useTapKit } from '@coxwave/tap-kit/react';
+ *
+ * function MyApp() {
+ *   const tapkit = useTapKit({
+ *     apiKey: 'your-key',
+ *     userId: 'user-123',
+ *     courseId: 'course-456',
+ *     clipId: 'clip-789',
+ *     onReady: () => console.log('Ready!'),
+ *     onError: (error) => console.error(error),
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={tapkit.show} disabled={!tapkit.isReady}>
+ *         Ask AI Tutor
+ *       </button>
+ *       <TapKit control={tapkit.control} />
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+
+interface UseTapKitOptions extends TapKitEventHandlers {
+    /** API Key (required) */
+    apiKey: string;
     /** User ID */
     userId?: string;
     /** Course ID */
@@ -75,11 +219,13 @@ interface UseTapKitOptions extends TapKitConfig {
     /** Environment */
     environment?: "dev" | "prod" | "staging" | "demo";
 }
+/**
+ * Configuration options type (non-function values)
+ */
+type TapKitOptions = Omit<UseTapKitOptions, keyof TapKitEventHandlers>;
 interface UseTapKitReturn {
-    /** Web Component element reference */
-    element: TapKitElement | null;
-    /** Container ref to attach element */
-    elementRef: React.RefCallback<HTMLDivElement>;
+    /** Control object for <TapKit /> component */
+    control: TapKitControl<TapKitOptions>;
     /** Whether TapKit is ready */
     isReady: boolean;
     /** Error during initialization */
@@ -95,15 +241,23 @@ interface UseTapKitReturn {
         userId?: string;
         clipPlayHead?: number;
     }) => void;
+    /** Video adapter control */
+    video: {
+        /** Bind video player for timeline synchronization */
+        bind: (adapter: {
+            getCurrentTime: () => number;
+            setCurrentTime: (time: number) => void;
+        }, clipId: string) => void;
+        /** Unbind current video player */
+        unbind: () => void;
+    };
 }
 /**
- * Hook for managing TapKit Web Component
- *
- * Automatically loads CDN, creates Web Component, and provides control methods.
+ * Hook for managing TapKit Web Component (ChatKit Pattern)
  *
- * @param options - TapKit configuration
- * @returns Methods to control TapKit instance
+ * Returns a control object to pass to <TapKit /> component.
+ * The component handles rendering, this hook handles state and methods.
  */
 declare function useTapKit(options: UseTapKitOptions): UseTapKitReturn;
 
-export { type UseTapKitOptions, type UseTapKitReturn, useTapKit };
+export { TapKit, type TapKitControl, type TapKitEventHandlers, type TapKitProps, type UseTapKitOptions, type UseTapKitReturn, useTapKit };

package/dist/react.d.ts

@@ -1,57 +1,201 @@
-import { TapKitConfig, TapKitElement } from '@coxwave/tap-kit-types';
+import { TapKitElement } from '@coxwave/tap-kit-types';
+import React from 'react';
 
 /**
- * useTapKit Hook - Advanced imperative control of TapKit Web Component
+ * React-specific type definitions for TapKit
  *
- * This hook provides direct access to the TapKitElement instance and full
- * control over its lifecycle. Use this when you need:
- * - Direct element manipulation
- * - Custom rendering logic
- * - Imperative control over Web Component behavior
+ * Defines event handler types and control patterns for React integration.
+ */
+
+/**
+ * Event handler type definitions for TapKit Web Component
+ *
+ * Maps CustomEvent types to React callback signatures.
+ */
+interface TapKitEventHandlers {
+    /**
+     * Called when TapKit SDK is ready
+     * @example onReady={() => console.log('TapKit ready!')}
+     */
+    onReady?: () => void;
+    /**
+     * Called when initialization or runtime error occurs
+     * @example onError={(error) => console.error('TapKit error:', error)}
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Called when timeline seek event occurs
+     * @example onTimelineSeek={(clipPlayHead, clipId) => console.log('Seek:', clipPlayHead)}
+     */
+    onTimelineSeek?: (clipPlayHead: number, clipId: string) => void;
+    /**
+     * Called when alarm fade-in occurs
+     * @example onAlarmFadeIn={(messageInfo) => console.log('Alarm:', messageInfo)}
+     */
+    onAlarmFadeIn?: (messageInfo: unknown) => void;
+}
+/**
+ * Control object pattern for managing TapKit instance
  *
- * For most use cases, prefer the `<TapKit />` component which provides a
- * simpler declarative API.
+ * Separates instance management (setInstance) from configuration (options)
+ * and event handling (handlers). Inspired by ChatKit's control pattern.
+ *
+ * @example
+ * ```tsx
+ * const tapkit = useTapKit({ apiKey: 'key', onReady: () => {} });
+ * <TapKit control={tapkit.control} />
+ * ```
+ */
+interface TapKitControl<T> {
+    /**
+     * Set the TapKit element instance reference
+     *
+     * Called by TapKit component to register the element instance.
+     * Enables imperative control via useTapKit methods.
+     */
+    setInstance: (instance: TapKitElement | null) => void;
+    /**
+     * Configuration options (non-function values)
+     *
+     * All options except event handlers.
+     */
+    options: T;
+    /**
+     * Event handler callbacks (function values)
+     *
+     * Separated from options for easier event listener management.
+     */
+    handlers: TapKitEventHandlers;
+    /**
+     * Whether CDN is loaded and Web Component is available
+     *
+     * @internal Used by TapKit component to delay rendering
+     */
+    isCdnLoaded: boolean;
+}
+
+/**
+ * TapKit React Component
  *
- * @param options - TapKit configuration
- * @returns Object with element reference, state, and control methods
+ * Declarative React wrapper for <tap-kit> Web Component.
+ * Use this with useTapKit hook for a clean separation of control and rendering.
  *
- * @example Advanced control with custom rendering
+ * @example
  * ```tsx
  * 'use client';
  *
- * import { useTapKit } from '@coxwave/tap-kit/react';
+ * import { TapKit, useTapKit } from '@coxwave/tap-kit/react';
  *
- * function MyComponent() {
- *   const { element, elementRef, show, hide, isReady, error } = useTapKit({
+ * function MyApp() {
+ *   const tapkit = useTapKit({
  *     apiKey: 'your-key',
  *     userId: 'user-123',
  *     courseId: 'course-456',
  *     clipId: 'clip-789',
+ *     onReady: () => console.log('TapKit ready!'),
+ *     onError: (error) => console.error('Error:', error),
  *   });
  *
- *   // Direct element access for advanced operations
- *   useEffect(() => {
- *     if (element) {
- *       // Direct manipulation of TapKitElement
- *       console.log('Element mounted:', element);
- *     }
- *   }, [element]);
- *
  *   return (
  *     <div>
- *       <button onClick={show} disabled={!isReady}>Show Chat</button>
- *       <button onClick={hide}>Hide Chat</button>
- *       {error && <p>Error: {error.message}</p>}
- *       <div ref={elementRef} /> // Container for Web Component
+ *       <button onClick={tapkit.show} disabled={!tapkit.isReady}>
+ *         Show Chat
+ *       </button>
+ *       <TapKit control={tapkit.control} style={{ height: '600px' }} />
  *     </div>
  *   );
  * }
  * ```
  *
- * @see TapKit - Use this component for simpler declarative API
+ * **Note for Next.js App Router users:**
+ * Make sure to add 'use client' at the top of your component file.
+ *
+ * @see https://edutap-ai-docs.vercel.app/docs/guides/react
  */
 
-interface UseTapKitOptions extends TapKitConfig {
+/**
+ * Props for TapKit React component
+ */
+interface TapKitProps extends Omit<React.HTMLAttributes<TapKitElement>, "children" | "dangerouslySetInnerHTML"> {
+    /**
+     * Control object from useTapKit hook
+     *
+     * Provides instance management, configuration, and event handlers.
+     */
+    control: TapKitControl<any>;
+}
+declare global {
+    namespace JSX {
+        interface IntrinsicElements {
+            "tap-kit": React.DetailedHTMLProps<React.HTMLAttributes<TapKitElement>, TapKitElement> & {
+                "api-key"?: string;
+                "user-id"?: string;
+                "course-id"?: string;
+                "clip-id"?: string;
+                "clip-play-head"?: number;
+                language?: "ko" | "en";
+                "button-id"?: string;
+                mode?: "inline" | "floating" | "sidebar";
+                debug?: boolean;
+                "tap-url"?: string;
+                "api-url"?: string;
+                environment?: "dev" | "prod" | "staging" | "demo";
+            };
+        }
+    }
+}
+/**
+ * TapKit React Component
+ *
+ * Renders <tap-kit> Web Component with React integration.
+ * Automatically manages instance lifecycle and event listeners.
+ *
+ * **Ref Access**: The forwarded ref provides direct access to the TapKitElement:
+ * ```tsx
+ * const tapkitRef = useRef<TapKitElement>(null);
+ * <TapKit ref={tapkitRef} control={...} />
+ * // tapkitRef.current?.show()
+ * ```
+ */
+declare const TapKit: React.ForwardRefExoticComponent<TapKitProps & React.RefAttributes<TapKitElement>>;
+
+/**
+ * useTapKit Hook - ChatKit-style control for TapKit Web Component
+ *
+ * This hook provides a control object to manage TapKit through the
+ * <TapKit /> component. Inspired by OpenAI's ChatKit pattern.
+ *
+ * @example
+ * ```tsx
+ * 'use client';
+ *
+ * import { TapKit, useTapKit } from '@coxwave/tap-kit/react';
+ *
+ * function MyApp() {
+ *   const tapkit = useTapKit({
+ *     apiKey: 'your-key',
+ *     userId: 'user-123',
+ *     courseId: 'course-456',
+ *     clipId: 'clip-789',
+ *     onReady: () => console.log('Ready!'),
+ *     onError: (error) => console.error(error),
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={tapkit.show} disabled={!tapkit.isReady}>
+ *         Ask AI Tutor
+ *       </button>
+ *       <TapKit control={tapkit.control} />
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+
+interface UseTapKitOptions extends TapKitEventHandlers {
+    /** API Key (required) */
+    apiKey: string;
     /** User ID */
     userId?: string;
     /** Course ID */
@@ -75,11 +219,13 @@ interface UseTapKitOptions extends TapKitConfig {
     /** Environment */
     environment?: "dev" | "prod" | "staging" | "demo";
 }
+/**
+ * Configuration options type (non-function values)
+ */
+type TapKitOptions = Omit<UseTapKitOptions, keyof TapKitEventHandlers>;
 interface UseTapKitReturn {
-    /** Web Component element reference */
-    element: TapKitElement | null;
-    /** Container ref to attach element */
-    elementRef: React.RefCallback<HTMLDivElement>;
+    /** Control object for <TapKit /> component */
+    control: TapKitControl<TapKitOptions>;
     /** Whether TapKit is ready */
     isReady: boolean;
     /** Error during initialization */
@@ -95,15 +241,23 @@ interface UseTapKitReturn {
         userId?: string;
         clipPlayHead?: number;
     }) => void;
+    /** Video adapter control */
+    video: {
+        /** Bind video player for timeline synchronization */
+        bind: (adapter: {
+            getCurrentTime: () => number;
+            setCurrentTime: (time: number) => void;
+        }, clipId: string) => void;
+        /** Unbind current video player */
+        unbind: () => void;
+    };
 }
 /**
- * Hook for managing TapKit Web Component
- *
- * Automatically loads CDN, creates Web Component, and provides control methods.
+ * Hook for managing TapKit Web Component (ChatKit Pattern)
  *
- * @param options - TapKit configuration
- * @returns Methods to control TapKit instance
+ * Returns a control object to pass to <TapKit /> component.
+ * The component handles rendering, this hook handles state and methods.
  */
 declare function useTapKit(options: UseTapKitOptions): UseTapKitReturn;
 
-export { type UseTapKitOptions, type UseTapKitReturn, useTapKit };
+export { TapKit, type TapKitControl, type TapKitEventHandlers, type TapKitProps, type UseTapKitOptions, type UseTapKitReturn, useTapKit };