ai-design-system 0.1.0

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

@@ -0,0 +1,142 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { PageLayout } from './PageLayout'
+import { usePageLayoutMock } from './usePageLayout.mock'
+import { mockSidebarConfig, mockHeaderConfig } from './PageLayout.mocks'
+
+const meta = {
+  title: 'Features/PageLayout',
+  component: PageLayout,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+  },
+} satisfies Meta<typeof PageLayout>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/**
+ * Default PageLayout
+ *
+ * Complete page layout with sidebar, header, and content area.
+ */
+export const Default: Story = {
+  args: {
+    sidebar: mockSidebarConfig,
+    header: mockHeaderConfig,
+    defaultSidebarOpen: true,
+    children: (
+      <div className="flex flex-col gap-4 py-4 md:gap-6 md:py-6">
+        <div className="px-4 lg:px-6">
+          <h2 className="text-2xl font-bold">Welcome to Dashboard</h2>
+          <p className="text-muted-foreground">
+            This is the main content area. The sidebar can be toggled using the button in the header.
+          </p>
+        </div>
+        <div className="grid gap-4 px-4 md:grid-cols-2 lg:grid-cols-3 lg:px-6">
+          {[1, 2, 3].map((i) => (
+            <div key={i} className="rounded-lg border p-4">
+              <h3 className="font-semibold">Card {i}</h3>
+              <p className="text-sm text-muted-foreground">Sample content</p>
+            </div>
+          ))}
+        </div>
+      </div>
+    ),
+  },
+}
+
+/**
+ * With State Management
+ *
+ * PageLayout with mock hook for state management demonstration.
+ */
+export const WithStateManagement: Story = {
+  render: () => {
+    const layoutState = usePageLayoutMock()
+    return (
+      <PageLayout
+        sidebar={mockSidebarConfig}
+        header={mockHeaderConfig}
+        defaultSidebarOpen={layoutState.isSidebarOpen}
+      >
+        <div className="@container/main flex flex-1 flex-col gap-2">
+          <div className="flex flex-col gap-4 py-4 md:gap-6 md:py-6">
+            <div className="px-4 lg:px-6">
+              <h2 className="text-2xl font-bold">State Management Demo</h2>
+              <p className="text-muted-foreground">
+                Sidebar is {layoutState.isSidebarOpen ? 'open' : 'closed'}
+              </p>
+            </div>
+            <div className="px-4 lg:px-6">
+              <div className="rounded-lg border p-4">
+                <h3 className="font-semibold">Layout Config</h3>
+                <pre className="mt-2 text-sm">
+                  {JSON.stringify(layoutState.layoutConfig, null, 2)}
+                </pre>
+              </div>
+            </div>
+          </div>
+        </div>
+      </PageLayout>
+    )
+  },
+}
+
+/**
+ * Collapsed Sidebar
+ *
+ * PageLayout with sidebar collapsed by default.
+ */
+export const CollapsedSidebar: Story = {
+  args: {
+    sidebar: mockSidebarConfig,
+    header: mockHeaderConfig,
+    defaultSidebarOpen: false,
+    children: (
+      <div className="flex flex-col gap-4 py-4 md:gap-6 md:py-6">
+        <div className="px-4 lg:px-6">
+          <h2 className="text-2xl font-bold">Collapsed Sidebar</h2>
+          <p className="text-muted-foreground">
+            The sidebar starts collapsed. Click the trigger button to expand it.
+          </p>
+        </div>
+      </div>
+    ),
+  },
+}
+
+/**
+ * With Multiple Sections
+ *
+ * PageLayout with sidebar containing multiple navigation sections.
+ */
+export const WithMultipleSections: Story = {
+  args: {
+    sidebar: {
+      ...mockSidebarConfig,
+      secondaryNavigation: [
+        { title: 'Settings', url: '#', icon: 'settings' },
+        { title: 'Help', url: '#', icon: 'help-circle' },
+      ],
+      documents: [
+        { title: 'Project A', url: '#', icon: 'file' },
+        { title: 'Project B', url: '#', icon: 'file' },
+        { title: 'Project C', url: '#', icon: 'file' },
+      ],
+    },
+    header: mockHeaderConfig,
+    defaultSidebarOpen: true,
+    children: (
+      <div className="flex flex-col gap-4 py-4 md:gap-6 md:py-6">
+        <div className="px-4 lg:px-6">
+          <h2 className="text-2xl font-bold">Multiple Sections</h2>
+          <p className="text-muted-foreground">
+            The sidebar contains main navigation, documents, and secondary navigation sections.
+          </p>
+        </div>
+      </div>
+    ),
+  },
+}
+

package/components/features/PageLayout/PageLayout.tsx

@@ -0,0 +1,94 @@
+import * as React from "react"
+import { AppSidebar, type AppSidebarProps } from "@/components/blocks/AppSidebar"
+import { LayoutProvider } from "@/components/blocks/LayoutProvider"
+import { AppHeader, type AppHeaderProps } from "@/components/composites/AppHeader"
+import { PageContainer } from "@/components/composites/PageContainer"
+
+/**
+ * PageLayout Feature
+ *
+ * Complete page layout with sidebar, header, and content area.
+ * Composes AppSidebar block and AppHeader composite with SidebarProvider.
+ *
+ * This is a self-contained feature component that handles all its own providers
+ * and layout internally. No external wrapping is required.
+ *
+ * @example
+ * ```tsx
+ * <PageLayout
+ *   sidebar={sidebarConfig}
+ *   header={headerConfig}
+ *   defaultSidebarOpen={true}
+ * >
+ *   {children}
+ * </PageLayout>
+ * ```
+ */
+
+export interface PageLayoutProps {
+  /**
+   * Sidebar configuration
+   */
+  sidebar: AppSidebarProps
+  /**
+   * Header configuration
+   */
+  header: AppHeaderProps
+  /**
+   * Page content
+   */
+  children: React.ReactNode
+  /**
+   * Additional CSS classes
+   */
+  className?: string
+  /**
+   * Whether the sidebar is open by default
+   * @default true
+   */
+  defaultSidebarOpen?: boolean
+  /**
+   * Sidebar width CSS variable value
+   * @default "var(--spacing-sidebar-width)"
+   */
+  sidebarWidth?: string
+  /**
+   * Sidebar icon width CSS variable value
+   * @default "var(--spacing-sidebar-width-icon)"
+   */
+  sidebarWidthIcon?: string
+}
+
+/**
+ * PageLayout component
+ *
+ * Provides a complete page layout with sidebar, header, and content area.
+ * Includes SidebarProvider for state management.
+ */
+export const PageLayout = React.memo<PageLayoutProps>(
+  ({ 
+    sidebar, 
+    header, 
+    children, 
+    className,
+    defaultSidebarOpen = true,
+    sidebarWidth = "var(--spacing-sidebar-width)",
+    sidebarWidthIcon = "var(--spacing-sidebar-width-icon)",
+  }) => {
+    return (
+      <LayoutProvider
+        defaultOpen={defaultSidebarOpen}
+        sidebarWidth={sidebarWidth}
+        sidebarWidthIcon={sidebarWidthIcon}
+      >
+        <AppSidebar {...sidebar} />
+        <PageContainer className={className}>
+          <AppHeader {...header} />
+          <div className="flex flex-1 flex-col">{children}</div>
+        </PageContainer>
+      </LayoutProvider>
+    )
+  }
+)
+
+PageLayout.displayName = "PageLayout"

package/components/features/PageLayout/index.ts

@@ -0,0 +1,4 @@
+export { PageLayout } from './PageLayout'
+export type { PageLayoutProps } from './PageLayout'
+export type { UsePageLayout, UsePageLayoutReturn } from './usePageLayout.d'
+export { usePageLayoutMock } from './usePageLayout.mock'

package/components/features/PageLayout/usePageLayout.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Hook contract for PageLayout feature
+ * Manages sidebar state and layout configuration
+ *
+ * @example
+ * ```tsx
+ * const { isSidebarOpen, toggleSidebar, layoutConfig } = usePageLayout()
+ * ```
+ */
+export interface UsePageLayoutReturn {
+  /** Whether the sidebar is currently open */
+  isSidebarOpen: boolean
+  /** Toggle sidebar open/closed */
+  toggleSidebar: () => void
+  /** Set sidebar open state */
+  setSidebarOpen: (open: boolean) => void
+  /** Current layout configuration */
+  layoutConfig: {
+    sidebarWidth: string
+    headerHeight: string
+  }
+}
+
+export type UsePageLayout = () => UsePageLayoutReturn

package/components/features/PageLayout/usePageLayout.mock.ts

@@ -0,0 +1,19 @@
+import { useState } from 'react'
+import type { UsePageLayoutReturn } from './usePageLayout.d'
+
+/**
+ * Mock implementation of usePageLayout hook for Storybook stories
+ */
+export const usePageLayoutMock = (): UsePageLayoutReturn => {
+  const [isSidebarOpen, setIsSidebarOpen] = useState(true)
+
+  return {
+    isSidebarOpen,
+    toggleSidebar: () => setIsSidebarOpen((prev) => !prev),
+    setSidebarOpen: setIsSidebarOpen,
+    layoutConfig: {
+      sidebarWidth: 'var(--spacing-sidebar-width-mobile)',
+      headerHeight: 'var(--spacing-header-height)',
+    },
+  }
+}

package/components/features/RefinementPanel/README.md

@@ -0,0 +1,189 @@
+# RefinementPanel Feature
+
+A comprehensive UI component for managing AI-powered refinement workflows with multi-agent conversations, file changes, and approval processes.
+
+## Architecture
+
+This feature follows the **extensible component pattern** with clear separation between:
+- **Component Layer**: Pure UI component (`RefinementPanel.tsx`)
+- **Hook Contract**: Interface definition (`useRefinementPanel.d.ts`)
+- **Mock Implementation**: Storybook testing (`useRefinementPanel.mock.ts`)
+- **Application Layer**: Real implementation (in your app)
+
+## Usage
+
+### In Your Application
+
+Implement the hook contract with real API calls:
+
+```tsx
+// app/hooks/useRefinementPanel.ts
+import { useState } from 'react';
+import type { UseRefinementPanelReturn } from 'ui-lib/components/features/RefinementPanel';
+
+export function useRefinementPanel(): UseRefinementPanelReturn {
+  const [messages, setMessages] = useState([]);
+  const [fileChanges, setFileChanges] = useState([]);
+  const [loading, setLoading] = useState(false);
+
+  const handleSubmit = async () => {
+    setLoading(true);
+    try {
+      const response = await fetch('/api/refinement/submit', {
+        method: 'POST',
+        body: JSON.stringify({ messages }),
+      });
+      const data = await response.json();
+      setMessages(data.messages);
+      setFileChanges(data.fileChanges);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const handleApprove = async () => {
+    setLoading(true);
+    try {
+      await fetch('/api/refinement/approve', {
+        method: 'POST',
+        body: JSON.stringify({ fileChanges }),
+      });
+      setFileChanges([]);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const handleReject = async () => {
+    setLoading(true);
+    try {
+      await fetch('/api/refinement/reject', {
+        method: 'POST',
+      });
+      setFileChanges([]);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return {
+    messages,
+    fileChanges,
+    loading,
+    handleSubmit,
+    handleApprove,
+    handleReject,
+  };
+}
+```
+
+Then use it with the component:
+
+```tsx
+// app/components/RefinementContainer.tsx
+import { RefinementPanel } from 'ui-lib/components/features/RefinementPanel';
+import { useRefinementPanel } from '../hooks/useRefinementPanel';
+
+export function RefinementContainer() {
+  const { messages, fileChanges, loading, handleSubmit, handleApprove, handleReject } =
+    useRefinementPanel();
+
+  return (
+    <RefinementPanel
+      messages={messages}
+      fileChanges={fileChanges}
+      loading={loading}
+      onSubmit={handleSubmit}
+      onApprove={handleApprove}
+      onReject={handleReject}
+      placeholder="Ask a question or describe a task..."
+    />
+  );
+}
+```
+
+### In Storybook
+
+Use the mock hook for visual testing:
+
+```tsx
+import { RefinementPanel, useMockRefinementPanel } from 'ui-lib/components/features/RefinementPanel';
+
+export const Interactive = () => {
+  const { messages, fileChanges, handleSubmit, handleApprove, handleReject } =
+    useMockRefinementPanel({
+      initialMessages: [...],
+      reviewMessages: [...],
+      reviewFileChanges: [...],
+      apiDelay: 800,
+    });
+
+  return (
+    <RefinementPanel
+      messages={messages}
+      fileChanges={fileChanges}
+      onSubmit={handleSubmit}
+      onApprove={handleApprove}
+      onReject={handleReject}
+    />
+  );
+};
+```
+
+## Hook Contract
+
+### `UseRefinementPanelReturn`
+
+```typescript
+interface UseRefinementPanelReturn {
+  messages: RefinementMessage[];
+  fileChanges: FileChangeData[];
+  loading: boolean;
+  handleSubmit: () => Promise<void> | void;
+  handleApprove: () => Promise<void> | void;
+  handleReject: () => Promise<void> | void;
+}
+```
+
+## Component Props
+
+### `RefinementPanelProps`
+
+```typescript
+interface RefinementPanelProps {
+  messages?: RefinementMessage[];
+  fileChanges?: FileChangeData[];
+  loading?: boolean;
+  placeholder?: string;
+  onSubmit?: (message: PromptInputMessage) => void;
+  onApprove?: () => void;
+  onReject?: () => void;
+}
+```
+
+## States
+
+The component supports multiple workflow states:
+
+1. **Input State**: Clean interface for submitting refinement requests
+2. **Review State**: Multi-agent processing with file changes and approval workflow
+3. **Loading State**: Visual feedback during async operations
+
+## Design Principles
+
+- **Declarative**: Component describes what happens visually, not how logic works
+- **Extensible**: Event props allow integration with any backend
+- **Stateless**: Business logic lives outside the component
+- **Testable**: Mock hook enables isolated visual testing
+
+## Files
+
+- `RefinementPanel.tsx` - Main component implementation
+- `RefinementPanel.stories.tsx` - Storybook stories and examples
+- `useRefinementPanel.d.ts` - Hook contract definition
+- `useRefinementPanel.mock.ts` - Mock implementation for testing
+- `index.ts` - Public exports
+
+## References
+
+See `.claude/skills/design-system/references/extendable-with-state-stories.md` for the complete pattern documentation.