toiljs 0.0.3 → 0.0.5

package/src/client/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.js';
+import { ParamsContext } from './params-context.js';
+import { prefetch } from './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/index.ts

@@ -1,12 +1,42 @@
 /**
- * toiljs client runtime, published as `toiljs/client`. Provides the router (mount/Router/Link),
- * navigation hooks, and route types consumed by the compiler-generated entry. Zero imports
- * needed in user route files beyond this package.
+ * toiljs client runtime, published as `toiljs/client`. Re-exports the router (mount/Router/Link),
+ * navigation hooks, prefetching, and the route types consumed by the compiler-generated entry.
+ * Zero imports needed in user route files beyond this package.
+ *
+ * Internals are split by concern: route `types`, history-based `navigation`, the params
+ * `params-context` + `hooks`, `lazy` component resolution, the `Link`/`Router` components,
+ * `mount`, `match` (pure matcher), `prefetch` (link prefetcher), and `channel` (WebSocket helper).
  */
 
-export { mount, Router, Link, navigate, useParams, useNavigate, useLocation } from './runtime.js';
-export type { RouteDef, LayoutLoader, NotFoundLoader } from './runtime.js';
+export { mount } from './mount.js';
+export { Router } from './Router.js';
+export { Link } from './Link.js';
+export type { LinkProps } from './Link.js';
+export { NavLink, matchActive } from './NavLink.js';
+export type { NavLinkProps, NavLinkState } from './NavLink.js';
+export { navigate, back, forward, refresh } from './navigation.js';
+export type { NavigateOptions } from './navigation.js';
+export {
+    useParams,
+    useNavigate,
+    useLocation,
+    usePathname,
+    useSearchParams,
+    useRouter,
+    useNavigationPending,
+} from './hooks.js';
+export type { RouterInstance } from './hooks.js';
+export { prefetch } from './prefetch.js';
+export type {
+    RouteDef,
+    LayoutLoader,
+    LayoutComponentLoader,
+    NotFoundLoader,
+    RouteErrorProps,
+} from './types.js';
 export { matchRoute } from './match.js';
 export type { RouteParams } from './match.js';
 export { connectChannel, useChannel, resolveChannelUrl } from './channel.js';
 export type { Channel, ChannelOptions, ChannelHook, ChannelData } from './channel.js';
+export { useHead, useTitle, Head, mergeHead } from './head.js';
+export type { HeadSpec, MetaTag, LinkTag, ResolvedHead } from './head.js';

package/src/client/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;
+}

package/src/client/match.ts

@@ -6,7 +6,8 @@ export type RouteParams = Record<string, string>;
  * Pure and runtime-agnostic (used by the router and unit-tested directly).
  *   matchRoute('/', '/')                  -> {}
  *   matchRoute('/blog/:id', '/blog/42')   -> { id: '42' }
- *   matchRoute('/docs/*slug', '/docs/a/b') -> { slug: 'a/b' }   (catch-all)
+ *   matchRoute('/docs/*slug', '/docs/a/b') -> { slug: 'a/b' }   (catch-all, 1+ segments)
+ *   matchRoute('/docs/**slug', '/docs')   -> { slug: '' }       (optional catch-all, 0+ segments)
  *   matchRoute('/about', '/x')            -> null
  */
 export function matchRoute(pattern: string, pathname: string): RouteParams | null {
@@ -17,7 +18,15 @@ export function matchRoute(pattern: string, pathname: string): RouteParams | nul
     for (let i = 0; i < patternSegs.length; i++) {
         const p = patternSegs[i];
 
-        // Catch-all (`*slug`): captures the rest of the path (one or more segments).
+        // Optional catch-all (`**slug`): captures the rest of the path, matching zero or more segments.
+        if (p.startsWith('**')) {
+            params[p.slice(2)] = pathSegs
+                .slice(i)
+                .map((s) => decodeURIComponent(s))
+                .join('/');
+            return params;
+        }
+
         if (p.startsWith('*')) {
             const rest = pathSegs.slice(i);
             if (rest.length === 0) return null;
@@ -34,6 +43,5 @@ export function matchRoute(pattern: string, pathname: string): RouteParams | nul
         }
     }
 
-    // No catch-all consumed the tail: lengths must match exactly.
     return patternSegs.length === pathSegs.length ? params : null;
 }

package/src/client/mount.tsx

@@ -0,0 +1,28 @@
+import { createRoot } from 'react-dom/client';
+
+import { initNavigation } from './navigation.js';
+import { startPrefetcher } from './prefetch.js';
+import { Router } from './Router.js';
+import type { LayoutLoader, NotFoundLoader, RouteDef } from './types.js';
+
+/**
+ * Mounts the toil client app into `#root` and starts idle link prefetching. Called by the
+ * compiler-generated `.toil/entry.tsx`.
+ */
+export function mount(
+    routes: RouteDef[],
+    layout: LayoutLoader = null,
+    notFound: NotFoundLoader = null,
+): void {
+    const el = document.getElementById('root');
+    if (!el) throw new Error('toil: #root element not found');
+    initNavigation();
+    createRoot(el).render(
+        <Router
+            routes={routes}
+            layout={layout}
+            notFound={notFound}
+        />,
+    );
+    startPrefetcher(routes);
+}

package/src/client/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/params-context.ts

@@ -0,0 +1,10 @@
+/**
+ * React context carrying the current route's dynamic params. The provider is set by {@link Router};
+ * read it with the {@link useParams} hook rather than consuming the context directly.
+ */
+import { createContext } from 'react';
+
+import type { RouteParams } from './match.js';
+
+/** Holds the params extracted from the active route (e.g. `{ id }` for `/blog/:id`). */
+export const ParamsContext = createContext<RouteParams>({});

package/src/client/prefetch.ts

@@ -0,0 +1,130 @@
+import { matchRoute } from './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/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);
+}