toiljs 0.0.116 → 0.0.117

package/src/client/channel/channel.ts

@@ -1,146 +0,0 @@
-/**
- * Client for the toil backend's WebSocket channel (served by the hyper-express/uWS backend at
- * `/_toil`). Supports text and binary (`ArrayBuffer`) frames, auto-reconnect, and a React hook.
- */
-import { useCallback, useEffect, useRef, useState } from 'react';
-
-/** A frame received from / sent to the channel. */
-export type ChannelData = string | ArrayBuffer;
-
-/** Whatever `WebSocket.send` accepts (string / BufferSource / Blob), per the DOM lib. */
-export type SendData = Parameters<WebSocket['send']>[0];
-
-export interface ChannelOptions {
-    /** Channel path on the toil backend. Default `/_toil`. */
-    readonly path?: string;
-    /** Full `ws(s)://` URL override (takes precedence over `path`). */
-    readonly url?: string;
-    /** Auto-reconnect after an unexpected close. Default `true`. */
-    readonly reconnect?: boolean;
-    /** Reconnect delay in ms. Default `1000`. */
-    readonly reconnectDelay?: number;
-}
-
-export interface Channel {
-    /** Sends a text or binary frame (no-op until the socket is open). */
-    send(data: SendData): void;
-    /** Closes the channel and stops reconnecting. */
-    close(): void;
-}
-
-/** Derives the channel's `ws(s)://` URL from the current page location. */
-export function resolveChannelUrl(
-    path: string = '/_toil',
-    location: { protocol: string; host: string } = window.location,
-): string {
-    const scheme = location.protocol === 'https:' ? 'wss:' : 'ws:';
-    const normalized = path.startsWith('/') ? path : `/${path}`;
-    return `${scheme}//${location.host}${normalized}`;
-}
-
-/**
- * Opens a channel to the backend, invoking `onMessage` for each frame. Reconnects on unexpected
- * close unless disabled. Returns a handle to `send()` and `close()`.
- */
-export function connectChannel(
-    onMessage: (data: ChannelData) => void,
-    options: ChannelOptions = {},
-): Channel {
-    const url = options.url ?? resolveChannelUrl(options.path);
-    const reconnect = options.reconnect ?? true;
-    const delay = options.reconnectDelay ?? 1000;
-
-    let socket: WebSocket | null = null;
-    let stopped = false;
-    let timer: ReturnType<typeof setTimeout> | undefined;
-
-    const open = (): void => {
-        const ws = new WebSocket(url);
-        ws.binaryType = 'arraybuffer';
-        socket = ws;
-        ws.addEventListener('message', (event: MessageEvent) => {
-            if (typeof event.data === 'string') onMessage(event.data);
-            else if (event.data instanceof ArrayBuffer) onMessage(event.data);
-        });
-        ws.addEventListener('close', () => {
-            if (!stopped && reconnect) timer = setTimeout(open, delay);
-        });
-    };
-    open();
-
-    return {
-        send: (data: SendData): void => {
-            if (socket && socket.readyState === WebSocket.OPEN) socket.send(data);
-        },
-        close: (): void => {
-            stopped = true;
-            if (timer !== undefined) clearTimeout(timer);
-            socket?.close();
-        },
-    };
-}
-
-export interface ChannelHook {
-    /** Whether the socket is currently open. */
-    readonly connected: boolean;
-    /** Frames received so far, in order. */
-    readonly messages: ChannelData[];
-    /** Sends a text or binary frame. */
-    send: (data: SendData) => void;
-}
-
-/**
- * React hook wrapping {@link connectChannel}: connects on mount, tracks `connected` state and the
- * received `messages`, and cleans up on unmount.
- */
-export function useChannel(options: ChannelOptions = {}): ChannelHook {
-    const { path, url, reconnect, reconnectDelay } = options;
-    const [connected, setConnected] = useState<boolean>(false);
-    const [messages, setMessages] = useState<ChannelData[]>([]);
-    const socketRef = useRef<WebSocket | null>(null);
-
-    useEffect(() => {
-        const target = url ?? resolveChannelUrl(path);
-        const shouldReconnect = reconnect ?? true;
-        const delay = reconnectDelay ?? 1000;
-        let stopped = false;
-        let timer: ReturnType<typeof setTimeout> | undefined;
-
-        const open = (): void => {
-            const ws = new WebSocket(target);
-            ws.binaryType = 'arraybuffer';
-            socketRef.current = ws;
-            ws.addEventListener('open', () => {
-                if (!stopped) setConnected(true);
-            });
-            ws.addEventListener('message', (event: MessageEvent) => {
-                if (typeof event.data === 'string') {
-                    const data = event.data;
-                    setMessages((prev) => [...prev, data]);
-                } else if (event.data instanceof ArrayBuffer) {
-                    const data = event.data;
-                    setMessages((prev) => [...prev, data]);
-                }
-            });
-            ws.addEventListener('close', () => {
-                if (stopped) return;
-                setConnected(false);
-                if (shouldReconnect) timer = setTimeout(open, delay);
-            });
-        };
-        open();
-
-        return () => {
-            stopped = true;
-            if (timer !== undefined) clearTimeout(timer);
-            socketRef.current?.close();
-        };
-    }, [path, url, reconnect, reconnectDelay]);
-
-    const send = useCallback((data: SendData): void => {
-        const socket = socketRef.current;
-        if (socket && socket.readyState === WebSocket.OPEN) socket.send(data);
-    }, []);
-
-    return { connected, messages, send };
-}

package/src/client/components/Form.tsx

@@ -1,65 +0,0 @@
-import { type ReactNode, type SyntheticEvent, useRef } from 'react';
-
-import { type ActionState, type RevalidateTarget, useAction } from '../routing/action.js';
-
-/** Props for {@link Form}. */
-export interface FormProps {
-    /** Handles the submission, receiving the form's `FormData`. May be async. */
-    action: (data: FormData) => void | Promise<void>;
-    /** Loader data to revalidate after a successful submit. Default `true` (the current route). */
-    revalidate?: RevalidateTarget;
-    /** Called after a successful submit. */
-    onSuccess?: () => void;
-    /** Called when the action throws. */
-    onError?: (error: unknown) => void;
-    /** Reset the form fields after a successful submit. Default `false`. */
-    resetOnSuccess?: boolean;
-    className?: string;
-    /**
-     * Form contents. Pass a render function to receive live submit state, e.g. to disable the
-     * button while pending: `{({ pending }) => <button disabled={pending}>Save</button>}`.
-     */
-    children?: ReactNode | ((state: ActionState<void>) => ReactNode);
-}
-
-/**
- * A `<form>` that runs an {@link useAction} on submit (no page reload) and revalidates loader data
- * on success, the write half of the loader/action data loop. Tracks pending/error state, which a
- * render-function child can read.
- */
-export function Form({
-    action,
-    revalidate,
-    onSuccess,
-    onError,
-    resetOnSuccess = false,
-    className,
-    children,
-}: FormProps): ReactNode {
-    const formRef = useRef<HTMLFormElement | null>(null);
-    const handle = useAction((data: FormData) => action(data), {
-        revalidate,
-        onError,
-        onSuccess: () => {
-            if (resetOnSuccess) formRef.current?.reset();
-            onSuccess?.();
-        },
-    });
-
-    const onSubmit = (event: SyntheticEvent<HTMLFormElement>): void => {
-        event.preventDefault();
-        formRef.current = event.currentTarget;
-        void handle.run(new FormData(event.currentTarget));
-    };
-
-    return (
-        <form
-            ref={formRef}
-            className={className}
-            onSubmit={onSubmit}>
-            {typeof children === 'function'
-                ? children({ pending: handle.pending, error: handle.error, data: handle.data })
-                : children}
-        </form>
-    );
-}

package/src/client/components/Image.tsx

@@ -1,160 +0,0 @@
-import { type ComponentPropsWithRef, type CSSProperties, type ReactNode, useState } from 'react';
-
-/**
- * Props for {@link Image}: every standard `<img>` attribute, plus toil's layout/loading controls.
- * `src` and `alt` are required (`alt` is enforced for accessibility, pass `alt=""` for decorative
- * images). `width`/`height` (or `fill`) reserve space to prevent layout shift.
- */
-/** A toil image source carrying an auto-generated blur LQIP + intrinsic size, produced by importing an
- * image with the `?toil` flag (`import hero from './hero.webp?toil'`). Pass it straight to `Image`. */
-export interface ToilImageSource {
-    src: string;
-    width?: number;
-    height?: number;
-    blurDataURL?: string;
-}
-
-export interface ImageProps extends Omit<
-    ComponentPropsWithRef<'img'>,
-    'loading' | 'placeholder' | 'width' | 'height' | 'src'
-> {
-    /** The image URL, or a `?toil` import object that auto-fills the blur placeholder + aspect-ratio. */
-    src: string | ToilImageSource;
-    alt: string;
-    /** Intrinsic width in px. Set together with `height` to reserve space (avoids layout shift). */
-    width?: number;
-    /** Intrinsic height in px. Set together with `width` to reserve space (avoids layout shift). */
-    height?: number;
-    /**
-     * Make the image fill the width of a box toil wraps around it (a block-level `<span>`), scaling to
-     * its natural height — or, if you size the box (`width`/`height`, or `style` like
-     * `aspectRatio: '16/9'`), the image covers that box, cropped per `objectFit` (default `cover`).
-     * The image flows in-block (never absolutely positioned), so it can't escape to fill the page or
-     * collapse to nothing. `className`/`style` apply to the box, not the `<img>`.
-     */
-    fill?: boolean;
-    /** `object-fit` for the rendered image (handy with `fill`). */
-    objectFit?: CSSProperties['objectFit'];
-    /**
-     * Mark this as a high-priority (LCP) image: eager load + `fetchPriority="high"` and no lazy
-     * loading. Use for above-the-fold hero images; everything else stays lazy. Default `false`.
-     */
-    priority?: boolean;
-    /**
-     * Placeholder shown until the image loads: `'empty'` (default) or `'blur'`. `'blur'` paints the
-     * `blurDataURL` (auto-filled from a `?toil` import, or passed) blurred, or a neutral skeleton
-     * shimmer if there's none. It needs a reserved size (`width`+`height`, or `fill`) to paint into —
-     * which also prevents layout shift (the placeholder is cosmetic; the reserved size is what holds).
-     */
-    placeholder?: 'empty' | 'blur';
-    /**
-     * A tiny base64 image shown blurred while the real image loads (with `placeholder="blur"`).
-     * Auto-generated when you import via `?toil` (`import hero from './hero.webp?toil'`); pass it
-     * explicitly only for a string `src`. Omit it to fall back to a neutral skeleton shimmer.
-     */
-    blurDataURL?: string;
-}
-
-/**
- * A drop-in `<img>` replacement that prevents layout shift and lazy-loads by default. It reserves
- * space from `width`/`height` (or fills its container with `fill`), decodes async, lazy-loads unless
- * `priority`, and can fade in from a `blur` placeholder. This is a client-only component, there is
- * no server-side resizing; pass an already-optimized `src` (Vite hashes imported assets for you).
- */
-export function Image(props: ImageProps): ReactNode {
-    const {
-        src: srcProp,
-        alt,
-        width: widthProp,
-        height: heightProp,
-        fill = false,
-        objectFit,
-        priority = false,
-        placeholder = 'empty',
-        blurDataURL: blurDataURLProp,
-        className: userClassName,
-        style,
-        onLoad,
-        ...rest
-    } = props;
-
-    // `src` may be a plain URL or a `?toil` import object; unpack it and let explicit props win, so a
-    // `?toil` import auto-fills the blur placeholder + aspect-ratio with no extra props.
-    const source = typeof srcProp === 'string' ? null : srcProp;
-    const src = typeof srcProp === 'string' ? srcProp : srcProp.src;
-    const width = widthProp ?? source?.width;
-    const height = heightProp ?? source?.height;
-    const blurDataURL = blurDataURLProp ?? source?.blurDataURL;
-
-    const [loaded, setLoaded] = useState(false);
-    // The placeholder paints while the real image loads, then drops on load. With a `blurDataURL`
-    // (auto-filled by a `?toil` import, or passed) it's that tiny image blurred; otherwise it's a
-    // neutral skeleton shimmer — so `placeholder="blur"` is never a silent no-op. It only shows if
-    // there's a reserved box to paint into (give `width`+`height`, or use `fill` in a sized parent).
-    const showPlaceholder = placeholder === 'blur' && !loaded;
-    const placeholderClass = !showPlaceholder
-        ? undefined
-        : blurDataURL !== undefined
-          ? 'toil-img-blur'
-          : 'toil-img-skeleton';
-    // Reserve space so the image can't shift layout when it loads: an explicit aspect-ratio derived
-    // from width+height survives responsive `width:100%` CSS (bare width/height attributes do not).
-    const aspectRatio =
-        width !== undefined && height !== undefined ? `${width} / ${height}` : undefined;
-
-    // Layout + placeholder come from toil's shipped CSS classes (see `buildHtml`'s `<style id="toil-
-    // base">`) not inline styles, so they're SSR-safe AND overridable. Only per-instance bits stay
-    // inline: `objectFit`, the aspect-ratio, and the blur image URL. For a non-`fill` image the
-    // caller's `className`/`style` ride on the <img>; for `fill` they go on the wrapper box below.
-    const imgClass =
-        [fill ? 'toil-img-fill' : userClassName, placeholderClass].filter(Boolean).join(' ') ||
-        undefined;
-    const imgStyle: CSSProperties = {
-        ...(objectFit !== undefined ? { objectFit } : {}),
-        ...(showPlaceholder && blurDataURL !== undefined
-            ? { backgroundImage: `url(${blurDataURL})` }
-            : {}),
-        ...(fill || aspectRatio === undefined ? {} : { aspectRatio }),
-        ...(fill ? {} : style),
-    };
-
-    const img = (
-        <img
-            {...rest}
-            className={imgClass}
-            src={src}
-            alt={alt}
-            width={fill ? undefined : width}
-            height={fill ? undefined : height}
-            loading={priority ? 'eager' : 'lazy'}
-            decoding="async"
-            fetchPriority={priority ? 'high' : 'auto'}
-            onLoad={(event) => {
-                setLoaded(true);
-                onLoad?.(event);
-            }}
-            style={Object.keys(imgStyle).length > 0 ? imgStyle : undefined}
-        />
-    );
-
-    if (!fill) return img;
-
-    // `fill`: the image flows in-block at 100% of its box's width (scaling to natural height), or
-    // covers the box if the caller sizes it (`width`/`height`, or `style` like `aspectRatio`). It is
-    // NEVER absolutely positioned, so it can't escape to fill the page nor collapse to a zero-height
-    // box. We still wrap it so the caller's `width`/`height`/`style` size the box, not the raw `<img>`.
-    const boxStyle: CSSProperties = {
-        ...(aspectRatio !== undefined ? { aspectRatio } : {}),
-        ...(width !== undefined ? { width } : {}),
-        ...(height !== undefined ? { height } : {}),
-        ...style,
-    };
-    return (
-        <span
-            className={[userClassName, 'toil-img-fill-box'].filter(Boolean).join(' ') || undefined}
-            style={Object.keys(boxStyle).length > 0 ? boxStyle : undefined}
-        >
-            {img}
-        </span>
-    );
-}

package/src/client/components/Script.tsx

@@ -1,113 +0,0 @@
-import { type ReactNode, useEffect } from 'react';
-
-/**
- * When a {@link Script} is injected, relative to the app becoming interactive:
- * - `afterInteractive` (default), on mount, once the app is running. Good for analytics, widgets.
- * - `lazyOnload`, deferred until the browser is idle (after `window.load`). For low-priority scripts.
- * - `beforeInteractive`, as early as possible. In a client-only SPA there is no SSR, so this still
- *   runs after hydration, but synchronously on first mount with high fetch priority.
- */
-export type ScriptStrategy = 'beforeInteractive' | 'afterInteractive' | 'lazyOnload';
-
-/** Props for {@link Script}. Provide either `src` (external) or inline `children` (script body). */
-export interface ScriptProps {
-    /** URL of an external script. Omit when providing an inline script body via `children`. */
-    src?: string;
-    /** When to load the script. Default `'afterInteractive'`. */
-    strategy?: ScriptStrategy;
-    /** Stable identity for dedup (required for inline scripts; defaults to `src` for external ones). */
-    id?: string;
-    /** `type` attribute (e.g. `'module'`, `'application/json'`). */
-    type?: string;
-    /** Fired once the script has loaded (external) or been inserted (inline). */
-    onLoad?: () => void;
-    /** Fired after load, and on every later mount once the script is already loaded. */
-    onReady?: () => void;
-    /** Fired if an external script fails to load. */
-    onError?: (error: unknown) => void;
-    /** Inline script body. Mutually exclusive with `src`. */
-    children?: string;
-}
-
-type LoadState = 'loading' | 'ready';
-/** Module-level registry so a given script is injected/executed at most once across the app. */
-const registry = new Map<string, LoadState>();
-
-function inject(props: ScriptProps, key: string): void {
-    const { src, type, onLoad, onReady, onError, children } = props;
-    const el = document.createElement('script');
-    el.dataset.toilScript = key;
-    if (type !== undefined) el.type = type;
-
-    if (src !== undefined) {
-        el.src = src;
-        el.async = true;
-        el.addEventListener('load', () => {
-            registry.set(key, 'ready');
-            onLoad?.();
-            onReady?.();
-        });
-        el.addEventListener('error', (event) => {
-            registry.delete(key); // allow a later remount to retry
-            onError?.(event);
-        });
-        document.head.appendChild(el);
-    } else {
-        el.textContent = children ?? '';
-        document.head.appendChild(el);
-        registry.set(key, 'ready');
-        onLoad?.();
-        onReady?.();
-    }
-}
-
-/**
- * Loads an external or inline `<script>` with a load `strategy`, deduplicated across the app so the
- * same script never executes twice. Renders nothing. Mirrors the ergonomics of Next.js `next/script`
- * for a client-only SPA.
- */
-export function Script(props: ScriptProps): ReactNode {
-    const { src, id, strategy = 'afterInteractive', onReady } = props;
-    const key = id ?? src;
-
-    useEffect(() => {
-        if (key === undefined) {
-            // No id and no src: nothing to dedup or load (an inline script needs at least an id).
-            return;
-        }
-
-        const state = registry.get(key);
-        if (state === 'ready') {
-            onReady?.();
-            return;
-        }
-        if (state === 'loading') {
-            return; // another instance is already injecting it
-        }
-
-        registry.set(key, 'loading');
-        const run = (): void => {
-            inject(props, key);
-        };
-
-        if (strategy === 'lazyOnload') {
-            if (document.readyState === 'complete') {
-                const idle = window.requestIdleCallback?.bind(window);
-                if (idle) idle(run);
-                else setTimeout(run, 0);
-            } else {
-                window.addEventListener('load', run, { once: true });
-            }
-            return () => {
-                window.removeEventListener('load', run);
-            };
-        }
-
-        // beforeInteractive + afterInteractive: inject now (on mount).
-        run();
-        // Intentionally keyed on identity only: inject once per script key; later prop changes
-        // (handlers, body) are read at inject time and must not re-run/re-inject the script.
-    }, [key, strategy]);
-
-    return null;
-}

package/src/client/components/Slot.tsx

@@ -1,21 +0,0 @@
-import { type ReactNode, useContext } from 'react';
-
-import { SlotContext } from '../routing/slot-context.js';
-
-/** Props for {@link Slot}. */
-export interface SlotProps {
-    /** The parallel-slot name, the `@name` directory under `routes/` (without the `@`). */
-    name: string;
-    /** Rendered when the slot has no match for the current URL. Default `null`. */
-    fallback?: ReactNode;
-}
-
-/**
- * Renders the parallel-route slot named `name` for the current URL. Place it in a layout or page to
- * show an `@name` route tree alongside the main content (e.g. a persistent sidebar, or a modal that
- * an intercepting route fills). Renders `fallback` (default nothing) when no slot route matches.
- */
-export function Slot({ name, fallback = null }: SlotProps): ReactNode {
-    const slots = useContext(SlotContext);
-    return slots[name] ?? fallback;
-}