toiljs 0.0.116 → 0.0.118

package/src/client/navigation/Link.tsx

@@ -1,108 +0,0 @@
-import type { ComponentPropsWithRef, FocusEvent, MouseEvent, PointerEvent, ReactNode } from 'react';
-
-import { navigate } from './navigation.js';
-import { prefetch } from './prefetch.js';
-import type { Href } from '../types.js';
-
-/**
- * Props for {@link Link}: every standard `<a>` attribute (`rel`, `target`, `download`,
- * `referrerPolicy`, `hrefLang`, `className`, `style`, `ref`, `data-*`, `aria-*`, event handlers …)
- * plus toil's `replace` and `prefetch` controls. `href` is required and typed to the project's routes.
- */
-export interface LinkProps extends Omit<ComponentPropsWithRef<'a'>, 'href'> {
-    /** Destination. Same-origin hrefs navigate client-side; external / `target` / `download` / `#hash` use the browser. */
-    href: Href;
-    /** Replace the current history entry instead of pushing a new one. Default `false`. */
-    replace?: boolean;
-    /** Scroll to top after navigating. Default `true`. */
-    scroll?: boolean;
-    /** Prefetch the route chunk on hover/focus. Default `true`; `false` opts this link out. */
-    prefetch?: boolean;
-}
-
-/** True for cross-origin, opaque (`mailto:` / `tel:`), or otherwise non-same-origin hrefs. */
-function isExternalHref(href: string): boolean {
-    try {
-        return new URL(href, window.location.href).origin !== window.location.origin;
-    } catch {
-        return true;
-    }
-}
-
-/**
- * Whether `href` is a usable client-navigation target. A data-driven href (`` `routeMap[key]` ``)
- * can resolve to `undefined` / `null` / `''` at runtime when the target page doesn't exist; the
- * resulting anchor is inert, so we must not intercept its click, calling `href.startsWith` /
- * `navigate` on a missing href would throw. `Href` is always a string at the type level, hence the
- * `unknown` parameter, the guard is purely a runtime safety net.
- */
-function isNavigableHref(href: unknown): href is string {
-    return typeof href === 'string' && href !== '';
-}
-
-/**
- * Client-side navigation link. Forwards all anchor attributes to the underlying `<a>`, and
- * prefetches the target route's chunk on hover/focus. Intercepts only plain same-origin clicks ,
- * modified clicks, `target=_blank`, `download`, in-page `#hash`, and external URLs fall through to
- * native browser behavior.
- */
-export function Link(props: LinkProps): ReactNode {
-    const {
-        href,
-        replace = false,
-        scroll = true,
-        prefetch: prefetchProp = true,
-        onClick,
-        onPointerEnter,
-        onFocus,
-        children,
-        ...rest
-    } = props;
-
-    const handleClick = (event: MouseEvent<HTMLAnchorElement>): void => {
-        onClick?.(event);
-        if (
-            event.defaultPrevented ||
-            // A missing href (the target page doesn't exist) makes the anchor inert: leave the click
-            // to the browser instead of intercepting it. Checked before `startsWith` so it can't throw.
-            !isNavigableHref(href) ||
-            event.button !== 0 ||
-            event.metaKey ||
-            event.ctrlKey ||
-            event.shiftKey ||
-            event.altKey ||
-            (rest.target !== undefined && rest.target !== '_self') ||
-            rest.download !== undefined ||
-            href.startsWith('#') ||
-            isExternalHref(href)
-        ) {
-            return;
-        }
-        event.preventDefault();
-        navigate(href, { replace, scroll });
-    };
-
-    const warm = (): void => {
-        if (prefetchProp && isNavigableHref(href)) prefetch(href);
-    };
-    const handlePointerEnter = (event: PointerEvent<HTMLAnchorElement>): void => {
-        onPointerEnter?.(event);
-        warm();
-    };
-    const handleFocus = (event: FocusEvent<HTMLAnchorElement>): void => {
-        onFocus?.(event);
-        warm();
-    };
-
-    return (
-        <a
-            {...rest}
-            {...(prefetchProp ? {} : { 'data-no-prefetch': '' })}
-            href={href}
-            onClick={handleClick}
-            onPointerEnter={handlePointerEnter}
-            onFocus={handleFocus}>
-            {children}
-        </a>
-    );
-}

package/src/client/navigation/NavLink.tsx

@@ -1,86 +0,0 @@
-import type { CSSProperties, ReactNode } from 'react';
-
-import { useLocation } from '../routing/hooks.js';
-import { Link, type LinkProps } from './Link.js';
-
-/** State passed to `NavLink`'s function-form `className` / `style` / `children`. */
-export interface NavLinkState {
-    readonly isActive: boolean;
-}
-
-/**
- * Props for {@link NavLink}: all {@link LinkProps}, but `className` / `style` / `children` may also
- * be functions of the active state.
- */
-export interface NavLinkProps extends Omit<LinkProps, 'className' | 'style' | 'children'> {
-    className?: string | ((state: NavLinkState) => string | undefined);
-    style?: CSSProperties | ((state: NavLinkState) => CSSProperties | undefined);
-    children?: ReactNode | ((state: NavLinkState) => ReactNode);
-    /** Match `href` exactly; without it, sub-paths are also active. Default `false`. */
-    end?: boolean;
-    /** Class added when active (used with a string `className`). Default `"active"`. */
-    activeClassName?: string;
-}
-
-function normalizePath(p: string): string {
-    return p.length > 1 ? p.replace(/\/+$/, '') : p;
-}
-
-/**
- * Whether a link to `linkPath` is active for `currentPath`. Exact when `end`; otherwise a parent
- * path is active for its sub-paths (and `/` is active everywhere, matching React Router).
- */
-export function matchActive(linkPath: string, currentPath: string, end: boolean): boolean {
-    const link = normalizePath(linkPath);
-    const current = normalizePath(currentPath);
-    if (current === link) return true;
-    if (end) return false;
-    if (link === '/') return true;
-    return current.startsWith(link + '/');
-}
-
-/**
- * A {@link Link} that knows whether it points at the current location. Applies an active class
- * (default `"active"`) and `aria-current="page"` when active; `className` / `style` / `children`
- * may be functions of `{ isActive }`. Inherits Link's full anchor API and prefetching.
- */
-export function NavLink(props: NavLinkProps): ReactNode {
-    const {
-        href,
-        className,
-        style,
-        children,
-        end = false,
-        activeClassName = 'active',
-        ...rest
-    } = props;
-    const pathname = useLocation();
-
-    let linkPath = href;
-    try {
-        linkPath = new URL(href, window.location.href).pathname;
-    } catch {
-        linkPath = href;
-    }
-    const isActive = matchActive(linkPath, pathname, end);
-    const state: NavLinkState = { isActive };
-
-    const resolvedClassName =
-        typeof className === 'function'
-            ? className(state)
-            : [className, isActive ? activeClassName : undefined].filter(Boolean).join(' ') ||
-              undefined;
-    const resolvedStyle = typeof style === 'function' ? style(state) : style;
-    const resolvedChildren = typeof children === 'function' ? children(state) : children;
-
-    return (
-        <Link
-            {...rest}
-            href={href}
-            className={resolvedClassName}
-            style={resolvedStyle}
-            aria-current={isActive ? 'page' : undefined}>
-            {resolvedChildren}
-        </Link>
-    );
-}

package/src/client/navigation/navigation.ts

@@ -1,235 +0,0 @@
-/**
- * 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 { startTransition } from 'react';
-import { flushSync } from 'react-dom';
-
-import { enableManualScrollRestoration, planScroll, rememberScroll } from './scroll.js';
-import type { Href } from '../types.js';
-
-/**
- * Asserts a runtime-computed string is a valid {@link Href}, the escape hatch for hrefs built from
- * data (e.g. `` `/${category}/${slug}` ``) that can't be checked against the static route union.
- * Use at the call site: `<Link href={href(path)} />`, `navigate(href(path))`.
- */
-export const href = (path: string): Href => path as Href;
-
-const listeners = new Set<() => void>();
-let popstateBound = false;
-
-/** `document.startViewTransition`, present only where the View Transitions API is supported. */
-interface ViewTransitionDocument {
-    startViewTransition?: (callback: () => void) => unknown;
-}
-let viewTransitions = false;
-
-/** Enables animated View Transitions for navigation. Called once by `mount` from `client.viewTransitions`. */
-export function setViewTransitions(enabled: boolean): void {
-    viewTransitions = enabled;
-}
-
-// Whether to wrap navigations in a React transition. Off by default: a navigation commits eagerly, so
-// a route's `loading.tsx` shows immediately while its loader runs. On, the current page is kept
-// visible until the next route is ready (smoother, but no loading state). Set from `client.transitions`.
-let navTransitions = false;
-
-/** Enables React-transition (keep-current-page) navigation. Called once by `mount` from `client.transitions`. */
-export function setTransitions(enabled: boolean): void {
-    navTransitions = enabled;
-}
-
-/** Whether the current navigation should animate via the View Transitions API. */
-function shouldViewTransition(): boolean {
-    if (!viewTransitions || typeof document === 'undefined' || typeof window === 'undefined') {
-        return false;
-    }
-    if (typeof (document as ViewTransitionDocument).startViewTransition !== 'function')
-        return false;
-    return !window.matchMedia('(prefers-reduced-motion: reduce)').matches;
-}
-
-interface ToilHistoryState {
-    __toilKey?: string;
-}
-let keyCounter = 0;
-let currentKey = 'initial';
-function nextKey(): string {
-    keyCounter += 1;
-    return `t${String(keyCounter)}`;
-}
-
-function runListeners(): void {
-    for (const listener of listeners) listener();
-}
-
-/**
- * Re-renders subscribers for a location change. When View Transitions are enabled and supported, the
- * commit runs synchronously inside `document.startViewTransition` so the browser animates the old and
- * new DOM. Otherwise, with `client.transitions` on, it's wrapped in `startTransition` (the current
- * page stays while the next route loads); by default it commits eagerly, so a route's `loading.tsx`
- * shows right away instead of holding the previous page.
- */
-function notify(): void {
-    if (shouldViewTransition()) {
-        (document as ViewTransitionDocument).startViewTransition?.(() => {
-            flushSync(runListeners);
-        });
-    } else if (navTransitions) {
-        startTransition(runListeners);
-    } else {
-        runListeners();
-    }
-}
-
-// Soft vs hard navigation, for intercepting routes. The initial page load (and any full refresh) is
-// "hard"; client navigations (`navigate` / back / forward) are "soft". `previousPath` is the path we
-// were on before the latest soft navigation, the route the main view keeps showing while an
-// intercepting route fills a slot (the modal overlay).
-let softNav = false;
-let currentPath = typeof window === 'undefined' ? '/' : window.location.pathname;
-let previousPath = currentPath;
-
-/** Records a transition to the live location; `soft` is false only for the initial load. */
-function recordTransition(soft: boolean): void {
-    previousPath = currentPath;
-    currentPath = typeof window === 'undefined' ? '/' : window.location.pathname;
-    softNav = soft;
-}
-
-/** Whether the current location was reached by a client navigation (not an initial load / refresh). */
-export function isSoftNavigation(): boolean {
-    return softNav;
-}
-
-/** The path the app was on before the latest navigation (what the main view keeps during an intercept). */
-export function previousPathname(): string {
-    return previousPath;
-}
-
-// 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;
-}
-
-/** Monotonic id incremented on each navigation, used to key/revalidate per-navigation route data. */
-export function navigationEpoch(): number {
-    return startedTick;
-}
-
-/** 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: Href, 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);
-    }
-    recordTransition(true);
-    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, bumping the navigation epoch so a revalidation of the *same* URL
- * re-keys its Suspense boundary (its `loading.tsx` shows while the loader re-runs) and
- * `useNavigationPending` reports the in-flight refetch, instead of silently freezing the old page.
- */
-export function refresh(): void {
-    beginNavigation();
-    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';
-    recordTransition(true);
-    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

@@ -1,169 +0,0 @@
-import { prefetchRouteData } from '../routing/loader.js';
-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>();
-const dataWarmed = new Set<string>();
-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);
-}
-
-/**
- * Prefetches both the chunk and the loader data for an internal `href`, so a later navigation
- * commits synchronously (no suspense, no held-page wait). Called on link hover / focus intent, where
- * running the route's loader early is worth it. No-op for external/unknown/already-warmed targets.
- */
-export function prefetchData(href: string): void {
-    let url: URL;
-    try {
-        url = new URL(href, window.location.href);
-    } catch {
-        return;
-    }
-    if (url.origin !== window.location.origin) return;
-    const key = url.pathname + url.search;
-    if (dataWarmed.has(key)) return;
-    for (const route of routeTable) {
-        const params = matchRoute(route.pattern, url.pathname);
-        if (params) {
-            dataWarmed.add(key);
-            warm(route);
-            prefetchRouteData(route, params, url.pathname, url.search);
-            return;
-        }
-    }
-}
-
-/** 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);
-            }
-        }
-    });
-
-    // Hover / focus intent: warm the chunk *and* run the loader for the target so the click commits
-    // synchronously. Delegated on the document so links added later are covered automatically.
-    const onIntent = (event: Event): void => {
-        const target = event.target;
-        if (!(target instanceof Element)) return;
-        const a = target.closest('a[href]');
-        if (a instanceof HTMLAnchorElement && isPrefetchable(a) && a.href) prefetchData(a.href);
-    };
-    document.addEventListener('pointerover', onIntent, { passive: true });
-    document.addEventListener('focusin', onIntent);
-
-    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

@@ -1,53 +0,0 @@
-/**
- * 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);
-}