ai-design-system 0.1.0

package/components/features/RefinementPanel/RefinementPanel.stories.tsx

@@ -0,0 +1,141 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { RefinementPanel } from "./RefinementPanel";
+import type { PromptInputMessage } from "@/components/ai-elements/prompt-input";
+import { useMockRefinementPanel } from "./useRefinementPanel.mock";
+import { inputStateMessages, reviewStateMessages, sampleFileChanges } from "./RefinementPanel.mocks";
+import * as React from "react";
+
+const meta: Meta<typeof RefinementPanel> = {
+  title: "Features/RefinementPanel",
+  component: RefinementPanel,
+  parameters: {
+    layout: "fullscreen",
+  },
+} satisfies Meta<typeof RefinementPanel>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * Input State - Clean interface for submitting refinement requests
+ *
+ * Shows:
+ * - Conversation history with previous interactions
+ * - Prompt input for new refinement requests
+ * - Simple, focused layout
+ */
+export const InputState: Story = {
+  args: {
+    messages: inputStateMessages,
+    placeholder: "Ask a question or describe a task...",
+    onSubmit: (message: PromptInputMessage) => {
+      console.log("Submitted:", message);
+      alert(`Submitted: ${message.text}`);
+    },
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Clean input interface for submitting refinement requests with conversation history. The user can type and submit new requests.",
+      },
+    },
+  },
+};
+
+/**
+ * Input State - Empty conversation
+ *
+ * Shows the empty state when no messages exist yet
+ */
+export const InputStateEmpty: Story = {
+  args: {
+    messages: [],
+    placeholder: "Ask a question or describe a task...",
+    onSubmit: (message: PromptInputMessage) => {
+      console.log("Submitted:", message);
+    },
+  },
+};
+
+/**
+ * Multi-Agent Review State - Full workflow with agents, file changes, and approval
+ *
+ * Shows:
+ * - Agent conversations with orchestrator and specialists
+ * - Tool call displays showing agent actions
+ * - Sub-agent indicators with status
+ * - File change queue with approve/reject buttons
+ * - Disabled input (textarea editable, submit blocked)
+ */
+export const MultiAgentReviewState: Story = {
+  args: {
+    messages: reviewStateMessages,
+    fileChanges: sampleFileChanges,
+    placeholder: "Continue refinement...",
+    onSubmit: (message: PromptInputMessage) => {
+      console.log("Submit blocked during review:", message);
+    },
+    onApprove: () => {
+      console.log("Approved all changes");
+      alert("✅ All changes approved!");
+    },
+    onReject: () => {
+      console.log("Rejected all changes");
+      alert("❌ All changes rejected!");
+    },
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Full multi-agent review interface showing agent conversations, file changes, tool calls, and approval workflow. The input is disabled during review.",
+      },
+    },
+  },
+};
+
+/**
+ * With State Management - Interactive behavior demonstration
+ *
+ * Demonstrates the complete refinement workflow with mocked state management:
+ * 1. User submits a refinement request
+ * 2. System transitions to review state with file changes
+ * 3. User approves or rejects changes
+ * 4. System returns to input state
+ *
+ * This story uses the useMockRefinementPanel hook to simulate realistic interaction patterns.
+ * Use this mock hook as a reference for implementing real application hooks.
+ */
+export const WithStateManagement: Story = {
+  render: () => {
+    // Use mocked hook for state management
+    const { messages, fileChanges, handleSubmit, handleApprove, handleReject } =
+      useMockRefinementPanel({
+        initialMessages: inputStateMessages,
+        reviewMessages: reviewStateMessages,
+        reviewFileChanges: sampleFileChanges,
+        apiDelay: 800,
+      });
+
+    return (
+      <RefinementPanel
+        messages={messages}
+        fileChanges={fileChanges}
+        placeholder="Ask a question or describe a task..."
+        onSubmit={handleSubmit}
+        onApprove={handleApprove}
+        onReject={handleReject}
+      />
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Interactive demonstration of the complete refinement workflow using the useMockRefinementPanel hook. This story simulates realistic user interactions including submission delays, state transitions, and approval/rejection flows. Use this mock hook as a reference for implementing real application hooks.",
+      },
+    },
+  },
+};
+

package/components/features/RefinementPanel/RefinementPanel.tsx

@@ -0,0 +1,160 @@
+"use client";
+
+import * as React from "react";
+import { AIConversation } from "@/components/blocks/AIConversation";
+import { FileChangeQueue } from "@/components/blocks/FileChangeQueue";
+import { PromptInput } from "@/components/composites/PromptInput";
+import type { ToolCall } from "@/components/composites/ToolCallDisplay";
+import type { SubAgent } from "@/components/composites/AgentIndicator";
+import type { FileChangeData } from "@/components/composites/FileQueue";
+import type { PromptInputMessage } from "@/components/ai-elements/prompt-input";
+import type { FormEvent } from "react";
+
+/**
+ * RefinementPanel Feature
+ *
+ * A two-state feature component for AI-powered code refinement workflows.
+ * Enables users to submit refinement requests and review multi-agent generated changes.
+ *
+ * States:
+ * - input: Clean interface for submitting refinement requests
+ * - multi-agent-review: Complex interface showing agent conversations and file changes
+ */
+
+/**
+ * Message data structure for conversation display
+ */
+export interface RefinementMessage {
+  id: string;
+  type: "human" | "ai";
+  role: "user" | "orchestrator" | "specialist";
+  content: string;
+  avatarSrc?: string;
+  avatarName?: string;
+  toolCalls?: ToolCall[];
+  subAgents?: SubAgent[];
+}
+
+/**
+ * RefinementPanel component props
+ */
+export interface RefinementPanelProps {
+  /**
+   * Conversation messages to display
+   */
+  messages: RefinementMessage[];
+  /**
+   * File changes to review
+   */
+  fileChanges?: FileChangeData[];
+  /**
+   * Submit handler for user input
+   */
+  onSubmit: (
+    message: PromptInputMessage,
+    event: FormEvent<HTMLFormElement>
+  ) => void | Promise<void>;
+  /**
+   * Approve handler for file changes
+   */
+  onApprove?: () => void;
+  /**
+   * Reject handler for file changes
+   */
+  onReject?: () => void;
+  /**
+   * Placeholder text for input
+   */
+  placeholder?: string;
+  /**
+   * Additional CSS classes
+   */
+  className?: string;
+}
+
+/**
+ * RefinementPanel component - two-state refinement workflow interface
+ */
+export const RefinementPanel = React.memo<RefinementPanelProps>(
+  ({
+    messages,
+    fileChanges = [],
+    onSubmit,
+    onApprove,
+    onReject,
+    placeholder = "Ask a question or describe a task...",
+    className,
+  }) => {
+    // File change queue state
+    const [fileChangeState, setFileChangeState] = React.useState<
+      "approval-requested" | "approval-responded"
+    >("approval-requested");
+    const [approval, setApproval] = React.useState<
+      { approved?: boolean }
+    >({});
+
+    // Handle approve action
+    const handleApprove = React.useCallback(() => {
+      setFileChangeState("approval-responded");
+      setApproval({ approved: true });
+      onApprove?.();
+    }, [onApprove]);
+
+    // Handle reject action
+    const handleReject = React.useCallback(() => {
+      setFileChangeState("approval-responded");
+      setApproval({ approved: false });
+      onReject?.();
+    }, [onReject]);
+
+    // Reset file change state when fileChanges are cleared
+    React.useEffect(() => {
+      if (fileChanges.length === 0) {
+        setFileChangeState("approval-requested");
+        setApproval({});
+      }
+    }, [fileChanges.length]);
+
+
+
+    return (
+      <div className={`relative flex h-screen flex-col ${className || ""}`}>
+        {/* Conversation Area - Override to prevent double scroll (StickToBottom handles scroll internally) */}
+        <AIConversation
+          messages={messages}
+          showAvatars={true}
+          className="relative min-h-0 flex-1 overflow-visible"
+        />
+
+        {/* File Changes Queue (fixed at bottom, constrained height) */}
+        {fileChanges.length > 0 && (
+          <div className="w-full flex-shrink-0 border-t">
+            <div className="max-h-[40vh] overflow-y-auto bg-background">
+              <FileChangeQueue
+                changes={fileChanges}
+                title="Review and approve these file changes"
+                state={fileChangeState}
+                approval={approval}
+                onApprove={handleApprove}
+                onReject={handleReject}
+              />
+            </div>
+          </div>
+        )}
+
+        {/* Input Area (visible only when no file changes to review) */}
+        {fileChanges.length === 0 && (
+          <div className="w-full flex-shrink-0">
+            <PromptInput
+              placeholder={placeholder}
+              onSubmit={onSubmit}
+              className="border-t"
+            />
+          </div>
+        )}
+      </div>
+    );
+  }
+);
+
+RefinementPanel.displayName = "RefinementPanel";

package/components/features/RefinementPanel/index.ts

@@ -0,0 +1,25 @@
+/**
+ * RefinementPanel Feature
+ *
+ * Export point for the RefinementPanel feature component and related utilities.
+ * 
+ * Component:
+ * - RefinementPanel: Main feature component for refinement workflows
+ * 
+ * Hook Contract:
+ * - useRefinementPanel: Interface definition for application hooks (implement in your app)
+ * - UseRefinementPanelReturn: Return type for the hook
+ * 
+ * Mock Utilities (for testing/development):
+ * - useMockRefinementPanel: Mock implementation for Storybook
+ */
+
+export { RefinementPanel } from "./RefinementPanel";
+export type { RefinementPanelProps, RefinementMessage } from "./RefinementPanel";
+
+// Hook contract definition (implement in your application)
+export type { UseRefinementPanelReturn } from "./useRefinementPanel";
+
+// Mock hook for testing and development
+export { useMockRefinementPanel } from "./useRefinementPanel.mock";
+export type { UseRefinementPanelOptions } from "./useRefinementPanel.mock";

package/components/features/RefinementPanel/useRefinementPanel.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Hook Contract Definition for RefinementPanel
+ * 
+ * This file defines the interface contract between the design system and consuming applications.
+ * It specifies the expected behavior of a real application hook without providing implementation.
+ * 
+ * Applications should implement this interface with real API calls and state management.
+ * The design system provides a mock implementation (useRefinementPanel.mock.ts) for Storybook.
+ */
+
+import type { RefinementMessage } from "./RefinementPanel";
+import type { FileChangeData } from "@/components/composites/FileQueue";
+
+/**
+ * Return type for the refinement panel hook
+ * 
+ * This interface defines what state and handlers the hook must provide
+ * to integrate with the RefinementPanel component.
+ */
+export interface UseRefinementPanelReturn {
+  /** Current conversation messages */
+  messages: RefinementMessage[];
+  
+  /** File changes pending review */
+  fileChanges: FileChangeData[];
+  
+  /** Loading state for async operations */
+  loading: boolean;
+  
+  /** Handle user submission of refinement requests */
+  handleSubmit: () => Promise<void> | void;
+  
+  /** Handle approval of all file changes */
+  handleApprove: () => Promise<void> | void;
+  
+  /** Handle rejection of all file changes */
+  handleReject: () => Promise<void> | void;
+}
+
+/**
+ * Hook for managing refinement panel state and interactions
+ * 
+ * Applications should implement this hook to:
+ * - Fetch and manage conversation messages
+ * - Process user refinement requests via API
+ * - Handle file change approval/rejection workflows
+ * - Manage loading states during async operations
+ * 
+ * @example
+ * ```tsx
+ * // Real application implementation
+ * export function useRefinementPanel(): UseRefinementPanelReturn {
+ *   const [messages, setMessages] = useState<RefinementMessage[]>([]);
+ *   const [fileChanges, setFileChanges] = useState<FileChangeData[]>([]);
+ *   const [loading, setLoading] = useState(false);
+ * 
+ *   const handleSubmit = async () => {
+ *     setLoading(true);
+ *     try {
+ *       const response = await api.submitRefinement(messages);
+ *       setMessages(response.messages);
+ *       setFileChanges(response.fileChanges);
+ *     } finally {
+ *       setLoading(false);
+ *     }
+ *   };
+ * 
+ *   // ... implement handleApprove and handleReject
+ * 
+ *   return { messages, fileChanges, loading, handleSubmit, handleApprove, handleReject };
+ * }
+ * ```
+ */
+export function useRefinementPanel(): UseRefinementPanelReturn;

package/components/features/RefinementPanel/useRefinementPanel.mock.ts

@@ -0,0 +1,121 @@
+import { useState, useCallback } from "react";
+import type { RefinementMessage } from "./RefinementPanel";
+import type { FileChangeData } from "@/components/composites/FileQueue";
+
+/**
+ * Mock hook for RefinementPanel state management
+ * 
+ * This mock simulates the behavior of a real application hook that would:
+ * - Manage conversation messages
+ * - Handle file changes from agent processing
+ * - Process user submissions
+ * - Handle approval/rejection workflows
+ * 
+ * Use this as a reference for implementing real application hooks.
+ */
+export interface UseRefinementPanelReturn {
+  messages: RefinementMessage[];
+  fileChanges: FileChangeData[];
+  loading: boolean;
+  handleSubmit: () => Promise<void>;
+  handleApprove: () => Promise<void>;
+  handleReject: () => Promise<void>;
+}
+
+export interface UseRefinementPanelOptions {
+  initialMessages?: RefinementMessage[];
+  reviewMessages?: RefinementMessage[];
+  reviewFileChanges?: FileChangeData[];
+  apiDelay?: number;
+}
+
+/**
+ * Mock implementation of refinement panel state management
+ * 
+ * @param options - Configuration for mock behavior
+ * @returns State and handlers for refinement workflow
+ */
+export function useMockRefinementPanel(
+  options: UseRefinementPanelOptions = {}
+): UseRefinementPanelReturn {
+  const {
+    initialMessages = [],
+    reviewMessages = [],
+    reviewFileChanges = [],
+    apiDelay = 800,
+  } = options;
+
+  const [messages, setMessages] = useState<RefinementMessage[]>(initialMessages);
+  const [fileChanges, setFileChanges] = useState<FileChangeData[]>([]);
+  const [loading, setLoading] = useState(false);
+
+  // Simulate submission: transition to review state with agent processing
+  const handleSubmit = useCallback(async () => {
+    setLoading(true);
+
+    // Simulate API call delay
+    await new Promise((resolve) => setTimeout(resolve, apiDelay));
+
+    // Transition to review state with agent messages and file changes
+    setMessages(reviewMessages);
+    setFileChanges(reviewFileChanges);
+    setLoading(false);
+  }, [reviewMessages, reviewFileChanges, apiDelay]);
+
+  // Simulate approval: clear file changes and add success message
+  const handleApprove = useCallback(async () => {
+    setLoading(true);
+
+    // Simulate API call delay
+    await new Promise((resolve) => setTimeout(resolve, apiDelay));
+
+    // Add success message and clear file changes
+    setMessages((prev) => [
+      ...prev,
+      {
+        id: `msg-${Date.now()}`,
+        type: "ai",
+        role: "orchestrator",
+        content: "✅ Changes approved and applied successfully!",
+        avatarSrc:
+          "https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?w=32&h=32&fit=crop&crop=face",
+        avatarName: "Coordinator",
+      },
+    ]);
+    setFileChanges([]);
+    setLoading(false);
+  }, [apiDelay]);
+
+  // Simulate rejection: clear file changes and add rejection message
+  const handleReject = useCallback(async () => {
+    setLoading(true);
+
+    // Simulate API call delay
+    await new Promise((resolve) => setTimeout(resolve, apiDelay));
+
+    // Add rejection message and clear file changes
+    setMessages((prev) => [
+      ...prev,
+      {
+        id: `msg-${Date.now()}`,
+        type: "ai",
+        role: "orchestrator",
+        content: "❌ Changes rejected. Let me know how to improve them.",
+        avatarSrc:
+          "https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?w=32&h=32&fit=crop&crop=face",
+        avatarName: "Coordinator",
+      },
+    ]);
+    setFileChanges([]);
+    setLoading(false);
+  }, [apiDelay]);
+
+  return {
+    messages,
+    fileChanges,
+    loading,
+    handleSubmit,
+    handleApprove,
+    handleReject,
+  };
+}