zephyr-framework.d.ts

/**
 * Zephyr Framework — TypeScript Declarations
 * @version 0.3.1
 */

// ---------------------------------------------------------------------------
// Component Elements
// ---------------------------------------------------------------------------

/** Base class for all Zephyr components. */
export declare class ZephyrElement extends HTMLElement {
  connectedCallback(): void;
  disconnectedCallback(): void;
  /** Override in subclasses to set up component DOM structure. */
  attachTemplate(): void;
  /** Auto-wires declarative behaviors from data attributes. */
  attachBehaviors(): void;
  /** Wraps a DOM mutation in a View Transition if available. */
  static withTransition(fn: () => void): void;
}

/** Minimal custom element for accordion items. */
export declare class ZAccordionItem extends HTMLElement {}

/** Collapsible accordion using CSS Grid transitions. Dispatches 'toggle' events. */
export declare class ZAccordion extends ZephyrElement {}

/** Modal dialog wrapping native <dialog> with View Transitions. */
export declare class ZModal extends ZephyrElement {
  /** Opens the modal with a View Transition animation. */
  open(): void;
  /** Closes the modal with a View Transition animation. */
  close(): void;
}

/** Tab panel component with keyboard navigation and View Transitions. */
export declare class ZTabs extends ZephyrElement {}

/** Form-associated custom select using ElementInternals. */
export declare class ZSelect extends ZephyrElement {
  static formAssociated: true;
  /** The current selected value. */
  value: string;
}

/** Slide carousel with autoplay and View Transitions. */
export declare class ZCarousel extends ZephyrElement {
  /** Transitions to the next slide. */
  next(): void;
  /** Transitions to the previous slide. */
  prev(): void;
}

/** Toast notification component. */
export declare class ZToast extends ZephyrElement {
  /**
   * Displays a toast message for the given duration.
   * @param message - The message to display
   * @param duration - Duration in milliseconds before auto-hide (default: 3000)
   */
  show(message: string, duration?: number): void;
}

/** Dropdown menu with click-outside handling. */
export declare class ZDropdown extends ZephyrElement {}

/** Filterable combobox with keyboard navigation and form association. */
export declare class ZCombobox extends ZephyrElement {
  static formAssociated: true;
  /** The current selected value. */
  value: string;
}

/** Enhanced date picker wrapping native input[type="date"]. */
export declare class ZDatepicker extends ZephyrElement {
  static formAssociated: true;
  /** The current date value (YYYY-MM-DD format). */
  value: string;
}

/** IntersectionObserver-based infinite scroll container. */
export declare class ZInfiniteScroll extends ZephyrElement {
  /** Call when all data has been loaded to stop observing. */
  complete(): void;
}

/** Drag & drop sortable list using the native HTML Drag and Drop API. */
export declare class ZSortable extends ZephyrElement {}

/** File upload component with drag-and-drop zone and progress display. */
export declare class ZFileUpload extends ZephyrElement {
  /**
   * Updates the progress bar for a specific file.
   * @param index - File index in the list
   * @param percent - Progress percentage (0-100)
   */
  setProgress(index: number, percent: number): void;
}

/** Virtual scrolling list for efficiently rendering large datasets. */
export declare class ZVirtualList extends ZephyrElement {
  /**
   * Sets the data items for the list.
   * @param items - Array of data objects to render
   */
  setItems(items: any[]): void;
  /**
   * Sets the render function that converts a data item to HTML.
   * @param fn - Renderer function returning an HTML string
   */
  setRenderer(fn: (item: any, index: number) => string): void;
}

// ---------------------------------------------------------------------------
// Custom Element Tag Name Map
// ---------------------------------------------------------------------------

declare global {
  interface HTMLElementTagNameMap {
    'z-accordion-item': ZAccordionItem;
    'z-accordion': ZAccordion;
    'z-modal': ZModal;
    'z-tabs': ZTabs;
    'z-select': ZSelect;
    'z-carousel': ZCarousel;
    'z-toast': ZToast;
    'z-dropdown': ZDropdown;
    'z-combobox': ZCombobox;
    'z-datepicker': ZDatepicker;
    'z-infinite-scroll': ZInfiniteScroll;
    'z-sortable': ZSortable;
    'z-file-upload': ZFileUpload;
    'z-virtual-list': ZVirtualList;
    'z-stat': ZStat;
    'z-dashboard-panel': ZDashboardPanel;
    'z-dashboard': ZDashboard;
    'z-data-grid': ZDataGrid;
    'z-chart': ZChart;
  }
}

// ---------------------------------------------------------------------------
// Component Registry Entry
// ---------------------------------------------------------------------------

interface ZephyrComponentDef {
  tag: string;
  slots: string[];
  attributes: string[];
  events: string[];
  methods: string[];
}

// ---------------------------------------------------------------------------
// Agent API Types
// ---------------------------------------------------------------------------

interface ZephyrComponentState {
  tag: string;
  id: string | null;
  state: Record<string, string | true>;
  actions: string[];
}

interface ZephyrComponentDescription extends ZephyrComponentState {
  description: string;
  slots: Record<string, string | null>;
  events: string[];
  methods: string[];
}

interface ZephyrActResult {
  success: boolean;
  error?: string;
  /** Present when a guard intercepts the action. */
  pending?: boolean;
  /** The ID to pass to confirm() or deny(). */
  confirmId?: string;
}

interface ZephyrDenyResult {
  success: boolean;
  denied?: boolean;
  error?: string;
}

interface ZephyrPendingAction {
  confirmId: string;
  selector: string;
  action: string;
  params: Record<string, any> | null;
  timestamp: number;
}

interface ZephyrSetStateResult {
  success: boolean;
  state?: Record<string, string | true>;
  error?: string;
}

interface ZephyrObserverDetail {
  element: Element;
  tag: string;
  attribute: string;
  oldValue: string | null;
  newValue: string | null;
}

interface ZephyrDiffDetail {
  component: string;
  id: string | null;
  property: string;
  from: string | null;
  to: string | null;
  timestamp: number;
}

interface ZephyrRecordedAction {
  selector: string;
  action: string;
  params: Record<string, any> | null;
  timestamp: number;
}

interface ZephyrRecordingHandle {
  /** Stops recording and returns the captured actions. */
  stop(): ZephyrRecordedAction[];
}

interface ZephyrReplayOptions {
  /** Milliseconds between each action (default: 0). Ignored if realtime is true. */
  delay?: number;
  /** If true, uses original timestamps to space out actions. */
  realtime?: boolean;
}

interface ZephyrReplayResult {
  selector: string;
  action: string;
  result: ZephyrActResult;
}

interface ZephyrAgentAPI {
  /** Returns the enriched component schema with descriptions, actions, and examples. */
  getSchema(): Record<string, ZephyrComponentDef & { actions: string[]; description: string }>;

  /**
   * Snapshots the state of all Zephyr components on the page.
   * @param selector - Optional CSS selector to scope the query
   */
  getState(selector?: string): ZephyrComponentState[];

  /**
   * Sets or removes data attributes on a Zephyr component.
   * @param selector - CSS selector for the target element
   * @param attributes - Attributes to set (null/false to remove)
   */
  setState(selector: string, attributes: Record<string, string | boolean | null>): ZephyrSetStateResult;

  /**
   * Returns a structured description of a specific component instance.
   * @param selector - CSS selector for the target element
   */
  describe(selector: string): ZephyrComponentDescription | { error: string };

  /**
   * Performs a high-level action on a Zephyr component.
   * @param selector - CSS selector for the target element
   * @param action - Action name (e.g., 'open', 'close', 'select', 'next')
   * @param params - Action parameters
   */
  act(selector: string, action: string, params?: Record<string, any>): ZephyrActResult;

  /**
   * Observes state attribute changes on all Zephyr components.
   * @param callback - Called with change details on every state mutation
   */
  observe(callback: (detail: ZephyrObserverDetail) => void): void;

  /**
   * Removes an observer callback.
   * @param callback - The callback to remove
   */
  unobserve(callback: (detail: ZephyrObserverDetail) => void): void;

  /**
   * Observes state changes with structured diff objects.
   * @param callback - Called with enriched diff details
   */
  observeDiffs(callback: (diff: ZephyrDiffDetail) => void): void;

  /**
   * Removes a diff observer callback.
   * @param callback - The callback to remove
   */
  unobserveDiffs(callback: (diff: ZephyrDiffDetail) => void): void;

  /**
   * Enables or disables headless mode.
   * @param enabled - true to enable, false to disable, omit to toggle
   * @returns Current headless state
   */
  headless(enabled?: boolean): boolean;

  /**
   * Starts recording agent actions.
   * @returns Recording handle with stop() method
   * @throws If a recording is already in progress
   */
  record(): ZephyrRecordingHandle;

  /**
   * Replays a recorded sequence of agent actions.
   * @param recording - Array of recorded actions
   * @param options - Replay options
   * @returns Resolves with results of each action
   */
  replay(recording: ZephyrRecordedAction[], options?: ZephyrReplayOptions): Promise<ZephyrReplayResult[]>;

  /**
   * Locks a component so only the specified agent can act on it.
   * @param selector - CSS selector for the component
   * @param agentId - Unique identifier for the locking agent
   */
  lock(selector: string, agentId: string): ZephyrActResult;

  /**
   * Unlocks a component.
   * @param selector - CSS selector for the component
   * @param agentId - The agent requesting the unlock
   * @param options - Unlock options
   */
  unlock(selector: string, agentId: string, options?: { force?: boolean }): ZephyrActResult;

  /**
   * Returns all currently locked components and their owning agents.
   */
  locks(): Array<{ selector: string; agentId: string }>;

  /**
   * Registers a guard requiring confirmation before executing specified actions.
   * @param selector - CSS selector, tag name, or '*' for all components
   * @param actions - Array of action names to guard, or '*' for all actions
   * @param handler - Optional function returning false to bypass the guard
   * @param options - Options: { timeout: number } (default 30000ms auto-deny)
   */
  guard(
    selector: string,
    actions: string[] | '*',
    handler?: (selector: string, action: string, params?: Record<string, any>) => boolean,
    options?: { timeout?: number }
  ): { success: true };

  /** Removes a guard and cleans up related pending confirmations. */
  unguard(selector: string): { success: true };

  /** Confirms a pending guarded action, executing it immediately. */
  confirm(confirmId: string): ZephyrActResult;

  /** Denies a pending guarded action, discarding it without executing. */
  deny(confirmId: string): ZephyrDenyResult;

  /** Returns all pending guarded actions awaiting confirmation. */
  guarded(): ZephyrPendingAction[];

  /** Generates a markdown prompt describing all Zephyr components on the page. */
  getPrompt(): string;

  /** Annotates all Zephyr components with data-z-actions for agent discovery. */
  annotate(): void;

  /**
   * Safely creates and inserts a Zephyr component into the DOM.
   * Uses DOM manipulation (no innerHTML) with a tag whitelist.
   */
  render(containerSelector: string, spec: ZephyrRenderSpec): ZephyrRenderResult;

  /**
   * Composes a complete dashboard layout from a declarative spec.
   * Sugar over render() for dashboard/panel patterns.
   */
  compose(containerSelector: string, layout: ZephyrComposeLayout): ZephyrComposeResult;

  /**
   * Auto-selects and renders the best Zephyr component for the given data.
   * Analyzes data shape: time series → z-chart, stat objects → z-stat cards,
   * simple arrays → z-sortable/z-virtual-list, object arrays → z-data-grid.
   * Clears the container before rendering.
   * @param data - Any data: time series array, stat array/object, string list, or object array
   * @param containerSelector - CSS selector for the target container
   * @param options - Optional hint and title
   */
  visualize(data: any, containerSelector: string, options?: ZephyrVisualizeOptions): ZephyrVisualizeResult;
}

// ---------------------------------------------------------------------------
// Visualize API Types
// ---------------------------------------------------------------------------

interface ZephyrVisualizeOptions {
  /** Override auto-detection: 'chart', 'stats', 'list', or 'table'. */
  hint?: 'chart' | 'stats' | 'list' | 'table';
  /** Title for chart visualizations. */
  title?: string;
}

interface ZephyrVisualizeResult {
  success: boolean;
  /** The component tag that was rendered (e.g., 'z-chart', 'z-stat'). */
  component?: string;
  selector?: string;
  error?: string;
}

// ---------------------------------------------------------------------------
// Render API Types
// ---------------------------------------------------------------------------

interface ZephyrRenderSpec {
  tag: string;
  id?: string;
  attributes?: Record<string, string>;
  text?: string;
  children?: ZephyrRenderSpec[];
  setup?: { method: string; params?: any };
  position?: number;
}

interface ZephyrRenderResult {
  success: boolean;
  selector?: string;
  error?: string;
  warning?: string;
}

interface ZephyrComposePanelSpec {
  id: string;
  colspan?: number;
  rowspan?: number;
  title?: string;
  component?: ZephyrRenderSpec;
}

interface ZephyrComposeLayout {
  tag?: string;
  id?: string;
  attributes?: Record<string, string>;
  panels: ZephyrComposePanelSpec[];
}

interface ZephyrComposeResult extends ZephyrRenderResult {
  panels?: string[];
}

// ---------------------------------------------------------------------------
// Dashboard Add-on Components (zephyr-dashboard.js)
// ---------------------------------------------------------------------------

/** KPI stat card with label, value, and trend indicator. */
export declare class ZStat extends ZephyrElement {
  static observedAttributes: string[];
  setValue(value?: string, trend?: string, trendValue?: string): void;
}

/** Dashboard panel container. */
export declare class ZDashboardPanel extends HTMLElement {}

/** Responsive grid layout container for dashboard panels. */
export declare class ZDashboard extends ZephyrElement {
  addPanel(config: { id: string; colspan?: number; rowspan?: number; title?: string; position?: number }): ZDashboardPanel;
  removePanel(id: string): void;
  movePanel(id: string, position: number): void;
}

/** Sortable, filterable data table. */
export declare class ZDataGrid extends ZephyrElement {
  setColumns(columns: Array<{ key: string; label: string; sortable?: boolean; width?: string; align?: string }>): void;
  setRows(rows: Array<Record<string, any>>): void;
  sort(column: string, direction?: string): void;
  filter(query: string): void;
}

/** Chart component wrapping lightweight-charts. */
export declare class ZChart extends ZephyrElement {
  setType(type: 'line' | 'candlestick' | 'area' | 'histogram'): void;
  setData(data: Array<{ time: number; value?: number; open?: number; high?: number; low?: number; close?: number }>): void;
  addPoint(point: { time: number; value?: number; open?: number; high?: number; low?: number; close?: number }): void;
  addSeries(config: { type?: string; data?: any[]; options?: any }): any;
  setTimeRange(from: number, to: number): void;
}

// ---------------------------------------------------------------------------
// Global Zephyr API
// ---------------------------------------------------------------------------

interface ZephyrAPI {
  /**
   * Returns a modal element by ID.
   * @param id - The modal element's ID attribute
   */
  modal(id: string): ZModal | null;

  /**
   * Displays a toast notification.
   * @param message - The message to display
   * @param duration - Duration in milliseconds (default: 3000)
   */
  toast(message: string, duration?: number): void;

  /** Registry of all Zephyr components and their capabilities. */
  components: Record<string, ZephyrComponentDef>;

  /** Structured interface for AI agents and LLMs. */
  agent: ZephyrAgentAPI;
}

declare global {
  interface Window {
    Zephyr: ZephyrAPI;
  }

  /** Global Zephyr API. */
  var Zephyr: ZephyrAPI;
}

export {};