/*!
 * Mode List — TypeScript Definitions
 * MIT License — Copyright (c) 2025 Silvio Corigliano
 */

/** A reactive array source (atom protocol over `T[]`). */
export interface ListSource<T> {
  get(): T[];
  sub(fn: (v: T[]) => void, runNow?: boolean): () => void;
}

/** What `mount` returns: at minimum an element; anything else is your instance state. */
export interface ListInstance {
  el: Element;
  [key: string]: unknown;
}

export interface ListConfig<T> {
  /** Reactive array to render. Must speak the atom protocol. */
  source: ListSource<T>;
  /** Stable identity per item — drives keyed reconciliation. */
  key: (item: T, i: number) => unknown;
  /** Create a node for a new item. Must return `{ el, ... }`. */
  mount: (item: T, i: number) => ListInstance;
  /** Update an existing instance in place (optional). */
  update?: (inst: ListInstance, next: T, prev: T) => void;
  /** Called when an item leaves the list (optional). */
  unmount?: (inst: ListInstance, data: T) => void;
  /** Called after every render with the current array (optional). */
  empty?: (host: Element, arr: T[]) => void;
}

/** Mount a keyed list into `host`; returns a stop function. */
export function list<T>(host: Element, cfg: ListConfig<T>): () => void;

/** Install the `list` helper onto a µ core, composing with any previous extension. */
export function register(core: unknown): boolean;