// src/serialization/IComponentSchema.ts

import type { IMethodSchema } from './IMethodSchema';
import type { IEventSchema } from './IEventSchema';
import type { IHandlerSchema } from './IHandlerSchema';
import type { ITrackSchema } from './ITrackSchema';

/**
 * Component schema - the canonical representation of a Matrix component.
 *
 * This is the "quoted form" (data) that can be:
 * - Serialized to HTML, JSON, S-expressions
 * - Evaluated by SchemaEvaluator into running components
 * - Introspected and manipulated programmatically
 *
 * Vision 45: IComponentSchema is to Matrix what S-expressions are to LISP.
 */
export interface IComponentSchema {
  /** Component name (used for display and mount derivation) */
  name: string;

  /** Optional explicit ID (used for mount derivation instead of name) */
  id?: string;

  /** Optional explicit mount path (overrides id/name derivation) */
  mount?: string;

  /** Commands this component accepts */
  accepts: Record<string, IMethodSchema>;

  /** Events this component emits */
  emits: Record<string, IEventSchema>;

  /** Child component schemas */
  children?: IComponentSchema[];

  /** Configuration options */
  config?: Record<string, unknown>;

  // ═══════════════════════════════════════════════════════════════════════════
  // Dynamic Component Properties (Vision 45 §4)
  // ═══════════════════════════════════════════════════════════════════════════

  /** Handler definitions (code as data) */
  handlers?: Record<string, IHandlerSchema | string>;

  /** Initial state values */
  state?: Record<string, unknown>;

  /** Registered component type to instantiate */
  componentType?: string;

  // ═══════════════════════════════════════════════════════════════════════════
  // Shell/Template Properties
  // ═══════════════════════════════════════════════════════════════════════════

  /** HTML template for shell rendering */
  template?: string;

  /** CSS styles for shell */
  styles?: string;

  /** Slot to place this component in (when nested) */
  slot?: string;

  // ═══════════════════════════════════════════════════════════════════════════
  // Reactive Bindings (Vision 45 §6)
  // ═══════════════════════════════════════════════════════════════════════════

  /** Track subscriptions to other components' events */
  tracks?: ITrackSchema[];

  /** Event bindings (shorthand for tracks) */
  bindings?: Record<string, unknown>;

  // ═══════════════════════════════════════════════════════════════════════════
  // Lifecycle Configuration
  // ═══════════════════════════════════════════════════════════════════════════

  /** When the component is considered ready */
  readyMode?: 'immediate' | 'children' | 'custom';

  // ═══════════════════════════════════════════════════════════════════════════
  // Metadata
  // ═══════════════════════════════════════════════════════════════════════════

  /** Source format this schema was parsed from (for round-tripping) */
  sourceFormat?: 'html' | 'json' | 'shadowlisp' | 'sexpr' | 'fluent' | 'topics';
}

// Re-export handler and track schemas for convenience
export type { IHandlerSchema } from './IHandlerSchema';
export type { ITrackSchema } from './ITrackSchema';
