ai-design-system 0.1.28 → 0.1.30

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

@@ -2,6 +2,9 @@
  * Mock data for PageLayout feature stories
  */
 
+import type { FileChangeData } from '@/components/composites/FileQueue'
+import type { RefinementMessage } from '@/components/features/RefinementPanel'
+
 export const mockSidebarConfig = {
   logo: { icon: 'command', text: 'Acme Inc.', href: '/' },
   mainNavigation: [
@@ -34,3 +37,27 @@ export const mockHeaderConfigWithTabs = {
   ],
   defaultTab: 'agent',
 }
+
+export const mockPageLayoutRefinementMessages: RefinementMessage[] = [
+  {
+    id: '1',
+    type: 'human',
+    role: 'user',
+    content: 'Please optimize this workflow for better performance',
+  },
+  {
+    id: '2',
+    type: 'ai',
+    role: 'orchestrator',
+    content: "I'll analyze the workflow and suggest optimizations for better performance.",
+  },
+]
+
+export const mockPageLayoutFileChanges: FileChangeData[] = [
+  {
+    id: '1',
+    filename: 'workflow.json',
+    status: 'modified',
+    path: 'workflow.json',
+  },
+]

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

@@ -1,11 +1,16 @@
 import type { Meta, StoryObj } from '@storybook/react'
-import { useState } from 'react'
 import { PageLayout } from './PageLayout'
-import { usePageLayoutMock } from './usePageLayout.mock'
-import { mockSidebarConfig, mockHeaderConfig, mockHeaderConfigWithTabs } from './PageLayout.mocks'
-import { WorkflowBuilder } from '@/components/features/WorkflowBuilder'
-import { RefinementPanel } from '@/components/features/RefinementPanel'
-import { mockVersions, mockNodes, mockEdges } from '@/components/features/WorkflowBuilder/WorkflowBuilder.mocks'
+import { usePageLayoutMock, usePageLayoutStoryActionsMock } from './usePageLayout.mock'
+import {
+  mockHeaderConfig,
+  mockHeaderConfigWithTabs,
+  mockPageLayoutFileChanges,
+  mockPageLayoutRefinementMessages,
+  mockSidebarConfig,
+} from './PageLayout.mocks'
+import { WorkflowBuilder } from '../WorkflowBuilder/WorkflowBuilder'
+import { RefinementPanel } from '../RefinementPanel/RefinementPanel'
+import { mockEdges, mockNodes, mockVersions } from '../WorkflowBuilder/WorkflowBuilder.mocks'
 
 const meta = {
   title: 'Features/PageLayout',
@@ -33,8 +38,8 @@ export const Default: Story = {
       {
         id: 'file-explorer',
         content: (
-          <div className="h-full bg-muted rounded-lg border p-4">
-            <h3 className="font-medium mb-2">File Explorer</h3>
+          <div className="h-full rounded-lg border bg-muted p-4">
+            <h3 className="mb-2 font-medium">File Explorer</h3>
             <p className="text-sm text-muted-foreground">Project files and folders</p>
           </div>
         ),
@@ -47,8 +52,8 @@ export const Default: Story = {
       {
         id: 'editor',
         content: (
-          <div className="h-full bg-muted rounded-lg border p-4">
-            <h3 className="font-medium mb-2">Editor</h3>
+          <div className="h-full rounded-lg border bg-muted p-4">
+            <h3 className="mb-2 font-medium">Editor</h3>
             <p className="text-sm text-muted-foreground">Main editing area</p>
           </div>
         ),
@@ -66,8 +71,8 @@ export const Default: Story = {
       {
         id: 'properties',
         content: (
-          <div className="h-full bg-muted rounded-lg border p-4">
-            <h3 className="font-medium mb-2">Properties</h3>
+          <div className="h-full rounded-lg border bg-muted p-4">
+            <h3 className="mb-2 font-medium">Properties</h3>
             <p className="text-sm text-muted-foreground">File and project properties</p>
           </div>
         ),
@@ -91,40 +96,18 @@ export const Default: Story = {
 export const WithStateManagement: Story = {
   render: () => {
     const layoutState = usePageLayoutMock()
-    
-    // Mock data for RefinementPanel
-    const mockMessages = [
-      {
-        id: '1',
-        type: 'human' as const,
-        role: 'user' as const,
-        content: 'Please optimize this workflow for better performance',
-      },
-      {
-        id: '2',
-        type: 'ai' as const,
-        role: 'orchestrator' as const,
-        content: 'I\'ll analyze the workflow and suggest optimizations for better performance.',
-      },
-    ]
-    
-    const mockFileChanges = [
-      {
-        id: '1',
-        filename: 'workflow.json',
-        status: 'modified' as const,
-        path: 'workflow.json',
-        changes: '+ Added parallel processing\n+ Optimized node connections',
-      },
-    ]
-    
+    const actions = usePageLayoutStoryActionsMock()
+
     return (
       <PageLayout
         sidebar={mockSidebarConfig}
         header={{
           ...mockHeaderConfigWithTabs,
+          defaultTab: layoutState.activeTab,
           onTabChange: layoutState.onTabChange,
         }}
+        isLoading={layoutState.isLoading}
+        loadingMessage={layoutState.loadingMessage}
         defaultSidebarOpen={layoutState.isSidebarOpen}
         layoutSections={[
           {
@@ -136,11 +119,10 @@ export const WithStateManagement: Story = {
                 versions={mockVersions}
                 nodes={mockNodes}
                 edges={mockEdges}
-                onVersionSelect={(id) => console.log('Selected version:', id)}
-                onSave={() => console.log('Workflow saved')}
-                onCancel={() => console.log('Cancelled')}
-                onUndo={() => console.log('Undo')}
-                onRedo={() => console.log('Redo')}
+                onVersionSelect={actions.onVersionSelect}
+                onSave={actions.onSave}
+                onUndo={actions.onUndo}
+                onRedo={actions.onRedo}
                 hasUnsavedChanges={true}
                 canUndo={true}
                 canRedo={false}
@@ -154,13 +136,11 @@ export const WithStateManagement: Story = {
             id: 'refinement-panel',
             content: (
               <RefinementPanel
-                messages={mockMessages}
-                fileChanges={mockFileChanges}
-                onSubmit={(message, event) => {
-                  console.log('Refinement request:', message)
-                }}
-                onApprove={() => console.log('Changes approved')}
-                onReject={() => console.log('Changes rejected')}
+                messages={mockPageLayoutRefinementMessages}
+                fileChanges={mockPageLayoutFileChanges}
+                onSubmit={actions.onSubmit}
+                onApprove={actions.onApprove}
+                onReject={actions.onReject}
                 placeholder="Ask for workflow optimizations or describe changes..."
               />
             ),

package/components/features/PageLayout/PageLayout.tsx

@@ -2,10 +2,30 @@ import * as React from "react"
 import { AppSidebar, type AppSidebarProps } from "@/components/blocks/AppSidebar"
 import { LayoutProvider } from "@/components/blocks/LayoutProvider"
 import { SectionLayout } from "@/components/blocks/SectionLayout/SectionLayout"
-import type { SectionLayoutProps, SectionLayoutSection } from "@/components/blocks/SectionLayout/interfaces"
+import type { SectionLayoutSection } from "@/components/blocks/SectionLayout/interfaces"
 import { AppHeader, type AppHeaderProps } from "@/components/composites/AppHeader"
 import { PageContainer } from "@/components/composites/PageContainer"
 
+function PageLayoutLoadingState({ message }: { message: string }) {
+  return (
+    <div className="flex h-full min-h-0 flex-1 items-center justify-center px-6 py-10">
+      <div className="w-full max-w-3xl space-y-5">
+        <div className="inline-flex w-fit animate-pulse rounded-md bg-muted px-3 py-1 text-sm text-muted-foreground">
+          {message}
+        </div>
+        <div className="space-y-3">
+          <div className="h-10 w-1/3 animate-pulse rounded-md bg-muted/70" />
+          <div className="h-24 w-full animate-pulse rounded-xl bg-muted/60" />
+          <div className="grid gap-3 md:grid-cols-2">
+            <div className="h-36 animate-pulse rounded-xl bg-muted/55" />
+            <div className="h-36 animate-pulse rounded-xl bg-muted/55" />
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}
+
 /**
  * PageLayout Feature
  *
@@ -44,8 +64,9 @@ import { PageContainer } from "@/components/composites/PageContainer"
 export interface PageLayoutProps {
   /**
    * Sidebar configuration
+   * Optional for apps that need header + content layout without a sidebar.
    */
-  sidebar: AppSidebarProps
+  sidebar?: AppSidebarProps
   /**
    * Header configuration
    */
@@ -55,6 +76,24 @@ export interface PageLayoutProps {
    * Optional when layoutSections is provided
    */
   children?: React.ReactNode
+  /**
+   * Whether the page content should render a built-in loading state.
+   */
+  isLoading?: boolean
+  /**
+   * Optional loading message shown inside the built-in shimmer state.
+   * @default "Loading..."
+   */
+  loadingMessage?: string
+  /**
+   * Optional custom shimmer/loading UI provided by the consumer.
+   * When omitted, PageLayout renders its built-in default shimmer state.
+   */
+  loadingShimmer?: React.ReactNode
+  /**
+   * Custom loading fallback. When provided, this replaces the built-in shimmer layout.
+   */
+  loadingFallback?: React.ReactNode
   /**
    * Additional CSS classes
    */
@@ -106,6 +145,10 @@ export const PageLayout = React.memo<PageLayoutProps>(
     sidebar, 
     header, 
     children, 
+    isLoading = false,
+    loadingMessage = "Loading...",
+    loadingShimmer,
+    loadingFallback,
     className,
     defaultSidebarOpen = true,
     sidebarWidth = "var(--spacing-sidebar-width)",
@@ -115,18 +158,33 @@ export const PageLayout = React.memo<PageLayoutProps>(
     layoutStorageKey,
     dragHandleColor = "border",
   }) => {
-    const contentArea = layoutSections ? (
-      <SectionLayout
-        sections={layoutSections}
-        orientation={layoutOrientation}
-        storageKey={layoutStorageKey}
-        dragHandleColor={dragHandleColor}
-        className="flex-1 min-h-0"
-      />
-    ) : (
-      <div className="flex min-h-0 flex-1 flex-col">{children}</div>
+    const contentArea = isLoading
+      ? (loadingShimmer ?? loadingFallback ?? <PageLayoutLoadingState message={loadingMessage} />)
+      : layoutSections ? (
+          <SectionLayout
+            sections={layoutSections}
+            orientation={layoutOrientation}
+            storageKey={layoutStorageKey}
+            dragHandleColor={dragHandleColor}
+            className="flex-1 min-h-0"
+          />
+        ) : (
+          <div className="flex min-h-0 flex-1 flex-col">{children}</div>
+        )
+
+    const pageContainer = (
+      <PageContainer className={`overflow-hidden ${className ?? ""}`}>
+        <AppHeader {...header} />
+        <div className={`min-h-0 flex-1 overflow-x-hidden ${layoutSections ? "overflow-hidden" : "overflow-y-auto"}`}>
+          {contentArea}
+        </div>
+      </PageContainer>
     )
 
+    if (!sidebar) {
+      return pageContainer
+    }
+
     return (
       <LayoutProvider
         defaultOpen={defaultSidebarOpen}
@@ -134,12 +192,7 @@ export const PageLayout = React.memo<PageLayoutProps>(
         sidebarWidthIcon={sidebarWidthIcon}
       >
         <AppSidebar {...sidebar} />
-        <PageContainer className={`overflow-hidden ${className ?? ""}`}>
-          <AppHeader {...header} />
-          <div className={`min-h-0 flex-1 overflow-x-hidden ${layoutSections ? "overflow-hidden" : "overflow-y-auto"}`}>
-            {contentArea}
-          </div>
-        </PageContainer>
+        {pageContainer}
       </LayoutProvider>
     )
   }

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

@@ -12,6 +12,10 @@ export interface UsePageLayoutReturn {
   isSidebarOpen: boolean
   /** Currently active tab value */
   activeTab: string
+  /** Whether a page-level loading state is active */
+  isLoading: boolean
+  /** Optional message for the page-level loading state */
+  loadingMessage?: string
   /** Toggle sidebar open/closed */
   toggleSidebar: () => void
   /** Set sidebar open state */

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

@@ -1,4 +1,6 @@
-import { useState, useCallback } from 'react'
+import { useState, useCallback, useEffect, useRef } from 'react'
+import type { FormEvent } from 'react'
+import type { PromptInputMessage } from '@/components/ai-elements/prompt-input'
 import type { UsePageLayoutReturn } from './usePageLayout.d'
 
 /**
@@ -7,15 +9,36 @@ import type { UsePageLayoutReturn } from './usePageLayout.d'
 export const usePageLayoutMock = (): UsePageLayoutReturn => {
   const [isSidebarOpen, setIsSidebarOpen] = useState(true)
   const [activeTab, setActiveTab] = useState('agent')
+  const [isLoading, setIsLoading] = useState(false)
+  const loadingTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  useEffect(() => {
+    return () => {
+      if (loadingTimerRef.current) {
+        clearTimeout(loadingTimerRef.current)
+      }
+    }
+  }, [])
 
   const handleTabChange = useCallback((value: string) => {
     console.log('🔄 State Management - Tab switched to:', value)
     setActiveTab(value)
+    setIsLoading(true)
+
+    if (loadingTimerRef.current) {
+      clearTimeout(loadingTimerRef.current)
+    }
+
+    loadingTimerRef.current = setTimeout(() => {
+      setIsLoading(false)
+    }, 900)
   }, [])
 
   return {
     isSidebarOpen,
     activeTab,
+    isLoading,
+    loadingMessage: `Loading ${activeTab} view...`,
     toggleSidebar: () => {
       const newState = !isSidebarOpen
       console.log('🔄 State Management - Sidebar toggled to:', newState)
@@ -32,3 +55,43 @@ export const usePageLayoutMock = (): UsePageLayoutReturn => {
     },
   }
 }
+
+export function usePageLayoutStoryActionsMock() {
+  const onVersionSelect = useCallback((id: string) => {
+    console.log('🔄 State Management - Selected version:', id)
+  }, [])
+
+  const onSave = useCallback(() => {
+    console.log('🔄 State Management - Workflow saved')
+  }, [])
+
+  const onUndo = useCallback(() => {
+    console.log('🔄 State Management - Undo')
+  }, [])
+
+  const onRedo = useCallback(() => {
+    console.log('🔄 State Management - Redo')
+  }, [])
+
+  const onSubmit = useCallback((message: PromptInputMessage, _event: FormEvent<HTMLFormElement>) => {
+    console.log('🔄 State Management - Refinement request:', message)
+  }, [])
+
+  const onApprove = useCallback(() => {
+    console.log('🔄 State Management - Changes approved')
+  }, [])
+
+  const onReject = useCallback(() => {
+    console.log('🔄 State Management - Changes rejected')
+  }, [])
+
+  return {
+    onVersionSelect,
+    onSave,
+    onUndo,
+    onRedo,
+    onSubmit,
+    onApprove,
+    onReject,
+  }
+}

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

@@ -110,7 +110,7 @@ export const MultiAgentReviewState: Story = {
 export const WithStateManagement: Story = {
   render: () => {
     // Use mocked hook for state management
-    const { messages, fileChanges, handleSubmit, handleApprove, handleReject } =
+    const { messages, fileChanges, onSubmit, handleApprove, handleReject } =
       useRefinementPanelMock({
         initialMessages: inputStateMessages,
         reviewMessages: reviewStateMessages,
@@ -123,7 +123,7 @@ export const WithStateManagement: Story = {
         messages={messages}
         fileChanges={fileChanges}
         placeholder="Ask a question or describe a task..."
-        onSubmit={(message) => handleSubmit(message.text)}
+        onSubmit={onSubmit}
         onApprove={handleApprove}
         onReject={handleReject}
       />

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

@@ -1,6 +1,8 @@
 import { useState, useCallback } from "react";
 import type { RefinementMessage } from "./RefinementPanel";
 import type { FileChangeData } from "@/components/composites/FileQueue";
+import type { PromptInputMessage } from "@/components/ai-elements/prompt-input";
+import type { FormEvent } from "react";
 
 /**
  * Mock hook for RefinementPanel state management
@@ -18,6 +20,7 @@ export interface UseRefinementPanelReturn {
   fileChanges: FileChangeData[];
   loading: boolean;
   handleSubmit: (prompt: string) => Promise<void>;
+  onSubmit: (message: PromptInputMessage, event: FormEvent<HTMLFormElement>) => Promise<void>;
   handleApprove: () => Promise<void>;
   handleReject: () => Promise<void>;
 }
@@ -62,6 +65,10 @@ export function useRefinementPanelMock(
     setLoading(false);
   }, [reviewMessages, reviewFileChanges, apiDelay]);
 
+  const onSubmit = useCallback(async (message: PromptInputMessage, _event: FormEvent<HTMLFormElement>) => {
+    await handleSubmit(message.text);
+  }, [handleSubmit]);
+
   // Simulate approval: clear file changes and add success message
   const handleApprove = useCallback(async () => {
     setLoading(true);
@@ -115,6 +122,7 @@ export function useRefinementPanelMock(
     fileChanges,
     loading,
     handleSubmit,
+    onSubmit,
     handleApprove,
     handleReject,
   };

package/components/index.ts

@@ -1,14 +1,11 @@
-// Primitives
-export * from './primitives';
-
-// Composites
-export * from './composites';
-
-// Blocks
-export * from './blocks';
-
-// Features
+// Root public runtime API: feature-layer values only.
 export * from './features';
 
+// Root public type API: allow contracts from all layers.
+export type * from './primitives';
+export type * from './composites';
+export type * from './blocks';
+export type * from './features';
+
 // Utilities
 export { cn } from '@/lib/utils';