toiljs 0.0.115 → 0.0.117

package/src/client/dev/error-overlay.tsx

@@ -1,225 +0,0 @@
-/**
- * Development-only error overlay. In dev, surfaces errors that would otherwise leave a blank page or
- * live only in the console: uncaught render errors (incl. those thrown by a loader during render),
- * plus `window` `error` / `unhandledrejection` events. Shows the message, stack, and (for render
- * errors) the React component stack, with Dismiss / Reload. Inert in production builds.
- */
-import {
-    Component,
-    type CSSProperties,
-    type ErrorInfo,
-    type ReactNode,
-    useSyncExternalStore,
-} from 'react';
-
-/** A captured dev error. */
-export interface DevError {
-    readonly error: Error;
-    readonly componentStack?: string;
-    /** Where it came from, a render boundary, a window `error`, or an unhandled rejection. */
-    readonly source: 'render' | 'window' | 'unhandledrejection';
-    /** Capture time (ms epoch). */
-    readonly time: number;
-}
-
-let current: DevError | null = null;
-const listeners = new Set<() => void>();
-/**
- * Bounded history of captured errors, for the dev toolbar's Errors tab. Reassigned to a new array
- * on each change (never mutated in place) so `getErrorLog` is a stable useSyncExternalStore snapshot:
- * the reference changes only when the log changes, so React re-renders on new errors but not in a loop.
- */
-let errorLog: readonly DevError[] = [];
-const MAX_LOG = 50;
-
-function emit(): void {
-    for (const listener of listeners) listener();
-}
-function setDevError(next: DevError | null): void {
-    current = next;
-    if (next) {
-        errorLog = [...errorLog, next].slice(-MAX_LOG);
-    }
-    emit();
-}
-function subscribe(listener: () => void): () => void {
-    listeners.add(listener);
-    return () => {
-        listeners.delete(listener);
-    };
-}
-
-/** The captured-error history (most recent last). Subscribe via {@link subscribeErrors}. */
-export function getErrorLog(): readonly DevError[] {
-    return errorLog;
-}
-/** Subscribes to error captures (fires whenever a new error is recorded or dismissed). */
-export const subscribeErrors = subscribe;
-
-/** True when running under Vite's dev server (replaced at build time; falsy in production). */
-export function isDevMode(): boolean {
-    try {
-        return Boolean((import.meta as { env?: { DEV?: boolean } }).env?.DEV);
-    } catch {
-        return false;
-    }
-}
-
-let windowBound = false;
-/** Wires `window` error / unhandledrejection into the overlay (idempotent; dev only). */
-export function initDevErrorOverlay(): void {
-    if (windowBound || typeof window === 'undefined') return;
-    windowBound = true;
-    window.addEventListener('error', (event) => {
-        if (event.error instanceof Error) {
-            setDevError({ error: event.error, source: 'window', time: Date.now() });
-        }
-    });
-    window.addEventListener('unhandledrejection', (event) => {
-        const reason: unknown = event.reason;
-        const error = reason instanceof Error ? reason : new Error(String(reason));
-        setDevError({ error, source: 'unhandledrejection', time: Date.now() });
-    });
-}
-
-interface BoundaryProps {
-    readonly children: ReactNode;
-}
-interface BoundaryState {
-    readonly crashed: boolean;
-}
-
-/**
- * Catches render errors in its subtree and reports them to the overlay. While crashed it renders
- * nothing (the subtree threw); it recovers when the overlay is dismissed. Class component because
- * React error boundaries have no hook equivalent.
- */
-export class DevErrorBoundary extends Component<BoundaryProps, BoundaryState> {
-    public state: BoundaryState = { crashed: false };
-    private unsubscribe: (() => void) | undefined;
-
-    public static getDerivedStateFromError(): BoundaryState {
-        return { crashed: true };
-    }
-
-    public override componentDidCatch(error: Error, info: ErrorInfo): void {
-        setDevError({
-            error,
-            componentStack: info.componentStack ?? undefined,
-            source: 'render',
-            time: Date.now(),
-        });
-    }
-
-    public override componentDidMount(): void {
-        // Recover (re-render children) once the error is dismissed from the overlay.
-        this.unsubscribe = subscribe(() => {
-            if (current === null && this.state.crashed) this.setState({ crashed: false });
-        });
-    }
-
-    public override componentWillUnmount(): void {
-        this.unsubscribe?.();
-    }
-
-    public override render(): ReactNode {
-        return this.state.crashed ? null : this.props.children;
-    }
-}
-
-const overlayStyle: CSSProperties = {
-    position: 'fixed',
-    inset: 0,
-    zIndex: 2147483647,
-    background: 'rgba(8, 8, 12, 0.88)',
-    color: '#f5f6fa',
-    font: '13px/1.6 ui-monospace, SFMono-Regular, Menlo, monospace',
-    padding: '2rem',
-    overflow: 'auto',
-    display: 'flex',
-    justifyContent: 'center',
-    alignItems: 'flex-start',
-};
-const panelStyle: CSSProperties = {
-    maxWidth: 900,
-    width: '100%',
-    background: '#15151c',
-    border: '1px solid #ef4444',
-    borderRadius: 10,
-    padding: '1.25rem 1.5rem',
-    boxShadow: '0 12px 48px rgba(0,0,0,0.5)',
-};
-const titleStyle: CSSProperties = {
-    margin: 0,
-    color: '#ff6b6b',
-    fontSize: '1rem',
-    fontWeight: 700,
-    wordBreak: 'break-word',
-};
-const preStyle: CSSProperties = {
-    whiteSpace: 'pre-wrap',
-    wordBreak: 'break-word',
-    margin: '0.75rem 0 0',
-    color: '#c8cee0',
-};
-const buttonStyle: CSSProperties = {
-    font: 'inherit',
-    color: '#f5f6fa',
-    background: '#2a2a36',
-    border: '1px solid #3a3a48',
-    borderRadius: 6,
-    padding: '0.4em 1em',
-    cursor: 'pointer',
-    marginRight: '0.5rem',
-};
-
-const SOURCE_LABEL: Record<DevError['source'], string> = {
-    render: 'Render error',
-    window: 'Uncaught error',
-    unhandledrejection: 'Unhandled promise rejection',
-};
-
-/** Renders the overlay when a dev error is captured. Mount once at the app root (dev only). */
-export function DevErrorOverlay(): ReactNode {
-    const devError = useSyncExternalStore(
-        subscribe,
-        () => current,
-        () => null,
-    );
-    if (!devError) return null;
-    return (
-        <div
-            style={overlayStyle}
-            role="alert">
-            <div style={panelStyle}>
-                <p style={titleStyle}>
-                    {SOURCE_LABEL[devError.source]}, {devError.error.name}: {devError.error.message}
-                </p>
-                {devError.error.stack !== undefined && (
-                    <pre style={preStyle}>{devError.error.stack}</pre>
-                )}
-                {devError.componentStack !== undefined && (
-                    <pre style={{ ...preStyle, color: '#8b9ab4' }}>{devError.componentStack}</pre>
-                )}
-                <div style={{ marginTop: '1.25rem' }}>
-                    <button
-                        type="button"
-                        style={buttonStyle}
-                        onClick={() => {
-                            setDevError(null);
-                        }}>
-                        Dismiss
-                    </button>
-                    <button
-                        type="button"
-                        style={buttonStyle}
-                        onClick={() => {
-                            window.location.reload();
-                        }}>
-                        Reload
-                    </button>
-                </div>
-            </div>
-        </div>
-    );
-}

package/src/client/errors.ts

@@ -1,11 +0,0 @@
-/**
- * Extracts a human-readable message from an unknown thrown value. Handy in `catch`
- * blocks where the caught value is typed `unknown`. Exposed as a global `parseError`
- * (no import) alongside the other toiljs globals.
- *
- * @param err - the caught value (an `Error`, a string, or anything else).
- * @returns the `Error.message` when `err` is an `Error`, otherwise `String(err)`.
- */
-export function parseError(err: unknown): string {
-    return err instanceof Error ? err.message : String(err);
-}

package/src/client/head/head.ts

@@ -1,182 +0,0 @@
-/**
- * Client-side document `<head>` management. `useHead` / `useTitle` / `<Head>` let any component
- * (layout or page) set the title and `<meta>` / `<link>` tags; entries compose across the tree
- * (later/deeper entries win per key) and are reverted when the component unmounts. Pure
- * `mergeHead` resolves the active entries; the manager reconciles `document.head`.
- */
-import { useEffect, useLayoutEffect } from 'react';
-
-import { __isSsrBuild } from '../ssr/markers';
-
-/** A `<meta>` tag. Use `name` or `property` (OpenGraph) as the dedup key; extra attrs pass through. */
-export interface MetaTag {
-    readonly name?: string;
-    readonly property?: string;
-    readonly content: string;
-    readonly [attr: string]: string | undefined;
-}
-
-/** A `<link>` tag (deduped by `rel` + `href`); extra attrs pass through. */
-export interface LinkTag {
-    readonly rel: string;
-    readonly href: string;
-    readonly [attr: string]: string | undefined;
-}
-
-/** A head contribution from one component. */
-export interface HeadSpec {
-    /** Document title. */
-    readonly title?: string;
-    readonly meta?: readonly MetaTag[];
-    readonly link?: readonly LinkTag[];
-}
-
-/** The resolved head after merging all active specs. */
-export interface ResolvedHead {
-    readonly title?: string;
-    readonly meta: MetaTag[];
-    readonly link: LinkTag[];
-}
-
-function metaKey(m: MetaTag): string {
-    if (m.name !== undefined) return `name:${m.name}`;
-    if (m.property !== undefined) return `property:${m.property}`;
-    return `meta:${JSON.stringify(m)}`;
-}
-
-/**
- * Merges head specs in order: the last `title` wins, `meta` dedupes by name/property and `link` by
- * rel+href (last wins).
- */
-export function mergeHead(specs: readonly HeadSpec[]): ResolvedHead {
-    let title: string | undefined;
-    const meta = new Map<string, MetaTag>();
-    const link = new Map<string, LinkTag>();
-    for (const spec of specs) {
-        if (spec.title !== undefined) title = spec.title;
-        for (const m of spec.meta ?? []) meta.set(metaKey(m), m);
-        for (const l of spec.link ?? []) link.set(`${l.rel}:${l.href}`, l);
-    }
-    return { title, meta: [...meta.values()], link: [...link.values()] };
-}
-
-const entries = new Map<number, HeadSpec>();
-let order: number[] = [];
-let seq = 0;
-let baseTitle: string | null = null;
-// The current route's resolved `metadata` export. Merged LAST (highest priority), so a route's
-// metadata wins over a layout's `useHead`/`<Head>` defaults (e.g. a site-wide title) for
-// the keys it sets, while the layout still fills everything the route leaves unset. Set by the router
-// via `setRouteHead` on each navigation.
-let routeHead: HeadSpec | null = null;
-
-// Component-level head (`useHead`/`useTitle`/<Head>) collected during the build's SSR extraction.
-// renderToString doesn't run effects, so specs are pushed during render (see `useHead`); the template
-// extractor drains them with `__drainSsrHead` after each route renders, to bake the route's
-// component-level head into the server HTML (not just its static `metadata` export).
-let ssrHeadSink: HeadSpec[] = [];
-
-function setAttrs(el: Element, attrs: Record<string, string | undefined>): void {
-    el.setAttribute('data-toil-head', '');
-    for (const [key, value] of Object.entries(attrs)) {
-        if (value !== undefined) el.setAttribute(key, value);
-    }
-}
-
-/** Reconciles `document.head` with the merged active specs. */
-function apply(): void {
-    if (typeof document === 'undefined') return;
-    if (baseTitle === null) baseTitle = document.title;
-
-    const specs = [...order.map((id) => entries.get(id)), routeHead];
-    const resolved = mergeHead(specs.filter((s): s is HeadSpec => !!s));
-
-    document.title = resolved.title ?? baseTitle;
-
-    for (const stale of document.head.querySelectorAll('[data-toil-head]')) stale.remove();
-    for (const m of resolved.meta) {
-        const el = document.createElement('meta');
-        setAttrs(el, m);
-        document.head.appendChild(el);
-    }
-    for (const l of resolved.link) {
-        const el = document.createElement('link');
-        setAttrs(el, l);
-        document.head.appendChild(el);
-    }
-}
-
-function addHead(spec: HeadSpec): number {
-    const id = ++seq;
-    entries.set(id, spec);
-    order.push(id);
-    apply();
-    return id;
-}
-
-function removeHead(id: number): void {
-    entries.delete(id);
-    order = order.filter((x) => x !== id);
-    apply();
-}
-
-/**
- * Applies a head contribution for the lifetime of the calling component: title, `<meta>`, `<link>`.
- * Reverts on unmount. Compose freely, a root layout can set defaults a page overrides.
- */
-export function useHead(spec: HeadSpec): void {
-    // During the build's SSR extraction (no document, effects don't run), collect the spec so the
-    // route's component-level head reaches the server HTML. A no-op in the browser bundle.
-    if (__isSsrBuild()) ssrHeadSink.push(spec);
-    const json = JSON.stringify(spec);
-    useEffect(() => {
-        const id = addHead(JSON.parse(json) as HeadSpec);
-        return () => {
-            removeHead(id);
-        };
-    }, [json]);
-}
-
-/** Sets `document.title` for the calling component's lifetime. */
-export function useTitle(title: string): void {
-    useHead({ title });
-}
-
-/** Declarative form of {@link useHead}: `<Head title="…" meta={[…]} />`. Renders nothing. */
-export function Head(props: HeadSpec): null {
-    useHead(props);
-    return null;
-}
-
-/** Sets the current route's baseline head (lowest priority). Pass `null` to clear it. */
-export function setRouteHead(spec: HeadSpec | null): void {
-    routeHead = spec;
-    apply();
-}
-
-/**
- * Applies a route's resolved `metadata` as the baseline head for the calling route's lifetime, and
- * clears it on unmount. Used internally by the router; a layout-effect so the title updates before
- * paint (no flicker).
- */
-export function useRouteHead(spec: HeadSpec | undefined): void {
-    const json = spec ? JSON.stringify(spec) : '';
-    useLayoutEffect(() => {
-        setRouteHead(json ? (JSON.parse(json) as HeadSpec) : null);
-        return () => {
-            setRouteHead(null);
-        };
-    }, [json]);
-}
-
-/**
- * Drains the component-level head (`useHead`/`useTitle`/<Head>) collected during ONE route's SSR-build
- * render and resolves it, then resets the sink for the next route. Called by the build's template
- * extractor right after `renderToString`, so the server HTML carries the same component head the client
- * computes — not just the route's static `metadata` export. (Build-only; unused in the browser.)
- */
-export function __drainSsrHead(): ResolvedHead {
-    const resolved = mergeHead(ssrHeadSink);
-    ssrHeadSink = [];
-    return resolved;
-}

package/src/client/head/metadata.ts

@@ -1,110 +0,0 @@
-/**
- * Route metadata, the declarative SEO counterpart to `useHead`/`<Head>`. A route file may
- * `export const metadata` (static) or `export const generateMetadata` (dynamic, using its loader
- * data); the compiler-driven loader resolves it to a {@link HeadSpec} that the router applies as the
- * route's baseline head (component-level `useHead`/`<Head>` still compose on top and can override).
- */
-import { type HeadSpec, type LinkTag, type MetaTag, useHead } from './head.js';
-import type { RouteParams } from '../routing/match.js';
-
-/** OpenGraph fields, expanded to `og:*` meta tags. */
-export interface OpenGraph {
-    readonly title?: string;
-    readonly description?: string;
-    readonly type?: string;
-    readonly url?: string;
-    readonly image?: string;
-    readonly siteName?: string;
-}
-
-/** A route's metadata. Convenience fields expand to the right `<meta>`/`<link>` tags. */
-export interface Metadata {
-    /** Document title. */
-    readonly title?: string;
-    /** `<meta name="description">`. */
-    readonly description?: string;
-    /** `<meta name="keywords">`, joined with `, ` if an array. */
-    readonly keywords?: string | readonly string[];
-    /** `<link rel="canonical">`. */
-    readonly canonical?: string;
-    /** `<meta name="robots">`, e.g. `'noindex, nofollow'`. */
-    readonly robots?: string;
-    /** `<meta name="theme-color">`. */
-    readonly themeColor?: string;
-    /** OpenGraph (`og:*`) tags. */
-    readonly openGraph?: OpenGraph;
-    /** Escape hatch: extra raw `<meta>` tags. */
-    readonly meta?: readonly MetaTag[];
-    /** Escape hatch: extra raw `<link>` tags. */
-    readonly link?: readonly LinkTag[];
-}
-
-/** Arguments passed to {@link GenerateMetadata}: route params, query, and the loader's data. */
-export interface GenerateMetadataArgs<T = unknown> {
-    readonly params: RouteParams;
-    readonly searchParams: URLSearchParams;
-    readonly data: T;
-}
-
-/** A route's `export const generateMetadata`, dynamic metadata derived from params/query/loader data. */
-export type GenerateMetadata<T = unknown> = (
-    args: GenerateMetadataArgs<T>,
-) => Metadata | Promise<Metadata>;
-
-/** Expands a {@link Metadata} into a {@link HeadSpec} (title + concrete meta/link tags). */
-export function resolveMetadata(metadata: Metadata): HeadSpec {
-    const meta: MetaTag[] = [];
-    if (metadata.description !== undefined) {
-        meta.push({ name: 'description', content: metadata.description });
-    }
-    if (metadata.keywords !== undefined) {
-        const content =
-            typeof metadata.keywords === 'string'
-                ? metadata.keywords
-                : metadata.keywords.join(', ');
-        meta.push({ name: 'keywords', content });
-    }
-    if (metadata.robots !== undefined) meta.push({ name: 'robots', content: metadata.robots });
-    if (metadata.themeColor !== undefined) {
-        meta.push({ name: 'theme-color', content: metadata.themeColor });
-    }
-    const og = metadata.openGraph;
-    if (og) {
-        const pairs: readonly [string, string | undefined][] = [
-            ['og:title', og.title],
-            ['og:description', og.description],
-            ['og:type', og.type],
-            ['og:url', og.url],
-            ['og:image', og.image],
-            ['og:site_name', og.siteName],
-        ];
-        for (const [property, content] of pairs) {
-            if (content !== undefined) meta.push({ property, content });
-        }
-    }
-    if (metadata.meta) meta.push(...metadata.meta);
-
-    const link: LinkTag[] = [];
-    if (metadata.canonical !== undefined) link.push({ rel: 'canonical', href: metadata.canonical });
-    if (metadata.link) link.push(...metadata.link);
-
-    return { title: metadata.title, meta, link };
-}
-
-/**
- * Applies a route-style {@link Metadata} object from inside any component for that component's
- * lifetime, reverting on unmount. The runtime counterpart of a route's `metadata` export, for
- * content that isn't itself a route file (a rendered article, a widget, ...). Composes through the
- * head manager like {@link useHead}; a route's own `metadata` (applied last) still wins for keys it
- * sets, so this fills in for routes that declare none. Resolved fresh each render, the head manager
- * dedupes by value, so passing a computed object is fine.
- */
-export function useMetadata(metadata: Metadata): void {
-    useHead(resolveMetadata(metadata));
-}
-
-/** Declarative form of {@link useMetadata}: `<Metadata title="…" openGraph={…} />`. Renders nothing. */
-export function Metadata(props: Metadata): null {
-    useMetadata(props);
-    return null;
-}

package/src/client/index.ts

@@ -1,130 +0,0 @@
-/**
- * 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 } from './routing/mount.js';
-export { Router } from './routing/Router.js';
-export {
-    Auth,
-    register as authRegister,
-    login as authLogin,
-    buildLoginMessage,
-    LOGIN_CONTEXT,
-    // Typed auth errors + the discriminant enum: catch `AuthError` (or a specific
-    // subclass) and branch on `err.code === AuthErrorCode.*`, never on `err.name`.
-    AuthError,
-    AuthErrorCode,
-    UsernameTakenError,
-    EmailInUseError,
-    InvalidCredentialsError,
-    EmailNotConfirmedError,
-    TwoFactorRequiredError,
-    ServerAuthFailedError,
-    TwoFactorCodeError,
-    ConfirmationInvalidError,
-    PasswordResetInvalidError,
-    WeakPasswordError,
-    InvalidEmailError,
-    InvalidUsernameError,
-    checkPassword,
-    isValidEmail,
-    isValidUsername,
-    DEFAULT_PASSWORD_POLICY,
-    PASSWORD_RULE_LABELS,
-} from './auth.js';
-export type { KdfParams, AuthOptions, PasswordPolicy, PasswordRule } from './auth.js';
-export { Link } from './navigation/Link.js';
-export type { LinkProps } from './navigation/Link.js';
-export { NavLink, matchActive } from './navigation/NavLink.js';
-export type { NavLinkProps, NavLinkState } from './navigation/NavLink.js';
-export {
-    navigate,
-    back,
-    forward,
-    refresh,
-    setViewTransitions,
-    setTransitions,
-    href,
-} from './navigation/navigation.js';
-export type { NavigateOptions } from './navigation/navigation.js';
-export {
-    useParams,
-    useNavigate,
-    useLocation,
-    usePathname,
-    useSearchParams,
-    useRouter,
-    useNavigationPending,
-    __setSsrLocation,
-} from './routing/hooks.js';
-export type { RouterInstance } from './routing/hooks.js';
-export {
-    useLoaderData,
-    revalidate,
-    invalidateLoaderData,
-    LoaderDataContext,
-} from './routing/loader.js';
-export type {
-    LoaderArgs,
-    LoaderFunction,
-    LoaderData,
-    Revalidate,
-    StaticParams,
-    GenerateStaticParams,
-} from './routing/loader.js';
-export { useAction } from './routing/action.js';
-export type {
-    UseActionOptions,
-    ActionState,
-    ActionHandle,
-    RevalidateTarget,
-} from './routing/action.js';
-export { prefetch } from './navigation/prefetch.js';
-export type {
-    RouteDef,
-    LayoutLoader,
-    LayoutComponentLoader,
-    NotFoundLoader,
-    RouteErrorProps,
-    Register,
-    RoutePath,
-    Href,
-} from './types.js';
-export { matchRoute } from './routing/match.js';
-export type { RouteParams } from './routing/match.js';
-export { connectChannel, useChannel, resolveChannelUrl } from './channel/channel.js';
-export type { Channel, ChannelOptions, ChannelHook, ChannelData } from './channel/channel.js';
-export { makeStreamClient } from './stream/client.js';
-export type { StreamChannel, StreamConnectable, StreamClient } from './stream/client.js';
-export { useHead, useTitle, Head, mergeHead, __drainSsrHead } from './head/head.js';
-export type { HeadSpec, MetaTag, LinkTag, ResolvedHead } from './head/head.js';
-export { resolveMetadata, useMetadata, Metadata } from './head/metadata.js';
-export type { GenerateMetadata, GenerateMetadataArgs, OpenGraph } from './head/metadata.js';
-export { searchPages, registerPages, getPages, pagePath } from './search/search.js';
-export type {
-    PageMeta,
-    PageSearchResult,
-    PageSearchOptions,
-    SearchField,
-    SearchHints,
-} from './search/search.js';
-export { usePageSearch } from './search/use-page-search.js';
-export type { PageSearch } from './search/use-page-search.js';
-export { Image } from './components/Image.js';
-export type { ImageProps, ToilImageSource } from './components/Image.js';
-export { Script } from './components/Script.js';
-export type { ScriptProps, ScriptStrategy } from './components/Script.js';
-export { Form } from './components/Form.js';
-export type { FormProps } from './components/Form.js';
-export { Slot } from './components/Slot.js';
-export type { SlotProps } from './components/Slot.js';
-export { Server } from './rpc.js';
-export { parseError } from './errors.js';
-export { Hole, RawHtml, Repeat, Island, attr, __setSsrBuild, __isSsrBuild } from './ssr/markers.js';
-export type { HoleProps, RawHtmlProps, RepeatProps, IslandProps } from './ssr/markers.js';