@coxwave/tap-kit 2.0.1 → 2.0.3

package/dist/react.d.cts

@@ -1,5 +1,5 @@
-import { TapKitElement, TapKitConfig } from '@coxwave/tap-kit-types';
-import React$1 from 'react';
+import { TapKitElement } from '@coxwave/tap-kit-types';
+import React from 'react';
 
 /**
  * React-specific type definitions for TapKit
@@ -66,6 +66,12 @@ interface TapKitControl<T> {
      * 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;
 }
 
 /**
@@ -110,24 +116,18 @@ interface TapKitControl<T> {
 /**
  * Props for TapKit React component
  */
-interface TapKitProps extends Omit<React$1.HTMLAttributes<TapKitElement>, "children" | "dangerouslySetInnerHTML"> {
+interface TapKitProps extends Omit<React.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-kit": React$1.DetailedHTMLProps<React$1.HTMLAttributes<TapKitElement>, TapKitElement> & {
+            "tap-kit": React.DetailedHTMLProps<React.HTMLAttributes<TapKitElement>, TapKitElement> & {
                 "api-key"?: string;
                 "user-id"?: string;
                 "course-id"?: string;
@@ -135,7 +135,6 @@ declare global {
                 "clip-play-head"?: number;
                 language?: "ko" | "en";
                 "button-id"?: string;
-                "container-id"?: string;
                 mode?: "inline" | "floating" | "sidebar";
                 debug?: boolean;
                 "tap-url"?: string;
@@ -158,60 +157,45 @@ declare global {
  * // tapkitRef.current?.show()
  * ```
  */
-declare const TapKit: React$1.ForwardRefExoticComponent<TapKitProps & React$1.RefAttributes<TapKitElement>>;
+declare const TapKit: React.ForwardRefExoticComponent<TapKitProps & React.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
+ * useTapKit Hook - ChatKit-style control for TapKit Web Component
  *
- * For most use cases, prefer the `<TapKit />` component which provides a
- * simpler declarative API.
+ * This hook provides a control object to manage TapKit through the
+ * <TapKit /> component. Inspired by OpenAI's ChatKit pattern.
  *
- * @param options - TapKit configuration
- * @returns Object with element reference, state, and control methods
- *
- * @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('Ready!'),
+ *     onError: (error) => console.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}>
+ *         Ask AI Tutor
+ *       </button>
+ *       <TapKit control={tapkit.control} />
  *     </div>
  *   );
  * }
  * ```
- *
- * @see TapKit - Use this component for simpler declarative API
  */
 
-interface UseTapKitOptions extends TapKitConfig, TapKitEventHandlers {
+interface UseTapKitOptions extends TapKitEventHandlers {
+    /** API Key (required) */
+    apiKey: string;
     /** User ID */
     userId?: string;
     /** Course ID */
@@ -240,13 +224,7 @@ interface UseTapKitOptions extends TapKitConfig, TapKitEventHandlers {
  */
 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 object for <TapKit /> component */
     control: TapKitControl<TapKitOptions>;
     /** Whether TapKit is ready */
     isReady: boolean;
@@ -263,14 +241,22 @@ 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 with event handlers
- * @returns Methods to control TapKit instance and control object
+ * 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;
 

package/dist/react.d.ts

@@ -1,5 +1,5 @@
-import { TapKitElement, TapKitConfig } from '@coxwave/tap-kit-types';
-import React$1 from 'react';
+import { TapKitElement } from '@coxwave/tap-kit-types';
+import React from 'react';
 
 /**
  * React-specific type definitions for TapKit
@@ -66,6 +66,12 @@ interface TapKitControl<T> {
      * 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;
 }
 
 /**
@@ -110,24 +116,18 @@ interface TapKitControl<T> {
 /**
  * Props for TapKit React component
  */
-interface TapKitProps extends Omit<React$1.HTMLAttributes<TapKitElement>, "children" | "dangerouslySetInnerHTML"> {
+interface TapKitProps extends Omit<React.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-kit": React$1.DetailedHTMLProps<React$1.HTMLAttributes<TapKitElement>, TapKitElement> & {
+            "tap-kit": React.DetailedHTMLProps<React.HTMLAttributes<TapKitElement>, TapKitElement> & {
                 "api-key"?: string;
                 "user-id"?: string;
                 "course-id"?: string;
@@ -135,7 +135,6 @@ declare global {
                 "clip-play-head"?: number;
                 language?: "ko" | "en";
                 "button-id"?: string;
-                "container-id"?: string;
                 mode?: "inline" | "floating" | "sidebar";
                 debug?: boolean;
                 "tap-url"?: string;
@@ -158,60 +157,45 @@ declare global {
  * // tapkitRef.current?.show()
  * ```
  */
-declare const TapKit: React$1.ForwardRefExoticComponent<TapKitProps & React$1.RefAttributes<TapKitElement>>;
+declare const TapKit: React.ForwardRefExoticComponent<TapKitProps & React.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
+ * useTapKit Hook - ChatKit-style control for TapKit Web Component
  *
- * For most use cases, prefer the `<TapKit />` component which provides a
- * simpler declarative API.
+ * This hook provides a control object to manage TapKit through the
+ * <TapKit /> component. Inspired by OpenAI's ChatKit pattern.
  *
- * @param options - TapKit configuration
- * @returns Object with element reference, state, and control methods
- *
- * @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('Ready!'),
+ *     onError: (error) => console.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}>
+ *         Ask AI Tutor
+ *       </button>
+ *       <TapKit control={tapkit.control} />
  *     </div>
  *   );
  * }
  * ```
- *
- * @see TapKit - Use this component for simpler declarative API
  */
 
-interface UseTapKitOptions extends TapKitConfig, TapKitEventHandlers {
+interface UseTapKitOptions extends TapKitEventHandlers {
+    /** API Key (required) */
+    apiKey: string;
     /** User ID */
     userId?: string;
     /** Course ID */
@@ -240,13 +224,7 @@ interface UseTapKitOptions extends TapKitConfig, TapKitEventHandlers {
  */
 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 object for <TapKit /> component */
     control: TapKitControl<TapKitOptions>;
     /** Whether TapKit is ready */
     isReady: boolean;
@@ -263,14 +241,22 @@ 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 with event handlers
- * @returns Methods to control TapKit instance and control object
+ * 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;