@bractjs/bractjs 0.1.26 → 0.1.28

package/src/client/components/Form.tsx

@@ -1,7 +1,5 @@
 import { useContext, type FormEvent, type ReactNode, type FormHTMLAttributes } from "react";
 import { RouterContext, NavigationContext } from "../router.tsx";
-import { reloadLoaders } from "../form-utils.ts";
-import { toSamePath } from "../nav-utils.ts";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -10,66 +8,57 @@ type FormMethod = "post" | "put" | "delete";
 interface FormProps extends Omit<FormHTMLAttributes<HTMLFormElement>, "method" | "onSubmit"> {
   method?: FormMethod;
   action?: string;
+  /**
+   * Convenience: renders `<input type="hidden" name="intent" value={intent}>`
+   * as the first child, so a single route action can dispatch on it (pairs with
+   * `defineActions()`). Carried on no-JS POSTs too.
+   */
+  intent?: string;
   children: ReactNode;
 }
 
 // ── Component ──────────────────────────────────────────────────────────────
 
-export function Form({ method = "post", action, children, ...rest }: FormProps) {
+export function Form({ method = "post", action, intent, children, ...rest }: FormProps) {
   const routerCtx = useContext(RouterContext);
   const navCtx = useContext(NavigationContext);
+  // The hidden intent input, rendered first so it's part of every submission
+  // (JS and native). `key` keeps React happy alongside arbitrary children.
+  const intentInput = intent !== undefined
+    ? <input key="__bract_intent" type="hidden" name="intent" value={intent} />
+    : null;
 
   // SSR: render a plain form — no JS submit handler needed
   if (!routerCtx || !navCtx) {
     return (
       <form method={method} action={action} {...rest}>
+        {intentInput}
         {children}
       </form>
     );
   }
 
-  const { pathname, setRoute } = routerCtx;
-  const { navigate } = navCtx;
-
-  // setLoaderData shim — updates just the loaderData slice via setRoute
-  function setLoaderData(data: Record<string, unknown>) {
-    setRoute({ loaderData: data });
-  }
+  const { location, setRoute } = routerCtx;
+  const { submit } = navCtx;
 
   async function handleSubmit(e: FormEvent<HTMLFormElement>) {
     e.preventDefault();
     setRoute({ actionData: null }); // clear stale action data
 
     const target = e.currentTarget;
-    const url = action ?? pathname;
-    const formData = new FormData(target);
-
-    const response = await fetch(url, {
-      method: method.toUpperCase(),
-      body: formData,
-      headers: { "X-BractJS-Action": "1" },
-    });
-
-    // The action returned (or threw) a redirect. The browser auto-follows the
-    // 3xx, so `response.url` is the *absolute* final URL — normalize it to a
-    // same-origin path before handing it to the client router, which matches a
-    // route pattern against the pathname (an absolute URL wouldn't match). An
-    // off-origin final URL is NOT handed to the SPA router: fall back to a
-    // full-page navigation so we don't open-redirect through it.
-    if (response.redirected) {
-      const to = toSamePath(response.url);
-      if (to) { await navigate(to); return; }
-      window.location.href = response.url;
-      return;
-    }
+    // Default to the full current URL (pathname + search) so actions can read
+    // the same search params their page was rendered with.
+    const url = action ?? location.pathname + location.search;
 
-    const actionData = (await response.json()) as unknown;
-    setRoute({ actionData });
-    await reloadLoaders(pathname, setLoaderData);
+    // The router's submit drives useNavigation() through "submitting" →
+    // "loading" → "idle", commits the action data, follows redirects safely
+    // (CSRF header + same-origin guard), and revalidates loaders.
+    await submit(url, { method, body: new FormData(target) });
   }
 
   return (
     <form method={method} onSubmit={(e) => { void handleSubmit(e); }} {...rest}>
+      {intentInput}
       {children}
     </form>
   );

package/src/client/components/Link.tsx

@@ -1,16 +1,49 @@
-import { useContext, type AnchorHTMLAttributes, type ReactNode } from "react";
+import {
+  useContext, useEffect, useRef, useCallback,
+  type AnchorHTMLAttributes, type ReactNode,
+} from "react";
 import { NavigationContext, RouterContext } from "../router.tsx";
-import { prefetchRoute } from "../prefetch.ts";
+import { prefetchRoute, observeOnce } from "../prefetch.ts";
+import { buildPath } from "../build-path.ts";
+import { withSearch } from "../search-serializer.ts";
+import type { RegisteredRoutes, ParamsFor, SearchOutputFor } from "../registry.ts";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
-interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
-  to: string;
-  prefetch?: "hover" | "none";
+/**
+ * When to prefetch the target route's chunk + loader data:
+ * - `"none"` (default) — never.
+ * - `"intent"` — on hover/focus, after a short delay (canceled if the pointer
+ *   leaves). The best default for most links.
+ * - `"hover"` — immediately on mouseenter (legacy alias of intent without the
+ *   delay; kept for back-compat).
+ * - `"viewport"` — when the link scrolls into view (shared
+ *   IntersectionObserver). Good for lists.
+ * - `"render"` — as soon as the link mounts.
+ */
+type PrefetchMode = "none" | "intent" | "hover" | "viewport" | "render";
+
+// `to` accepts any registered route literal (autocomplete + typed `params`) but
+// also any string via `(string & {})`, so existing call sites that build the URL
+// themselves — `to={`/posts/${slug}`}`, `to={item.href}` — keep compiling. Run
+// `bractjs codegen` to register the app's routes and unlock autocomplete; until
+// then `RegisteredRoutes` is `string` and this is just today's loose prop.
+type LinkProps<TTo extends RegisteredRoutes = RegisteredRoutes> = Omit<
+  AnchorHTMLAttributes<HTMLAnchorElement>,
+  "href"
+> & {
+  to: TTo | (string & {});
+  /** 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>>;
+  prefetch?: PrefetchMode;
   /** Opt in to View Transitions API for this navigation (E1). */
   viewTransition?: boolean;
+  /** Replace the current history entry instead of pushing. */
+  replace?: boolean;
   children: ReactNode;
-}
+};
 
 // ── Component ──────────────────────────────────────────────────────────────
 
@@ -19,11 +52,51 @@ const supportsViewTransitions =
   typeof document !== "undefined" &&
   typeof (document as Document & { startViewTransition?: unknown }).startViewTransition === "function";
 
-export function Link({ to, prefetch = "none", viewTransition = false, children, ...rest }: LinkProps) {
+/** Hover-intent delay before prefetching — cancels on a fly-by pointer. */
+const INTENT_DELAY_MS = 100;
+
+export function Link<TTo extends RegisteredRoutes = RegisteredRoutes>({
+  to,
+  params,
+  search,
+  prefetch = "none",
+  viewTransition = false,
+  replace,
+  children,
+  ...rest
+}: LinkProps<TTo>) {
   const navCtx = useContext(NavigationContext);
   const routerCtx = useContext(RouterContext);
   const isLoading = navCtx?.state === "loading";
 
+  // Resolve the final href once: substitute params into a dynamic pattern, or
+  // pass an already-built string straight through; then apply `search`.
+  const base = params ? buildPath(to as string, params as Record<string, string>) : (to as string);
+  const href = withSearch(base, search as Record<string, unknown> | undefined);
+
+  const anchorRef = useRef<HTMLAnchorElement>(null);
+  const intentTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const triggerPrefetch = useCallback(() => {
+    if (routerCtx) void prefetchRoute(href, routerCtx.manifest);
+  }, [href, routerCtx]);
+
+  // viewport / render modes register in an effect — SSR renders a plain <a>.
+  useEffect(() => {
+    if (prefetch === "render") {
+      triggerPrefetch();
+      return;
+    }
+    if (prefetch === "viewport" && anchorRef.current) {
+      return observeOnce(anchorRef.current, triggerPrefetch);
+    }
+  }, [prefetch, triggerPrefetch]);
+
+  // Cancel a pending intent timer on unmount.
+  useEffect(() => () => {
+    if (intentTimer.current) clearTimeout(intentTimer.current);
+  }, []);
+
   function handleClick(e: React.MouseEvent<HTMLAnchorElement>) {
     if (!navCtx) return; // SSR: let browser handle naturally
     if (e.ctrlKey || e.metaKey || e.shiftKey || e.altKey) return;
@@ -31,22 +104,43 @@ export function Link({ to, prefetch = "none", viewTransition = false, children,
 
     if (viewTransition && supportsViewTransitions) {
       (document as Document & { startViewTransition(cb: () => void): void }).startViewTransition(
-        () => { void navCtx.navigate(to); },
+        () => { void navCtx.navigate(href, { replace }); },
       );
     } else {
-      void navCtx.navigate(to);
+      void navCtx.navigate(href, { replace });
+    }
+  }
+
+  function startIntent() {
+    if (prefetch !== "intent" || intentTimer.current) return;
+    intentTimer.current = setTimeout(() => {
+      intentTimer.current = null;
+      triggerPrefetch();
+    }, INTENT_DELAY_MS);
+  }
+
+  function cancelIntent() {
+    if (intentTimer.current) {
+      clearTimeout(intentTimer.current);
+      intentTimer.current = null;
     }
   }
 
   function handleMouseEnter() {
-    if (prefetch === "hover" && routerCtx) prefetchRoute(to, routerCtx.manifest);
+    if (prefetch === "hover") triggerPrefetch();
+    else startIntent();
   }
 
   return (
     <a
-      href={to}
+      href={href}
+      ref={anchorRef}
       onClick={handleClick}
       onMouseEnter={handleMouseEnter}
+      onMouseLeave={cancelIntent}
+      onFocus={startIntent}
+      onBlur={cancelIntent}
+      onTouchStart={prefetch === "intent" || prefetch === "hover" ? triggerPrefetch : undefined}
       aria-disabled={isLoading || undefined}
       {...rest}
     >

package/src/client/components/Outlet.tsx

@@ -41,8 +41,14 @@ export function Outlet(): ReactElement | null {
   // Server-side (SSR): fall back to BractJSContext which carries RouteComponent
   const bractCtx = useContext(BractJSContext);
 
-  const RouteComponent: ComponentType | undefined =
-    routerCtx?.currentModule?.default ?? bractCtx?.RouteComponent;
+  // While selective-SSR hydration is pending, render exactly what the server
+  // sent: the route's Fallback ("client-only"/"data-only" documents) or
+  // nothing (the "spa" shell knows no route at build time). Rendering the real
+  // component here would mismatch the server HTML.
+  const pending = routerCtx?.hydrationPending;
+  const RouteComponent: ComponentType | undefined = pending
+    ? (pending === "spa" ? undefined : routerCtx?.currentModule?.Fallback)
+    : routerCtx?.currentModule?.default ?? bractCtx?.RouteComponent;
   const ErrorFallback: ComponentType<{ error: Error }> =
     routerCtx?.currentModule?.ErrorBoundary ?? DefaultErrorFallback;
 

package/src/client/components/ScrollRestoration.tsx

@@ -0,0 +1,125 @@
+import { useEffect, useLayoutEffect, useRef } from "react";
+import { useLocation } from "../hooks/useLocation.ts";
+import type { RouterLocation } from "../../shared/route-types.ts";
+import {
+  SCROLL_STORAGE_KEY,
+  savePosition,
+  serializePositions,
+  deserializePositions,
+} from "../scroll-restoration.ts";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export interface ScrollRestorationProps {
+  /**
+   * Derive the storage key for a location. Defaults to `location.key` (one
+   * position per history entry). Return e.g. `location.pathname` to share one
+   * position across every visit to the same path.
+   */
+  getKey?: (location: RouterLocation) => string;
+  /** sessionStorage key holding the persisted positions. */
+  storageKey?: string;
+}
+
+// ── Component ──────────────────────────────────────────────────────────────
+
+// useLayoutEffect warns during SSR; the component renders nothing and the
+// effect only matters in the browser, so alias it away on the server.
+const useBrowserLayoutEffect = typeof document !== "undefined" ? useLayoutEffect : useEffect;
+
+/**
+ * Emulates the browser's scroll restoration on soft navigations. Render it
+ * once in `app/root.tsx` (next to `<Scripts />`).
+ *
+ * Behavior: returning to a history entry (back/forward, reload) restores its
+ * saved scroll position; navigating to a new entry scrolls to the top, or to
+ * the `#fragment` element when the target has one. Positions are tracked from
+ * scroll events (so the leaving page's offset is never lost to layout
+ * clamping) and persisted to sessionStorage across reloads.
+ */
+export function ScrollRestoration({ getKey, storageKey = SCROLL_STORAGE_KEY }: ScrollRestorationProps): null {
+  const location = useLocation();
+
+  const getKeyRef = useRef(getKey);
+  useEffect(() => { getKeyRef.current = getKey; });
+
+  // Lazily hydrated from sessionStorage on first access — the restore layout
+  // effect runs before mount effects, so eager hydration would come too late.
+  const positionsRef = useRef<Map<string, number> | null>(null);
+  const getPositions = (): Map<string, number> => {
+    if (positionsRef.current === null) {
+      positionsRef.current = deserializePositions(sessionStorage.getItem(storageKey));
+    }
+    return positionsRef.current;
+  };
+
+  /** Storage key of the entry currently on screen (what scroll events record). */
+  const activeKeyRef = useRef<string | null>(null);
+
+  // Take manual control + persist across reloads/full navigations.
+  useEffect(() => {
+    if ("scrollRestoration" in history) history.scrollRestoration = "manual";
+    const persist = () => {
+      if (positionsRef.current !== null) {
+        try {
+          sessionStorage.setItem(storageKey, serializePositions(positionsRef.current));
+        } catch {
+          // Storage full/blocked — restoration degrades to in-memory only.
+        }
+      }
+    };
+    window.addEventListener("pagehide", persist);
+    return () => {
+      window.removeEventListener("pagehide", persist);
+      persist();
+    };
+  }, [storageKey]);
+
+  // Continuously record the active entry's position (rAF-throttled). Recording
+  // from scroll events — rather than snapshotting at navigation time — means
+  // the position is already saved before the new page's (possibly shorter)
+  // content clamps window.scrollY.
+  useEffect(() => {
+    let frame = 0;
+    const onScroll = () => {
+      if (frame) return;
+      frame = requestAnimationFrame(() => {
+        frame = 0;
+        if (activeKeyRef.current !== null) {
+          savePosition(getPositions(), activeKeyRef.current, window.scrollY);
+        }
+      });
+    };
+    window.addEventListener("scroll", onScroll, { passive: true });
+    return () => {
+      window.removeEventListener("scroll", onScroll);
+      if (frame) cancelAnimationFrame(frame);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // Apply scroll on every committed location change (and on first mount, which
+  // restores the position after a reload).
+  useBrowserLayoutEffect(() => {
+    const key = getKeyRef.current ? getKeyRef.current(location) : location.key;
+    if (activeKeyRef.current === key) return;
+    activeKeyRef.current = key;
+
+    const saved = getPositions().get(key);
+    if (typeof saved === "number") {
+      window.scrollTo(0, saved);
+      return;
+    }
+    if (location.hash) {
+      const el = document.getElementById(location.hash.slice(1));
+      if (el) {
+        el.scrollIntoView();
+        return;
+      }
+    }
+    window.scrollTo(0, 0);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [location]);
+
+  return null;
+}

package/src/client/entry.tsx

@@ -20,6 +20,25 @@ function FallbackApp(): ReactElement {
 (async () => {
   const data: BractJSClientData = window.__BRACTJS_DATA__;
 
+  // Dev-only: surface a loader error captured during SSR in the error overlay.
+  // safeRun serializes failures as `{ __error: { message, stack, routeFile } }`
+  // into each loader slot; this is the overlay's producer (the overlay script
+  // installs a __BRACTJS_ERROR__ setter but nothing assigned it before).
+  if ((window as unknown as { __BRACT_DEV__?: boolean }).__BRACT_DEV__) {
+    const slots = [data.loaderData?.root, data.loaderData?.route, ...((data.loaderData?.layouts as unknown[]) ?? [])];
+    for (const slot of slots) {
+      const e = (slot as { __error?: { message?: string; stack?: string; routeFile?: string } } | null)?.__error;
+      if (e) {
+        const where = e.routeFile ? ` in ${e.routeFile}` : "";
+        (window as unknown as { __BRACTJS_ERROR__?: unknown }).__BRACTJS_ERROR__ = {
+          message: `Loader error${where}: ${e.message ?? "unknown error"}`,
+          stack: e.stack,
+        };
+        break;
+      }
+    }
+  }
+
   // 1. Import the root component (app/root.tsx) so the client tree matches
   //    the server-rendered shell (html, head, body, header, nav, etc.).
   let RootComponent: ComponentType = FallbackApp;
@@ -28,9 +47,13 @@ function FallbackApp(): ReactElement {
     if (rootMod.default) RootComponent = rootMod.default;
   }
 
+  // The SPA shell is built once for "/" and served for every document path —
+  // the browser URL, not the payload, says where we actually are.
+  const initialPathname = data.ssrMode === "spa" ? window.location.pathname : data.pathname;
+
   // 2. Pre-load the current route module so <Outlet> sees it during hydration.
   let initialModule: RouteModuleClient | null = null;
-  const pattern = matchPatternForPath(data.pathname, data.manifest);
+  const pattern = matchPatternForPath(initialPathname, data.manifest);
   const chunkUrl = pattern !== null ? data.manifest.routes[pattern]?.chunk : undefined;
 
   if (chunkUrl) {
@@ -40,9 +63,23 @@ function FallbackApp(): ReactElement {
     initialModule = (await import(url)) as RouteModuleClient;
   }
 
+  // Initial location: pathname comes from the server payload; search is
+  // identical to the request's by construction. The hash never reaches the
+  // server, so it is only known here.
+  const initialLocation = {
+    pathname: initialPathname,
+    search: window.location.search,
+    hash: window.location.hash,
+    state: null,
+    key: "default",
+  };
+
   hydrateRoot(
     document,
-    <ClientRouter initialData={data} initialModule={initialModule}>
+    <ClientRouter
+      initialData={{ ...data, location: initialLocation, search: data.search ?? {} }}
+      initialModule={initialModule}
+    >
       <RootComponent />
     </ClientRouter>,
   );

package/src/client/fetcher-store.ts

@@ -0,0 +1,61 @@
+// Module-level fetcher state, shaped for React's useSyncExternalStore. Giving
+// fetchers identity outside component state is what makes optimistic UI work:
+// a keyed fetcher survives remounts, and `useFetchers()` lets any component
+// observe every in-flight mutation (e.g. dim a list row while its delete
+// fetcher is submitting elsewhere in the tree).
+
+export type FetcherState = "idle" | "loading" | "submitting";
+
+export interface FetcherEntry {
+  key: string;
+  state: FetcherState;
+  data: unknown;
+  /** The submitted form data, available from the moment submit() is called — read this for optimistic UI. */
+  formData?: FormData;
+  /** Uppercase HTTP method of the in-flight/last submission. */
+  formMethod?: string;
+}
+
+type Listener = () => void;
+
+const IDLE_ENTRY: Omit<FetcherEntry, "key"> = { state: "idle", data: undefined };
+
+class FetcherStore {
+  private entries = new Map<string, FetcherEntry>();
+  private listeners = new Set<Listener>();
+  // Snapshots must be referentially stable between emits or
+  // useSyncExternalStore loops. Rebuilt only inside emit().
+  private snapshot: FetcherEntry[] = [];
+
+  get(key: string): FetcherEntry | undefined {
+    return this.entries.get(key);
+  }
+
+  update(key: string, partial: Partial<Omit<FetcherEntry, "key">>): void {
+    const prev = this.entries.get(key) ?? { key, ...IDLE_ENTRY };
+    this.entries.set(key, { ...prev, ...partial });
+    this.emit();
+  }
+
+  remove(key: string): void {
+    if (this.entries.delete(key)) this.emit();
+  }
+
+  subscribe = (listener: Listener): (() => void) => {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+
+  /** All current entries (stable reference between updates). */
+  getSnapshot = (): FetcherEntry[] => this.snapshot;
+
+  private emit(): void {
+    this.snapshot = Array.from(this.entries.values());
+    for (const listener of this.listeners) listener();
+  }
+}
+
+export const fetcherStore = new FetcherStore();
+
+/** Stable server snapshot — SSR renders with no active fetchers. */
+export const EMPTY_FETCHERS: FetcherEntry[] = [];

package/src/client/form-utils.ts

@@ -1,5 +1,8 @@
 /**
  * Fetches fresh loader data for a pathname and updates the router context.
+ *
+ * @deprecated `<Form>` now revalidates through the router (see
+ * `useRevalidator`); kept only for callers that imported this directly.
  */
 export async function reloadLoaders(
   pathname: string,

package/src/client/hooks/useActionData.ts

@@ -1,14 +1,18 @@
 import { useContext } from "react";
 import { RouterContext } from "../router.tsx";
 import { BractJSContext } from "../../shared/context.ts";
+import type { ActionData } from "../../shared/route-types.ts";
 
 /**
- * Returns the current route's action data, typed as T | null.
+ * Returns the current route's action data, or null until an action has run.
  * Works in both SSR and client contexts.
+ *
+ * Prefer passing the action function type — `useActionData<typeof action>()` —
+ * so the type is inferred from the action's return. An explicit type still works.
  */
-export function useActionData<T = unknown>(): T | null {
+export function useActionData<T = unknown>(): ActionData<T> | null {
   const router = useContext(RouterContext);
   const bract = useContext(BractJSContext);
   const actionData = router?.actionData ?? bract?.actionData ?? null;
-  return actionData as T | null;
+  return actionData as ActionData<T> | null;
 }