@fragments-sdk/cli 0.6.0 → 0.7.1

package/src/viewer/components/PreviewFrameHost.tsx

@@ -3,7 +3,7 @@
  *
  * This component runs inside the preview iframe and:
  * 1. Listens for render requests from the parent window
- * 2. Loads and renders the requested segment variant
+ * 2. Loads and renders the requested fragment variant
  * 3. Applies theme styling
  * 4. Reports render status back to parent
  */
@@ -11,8 +11,8 @@
 import { useState, useEffect, useRef, type ReactNode } from 'react';
 import { useFrameBridge } from '../hooks/usePreviewBridge.js';
 
-// Types for segment data
-interface SegmentVariant {
+// Types for fragment data
+interface FragmentVariant {
   name: string;
   render: (options?: { loadedData?: Record<string, unknown> }) => ReactNode;
   loaders?: Array<() => Promise<Record<string, unknown>>>;
@@ -20,66 +20,84 @@ interface SegmentVariant {
   hasPlayFunction?: boolean;
 }
 
-interface SegmentDefinition {
+interface FragmentDefinition {
   meta: {
     name: string;
     description?: string;
+    category?: string;
   };
-  variants?: SegmentVariant[];
+  variants?: FragmentVariant[];
 }
 
-interface SegmentItem {
+interface FragmentItem {
   path: string;
-  segment: SegmentDefinition;
+  fragment: FragmentDefinition;
 }
 
-// Cached segments
-let cachedSegments: SegmentItem[] | null = null;
-let segmentsPromise: Promise<SegmentItem[]> | null = null;
+// Cached fragments
+let cachedFragments: FragmentItem[] | null = null;
+let fragmentsPromise: Promise<FragmentItem[]> | null = null;
 
 /**
- * Load segments from the virtual module
+ * Load fragments from the virtual module
  */
-async function loadSegments(): Promise<SegmentItem[]> {
-  if (cachedSegments) {
-    return cachedSegments;
+async function loadFragments(): Promise<FragmentItem[]> {
+  if (cachedFragments) {
+    return cachedFragments;
   }
 
-  if (segmentsPromise) {
-    return segmentsPromise;
+  if (fragmentsPromise) {
+    return fragmentsPromise;
   }
 
-  segmentsPromise = (async () => {
+  fragmentsPromise = (async () => {
     try {
       // @ts-expect-error Virtual module
       const module = await import('virtual:fragments');
-      if (module.segmentsPromise) {
-        cachedSegments = await module.segmentsPromise;
+      if (module.fragmentsPromise) {
+        cachedFragments = await module.fragmentsPromise;
       } else {
-        cachedSegments = module.segments || [];
+        cachedFragments = module.fragments || [];
       }
-      return cachedSegments!;
+      return cachedFragments!;
     } catch (error) {
-      console.error('[PreviewFrameHost] Failed to load segments:', error);
+      console.error('[PreviewFrameHost] Failed to load fragments:', error);
       throw error;
     }
   })();
 
-  return segmentsPromise;
+  return fragmentsPromise;
 }
 
 /**
- * Find a segment by its path
+ * Find a fragment by its path
  */
-function findSegmentByPath(segments: SegmentItem[], path: string): SegmentItem | undefined {
-  return segments.find(s => s.path === path);
+function findFragmentByPath(fragments: FragmentItem[], path: string): FragmentItem | undefined {
+  return fragments.find(s => s.path === path);
 }
 
 /**
- * Find a variant by name within a segment
+ * Find a variant by name within a fragment
  */
-function findVariant(segment: SegmentDefinition, variantName: string): SegmentVariant | undefined {
-  return segment.variants?.find(v => v.name === variantName);
+function findVariant(fragment: FragmentDefinition, variantName: string): FragmentVariant | undefined {
+  return fragment.variants?.find(v => v.name === variantName);
+}
+
+type PreviewMode = 'centered' | 'full-bleed';
+
+function resolvePreviewMode(fragment: FragmentDefinition): PreviewMode {
+  const name = fragment.meta.name.toLowerCase();
+  const category = (fragment.meta.category || '').toLowerCase();
+
+  if (category === 'layout' || category === 'navigation') {
+    return 'full-bleed';
+  }
+
+  if (name.includes('appshell') || name.includes('sidebar') || name.includes('header') || name.includes('layout')) {
+    return 'full-bleed';
+  }
+
+  return 'centered';
 }
 
 /**
@@ -118,11 +136,13 @@ function LoadingIndicator() {
 function VariantRenderer({
   variant,
   props,
+  mode,
   onRendered,
   onError,
 }: {
-  variant: SegmentVariant;
+  variant: FragmentVariant;
   props?: Record<string, unknown>;
+  mode: PreviewMode;
   onRendered: (width: number, height: number) => void;
   onError: (message: string, stack?: string) => void;
 }) {
@@ -208,7 +228,9 @@ function VariantRenderer({
     <div
       ref={containerRef}
       style={{
-        display: 'inline-block',
+        display: mode === 'full-bleed' ? 'block' : 'inline-block',
+        width: mode === 'full-bleed' ? '100%' : undefined,
+        minHeight: mode === 'full-bleed' ? '100vh' : undefined,
         transition: 'opacity 150ms',
         opacity: content ? 1 : 0,
       }}
@@ -223,10 +245,11 @@ function VariantRenderer({
  */
 export function PreviewFrameHost() {
   const { renderRequest, theme, notifyReady, notifyRendered, notifyError } = useFrameBridge();
-  const [segments, setSegments] = useState<SegmentItem[] | null>(null);
+  const [fragments, setFragments] = useState<FragmentItem[] | null>(null);
   const [loadError, setLoadError] = useState<string | null>(null);
-  const [currentVariant, setCurrentVariant] = useState<SegmentVariant | null>(null);
+  const [currentVariant, setCurrentVariant] = useState<FragmentVariant | null>(null);
   const [currentProps, setCurrentProps] = useState<Record<string, unknown> | undefined>(undefined);
+  const [previewMode, setPreviewMode] = useState<PreviewMode>('centered');
 
   // Apply theme to document
   useEffect(() => {
@@ -237,15 +260,19 @@ export function PreviewFrameHost() {
     }
   }, [theme]);
 
-  // Load segments on mount
   useEffect(() => {
-    loadSegments()
+    document.body.setAttribute('data-preview-mode', previewMode);
+  }, [previewMode]);
+
+  // Load fragments on mount
+  useEffect(() => {
+    loadFragments()
       .then(segs => {
-        setSegments(segs);
+        setFragments(segs);
         notifyReady();
       })
       .catch(err => {
-        const message = err instanceof Error ? err.message : 'Failed to load segments';
+        const message = err instanceof Error ? err.message : 'Failed to load fragments';
         setLoadError(message);
         notifyError(message);
       });
@@ -253,32 +280,33 @@ export function PreviewFrameHost() {
 
   // Handle render requests
   useEffect(() => {
-    if (!renderRequest || !segments) return;
+    if (!renderRequest || !fragments) return;
 
-    const { segmentPath, variantName, props } = renderRequest;
+    const { fragmentPath, variantName, props } = renderRequest;
 
-    // Find segment
-    const segmentItem = findSegmentByPath(segments, segmentPath);
-    if (!segmentItem) {
-      notifyError(`Segment not found: ${segmentPath}`);
+    // Find fragment
+    const fragmentItem = findFragmentByPath(fragments, fragmentPath);
+    if (!fragmentItem) {
+      notifyError(`Fragment not found: ${fragmentPath}`);
       setCurrentVariant(null);
       return;
     }
 
     // Find variant
-    const variant = findVariant(segmentItem.segment, variantName);
+    const variant = findVariant(fragmentItem.fragment, variantName);
     if (!variant) {
-      notifyError(`Variant not found: ${variantName} in ${segmentPath}`);
+      notifyError(`Variant not found: ${variantName} in ${fragmentPath}`);
       setCurrentVariant(null);
       return;
     }
 
+    setPreviewMode(resolvePreviewMode(fragmentItem.fragment));
     setCurrentVariant(variant);
     setCurrentProps(props);
-  }, [renderRequest, segments, notifyError]);
+  }, [renderRequest, fragments, notifyError]);
 
   // Show loading state
-  if (!segments && !loadError) {
+  if (!fragments && !loadError) {
     return <LoadingIndicator />;
   }
 
@@ -299,9 +327,10 @@ export function PreviewFrameHost() {
   // Render the variant
   return (
     <VariantRenderer
-      key={`${renderRequest?.segmentPath}-${renderRequest?.variantName}`}
+      key={`${renderRequest?.fragmentPath}-${renderRequest?.variantName}`}
       variant={currentVariant}
       props={currentProps}
+      mode={previewMode}
       onRendered={notifyRendered}
       onError={notifyError}
     />

package/src/viewer/components/PreviewToolbar.tsx

@@ -12,13 +12,62 @@ export type { ZoomLevel, BackgroundOption };
 export { getBackgroundStyle } from '../constants/ui.js';
 
 // Background options with display metadata
-const BACKGROUND_OPTIONS_UI: { value: BackgroundOption; label: string; icon: string }[] = [
-  { value: 'white', label: 'White', icon: '\u25FB' },
-  { value: 'black', label: 'Black', icon: '\u25FC' },
-  { value: 'checkerboard', label: 'Checkerboard', icon: '\u25A6' },
-  { value: 'transparent', label: 'Transparent', icon: '\u25C7' },
+const BACKGROUND_OPTIONS_UI: { value: BackgroundOption; label: string }[] = [
+  { value: 'white', label: 'White' },
+  { value: 'black', label: 'Black' },
+  { value: 'checkerboard', label: 'Checkerboard' },
+  { value: 'transparent', label: 'Transparent' },
 ];
 
+function BackgroundSwatch({ background }: { background: BackgroundOption }) {
+  const baseStyle = {
+    width: '14px',
+    height: '14px',
+    borderRadius: '4px',
+    border: '1px solid var(--border)',
+    flexShrink: 0,
+  };
+
+  if (background === 'white') {
+    return <span aria-hidden="true" style={{ ...baseStyle, backgroundColor: '#ffffff' }} />;
+  }
+
+  if (background === 'black') {
+    return <span aria-hidden="true" style={{ ...baseStyle, backgroundColor: '#171717', borderColor: '#2a2a2a' }} />;
+  }
+
+  if (background === 'checkerboard') {
+    return (
+      <span
+        aria-hidden="true"
+        style={{
+          ...baseStyle,
+          backgroundColor: '#ffffff',
+          backgroundImage: `
+            linear-gradient(45deg, #d4d4d8 25%, transparent 25%),
+            linear-gradient(-45deg, #d4d4d8 25%, transparent 25%),
+            linear-gradient(45deg, transparent 75%, #d4d4d8 75%),
+            linear-gradient(-45deg, transparent 75%, #d4d4d8 75%)
+          `,
+          backgroundSize: '8px 8px',
+          backgroundPosition: '0 0, 0 4px, 4px -4px, -4px 0',
+        }}
+      />
+    );
+  }
+
+  return (
+    <span
+      aria-hidden="true"
+      style={{
+        ...baseStyle,
+        backgroundColor: 'transparent',
+        backgroundImage: 'linear-gradient(135deg, transparent 42%, var(--text-tertiary) 43%, var(--text-tertiary) 57%, transparent 58%)',
+      }}
+    />
+  );
+}
+
 interface PreviewToolbarProps {
   zoom: ZoomLevel;
   background: BackgroundOption;
@@ -102,10 +151,8 @@ export function PreviewToolbar({
         <Menu.Trigger asChild>
           <Button variant="ghost" size="sm" title="Background color">
             <Stack direction="row" gap="xs" align="center">
-              <span style={{ fontSize: '14px' }}>
-                {BACKGROUND_OPTIONS_UI.find(o => o.value === background)?.icon}
-              </span>
-              <span style={{ textTransform: 'capitalize' }}>{background}</span>
+              <BackgroundSwatch background={background} />
+              <span>{BACKGROUND_OPTIONS_UI.find(o => o.value === background)?.label}</span>
               <span style={{ display: 'inline-flex', width: '12px', height: '12px' }}>
                 <ChevronDownIcon />
               </span>
@@ -120,7 +167,7 @@ export function PreviewToolbar({
             {BACKGROUND_OPTIONS_UI.map((option) => (
               <Menu.RadioItem key={option.value} value={option.value}>
                 <Stack direction="row" gap="sm" align="center">
-                  <span style={{ fontSize: '14px' }}>{option.icon}</span>
+                  <BackgroundSwatch background={option.value} />
                   {option.label}
                 </Stack>
               </Menu.RadioItem>

package/src/viewer/components/RightSidebar.tsx

@@ -1,9 +1,9 @@
-import type { SegmentDefinition } from '../../core/index.js';
+import type { FragmentDefinition } from '../../core/index.js';
 import { useScrollSpy } from '../hooks/useScrollSpy.js';
 import { Sidebar } from '@fragments/ui';
 
 interface RightSidebarProps {
-  segment: SegmentDefinition;
+  fragment: FragmentDefinition;
 }
 
 interface TocItem {
@@ -12,19 +12,19 @@ interface TocItem {
   children?: TocItem[];
 }
 
-export function RightSidebar({ segment }: RightSidebarProps) {
-  // Build table of contents from segment
+export function RightSidebar({ fragment }: RightSidebarProps) {
+  // Build table of contents from fragment
   const tocItems: TocItem[] = [];
 
   // Overview section
   tocItems.push({ id: 'overview', label: 'Overview' });
 
   // Variants section with nested items
-  if (segment.variants && segment.variants.length > 0) {
+  if (fragment.variants && fragment.variants.length > 0) {
     tocItems.push({
       id: 'variants',
       label: 'Variants',
-      children: segment.variants.map((variant, index) => ({
+      children: fragment.variants.map((variant, index) => ({
         id: `variant-${index}`,
         label: variant.name,
       })),
@@ -32,17 +32,17 @@ export function RightSidebar({ segment }: RightSidebarProps) {
   }
 
   // Usage section
-  if (segment.usage) {
+  if (fragment.usage) {
     tocItems.push({ id: 'usage', label: 'Usage' });
   }
 
   // Props section
-  if (segment.props && Object.keys(segment.props).length > 0) {
+  if (fragment.props && Object.keys(fragment.props).length > 0) {
     tocItems.push({ id: 'props', label: 'Props' });
   }
 
   // Relations section
-  if (segment.relations && segment.relations.length > 0) {
+  if (fragment.relations && fragment.relations.length > 0) {
     tocItems.push({ id: 'relations', label: 'Relations' });
   }
 

package/src/viewer/components/Sidebar.tsx

@@ -1,21 +1,21 @@
 import React, { useState, useMemo } from 'react';
-import type { SegmentDefinition } from '../../core/index.js';
+import type { FragmentDefinition } from '../../core/index.js';
 
 interface SidebarProps {
-  segments: Array<{ path: string; segment: SegmentDefinition }>;
-  activeSegment: string | null;
+  fragments: Array<{ path: string; fragment: FragmentDefinition }>;
+  activeFragment: string | null;
   onSelect: (path: string) => void;
 }
 
-export function Sidebar({ segments, activeSegment, onSelect }: SidebarProps): React.ReactElement {
+export function Sidebar({ fragments, activeFragment, onSelect }: SidebarProps): React.ReactElement {
   const [search, setSearch] = useState('');
 
-  // Group segments by category
+  // Group fragments by category
   const grouped = useMemo(() => {
-    const groups: Record<string, typeof segments> = {};
+    const groups: Record<string, typeof fragments> = {};
 
-    for (const item of segments) {
-      const category = item.segment.meta.category || 'uncategorized';
+    for (const item of fragments) {
+      const category = item.fragment.meta.category || 'uncategorized';
       if (!groups[category]) {
         groups[category] = [];
       }
@@ -24,12 +24,12 @@ export function Sidebar({ segments, activeSegment, onSelect }: SidebarProps): Re
 
     // Filter by search
     if (search) {
-      const filtered: Record<string, typeof segments> = {};
+      const filtered: Record<string, typeof fragments> = {};
       for (const [category, items] of Object.entries(groups)) {
         const matchingItems = items.filter(
           (item) =>
-            item.segment.meta.name.toLowerCase().includes(search.toLowerCase()) ||
-            item.segment.meta.description.toLowerCase().includes(search.toLowerCase())
+            item.fragment.meta.name.toLowerCase().includes(search.toLowerCase()) ||
+            item.fragment.meta.description.toLowerCase().includes(search.toLowerCase())
         );
         if (matchingItems.length > 0) {
           filtered[category] = matchingItems;
@@ -39,7 +39,7 @@ export function Sidebar({ segments, activeSegment, onSelect }: SidebarProps): Re
     }
 
     return groups;
-  }, [segments, search]);
+  }, [fragments, search]);
 
   return (
     <div
@@ -68,7 +68,7 @@ export function Sidebar({ segments, activeSegment, onSelect }: SidebarProps): Re
             color: '#111827',
           }}
         >
-          Segments
+          Fragments
         </h1>
         <p
           style={{
@@ -77,7 +77,7 @@ export function Sidebar({ segments, activeSegment, onSelect }: SidebarProps): Re
             color: '#6b7280',
           }}
         >
-          {segments.length} component{segments.length !== 1 ? 's' : ''}
+          {fragments.length} component{fragments.length !== 1 ? 's' : ''}
         </p>
       </div>
 
@@ -132,7 +132,7 @@ export function Sidebar({ segments, activeSegment, onSelect }: SidebarProps): Re
                   padding: '8px 12px',
                   border: 'none',
                   borderRadius: '6px',
-                  background: activeSegment === item.path ? '#e5e7eb' : 'transparent',
+                  background: activeFragment === item.path ? '#e5e7eb' : 'transparent',
                   textAlign: 'left',
                   cursor: 'pointer',
                   transition: 'background 0.15s',
@@ -145,7 +145,7 @@ export function Sidebar({ segments, activeSegment, onSelect }: SidebarProps): Re
                     color: '#111827',
                   }}
                 >
-                  {item.segment.meta.name}
+                  {item.fragment.meta.name}
                 </div>
                 <div
                   style={{
@@ -157,7 +157,7 @@ export function Sidebar({ segments, activeSegment, onSelect }: SidebarProps): Re
                     whiteSpace: 'nowrap',
                   }}
                 >
-                  {item.segment.meta.description}
+                  {item.fragment.meta.description}
                 </div>
               </button>
             ))}

package/src/viewer/components/StoryRenderer.tsx

@@ -1,9 +1,9 @@
 import { useState, useEffect, useMemo, type ReactNode } from "react";
-import type { SegmentVariant } from "../../core/index.js";
+import type { FragmentVariant } from "../../core/index.js";
 
 interface StoryRendererProps {
   /** The variant to render */
-  variant: SegmentVariant;
+  variant: FragmentVariant;
   /** Children render function - receives rendered content */
   children: (content: ReactNode | null, isLoading: boolean, error: Error | null) => ReactNode;
 }

package/src/viewer/components/TokenStylePanel.tsx

@@ -164,7 +164,7 @@ export function TokenStylePanel({
       setTokenError(null);
 
       try {
-        const response = await fetch("/segments/tokens");
+        const response = await fetch("/fragments/tokens");
 
         if (!response.ok) {
           const data = await response.json();

package/src/viewer/components/UsageSection.tsx

@@ -1,8 +1,8 @@
-import type { SegmentUsage } from '../../core/index.js';
+import type { FragmentUsage } from '../../core/index.js';
 import { CheckIcon, XIcon, AccessibilityIcon } from './Icons.js';
 
 interface UsageSectionProps {
-  usage: SegmentUsage;
+  usage: FragmentUsage;
 }
 
 export function UsageSection({ usage }: UsageSectionProps) {

package/src/viewer/components/VariantMatrix.tsx

@@ -12,7 +12,7 @@
 
 import { useState, useMemo, useRef, useCallback } from "react";
 import { useVirtualizer } from "@tanstack/react-virtual";
-import type { SegmentVariant } from "../../core/index.js";
+import type { FragmentVariant } from "../../core/index.js";
 import { ErrorBoundary } from "./ErrorBoundary.js";
 import { StoryRenderer, LoaderIndicator } from "./StoryRenderer.js";
 import { IsolatedPreviewFrame } from "./IsolatedPreviewFrame.js";
@@ -21,11 +21,11 @@ import { getBackgroundStyle, type BackgroundOption } from "./PreviewToolbar.js";
 
 interface VariantMatrixProps {
   /** All variants to display */
-  variants: SegmentVariant[];
+  variants: FragmentVariant[];
   /** Component name for error display */
   componentName: string;
-  /** Segment path for iframe rendering */
-  segmentPath: string;
+  /** Fragment path for iframe rendering */
+  fragmentPath: string;
   /** Current zoom level */
   zoom: number;
   /** Preview theme */
@@ -60,7 +60,7 @@ const VIRTUALIZATION_THRESHOLD = 12;
 export function VariantMatrix({
   variants,
   componentName,
-  segmentPath,
+  fragmentPath,
   zoom,
   previewTheme,
   background,
@@ -204,7 +204,7 @@ export function VariantMatrix({
                           variant={variant}
                           index={index}
                           componentName={componentName}
-                          segmentPath={segmentPath}
+                          fragmentPath={fragmentPath}
                           scale={effectiveScale}
                           minHeight={gridConfig.minHeight}
                           previewTheme={previewTheme}
@@ -236,7 +236,7 @@ export function VariantMatrix({
                 variant={variant}
                 index={index}
                 componentName={componentName}
-                segmentPath={segmentPath}
+                fragmentPath={fragmentPath}
                 scale={effectiveScale}
                 minHeight={gridConfig.minHeight}
                 previewTheme={previewTheme}
@@ -256,10 +256,10 @@ export function VariantMatrix({
 }
 
 interface VariantCardProps {
-  variant: SegmentVariant;
+  variant: FragmentVariant;
   index: number;
   componentName: string;
-  segmentPath: string;
+  fragmentPath: string;
   scale: number;
   minHeight: string;
   previewTheme: "light" | "dark";
@@ -275,7 +275,7 @@ function VariantCard({
   variant,
   index,
   componentName,
-  segmentPath,
+  fragmentPath,
   scale,
   minHeight,
   previewTheme,
@@ -378,7 +378,7 @@ function VariantCard({
       >
         {useIframeIsolation ? (
           <IsolatedPreviewFrame
-            segmentPath={segmentPath}
+            fragmentPath={fragmentPath}
             variantName={variant.name}
             theme={previewTheme}
             width="100%"

package/src/viewer/components/VariantRenderer.tsx

@@ -1,11 +1,11 @@
 // @ts-nocheck
 import React, { type ReactNode, Suspense } from 'react';
-import type { SegmentVariant } from '../../core/index.js';
+import type { FragmentVariant } from '../../core/index.js';
 import { ErrorBoundary } from './ErrorBoundary.js';
 
 interface VariantRendererProps {
   /** The variant to render */
-  variant: SegmentVariant;
+  variant: FragmentVariant;
 
   /** Optional loading fallback for async components */
   loadingFallback?: ReactNode;
@@ -54,7 +54,7 @@ export function VariantRenderer({
 
 interface VariantGridProps {
   /** Variants to render */
-  variants: SegmentVariant[];
+  variants: FragmentVariant[];
 
   /** Number of columns in the grid */
   columns?: number;

package/src/viewer/components/VariantTabs.tsx

@@ -1,9 +1,9 @@
 import { Tabs } from '@fragments/ui';
-import type { SegmentVariant } from '../../core/index.js';
+import type { FragmentVariant } from '../../core/index.js';
 import { PlayIcon } from './Icons.js';
 
 interface VariantTabsProps {
-  variants: SegmentVariant[];
+  variants: FragmentVariant[];
   activeIndex: number;
   onSelect: (index: number) => void;
 }