@bractjs/bractjs 0.1.26 → 0.1.28

package/src/client/hooks/useFetcher.ts

@@ -1,27 +1,57 @@
-import { useState } from "react";
+import {
+  createElement, useCallback, useEffect, useId, useMemo, useSyncExternalStore,
+  type FormEvent, type FormHTMLAttributes, type FunctionComponent, type ReactNode,
+} from "react";
 import { toSamePath } from "../nav-utils.ts";
+import { fetcherStore, type FetcherState } from "../fetcher-store.ts";
+import { triggerRevalidation } from "../revalidation.ts";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
-type FetcherState = "idle" | "loading" | "submitting";
-
 interface SubmitOptions {
   method: string;
   body: FormData | Record<string, string>;
 }
 
-interface FetcherResult {
+export interface FetcherFormProps extends Omit<FormHTMLAttributes<HTMLFormElement>, "method" | "onSubmit"> {
+  method?: "post" | "put" | "delete";
+  action?: string;
+  /** Renders a hidden `intent` input (pairs with `defineActions()`). */
+  intent?: string;
+  children: ReactNode;
+}
+
+export interface FetcherResult {
   data: unknown;
   state: FetcherState;
+  /** The submitted FormData while a submission is in flight — the optimistic-UI source. */
+  formData?: FormData;
+  /** Uppercase method of the in-flight/last submission. */
+  formMethod?: string;
+  /** This fetcher's identity (explicit `key` option, or component-bound). */
+  key: string;
   load(path: string): Promise<void>;
   submit(path: string, opts: SubmitOptions): Promise<void>;
+  /** A `<fetcher.Form>` that submits through this fetcher (no navigation, no history). */
+  Form: FunctionComponent<FetcherFormProps>;
 }
 
 interface StreamFetcherResult<T = unknown> {
+  /** @deprecated Never emitted — call `connect(actionId)` instead. Removed in 0.2. */
   events: AsyncGenerator<T>;
   connect(actionId: string): AsyncGenerator<T>;
 }
 
+export interface UseFetcherOptions {
+  /**
+   * Give the fetcher a stable identity. Keyed fetchers persist across
+   * unmounts and are shared by every component using the same key; unkeyed
+   * fetchers are removed from `useFetchers()` when their component unmounts.
+   */
+  key?: string;
+  stream?: boolean;
+}
+
 // ── SSE async generator ────────────────────────────────────────────────────
 
 async function* sseStream<T>(actionId: string): AsyncGenerator<T> {
@@ -66,46 +96,60 @@ async function* sseStream<T>(actionId: string): AsyncGenerator<T> {
 
 // ── Hook ───────────────────────────────────────────────────────────────────
 
-export function useFetcher(): FetcherResult;
+const EMPTY_ENTRY = undefined;
+
+export function useFetcher(opts?: { key?: string }): FetcherResult;
 export function useFetcher<T>(opts: { stream: true }): StreamFetcherResult<T>;
-export function useFetcher<T>(opts?: { stream?: boolean }): FetcherResult | StreamFetcherResult<T> {
-  if (opts?.stream) {
-    return {
-      events: (null as unknown) as AsyncGenerator<T>,
-      connect(actionId: string): AsyncGenerator<T> {
-        return sseStream<T>(actionId);
-      },
-    } satisfies StreamFetcherResult<T>;
-  }
+export function useFetcher<T = unknown>(opts?: UseFetcherOptions): FetcherResult | StreamFetcherResult<T> {
+  // All hooks run unconditionally — branching on opts.stream happens only in
+  // the returned value, so the rules of hooks hold for every variant.
+  const autoKey = useId();
+  const key = opts?.key ?? `__fetcher${autoKey}`;
+
+  const entry = useSyncExternalStore(
+    fetcherStore.subscribe,
+    () => fetcherStore.get(key),
+    () => EMPTY_ENTRY,
+  );
 
-  // eslint-disable-next-line react-hooks/rules-of-hooks
-  const [data, setData] = useState<unknown>(undefined);
-  // eslint-disable-next-line react-hooks/rules-of-hooks
-  const [state, setState] = useState<FetcherState>("idle");
+  // Unkeyed fetchers disappear from useFetchers() with their component; keyed
+  // ones persist so optimistic state survives remounts.
+  const isKeyed = opts?.key !== undefined;
+  useEffect(() => {
+    if (isKeyed) return;
+    return () => fetcherStore.remove(key);
+  }, [key, isKeyed]);
 
-  async function load(path: string): Promise<void> {
-    setState("loading");
+  const load = useCallback(async (path: string): Promise<void> => {
+    fetcherStore.update(key, { state: "loading" });
     try {
       const res = await fetch(`/_data?path=${encodeURIComponent(path)}`);
       const json = (await res.json()) as { route?: unknown };
-      setData(json.route);
+      fetcherStore.update(key, { data: json.route });
     } finally {
-      setState("idle");
+      fetcherStore.update(key, { state: "idle" });
     }
-  }
+  }, [key]);
 
-  async function submit(path: string, submitOpts: SubmitOptions): Promise<void> {
-    setState("submitting");
+  const submit = useCallback(async (path: string, submitOpts: SubmitOptions): Promise<void> => {
+    const body =
+      submitOpts.body instanceof FormData
+        ? submitOpts.body
+        : new URLSearchParams(submitOpts.body as Record<string, string>);
+    const formMethod = submitOpts.method.toUpperCase();
+    // Expose the submission BEFORE the fetch — this is what optimistic UI
+    // renders while the mutation is in flight.
+    fetcherStore.update(key, {
+      state: "submitting",
+      formData: submitOpts.body instanceof FormData ? submitOpts.body : undefined,
+      formMethod,
+    });
     try {
-      const body =
-        submitOpts.body instanceof FormData
-          ? submitOpts.body
-          : new URLSearchParams(submitOpts.body as Record<string, string>);
       // Send the custom header so the server's CSRF gate accepts this
       // same-origin mutation (browsers block it cross-origin without a CORS
       // preflight). Without it every fetcher submit 403s.
       const res = await fetch(path, {
-        method: submitOpts.method,
+        method: formMethod,
         body,
         headers: { "X-BractJS-Action": "1" },
       });
@@ -117,11 +161,50 @@ export function useFetcher<T>(opts?: { stream?: boolean }): FetcherResult | Stre
         window.location.assign(to ?? res.url);
         return;
       }
-      setData(await res.json());
+      fetcherStore.update(key, { data: await res.json() });
+      // Mutations invalidate loader data — re-run the active route's loaders
+      // (gated by its shouldRevalidate) so the page reflects the change.
+      fetcherStore.update(key, { state: "loading" });
+      await triggerRevalidation({ formMethod, actionStatus: res.status });
     } finally {
-      setState("idle");
+      fetcherStore.update(key, { state: "idle", formData: undefined });
     }
+  }, [key]);
+
+  // Stable component identity across renders (remounting a form on every
+  // render would drop focus/IME state).
+  const FetcherForm = useMemo<FunctionComponent<FetcherFormProps>>(() => {
+    return function FetcherFormImpl({ method = "post", action, intent, children, ...rest }: FetcherFormProps) {
+      function handleSubmit(e: FormEvent<HTMLFormElement>) {
+        e.preventDefault();
+        const target = e.currentTarget;
+        const url = action ?? window.location.pathname + window.location.search;
+        void submit(url, { method, body: new FormData(target) });
+      }
+      const intentInput = intent !== undefined
+        ? createElement("input", { key: "__bract_intent", type: "hidden", name: "intent", value: intent })
+        : null;
+      return createElement("form", { method, onSubmit: handleSubmit, ...rest }, intentInput, children);
+    };
+  }, [submit]);
+
+  if (opts?.stream) {
+    return {
+      events: (null as unknown) as AsyncGenerator<T>,
+      connect(actionId: string): AsyncGenerator<T> {
+        return sseStream<T>(actionId);
+      },
+    } satisfies StreamFetcherResult<T>;
   }
 
-  return { data, state, load, submit };
+  return {
+    data: entry?.data,
+    state: entry?.state ?? "idle",
+    formData: entry?.formData,
+    formMethod: entry?.formMethod,
+    key,
+    load,
+    submit,
+    Form: FetcherForm,
+  };
 }

package/src/client/hooks/useFetchers.ts

@@ -0,0 +1,23 @@
+import { useSyncExternalStore } from "react";
+import { fetcherStore, EMPTY_FETCHERS, type FetcherEntry } from "../fetcher-store.ts";
+
+/**
+ * Every active fetcher (keyed and mounted-unkeyed alike) — the cross-component
+ * view for optimistic UI. Example: a table dims each row whose keyed delete
+ * fetcher (`useFetcher({ key: "delete-" + id })`) is currently submitting:
+ *
+ *   const deleting = new Set(
+ *     useFetchers()
+ *       .filter((f) => f.state === "submitting" && f.key.startsWith("delete-"))
+ *       .map((f) => f.key.slice("delete-".length)),
+ *   );
+ *
+ * SSR-safe: renders an empty list on the server.
+ */
+export function useFetchers(): FetcherEntry[] {
+  return useSyncExternalStore(
+    fetcherStore.subscribe,
+    fetcherStore.getSnapshot,
+    () => EMPTY_FETCHERS,
+  );
+}

package/src/client/hooks/useLoaderData.ts

@@ -1,14 +1,18 @@
 import { useContext } from "react";
 import { RouterContext } from "../router.tsx";
 import { BractJSContext } from "../../shared/context.ts";
+import type { LoaderData } from "../../shared/route-types.ts";
 
 /**
- * Returns the current route's loader data, typed as T.
- * Works in both SSR and client contexts.
+ * Returns the current route's loader data. Works in both SSR and client contexts.
+ *
+ * Prefer passing the loader function type — `useLoaderData<typeof loader>()` —
+ * so the data type is inferred from the loader's return (no hand-written type to
+ * keep in sync). An explicit object type still works: `useLoaderData<HomeData>()`.
  */
-export function useLoaderData<T = unknown>(): T {
+export function useLoaderData<T = unknown>(): LoaderData<T> {
   const router = useContext(RouterContext);
   const bract = useContext(BractJSContext);
   const loaderData = router?.loaderData ?? bract?.loaderData ?? {};
-  return loaderData.route as T;
+  return loaderData.route as LoaderData<T>;
 }

package/src/client/hooks/useLocation.ts

@@ -0,0 +1,27 @@
+import { useContext } from "react";
+import { RouterContext } from "../router.tsx";
+import { BractJSContext } from "../../shared/context.ts";
+import type { RouterLocation } from "../../shared/route-types.ts";
+
+/**
+ * The current location: `{ pathname, search, hash, state, key }`.
+ *
+ * Reactive on the client — re-renders on every navigation (including
+ * back/forward). SSR-safe: during server rendering it reflects the request URL
+ * (`hash` is always `""` there, since fragments never reach the server), so
+ * components rendering `pathname`/`search` hydrate without mismatch. Never
+ * reads `window.location` during render.
+ */
+export function useLocation(): RouterLocation {
+  const routerCtx = useContext(RouterContext);
+  const bractCtx = useContext(BractJSContext);
+  if (routerCtx?.location) return routerCtx.location;
+  if (bractCtx?.location) return bractCtx.location;
+  return {
+    pathname: bractCtx?.pathname ?? "/",
+    search: "",
+    hash: "",
+    state: null,
+    key: "default",
+  };
+}

package/src/client/hooks/useNavigate.ts

@@ -0,0 +1,51 @@
+import { useContext, useCallback } from "react";
+import { NavigationContext } from "../router.tsx";
+import { buildPath } from "../build-path.ts";
+import { withSearch } from "../search-serializer.ts";
+import type { RegisteredRoutes, ParamsFor, SearchOutputFor } from "../registry.ts";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export interface NavigateOptions<TTo extends RegisteredRoutes = RegisteredRoutes> {
+  /** Path params for a dynamic `to` (e.g. `{ params: { id } }` for `/blog/:id`). */
+  params?: ParamsFor<TTo>;
+  /** Search params for the target, typed by its `searchSchema` (replaces any query in `to`). */
+  search?: Partial<SearchOutputFor<TTo>>;
+  /** Replace the current history entry instead of pushing a new one. */
+  replace?: boolean;
+  /** Arbitrary history state, readable via `useLocation().state` after navigating. */
+  state?: unknown;
+}
+
+export interface NavigateFn {
+  <TTo extends RegisteredRoutes>(
+    to: TTo | (string & {}),
+    options?: NavigateOptions<TTo>,
+  ): Promise<void>;
+}
+
+// ── Hook ───────────────────────────────────────────────────────────────────
+
+/**
+ * Returns a typed `navigate(to, { params })` for programmatic soft navigation —
+ * the imperative counterpart to `<Link>`. Mirrors `<Link>`'s `to`/`params` API:
+ * `to` autocompletes registered routes (after `bractjs codegen`) while still
+ * accepting any string, and `params` is typed per route.
+ *
+ * SSR-safe and safe outside a `ClientRouter`: with no NavigationContext it
+ * resolves to a no-op (same guard as `<Link>`), so it never throws during render.
+ */
+export function useNavigate(): NavigateFn {
+  const navCtx = useContext(NavigationContext);
+  return useCallback<NavigateFn>(
+    (to, options) => {
+      const base = options?.params
+        ? buildPath(to as string, options.params as Record<string, string>)
+        : (to as string);
+      const href = withSearch(base, options?.search as Record<string, unknown> | undefined);
+      if (!navCtx) return Promise.resolve();
+      return navCtx.navigate(href, { replace: options?.replace, state: options?.state });
+    },
+    [navCtx],
+  );
+}

package/src/client/hooks/useParams.ts

@@ -1,14 +1,25 @@
 import { useContext } from "react";
 import { RouterContext } from "../router.tsx";
 import { BractJSContext } from "../../shared/context.ts";
+import type { ParamsFor } from "../registry.ts";
 
 /**
- * Returns the current route's URL params (e.g. { id: "42" }).
- * Pass a RouteParams<T> generic for typed params: useParams<RouteParams<"/blog/:id">>()
+ * Returns the current route's URL params (e.g. `{ id: "42" }`).
+ *
+ * Pass the route pattern as a generic to type the result against your codegen'd
+ * routes: `useParams<"/blog/:id">()` → `{ id: string }`. The pattern is supplied
+ * by the caller because the framework can't infer the active route at the type
+ * level (React Router's `useParams` has the same limitation). An object generic
+ * — `useParams<{ id: string }>()` — also works for hand-typed shapes.
+ *
  * Works in both SSR and client contexts.
  */
-export function useParams<T extends Record<string, string> = Record<string, string>>(): T {
+// Overload 1: a route literal → params resolved from the registry.
+export function useParams<TTo extends string>(): ParamsFor<TTo>;
+// Overload 2: an explicit object shape (back-compat with the old generic form).
+export function useParams<T extends Record<string, string> = Record<string, string>>(): T;
+export function useParams(): Record<string, string> {
   const router = useContext(RouterContext);
   const bract = useContext(BractJSContext);
-  return (router?.params ?? bract?.params ?? {}) as T;
+  return router?.params ?? bract?.params ?? {};
 }

package/src/client/hooks/useRevalidator.ts

@@ -0,0 +1,26 @@
+import { useContext } from "react";
+import { RouterContext } from "../router.tsx";
+
+export interface Revalidator {
+  /** Re-run the active route's loaders and commit fresh data. */
+  revalidate(): Promise<void>;
+  state: "idle" | "loading";
+}
+
+const noop = async (): Promise<void> => {};
+
+/**
+ * Manually revalidate the current route's loader data — for "Refresh" buttons,
+ * window-focus refetching, polling, or after out-of-band mutations (e.g. a
+ * WebSocket message). Respects the route's `shouldRevalidate` export.
+ *
+ * `state` tracks only revalidation — it does not flip during navigations
+ * (that's `useNavigation()`).
+ *
+ * SSR-safe: without a ClientRouter it returns an idle no-op.
+ */
+export function useRevalidator(): Revalidator {
+  const routerCtx = useContext(RouterContext);
+  if (!routerCtx) return { revalidate: noop, state: "idle" };
+  return { revalidate: routerCtx.revalidate, state: routerCtx.revalidationState };
+}

package/src/client/hooks/useSearch.ts

@@ -0,0 +1,73 @@
+import { useContext, useCallback } from "react";
+import { RouterContext, NavigationContext } from "../router.tsx";
+import { BractJSContext } from "../../shared/context.ts";
+import { serializeSearch } from "../search-serializer.ts";
+import type { SearchOutputFor } from "../registry.ts";
+
+// ── useSearch ──────────────────────────────────────────────────────────────
+
+/**
+ * The current route's VALIDATED search params — the output of its
+ * `searchSchema` export (numbers/booleans/arrays/defaults already applied),
+ * or the raw string record for routes without a schema.
+ *
+ * Validation happens once, on the server; this hook reads the validated object
+ * that rode in with the page (`__BRACTJS_DATA__`) or the last soft-nav
+ * (`/_data`) — the client never re-runs the schema.
+ *
+ * Type it against your codegen'd routes with a route literal —
+ * `useSearch<"/posts">()` → `{ page: number }` — or pass an explicit shape:
+ * `useSearch<{ page: number }>()`. SSR-safe.
+ */
+// Overload 1: a route literal → schema-output shape from the registry.
+export function useSearch<TTo extends string>(): SearchOutputFor<TTo>;
+// Overload 2: an explicit object shape.
+export function useSearch<T extends Record<string, unknown>>(): T;
+export function useSearch(): Record<string, unknown> {
+  const routerCtx = useContext(RouterContext);
+  const bractCtx = useContext(BractJSContext);
+  return routerCtx?.search ?? bractCtx?.search ?? {};
+}
+
+// ── useSetSearch ───────────────────────────────────────────────────────────
+
+export interface SetSearchOptions {
+  /** Replace the current history entry instead of pushing a new one. */
+  replace?: boolean;
+}
+
+export type SetSearchFn<T extends Record<string, unknown>> = (
+  updater: Partial<T> | ((prev: T) => Partial<T>),
+  options?: SetSearchOptions,
+) => Promise<void>;
+
+/**
+ * Returns a setter that merges a patch into the current search params,
+ * serializes the result back into the URL, and soft-navigates — so loaders
+ * re-run and the route's `searchSchema` re-validates server-side. Set a key
+ * to `undefined` to delete it.
+ *
+ *   const setSearch = useSetSearch<"/posts">();
+ *   setSearch({ page: 2 });                       // patch
+ *   setSearch((prev) => ({ page: prev.page + 1 })); // functional
+ *
+ * SSR-safe: without a ClientRouter it resolves to a no-op.
+ */
+export function useSetSearch<TTo extends string>(): SetSearchFn<SearchOutputFor<TTo>>;
+export function useSetSearch<T extends Record<string, unknown>>(): SetSearchFn<T>;
+export function useSetSearch(): SetSearchFn<Record<string, unknown>> {
+  const routerCtx = useContext(RouterContext);
+  const navCtx = useContext(NavigationContext);
+
+  return useCallback<SetSearchFn<Record<string, unknown>>>(
+    (updater, options) => {
+      if (!routerCtx || !navCtx) return Promise.resolve();
+      const prev = routerCtx.search;
+      const patch = typeof updater === "function" ? updater(prev) : updater;
+      const next = { ...prev, ...patch };
+      const target = routerCtx.location.pathname + serializeSearch(next);
+      return navCtx.navigate(target, { replace: options?.replace });
+    },
+    [routerCtx, navCtx],
+  );
+}

package/src/client/hooks/useSearchParams.ts

@@ -1,6 +1,7 @@
 import { useState, useCallback, useEffect, useRef, startTransition } from "react";
 import { NavigationContext } from "../router.tsx";
 import { useContext } from "react";
+import type { SearchFor } from "../registry.ts";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -17,13 +18,27 @@ export interface SearchParamsResult<T extends Record<string, string>> {
 // ── Hook ───────────────────────────────────────────────────────────────────
 
 /**
- * Reads and writes URL search params, typed per-route via generic T.
- * Triggers a loader re-run (soft-nav fetch) when params change.
+ * Low-level read/write of raw `URLSearchParams` (string values only). Triggers a
+ * loader re-run (soft-nav fetch) when params change.
+ *
+ * Prefer `useSearch()` / `useSetSearch()` when the route has a `searchSchema`:
+ * those return the VALIDATED, coerced object (numbers stay numbers, defaults
+ * applied) and accept typed patches. Reach for `useSearchParams` only when you
+ * want raw string access or the route has no schema.
+ *
+ * Pass the route pattern as a generic to type the result against your codegen'd
+ * routes: `useSearchParams<"/posts">()`. Augment `RouteSearchParamsMap` to give a
+ * route a concrete shape (defaults to `Record<string, string>`). The pattern is
+ * supplied by the caller — the framework can't infer the active route at the type
+ * level. An object generic — `useSearchParams<{ page: string }>()` — also works.
  *
- * T is the route's SearchParams shape (e.g. { page: string; sort: string }).
  * This hook is SSR-safe: on the server window is absent, so it returns empty params.
  */
-export function useSearchParams<T extends Record<string, string> = Record<string, string>>(): SearchParamsResult<T> {
+// Overload 1: a route literal → search shape resolved from the registry.
+export function useSearchParams<TTo extends string>(): SearchParamsResult<SearchFor<TTo>>;
+// Overload 2: an explicit object shape (back-compat with the old generic form).
+export function useSearchParams<T extends Record<string, string> = Record<string, string>>(): SearchParamsResult<T>;
+export function useSearchParams(): SearchParamsResult<Record<string, string>> {
   const navCtx = useContext(NavigationContext);
 
   function readCurrent(): URLSearchParams {
@@ -66,8 +81,8 @@ export function useSearchParams<T extends Record<string, string> = Record<string
     }
   }, [navCtx]);
 
-  const getParam = useCallback(<K extends keyof T & string>(key: K): T[K] | null => {
-    return (searchParams.get(key) as T[K] | null);
+  const getParam = useCallback((key: string): string | null => {
+    return searchParams.get(key);
   }, [searchParams]);
 
   return { searchParams, getParam, setSearchParams };

package/src/client/nav-utils.ts

@@ -22,6 +22,32 @@ export function toSamePath(loc: string): string | null {
   }
 }
 
+// ── Navigation target parsing ──────────────────────────────────────────────
+
+/**
+ * Split an internal navigation target ("/path", "/path?q", "/path#h",
+ * "/path?q#h") into its parts. Callers must normalize absolute URLs through
+ * `toSamePath()` first — this is a pure string split, not a URL parser.
+ */
+export function parseTo(to: string): { pathname: string; search: string; hash: string } {
+  const hashIdx = to.indexOf("#");
+  const hash = hashIdx === -1 ? "" : to.slice(hashIdx);
+  const beforeHash = hashIdx === -1 ? to : to.slice(0, hashIdx);
+  const searchIdx = beforeHash.indexOf("?");
+  const search = searchIdx === -1 ? "" : beforeHash.slice(searchIdx);
+  const pathname = searchIdx === -1 ? beforeHash : beforeHash.slice(0, searchIdx);
+  return { pathname: pathname || "/", search, hash };
+}
+
+/** Random short key identifying a history entry (scroll restoration identity). */
+export function createLocationKey(): string {
+  try {
+    return crypto.randomUUID().slice(0, 8);
+  } catch {
+    return Math.random().toString(36).slice(2, 10);
+  }
+}
+
 // ── Pattern Matching ───────────────────────────────────────────────────────
 
 /**