@enigmax/primitives 0.25.0 → 0.26.0

package/src/core/player.ts

@@ -0,0 +1,303 @@
+/**
+ * The arithmetic behind the video player: times, seeking, buffering, volume and the keys.
+ *
+ * None of it is rendering, so it is testable without a browser and reusable by a page that
+ * draws its own controls - the same split the colour maths and the image viewer's are in.
+ */
+
+/** The playback rates the settings menu offers, in the order it lists them. */
+export const SPEEDS = [0.5, 0.75, 1, 1.25, 1.5, 1.75, 2] as const;
+
+/** How far the arrows seek, in seconds, and what a bigger jump moves by. */
+export const SEEK_STEP = 5;
+export const SEEK_JUMP = 10;
+export const VOLUME_STEP = 0.05;
+
+/**
+ * Seconds as a clock, sized by the LONGEST time it will have to show.
+ *
+ * `duration` is what stops the label changing width mid-playback: a 1h04m video passing 10:00
+ * would otherwise go from `9:59` to `10:00` to `1:00:00`, and every control after it moves.
+ */
+export function formatTime(seconds: number, duration = seconds): string {
+    if (!Number.isFinite(seconds) || seconds < 0) seconds = 0;
+    const total = Math.floor(seconds);
+    const hours = Math.floor(total / 3600);
+    const minutes = Math.floor((total % 3600) / 60);
+    const rest = total % 60;
+    const withHours = Number.isFinite(duration) && duration >= 3600;
+
+    const pad = (value: number): string => String(value).padStart(2, "0");
+    if (withHours || hours > 0) return `${hours}:${pad(minutes)}:${pad(rest)}`;
+    return `${minutes}:${pad(rest)}`;
+}
+
+/** A time as a fraction of the duration, safe before the metadata says what that is. */
+export function progress(time: number, duration: number): number {
+    if (!Number.isFinite(duration) || duration <= 0) return 0;
+    return Math.min(Math.max(time / duration, 0), 1);
+}
+
+/** Where a press on a horizontal rail lands, as a fraction of it. */
+export function fractionAt(box: { left: number; width: number; }, clientX: number): number {
+    if (!box.width) return 0;
+    return Math.min(Math.max((clientX - box.left) / box.width, 0), 1);
+}
+
+/**
+ * How much is buffered AHEAD of where playback is.
+ *
+ * The range under the playhead, not the largest one: a viewer who seeks past the buffer is
+ * looking at a bar that says nothing is loaded, which is true of the part they are watching.
+ */
+export function bufferedAhead(ranges: TimeRanges | null, time: number, duration: number): number {
+    if (!ranges || !Number.isFinite(duration) || duration <= 0) return 0;
+    for (let at = 0; at < ranges.length; at += 1) {
+        if (ranges.start(at) <= time && ranges.end(at) >= time) return Math.min(ranges.end(at) / duration, 1);
+    }
+    return 0;
+}
+
+/** The next rate in the list, wrapping - what a repeated press on the speed row does. */
+export function nextSpeed(current: number, step = 1): number {
+    const at = SPEEDS.indexOf(current as typeof SPEEDS[number]);
+    const from = at === -1 ? SPEEDS.indexOf(1) : at;
+    return SPEEDS[(from + step + SPEEDS.length) % SPEEDS.length] as number;
+}
+
+/** What a key press means, or null when the player should leave it to the page. */
+export type PlayerCommand =
+    | { type: "toggle"; }
+    | { type: "seek"; by: number; }
+    | { type: "seekTo"; fraction: number; }
+    | { type: "volume"; by: number; }
+    | { type: "mute"; }
+    | { type: "fullscreen"; }
+    | { type: "captions"; }
+    | { type: "pip"; };
+
+/**
+ * The shortcuts, as the platform's video players define them.
+ *
+ * Space and K play, J and L jump ten, the arrows nudge five and the volume, M mutes, F is
+ * fullscreen, C captions, and a digit seeks to that tenth of the video.
+ */
+export function commandFor(key: string): PlayerCommand | null {
+    if (key === " " || key === "k" || key === "K") return { type: "toggle" };
+    if (key === "ArrowRight") return { type: "seek", by: SEEK_STEP };
+    if (key === "ArrowLeft") return { type: "seek", by: -SEEK_STEP };
+    if (key === "l" || key === "L") return { type: "seek", by: SEEK_JUMP };
+    if (key === "j" || key === "J") return { type: "seek", by: -SEEK_JUMP };
+    if (key === "ArrowUp") return { type: "volume", by: VOLUME_STEP };
+    if (key === "ArrowDown") return { type: "volume", by: -VOLUME_STEP };
+    if (key === "m" || key === "M") return { type: "mute" };
+    if (key === "f" || key === "F") return { type: "fullscreen" };
+    if (key === "c" || key === "C") return { type: "captions" };
+    if (key === "p" || key === "P") return { type: "pip" };
+    if (key >= "0" && key <= "9") return { type: "seekTo", fraction: Number(key) / 10 };
+    return null;
+}
+
+/**
+ * Whether a key press belongs to the page rather than to the player.
+ *
+ * A shortcut that fires while somebody is typing turns their space bar into a pause, so the
+ * player stands down inside anything that takes text.
+ */
+export function isTypingTarget(target: EventTarget | null): boolean {
+    const element = target as HTMLElement | null;
+    if (!element || typeof element.tagName !== "string") return false;
+    if (element.isContentEditable) return true;
+    return ["INPUT", "TEXTAREA", "SELECT"].includes(element.tagName);
+}
+
+/** Whether the document is showing something fullscreen, across the two spellings of it. */
+export function fullscreenElement(): Element | null {
+    if (typeof document === "undefined") return null;
+    const legacy = document as Document & { webkitFullscreenElement?: Element | null; };
+    return document.fullscreenElement ?? legacy.webkitFullscreenElement ?? null;
+}
+
+/**
+ * Fullscreen, including the one platform that will not give it to a container.
+ *
+ * iOS Safari has no Fullscreen API on an arbitrary element: the only thing that can fill the
+ * screen is the video itself, through `webkitEnterFullscreen`. Without that branch the button
+ * does nothing at all on an iPhone, which is where most video is watched.
+ */
+export async function toggleFullscreen(container: HTMLElement, video: HTMLVideoElement | null): Promise<void> {
+    const legacyDocument = document as Document & { webkitExitFullscreen?: () => Promise<void>; };
+    if (fullscreenElement()) {
+        await (document.exitFullscreen?.() ?? legacyDocument.webkitExitFullscreen?.());
+        return;
+    }
+
+    const legacyElement = container as HTMLElement & { webkitRequestFullscreen?: () => Promise<void>; };
+    if (container.requestFullscreen) return void await container.requestFullscreen();
+    if (legacyElement.webkitRequestFullscreen) return void await legacyElement.webkitRequestFullscreen();
+
+    const iosVideo = video as (HTMLVideoElement & { webkitEnterFullscreen?: () => void; }) | null;
+    iosVideo?.webkitEnterFullscreen?.();
+}
+
+/** Picture in picture, where the browser has it. Firefox has its own button and no API. */
+export function supportsPip(): boolean {
+    return typeof document !== "undefined" && Boolean(document.pictureInPictureEnabled);
+}
+
+export async function togglePip(video: HTMLVideoElement): Promise<void> {
+    if (document.pictureInPictureElement) return void await document.exitPictureInPicture();
+    await video.requestPictureInPicture();
+}
+
+/* -------- captions -------- */
+
+/** One subtitle track, as the menu lists it. */
+export interface CaptionTrack {
+    /** Where it sits in the element's own `textTracks`, which is what turns it on. */
+    index: number;
+    label: string;
+    language: string;
+}
+
+/** Which of the element's text tracks are subtitles a viewer would choose between. */
+export function captionTracks(list: TextTrackList | null | undefined): CaptionTrack[] {
+    if (!list) return [];
+    const found: CaptionTrack[] = [];
+    for (let at = 0; at < list.length; at += 1) {
+        const track = list[at];
+        // Chapters and metadata are for the page, not for the viewer: listing them offers a
+        // language picker entry that draws nothing over the picture.
+        if (!track || (track.kind !== "subtitles" && track.kind !== "captions")) continue;
+        found.push({ index: at, label: track.label || track.language || `Track ${found.length + 1}`, language: track.language });
+    }
+    return found;
+}
+
+/**
+ * The track the element is SHOWING, or -1.
+ *
+ * Read rather than remembered: a `default` track is showing before any button was pressed, and
+ * a player that assumed "off" would need two presses to turn something off.
+ */
+export function activeCaption(list: TextTrackList | null | undefined): number {
+    if (!list) return -1;
+    for (let at = 0; at < list.length; at += 1) if (list[at]?.mode === "showing") return at;
+    return -1;
+}
+
+/**
+ * Show one track and disable the rest. -1 turns them all off.
+ *
+ * "disabled" rather than "hidden": a hidden track still fires its cues, so a page listening to
+ * `cuechange` for its own transcript would keep receiving a language nobody asked for.
+ */
+export function showCaption(list: TextTrackList | null | undefined, index: number): void {
+    if (!list) return;
+    for (let at = 0; at < list.length; at += 1) {
+        const track = list[at];
+        if (track) track.mode = at === index ? "showing" : "disabled";
+    }
+}
+
+/* -------- casting: the remote screen this is played on -------- */
+
+/** What the cast control knows about the world. */
+export interface RemoteState {
+    /** There is somewhere to cast TO. Before the browser has looked, this is optimistic. */
+    available: boolean;
+    /** Playing on that screen right now. */
+    connected: boolean;
+}
+
+interface RemotePlaybackLike {
+    state: "connected" | "connecting" | "disconnected";
+    watchAvailability: (callback: (available: boolean) => void) => Promise<number>;
+    cancelWatchAvailability: (id: number) => Promise<void>;
+    prompt: () => Promise<void>;
+    addEventListener: (type: string, listener: () => void) => void;
+    removeEventListener: (type: string, listener: () => void) => void;
+}
+
+/** The element, with the two spellings of "play this somewhere else" on it. */
+type CastableVideo = HTMLVideoElement & {
+    remote?: RemotePlaybackLike;
+    /** Safari's AirPlay picker, which predates the standard and is still the only one it has on iOS. */
+    webkitShowPlaybackTargetPicker?: () => void;
+    webkitCurrentPlaybackTargetIsWireless?: boolean;
+};
+
+/**
+ * Whether this element can be cast at all.
+ *
+ * `disableRemotePlayback` is honoured: a page that asked for the button to be gone does not
+ * get one drawn over its video by a component.
+ */
+export function supportsRemote(video: HTMLVideoElement | null): boolean {
+    const element = video as CastableVideo | null;
+    if (!element || element.disableRemotePlayback) return false;
+    return Boolean(element.remote?.prompt ?? element.webkitShowPlaybackTargetPicker);
+}
+
+/**
+ * Watch for a screen to cast to, and for the connection to it.
+ *
+ * WHY AVAILABILITY IS OPTIMISTIC WHEN THE WATCH FAILS. `watchAvailability` rejects with
+ * NotSupportedError on the platforms that can still `prompt()` - Safari, and Chromium for some
+ * sources - so treating a rejection as "no devices" hides a control that works. A button that
+ * opens an empty picker is a smaller loss than a missing one.
+ */
+export function watchRemote(video: HTMLVideoElement, onChange: (state: RemoteState) => void): () => void {
+    const element = video as CastableVideo;
+    const state: RemoteState = { available: false, connected: false };
+    const publish = (next: Partial<RemoteState>): void => {
+        Object.assign(state, next);
+        onChange({ ...state });
+    };
+
+    if (element.remote) {
+        const remote = element.remote;
+        const onState = (): void => publish({ connected: remote.state === "connected" });
+        let watch: number | null = null;
+        let cancelled = false;
+
+        remote.watchAvailability((available) => { if (!cancelled) publish({ available }); })
+            .then((id) => {
+                if (cancelled) void remote.cancelWatchAvailability(id).catch(() => { /* already gone */ });
+                else watch = id;
+            })
+            .catch(() => { if (!cancelled) publish({ available: true }); });
+
+        for (const name of ["connect", "connecting", "disconnect"]) remote.addEventListener(name, onState);
+        onState();
+
+        return () => {
+            cancelled = true;
+            for (const name of ["connect", "connecting", "disconnect"]) remote.removeEventListener(name, onState);
+            if (watch !== null) void remote.cancelWatchAvailability(watch).catch(() => { /* already gone */ });
+        };
+    }
+
+    const onAvailability = (event: Event): void => publish({ available: (event as Event & { availability?: string; }).availability === "available" });
+    const onWireless = (): void => publish({ connected: Boolean(element.webkitCurrentPlaybackTargetIsWireless) });
+    element.addEventListener("webkitplaybacktargetavailabilitychanged", onAvailability);
+    element.addEventListener("webkitcurrentplaybacktargetiswirelesschanged", onWireless);
+    onWireless();
+
+    return () => {
+        element.removeEventListener("webkitplaybacktargetavailabilitychanged", onAvailability);
+        element.removeEventListener("webkitcurrentplaybacktargetiswirelesschanged", onWireless);
+    };
+}
+
+/**
+ * Open the browser's own device picker.
+ *
+ * There is no list to draw ourselves: both APIs hand the choice to the platform, which is the
+ * only thing that can enumerate the screens on the network.
+ */
+export async function promptRemote(video: HTMLVideoElement): Promise<void> {
+    const element = video as CastableVideo;
+    if (element.remote?.prompt) return void await element.remote.prompt();
+    element.webkitShowPlaybackTargetPicker?.();
+}

package/src/index.ts

@@ -152,3 +152,55 @@ export {
     type TypeaheadState,
     type TypeaheadStep
 } from "@/core/keys";
+
+// The image viewer's arithmetic: zoom that stays under the cursor, a pan that cannot lose the
+// picture, and moving through a set. The lightbox is React; none of this is.
+export {
+    zoomAt,
+    clampPan,
+    clampScale,
+    wheelFactor,
+    fittedSize,
+    pinchDistance,
+    nextIndex,
+    filenameFrom,
+    downloadFile,
+    flightFrom,
+    flightMs,
+    prefersReducedMotion,
+    FLIGHT_MS,
+    IDENTITY,
+    ZOOM_LIMITS,
+    ZOOM_STEP,
+    ZOOM_DOUBLE,
+    type Transform,
+    type ZoomLimits,
+    type Box
+} from "@/core/image-viewer";
+// The video player's arithmetic: times, seeking, buffering and the shortcut map.
+export {
+    formatTime,
+    progress,
+    fractionAt,
+    bufferedAhead,
+    nextSpeed,
+    commandFor,
+    isTypingTarget,
+    fullscreenElement,
+    toggleFullscreen,
+    supportsPip,
+    togglePip,
+    captionTracks,
+    activeCaption,
+    showCaption,
+    supportsRemote,
+    watchRemote,
+    promptRemote,
+    SPEEDS,
+    SEEK_STEP,
+    SEEK_JUMP,
+    VOLUME_STEP,
+    type PlayerCommand,
+    type CaptionTrack,
+    type RemoteState
+} from "@/core/player";

package/src/react/image/icons.tsx

@@ -0,0 +1,55 @@
+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>;
+}

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