@vertz/ui 0.2.23 → 0.2.25

package/dist/src/index.d.ts

@@ -117,6 +117,24 @@ declare function createContext<T>(defaultValue?: T, __stableId?: string): Contex
 * Returns the default value if no Provider is active.
 */
 declare function useContext<T>(ctx: Context<T>): UnwrapSignals<T> | undefined;
+/** Props for error fallback components (shared by DefaultErrorFallback and route errorComponent). */
+interface ErrorFallbackProps {
+	error: Error;
+	retry: () => void;
+}
+/**
+* Framework-provided error fallback component.
+*
+* Renders a simple error display with the error message and a "Try again" button.
+* Works without any theme registered — uses inline styles for a clean default look.
+*
+* Exported from `@vertz/ui` (not `@vertz/ui/components`) because it is a
+* framework-level component, not a theme-provided one.
+*
+* Uses imperative DOM instead of JSX because `@vertz/ui` is a core package
+* without the Vertz compiler plugin — `.ts` files don't go through JSX transforms.
+*/
+declare function DefaultErrorFallback({ error, retry }: ErrorFallbackProps): HTMLElement;
 /** DOM element types accepted by JSX (mirrors JSX.Element). */
 type JsxElement = HTMLElement | SVGElement | DocumentFragment;
 /** Props for the ErrorBoundary component. */
@@ -160,6 +178,15 @@ interface ForeignProps {
 	* For SVG tags, cast to the appropriate SVG element type.
 	*/
 	onReady?: (container: HTMLElement | SVGElement) => (() => void) | void;
+	/**
+	* Pre-rendered HTML content to inject during SSR.
+	* Only takes effect during server-side rendering — on the client,
+	* the SSR content is already in the DOM and preserved by hydration.
+	*
+	* Use this for content that can be pre-rendered on the server
+	* (e.g. syntax-highlighted code) to avoid a flash on first paint.
+	*/
+	html?: string;
 	/** Element id */
 	id?: string;
 	/** CSS class name */
@@ -182,7 +209,7 @@ interface ForeignProps {
 * Implemented as a hand-written `.ts` component (no JSX, no compiler transforms)
 * because it's a framework primitive that uses `__element()` directly.
 */
-declare function Foreign({ tag, onReady, id, className, style }: ForeignProps): Element;
+declare function Foreign({ tag, onReady, html, id, className, style }: ForeignProps): Element;
 /**
 * Runs callback once on mount. Never re-executes.
 * Return a function to register cleanup that runs on unmount.
@@ -195,20 +222,6 @@ declare function Foreign({ tag, onReady, id, className, style }: ForeignProps):
 * ```
 */
 declare function onMount2(callback: () => (() => void) | void): void;
-interface ListTransitionProps<T> {
-	each: T[];
-	keyFn: (item: T, index: number) => string | number;
-	children: (item: T) => Node;
-}
-/**
-* ListTransition component for animated list item enter/exit.
-* New items get `data-presence="enter"`, removed items get `data-presence="exit"`
-* with DOM removal deferred until CSS animation completes.
-*
-* Props are accessed as getters (not destructured) so the compiler-generated
-* reactive getters are tracked by the underlying domEffect.
-*/
-declare function ListTransition<T>(props: ListTransitionProps<T>): DocumentFragment;
 interface PresenceProps {
 	when: boolean;
 	children: () => HTMLElement;
@@ -585,8 +598,12 @@ interface ThemeProviderProps {
 *
 * Uses __element() directly (instead of jsx()) so the hydration cursor
 * walker can claim the existing SSR node during mount().
+*
+* Accepts `props` without destructuring so that the compiler-generated
+* getter for `theme` stays alive — `__attr()` reads it inside a domEffect,
+* making the attribute reactive when the parent passes a signal-backed value.
 */
-declare function ThemeProvider({ theme, children }: ThemeProviderProps): HTMLElement;
+declare function ThemeProvider(props: ThemeProviderProps): HTMLElement;
 /**
 * A record of variant names to their possible values (each value maps to style entries).
 *
@@ -626,6 +643,9 @@ interface VariantFunction<V extends VariantDefinitions> {
 */
 declare function variants<V extends VariantDefinitions>(config: VariantsConfig<V>): VariantFunction<V>;
 declare const DialogStackContext: Context<DialogStack>;
+declare const DialogHandleContext: Context<DialogHandle<unknown>>;
+declare const DialogIdContext: Context<string>;
+declare function useDialog<T = void>(): DialogHandle<T>;
 declare function useDialogStack(): DialogStack;
 interface DialogHandle<TResult> {
 	close(...args: void extends TResult ? [] : [result: TResult]): void;
@@ -642,19 +662,42 @@ type DialogResult<T> = {
 } | {
 	readonly ok: false;
 };
+interface DialogOpenOptions {
+	/** Whether the dialog can be dismissed by backdrop click or Escape. Default: true */
+	dismissible?: boolean;
+}
+interface ConfirmOptions {
+	title: string;
+	description?: string;
+	confirm?: string;
+	cancel?: string;
+	intent?: "primary" | "danger";
+	dismissible?: boolean;
+}
 interface DialogStack {
 	open<
 		TResult,
 		TProps
-	>(component: DialogComponent<TResult, TProps>, props: TProps): Promise<DialogResult<TResult>>;
+	>(component: DialogComponent<TResult, TProps>, props: TProps, options?: DialogOpenOptions): Promise<DialogResult<TResult>>;
 	/** @internal — used by useDialogStack() to pass captured context scope */
 	openWithScope<
 		TResult,
 		TProps
-	>(component: DialogComponent<TResult, TProps>, props: TProps, scope: ContextScope | null): Promise<DialogResult<TResult>>;
+	>(component: DialogComponent<TResult, TProps>, props: TProps, scope: ContextScope | null, options?: DialogOpenOptions): Promise<DialogResult<TResult>>;
+	confirm(options: ConfirmOptions): Promise<boolean>;
 	readonly size: number;
 	closeAll(): void;
 }
+/**
+* Manages the dialog container element and provides DialogStack via context.
+*
+* Creates a hydration-safe container div via `__element`, initializes the
+* dialog stack, and wraps children in `DialogStackContext.Provider`.
+* The container renders after children — dialogs portal into it.
+*/
+declare function DialogStackProvider({ children }: {
+	children?: unknown;
+}): HTMLElement;
 declare function createDialogStack(container: HTMLElement): DialogStack;
 /**
 * Brand symbol for render nodes.
@@ -752,6 +795,31 @@ declare function __enterChildren(el: Element): void;
 */
 declare function __exitChildren(): void;
 /**
+* 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>;
+/**
 * Returns true when running in a real browser environment.
 * Returns false on the server, even if `window` exists (DOM shim).
 *
@@ -930,6 +998,37 @@ interface FormDataOptions {
 *   "true"/"false" become booleans.
 */
 declare function formDataToObject(formData: FormData, options?: FormDataOptions): Record<string, unknown>;
+type DateInput = Date | string | number;
+interface FormatRelativeTimeOptions {
+	/** BCP 47 locale tag. Defaults to user's locale via Intl defaults. */
+	locale?: string;
+	/** Intl.RelativeTimeFormat numeric option. Defaults to 'auto'. */
+	numeric?: "auto" | "always";
+	/** Reference time for "now". Defaults to `new Date()`. Useful for testing. */
+	now?: Date;
+}
+declare function formatRelativeTime(date: DateInput, options?: FormatRelativeTimeOptions): string;
+interface RelativeTimeProps {
+	/** The date to format. Accepts Date, ISO string, or epoch ms. */
+	date: DateInput;
+	/** BCP 47 locale tag. */
+	locale?: string;
+	/** Intl.RelativeTimeFormat numeric option. Defaults to 'auto'. */
+	numeric?: "auto" | "always";
+	/** Update interval in ms. Defaults to adaptive. */
+	updateInterval?: number;
+	/** CSS class name for the <time> element. */
+	className?: string;
+	/** Title attribute (shown on hover). Defaults to full formatted date. Set to false to disable. */
+	title?: string | false;
+}
+/**
+* Auto-updating relative time component.
+* Renders a `<time>` element with the formatted relative time.
+* Uses `setTimeout` chains with adaptive intervals for live updates.
+* Timer starts in `onMount()` — safe for SSR (skipped on server).
+*/
+declare function RelativeTime({ date, locale, numeric, updateInterval, className, title }: RelativeTimeProps): HTMLTimeElement;
 /** A function returning a dynamic import of a component module. */
 type ComponentLoader = () => Promise<{
 	default: ComponentFunction;
@@ -1072,6 +1171,16 @@ declare function invalidate<
 	T,
 	E
 >(descriptor: QueryDescriptor<T, E>): void;
+/**
+* Invalidate all active queries targeting tenant-scoped entities.
+* Clears cached data first (no SWR stale window), then refetches.
+*
+* Called automatically by TenantProvider after switchTenant() succeeds.
+* Can also be called manually if needed.
+*
+* No-op during SSR.
+*/
+declare function invalidateTenantQueries(): void;
 import { EntityQueryMeta as EntityQueryMeta2, QueryDescriptor as QueryDescriptor2 } from "@vertz/fetch";
 /** Options for query(). */
 interface QueryOptions<T> {
@@ -1079,8 +1188,6 @@ interface QueryOptions<T> {
 	initialData?: T;
 	/** Debounce re-fetches triggered by reactive dependency changes (ms). */
 	debounce?: number;
-	/** When false, the query will not fetch. Defaults to true. */
-	enabled?: boolean;
 	/** Explicit cache key. When omitted, derived from the thunk. */
 	key?: string;
 	/** Custom cache store. Defaults to a shared in-memory Map. */
@@ -1114,6 +1221,8 @@ interface QueryResult<
 	readonly revalidating: Unwrapped<ReadonlySignal<boolean>>;
 	/** The error from the latest failed fetch, or undefined. */
 	readonly error: Unwrapped<ReadonlySignal<E | undefined>>;
+	/** True when the query has never fetched (thunk returned null or not yet run). */
+	readonly idle: Unwrapped<ReadonlySignal<boolean>>;
 	/** Manually trigger a refetch (clears cache for this key). */
 	refetch: () => void;
 	/** Alias for refetch — revalidate the cached data. */
@@ -1135,36 +1244,11 @@ declare function query<
 	T,
 	E
 >(descriptor: QueryDescriptor2<T, E>, options?: Omit<QueryOptions<T>, "key">): QueryResult<T, E>;
-declare function query<T>(thunk: () => Promise<T>, options?: QueryOptions<T>): QueryResult<T>;
-interface QueryMatchHandlers<
-	T,
-	E
-> {
-	loading: () => Node | null;
-	error: (error: E) => Node | null;
-	data: (data: T) => Node | null;
-}
-/**
-* Pattern-match on a QueryResult's exclusive state.
-*
-* Returns a stable `<span style="display:contents">` wrapper that internally
-* manages branch switching (loading/error/data) via a reactive effect.
-* The same wrapper is returned for repeated calls with the same queryResult
-* (cached via WeakMap), enabling __child's stable-node optimization.
-*
-* Priority: loading → error → data.
-*
-* `loading` only fires on the initial load (no data yet).
-* When revalidating with existing data, the `data` handler receives the
-* current data. Access `query.revalidating` from the component scope for
-* revalidation state.
-*/
-declare function queryMatch<
+declare function query<
 	T,
 	E
->(queryResult: QueryResult<T, E>, handlers: QueryMatchHandlers<T, E>): HTMLElement & {
-	dispose: DisposeFn;
-};
+>(thunk: () => QueryDescriptor2<T, E> | null, options?: Omit<QueryOptions<T>, "key">): QueryResult<T, E>;
+declare function query<T>(thunk: () => Promise<T> | null, options?: QueryOptions<T>): QueryResult<T>;
 /**
 * Template literal type utility that extracts route parameter names from a path pattern.
 *
@@ -1260,7 +1344,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. */
@@ -1298,7 +1385,10 @@ interface RouteConfigLike {
 		params: Record<string, string>;
 		signal: AbortSignal;
 	}): unknown;
-	errorComponent?: (error: Error) => Node;
+	errorComponent?: (props: {
+		error: Error;
+		retry: () => void;
+	}) => Node;
 	params?: ParamSchema<unknown>;
 	searchParams?: SearchParamSchema<unknown>;
 	children?: Record<string, RouteConfigLike>;
@@ -1332,7 +1422,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"];
@@ -1550,9 +1643,18 @@ declare function useRouter<T extends Record<string, RouteConfigLike> = RouteDefi
 */
 declare function useParams<TPath extends string = string>(): ExtractParams<TPath>;
 declare function useParams<T extends Record<string, unknown>>(): T;
+/** Error fallback component signature, reuses ErrorFallbackProps from DefaultErrorFallback. */
+type ErrorFallbackFn = (props: ErrorFallbackProps) => Node;
 interface RouterViewProps {
 	router: Router;
+	/** Rendered when no route matches (404). */
 	fallback?: () => Node;
+	/**
+	* Global error fallback for all routes. When set, every route component is
+	* automatically wrapped in an ErrorBoundary using this fallback.
+	* Per-route `errorComponent` takes precedence over this.
+	*/
+	errorFallback?: ErrorFallbackFn;
 }
 /**
 * Renders the matched route's component inside a container div.
@@ -1565,7 +1667,7 @@ interface RouterViewProps {
 * domEffect runs the component factory (to attach reactivity/event handlers)
 * but skips clearing the container.
 */
-declare function RouterView({ router, fallback }: RouterViewProps): HTMLElement;
+declare function RouterView({ router, fallback, errorFallback }: RouterViewProps): HTMLElement;
 /**
 * Parse URLSearchParams into a typed object, optionally through a schema.
 *
@@ -1591,6 +1693,12 @@ declare class DisposalScopeError extends Error {
 	constructor();
 }
 /**
+* Register a cleanup function with the current disposal scope.
+* Throws `DisposalScopeError` if no scope is active — fail-fast
+* so developers know their cleanup callback was not registered.
+*/
+declare function onCleanup(fn: DisposeFn): void;
+/**
 * Group multiple signal writes into a single update flush.
 * Nested batches are supported — only the outermost batch triggers the flush.
 */
@@ -1830,6 +1938,7 @@ declare class QueryEnvelopeStore {
 	private _envelopes;
 	get(queryKey: string): QueryEnvelope | undefined;
 	set(queryKey: string, envelope: QueryEnvelope): void;
+	delete(queryKey: string): void;
 	clear(): void;
 }
 /** Get the global EntityStore singleton. */
@@ -1954,4 +2063,4 @@ interface RegisterThemeInput {
 * ```
 */
 declare function registerTheme(resolved: RegisterThemeInput): void;
-export { zoomOut, zoomIn, variants, validate, useSearchParams, useRouter, useParams, useDialogStack, useContext, untrack, slideOutToTop, slideOutToRight, slideOutToLeft, slideOutToBottom, slideInFromTop, slideInFromRight, slideInFromLeft, slideInFromBottom, signal, setAdapter, s, resolveChildren, resetRelationSchemas_TEST_ONLY, resetInjectedStyles, registerTheme, registerRelationSchema, ref, queryMatch, query, parseSearchParams, palettes, onMount2 as onMount, onAnimationsComplete, mount, keyframes, isRenderNode, isQueryDescriptor, isBrowser, invalidate, injectCSS, hydrateIslands, hydrate, globalCss, getRelationSchema, getQueryEnvelopeStore, getInjectedCSS, getEntityStore, getAdapter, formDataToObject, form, font, fadeOut, fadeIn, defineTheme, defineRoutes, css, createTestStore, createRouter, createOptimisticHandler, createLink, createFieldState, createDialogStack, createDOMAdapter, createContext, configureImageOptimizer, computed, compileTheme, compileFonts, children, buildOptimizedUrl, batch, accordionUp, accordionDown, __staticText, __exitChildren, __enterChildren, __element, __append, VariantsConfig, VariantProps, VariantFunction, ValidationResult, UnwrapSignals, TypedRoutes, TypedRouter, ThemeProviderProps, ThemeProvider, ThemeInput, Theme, SuspenseProps, Suspense, StyleValue, StyleEntry, Signal, SerializedStore, SearchParamSchema, SdkMethodWithMeta, SdkMethod, RouterViewProps, RouterView, RouterOptions, RouterContext, Router, RoutePattern, RoutePaths, RouteMatch, RouteDefinitionMap, RouteConfig, RenderText, RenderNode, RenderElement, RenderAdapter, RelationSchema, RelationFieldDef, RegisterThemeInput, Ref, ReadonlySignal, RENDER_NODE_BRAND, QueryResult, QueryOptions, QueryMatchHandlers, QueryEnvelopeStore, QueryEnvelope, QueryDescriptor3 as QueryDescriptor, PresenceProps, Presence, PreloadItem, PathWithParams, ParamSchema, OutletContextValue, OutletContext, Outlet, NavigateOptions, NavigateInput, MountOptions, MountHandle, MergeSelectOptions, MatchedRoute, LoaderData, ListTransitionProps, ListTransition, LinkProps, LinkFactoryOptions, Link, IslandRegistry, IslandProps, Island, InferRouteMap, ImageProps, Image, GlobalCSSOutput, GlobalCSSInput, FormSchema, FormOptions, FormInstance, FormDataOptions, ForeignProps, Foreign, FontSrc, FontOptions, FontFallbackMetrics, FontDescriptor, FieldState, FieldSelectionTracker, FallbackFontName, ExtractParams, ErrorBoundaryProps, ErrorBoundary, EntityStoreOptions, EntityStore, DisposeFn, DisposalScopeError, DialogStackContext, DialogStack, DialogResult, DialogHandle, DialogComponent, Context, Computed, ComponentRegistry, ComponentLoader, ComponentFunction, CompiledTheme, CompiledRoute, CompiledFonts, CompileThemeOptions, CompileFontsOptions, ColorPalette, ChildrenAccessor, ChildValue, CacheStore, CSSOutput, CSSInput, ANIMATION_EASING, ANIMATION_DURATION };
+export { zoomOut, zoomIn, variants, validate, useSearchParams, useRouter, useParams, useDialogStack, useDialog, useContext, untrack, slideOutToTop, slideOutToRight, slideOutToLeft, slideOutToBottom, slideInFromTop, slideInFromRight, slideInFromLeft, slideInFromBottom, signal, setAdapter, s, resolveChildren, resetRelationSchemas_TEST_ONLY, resetInjectedStyles, registerTheme, registerRelationSchema, ref, query, parseSearchParams, palettes, onMount2 as onMount, onCleanup, onAnimationsComplete, mount, keyframes, isRenderNode, isQueryDescriptor, isBrowser, invalidateTenantQueries, invalidate, injectCSS, hydrateIslands, hydrate, globalCss, getRelationSchema, getQueryEnvelopeStore, getInjectedCSS, getEntityStore, getAdapter, formatRelativeTime, formDataToObject, form, font, fadeOut, fadeIn, defineTheme, defineRoutes, css, createTestStore, createRouter, createOptimisticHandler, createLink, createFieldState, createDialogStack, createDOMAdapter, createContext, configureImageOptimizer, computed, compileTheme, compileFonts, children, buildOptimizedUrl, batch, accordionUp, accordionDown, __staticText, __exitChildren, __enterChildren, __element, __append, VariantsConfig, VariantProps, VariantFunction, ValidationResult, UnwrapSignals, TypedRoutes, TypedRouter, ThemeProviderProps, ThemeProvider, ThemeInput, Theme, SuspenseProps, Suspense, StyleValue, StyleEntry, Signal, SerializedStore, SearchParamSchema, SdkMethodWithMeta, SdkMethod, RouterViewProps, RouterView, RouterOptions, RouterContext, Router, RoutePattern, RoutePaths, RouteMatch, RouteDefinitionMap, RouteConfig, RenderText, RenderNode, RenderElement, RenderAdapter, RelativeTimeProps, RelativeTime, RelationSchema, RelationFieldDef, RegisterThemeInput, Ref, ReadonlySignal, RENDER_NODE_BRAND, QueryResult, QueryOptions, QueryEnvelopeStore, QueryEnvelope, QueryDescriptor3 as QueryDescriptor, PresenceProps, Presence, PreloadItem, PathWithParams, ParamSchema, OutletContextValue, OutletContext, Outlet, NavigateOptions, NavigateInput, MountOptions, MountHandle, MergeSelectOptions, MatchedRoute, LoaderData, ListAnimationHooks, ListAnimationContext, LinkProps, LinkFactoryOptions, Link, IslandRegistry, IslandProps, Island, InferRouteMap, ImageProps, Image, GlobalCSSOutput, GlobalCSSInput, FormatRelativeTimeOptions, FormSchema, FormOptions, FormInstance, FormDataOptions, ForeignProps, Foreign, FontSrc, FontOptions, FontFallbackMetrics, FontDescriptor, FieldState, FieldSelectionTracker, FallbackFontName, ExtractParams, ErrorFallbackProps, ErrorBoundaryProps, ErrorBoundary, EntityStoreOptions, EntityStore, DisposeFn, DisposalScopeError, DialogStackProvider, DialogStackContext, DialogStack, DialogResult, DialogOpenOptions, DialogIdContext, DialogHandleContext, DialogHandle, DialogComponent, DefaultErrorFallback, DateInput, Context, ConfirmOptions, Computed, ComponentRegistry, ComponentLoader, ComponentFunction, CompiledTheme, CompiledRoute, CompiledFonts, CompileThemeOptions, CompileFontsOptions, ColorPalette, ChildrenAccessor, ChildValue, CacheStore, CSSOutput, CSSInput, ANIMATION_EASING, ANIMATION_DURATION };