@coxwave/tap-kit-types 0.0.50 → 0.0.52

package/dist/index.d.ts

@@ -7,6 +7,14 @@ interface AlarmMessageInstanceType {
     priority: number;
 }
 
+/**
+ * Config Update Message (parent → iframe)
+ *
+ * IMPORTANT: container field mirrors ContainerConfig from @coxwave/tap-kit-types
+ * - SSOT: @coxwave/tap-kit-types/src/styles.ts (ContainerConfig)
+ * - This message protocol mirrors the structure for serialization
+ * - When updating ContainerConfig, update this structure accordingly
+ */
 interface ConfigUpdateMessage {
     type: "config:update";
     apiKey?: string;
@@ -19,8 +27,33 @@ interface ConfigUpdateMessage {
     courseId?: string;
     clipId?: string;
     clipPlayHead?: number;
+    /**
+     * Container configuration (mirrors ContainerConfig from @coxwave/tap-kit-types)
+     *
+     * Structure:
+     * - mode: "auto" (default) | "floating" | "sidebar"
+     * - floatingConfig: { position, width, height, borderRadius }
+     * - sidebarConfig: { maxWidth, minViewportWidth }
+     *
+     * @see ContainerConfig in @coxwave/tap-kit-types
+     */
     container?: {
-        disableSidebar?: boolean;
+        mode?: "auto" | "floating" | "sidebar";
+        floatingConfig?: {
+            position?: {
+                top?: string;
+                left?: string;
+                right?: string;
+                bottom?: string;
+            };
+            width?: string;
+            height?: string;
+            borderRadius?: string;
+        };
+        sidebarConfig?: {
+            maxWidth?: string;
+            minViewportWidth?: number;
+        };
     };
 }
 
@@ -34,41 +67,104 @@ type PositionType = {
     bottom?: string;
 };
 /**
- * Container Mode
- * - floating: Floating positioned container (default)
- * - sidebar: Fixed sidebar positioned at the right edge
+ * Container Layout State (SSOT - Visual State)
+ *
+ * This is the SINGLE SOURCE OF TRUTH for container visual state.
+ * Managed by Container class (tap-kit-core), streamed to iframe via messages.
+ *
+ * - floating: User-chosen floating layout
+ * - sidebar: User-chosen sidebar layout
+ * - floating-forced: Forced floating due to narrow viewport (sidebar unavailable)
+ *
+ * Both tap-kit-core (Container) and edutap (UIConfigStore) use this type.
+ * iframe receives this as read-only shadow state via container:layout:state:changed message.
  */
-type ContainerMode = "floating" | "sidebar";
+type ContainerLayoutState = "floating" | "sidebar" | "floating-forced";
+/**
+ * Container Mode (Behavior Configuration)
+ *
+ * Controls toggle button visibility and layout persistence:
+ * - auto: User can toggle between layouts, remembers preference via localStorage (DEFAULT)
+ * - floating: Fixed in floating layout, no toggle button, no persistence
+ * - sidebar: Fixed in sidebar layout, no toggle button, no persistence
+ */
+type ContainerMode = "auto" | "floating" | "sidebar";
+/**
+ * Floating mode configuration
+ * Includes position, size, and style settings for floating container
+ */
+type FloatingConfig = {
+    /** Position (default: top: "50px", right: "24px") */
+    position?: PositionType;
+    /** Width (default: "340px") */
+    width?: string;
+    /** Height (default: "calc(100% - 116px)") */
+    height?: string;
+    /** Border radius (default: "16px") */
+    borderRadius?: string;
+};
 /**
  * Sidebar Configuration
  */
 type SidebarConfig = {
-    /** Width of the sidebar (default: "max(15%, 400px)") */
-    width?: string;
+    /** Maximum width of the sidebar (default: "min(50%, 600px)") */
+    maxWidth?: string;
     /** Minimum viewport width to enable sidebar mode (default: 768) */
     minViewportWidth?: number;
 };
 /**
- * Container Styling
+ * Container Configuration (SSOT - Type Level)
+ *
+ * This is the SINGLE SOURCE OF TRUTH for container configuration at the TYPE level.
+ * - Public API: TapKitInitParams.container
+ * - Internal: Container class configuration
+ * - Protocol: ConfigUpdateMessage.container mirrors this structure
+ *
+ * When modifying this type, also update ConfigUpdateMessage.container in @coxwave/tap-messages
+ *
+ * @example
+ * // Default: Auto mode with floating layout (toggle button visible)
+ * const config: ContainerConfig = {}
+ *
+ * @example
+ * // Auto mode with custom styling for both layouts
+ * const config: ContainerConfig = {
+ *   floatingConfig: { width: "400px", position: { top: "80px" } },
+ *   sidebarConfig: { maxWidth: "600px" }
+ * }
+ *
+ * @example
+ * // Fixed floating mode (no toggle button)
+ * const config: ContainerConfig = {
+ *   mode: "floating",
+ *   floatingConfig: { position: { top: "80px" }, width: "400px" }
+ * }
+ *
+ * @example
+ * // Fixed sidebar mode (no toggle button)
+ * const config: ContainerConfig = {
+ *   mode: "sidebar",
+ *   sidebarConfig: { maxWidth: "500px" }
+ * }
  */
-type ContainerStyle = {
-    /** Container mode (default: "floating") */
+type ContainerConfig = {
+    /**
+     * Container mode controls toggle button visibility and behavior
+     * - "auto" (default): User can toggle between layouts, starts in floating, remembers preference via localStorage
+     * - "floating": Fixed in floating layout, no toggle button
+     * - "sidebar": Fixed in sidebar layout, no toggle button
+     */
     mode?: ContainerMode;
-    /** Sidebar configuration (only applicable when mode is "sidebar") */
+    /** Floating layout configuration (applied when in floating layout) */
+    floatingConfig?: FloatingConfig;
+    /** Sidebar layout configuration (applied when in sidebar layout) */
     sidebarConfig?: SidebarConfig;
-    /** Position (only applicable when mode is "floating") */
-    position?: PositionType;
-    /** Width (only applicable when mode is "floating") */
-    width?: string;
-    /** Height (only applicable when mode is "floating") */
-    height?: string;
-    /** Border radius */
-    borderRadius?: string;
 };
+
 /**
- * Flattened container styles (backward compatibility)
+ * Core Configuration Types
+ * Based on ConfigUpdateMessage protocol for type consistency (SSOT)
  */
-type CustomStyles = ContainerStyle;
 
 /**
  * SDK Configuration (Public API)
@@ -77,7 +173,7 @@ type CustomStyles = ContainerStyle;
  * Default values:
  * - tapUrl: https://edutap-ai.vercel.app
  * - apiUrl: https://tapapi.coxwave.link
- * - environment: local (console logging enabled)
+ * - environment: dev (console logging enabled)
  */
 type TapKitConfig = {
     apiKey: string;
@@ -87,7 +183,7 @@ type TapKitConfig = {
  * Derived from ConfigUpdateMessage protocol (without 'type' field)
  * This ensures type consistency between iframe messages and config
  */
-type TapKitRuntimeConfig = Omit<ConfigUpdateMessage, 'type'>;
+type TapKitRuntimeConfig = Omit<ConfigUpdateMessage, "type">;
 /**
  * All SDK Configuration Options (Internal API)
  * Derived from ConfigUpdateMessage protocol for type consistency
@@ -111,14 +207,45 @@ type Course = {
 };
 /**
  * SDK Initialization Parameters
+ *
+ * @example
+ * ```typescript
+ * const sdk = new TapSDK({ apiKey: "your-key" });
+ *
+ * // Minimal initialization (uses all defaults)
+ * await sdk.init({
+ *   buttonId: "tap-button",
+ *   course: { userId: "user1", courseId: "course1", clipId: "clip1" }
+ * });
+ *
+ * // Custom floating container
+ * await sdk.init({
+ *   buttonId: "tap-button",
+ *   course: { userId: "user1", courseId: "course1", clipId: "clip1" },
+ *   container: {
+ *     mode: "floating",
+ *     position: { top: "80px", right: "32px" },
+ *     width: "400px",
+ *     disableSidebar: true // Prevent user from switching to sidebar
+ *   }
+ * });
+ *
+ * // Sidebar mode with custom width
+ * await sdk.init({
+ *   buttonId: "tap-button",
+ *   course: { userId: "user1", courseId: "course1", clipId: "clip1" },
+ *   container: {
+ *     mode: "sidebar",
+ *     sidebarConfig: { width: "600px", minViewportWidth: 1024 }
+ *   }
+ * });
+ * ```
  */
 type TapKitInitParams = {
     buttonId: string;
     course: Course;
-    container?: ContainerStyle & {
-        /** Disable sidebar mode toggle (sidebar mode will not be available) */
-        disableSidebar?: boolean;
-    };
+    /** Container configuration (optional, uses defaults if omitted) */
+    container?: ContainerConfig;
 };
 
 /**
@@ -257,4 +384,4 @@ declare global {
   function cancelIdleCallback(handle: number): void;
 }
 
-export { type AlarmMessageInstanceType, type AlarmType, type ContainerMode, type ContainerStyle, type ContainerVisibility, type Course, type CustomStyles, TapKitInitializationError as InitializationError, type PositionType, type SeekTimelineParamsType, type ShortcutKeyPropertiesType, type SidebarConfig, TAPKIT_CONFIG_SYMBOL, TAP_ERROR_MARKER, type TapErrorOptions, type TapKitConfig, type TapKitConfigOptions, TapKitConfigurationError, type TapKitConstructor, TapKitError, TapKitIframeError, type TapKitInitParams, TapKitInitializationError, type TapKitInstance, TapKitLoaderError, TapKitMessageError, type TapKitRuntimeConfig };
+export { type AlarmMessageInstanceType, type AlarmType, type ContainerConfig, type ContainerLayoutState, type ContainerMode, type ContainerVisibility, type Course, type FloatingConfig, TapKitInitializationError as InitializationError, type PositionType, type SeekTimelineParamsType, type ShortcutKeyPropertiesType, type SidebarConfig, TAPKIT_CONFIG_SYMBOL, TAP_ERROR_MARKER, type TapErrorOptions, type TapKitConfig, type TapKitConfigOptions, TapKitConfigurationError, type TapKitConstructor, TapKitError, TapKitIframeError, type TapKitInitParams, TapKitInitializationError, type TapKitInstance, TapKitLoaderError, TapKitMessageError, type TapKitRuntimeConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coxwave/tap-kit-types",
-  "version": "0.0.50",
+  "version": "0.0.52",
   "type": "module",
   "description": "Shared TypeScript types for TapKit SDK packages",
   "main": "dist/index.js",
@@ -23,9 +23,9 @@
   ],
   "devDependencies": {
     "tsup": "^8.5.0",
-    "@coxwave/config-typescript": "1.0.0",
+    "@coxwave/config-eslint": "1.0.0",
     "@coxwave/tap-messages": "0.0.1",
-    "@coxwave/config-eslint": "1.0.0"
+    "@coxwave/config-typescript": "1.0.0"
   },
   "scripts": {
     "build": "tsup",