/**
 * Lightweight tagged-template rendering — `html`, `css`, `repeat`, `stamp`.
 *
 * Detects signal/function bound values and wraps them in `effect()` so the
 * binding re-fires on dependency change. Static values bypass — see USAGE.md
 * § property-binding-patterns for the eager-evaluation trap.
 */

import type { ReadonlySignal } from './signals.js';

/** Result of an `html\`…\`` call — pass to `stamp()` to mount in a container. */
export interface TemplateResult {
  readonly strings: TemplateStringsArray;
  readonly values: readonly unknown[];
}

/**
 * Tagged template for HTML — returns a `TemplateResult` that `stamp()` mounts.
 *
 * - `attr=${value}` — attribute binding (string-coerced, removed if null/false)
 * - `.prop=${value}` — JS property binding (signal/function = reactive)
 * - `@event=${handler}` — event listener binding
 *
 * @example
 *   html`<button-ui .disabled=${isLoading} @click=${onSave}>Save</button-ui>`
 */
export function html(strings: TemplateStringsArray, ...values: unknown[]): TemplateResult;

/**
 * Tagged template for CSS — returns a `CSSStyleSheet`. Use as `static styles =
 * css\`…\`` on a component or feed to `document.adoptedStyleSheets`.
 *
 * @example
 *   const sheet = css`button { color: red; }`;
 *   document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];
 */
export function css(strings: TemplateStringsArray, ...values: unknown[]): CSSStyleSheet;

/**
 * Mount or update a `TemplateResult` inside a container. Re-running with a
 * different result with the same `strings` reuses the template; different
 * `strings` re-mounts.
 */
export function stamp(result: TemplateResult, container: Element): void;

/**
 * Internal — disposes effects attached to template parts. You won't call this
 * directly unless implementing a custom directive.
 */
export function disposeParts(parts: readonly unknown[]): void;

/**
 * Keyed list directive — minimal-ops re-render of dynamic lists. Reuses DOM
 * elements across re-renders by `key`.
 *
 * @example
 *   html`<ul>${repeat(
 *     items.value,
 *     (item) => item.id,
 *     (item) => html`<li>${item.name}</li>`
 *   )}</ul>`
 */
export function repeat<T>(
  items: readonly T[],
  keyFn: (item: T, index: number) => string | number,
  tplFn: (item: T, index: number) => TemplateResult,
): unknown;

/** Internal symbol — key-map storage on container nodes for `repeat()`. */
export const KEY_MAP: unique symbol;
