@coxwave/tap-kit-types 2.0.6 → 2.0.7

package/dist/index.d.ts

@@ -2328,23 +2328,49 @@ type TapKitConfig = {
     apiKey: string;
 };
 /**
- * Runtime configuration sent to iframe via config:update message
- * Derived from ConfigUpdateMessage protocol (without 'type' field)
- * This ensures type consistency between iframe messages and config
+ * =============================================================================
+ * SSOT (Single Source of Truth) Type Hierarchy
+ * =============================================================================
+ *
+ * All configuration types derive from ConfigUpdateMessage:
+ *
+ * ConfigUpdateMessage (SSOT - protocol/messages.ts)
+ *     ↓ Omit<..., "type">
+ * ConfigUpdatePayload (모든 config 필드)
+ *     ↓ Partial<...>
+ * ConfigUpdateOptions (런타임 업데이트용, 모든 필드 optional)
+ *     ↓ Exclude<keyof ..., ...>
+ * SyncableConfigKey (iframe 동기화 대상 키들)
+ *
+ * Benefits:
+ * - 새 필드 추가 시 ConfigUpdateMessage만 수정
+ * - 다른 위치에서 컴파일 에러 발생으로 누락 방지
+ * =============================================================================
  */
-type TapKitRuntimeConfig = Omit<ConfigUpdateMessage, "type">;
 /**
- * All SDK Configuration Options (Internal API)
- * Derived from ConfigUpdateMessage protocol for type consistency
- * Used by Symbol-based config() method for advanced configuration
- *
- * Note: All fields (tapUrl, environment, etc.) are now part of TapKitRuntimeConfig
- * which is based on ConfigUpdateMessage. This ensures consistency between
- * SDK configuration and iframe message protocol.
+ * config:update 메시지의 payload (type 필드 제외)
+ * 모든 config 관련 타입의 기반
+ */
+type ConfigUpdatePayload = Omit<ConfigUpdateMessage, "type">;
+/**
+ * 런타임 업데이트 가능한 config 키
+ */
+type ConfigUpdateKey = keyof ConfigUpdatePayload;
+/**
+ * 런타임 config 업데이트용 (모든 필드 optional)
+ * updateConfig() 메서드에서 사용
+ */
+type ConfigUpdateOptions = Partial<ConfigUpdatePayload>;
+/**
+ * iframe 동기화 대상 키 (초기화 전용 키 제외)
+ * CONFIG_KEYS 배열의 타입 제약으로 사용
  *
- * @internal This is not part of the public API
+ * 제외 항목:
+ * - apiKey: 초기화 시에만 설정
+ * - hostOrigin: 자동 감지
+ * - tapUrl: 초기화 시에만 설정
  */
-type TapKitConfigOptions = TapKitRuntimeConfig;
+type SyncableConfigKey = Exclude<ConfigUpdateKey, "apiKey" | "hostOrigin" | "tapUrl">;
 /**
  * Course Information
  */
@@ -2630,8 +2656,13 @@ interface TapKitInstance {
         onAlarmFadeIn: (handler: (messageInfo: AlarmMessageInstanceType) => void) => () => void;
     };
     video: {
-        /** Bind video player for timeline synchronization */
-        bind: (config: VideoPlayerConfig, clipId: string) => void;
+        /**
+         * Bind video player for timeline synchronization
+         *
+         * @param config - HTMLVideoElement or VideoPlayerAdapter
+         * @param clipId - Optional clipId. If not provided, uses SDK config (auto-tracks changes from setCourse)
+         */
+        bind: (config: VideoPlayerConfig, clipId?: string) => void;
         /** Unbind current video player */
         unbind: () => void;
     };
@@ -3229,11 +3260,55 @@ interface TapKitElement extends HTMLElement {
   mode?: "inline" | "floating" | "sidebar";
 
   /**
-   * Auto-created flag (internal use only)
-   * Indicates SDK-controlled element (used by legacy TapKit class)
-   * @internal
+   * Allow user to toggle between floating and sidebar layouts
+   * Only applies when mode is "floating" or "sidebar"
+   * @default true
+   */
+  allowLayoutToggle: boolean;
+
+  /**
+   * Video player target for timeline synchronization (recommended)
+   *
+   * Supports HTMLVideoElement or VideoPlayerAdapter.
+   * Survives lifecycle changes (mode change, reconnect).
+   *
+   * @example
+   * ```typescript
+   * // HTMLVideoElement
+   * kit.videoTarget = document.querySelector('video');
+   *
+   * // VideoPlayerAdapter (YouTube, Vimeo, etc.)
+   * kit.videoTarget = {
+   *   getCurrentTime: () => player.getCurrentTime(),
+   *   setCurrentTime: (t) => player.seekTo(t)
+   * };
+   * ```
+   */
+  videoTarget?: VideoPlayerConfig;
+
+  /**
+   * Root element - tracks the parent element where TapKit is rendered
+   *
+   * **Declarative mode** (`<TapKit />`, `<tap-kit>`):
+   * - Automatically set to `parentElement` on mount
+   * - Read-only after initialization
+   *
+   * **Imperative mode** (`createTapKit()`):
+   * - Set before mount (default: `document.body`)
+   * - Can be changed at runtime
+   *
+   * **Note:** Ignored in inline mode (element stays in declarative position).
+   *
+   * @example
+   * ```typescript
+   * // Imperative: set root before mount
+   * const kit = createTapKit({ apiKey: '...', root: myContainer });
+   *
+   * // Imperative: change root at runtime
+   * kit.root = document.getElementById('another-container');
+   * ```
    */
-  autoCreated?: boolean;
+  root?: HTMLElement;
 
   // ===== Public Methods (Imperative API) =====
 
@@ -3387,9 +3462,6 @@ interface TapKitAttributes {
   /** Custom button element ID */
   "button-id"?: string;
 
-  /** Custom container element ID */
-  "container-id"?: string;
-
   /** Enable debug mode */
   debug?: boolean;
 
@@ -3401,6 +3473,12 @@ interface TapKitAttributes {
    */
   mode?: "inline" | "floating" | "sidebar";
 
+  /**
+   * Allow user to toggle between floating and sidebar layouts
+   * Only applies when mode is "floating" or "sidebar"
+   */
+  "allow-layout-toggle"?: boolean;
+
   /** Custom inline styles */
   style?: CSSProperties;
 
@@ -3529,6 +3607,8 @@ interface ITapMaterialViewerElement extends HTMLElement {
    * Downloads PDF from presigned URL, extracts specified pages,
    * and displays in an overlay positioned relative to containerElement.
    *
+   * Note: For HTML content, use TapHtmlViewerElement instead (Separation of Concerns).
+   *
    * @param config - Material view configuration
    * @throws {MaterialViewerError} If PDF fetch or processing fails
    * @fires error - When material loading fails
@@ -3701,4 +3781,4 @@ declare global {
   function cancelIdleCallback(handle: number): void;
 }
 
-export { ALARM_DURATION, type AlarmClickMessage, AlarmClickSchema, type AlarmElement, type AlarmElementProps, AlarmElementPropsSchema, AlarmElementSchema, type AlarmFadeInMessage, AlarmFadeInSchema, AlarmMessageInstanceSchema, type AlarmMessageInstanceType, type AlarmPayload, type AlarmType, type CSSStyle, CSSStyleSchema, type ConfigUpdateMessage, ConfigUpdateSchema, type ContainerConfig, type ContainerLayoutStateChangedMessage, ContainerLayoutStateChangedSchema, type ContainerModeChangeAckMessage, ContainerModeChangeAckSchema, type ContainerModeChangeMessage, ContainerModeChangeSchema, type ContainerVisibility, type Course, type DisplayMode, type EventManager, type FloatingConfig, type GAEventMessage, GAEventSchema, type HtmlViewCloseMessage, HtmlViewCloseSchema, type HtmlViewConfig, type HtmlViewOpenMessage, HtmlViewOpenSchema, type ITapButtonElement, type ITapContainerElement, type ITapHtmlViewerElement, type ITapKitElement, type ITapMaterialViewerElement, TapKitInitializationError as InitializationError, type LayoutMode, type MaterialViewCloseMessage, MaterialViewCloseSchema, type MaterialViewConfig, type MaterialViewErrorMessage, MaterialViewErrorSchema, type MaterialViewOpenMessage, MaterialViewOpenSchema, MaterialViewerError, type PopUpCloseMessage, PopUpCloseSchema, type PopUpOpenMessage, PopUpOpenSchema, type PositionType, type SeekTimelineParamsType, type ShortcutKeyPropertiesType, type SidebarConfig, TAP_BUTTON_CLICK_EVENT, TAP_ERROR_MARKER, type TapButtonAttributes, type TapButtonClickEventDetail, type TapCloseMessage, TapCloseSchema, type TapContainerAttributes, type TapErrorOptions, type TapHtmlViewerAttributes, type TapKitConfig, type TapKitConfigOptions, TapKitConfigurationError, type TapKitConstructor, type TapKitElement, type TapKitElementEventMap, TapKitError, TapKitIframeError, type TapKitInitParams, TapKitInitializationError, type TapKitInstance, TapKitLoaderError, TapKitMessageError, type TapKitRuntimeConfig, type TapMaterialViewerAttributes, type TapMessage, type TapMessageRecord, TapMessageSchema, type TapMessageType, type TapReadyMessage, TapReadySchema, type TimelineSeekMessage, TimelineSeekSchema, type VideoController, type VideoPlayerAdapter, type VideoPlayerConfig, type ViewportResizeMessage, ViewportResizeSchema };
+export { ALARM_DURATION, type AlarmClickMessage, AlarmClickSchema, type AlarmElement, type AlarmElementProps, AlarmElementPropsSchema, AlarmElementSchema, type AlarmFadeInMessage, AlarmFadeInSchema, AlarmMessageInstanceSchema, type AlarmMessageInstanceType, type AlarmPayload, type AlarmType, type CSSStyle, CSSStyleSchema, type ConfigUpdateKey, type ConfigUpdateMessage, type ConfigUpdateOptions, type ConfigUpdatePayload, ConfigUpdateSchema, type ContainerConfig, type ContainerLayoutStateChangedMessage, ContainerLayoutStateChangedSchema, type ContainerModeChangeAckMessage, ContainerModeChangeAckSchema, type ContainerModeChangeMessage, ContainerModeChangeSchema, type ContainerVisibility, type Course, type DisplayMode, type EventManager, type FloatingConfig, type GAEventMessage, GAEventSchema, type HtmlViewCloseMessage, HtmlViewCloseSchema, type HtmlViewConfig, type HtmlViewOpenMessage, HtmlViewOpenSchema, type ITapButtonElement, type ITapContainerElement, type ITapHtmlViewerElement, type ITapKitElement, type ITapMaterialViewerElement, TapKitInitializationError as InitializationError, type LayoutMode, type MaterialViewCloseMessage, MaterialViewCloseSchema, type MaterialViewConfig, type MaterialViewErrorMessage, MaterialViewErrorSchema, type MaterialViewOpenMessage, MaterialViewOpenSchema, MaterialViewerError, type PopUpCloseMessage, PopUpCloseSchema, type PopUpOpenMessage, PopUpOpenSchema, type PositionType, type SeekTimelineParamsType, type ShortcutKeyPropertiesType, type SidebarConfig, type SyncableConfigKey, TAP_BUTTON_CLICK_EVENT, TAP_ERROR_MARKER, type TapButtonAttributes, type TapButtonClickEventDetail, type TapCloseMessage, TapCloseSchema, type TapContainerAttributes, type TapErrorOptions, type TapHtmlViewerAttributes, type TapKitConfig, TapKitConfigurationError, type TapKitConstructor, type TapKitElement, type TapKitElementEventMap, TapKitError, TapKitIframeError, type TapKitInitParams, TapKitInitializationError, type TapKitInstance, TapKitLoaderError, TapKitMessageError, type TapMaterialViewerAttributes, type TapMessage, type TapMessageRecord, TapMessageSchema, type TapMessageType, type TapReadyMessage, TapReadySchema, type TimelineSeekMessage, TimelineSeekSchema, type VideoController, type VideoPlayerAdapter, type VideoPlayerConfig, type ViewportResizeMessage, ViewportResizeSchema };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coxwave/tap-kit-types",
-  "version": "2.0.6",
+  "version": "2.0.7",
   "type": "module",
   "description": "Shared TypeScript types for TapKit SDK packages",
   "main": "dist/index.js",