@fragments-sdk/cli 0.9.0 → 0.10.0

package/dist/defineFragment-D0UTve-I.d.ts

@@ -1,665 +0,0 @@
-import { ComponentType, ReactNode, JSX } from 'react';
-import { CompiledBlock, CompiledFragment } from '@fragments-sdk/context/types';
-
-/**
- * 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.
- */
-type FragmentComponent<TProps = any> = ComponentType<TProps> | ((props: TProps) => ReactNode | JSX.Element | null);
-/**
- * Metadata about the component
- */
-interface FragmentMeta {
-    /** Component display name */
-    name: string;
-    /** Brief description of the component's purpose */
-    description: string;
-    /** Category for organizing components (e.g., "actions", "forms", "layout") */
-    category: string;
-    /** Optional tags for additional categorization */
-    tags?: string[];
-    /** Component status */
-    status?: "stable" | "beta" | "deprecated" | "experimental";
-    /** Version when component was introduced */
-    since?: string;
-    /** External npm packages required by this component (displayed in docs Setup section) */
-    dependencies?: Array<{
-        name: string;
-        version: string;
-        reason?: string;
-    }>;
-    /** Figma frame URL for design verification */
-    figma?: string;
-    /** Figma property mappings (how Figma props map to code props) */
-    figmaProps?: Record<string, FigmaPropMapping>;
-}
-/**
- * Figma property mapping types - describes how a Figma property maps to code
- */
-type FigmaPropMapping = FigmaStringMapping | FigmaBooleanMapping | FigmaEnumMapping | FigmaInstanceMapping | FigmaChildrenMapping | FigmaTextContentMapping;
-/** Maps a Figma text property to a string prop */
-interface FigmaStringMapping {
-    __type: 'figma-string';
-    figmaProperty: string;
-}
-/** Maps a Figma boolean property to a boolean prop (with optional value mapping) */
-interface FigmaBooleanMapping {
-    __type: 'figma-boolean';
-    figmaProperty: string;
-    valueMapping?: {
-        true: unknown;
-        false: unknown;
-    };
-}
-/** Maps a Figma variant property to an enum prop */
-interface FigmaEnumMapping {
-    __type: 'figma-enum';
-    figmaProperty: string;
-    valueMapping: Record<string, unknown>;
-}
-/** References a nested Figma component instance */
-interface FigmaInstanceMapping {
-    __type: 'figma-instance';
-    figmaProperty: string;
-}
-/** Renders children from Figma layer names */
-interface FigmaChildrenMapping {
-    __type: 'figma-children';
-    layers: string[];
-}
-/** Extracts text content from a Figma text layer */
-interface FigmaTextContentMapping {
-    __type: 'figma-text-content';
-    layer: string;
-}
-/**
- * Usage guidelines for AI agents and developers
- */
-interface FragmentUsage {
-    /** When to use this component */
-    when: string[];
-    /** When NOT to use this component (with alternatives) */
-    whenNot: string[];
-    /** Additional usage guidelines and best practices */
-    guidelines?: string[];
-    /** Accessibility considerations */
-    accessibility?: string[];
-}
-/**
- * Prop type definitions
- */
-type PropType = {
-    type: "string";
-    pattern?: string;
-} | {
-    type: "number";
-    min?: number;
-    max?: number;
-} | {
-    type: "boolean";
-} | {
-    type: "enum";
-    values: readonly string[];
-} | {
-    type: "function";
-    signature?: string;
-} | {
-    type: "node";
-} | {
-    type: "element";
-} | {
-    type: "object";
-    shape?: Record<string, PropDefinition>;
-} | {
-    type: "array";
-    items?: PropType;
-} | {
-    type: "union";
-    types: PropType[];
-} | {
-    type: "custom";
-    typescript: string;
-};
-/**
- * Storybook control types for UI rendering
- */
-type ControlType = "text" | "number" | "range" | "boolean" | "select" | "multi-select" | "radio" | "inline-radio" | "check" | "inline-check" | "object" | "file" | "color" | "date";
-/**
- * Definition for a single prop
- */
-interface PropDefinition {
-    /** The prop type */
-    type: PropType["type"];
-    /** For enum types, the allowed values */
-    values?: readonly string[];
-    /** Default value if not provided */
-    default?: unknown;
-    /** Description of what this prop does */
-    description: string;
-    /** Whether this prop is required */
-    required?: boolean;
-    /** Usage constraints for AI agents */
-    constraints?: string[];
-    /** Additional type details for complex types */
-    typeDetails?: Omit<PropType, "type">;
-    /** Original Storybook control type for UI rendering (e.g., "color", "date", "range") */
-    controlType?: ControlType;
-    /** Control options (e.g., min/max for range, presetColors for color) */
-    controlOptions?: {
-        min?: number;
-        max?: number;
-        step?: number;
-        presetColors?: string[];
-    };
-}
-/**
- * Relationship types between components
- */
-type RelationshipType = "alternative" | "sibling" | "parent" | "child" | "composition" | "complementary" | "used-by";
-/**
- * Relationship to another component
- */
-interface ComponentRelation {
-    /** Name of the related component */
-    component: string;
-    /** Type of relationship */
-    relationship: RelationshipType;
-    /** Explanation of the relationship */
-    note: string;
-}
-/**
- * Loader function type for async data loading before render
- */
-type VariantLoader = () => Promise<Record<string, unknown>>;
-/**
- * Play function context passed during interaction testing
- */
-interface PlayFunctionContext {
-    /** The rendered canvas element containing the story */
-    canvasElement: HTMLElement;
-    /** Args passed to the story */
-    args: Record<string, unknown>;
-    /** Step function for organizing interactions */
-    step: (name: string, fn: () => Promise<void>) => Promise<void>;
-}
-/**
- * Play function type for interaction testing
- */
-type PlayFunction = (context: PlayFunctionContext) => Promise<void>;
-/**
- * Options passed to variant render function
- */
-interface VariantRenderOptions {
-    /** Props/args to override the variant defaults */
-    args?: Record<string, unknown>;
-    /** Data loaded from async loaders */
-    loadedData?: Record<string, unknown>;
-}
-/**
- * A single variant/example of the component
- */
-interface FragmentVariant {
-    /** Variant name */
-    name: string;
-    /** Description of when to use this variant */
-    description: string;
-    /** Render function that returns the component example
-     * @param options - Optional args overrides and loaded data
-     */
-    render: (options?: VariantRenderOptions) => ReactNode;
-    /** Optional code string for display (auto-generated if not provided) */
-    code?: string;
-    /** Figma frame URL for this specific variant (overrides meta.figma) */
-    figma?: string;
-    /** Whether this variant has a Storybook play function (for display purposes) */
-    hasPlayFunction?: boolean;
-    /** The actual play function for interaction testing */
-    play?: PlayFunction;
-    /** Storybook story ID for this variant (generated by @storybook/csf toId) */
-    storyId?: string;
-    /** Optional tags for this variant (inherited from story tags) */
-    tags?: string[];
-    /** Async loaders to execute before rendering (from Storybook loaders) */
-    loaders?: VariantLoader[];
-    /** The args/props used to render this variant (for code generation) */
-    args?: Record<string, unknown>;
-}
-/**
- * Agent-optimized contract metadata
- * Provides compact, structured data for AI code generation
- */
-interface FragmentContract {
-    /** Short prop descriptions for agents (e.g., "variant: primary|secondary (required)") */
-    propsSummary?: string[];
-    /** Accessibility rule IDs for lookup in glossary (e.g., "A11Y_BTN_LABEL") */
-    a11yRules?: string[];
-    /** Banned patterns in codebase - triggers warnings during code review */
-    bans?: Array<{
-        /** Pattern to match (regex string or literal) */
-        pattern: string;
-        /** Message explaining why this pattern is banned and what to use instead */
-        message: string;
-    }>;
-    /** Scenario tags for use-case matching (e.g., "form.submit", "navigation.primary") */
-    scenarioTags?: string[];
-    /** Per-component performance budget override in bytes (gzipped). Overrides global budget. */
-    performanceBudget?: number;
-}
-/**
- * Provenance tracking for generated fragments
- * Helps distinguish human-authored from machine-generated content
- */
-interface FragmentGenerated {
-    /** Source of this fragment definition */
-    source: "storybook" | "manual" | "ai";
-    /** Original source file (e.g., "Button.stories.tsx") */
-    sourceFile?: string;
-    /** Confidence score from 0-1 (how reliable the extraction was) */
-    confidence?: number;
-    /** ISO timestamp when this was generated */
-    timestamp?: string;
-}
-/**
- * AI-specific metadata for playground context generation
- * Provides hints for AI code generation about component composition
- */
-interface AIMetadata {
-    /** How this component is composed with others */
-    compositionPattern?: "compound" | "simple" | "controlled";
-    /** Sub-component names (without parent prefix, e.g., "Header" not "Card.Header") */
-    subComponents?: string[];
-    /** Sub-components that must be present for valid composition */
-    requiredChildren?: string[];
-    /** Common usage patterns as JSX strings for AI reference */
-    commonPatterns?: string[];
-}
-/**
- * Complete fragment definition
- */
-interface FragmentDefinition<TProps = unknown> {
-    /** The component being documented */
-    component: FragmentComponent<TProps>;
-    /** Component metadata */
-    meta: FragmentMeta;
-    /** Usage guidelines */
-    usage: FragmentUsage;
-    /** Props documentation */
-    props: Record<string, PropDefinition>;
-    /** Relationships to other components */
-    relations?: ComponentRelation[];
-    /** Component variants/examples */
-    variants: FragmentVariant[];
-    /** Agent-optimized contract metadata */
-    contract?: FragmentContract;
-    /** AI-specific metadata for playground context generation */
-    ai?: AIMetadata;
-    /** Provenance tracking (for generated fragments) */
-    _generated?: FragmentGenerated;
-}
-/**
- * Registry generation options
- */
-interface RegistryOptions {
-    /** Only include components that have a corresponding .stories.tsx file */
-    requireStory?: boolean;
-    /** Only include components that are exported (public API) */
-    publicOnly?: boolean;
-    /** Maximum depth for category inference from directory structure (default: 1) */
-    categoryDepth?: number;
-    /** Include props in registry (default: false - AI can read TypeScript directly) */
-    includeProps?: boolean;
-    /** Include full fragment data in registry (default: false - reference fragmentPath instead) */
-    embedFragments?: boolean;
-}
-/**
- * Design token configuration
- */
-interface TokenConfig {
-    /**
-     * Glob patterns for files to scan for tokens
-     * e.g., ["src/styles/theme.scss", "src/styles/variables.css"]
-     */
-    include: string[];
-    /**
-     * Glob patterns to exclude
-     * @example ["node_modules"]
-     */
-    exclude?: string[];
-    /**
-     * Map CSS selectors to theme names
-     * @example { ":root": "default", "[data-theme='dark']": "dark" }
-     */
-    themeSelectors?: Record<string, string>;
-    /** Enable token comparison in style diffs (default: true) */
-    enabled?: boolean;
-}
-/**
- * CI configuration for automated compliance checks
- */
-interface CIConfig {
-    /** Minimum compliance percentage to pass (default: 80) */
-    minCompliance?: number;
-    /** Whether to fail on any visual regression */
-    failOnDiff?: boolean;
-    /** Whether to output JSON format */
-    jsonOutput?: boolean;
-}
-/**
- * Snippet policy configuration.
- * Controls snippet/render quality enforcement in `fragments validate`.
- */
-interface SnippetPolicyConfig {
-    /** Validation mode: warn (non-blocking) or error (blocking). Default: warn */
-    mode?: "warn" | "error";
-    /** Validate snippet strings only, or snippet strings + render functions. Default: snippet+render */
-    scope?: "snippet" | "snippet+render";
-    /** Require authored snippets to be full, copy-pasteable examples with imports. Default: true */
-    requireFullSnippet?: boolean;
-    /** Allow these external modules for JSX components in snippets/renders. */
-    allowedExternalModules?: string[];
-}
-/**
- * Config file structure
- */
-interface FragmentsConfig {
-    /** Glob patterns for finding fragment/fragment files */
-    include: string[];
-    /** Glob patterns to exclude */
-    exclude?: string[];
-    /** Glob patterns for finding component files (for coverage validation) */
-    components?: string[];
-    /** Output path for compiled output */
-    outFile?: string;
-    /** Framework adapter to use */
-    framework?: "react" | "vue" | "svelte";
-    /** Figma file URL for the design system (used by `fragments link`) */
-    figmaFile?: string;
-    /** Figma access token (alternative to FIGMA_ACCESS_TOKEN env var) */
-    figmaToken?: string;
-    /** Screenshot configuration */
-    screenshots?: ScreenshotConfig;
-    /** Service configuration */
-    service?: ServiceConfig;
-    /** Registry generation options */
-    registry?: RegistryOptions;
-    /** Design token discovery and mapping configuration */
-    tokens?: TokenConfig;
-    /** CI pipeline configuration */
-    ci?: CIConfig;
-    /** Snippet/render policy validation */
-    snippets?: SnippetPolicyConfig;
-    /** Performance budgets: preset name or custom config */
-    performance?: string | {
-        preset?: string;
-        budgets?: {
-            bundleSize?: number;
-        };
-    };
-}
-/**
- * Screenshot capture configuration
- */
-interface ScreenshotConfig {
-    /** Default viewport for captures */
-    viewport?: Viewport;
-    /** Diff threshold percentage (0-100) */
-    threshold?: number;
-    /** Additional delay after render before capture (ms) */
-    delay?: number;
-    /** Output directory for baselines (relative to project root) */
-    outputDir?: string;
-    /** Themes to capture */
-    themes?: Theme[];
-}
-/**
- * Service configuration
- */
-interface ServiceConfig {
-    /** Browser pool size */
-    poolSize?: number;
-    /** Idle timeout before shutdown (ms) */
-    idleTimeout?: number;
-}
-/**
- * Viewport dimensions
- */
-interface Viewport {
-    width: number;
-    height: number;
-    deviceScaleFactor?: number;
-}
-/**
- * Theme identifier
- */
-type Theme = "light" | "dark";
-/**
- * Screenshot metadata
- */
-interface Screenshot {
-    /** PNG image data */
-    data: Buffer;
-    /** SHA-256 hash of image data (for change detection) */
-    hash: string;
-    /** Viewport used for capture */
-    viewport: Viewport;
-    /** When this screenshot was taken */
-    capturedAt: Date;
-    /** Capture metadata */
-    metadata: ScreenshotMetadata;
-}
-/**
- * Screenshot metadata
- */
-interface ScreenshotMetadata {
-    /** Component name */
-    component: string;
-    /** Variant name */
-    variant: string;
-    /** Theme used */
-    theme: Theme;
-    /** Time to render the component (ms) */
-    renderTimeMs: number;
-    /** Time to capture the screenshot (ms) */
-    captureTimeMs: number;
-}
-/**
- * Result of comparing two screenshots
- */
-interface DiffResult {
-    /** Whether images are considered matching (below threshold) */
-    matches: boolean;
-    /** Percentage of pixels that differ (0-100) */
-    diffPercentage: number;
-    /** Number of differing pixels */
-    diffPixelCount: number;
-    /** Total pixels compared */
-    totalPixels: number;
-    /** PNG image highlighting differences */
-    diffImage?: Buffer;
-    /** Bounding boxes of changed regions */
-    changedRegions: BoundingBox[];
-    /** Time taken to compute diff (ms) */
-    diffTimeMs: number;
-}
-/**
- * Bounding box for changed region
- */
-interface BoundingBox {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-}
-/**
- * Baseline information stored in manifest
- */
-interface BaselineInfo {
-    /** Component name */
-    component: string;
-    /** Variant name */
-    variant: string;
-    /** Theme */
-    theme: Theme;
-    /** Relative path to image file */
-    path: string;
-    /** SHA-256 hash */
-    hash: string;
-    /** Viewport used */
-    viewport: Viewport;
-    /** When captured */
-    capturedAt: string;
-    /** File size in bytes */
-    fileSize: number;
-}
-/**
- * Manifest file structure
- */
-interface Manifest {
-    /** Schema version */
-    version: "1.0.0";
-    /** When manifest was generated */
-    generatedAt: string;
-    /** Configuration used for capture */
-    config: {
-        defaultViewport: Viewport;
-        defaultThreshold: number;
-        captureDelay: number;
-    };
-    /** All baselines indexed by component/variant */
-    baselines: Record<string, Record<string, BaselineInfo>>;
-}
-/**
- * Verification request from AI agents
- */
-interface VerifyRequest {
-    /** Component name */
-    component: string;
-    /** Variant name */
-    variant: string;
-    /** Theme to verify against */
-    theme?: Theme;
-    /** Override diff threshold */
-    threshold?: number;
-}
-/**
- * Verification result
- */
-interface VerifyResult {
-    /** Overall verdict */
-    verdict: "pass" | "fail" | "error";
-    /** Whether diff is below threshold */
-    matches: boolean;
-    /** Percentage of pixels that differ */
-    diffPercentage: number;
-    /** Current screenshot (base64 PNG) */
-    screenshot: string;
-    /** Baseline screenshot (base64 PNG) */
-    baseline: string;
-    /** Diff image if different (base64 PNG) */
-    diffImage?: string;
-    /** Human-readable notes */
-    notes: string[];
-    /** Error message if verdict is "error" */
-    error?: string;
-    /** Performance metrics */
-    timing: {
-        renderMs: number;
-        captureMs: number;
-        diffMs: number;
-        totalMs: number;
-    };
-}
-
-/**
- * Block definition — a named composition pattern showing how
- * design system components wire together for a common use case.
- */
-interface BlockDefinition {
-    name: string;
-    description: string;
-    category: string;
-    components: string[];
-    code: string;
-    tags?: string[];
-}
-/**
- * @deprecated Use BlockDefinition instead
- */
-type RecipeDefinition = BlockDefinition;
-/**
- * @deprecated Use CompiledBlock instead
- */
-type CompiledRecipe = CompiledBlock;
-
-/**
- * Define a fragment for a component.
- *
- * This is the main API for creating fragment documentation.
- * It provides runtime validation and type safety.
- *
- * @example
- * ```tsx
- * import { defineFragment } from '@fragments-sdk/cli/core';
- * import { Button } from './Button';
- *
- * export default defineFragment({
- *   component: Button,
- *   meta: {
- *     name: 'Button',
- *     description: 'Primary action trigger',
- *     category: 'actions',
- *   },
- *   usage: {
- *     when: ['User needs to trigger an action'],
- *     whenNot: ['Navigation without side effects'],
- *   },
- *   props: {
- *     variant: {
- *       type: 'enum',
- *       values: ['primary', 'secondary'],
- *       default: 'primary',
- *       description: 'Visual style',
- *     },
- *   },
- *   variants: [
- *     {
- *       name: 'Default',
- *       description: 'Default button',
- *       render: () => <Button>Click me</Button>,
- *     },
- *   ],
- * });
- * ```
- */
-declare function defineFragment<TProps>(definition: FragmentDefinition<TProps>): FragmentDefinition<TProps>;
-/**
- * Compile a fragment definition to JSON-serializable format.
- * Used for generating fragments.json for AI consumption.
- */
-declare function compileFragment(definition: FragmentDefinition, filePath: string): CompiledFragment;
-/**
- * Define a composition block.
- *
- * Blocks are pure data describing how design system components
- * wire together for common use cases.
- */
-declare function defineBlock(definition: BlockDefinition): BlockDefinition;
-/**
- * @deprecated Use defineBlock instead
- */
-declare const defineRecipe: typeof defineBlock;
-/**
- * Compile a block definition to JSON-serializable format.
- */
-declare function compileBlock(definition: BlockDefinition, filePath: string): CompiledBlock;
-/**
- * @deprecated Use compileBlock instead
- */
-declare const compileRecipe: typeof compileBlock;
-/**
- * Type helper for extracting props type from a component
- */
-type InferProps<T> = T extends FragmentComponent<infer P> ? P : never;
-
-export { type AIMetadata as A, type BlockDefinition as B, type ControlType as C, type DiffResult as D, type Screenshot as E, type FragmentsConfig as F, type ScreenshotMetadata as G, type BoundingBox as H, type BaselineInfo as I, type VerifyRequest as J, type VerifyResult as K, type FigmaPropMapping as L, type Manifest as M, type TokenConfig as N, compileFragment as O, type PropType as P, compileBlock as Q, type RelationshipType as R, type SnippetPolicyConfig as S, type Theme as T, defineRecipe as U, type VariantLoader as V, compileRecipe as W, type InferProps as X, defineBlock as a, type FragmentDefinition as b, type FigmaStringMapping as c, defineFragment as d, type FigmaBooleanMapping as e, type FigmaEnumMapping as f, type FigmaInstanceMapping as g, type FigmaChildrenMapping as h, type FigmaTextContentMapping as i, type VariantRenderOptions as j, type FragmentComponent as k, type FragmentMeta as l, type FragmentUsage as m, type PropDefinition as n, type ComponentRelation as o, type PlayFunction as p, type PlayFunctionContext as q, type FragmentVariant as r, type RegistryOptions as s, type RecipeDefinition as t, type CompiledRecipe as u, type FragmentContract as v, type FragmentGenerated as w, type ScreenshotConfig as x, type ServiceConfig as y, type Viewport as z };