/**
 * TypeScript types for Fragment JSON files.
 * These types correspond to the JSON schemas in ./schema/
 */

/**
 * Figma design links and mappings
 */
export interface FragmentFigma {
  /** Figma file URL */
  file?: string;
  /** Default Figma node ID for this component */
  nodeId?: string;
  /** Mapping of variant names to Figma node IDs */
  variants?: Record<string, string>;
}

/**
 * Anti-pattern with optional alternative
 */
export interface FragmentDoNotItem {
  /** What not to do */
  text: string;
  /** Component name to use instead */
  instead?: string;
}

/**
 * Usage pattern with code example
 */
export interface FragmentPattern {
  /** Pattern name */
  name: string;
  /** Code example */
  code: string;
  /** When to use this pattern */
  description?: string;
}

/**
 * Usage guidelines for AI agents and developers
 */
export interface FragmentUsage {
  /** Scenarios when this component should be used */
  when?: string[];
  /** Anti-patterns and what to use instead */
  doNot?: (string | FragmentDoNotItem)[];
  /** Common usage patterns with code examples */
  patterns?: FragmentPattern[];
}

/**
 * Accessibility requirements and guidelines
 */
export interface FragmentAccessibility {
  /** ARIA role this component implements */
  role?: string;
  /** Accessibility requirements */
  requirements?: string[];
  /** Keyboard interaction patterns (key -> description) */
  keyboard?: Record<string, string>;
}

/**
 * Relationships to other components
 */
export interface FragmentRelated {
  /** Similar components that might be alternatives */
  similar?: string[];
  /** Components commonly used together with this one */
  composedWith?: string[];
  /** Parent components or patterns where this is commonly used */
  usedIn?: string[];
}

/**
 * Administrative metadata
 */
export interface FragmentMeta {
  /** Team or person responsible for this component */
  owner?: string;
  /** Component lifecycle status */
  status?: "draft" | "experimental" | "beta" | "stable" | "deprecated";
  /** Version when this component was introduced */
  since?: string;
  /** Version when this component was deprecated */
  deprecatedSince?: string;
  /** Why this component was deprecated and what to use instead */
  deprecatedReason?: string;
  /** Tags for categorization and search */
  tags?: string[];
}

/**
 * Fragment JSON file structure (.fragment.json)
 * Contains enrichment metadata for a component
 */
export interface Fragment {
  /** JSON Schema reference */
  $schema?: string;
  /** Component name (must match the component export name) */
  name: string;
  /** Brief description of the component's purpose */
  description?: string;
  /** Figma design links and mappings */
  figma?: FragmentFigma;
  /** Usage guidelines for AI agents and developers */
  usage?: FragmentUsage;
  /** Accessibility requirements and guidelines */
  accessibility?: FragmentAccessibility;
  /** Relationships to other components */
  related?: FragmentRelated;
  /** Administrative metadata */
  meta?: FragmentMeta;
}

/**
 * Prop entry in the registry
 */
export interface RegistryPropEntry {
  /** TypeScript type (e.g., 'string', 'boolean', enum values) */
  type?: string;
  /** Simplified type category */
  typeKind?: "string" | "number" | "boolean" | "enum" | "object" | "array" | "function" | "node" | "element" | "union" | "unknown";
  /** For enum types, the allowed values */
  options?: string[];
  /** Default value if specified */
  default?: unknown;
  /** Whether this prop is required */
  required?: boolean;
  /** Prop description from JSDoc or TypeScript */
  description?: string;
}

/**
 * Component entry in the registry (simplified - focuses on paths and enrichment)
 */
export interface RegistryComponentEntry {
  /** Relative path to the component source file */
  path: string;
  /** Relative path to the .fragment.json file (if exists) */
  fragmentPath?: string;
  /** Relative path to the .stories.tsx file (if exists) */
  storyPath?: string;
  /** Component category (inferred from directory or fragment) */
  category?: string;
  /** Component lifecycle status (from fragment) */
  status?: "draft" | "experimental" | "beta" | "stable" | "deprecated";
  /** Component description (from fragment or JSDoc) */
  description?: string;
  /** Has human-authored enrichment (fragment file exists with content beyond skeleton) */
  hasEnrichment?: boolean;
  /** Extracted prop definitions - only included if config.registry.includeProps is true */
  props?: Record<string, RegistryPropEntry>;
  /** Named exports from the component file */
  exports?: string[];
  /** Component dependencies (other components used) */
  dependencies?: string[];
  /** Merged fragment enrichment data - only included if config.registry.embedFragments is true */
  fragment?: Fragment;
}

/**
 * Minimal component index (.fragments/index.json)
 * Ultra-light name → path mapping for quick lookups
 */
export interface FragmentIndex {
  /** Schema version */
  version: string;
  /** When this index was generated */
  generatedAt: string;
  /** Simple name → path mapping */
  components: Record<string, string>;
  /** Categories for grouping */
  categories?: Record<string, string[]>;
}

/**
 * Registry file structure (.fragments/registry.json)
 * Component index with resolved paths and optional metadata
 */
export interface FragmentRegistry {
  /** JSON Schema reference */
  $schema?: string;
  /** Schema version */
  version: string;
  /** When this registry was generated */
  generatedAt: string;
  /** Component count for quick reference */
  componentCount: number;
  /** Component index keyed by component name */
  components: Record<string, RegistryComponentEntry>;
  /** Components grouped by category */
  categories?: Record<string, string[]>;
}

/**
 * Context file options for generation
 */
export interface FragmentContextOptions {
  /** Output format */
  format?: "markdown" | "json";
  /** Compact mode - minimal output for token efficiency */
  compact?: boolean;
  /** What to include in the output */
  include?: {
    /** Include prop details (default: true) */
    props?: boolean;
    /** Include code examples (default: false) */
    code?: boolean;
    /** Include related components (default: true) */
    relations?: boolean;
  };
}