@fragments-sdk/cli 0.9.0 → 0.10.0

package/src/core/types.ts

@@ -1,762 +0,0 @@
-import type { ComponentType, ReactNode, JSX } from "react";
-
-/**
- * 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 FragmentComponent<TProps = any> =
-  | ComponentType<TProps>
-  | ((props: TProps) => ReactNode | JSX.Element | null);
-
-/**
- * Metadata about the component
- */
-export 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
- */
-export type FigmaPropMapping =
-  | FigmaStringMapping
-  | FigmaBooleanMapping
-  | FigmaEnumMapping
-  | FigmaInstanceMapping
-  | FigmaChildrenMapping
-  | FigmaTextContentMapping;
-
-/** Maps a Figma text property to a string prop */
-export interface FigmaStringMapping {
-  __type: 'figma-string';
-  figmaProperty: string;
-}
-
-/** Maps a Figma boolean property to a boolean prop (with optional value mapping) */
-export interface FigmaBooleanMapping {
-  __type: 'figma-boolean';
-  figmaProperty: string;
-  valueMapping?: { true: unknown; false: unknown };
-}
-
-/** Maps a Figma variant property to an enum prop */
-export interface FigmaEnumMapping {
-  __type: 'figma-enum';
-  figmaProperty: string;
-  valueMapping: Record<string, unknown>;
-}
-
-/** References a nested Figma component instance */
-export interface FigmaInstanceMapping {
-  __type: 'figma-instance';
-  figmaProperty: string;
-}
-
-/** Renders children from Figma layer names */
-export interface FigmaChildrenMapping {
-  __type: 'figma-children';
-  layers: string[];
-}
-
-/** Extracts text content from a Figma text layer */
-export interface FigmaTextContentMapping {
-  __type: 'figma-text-content';
-  layer: string;
-}
-
-/**
- * Usage guidelines for AI agents and developers
- */
-export 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
- */
-export 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
- */
-export type ControlType =
-  | "text"
-  | "number"
-  | "range"
-  | "boolean"
-  | "select"
-  | "multi-select"
-  | "radio"
-  | "inline-radio"
-  | "check"
-  | "inline-check"
-  | "object"
-  | "file"
-  | "color"
-  | "date";
-
-/**
- * Definition for a single prop
- */
-export 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
- */
-export type RelationshipType =
-  | "alternative" // Use instead of this component in certain cases
-  | "sibling" // Related component at same level
-  | "parent" // This component should be wrapped by
-  | "child" // This component should contain
-  | "composition" // Used together as compound component
-  | "complementary" // Enhances or works alongside this component
-  | "used-by"; // This component is consumed by another
-
-/**
- * Relationship to another component
- */
-export 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
- */
-export type VariantLoader = () => Promise<Record<string, unknown>>;
-
-/**
- * Play function context passed during interaction testing
- */
-export 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
- */
-export type PlayFunction = (context: PlayFunctionContext) => Promise<void>;
-
-/**
- * Options passed to variant render function
- */
-export 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
- */
-export 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
- */
-export 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
- */
-export 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
- */
-export 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
- */
-export 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
- */
-export 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
- */
-export 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
- */
-export 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`.
- */
-export 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
- */
-export 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
- */
-export 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
- */
-export interface ServiceConfig {
-  /** Browser pool size */
-  poolSize?: number;
-
-  /** Idle timeout before shutdown (ms) */
-  idleTimeout?: number;
-}
-
-/**
- * Viewport dimensions
- */
-export interface Viewport {
-  width: number;
-  height: number;
-  deviceScaleFactor?: number;
-}
-
-/**
- * Theme identifier
- */
-export type Theme = "light" | "dark";
-
-/**
- * Screenshot metadata
- */
-export 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
- */
-export 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
- */
-export 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
- */
-export interface BoundingBox {
-  x: number;
-  y: number;
-  width: number;
-  height: number;
-}
-
-/**
- * Baseline information stored in manifest
- */
-export 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
- */
-export 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
- */
-export interface VerifyRequest {
-  /** Component name */
-  component: string;
-
-  /** Variant name */
-  variant: string;
-
-  /** Theme to verify against */
-  theme?: Theme;
-
-  /** Override diff threshold */
-  threshold?: number;
-}
-
-/**
- * Verification result
- */
-export 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;
-  };
-}
-
-// Compiled types — re-exported from @fragments-sdk/context
-export type {
-  CompiledFragment,
-  CompiledBlock,
-  CompiledTokenEntry,
-  CompiledTokenData,
-  CompiledFragmentsFile,
-} from '@fragments-sdk/context/types';
-
-// Re-export CompiledBlock under deprecated alias
-import type { CompiledBlock as _CompiledBlock } from '@fragments-sdk/context/types';
-
-/**
- * Block definition — a named composition pattern showing how
- * design system components wire together for a common use case.
- */
-export interface BlockDefinition {
-  name: string;
-  description: string;
-  category: string;
-  components: string[];
-  code: string;
-  tags?: string[];
-}
-
-/**
- * @deprecated Use BlockDefinition instead
- */
-export type RecipeDefinition = BlockDefinition;
-
-/**
- * @deprecated Use CompiledBlock instead
- */
-export type CompiledRecipe = _CompiledBlock;