@nanisoft/prism-ui 0.13.0 → 0.15.0

package/dist/components/ui/image-list-field.js

@@ -0,0 +1,168 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ImagePlusIcon, XIcon } from 'lucide-react';
+import { useEffect, useId, useRef } from 'react';
+import { Button } from './button.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * The remove control, drawn once and used by every row.
+ *
+ * The same treatment `FileUpload` gives its own remove control, for the same
+ * reason and with the same two decisions: the ink is the muted one because every
+ * row is the same surface and a control that changed colour with its row's state
+ * would be a second thing to read, and the target takes the 44px coarse-pointer
+ * floor so a list of photographs on a phone is a list of rows a thumb can hit.
+ * Duplicated as a constant rather than imported, because `FileUpload` does not
+ * export it and the alternative is for this Component to redraw the whole list
+ * to get at one class string.
+ */
+const REMOVE_CONTROL = 'text-muted-foreground hover:text-foreground inline-flex size-5 shrink-0 cursor-pointer items-center justify-center rounded-sm outline-none transition-colors duration-fast ease-out pointer-coarse:size-11 focus-visible:ring-ring focus-visible:ring-[3px]';
+/**
+ * A row's own `data-slot`, read back through one root ref.
+ *
+ * The Component does not hold a ref per row. A ref array indexed by position has
+ * to be reconciled with the value on every commit, and the value is the caller's,
+ * so the reconciliation is a second source of truth about how many rows there
+ * are. One ref on the root and a query for the Component's own slots is the same
+ * answer with no bookkeeping, and the cost is stated rather than hidden: it reads
+ * markup rather than state, so it can only reach what this Component drew, which
+ * is exactly the set that has to move.
+ */
+const REMOVE_SLOT = '[data-slot="image-list-field-remove"]';
+const ADD_SLOT = '[data-slot="image-list-field-add"]';
+/**
+ * An ordered list of images with a cap, a per-item remove, and an add affordance
+ * that stops offering a seventh before the reader has chosen one.
+ *
+ * **It is not a `FileUpload`, and the difference is the cap.** `FileUpload` is the
+ * receipt half of an upload: it renders whatever array it is handed, with no
+ * ceiling and no way in, because a receipt names what was sent and a limit on
+ * what may be sent belongs to the control that sends. This is the other half. It
+ * has a ceiling, and the ceiling is a rule about the caller's product, so the
+ * Component that can enforce it is the one that owns the affordance. A caller who
+ * wants a capped list today writes a button, a length test and a disabled branch,
+ * and the branch is the interesting one, because a cap enforced anywhere else
+ * produces one of two lies: a value holding six images rendered as four, or six
+ * rows where the fifth and sixth are drawn in a way that says they are not
+ * welcome. Neither is a fact about the reader's field. The one thing that is a
+ * fact is the affordance, and this is the Component that draws it.
+ *
+ * **The cap is enforced at the affordance and nowhere else, and that placement is
+ * the design.** The moment the cap is reached, the add control is still there, in
+ * the tab order, and marked `aria-disabled`; it is not removed and it is not
+ * natively disabled, because a control that vanishes leaves a keyboard reader
+ * with a gap and no announcement, and a natively disabled one is gone from the tab
+ * order for the same reason. `Dropzone` states the whole argument and this
+ * Component inherits it. The reader learns the cap before they spend a pick, and
+ * the value is never silently truncated.
+ *
+ * **Removing a middle row moves focus, and that is the part no prop can express.**
+ * The naive `onRemove` hands the reader back to the document: the button they
+ * pressed is unmounted with the row, focus falls to `body`, and the next Tab
+ * starts from the top of the page, so a reader removing the third of six
+ * photographs is returned to the top of a form to find the two they still meant
+ * to change. The correct destination is a neighbour, and which neighbour is a
+ * fact about the index the caller does not know this Component holds: the row
+ * that moved up into the removed row's place, or the one above it when the
+ * removed row was last. Prism knows the index because it drew the row, so Prism
+ * moves the focus. When the last image goes, the focus lands on the add control,
+ * because that is the only operable thing left in the field and dropping a reader
+ * on nothing is the same defect one level up.
+ *
+ * **The row is a reference and the list is an `ol`, so position is in the
+ * accessibility tree.** The Component does not draw an ordinal and does not
+ * renumber anything by hand: an `ol` reports "3 of 6" for free, and the
+ * renumbering the reader needs after a removal is the list doing its job rather
+ * than a number this Component recomputed and could get wrong. The remove control
+ * is named by the caller's own sentence so the two do not have to agree.
+ *
+ * **It draws its own row and does not compose `FileUpload`, and the reason is the
+ * number of bytes.** `FileUpload`'s row is a name, a size in bytes, an optional
+ * transfer meter and an optional per-file error, and a field of references has
+ * none of those: a stored image has no size until the caller fetches it, and
+ * drawing a byte count for an image that has not been downloaded is a
+ * measurement of nothing. The two would also disagree about focus, because
+ * `FileUpload` owns its own remove control and there is no way to tell it where
+ * the reader's focus should land afterwards without reaching into its markup. The
+ * composition Prism does make is outward: `onAdd` is the seam where a `Dropzone`
+ * or a hidden `input` is composed, and `Button` draws the affordance rather than
+ * this Component re-deriving a control's metrics.
+ *
+ * **It is a client Component**, because the focus handoff and the cap's arrival
+ * both happen after the reader acts, and neither can be known at a server render.
+ * What that costs is the price of every client field: a form with images on it
+ * carries a hydration boundary, and a caller whose form is otherwise static pays
+ * for this one. The value is still the caller's, so a server Component may render
+ * the whole field once with the list already in place; what it may not do is offer
+ * a capped, removable list whose focus behaves, because that part is a client
+ * fact.
+ *
+ * **Two upstream spellings are this one job, and the catalogue holds one of
+ * them.** An image list and a gallery upload differ in whether the frame around
+ * the images is decorative, and in nothing else: both are an ordered list of
+ * image references, both cap, both remove. Publishing both would put two Items in
+ * the list whose only difference is a wrapper one of them drew, and a list
+ * nobody can search is what the naming law exists to prevent. A caller who wants
+ * a gallery frames the list themselves, which is layout and therefore already
+ * theirs.
+ */
+function ImageListField({ images, cap, addLabel, onAdd, onRemove, removeLabel, empty, capLabel, label, className, }) {
+    const generated = useId();
+    const labelId = `${generated}-label`;
+    const capId = `${generated}-cap`;
+    const rootRef = useRef(null);
+    // The index whose remove control should take focus after the caller's value
+    // settles, or `'add'` for the add control when the list empties. Armed before
+    // the callback runs and read after the next commit, because the row that is
+    // gone cannot be focused and the row that replaced it does not exist yet.
+    const pending = useRef(null);
+    const capped = images.length >= cap;
+    // The four absent values rather than a truthiness test, for the reason
+    // `LiveRegion` states: an empty string, a null from a state that has not
+    // resolved and a false from a condition are three routes to "nothing to say",
+    // and a list of three is a list the fourth route would miss. Zero is not on it
+    // because React renders `0`.
+    const showEmpty = images.length === 0 && empty !== '' && empty !== null && empty !== undefined && empty !== false;
+    useEffect(() => {
+        const target = pending.current;
+        if (target === null)
+            return;
+        pending.current = null;
+        const root = rootRef.current;
+        if (root === null)
+            return;
+        if (target === 'add') {
+            root.querySelector(ADD_SLOT)?.focus();
+            return;
+        }
+        const buttons = root.querySelectorAll(REMOVE_SLOT);
+        // The row that moved up into the removed row's place, or the one above it when
+        // the removed row was the last. `Math.min` against the new count is the whole
+        // rule, and the list being empty afterwards is the case that has no row left
+        // to land on.
+        const button = buttons.item(Math.min(target, buttons.length - 1));
+        if (button === null)
+            root.querySelector(ADD_SLOT)?.focus();
+        else
+            button.focus();
+    });
+    const removeAt = (index) => {
+        const image = images[index];
+        if (image === undefined)
+            return;
+        pending.current = index;
+        onRemove(image.id);
+    };
+    return (_jsxs("div", { ref: rootRef, "data-slot": "image-list-field", className: cn('flex w-full flex-col gap-2', className), children: [label === undefined ? null : (_jsx("span", { id: labelId, "data-slot": "image-list-field-label", className: "text-muted-foreground text-xs font-medium tracking-wide uppercase", children: label })), showEmpty ? (_jsx("p", { "data-slot": "image-list-field-empty", className: "text-muted-foreground text-sm", children: empty })) : (_jsx("ol", { "data-slot": "image-list-field-list", "aria-labelledby": label === undefined ? undefined : labelId, className: "flex w-full flex-col gap-2", children: images.map((image, index) => (_jsxs("li", { "data-slot": "image-list-field-item", className: "border-border bg-card flex items-center gap-3 rounded-md border px-3 py-2", children: [image.preview === undefined || image.preview === null || image.preview === false ? null : (
+                        /*
+                         * The caller's picture, clipped rather than sized. A preview that
+                         * keeps its own aspect ratio changes the height of the row it sits
+                         * in, and a list of rows whose heights depend on the pictures in
+                         * them is a list a reader cannot scan. The caller's own `alt`
+                         * stays reachable: the box is not `aria-hidden`, because an image
+                         * carries information the row's name does not, and a caller whose
+                         * preview really is decoration passes one that says so.
+                         */
+                        _jsx("div", { "data-slot": "image-list-field-preview", className: "bg-muted flex size-12 shrink-0 items-center justify-center overflow-hidden rounded-md", children: image.preview })), _jsx("span", { "data-slot": "image-list-field-name", className: "min-w-0 flex-1 truncate text-sm font-medium", children: image.name }), _jsx("button", { type: "button", "data-slot": "image-list-field-remove", "aria-label": removeLabel(image.name), onClick: () => removeAt(index), className: REMOVE_CONTROL, children: _jsx(XIcon, { className: "size-4", "aria-hidden": "true" }) })] }, image.id))) })), _jsxs("div", { "data-slot": "image-list-field-actions", className: "flex items-center gap-2", children: [_jsx("span", { "data-slot": "image-list-field-add-control", className: cn('inline-flex', capped && 'opacity-50'), children: _jsxs(Button, { "data-slot": "image-list-field-add", type: "button", variant: "outline", size: "sm", "aria-disabled": capped || undefined, "aria-describedby": capped && capLabel !== undefined ? capId : undefined, onClick: capped ? () => undefined : onAdd, children: [_jsx(ImagePlusIcon, { "aria-hidden": "true" }), addLabel] }) }), capped && capLabel !== undefined ? (_jsx("span", { id: capId, "data-slot": "image-list-field-cap", className: "text-muted-foreground text-xs", children: capLabel })) : null] })] }));
+}
+export { ImageListField };

package/dist/components/ui/image-zoom.d.ts

@@ -0,0 +1,164 @@
+import { type ComponentProps, type ReactNode } from 'react';
+/** The props the ImageZoom accepts. */
+export interface ImageZoomProps extends Omit<ComponentProps<'div'>, 'children'> {
+    /** The image to magnify, at the resolution it should be magnified into. */
+    src: string;
+    /**
+     * The image's description, and required.
+     *
+     * Required for the reason it is required on `Lightbox`: an image with no
+     * description is a picture a reader can see more of and still not read, and
+     * this Component's whole purpose is that they see more of it. It is also the
+     * only thing that tells a screen reader what the thing they are magnifying is,
+     * because magnification changes no semantics at all: the element is still an
+     * `img` with this `alt` before, during and after.
+     */
+    alt: string;
+    /**
+     * The accessible name of the group, and required.
+     *
+     * A page with two magnified images is a page where a reader cannot tell which
+     * set of controls they are in, and the controls are three buttons that all
+     * look alike. The name is the caller's word, and `role="group"` is the
+     * deliberate choice over a landmark: a group is announced where it is met and
+     * never appears in a landmark list, so a page with six figures does not put six
+     * new entries in a reader's list of regions to walk.
+     */
+    label: string;
+    /**
+     * The words for the current magnification, and required.
+     *
+     * A function rather than a string, for the reason `Carousel`'s `position` is
+     * one: a magnification is a number and the sentence around it is different in
+     * every language, so the sentence is the caller's. It receives a percentage, not
+     * a multiplier, because a percentage is the form a reader reads and a
+     * multiplier is the form this Component stores.
+     */
+    scale: (percent: number) => string;
+    /**
+     * The smallest magnification, as a multiple of the fitted size. @defaultValue 1
+     *
+     * A number and not a keyword, because the useful answers are a designer's: the
+     * fitted size, twice the fitted size, and a figure from the caller's own brief.
+     */
+    minScale?: number;
+    /** The largest. @defaultValue 4 */
+    maxScale?: number;
+    /** How much one press moves it. @defaultValue 0.5 */
+    step?: number;
+    /**
+     * The accessible name of the control that magnifies, and required.
+     *
+     * Required rather than defaulted on the reasoning `Lightbox` states: a
+     * hardcoded accessible name is a sentence a consumer cannot localise, and the
+     * only fix is a fork of this package. The three names are the caller's because
+     * they are three sentences in the caller's own words, and because "Zoom" is
+     * not the word a German product says for it.
+     */
+    zoomInLabel: string;
+    /** The accessible name of the control that reduces the magnification. */
+    zoomOutLabel: string;
+    /** The accessible name of the control that returns the image to its fitted size. */
+    resetLabel: string;
+    /**
+     * The caller's own controls, drawn after this Component's three.
+     *
+     * A slot and not a second set of props, because everything a reader might want
+     * beside a magnifier is the consumer's decision: a download, a "show the whole
+     * page" that hands off to `Lightbox`, a reset for the surrounding form. Prism
+     * draws the three controls it can get right, and this is where the rest go. The
+     * cost is that a caller who wants their own magnification controls cannot
+     * suppress these three, and the answer is that a magnifier whose only route to
+     * magnification is in someone else's markup is not a magnifier.
+     */
+    controls?: ReactNode;
+    /**
+     * Called with the magnification after every press.
+     *
+     * A notification rather than a controlled prop, and the reason is the same as
+     * `Lightbox`'s reset: the magnification is a decision about this visit. A
+     * reader who magnified a diagram, went away and came back should find it as
+     * they left it, not as they found it, so it is held here and not lifted. What
+     * the caller usually wants the number for is layout, and a notification is
+     * enough for that.
+     */
+    onScaleChange?: (scale: number) => void;
+    /** Layout only, exactly as on every Component. */
+    className?: string;
+}
+/**
+ * An image the reader magnifies where it already sits, with a frame that scrolls
+ * once it is larger than its box.
+ *
+ * **It is the `Lightbox` with the dialog taken out, and that subtraction is the
+ * whole Component.** A `Lightbox` opens a portal, traps focus, locks page scroll,
+ * swallows the Escape key and hands the reader a different place in the document
+ * to come back from. All five of those are the right price for an image the page
+ * has not shown the reader at all, where the enlargement is the only way to see
+ * it. They are the wrong price for an image the reader is already looking at:
+ * paying a focus trap to make a picture on the page bigger costs the reader their
+ * scroll position, their place in the document and their focus context, and a
+ * reader who has magnified an inline diagram and then closed the dialog lands
+ * somewhere they have to find again. So there is no portal, no overlay, no trap,
+ * no Escape key and no dismiss here. The page does not move and nothing is taken
+ * away from it. **Use a `Lightbox` when the enlargement is the only route to the
+ * image; use this when the image is already on the page and only its size is in
+ * the way.**
+ *
+ * **Prism draws the three controls and asks for their names, rather than taking
+ * the controls as a slot.** A slot would move the one guarantee that makes a
+ * magnifier usable to the caller: that the controls exist, that they are real
+ * buttons in the tab order, that they are disabled at the ends of the range, and
+ * that a reader whose control has just been disabled is moved to one that still
+ * works. That last one is not obvious and `Carousel` had to write a `useEffect`
+ * to get it right, because a disabled button leaves the tab order without giving
+ * up focus: a reader who presses zoom in at the ceiling is left focused on a
+ * control that can no longer answer Enter, Space or anything else, stranded
+ * inside the magnifier with no working control under their fingers. This
+ * Component does that move itself. The cost is that a caller who wants their own
+ * magnification controls cannot have them here, and the answer is that this is
+ * the wrong Component for a caller who wants that.
+ *
+ * **The scale transition is a transform with a token duration, and it is the only
+ * motion on the surface.** Magnifying a picture is spatial movement of a whole
+ * surface, so a reader who has asked for reduced motion gets the new size
+ * immediately and loses nothing but the travel between the two. Nothing here is
+ * guarded per call site any more: `packages/ui/src/styles.css` stops every
+ * transition under `prefers-reduced-motion` in one unlayered rule, and a
+ * `motion-safe:` beside an unguarded `transition-transform` was inert rather than
+ * cautious. The transition is on `transform` and on nothing else: an animated
+ * `width` or `height` is a layout animation on the main thread, which is the
+ * defect the compositor rule in the ambient layer exists to prevent, and a
+ * magnified diagram is large enough for that to be visible.
+ *
+ * **The scale reaches its final value before the pixels do, and that is the
+ * price of using a transform.** A transform does not change layout, so the
+ * frame's scroll extent is already at its full size on the first frame of the
+ * transition and the scrollbar arrives while the image is still travelling. The
+ * alternative is to animate the image's own size, which is a main-thread layout
+ * animation on the largest element on the page, and a scrollbar that moves a
+ * fraction early is a cheaper defect than a stuttering diagram.
+ *
+* **Panning is a scroll, not a gesture.** Once the image is larger than its frame
+ * the frame scrolls, and the reader pans with the keys they already use: the
+ * arrow keys, the space bar, the Home and End keys, and a trackpad or a finger.
+ * There is no drag to pan, no pinch and no double tap, for the reason
+ * `Lightbox` gives: each of those is a bespoke pointer model a reader has to
+ * discover, and a scrollable frame is a thing every reader already knows. The
+ * frame is a block rather than a centred flex row, because a centred child
+ * larger than its scroll container has a left edge that cannot be scrolled back
+ * to in more than one browser, and a magnified image is routinely larger than
+ * its frame.
+ *
+ * **The scale is announced, politely, in the caller's words.** The sentence is in
+   * an `aria-live="polite"` region beside the controls, so a reader who has just
+   * pressed a button is told where they are without the announcement interrupting
+   * whatever they were reading. It is polite rather than assertive for the same
+   * reason `Carousel`'s position is: the reader caused the change by pressing a
+   * control and does not need to be interrupted by it.
+ *
+ * It is a client Component, because it holds a magnification and answers presses.
+ */
+declare function ImageZoom({ src, alt, label, scale, minScale, maxScale, step, zoomInLabel, zoomOutLabel, resetLabel, controls, onScaleChange, className, ...props }: ImageZoomProps): import("react").JSX.Element;
+export { ImageZoom };
+//# sourceMappingURL=image-zoom.d.ts.map

package/dist/components/ui/image-zoom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-zoom.d.ts","sourceRoot":"","sources":["../../../src/components/ui/image-zoom.tsx"],"names":[],"mappings":"AAGA,OAAO,EAA4C,KAAK,cAAc,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAgBrG,uCAAuC;AACvC,MAAM,WAAW,cAAe,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAC7E,2EAA2E;IAC3E,GAAG,EAAE,MAAM,CAAA;IACX;;;;;;;;;OASG;IACH,GAAG,EAAE,MAAM,CAAA;IACX;;;;;;;;;OASG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;OAQG;IACH,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAA;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;;;OAQG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB,yEAAyE;IACzE,YAAY,EAAE,MAAM,CAAA;IACpB,oFAAoF;IACpF,UAAU,EAAE,MAAM,CAAA;IAClB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACvC,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AA6BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AACH,iBAAS,SAAS,CAAC,EACjB,GAAG,EACH,GAAG,EACH,KAAK,EACL,KAAK,EACL,QAAc,EACd,QAAkB,EAClB,IAAa,EACb,WAAW,EACX,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,aAAa,EACb,SAAS,EACT,GAAG,KAAK,EACT,EAAE,cAAc,+BAyJhB;AAED,OAAO,EAAE,SAAS,EAAE,CAAA"}

package/dist/components/ui/image-zoom.js

@@ -0,0 +1,169 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ScanIcon, ZoomInIcon, ZoomOutIcon } from 'lucide-react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { cn } from '../../lib/utils.js';
+/**
+ * The magnification the Component holds at its smallest, and the value it returns
+ * to, as a multiple of the image's fitted size.
+ */
+const FIT = 1;
+/** The largest magnification offered when the caller names none. */
+const CEILING = 4;
+/** How much one press moves the magnification when the caller names no step. */
+const STRIDE = 0.5;
+/**
+ * The magnification every control in this Component draws.
+ *
+ * One string rather than three, for the reason `drawer.tsx` states: a control bar
+ * where the out control has its own metrics and the reset has another is a bar a
+ * reader moving by Tab finds unevenly spaced, and the difference is invisible in
+ * review.
+ *
+ * `pointer-coarse:size-11` is the coarse-pointer floor, as a step, because the bar
+ * is `flex flex-wrap items-center gap-2` and a bordered box at 44px is what a finger
+ * aims at. A band was rejected on condition 1: the controls sit eight pixels apart,
+ * and a 44px band centred on a 36px box overhangs its box by four on each side, which
+ * lands inside that gap rather than on a neighbour, so the band would buy eight
+ * pixels of reach for a target that is already only eight short and would leave the
+ * drawn box at 36. See DESIGN.md, The coarse-pointer floor.
+ */
+const CONTROL = 'text-muted-foreground hover:text-foreground border-input bg-background inline-flex size-9 items-center justify-center rounded-md border outline-none transition-colors duration-fast ease-out disabled:pointer-events-none disabled:opacity-50 focus-visible:ring-ring focus-visible:ring-[3px]' +
+    ' pointer-coarse:size-11';
+/** A magnification inside the caller's bounds, so no press can leave the range. */
+function bound(value, low, high) {
+    if (!Number.isFinite(value))
+        return low;
+    if (high < low)
+        return low;
+    return Math.min(Math.max(value, low), high);
+}
+/**
+ * An image the reader magnifies where it already sits, with a frame that scrolls
+ * once it is larger than its box.
+ *
+ * **It is the `Lightbox` with the dialog taken out, and that subtraction is the
+ * whole Component.** A `Lightbox` opens a portal, traps focus, locks page scroll,
+ * swallows the Escape key and hands the reader a different place in the document
+ * to come back from. All five of those are the right price for an image the page
+ * has not shown the reader at all, where the enlargement is the only way to see
+ * it. They are the wrong price for an image the reader is already looking at:
+ * paying a focus trap to make a picture on the page bigger costs the reader their
+ * scroll position, their place in the document and their focus context, and a
+ * reader who has magnified an inline diagram and then closed the dialog lands
+ * somewhere they have to find again. So there is no portal, no overlay, no trap,
+ * no Escape key and no dismiss here. The page does not move and nothing is taken
+ * away from it. **Use a `Lightbox` when the enlargement is the only route to the
+ * image; use this when the image is already on the page and only its size is in
+ * the way.**
+ *
+ * **Prism draws the three controls and asks for their names, rather than taking
+ * the controls as a slot.** A slot would move the one guarantee that makes a
+ * magnifier usable to the caller: that the controls exist, that they are real
+ * buttons in the tab order, that they are disabled at the ends of the range, and
+ * that a reader whose control has just been disabled is moved to one that still
+ * works. That last one is not obvious and `Carousel` had to write a `useEffect`
+ * to get it right, because a disabled button leaves the tab order without giving
+ * up focus: a reader who presses zoom in at the ceiling is left focused on a
+ * control that can no longer answer Enter, Space or anything else, stranded
+ * inside the magnifier with no working control under their fingers. This
+ * Component does that move itself. The cost is that a caller who wants their own
+ * magnification controls cannot have them here, and the answer is that this is
+ * the wrong Component for a caller who wants that.
+ *
+ * **The scale transition is a transform with a token duration, and it is the only
+ * motion on the surface.** Magnifying a picture is spatial movement of a whole
+ * surface, so a reader who has asked for reduced motion gets the new size
+ * immediately and loses nothing but the travel between the two. Nothing here is
+ * guarded per call site any more: `packages/ui/src/styles.css` stops every
+ * transition under `prefers-reduced-motion` in one unlayered rule, and a
+ * `motion-safe:` beside an unguarded `transition-transform` was inert rather than
+ * cautious. The transition is on `transform` and on nothing else: an animated
+ * `width` or `height` is a layout animation on the main thread, which is the
+ * defect the compositor rule in the ambient layer exists to prevent, and a
+ * magnified diagram is large enough for that to be visible.
+ *
+ * **The scale reaches its final value before the pixels do, and that is the
+ * price of using a transform.** A transform does not change layout, so the
+ * frame's scroll extent is already at its full size on the first frame of the
+ * transition and the scrollbar arrives while the image is still travelling. The
+ * alternative is to animate the image's own size, which is a main-thread layout
+ * animation on the largest element on the page, and a scrollbar that moves a
+ * fraction early is a cheaper defect than a stuttering diagram.
+ *
+* **Panning is a scroll, not a gesture.** Once the image is larger than its frame
+ * the frame scrolls, and the reader pans with the keys they already use: the
+ * arrow keys, the space bar, the Home and End keys, and a trackpad or a finger.
+ * There is no drag to pan, no pinch and no double tap, for the reason
+ * `Lightbox` gives: each of those is a bespoke pointer model a reader has to
+ * discover, and a scrollable frame is a thing every reader already knows. The
+ * frame is a block rather than a centred flex row, because a centred child
+ * larger than its scroll container has a left edge that cannot be scrolled back
+ * to in more than one browser, and a magnified image is routinely larger than
+ * its frame.
+ *
+ * **The scale is announced, politely, in the caller's words.** The sentence is in
+   * an `aria-live="polite"` region beside the controls, so a reader who has just
+   * pressed a button is told where they are without the announcement interrupting
+   * whatever they were reading. It is polite rather than assertive for the same
+   * reason `Carousel`'s position is: the reader caused the change by pressing a
+   * control and does not need to be interrupted by it.
+ *
+ * It is a client Component, because it holds a magnification and answers presses.
+ */
+function ImageZoom({ src, alt, label, scale, minScale = FIT, maxScale = CEILING, step = STRIDE, zoomInLabel, zoomOutLabel, resetLabel, controls, onScaleChange, className, ...props }) {
+    const [at, setAt] = useState(FIT);
+    /*
+     * The caller's range, made into a range that can hold. A magnification that is
+     * not a positive number is a division that has not happened yet, and a ceiling
+     * that is not above the floor is two numbers that cannot both be true. In
+     * either case the fitted size and the default ceiling are drawn instead rather
+     * than a range that magnifies the wrong way or refuses to move, and the value
+     * actually in force is reported on the frame as `data-scale`, so a substituted
+     * bound is legible in the markup rather than only in the screenshot. That is
+     * `AspectRatio`'s rule about a value that cannot be drawn, applied to a range.
+     */
+    const low = Number.isFinite(minScale) && minScale > 0 ? minScale : FIT;
+    const high = Number.isFinite(maxScale) && maxScale > low ? maxScale : Math.max(CEILING, low);
+    const stride = Number.isFinite(step) && step !== 0 ? Math.abs(step) : STRIDE;
+    const zoomIn = useRef(null);
+    const zoomOut = useRef(null);
+    const set = useCallback((next) => {
+        const value = bound(next, low, high);
+        setAt(value);
+        onScaleChange?.(value);
+    }, [high, low, onScaleChange]);
+    const magnified = at > FIT;
+    const atFloor = at <= low;
+    const atCeiling = at >= high;
+    /*
+     * A control that has just been disabled must not keep the reader's focus. A
+     * disabled button is out of the tab order and does not give up focus, so a
+     * reader who magnifies to the ceiling is left focused on a control that can no
+     * longer answer anything. Focus is handed to the sibling that is still live,
+     * which is what a browser does when focus lands on something that has become
+     * inert, and only when the stranded control is one of this Component's two.
+     */
+    useEffect(() => {
+        const active = document.activeElement;
+        if (!(active instanceof HTMLButtonElement))
+            return;
+        if (active !== zoomIn.current && active !== zoomOut.current)
+            return;
+        if (active.disabled !== true)
+            return;
+        const live = active === zoomIn.current ? zoomOut.current : zoomIn.current;
+        if (live === null || live.disabled)
+            return;
+        live.focus();
+    });
+    return (_jsxs("div", { "data-slot": "image-zoom", role: "group", "aria-label": label, className: cn('flex flex-col gap-2', className), ...props, children: [_jsx("div", { "data-slot": "image-zoom-frame", "data-scale": at, "data-zoomed": magnified || undefined, className: "overflow-auto overscroll-contain", children: _jsx("img", { "data-slot": "image-zoom-image", src: src, alt: alt, 
+                    // A transform is the one value on this element that is not a utility
+                    // class, and the reason is that the magnification is a number the
+                    // caller passed rather than one of a closed set Prism authored. A
+                    // utility would be a closed list of factors, and a magnifier whose
+                    // ceiling is whichever factor the caller happened to be closest to is a
+                    // magnifier that rounds the reader's request.
+                    style: { transform: `scale(${at})` }, className: "block h-auto w-full origin-top-left transition-transform duration-base ease-out" }) }), _jsxs("div", { "data-slot": "image-zoom-controls", className: "flex flex-wrap items-center gap-2", children: [_jsx("button", { type: "button", ref: zoomOut, "data-slot": "image-zoom-out", "aria-label": zoomOutLabel, disabled: atFloor, onClick: () => set(at - stride), className: CONTROL, children: _jsx(ZoomOutIcon, { className: "size-4", "aria-hidden": "true" }) }), magnified ? (_jsx("button", { type: "button", "data-slot": "image-zoom-reset", "aria-label": resetLabel, onClick: () => set(low), className: CONTROL, children: _jsx(ScanIcon, { className: "size-4", "aria-hidden": "true" }) })) : null, _jsx("button", { type: "button", ref: zoomIn, "data-slot": "image-zoom-in", "aria-label": zoomInLabel, disabled: atCeiling, onClick: () => set(at + stride), className: CONTROL, children: _jsx(ZoomInIcon, { className: "size-4", "aria-hidden": "true" }) }), _jsx("p", { "data-slot": "image-zoom-scale", "aria-live": "polite", className: "text-muted-foreground text-sm tabular-nums", children: scale(Math.round(at * 100)) }), controls] })] }));
+}
+export { ImageZoom };