ai-design-system 0.1.0

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

@@ -0,0 +1,140 @@
+/**
+ * AIDocEditor Stories
+ * 
+ * Demonstrates the AIDocEditor feature with various scenarios
+ */
+
+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> = {
+  title: 'Features/AIDocEditor',
+  component: AIDocEditor,
+  parameters: {
+    layout: 'fullscreen',
+  },
+  tags: ['autodocs'],
+}
+
+export default meta
+type Story = StoryObj<typeof AIDocEditor>
+
+/**
+ * Default story with static props
+ * Shows the editor with existing annotations
+ */
+export const Default: Story = {
+  args: {
+    content: sampleContent,
+    annotations: sampleAnnotations,
+    currentUser,
+    mode: 'review',
+    onAnnotationAdd: (annotation) => console.log('Added annotation:', annotation),
+    onAnnotationUpdate: (annotation) => console.log('Updated annotation:', annotation),
+  },
+}
+
+/**
+ * Story with empty document
+ */
+export const EmptyDocument: Story = {
+  args: {
+    content: {
+      type: 'doc',
+      content: [
+        {
+          type: 'paragraph',
+          content: [],
+        },
+      ],
+    },
+    annotations: [],
+    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
+ */
+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()}`
+
+    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>
+    )
+  },
+}

package/components/features/AIDocEditor/AIDocEditor.tsx

@@ -0,0 +1,130 @@
+/**
+ * AIDocEditor Feature Component
+ * 
+ * Complete document editor with inline comment annotations.
+ * Feature layer: uses DocumentEditorWithComments section with data management.
+ * 
+ * @example
+ * ```tsx
+ * <AIDocEditor
+ *   content={document}
+ *   annotations={annotations}
+ *   currentUser={user}
+ *   mode="review"
+ *   onAnnotationAdd={(annotation) => saveAnnotation(annotation)}
+ * />
+ * ```
+ */
+
+import React, { useCallback } from 'react'
+import { DocumentEditorWithComments } from '@/components/blocks/DocumentEditorWithComments'
+import { cn } from '@/lib/utils'
+import type { JSONContent } from '@tiptap/core'
+import type { Annotation, User } from '@/types/ai-editor/annotations'
+
+/**
+ * Props for AIDocEditor feature component
+ */
+export interface AIDocEditorProps {
+  /** 
+   * Document content - can be either:
+   * - JSONContent: Tiptap's JSON format (default)
+   * - string: Markdown string (when format='markdown')
+   */
+  content: JSONContent | string
+  /** 
+   * Content format - determines how content prop is interpreted
+   * - 'json': Content is Tiptap JSONContent (default)
+   * - 'markdown': Content is a markdown string
+   * 
+   * @default 'json'
+   */
+  format?: 'json' | 'markdown'
+  /** Array of annotations to display */
+  annotations: Annotation[]
+  /** ID of currently selected annotation */
+  selectedAnnotationId?: string
+  /** Current user information */
+  currentUser: User
+  /** Editor mode: 'review' allows commenting, 'readonly' disables interactions */
+  mode: 'review' | 'readonly'
+  /** Callback when document content is updated */
+  onContentUpdate?: (content: JSONContent) => void
+  /** Callback when annotation is clicked */
+  onAnnotationClick?: (annotation: Annotation) => void
+  /** Callback when annotation is hovered */
+  onAnnotationHover?: (annotation: Annotation | null) => void
+  /** Callback when text is selected */
+  onTextSelect?: (range: { from: number; to: number }, selectedText: string) => void
+  /** Callback when new annotation is added */
+  onAnnotationAdd?: (annotation: Annotation) => void
+  /** Callback when annotation is updated (e.g., reply added) */
+  onAnnotationUpdate?: (annotation: Annotation) => void
+  /** Callback when annotation is deleted */
+  onAnnotationDelete?: (annotationId: string) => void
+  /** Additional CSS classes */
+  className?: string
+}
+
+/**
+ * AIDocEditor - Document editor with inline comment annotations
+ * 
+ * This feature component provides a complete document review experience with:
+ * - 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)
+ * 
+ * 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,
+  }) => {
+    /**
+     * Handle annotation add - emit event to parent
+     */
+    const handleAnnotationAdd = useCallback(
+      (annotation: Annotation) => {
+        onAnnotationAdd?.(annotation)
+      },
+      [onAnnotationAdd]
+    )
+
+    /**
+     * Handle annotation update - emit event to parent
+     */
+    const handleAnnotationUpdate = useCallback(
+      (annotation: Annotation) => {
+        onAnnotationUpdate?.(annotation)
+      },
+      [onAnnotationUpdate]
+    )
+
+    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)}
+      />
+    )
+  }
+)
+
+AIDocEditor.displayName = 'AIDocEditor'

package/components/features/AIDocEditor/index.ts

@@ -0,0 +1,8 @@
+/**
+ * AIDocEditor Feature Component
+ * 
+ * Complete document editor with inline comment annotations
+ */
+
+export { AIDocEditor } from './AIDocEditor'
+export type { AIDocEditorProps } from './AIDocEditor'

package/components/features/AIDocEditor/useAIDocEditor.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Hook contract for AIDocEditor feature
+ * 
+ * This interface defines the contract for managing document annotations.
+ * Applications should implement this hook to provide real data management,
+ * while Storybook uses mock implementations for visual testing.
+ * 
+ * @example
+ * ```tsx
+ * // Real implementation in application
+ * export function useAIDocEditor(documentId: string): UseAIDocEditorReturn {
+ *   const [annotations, setAnnotations] = useState<Annotation[]>([])
+ *   const [loading, setLoading] = useState(false)
+ * 
+ *   const addAnnotation = async (annotation: Annotation) => {
+ *     setLoading(true)
+ *     await api.createAnnotation(documentId, annotation)
+ *     setAnnotations(prev => [...prev, annotation])
+ *     setLoading(false)
+ *   }
+ * 
+ *   // ... other methods
+ * 
+ *   return { annotations, addAnnotation, updateAnnotation, deleteAnnotation, loading }
+ * }
+ * ```
+ * 
+ * @example
+ * ```tsx
+ * // Usage in component
+ * const MyDocumentEditor = ({ documentId }) => {
+ *   const { annotations, addAnnotation, updateAnnotation, loading } = useAIDocEditor(documentId)
+ * 
+ *   return (
+ *     <AIDocEditor
+ *       content={document}
+ *       annotations={annotations}
+ *       currentUser={user}
+ *       mode="review"
+ *       onAnnotationAdd={addAnnotation}
+ *       onAnnotationUpdate={updateAnnotation}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+
+import type { Annotation } from '@/types/ai-editor/annotations'
+
+/**
+ * Return type for useAIDocEditor hook
+ */
+export interface UseAIDocEditorReturn {
+  /**
+   * Array of annotations for the document
+   */
+  annotations: Annotation[]
+
+  /**
+   * Add a new annotation to the document
+   * @param annotation - The annotation to add
+   */
+  addAnnotation: (annotation: Annotation) => Promise<void> | void
+
+  /**
+   * Update an existing annotation (e.g., add reply, edit comment)
+   * @param annotation - The updated annotation
+   */
+  updateAnnotation: (annotation: Annotation) => Promise<void> | void
+
+  /**
+   * Delete an annotation from the document
+   * @param annotationId - ID of the annotation to delete
+   */
+  deleteAnnotation: (annotationId: string) => Promise<void> | void
+
+  /**
+   * Loading state for async operations
+   */
+  loading: boolean
+}
+
+/**
+ * Hook for managing document annotations
+ * 
+ * Applications must implement this hook to provide real data management.
+ * The hook should handle:
+ * - Fetching annotations from API
+ * - Creating new annotations
+ * - Updating existing annotations
+ * - Deleting annotations
+ * - Managing loading states
+ * 
+ * @param documentId - ID of the document to manage annotations for
+ * @returns Object containing annotations array and mutation methods
+ */
+export function useAIDocEditor(documentId: string): UseAIDocEditorReturn

package/components/features/AIDocEditor/useAIDocEditor.mock.ts

@@ -0,0 +1,83 @@
+/**
+ * Mock implementation of useAIDocEditor hook for Storybook
+ * 
+ * This mock provides realistic state management and simulated async operations
+ * for visual testing and interactive demos in Storybook.
+ */
+
+import { useState, useCallback } from 'react'
+import type { Annotation } from '@/types/ai-editor/annotations'
+import type { UseAIDocEditorReturn } from './useAIDocEditor'
+
+/**
+ * Mock hook for managing document annotations in Storybook
+ * 
+ * Simulates async operations with setTimeout to demonstrate loading states
+ * and realistic user interactions.
+ * 
+ * @param initialAnnotations - Initial annotations to display
+ * @returns Mock implementation of UseAIDocEditorReturn
+ */
+export function useAIDocEditorMock(
+  initialAnnotations: Annotation[] = []
+): UseAIDocEditorReturn {
+  const [annotations, setAnnotations] = useState<Annotation[]>(initialAnnotations)
+  const [loading, setLoading] = useState(false)
+
+  /**
+   * Add a new annotation with simulated async delay
+   */
+  const addAnnotation = useCallback(async (annotation: Annotation) => {
+    console.log('[AIDocEditor Mock] Adding annotation:', annotation)
+    setLoading(true)
+    
+    // Simulate API call delay
+    await new Promise(resolve => setTimeout(resolve, 500))
+    
+    setAnnotations(prev => {
+      const updated = [...prev, annotation]
+      console.log('[AIDocEditor Mock] Annotations after add:', updated)
+      return updated
+    })
+    setLoading(false)
+  }, [])
+
+  /**
+   * Update an existing annotation with simulated async delay
+   */
+  const updateAnnotation = useCallback(async (annotation: Annotation) => {
+    console.log('[AIDocEditor Mock] Updating annotation:', annotation)
+    setLoading(true)
+    
+    // Simulate API call delay
+    await new Promise(resolve => setTimeout(resolve, 500))
+    
+    setAnnotations(prev => {
+      const updated = prev.map(a => (a.id === annotation.id ? annotation : a))
+      console.log('[AIDocEditor Mock] Annotations after update:', updated)
+      return updated
+    })
+    setLoading(false)
+  }, [])
+
+  /**
+   * Delete an annotation with simulated async delay
+   */
+  const deleteAnnotation = useCallback(async (annotationId: string) => {
+    setLoading(true)
+    
+    // Simulate API call delay
+    await new Promise(resolve => setTimeout(resolve, 500))
+    
+    setAnnotations(prev => prev.filter(a => a.id !== annotationId))
+    setLoading(false)
+  }, [])
+
+  return {
+    annotations,
+    addAnnotation,
+    updateAnnotation,
+    deleteAnnotation,
+    loading,
+  }
+}

package/components/features/PageLayout/PageLayout.behaviors.stories.tsx

@@ -0,0 +1,119 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { expect, fn, userEvent, waitFor, within } from '@storybook/test'
+import { PageLayout } from './PageLayout'
+import { mockSidebarConfig, mockHeaderConfig } from './PageLayout.mocks'
+
+const meta = {
+  title: 'Features/PageLayout/Behaviors',
+  component: PageLayout,
+  tags: ['test'],
+  parameters: {
+    layout: 'fullscreen',
+  },
+} satisfies Meta<typeof PageLayout>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/**
+ * Sidebar Toggle Behavior
+ *
+ * Tests that the sidebar can be toggled using the trigger button.
+ */
+export const SidebarToggle: Story = {
+  args: {
+    sidebar: mockSidebarConfig,
+    header: mockHeaderConfig,
+    defaultSidebarOpen: true,
+    children: <div>Content</div>,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement)
+
+    // Find the sidebar trigger button
+    const trigger = canvas.getByRole('button', { name: /toggle sidebar/i })
+    await expect(trigger).toBeInTheDocument()
+
+    // Get the sidebar element to check its state
+    const sidebar = canvasElement.querySelector('[data-sidebar="sidebar"]')
+    await expect(sidebar).toBeInTheDocument()
+
+    // Click to toggle sidebar
+    await userEvent.click(trigger)
+
+    // Wait for the state change and verify sidebar collapsed
+    await waitFor(() => {
+      const sidebarWrapper = canvasElement.querySelector('[data-state]')
+      expect(sidebarWrapper).toHaveAttribute('data-state', 'collapsed')
+    })
+  },
+}
+
+/**
+ * Navigation Click Behavior
+ *
+ * Tests that navigation items are clickable and callbacks are invoked.
+ */
+export const NavigationClick: Story = {
+  args: {
+    sidebar: mockSidebarConfig,
+    header: mockHeaderConfig,
+    defaultSidebarOpen: true,
+    children: <div>Content</div>,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement)
+
+    // Find a navigation link
+    const dashboardLink = canvas.getByText('Dashboard')
+    await expect(dashboardLink).toBeInTheDocument()
+
+    // Click the navigation item
+    await userEvent.click(dashboardLink)
+
+    // Verify it's still in the document (navigation occurred)
+    await expect(dashboardLink).toBeInTheDocument()
+  },
+}
+
+/**
+ * User Menu Interaction
+ *
+ * Tests that the user menu can be opened and callbacks are invoked.
+ */
+export const UserMenuInteraction: Story = {
+  args: {
+    sidebar: {
+      ...mockSidebarConfig,
+      userActions: [
+        { label: 'Profile', onClick: fn() },
+        { label: 'Logout', onClick: fn() },
+      ],
+    },
+    header: mockHeaderConfig,
+    defaultSidebarOpen: true,
+    children: <div>Content</div>,
+  },
+  play: async ({ args, canvasElement }) => {
+    const canvas = within(canvasElement)
+
+    // Find the user menu button (by user name)
+    const userButton = canvas.getByText('John Doe')
+    await expect(userButton).toBeInTheDocument()
+
+    // Click to open menu
+    await userEvent.click(userButton)
+
+    // Verify menu items appear
+    const profileItem = await canvas.findByText('Profile')
+    await expect(profileItem).toBeInTheDocument()
+
+    // Click the Profile menu item
+    await userEvent.click(profileItem)
+
+    // Verify the callback was called
+    await waitFor(() => {
+      expect(args.sidebar.userActions?.[0].onClick).toHaveBeenCalled()
+    })
+  },
+}

package/components/features/PageLayout/PageLayout.mocks.ts

@@ -0,0 +1,27 @@
+/**
+ * Mock data for PageLayout feature stories
+ */
+
+export const mockSidebarConfig = {
+  logo: { icon: 'command', text: 'Acme Inc.', href: '/' },
+  mainNavigation: [
+    { title: 'Dashboard', url: '#', icon: 'layout-dashboard', isActive: true },
+    { title: 'Projects', url: '#', icon: 'folder' },
+    { title: 'Tasks', url: '#', icon: 'check-square' },
+    { title: 'Analytics', url: '#', icon: 'bar-chart' },
+  ],
+  user: {
+    name: 'John Doe',
+    email: 'john@example.com',
+    avatar: 'https://github.com/shadcn.png',
+  },
+  userActions: [
+    { label: 'Profile', onClick: () => console.log('Profile') },
+    { label: 'Settings', onClick: () => console.log('Settings') },
+    { label: 'Logout', onClick: () => console.log('Logout') },
+  ],
+}
+
+export const mockHeaderConfig = {
+  title: 'Dashboard',
+}