toiljs 0.0.7 → 0.0.8

package/src/cli/features.ts

@@ -114,6 +114,38 @@ export function setStyleImports(source: string, f: StyleFeatures): string {
     return `${head}\n\n${block}\n${tail}`.replace(/\n{3,}/g, '\n\n');
 }
 
+/** A `toil.config` source containing `client: { images: <bool> }` (for scaffolding when none exists). */
+export function defaultConfigSource(images: boolean): string {
+    return (
+        "import { defineConfig } from 'toiljs/compiler';\n\n" +
+        'export default defineConfig({\n' +
+        '    client: {\n' +
+        '        // Optimize images at build time (resize/compress imported images).\n' +
+        `        images: ${String(images)},\n` +
+        '    },\n' +
+        '});\n'
+    );
+}
+
+/**
+ * Sets the `client.images` flag in a `toil.config` source, returning the updated source — or `null`
+ * if the file's shape isn't recognized (the caller should then fall back to a manual note). Handles
+ * an existing `images:` value, an existing `client: {` block, or a bare `defineConfig({ … })`.
+ */
+export function setConfigImages(source: string, enabled: boolean): string | null {
+    const value = String(enabled);
+    if (/\bimages\s*:\s*(?:true|false)/.test(source)) {
+        return source.replace(/\bimages\s*:\s*(?:true|false)/, `images: ${value}`);
+    }
+    if (/\bclient\s*:\s*\{/.test(source)) {
+        return source.replace(/\bclient\s*:\s*\{/, `client: {\n        images: ${value},`);
+    }
+    if (/defineConfig\(\s*\{/.test(source)) {
+        return source.replace(/defineConfig\(\s*\{/, `defineConfig({\n    client: { images: ${value} },`);
+    }
+    return null;
+}
+
 /** Detects the active preprocessor from a project's combined dependency map. */
 export function detectPreprocessor(deps: Record<string, string>): Preprocessor {
     if ('sass' in deps) return 'sass';

package/src/cli/index.ts

@@ -19,6 +19,7 @@ interface Flags {
     preprocessor?: Preprocessor;
     tailwind?: boolean;
     ai?: boolean;
+    images?: boolean;
     install?: boolean;
     git?: boolean;
     pm?: string;
@@ -64,6 +65,12 @@ function parseArgs(argv: string[]): Flags {
             case '--no-ai':
                 flags.ai = false;
                 break;
+            case '--images':
+                flags.images = true;
+                break;
+            case '--no-images':
+                flags.images = false;
+                break;
             case '--install':
                 flags.install = true;
                 break;
@@ -134,6 +141,7 @@ async function main(): Promise<void> {
                 preprocessor: flags.preprocessor,
                 tailwind: flags.tailwind,
                 ai: flags.ai,
+                images: flags.images,
                 install: flags.install,
                 git: flags.git,
                 pm: flags.pm,
@@ -148,6 +156,7 @@ async function main(): Promise<void> {
                 root: flags.root,
                 preprocessor: flags.preprocessor,
                 tailwind: flags.tailwind,
+                images: flags.images,
                 install: flags.install,
                 cwd: process.cwd(),
             });

package/src/client/components/Form.tsx

@@ -0,0 +1,65 @@
+import { useRef, type ReactNode, type SyntheticEvent } from 'react';
+
+import { useAction, type ActionState, type RevalidateTarget } 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

@@ -0,0 +1,89 @@
+import { useState, type CSSProperties, type ComponentPropsWithRef, type ReactNode } 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.
+ */
+export interface ImageProps
+    extends Omit<ComponentPropsWithRef<'img'>, 'loading' | 'placeholder' | 'width' | 'height'> {
+    src: string;
+    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;
+    /**
+     * Fill the nearest positioned ancestor (the parent must be `position: relative|absolute|fixed`).
+     * The image is absolutely positioned at 100% × 100%; `width`/`height` are ignored. Pair with
+     * `objectFit` to control cropping.
+     */
+    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'` (needs `blurDataURL`). */
+    placeholder?: 'empty' | 'blur';
+    /** A tiny (base64) image shown blurred behind the image while it loads, when `placeholder="blur"`. */
+    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,
+        alt,
+        width,
+        height,
+        fill = false,
+        objectFit,
+        priority = false,
+        placeholder = 'empty',
+        blurDataURL,
+        style,
+        onLoad,
+        ...rest
+    } = props;
+
+    const [loaded, setLoaded] = useState(false);
+    const showBlur = placeholder === 'blur' && blurDataURL !== undefined && !loaded;
+
+    const layoutStyle: CSSProperties = fill
+        ? { position: 'absolute', inset: 0, width: '100%', height: '100%' }
+        : {};
+    const blurStyle: CSSProperties = showBlur
+        ? {
+              backgroundImage: `url(${blurDataURL})`,
+              backgroundSize: 'cover',
+              backgroundPosition: 'center',
+              filter: 'blur(20px)',
+          }
+        : {};
+
+    return (
+        <img
+            {...rest}
+            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={{ ...layoutStyle, objectFit, ...blurStyle, ...style }}
+        />
+    );
+}

package/src/client/components/Script.tsx

@@ -0,0 +1,113 @@
+import { useEffect, type ReactNode } 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/index.ts

@@ -26,8 +26,15 @@ export {
     useNavigationPending,
 } from './routing/hooks.js';
 export type { RouterInstance } from './routing/hooks.js';
-export { useLoaderData } from './routing/loader.js';
-export type { LoaderArgs, LoaderFunction } from './routing/loader.js';
+export { useLoaderData, revalidate, invalidateLoaderData } from './routing/loader.js';
+export type { LoaderArgs, LoaderFunction, LoaderData, Revalidate } 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,
@@ -45,3 +52,9 @@ export { connectChannel, useChannel, resolveChannelUrl } from './channel/channel
 export type { Channel, ChannelOptions, ChannelHook, ChannelData } from './channel/channel.js';
 export { useHead, useTitle, Head, mergeHead } from './head/head.js';
 export type { HeadSpec, MetaTag, LinkTag, ResolvedHead } from './head/head.js';
+export { Image } from './components/Image.js';
+export type { ImageProps } 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';

package/src/client/routing/Router.tsx

@@ -9,7 +9,7 @@ import {
     resolveLayout,
     resolveNotFound,
 } from './lazy.js';
-import { LoaderDataContext, readRouteData } from './loader.js';
+import { loaderKey, LoaderDataContext, readRouteData } from './loader.js';
 import { matchRoute, type RouteParams } from './match.js';
 import { ParamsContext } from './params-context.js';
 import { navigationEpoch, settleNavigation } from '../navigation/navigation.js';
@@ -17,8 +17,13 @@ import { applyScroll } from '../navigation/scroll.js';
 import type { ErrorComponentLoader, LayoutLoader, NotFoundLoader, RouteDef } from '../types.js';
 
 /** Loads a matched route's module + loader data (suspending), then renders it with the data in context. */
-function RoutePage(props: { route: RouteDef; params: RouteParams; dataKey: string }): ReactNode {
-    const { Component, data } = readRouteData(props.route, props.params, props.dataKey);
+function RoutePage(props: {
+    route: RouteDef;
+    params: RouteParams;
+    dataKey: string;
+    epoch: number;
+}): ReactNode {
+    const { Component, data } = readRouteData(props.route, props.params, props.dataKey, props.epoch);
     return <LoaderDataContext.Provider value={data}>{createElement(Component)}</LoaderDataContext.Provider>;
 }
 
@@ -56,13 +61,20 @@ export function Router(props: {
             ? createElement(Suspense, { fallback: null }, createElement(loadingComponent(matched.loading)))
             : null;
         const search = typeof window === 'undefined' ? '' : window.location.search;
-        const dataKey = `${String(navigationEpoch())}:${pathname}${search}`;
+        const dataKey = loaderKey(pathname, search);
+        // Navigation runs in a transition (smooth — the old page stays during load). A route with a
+        // `loading.tsx` opts into an immediate loading state: keying its Suspense boundary per URL
+        // makes React show the fallback even inside the transition. Routes without one keep a stable
+        // boundary, so the transition holds the previous page instead of flashing a blank fallback.
         content = (
-            <Suspense fallback={fallback}>
+            <Suspense
+                key={matched.loading ? dataKey : undefined}
+                fallback={fallback}>
                 <RoutePage
                     route={matched}
                     params={params}
                     dataKey={dataKey}
+                    epoch={navigationEpoch()}
                 />
             </Suspense>
         );

package/src/client/routing/action.ts

@@ -0,0 +1,122 @@
+/**
+ * Mutations (writes) — the counterpart to loaders (reads). A loader fetches data on navigation;
+ * an action performs a write (save, delete, a server/WASM call) on demand, then revalidates the
+ * affected loader data so the UI reflects the change. `useAction` tracks pending/error/result state;
+ * `<Form>` is sugar over it for the form case.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { invalidateLoaderData } from './loader.js';
+import { refresh } from '../navigation/navigation.js';
+import type { Href } from '../types.js';
+
+/**
+ * Which loader data to refetch after an action succeeds:
+ * - `true` (default) — the current route.
+ * - an `Href` (or array) — those specific routes.
+ * - `false` — nothing.
+ */
+export type RevalidateTarget = boolean | Href | readonly Href[];
+
+/** Options for {@link useAction}. */
+export interface UseActionOptions<TData> {
+    /** Loader data to revalidate after success. Default `true` (the current route). */
+    readonly revalidate?: RevalidateTarget;
+    /** Called after a successful run, with the action's return value. */
+    readonly onSuccess?: (data: TData) => void;
+    /** Called when the action throws. */
+    readonly onError?: (error: unknown) => void;
+}
+
+/** Live state of an action. */
+export interface ActionState<TData> {
+    /** True while a run is in flight. */
+    readonly pending: boolean;
+    /** The error from the last failed run, or `undefined`. */
+    readonly error: unknown;
+    /** The value returned by the last successful run, or `undefined`. */
+    readonly data: TData | undefined;
+}
+
+/** Handle returned by {@link useAction}: current state plus `run` / `reset`. */
+export interface ActionHandle<TInput, TData> extends ActionState<TData> {
+    /**
+     * Run the action. Resolves to the result on success, or `undefined` if it threw (the error is
+     * captured in `error` instead of rejecting, so a fire-and-forget `onClick` can't leak an
+     * unhandled rejection).
+     */
+    run: (input: TInput) => Promise<TData | undefined>;
+    /** Reset back to idle (clears `pending` / `error` / `data`). */
+    reset: () => void;
+}
+
+/** Refetches loader data per a {@link RevalidateTarget}, then re-renders once. */
+function applyRevalidate(target: RevalidateTarget | undefined): void {
+    if (target === false) return;
+    if (target === undefined || target === true) {
+        invalidateLoaderData();
+    } else {
+        const hrefs = typeof target === 'string' ? [target] : target;
+        for (const href of hrefs) invalidateLoaderData(href);
+    }
+    refresh();
+}
+
+/**
+ * Runs a mutation with pending/error/result tracking, revalidating loader data on success. Example:
+ *
+ * ```ts
+ * const save = useAction((title: string) => api.save(title), { revalidate: true });
+ * <button disabled={save.pending} onClick={() => void save.run(title)}>Save</button>
+ * ```
+ */
+export function useAction<TInput = void, TData = unknown>(
+    fn: (input: TInput) => TData | Promise<TData>,
+    options: UseActionOptions<TData> = {},
+): ActionHandle<TInput, TData> {
+    const [state, setState] = useState<ActionState<TData>>({
+        pending: false,
+        error: undefined,
+        data: undefined,
+    });
+
+    // Hold the latest fn/options so `run` keeps a stable identity across renders.
+    const latest = useRef({ fn, options });
+    latest.current = { fn, options };
+    const runId = useRef(0);
+    const mounted = useRef(true);
+    useEffect(
+        () => () => {
+            mounted.current = false;
+        },
+        [],
+    );
+
+    const run = useCallback(async (input: TInput): Promise<TData | undefined> => {
+        const id = ++runId.current;
+        setState((s) => ({ ...s, pending: true, error: undefined }));
+        try {
+            const data = await latest.current.fn(input);
+            // Ignore a stale run that a newer one (or unmount) has superseded.
+            if (mounted.current && id === runId.current) {
+                setState({ pending: false, error: undefined, data });
+            }
+            applyRevalidate(latest.current.options.revalidate);
+            latest.current.options.onSuccess?.(data);
+            return data;
+        } catch (error) {
+            if (mounted.current && id === runId.current) {
+                setState({ pending: false, error, data: undefined });
+            }
+            latest.current.options.onError?.(error);
+            return undefined;
+        }
+    }, []);
+
+    const reset = useCallback(() => {
+        runId.current += 1;
+        setState({ pending: false, error: undefined, data: undefined });
+    }, []);
+
+    return { ...state, run, reset };
+}

package/src/client/routing/hooks.ts

@@ -22,7 +22,7 @@ import {
     subscribePending,
     type NavigateOptions,
 } from '../navigation/navigation.js';
-import { clearLoaderData } from './loader.js';
+import { clearLoaderData, revalidate as revalidateData } from './loader.js';
 import { ParamsContext } from './params-context.js';
 import { prefetch } from '../navigation/prefetch.js';
 import type { Href } from '../types.js';
@@ -37,8 +37,13 @@ export interface RouterInstance {
     back(): void;
     /** Go forward one history entry. */
     forward(): void;
-    /** Re-render the current route and re-run its loader. */
+    /** Re-render the current route and re-run its loader (clears all cached loader data). */
     refresh(): void;
+    /**
+     * Invalidate cached loader data and re-render so it refetches. No argument refetches the active
+     * route; pass an `href` to target a specific route. Use after a mutation.
+     */
+    revalidate(href?: Href): void;
     /** Prefetch a route's chunk ahead of navigation. */
     prefetch(href: Href): void;
 }
@@ -56,6 +61,9 @@ const ROUTER: RouterInstance = {
         clearLoaderData();
         refresh();
     },
+    revalidate: (href) => {
+        revalidateData(href);
+    },
     prefetch,
 };
 
@@ -75,9 +83,14 @@ export function useRouter(): RouterInstance {
 }
 
 /**
- * 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.
+ * Subscribes to location changes and reads the live `window.location` on render. Re-renders on any
+ * pathname, search, or hash change.
+ *
+ * The update runs in a `startTransition` so navigation is smooth: React keeps the current page on
+ * screen while the next route's chunk/data load, instead of flashing a blank fallback. Routes that
+ * define a `loading.tsx` opt back into an immediate loading state — the Router keys their Suspense
+ * boundary per navigation, so the fallback shows even within the transition (no frozen page). Warm
+ * routes (prefetched, no loader) render synchronously and commit instantly.
  */
 function useLocationSubscription(): void {
     const [, forceUpdate] = useReducer((n: number): number => n + 1, 0);