@fragments-sdk/core 0.1.0

package/src/types.ts

@@ -0,0 +1,784 @@
+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[];
+}
+
+/**
+ * Storybook adapter filtering configuration.
+ * Controls which Storybook stories are included when generating fragments.
+ */
+export interface StorybookFilterConfig {
+  /** Glob-style patterns for component names to explicitly exclude */
+  exclude?: string[];
+  /** Glob-style patterns for component names to force-include (bypasses all heuristic filters) */
+  include?: string[];
+  /** Exclude stories with "Deprecated" in the title (default: true) */
+  excludeDeprecated?: boolean;
+  /** Exclude test stories (title ending /test(s) or *.test.stories.* files) (default: true) */
+  excludeTests?: boolean;
+  /** Exclude SVG icon components (names matching Svg[A-Z]*) (default: true) */
+  excludeSvgIcons?: boolean;
+  /** Exclude sub-components detected by directory structure (default: true) */
+  excludeSubComponents?: boolean;
+}
+
+/**
+ * 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 } };
+
+  /** Storybook adapter filtering configuration */
+  storybook?: StorybookFilterConfig;
+}
+
+/**
+ * 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;