@fragments-sdk/cli 0.8.1 → 0.9.1

package/src/viewer/components/PerformancePanel.tsx

@@ -11,8 +11,10 @@
  */
 
 import { useState, useEffect } from 'react';
-import { Card, Badge, Text, Stack, EmptyState, Alert, Collapsible } from '@fragments-sdk/ui';
+import { Card, Badge, Text, Stack, Alert, Collapsible, Box } from '@fragments-sdk/ui';
+import { Lightning, Package, FileCode, Star } from '@phosphor-icons/react';
 import { BRAND } from '../../core/index.js';
+import { PanelShell } from './PanelShell.js';
 
 interface ImportEntry {
   path: string;
@@ -211,32 +213,24 @@ export function PerformancePanel({ componentName }: PerformancePanelProps) {
     return () => { cancelled = true; };
   }, [componentName]);
 
-  if (loading) {
-    return (
-      <div style={{ padding: '16px' }}>
-        <Text size="sm" color="secondary">Loading performance data...</Text>
-      </div>
-    );
-  }
+  const showEmpty = !loading && (noData || !perfData);
 
-  if (noData || !perfData) {
-    return (
-      <div style={{ padding: '16px' }}>
-        <EmptyState>
-          <EmptyState.Title>No performance data</EmptyState.Title>
-          <EmptyState.Description>
-            Run <code>{BRAND.cliCommand} perf</code> to measure bundle sizes, then reload.
-          </EmptyState.Description>
-        </EmptyState>
-      </div>
-    );
-  }
+  const emptyConfig = showEmpty ? {
+    icon: <Lightning size={24} weight="regular" style={{ color: 'var(--text-tertiary)' }} />,
+    title: "No performance data",
+    description: (
+      <>
+        Run <Box as="code" padding="xs" background="secondary" rounded="sm" style={{ fontSize: '12px', display: 'inline', fontFamily: 'var(--fui-font-mono, monospace)' }}>{BRAND.cliCommand} perf</Box> to measure bundle sizes, then reload the viewer.
+      </>
+    ),
+  } : undefined;
 
-  const { bundleSize, rawSize, complexity, budgetPercent, overBudget, measuredAt } = perfData;
-  const measuredDate = new Date(measuredAt).toLocaleString();
+  // Safe destructure — only used when PanelShell renders children (not loading/empty)
+  const { bundleSize = 0, rawSize = 0, complexity = 'lightweight' as const, budgetPercent = 0, overBudget = false, measuredAt = '' } = perfData || {};
+  const measuredDate = measuredAt ? new Date(measuredAt).toLocaleString() : '';
 
   return (
-    <div style={{ padding: '16px' }}>
+    <PanelShell loading={loading} empty={emptyConfig}>
       <Stack gap="md">
         {overBudget && (
           <Alert variant="danger">
@@ -249,7 +243,10 @@ export function PerformancePanel({ componentName }: PerformancePanelProps) {
           <Card>
             <Card.Body>
               <Stack gap="xs">
-                <Text size="sm" color="secondary">Gzipped</Text>
+                <Stack direction="row" align="center" gap="xs">
+                  <Package size={14} weight="regular" style={{ color: 'var(--text-tertiary)' }} />
+                  <Text size="xs" color="secondary">Gzipped</Text>
+                </Stack>
                 <Text size="xl" weight="bold">{formatBytes(bundleSize)}</Text>
               </Stack>
             </Card.Body>
@@ -258,7 +255,10 @@ export function PerformancePanel({ componentName }: PerformancePanelProps) {
           <Card>
             <Card.Body>
               <Stack gap="xs">
-                <Text size="sm" color="secondary">Raw (minified)</Text>
+                <Stack direction="row" align="center" gap="xs">
+                  <FileCode size={14} weight="regular" style={{ color: 'var(--text-tertiary)' }} />
+                  <Text size="xs" color="secondary">Raw (minified)</Text>
+                </Stack>
                 <Text size="xl" weight="bold">{formatBytes(rawSize)}</Text>
               </Stack>
             </Card.Body>
@@ -267,7 +267,10 @@ export function PerformancePanel({ componentName }: PerformancePanelProps) {
           <Card>
             <Card.Body>
               <Stack gap="xs">
-                <Text size="sm" color="secondary">Complexity</Text>
+                <Stack direction="row" align="center" gap="xs">
+                  <Star size={14} weight="regular" style={{ color: 'var(--text-tertiary)' }} />
+                  <Text size="xs" color="secondary">Complexity</Text>
+                </Stack>
                 <div>
                   <Badge variant={tierVariant(complexity)} size="lg">
                     {complexity}
@@ -284,7 +287,7 @@ export function PerformancePanel({ componentName }: PerformancePanelProps) {
           </Card.Body>
         </Card>
 
-        {perfData.imports && perfData.imports.length > 0 && (
+        {perfData?.imports && perfData.imports.length > 0 && (
           <Card>
             <Card.Body>
               <ImportBreakdown imports={perfData.imports} rawSize={rawSize} />
@@ -296,6 +299,6 @@ export function PerformancePanel({ componentName }: PerformancePanelProps) {
           Measured {measuredDate}. CSS excluded (JS-only measurement).
         </Text>
       </Stack>
-    </div>
+    </PanelShell>
   );
 }

package/src/viewer/components/PreviewArea.tsx

@@ -423,7 +423,7 @@ export function PreviewArea({
               theme={previewTheme}
               width="100%"
               height="100%"
-              minHeight={viewportHeight || 200}
+              minHeight={viewportHeight || 400}
               previewKey={previewKey}
             />
           </div>

package/src/viewer/components/PreviewAside.tsx

@@ -0,0 +1,168 @@
+import { useState, useEffect, useMemo } from "react";
+import type { FragmentDefinition, FragmentVariant } from "../../core/index.js";
+import { Box, Stack, Text, Separator, Button, TableOfContents } from "@fragments-sdk/ui";
+import { getVariantSectionId } from "./viewer-utils.js";
+
+interface TocHeading {
+  id: string;
+  text: string;
+  level: 2 | 3;
+}
+
+interface PreviewAsideProps {
+  fragment: FragmentDefinition;
+  variants: FragmentVariant[];
+  focusedVariantIndex: number;
+  activePanel: string;
+  onSelectVariant: (index: number) => void;
+  onCopyLink: () => void;
+  onShowShortcuts: () => void;
+}
+
+function buildHeadings(fragment: FragmentDefinition): TocHeading[] {
+  const headings: TocHeading[] = [{ id: "setup", text: "Setup", level: 2 }];
+
+  if (fragment.variants.length > 0) {
+    headings.push({ id: "examples", text: "Examples", level: 2 });
+  }
+
+  headings.push({ id: "props", text: "Props", level: 2 });
+  headings.push({ id: "usage-guidelines", text: "Usage Guidelines", level: 2 });
+  headings.push({ id: "when-to-use", text: "When to use", level: 3 });
+  headings.push({ id: "when-not-to-use", text: "When not to use", level: 3 });
+
+  if ((fragment.usage?.guidelines?.length ?? 0) > 0) {
+    headings.push({ id: "best-practices", text: "Best practices", level: 3 });
+  }
+
+  if ((fragment.relations?.length ?? 0) > 0) {
+    headings.push({ id: "related-components", text: "Related Components", level: 2 });
+  }
+
+  return headings;
+}
+
+function useActiveHeading(ids: string[]): string | null {
+  const [activeId, setActiveId] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (ids.length === 0) return;
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting) {
+            setActiveId(entry.target.id);
+          }
+        }
+      },
+      { rootMargin: "-80px 0px -60% 0px", threshold: 0 }
+    );
+
+    for (const id of ids) {
+      const el = document.getElementById(id);
+      if (el) observer.observe(el);
+    }
+
+    return () => observer.disconnect();
+  }, [ids]);
+
+  return activeId;
+}
+
+export function PreviewAside({
+  fragment,
+  variants,
+  focusedVariantIndex,
+  activePanel,
+  onSelectVariant,
+  onCopyLink,
+  onShowShortcuts,
+}: PreviewAsideProps) {
+  const focusedVariant = variants[focusedVariantIndex] || null;
+
+  const headings = useMemo(() => buildHeadings(fragment), [fragment]);
+  const headingIds = useMemo(() => headings.map((h) => h.id), [headings]);
+  const activeId = useActiveHeading(headingIds);
+
+  return (
+    <Box padding="md" style={{ position: "sticky", top: "80px" }}>
+      <Stack gap="md">
+        {/* On This Page — same TOC component as docs site */}
+        <TableOfContents>
+          {headings.map((heading) => (
+            <TableOfContents.Item
+              key={heading.id}
+              id={heading.id}
+              active={activeId === heading.id}
+              indent={heading.level === 3}
+            >
+              {heading.text}
+            </TableOfContents.Item>
+          ))}
+        </TableOfContents>
+
+        {/* Variant list */}
+        {variants.length > 0 && (
+          <>
+            <Separator />
+            <Stack gap="xs">
+              <Text
+                size="xs"
+                color="tertiary"
+                style={{ textTransform: "uppercase", letterSpacing: "0.08em" }}
+              >
+                Variants
+              </Text>
+              {variants.map((variant, index) => {
+                const active = index === focusedVariantIndex;
+                const anchorId = getVariantSectionId(fragment.meta.name, variant.name);
+
+                return (
+                  <Button
+                    key={variant.name}
+                    as="a"
+                    variant={active ? "secondary" : "ghost"}
+                    size="sm"
+                    href={`#${anchorId}`}
+                    onClick={(event: React.MouseEvent) => {
+                      event.preventDefault();
+                      onSelectVariant(index);
+                    }}
+                    style={{ justifyContent: "flex-start" }}
+                  >
+                    {variant.name}
+                  </Button>
+                );
+              })}
+            </Stack>
+          </>
+        )}
+
+        <Separator />
+        <Stack gap="xs">
+          <Text size="sm" weight="medium">
+            {fragment.meta.name}
+          </Text>
+          <Text size="xs" color="secondary">
+            {focusedVariant
+              ? `Variant: ${focusedVariant.name}`
+              : "Select a variant"}
+          </Text>
+          <Text size="xs" color="tertiary">
+            Active panel: {activePanel}
+          </Text>
+        </Stack>
+        <Separator />
+        <Stack gap="xs">
+          <Button variant="ghost" size="sm" onClick={onCopyLink}>
+            Copy Link
+          </Button>
+          <Button variant="ghost" size="sm" onClick={onShowShortcuts}>
+            Keyboard Shortcuts
+          </Button>
+        </Stack>
+      </Stack>
+    </Box>
+  );
+}

package/src/viewer/components/PreviewFrameHost.tsx

@@ -191,9 +191,9 @@ function VariantRenderer({
     <div
       ref={containerRef}
       style={{
-        display: mode === 'full-bleed' ? 'block' : 'inline-block',
-        width: mode === 'full-bleed' ? '100%' : undefined,
-        minHeight: mode === 'full-bleed' ? '100vh' : undefined,
+        display: 'block',
+        width: '100%',
+        minHeight: '100%',
         transition: 'opacity 150ms',
         opacity: content ? 1 : 0,
       }}

package/src/viewer/components/PropsEditor.tsx

@@ -1,6 +1,6 @@
 import { useState } from "react";
 import type { PropDefinition } from "../../core/index.js";
-import { Input, Select, Toggle } from "@fragments-sdk/ui";
+import { Box, Stack, Text, Button, Badge, Card, Input, Select, Toggle } from "@fragments-sdk/ui";
 import { ControlsIcon, ChevronDownIcon, RefreshIcon } from "./Icons.js";
 
 interface PropsEditorProps {
@@ -28,7 +28,7 @@ export function PropsEditor({
   // Compact mode - show controls in a single horizontal line
   if (compact) {
     return (
-      <div style={{ display: 'flex', flexDirection: 'column', gap: '24px' }}>
+      <Stack gap="lg">
         {propEntries.map(([name, prop]) => (
           <PropControl
             key={name}
@@ -40,114 +40,60 @@ export function PropsEditor({
           />
         ))}
         {hasChanges && (
-          <button
-            onClick={onReset}
-            style={{
-              display: 'flex',
-              alignItems: 'center',
-              gap: '6px',
-              padding: '4px 8px',
-              fontSize: '12px',
-              fontWeight: 500,
-              color: 'var(--color-accent)',
-              background: 'transparent',
-              border: 'none',
-              borderRadius: '4px',
-              cursor: 'pointer',
-              transition: 'background 0.15s',
-            }}
-          >
+          <Button variant="ghost" size="sm" onClick={onReset}>
             <RefreshIcon style={{ width: 12, height: 12 }} />
             Reset
-          </button>
+          </Button>
         )}
-      </div>
+      </Stack>
     );
   }
 
   return (
-    <div style={{ border: '1px solid var(--border)', borderRadius: '12px', overflow: 'hidden', background: 'var(--bg-elevated)' }}>
+    <Card>
       {/* Header */}
-      <button
+      <Button
+        variant="ghost"
+        fullWidth
         onClick={() => setIsCollapsed(!isCollapsed)}
-        style={{
-          width: '100%',
-          padding: '12px 16px',
-          display: 'flex',
-          alignItems: 'center',
-          justifyContent: 'space-between',
-          background: 'var(--bg-secondary)',
-          borderBottom: '1px solid var(--border)',
-          cursor: 'pointer',
-          transition: 'background 0.15s',
-          border: 'none',
-          color: 'inherit',
-        }}
+        style={{ justifyContent: 'space-between', padding: '12px 16px', borderRadius: 0, borderBottom: '1px solid var(--border)' }}
       >
-        <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
-          <ControlsIcon style={{ width: 16, height: 16, color: 'var(--text-secondary)' }} />
-          <span style={{ fontSize: '13px', fontWeight: 500, color: 'var(--text-primary)' }}>
-            Props Editor
-          </span>
-          {hasChanges && (
-            <span style={{ padding: '2px 6px', fontSize: '10px', fontWeight: 500, background: 'var(--color-accent)', color: '#fff', borderRadius: '4px' }}>
-              Modified
-            </span>
-          )}
-        </div>
-        <ChevronDownIcon
-          style={{
-            width: 16,
-            height: 16,
-            color: 'var(--text-tertiary)',
-            transition: 'transform 0.15s',
-            transform: isCollapsed ? 'rotate(-90deg)' : 'rotate(0deg)',
-          }}
-        />
-      </button>
+        <Stack direction="row" align="center" gap="sm">
+          <ControlsIcon style={{ width: 16, height: 16 }} />
+          <Text size="sm" weight="medium">Props Editor</Text>
+          {hasChanges && <Badge variant="info" size="sm">Modified</Badge>}
+        </Stack>
+        <ChevronDownIcon style={{ width: 16, height: 16, transition: 'transform 0.15s', transform: isCollapsed ? 'rotate(-90deg)' : 'rotate(0deg)' }} />
+      </Button>
 
       {/* Content */}
       {!isCollapsed && (
-        <div style={{ padding: '16px', display: 'flex', flexDirection: 'column', gap: '16px' }}>
-          {/* Reset button */}
-          {hasChanges && (
-            <button
-              onClick={onReset}
-              style={{
-                display: 'flex',
-                alignItems: 'center',
-                gap: '6px',
-                padding: '6px 10px',
-                fontSize: '12px',
-                fontWeight: 500,
-                color: 'var(--color-accent)',
-                background: 'transparent',
-                border: 'none',
-                borderRadius: '4px',
-                cursor: 'pointer',
-                transition: 'background 0.15s',
-              }}
-            >
-              <RefreshIcon style={{ width: 14, height: 14 }} />
-              Reset to defaults
-            </button>
-          )}
-
-          {/* Prop controls */}
-          <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
-            {propEntries.map(([name, prop]) => (
-              <PropControl
-                key={name}
-                name={name}
-                prop={prop}
-                value={values[name]}
-                onChange={(value) => onChange(name, value)}
-              />
-            ))}
-          </div>
-        </div>
+        <Box padding="md">
+          <Stack gap="md">
+            {/* Reset button */}
+            {hasChanges && (
+              <Button variant="ghost" size="sm" onClick={onReset}>
+                <RefreshIcon style={{ width: 14, height: 14 }} />
+                Reset to defaults
+              </Button>
+            )}
+
+            {/* Prop controls */}
+            <Stack gap="sm">
+              {propEntries.map(([name, prop]) => (
+                <PropControl
+                  key={name}
+                  name={name}
+                  prop={prop}
+                  value={values[name]}
+                  onChange={(value) => onChange(name, value)}
+                />
+              ))}
+            </Stack>
+          </Stack>
+        </Box>
       )}
-    </div>
+    </Card>
   );
 }
 
@@ -236,40 +182,38 @@ function PropControl({
 
   if (compact) {
     return (
-      <div style={{ display: 'flex', gap: '8px' }}>
-        <label style={{ fontSize: '11px', fontWeight: 500, color: 'var(--text-secondary)', fontFamily: 'monospace', whiteSpace: 'nowrap', minWidth: '100px' }}>
+      <Stack direction="row" gap="sm">
+        <Text as="label" size="xs" weight="medium" font="mono" style={{ whiteSpace: 'nowrap', minWidth: '100px' }} color="secondary">
           {name}
-        </label>
+        </Text>
         {getControlForProp(prop, displayValue, onChange, true)}
-      </div>
+      </Stack>
     );
   }
 
   return (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: '6px' }}>
-      <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
-        <label style={{ fontSize: '12px', fontWeight: 500, color: 'var(--text-primary)', fontFamily: 'monospace' }}>
+    <Stack gap="sm">
+      <Stack direction="row" align="center" gap="sm">
+        <Text as="label" size="xs" weight="medium" font="mono">
           {name}
           {prop.required && (
             <span style={{ color: 'var(--color-danger, #ef4444)', marginLeft: '2px' }}>*</span>
           )}
-        </label>
-        <span style={{ fontSize: '11px', color: 'var(--text-tertiary)' }}>{prop.type}</span>
+        </Text>
+        <Text size="xs" color="tertiary">{prop.type}</Text>
         {prop.controlType && prop.controlType !== prop.type && (
-          <span style={{ fontSize: '10px', color: 'var(--text-tertiary)', background: 'var(--bg-secondary)', padding: '2px 6px', borderRadius: '4px' }}>
-            {prop.controlType}
-          </span>
+          <Badge size="sm">{prop.controlType}</Badge>
         )}
-      </div>
+      </Stack>
 
       {getControlForProp(prop, displayValue, onChange, false)}
 
       {prop.description && (
-        <p style={{ fontSize: '11px', color: 'var(--text-tertiary)', lineHeight: 1.6 }}>
+        <Text as="p" size="xs" color="tertiary" style={{ lineHeight: 1.6 }}>
           {prop.description}
-        </p>
+        </Text>
       )}
-    </div>
+    </Stack>
   );
 }
 
@@ -407,7 +351,7 @@ function FunctionControl({
 
   if (isEditing) {
     return (
-      <div style={{ display: 'flex', flexDirection: 'column', gap: '8px', flex: 1 }}>
+      <Stack gap="sm" style={{ flex: 1 }}>
         <textarea
           value={inputValue}
           onChange={(e) => setInputValue(e.target.value)}
@@ -427,41 +371,11 @@ function FunctionControl({
           placeholder="() => console.log('clicked')"
           autoFocus
         />
-        <div style={{ display: 'flex', gap: '6px' }}>
-          <button
-            onClick={handleSave}
-            style={{
-              padding: '4px 8px',
-              fontSize: '10px',
-              fontWeight: 500,
-              background: 'var(--color-accent)',
-              color: '#fff',
-              borderRadius: '4px',
-              border: 'none',
-              cursor: 'pointer',
-              transition: 'opacity 0.15s',
-            }}
-          >
-            Apply
-          </button>
-          <button
-            onClick={handleCancel}
-            style={{
-              padding: '4px 8px',
-              fontSize: '10px',
-              fontWeight: 500,
-              color: 'var(--text-tertiary)',
-              background: 'transparent',
-              borderRadius: '4px',
-              border: 'none',
-              cursor: 'pointer',
-              transition: 'color 0.15s, background 0.15s',
-            }}
-          >
-            Cancel
-          </button>
-        </div>
-      </div>
+        <Stack direction="row" gap="sm">
+          <Button variant="primary" size="sm" onClick={handleSave}>Apply</Button>
+          <Button variant="ghost" size="sm" onClick={handleCancel}>Cancel</Button>
+        </Stack>
+      </Stack>
     );
   }
 
@@ -498,7 +412,7 @@ function ColorControl({
   presetColors?: string[];
 }) {
   return (
-    <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+    <Stack direction="row" align="center" gap="sm">
       <input
         type="color"
         value={value || "#000000"}
@@ -513,7 +427,7 @@ function ColorControl({
         style={{ width: '96px', fontSize: '11px', fontFamily: 'monospace' }}
       />
       {presetColors && presetColors.length > 0 && (
-        <div style={{ display: 'flex', gap: '4px', flexWrap: 'wrap' }}>
+        <Stack direction="row" gap="xs" wrap>
           {presetColors.slice(0, 6).map((color) => (
             <button
               key={color}
@@ -530,9 +444,9 @@ function ColorControl({
               title={color}
             />
           ))}
-        </div>
+        </Stack>
       )}
-    </div>
+    </Stack>
   );
 }
 
@@ -574,7 +488,7 @@ function RangeControl({
   step?: number;
 }) {
   return (
-    <div style={{ display: 'flex', alignItems: 'center', gap: '12px' }}>
+    <Stack direction="row" align="center" gap="sm">
       <input
         type="range"
         value={value ?? min}
@@ -584,9 +498,9 @@ function RangeControl({
         onChange={(e) => onChange(Number(e.target.value))}
         style={{ flex: 1, height: '8px', background: 'var(--bg-secondary)', borderRadius: '8px', cursor: 'pointer', accentColor: 'var(--color-accent)' }}
       />
-      <span style={{ fontSize: '11px', fontFamily: 'monospace', color: 'var(--text-secondary)', minWidth: '3rem', textAlign: 'right' }}>
+      <Text size="xs" font="mono" color="secondary" style={{ minWidth: '3rem', textAlign: 'right' }}>
         {value ?? min}
-      </span>
-    </div>
+      </Text>
+    </Stack>
   );
 }