@fragments-sdk/cli 0.6.0 → 0.7.1

package/src/core/storyAdapter.test.ts

@@ -1,12 +1,12 @@
 /**
- * Unit tests for storyModuleToSegment and related utilities.
+ * Unit tests for storyModuleToFragment and related utilities.
  * Tests both CSF2 (Template.bind) and CSF3 (object stories) patterns.
  */
 
 import { describe, it, expect, beforeEach } from "vitest";
 import { createElement, type ComponentType } from "react";
 import {
-  storyModuleToSegment,
+  storyModuleToFragment,
   setPreviewConfig,
   toId,
   storyNameFromExport,
@@ -23,14 +23,14 @@ const MockComponent = (({ label = "Test" }: { label?: string }) =>
   createElement("button", null, label)) as ComponentType<unknown>;
 (MockComponent as unknown as { displayName: string }).displayName = "MockComponent";
 
-describe("storyModuleToSegment", () => {
+describe("storyModuleToFragment", () => {
   beforeEach(() => {
     // Reset preview config before each test
     setPreviewConfig({});
   });
 
   describe("basic conversion", () => {
-    it("should convert a basic story module to a segment definition", () => {
+    it("should convert a basic story module to a fragment definition", () => {
       const storyModule: StoryModule = {
         default: {
           title: "Components/Button",
@@ -41,14 +41,14 @@ describe("storyModuleToSegment", () => {
         } as Story,
       };
 
-      const segment = storyModuleToSegment(storyModule, "Button.stories.tsx");
+      const fragment = storyModuleToFragment(storyModule, "Button.stories.tsx");
 
-      expect(segment).not.toBeNull();
-      expect(segment!.meta.name).toBe("Button");
-      expect(segment!.meta.category).toBe("general");
-      expect(segment!.component).toBe(MockComponent);
-      expect(segment!.variants).toHaveLength(1);
-      expect(segment!.variants[0].name).toBe("Primary");
+      expect(fragment).not.toBeNull();
+      expect(fragment!.meta.name).toBe("Button");
+      expect(fragment!.meta.category).toBe("general");
+      expect(fragment!.component).toBe(MockComponent);
+      expect(fragment!.variants).toHaveLength(1);
+      expect(fragment!.variants[0].name).toBe("Primary");
     });
 
     it("should return null for stories without a component", () => {
@@ -58,8 +58,8 @@ describe("storyModuleToSegment", () => {
         },
       };
 
-      const segment = storyModuleToSegment(storyModule, "Intro.stories.tsx");
-      expect(segment).toBeNull();
+      const fragment = storyModuleToFragment(storyModule, "Intro.stories.tsx");
+      expect(fragment).toBeNull();
     });
 
     it("should extract component name from title path", () => {
@@ -71,10 +71,10 @@ describe("storyModuleToSegment", () => {
         Default: { args: {} } as Story,
       };
 
-      const segment = storyModuleToSegment(storyModule, "TextField.stories.tsx");
+      const fragment = storyModuleToFragment(storyModule, "TextField.stories.tsx");
 
-      expect(segment!.meta.name).toBe("TextField");
-      expect(segment!.meta.category).toBe("forms");
+      expect(fragment!.meta.name).toBe("TextField");
+      expect(fragment!.meta.category).toBe("forms");
     });
 
     it("should use component displayName when title is not provided", () => {
@@ -85,9 +85,9 @@ describe("storyModuleToSegment", () => {
         Default: { args: {} } as Story,
       };
 
-      const segment = storyModuleToSegment(storyModule, "path/to/Component.stories.tsx");
+      const fragment = storyModuleToFragment(storyModule, "path/to/Component.stories.tsx");
 
-      expect(segment!.meta.name).toBe("MockComponent");
+      expect(fragment!.meta.name).toBe("MockComponent");
     });
   });
 
@@ -112,11 +112,11 @@ describe("storyModuleToSegment", () => {
         Secondary,
       };
 
-      const segment = storyModuleToSegment(storyModule, "Button.stories.tsx");
+      const fragment = storyModuleToFragment(storyModule, "Button.stories.tsx");
 
-      expect(segment!.variants).toHaveLength(2);
-      expect(segment!.variants[0].name).toBe("Primary");
-      expect(segment!.variants[1].name).toBe("Secondary");
+      expect(fragment!.variants).toHaveLength(2);
+      expect(fragment!.variants[0].name).toBe("Primary");
+      expect(fragment!.variants[1].name).toBe("Secondary");
     });
 
     it("should use storyName when provided on CSF2 story", () => {
@@ -135,9 +135,9 @@ describe("storyModuleToSegment", () => {
         MyStory,
       };
 
-      const segment = storyModuleToSegment(storyModule, "Button.stories.tsx");
+      const fragment = storyModuleToFragment(storyModule, "Button.stories.tsx");
 
-      expect(segment!.variants[0].name).toBe("Custom Story Name");
+      expect(fragment!.variants[0].name).toBe("Custom Story Name");
     });
   });
 
@@ -157,11 +157,11 @@ describe("storyModuleToSegment", () => {
         } as Story,
       };
 
-      const segment = storyModuleToSegment(storyModule, "Button.stories.tsx");
+      const fragment = storyModuleToFragment(storyModule, "Button.stories.tsx");
 
-      expect(segment!.variants).toHaveLength(2);
-      expect(segment!.variants[0].name).toBe("Primary");
-      expect(segment!.variants[1].name).toBe("With Custom Render");
+      expect(fragment!.variants).toHaveLength(2);
+      expect(fragment!.variants[0].name).toBe("Primary");
+      expect(fragment!.variants[1].name).toBe("With Custom Render");
     });
 
     it("should use story name property when provided", () => {
@@ -176,9 +176,9 @@ describe("storyModuleToSegment", () => {
         } as Story,
       };
 
-      const segment = storyModuleToSegment(storyModule, "Button.stories.tsx");
+      const fragment = storyModuleToFragment(storyModule, "Button.stories.tsx");
 
-      expect(segment!.variants[0].name).toBe("Explicit Name");
+      expect(fragment!.variants[0].name).toBe("Explicit Name");
     });
 
     it("should detect play functions", () => {
@@ -198,10 +198,10 @@ describe("storyModuleToSegment", () => {
         } as Story,
       };
 
-      const segment = storyModuleToSegment(storyModule, "Button.stories.tsx");
+      const fragment = storyModuleToFragment(storyModule, "Button.stories.tsx");
 
-      expect(segment!.variants[0].hasPlayFunction).toBe(true);
-      expect(segment!.variants[1].hasPlayFunction).toBeUndefined();
+      expect(fragment!.variants[0].hasPlayFunction).toBe(true);
+      expect(fragment!.variants[1].hasPlayFunction).toBeUndefined();
     });
   });
 
@@ -230,13 +230,13 @@ describe("storyModuleToSegment", () => {
         Default: { args: {} } as Story,
       };
 
-      const segment = storyModuleToSegment(storyModule, "Button.stories.tsx");
+      const fragment = storyModuleToFragment(storyModule, "Button.stories.tsx");
 
-      expect(segment!.props.label.type).toBe("string");
-      expect(segment!.props.label.description).toBe("Button label text");
-      expect(segment!.props.disabled.type).toBe("boolean");
-      expect(segment!.props.size.type).toBe("enum");
-      expect(segment!.props.size.values).toEqual(["small", "medium", "large"]);
+      expect(fragment!.props.label.type).toBe("string");
+      expect(fragment!.props.label.description).toBe("Button label text");
+      expect(fragment!.props.disabled.type).toBe("boolean");
+      expect(fragment!.props.size.type).toBe("enum");
+      expect(fragment!.props.size.values).toEqual(["small", "medium", "large"]);
     });
 
     it("should handle all control types", () => {
@@ -261,23 +261,23 @@ describe("storyModuleToSegment", () => {
         Default: { args: {} } as Story,
       };
 
-      const segment = storyModuleToSegment(storyModule, "Test.stories.tsx");
-
-      expect(segment!.props.text.type).toBe("string");
-      expect(segment!.props.number.type).toBe("number");
-      expect(segment!.props.range.type).toBe("number");
-      expect(segment!.props.range.controlType).toBe("range");
-      expect(segment!.props.range.controlOptions).toEqual({ min: 0, max: 100 });
-      expect(segment!.props.boolean.type).toBe("boolean");
-      expect(segment!.props.color.type).toBe("string");
-      expect(segment!.props.color.controlType).toBe("color");
-      expect(segment!.props.date.type).toBe("string");
-      expect(segment!.props.date.controlType).toBe("date");
-      expect(segment!.props.object.type).toBe("object");
-      expect(segment!.props.radio.type).toBe("enum");
-      expect(segment!.props.inlineRadio.type).toBe("enum");
-      expect(segment!.props.select.type).toBe("enum");
-      expect(segment!.props.multiSelect.type).toBe("enum");
+      const fragment = storyModuleToFragment(storyModule, "Test.stories.tsx");
+
+      expect(fragment!.props.text.type).toBe("string");
+      expect(fragment!.props.number.type).toBe("number");
+      expect(fragment!.props.range.type).toBe("number");
+      expect(fragment!.props.range.controlType).toBe("range");
+      expect(fragment!.props.range.controlOptions).toEqual({ min: 0, max: 100 });
+      expect(fragment!.props.boolean.type).toBe("boolean");
+      expect(fragment!.props.color.type).toBe("string");
+      expect(fragment!.props.color.controlType).toBe("color");
+      expect(fragment!.props.date.type).toBe("string");
+      expect(fragment!.props.date.controlType).toBe("date");
+      expect(fragment!.props.object.type).toBe("object");
+      expect(fragment!.props.radio.type).toBe("enum");
+      expect(fragment!.props.inlineRadio.type).toBe("enum");
+      expect(fragment!.props.select.type).toBe("enum");
+      expect(fragment!.props.multiSelect.type).toBe("enum");
     });
 
     it("should handle action argTypes as functions", () => {
@@ -294,9 +294,9 @@ describe("storyModuleToSegment", () => {
         Default: { args: {} } as Story,
       };
 
-      const segment = storyModuleToSegment(storyModule, "Button.stories.tsx");
+      const fragment = storyModuleToFragment(storyModule, "Button.stories.tsx");
 
-      expect(segment!.props.onClick.type).toBe("function");
+      expect(fragment!.props.onClick.type).toBe("function");
     });
 
     it("should skip disabled argTypes", () => {
@@ -312,10 +312,10 @@ describe("storyModuleToSegment", () => {
         Default: { args: {} } as Story,
       };
 
-      const segment = storyModuleToSegment(storyModule, "Button.stories.tsx");
+      const fragment = storyModuleToFragment(storyModule, "Button.stories.tsx");
 
-      expect(segment!.props.visible).toBeDefined();
-      expect(segment!.props.hidden).toBeUndefined();
+      expect(fragment!.props.visible).toBeDefined();
+      expect(fragment!.props.hidden).toBeUndefined();
     });
   });
 
@@ -339,8 +339,8 @@ describe("storyModuleToSegment", () => {
         } as Story,
       };
 
-      const segment = storyModuleToSegment(storyModule, "Button.stories.tsx");
-      segment!.variants[0].render();
+      const fragment = storyModuleToFragment(storyModule, "Button.stories.tsx");
+      fragment!.variants[0].render();
 
       expect(decoratorCalled).toBe(true);
     });
@@ -363,9 +363,9 @@ describe("storyModuleToSegment", () => {
         Story2: { args: { label: "2" } } as Story,
       };
 
-      const segment = storyModuleToSegment(storyModule, "Button.stories.tsx");
-      segment!.variants[0].render();
-      segment!.variants[1].render();
+      const fragment = storyModuleToFragment(storyModule, "Button.stories.tsx");
+      fragment!.variants[0].render();
+      fragment!.variants[1].render();
 
       expect(metaDecoratorCount).toBe(2);
     });
@@ -390,8 +390,8 @@ describe("storyModuleToSegment", () => {
         Default: { args: { label: "Test" } } as Story,
       };
 
-      const segment = storyModuleToSegment(storyModule, "Button.stories.tsx");
-      segment!.variants[0].render();
+      const fragment = storyModuleToFragment(storyModule, "Button.stories.tsx");
+      fragment!.variants[0].render();
 
       expect(globalDecoratorCalled).toBe(true);
     });
@@ -410,12 +410,12 @@ describe("storyModuleToSegment", () => {
         Excluded: { args: { label: "Excluded" } } as Story,
       };
 
-      const segment = storyModuleToSegment(storyModule, "Button.stories.tsx");
+      const fragment = storyModuleToFragment(storyModule, "Button.stories.tsx");
 
-      expect(segment!.variants).toHaveLength(2);
-      expect(segment!.variants.map((v) => v.name)).toContain("Primary");
-      expect(segment!.variants.map((v) => v.name)).toContain("Secondary");
-      expect(segment!.variants.map((v) => v.name)).not.toContain("Excluded");
+      expect(fragment!.variants).toHaveLength(2);
+      expect(fragment!.variants.map((v) => v.name)).toContain("Primary");
+      expect(fragment!.variants.map((v) => v.name)).toContain("Secondary");
+      expect(fragment!.variants.map((v) => v.name)).not.toContain("Excluded");
     });
 
     it("should filter stories using excludeStories array", () => {
@@ -429,10 +429,10 @@ describe("storyModuleToSegment", () => {
         Internal: { args: { label: "Internal" } } as Story,
       };
 
-      const segment = storyModuleToSegment(storyModule, "Button.stories.tsx");
+      const fragment = storyModuleToFragment(storyModule, "Button.stories.tsx");
 
-      expect(segment!.variants).toHaveLength(1);
-      expect(segment!.variants[0].name).toBe("Primary");
+      expect(fragment!.variants).toHaveLength(1);
+      expect(fragment!.variants[0].name).toBe("Primary");
     });
 
     it("should filter stories using excludeStories regex", () => {
@@ -447,10 +447,10 @@ describe("storyModuleToSegment", () => {
         _Internal: { args: { label: "Internal" } } as Story,
       };
 
-      const segment = storyModuleToSegment(storyModule, "Button.stories.tsx");
+      const fragment = storyModuleToFragment(storyModule, "Button.stories.tsx");
 
-      expect(segment!.variants).toHaveLength(1);
-      expect(segment!.variants[0].name).toBe("Primary");
+      expect(fragment!.variants).toHaveLength(1);
+      expect(fragment!.variants[0].name).toBe("Primary");
     });
   });
 
@@ -467,10 +467,10 @@ describe("storyModuleToSegment", () => {
         } as Story,
       };
 
-      const segment = storyModuleToSegment(storyModule, "Button.stories.tsx");
+      const fragment = storyModuleToFragment(storyModule, "Button.stories.tsx");
 
-      expect(segment!.variants[0].loaders).toBeDefined();
-      expect(segment!.variants[0].loaders).toHaveLength(1);
+      expect(fragment!.variants[0].loaders).toBeDefined();
+      expect(fragment!.variants[0].loaders).toHaveLength(1);
     });
 
     it("should collect loaders from meta and story", () => {
@@ -486,10 +486,10 @@ describe("storyModuleToSegment", () => {
         } as Story,
       };
 
-      const segment = storyModuleToSegment(storyModule, "Button.stories.tsx");
+      const fragment = storyModuleToFragment(storyModule, "Button.stories.tsx");
 
       // Should have both meta and story loaders
-      expect(segment!.variants[0].loaders).toHaveLength(2);
+      expect(fragment!.variants[0].loaders).toHaveLength(2);
     });
   });
 
@@ -504,11 +504,11 @@ describe("storyModuleToSegment", () => {
         WithIcon: { args: { label: "With Icon" } } as Story,
       };
 
-      const segment = storyModuleToSegment(storyModule, "Button.stories.tsx");
+      const fragment = storyModuleToFragment(storyModule, "Button.stories.tsx");
 
       // toId lowercases the export name without adding hyphens
-      expect(segment!.variants[0].storyId).toBe("components-forms-button--primary");
-      expect(segment!.variants[1].storyId).toBe("components-forms-button--withicon");
+      expect(fragment!.variants[0].storyId).toBe("components-forms-button--primary");
+      expect(fragment!.variants[1].storyId).toBe("components-forms-button--withicon");
     });
   });
 });

package/src/core/storyAdapter.ts

@@ -1,5 +1,5 @@
 /**
- * Runtime adapter for converting Storybook CSF modules to Segment definitions.
+ * Runtime adapter for converting Storybook CSF modules to Fragment definitions.
  *
  * This operates on IMPORTED modules at runtime, not source code parsing.
  * By leveraging Vite's module system, we get 100% accurate render functions
@@ -11,11 +11,11 @@
 import { createElement, type ComponentType, type ReactNode } from "react";
 import { toId, storyNameFromExport, isExportStory } from "./storybook-csf.js";
 import type {
-  SegmentDefinition,
-  SegmentMeta,
-  SegmentUsage,
+  FragmentDefinition,
+  FragmentMeta,
+  FragmentUsage,
   PropDefinition,
-  SegmentVariant,
+  FragmentVariant,
   ControlType,
   VariantLoader,
   PlayFunction,
@@ -194,16 +194,16 @@ export function getPreviewConfig(): PreviewConfig {
 }
 
 /**
- * Convert a Storybook module to a Segment definition at runtime.
+ * Convert a Storybook module to a Fragment definition at runtime.
  *
  * @param storyModule - The imported Storybook module
  * @param filePath - File path for metadata extraction
- * @returns A complete SegmentDefinition ready for the viewer
+ * @returns A complete FragmentDefinition ready for the viewer
  */
-export function storyModuleToSegment(
+export function storyModuleToFragment(
   storyModule: StoryModule,
   filePath: string
-): SegmentDefinition | null {
+): FragmentDefinition | null {
   const meta = storyModule.default;
   const component = meta.component;
 
@@ -220,7 +220,7 @@ export function storyModuleToSegment(
   // Extract Figma URL from parameters.design.url (storybook-addon-designs) or parameters.figma
   const figmaUrl = extractFigmaUrl(meta.parameters);
 
-  const segmentMeta: SegmentMeta = {
+  const fragmentMeta: FragmentMeta = {
     name: componentName,
     description:
       meta.parameters?.docs?.description?.component ??
@@ -231,14 +231,14 @@ export function storyModuleToSegment(
     figma: figmaUrl,
   };
 
-  const usage: SegmentUsage = {
+  const usage: FragmentUsage = {
     when: [`Use ${componentName} for its intended purpose`],
     whenNot: ["When a more specific component is available"],
   };
 
   return {
     component,
-    meta: segmentMeta,
+    meta: fragmentMeta,
     usage,
     props,
     variants,
@@ -249,7 +249,7 @@ export function storyModuleToSegment(
  * Extract component name from meta or file path
  */
 function extractComponentName(meta: StoryMeta, filePath: string): string {
-  // Try title (last segment of path like "Components/Forms/Button" -> "Button")
+  // Try title (last fragment of path like "Components/Forms/Button" -> "Button")
   if (meta.title) {
     const parts = meta.title.split("/");
     return parts[parts.length - 1];
@@ -307,7 +307,7 @@ function extractFigmaUrl(parameters?: Record<string, unknown>): string | undefin
 }
 
 /**
- * Convert Storybook argTypes to Segment props
+ * Convert Storybook argTypes to Fragment props
  * Merges global argTypes from preview config with meta argTypes
  */
 function convertArgTypes(
@@ -482,8 +482,8 @@ function extractVariants(
   storyModule: StoryModule,
   component: ComponentType<unknown>,
   meta: StoryMeta
-): SegmentVariant[] {
-  const variants: SegmentVariant[] = [];
+): FragmentVariant[] {
+  const variants: FragmentVariant[] = [];
 
   for (const [exportName, exportValue] of Object.entries(storyModule)) {
     // Skip default export

package/src/core/types.ts

@@ -1,19 +1,19 @@
 import type { ComponentType, ReactNode, JSX } from "react";
 
 /**
- * A React component that can be used in a segment definition.
+ * A React component that can be used in a fragment definition.
  * This type is intentionally broad to support various React component patterns
  * including FC, forwardRef, memo, and class components across different React versions.
  */
  
-export type SegmentComponent<TProps = any> =
+export type FragmentComponent<TProps = any> =
   | ComponentType<TProps>
   | ((props: TProps) => ReactNode | JSX.Element | null);
 
 /**
  * Metadata about the component
  */
-export interface SegmentMeta {
+export interface FragmentMeta {
   /** Component display name */
   name: string;
 
@@ -91,7 +91,7 @@ export interface FigmaTextContentMapping {
 /**
  * Usage guidelines for AI agents and developers
  */
-export interface SegmentUsage {
+export interface FragmentUsage {
   /** When to use this component */
   when: string[];
 
@@ -238,7 +238,7 @@ export interface VariantRenderOptions {
 /**
  * A single variant/example of the component
  */
-export interface SegmentVariant {
+export interface FragmentVariant {
   /** Variant name */
   name: string;
 
@@ -279,7 +279,7 @@ export interface SegmentVariant {
  * Agent-optimized contract metadata
  * Provides compact, structured data for AI code generation
  */
-export interface SegmentContract {
+export interface FragmentContract {
   /** Short prop descriptions for agents (e.g., "variant: primary|secondary (required)") */
   propsSummary?: string[];
 
@@ -299,11 +299,11 @@ export interface SegmentContract {
 }
 
 /**
- * Provenance tracking for generated segments
+ * Provenance tracking for generated fragments
  * Helps distinguish human-authored from machine-generated content
  */
-export interface SegmentGenerated {
-  /** Source of this segment definition */
+export interface FragmentGenerated {
+  /** Source of this fragment definition */
   source: "storybook" | "manual" | "ai";
 
   /** Original source file (e.g., "Button.stories.tsx") */
@@ -335,17 +335,17 @@ export interface AIMetadata {
 }
 
 /**
- * Complete segment definition
+ * Complete fragment definition
  */
-export interface SegmentDefinition<TProps = unknown> {
+export interface FragmentDefinition<TProps = unknown> {
   /** The component being documented */
-  component: SegmentComponent<TProps>;
+  component: FragmentComponent<TProps>;
 
   /** Component metadata */
-  meta: SegmentMeta;
+  meta: FragmentMeta;
 
   /** Usage guidelines */
-  usage: SegmentUsage;
+  usage: FragmentUsage;
 
   /** Props documentation */
   props: Record<string, PropDefinition>;
@@ -354,16 +354,16 @@ export interface SegmentDefinition<TProps = unknown> {
   relations?: ComponentRelation[];
 
   /** Component variants/examples */
-  variants: SegmentVariant[];
+  variants: FragmentVariant[];
 
   /** Agent-optimized contract metadata */
-  contract?: SegmentContract;
+  contract?: FragmentContract;
 
   /** AI-specific metadata for playground context generation */
   ai?: AIMetadata;
 
-  /** Provenance tracking (for generated segments) */
-  _generated?: SegmentGenerated;
+  /** Provenance tracking (for generated fragments) */
+  _generated?: FragmentGenerated;
 }
 
 /**
@@ -430,7 +430,7 @@ export interface CIConfig {
  * Config file structure
  */
 export interface FragmentsConfig {
-  /** Glob patterns for finding segment/fragment files */
+  /** Glob patterns for finding fragment/fragment files */
   include: string[];
 
   /** Glob patterns to exclude */
@@ -467,11 +467,6 @@ export interface FragmentsConfig {
   ci?: CIConfig;
 }
 
-/**
- * @deprecated Use FragmentsConfig instead
- */
-export type SegmentsConfig = FragmentsConfig;
-
 /**
  * Screenshot capture configuration
  */
@@ -699,11 +694,11 @@ export interface VerifyResult {
 
 // Compiled types — re-exported from @fragments-sdk/context
 export type {
-  CompiledSegment,
+  CompiledFragment,
   CompiledBlock,
   CompiledTokenEntry,
   CompiledTokenData,
-  CompiledSegmentsFile,
+  CompiledFragmentsFile,
 } from '@fragments-sdk/context/types';
 
 // Re-export CompiledBlock under deprecated alias