toiljs 0.0.79 → 0.0.81

package/src/client/components/Image.tsx

@@ -5,21 +5,32 @@ import { type ComponentPropsWithRef, type CSSProperties, type ReactNode, useStat
  * `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'
+    'loading' | 'placeholder' | 'width' | 'height' | 'src'
 > {
-    src: string;
+    /** 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;
     /**
-     * Fill a box toil wraps around the image (a relatively-positioned, block-level `<span>`), so the
-     * image can never escape to fill the page. Size the box via `width`/`height` or `style` (e.g.
-     * `style={{ aspectRatio: '16/9' }}`); `className`/`style` apply to the box, not the `<img>`. Pair
-     * with `objectFit` to control cropping.
+     * 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`). */
@@ -30,12 +41,17 @@ export interface ImageProps extends Omit<
      */
     priority?: boolean;
     /**
-     * Placeholder shown until the image loads: `'empty'` (default) or `'blur'`. `'blur'` needs
-     * `blurDataURL` AND a reserved size (`width`+`height`, or `fill`) — without a box there's nothing
-     * to paint it in. Layout shift is prevented by the reserved size, not by the placeholder.
+     * 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 behind the image while it loads, when `placeholder="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;
 }
 
@@ -47,36 +63,58 @@ export interface ImageProps extends Omit<
  */
 export function Image(props: ImageProps): ReactNode {
     const {
-        src,
+        src: srcProp,
         alt,
-        width,
-        height,
+        width: widthProp,
+        height: heightProp,
         fill = false,
         objectFit,
         priority = false,
         placeholder = 'empty',
-        blurDataURL,
+        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);
-    const showBlur = placeholder === 'blur' && blurDataURL !== undefined && !loaded;
+    // 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 + the blur placeholder come from toil's shipped CSS classes (see `buildHtml`'s
-    // `<style id="toil-base">`) rather than inline styles, so they're SSR-safe AND overridable by the
-    // app's CSS. Only genuinely per-instance bits stay inline: `objectFit` 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) instead, since that box is what the caller sizes.
+    // 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, showBlur ? 'toil-img-blur' : undefined]
-            .filter(Boolean)
-            .join(' ') || undefined;
+        [fill ? 'toil-img-fill' : userClassName, placeholderClass].filter(Boolean).join(' ') ||
+        undefined;
     const imgStyle: CSSProperties = {
         ...(objectFit !== undefined ? { objectFit } : {}),
-        ...(showBlur ? { backgroundImage: `url(${blurDataURL})` } : {}),
+        ...(showPlaceholder && blurDataURL !== undefined
+            ? { backgroundImage: `url(${blurDataURL})` }
+            : {}),
+        ...(fill || aspectRatio === undefined ? {} : { aspectRatio }),
         ...(fill ? {} : style),
     };
 
@@ -101,11 +139,12 @@ export function Image(props: ImageProps): ReactNode {
 
     if (!fill) return img;
 
-    // `fill`: the image is absolutely positioned, so without a positioned ancestor it escapes to fill
-    // the nearest positioned one (often the whole page). Wrap it in our OWN relatively-positioned,
-    // block-level box so it can only ever fill THIS box, which the caller sizes via `width`/`height`
-    // or `style` (e.g. `<Image fill width={400} height={300} />` or `style={{ aspectRatio: '16/9' }}`).
+    // `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,

package/src/client/index.ts

@@ -96,7 +96,7 @@ export type {
 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 } 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';

package/src/compiler/generate.ts

@@ -36,6 +36,9 @@ const IMAGETOOLS_MODULES = [
     `declare module '*as=srcset' {\n    const src: string;\n    export default src;\n}`,
     `declare module '*as=url' {\n    const src: string;\n    export default src;\n}`,
     `declare module '*as=metadata' {\n    const metadata: { src: string; width?: number; height?: number; format?: string }[];\n    export default metadata;\n}`,
+    // `import hero from './hero.webp?toil'` -> a Toil.Image source carrying an auto-generated blur LQIP
+    // and intrinsic size (see compiler/image-blur.ts). Pass it straight to `<Toil.Image src={hero} />`.
+    `declare module '*?toil' {\n    const image: { src: string; width: number; height: number; blurDataURL: string };\n    export default image;\n}`,
 ].join('\n');
 
 export const TOIL_ENV_DTS =
@@ -409,9 +412,12 @@ const ENTRY_SCRIPT = `<script type="module" src="./entry.tsx"></script>`;
  * SSR-safe (present before JS). The app can restyle `.toil-img-*` freely. */
 const TOIL_BASE_STYLE =
     `<style id="toil-base">` +
-    `.toil-img-fill-box{position:relative;display:block;overflow:hidden}` +
-    `.toil-img-fill{position:absolute;inset:0;width:100%;height:100%}` +
+    `.toil-img-fill-box{display:block;overflow:hidden}` +
+    `.toil-img-fill{display:block;width:100%;height:100%;object-fit:cover}` +
     `.toil-img-blur{background-size:cover;background-position:center;filter:blur(20px)}` +
+    `.toil-img-skeleton{background:linear-gradient(90deg,#ececed 25%,#f4f4f5 37%,#ececed 63%);background-size:400% 100%;animation:toil-img-shimmer 1.4s ease infinite}` +
+    `@keyframes toil-img-shimmer{0%{background-position:100% 50%}100%{background-position:0 50%}}` +
+    `@media (prefers-reduced-motion:reduce){.toil-img-skeleton{animation:none}}` +
     `</style>`;
 
 /**

package/src/compiler/image-blur.ts

@@ -0,0 +1,42 @@
+import type { Plugin } from 'vite';
+
+/** An image import carrying the `?toil` flag: `import hero from './hero.webp?toil'`. */
+const TOIL_QUERY = /[?&]toil(?:&|$)/;
+/** Raster formats sharp can downscale into an LQIP. (SVG/animated stay as-is — no blur.) */
+const RASTER = /\.(?:png|jpe?g|webp|avif|gif|tiff?)(?:\?|$)/i;
+
+/**
+ * Auto-generates a tiny blurred base64 LQIP (low-quality image placeholder) for raster images imported
+ * with the `?toil` flag, and returns a `{ src, width, height, blurDataURL }` object that `Toil.Image`
+ * consumes to auto-fill its `blurDataURL` (`placeholder="blur"`) and its aspect-ratio — the way Next.js
+ * bakes a `blurDataURL` for static image imports. Runs in dev and build (Vite `load`); `sharp` is loaded
+ * lazily so it only costs anything when a `?toil` import is actually resolved.
+ *
+ * Usage: `import hero from './hero.webp?toil'` then `<Toil.Image src={hero} placeholder="blur" />`.
+ * The bare `src` is re-imported with no query, so Vite/imagetools still optimize + hash the real asset
+ * (this plugin only adds the placeholder + intrinsic size); it skips itself on that bare import.
+ */
+export function imageBlurPlugin(): Plugin {
+    return {
+        name: 'toil:image-blur',
+        enforce: 'pre',
+        async load(id) {
+            if (!TOIL_QUERY.test(id) || !RASTER.test(id)) return undefined;
+            const file = id.replace(/\?.*$/, '');
+            const { default: sharp } = await import('sharp');
+            const meta = await sharp(file).metadata();
+            // ~24px longest edge, blurred, webp — a few hundred base64 bytes, inlined as a data URI.
+            const lqip = await sharp(file)
+                .resize(24, 24, { fit: 'inside' })
+                .blur()
+                .webp({ quality: 40 })
+                .toBuffer();
+            const blurDataURL = `data:image/webp;base64,${lqip.toString('base64')}`;
+            return (
+                `import src from ${JSON.stringify(file)};\n` +
+                `export default { src, width: ${meta.width ?? 0}, height: ${meta.height ?? 0}, ` +
+                `blurDataURL: ${JSON.stringify(blurDataURL)} };\n`
+            );
+        },
+    };
+}

package/src/compiler/vite.ts

@@ -12,6 +12,7 @@ import { createLogger, type InlineConfig, type Logger, mergeConfig, type PluginO
 import { type ResolvedToilConfig } from './config.js';
 import { fontPreloadPlugin } from './fonts.js';
 import { imageReportPlugin } from './image-report.js';
+import { imageBlurPlugin } from './image-blur.js';
 import { toilPlugin } from './plugin.js';
 import { prerenderPlugin } from './prerender.js';
 
@@ -166,6 +167,10 @@ export async function createViteConfig(cfg: ResolvedToilConfig): Promise<InlineC
         customLogger: brandedLogger(),
         plugins: [
             tailwind,
+            // Auto-generate a tiny blurred base64 LQIP for `?toil` image imports (consumed by
+            // `Toil.Image` placeholder="blur"). Runs before imagetools (enforce:'pre') so it owns the
+            // `?toil` query; the bare re-imported src still flows through imagetools below.
+            cfg.images ? imageBlurPlugin() : undefined,
             // Build-time image resize/optimization. Every *imported* raster image is compressed to
             // webp by default (so a plain `<img src={imported}>` is optimized too, not just
             // `Toil.Image`); add `?w=400;800&format=…` to resize or pick a format. `public/` assets

package/test/dom/Image.test.tsx

@@ -23,8 +23,8 @@ describe('Image', () => {
         expect(img.getAttribute('width')).toBe('200');
         expect(img.getAttribute('height')).toBe('100');
         expect(img.getAttribute('fetchpriority')).toBe('auto');
-        // A plain image adds no inline style and no toil class (nothing to lay out).
-        expect(img.getAttribute('style')).toBe(null);
+        // width+height reserve space via an explicit aspect-ratio (survives responsive `width:100%`).
+        expect(img.style.aspectRatio).toBe('200 / 100');
         expect(img.className).toBe('');
     });
 
@@ -41,7 +41,7 @@ describe('Image', () => {
         expect(img.getAttribute('fetchpriority')).toBe('high');
     });
 
-    it('fill wraps the image in a positioned box; the image lays out via a class, not inline styles', () => {
+    it('fill wraps the image in a box; the image lays out via a class, not inline styles', () => {
         const { getByAltText } = render(
             <Image
                 src="/bg.png"
@@ -58,7 +58,7 @@ describe('Image', () => {
         expect(img.style.position).toBe('');
         // objectFit is genuinely per-instance, so it stays inline.
         expect(img.style.objectFit).toBe('cover');
-        // The image is wrapped in a relatively-positioned <span> box, so it can only fill THAT box.
+        // The image is wrapped in a <span> box the caller sizes, so it fills the box, not the page.
         const box = img.parentElement as HTMLElement;
         expect(box.tagName).toBe('SPAN');
         expect(box.classList.contains('toil-img-fill-box')).toBe(true);
@@ -105,4 +105,40 @@ describe('Image', () => {
         expect(img.style.backgroundImage).toBe('');
         expect(img.classList.contains('toil-img-blur')).toBe(false);
     });
+
+    it('falls back to a skeleton shimmer when placeholder="blur" has no blurDataURL', () => {
+        const { getByAltText } = render(
+            <Image src="/s.png" alt="s" width={10} height={10} placeholder="blur" />,
+        );
+        const img = getByAltText('s') as HTMLImageElement;
+        // never a silent no-op: a neutral skeleton paints (not the blur class, no background image)
+        expect(img.classList.contains('toil-img-skeleton')).toBe(true);
+        expect(img.classList.contains('toil-img-blur')).toBe(false);
+        expect(img.style.backgroundImage).toBe('');
+        fireEvent.load(img);
+        expect(img.classList.contains('toil-img-skeleton')).toBe(false);
+    });
+
+    it('reserves space with an aspect-ratio derived from width+height', () => {
+        const { getByAltText } = render(<Image src="/a.png" alt="a" width={400} height={300} />);
+        const img = getByAltText('a') as HTMLImageElement;
+        expect(img.style.aspectRatio).toBe('400 / 300');
+        expect(img.getAttribute('width')).toBe('400');
+        expect(img.getAttribute('height')).toBe('300');
+    });
+
+    it('reads src/dimensions/blur from a ?toil import object', () => {
+        const { getByAltText } = render(
+            <Image
+                src={{ src: '/hero.webp', width: 40, height: 30, blurDataURL: 'data:image/blur' }}
+                alt="h"
+                placeholder="blur"
+            />,
+        );
+        const img = getByAltText('h') as HTMLImageElement;
+        expect(img.getAttribute('src')).toBe('/hero.webp');
+        expect(img.style.aspectRatio).toBe('40 / 30');
+        expect(img.classList.contains('toil-img-blur')).toBe(true);
+        expect(img.style.backgroundImage).toContain('data:image/blur');
+    });
 });

package/test/image-blur.test.ts

@@ -0,0 +1,50 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import sharp from 'sharp';
+import { describe, expect, it } from 'vitest';
+
+import { imageBlurPlugin } from '../src/compiler/image-blur';
+
+/** Call the plugin's `load` hook directly (it uses no Rollup `this` context). */
+function loadHook(): (id: string) => Promise<string | undefined> {
+    const plugin = imageBlurPlugin();
+    return plugin.load as unknown as (id: string) => Promise<string | undefined>;
+}
+
+describe('imageBlurPlugin', () => {
+    it('emits a { src, width, height, blurDataURL } module for a ?toil image import', async () => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'toil-blur-'));
+        const file = path.join(dir, 'pic.png');
+        await sharp({
+            create: { width: 40, height: 30, channels: 3, background: { r: 200, g: 100, b: 50 } },
+        })
+            .png()
+            .toFile(file);
+        try {
+            const load = loadHook();
+            const out = await load(`${file}?toil`);
+            expect(typeof out).toBe('string');
+            // re-imports the bare asset for src (so Vite/imagetools still optimize + hash it)
+            expect(out).toContain(`import src from ${JSON.stringify(file)}`);
+            // carries the intrinsic size for the aspect-ratio
+            expect(out).toContain('width: 40');
+            expect(out).toContain('height: 30');
+            // a real inlined LQIP, not a placeholder string
+            expect(out).toContain('blurDataURL: "data:image/webp;base64,');
+            const b64 = /base64,([^"]+)"/.exec(out as string)?.[1] ?? '';
+            expect(b64.length).toBeGreaterThan(20);
+        } finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+
+    it('ignores imports without the ?toil flag', async () => {
+        const load = loadHook();
+        expect(await load('/some/pic.png')).toBeUndefined();
+        expect(await load('/some/pic.png?w=400')).toBeUndefined();
+        // non-raster ?toil (e.g. svg) is skipped too
+        expect(await load('/some/icon.svg?toil')).toBeUndefined();
+    });
+});