@vertz/ui 0.2.0

package/dist/shared/chunk-zbbvx05f.js

@@ -0,0 +1,202 @@
+import {
+  computed,
+  effect,
+  setReadValueCallback,
+  signal,
+  untrack
+} from "./chunk-pgymxpn1.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);
+  }
+}
+
+// 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
+var defaultCache = new MemoryCache;
+var inflight = new Map;
+function query(thunk, options = {}) {
+  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 error = signal(undefined);
+  if (initialData !== undefined) {
+    cache.set(getCacheKey(), initialData);
+  }
+  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;
+    }, (err) => {
+      inflight.delete(key);
+      inflightKeys.delete(key);
+      if (id !== fetchId)
+        return;
+      error.value = err;
+      loading.value = false;
+    });
+  }
+  function startFetch(fetchPromise, key) {
+    const id = ++fetchId;
+    untrack(() => {
+      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 = effect(() => {
+      refetchTrigger.value;
+      if (customKey) {
+        const existing = untrack(() => inflight.get(customKey));
+        if (existing) {
+          const id = ++fetchId;
+          untrack(() => {
+            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(() => {
+            loading.value = true;
+            error.value = undefined;
+          });
+          handleFetchPromise(existing, id, key);
+          isFirst = false;
+          return;
+        }
+      }
+      if (!isFirst && !customKey) {
+        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?.();
+    clearTimeout(debounceTimer);
+    fetchId++;
+    for (const key of inflightKeys) {
+      inflight.delete(key);
+    }
+    inflightKeys.clear();
+  }
+  return {
+    data,
+    loading,
+    error,
+    refetch,
+    revalidate: refetch,
+    dispose
+  };
+}
+
+export { MemoryCache, deriveKey, query };

package/dist/test/index.d.ts

@@ -0,0 +1,268 @@
+/**
+* User interaction simulation utilities for testing Vertz UI components.
+*
+* Dispatches real DOM events so that event listeners set up with `__on`
+* (or plain addEventListener) fire as they would in a browser.
+*/
+/**
+* Simulate a mouse click on the given element.
+*
+* Dispatches a `click` MouseEvent that bubbles and is cancelable,
+* matching browser behavior.
+*/
+declare function click(el: Element): Promise<void>;
+/**
+* Simulate a keyboard key press.
+*
+* Dispatches `keydown` followed by `keyup` on the currently active
+* element (or `document.body` if nothing is focused).
+*/
+declare function press(key: string): Promise<void>;
+/**
+* Fill form fields by name with the provided values.
+*
+* Looks up each key in `data` as a form element `[name="<key>"]` inside
+* the given `<form>` and sets its value. Dispatches `input` and `change`
+* events on each field so reactive bindings pick up the new values.
+*
+* Supported element types:
+* - `<input>` (text, email, password, etc.) — sets `.value`
+* - `<input type="checkbox">` — sets `.checked` (`"true"` / `"false"`)
+* - `<input type="radio">` — checks the radio whose `.value` matches
+* - `<textarea>` — sets `.value`
+* - `<select>` — sets `.value`
+*
+* @throws {TypeError} If `formEl` is not an `HTMLFormElement`.
+* @throws {TypeError} If a named field in `data` does not exist in the form.
+*/
+declare function fillForm(formEl: HTMLFormElement, data: Record<string, string>): Promise<void>;
+/**
+* Trigger form submission by dispatching a `submit` event.
+*
+* The event bubbles and is cancelable, matching browser behavior.
+* Test handlers can call `event.preventDefault()` to prevent default
+* form navigation.
+*
+* @throws {TypeError} If `formEl` is not an `HTMLFormElement`.
+*/
+declare function submitForm(formEl: HTMLFormElement): Promise<void>;
+/**
+* DOM query utilities for testing Vertz UI components.
+*
+* Provides helpers to locate elements by text content or test IDs,
+* plus an async `waitFor` poller for assertions on async updates.
+*/
+/**
+* Find a descendant element whose text content matches `text`.
+* Throws if no match is found.
+*/
+declare function findByText2(container: Element, text: string): HTMLElement;
+/**
+* Find a descendant element whose text content matches `text`.
+* Returns null if no match is found.
+*/
+declare function queryByText2(container: Element, text: string): HTMLElement | null;
+/**
+* Find a descendant element with `data-testid="<id>"`.
+* Throws if no match is found.
+*/
+declare function findByTestId2(container: Element, id: string): HTMLElement;
+/**
+* Find a descendant element with `data-testid="<id>"`.
+* Returns null if no match is found.
+*/
+declare function queryByTestId2(container: Element, id: string): HTMLElement | null;
+/** Options for `waitFor`. */
+interface WaitForOptions {
+	/** Maximum time in ms to wait before throwing (default 1000). */
+	timeout?: number;
+	/** Polling interval in ms (default 50). */
+	interval?: number;
+}
+/**
+* Poll an assertion function until it passes or times out.
+*
+* Useful for waiting on async DOM updates driven by signals or loaders.
+*/
+declare function waitFor(assertion: () => void, opts?: WaitForOptions): Promise<void>;
+/** The result returned by `renderTest()`. */
+interface RenderTestResult {
+	/** The container element that wraps the rendered component. */
+	container: HTMLElement;
+	/** Find an element by its text content. Throws if not found. */
+	findByText: (text: string) => HTMLElement;
+	/** Find an element by its text content. Returns null if not found. */
+	queryByText: (text: string) => HTMLElement | null;
+	/** Find an element by `data-testid`. Throws if not found. */
+	findByTestId: (id: string) => HTMLElement;
+	/** Find an element by `data-testid`. Returns null if not found. */
+	queryByTestId: (id: string) => HTMLElement | null;
+	/** Simulate a click on the given element. */
+	click: (el: Element) => Promise<void>;
+	/** Simulate typing text into an input element. */
+	type: (el: Element, text: string) => Promise<void>;
+	/** Remove the container from the DOM and clean up. */
+	unmount: () => void;
+}
+/**
+* Render a component (Element or DocumentFragment) into a fresh container
+* attached to `document.body`.
+*
+* Returns scoped query and interaction helpers for the rendered tree.
+*/
+declare function renderTest(component: Element | DocumentFragment): RenderTestResult;
+/**
+* Template literal type utility that extracts route parameter names from a path pattern.
+*
+* Examples:
+* - `'/users/:id'` -> `{ id: string }`
+* - `'/users/:id/posts/:postId'` -> `{ id: string; postId: string }`
+* - `'/files/*'` -> `{ '*': string }`
+* - `'/users'` -> `Record<string, never>`
+*/
+/** Extract param names from a single segment. */
+type ExtractSegmentParam<S extends string> = S extends `:${infer Param}` ? Param : never;
+/** Recursively extract params from path segments separated by '/'. */
+type ExtractParamsFromSegments<T extends string> = T extends `${infer Segment}/${infer Rest}` ? ExtractSegmentParam<Segment> | ExtractParamsFromSegments<Rest> : ExtractSegmentParam<T>;
+/** Check if a path contains a wildcard '*' at the end. */
+type HasWildcard<T extends string> = T extends `${string}*` ? true : false;
+/** Remove trailing wildcard for param extraction. */
+type WithoutWildcard<T extends string> = T extends `${infer Before}*` ? Before : T;
+/**
+* Extract typed params from a route path pattern.
+* `:param` segments become `{ param: string }`.
+* A trailing `*` becomes `{ '*': string }`.
+*/
+type ExtractParams<T extends string> = [ExtractParamsFromSegments<WithoutWildcard<T>>] extends [never] ? HasWildcard<T> extends true ? {
+	"*": string;
+} : Record<string, never> : HasWildcard<T> extends true ? { [K in ExtractParamsFromSegments<WithoutWildcard<T>>] : string } & {
+	"*": string;
+} : { [K in ExtractParamsFromSegments<WithoutWildcard<T>>] : string };
+/** Simple schema interface for search param parsing. */
+interface SearchParamSchema<T> {
+	parse(data: unknown): T;
+}
+/** A route configuration for a single path. */
+interface RouteConfig<
+	TPath extends string = string,
+	TLoaderData = unknown,
+	TSearch = unknown
+> {
+	/** Component factory (lazy for code splitting). */
+	component: () => Node | Promise<{
+		default: () => Node;
+	}>;
+	/** Optional loader that runs before render. */
+	loader?: (ctx: {
+		params: ExtractParams<TPath>;
+		signal: AbortSignal;
+	}) => Promise<TLoaderData> | TLoaderData;
+	/** Optional error component rendered when loader throws. */
+	errorComponent?: (error: Error) => Node;
+	/** Optional search params schema for validation/coercion. */
+	searchParams?: SearchParamSchema<TSearch>;
+	/** Nested child routes. */
+	children?: RouteDefinitionMap;
+}
+/** A map of path patterns to route configs (user input format). */
+interface RouteDefinitionMap {
+	[pattern: string]: RouteConfig;
+}
+/** Internal compiled route. */
+interface CompiledRoute {
+	/** The original path pattern. */
+	pattern: string;
+	/** The route config. */
+	component: RouteConfig["component"];
+	loader?: (ctx: {
+		params: Record<string, string>;
+		signal: AbortSignal;
+	}) => Promise<unknown> | unknown;
+	errorComponent?: RouteConfig["errorComponent"];
+	searchParams?: RouteConfig["searchParams"];
+	/** Compiled children. */
+	children?: CompiledRoute[];
+}
+/** A single matched route entry in the matched chain. */
+interface MatchedRoute {
+	route: CompiledRoute;
+	params: Record<string, string>;
+}
+/** Result of matching a URL against the route tree. */
+interface RouteMatch {
+	/** All params extracted from the full URL path. */
+	params: Record<string, string>;
+	/** The leaf route config that matched. */
+	route: CompiledRoute;
+	/** The chain of matched routes from root to leaf (for nested layouts). */
+	matched: MatchedRoute[];
+	/** URLSearchParams from the URL. */
+	searchParams: URLSearchParams;
+	/** Parsed/coerced search params if schema is defined. */
+	search: Record<string, unknown>;
+}
+/**
+* A reactive signal that holds a value and notifies subscribers on change.
+*/
+interface Signal<T> {
+	/** Get the current value and subscribe to changes (when inside a tracking context). */
+	get value(): T;
+	/** Set the current value and notify subscribers if changed. */
+	set value(newValue: T);
+	/** Read the current value without subscribing (no tracking). */
+	peek(): T;
+	/** Manually notify all subscribers (useful after mutating the value in place). */
+	notify(): void;
+}
+/** Options for router.navigate(). */
+interface NavigateOptions {
+	/** Use history.replaceState instead of pushState. */
+	replace?: boolean;
+}
+/** The router instance returned by createRouter. */
+interface Router {
+	/** Current matched route (reactive signal). */
+	current: Signal<RouteMatch | null>;
+	/** Loader data from the current route's loaders (reactive signal). */
+	loaderData: Signal<unknown[]>;
+	/** Loader error if any loader threw (reactive signal). */
+	loaderError: Signal<Error | null>;
+	/** 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>;
+	/** Re-run all loaders for the current route. */
+	revalidate: () => Promise<void>;
+	/** Remove popstate listener and clean up the router. */
+	dispose: () => void;
+}
+/** Options for `createTestRouter`. */
+interface TestRouterOptions {
+	/** The initial URL path to navigate to (default "/"). */
+	initialPath?: string;
+}
+/** Result returned by `createTestRouter`. */
+interface TestRouterResult {
+	/** A container element that holds the route's rendered component. */
+	component: Element;
+	/** The underlying router instance. */
+	router: Router;
+	/** Navigate to a new path (wraps router.navigate). */
+	navigate: (path: string) => Promise<void>;
+}
+/**
+* Create a test router with the given route definitions.
+*
+* The router is initialized at `initialPath` (default "/") and the
+* matched route's component is resolved and returned in `component`.
+*
+* @example
+* ```ts
+* const { component, router, navigate } = await createTestRouter({
+*   '/': { component: () => { const el = document.createElement('div'); el.textContent = 'Home'; return el; } },
+*   '/about': { component: () => { const el = document.createElement('div'); el.textContent = 'About'; return el; } },
+* });
+* ```
+*/
+declare function createTestRouter(routes: RouteDefinitionMap, opts?: TestRouterOptions): Promise<TestRouterResult>;
+export { waitFor, submitForm, renderTest, queryByText2 as queryByText, queryByTestId2 as queryByTestId, press, findByText2 as findByText, findByTestId2 as findByTestId, fillForm, createTestRouter, click, WaitForOptions, TestRouterResult, TestRouterOptions, RenderTestResult };

package/dist/test/index.js

@@ -0,0 +1,236 @@
+import {
+  createRouter
+} from "../shared/chunk-xd9d7q5p.js";
+import {
+  defineRoutes
+} from "../shared/chunk-j8vzvne3.js";
+import"../shared/chunk-pgymxpn1.js";
+
+// src/test/interactions.ts
+async function click(el) {
+  el.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
+  await Promise.resolve();
+}
+async function type(el, text) {
+  const target = typeof el === "string" ? document.querySelector(el) : el;
+  if (!target) {
+    throw new TypeError(`type: element not found${typeof el === "string" ? ` for selector "${el}"` : ""}`);
+  }
+  if (!isInputLike(target)) {
+    throw new TypeError("type: element is not an <input> or <textarea>");
+  }
+  target.value = text;
+  target.dispatchEvent(new Event("input", { bubbles: true }));
+  target.dispatchEvent(new Event("change", { bubbles: true }));
+  await Promise.resolve();
+}
+async function press(key) {
+  const target = document.activeElement ?? document.body;
+  target.dispatchEvent(new KeyboardEvent("keydown", { key, bubbles: true, cancelable: true }));
+  target.dispatchEvent(new KeyboardEvent("keyup", { key, bubbles: true, cancelable: true }));
+  await Promise.resolve();
+}
+async function fillForm(formEl, data) {
+  if (!(formEl instanceof HTMLFormElement)) {
+    throw new TypeError("fillForm: first argument must be an <form> element");
+  }
+  for (const [name, value] of Object.entries(data)) {
+    const elements = formEl.querySelectorAll(`[name="${name}"]`);
+    if (elements.length === 0) {
+      throw new TypeError(`fillForm: no element found with name "${name}" in the form`);
+    }
+    const first = elements[0];
+    if (first instanceof HTMLInputElement && first.type === "radio") {
+      let matched = false;
+      for (const el of elements) {
+        if (el instanceof HTMLInputElement && el.type === "radio") {
+          const shouldCheck = el.value === value;
+          el.checked = shouldCheck;
+          if (shouldCheck) {
+            el.dispatchEvent(new Event("input", { bubbles: true }));
+            el.dispatchEvent(new Event("change", { bubbles: true }));
+            matched = true;
+          }
+        }
+      }
+      if (!matched) {
+        throw new TypeError(`fillForm: no radio button with name "${name}" has value "${value}"`);
+      }
+      continue;
+    }
+    if (first instanceof HTMLInputElement && first.type === "checkbox") {
+      first.checked = value === "true";
+      first.dispatchEvent(new Event("input", { bubbles: true }));
+      first.dispatchEvent(new Event("change", { bubbles: true }));
+      continue;
+    }
+    if (first instanceof HTMLSelectElement) {
+      first.value = value;
+      first.dispatchEvent(new Event("input", { bubbles: true }));
+      first.dispatchEvent(new Event("change", { bubbles: true }));
+      continue;
+    }
+    if (first instanceof HTMLInputElement || first instanceof HTMLTextAreaElement) {
+      first.value = value;
+      first.dispatchEvent(new Event("input", { bubbles: true }));
+      first.dispatchEvent(new Event("change", { bubbles: true }));
+      continue;
+    }
+    throw new TypeError(`fillForm: element with name "${name}" is not a supported form field type`);
+  }
+  await Promise.resolve();
+}
+async function submitForm(formEl) {
+  if (!(formEl instanceof HTMLFormElement)) {
+    throw new TypeError("submitForm: argument must be a <form> element");
+  }
+  formEl.dispatchEvent(new Event("submit", { bubbles: true, cancelable: true }));
+  await Promise.resolve();
+}
+function isInputLike(el) {
+  const tag = el.tagName.toLowerCase();
+  return tag === "input" || tag === "textarea";
+}
+// src/test/queries.ts
+function findByText(container, text) {
+  const el = queryByText(container, text);
+  if (!el) {
+    throw new TypeError(`findByText: no element found with text "${text}"`);
+  }
+  return el;
+}
+function queryByText(container, text) {
+  const walker = document.createTreeWalker(container, NodeFilter.SHOW_ELEMENT);
+  let node = walker.currentNode;
+  while (node) {
+    if (hasDirectTextMatch(node, text)) {
+      return node;
+    }
+    const next = walker.nextNode();
+    if (!next)
+      break;
+    node = next;
+  }
+  return queryByTextContent(container, text);
+}
+function hasDirectTextMatch(el, text) {
+  for (const child of el.childNodes) {
+    if (child.nodeType === Node.TEXT_NODE && child.textContent?.trim() === text) {
+      return true;
+    }
+  }
+  return false;
+}
+function queryByTextContent(container, text) {
+  let best = null;
+  const walker = document.createTreeWalker(container, NodeFilter.SHOW_ELEMENT);
+  let node = walker.currentNode;
+  while (node) {
+    if (node.textContent?.trim() === text) {
+      best = node;
+    }
+    const next = walker.nextNode();
+    if (!next)
+      break;
+    node = next;
+  }
+  return best;
+}
+function findByTestId(container, id) {
+  const el = queryByTestId(container, id);
+  if (!el) {
+    throw new TypeError(`findByTestId: no element found with data-testid="${id}"`);
+  }
+  return el;
+}
+function queryByTestId(container, id) {
+  return container.querySelector(`[data-testid="${id}"]`);
+}
+async function waitFor(assertion, opts) {
+  const timeout = opts?.timeout ?? 1000;
+  const interval = opts?.interval ?? 50;
+  const deadline = Date.now() + timeout;
+  let lastError;
+  while (Date.now() < deadline) {
+    try {
+      assertion();
+      return;
+    } catch (err) {
+      lastError = err;
+    }
+    await sleep(interval);
+  }
+  try {
+    assertion();
+  } catch {
+    throw lastError instanceof Error ? lastError : new TypeError(`waitFor timed out after ${timeout}ms`);
+  }
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// src/test/render-test.ts
+function renderTest(component) {
+  const container = document.createElement("div");
+  container.setAttribute("data-testid", "render-test-container");
+  container.appendChild(component);
+  document.body.appendChild(container);
+  return {
+    click,
+    container,
+    findByTestId: (id) => findByTestId(container, id),
+    findByText: (text) => findByText(container, text),
+    queryByTestId: (id) => queryByTestId(container, id),
+    queryByText: (text) => queryByText(container, text),
+    type,
+    unmount() {
+      container.remove();
+    }
+  };
+}
+// src/test/test-router.ts
+async function createTestRouter(routes, opts) {
+  const initialPath = opts?.initialPath ?? "/";
+  window.history.replaceState(null, "", initialPath);
+  const compiled = defineRoutes(routes);
+  const router = createRouter(compiled, initialPath);
+  const container = document.createElement("div");
+  container.setAttribute("data-testid", "test-router-container");
+  await renderCurrentRoute(router, container);
+  async function navigate(path) {
+    await router.navigate(path);
+    await renderCurrentRoute(router, container);
+  }
+  return { component: container, navigate, router };
+}
+async function renderCurrentRoute(router, container) {
+  while (container.firstChild) {
+    container.removeChild(container.firstChild);
+  }
+  const match = router.current.value;
+  if (!match)
+    return;
+  const componentResult = match.route.component();
+  let node;
+  if (componentResult instanceof Promise) {
+    const mod = await componentResult;
+    node = mod.default();
+  } else {
+    node = componentResult;
+  }
+  container.appendChild(node);
+}
+export {
+  waitFor,
+  type,
+  submitForm,
+  renderTest,
+  queryByText,
+  queryByTestId,
+  press,
+  findByText,
+  findByTestId,
+  fillForm,
+  createTestRouter,
+  click
+};