@coxwave/tap-kit 1.0.6 → 2.0.1

package/dist/react.d.ts

@@ -1,87 +1,277 @@
-import { TapKitInstance, TapKitInitParams, TapKitConfig, TapButtonAttributes } from '@coxwave/tap-kit-types';
+import { TapKitElement, TapKitConfig } from '@coxwave/tap-kit-types';
+import React$1 from 'react';
 
-interface UseTapKitReturn {
-    /** TapKit instance */
-    kit: TapKitInstance | null;
-    /** Whether TapKit is ready to use */
-    isReady: boolean;
-    /** Error that occurred during loading */
-    error: Error | null;
-    /** Setup TapKit with given parameters (button, course info, etc.) */
-    setup: (params: TapKitInitParams) => Promise<() => void>;
-}
 /**
- * 🌟 TapKit을 React에서 사용하기 위한 핵심 Hook
+ * React-specific type definitions for TapKit
  *
- * useSyncExternalStore를 활용하여 TapKit 인스턴스를 관리합니다.
- * 같은 apiKey로 여러 컴포넌트에서 호출해도 동일한 인스턴스를 공유합니다.
+ * Defines event handler types and control patterns for React integration.
+ */
+
+/**
+ * Event handler type definitions for TapKit Web Component
  *
- * **Note for Next.js App Router users:**
- * Make sure to add 'use client' at the top of your component file when using this hook.
+ * 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
  *
- * @param config - TapKit 설정 (apiKey 등)
- * @returns TapKit 인스턴스, 로딩 상태, 에러 정보, 설정 함수
+ * Separates instance management (setInstance) from configuration (options)
+ * and event handling (handlers). Inspired by ChatKit's control pattern.
  *
  * @example
  * ```tsx
- * 'use client'; // Add this for Next.js App Router
- *
- * import { useEffect } from 'react';
- * import { useTapKit } from '@coxwave/tap-kit/react';
+ * 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;
+}
+
+/**
+ * TapKit React Component
  *
- * function MyComponent() {
- *   const { kit, isReady, error, setup } = useTapKit({
- *     apiKey: 'your-api-key',
- *   });
+ * Declarative React wrapper for <tap-kit> Web Component.
+ * Use this with useTapKit hook for a clean separation of control and rendering.
  *
- *   useEffect(() => {
- *     if (isReady) {
- *       setup({
- *         buttonId: 'tap-button',
- *         course: {
- *           userId: 'user-123',
- *           courseId: 'course-456',
- *           clipId: 'clip-789',
- *         },
- *       });
- *     }
- *   }, [isReady, setup]);
+ * @example
+ * ```tsx
+ * 'use client';
  *
- *   if (error) {
- *     return <div>에러 발생: {error.message}</div>;
- *   }
+ * import { TapKit, useTapKit } from '@coxwave/tap-kit/react';
  *
- *   if (!isReady) {
- *     return <div>TapKit 로딩 중...</div>;
- *   }
+ * 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),
+ *   });
  *
- *   return <div id="tap-button">AI 튜터</div>;
+ *   return (
+ *     <div>
+ *       <button onClick={tapkit.show} disabled={!tapkit.isReady}>
+ *         Show Chat
+ *       </button>
+ *       <TapKit control={tapkit.control} style={{ height: '600px' }} />
+ *     </div>
+ *   );
  * }
  * ```
- */
-declare function useTapKit(config: TapKitConfig): UseTapKitReturn;
-
-/**
- * TapKit React Integration
- *
- * React 앱에서 TapKit을 쉽게 사용할 수 있는 Hook을 제공합니다.
- *
- * useTapKit은 useSyncExternalStore를 활용하여 전역 store를 관리합니다.
- * 같은 apiKey로 여러 컴포넌트에서 호출하면 자동으로 같은 인스턴스를 공유합니다.
  *
  * **Note for Next.js App Router users:**
- * If you're using this in a Next.js App Router project with Server Components,
- * make sure to add 'use client' at the top of your component file that imports this hook.
+ * Make sure to add 'use client' at the top of your component file.
  *
  * @see https://edutap-ai-docs.vercel.app/docs/guides/react
  */
 
+/**
+ * Props for TapKit React component
+ */
+interface TapKitProps extends Omit<React$1.HTMLAttributes<TapKitElement>, "children" | "dangerouslySetInnerHTML"> {
+    /**
+     * Control object from useTapKit hook
+     *
+     * Provides instance management, configuration, and event handlers.
+     */
+    control: TapKitControl<any>;
+    /**
+     * Custom container element ID (optional)
+     *
+     * If provided, TapKit will use this element as container.
+     */
+    containerId?: string;
+}
 declare global {
     namespace JSX {
         interface IntrinsicElements {
-            "tap-button": TapButtonAttributes;
+            "tap-kit": React$1.DetailedHTMLProps<React$1.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;
+                "container-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$1.ForwardRefExoticComponent<TapKitProps & React$1.RefAttributes<TapKitElement>>;
+
+/**
+ * useTapKit Hook - Advanced imperative control of TapKit Web Component
+ *
+ * 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
+ *
+ * For most use cases, prefer the `<TapKit />` component which provides a
+ * simpler declarative API.
+ *
+ * @param options - TapKit configuration
+ * @returns Object with element reference, state, and control methods
+ *
+ * @example Advanced control with custom rendering
+ * ```tsx
+ * 'use client';
+ *
+ * import { useTapKit } from '@coxwave/tap-kit/react';
+ *
+ * function MyComponent() {
+ *   const { element, elementRef, show, hide, isReady, error } = useTapKit({
+ *     apiKey: 'your-key',
+ *     userId: 'user-123',
+ *     courseId: 'course-456',
+ *     clipId: 'clip-789',
+ *   });
+ *
+ *   // 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
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @see TapKit - Use this component for simpler declarative API
+ */
+
+interface UseTapKitOptions extends TapKitConfig, TapKitEventHandlers {
+    /** User ID */
+    userId?: string;
+    /** Course ID */
+    courseId?: string;
+    /** Clip ID */
+    clipId?: string;
+    /** Clip playhead position */
+    clipPlayHead?: number;
+    /** Language */
+    language?: "ko" | "en";
+    /** Custom button element ID */
+    buttonId?: string;
+    /** Display mode */
+    mode?: "inline" | "floating" | "sidebar";
+    /** Debug mode */
+    debug?: boolean;
+    /** TAP Frontend URL */
+    tapUrl?: string;
+    /** API Backend URL */
+    apiUrl?: string;
+    /** 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;
+    /** Ref object for direct element access */
+    ref: React.RefObject<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 */
+    error: Error | null;
+    /** Show chat interface */
+    show: () => void;
+    /** Hide chat interface */
+    hide: () => void;
+    /** Set course information */
+    setCourse: (course: {
+        courseId: string;
+        clipId: string;
+        userId?: string;
+        clipPlayHead?: number;
+    }) => void;
+}
+/**
+ * Hook for managing TapKit Web Component
+ *
+ * Automatically loads CDN, creates Web Component, and provides control methods.
+ *
+ * @param options - TapKit configuration with event handlers
+ * @returns Methods to control TapKit instance and control object
+ */
+declare function useTapKit(options: UseTapKitOptions): UseTapKitReturn;
 
-export { type UseTapKitReturn, useTapKit };
+export { TapKit, type TapKitControl, type TapKitEventHandlers, type TapKitProps, type UseTapKitOptions, type UseTapKitReturn, useTapKit };