streetui 1.7.0 → 1.9.0

package/dist/{compile-Cte0nf06.d.cts → compile-DqsMQVJk.d.cts}

@@ -7,7 +7,7 @@
  * (`streetui --version`) — the consolidated test-suite pins all three to the
  * same coordinated release so they can never silently drift apart.
  */
-declare const VERSION = "1.7.0";
+declare const VERSION = "1.9.0";
 
 /**
  * StreetUI reactive signals — framework-owned reactivity, no external libraries.
@@ -341,6 +341,195 @@ interface SerializedGraph {
     readonly root: SerializedNode;
 }
 
+/**
+ * First-class StreetUI-native components (§3–§9).
+ *
+ * A component is a *reusable unit that owns its own local state and lifecycle*.
+ * It is NOT a virtual-DOM element, a second reactive system, or a second
+ * renderer. It compiles into the EXISTING pipeline: `container.component(...)`
+ * creates a reserved `'component'` GraphNode (already a `SemanticNodeType`,
+ * already mapped to `<div>`), runs the component's `setup` synchronously during
+ * the same build-time descent every other builder uses, and routes any cleanups
+ * the setup registers into the node's `NodeInstance` at mount (so they run,
+ * children-first, when the component leaves the graph).
+ *
+ * Design (derived from the existing DSL architecture, not copied from React/Vue):
+ *
+ *   const UserCard = component<{ name: Signal<string> }>((props, ctx) => {
+ *     // ── setup: runs ONCE per instance, at build time ──
+ *     const open = signal(false);
+ *     ctx.effect(() => { ... });            // auto-disposed on unmount
+ *     ctx.onCleanup(() => { ... });         // explicit teardown hook
+ *     // ── render: fills the component's own container scope ──
+ *     return (content) => {
+ *       content.text(props.name);           // fine-grained: signal prop, no re-setup
+ *       content.when(open, (c) => c.text('expanded'));
+ *       ctx.renderChildren(content);        // where slotted children go (§6)
+ *     };
+ *   }, { name: 'UserCard' });
+ *
+ *   page.component('card-1', UserCard, { name }, (slot) => slot.text('child'));
+ *
+ * Props are ordinary typed values (§5 — typing is a TypeScript concern, no
+ * runtime schema). Passing a `Signal<T>` prop and binding it in the render body
+ * gives fine-grained updates (§13) WITHOUT re-running `setup`: only the bound
+ * node mutates when the signal changes. `setup` re-runs only when the component
+ * is genuinely rebuilt (removed + re-created by a keyed list / conditional),
+ * at which point the previous instance is disposed first — so cleanup stays
+ * correct.
+ */
+
+/**
+ * The render half of a component: fills the component's own container scope.
+ * Returned by `setup` so that per-instance state created in `setup` is captured
+ * by closure and the render body can read it.
+ */
+type ComponentRender = (content: ContainerDSL) => void;
+/**
+ * Lifecycle + composition surface handed to a component's `setup`. Local
+ * reactive state is created with the EXISTING `signal`/`derived`/`effect`/
+ * `batch` primitives (§8) — `ctx` only adds ownership: anything registered here
+ * is torn down automatically when the component leaves the graph (§9).
+ */
+interface ComponentContext {
+    /** This instance's stable identity key (the `key` passed at the call site). */
+    readonly key: string;
+    /**
+     * Register a teardown callback. Runs when the component unmounts (children
+     * first, then this — mirroring `NodeInstance.dispose`). Use for resources,
+     * `form.dispose`, subscriptions, timers, etc.
+     */
+    onCleanup(fn: () => void): void;
+    /**
+     * Run a reactive effect owned by this component. Wraps the framework's
+     * `effect()`; the returned unsubscribe is auto-tracked and disposed on
+     * unmount, so component effects never leak (the pain point the audit ranked
+     * #1). The effect may itself return a cleanup, exactly like `effect()`.
+     */
+    effect(fn: () => void | (() => void)): void;
+    /**
+     * Render the caller-supplied children into `content` at this point (§6 native
+     * child composition / slots). No-op when the call site passed no children.
+     * Call it wherever the component wants its slotted content to appear.
+     */
+    renderChildren(content: ContainerDSL): void;
+}
+/**
+ * A component's setup function: receives typed props and the lifecycle context,
+ * creates any local state, and returns the render function. Runs synchronously
+ * during the build-time descent (like `errorBoundary`'s callback), so it must be
+ * SSR-safe — on the server it runs at render time and its cleanups run when the
+ * SSR root is disposed.
+ */
+type ComponentSetup<P> = (props: P, ctx: ComponentContext) => ComponentRender;
+/**
+ * The opaque, reusable definition produced by `component(...)`. Carries the
+ * `setup` and an inspectable `name`; the brand lets the builder method (and
+ * DevTools) recognise a definition at runtime without a class.
+ */
+interface ComponentDefinition<P> {
+    readonly __streetui_component: true;
+    readonly name: string;
+    readonly setup: ComponentSetup<P>;
+}
+/**
+ * Define a reusable component. Returns a `ComponentDefinition` you render with
+ * `container.component(key, def, props, children?)`. This is a pure factory — it
+ * builds no graph and runs no `setup`; instantiation happens per call site.
+ *
+ * @param setup  Runs once per instance: create local state, return the render fn.
+ * @param options.name  Human-readable name for DevTools/`data-streetui-component`.
+ */
+declare function component<P = Record<string, never>>(setup: ComponentSetup<P>, options?: {
+    name?: string;
+}): ComponentDefinition<P>;
+/** Runtime guard: is `value` a component definition? */
+declare function isComponentDefinition(value: unknown): value is ComponentDefinition<unknown>;
+
+/**
+ * Transition configuration (§2, §4).
+ *
+ * A `TransitionConfig` is a pure, declarative description of a CSS class-based
+ * enter/leave transition — the engine choice for this milestone. It contains NO
+ * DOM references, NO timers and NO browser-only APIs, so it is safe to build on
+ * the server (where it is simply ignored — see the renderer's SSR guard) and to
+ * carry on a graph handler (`__transition__<nodeId>`) alongside the existing
+ * `__overlay__`/`__component__` descriptors.
+ *
+ * The class model follows the widely-understood enter/leave convention:
+ *
+ *   enter:  [enterActive (+ enter) whole phase] · enterFrom (start) → enterTo (end)
+ *   leave:  [leaveActive (+ leave) whole phase] · leaveFrom (start) → leaveTo (end)
+ *
+ * `name` is a shorthand that expands to `${name}-enter-from`,
+ * `${name}-enter-active`, `${name}-enter-to` and the leave equivalents; explicit
+ * class fields override the derived ones. Because the classes are just strings,
+ * SSR output is deterministic (no class is applied on the server at all — the
+ * controller is browser-only), satisfying §4/§21.
+ */
+interface TransitionConfig {
+    /** Shorthand base: expands to `${name}-enter-from`, `${name}-enter-active`, … */
+    readonly name?: string;
+    /** Class(es) present for the whole enter phase (in addition to `enterActive`). */
+    readonly enter?: string;
+    /** Class(es) applied at the start of enter, removed on the next frame. */
+    readonly enterFrom?: string;
+    /** Class(es) present for the whole enter phase (where the CSS `transition` lives). */
+    readonly enterActive?: string;
+    /** Class(es) added on the next frame, removed when enter completes. */
+    readonly enterTo?: string;
+    /** Class(es) present for the whole leave phase (in addition to `leaveActive`). */
+    readonly leave?: string;
+    /** Class(es) applied at the start of leave, removed on the next frame. */
+    readonly leaveFrom?: string;
+    /** Class(es) present for the whole leave phase (where the CSS `transition` lives). */
+    readonly leaveActive?: string;
+    /** Class(es) added on the next frame, removed when leave completes. */
+    readonly leaveTo?: string;
+    /**
+     * Also animate the very first appearance (initial mount). Hydration never
+     * animates appear (the DOM is already present and correct); this only affects
+     * fresh browser mounts. Defaults to false.
+     */
+    readonly appear?: boolean;
+    /**
+     * Fallback completion timeout in milliseconds. A transition normally completes
+     * on the element's `transitionend`/`animationend`. This timeout is the safety
+     * net for (a) transitions that fire no such event and (b) test DOMs like
+     * happy-dom that dispatch no transition events at all — making tests
+     * deterministic without a real browser (§24). Defaults to 1000. Use a small
+     * value (or 0 → next macrotask) in tests.
+     */
+    readonly duration?: number;
+}
+/**
+ * The resolved, ready-to-apply form of a {@link TransitionConfig}: each phase's
+ * classes are pre-split into arrays so the controller applies/removes them with
+ * no per-run string parsing. Produced once by {@link resolveTransition} at wire
+ * time (browser only).
+ */
+interface ResolvedTransition {
+    /** enter classes present for the whole phase (base `enter` + `enterActive`). */
+    readonly enterActive: readonly string[];
+    /** enter start classes (removed next frame). */
+    readonly enterFrom: readonly string[];
+    /** enter end classes (added next frame). */
+    readonly enterTo: readonly string[];
+    readonly leaveActive: readonly string[];
+    readonly leaveFrom: readonly string[];
+    readonly leaveTo: readonly string[];
+    readonly appear: boolean;
+    readonly duration: number;
+}
+/**
+ * Resolve a {@link TransitionConfig} into applied class arrays. The `name`
+ * shorthand supplies defaults; any explicit field overrides the derived class
+ * for that phase-slot (still merged with `enter`/`leave` base classes).
+ */
+declare function resolveTransition(config: TransitionConfig): ResolvedTransition;
+/** Runtime brand check for a transition descriptor value. */
+declare function isTransitionConfig(value: unknown): value is TransitionConfig;
+
 /**
  * StreetUI DSL type system.
  * All builder callbacks and option shapes live here.
@@ -387,6 +576,14 @@ interface A11yOptions {
     readonly ariaRequired?: boolean;
     /** aria-modal — mark a dialog as modal (content outside is inert to AT). */
     readonly ariaModal?: boolean;
+    /** aria-owns — id(s) of elements owned by this one when the DOM can't express it. */
+    readonly ariaOwns?: string;
+    /** aria-activedescendant — id of the active option in a composite widget (menu/listbox/combobox). */
+    readonly ariaActiveDescendant?: string;
+    /** aria-haspopup — the element opens a popup ('menu' | 'listbox' | 'dialog' | 'grid' | 'tree' | true). */
+    readonly ariaHasPopup?: boolean | 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog';
+    /** aria-selected — selection state within a composite widget. */
+    readonly ariaSelected?: boolean;
 }
 interface TextOptions extends A11yOptions {
     readonly class?: string;
@@ -450,6 +647,15 @@ interface ContainerOptions extends A11yOptions {
     readonly class?: string;
     readonly id?: string;
     readonly key?: string;
+    /**
+     * Enter/leave transition for this element (§2). CSS class-based and
+     * browser-only: on the server it is ignored (deterministic SSR output). The
+     * enter animation runs when the element is added by a reactive `when`/`listOf`
+     * change (or on initial mount when `appear` is set); the leave animation runs
+     * before the element is removed and disposed — the reconciler defers teardown
+     * until the transition completes.
+     */
+    readonly transition?: TransitionConfig;
 }
 interface SectionOptions extends ContainerOptions {
 }
@@ -457,6 +663,21 @@ interface FormOptions extends ContainerOptions {
     readonly onSubmit?: (e: Event) => void;
 }
 interface ListOptions extends ContainerOptions {
+    /**
+     * Enter/leave transition applied to each list item (§7). Preserves keyed
+     * identity: reordering reuses items (no leave/enter), append/prepend enter,
+     * remove leaves before disposal, and a removed key that reappears mid-leave is
+     * reclaimed (leave→enter). `transition` (inherited) applies to the list
+     * container itself; `itemTransition` applies to its rows.
+     */
+    readonly itemTransition?: TransitionConfig;
+}
+/** Options for `when()` (§2 conditional transitions). */
+interface WhenOptions {
+    /** Transition applied to the active branch as it mounts/unmounts. */
+    readonly transition?: TransitionConfig;
+    /** Also animate the branch present on the initial mount (appear). */
+    readonly appear?: boolean;
 }
 /** Options for a plain portal (mount children into `document.body`). */
 interface PortalOptions extends ContainerOptions {
@@ -529,7 +750,7 @@ interface ContainerDSL extends ContentDSL {
      * renders while the condition is false. Compiles into the same reactive
      * reconciliation machinery as `listOf` — there is no separate render path.
      */
-    when(condition: Bindable<boolean>, builder: ContainerBuilder, elseBuilder?: ContainerBuilder): void;
+    when(condition: Bindable<boolean>, builder: ContainerBuilder, elseBuilder?: ContainerBuilder, options?: WhenOptions): void;
     /**
      * Render `builder`, but swap to `options.fallback` when the boundary enters an
      * error state. A boundary enters that state when (a) any observed `source`
@@ -577,6 +798,18 @@ interface ContainerDSL extends ContentDSL {
      * `aria-live="polite"`. Non-modal and never steals focus; no Escape handling.
      */
     toast(key: string, options: OverlayOptions, builder: ContainerBuilder): void;
+    /**
+     * Instantiate a reusable `component()` at this position (§3–§9). Creates a
+     * `'component'` node (rendered as a `<div>` wrapper), runs the definition's
+     * `setup(props, ctx)` synchronously to obtain its render function, and fills
+     * the component's own container scope with it. Any `ctx.effect`/`ctx.onCleanup`
+     * registered by the setup is torn down automatically when the component leaves
+     * the graph. `props` are strongly typed by the definition's generic; pass
+     * `Signal` props for fine-grained updates that do NOT re-run `setup` (§13).
+     * The optional `children` builder is rendered wherever the component calls
+     * `ctx.renderChildren` (§6 native child composition).
+     */
+    component<P>(key: string, def: ComponentDefinition<P>, props: P, children?: ContainerBuilder): void;
 }
 interface SectionDSL extends ContainerDSL {
 }
@@ -636,7 +869,7 @@ declare class ContainerBuilderBase extends ContentBuilderBase implements Contain
     list(key: string, builder: ListBuilder, options?: ListOptions): void;
     listOf<T>(key: string, items: Signal<T[]> | ReadonlySignal<T[]>, renderItem: (item: T, index: number, content: ContentDSL) => void, options?: ListOptions): void;
     form(key: string, builder: FormBuilder, options?: FormOptions): void;
-    when(condition: Bindable<boolean>, builder: ContainerBuilder, elseBuilder?: ContainerBuilder): void;
+    when(condition: Bindable<boolean>, builder: ContainerBuilder, elseBuilder?: ContainerBuilder, options?: WhenOptions): void;
     errorBoundary(id: string, builder: ContainerBuilder, options: ErrorBoundaryOptions): void;
     portal(key: string, builder: ContainerBuilder, options?: PortalOptions): void;
     /**
@@ -653,6 +886,24 @@ declare class ContainerBuilderBase extends ContentBuilderBase implements Contain
     tooltip(key: string, options: OverlayOptions, builder: ContainerBuilder): void;
     dropdown(key: string, options: OverlayOptions, builder: ContainerBuilder): void;
     toast(key: string, options: OverlayOptions, builder: ContainerBuilder): void;
+    /**
+     * Instantiate a reusable component (§3–§9). Creates a `'component'` node
+     * (rendered as a `<div>` wrapper — preserves the one-node/one-element
+     * positional-hydration invariant), then runs `def.setup(props, ctx)`
+     * synchronously to obtain the render function and fills the component's own
+     * container scope with it — structurally identical to `container`/
+     * `errorBoundary`. Cleanups the setup registers via `ctx.effect`/
+     * `ctx.onCleanup` are collected into a closure and exposed to the renderer
+     * through a `__component__<id>` handler (mirroring `__overlay__`); the mount/
+     * hydrate paths read it and route each into `NodeInstance.trackCleanup`, so
+     * teardown runs (children-first) when the component leaves the graph.
+     *
+     * `setup` runs once per instance here at build time. When this component sits
+     * inside a keyed list / conditional, a rebuild disposes the old instance
+     * (running its cleanups + pruning its `__component__` entry) and re-runs this
+     * method for the new node — so re-invocation is safe and leak-free.
+     */
+    component<P>(key: string, def: ComponentDefinition<P>, props: P, children?: ContainerBuilder): void;
 }
 declare class SectionBuilderImpl extends ContainerBuilderBase implements SectionDSL {
 }
@@ -745,4 +996,4 @@ declare function compile(app: StreetApp, options?: CompileOptions): CompiledAppl
  */
 declare function compileGraph(graph: ApplicationGraph, options?: CompileOptions): CompiledApplication;
 
-export { type ListDSL as $, type ApplicationId as A, BaseNode as B, type CompiledApplication as C, DiagnosticCollector as D, type ErrorBoundaryOptions as E, type ErrorFallbackBuilder as F, GraphNode as G, type ErrorSource as H, type EventDescriptor as I, type FormBuilder as J, FormBuilderImpl as K, type FormDSL as L, type FormOptions as M, type GraphNodeData as N, type HandlerFn as O, type PageDSL as P, type HeadingOptions as Q, type ReadonlySignal as R, StreetApp as S, type ImageOptions as T, type Unsubscribe as U, VERSION as V, type InputOptions as W, type InputOptionsBase as X, type LinkOptions as Y, type ListBuilder as Z, ListBuilderImpl as _, Signal as a, type ListOptions as a0, type ListPlanEntry as a1, type NodeId as a2, type NodeMetadata as a3, type OverlayOptions as a4, type PageBuilder as a5, PageBuilderImpl as a6, type PortalOptions as a7, type PropValue as a8, type Props as a9, reactiveListItemSignature as aA, resetIdCounter as aB, signal as aC, signalKind as aD, streetui as aE, type ReactiveConsumer as aa, type ReactiveSource as ab, type SectionBuilder as ac, SectionBuilderImpl as ad, type SectionDSL as ae, type SectionOptions as af, type SerializedGraph as ag, type SerializedNode as ah, type StateRef as ai, type StreetUI as aj, type TextOptions as ak, type TextValue as al, batch as am, compile as an, compileGraph as ao, createNodeId as ap, derived as aq, effect as ar, formatDiagnostic as as, generateApplicationId as at, generateNodeId as au, isBatching as av, nextId as aw, nodeIdPrefix as ax, observerCount as ay, reactiveListItemKey as az, type Subscriber as b, ApplicationGraph as c, type SemanticNodeType as d, type ContainerDSL as e, type SignalKind as f, type A11yOptions as g, AppBuilder as h, type AppDSL as i, type AppOptions as j, type ApplicationGraphOptions as k, type Bindable as l, type BindableText as m, type BoundInputOptions as n, type ButtonOptions as o, type CompileOptions as p, type ContainerBuilder as q, ContainerBuilderImpl as r, type ContainerOptions as s, type ContentDSL as t, type ControlledInputOptions as u, DerivedSignal as v, type Diagnostic as w, DiagnosticError as x, type DiagnosticLocation as y, type DiagnosticSeverity as z };
+export { type InputOptions as $, type ApplicationId as A, BaseNode as B, type CompiledApplication as C, DiagnosticCollector as D, type Diagnostic as E, DiagnosticError as F, GraphNode as G, type DiagnosticLocation as H, type DiagnosticSeverity as I, type ErrorBoundaryOptions as J, type ErrorFallbackBuilder as K, type ErrorSource as L, type EventDescriptor as M, type FormBuilder as N, FormBuilderImpl as O, type PageDSL as P, type FormDSL as Q, type ReadonlySignal as R, StreetApp as S, type TransitionConfig as T, type Unsubscribe as U, VERSION as V, type FormOptions as W, type GraphNodeData as X, type HandlerFn as Y, type HeadingOptions as Z, type ImageOptions as _, type ComponentDefinition as a, type InputOptionsBase as a0, type LinkOptions as a1, type ListBuilder as a2, ListBuilderImpl as a3, type ListDSL as a4, type ListOptions as a5, type ListPlanEntry as a6, type NodeId as a7, type NodeMetadata as a8, type OverlayOptions as a9, formatDiagnostic as aA, generateApplicationId as aB, generateNodeId as aC, isBatching as aD, isComponentDefinition as aE, isTransitionConfig as aF, nextId as aG, nodeIdPrefix as aH, observerCount as aI, reactiveListItemKey as aJ, reactiveListItemSignature as aK, resetIdCounter as aL, resolveTransition as aM, signal as aN, signalKind as aO, streetui as aP, type PageBuilder as aa, PageBuilderImpl as ab, type PortalOptions as ac, type PropValue as ad, type Props as ae, type ReactiveConsumer as af, type ReactiveSource as ag, type ResolvedTransition as ah, type SectionBuilder as ai, SectionBuilderImpl as aj, type SectionDSL as ak, type SectionOptions as al, type SerializedGraph as am, type SerializedNode as an, type StateRef as ao, type StreetUI as ap, type TextOptions as aq, type TextValue as ar, type WhenOptions as as, batch as at, compile as au, compileGraph as av, component as aw, createNodeId as ax, derived as ay, effect as az, type ContainerBuilder as b, Signal as c, type Subscriber as d, ApplicationGraph as e, type SemanticNodeType as f, type ContainerDSL as g, type SignalKind as h, type A11yOptions as i, AppBuilder as j, type AppDSL as k, type AppOptions as l, type ApplicationGraphOptions as m, type Bindable as n, type BindableText as o, type BoundInputOptions as p, type ButtonOptions as q, type CompileOptions as r, type ComponentContext as s, type ComponentRender as t, type ComponentSetup as u, ContainerBuilderImpl as v, type ContainerOptions as w, type ContentDSL as x, type ControlledInputOptions as y, DerivedSignal as z };