ai-design-system 0.1.0

package/components/composites/DocumentEditor/DocumentEditor.tsx

@@ -0,0 +1,279 @@
+/**
+ * DocumentEditor Block
+ * 
+ * Tiptap-based read-only editor with annotation overlays
+ * Block layer: uses primitives and Tiptap extensions only
+ */
+
+import React, { useEffect } from 'react'
+import './DocumentEditor.css'
+import { useEditor, EditorContent } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import Highlight from '@tiptap/extension-highlight'
+import { Markdown } from '@tiptap/markdown'
+import { cn } from '@/lib/utils'
+import {
+  CommentMark,
+  PendingCommentMark,
+  SuggestionInsertMark,
+  SuggestionDeleteMark,
+  SuggestionModifyMark,
+  BlockAdditionNode,
+} from '@/extensions/tiptap'
+import { applyAnnotationsToEditor } from '@/utils/editor-annotations'
+import type { DocumentEditorProps } from '@/types/ai-editor'
+
+export const DocumentEditor = React.memo<DocumentEditorProps>(
+  ({
+    content,
+    format = 'json',
+    annotations,
+    selectedAnnotationId,
+    hoveredAnnotationId,
+    pendingCommentRange,
+    onTextSelect,
+    onAnnotationClick,
+    onAnnotationHover,
+    readOnly = true,
+    className,
+  }) => {
+    const editor = useEditor({
+      extensions: [
+        StarterKit,
+        Highlight,
+        Markdown,
+        CommentMark,
+        PendingCommentMark,
+        SuggestionInsertMark,
+        SuggestionDeleteMark,
+        SuggestionModifyMark,
+        BlockAdditionNode,
+      ],
+      content,
+      // Tell Tiptap what format the initial content is in
+      contentType: format === 'markdown' ? 'markdown' : 'json',
+      editable: !readOnly,
+      editorProps: {
+        attributes: {
+          class: cn(
+            'prose max-w-none focus:outline-none',
+            'min-h-[200px] p-4',
+            className
+          ),
+        },
+      },
+    })
+
+    // Update content when it changes
+    useEffect(() => {
+      if (editor && content) {
+        // Handle markdown format
+        if (format === 'markdown' && typeof content === 'string') {
+          // Use contentType option to tell Tiptap to parse as markdown
+          editor.commands.setContent(content, { contentType: 'markdown' })
+        } 
+        // Handle JSON format
+        else {
+          const currentContent = editor.getJSON()
+          if (JSON.stringify(currentContent) !== JSON.stringify(content)) {
+            editor.commands.setContent(content)
+          }
+        }
+      }
+    }, [editor, content, format])
+
+    // Apply annotations when they change
+    useEffect(() => {
+      if (editor) {
+        applyAnnotationsToEditor(editor, annotations, selectedAnnotationId, hoveredAnnotationId)
+      }
+    }, [editor, annotations, selectedAnnotationId, hoveredAnnotationId])
+
+    // Apply pending comment highlight (yellow) when user selects text
+    useEffect(() => {
+      if (!editor) return
+
+      if (pendingCommentRange) {
+        const { from, to } = pendingCommentRange
+        
+        // Apply pending comment mark to show yellow highlight
+        // Use transaction to avoid triggering selection events
+        const { state, view } = editor
+        const tr = state.tr
+        tr.addMark(from, to, state.schema.marks.pendingComment.create({ pending: true }))
+        view.dispatch(tr)
+      } else {
+        // Clear all pending comment marks
+        const { state, view } = editor
+        const tr = state.tr
+        
+        state.doc.descendants((node, pos) => {
+          node.marks.forEach((mark) => {
+            if (mark.type.name === 'pendingComment') {
+              tr.removeMark(pos, pos + node.nodeSize, mark.type)
+            }
+          })
+        })
+        
+        if (tr.docChanged) {
+          view.dispatch(tr)
+        }
+      }
+    }, [editor, pendingCommentRange])
+
+    // Handle text selection events - trigger on mouseup (selection complete)
+    useEffect(() => {
+      if (!editor || !onTextSelect) return
+
+      const handleMouseUp = (event: MouseEvent) => {
+        // Check if the click was on an existing annotation
+        // If so, skip text selection handling (annotation click handler will handle it)
+        const target = event.target as HTMLElement
+        const annotationEl = target.closest(
+          '[data-comment-id], [data-suggestion-id], [data-addition-id]'
+        )
+        
+        if (annotationEl) {
+          // This is a click on an existing annotation, not a text selection
+          // The annotation click handler will handle this
+          return
+        }
+        
+        // Small delay to ensure selection is finalized
+        setTimeout(() => {
+          let { from, to, empty } = editor.state.selection
+          if (!empty) {
+            let text = editor.state.doc.textBetween(from, to)
+            
+            // Trim leading whitespace and adjust range
+            const leadingWhitespace = text.match(/^\s+/)
+            if (leadingWhitespace) {
+              from += leadingWhitespace[0].length
+              text = text.trimStart()
+            }
+            
+            // Trim trailing whitespace and adjust range
+            const trailingWhitespace = text.match(/\s+$/)
+            if (trailingWhitespace) {
+              to -= trailingWhitespace[0].length
+              text = text.trimEnd()
+            }
+            
+            // Skip if only whitespace was selected
+            if (!text.trim()) return
+            
+            // Log selected text for API usage
+            console.log('Selected text:', text)
+            console.log('Selection range:', { from, to })
+            
+            // Calculate position for CommentBox based on selection
+            const selection = window.getSelection()
+            if (selection && selection.rangeCount > 0) {
+              const range = selection.getRangeAt(0)
+              const rect = range.getBoundingClientRect()
+              const position = {
+                x: rect.left,
+                y: rect.bottom + 8, // 8px below selection
+              }
+              
+              // Clear the browser selection
+              selection.removeAllRanges()
+              
+              onTextSelect({ from, to }, text, position)
+            } else {
+              onTextSelect({ from, to }, text)
+            }
+          }
+        }, 10)
+      }
+
+      const editorElement = editor.view.dom
+      editorElement.addEventListener('mouseup', handleMouseUp)
+      
+      return () => {
+        editorElement.removeEventListener('mouseup', handleMouseUp)
+      }
+    }, [editor, onTextSelect])
+
+    // Handle annotation click events
+    useEffect(() => {
+      if (!editor || !onAnnotationClick) return
+
+      const handleClick = (event: MouseEvent) => {
+        const target = event.target as HTMLElement
+        const annotationEl = target.closest(
+          '[data-comment-id], [data-suggestion-id], [data-addition-id]'
+        )
+        
+        if (annotationEl) {
+          const id =
+            annotationEl.getAttribute('data-comment-id') ||
+            annotationEl.getAttribute('data-suggestion-id') ||
+            annotationEl.getAttribute('data-addition-id')
+          
+          if (id) {
+            // Calculate position based on the clicked element
+            // Position below the annotation, similar to Google Docs
+            const rect = annotationEl.getBoundingClientRect()
+            const position = {
+              x: rect.left, // Align with left edge of annotation
+              y: rect.bottom + 8, // 8px below the annotation
+            }
+            onAnnotationClick(id, position)
+          }
+        }
+      }
+
+      const editorElement = editor.view.dom
+      editorElement.addEventListener('click', handleClick)
+      
+      return () => {
+        editorElement.removeEventListener('click', handleClick)
+      }
+    }, [editor, onAnnotationClick])
+
+    // Handle annotation hover events
+    useEffect(() => {
+      if (!editor || !onAnnotationHover) return
+
+      const handleMouseOver = (event: MouseEvent) => {
+        const target = event.target as HTMLElement
+        const annotationEl = target.closest(
+          '[data-comment-id], [data-suggestion-id], [data-addition-id]'
+        )
+        
+        if (annotationEl) {
+          const id =
+            annotationEl.getAttribute('data-comment-id') ||
+            annotationEl.getAttribute('data-suggestion-id') ||
+            annotationEl.getAttribute('data-addition-id')
+          
+          if (id) {
+            onAnnotationHover(id)
+          }
+        } else {
+          onAnnotationHover(null)
+        }
+      }
+
+      const editorElement = editor.view.dom
+      editorElement.addEventListener('mouseover', handleMouseOver)
+      
+      return () => {
+        editorElement.removeEventListener('mouseover', handleMouseOver)
+      }
+    }, [editor, onAnnotationHover])
+
+    if (!editor) {
+      return null
+    }
+
+    return (
+      <div className={cn('document-editor-wrapper', className)}>
+        <EditorContent editor={editor} />
+      </div>
+    )
+  }
+)
+
+DocumentEditor.displayName = 'DocumentEditor'

package/components/composites/DocumentEditor/index.ts

@@ -0,0 +1,8 @@
+/**
+ * DocumentEditor Block
+ * 
+ * Exports the DocumentEditor component
+ */
+
+export { DocumentEditor } from './DocumentEditor'
+export type { DocumentEditorProps } from '@/types/ai-editor'

package/components/composites/FileQueue/FileQueue.stories.tsx

@@ -0,0 +1,175 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { useState } from "react";
+import { FileQueue, type FileGroup } from "./FileQueue";
+
+const meta: Meta<typeof FileQueue> = {
+  title: "Blocks/FileQueue",
+  component: FileQueue,
+  parameters: {
+    layout: "padded",
+  },
+  argTypes: {
+    groups: {
+      description: "Array of file groups to display with customizable titles, icons, and files",
+    },
+    selectedFileId: {
+      description: "ID of currently selected file for visual highlighting",
+    },
+    onFileSelect: {
+      description: "Callback function invoked when a file is selected",
+    },
+    className: {
+      description: "Additional CSS classes for custom styling",
+    },
+  },
+} satisfies Meta<typeof FileQueue>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// Sample file groups for stories
+const sampleGroups: FileGroup[] = [
+  {
+    id: "requirements",
+    title: "Requirements",
+    icon: "file-text",
+    iconColor: "text-blue-600 dark:text-blue-500",
+    files: [
+      { id: "req1", name: "requirements.md", path: ".kiro/specs/feature/" },
+      { id: "req2", name: "user-stories.md", path: ".kiro/specs/feature/" },
+      { id: "req3", name: "acceptance-criteria.md", path: ".kiro/specs/feature/" },
+    ],
+    defaultOpen: true,
+  },
+  {
+    id: "design",
+    title: "Design",
+    icon: "layout",
+    iconColor: "text-purple-600 dark:text-purple-500",
+    files: [
+      { id: "design1", name: "design.md", path: ".kiro/specs/feature/" },
+      { id: "design2", name: "architecture.md", path: ".kiro/specs/feature/" },
+    ],
+    defaultOpen: false,
+  },
+  {
+    id: "tasks",
+    title: "Tasks",
+    icon: "check-square",
+    iconColor: "text-green-600 dark:text-green-500",
+    files: [
+      { id: "task1", name: "tasks.md", path: ".kiro/specs/feature/" },
+      { id: "task2", name: "implementation-plan.md", path: ".kiro/specs/feature/" },
+    ],
+    defaultOpen: false,
+  },
+];
+
+/**
+ * Default story demonstrating multiple file groups with different icons and colors.
+ * Shows the generic grouping capability with customizable group properties.
+ */
+export const Default: Story = {
+  args: {
+    groups: sampleGroups,
+  },
+};
+
+/**
+ * Empty state with no file groups.
+ * Demonstrates how the component handles an empty groups array.
+ */
+export const Empty: Story = {
+  args: {
+    groups: [],
+  },
+};
+
+/**
+ * Single group with multiple files.
+ * Shows the component with only one file group, useful for focused displays.
+ */
+export const SingleGroup: Story = {
+  args: {
+    groups: [
+      {
+        id: "components",
+        title: "Components",
+        icon: "box",
+        iconColor: "text-orange-600 dark:text-orange-500",
+        files: [
+          { id: "comp1", name: "Button.tsx", path: "src/components/primitives/" },
+          { id: "comp2", name: "Input.tsx", path: "src/components/primitives/" },
+          { id: "comp3", name: "Card.tsx", path: "src/components/primitives/" },
+        ],
+        defaultOpen: true,
+      },
+    ],
+  },
+};
+
+/**
+ * Multiple groups demonstrating various use cases.
+ * Shows different group configurations including groups without icons.
+ */
+export const MultipleGroups: Story = {
+  args: {
+    groups: [
+      {
+        id: "modified",
+        title: "Modified Files",
+        icon: "file-text",
+        iconColor: "text-blue-600 dark:text-blue-500",
+        files: [
+          { id: "mod1", name: "Button.tsx", path: "src/components/" },
+          { id: "mod2", name: "Input.tsx", path: "src/components/" },
+        ],
+        defaultOpen: true,
+      },
+      {
+        id: "created",
+        title: "Created Files",
+        icon: "plus",
+        iconColor: "text-green-600 dark:text-green-500",
+        files: [
+          { id: "new1", name: "Icon.tsx", path: "src/components/" },
+          { id: "new2", name: "Badge.tsx", path: "src/components/" },
+        ],
+        defaultOpen: false,
+      },
+      {
+        id: "documentation",
+        title: "Documentation",
+        files: [
+          { id: "doc1", name: "README.md" },
+          { id: "doc2", name: "CONTRIBUTING.md" },
+        ],
+        defaultOpen: false,
+      },
+    ],
+  },
+};
+
+/**
+ * File selection with interactive state management.
+ * Demonstrates the selection functionality with visual highlighting and click handling.
+ * Uses React state to manage the selected file ID.
+ */
+export const WithSelection: Story = {
+  render: () => {
+    const [selectedFileId, setSelectedFileId] = useState<string>("req1");
+
+    return (
+      <div className="space-y-4">
+        <div className="text-sm text-muted-foreground">
+          Selected file: <span className="font-mono">{selectedFileId}</span>
+        </div>
+        <FileQueue
+          groups={sampleGroups}
+          selectedFileId={selectedFileId}
+          onFileSelect={setSelectedFileId}
+        />
+      </div>
+    );
+  },
+};

package/components/composites/FileQueue/FileQueue.tsx

@@ -0,0 +1,161 @@
+import * as React from "react";
+import {
+  Queue,
+  QueueSection,
+  QueueSectionTrigger,
+  QueueSectionLabel,
+  QueueSectionContent,
+  QueueList,
+  QueueItem,
+  QueueItemContent,
+} from "@/components/ai-elements/queue";
+import { Icon } from "@/components/primitives/Icon";
+import { cn } from "@/lib/utils";
+
+/**
+ * FileQueue Block
+ *
+ * Generic block component for displaying files organized into collapsible groups.
+ * Supports optional file selection with visual feedback and keyboard navigation.
+ * Uses Queue AI element for structure.
+ */
+
+/**
+ * File item structure
+ */
+export interface FileItem {
+  /** Unique identifier for the file */
+  id: string;
+  /** File name to display */
+  name: string;
+  /** Optional file path to display */
+  path?: string;
+}
+
+/**
+ * File group structure
+ */
+export interface FileGroup {
+  /** Unique identifier for the group */
+  id: string;
+  /** Display title for the group */
+  title: string;
+  /** Optional icon name from icon registry */
+  icon?: string;
+  /** Optional icon color class */
+  iconColor?: string;
+  /** Array of files in this group */
+  files: FileItem[];
+  /** Whether group should be open by default */
+  defaultOpen?: boolean;
+}
+
+/**
+ * FileQueue component props
+ */
+export interface FileQueueProps {
+  /** Array of file groups to display */
+  groups: FileGroup[];
+  /** ID of currently selected file */
+  selectedFileId?: string;
+  /** Callback when a file is selected */
+  onFileSelect?: (fileId: string) => void;
+  /** Additional CSS classes */
+  className?: string;
+}
+
+/**
+ * FileQueue component - displays files organized into collapsible groups
+ */
+export const FileQueue = React.memo<FileQueueProps>(
+  ({ groups, selectedFileId, onFileSelect, className }) => {
+    const handleFileClick = React.useCallback(
+      (fileId: string) => {
+        if (onFileSelect) {
+          onFileSelect(fileId);
+        }
+      },
+      [onFileSelect]
+    );
+
+    const handleKeyDown = React.useCallback(
+      (e: React.KeyboardEvent, fileId: string) => {
+        if (onFileSelect && (e.key === "Enter" || e.key === " ")) {
+          e.preventDefault();
+          handleFileClick(fileId);
+        }
+      },
+      [onFileSelect, handleFileClick]
+    );
+
+    return (
+      <Queue className={cn("w-full", className)}>
+        {groups.map((group) => {
+          return (
+            <QueueSection key={group.id} defaultOpen={group.defaultOpen}>
+              <QueueSectionTrigger>
+                <QueueSectionLabel
+                  count={group.files.length}
+                  label={group.title}
+                  icon={
+                    group.icon ? (
+                      <Icon
+                        name={group.icon}
+                        size="sm"
+                        className={group.iconColor}
+                      />
+                    ) : undefined
+                  }
+                />
+              </QueueSectionTrigger>
+              <QueueSectionContent>
+                <QueueList className="max-h-[300px]">
+                  {group.files.length === 0 ? (
+                    <div className="px-4 py-3 text-sm text-muted-foreground italic">
+                      No files yet
+                    </div>
+                  ) : (
+                    group.files.map((file) => {
+                      const isSelected = selectedFileId === file.id;
+                      const isClickable = !!onFileSelect;
+
+                      return (
+                        <QueueItem
+                          key={file.id}
+                          className={cn(
+                            isClickable && "cursor-pointer",
+                            isSelected && "bg-accent"
+                          )}
+                          onClick={() => isClickable && handleFileClick(file.id)}
+                          role={isClickable ? "button" : undefined}
+                          tabIndex={isClickable ? 0 : undefined}
+                          onKeyDown={(e) => handleKeyDown(e, file.id)}
+                          aria-selected={isClickable ? isSelected : undefined}
+                        >
+                          <div className="flex items-start gap-2">
+                            <Icon name="file" size="sm" className="mt-0.5" />
+                            <QueueItemContent>
+                              {file.name}
+                              {file.path && (
+                                <span className="text-muted-foreground/70">
+                                  {" "}
+                                  • {file.path}
+                                </span>
+                              )}
+                            </QueueItemContent>
+                          </div>
+                        </QueueItem>
+                      );
+                    })
+                  )}
+                </QueueList>
+              </QueueSectionContent>
+            </QueueSection>
+          );
+        })}
+      </Queue>
+    );
+  }
+);
+
+FileQueue.displayName = "FileQueue";

package/components/composites/FileQueue/FileStatusBadge.tsx

@@ -0,0 +1,74 @@
+import * as React from "react";
+import { Badge } from "@/components/primitives/Badge";
+import { Icon } from "@/components/primitives/Icon";
+import { cn } from "@/lib/utils";
+
+/**
+ * FileStatusBadge
+ *
+ * Displays file change status with color-coded badge and icon.
+ * Adapted from Tool AI element's status badge pattern.
+ */
+
+export type FileStatus = "pending" | "modified" | "created" | "deleted";
+
+export interface FileStatusBadgeProps {
+  status: FileStatus;
+  className?: string;
+}
+
+const statusConfig: Record<
+  FileStatus,
+  {
+    label: string;
+    icon: string;
+    colorClass: string;
+  }
+> = {
+  pending: {
+    label: "Pending",
+    icon: "loader-2",
+    colorClass: "text-yellow-600 dark:text-yellow-500",
+  },
+  modified: {
+    label: "Modified",
+    icon: "file-text",
+    colorClass: "text-blue-600 dark:text-blue-500",
+  },
+  created: {
+    label: "Created",
+    icon: "plus",
+    colorClass: "text-green-600 dark:text-green-500",
+  },
+  deleted: {
+    label: "Deleted",
+    icon: "x",
+    colorClass: "text-red-600 dark:text-red-500",
+  },
+};
+
+/**
+ * FileStatusBadge component - displays file change status
+ */
+export const FileStatusBadge = React.memo<FileStatusBadgeProps>(
+  ({ status, className }) => {
+    const config = statusConfig[status];
+
+    return (
+      <Badge
+        variant="secondary"
+        className={cn("gap-1.5 rounded-full text-xs", className)}
+      >
+        <Icon
+          name={config.icon}
+          size="xs"
+          className={config.colorClass}
+          aria-hidden="true"
+        />
+        <span className={config.colorClass}>{config.label}</span>
+      </Badge>
+    );
+  }
+);
+
+FileStatusBadge.displayName = "FileStatusBadge";