toiljs 0.0.116 → 0.0.118

package/src/client/routing/Router.tsx

@@ -1,216 +0,0 @@
-import { createElement, type ReactNode, Suspense, useLayoutEffect } from 'react';
-
-import { ErrorBoundary } from './error-boundary.js';
-import { useLocation } from './hooks.js';
-import {
-    errorComponent,
-    loadingComponent,
-    nestedLayout,
-    resolveLayout,
-    resolveNotFound,
-} from './lazy.js';
-import { LoaderDataContext, loaderKey, readRouteData } from './loader.js';
-import { matchRoute, type RouteParams } from './match.js';
-import { useRouteHead } from '../head/head.js';
-import { ParamsContext } from './params-context.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;
-    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 (key `undefined`): the Suspense
-    // must NOT be remounted on navigation, or it becomes a freshly-mounted boundary with no committed
-    // content and React shows its (null) fallback during the next route's chunk/loader load, i.e. a
-    // blank flash, even inside the transition. With a stable boundary the transition holds the old
-    // page until the next one is ready. The loader cache key stays the bare URL, so reused data hits.
-    // The page itself is keyed by URL so each route mounts fresh (no state bleed between routes); it
-    // lives INSIDE the boundary so that re-mount doesn't tear down the boundary above it.
-    let content: ReactNode = (
-        <Suspense
-            key={matched.loading ? `${dataKey}:${String(epoch)}` : undefined}
-            fallback={fallback}>
-            <RoutePage
-                key={dataKey}
-                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, slots = {} } = props;
-    const pathname = useLocation();
-
-    // After each navigation commits, apply the planned scroll (top / restore / #hash) and mark the
-    // navigation settled. A layout effect runs before paint, so the scroll lands without a flash.
-    useLayoutEffect(() => {
-        applyScroll();
-        settleNavigation();
-    });
-
-    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) {
-        content = renderMatched(matched.route, matched.params, mainPath, epoch, '');
-    } else if (notFound) {
-        const NotFound = resolveNotFound(notFound);
-        content = (
-            <Suspense fallback={null}>
-                <NotFound />
-            </Suspense>
-        );
-    } else {
-        content = <div style={{ padding: 24, fontFamily: 'system-ui' }}>404, Not found</div>;
-    }
-
-    if (layout) {
-        const Layout = resolveLayout(layout);
-        content = (
-            <Suspense fallback={null}>
-                <Layout>{content}</Layout>
-            </Suspense>
-        );
-    }
-
-    // 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.
-    if (globalError) {
-        content = <ErrorBoundary fallback={errorComponent(globalError)}>{content}</ErrorBoundary>;
-    }
-
-    return (
-        <ParamsContext.Provider value={params}>
-            <SlotContext.Provider value={slotElements}>{content}</SlotContext.Provider>
-        </ParamsContext.Provider>
-    );
-}

package/src/client/routing/action.ts

@@ -1,122 +0,0 @@
-/**
- * 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

@@ -1,43 +0,0 @@
-import { Component, type ComponentType, type ReactNode, Suspense } from 'react';
-
-import type { RouteErrorProps } from '../types.js';
-
-interface ErrorBoundaryProps {
-    readonly fallback: ComponentType<RouteErrorProps>;
-    readonly children: ReactNode;
-}
-interface ErrorBoundaryState {
-    readonly error: Error | null;
-}
-
-/**
- * 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.
- */
-export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
-    state: ErrorBoundaryState = { error: null };
-
-    static getDerivedStateFromError(error: Error): ErrorBoundaryState {
-        return { error };
-    }
-
-    reset = (): void => {
-        this.setState({ error: null });
-    };
-
-    render(): ReactNode {
-        const { error } = this.state;
-        if (error) {
-            const Fallback = this.props.fallback;
-            return (
-                <Suspense fallback={null}>
-                    <Fallback
-                        error={error}
-                        reset={this.reset}
-                    />
-                </Suspense>
-            );
-        }
-        return this.props.children;
-    }
-}

package/src/client/routing/hooks.ts

@@ -1,140 +0,0 @@
-/**
- * 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 type { RouteParams } from './match.js';
-import {
-    back,
-    forward,
-    isNavigationPending,
-    navigate,
-    type NavigateOptions,
-    refresh,
-    subscribeLocation,
-    subscribePending,
-} from '../navigation/navigation.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';
-
-/** Imperative router handle returned by {@link useRouter}. */
-export interface RouterInstance {
-    /** Navigate to `href`, pushing a new history entry (or replacing with `{ replace: true }`). */
-    push(href: Href, options?: NavigateOptions): void;
-    /** Navigate to `href`, replacing the current history entry. */
-    replace(href: Href): void;
-    /** Go back one history entry. */
-    back(): void;
-    /** Go forward one history entry. */
-    forward(): void;
-    /** 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;
-}
-
-const ROUTER: RouterInstance = {
-    push: (href, options) => {
-        navigate(href, options);
-    },
-    replace: (href) => {
-        navigate(href, { replace: true });
-    },
-    back,
-    forward,
-    refresh: () => {
-        clearLoaderData();
-        refresh();
-    },
-    revalidate: (href) => {
-        revalidateData(href);
-    },
-    prefetch,
-};
-
-/** Current dynamic route params, e.g. `{ id }` inside `/blog/:id`. Pass a shape: `useParams<{ id: string }>()`. */
-export function useParams<T extends RouteParams = RouteParams>(): T {
-    return useContext(ParamsContext) as T;
-}
-
-/** Returns the imperative `navigate(href, { replace })` function. */
-export function useNavigate(): typeof navigate {
-    return navigate;
-}
-
-/** Returns the router handle (`push` / `replace` / `back` / `forward` / `refresh` / `prefetch`). */
-export function useRouter(): RouterInstance {
-    return ROUTER;
-}
-
-/**
- * Subscribes to location changes and reads the live `window.location` on render. The re-render runs
- * inside `startTransition` so React keeps the current page visible while the next route's chunk and
- * loader resolve (committing the new tree only once it's ready), instead of committing a suspended
- * tree and flashing an empty page on every link click.
- */
-function useLocationSubscription(): void {
-    const [, forceUpdate] = useReducer((n: number): number => n + 1, 0);
-    useEffect(
-        () =>
-            subscribeLocation(() => {
-                startTransition(() => {
-                    forceUpdate();
-                });
-            }),
-        [],
-    );
-}
-
-/** Build-only override for the SSR pathname, set by the template extractor per route via
- * {@link __setSsrLocation}. Lets location-dependent markup (a `NavLink`'s active class /
- * `aria-current`) render as the route's own URL so it matches what the client computes on
- * hydration, instead of the `/` default. Ignored in the browser (the live URL wins). */
-let ssrLocationOverride: string | null = null;
-
-/** Build-only: set the pathname the extractor is currently rendering (or `null` to clear).
- * No effect in the browser. Exported through `toiljs/client` for the compiler. */
-export function __setSsrLocation(path: string | null): void {
-    ssrLocationOverride = path;
-}
-
-/** Subscribes to and returns the current `location.pathname`. SSR-safe: during a
- *  server render there is no `window`, so it reports the extractor's override (the route
- *  being rendered) or `/`; the client recomputes on hydration. */
-export function useLocation(): string {
-    useLocationSubscription();
-    if (typeof window === 'undefined') return ssrLocationOverride ?? '/';
-    return window.location.pathname;
-}
-
-/** Alias of {@link useLocation}: the current `location.pathname`. */
-export function usePathname(): string {
-    return useLocation();
-}
-
-/** The current query string as a `URLSearchParams`, re-read on every navigation. */
-export function useSearchParams(): URLSearchParams {
-    useLocationSubscription();
-    const search = typeof window === 'undefined' ? '' : window.location.search;
-    return useMemo(() => new URLSearchParams(search), [search]);
-}
-
-/** 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, isNavigationPending, () => false);
-}

package/src/client/routing/lazy.ts

@@ -1,77 +0,0 @@
-/**
- * Lazy-component resolution and caching. Each page/layout/not-found loader is wrapped in
- * `React.lazy` exactly once and memoized, so re-renders reuse the same component (and React's
- * Suspense cache) instead of re-creating it. Keyed by loader identity.
- */
-import { type ComponentType, lazy, type ReactNode } from 'react';
-
-import type {
-    LayoutComponentLoader,
-    LayoutLoader,
-    NotFoundLoader,
-    RouteErrorProps,
-} from '../types.js';
-
-type Loader<P> = () => Promise<{ default: ComponentType<P> }>;
-
-/** Memoizes `lazy()` per loader identity in `cache`. */
-function memoLazy<P>(cache: Map<Loader<P>, ComponentType<P>>, loader: Loader<P>): ComponentType<P> {
-    let component = cache.get(loader);
-    if (!component) {
-        component = lazy(loader);
-        cache.set(loader, component);
-    }
-    return component;
-}
-
-const loadingCache = new Map<Loader<object>, ComponentType<object>>();
-/** Memoized lazy component for a route's `loading.tsx`. */
-export function loadingComponent(loader: Loader<object>): ComponentType<object> {
-    return memoLazy(loadingCache, loader);
-}
-
-const errorCache = new Map<Loader<RouteErrorProps>, ComponentType<RouteErrorProps>>();
-/** Memoized lazy component for a route's `error.tsx`. */
-export function errorComponent(loader: Loader<RouteErrorProps>): ComponentType<RouteErrorProps> {
-    return memoLazy(errorCache, loader);
-}
-
-let layoutComponent: ComponentType<{ children?: ReactNode }> | null = null;
-let layoutLoader: LayoutLoader = null;
-
-/** Returns the memoized lazy root-layout component, rebuilding only if the loader identity changes. */
-export function resolveLayout(
-    loader: NonNullable<LayoutLoader>,
-): ComponentType<{ children?: ReactNode }> {
-    if (layoutLoader !== loader || !layoutComponent) {
-        layoutComponent = lazy(loader);
-        layoutLoader = loader;
-    }
-    return layoutComponent;
-}
-
-const nestedLayoutCache = new Map<LayoutComponentLoader, ComponentType<{ children?: ReactNode }>>();
-
-/** Returns the memoized lazy component for a nested layout loader, keyed by loader identity. */
-export function nestedLayout(
-    loader: LayoutComponentLoader,
-): ComponentType<{ children?: ReactNode }> {
-    let component = nestedLayoutCache.get(loader);
-    if (!component) {
-        component = lazy(loader);
-        nestedLayoutCache.set(loader, component);
-    }
-    return component;
-}
-
-let notFoundComponent: ComponentType | null = null;
-let notFoundLoader: NotFoundLoader = null;
-
-/** Returns the memoized lazy not-found component, rebuilding only if the loader identity changes. */
-export function resolveNotFound(loader: NonNullable<NotFoundLoader>): ComponentType {
-    if (notFoundLoader !== loader || !notFoundComponent) {
-        notFoundComponent = lazy(loader);
-        notFoundLoader = loader;
-    }
-    return notFoundComponent;
-}