@enigmax/primitives 0.25.0 → 0.27.0

package/src/react/context-menu/root.tsx

@@ -146,6 +146,12 @@ export interface ContextMenuRootProps {
      * selection, Cut over a selection in something writable, Paste in anything writable.
      */
     clipboard?: boolean | ClipboardMenuOptions;
+    /**
+     * A filter field over the rows. `"auto"` (the default) grows one only once there are
+     * enough rows to be worth filtering; `true` asks for one whatever the count - which is
+     * what a menu whose rows are fetched wants - and `false` never draws one.
+     */
+    searchable?: boolean | "auto";
     /** Fuse.js's constructor, for fuzzy filtering. Omit it for the built-in matcher. */
     fuse?: ContextMenuOptions["fuse"];
     fuseOptions?: Record<string, unknown>;
@@ -169,6 +175,7 @@ export function ContextMenuRoot(props: ContextMenuRootProps): ReactNode {
     const {
         items,
         title,
+        searchable,
         disabled = false,
         fuse,
         fuseOptions,
@@ -208,6 +215,7 @@ export function ContextMenuRoot(props: ContextMenuRootProps): ReactNode {
     const instance = useMemo<ContextMenuInstance>(() => createContextMenu({
         items: items as readonly ContextMenuEntry[],
         title,
+        searchable,
         fuse,
         fuseOptions,
         matcher,
@@ -307,8 +315,8 @@ export function ContextMenuRoot(props: ContextMenuRootProps): ReactNode {
     }, []);
 
     useEffect(() => {
-        instance.update({ items: withClipboard(currentItems.current), title });
-    }, [instance, signature, title, withClipboard]);
+        instance.update({ items: withClipboard(currentItems.current), title, searchable });
+    }, [instance, signature, title, searchable, withClipboard]);
 
     const cancelClose = useCallback(() => { window.clearTimeout(closing.current); }, []);
 
@@ -883,6 +891,18 @@ export function ContextMenuRow({ level, index, entry, children, ...props }: Cont
         return <p {...props} data-enigma-menu-label="" aria-hidden="true">{entry.label}</p>;
     }
 
+    /**
+     * Whether the level RESERVES the tick column, which is not the same as this row having a
+     * tick.
+     *
+     * A checkable row carries a check and, usually, an icon; its neighbours carry only the
+     * icon. Drawn per row, the ticked one's label therefore sat a column further right than
+     * everyone else's and the menu read as broken. Every desktop menu reserves the column for
+     * the whole level instead, so this asks the LEVEL. Read from `entries` rather than from
+     * what is visible: filtering a menu must not shift its rows sideways.
+     */
+    const reserveCheck = state?.entries.some((entry) => isAction(entry) && (entry as ContextMenuItem).checked !== undefined) ?? false;
+
     const checkable = item.checked !== undefined;
     // A checkable row inside a group is a radio: choosing one is choosing INSTEAD of its
     // siblings, and a screen reader announces the two differently.
@@ -942,16 +962,18 @@ export function ContextMenuRow({ level, index, entry, children, ...props }: Cont
                 menu.instance.select(level, index);
             }}
         >
-            {children ?? menu.renderItem?.(item, level, index) ?? <ContextMenuRowContent item={item} submenu={submenu} />}
+            {children ?? menu.renderItem?.(item, level, index) ?? <ContextMenuRowContent item={item} submenu={submenu} reserveCheck={reserveCheck} />}
         </div>
     );
 }
 
 /** The default row: what a desktop menu draws, in the order it draws it. */
-function ContextMenuRowContent({ item, submenu }: { item: ContextMenuItem; submenu: boolean; }): ReactNode {
+function ContextMenuRowContent({ item, submenu, reserveCheck }: { item: ContextMenuItem; submenu: boolean; reserveCheck: boolean; }): ReactNode {
     return (
         <>
-            {item.checked !== undefined && <span data-enigma-menu-check="" aria-hidden="true" />}
+            {/* Empty when this row is not checkable and something else in the level is: the
+                column is the level's, not the row's. */}
+            {(item.checked !== undefined || reserveCheck) && <span data-enigma-menu-check="" aria-hidden="true" />}
             {item.icon ? <span data-enigma-menu-icon="">{item.icon}</span> : null}
             <span data-enigma-menu-item-text="">
                 <span data-enigma-menu-item-label="">{item.label}</span>

package/src/react/context-menu/styles.ts

@@ -29,6 +29,13 @@ export const CONTEXT_MENU_STYLES = `
     --enigma-menu-accent: #fbbf24;
     --enigma-menu-danger: #f87171;
     --enigma-menu-danger-bg: rgba(248, 113, 113, 0.12);
+
+    /* Above the lightbox, which sits at 9999, because a menu is opened FROM whatever is on
+       top: the image viewer's own three-dot menu was portalled to the same body and painted
+       underneath it, so its rows could be neither seen nor pressed. A menu is the topmost
+       transient surface on a page, and this is the number that says so. It belongs here and
+       not in the light-scheme block, or half the readers get an invalid z-index. */
+    --enigma-menu-z: 10000;
 }
 
 @media (prefers-color-scheme: light) {
@@ -49,7 +56,7 @@ export const CONTEXT_MENU_STYLES = `
    and what a menu opened at the pointer needs. Fixed rather than absolute so a scrolling
    ancestor cannot drag it away from the place it was opened. */
 [data-enigma-menu-panel] {
-    position: fixed; z-index: 60;
+    position: fixed; z-index: var(--enigma-menu-z);
     box-sizing: border-box;
     min-width: var(--enigma-menu-min-width);
     max-width: min(22rem, calc(100vw - 1rem));

package/src/react/image/icons.tsx

@@ -0,0 +1,59 @@
+import type { ReactNode } from "react";
+
+/**
+ * The viewer's icons, drawn rather than loaded.
+ *
+ * A sprite or an SVG file would be a request, and an icon package would be a dependency for
+ * eight paths. They sit in one module so the viewer and its menu share them without either
+ * pulling the other's chunk.
+ */
+
+function Glyph({ children }: { children: ReactNode; }): ReactNode {
+    return (
+        <svg viewBox="0 0 24 24" width="1.125em" height="1.125em" fill="none" stroke="currentColor" strokeWidth={2} strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+            {children}
+        </svg>
+    );
+}
+
+export function Close(): ReactNode {
+    return <Glyph><path d="M6 6 18 18M18 6 6 18" /></Glyph>;
+}
+
+export function Plus(): ReactNode {
+    return <Glyph><path d="M12 5v14M5 12h14" /></Glyph>;
+}
+
+export function Minus(): ReactNode {
+    return <Glyph><path d="M5 12h14" /></Glyph>;
+}
+
+export function ChevronLeft(): ReactNode {
+    return <Glyph><path d="m15 5-7 7 7 7" /></Glyph>;
+}
+
+export function ChevronRight(): ReactNode {
+    return <Glyph><path d="m9 5 7 7-7 7" /></Glyph>;
+}
+
+export function Trash(): ReactNode {
+    return <Glyph><path d="M4 7h16M9 7V4h6v3M6 7l1 13h10l1-13" /></Glyph>;
+}
+
+export function Dots(): ReactNode {
+    return (
+        <svg viewBox="0 0 24 24" width="1.125em" height="1.125em" fill="currentColor" aria-hidden="true">
+            <circle cx="12" cy="5" r="1.75" />
+            <circle cx="12" cy="12" r="1.75" />
+            <circle cx="12" cy="19" r="1.75" />
+        </svg>
+    );
+}
+
+export function Download(): ReactNode {
+    return <Glyph><path d="M12 3v12M7 11l5 5 5-5M4 20h16" /></Glyph>;
+}
+
+export function NewTab(): ReactNode {
+    return <Glyph><path d="M14 4h6v6" /><path d="M20 4 11 13" /><path d="M18 14v5a1.5 1.5 0 0 1-1.5 1.5h-11A1.5 1.5 0 0 1 4 19V7.5A1.5 1.5 0 0 1 5.5 6H10" /></Glyph>;
+}

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,80 @@
+"use client";
+
+import * as icons from "@/react/image/icons";
+import { useRef, type ReactNode } from "react";
+import { MenuButton } from "@/react/image/viewer";
+import { downloadFile, openInNewTab } 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.newTab !== false) {
+        rows.push({ id: "new-tab", label: labels.newTab ?? "Open in a new tab", icon: <icons.NewTab /> });
+    }
+    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);
+                if (row.id === "new-tab") openInNewTab(item.src);
+                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);
+}