@vertz/ui 0.2.0 → 0.2.1

package/dist/shared/chunk-vx0kzack.js

@@ -0,0 +1,103 @@
+// src/router/server-nav.ts
+function parseSSE(buffer) {
+  const events = [];
+  const blocks = buffer.split(`
+
+`);
+  const remaining = blocks.pop() ?? "";
+  for (const block of blocks) {
+    if (block.trim() === "")
+      continue;
+    let type = "";
+    let data = "";
+    for (const line of block.split(`
+`)) {
+      if (line.startsWith("event: ")) {
+        type = line.slice(7).trim();
+      } else if (line.startsWith("data: ")) {
+        data = line.slice(6);
+      }
+    }
+    if (type) {
+      events.push({ type, data });
+    }
+  }
+  return { events, remaining };
+}
+function ensureSSRDataBus() {
+  const g = globalThis;
+  g.__VERTZ_SSR_DATA__ = [];
+  g.__VERTZ_SSR_PUSH__ = (key, data) => {
+    g.__VERTZ_SSR_DATA__.push({ key, data });
+    document.dispatchEvent(new CustomEvent("vertz:ssr-data", { detail: { key, data } }));
+  };
+}
+function pushNavData(key, data) {
+  const push = globalThis.__VERTZ_SSR_PUSH__;
+  if (typeof push === "function") {
+    push(key, data);
+  }
+}
+function isNavPrefetchActive() {
+  return globalThis.__VERTZ_NAV_PREFETCH_ACTIVE__ === true;
+}
+function setNavPrefetchActive(active) {
+  globalThis.__VERTZ_NAV_PREFETCH_ACTIVE__ = active;
+}
+function dispatchPrefetchDone() {
+  setNavPrefetchActive(false);
+  document.dispatchEvent(new CustomEvent("vertz:nav-prefetch-done"));
+}
+function prefetchNavData(url, options) {
+  const controller = new AbortController;
+  const timeout = options?.timeout ?? 5000;
+  ensureSSRDataBus();
+  setNavPrefetchActive(true);
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+  const done = fetch(url, {
+    headers: { "X-Vertz-Nav": "1" },
+    signal: controller.signal
+  }).then(async (response) => {
+    if (!response.body) {
+      dispatchPrefetchDone();
+      return;
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder;
+    let buffer = "";
+    while (true) {
+      const { done: streamDone, value } = await reader.read();
+      if (streamDone)
+        break;
+      buffer += decoder.decode(value, { stream: true });
+      const parsed = parseSSE(buffer);
+      buffer = parsed.remaining;
+      for (const event of parsed.events) {
+        if (event.type === "data") {
+          try {
+            const { key, data } = JSON.parse(event.data);
+            pushNavData(key, data);
+          } catch {}
+        } else if (event.type === "done") {
+          dispatchPrefetchDone();
+          clearTimeout(timeoutId);
+          return;
+        }
+      }
+    }
+    dispatchPrefetchDone();
+  }).catch(() => {
+    dispatchPrefetchDone();
+  }).finally(() => {
+    clearTimeout(timeoutId);
+  });
+  return {
+    abort: () => {
+      controller.abort();
+      clearTimeout(timeoutId);
+    },
+    done
+  };
+}
+
+export { isNavPrefetchActive, prefetchNavData };

package/dist/shared/chunk-wv6kkj1w.js

@@ -0,0 +1,464 @@
+import {
+  isNavPrefetchActive
+} from "./chunk-vx0kzack.js";
+import {
+  getAdapter,
+  isRenderNode
+} from "./chunk-g4rch80a.js";
+import {
+  _tryOnCleanup,
+  computed,
+  domEffect,
+  lifecycleEffect,
+  popScope,
+  pushScope,
+  runCleanups,
+  setReadValueCallback,
+  signal,
+  untrack
+} from "./chunk-hrd0mft1.js";
+
+// src/query/cache.ts
+class MemoryCache {
+  _store = new Map;
+  get(key) {
+    return this._store.get(key);
+  }
+  set(key, value) {
+    this._store.set(key, value);
+  }
+  delete(key) {
+    this._store.delete(key);
+  }
+  clear() {
+    this._store.clear();
+  }
+}
+
+// src/query/key-derivation.ts
+function deriveKey(thunk) {
+  return `__q:${hashString(thunk.toString())}`;
+}
+function hashString(str) {
+  let hash = 5381;
+  for (let i = 0;i < str.length; i++) {
+    hash = hash * 33 ^ str.charCodeAt(i);
+  }
+  return (hash >>> 0).toString(36);
+}
+
+// src/query/query.ts
+import { isQueryDescriptor } from "@vertz/fetch";
+
+// src/query/ssr-hydration.ts
+function hydrateQueryFromSSR(key, resolve) {
+  const ssrData = globalThis.__VERTZ_SSR_DATA__;
+  if (!ssrData)
+    return null;
+  const existing = ssrData.find((entry) => entry.key === key);
+  if (existing) {
+    resolve(existing.data);
+    return () => {};
+  }
+  const handler = (event) => {
+    const detail = event.detail;
+    if (detail.key === key) {
+      resolve(detail.data);
+      document.removeEventListener("vertz:ssr-data", handler);
+    }
+  };
+  document.addEventListener("vertz:ssr-data", handler);
+  return () => {
+    document.removeEventListener("vertz:ssr-data", handler);
+  };
+}
+
+// src/query/query.ts
+function isSSR() {
+  const check = typeof globalThis !== "undefined" && globalThis.__VERTZ_IS_SSR__;
+  return typeof check === "function" ? check() : false;
+}
+function getGlobalSSRTimeout() {
+  const g = globalThis;
+  const getter = typeof globalThis !== "undefined" && g.__VERTZ_GET_GLOBAL_SSR_TIMEOUT__;
+  return typeof getter === "function" ? getter() : undefined;
+}
+var defaultCache = new MemoryCache;
+var inflight = new Map;
+function clearDefaultQueryCache() {
+  defaultCache.clear();
+  inflight.clear();
+}
+globalThis.__VERTZ_CLEAR_QUERY_CACHE__ = clearDefaultQueryCache;
+function query(source, options = {}) {
+  if (isQueryDescriptor(source)) {
+    return query(async () => {
+      const result = await source._fetch();
+      if (!result.ok)
+        throw result.error;
+      return result.data;
+    }, { ...options, key: source._key });
+  }
+  const thunk = source;
+  const {
+    initialData,
+    debounce: debounceMs,
+    enabled = true,
+    key: customKey,
+    cache = defaultCache
+  } = options;
+  const baseKey = deriveKey(thunk);
+  const depHashSignal = signal("");
+  const cacheKeyComputed = computed(() => {
+    const dh = depHashSignal.value;
+    return customKey ?? (dh ? `${baseKey}:${dh}` : `${baseKey}:init`);
+  });
+  function getCacheKey() {
+    return cacheKeyComputed.value;
+  }
+  function callThunkWithCapture() {
+    const captured = [];
+    const prevCb = setReadValueCallback((v) => captured.push(v));
+    let promise;
+    try {
+      promise = thunk();
+    } finally {
+      setReadValueCallback(prevCb);
+    }
+    const serialized = captured.map((v) => JSON.stringify(v)).join("|");
+    untrack(() => {
+      depHashSignal.value = hashString(serialized);
+    });
+    return promise;
+  }
+  const data = signal(initialData);
+  const loading = signal(initialData === undefined && enabled);
+  const revalidating = signal(false);
+  const error = signal(undefined);
+  if (initialData !== undefined) {
+    cache.set(getCacheKey(), initialData);
+  }
+  const ssrTimeout = options.ssrTimeout ?? getGlobalSSRTimeout() ?? 300;
+  if (isSSR() && enabled && ssrTimeout !== 0 && initialData === undefined) {
+    const promise = callThunkWithCapture();
+    const key = untrack(() => getCacheKey());
+    const cached = cache.get(key);
+    if (cached !== undefined) {
+      promise.catch(() => {});
+      data.value = cached;
+      loading.value = false;
+    } else {
+      promise.catch(() => {});
+      const register = globalThis.__VERTZ_SSR_REGISTER_QUERY__;
+      if (typeof register === "function") {
+        register({
+          promise,
+          timeout: ssrTimeout,
+          resolve: (result) => {
+            data.value = result;
+            loading.value = false;
+            cache.set(key, result);
+          },
+          key
+        });
+      }
+    }
+  }
+  let ssrHydrationCleanup = null;
+  let ssrHydrated = false;
+  let navPrefetchDeferred = false;
+  if (!isSSR() && enabled && initialData === undefined) {
+    const hydrationKey = customKey ?? baseKey;
+    ssrHydrationCleanup = hydrateQueryFromSSR(hydrationKey, (result) => {
+      data.value = result;
+      loading.value = false;
+      cache.set(hydrationKey, result);
+      ssrHydrated = true;
+    });
+    if (!ssrHydrated && ssrHydrationCleanup !== null && isNavPrefetchActive()) {
+      if (customKey) {
+        const cached = cache.get(customKey);
+        if (cached !== undefined) {
+          data.value = cached;
+          loading.value = false;
+          ssrHydrated = true;
+        }
+      }
+    }
+    if (!ssrHydrated && ssrHydrationCleanup !== null && isNavPrefetchActive()) {
+      navPrefetchDeferred = true;
+      const doneHandler = () => {
+        document.removeEventListener("vertz:nav-prefetch-done", doneHandler);
+        if (data.peek() === undefined) {
+          refetchTrigger.value = refetchTrigger.peek() + 1;
+        }
+      };
+      document.addEventListener("vertz:nav-prefetch-done", doneHandler);
+      const prevCleanup = ssrHydrationCleanup;
+      ssrHydrationCleanup = () => {
+        prevCleanup?.();
+        document.removeEventListener("vertz:nav-prefetch-done", doneHandler);
+      };
+    }
+  }
+  let fetchId = 0;
+  let debounceTimer;
+  const inflightKeys = new Set;
+  const refetchTrigger = signal(0);
+  function handleFetchPromise(promise, id, key) {
+    promise.then((result) => {
+      inflight.delete(key);
+      inflightKeys.delete(key);
+      if (id !== fetchId)
+        return;
+      cache.set(key, result);
+      data.value = result;
+      loading.value = false;
+      revalidating.value = false;
+    }, (err) => {
+      inflight.delete(key);
+      inflightKeys.delete(key);
+      if (id !== fetchId)
+        return;
+      error.value = err;
+      loading.value = false;
+      revalidating.value = false;
+    });
+  }
+  function startFetch(fetchPromise, key) {
+    const id = ++fetchId;
+    untrack(() => {
+      if (data.value !== undefined) {
+        revalidating.value = true;
+      } else {
+        loading.value = true;
+      }
+      error.value = undefined;
+    });
+    const existing = inflight.get(key);
+    if (existing) {
+      handleFetchPromise(existing, id, key);
+      return;
+    }
+    inflight.set(key, fetchPromise);
+    inflightKeys.add(key);
+    handleFetchPromise(fetchPromise, id, key);
+  }
+  function refetch() {
+    const key = getCacheKey();
+    cache.delete(key);
+    inflight.delete(key);
+    refetchTrigger.value = refetchTrigger.peek() + 1;
+  }
+  let disposeFn;
+  if (enabled) {
+    let isFirst = true;
+    disposeFn = lifecycleEffect(() => {
+      refetchTrigger.value;
+      if (isFirst && ssrHydrated) {
+        isFirst = false;
+        return;
+      }
+      if (isFirst && navPrefetchDeferred) {
+        if (customKey) {
+          const cached = untrack(() => cache.get(customKey));
+          if (cached !== undefined) {
+            untrack(() => {
+              data.value = cached;
+              loading.value = false;
+            });
+            isFirst = false;
+            return;
+          }
+        }
+        isFirst = false;
+        return;
+      }
+      if (customKey) {
+        const existing = untrack(() => inflight.get(customKey));
+        if (existing) {
+          const id = ++fetchId;
+          untrack(() => {
+            if (data.value !== undefined) {
+              revalidating.value = true;
+            } else {
+              loading.value = true;
+            }
+            error.value = undefined;
+          });
+          handleFetchPromise(existing, id, customKey);
+          isFirst = false;
+          return;
+        }
+      }
+      const promise = callThunkWithCapture();
+      const key = untrack(() => getCacheKey());
+      if (!customKey) {
+        const existing = untrack(() => inflight.get(key));
+        if (existing) {
+          promise.catch(() => {});
+          const id = ++fetchId;
+          untrack(() => {
+            if (data.value !== undefined) {
+              revalidating.value = true;
+            } else {
+              loading.value = true;
+            }
+            error.value = undefined;
+          });
+          handleFetchPromise(existing, id, key);
+          isFirst = false;
+          return;
+        }
+      }
+      const shouldCheckCache = isFirst ? !!customKey : !customKey;
+      if (shouldCheckCache) {
+        const cached = untrack(() => cache.get(key));
+        if (cached !== undefined) {
+          promise.catch(() => {});
+          untrack(() => {
+            data.value = cached;
+            loading.value = false;
+            error.value = undefined;
+          });
+          isFirst = false;
+          return;
+        }
+      }
+      if (isFirst && initialData !== undefined) {
+        promise.catch(() => {});
+        isFirst = false;
+        return;
+      }
+      isFirst = false;
+      if (debounceMs !== undefined && debounceMs > 0) {
+        clearTimeout(debounceTimer);
+        promise.catch(() => {});
+        debounceTimer = setTimeout(() => {
+          startFetch(promise, key);
+        }, debounceMs);
+      } else {
+        startFetch(promise, key);
+      }
+    });
+  }
+  function dispose() {
+    disposeFn?.();
+    ssrHydrationCleanup?.();
+    clearTimeout(debounceTimer);
+    fetchId++;
+    for (const key of inflightKeys) {
+      inflight.delete(key);
+    }
+    inflightKeys.clear();
+  }
+  _tryOnCleanup(dispose);
+  return {
+    data,
+    loading,
+    revalidating,
+    error,
+    refetch,
+    revalidate: refetch,
+    dispose
+  };
+}
+
+// src/query/query-match.ts
+var cache = new WeakMap;
+function queryMatch(queryResult, handlers) {
+  const key = queryResult;
+  const existing = cache.get(key);
+  if (existing && !existing.disposed) {
+    existing.handlers = handlers;
+    return existing.wrapper;
+  }
+  if (existing) {
+    cache.delete(key);
+  }
+  const wrapper = getAdapter().createElement("span");
+  wrapper.style.display = "contents";
+  const entry = { wrapper, handlers, disposed: false };
+  cache.set(key, entry);
+  let currentBranch = null;
+  let branchCleanups = [];
+  const outerScope = pushScope();
+  domEffect(() => {
+    const isLoading = queryResult.loading.value;
+    const err = queryResult.error.value;
+    const dataValue = queryResult.data.value;
+    let branch;
+    if (isLoading || err === undefined && dataValue === undefined) {
+      branch = "loading";
+    } else if (err !== undefined) {
+      branch = "error";
+    } else {
+      branch = "data";
+    }
+    if (branch === currentBranch && branch !== "data") {
+      return;
+    }
+    runCleanups(branchCleanups);
+    while (wrapper.firstChild) {
+      wrapper.removeChild(wrapper.firstChild);
+    }
+    currentBranch = branch;
+    const scope = pushScope();
+    let branchResult = null;
+    if (branch === "loading") {
+      branchResult = entry.handlers.loading();
+    } else if (branch === "error") {
+      branchResult = entry.handlers.error(err);
+    } else {
+      const dataSignal = queryResult.data;
+      const dataProxy = new Proxy({}, {
+        get(_target, prop, receiver) {
+          const current = dataSignal.value;
+          if (current == null)
+            return;
+          const value = Reflect.get(current, prop, receiver);
+          if (typeof value === "function") {
+            return value.bind(current);
+          }
+          return value;
+        },
+        has(_target, prop) {
+          const current = dataSignal.value;
+          if (current == null)
+            return false;
+          return Reflect.has(current, prop);
+        },
+        ownKeys() {
+          const current = dataSignal.value;
+          if (current == null)
+            return [];
+          return Reflect.ownKeys(current);
+        },
+        getOwnPropertyDescriptor(_target, prop) {
+          const current = dataSignal.value;
+          if (current == null)
+            return;
+          return Reflect.getOwnPropertyDescriptor(current, prop);
+        }
+      });
+      branchResult = entry.handlers.data(dataProxy);
+    }
+    popScope();
+    branchCleanups = scope;
+    if (branchResult != null && isRenderNode(branchResult)) {
+      wrapper.appendChild(branchResult);
+    }
+  });
+  popScope();
+  const dispose = () => {
+    entry.disposed = true;
+    runCleanups(branchCleanups);
+    runCleanups(outerScope);
+    cache.delete(key);
+  };
+  wrapper.dispose = dispose;
+  _tryOnCleanup(dispose);
+  return wrapper;
+}
+
+export { MemoryCache, deriveKey, query, queryMatch };

package/dist/test/index.d.ts

@@ -138,9 +138,34 @@ type ExtractParams<T extends string> = [ExtractParamsFromSegments<WithoutWildcar
 } : Record<string, never> : HasWildcard<T> extends true ? { [K in ExtractParamsFromSegments<WithoutWildcard<T>>] : string } & {
 	"*": string;
 } : { [K in ExtractParamsFromSegments<WithoutWildcard<T>>] : string };
+/**
+* Convert a route pattern to the union of URL shapes it accepts.
+* - Static: `'/'` → `'/'`
+* - Param: `'/tasks/:id'` → `` `/tasks/${string}` ``
+* - Wildcard: `'/files/*'` → `` `/files/${string}` ``
+* - Multi: `'/users/:id/posts/:postId'` → `` `/users/${string}/posts/${string}` ``
+* - Fallback: `string` → `string` (backward compat)
+*/
+type PathWithParams<T extends string> = T extends `${infer Before}*` ? `${PathWithParams<Before>}${string}` : T extends `${infer Before}:${string}/${infer After}` ? `${Before}${string}/${PathWithParams<`${After}`>}` : T extends `${infer Before}:${string}` ? `${Before}${string}` : T;
+/**
+* Union of all valid URL shapes for a route map.
+* Maps each route pattern key through `PathWithParams` to produce the accepted URL shapes.
+*
+* Example:
+* ```
+* RoutePaths<{ '/': ..., '/tasks/:id': ... }> = '/' | `/tasks/${string}`
+* ```
+*/
+type RoutePaths<TRouteMap extends Record<string, unknown>> = { [K in keyof TRouteMap & string] : PathWithParams<K> }[keyof TRouteMap & string];
 /** Simple schema interface for search param parsing. */
 interface SearchParamSchema<T> {
-	parse(data: unknown): T;
+	parse(data: unknown): {
+		ok: true;
+		data: T;
+	} | {
+		ok: false;
+		error: unknown;
+	};
 }
 /** A route configuration for a single path. */
 interface RouteConfig<
@@ -168,6 +193,30 @@ interface RouteConfig<
 interface RouteDefinitionMap {
 	[pattern: string]: RouteConfig;
 }
+/**
+* Loose route config used as the generic constraint for `defineRoutes`.
+* Uses `Record<string, string>` for loader params so any concrete loader
+* that accesses string params (e.g., `params.id`) satisfies the constraint.
+*/
+interface RouteConfigLike {
+	component: () => Node | Promise<{
+		default: () => Node;
+	}>;
+	/**
+	* Method syntax (`loader?(ctx): R`) is intentional — it enables **bivariant**
+	* parameter checking under `strictFunctionTypes`. Property syntax
+	* (`loader?: (ctx) => R`) would be contravariant, causing `RouteConfig<string>`
+	* (whose loader has `params: Record<string, never>`) to fail assignability
+	* against this constraint's `params: Record<string, string>`.
+	*/
+	loader?(ctx: {
+		params: Record<string, string>;
+		signal: AbortSignal;
+	}): unknown;
+	errorComponent?: (error: Error) => Node;
+	searchParams?: SearchParamSchema<unknown>;
+	children?: Record<string, RouteConfigLike>;
+}
 /** Internal compiled route. */
 interface CompiledRoute {
 	/** The original path pattern. */
@@ -219,8 +268,20 @@ interface NavigateOptions {
 	/** Use history.replaceState instead of pushState. */
 	replace?: boolean;
 }
-/** The router instance returned by createRouter. */
-interface Router {
+/**
+* The router instance returned by createRouter.
+*
+* Generic over the route map `T`. Defaults to `RouteDefinitionMap` (string
+* index signature) for backward compatibility — unparameterized `Router`
+* accepts any string in `navigate()`.
+*
+* Method syntax on `navigate`, `revalidate`, and `dispose` enables bivariant
+* parameter checking under `strictFunctionTypes`. This means `Router<T>` is
+* assignable to `Router` (the unparameterized default), which is required for
+* storing typed routers in the `RouterContext` without contravariance errors.
+* At call sites, TypeScript still enforces the `RoutePaths<T>` constraint.
+*/
+interface Router<T extends Record<string, RouteConfigLike> = RouteDefinitionMap> {
 	/** Current matched route (reactive signal). */
 	current: Signal<RouteMatch | null>;
 	/** Loader data from the current route's loaders (reactive signal). */
@@ -230,11 +291,11 @@ interface Router {
 	/** Parsed search params from the current route (reactive signal). */
 	searchParams: Signal<Record<string, unknown>>;
 	/** Navigate to a new URL path. */
-	navigate: (url: string, options?: NavigateOptions) => Promise<void>;
+	navigate(url: RoutePaths<T>, options?: NavigateOptions): Promise<void>;
 	/** Re-run all loaders for the current route. */
-	revalidate: () => Promise<void>;
+	revalidate(): Promise<void>;
 	/** Remove popstate listener and clean up the router. */
-	dispose: () => void;
+	dispose(): void;
 }
 /** Options for `createTestRouter`. */
 interface TestRouterOptions {

package/dist/test/index.js

@@ -1,10 +1,11 @@
 import {
   createRouter
-} from "../shared/chunk-xd9d7q5p.js";
+} from "../shared/chunk-cq7xg4xe.js";
 import {
   defineRoutes
-} from "../shared/chunk-j8vzvne3.js";
-import"../shared/chunk-pgymxpn1.js";
+} from "../shared/chunk-9e92w0wt.js";
+import"../shared/chunk-vx0kzack.js";
+import"../shared/chunk-hrd0mft1.js";
 
 // src/test/interactions.ts
 async function click(el) {