@fragments-sdk/cli 0.8.1 → 0.9.1

package/src/viewer/components/InteractionsPanel.tsx

@@ -10,8 +10,9 @@
  */
 
 import { useState, useCallback, useRef, useEffect } from "react";
-import { Button, Stack, Text, Badge, EmptyState, CodeBlock, Alert } from "@fragments-sdk/ui";
+import { Button, Stack, Text, Badge, CodeBlock, Alert, Box } from "@fragments-sdk/ui";
 import type { PlayFunction, PlayFunctionContext, FragmentVariant } from "../../core/index.js";
+import { Play } from "@phosphor-icons/react";
 import {
   PlayIcon,
   CheckIcon,
@@ -27,6 +28,7 @@ import {
   BreakpointIcon,
   BreakpointEmptyIcon,
 } from "./Icons.js";
+import { PanelShell } from "./PanelShell.js";
 
 // Step execution state
 interface StepResult {
@@ -424,27 +426,17 @@ export function InteractionsPanel({
     return `${(ms / 1000).toFixed(2)}s`;
   };
 
-  // No play function available
-  if (!hasPlayFunction) {
-    return (
-      <div style={{ height: '100%', display: 'flex', flexDirection: 'column' }}>
-        <div style={{ padding: '16px', borderBottom: '1px solid var(--border)' }}>
-          <Stack direction="row" align="center" gap="sm">
-            <PlayIcon style={{ width: 16, height: 16 }} />
-            <Text weight="medium">Interactions</Text>
-          </Stack>
-        </div>
-        <div style={{ flex: 1, display: 'flex', alignItems: 'center', justifyContent: 'center', padding: '32px' }}>
-          <EmptyState>
-            <EmptyState.Icon>
-              <PlayIcon style={{ width: 24, height: 24 }} />
-            </EmptyState.Icon>
-            <EmptyState.Title>No interactions defined</EmptyState.Title>
-            <EmptyState.Description>
-              This variant doesn't have a play function. Add a <code style={{ padding: '2px 4px', background: 'var(--bg-secondary)', borderRadius: '4px', fontSize: '12px' }}>play</code> function to your Storybook story to enable interaction testing.
-            </EmptyState.Description>
-            <div style={{ marginTop: '16px', width: '100%' }}>
-              <CodeBlock language="typescript">{`export const Default = {
+  // Empty state for no play function
+  const emptyConfig = !hasPlayFunction ? {
+    icon: <Play size={24} weight="regular" style={{ color: 'var(--text-tertiary)' }} />,
+    title: "No interactions defined",
+    description: (
+      <>
+        This variant doesn't have a play function. Add a <Box as="code" padding="xs" background="secondary" rounded="sm" style={{ fontSize: '12px', display: 'inline' }}>play</Box> function to your Storybook story to enable interaction testing.
+      </>
+    ),
+    action: (
+      <CodeBlock language="typescript">{`export const Default = {
   play: async ({ canvasElement, step }) => {
     const canvas = within(canvasElement);
 
@@ -459,110 +451,102 @@ export function InteractionsPanel({
     ).toBeInTheDocument();
   }
 };`}</CodeBlock>
-            </div>
-          </EmptyState>
-        </div>
-      </div>
-    );
-  }
-
-  return (
-    <div style={{ height: '100%', display: 'flex', flexDirection: 'column' }} data-interactions-panel>
-      {/* Header */}
-      <div style={{ padding: '16px', borderBottom: '1px solid var(--border)' }}>
-        <Stack direction="row" align="center" justify="between">
-          <Stack direction="row" align="center" gap="sm">
-            <PlayIcon style={{ width: 16, height: 16 }} />
-            <Text weight="medium">Interactions</Text>
-          </Stack>
-          <Stack direction="row" align="center" gap="sm">
-            {result.duration !== undefined && (
-              <Text size="xs" color="tertiary">{formatDuration(result.duration)}</Text>
-            )}
-
-            {/* Debug mode toggle */}
+    ),
+  } : undefined;
+
+  // Toolbar with duration, debug controls, and run button
+  const toolbar = hasPlayFunction ? (
+    <Stack direction="row" align="center" justify="between" style={{ width: '100%' }}>
+      <Stack direction="row" align="center" gap="sm">
+        {result.duration !== undefined && (
+          <Text size="xs" color="tertiary">{formatDuration(result.duration)}</Text>
+        )}
+      </Stack>
+      <Stack direction="row" align="center" gap="sm">
+        {/* Debug mode toggle */}
+        <Button
+          onClick={toggleDebugMode}
+          variant="ghost"
+          size="sm"
+          title={debugState.mode === 'debug' ? "Exit debug mode" : "Enable debug mode (F5 to run with debugger)"}
+          style={{
+            color: debugState.mode === 'debug' ? '#ea580c' : undefined,
+            background: debugState.mode === 'debug' ? 'color-mix(in srgb, #f97316 10%, transparent)' : undefined,
+          }}
+        >
+          <BugIcon style={{ width: 16, height: 16 }} />
+        </Button>
+
+        {/* Debug controls when paused */}
+        {debugState.isPaused && (
+          <>
             <Button
-              onClick={toggleDebugMode}
+              onClick={handleResume}
               variant="ghost"
               size="sm"
-              title={debugState.mode === 'debug' ? "Exit debug mode" : "Enable debug mode (F5 to run with debugger)"}
-              style={{
-                color: debugState.mode === 'debug' ? '#ea580c' : undefined,
-                background: debugState.mode === 'debug' ? 'color-mix(in srgb, #f97316 10%, transparent)' : undefined,
-              }}
+              title="Continue (F8)"
+              style={{ color: '#16a34a' }}
             >
-              <BugIcon style={{ width: 16, height: 16 }} />
+              <ContinueIcon style={{ width: 16, height: 16 }} />
             </Button>
-
-            {/* Debug controls when paused */}
-            {debugState.isPaused && (
-              <>
-                <Button
-                  onClick={handleResume}
-                  variant="ghost"
-                  size="sm"
-                  title="Continue (F8)"
-                  style={{ color: '#16a34a' }}
-                >
-                  <ContinueIcon style={{ width: 16, height: 16 }} />
-                </Button>
-                <Button
-                  onClick={handleStepOver}
-                  variant="ghost"
-                  size="sm"
-                  title="Step over (F10)"
-                  style={{ color: '#2563eb' }}
-                >
-                  <StepOverIcon style={{ width: 16, height: 16 }} />
-                </Button>
-              </>
-            )}
-
             <Button
-              onClick={() => runInteractions(debugState.mode === 'debug')}
-              disabled={result.status === "running"}
-              variant={result.status === "running" || result.status === "paused" ? "outline" : "solid"}
+              onClick={handleStepOver}
+              variant="ghost"
               size="sm"
-              style={
-                result.status === "running" || result.status === "paused"
-                  ? { background: 'var(--bg-secondary)', color: 'var(--text-muted)', cursor: 'not-allowed' }
-                  : { background: 'var(--color-accent)', color: '#fff' }
-              }
+              title="Step over (F10)"
+              style={{ color: '#2563eb' }}
             >
-              {result.status === "running" ? (
-                <>
-                  <LoadingIcon style={{ width: 16, height: 16, animation: 'spin 1s linear infinite' }} />
-                  Running...
-                </>
-              ) : result.status === "paused" ? (
-                <>
-                  <PauseIcon style={{ width: 16, height: 16 }} />
-                  Paused
-                </>
-              ) : result.status === "idle" ? (
-                <>
-                  <PlayIcon style={{ width: 16, height: 16 }} />
-                  {debugState.mode === 'debug' ? 'Debug' : 'Run'}
-                </>
-              ) : (
-                <>
-                  <RefreshIcon style={{ width: 16, height: 16 }} />
-                  Rerun
-                </>
-              )}
+              <StepOverIcon style={{ width: 16, height: 16 }} />
             </Button>
-          </Stack>
-        </Stack>
-      </div>
+          </>
+        )}
+
+        <Button
+          onClick={() => runInteractions(debugState.mode === 'debug')}
+          disabled={result.status === "running"}
+          variant={result.status === "running" || result.status === "paused" ? "outline" : "solid"}
+          size="sm"
+          style={
+            result.status === "running" || result.status === "paused"
+              ? { background: 'var(--bg-secondary)', color: 'var(--text-muted)', cursor: 'not-allowed' }
+              : { background: 'var(--color-accent)', color: '#fff' }
+          }
+        >
+          {result.status === "running" ? (
+            <>
+              <LoadingIcon style={{ width: 16, height: 16, animation: 'spin 1s linear infinite' }} />
+              Running...
+            </>
+          ) : result.status === "paused" ? (
+            <>
+              <PauseIcon style={{ width: 16, height: 16 }} />
+              Paused
+            </>
+          ) : result.status === "idle" ? (
+            <>
+              <PlayIcon style={{ width: 16, height: 16 }} />
+              {debugState.mode === 'debug' ? 'Debug' : 'Run'}
+            </>
+          ) : (
+            <>
+              <RefreshIcon style={{ width: 16, height: 16 }} />
+              Rerun
+            </>
+          )}
+        </Button>
+      </Stack>
+    </Stack>
+  ) : undefined;
 
-      {/* Results */}
-      <div style={{ flex: 1, overflowY: 'auto' }}>
+  return (
+    <div data-interactions-panel style={{ height: '100%' }}>
+      <PanelShell toolbar={toolbar} empty={emptyConfig} bodyPadding="none">
         {result.status === "idle" ? (
-          <div style={{ padding: '32px', textAlign: 'center' }}>
+          <Box padding="lg" style={{ textAlign: 'center' }}>
             <Text size="sm" color="tertiary">
               Click "Run" to execute the interaction tests
             </Text>
-          </div>
+          </Box>
         ) : (
           <Stack direction="column" gap="sm" style={{ padding: '16px' }}>
             {/* Overall status */}
@@ -743,7 +727,7 @@ export function InteractionsPanel({
 
             {/* Keyboard shortcuts help in debug mode */}
             {debugState.mode === 'debug' && (
-              <div style={{ marginTop: '16px', padding: '12px', background: 'var(--bg-secondary)', borderRadius: '8px' }}>
+              <Box padding="sm" background="secondary" rounded="lg" style={{ marginTop: '16px' }}>
                 <Text size="xs" weight="medium" color="tertiary" style={{ marginBottom: '4px' }}>Keyboard shortcuts:</Text>
                 <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '4px' }}>
                   <Text size="xs" color="tertiary"><Badge size="sm" variant="default">F5</Badge> Run with debugger</Text>
@@ -751,23 +735,23 @@ export function InteractionsPanel({
                   <Text size="xs" color="tertiary"><Badge size="sm" variant="default">F9</Badge> Toggle breakpoint</Text>
                   <Text size="xs" color="tertiary"><Badge size="sm" variant="default">F10</Badge> Step over</Text>
                 </div>
-              </div>
+              </Box>
             )}
 
             {/* Top-level error (if no steps failed) */}
             {result.error && !result.steps.some((s) => s.status === "failed") && (
-              <div style={{ marginTop: '16px' }}>
+              <Box style={{ marginTop: '16px' }}>
                 <Text size="xs" weight="medium" color="tertiary" style={{ textTransform: 'uppercase', letterSpacing: '0.05em', marginBottom: '8px' }}>
                   Error
                 </Text>
                 <pre style={{ fontSize: '12px', color: '#dc2626', background: 'color-mix(in srgb, #ef4444 10%, transparent)', padding: '12px', borderRadius: '4px', overflowX: 'auto', whiteSpace: 'pre-wrap' }}>
                   {result.error}
                 </pre>
-              </div>
+              </Box>
             )}
           </Stack>
         )}
-      </div>
+      </PanelShell>
     </div>
   );
 }

package/src/viewer/components/IsolatedPreviewFrame.tsx

@@ -258,6 +258,7 @@ export const IsolatedPreviewFrame = memo(function IsolatedPreviewFrame({
         style={{
           width: '100%',
           height: '100%',
+          minHeight: frameMinHeight,
           border: 'none',
           display: 'block',
           background: 'transparent',

package/src/viewer/components/LandingPage.tsx

@@ -3,7 +3,7 @@ import { zodResolver } from '@hookform/resolvers/zod';
 import { z } from 'zod';
 import { useState, useRef, useEffect } from 'react';
 import { HexColorPicker } from 'react-colorful';
-import { Button, Input, Toggle, Stack, Text, Card, Field, Separator, Select } from '@fragments-sdk/ui';
+import { Box, Button, Input, Toggle, Stack, Text, Card, Field, Separator, Select } from '@fragments-sdk/ui';
 import { generateColorScheme, type ColorSchemeType } from '../utils/colorSchemes.js';
 import { ChevronDownIcon } from './Icons.js';
 
@@ -106,7 +106,7 @@ export function LandingPage({ onSubmit }: LandingPageProps) {
   };
 
   return (
-    <div style={{ minHeight: '100vh', backgroundColor: 'var(--bg-primary)' }}>
+    <Box background="primary" style={{ minHeight: '100vh' }}>
       <div style={{ maxWidth: '672px', margin: '0 auto', padding: '64px 24px' }}>
         {/* Header */}
         <Stack direction="column" gap="sm" style={{ marginBottom: '48px' }}>
@@ -416,6 +416,6 @@ export function LandingPage({ onSubmit }: LandingPageProps) {
           </Stack>
         </form>
       </div>
-    </div>
+    </Box>
   );
 }

package/src/viewer/components/LeftSidebar.tsx

@@ -1,6 +1,6 @@
 import { useState, useMemo, useRef, useEffect, useCallback } from 'react';
 import type { FragmentDefinition } from '../../core/index.js';
-import { Sidebar, useSidebar, Text, Menu } from '@fragments-sdk/ui';
+import { Sidebar, useSidebar, Text, Menu, Button, Box, Stack } from '@fragments-sdk/ui';
 
 // Fuzzy matching utility
 interface FuzzyMatch {
@@ -160,6 +160,32 @@ const FilterIcon = ({ active }: { active?: boolean }) => (
 
 const isInstalled = (path: string) => path.startsWith('@');
 
+/** Normalize category names to Title Case: "form" → "Form", "Data Display" stays */
+function titleCase(str: string): string {
+  return str.replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+/** Normalize category to a canonical key so "Form" and "Forms" merge into one group.
+ *  Returns the singular form as grouping key. */
+function categoryKey(raw: string): string {
+  const tc = titleCase(raw.trim());
+  // Strip trailing "s" plurals (Forms→Form, Buttons→Button) but not short words like "Tabs"
+  if (tc.length > 4 && tc.endsWith('s') && !tc.endsWith('ss')) {
+    return tc.slice(0, -1);
+  }
+  return tc;
+}
+
+/** Pluralize a category name for display: "Form" → "Forms", "General" stays */
+function pluralizeCategory(key: string): string {
+  // Already plural or naturally non-plural categories
+  const nonPlural = new Set(['General', 'Feedback', 'Layout', 'Navigation', 'Typography', 'Deprecated', 'Data Display']);
+  if (nonPlural.has(key)) return key;
+  // Already ends in s (edge case)
+  if (key.endsWith('s')) return key;
+  return key + 's';
+}
+
 export function LeftSidebar({ fragments, activeFragment, searchQuery, onSelect, showHealth, onHealthClick }: LeftSidebarProps) {
   const [focusedIndex, setFocusedIndex] = useState(-1);
   const [showCustom, setShowCustom] = useState(true);
@@ -229,6 +255,22 @@ export function LeftSidebar({ fragments, activeFragment, searchQuery, onSelect,
       );
   }, [sourceFiltered, searchResults, isFilterActive, showLibrary]);
 
+  // Group items by category when not searching (for large lists)
+  const categoryGroups = useMemo(() => {
+    if (searchResults || flatItems.length < 30) return null; // Flat list for small sets or search
+    const groups = new Map<string, typeof flatItems>();
+    for (const item of flatItems) {
+      const raw = item.fragment.meta.category || 'Uncategorized';
+      const key = categoryKey(raw);
+      if (!groups.has(key)) groups.set(key, []);
+      groups.get(key)!.push(item);
+    }
+    // Sort categories alphabetically, map key → display label
+    return [...groups.entries()]
+      .sort((a, b) => a[0].toLowerCase().localeCompare(b[0].toLowerCase()))
+      .map(([key, items]) => [pluralizeCategory(key), items] as const);
+  }, [flatItems, searchResults]);
+
   const keyboardItems = useMemo(() => {
     const componentItems = flatItems.map((item) => ({ type: 'component' as const, path: item.path }));
     if (!onHealthClick) return componentItems;
@@ -245,6 +287,19 @@ export function LeftSidebar({ fragments, activeFragment, searchQuery, onSelect,
     }
   }, [focusedIndex, keyboardItems.length]);
 
+  // Scroll the active sidebar item into view on mount and when activeFragment changes
+  useEffect(() => {
+    if (!activeFragment || !navRef.current) return;
+    // Small delay to let the DOM render after category grouping
+    const timer = setTimeout(() => {
+      const activeButton = navRef.current?.querySelector<HTMLButtonElement>('[aria-current="page"]');
+      if (activeButton) {
+        activeButton.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
+      }
+    }, 100);
+    return () => clearTimeout(timer);
+  }, [activeFragment]);
+
   useEffect(() => {
     setFocusedIndex(-1);
   }, [searchQuery]);
@@ -312,82 +367,105 @@ export function LeftSidebar({ fragments, activeFragment, searchQuery, onSelect,
             </Sidebar.Section>
           )}
 
-          <Sidebar.Section
-            label="Components"
-            action={hasBothSources ? (
-              <Menu modal={false}>
-                <Menu.Trigger asChild>
-                  <button
-                    type="button"
-                    aria-label="Filter components by source"
-                    style={{
-                      background: 'none',
-                      border: 'none',
-                      cursor: 'pointer',
-                      padding: '2px',
-                      display: 'flex',
-                      alignItems: 'center',
-                      color: 'var(--text-tertiary)',
-                      borderRadius: '4px',
-                    }}
-                  >
-                    <FilterIcon active={isFilterActive} />
-                  </button>
-                </Menu.Trigger>
-                <Menu.Content>
-                  <Menu.CheckboxItem checked={showCustom} onCheckedChange={setShowCustom}>
-                    Custom
-                  </Menu.CheckboxItem>
-                  <Menu.CheckboxItem checked={showLibrary} onCheckedChange={setShowLibrary}>
-                    Fragments UI
-                  </Menu.CheckboxItem>
-                </Menu.Content>
-              </Menu>
-            ) : undefined}
-          >
-            {flatItems.map((item) => {
-              const hasError = !!(item.fragment as any)?._loadError;
-              return (
-                <Sidebar.Item
-                  key={item.path}
-                  active={activeFragment === item.path}
-                  onClick={() => handleSelect(item.path)}
-                >
-                  <span style={{ display: 'flex', alignItems: 'center', gap: '6px', width: '100%' }}>
-                    <HighlightedText
-                      text={item.fragment.meta.name}
-                      indices={highlightMap.get(item.path) || []}
-                    />
-                    {hasError && (
-                      <span
-                        title="Missing dependencies"
-                        style={{ color: 'var(--color-warning, #f59e0b)', fontSize: '14px', lineHeight: 1, flexShrink: 0 }}
+          {categoryGroups ? (
+            // Grouped by category for large component lists
+            <>
+              {categoryGroups.map(([category, items]) => (
+                <Sidebar.Section key={category} label={`${category} (${items.length})`}>
+                  {items.map((item) => {
+                    const hasError = !!(item.fragment as any)?._loadError;
+                    return (
+                      <Sidebar.Item
+                        key={item.path}
+                        active={activeFragment === item.path}
+                        onClick={() => handleSelect(item.path)}
                       >
-                        &#9888;
-                      </span>
-                    )}
-                  </span>
-                </Sidebar.Item>
-              );
-            })}
-          </Sidebar.Section>
+                        <span style={{ display: 'flex', alignItems: 'center', gap: '6px', width: '100%' }}>
+                          <HighlightedText
+                            text={item.fragment.meta.name}
+                            indices={highlightMap.get(item.path) || []}
+                          />
+                          {hasError && (
+                            <span
+                              title="Missing dependencies"
+                              style={{ color: 'var(--color-warning, #f59e0b)', fontSize: '14px', lineHeight: 1, flexShrink: 0 }}
+                            >
+                              &#9888;
+                            </span>
+                          )}
+                        </span>
+                      </Sidebar.Item>
+                    );
+                  })}
+                </Sidebar.Section>
+              ))}
+            </>
+          ) : (
+            // Flat list for search results or small component sets
+            <Sidebar.Section
+              label="Components"
+              action={hasBothSources ? (
+                <Menu modal={false}>
+                  <Menu.Trigger asChild>
+                    <Button variant="ghost" size="sm" icon aria-label="Filter components by source">
+                      <FilterIcon active={isFilterActive} />
+                    </Button>
+                  </Menu.Trigger>
+                  <Menu.Content>
+                    <Menu.CheckboxItem checked={showCustom} onCheckedChange={setShowCustom}>
+                      Custom
+                    </Menu.CheckboxItem>
+                    <Menu.CheckboxItem checked={showLibrary} onCheckedChange={setShowLibrary}>
+                      Fragments UI
+                    </Menu.CheckboxItem>
+                  </Menu.Content>
+                </Menu>
+              ) : undefined}
+            >
+              {flatItems.map((item) => {
+                const hasError = !!(item.fragment as any)?._loadError;
+                return (
+                  <Sidebar.Item
+                    key={item.path}
+                    active={activeFragment === item.path}
+                    onClick={() => handleSelect(item.path)}
+                  >
+                    <span style={{ display: 'flex', alignItems: 'center', gap: '6px', width: '100%' }}>
+                      <HighlightedText
+                        text={item.fragment.meta.name}
+                        indices={highlightMap.get(item.path) || []}
+                      />
+                      {hasError && (
+                        <span
+                          title="Missing dependencies"
+                          style={{ color: 'var(--color-warning, #f59e0b)', fontSize: '14px', lineHeight: 1, flexShrink: 0 }}
+                        >
+                          &#9888;
+                        </span>
+                      )}
+                    </span>
+                  </Sidebar.Item>
+                );
+              })}
+            </Sidebar.Section>
+          )}
 
           {flatItems.length === 0 && (
-            <div style={{ padding: '8px 32px', textAlign: 'center' }}>
+            <Box paddingX="lg" paddingY="sm" style={{ textAlign: 'center' }}>
               <Text size="sm" color="tertiary">No results</Text>
-            </div>
+            </Box>
           )}
         </div>
       </Sidebar.Nav>
 
       {/* Footer */}
       <Sidebar.Footer>
-        <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', width: '100%' }}>
+        <Stack direction="row" align="center" justify="between" style={{ width: '100%' }}>
           <Text size="xs" color="tertiary">
             {isFilterActive || searchResults ? `${flatItems.length} of ${fragments.length}` : fragments.length} components
           </Text>
           <Sidebar.CollapseToggle />
-        </div>
+        </Stack>
       </Sidebar.Footer>
     </>
   );