@fragments-sdk/cli 0.9.0 → 0.10.0

package/src/viewer/components/ComponentGraph.tsx

@@ -10,9 +10,11 @@
 
 import { useMemo, useState } from "react";
 import type { FragmentDefinition, ComponentRelation, RelationshipType } from "../../core/index.js";
-import { ChevronRightIcon, EmptyIcon, WandIcon } from "./Icons.js";
+import { ChevronRightIcon, WandIcon } from "./Icons.js";
 import { detectAllRelationships, mergeRelationships } from "../utils/detectRelationships.js";
-import { Stack, Text, Badge, Button, EmptyState, CodeBlock, Grid, Separator } from "@fragments-sdk/ui";
+import { Stack, Text, Badge, Button, CodeBlock, Separator, Box } from "@fragments-sdk/ui";
+import { TreeStructure } from "@phosphor-icons/react";
+import { PanelShell } from "./PanelShell.js";
 
 interface ComponentGraphProps {
   /** Current fragment definition */
@@ -148,46 +150,24 @@ export function ComponentGraph({ fragment, allFragments, onNavigate }: Component
     }
   };
 
-  // No fragment selected
-  if (!fragment) {
-    return (
-      <div style={{ height: '100%', display: 'flex', flexDirection: 'column' }}>
-        <div style={{ padding: '16px', borderBottom: '1px solid var(--border)' }}>
-          <Text weight="medium">Component Graph</Text>
-        </div>
-        <div style={{ flex: 1, display: 'flex', alignItems: 'center', justifyContent: 'center', padding: '32px' }}>
-          <EmptyState>
-            <EmptyState.Icon>
-              <EmptyIcon style={{ width: '24px', height: '24px' }} />
-            </EmptyState.Icon>
-            <EmptyState.Description>Select a component to view its relationships</EmptyState.Description>
-          </EmptyState>
-        </div>
-      </div>
-    );
-  }
-
   const hasRelations = (groupedRelations && Object.values(groupedRelations).some(g => g.length > 0)) || reverseRelations.length > 0;
   const detectedCount = detectedRelationships.length;
 
-  // No relations defined
-  if (!hasRelations) {
-    return (
-      <div style={{ height: '100%', display: 'flex', flexDirection: 'column' }}>
-        <div style={{ padding: '16px', borderBottom: '1px solid var(--border)' }}>
-          <Text weight="medium">Component Graph</Text>
-        </div>
-        <div style={{ flex: 1, display: 'flex', alignItems: 'center', justifyContent: 'center', padding: '32px' }}>
-          <EmptyState>
-            <EmptyState.Icon>
-              <EmptyIcon style={{ width: '24px', height: '24px' }} />
-            </EmptyState.Icon>
-            <EmptyState.Title>No relationships defined</EmptyState.Title>
-            <EmptyState.Description>
-              This component doesn't have any defined relationships. Add a <code style={{ padding: '2px 4px', background: 'var(--bg-secondary)', borderRadius: '4px', fontSize: '12px' }}>relations</code> array to your fragment definition to visualize component connections.
-            </EmptyState.Description>
-            <div style={{ marginTop: '16px', width: '100%' }}>
-              <CodeBlock language="typescript">{`relations: [
+  // Determine empty config
+  const emptyConfig = !fragment ? {
+    icon: <TreeStructure size={24} weight="regular" style={{ color: 'var(--text-tertiary)' }} />,
+    title: "No component selected",
+    description: "Select a component to view its relationships",
+  } : !hasRelations ? {
+    icon: <TreeStructure size={24} weight="regular" style={{ color: 'var(--text-tertiary)' }} />,
+    title: "No relationships defined",
+    description: (
+      <>
+        Add a <Box as="code" padding="xs" background="secondary" rounded="sm" style={{ fontSize: '12px', display: 'inline' }}>relations</Box> array to your fragment definition to visualize component connections.
+      </>
+    ),
+    action: (
+      <CodeBlock language="typescript" code={`relations: [
   {
     component: "ButtonGroup",
     relationship: "parent",
@@ -198,116 +178,105 @@ export function ComponentGraph({ fragment, allFragments, onNavigate }: Component
     relationship: "alternative",
     note: "Use when only an icon is needed"
   }
-]`}</CodeBlock>
-            </div>
-          </EmptyState>
-        </div>
-      </div>
-    );
-  }
+]`} />
+    ),
+  } : undefined;
+
+  // Toolbar with badges + auto-detect toggle (only when we have data)
+  const toolbar = fragment && hasRelations ? (
+    <Stack direction="row" align="center" justify="between" style={{ width: '100%' }}>
+      <Stack direction="row" align="center" gap="sm">
+        <Badge size="sm">{fragment.meta.name}</Badge>
+        <Badge size="sm" variant="default">
+          {allRelationships.length + reverseRelations.length} connection{(allRelationships.length + reverseRelations.length) !== 1 ? 's' : ''}
+        </Badge>
+      </Stack>
+      {detectedCount > 0 && (
+        <AutoDetectToggle
+          showAutoDetected={showAutoDetected}
+          onToggle={() => setShowAutoDetected(!showAutoDetected)}
+        />
+      )}
+    </Stack>
+  ) : undefined;
 
   return (
-    <div style={{ height: '100%', display: 'flex', flexDirection: 'column' }}>
-      {/* Header */}
-      <div style={{ padding: '16px', borderBottom: '1px solid var(--border)' }}>
-        <Stack direction="row" align="center" justify="between">
-          <Text weight="medium">Component Graph</Text>
-          {detectedCount > 0 && (
-            <AutoDetectToggle
-              showAutoDetected={showAutoDetected}
-              onToggle={() => setShowAutoDetected(!showAutoDetected)}
-            />
+    <PanelShell toolbar={toolbar} empty={emptyConfig}>
+      {/* Defined relations */}
+      {groupedRelations && (
+        <Stack direction="column" gap="md">
+          {(Object.entries(groupedRelations) as [RelationshipType, ComponentRelation[]][]).map(
+            ([type, relations]) => {
+              if (relations.length === 0) return null;
+              const config = RELATIONSHIP_CONFIG[type];
+
+              return (
+                <div key={type}>
+                  <Stack direction="row" align="center" gap="sm" style={{ marginBottom: '8px' }}>
+                    <Text size="xs" weight="medium" style={{ textTransform: 'uppercase', letterSpacing: '0.05em', color: config.color }}>
+                      {config.label}
+                    </Text>
+                    <Separator style={{ flex: 1 }} />
+                  </Stack>
+                  <Stack direction="column" gap="sm">
+                    {relations.map((relation, index) => (
+                      <RelationCard
+                        key={`${relation.component}-${index}`}
+                        relation={relation}
+                        config={config}
+                        exists={componentExists(relation.component)}
+                        onNavigate={handleNavigate}
+                      />
+                    ))}
+                  </Stack>
+                </div>
+              );
+            }
           )}
         </Stack>
-        <Text size="xs" color="secondary" style={{ marginTop: '4px' }}>
-          Relationships for <Text as="span" weight="medium" size="xs">{fragment.meta.name}</Text>
-          {showAutoDetected && detectedCount > 0 && (
-            <span style={{ marginLeft: '4px' }}>
-              ({detectedCount} from variants)
-            </span>
-          )}
-        </Text>
-      </div>
-
-      {/* Graph visualization */}
-      <div style={{ flex: 1, overflowY: 'auto', padding: '16px' }}>
-        {/* Defined relations */}
-        {groupedRelations && (
-          <Stack direction="column" gap="md">
-            {(Object.entries(groupedRelations) as [RelationshipType, ComponentRelation[]][]).map(
-              ([type, relations]) => {
-                if (relations.length === 0) return null;
-                const config = RELATIONSHIP_CONFIG[type];
+      )}
 
-                return (
-                  <div key={type}>
-                    <Stack direction="row" align="center" gap="sm" style={{ marginBottom: '8px' }}>
-                      <Text size="xs" weight="medium" style={{ textTransform: 'uppercase', letterSpacing: '0.05em', color: config.color }}>
-                        {config.label}
-                      </Text>
-                      <div style={{ flex: 1, height: '1px', background: 'var(--border)' }} />
-                    </Stack>
-                    <Stack direction="column" gap="sm">
-                      {relations.map((relation, index) => (
-                        <RelationCard
-                          key={`${relation.component}-${index}`}
-                          relation={relation}
-                          config={config}
-                          exists={componentExists(relation.component)}
-                          onNavigate={handleNavigate}
-                        />
-                      ))}
-                    </Stack>
-                  </div>
-                );
-              }
-            )}
+      {/* Reverse relations (inbound references) */}
+      {reverseRelations.length > 0 && (
+        <Box style={{ marginTop: '24px' }}>
+          <Stack direction="row" align="center" gap="sm" style={{ marginBottom: '8px' }}>
+            <Text size="xs" weight="medium" color="secondary" style={{ textTransform: 'uppercase', letterSpacing: '0.05em' }}>
+              Referenced By
+            </Text>
+            <Separator style={{ flex: 1 }} />
           </Stack>
-        )}
-
-        {/* Reverse relations (inbound references) */}
-        {reverseRelations.length > 0 && (
-          <div style={{ marginTop: '24px' }}>
-            <Stack direction="row" align="center" gap="sm" style={{ marginBottom: '8px' }}>
-              <Text size="xs" weight="medium" color="secondary" style={{ textTransform: 'uppercase', letterSpacing: '0.05em' }}>
-                Referenced By
-              </Text>
-              <div style={{ flex: 1, height: '1px', background: 'var(--border)' }} />
-            </Stack>
-            <Stack direction="column" gap="sm">
-              {reverseRelations.map(({ relation }, index) => {
-                const config = RELATIONSHIP_CONFIG[relation.relationship];
-                return (
-                  <RelationCard
-                    key={`reverse-${relation.component}-${index}`}
-                    relation={relation}
-                    config={config}
-                    exists={componentExists(relation.component)}
-                    onNavigate={handleNavigate}
-                    isReverse
-                  />
-                );
-              })}
-            </Stack>
-          </div>
-        )}
+          <Stack direction="column" gap="sm">
+            {reverseRelations.map(({ relation }, index) => {
+              const config = RELATIONSHIP_CONFIG[relation.relationship];
+              return (
+                <RelationCard
+                  key={`reverse-${relation.component}-${index}`}
+                  relation={relation}
+                  config={config}
+                  exists={componentExists(relation.component)}
+                  onNavigate={handleNavigate}
+                  isReverse
+                />
+              );
+            })}
+          </Stack>
+        </Box>
+      )}
 
-        {/* Legend */}
-        <div style={{ marginTop: '32px', paddingTop: '16px', borderTop: '1px solid var(--border)' }}>
-          <Text size="xs" weight="medium" color="secondary" style={{ marginBottom: '8px' }}>Legend</Text>
-          <Grid columns={2} gap="sm">
-            {(Object.entries(RELATIONSHIP_CONFIG) as [RelationshipType, typeof RELATIONSHIP_CONFIG[RelationshipType]][]).map(
-              ([type, config]) => (
-                <Stack key={type} direction="row" align="center" gap="sm">
-                  <span style={{ width: '8px', height: '8px', borderRadius: '50%', backgroundColor: config.bgColor, border: `1px solid ${config.color}` }} />
-                  <Text size="xs" color="secondary">{config.label}</Text>
-                </Stack>
-              )
-            )}
-          </Grid>
-        </div>
-      </div>
-    </div>
+      {/* Legend */}
+      <Box borderTop style={{ marginTop: '24px', paddingTop: '12px' }}>
+        <Stack direction="row" gap="md" style={{ flexWrap: 'wrap' }}>
+          {(Object.entries(RELATIONSHIP_CONFIG) as [RelationshipType, typeof RELATIONSHIP_CONFIG[RelationshipType]][]).map(
+            ([type, config]) => (
+              <Stack key={type} direction="row" align="center" gap="xs">
+                <span style={{ width: '6px', height: '6px', borderRadius: '50%', backgroundColor: config.color, flexShrink: 0 }} />
+                <Text size="xs" color="tertiary">{config.label}</Text>
+              </Stack>
+            )
+          )}
+        </Stack>
+      </Box>
+    </PanelShell>
   );
 }
 

package/src/viewer/components/ContractPanel.tsx

@@ -5,7 +5,7 @@
 
 import { memo } from 'react';
 import type { FragmentContract } from '../../core/index.js';
-import { Stack, Text, Card, Chip, Alert, EmptyState, CodeBlock, Badge } from '@fragments-sdk/ui';
+import { Stack, Text, Card, Chip, Alert, EmptyState, CodeBlock, Badge, Box } from '@fragments-sdk/ui';
 
 interface ContractPanelProps {
   contract?: FragmentContract;
@@ -37,7 +37,7 @@ export const ContractPanel = memo(function ContractPanel({
         </EmptyState.Icon>
         <EmptyState.Title>No contract metadata</EmptyState.Title>
         <EmptyState.Description>
-          Add a <code style={{ background: 'var(--bg-hover)', padding: '2px 4px', borderRadius: '4px' }}>contract</code> field to the fragment definition to enable AI agent features.
+          Add a <Box as="code" padding="xs" background="secondary" rounded="sm">contract</Box> field to the fragment definition to enable AI agent features.
         </EmptyState.Description>
         <EmptyState.Actions>
           <CodeBlock
@@ -55,7 +55,7 @@ export const ContractPanel = memo(function ContractPanel({
   }
 
   return (
-    <div style={{ padding: '16px', fontSize: '14px' }}>
+    <Box padding="md" style={{ fontSize: '14px' }}>
       <Stack gap="lg">
         {/* Props Summary */}
         {contract.propsSummary && contract.propsSummary.length > 0 && (
@@ -110,12 +110,11 @@ export const ContractPanel = memo(function ContractPanel({
           <Section title="Accessibility Rules">
             <Stack gap="sm">
               {contract.a11yRules.map((rule, i) => (
+                <Box key={i} padding="sm" background="secondary" rounded="sm">
                 <Stack
-                  key={i}
                   direction="row"
                   align="center"
                   gap="sm"
-                  style={{ padding: '8px', background: 'var(--bg-hover)', borderRadius: '4px' }}
                 >
                   <span style={{ color: '#22c55e' }}>
                     <svg style={{ width: '16px', height: '16px' }} fill="none" viewBox="0 0 24 24" stroke="currentColor">
@@ -124,6 +123,7 @@ export const ContractPanel = memo(function ContractPanel({
                   </span>
                   <Text font="mono" size="xs" color="secondary">{rule}</Text>
                 </Stack>
+                </Box>
               ))}
             </Stack>
           </Section>
@@ -160,7 +160,7 @@ export const ContractPanel = memo(function ContractPanel({
           </Alert>
         )}
       </Stack>
-    </div>
+    </Box>
   );
 });
 

package/src/viewer/components/EmptyVariantMessage.tsx

@@ -0,0 +1,54 @@
+import { Stack, Text, Alert } from "@fragments-sdk/ui";
+
+interface EmptyVariantMessageProps {
+  reason: string;
+  variantName: string;
+  hint?: string;
+}
+
+export function EmptyVariantMessage({ reason, variantName, hint }: EmptyVariantMessageProps) {
+  return (
+    <Alert variant="warning">
+      <Alert.Body>
+        <Alert.Title>Variant "{variantName}" rendered empty</Alert.Title>
+        <Alert.Content>
+          <Stack direction="column" gap="sm">
+            <Text size="xs" color="secondary">
+              {reason}
+            </Text>
+            {hint && (
+              <Text size="xs" color="tertiary">
+                <Text as="span" size="xs" weight="semibold">
+                  Tip:
+                </Text>{" "}
+                {hint}
+              </Text>
+            )}
+            <div>
+              <Text size="xs" color="tertiary" weight="semibold">
+                Common causes:
+              </Text>
+              <ul style={{ marginTop: "4px", marginLeft: "16px", listStyleType: "disc" }}>
+                <li>
+                  <Text size="xs" color="secondary">
+                    Component requires props that weren't provided
+                  </Text>
+                </li>
+                <li>
+                  <Text size="xs" color="secondary">
+                    Component renders conditionally and conditions aren't met
+                  </Text>
+                </li>
+                <li>
+                  <Text size="xs" color="secondary">
+                    Story args reference variables that don't exist in this context
+                  </Text>
+                </li>
+              </ul>
+            </div>
+          </Stack>
+        </Alert.Content>
+      </Alert.Body>
+    </Alert>
+  );
+}

package/src/viewer/components/FigmaEmbed.tsx

@@ -1,5 +1,6 @@
 import { useRef, useEffect, useState, useMemo, useCallback } from "react";
 import { FigmaIcon } from "./Icons.js";
+import { Stack, Text, Button } from '@fragments-sdk/ui';
 
 interface FigmaEmbedProps {
   /** Current Figma URL to display */
@@ -124,18 +125,19 @@ export function FigmaEmbed({ figmaUrl, allFigmaUrls, zoom = 100, className, styl
   // If we can't parse the URL, show error
   if (!currentParsed) {
     return (
-      <div className={className} style={{ ...style, display: "flex", alignItems: "center", justifyContent: "center" }}>
-        <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: '8px', color: 'var(--text-tertiary)', padding: '16px', textAlign: 'center' }}>
+      <Stack className={className} align="center" justify="center" style={style}>
+        <Stack direction="column" align="center" gap="sm" style={{ color: 'var(--text-tertiary)', padding: '16px', textAlign: 'center' }}>
           <FigmaIcon style={{ width: '24px', height: '24px' }} />
-          <span style={{ fontSize: '12px' }}>Unable to embed Figma design</span>
-          <button
+          <Text size="xs">Unable to embed Figma design</Text>
+          <Button
+            variant="ghost"
+            size="sm"
             onClick={() => window.open(figmaUrl, "_blank", "noopener,noreferrer")}
-            style={{ fontSize: '12px', color: 'var(--color-accent)', background: 'none', border: 'none', cursor: 'pointer', textDecoration: 'underline' }}
           >
             Open in Figma
-          </button>
-        </div>
-      </div>
+          </Button>
+        </Stack>
+      </Stack>
     );
   }
 
@@ -143,22 +145,22 @@ export function FigmaEmbed({ figmaUrl, allFigmaUrls, zoom = 100, className, styl
     <div className={className} style={{ ...style, position: "relative", overflow: "hidden" }}>
       {/* Loading overlay - shows while current iframe is loading */}
       {!isCurrentLoaded && (
-        <div style={{ position: 'absolute', inset: 0, display: 'flex', alignItems: 'center', justifyContent: 'center', backgroundColor: 'var(--bg-secondary)', zIndex: 20 }}>
-          <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: '8px' }}>
+        <Stack align="center" justify="center" style={{ position: 'absolute', inset: 0, backgroundColor: 'var(--bg-secondary)', zIndex: 20 }}>
+          <Stack direction="column" align="center" gap="sm">
             <FigmaIcon style={{ width: '20px', height: '20px', color: 'var(--text-tertiary)' }} />
-            <span style={{ fontSize: '12px', color: 'var(--text-tertiary)' }}>Loading Figma...</span>
-          </div>
-        </div>
+            <Text size="xs" color="tertiary">Loading Figma...</Text>
+          </Stack>
+        </Stack>
       )}
 
       {/* Error overlay */}
       {error && (
-        <div style={{ position: 'absolute', inset: 0, display: 'flex', alignItems: 'center', justifyContent: 'center', backgroundColor: 'var(--bg-secondary)', zIndex: 20 }}>
-          <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: '8px', color: 'var(--text-tertiary)' }}>
+        <Stack align="center" justify="center" style={{ position: 'absolute', inset: 0, backgroundColor: 'var(--bg-secondary)', zIndex: 20 }}>
+          <Stack direction="column" align="center" gap="sm" style={{ color: 'var(--text-tertiary)' }}>
             <FigmaIcon style={{ width: '24px', height: '24px' }} />
-            <span style={{ fontSize: '12px' }}>{error}</span>
-          </div>
-        </div>
+            <Text size="xs">{error}</Text>
+          </Stack>
+        </Stack>
       )}
 
       {/*