@coxwave/tap-kit 1.0.5 → 2.0.0

package/dist/react.d.cts

@@ -1,64 +1,109 @@
-import { TapKitInstance, TapKitInitParams, TapKitConfig } from '@coxwave/tap-kit-types';
+import { TapKitConfig, TapKitElement } from '@coxwave/tap-kit-types';
 
-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
+ * useTapKit Hook - Advanced imperative control of TapKit Web Component
  *
- * useSyncExternalStore를 활용하여 TapKit 인스턴스를 관리합니다.
- * 같은 apiKey로 여러 컴포넌트에서 호출해도 동일한 인스턴스를 공유합니다.
+ * 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
  *
- * **Note for Next.js App Router users:**
- * Make sure to add 'use client' at the top of your component file when using this hook.
+ * For most use cases, prefer the `<TapKit />` component which provides a
+ * simpler declarative API.
  *
- * @param config - TapKit 설정 (apiKey 등)
- * @returns TapKit 인스턴스, 로딩 상태, 에러 정보, 설정 함수
+ * @param options - TapKit configuration
+ * @returns Object with element reference, state, and control methods
  *
- * @example
+ * @example Advanced control with custom rendering
  * ```tsx
- * 'use client'; // Add this for Next.js App Router
+ * 'use client';
  *
- * import { useEffect } from 'react';
  * import { useTapKit } from '@coxwave/tap-kit/react';
  *
  * function MyComponent() {
- *   const { kit, isReady, error, setup } = useTapKit({
- *     apiKey: 'your-api-key',
+ *   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 (isReady) {
- *       setup({
- *         buttonId: 'tap-button',
- *         course: {
- *           userId: 'user-123',
- *           courseId: 'course-456',
- *           clipId: 'clip-789',
- *         },
- *       });
+ *     if (element) {
+ *       // Direct manipulation of TapKitElement
+ *       console.log('Element mounted:', element);
  *     }
- *   }, [isReady, setup]);
- *
- *   if (error) {
- *     return <div>에러 발생: {error.message}</div>;
- *   }
+ *   }, [element]);
  *
- *   if (!isReady) {
- *     return <div>TapKit 로딩 중...</div>;
- *   }
- *
- *   return <div id="tap-button">AI 튜터</div>;
+ *   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 {
+    /** 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";
+}
+interface UseTapKitReturn {
+    /** Web Component element reference */
+    element: TapKitElement | null;
+    /** Container ref to attach element */
+    elementRef: React.RefCallback<HTMLDivElement>;
+    /** 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
+ * @returns Methods to control TapKit instance
  */
-declare function useTapKit(config: TapKitConfig): UseTapKitReturn;
+declare function useTapKit(options: UseTapKitOptions): UseTapKitReturn;
 
-export { type UseTapKitReturn, useTapKit };
+export { type UseTapKitOptions, type UseTapKitReturn, useTapKit };

package/dist/react.d.ts

@@ -1,64 +1,109 @@
-import { TapKitInstance, TapKitInitParams, TapKitConfig } from '@coxwave/tap-kit-types';
+import { TapKitConfig, TapKitElement } from '@coxwave/tap-kit-types';
 
-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
+ * useTapKit Hook - Advanced imperative control of TapKit Web Component
  *
- * useSyncExternalStore를 활용하여 TapKit 인스턴스를 관리합니다.
- * 같은 apiKey로 여러 컴포넌트에서 호출해도 동일한 인스턴스를 공유합니다.
+ * 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
  *
- * **Note for Next.js App Router users:**
- * Make sure to add 'use client' at the top of your component file when using this hook.
+ * For most use cases, prefer the `<TapKit />` component which provides a
+ * simpler declarative API.
  *
- * @param config - TapKit 설정 (apiKey 등)
- * @returns TapKit 인스턴스, 로딩 상태, 에러 정보, 설정 함수
+ * @param options - TapKit configuration
+ * @returns Object with element reference, state, and control methods
  *
- * @example
+ * @example Advanced control with custom rendering
  * ```tsx
- * 'use client'; // Add this for Next.js App Router
+ * 'use client';
  *
- * import { useEffect } from 'react';
  * import { useTapKit } from '@coxwave/tap-kit/react';
  *
  * function MyComponent() {
- *   const { kit, isReady, error, setup } = useTapKit({
- *     apiKey: 'your-api-key',
+ *   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 (isReady) {
- *       setup({
- *         buttonId: 'tap-button',
- *         course: {
- *           userId: 'user-123',
- *           courseId: 'course-456',
- *           clipId: 'clip-789',
- *         },
- *       });
+ *     if (element) {
+ *       // Direct manipulation of TapKitElement
+ *       console.log('Element mounted:', element);
  *     }
- *   }, [isReady, setup]);
- *
- *   if (error) {
- *     return <div>에러 발생: {error.message}</div>;
- *   }
+ *   }, [element]);
  *
- *   if (!isReady) {
- *     return <div>TapKit 로딩 중...</div>;
- *   }
- *
- *   return <div id="tap-button">AI 튜터</div>;
+ *   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 {
+    /** 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";
+}
+interface UseTapKitReturn {
+    /** Web Component element reference */
+    element: TapKitElement | null;
+    /** Container ref to attach element */
+    elementRef: React.RefCallback<HTMLDivElement>;
+    /** 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
+ * @returns Methods to control TapKit instance
  */
-declare function useTapKit(config: TapKitConfig): UseTapKitReturn;
+declare function useTapKit(options: UseTapKitOptions): UseTapKitReturn;
 
-export { type UseTapKitReturn, useTapKit };
+export { type UseTapKitOptions, type UseTapKitReturn, useTapKit };