toiljs 0.0.7 → 0.0.9

package/src/cli/configure.ts

@@ -1,5 +1,5 @@
 /**
- * `toiljs configure` — toggle a project's client styling features (CSS preprocessor + Tailwind) on
+ * `toiljs configure`, toggle a project's client styling features (CSS preprocessor + Tailwind) on
  * an existing app. Detects the current setup, prompts for the desired one, then rewrites the
  * stylesheet(s) + the `client/toil.tsx` imports, edits `package.json`, and syncs node_modules with
  * the project's package manager (so removed features are fully cleaned, not just disabled).
@@ -16,10 +16,12 @@ import {
     PREPROCESSORS,
     TAILWIND_CSS,
     TAILWIND_ENTRY,
+    defaultConfigSource,
     detectPreprocessor,
     detectTailwind,
     packageDiff,
     preprocessorForExt,
+    setConfigImages,
     setStyleImports,
     styleEntry,
     type Preprocessor,
@@ -34,10 +36,60 @@ export interface ConfigureOptions {
     /** When set, the corresponding prompt is skipped (non-interactive). */
     readonly preprocessor?: Preprocessor;
     readonly tailwind?: boolean;
+    /** Toggle build-time image optimization. When set, the prompt is skipped. */
+    readonly images?: boolean;
     /** Run the package manager to sync deps. Default `true`; `false` edits files only. */
     readonly install?: boolean;
 }
 
+const CONFIG_FILES = [
+    'toil.config.ts',
+    'toil.config.mts',
+    'toil.config.js',
+    'toil.config.mjs',
+    'toiljs.config.ts',
+    'toiljs.config.mts',
+    'toiljs.config.js',
+    'toiljs.config.mjs',
+];
+
+/** Reads the project's `toil.config.*` (path + source), or null if none exists. */
+async function readConfigFile(root: string): Promise<{ path: string; source: string } | null> {
+    for (const name of CONFIG_FILES) {
+        const p = path.join(root, name);
+        try {
+            return { path: p, source: await fs.readFile(p, 'utf8') };
+        } catch {}
+    }
+    return null;
+}
+
+/**
+ * Persists `client.images` to the project's `toil.config`. Edits an existing config in place (or
+ * creates `toil.config.ts` if none); returns `false` if the existing file's shape couldn't be
+ * edited, so the caller can tell the user to set it by hand.
+ */
+async function writeImagesFlag(root: string, enabled: boolean): Promise<boolean> {
+    const existing = await readConfigFile(root);
+    if (!existing) {
+        await fs.writeFile(path.join(root, 'toil.config.ts'), defaultConfigSource(enabled), 'utf8');
+        return true;
+    }
+    const next = setConfigImages(existing.source, enabled);
+    if (next === null) return false;
+    await fs.writeFile(existing.path, next, 'utf8');
+    return true;
+}
+
+/** Current `client.images` setting (defaults to `true` when the config can't be loaded). */
+async function resolveImages(root: string): Promise<boolean> {
+    try {
+        return (await loadConfig({ root })).images;
+    } catch {
+        return true;
+    }
+}
+
 /** Resolves the client source dir, falling back to `<root>/client` if the config can't be loaded. */
 async function resolveClientDir(root: string): Promise<string> {
     try {
@@ -121,7 +173,7 @@ async function applyStyleFiles(
         const newPath = path.join(clientDir, styleEntry(to.preprocessor));
         await fs.mkdir(path.dirname(newPath), { recursive: true });
         // Rename whatever main stylesheet actually exists (preserving its content), not an assumed
-        // name — so we never blow away the user's styles when the on-disk extension differs.
+        // name, so we never blow away the user's styles when the on-disk extension differs.
         const existing = await findMainStylesheet(clientDir);
         if (existing && path.resolve(existing) !== path.resolve(newPath)) {
             await fs.rename(existing, newPath);
@@ -213,7 +265,7 @@ export async function runConfigure(opts: ConfigureOptions): Promise<void> {
     try {
         pkg = JSON.parse(await fs.readFile(pkgPath, 'utf8')) as PackageJson;
     } catch {
-        cancel(`No package.json in ${pc.cyan(root)} — run this inside a toiljs project.`);
+        cancel(`No package.json in ${pc.cyan(root)}, run this inside a toiljs project.`);
         process.exit(1);
     }
 
@@ -224,13 +276,18 @@ export async function runConfigure(opts: ConfigureOptions): Promise<void> {
         tailwind: detectTailwind(deps),
     };
 
-    const nonInteractive = opts.preprocessor !== undefined || opts.tailwind !== undefined;
+    const currentImages = await resolveImages(root);
+
+    const nonInteractive =
+        opts.preprocessor !== undefined || opts.tailwind !== undefined || opts.images !== undefined;
     let target: StyleFeatures;
+    let targetImages: boolean;
     if (nonInteractive) {
         target = {
             preprocessor: opts.preprocessor ?? current.preprocessor,
             tailwind: opts.tailwind ?? current.tailwind,
         };
+        targetImages = opts.images ?? currentImages;
     } else {
         const ppChoice = await select<Preprocessor>({
             message: 'CSS preprocessor',
@@ -240,33 +297,57 @@ export async function runConfigure(opts: ConfigureOptions): Promise<void> {
         bail(ppChoice);
         const twChoice = await confirm({ message: 'Use Tailwind CSS?', initialValue: current.tailwind });
         bail(twChoice);
+        const imChoice = await confirm({
+            message: 'Optimize images at build time?',
+            initialValue: currentImages,
+        });
+        bail(imChoice);
         target = { preprocessor: ppChoice, tailwind: twChoice };
+        targetImages = imChoice;
     }
 
-    if (target.preprocessor === current.preprocessor && target.tailwind === current.tailwind) {
-        outro('No changes — your styling setup is already up to date.');
+    const styleChanged =
+        target.preprocessor !== current.preprocessor || target.tailwind !== current.tailwind;
+    const imagesChanged = targetImages !== currentImages;
+    if (!styleChanged && !imagesChanged) {
+        outro('No changes, your setup is already up to date.');
         return;
     }
 
     const s = spinner();
     s.start('Updating project files');
-    await applyConfigure(clientAbsDir, pkgPath, pkg, current, target);
-    s.stop('Updated stylesheets, entry imports, and package.json');
+    if (styleChanged) await applyConfigure(clientAbsDir, pkgPath, pkg, current, target);
+    let imagesWarning = '';
+    if (imagesChanged && !(await writeImagesFlag(root, targetImages))) {
+        imagesWarning = pc.yellow(
+            ' Could not edit toil.config automatically, set `client.images` by hand.',
+        );
+    }
+    s.stop('Updated project files');
 
-    const pm = await detectPackageManager(root);
-    if (opts.install === false) {
-        note(`${pc.cyan(`${pm} install`)} to sync the dependency changes.`, 'Next step');
-    } else {
-        const i = spinner();
-        i.start(`Syncing dependencies with ${pm}`);
-        try {
-            await run(pm, ['install'], root);
-            i.stop('Dependencies synced');
-        } catch {
-            i.stop(pc.yellow(`Could not run \`${pm} install\` — run it yourself to finish`));
+    if (styleChanged) {
+        const pm = await detectPackageManager(root);
+        if (opts.install === false) {
+            note(`${pc.cyan(`${pm} install`)} to sync the dependency changes.`, 'Next step');
+        } else {
+            const i = spinner();
+            i.start(`Syncing dependencies with ${pm}`);
+            try {
+                await run(pm, ['install'], root);
+                i.stop('Dependencies synced');
+            } catch {
+                i.stop(pc.yellow(`Could not run \`${pm} install\`, run it yourself to finish`));
+            }
         }
     }
 
-    note(describe(current, target), 'Styling updated');
-    outro(`Reconfigured — restart \`${accent('toiljs dev')}\` to pick up the changes.`);
+    const summary = [
+        styleChanged ? describe(current, target) : '',
+        imagesChanged ? dim('  ') + `image optimization: ${currentImages ? 'on' : 'off'} → ${targetImages ? 'on' : 'off'}` : '',
+        imagesWarning,
+    ]
+        .filter(Boolean)
+        .join('\n');
+    note(summary, 'Updated');
+    outro(`Reconfigured, restart \`${accent('toiljs dev')}\` to pick up the changes.`);
 }

package/src/cli/create.ts

@@ -1,5 +1,5 @@
 /**
- * `toiljs create` — an interactive project scaffolder (Clack-powered) that wires a new
+ * `toiljs create`, an interactive project scaffolder (Clack-powered) that wires a new
  * app to the enforced toiljs presets (tsconfig / eslint / prettier) and file-based routing.
  * Supports a non-interactive path via flags (`--yes`, `--template`, …) for scripting/CI.
  */
@@ -74,6 +74,8 @@ export interface CreateOptions {
     readonly tailwind?: boolean;
     /** AI assistant files to scaffold: `true` = all, `false` = none, omitted = ask. */
     readonly ai?: boolean;
+    /** Enable build-time image optimization. Default `true`; omitted = ask. */
+    readonly images?: boolean;
     readonly install?: boolean;
     readonly git?: boolean;
     readonly pm?: string;
@@ -104,6 +106,7 @@ function scaffold(
     template: Template,
     features: StyleFeatures,
     aiTools: readonly string[],
+    images: boolean,
 ): Record<string, string> {
     const toilVersion = version();
     const devDependencies: Record<string, string> = {
@@ -142,7 +145,12 @@ function scaffold(
         'package.json': JSON.stringify(pkg, null, 4) + '\n',
         'toil.config.ts':
             "import { defineConfig } from 'toiljs/compiler';\n\n" +
-            'export default defineConfig({});\n',
+            'export default defineConfig({\n' +
+            '    client: {\n' +
+            '        // Optimize images at build time (resize/compress imported images).\n' +
+            `        images: ${String(images)},\n` +
+            '    },\n' +
+            '});\n',
         'tsconfig.json':
             '{\n    "extends": "toiljs/tsconfig",\n    "include": ["client", "toil-env.d.ts", "toil-routes.d.ts"]\n}\n',
         'eslint.config.js': "import toiljs from 'toiljs/eslint';\n\nexport default toiljs;\n",
@@ -153,7 +161,7 @@ function scaffold(
             JSON.stringify({ 'typescript.tsdk': 'node_modules/typescript/lib' }, null, 4) + '\n',
         'toil-env.d.ts': TOIL_ENV_DTS,
         // Stub typed-routes augmentation (RoutePath = string until the first dev/build regenerates it).
-        'toil-routes.d.ts': '// AUTO-GENERATED by toil — do not edit.\nexport {};\n',
+        'toil-routes.d.ts': '// AUTO-GENERATED by toil, do not edit.\nexport {};\n',
         'toilconfig.json':
             JSON.stringify(
                 {
@@ -304,7 +312,7 @@ export default function Layout({ children }: { children?: ReactNode }) {
 
 /**
  * Absolute path to the `app` starter client UI. There is a single source: `examples/basic/client`
- * (shipped in the package) — the runnable example IS the create template, so there's nothing to
+ * (shipped in the package), the runnable example IS the create template, so there's nothing to
  * keep in sync.
  */
 function appClientDir(): string {
@@ -323,7 +331,7 @@ function appClientDir(): string {
  * preprocessor's extension, adds the Tailwind entry, and rewrites `toil.tsx`'s style imports.
  */
 async function applyStyling(clientDir: string, features: StyleFeatures): Promise<void> {
-    // Plain CSS without Tailwind is exactly what the template ships — leave it byte-for-byte.
+    // Plain CSS without Tailwind is exactly what the template ships, leave it byte-for-byte.
     if (features.preprocessor === 'css' && !features.tailwind) return;
     const entry = styleEntry(features.preprocessor);
     if (entry !== 'styles/main.css') {
@@ -398,7 +406,7 @@ export async function runCreate(opts: CreateOptions): Promise<void> {
     let template: Template = opts.template ?? 'app';
     if (!opts.template && !opts.yes) {
         const templateOptions: TemplateOption[] = [
-            { value: 'app', label: 'App', hint: 'the full ToilJS starter — landing page, layout, styles, demo routes' },
+            { value: 'app', label: 'App', hint: 'the full ToilJS starter, landing page, layout, styles, demo routes' },
             { value: 'minimal', label: 'Minimal', hint: 'just a layout and a home route' },
         ];
         const choice = await select({ message: 'Which template?', options: templateOptions, initialValue: 'app' });
@@ -443,6 +451,14 @@ export async function runCreate(opts: CreateOptions): Promise<void> {
         aiTools = picked.includes('none') ? [] : picked;
     }
 
+    // Build-time image optimization: on by default (just press enter to keep it).
+    let images = opts.images ?? true;
+    if (opts.images === undefined && !opts.yes) {
+        const im = await confirm({ message: 'Optimize images at build time?', initialValue: true });
+        bail(im);
+        images = im;
+    }
+
     let initGit = opts.git ?? false;
     let install = opts.install ?? false;
     const pm = opts.pm ?? 'npm';
@@ -465,7 +481,7 @@ export async function runCreate(opts: CreateOptions): Promise<void> {
 
     const s = spinner();
     s.start('Scaffolding project');
-    await writeFiles(targetDir, scaffold(name, template, features, aiTools));
+    await writeFiles(targetDir, scaffold(name, template, features, aiTools, images));
     if (template === 'app') {
         // Copy the example client (the single starter source), set its <title>, then apply styling.
         await fs.cp(appClientDir(), path.join(targetDir, 'client'), { recursive: true });
@@ -498,7 +514,7 @@ export async function runCreate(opts: CreateOptions): Promise<void> {
             await run(pm, ['install'], targetDir);
             i.stop('Installed dependencies');
         } catch {
-            i.stop(pc.yellow(`Could not install with ${pm} — run it yourself later`));
+            i.stop(pc.yellow(`Could not install with ${pm}, run it yourself later`));
             install = false;
         }
     }
@@ -510,5 +526,5 @@ export async function runCreate(opts: CreateOptions): Promise<void> {
     steps.push(`${accent('npm run build')} ${dim('build for production')}`);
     note(steps.map((l) => dim('  ') + l).join('\n'), 'Next steps');
 
-    outro(`Created ${accent(path.basename(name))} — happy building! ${dim('· v' + version())}`);
+    outro(`Created ${accent(path.basename(name))}, happy building! ${dim('· v' + version())}`);
 }

package/src/cli/features.ts

@@ -1,5 +1,5 @@
 /**
- * Pure description of toiljs's optional client styling features — a CSS preprocessor and Tailwind —
+ * Pure description of toiljs's optional client styling features, a CSS preprocessor and Tailwind , 
  * shared by `create` (scaffold) and `configure` (toggle on existing projects). Dependency-light
  * (no node IO) so it can be unit-tested; the file writes and package-manager calls live in the
  * commands. Preprocessor and Tailwind are independent: Tailwind lives in its own `.css` entry so
@@ -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

@@ -2,7 +2,7 @@
 /**
  * toiljs CLI. Routes `create` / `dev` / `build` and wraps them in the toiljs brand banner.
  * The compiler stays presentation-free (imported via the package's own `toiljs/compiler`
- * export); the epic bits — banner, the Clack scaffolding wizard — live here.
+ * export); the epic bits, banner, the Clack scaffolding wizard, live here.
  */
 import { build, dev, start } from 'toiljs/compiler';
 
@@ -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/cli/ui.ts

@@ -54,7 +54,7 @@ export function success(s: string): string {
     return rgb(ACCENT, s);
 }
 
-/** Error accent (red — kept outside the brand palette since errors should read as errors). */
+/** Error accent (red, kept outside the brand palette since errors should read as errors). */
 export const danger = pc.red;
 
 function lerp(a: number, b: number, t: number): number {

package/src/cli/validate.ts

@@ -1,5 +1,5 @@
 /**
- * Pure input validation for `toiljs create` — kept dependency-light (only node:path) so it can be
+ * Pure input validation for `toiljs create`, kept dependency-light (only node:path) so it can be
  * unit-tested without pulling in the rest of the CLI.
  */
 import path from 'node:path';

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 }}
+        />
+    );
+}