ai-design-system 0.1.13 → 0.1.15

package/components/features/AIDocEditor/AIDocEditor.stories.tsx

@@ -1,29 +1,40 @@
 /**
- * AIDocEditor Stories
+ * AIDocEditor Feature Stories
  * 
- * Demonstrates the AIDocEditor feature with various scenarios
+ * Required story patterns for AIDocEditor feature:
+ * - Default: Static single-document mode (backward compatible)
+ * - Empty: Empty state for multi-tab mode
+ * - WithStateManagement: Interactive multi-tab with mock hook
  */
 
 import type { Meta, StoryObj } from '@storybook/react'
 import { AIDocEditor } from './AIDocEditor'
 import { useAIDocEditorMock } from './useAIDocEditor.mock'
-import { sampleContent, currentUser, sampleAnnotations } from './AIDocEditor.mocks'
-
-const meta: Meta<typeof AIDocEditor> = {
+import {
+  sampleContent,
+  currentUser,
+  sampleAnnotations,
+  sampleMultiTabDocuments,
+} from './AIDocEditor.mocks'
+
+const meta = {
   title: 'Features/AIDocEditor',
   component: AIDocEditor,
   parameters: {
     layout: 'fullscreen',
   },
   tags: ['autodocs'],
-}
+} satisfies Meta<typeof AIDocEditor>
 
 export default meta
-type Story = StoryObj<typeof AIDocEditor>
+type Story = StoryObj<typeof meta>
 
 /**
- * Default story with static props
- * Shows the editor with existing annotations
+ * Default - Static single-document mode (REQUIRED)
+ * 
+ * Shows the editor in the original single-document usage pattern with
+ * existing annotations. Demonstrates backward compatibility with existing
+ * consumers who have not yet migrated to multi-tab mode.
  */
 export const Default: Story = {
   args: {
@@ -37,104 +48,44 @@ export const Default: Story = {
 }
 
 /**
- * Story with empty document
+ * Empty - Multi-tab empty state (REQUIRED edge case)
+ * 
+ * Shows the empty state when no documents are open in multi-tab mode.
+ * Demonstrates edge case behavior and placeholder messaging.
  */
-export const EmptyDocument: Story = {
+export const Empty: Story = {
   args: {
-    content: {
-      type: 'doc',
-      content: [
-        {
-          type: 'paragraph',
-          content: [],
-        },
-      ],
-    },
-    annotations: [],
+    documents: [],
     currentUser,
     mode: 'review',
   },
 }
 
 /**
- * Story in readonly mode (no interactions)
- */
-export const ReadonlyMode: Story = {
-  args: {
-    content: sampleContent,
-    annotations: sampleAnnotations,
-    currentUser,
-    mode: 'readonly',
-  },
-}
-
-/**
- * Interactive story with state management using mock hook
- * Demonstrates adding comments and replies with simulated async operations
- * Uses markdown format for easy content creation
+ * WithStateManagement - Multi-tab interactive mode (REQUIRED)
+ * 
+ * Demonstrates the new multi-tab capability with live state management.
+ * Users can switch tabs, close tabs, and manage annotations across
+ * multiple documents. Uses mock hook for realistic interaction simulation.
  */
 export const WithStateManagement: Story = {
   render: () => {
-    const { annotations, addAnnotation, updateAnnotation, loading } = useAIDocEditorMock(sampleAnnotations)
-
-    const markdownContent = `# AI Document Review Demo
-
-This document demonstrates the **AIDocEditor** feature with full state management.
-
-## Interactive Features
-
-Try these interactions:
-
-- **Select text** to add a new comment
-- **Click highlighted text** to view existing annotations
-- **Reply to comments** in the comment thread
-- All changes are saved with simulated async operations
-
-## Sample Content for Review
-
-The AI has analyzed this document and provided several suggestions. You can review each suggestion and add your own comments.
-
-### Code Example
-
-\`\`\`javascript
-function processData(items) {
-  return items.map(item => ({
-    id: item.id,
-    name: item.name,
-    processed: true
-  }));
-}
-\`\`\`
-
-### Key Points
-
-1. **Performance**: The current implementation is efficient
-2. **Maintainability**: Code is well-structured and documented
-3. **Testing**: Unit tests cover all critical paths
-
-> **Note:** This is a live demo with state management. Try selecting text and adding comments!
-
----
-
-**Status:** Ready for review | **Last updated:** ${new Date().toLocaleDateString()}`
+    const mockState = useAIDocEditorMock({
+      multiDoc: true,
+      initialDocuments: sampleMultiTabDocuments,
+    })
 
     return (
-      <div className="h-screen p-8">
-        <AIDocEditor
-          content={markdownContent}
-          format="markdown"
-          annotations={annotations}
-          currentUser={currentUser}
-          mode="review"
-          onAnnotationAdd={addAnnotation}
-          onAnnotationUpdate={updateAnnotation}
-        />
-        {loading && (
-          <div className="fixed bottom-4 right-4 bg-primary text-primary-foreground px-4 py-2 rounded-md">
-            Saving...
-          </div>
-        )}
-      </div>
+      <AIDocEditor
+        documents={mockState.documents}
+        activeDocumentId={mockState.activeDocumentId}
+        currentUser={currentUser}
+        mode="review"
+        onTabSelect={mockState.switchDocument}
+        onTabClose={mockState.closeDocument}
+        onAnnotationAdd={mockState.addAnnotation}
+        onAnnotationUpdate={mockState.updateAnnotation}
+      />
     )
   },
 }

package/components/features/AIDocEditor/AIDocEditor.tsx

@@ -2,9 +2,9 @@
  * AIDocEditor Feature Component
  * 
  * Complete document editor with inline comment annotations.
- * Feature layer: uses DocumentEditorWithComments section with data management.
+ * Supports both single-document and multi-tab modes.
  * 
- * @example
+ * Single-document mode (backward compatible):
  * ```tsx
  * <AIDocEditor
  *   content={document}
@@ -14,18 +14,36 @@
  *   onAnnotationAdd={(annotation) => saveAnnotation(annotation)}
  * />
  * ```
+ * 
+ * Multi-tab mode:
+ * ```tsx
+ * <AIDocEditor
+ *   documents={[
+ *     { file: { id: 'doc-1', name: 'File.md', isDirty: false, lastModified: now }, 
+ *       content: '...',
+ *       annotations: [] }
+ *   ]}
+ *   activeDocumentId="doc-1"
+ *   currentUser={user}
+ *   mode="review"
+ *   onTabSelect={(id) => switchDocument(id)}
+ *   onTabClose={(id) => closeDocument(id)}
+ * />
+ * ```
  */
 
-import React, { useCallback } from 'react'
+import React, { useCallback, useMemo } from 'react'
 import { DocumentEditorWithComments } from '@/components/blocks/DocumentEditorWithComments'
+import { DocumentTabBar } from '@/components/composites/DocumentTabBar'
 import { cn } from '@/lib/utils'
 import type { JSONContent } from '@tiptap/core'
 import type { Annotation, User } from '@/types/ai-editor/annotations'
+import type { DocumentWithAnnotations } from '@/types/ai-editor'
 
 /**
- * Props for AIDocEditor feature component
+ * Props for AIDocEditor feature component - Single document mode (backward compatible)
  */
-export interface AIDocEditorProps {
+export interface AIDocEditorSingleProps {
   /** 
    * Document content - can be either:
    * - JSONContent: Tiptap's JSON format (default)
@@ -44,6 +62,42 @@ export interface AIDocEditorProps {
   annotations: Annotation[]
   /** ID of currently selected annotation */
   selectedAnnotationId?: string
+  /** Multi-document array (not provided in single-doc mode) */
+  documents?: never
+  /** Active document ID (not provided in single-doc mode) */
+  activeDocumentId?: never
+  /** Tab selection callback (not provided in single-doc mode) */
+  onTabSelect?: never
+  /** Tab close callback (not provided in single-doc mode) */
+  onTabClose?: never
+}
+
+/**
+ * Props for AIDocEditor feature component - Multi-tab mode
+ */
+export interface AIDocEditorMultiTabProps {
+  /** Array of open documents with their content and annotations */
+  documents: DocumentWithAnnotations[]
+  /** ID of currently active document */
+  activeDocumentId?: string
+  /** Content prop (not provided in multi-tab mode) */
+  content?: never
+  /** Format prop (not provided in multi-tab mode) */
+  format?: never
+  /** Annotations prop (not provided in multi-tab mode) */
+  annotations?: never
+  /** Selected annotation ID (not provided in multi-tab mode) */
+  selectedAnnotationId?: never
+  /** Callback when tab is selected */
+  onTabSelect?: (documentId: string) => void
+  /** Callback when tab close button is clicked */
+  onTabClose?: (documentId: string) => void
+}
+
+/**
+ * Props for AIDocEditor feature component
+ */
+export type AIDocEditorProps = (AIDocEditorSingleProps | AIDocEditorMultiTabProps) & {
   /** Current user information */
   currentUser: User
   /** Editor mode: 'review' allows commenting, 'readonly' disables interactions */
@@ -66,30 +120,56 @@ export interface AIDocEditorProps {
   className?: string
 }
 
+/**
+ * Determine if props are multi-tab mode
+ */
+function isMultiTabMode(props: AIDocEditorProps): props is AIDocEditorMultiTabProps & {
+  currentUser: User
+  mode: 'review' | 'readonly'
+} {
+  return 'documents' in props && props.documents !== undefined
+}
+
 /**
  * AIDocEditor - Document editor with inline comment annotations
  * 
  * This feature component provides a complete document review experience with:
+ * - Single-document or multi-tab display modes
  * - Read-only document display with annotation highlights
  * - Inline comment box for viewing and adding comments
  * - Support for comments, suggestions, and block additions
  * - Controlled component pattern (all state managed by parent)
+ * - Backward-compatible with single-document consumers
  * 
  * Note: The refinement panel (right sidebar with Accept All/Reject All) is a
  * separate component in the parent application, not part of this feature.
  */
 export const AIDocEditor = React.memo<AIDocEditorProps>(
-  ({
-    content,
-    format = 'json',
-    annotations,
-    selectedAnnotationId,
-    currentUser,
-    mode,
-    onAnnotationAdd,
-    onAnnotationUpdate,
-    className,
-  }) => {
+  (props) => {
+    const {
+      currentUser,
+      mode,
+      onAnnotationAdd,
+      onAnnotationUpdate,
+      onAnnotationDelete: _onAnnotationDelete, // Callback for consumers; passed through on demand
+      className,
+    } = props
+
+    const isMultiTab = isMultiTabMode(props)
+
+    /**
+     * Get current document for rendering
+     */
+    const currentDocument = useMemo(() => {
+      if (isMultiTab && props.documents) {
+        return (
+          props.documents.find((doc) => doc.file.id === props.activeDocumentId) ||
+          props.documents[0]
+        )
+      }
+      return null
+    }, [isMultiTab, props])
+
     /**
      * Handle annotation add - emit event to parent
      */
@@ -110,19 +190,67 @@ export const AIDocEditor = React.memo<AIDocEditorProps>(
       [onAnnotationUpdate]
     )
 
+    /**
+     * Single-document mode
+     */
+    if (!isMultiTab) {
+      return (
+        <DocumentEditorWithComments
+          content={props.content}
+          format={props.format}
+          annotations={props.annotations}
+          selectedAnnotationId={props.selectedAnnotationId}
+          currentUserId={currentUser.id}
+          currentUserName={currentUser.name}
+          readOnly={mode === 'readonly'}
+          onAnnotationAdd={handleAnnotationAdd}
+          onAnnotationUpdate={handleAnnotationUpdate}
+          className={cn('ai-doc-editor p-6', className)}
+        />
+      )
+    }
+
+    /**
+     * Multi-tab mode
+     */
+    if (!currentDocument) {
+      return (
+        <div className={cn('ai-doc-editor flex flex-col h-full', className)}>
+          <DocumentTabBar
+            tabs={props.documents?.map((doc) => doc.file) || []}
+            activeTabId={props.activeDocumentId}
+            onTabSelect={props.onTabSelect}
+            onTabClose={props.onTabClose}
+          />
+          <div className="flex-1 flex items-center justify-center p-6 text-muted-foreground">
+            No documents open
+          </div>
+        </div>
+      )
+    }
+
     return (
-      <DocumentEditorWithComments
-        content={content}
-        format={format}
-        annotations={annotations}
-        selectedAnnotationId={selectedAnnotationId}
-        currentUserId={currentUser.id}
-        currentUserName={currentUser.name}
-        readOnly={mode === 'readonly'}
-        onAnnotationAdd={handleAnnotationAdd}
-        onAnnotationUpdate={handleAnnotationUpdate}
-        className={cn('ai-doc-editor p-6', className)}
-      />
+      <div className={cn('ai-doc-editor flex flex-col h-full', className)}>
+        <DocumentTabBar
+          tabs={props.documents?.map((doc) => doc.file) || []}
+          activeTabId={props.activeDocumentId}
+          onTabSelect={props.onTabSelect}
+          onTabClose={props.onTabClose}
+        />
+        <div className="flex-1 overflow-auto">
+          <DocumentEditorWithComments
+            content={currentDocument.content}
+            format={currentDocument.file.format}
+            annotations={currentDocument.annotations}
+            currentUserId={currentUser.id}
+            currentUserName={currentUser.name}
+            readOnly={mode === 'readonly'}
+            onAnnotationAdd={handleAnnotationAdd}
+            onAnnotationUpdate={handleAnnotationUpdate}
+            className="p-6"
+          />
+        </div>
+      </div>
     )
   }
 )

package/components/features/AIDocEditor/README.md

@@ -2,16 +2,21 @@
 
 Document editor with inline comment annotations for AI-powered document review workflows.
 
+Supports both single-document and multi-tab modes for flexible document management.
+
 ## Architecture
 
-- **Component Layer**: Pure UI component (`AIDocEditor.tsx`)
-- **Hook Contract**: Interface definition (`useAIDocEditor.d.ts`)
+- **Component Layer**: Pure UI component (`AIDocEditor.tsx`) with mode detection
+- **Hook Contract**: Interface definitions (`useAIDocEditor.d.ts`) for single and multi-tab modes
+- **Composite Layer**: `DocumentTabBar` composite for tab rendering
 - **Mock Implementation**: Storybook testing (`useAIDocEditor.mock.ts`)
 - **Application Layer**: Real implementation (in your app)
 
 ## Usage
 
-### In Your Application (implement hook with real API)
+### Single-Document Mode (Backward Compatible)
+
+#### In Your Application
 
 ```tsx
 // app/hooks/useAIDocEditor.ts
@@ -53,14 +58,89 @@ export function DocEditorContainer({ documentId, content, currentUser }) {
 }
 ```
 
-### In Storybook (use mock hook)
+### Multi-Tab Mode
+
+#### In Your Application
 
 ```tsx
+// app/hooks/useMultiTabDocEditor.ts
+import type { UseAIMultiTabDocEditorReturn, DocumentWithAnnotations } from 'ui-lib/components/features/AIDocEditor';
+
+export function useAIMultiTabDocEditor(): UseAIMultiTabDocEditorReturn {
+  const [documents, setDocuments] = useState<DocumentWithAnnotations[]>([]);
+  const [activeDocumentId, setActiveDocumentId] = useState<string>();
+  const [loading, setLoading] = useState(false);
+
+  const switchDocument = (documentId: string) => {
+    setActiveDocumentId(documentId);
+  };
+
+  const closeDocument = (documentId: string) => {
+    setDocuments(prev => {
+      const filtered = prev.filter(doc => doc.file.id !== documentId);
+      if (activeDocumentId === documentId && filtered.length > 0) {
+        setActiveDocumentId(filtered[0].file.id);
+      }
+      return filtered;
+    });
+  };
+
+  const addAnnotation = async (documentId: string, annotation: Annotation) => {
+    setLoading(true);
+    await api.createAnnotation(documentId, annotation);
+    setDocuments(prev =>
+      prev.map(doc =>
+        doc.file.id === documentId
+          ? { ...doc, annotations: [...doc.annotations, annotation] }
+          : doc
+      )
+    );
+    setLoading(false);
+  };
+
+  // ... other methods
+
+  return {
+    documents,
+    activeDocumentId,
+    switchDocument,
+    closeDocument,
+    addAnnotation,
+    // ... other methods
+  };
+}
+```
+
+```tsx
+// app/components/MultiDocEditorContainer.tsx
 import { AIDocEditor } from 'ui-lib/components/features/AIDocEditor';
-import { useMockAIDocEditor } from 'ui-lib/components/features/AIDocEditor';
+import { useAIMultiTabDocEditor } from '../hooks/useMultiTabDocEditor';
+
+export function MultiDocEditorContainer({ currentUser }) {
+  const { documents, activeDocumentId, switchDocument, closeDocument } = useAIMultiTabDocEditor();
+
+  return (
+    <AIDocEditor
+      documents={documents}
+      activeDocumentId={activeDocumentId}
+      currentUser={currentUser}
+      mode="review"
+      onTabSelect={switchDocument}
+      onTabClose={closeDocument}
+    />
+  );
+}
+```
+
+### In Storybook (use mock hook)
+
+#### Single-Document Mode
+
+```tsx
+import { AIDocEditor, useAIDocEditorMock, sampleAnnotations } from 'ui-lib/components/features/AIDocEditor';
 
 export const Default = () => {
-  const { annotations, addAnnotation, updateAnnotation } = useMockAIDocEditor();
+  const { annotations, addAnnotation, updateAnnotation } = useAIDocEditorMock(sampleAnnotations);
 
   return (
     <AIDocEditor
@@ -75,9 +155,36 @@ export const Default = () => {
 };
 ```
 
-## Hook Contract
+#### Multi-Tab Mode
+
+```tsx
+import { 
+  AIDocEditor, 
+  useAIMultiTabDocEditorMock, 
+  sampleMultiTabDocuments 
+} from 'ui-lib/components/features/AIDocEditor';
+
+export const MultiTab = () => {
+  const [documents, activeDocumentId, , , switchDocument, closeDocument] = Object.values(
+    useAIMultiTabDocEditorMock(sampleMultiTabDocuments)
+  );
+
+  return (
+    <AIDocEditor
+      documents={documents}
+      activeDocumentId={activeDocumentId}
+      currentUser={mockUser}
+      mode="review"
+      onTabSelect={switchDocument}
+      onTabClose={closeDocument}
+    />
+  );
+};
+```
+
+## Hook Contracts
 
-### `UseAIDocEditorReturn`
+### `UseAIDocEditorReturn` (Single-Document, Deprecated)
 
 ```typescript
 interface UseAIDocEditorReturn {
@@ -89,38 +196,83 @@ interface UseAIDocEditorReturn {
 }
 ```
 
+### `UseAIMultiTabDocEditorReturn` (Multi-Tab, Recommended)
+
+```typescript
+interface UseAIMultiTabDocEditorReturn {
+  documents: DocumentWithAnnotations[];
+  activeDocumentId?: string;
+  addDocument: (file: DocumentFile, content: string | JSONContent) => void;
+  closeDocument: (documentId: string) => void;
+  switchDocument: (documentId: string) => void;
+  addAnnotation: (documentId: string, annotation: Annotation) => Promise<void> | void;
+  updateAnnotation: (documentId: string, annotation: Annotation) => Promise<void> | void;
+  deleteAnnotation: (documentId: string, annotationId: string) => Promise<void> | void;
+  setDocumentDirty: (documentId: string, isDirty: boolean) => void;
+  loading: boolean;
+}
+```
+
 ## Component Props
 
-### `AIDocEditorProps`
+### `AIDocEditorSingleProps` (Single-Document Mode)
 
 ```typescript
-interface AIDocEditorProps {
+interface AIDocEditorSingleProps {
   content: JSONContent | string;
   format?: 'json' | 'markdown';
   annotations: Annotation[];
   selectedAnnotationId?: string;
   currentUser: User;
   mode: 'review' | 'readonly';
-  onContentUpdate?: (content: JSONContent) => void;
-  onAnnotationClick?: (annotation: Annotation) => void;
-  onAnnotationHover?: (annotation: Annotation | null) => void;
-  onTextSelect?: (range: { from: number; to: number }, selectedText: string) => void;
-  onAnnotationAdd?: (annotation: Annotation) => void;
-  onAnnotationUpdate?: (annotation: Annotation) => void;
-  onAnnotationDelete?: (annotationId: string) => void;
-  className?: string;
+  // ... event callbacks (onAnnotationAdd, etc.)
 }
 ```
 
+### `AIDocEditorMultiTabProps` (Multi-Tab Mode)
+
+```typescript
+interface AIDocEditorMultiTabProps {
+  documents: DocumentWithAnnotations[];
+  activeDocumentId?: string;
+  currentUser: User;
+  mode: 'review' | 'readonly';
+  onTabSelect?: (documentId: string) => void;
+  onTabClose?: (documentId: string) => void;
+  // ... other event callbacks
+}
+```
+
+### Shared Props (Both Modes)
+
+```typescript
+onContentUpdate?: (content: JSONContent) => void;
+onAnnotationClick?: (annotation: Annotation) => void;
+onAnnotationHover?: (annotation: Annotation | null) => void;
+onTextSelect?: (range: { from: number; to: number }, selectedText: string) => void;
+onAnnotationAdd?: (annotation: Annotation) => void;
+onAnnotationUpdate?: (annotation: Annotation) => void;
+onAnnotationDelete?: (annotationId: string) => void;
+className?: string;
+```
+
 ## Files
 
-- `AIDocEditor.tsx` - Main component implementation
-- `AIDocEditor.stories.tsx` - Storybook stories and examples
-- `AIDocEditor.behaviors.stories.tsx` - Behavior-driven stories
-- `AIDocEditor.mocks.ts` - Shared mock data
-- `useAIDocEditor.d.ts` - Hook contract definition
-- `useAIDocEditor.mock.ts` - Mock implementation for testing
+- `AIDocEditor.tsx` - Main component implementation with mode detection
+- `AIDocEditor.stories.tsx` - Storybook stories for both single-doc and multi-tab modes
+- `AIDocEditor.behaviors.stories.tsx` - Behavior-driven stories including tab interactions
+- `AIDocEditor.mocks.ts` - Shared mock data for both modes
+- `useAIDocEditor.d.ts` - Hook contract definitions
+- `useAIDocEditor.mock.ts` - Mock implementations for both single and multi-tab modes
 - `index.ts` - Public exports
+- `README.md` - This file
+
+## Composites Used
+
+- `DocumentTabBar` - VS Code-style tab bar for multi-document display
+  - Displays open documents as tabs with dirty indicators
+  - Handles tab selection and closing
+  - Horizontally scrollable when many tabs are open
 
 ## References