@vertz/ui 0.2.12 → 0.2.13

package/dist/src/css/public.js

@@ -0,0 +1,22 @@
+import {
+  ThemeProvider,
+  compileTheme,
+  css,
+  defineTheme,
+  globalCss,
+  s,
+  variants
+} from "../../shared/chunk-c9xxsrat.js";
+import"../../shared/chunk-j6qyxfdc.js";
+import"../../shared/chunk-prj7nm08.js";
+import"../../shared/chunk-h89w580h.js";
+import"../../shared/chunk-8hsz5y4a.js";
+export {
+  variants,
+  s,
+  globalCss,
+  defineTheme,
+  css,
+  compileTheme,
+  ThemeProvider
+};

package/dist/{form → src/form}/public.js

@@ -3,8 +3,8 @@ import {
   form,
   formDataToObject,
   validate
-} from "../shared/chunk-55tgkc7s.js";
-import"../shared/chunk-2rs8a26p.js";
+} from "../../shared/chunk-c30eg6wn.js";
+import"../../shared/chunk-8hsz5y4a.js";
 export {
   validate,
   formDataToObject,

package/dist/{index.d.ts → src/index.d.ts}

@@ -151,7 +151,7 @@ declare function onMount2(callback: () => (() => void) | void): void;
 interface ListTransitionProps<T> {
 	each: T[];
 	keyFn: (item: T, index: number) => string | number;
-	children: (item: T) => HTMLElement | SVGElement;
+	children: (item: T) => Node;
 }
 /**
 * ListTransition component for animated list item enter/exit.
@@ -161,7 +161,7 @@ interface ListTransitionProps<T> {
 * 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>): Node;
+declare function ListTransition<T>(props: ListTransitionProps<T>): DocumentFragment;
 interface PresenceProps {
 	when: boolean;
 	children: () => HTMLElement;
@@ -173,7 +173,7 @@ interface PresenceProps {
 * Props are accessed as getters (not destructured) so the compiler-generated
 * reactive getters are tracked by domEffect.
 */
-declare function Presence(props: PresenceProps): Node;
+declare function Presence(props: PresenceProps): DocumentFragment;
 /** A ref container for DOM element access. */
 interface Ref<T> {
 	current: T | undefined;
@@ -241,7 +241,7 @@ type CSSOutput<T extends CSSInput = CSSInput> = { readonly [K in keyof T & strin
 * In SSR, document.head is freshly created per request by installDomShim().
 * The module-level dedup Set would incorrectly block injection on request 2+
 * since the Set persists across requests while document.head is replaced.
-* We bypass dedup when __SSR_URL__ is set (SSR context).
+* We bypass dedup when SSR context is active.
 */
 declare function injectCSS(cssText: string): void;
 /** Reset injected styles tracking. Used in tests. */
@@ -738,19 +738,18 @@ interface MountHandle {
 	root: HTMLElement;
 }
 /**
-* Mount an app to a DOM element.
+* Mount an app to the `#app` root element.
 *
 * Uses tolerant hydration automatically: if the root element has SSR content,
 * it walks the existing DOM and attaches reactivity without re-creating nodes.
 * If the root is empty (CSR), it renders from scratch.
 *
 * @param app - App function that returns an HTMLElement
-* @param selector - CSS selector string or HTMLElement
 * @param options - Mount options (theme, styles, onMount, etc.)
 * @returns MountHandle with unmount function and root element
 */
-declare function mount<AppFn extends () => Element | DocumentFragment>(app: AppFn, selector: string | HTMLElement, options?: MountOptions): MountHandle;
-import { QueryDescriptor as QueryDescriptor2 } from "@vertz/fetch";
+declare function mount<AppFn extends () => Element | DocumentFragment>(app: AppFn, options?: MountOptions): MountHandle;
+import { QueryDescriptor as QueryDescriptor3 } from "@vertz/fetch";
 import { isQueryDescriptor } from "@vertz/fetch";
 /**
 * Interface for cache stores used by query().
@@ -763,6 +762,31 @@ interface CacheStore<T = unknown> {
 	clear?(): void;
 }
 import { QueryDescriptor } from "@vertz/fetch";
+/**
+* Invalidate all active queries matching the descriptor's entity metadata.
+*
+* - List descriptors match ALL active list queries for that entity type
+*   (regardless of filter params).
+* - Get descriptors match by entity type + specific id.
+* - Descriptors without entity metadata are a no-op.
+*
+* Active queries are revalidated in the background (SWR pattern) —
+* existing data stays visible while the refetch happens.
+*
+* @example
+* ```ts
+* import { invalidate } from '@vertz/ui';
+*
+* // After a custom operation not covered by optimistic updates:
+* invalidate(api.todos.list());      // revalidates all active todo list queries
+* invalidate(api.todos.get('123'));   // revalidates the specific get query
+* ```
+*/
+declare function invalidate<
+	T,
+	E
+>(descriptor: QueryDescriptor<T, E>): void;
+import { EntityQueryMeta as EntityQueryMeta2, QueryDescriptor as QueryDescriptor2 } from "@vertz/fetch";
 /** Options for query(). */
 interface QueryOptions<T> {
 	/** Pre-populated data — skips the initial fetch when provided. */
@@ -788,6 +812,8 @@ interface QueryOptions<T> {
 	*   when the function returns `false`).
 	*/
 	refetchInterval?: number | false | ((data: T | undefined, iteration: number) => number | false);
+	/** @internal Entity metadata for entity-backed queries. Set by descriptor overload. */
+	_entityMeta?: EntityQueryMeta2;
 }
 /** The reactive object returned by query(). */
 interface QueryResult<
@@ -822,7 +848,7 @@ interface QueryResult<
 declare function query<
 	T,
 	E
->(descriptor: QueryDescriptor<T, E>, options?: Omit<QueryOptions<T>, "key">): QueryResult<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,
@@ -899,7 +925,7 @@ type PathWithParams<T extends string> = T extends `${infer Before}*` ? `${PathWi
 * ```
 */
 type RoutePaths<TRouteMap extends Record<string, unknown>> = { [K in keyof TRouteMap & string] : PathWithParams<K> }[keyof TRouteMap & string];
-/** Simple schema interface for search param parsing. */
+/** Schema interface for parsing and validating values (search params, path params). */
 interface SearchParamSchema<T> {
 	parse(data: unknown): {
 		ok: true;
@@ -909,11 +935,14 @@ interface SearchParamSchema<T> {
 		error: unknown;
 	};
 }
+/** Schema interface for parsing and validating route path params. */
+type ParamSchema<T> = SearchParamSchema<T>;
 /** A route configuration for a single path. */
 interface RouteConfig<
 	TPath extends string = string,
 	TLoaderData = unknown,
-	TSearch = unknown
+	TSearch = unknown,
+	TParams = unknown
 > {
 	/** Component factory (lazy for code splitting). */
 	component: () => Node | Promise<{
@@ -926,6 +955,8 @@ interface RouteConfig<
 	}) => Promise<TLoaderData> | TLoaderData;
 	/** Optional error component rendered when loader throws. */
 	errorComponent?: (error: Error) => Node;
+	/** Optional path params schema for validation/parsing. */
+	params?: ParamSchema<TParams>;
 	/** Optional search params schema for validation/coercion. */
 	searchParams?: SearchParamSchema<TSearch>;
 	/** Nested child routes. */
@@ -956,6 +987,7 @@ interface RouteConfigLike {
 		signal: AbortSignal;
 	}): unknown;
 	errorComponent?: (error: Error) => Node;
+	params?: ParamSchema<unknown>;
 	searchParams?: SearchParamSchema<unknown>;
 	children?: Record<string, RouteConfigLike>;
 }
@@ -986,6 +1018,8 @@ interface CompiledRoute {
 		signal: AbortSignal;
 	}) => Promise<unknown> | unknown;
 	errorComponent?: RouteConfig["errorComponent"];
+	/** Optional path params schema for validation/parsing. */
+	params?: ParamSchema<unknown>;
 	searchParams?: RouteConfig["searchParams"];
 	/** Compiled children. */
 	children?: CompiledRoute[];
@@ -999,6 +1033,8 @@ interface MatchedRoute {
 interface RouteMatch {
 	/** All params extracted from the full URL path. */
 	params: Record<string, string>;
+	/** Parsed params via schema (set when route has a params schema and parse succeeds). */
+	parsedParams?: Record<string, unknown>;
 	/** The leaf route config that matched. */
 	route: CompiledRoute;
 	/** The chain of matched routes from root to leaf (for nested layouts). */
@@ -1116,7 +1152,7 @@ type TypedRouter<T extends Record<string, RouteConfigLike> = RouteDefinitionMap>
 * Create a router instance.
 *
 * @param routes - Compiled route list from defineRoutes()
-* @param initialUrl - The initial URL to match (optional; auto-detects from window.location or __SSR_URL__)
+* @param initialUrl - The initial URL to match (optional; auto-detects from window.location or SSR context)
 * @returns Router instance with reactive state and navigation methods
 */
 declare function createRouter<T extends Record<string, RouteConfigLike> = RouteDefinitionMap>(routes: TypedRoutes<T>, initialUrl?: string, options?: RouterOptions): Router<T>;
@@ -1140,7 +1176,18 @@ declare const OutletContext: Context<OutletContextValue>;
 declare function Outlet(): Node;
 declare const RouterContext: Context<Router>;
 declare function useRouter<T extends Record<string, RouteConfigLike> = RouteDefinitionMap>(): UnwrapSignals<Router<T>>;
+/**
+* Read route params from the current matched route.
+*
+* Overload 1: `useParams<'/tasks/:id'>()` — returns `{ id: string }` (backward compat).
+* Overload 2: `useParams<{ id: number }>()` — returns parsed type assertion
+*   (reads `parsedParams` when a route has a `params` schema).
+*
+* At runtime, both overloads prefer `parsedParams` (schema-parsed) when available,
+* falling back to raw `params` (string values).
+*/
 declare function useParams<TPath extends string = string>(): ExtractParams<TPath>;
+declare function useParams<T extends Record<string, unknown>>(): T;
 interface RouterViewProps {
 	router: Router;
 	fallback?: () => Node;
@@ -1202,6 +1249,38 @@ declare function computed<T>(fn: () => T): Computed<T>;
 */
 declare function untrack<T>(fn: () => T): T;
 /**
+* QueryResultIndex tracks ordered arrays of entity IDs for list queries.
+* Used to maintain list query results and invalidate on entity removal.
+*/
+declare class QueryResultIndex {
+	private _indices;
+	/**
+	* Set the result IDs for a query key.
+	*/
+	set(queryKey: string, ids: string[]): void;
+	/**
+	* Get the result IDs for a query key.
+	*/
+	get(queryKey: string): string[] | undefined;
+	/**
+	* Remove an entity ID from all indices (called after entity delete).
+	*/
+	removeEntity(entityId: string): void;
+	/**
+	* Clear a specific query's index (for revalidation).
+	*/
+	clear(queryKey: string): void;
+	/**
+	* Snapshot all indices containing the given entity ID.
+	* Returns a Map of queryKey → full ID array (copy) for rollback support.
+	*/
+	snapshotEntity(entityId: string): Map<string, string[]>;
+	/**
+	* Get all query keys (for serialization).
+	*/
+	keys(): string[];
+}
+/**
 * Serialized format for EntityStore - used for SSR transfer and hydration.
 */
 interface SerializedStore {
@@ -1224,12 +1303,14 @@ interface EntityStoreOptions {
 * EntityStore - Normalized, signal-backed entity cache for @vertz/ui.
 *
 * Stores entities by type and ID, with signal-per-entity reactivity.
-* Supports field-level merge, SSR hydration, and query result indices.
+* Supports field-level merge, SSR hydration, optimistic layers, and query result indices.
 */
 declare class EntityStore {
 	private _entities;
 	private _typeListeners;
 	private _queryIndices;
+	/** Public accessor for query indices — used by optimistic handlers and tests. */
+	get queryIndices(): QueryResultIndex;
 	constructor(options?: EntityStoreOptions);
 	/**
 	* Read a single entity. Returns a signal that updates on merge.
@@ -1270,16 +1351,139 @@ declare class EntityStore {
 	size(type: string): number;
 	/**
 	* Serialize the store for SSR transfer.
+	* Serializes base values only — optimistic layers are transient.
 	*/
 	dehydrate(): SerializedStore;
 	/**
 	* Hydrate from serialized data. Merges into existing store (doesn't replace).
 	*/
 	hydrate(data: SerializedStore): void;
+	/**
+	* Apply an optimistic layer to an entity.
+	* The layer is stacked on top of base, recomputing the visible signal value.
+	*/
+	applyLayer(type: string, id: string, mutationId: string, patch: Record<string, unknown>): void;
+	/**
+	* Increment the reference count for an entity.
+	* Clears orphanedAt timestamp. No-op if entity doesn't exist.
+	*/
+	addRef(type: string, id: string): void;
+	/**
+	* Decrement the reference count for an entity.
+	* Sets orphanedAt when refCount reaches 0. No-op if entity doesn't exist.
+	*/
+	removeRef(type: string, id: string): void;
+	/**
+	* Evict orphaned entities (refCount=0) that have been unreferenced
+	* for longer than maxAge ms. Entities with pending layers are preserved.
+	* Default maxAge: 5 minutes.
+	*/
+	evictOrphans(maxAge?: number): number;
+	/**
+	* Inspect the internal state of an entity — for debugging and testing.
+	* Returns base, layers, visible (computed) state, refCount, and orphanedAt.
+	*/
+	inspect(type: string, id: string): {
+		base: Record<string, unknown>;
+		layers: Map<string, Record<string, unknown>>;
+		visible: unknown;
+		refCount: number;
+		orphanedAt: number | null;
+	} | undefined;
+	/**
+	* Rollback an optimistic layer (mutation failed).
+	* Removes the layer and recomputes visible from base + remaining layers.
+	*/
+	rollbackLayer(type: string, id: string, mutationId: string): void;
+	/**
+	* Optimistically remove an entity (for delete mutations).
+	* Removes the entity from the store and query indices.
+	* Caller should snapshot entity + indices beforehand for rollback.
+	*/
+	removeOptimistic(type: string, id: string, _mutationId: string): void;
+	/**
+	* Restore an entity after a failed optimistic delete.
+	* Re-merges the entity and restores query index positions.
+	*/
+	restoreOptimistic(type: string, _id: string, _mutationId: string, entitySnapshot: unknown, indexSnapshot: Map<string, string[]>): void;
+	/**
+	* Commit an optimistic layer after server confirms the mutation.
+	* Sets base to server data, removes the layer, recomputes visible.
+	*/
+	commitLayer(type: string, id: string, mutationId: string, serverData: Record<string, unknown>): void;
+	/**
+	* Merge a single (already normalized) entity into the store.
+	*/
+	private _mergeOne;
+	/**
+	* Recompute the visible signal value from base + all layers.
+	*/
+	private _recomputeVisible;
 	private _getOrCreateTypeMap;
 	private _getOrCreateListeners;
 	private _notifyTypeChange;
 }
+/** Envelope metadata for list queries (pagination info without entity data). */
+interface QueryEnvelope {
+	total?: number;
+	limit?: number;
+	nextCursor?: string | null;
+	hasNextPage?: boolean;
+	[key: string]: unknown;
+}
+/**
+* Stores list query envelope metadata per query key.
+* Decoupled from entity data — entities live in EntityStore,
+* envelopes live here. Allows list query reconstruction from
+* EntityStore data + envelope metadata.
+*/
+declare class QueryEnvelopeStore {
+	private _envelopes;
+	get(queryKey: string): QueryEnvelope | undefined;
+	set(queryKey: string, envelope: QueryEnvelope): void;
+	clear(): void;
+}
+/** Get the global EntityStore singleton. */
+declare function getEntityStore(): EntityStore;
+/** Get the global QueryEnvelopeStore singleton. */
+declare function getQueryEnvelopeStore(): QueryEnvelopeStore;
+/**
+* MutationEventBus — simple pub/sub for same-type query revalidation.
+*
+* When a mutation commits, the handler emits the mutated entity type.
+* Queries subscribed to that entity type revalidate automatically.
+*/
+interface MutationEventBus {
+	/** Subscribe to mutation events for a specific entity type. Returns unsubscribe function. */
+	subscribe(entityType: string, callback: () => void): () => void;
+	/** Emit a mutation event for an entity type. All subscribers for that type are notified. */
+	emit(entityType: string): void;
+	/** Remove all subscriptions. Used for SSR per-request isolation. */
+	clear(): void;
+}
+import { OptimisticHandler } from "@vertz/fetch";
+interface OptimisticHandlerOptions {
+	/** Custom MutationEventBus instance. Defaults to the singleton bus. */
+	mutationEventBus?: MutationEventBus;
+}
+/**
+* Create an OptimisticHandler that bridges @vertz/fetch mutations
+* to EntityStore's optimistic layer API.
+*
+* By default, emits mutation events to the singleton MutationEventBus
+* so that entity-backed queries revalidate automatically.
+*/
+declare function createOptimisticHandler(store: EntityStore, options?: OptimisticHandlerOptions): OptimisticHandler;
+interface RelationFieldDef {
+	readonly type: "one" | "many";
+	readonly entity: string;
+}
+interface RelationSchema {
+	readonly [fieldName: string]: RelationFieldDef;
+}
+declare function registerRelationSchema(entityType: string, schema: RelationSchema): void;
+declare function getRelationSchema(entityType: string): RelationSchema | undefined;
+declare function resetRelationSchemas_TEST_ONLY(): void;
 /**
 * Create a pre-populated EntityStore for testing.
 *
@@ -1299,4 +1503,4 @@ declare class EntityStore {
 * ```
 */
 declare function createTestStore(data: Record<string, Record<string, unknown>>): EntityStore;
-export { zoomOut, zoomIn, variants, validate, useSearchParams, useRouter, useParams, useDialogStack, useContext, untrack, slideOutToTop, slideOutToRight, slideOutToLeft, slideOutToBottom, slideInFromTop, slideInFromRight, slideInFromLeft, slideInFromBottom, signal, setAdapter, s, resolveChildren, resetInjectedStyles, ref, queryMatch, query, parseSearchParams, palettes, onMount2 as onMount, mount, keyframes, isRenderNode, isQueryDescriptor, injectCSS, hydrate, globalCss, getInjectedCSS, getAdapter, formDataToObject, form, fadeOut, fadeIn, defineTheme, defineRoutes, css, createTestStore, createRouter, createLink, createFieldState, createDialogStack, createDOMAdapter, createContext, computed, compileTheme, children, 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, RoutePaths, RouteMatch, RouteDefinitionMap, RouteConfig, RenderText, RenderNode, RenderElement, RenderAdapter, Ref, ReadonlySignal, RawDeclaration, RENDER_NODE_BRAND, QueryResult, QueryOptions, QueryMatchHandlers, QueryDescriptor2 as QueryDescriptor, PresenceProps, Presence, PathWithParams, OutletContextValue, OutletContext, Outlet, NavigateOptions, MountOptions, MountHandle, MatchedRoute, LoaderData, ListTransitionProps, ListTransition, LinkProps, LinkFactoryOptions, InferRouteMap, GlobalCSSOutput, GlobalCSSInput, FormSchema, FormOptions, FormInstance, FormDataOptions, FieldState, ExtractParams, ErrorBoundaryProps, ErrorBoundary, EntityStoreOptions, EntityStore, DisposeFn, DisposalScopeError, DialogStackContext, DialogStack, DialogHandle, DialogDismissedError, DialogComponent, Context, Computed, ComponentRegistry, ComponentLoader, ComponentFunction, CompiledTheme, CompiledRoute, ColorPalette, ChildrenAccessor, ChildValue, CacheStore, CSSOutput, CSSInput, ANIMATION_EASING, ANIMATION_DURATION };
+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, registerRelationSchema, ref, queryMatch, query, parseSearchParams, palettes, onMount2 as onMount, mount, keyframes, isRenderNode, isQueryDescriptor, invalidate, injectCSS, hydrate, globalCss, getRelationSchema, getQueryEnvelopeStore, getInjectedCSS, getEntityStore, getAdapter, formDataToObject, form, fadeOut, fadeIn, defineTheme, defineRoutes, css, createTestStore, createRouter, createOptimisticHandler, createLink, createFieldState, createDialogStack, createDOMAdapter, createContext, computed, compileTheme, children, 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, RoutePaths, RouteMatch, RouteDefinitionMap, RouteConfig, RenderText, RenderNode, RenderElement, RenderAdapter, RelationSchema, RelationFieldDef, Ref, ReadonlySignal, RawDeclaration, RENDER_NODE_BRAND, QueryResult, QueryOptions, QueryMatchHandlers, QueryEnvelopeStore, QueryEnvelope, QueryDescriptor3 as QueryDescriptor, PresenceProps, Presence, PathWithParams, ParamSchema, OutletContextValue, OutletContext, Outlet, NavigateOptions, MountOptions, MountHandle, MatchedRoute, LoaderData, ListTransitionProps, ListTransition, LinkProps, LinkFactoryOptions, InferRouteMap, GlobalCSSOutput, GlobalCSSInput, FormSchema, FormOptions, FormInstance, FormDataOptions, FieldState, ExtractParams, ErrorBoundaryProps, ErrorBoundary, EntityStoreOptions, EntityStore, DisposeFn, DisposalScopeError, DialogStackContext, DialogStack, DialogHandle, DialogDismissedError, DialogComponent, Context, Computed, ComponentRegistry, ComponentLoader, ComponentFunction, CompiledTheme, CompiledRoute, ColorPalette, ChildrenAccessor, ChildValue, CacheStore, CSSOutput, CSSInput, ANIMATION_EASING, ANIMATION_DURATION };