toiljs 0.0.7 → 0.0.9

package/src/client/routing/Router.tsx

@@ -9,27 +9,120 @@ import {
     resolveLayout,
     resolveNotFound,
 } from './lazy.js';
-import { LoaderDataContext, readRouteData } from './loader.js';
+import { loaderKey, LoaderDataContext, readRouteData } from './loader.js';
 import { matchRoute, type RouteParams } from './match.js';
+import { useRouteHead } from '../head/head.js';
 import { ParamsContext } from './params-context.js';
-import { navigationEpoch, settleNavigation } from '../navigation/navigation.js';
+import { SlotContext } from './slot-context.js';
+import {
+    isSoftNavigation,
+    navigationEpoch,
+    previousPathname,
+    settleNavigation,
+} from '../navigation/navigation.js';
 import { applyScroll } from '../navigation/scroll.js';
 import type { ErrorComponentLoader, LayoutLoader, NotFoundLoader, RouteDef } from '../types.js';
 
 /** Loads a matched route's module + loader data (suspending), then renders it with the data in context. */
-function RoutePage(props: { route: RouteDef; params: RouteParams; dataKey: string }): ReactNode {
-    const { Component, data } = readRouteData(props.route, props.params, props.dataKey);
+function RoutePage(props: {
+    route: RouteDef;
+    params: RouteParams;
+    dataKey: string;
+    epoch: number;
+}): ReactNode {
+    const { Component, data, head } = readRouteData(props.route, props.params, props.dataKey, props.epoch);
+    useRouteHead(head);
     return <LoaderDataContext.Provider value={data}>{createElement(Component)}</LoaderDataContext.Provider>;
 }
 
+/**
+ * Wraps a matched route's page in its loading boundary, templates, nested layouts, and error
+ * boundary. `keyPrefix` namespaces the loader-cache key and boundary keys so a parallel slot and the
+ * main route can match the same URL without colliding.
+ */
+function renderMatched(
+    matched: RouteDef,
+    params: RouteParams,
+    pathname: string,
+    epoch: number,
+    keyPrefix: string,
+): ReactNode {
+    const search = typeof window === 'undefined' ? '' : window.location.search;
+    const dataKey = keyPrefix + loaderKey(pathname, search);
+    const fallback: ReactNode = matched.loading
+        ? createElement(Suspense, { fallback: null }, createElement(loadingComponent(matched.loading)))
+        : null;
+
+    // A route with a `loading.tsx` keys its boundary per URL *and* navigation epoch, so its fallback
+    // shows even inside the transition, on first nav and on an in-place revalidate of the same URL
+    // (the epoch bumps). A route without one keeps a stable boundary so the transition holds the old
+    // page. The loader cache key stays the bare URL, so the boundary remount still reuses cached data.
+    let content: ReactNode = (
+        <Suspense
+            key={matched.loading ? `${dataKey}:${String(epoch)}` : undefined}
+            fallback={fallback}>
+            <RoutePage
+                route={matched}
+                params={params}
+                dataKey={dataKey}
+                epoch={epoch}
+            />
+        </Suspense>
+    );
+    // Templates wrap inside the layouts and re-mount on every navigation (keyed by URL).
+    const templates = matched.templates ?? [];
+    for (let i = templates.length - 1; i >= 0; i--) {
+        const Template = nestedLayout(templates[i]);
+        content = (
+            <Suspense
+                key={`${keyPrefix}${pathname}:${String(i)}`}
+                fallback={null}>
+                <Template>{content}</Template>
+            </Suspense>
+        );
+    }
+    // Nested layouts, deepest first so the shallowest ends up outermost.
+    const chain = matched.layouts ?? [];
+    for (let i = chain.length - 1; i >= 0; i--) {
+        const NestedLayout = nestedLayout(chain[i]);
+        content = (
+            <Suspense fallback={null}>
+                <NestedLayout>{content}</NestedLayout>
+            </Suspense>
+        );
+    }
+    if (matched.errorComponent) {
+        content = <ErrorBoundary fallback={errorComponent(matched.errorComponent)}>{content}</ErrorBoundary>;
+    }
+    return content;
+}
+
+/**
+ * Finds the first route (already specificity-sorted) matching `pathname`. Intercepting routes are
+ * skipped unless `allowIntercept`, they only apply on soft navigation.
+ */
+function match(
+    routes: RouteDef[],
+    pathname: string,
+    allowIntercept = true,
+): { route: RouteDef; params: RouteParams } | null {
+    for (const route of routes) {
+        if (route.intercept && !allowIntercept) continue;
+        const params = matchRoute(route.pattern, pathname);
+        if (params) return { route, params };
+    }
+    return null;
+}
+
 /** Matches the current location to a route and renders it, optionally wrapped in the root layout. */
 export function Router(props: {
     routes: RouteDef[];
     layout?: LayoutLoader;
     notFound?: NotFoundLoader;
     globalError?: ErrorComponentLoader;
+    slots?: Record<string, RouteDef[]>;
 }): ReactNode {
-    const { routes, layout = null, notFound = null, globalError = null } = props;
+    const { routes, layout = null, notFound = null, globalError = null, slots = {} } = props;
     const pathname = useLocation();
 
     // After each navigation commits, apply the planned scroll (top / restore / #hash) and mark the
@@ -39,64 +132,33 @@ export function Router(props: {
         settleNavigation();
     });
 
-    let matched: RouteDef | undefined;
-    let params: RouteParams = {};
-    for (const route of routes) {
-        const result = matchRoute(route.pattern, pathname);
-        if (result) {
-            matched = route;
-            params = result;
-            break;
-        }
+    const epoch = navigationEpoch();
+    const soft = isSoftNavigation();
+
+    // Parallel slots: each `@slot` tree matches the current URL independently (intercepting routes
+    // only on soft navigation). Each match is exposed by name via SlotContext and rendered wherever a
+    // layout/page places a `Slot`. If an intercepting route matches, the main view holds the previous
+    // page (the backdrop) while the slot shows the intercepted route, i.e. a modal overlay.
+    const slotElements: Record<string, ReactNode> = {};
+    let intercepting = false;
+    for (const [name, defs] of Object.entries(slots)) {
+        const slotMatch = match(defs, pathname, soft);
+        if (!slotMatch) continue;
+        if (slotMatch.route.intercept) intercepting = true;
+        slotElements[name] = (
+            <ParamsContext.Provider value={slotMatch.params}>
+                {renderMatched(slotMatch.route, slotMatch.params, pathname, epoch, `@${name} `)}
+            </ParamsContext.Provider>
+        );
     }
 
+    const mainPath = intercepting ? previousPathname() : pathname;
+    const matched = match(routes, mainPath);
+    const params: RouteParams = matched?.params ?? {};
+
     let content: ReactNode;
     if (matched) {
-        const fallback: ReactNode = matched.loading
-            ? createElement(Suspense, { fallback: null }, createElement(loadingComponent(matched.loading)))
-            : null;
-        const search = typeof window === 'undefined' ? '' : window.location.search;
-        const dataKey = `${String(navigationEpoch())}:${pathname}${search}`;
-        content = (
-            <Suspense fallback={fallback}>
-                <RoutePage
-                    route={matched}
-                    params={params}
-                    dataKey={dataKey}
-                />
-            </Suspense>
-        );
-        // Wrap in templates, deepest first so the shallowest ends up outermost. Templates sit
-        // inside the layouts and are keyed by pathname so they re-mount on every navigation
-        // (resetting their state), unlike layouts which persist across navigations.
-        const templates = matched.templates ?? [];
-        for (let i = templates.length - 1; i >= 0; i--) {
-            const Template = nestedLayout(templates[i]);
-            content = (
-                <Suspense
-                    key={`${pathname}:${String(i)}`}
-                    fallback={null}>
-                    <Template>{content}</Template>
-                </Suspense>
-            );
-        }
-        // Wrap in nested layouts, deepest first so the shallowest ends up outermost.
-        const chain = matched.layouts ?? [];
-        for (let i = chain.length - 1; i >= 0; i--) {
-            const NestedLayout = nestedLayout(chain[i]);
-            content = (
-                <Suspense fallback={null}>
-                    <NestedLayout>{content}</NestedLayout>
-                </Suspense>
-            );
-        }
-        if (matched.errorComponent) {
-            content = (
-                <ErrorBoundary fallback={errorComponent(matched.errorComponent)}>
-                    {content}
-                </ErrorBoundary>
-            );
-        }
+        content = renderMatched(matched.route, matched.params, mainPath, epoch, '');
     } else if (notFound) {
         const NotFound = resolveNotFound(notFound);
         content = (
@@ -105,7 +167,7 @@ export function Router(props: {
             </Suspense>
         );
     } else {
-        content = <div style={{ padding: 24, fontFamily: 'system-ui' }}>404 — Not found</div>;
+        content = <div style={{ padding: 24, fontFamily: 'system-ui' }}>404, Not found</div>;
     }
 
     if (layout) {
@@ -118,10 +180,14 @@ export function Router(props: {
     }
 
     // The root error boundary (global-error.tsx) sits outside the root layout, so it catches
-    // errors thrown by the layout itself — the last line of defense before a blank screen.
+    // errors thrown by the layout itself, the last line of defense before a blank screen.
     if (globalError) {
         content = <ErrorBoundary fallback={errorComponent(globalError)}>{content}</ErrorBoundary>;
     }
 
-    return <ParamsContext.Provider value={params}>{content}</ParamsContext.Provider>;
+    return (
+        <ParamsContext.Provider value={params}>
+            <SlotContext.Provider value={slotElements}>{content}</SlotContext.Provider>
+        </ParamsContext.Provider>
+    );
 }

package/src/client/routing/action.ts

@@ -0,0 +1,122 @@
+/**
+ * Mutations (writes), the counterpart to loaders (reads). A loader fetches data on navigation;
+ * an action performs a write (save, delete, a server/WASM call) on demand, then revalidates the
+ * affected loader data so the UI reflects the change. `useAction` tracks pending/error/result state;
+ * `<Form>` is sugar over it for the form case.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { invalidateLoaderData } from './loader.js';
+import { refresh } from '../navigation/navigation.js';
+import type { Href } from '../types.js';
+
+/**
+ * Which loader data to refetch after an action succeeds:
+ * - `true` (default), the current route.
+ * - an `Href` (or array), those specific routes.
+ * - `false`, nothing.
+ */
+export type RevalidateTarget = boolean | Href | readonly Href[];
+
+/** Options for {@link useAction}. */
+export interface UseActionOptions<TData> {
+    /** Loader data to revalidate after success. Default `true` (the current route). */
+    readonly revalidate?: RevalidateTarget;
+    /** Called after a successful run, with the action's return value. */
+    readonly onSuccess?: (data: TData) => void;
+    /** Called when the action throws. */
+    readonly onError?: (error: unknown) => void;
+}
+
+/** Live state of an action. */
+export interface ActionState<TData> {
+    /** True while a run is in flight. */
+    readonly pending: boolean;
+    /** The error from the last failed run, or `undefined`. */
+    readonly error: unknown;
+    /** The value returned by the last successful run, or `undefined`. */
+    readonly data: TData | undefined;
+}
+
+/** Handle returned by {@link useAction}: current state plus `run` / `reset`. */
+export interface ActionHandle<TInput, TData> extends ActionState<TData> {
+    /**
+     * Run the action. Resolves to the result on success, or `undefined` if it threw (the error is
+     * captured in `error` instead of rejecting, so a fire-and-forget `onClick` can't leak an
+     * unhandled rejection).
+     */
+    run: (input: TInput) => Promise<TData | undefined>;
+    /** Reset back to idle (clears `pending` / `error` / `data`). */
+    reset: () => void;
+}
+
+/** Refetches loader data per a {@link RevalidateTarget}, then re-renders once. */
+function applyRevalidate(target: RevalidateTarget | undefined): void {
+    if (target === false) return;
+    if (target === undefined || target === true) {
+        invalidateLoaderData();
+    } else {
+        const hrefs = typeof target === 'string' ? [target] : target;
+        for (const href of hrefs) invalidateLoaderData(href);
+    }
+    refresh();
+}
+
+/**
+ * Runs a mutation with pending/error/result tracking, revalidating loader data on success. Example:
+ *
+ * ```ts
+ * const save = useAction((title: string) => api.save(title), { revalidate: true });
+ * <button disabled={save.pending} onClick={() => void save.run(title)}>Save</button>
+ * ```
+ */
+export function useAction<TInput = void, TData = unknown>(
+    fn: (input: TInput) => TData | Promise<TData>,
+    options: UseActionOptions<TData> = {},
+): ActionHandle<TInput, TData> {
+    const [state, setState] = useState<ActionState<TData>>({
+        pending: false,
+        error: undefined,
+        data: undefined,
+    });
+
+    // Hold the latest fn/options so `run` keeps a stable identity across renders.
+    const latest = useRef({ fn, options });
+    latest.current = { fn, options };
+    const runId = useRef(0);
+    const mounted = useRef(true);
+    useEffect(
+        () => () => {
+            mounted.current = false;
+        },
+        [],
+    );
+
+    const run = useCallback(async (input: TInput): Promise<TData | undefined> => {
+        const id = ++runId.current;
+        setState((s) => ({ ...s, pending: true, error: undefined }));
+        try {
+            const data = await latest.current.fn(input);
+            // Ignore a stale run that a newer one (or unmount) has superseded.
+            if (mounted.current && id === runId.current) {
+                setState({ pending: false, error: undefined, data });
+            }
+            applyRevalidate(latest.current.options.revalidate);
+            latest.current.options.onSuccess?.(data);
+            return data;
+        } catch (error) {
+            if (mounted.current && id === runId.current) {
+                setState({ pending: false, error, data: undefined });
+            }
+            latest.current.options.onError?.(error);
+            return undefined;
+        }
+    }, []);
+
+    const reset = useCallback(() => {
+        runId.current += 1;
+        setState({ pending: false, error: undefined, data: undefined });
+    }, []);
+
+    return { ...state, run, reset };
+}

package/src/client/routing/error-boundary.tsx

@@ -12,7 +12,7 @@ interface ErrorBoundaryState {
 
 /**
  * Catches render errors in its subtree and shows the route's `error.tsx` (with a `reset` to retry).
- * Error boundaries must be class components — React has no hook equivalent.
+ * Error boundaries must be class components, React has no hook equivalent.
  */
 export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
     state: ErrorBoundaryState = { error: null };

package/src/client/routing/hooks.ts

@@ -2,14 +2,7 @@
  * Router hooks for user route components: read the params / pathname / search params, navigate
  * imperatively, and grab a router handle.
  */
-import {
-    startTransition,
-    useContext,
-    useEffect,
-    useMemo,
-    useReducer,
-    useSyncExternalStore,
-} from 'react';
+import { useContext, useEffect, useMemo, useReducer, useSyncExternalStore } from 'react';
 
 import type { RouteParams } from './match.js';
 import {
@@ -22,7 +15,7 @@ import {
     subscribePending,
     type NavigateOptions,
 } from '../navigation/navigation.js';
-import { clearLoaderData } from './loader.js';
+import { clearLoaderData, revalidate as revalidateData } from './loader.js';
 import { ParamsContext } from './params-context.js';
 import { prefetch } from '../navigation/prefetch.js';
 import type { Href } from '../types.js';
@@ -37,8 +30,13 @@ export interface RouterInstance {
     back(): void;
     /** Go forward one history entry. */
     forward(): void;
-    /** Re-render the current route and re-run its loader. */
+    /** Re-render the current route and re-run its loader (clears all cached loader data). */
     refresh(): void;
+    /**
+     * Invalidate cached loader data and re-render so it refetches. No argument refetches the active
+     * route; pass an `href` to target a specific route. Use after a mutation.
+     */
+    revalidate(href?: Href): void;
     /** Prefetch a route's chunk ahead of navigation. */
     prefetch(href: Href): void;
 }
@@ -56,6 +54,9 @@ const ROUTER: RouterInstance = {
         clearLoaderData();
         refresh();
     },
+    revalidate: (href) => {
+        revalidateData(href);
+    },
     prefetch,
 };
 
@@ -75,21 +76,14 @@ export function useRouter(): RouterInstance {
 }
 
 /**
- * Subscribes to location changes (in a transition, so the current page stays on screen while the
- * next chunk loads) and reads the live `window.location` on render. Re-renders on any pathname,
- * search, or hash change.
+ * Subscribes to location changes and reads the live `window.location` on render. Re-renders on any
+ * pathname, search, or hash change. The re-render is orchestrated by `navigate`/`notify` (wrapped in
+ * `startTransition` for smooth nav, or `document.startViewTransition` when enabled), so the listener
+ * itself is a plain force-update.
  */
 function useLocationSubscription(): void {
     const [, forceUpdate] = useReducer((n: number): number => n + 1, 0);
-    useEffect(
-        () =>
-            subscribeLocation(() => {
-                startTransition(() => {
-                    forceUpdate();
-                });
-            }),
-        [],
-    );
+    useEffect(() => subscribeLocation(forceUpdate), []);
 }
 
 /** Subscribes to and returns the current `location.pathname`. */
@@ -110,7 +104,7 @@ export function useSearchParams(): URLSearchParams {
     return useMemo(() => new URLSearchParams(search), [search]);
 }
 
-/** True while a navigation is in flight (started but not yet committed) — e.g. for a loading bar. */
+/** True while a navigation is in flight (started but not yet committed), e.g. for a loading bar. */
 export function useNavigationPending(): boolean {
     return useSyncExternalStore(
         subscribePending,