@fragments-sdk/cli 0.7.0 → 0.7.2

package/src/viewer/components/MultiViewportPreview.tsx

@@ -42,8 +42,8 @@ const DEFAULT_VIEWPORTS: ViewportConfig[] = [
 interface MultiViewportPreviewProps {
   /** Component name for error boundary */
   componentName: string;
-  /** Segment path for iframe rendering */
-  segmentPath: string;
+  /** Fragment path for iframe rendering */
+  fragmentPath: string;
   /** Variant name for iframe rendering */
   variantName: string;
   /** Render function that returns the component (fallback) */
@@ -60,7 +60,7 @@ interface MultiViewportPreviewProps {
 
 export function MultiViewportPreview({
   componentName,
-  segmentPath,
+  fragmentPath,
   variantName,
   renderContent,
   previewTheme,
@@ -203,7 +203,7 @@ export function MultiViewportPreview({
               key={`${vp.name}-${vp.width}`}
               viewport={vp}
               componentName={componentName}
-              segmentPath={segmentPath}
+              fragmentPath={fragmentPath}
               variantName={variantName}
               renderContent={renderContent}
               previewTheme={previewTheme}
@@ -220,7 +220,7 @@ export function MultiViewportPreview({
 interface ViewportPanelProps {
   viewport: ViewportConfig;
   componentName: string;
-  segmentPath: string;
+  fragmentPath: string;
   variantName: string;
   renderContent: () => ReactNode;
   previewTheme: "light" | "dark";
@@ -231,7 +231,7 @@ interface ViewportPanelProps {
 function ViewportPanel({
   viewport,
   componentName,
-  segmentPath,
+  fragmentPath,
   variantName,
   renderContent,
   previewTheme,
@@ -247,7 +247,7 @@ function ViewportPanel({
         previewTheme={previewTheme}
         background={background}
         componentName={componentName}
-        segmentPath={segmentPath}
+        fragmentPath={fragmentPath}
         variantName={variantName}
         renderContent={renderContent}
         useIframeIsolation={useIframeIsolation}
@@ -264,7 +264,7 @@ function ViewportPanel({
       previewTheme={previewTheme}
       background={background}
       componentName={componentName}
-      segmentPath={segmentPath}
+      fragmentPath={fragmentPath}
       variantName={variantName}
       renderContent={renderContent}
       useIframeIsolation={useIframeIsolation}
@@ -280,7 +280,7 @@ interface DeviceMockupProps {
   previewTheme: "light" | "dark";
   background: BackgroundOption;
   componentName: string;
-  segmentPath: string;
+  fragmentPath: string;
   variantName: string;
   renderContent: () => ReactNode;
   useIframeIsolation: boolean;
@@ -294,7 +294,7 @@ function DeviceMockup({
   previewTheme,
   background,
   componentName,
-  segmentPath,
+  fragmentPath,
   variantName,
   renderContent,
   useIframeIsolation,
@@ -427,7 +427,7 @@ function DeviceMockup({
             >
               {useIframeIsolation ? (
                 <IsolatedPreviewFrame
-                  segmentPath={segmentPath}
+                  fragmentPath={fragmentPath}
                   variantName={variantName}
                   theme={previewTheme}
                   width="100%"
@@ -481,7 +481,7 @@ interface DesktopMockupProps {
   previewTheme: "light" | "dark";
   background: BackgroundOption;
   componentName: string;
-  segmentPath: string;
+  fragmentPath: string;
   variantName: string;
   renderContent: () => ReactNode;
   useIframeIsolation: boolean;
@@ -494,7 +494,7 @@ function DesktopMockup({
   previewTheme,
   background,
   componentName,
-  segmentPath,
+  fragmentPath,
   variantName,
   renderContent,
   useIframeIsolation,
@@ -574,7 +574,7 @@ function DesktopMockup({
           >
             {useIframeIsolation ? (
               <IsolatedPreviewFrame
-                segmentPath={segmentPath}
+                fragmentPath={fragmentPath}
                 variantName={variantName}
                 theme={previewTheme}
                 width="100%"

package/src/viewer/components/PreviewArea.tsx

@@ -7,7 +7,7 @@
  */
 
 import { memo, type ReactNode } from 'react';
-import type { SegmentVariant } from '../../core/index.js';
+import type { FragmentVariant } from '../../core/index.js';
 import { ErrorBoundary } from './ErrorBoundary.js';
 import { FigmaEmbed } from './FigmaEmbed.js';
 import { VariantMatrix } from './VariantMatrix.js';
@@ -20,9 +20,9 @@ import { getViewportWidth, type ViewportPreset, type ViewportSize } from './View
 interface PreviewAreaProps {
   // Component data
   componentName: string;
-  segmentPath: string;
-  variant: SegmentVariant | undefined;
-  variants: SegmentVariant[] | undefined;
+  fragmentPath: string;
+  variant: FragmentVariant | undefined;
+  variants: FragmentVariant[] | undefined;
 
   // View settings
   zoom: ZoomLevel;
@@ -185,7 +185,7 @@ const PreviewContent = memo(function PreviewContent({ zoom, previewTheme, backgr
 
 export function PreviewArea({
   componentName,
-  segmentPath,
+  fragmentPath,
   variant,
   variants,
   zoom,
@@ -210,7 +210,7 @@ export function PreviewArea({
       <VariantMatrix
         variants={variants}
         componentName={componentName}
-        segmentPath={segmentPath}
+        fragmentPath={fragmentPath}
         zoom={zoom}
         previewTheme={previewTheme}
         background={background}
@@ -227,7 +227,7 @@ export function PreviewArea({
     return (
       <MultiViewportPreview
         componentName={componentName}
-        segmentPath={segmentPath}
+        fragmentPath={fragmentPath}
         variantName={variant.name}
         renderContent={renderContent}
         previewTheme={previewTheme}
@@ -257,7 +257,7 @@ export function PreviewArea({
                 <DeviceMockup type={viewport as 'tablet' | 'mobile'} width={viewportWidth}>
                   {useIframeIsolation ? (
                     <IsolatedPreviewFrame
-                      segmentPath={segmentPath}
+                      fragmentPath={fragmentPath}
                       variantName={variant.name}
                       theme={previewTheme}
                       width={viewportWidth}
@@ -300,7 +300,7 @@ export function PreviewArea({
         <DeviceMockup type={viewport as 'tablet' | 'mobile'} width={viewportWidth}>
           {useIframeIsolation ? (
             <IsolatedPreviewFrame
-              segmentPath={segmentPath}
+              fragmentPath={fragmentPath}
               variantName={variant.name}
               theme={previewTheme}
               width={viewportWidth}
@@ -337,7 +337,7 @@ export function PreviewArea({
             >
               {useIframeIsolation ? (
                 <IsolatedPreviewFrame
-                  segmentPath={segmentPath}
+                  fragmentPath={fragmentPath}
                   variantName={variant.name}
                   theme={previewTheme}
                   width="100%"
@@ -420,7 +420,7 @@ export function PreviewArea({
           }}
         >
           <IsolatedPreviewFrame
-            segmentPath={segmentPath}
+            fragmentPath={fragmentPath}
             variantName={variant.name}
             theme={previewTheme}
             width="100%"

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,74 +20,74 @@ 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(segment: SegmentDefinition): PreviewMode {
-  const name = segment.meta.name.toLowerCase();
-  const category = (segment.meta.category || '').toLowerCase();
+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';
@@ -140,7 +140,7 @@ function VariantRenderer({
   onRendered,
   onError,
 }: {
-  variant: SegmentVariant;
+  variant: FragmentVariant;
   props?: Record<string, unknown>;
   mode: PreviewMode;
   onRendered: (width: number, height: number) => void;
@@ -245,9 +245,9 @@ 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');
 
@@ -264,15 +264,15 @@ export function PreviewFrameHost() {
     document.body.setAttribute('data-preview-mode', previewMode);
   }, [previewMode]);
 
-  // Load segments on mount
+  // Load fragments on mount
   useEffect(() => {
-    loadSegments()
+    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);
       });
@@ -280,33 +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(segmentItem.segment));
+    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 />;
   }
 
@@ -327,7 +327,7 @@ export function PreviewFrameHost() {
   // Render the variant
   return (
     <VariantRenderer
-      key={`${renderRequest?.segmentPath}-${renderRequest?.variantName}`}
+      key={`${renderRequest?.fragmentPath}-${renderRequest?.variantName}`}
       variant={currentVariant}
       props={currentProps}
       mode={previewMode}

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) {