toiljs 0.0.4 → 0.0.6

package/src/client/navigation/navigation.ts

@@ -0,0 +1,142 @@
+/**
+ * History-based navigation core. Owns the location subscribers, the single `popstate` handler, and
+ * the per-entry history keys used for scroll restoration. Consumed by `useLocation` (to re-render),
+ * `Link` / `navigate` (to change location), and `Router` (which calls `applyScroll` after commit).
+ */
+import {
+    enableManualScrollRestoration,
+    planScroll,
+    rememberScroll,
+} from './scroll.js';
+
+const listeners = new Set<() => void>();
+let popstateBound = false;
+
+interface ToilHistoryState {
+    __toilKey?: string;
+}
+let keyCounter = 0;
+let currentKey = 'initial';
+function nextKey(): string {
+    keyCounter += 1;
+    return `t${String(keyCounter)}`;
+}
+
+/** Notifies every subscriber that the location may have changed. */
+function notify(): void {
+    for (const listener of listeners) listener();
+}
+
+// Navigation-pending tracking: a navigation is "pending" from when it starts until the new route
+// commits. Drives useNavigationPending() (e.g. a top loading bar).
+let startedTick = 0;
+let committedTick = 0;
+const pendingListeners = new Set<() => void>();
+function emitPending(): void {
+    for (const listener of pendingListeners) listener();
+}
+function beginNavigation(): void {
+    startedTick += 1;
+    emitPending();
+}
+
+/** Marks the in-flight navigation as committed. Called by `Router` after each commit. */
+export function settleNavigation(): void {
+    if (committedTick !== startedTick) {
+        committedTick = startedTick;
+        emitPending();
+    }
+}
+
+/** Whether a navigation is in flight (started but not yet committed). */
+export function isNavigationPending(): boolean {
+    return startedTick !== committedTick;
+}
+
+/** Subscribes to navigation-pending changes; returns an unsubscribe function. */
+export function subscribePending(listener: () => void): () => void {
+    pendingListeners.add(listener);
+    return () => {
+        pendingListeners.delete(listener);
+    };
+}
+
+/** Options for {@link navigate}. */
+export interface NavigateOptions {
+    /** Replace the current history entry instead of pushing a new one. Default `false`. */
+    readonly replace?: boolean;
+    /** Scroll to the top of the page after navigating. Default `true`. */
+    readonly scroll?: boolean;
+}
+
+/** Initializes manual scroll restoration and the initial history key. Called once by `mount`. */
+export function initNavigation(): void {
+    enableManualScrollRestoration();
+    const state = window.history.state as ToilHistoryState | null;
+    if (state?.__toilKey) {
+        currentKey = state.__toilKey;
+    } else {
+        currentKey = nextKey();
+        window.history.replaceState({ ...state, __toilKey: currentKey }, '');
+    }
+}
+
+/** Navigates to `href` without a full page reload (history push/replace + subscriber re-render). */
+export function navigate(href: string, options?: NavigateOptions): void {
+    beginNavigation();
+    rememberScroll(currentKey);
+    let hash = '';
+    try {
+        hash = new URL(href, window.location.href).hash;
+    } catch {
+        hash = '';
+    }
+    if (options?.replace) {
+        window.history.replaceState({ __toilKey: currentKey }, '', href);
+    } else {
+        currentKey = nextKey();
+        window.history.pushState({ __toilKey: currentKey }, '', href);
+    }
+    planScroll({ hash, toTop: options?.scroll !== false });
+    notify();
+}
+
+/** Goes back one entry in history (fires `popstate`, which notifies subscribers). */
+export function back(): void {
+    window.history.back();
+}
+
+/** Goes forward one entry in history. */
+export function forward(): void {
+    window.history.forward();
+}
+
+/** Re-renders the current route without changing the URL (there is no server data to refetch). */
+export function refresh(): void {
+    notify();
+}
+
+/** Handles browser back/forward: restores the saved scroll for the target entry, then re-renders. */
+function handlePopState(event: PopStateEvent): void {
+    beginNavigation();
+    rememberScroll(currentKey);
+    const state = event.state as ToilHistoryState | null;
+    currentKey = state?.__toilKey ?? 'initial';
+    planScroll({ restoreKey: currentKey, hash: window.location.hash, toTop: false });
+    notify();
+}
+
+/**
+ * Subscribes `listener` to location changes and returns an unsubscribe function. Browser
+ * back/forward is wired once, on the first subscription, via a shared `popstate` handler.
+ */
+export function subscribeLocation(listener: () => void): () => void {
+    if (!popstateBound) {
+        window.addEventListener('popstate', handlePopState);
+        popstateBound = true;
+    }
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}

package/src/client/navigation/prefetch.ts

@@ -0,0 +1,130 @@
+import { matchRoute } from '../routing/match.js';
+import type { RouteDef } from '../types.js';
+
+declare global {
+    interface Navigator {
+        /** Non-standard but widely shipped; used to skip prefetch on data-saver / slow links. */
+        readonly connection?: {
+            readonly saveData?: boolean;
+            readonly effectiveType?: string;
+        };
+    }
+}
+
+let routeTable: RouteDef[] = [];
+const warmed = new WeakSet<RouteDef>();
+let io: IntersectionObserver | null = null;
+let mo: MutationObserver | null = null;
+
+/** Resolves a same-origin `href` to a registered route, or `null` for external/unknown targets. */
+function routeForHref(href: string): RouteDef | null {
+    let url: URL;
+    try {
+        url = new URL(href, window.location.href);
+    } catch {
+        return null;
+    }
+    if (url.origin !== window.location.origin) return null;
+    for (const route of routeTable) {
+        if (matchRoute(route.pattern, url.pathname)) return route;
+    }
+    return null;
+}
+
+/**
+ * Warms a route's lazy chunk by triggering its loader once. Best-effort: each route loads at most
+ * once, and a failed load is forgotten (so the real navigation can retry and surface the error).
+ */
+function warm(route: RouteDef): void {
+    if (warmed.has(route)) return;
+    warmed.add(route);
+    void route.load().catch(() => {
+        warmed.delete(route);
+    });
+}
+
+/**
+ * Prefetches the route chunk for an internal `href` so a later navigation resolves instantly.
+ * No-op for external, unknown, or already-prefetched targets — safe to call from anywhere,
+ * including before an imperative {@link navigate} (e.g. `prefetch('/dashboard')` on hover/intent).
+ */
+export function prefetch(href: string): void {
+    const route = routeForHref(href);
+    if (route) warm(route);
+}
+
+/** Anchors to skip even when internal: new-tab, downloads, or an explicit `data-no-prefetch` opt-out. */
+function isPrefetchable(a: HTMLAnchorElement): boolean {
+    if (a.target && a.target !== '_self') return false;
+    if (a.hasAttribute('download')) return false;
+    if (a.dataset.noPrefetch !== undefined) return false;
+    return true;
+}
+
+/** Observes an anchor for viewport entry if it points at a known internal route. */
+function observeAnchor(a: HTMLAnchorElement): void {
+    if (!io || !isPrefetchable(a) || !routeForHref(a.href)) return;
+    io.observe(a);
+}
+
+/** Finds and observes every `<a href>` under `root`. */
+function scan(root: ParentNode): void {
+    root.querySelectorAll('a[href]').forEach((el) => {
+        if (el instanceof HTMLAnchorElement) observeAnchor(el);
+    });
+}
+
+/** Skip prefetching on data-saver mode or 2g-class connections, where bandwidth is precious. */
+function shouldSkipForConnection(): boolean {
+    const c = navigator.connection;
+    if (!c) return false;
+    return c.saveData === true || c.effectiveType === 'slow-2g' || c.effectiveType === '2g';
+}
+
+/**
+ * Starts idle-time prefetching of internal links. As each `<a>` pointing at a known route scrolls
+ * into view (or near it — 200px margin) its chunk is warmed once; links added later by client
+ * navigation are picked up via a MutationObserver. Called by {@link mount}; runs once per app.
+ */
+export function startPrefetcher(routes: RouteDef[]): void {
+    routeTable = routes;
+    if (
+        typeof window === 'undefined' ||
+        typeof IntersectionObserver === 'undefined' ||
+        typeof MutationObserver === 'undefined' ||
+        io
+    ) {
+        return;
+    }
+    if (shouldSkipForConnection()) return;
+
+    io = new IntersectionObserver(
+        (entries) => {
+            for (const entry of entries) {
+                if (!entry.isIntersecting) continue;
+                const a = entry.target;
+                if (a instanceof HTMLAnchorElement) {
+                    io?.unobserve(a);
+                    prefetch(a.href);
+                }
+            }
+        },
+        { rootMargin: '200px' },
+    );
+
+    mo = new MutationObserver((mutations) => {
+        for (const m of mutations) {
+            for (const node of m.addedNodes) {
+                if (node instanceof HTMLAnchorElement) observeAnchor(node);
+                else if (node instanceof Element) scan(node);
+            }
+        }
+    });
+
+    const begin = (): void => {
+        scan(document);
+        mo?.observe(document.body, { childList: true, subtree: true });
+    };
+    if (typeof requestIdleCallback === 'function') requestIdleCallback(begin);
+    else setTimeout(begin, 200);
+}

package/src/client/navigation/scroll.ts

@@ -0,0 +1,53 @@
+/**
+ * Manual scroll management for client navigation: scroll to top on push navigations, restore the
+ * saved position on back/forward, and honor in-page `#hash` targets. Positions are keyed by
+ * history entry; {@link applyScroll} runs once after the navigation commits.
+ */
+const positions = new Map<string, number>();
+
+interface ScrollPlan {
+    readonly restore: number | null;
+    readonly hash: string;
+    readonly toTop: boolean;
+}
+let plan: ScrollPlan | null = null;
+
+/** Switches off the browser's automatic scroll restoration so the router can manage it. */
+export function enableManualScrollRestoration(): void {
+    if (typeof window !== 'undefined' && 'scrollRestoration' in window.history) {
+        window.history.scrollRestoration = 'manual';
+    }
+}
+
+/** Saves the current scroll position for a history key (called before leaving an entry). */
+export function rememberScroll(key: string): void {
+    positions.set(key, window.scrollY);
+}
+
+/** Plans what {@link applyScroll} should do after the next navigation commits. */
+export function planScroll(opts: { restoreKey?: string; hash: string; toTop: boolean }): void {
+    plan = {
+        restore: opts.restoreKey !== undefined ? (positions.get(opts.restoreKey) ?? 0) : null,
+        hash: opts.hash,
+        toTop: opts.toTop,
+    };
+}
+
+/** Applies the pending scroll plan once: hash target, else restored position, else top. */
+export function applyScroll(): void {
+    const current = plan;
+    plan = null;
+    if (!current) return;
+    if (current.hash) {
+        const el = document.getElementById(decodeURIComponent(current.hash.slice(1)));
+        if (el) {
+            el.scrollIntoView();
+            return;
+        }
+    }
+    if (current.restore !== null) {
+        window.scrollTo(0, current.restore);
+        return;
+    }
+    if (current.toTop) window.scrollTo(0, 0);
+}

package/src/client/routing/Router.tsx

@@ -0,0 +1,95 @@
+import { createElement, Suspense, useLayoutEffect, type ReactNode } from 'react';
+
+import { ErrorBoundary } from './error-boundary.js';
+import { useLocation } from './hooks.js';
+import {
+    errorComponent,
+    loadingComponent,
+    nestedLayout,
+    pageComponent,
+    resolveLayout,
+    resolveNotFound,
+} from './lazy.js';
+import { matchRoute, type RouteParams } from './match.js';
+import { ParamsContext } from './params-context.js';
+import { settleNavigation } from '../navigation/navigation.js';
+import { applyScroll } from '../navigation/scroll.js';
+import type { LayoutLoader, NotFoundLoader, RouteDef } from '../types.js';
+
+/** 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;
+}): ReactNode {
+    const { routes, layout = null, notFound = null } = 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();
+    });
+
+    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;
+        }
+    }
+
+    let content: ReactNode;
+    if (matched) {
+        const Page = pageComponent(matched);
+        const fallback: ReactNode = matched.loading
+            ? createElement(Suspense, { fallback: null }, createElement(loadingComponent(matched.loading)))
+            : null;
+        content = (
+            <Suspense fallback={fallback}>
+                <Page />
+            </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>
+            );
+        }
+    } 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>
+        );
+    }
+
+    return <ParamsContext.Provider value={params}>{content}</ParamsContext.Provider>;
+}

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

@@ -0,0 +1,43 @@
+import { Component, Suspense, type ComponentType, type ReactNode } 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

@@ -0,0 +1,115 @@
+/**
+ * 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,
+    refresh,
+    subscribeLocation,
+    subscribePending,
+    type NavigateOptions,
+} from '../navigation/navigation.js';
+import { ParamsContext } from './params-context.js';
+import { prefetch } from '../navigation/prefetch.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: string, options?: NavigateOptions): void;
+    /** Navigate to `href`, replacing the current history entry. */
+    replace(href: string): void;
+    /** Go back one history entry. */
+    back(): void;
+    /** Go forward one history entry. */
+    forward(): void;
+    /** Re-render the current route. */
+    refresh(): void;
+    /** Prefetch a route's chunk ahead of navigation. */
+    prefetch(href: string): void;
+}
+
+const ROUTER: RouterInstance = {
+    push: (href, options) => {
+        navigate(href, options);
+    },
+    replace: (href) => {
+        navigate(href, { replace: true });
+    },
+    back,
+    forward,
+    refresh,
+    prefetch,
+};
+
+/** Current dynamic route params, e.g. `{ id }` inside `/blog/:id`. */
+export function useParams(): RouteParams {
+    return useContext(ParamsContext);
+}
+
+/** 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 (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.
+ */
+function useLocationSubscription(): void {
+    const [, forceUpdate] = useReducer((n: number): number => n + 1, 0);
+    useEffect(
+        () =>
+            subscribeLocation(() => {
+                startTransition(() => {
+                    forceUpdate();
+                });
+            }),
+        [],
+    );
+}
+
+/** Subscribes to and returns the current `location.pathname`. */
+export function useLocation(): string {
+    useLocationSubscription();
+    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 = 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

@@ -0,0 +1,93 @@
+/**
+ * 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 { lazy, type ComponentType, type ReactNode } from 'react';
+
+import type {
+    LayoutComponentLoader,
+    LayoutLoader,
+    NotFoundLoader,
+    RouteDef,
+    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);
+}
+
+const pageCache = new Map<RouteDef, ComponentType>();
+
+/** Returns the memoized lazy component for `route`, creating it on first use. */
+export function pageComponent(route: RouteDef): ComponentType {
+    let component = pageCache.get(route);
+    if (!component) {
+        component = lazy(route.load);
+        pageCache.set(route, component);
+    }
+    return component;
+}
+
+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;
+}