@vertz/ui 0.2.23 → 0.2.25

package/dist/src/internals.d.ts

@@ -142,7 +142,12 @@ declare const KEYWORD_MAP: Record<string, CSSDeclarationEntry[]>;
 declare const DISPLAY_MAP: Record<string, string>;
 /** Spacing scale: number -> rem. 1=0.25rem, 2=0.5rem, 4=1rem, 8=2rem, etc. */
 declare const SPACING_SCALE: Record<string, string>;
-/** Border radius scale — matches Tailwind v4 / shadcn. */
+/**
+* Border radius scale — derived from the `--radius` CSS custom property.
+*
+* All levels (except none/full) are proportional to `--radius` (default 0.375rem).
+* Changing `--radius` on a theme element scales every component's border-radius.
+*/
 declare const RADIUS_SCALE: Record<string, string>;
 /** Shadow scale. */
 declare const SHADOW_SCALE: Record<string, string>;
@@ -382,6 +387,10 @@ interface DisposableText extends Text {
 * Returns a Text node with a `dispose` property for cleanup.
 */
 declare function __text(fn: () => string): DisposableText;
+/** A Node that also carries a dispose function for cleanup. */
+interface DisposableChild extends Node {
+	dispose: DisposeFn;
+}
 /**
 * Create a reactive child node that updates when dependencies change.
 * Unlike __text(), this handles both Node values (appended directly)
@@ -390,11 +399,12 @@ declare function __text(fn: () => string): DisposableText;
 * This prevents HTMLElements from being stringified to "[object HTMLElement]"
 * when used as JSX expression children like {someElement}.
 *
-* Returns a wrapper element with `display: contents` and a `dispose` property.
+* Uses a comment anchor (<!--child-->) with sibling-based content management.
+* Content nodes are inserted after the anchor and tracked for cleanup.
+* Returns a DocumentFragment (CSR) or the claimed comment (hydration),
+* with a `dispose` property for lifecycle management.
 */
-declare function __child(fn: () => Node | string | number | boolean | null | undefined): HTMLElement & {
-	dispose: DisposeFn;
-};
+declare function __child(fn: () => Node | string | number | boolean | null | undefined): DisposableChild;
 /**
 * Insert a static (non-reactive) child value into a parent node.
 * This is used for static JSX expression children to avoid the performance
@@ -443,6 +453,11 @@ declare function __exitChildren(): void;
 * Bind an event handler to an element.
 * Returns a cleanup function to remove the listener.
 *
+* Registers the cleanup with the current disposal scope (if any) so that
+* event listeners are automatically removed when the owning component or
+* dialog is unmounted. Without this, listeners on dynamically-mounted
+* elements (e.g., forms inside useDialogStack dialogs) would leak.
+*
 * Compiler output target for event bindings (onClick, onInput, etc.).
 */
 declare function __on(el: HTMLElement, event: string, handler: EventListener): () => void;
@@ -475,11 +490,64 @@ declare function clearChildren(container: Node): void;
 * @param items - A signal or getter function containing the array of items.
 *   The compiler generates `() => signal.value` as a getter; the runtime
 *   also accepts a raw Signal for direct use in tests.
-* @param keyFn - Extracts a unique key from each item (receives item and index)
+* @param keyFn - Extracts a unique key from each item (receives item and index).
+*   Pass `null` for unkeyed lists — triggers full-replacement mode (safe but slower).
 * @param renderFn - Creates a DOM node for an item (called once per key)
 * @returns A dispose function to stop the reactive list reconciliation
 */
-declare function __list<T>(container: HTMLElement, items: Signal<T[]> | (() => T[]), keyFn: (item: T, index: number) => string | number, renderFn: (item: T) => Node): DisposeFn;
+declare function __list<T>(container: HTMLElement, items: Signal<T[]> | (() => T[]), keyFn: ((item: T, index: number) => string | number) | null, renderFn: (item: T) => Node): DisposeFn;
+/**
+* Lifecycle hooks for list animation (enter/exit/reorder).
+*
+* Provided by `<List animate>` via ListAnimationContext.
+* Consumed by `__listValue()` during reconciliation.
+*/
+interface ListAnimationHooks {
+	/** Called before reconciliation starts. Use to snapshot element rects for FLIP. */
+	onBeforeReconcile: () => void;
+	/** Called after reconciliation finishes. Use to play FLIP animations. */
+	onAfterReconcile: () => void;
+	/** Called when a new item enters (after first render). */
+	onItemEnter: (node: Node, key: string | number) => void;
+	/** Called when an item exits. Must call `done()` when animation finishes so the node can be removed. */
+	onItemExit: (node: Node, key: string | number, done: () => void) => void;
+}
+/**
+* Context for list animation hooks.
+*
+* When provided, `__listValue()` calls these hooks during reconciliation
+* to enable enter/exit animations and FLIP reordering.
+*
+* When not provided, `__listValue()` behaves as a plain keyed list.
+*/
+declare const ListAnimationContext: Context<ListAnimationHooks | undefined>;
+/**
+* Keyed list reconciliation that returns a DisposableNode (DocumentFragment).
+*
+* Unlike `__list()` which appends to an existing container element,
+* `__listValue()` manages items between comment markers in a DocumentFragment.
+* This makes it suitable for use in component children thunks where there is
+* no parent element variable at compile time.
+*
+* Compiler output target for .map() expressions in component children JSX.
+*
+* @param items - A signal or getter function containing the array of items
+* @param keyFn - Extracts a unique key from each item. Pass null for unkeyed mode.
+* @param renderFn - Creates a DOM node for an item (called once per key)
+* @returns A DisposableNode (DocumentFragment with dispose method)
+*/
+declare function __listValue<T>(items: Signal<T[]> | (() => T[]), keyFn: ((item: T, index: number) => string | number) | null, renderFn: (item: T) => Node): DisposableNode;
+/**
+* Apply a spread props object to a DOM element.
+*
+* Compiler output target for JSX spread attributes on intrinsic elements:
+*   <button {...rest} /> → __spread(el, rest)
+*
+* Handles event handlers (on*), ref, style, class/className, htmlFor,
+* SVG attribute normalization, and standard HTML attributes.
+* Uses replace (not merge) semantics — last-wins, matching source order.
+*/
+declare function __spread(el: Element, props: Record<string, unknown>): void;
 declare function styleObjectToString(style: Record<string, string | number | null | undefined>): string;
 /**
 * Returns true when running in a real browser environment.
@@ -625,7 +693,10 @@ interface RouteConfig<
 		signal: AbortSignal;
 	}) => Promise<TLoaderData> | TLoaderData;
 	/** Optional error component rendered when loader throws. */
-	errorComponent?: (error: Error) => Node;
+	errorComponent?: (props: {
+		error: Error;
+		retry: () => void;
+	}) => Node;
 	/** Optional path params schema for validation/parsing. */
 	params?: ParamSchema<TParams>;
 	/** Optional search params schema for validation/coercion. */
@@ -653,7 +724,10 @@ interface CompiledRoute {
 		params: Record<string, string>;
 		signal: AbortSignal;
 	}) => Promise<unknown> | unknown;
-	errorComponent?: RouteConfig["errorComponent"];
+	errorComponent?: (props: {
+		error: Error;
+		retry: () => void;
+	}) => Node;
 	/** Optional path params schema for validation/parsing. */
 	params?: ParamSchema<unknown>;
 	searchParams?: RouteConfig["searchParams"];
@@ -993,6 +1067,7 @@ declare class QueryEnvelopeStore {
 	private _envelopes;
 	get(queryKey: string): QueryEnvelope | undefined;
 	set(queryKey: string, envelope: QueryEnvelope): void;
+	delete(queryKey: string): void;
 	clear(): void;
 }
 /** Entry registered by query() during SSR for renderToHTML() to await. */
@@ -1093,4 +1168,4 @@ declare function getSSRContext(): SSRRenderContext | undefined;
 * clears during HMR module re-evaluation.
 */
 declare function hasSSRResolver(): boolean;
-export { stopSignalCollection, startSignalCollection, setContextScope, setAdapter, runCleanups, resolveComponent, removeNode, registerSSRResolver, pushScope, popScope, onCleanup, onAnimationsComplete, matchRoute, matchPath, lifecycleEffect, isRenderNode, isBrowser, insertBefore, hasSSRResolver, getSSRContext, getContextScope, getAdapter, executeLoaders, domEffect, deserializeProps, deriveKey, createDOMAdapter, compileTheme, clearChildren, _tryOnCleanup, __text, styleObjectToString as __styleStr, __staticText, __show, __pushMountFrame, __prop, __on, __list, __insert, __flushMountFrame, __exitChildren, __enterChildren, __element, __discardMountFrame, __conditional, __classList, __child, __attr, __append, SSRRenderContext, SSRQueryEntry, SSRAuth, SPACING_SCALE, SIZE_KEYWORDS, SHADOW_SCALE, RenderText, RenderNode, RenderElement, RenderAdapter, RENDER_NODE_BRAND, RADIUS_SCALE, QueryEnvelopeStore, PropertyMapping, PSEUDO_PREFIXES, PSEUDO_MAP, PROPERTY_MAP, MemoryCache, MatchResult, LINE_HEIGHT_SCALE, KEYWORD_MAP, HEIGHT_AXIS_PROPERTIES, FONT_WEIGHT_SCALE, FONT_SIZE_SCALE, EntityStore, DISPLAY_MAP, CSS_COLOR_KEYWORDS, CSSDeclarationEntry, CONTENT_MAP, COLOR_NAMESPACES, ALIGNMENT_MAP };
+export { stopSignalCollection, startSignalCollection, setContextScope, setAdapter, runCleanups, resolveComponent, removeNode, registerSSRResolver, pushScope, popScope, onCleanup, onAnimationsComplete, matchRoute, matchPath, lifecycleEffect, isRenderNode, isBrowser, insertBefore, hasSSRResolver, getSSRContext, getContextScope, getAdapter, executeLoaders, domEffect, deserializeProps, deriveKey, createDOMAdapter, compileTheme, clearChildren, _tryOnCleanup, __text, styleObjectToString as __styleStr, __staticText, __spread, __show, __pushMountFrame, __prop, __on, __listValue, __list, __insert, __flushMountFrame, __exitChildren, __enterChildren, __element, __discardMountFrame, __conditional, __classList, __child, __attr, __append, SSRRenderContext, SSRQueryEntry, SSRAuth, SPACING_SCALE, SIZE_KEYWORDS, SHADOW_SCALE, RenderText, RenderNode, RenderElement, RenderAdapter, RENDER_NODE_BRAND, RADIUS_SCALE, QueryEnvelopeStore, PropertyMapping, PSEUDO_PREFIXES, PSEUDO_MAP, PROPERTY_MAP, MemoryCache, MatchResult, ListAnimationHooks, ListAnimationContext, LINE_HEIGHT_SCALE, KEYWORD_MAP, HEIGHT_AXIS_PROPERTIES, FONT_WEIGHT_SCALE, FONT_SIZE_SCALE, EntityStore, DISPLAY_MAP, CSS_COLOR_KEYWORDS, CSSDeclarationEntry, CONTENT_MAP, COLOR_NAMESPACES, ALIGNMENT_MAP };