@enigmax/primitives 0.24.0 → 0.26.0

package/src/react/image/index.tsx

@@ -0,0 +1,185 @@
+"use client";
+
+import { toItem } from "@/react/image/types";
+import { injectImageStyles } from "@/react/image/styles";
+import type { ImageItem, ImageProps, ZoomOptions } from "@/react/image/types";
+import { lazy, Suspense, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode } from "react";
+
+/**
+ * `<Image>` - the picture in the page, and the viewer a press on it opens.
+ *
+ * ```tsx
+ * <Image src="/shot.png" alt="The dashboard" />
+ * <Image src={shot} alt="..." images={gallery} navigation thumbnails menu discardable />
+ * ```
+ *
+ * WHAT IS ON BY DEFAULT is the API: click to enlarge, and zoom with the wheel. The arrows,
+ * the strip of previews, the menu and the discard action are each a decision about the page
+ * this sits in - a product gallery wants all four, an avatar wants none - so each is a prop
+ * you turn on rather than one you have to remember to turn off.
+ *
+ * WHAT LOADS. This module is the `<img>` and the press. The lightbox is its own chunk, and
+ * its menu another under that, so a page of images nobody enlarges downloads neither. The
+ * chunk is fetched on INTENT - a pointer over the image, or focus reaching it - so by the
+ * time the press lands it is usually already here; a press that beats it opens the viewer as
+ * soon as it arrives, rather than being dropped.
+ */
+
+const ImageViewer = lazy(() => import("@/react/image/viewer").then((module) => ({ default: module.ImageViewer })));
+
+/** Kept out of the render so the hover prefetch fires once per session rather than per event. */
+let prefetched = false;
+
+function prefetchViewer(): void {
+    if (prefetched) return;
+    prefetched = true;
+    void import("@/react/image/viewer");
+}
+
+const ZOOM_DEFAULTS = { min: 1, max: 8, wheel: true, doubleClick: true } as const;
+
+export function Image(props: ImageProps): ReactNode {
+    const {
+        src,
+        alt,
+        images,
+        index,
+        lightbox = true,
+        zoom = true,
+        animate = true,
+        navigation = false,
+        thumbnails = false,
+        menu = false,
+        discardable = false,
+        onDiscard,
+        loop = true,
+        caption,
+        onOpenChange,
+        onIndexChange,
+        styles = true,
+        labels = {},
+        wrapperProps,
+        ...rest
+    } = props;
+
+    // Before paint, and from HERE rather than only from the viewer: the picture in the page is
+    // styled from the first frame, so it says it enlarges before anybody has opened one.
+    useLayoutEffect(() => { if (styles) injectImageStyles(); }, [styles]);
+
+    const [open, setOpen] = useState(false);
+
+    const items = useMemo<ImageItem[]>(() => {
+        const set = (images ?? [src]).map(toItem);
+        // A set that does not contain this image would open the viewer on somebody else's
+        // picture, so the one that was pressed is always in it.
+        return set.some((entry) => entry.src === src) ? set : [{ src, alt }, ...set];
+    }, [images, src, alt]);
+
+    const initial = useMemo(() => {
+        if (typeof index === "number" && index >= 0 && index < items.length) return index;
+        const found = items.findIndex((entry) => entry.src === src);
+        return found === -1 ? 0 : found;
+    }, [index, items, src]);
+
+    const [current, setCurrent] = useState(initial);
+    useEffect(() => setCurrent(initial), [initial]);
+
+    const triggerRef = useRef<HTMLButtonElement | null>(null);
+    const thumbnailRef = useRef<HTMLImageElement | null>(null);
+
+    const shown = useRef(current);
+    shown.current = current;
+
+    /**
+     * Where this picture is in the page, read at the moment the viewer needs it.
+     *
+     * Read live rather than captured on open: the flight back happens whenever the viewer is
+     * closed, and by then the page may have scrolled. A rectangle taken at open would land the
+     * picture where the thumbnail used to be.
+     *
+     * Null once the reader has moved through a set to a different image. This component knows
+     * where ITS picture is and nothing about anyone else's, so flying the fourth image back
+     * onto the first one's thumbnail would be a lie; the viewer then closes without one.
+     */
+    const origin = useCallback((): DOMRect | null => (
+        shown.current === initial ? thumbnailRef.current?.getBoundingClientRect() ?? null : null
+    ), [initial]);
+
+    const zoomOptions = useMemo(() => {
+        if (zoom === false) return null;
+        const given: ZoomOptions = zoom === true ? {} : zoom;
+        return { ...ZOOM_DEFAULTS, ...given, doubleClick: given.doubleClick !== false, wheel: given.wheel !== false };
+    }, [zoom]);
+
+    const menuOptions = useMemo(() => (menu === false ? null : menu === true ? {} : menu), [menu]);
+
+    const show = useCallback(() => {
+        if (!lightbox) return;
+        // A press before the chunk lands is not lost: this is state, and the viewer mounts
+        // with it the moment its code is here.
+        setOpen(true);
+        onOpenChange?.(true);
+    }, [lightbox, onOpenChange]);
+
+    const close = useCallback(() => {
+        setOpen(false);
+        onOpenChange?.(false);
+        // Back where the press came from: closing a dialog that leaves focus on the body
+        // sends the next Tab to the top of the page.
+        triggerRef.current?.focus();
+    }, [onOpenChange]);
+
+    const goTo = useCallback((next: number) => {
+        setCurrent(next);
+        const item = items[next];
+        if (item) onIndexChange?.(next, item);
+    }, [items, onIndexChange]);
+
+    const image = <img ref={thumbnailRef} src={src} alt={alt} {...rest} />;
+
+    return (
+        <span {...wrapperProps} data-enigma-image="" data-clickable={lightbox ? "" : undefined}>
+            {lightbox ? (
+                <button
+                    ref={triggerRef}
+                    type="button"
+                    data-enigma-image-trigger=""
+                    // The image IS the label: a second name here would have a screen reader
+                    // read the picture twice, once for the button and once for the alt.
+                    aria-label={labels.open ? `${labels.open}: ${alt}` : alt}
+                    aria-haspopup="dialog"
+                    onClick={show}
+                    onPointerEnter={prefetchViewer}
+                    onFocus={prefetchViewer}
+                >
+                    {image}
+                </button>
+            ) : image}
+
+            {open && (
+                <Suspense fallback={null}>
+                    <ImageViewer
+                        items={items}
+                        index={current}
+                        onIndex={goTo}
+                        onClose={close}
+                        zoom={zoomOptions}
+                        navigation={navigation}
+                        thumbnails={thumbnails}
+                        menu={menuOptions}
+                        discardable={discardable}
+                        onDiscard={onDiscard}
+                        loop={loop}
+                        caption={caption}
+                        origin={origin}
+                        animate={animate}
+                        styles={styles}
+                        labels={labels}
+                    />
+                </Suspense>
+            )}
+        </span>
+    );
+}
+
+export type { ImageProps, ImageItem, ImageSource, ImageLabels, ImageMenuOptions, ZoomOptions } from "@/react/image/types";

package/src/react/image/menu.tsx

@@ -0,0 +1,76 @@
+"use client";
+
+import * as icons from "@/react/image/icons";
+import { useRef, type ReactNode } from "react";
+import { MenuButton } from "@/react/image/viewer";
+import { downloadFile } from "@/core/image-viewer";
+import type { ImageItem, ImageLabels, ImageMenuOptions } from "@/react/image/types";
+import { ContextMenu, useContextMenuContext, type ContextMenuNode } from "@/react/context-menu";
+
+/**
+ * The three dots, and the rows under them.
+ *
+ * The MENU is the context menu component, opened from a left press at the button's corner
+ * rather than from a right-click - which is the composition its own docs describe. Writing a
+ * second popup here would mean a second keyboard model, a second set of roles and a second
+ * thing to fix, and the `fe-context-menu-hand-rolled` guardrail exists to say so.
+ *
+ * Its own chunk under the viewer's: the menu is off by default, so a viewer that was never
+ * given one downloads neither this module nor the component it composes.
+ */
+
+export interface ImageMenuProps {
+    item: ImageItem;
+    index: number;
+    options: ImageMenuOptions;
+    labels: ImageLabels;
+}
+
+export function ImageMenu({ item, index, options, labels }: ImageMenuProps): ReactNode {
+    const rows: ContextMenuNode[] = [];
+    if (options.download !== false) {
+        rows.push({ id: "download", label: labels.download ?? "Download", icon: <icons.Download /> });
+    }
+    if (options.items?.length) {
+        if (rows.length > 0) rows.push({ type: "separator" });
+        rows.push(...options.items);
+    }
+
+    return (
+        <ContextMenu.Root
+            items={rows}
+            // The rows act on the picture, not on a selection: Copy, Cut and Paste are built
+            // from what was right-clicked, and there is nothing writable in a lightbox.
+            clipboard={false}
+            onSelect={(row) => {
+                if (row.id === "download") void downloadFile(item.download ?? item.src, item.filename);
+                options.onSelect?.(row.id, item, index);
+            }}
+        >
+            <Trigger label={labels.menu ?? "More"} />
+            <ContextMenu.Content />
+        </ContextMenu.Root>
+    );
+}
+
+/** The button, wired to open the menu under itself the way a toolbar's overflow does. */
+function Trigger({ label }: { label: string; }): ReactNode {
+    const menu = useContextMenuContext("Image.Menu");
+    const ref = useRef<HTMLSpanElement | null>(null);
+
+    return (
+        <span ref={ref} style={{ display: "contents" }}>
+            <MenuButton
+                label={label}
+                expanded={menu.state.open}
+                onPress={() => {
+                    const box = ref.current?.firstElementChild?.getBoundingClientRect();
+                    if (!box) return;
+                    // Under the button and aligned to its right edge, which is where a toolbar
+                    // menu belongs - the panel flips itself if the window has no room.
+                    menu.open({ x: box.right, y: box.bottom + 6 });
+                }}
+            />
+        </span>
+    );
+}

package/src/react/image/styles.ts

@@ -0,0 +1,213 @@
+/**
+ * The image viewer's look.
+ *
+ * It ships one, for the reason the colour picker and the toast do: there is no useful
+ * "unstyled" lightbox. A dialog with no backdrop, no size and no stacking is not a plain
+ * viewer, it is the page with an image lying across it - so the panel arrives dressed and
+ * `styles={false}` takes it away for anyone drawing their own.
+ *
+ * A string because the component injects it. `scripts/sync-recipes.mjs` generates
+ * `recipes/image/styles.css` from here and CI fails when the two drift, so this module is the
+ * source and the stylesheet is the copy for anyone who prefers an import.
+ *
+ * Everything below is a custom property or an attribute selector: the sheet is PREPENDED to
+ * `<head>`, so anything the document already has wins at equal specificity.
+ */
+
+export const IMAGE_STYLES = `
+:root {
+    --enigma-image-backdrop: rgba(0, 0, 0, 0.92);
+    --enigma-image-text: #f5f5f5;
+    --enigma-image-muted: #a3a3a3;
+    --enigma-image-control-bg: rgba(23, 23, 23, 0.72);
+    --enigma-image-control-hover: rgba(64, 64, 64, 0.82);
+    --enigma-image-control-size: 2.25rem;
+    --enigma-image-radius: 0.625rem;
+    --enigma-image-gap: 0.75rem;
+    --enigma-image-thumb-size: 3.5rem;
+    --enigma-image-focus: #f5f5f5;
+    /* Above the page's own chrome, not merely above its content: a header or a sticky sidebar
+       with a z-index of its own would otherwise paint over the dialog covering it. */
+    --enigma-image-z: 9999;
+    /* How long the picture takes to fly out of the page and back into it, and the curve it
+       flies on. They are the numbers core/image-viewer.ts waits for, so a project that
+       changes one here changes it there - see the note above the keyframes. */
+    --enigma-image-flight: 300ms;
+    --enigma-image-flight-ease: cubic-bezier(0.2, 0, 0.2, 1);
+}
+
+/* The thumbnail in the page. Only what the behaviour needs: the pointer says it opens, and
+   the box is the caller's to size. */
+[data-enigma-image] { display: inline-flex; max-width: 100%; }
+[data-enigma-image][data-clickable] { cursor: zoom-in; }
+/* Stated on the picture as well as inherited: a project that restyles the trigger button is
+   one cursor: pointer away from a thumbnail that no longer says it enlarges. */
+[data-enigma-image][data-clickable] img { cursor: zoom-in; }
+[data-enigma-image] img { display: block; max-width: 100%; height: auto; }
+/* A real box, never display:contents: an element without one cannot be focused in Chromium,
+   so a viewer closed with Escape would hand focus to the body instead of back to the picture
+   it was opened from, and the next Tab would start at the top of the page. */
+[data-enigma-image-trigger] {
+    display: inline-flex; max-width: 100%; padding: 0; margin: 0;
+    background: none; border: 0; color: inherit; font: inherit; cursor: inherit;
+}
+[data-enigma-image-trigger]:focus-visible img { outline: 2px solid var(--enigma-image-focus); outline-offset: 3px; }
+
+/* The viewer. Fixed and portalled: a lightbox inside the page's own stacking context is a
+   lightbox some ancestor's overflow or transform will clip. */
+[data-enigma-image-viewer] {
+    position: fixed; inset: 0; z-index: var(--enigma-image-z);
+    display: grid; grid-template-rows: auto minmax(0, 1fr) auto;
+    background: var(--enigma-image-backdrop);
+    color: var(--enigma-image-text);
+}
+
+/* The opening: the backdrop arrives while the picture flies out of the page, and the toolbar
+   and the strip arrive with it rather than being there first over a picture that is still on
+   its way. data-state is only ever "opening" or "closing" while an animation is meant to be
+   running, so a viewer that skipped the flight - reduced motion, animate={false} - matches
+   none of these rules and simply exists. */
+@keyframes enigma-image-in { from { background-color: transparent; } to { background-color: var(--enigma-image-backdrop); } }
+@keyframes enigma-image-chrome { from { opacity: 0; } to { opacity: 1; } }
+[data-enigma-image-viewer][data-state="opening"] { animation: enigma-image-in var(--enigma-image-flight) ease-out; }
+[data-enigma-image-viewer][data-state="opening"] [data-enigma-image-bar],
+[data-enigma-image-viewer][data-state="opening"] [data-enigma-image-foot],
+[data-enigma-image-viewer][data-state="opening"] [data-enigma-image-nav] {
+    animation: enigma-image-chrome var(--enigma-image-flight) ease-out;
+}
+/* On the way out the backdrop drains, and the dialog stops taking presses: it is over the
+   page again, so a click through it would land on whatever is now under the pointer. */
+[data-enigma-image-viewer][data-state="closing"] {
+    background-color: transparent; pointer-events: none;
+    transition: background-color var(--enigma-image-flight) var(--enigma-image-flight-ease);
+}
+[data-enigma-image-viewer][data-state="closing"] [data-enigma-image-bar],
+[data-enigma-image-viewer][data-state="closing"] [data-enigma-image-foot],
+[data-enigma-image-viewer][data-state="closing"] [data-enigma-image-nav] {
+    opacity: 0; transition: opacity calc(var(--enigma-image-flight) / 2) ease-in;
+}
+
+[data-enigma-image-bar] {
+    display: flex; align-items: center; gap: 0.5rem;
+    padding: var(--enigma-image-gap);
+}
+[data-enigma-image-counter] {
+    font-size: 0.8125rem; font-variant-numeric: tabular-nums; color: var(--enigma-image-muted);
+    margin-inline-end: auto;
+}
+
+[data-enigma-image-button] {
+    display: grid; place-items: center; flex: none;
+    width: var(--enigma-image-control-size); height: var(--enigma-image-control-size);
+    padding: 0; color: var(--enigma-image-text);
+    background: var(--enigma-image-control-bg); border: 0; border-radius: 999px;
+    cursor: pointer;
+}
+[data-enigma-image-button]:hover { background: var(--enigma-image-control-hover); }
+[data-enigma-image-button]:focus-visible { outline: 2px solid var(--enigma-image-focus); outline-offset: 2px; }
+[data-enigma-image-button][disabled] { opacity: 0.35; cursor: not-allowed; }
+
+/* The frame the picture is fitted into, and the surface every gesture is measured against. */
+[data-enigma-image-frame] {
+    position: relative; overflow: hidden;
+    display: grid; place-items: center;
+    /* Room for the arrows down each side, so they sit beside the picture rather than on it. */
+    padding: 0 calc(var(--enigma-image-control-size) + var(--enigma-image-gap) * 1.5);
+    /* The drag IS the control once zoomed, so the page must not scroll under it. */
+    touch-action: none;
+    -webkit-user-select: none; user-select: none;
+}
+[data-enigma-image-frame] img {
+    max-width: 100%; max-height: 100%;
+    -webkit-user-drag: none;
+    will-change: transform;
+}
+/* Only while it is MOVING, which is not the same as "during the flight".
+   A transition left on permanently would put 300ms of lag between the wheel and the zoom, and
+   turn every pan into a drag the picture follows late. And one left on during "pending" is
+   worse than useless: putting the picture on the thumbnail is itself a transform change, so it
+   animated there over 300ms - behind a hidden element - and by the time anybody could see it
+   the flight was nearly over. */
+[data-enigma-image-frame][data-flying="moving"] img { transition: transform var(--enigma-image-flight) var(--enigma-image-flight-ease); }
+/* Not drawn until there is somewhere to fly from - see the note on the attribute. The spinner
+   is what stands in for it, the same one a slow picture gets. */
+[data-enigma-image-frame][data-flying="pending"] img { visibility: hidden; }
+@media (prefers-reduced-motion: reduce) {
+    [data-enigma-image-frame][data-flying="moving"] img { transition: none; }
+}
+
+/* The cursor says what a press does, which in a lightbox is three different things. The empty
+   part of the frame IS the backdrop and closes it; the picture at rest takes a double press to
+   enlarge; once it is enlarged the gesture is a drag. */
+[data-enigma-image-frame] { cursor: zoom-out; }
+[data-enigma-image-frame][data-zoom] img { cursor: zoom-in; }
+[data-enigma-image-frame][data-zoomed],
+[data-enigma-image-frame][data-zoomed] img { cursor: grab; }
+[data-enigma-image-frame][data-panning],
+[data-enigma-image-frame][data-panning] img { cursor: grabbing; }
+[data-enigma-image-frame][data-loading] img { opacity: 0.35; }
+
+/* Left and right sit over the picture rather than beside it: the frame is the biggest thing
+   on screen and the arrows have to be reachable without hunting for an edge. */
+[data-enigma-image-nav] {
+    position: absolute; top: 50%; translate: 0 -50%;
+    width: var(--enigma-image-control-size); height: var(--enigma-image-control-size);
+}
+[data-enigma-image-nav="previous"] { left: var(--enigma-image-gap); }
+[data-enigma-image-nav="next"] { right: var(--enigma-image-gap); }
+
+[data-enigma-image-spinner] {
+    position: absolute; width: 1.75rem; height: 1.75rem;
+    border: 2px solid rgba(255, 255, 255, 0.25); border-top-color: var(--enigma-image-text);
+    border-radius: 999px; animation: enigma-image-spin 700ms linear infinite;
+}
+@keyframes enigma-image-spin { to { rotate: 360deg; } }
+@media (prefers-reduced-motion: reduce) {
+    [data-enigma-image-spinner] { animation-duration: 2s; }
+}
+
+[data-enigma-image-foot] { display: grid; gap: 0.5rem; padding: var(--enigma-image-gap); }
+[data-enigma-image-caption] {
+    margin: 0; text-align: center; font-size: 0.8125rem; line-height: 1.5;
+    color: var(--enigma-image-muted);
+}
+
+/* The strip. Scrolls on its own rather than wrapping: a gallery of forty is one row you drag
+   through, not five rows that push the picture off the screen. */
+[data-enigma-image-strip] {
+    display: flex; gap: 0.5rem; overflow-x: auto; scrollbar-width: thin;
+    justify-content: safe center;
+    padding-bottom: 0.25rem;
+}
+[data-enigma-image-thumb] {
+    flex: none; width: var(--enigma-image-thumb-size); height: var(--enigma-image-thumb-size);
+    padding: 0; overflow: hidden;
+    background: none; border: 0; border-radius: 0.375rem;
+    opacity: 0.55; cursor: pointer;
+}
+[data-enigma-image-thumb] img { width: 100%; height: 100%; object-fit: cover; }
+[data-enigma-image-thumb]:hover { opacity: 0.85; }
+[data-enigma-image-thumb][aria-current="true"] { opacity: 1; box-shadow: 0 0 0 2px var(--enigma-image-focus); }
+[data-enigma-image-thumb]:focus-visible { outline: 2px solid var(--enigma-image-focus); outline-offset: 2px; }
+`;
+
+let injected = false;
+
+/**
+ * Put the sheet in the document, once.
+ *
+ * It lives here rather than in the component because BOTH halves need it and they are in
+ * different chunks: the thumbnail is in the page from the first paint, and the viewer arrives
+ * with its own module later. Injecting only from the viewer left the picture in the page
+ * unstyled until somebody opened one - so the cursor did not say it enlarges, and the focus
+ * ring around it did not exist, until after the first press.
+ */
+export function injectImageStyles(): void {
+    if (injected || typeof document === "undefined") return;
+    injected = true;
+    if (document.querySelector("[data-enigma-image-styles]")) return;
+    const element = document.createElement("style");
+    element.setAttribute("data-enigma-image-styles", "");
+    element.textContent = IMAGE_STYLES;
+    document.head.prepend(element);
+}

package/src/react/image/types.ts

@@ -0,0 +1,113 @@
+/**
+ * The prop shapes for `<Image>`, split from the component so the viewer's chunk can import
+ * them without pulling the component in - the same arrangement `<Input>` is in.
+ *
+ * WHAT IS ON BY DEFAULT is the whole design of this API: an image that opens and zooms, and
+ * nothing else. A gallery's arrows, its thumbnails, a menu and a discard action are each a
+ * decision about the page they sit in, so each is a prop you turn on rather than one you
+ * remember to turn off.
+ */
+
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import type { ContextMenuNode } from "@/react/context-menu/context";
+
+/** One image in a set: a URL, or the URL plus what is known about it. */
+export type ImageSource = string | ImageItem;
+
+export interface ImageItem {
+    src: string;
+    alt?: string;
+    /** A smaller file for the strip and for the frame while the full one loads. */
+    thumbnail?: string;
+    /** The URL to save, when the file to download is not the one being shown. */
+    download?: string;
+    /** Saved under this name instead of the one in the URL. */
+    filename?: string;
+    caption?: ReactNode;
+}
+
+export interface ZoomOptions {
+    /** How far out. 1 is the fitted image; below it the picture is smaller than its frame. */
+    min?: number;
+    max?: number;
+    /** Zoom on the wheel. On by default - it is the gesture every image viewer answers. */
+    wheel?: boolean;
+    /** A double press toggles between fitted and this. `false` leaves the gesture alone. */
+    doubleClick?: boolean;
+}
+
+export interface ImageMenuOptions {
+    /** The download row. On whenever the menu is. */
+    download?: boolean;
+    /** Rows of your own, after the built-in ones. */
+    items?: readonly ContextMenuNode[];
+    onSelect?: (id: string, item: ImageItem, index: number) => void;
+}
+
+/** Every string the viewer says, for a UI that is not in English. */
+export interface ImageLabels {
+    open?: string;
+    close?: string;
+    zoomIn?: string;
+    zoomOut?: string;
+    reset?: string;
+    previous?: string;
+    next?: string;
+    menu?: string;
+    download?: string;
+    discard?: string;
+    thumbnails?: string;
+    /** The frame itself, announced as the dialog's name. Default "Image viewer". */
+    viewer?: string;
+    /** `{index}` and `{total}` are replaced. Default "{index} of {total}". */
+    counter?: string;
+}
+
+export interface ImageProps extends Omit<ComponentPropsWithoutRef<"img">, "children" | "onSelect"> {
+    src: string;
+    alt: string;
+    /**
+     * The set this image belongs to. Without it the viewer shows this one image; with it the
+     * arrows, the strip and the discard action have something to move through.
+     */
+    images?: readonly ImageSource[];
+    /** Where in `images` this one is. Found by `src` when it is left out. */
+    index?: number;
+    /** Click to see it larger. ON by default: it is what an image in a page is expected to do. */
+    lightbox?: boolean;
+    /** Zoom, with the wheel and the keyboard. ON by default. */
+    zoom?: boolean | ZoomOptions;
+    /**
+     * The picture flies out of the page into the viewer, and back into it on the way out. ON
+     * by default, and skipped anyway for a reader who has asked for less movement.
+     */
+    animate?: boolean;
+    /** Arrows, the counter, and Left/Right on the keyboard. Off by default. */
+    navigation?: boolean;
+    /** The strip of previews along the bottom. Off by default. */
+    thumbnails?: boolean;
+    /** The three dots, and what is under them. Off by default. */
+    menu?: boolean | ImageMenuOptions;
+    /**
+     * Take an image out of the set and move to the next one. Off by default, because it is
+     * destructive and only the caller knows whether it means anything on their page.
+     */
+    discardable?: boolean;
+    onDiscard?: (item: ImageItem, index: number) => void;
+    /** Whether the arrows and the strip wrap around at the ends. On by default. */
+    loop?: boolean;
+    /** The caption under the frame, when the item carries none of its own. */
+    caption?: ReactNode;
+    onOpenChange?: (open: boolean) => void;
+    onIndexChange?: (index: number, item: ImageItem) => void;
+    /** The viewer's stylesheet, injected once. There is no useful unstyled lightbox. */
+    styles?: boolean;
+    labels?: ImageLabels;
+    /** Props for the element wrapping the thumbnail - this is what you position. */
+    wrapperProps?: ComponentPropsWithoutRef<"span">;
+}
+
+/** A source in either spelling, as the one the viewer works in. */
+export function toItem(source: ImageSource): ImageItem {
+    return typeof source === "string" ? { src: source } : source;
+}