nexus-shared 3.2.0 → 4.0.0

package/dist/Components/Viewers/OwnerFiles.js

@@ -0,0 +1,589 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { iconEye, iconFile, iconFileText, iconPencil, iconPhoto, iconStar, iconTrash, iconUpload, iconX, InlineIcon } from "nexus-icons";
+import { useCallback, useEffect, useLayoutEffect, useRef, useState, useSyncExternalStore } from "react";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { formatDateTime } from "../../Helpers/DateTimeHelpers.js";
+import { avatarTone, initials } from "../../Helpers/DropdownHelpers.js";
+import { useDatePreferences } from "../../Helpers/DatePreferences.js";
+import { acceptOf, fileKindName, fileKindsSentence, fileRefusal, fileSizeText, PICTURE_LIMITS, pictureLimits, pictureName, roomLeft, takesDocuments, typedFile } from "../../Helpers/FileAdapter.js";
+import { readPath } from "../../Helpers/TableHelpers.js";
+import { isPictureType } from "../../Interfaces/FileInterfaces.js";
+import { getFileAdapter, primaryPictures } from "../../Services/FileApi.js";
+import { loadImageEditor, preloadImageEditor } from "../../Services/ImageEditorLoader.js";
+import { Button } from "../Documents/Button.js";
+import { messageBox } from "../Layouts/MessageBox.js";
+import { openPopup } from "../Layouts/PopupHost.js";
+import { toast } from "../Layouts/Toaster.js";
+/** What a person the backend lets only look at an owner's files is told, when it gave no words of its own. */
+export const READ_ONLY_REASON = "You can see these files, but you may not change them.";
+/** The longest side of a stored picture when neither the params nor the backend say: Drive's default (`PICTURE_LIMITS`). */
+export const MAX_PICTURE_SIDE = PICTURE_LIMITS.maxSide;
+/** Tells what a refused or failed call said, once, in the server's own words. */
+export function toastFileFailure(title, answer) {
+    if (answer.aborted)
+        return;
+    toast(title, { tone: "danger", message: answer.message ?? "Try again in a moment." });
+}
+const ownerOf = (params) => ({ module: params.module, category: params.category, ownerId: params.ownerId });
+/** Opens a file chooser for the category's kinds; resolves the chosen files, empty when nothing was chosen. */
+function chooseFiles(accept, multiple) {
+    return new Promise(resolve => {
+        const input = document.createElement("input");
+        input.type = "file";
+        input.accept = accept;
+        input.multiple = multiple;
+        input.addEventListener("change", () => resolve(Array.from(input.files ?? [])), { once: true });
+        input.addEventListener("cancel", () => resolve([]), { once: true });
+        input.click();
+    });
+}
+/**
+ * The editor module, or null when it could not be downloaded: then a toast says why, and so does `onProblem` - the
+ * input's or the gallery's own note, which stays until a later try opens it (`loadImageEditor` keeps no failure, so the
+ * next Upload, Edit or View tries again).
+ */
+async function editor(onProblem) {
+    try {
+        const module = await loadImageEditor();
+        onProblem(null);
+        return module;
+    }
+    catch (error) {
+        const message = error instanceof Error && error.message ? error.message : "The image editor could not be downloaded. Try again in a moment.";
+        onProblem(message);
+        toastFileFailure("The image editor could not be opened", { message });
+        return null;
+    }
+}
+/**
+ * What the editor is opened with for a picture of this category: the page's shape, kind and start quality within the
+ * category's limits (`pictureLimits`: Drive's settings, else the defaults).
+ */
+function pictureOptions(params, category) {
+    const limits = pictureLimits(category);
+    return {
+        aspect: params.aspect ?? "free",
+        shape: params.shape,
+        maxWidth: Math.min(params.maxWidth ?? limits.maxSide, limits.maxSide),
+        maxHeight: Math.min(params.maxHeight ?? limits.maxSide, limits.maxSide),
+        type: params.type,
+        // Only kinds the category takes: a picture the editor would otherwise save as a WebP for its size is never refused.
+        types: category.types.filter(isPictureType),
+        quality: params.quality,
+        maxQuality: limits.quality / 100,
+        maxBytes: limits.maxBytes,
+        thumbnail: category.thumbnailSize || false,
+    };
+}
+/** What a toast says of a picture its size limit made smaller; nothing when it fitted as it was. */
+function fittedNote(saved) {
+    return saved.fitted ? `Made smaller to fit the ${fileSizeText(saved.fitted.maxBytes)} a picture may take here.` : undefined;
+}
+/** One owner's files, and every change a person can make to them. `ownerId` null: nothing is read (a record not saved yet). */
+export function useOwnerFiles(params) {
+    const [status, setStatus] = useState({ kind: "idle" });
+    const [busy, setBusy] = useState(null);
+    // Why the image editor could not be opened, the last time it was tried: the input says so until it opens.
+    const [editorProblem, setEditorProblem] = useState(null);
+    const latest = useRef(params);
+    latest.current = params;
+    const { module, category, ownerId } = params;
+    const owner = ownerId ? { module, category, ownerId } : null;
+    const ownerKey = owner ? `${String(module)}|${category}|${ownerId}` : null;
+    const load = useCallback(async (signal) => {
+        const current = latest.current;
+        if (!current.ownerId)
+            return setStatus({ kind: "idle" });
+        const answer = await getFileAdapter().list(ownerOf(current), { signal });
+        if (signal?.aborted)
+            return;
+        if (!answer.ok || !answer.result)
+            return setStatus({ kind: "failed", message: answer.message ?? "The files could not be loaded." });
+        setStatus({ kind: "ready", data: answer.result });
+        const primary = answer.result.files.find(file => file.isPrimary) ?? null;
+        primaryPictures.set(ownerOf(current), primary);
+        return primary;
+    }, [ownerKey]);
+    useEffect(() => {
+        if (!ownerKey) {
+            setStatus({ kind: "idle" });
+            return;
+        }
+        setStatus({ kind: "loading" });
+        const controller = new AbortController();
+        void load(controller.signal);
+        return () => controller.abort();
+    }, [ownerKey, load]);
+    const data = status.kind === "ready" ? status.data : null;
+    const locked = params.lockReason?.trim() || null;
+    const canWrite = Boolean(data?.category.canWrite) && !params.readOnly && !locked;
+    /** Why nothing can be changed, when it is the page's or the backend's rule (not a form shown read only). */
+    const readOnlyReason = locked ?? (data && !data.category.canWrite ? data.readOnlyReason || READ_ONLY_REASON : null);
+    const pictures = data ? !takesDocuments(data.category) : true;
+    /** Runs one change with its line of progress, then reads the files again and tells the page. */
+    async function change(label, work) {
+        if (busy)
+            return;
+        setBusy(label);
+        try {
+            const changed = await work();
+            if (changed) {
+                const primary = await load();
+                if (primary !== undefined)
+                    latest.current.onChange?.(primary);
+            }
+        }
+        finally {
+            setBusy(null);
+        }
+    }
+    /** Room for more, or a plain refusal. */
+    function hasRoom(files, wanted = 1) {
+        if (roomLeft(files) >= wanted)
+            return true;
+        toastFileFailure("No room for another file", { message: `This keeps at most ${files.category.maxCount}. Delete one first.` });
+        return false;
+    }
+    /**
+     * Opens the editor on a picture, then stores what it saved as a new picture; `primary` makes it the owner's picture.
+     * `replacing`: the file a one-file category keeps, deleted once the editor has saved, since the category has no room
+     * for both.
+     */
+    async function editAndStore(src, name, primary, replacing) {
+        if (!owner || !data)
+            return false;
+        const module = await editor(setEditorProblem);
+        if (!module)
+            return false;
+        const current = latest.current;
+        const saved = await module.openImageEditor({ ...pictureOptions(current, data.category), src, title: current.title, fileName: name });
+        if (!saved)
+            return false;
+        const refusal = fileRefusal(data.category, saved.blob, saved.name || name);
+        if (refusal) {
+            toastFileFailure("The picture was not saved", { message: refusal });
+            return false;
+        }
+        if (replacing) {
+            const removed = await getFileAdapter().remove(owner, replacing.id);
+            if (!removed.ok) {
+                toastFileFailure("The picture was not replaced", removed);
+                return false;
+            }
+        }
+        const stored = await getFileAdapter().upload(owner, { file: saved.blob, name: pictureName(saved.name || name, saved.blob.type), thumbnail: saved.thumbnail });
+        if (!stored.ok || !stored.result) {
+            toastFileFailure(replacing ? "The old picture was deleted, but the new one was not saved" : "The picture was not saved", stored);
+            // A replaced file is gone: the list is read again either way.
+            return Boolean(replacing);
+        }
+        if (primary && !stored.result.isPrimary) {
+            const made = await getFileAdapter().setPrimary(owner, stored.result.id);
+            if (!made.ok) {
+                // Stored all the same: the list is read again, and the person is told once, not also "saved".
+                toastFileFailure("The picture was saved, but it is not the main picture yet", made);
+                return true;
+            }
+        }
+        toast("Picture saved", { tone: "success", message: fittedNote(saved) });
+        return true;
+    }
+    /**
+     * Stores chosen files, up to the room left: each picture through the editor first, one at a time ("Picture 2 of 5" in
+     * its title), saved within the category's limits with its thumbnail - Cancel there skips that one, and asks whether to
+     * go on with the rest - and any other file (a PDF) as it is.
+     */
+    async function storeMany(chosen) {
+        if (!owner || !data)
+            return false;
+        const room = roomLeft(data);
+        // A file the browser gave no type is typed from its bytes: a picture among them still goes through the editor.
+        const files = await Promise.all(chosen.slice(0, room).map(typedFile));
+        if (files.length < chosen.length)
+            toastFileFailure("Some files were left out", { message: `Only ${room} more fit here; ${chosen.length - files.length} were not uploaded.` });
+        const pictureCount = files.filter(file => isPictureType(file.type)).length;
+        let module = null;
+        let stored = 0;
+        let fitted = 0;
+        let pictureAt = 0;
+        for (const [index, file] of files.entries()) {
+            setBusy(files.length > 1 ? `Uploading ${index + 1} of ${files.length}` : "Uploading");
+            const picture = isPictureType(file.type);
+            // A picture is checked for its kind now and for its size once the editor has made it (a 12 MB phone photo is well
+            // under the limit once made); any other file is sent as it is, so it is checked whole now.
+            const refusal = fileRefusal(data.category, picture ? { type: file.type, size: 0 } : file, file.name);
+            if (refusal) {
+                toastFileFailure("A file was not uploaded", { message: refusal });
+                if (picture)
+                    pictureAt++;
+                continue;
+            }
+            let blob = file;
+            let thumbnail = null;
+            let name = file.name;
+            if (picture) {
+                pictureAt++;
+                module ??= await editor(setEditorProblem);
+                if (!module)
+                    break;
+                const current = latest.current;
+                const step = pictureCount > 1 ? `Picture ${pictureAt} of ${pictureCount}` : null;
+                let saved = null;
+                try {
+                    saved = await module.openImageEditor({ ...pictureOptions(current, data.category), src: file, title: step ? (current.title ? `${step} · ${current.title}` : step) : current.title, fileName: file.name });
+                }
+                catch {
+                    toastFileFailure("A file was not uploaded", { message: `"${file.name}" could not be read as a picture.` });
+                    continue;
+                }
+                if (!saved) {
+                    // Cancelled: that picture is skipped; with more to come, the person says whether to go on.
+                    const left = files.length - index - 1;
+                    if (left === 0)
+                        continue;
+                    const goOn = await messageBox.confirm({
+                        title: "Go on with the next file?",
+                        message: `"${file.name}" was not uploaded. ${left} more ${left === 1 ? "file waits" : "files wait"} to be uploaded.`,
+                        confirmLabel: "Next file",
+                        cancelLabel: "Stop here",
+                    });
+                    if (!goOn)
+                        break;
+                    continue;
+                }
+                blob = saved.blob;
+                thumbnail = saved.thumbnail;
+                // An upload keeps the chosen file's name, with the kind it was saved as.
+                name = pictureName(file.name, saved.blob.type);
+                if (saved.fitted)
+                    fitted++;
+                const tooLarge = fileRefusal(data.category, blob, file.name);
+                if (tooLarge) {
+                    toastFileFailure("A file was not uploaded", { message: tooLarge });
+                    continue;
+                }
+            }
+            const answer = await getFileAdapter().upload(owner, { file: blob, name, thumbnail });
+            if (answer.ok)
+                stored++;
+            else
+                toastFileFailure(`"${file.name}" was not uploaded`, answer);
+        }
+        const limit = fileSizeText(pictureLimits(data.category).maxBytes);
+        const note = fitted === 0 ? undefined : fitted === 1 ? `One picture was made smaller to fit the ${limit} a picture may take here.` : `${fitted} pictures were made smaller to fit the ${limit} a picture may take here.`;
+        if (stored > 0)
+            toast(stored === 1 ? "File uploaded" : `${stored} files uploaded`, { tone: "success", message: note });
+        return stored > 0;
+    }
+    const actions = {
+        reload: () => load(),
+        /**
+         * Chooses a picture, edits it, and makes it the owner's picture (the picture input's Upload). In a category that
+         * keeps one file, the new picture takes the place of the one kept (Replace).
+         */
+        replace: async () => {
+            if (!data)
+                return;
+            const replacing = data.category.maxCount === 1 ? data.files[0] : undefined;
+            if (!replacing && !hasRoom(data))
+                return;
+            const [file] = await chooseFiles(acceptOf({ types: data.category.types.filter(isPictureType) }), false);
+            if (file)
+                await change("Saving", () => editAndStore(file, file.name, true, replacing));
+        },
+        /** Chooses several files and stores them: each picture through the editor, one at a time (the gallery's Upload). */
+        upload: async () => {
+            if (!data || !hasRoom(data))
+                return;
+            const chosen = await chooseFiles(acceptOf(data.category), data.category.maxCount > 1);
+            if (chosen.length > 0)
+                await change("Uploading", () => storeMany(chosen));
+        },
+        /**
+         * Edits a stored picture; what is saved is a new picture, the owner's picture when the edited one was. In a category
+         * that keeps one file, the edited picture takes its place.
+         */
+        edit: async (file) => {
+            if (!data)
+                return;
+            const replacing = data.category.maxCount === 1 && data.files.length === 1 ? file : undefined;
+            if (!replacing && !hasRoom(data))
+                return;
+            await change("Saving", () => editAndStore(getFileAdapter().fileUrl(file, "original"), file.name, file.isPrimary || Boolean(replacing), replacing));
+        },
+        makePrimary: (file) => owner &&
+            change("Saving", async () => {
+                const answer = await getFileAdapter().setPrimary(owner, file?.id ?? null);
+                if (!answer.ok)
+                    toastFileFailure(file ? "This picture could not be made the main one" : "The picture could not be removed", answer);
+                return answer.ok;
+            }),
+        rename: async (file) => {
+            if (!owner)
+                return;
+            const name = await messageBox.prompt({ title: "Rename", label: "Name", defaultValue: file.name.replace(/\.[A-Za-z][A-Za-z0-9]{0,3}$/, ""), confirmLabel: "Rename" });
+            if (name === null || !name.trim())
+                return;
+            await change("Saving", async () => {
+                const answer = await getFileAdapter().rename(owner, file.id, name.trim());
+                if (!answer.ok)
+                    toastFileFailure("The file was not renamed", answer);
+                return answer.ok;
+            });
+        },
+        remove: async (file) => {
+            if (!owner)
+                return;
+            const yes = await messageBox.confirm({
+                title: `Delete "${file.name}"?`,
+                message: file.isPrimary && (data?.files.length ?? 0) > 1 ? "It is the main picture now; the next one takes its place. It cannot be brought back." : "It cannot be brought back.",
+                tone: "danger",
+                confirmLabel: "Delete",
+            });
+            if (!yes)
+                return;
+            await change("Deleting", async () => {
+                const answer = await getFileAdapter().remove(owner, file.id);
+                if (!answer.ok)
+                    toastFileFailure("The file was not deleted", answer);
+                return answer.ok;
+            });
+        },
+        /** Shows the pictures in the editor module's viewer, from `file`. */
+        view: async (file) => {
+            if (!data)
+                return;
+            const shown = data.files.filter(item => isPictureType(item.contentType));
+            const module = await editor(setEditorProblem);
+            if (!module)
+                return;
+            await module.openImageViewer({
+                images: shown.map(item => ({ src: getFileAdapter().fileUrl(item, "original"), title: item.name })),
+                index: Math.max(0, shown.indexOf(file)),
+                title: latest.current.title,
+            });
+        },
+    };
+    return { status, data, busy, canWrite, readOnlyReason, pictures, editorProblem, actions };
+}
+const FOCUSABLE = 'button, a[href], input, select, textarea, [tabindex]:not([tabindex="-1"])';
+/**
+ * Keeps the keyboard focus in an owner's files through a change (`busy`). Its buttons stay focusable while it runs
+ * (`aria-disabled`, never `disabled`: a focused control switched off sends the focus to the page in every browser), and
+ * when it ends with the focused button gone - a deleted file's, Edit after Remove, a star once its picture is the main
+ * one - the focus goes to the first control left in the same tile, row or `role="group"` (the picture input's buttons),
+ * else the first in `root`. Only when the focus
+ * was in `root` as the change began (or on the page, after a confirmation, while `root` had it last), and only when it
+ * has dropped to the page since: a person who moved on keeps their place.
+ */
+export function useFocusThroughChange(root, busy) {
+    const last = useRef(null);
+    const held = useRef(null);
+    useEffect(() => {
+        const box = root.current;
+        if (!box)
+            return;
+        const remember = (event) => {
+            if (event.target instanceof HTMLElement)
+                last.current = event.target;
+        };
+        box.addEventListener("focusin", remember);
+        return () => box.removeEventListener("focusin", remember);
+    }, [root]);
+    useLayoutEffect(() => {
+        const box = root.current;
+        if (!box)
+            return;
+        const now = document.activeElement;
+        const onPage = !now || now === document.body || now === document.documentElement || (now !== box && now.contains(box));
+        if (busy) {
+            if (held.current)
+                return;
+            const from = now instanceof HTMLElement && box.contains(now) ? now : onPage && last.current && box.contains(last.current) ? last.current : null;
+            held.current = from ? { element: from, group: from.closest("li, tr, [role=group]") } : null;
+            return;
+        }
+        const was = held.current;
+        held.current = null;
+        if (!was || !onPage)
+            return;
+        const usable = (element) => element instanceof HTMLElement && element.isConnected && box.contains(element) && !element.matches(":disabled") && element.getClientRects().length > 0;
+        const firstIn = (scope) => (scope?.isConnected ? Array.from(scope.querySelectorAll(FOCUSABLE)).find(usable) : undefined);
+        const target = (usable(was.element) ? was.element : undefined) ?? firstIn(was.group) ?? firstIn(box);
+        target?.focus({ preventScroll: true });
+    }, [root, busy]);
+}
+/** A control's props while a change runs: still focusable and announced as unavailable, its press ignored. */
+export function busyProps(busy, run) {
+    return { "aria-disabled": busy ? true : undefined, onClick: () => (busy ? undefined : run()) };
+}
+/* The owner's picture, small */
+/** The owner's picture as the page keeps it, read with the other rows' in one call. */
+export function usePrimaryPicture(owner) {
+    const key = owner ? `${String(owner.module)}|${owner.category}|${owner.ownerId}` : "";
+    const subscribe = useCallback((listener) => (owner ? primaryPictures.subscribe(owner, listener) : () => undefined), [key]);
+    const read = () => (owner ? primaryPictures.peek(owner) : null);
+    const file = useSyncExternalStore(subscribe, read, () => undefined);
+    useEffect(() => {
+        if (owner && primaryPictures.peek(owner) === undefined)
+            void primaryPictures.get(owner);
+    }, [key]);
+    return file;
+}
+/** An owner's picture, small: its thumbnail, or, when it has none, the initials of its `name` or a picture icon. */
+export function OwnerPicture({ owner, size = 28, aspect = 1, shape = "rect", label, name, onClick, className }) {
+    const file = usePrimaryPicture(owner);
+    const [failed, setFailed] = useState(null);
+    const url = file ? getFileAdapter().fileUrl(file, "thumbnail") : null;
+    const shown = url && failed !== url;
+    const ratio = typeof aspect === "number" && aspect > 0 ? aspect : 1;
+    const style = { "--nx-picture-h": typeof size === "number" ? `${size}px` : size, "--nx-picture-ratio": ratio };
+    const loading = file === undefined && Boolean(owner);
+    // Initials once it is known there is no picture (or it failed to load): never over a picture still on its way.
+    const letters = !shown && !loading && name ? initials(name) : "";
+    const face = shown ? _jsx("img", { src: url, alt: "", loading: "lazy", decoding: "async", onError: () => setFailed(url) }) : letters ? _jsx("span", { "aria-hidden": "true", children: letters }) : _jsx(InlineIcon, { icon: iconPhoto });
+    const classes = cx("nx-picture", shape === "circle" && "nx-picture--round", !shown && "nx-picture--empty", letters && "nx-picture--initials", loading && "nx-picture--loading", className);
+    const tone = letters ? avatarTone(name) : undefined;
+    if (!onClick) {
+        return (_jsx("span", { className: classes, style: style, "data-tone": tone, role: label ? "img" : undefined, "aria-label": label, title: label, children: face }));
+    }
+    return (_jsx("button", { type: "button", className: classes, style: style, "data-tone": tone, "aria-label": label, title: label, onClick: onClick, onPointerEnter: preloadImageEditor, children: face }));
+}
+/** The held tiles a gallery draws while its pictures are read, so the grid is there at once. */
+const HELD_TILES = [0, 1, 2];
+/** "2 of 20 · PNG, JPEG or WebP, up to 300 KB each": how many are kept, of how many, what kinds and how large. */
+function limitsLine(owned) {
+    // A picture's size is the category's picture limit (Drive's settings), a document's the category's own.
+    const pictureBytes = pictureLimits(owned.category).maxBytes;
+    const takesPictures = owned.category.types.some(isPictureType);
+    const sizes = takesPictures && takesDocuments(owned.category) ? `pictures up to ${fileSizeText(pictureBytes)}, documents up to ${fileSizeText(owned.category.maxBytes)}` : `up to ${fileSizeText(takesPictures ? pictureBytes : owned.category.maxBytes)} each`;
+    return `${owned.files.length} of ${owned.category.maxCount} · ${fileKindsSentence(owned.category.types)}, ${sizes}`;
+}
+/**
+ * Why a new file cannot be added: the category keeps no more. In the pictures' view a one-file category replaces, so it
+ * always can; the document list has no Replace, so there a full one-file category is held too.
+ */
+function noRoomReason(owned, replaces = true) {
+    if (roomLeft(owned) > 0 || (replaces && owned.category.maxCount === 1))
+        return null;
+    return owned.category.maxCount === 1 ? "This keeps one file: delete it first." : `This keeps at most ${owned.category.maxCount}: delete one first.`;
+}
+/**
+ * An owner's pictures, or documents for a category that takes PDF: upload several up to the category's limit, make
+ * one the main picture, view them in the editor module's viewer, edit one (saved as a new picture), delete.
+ *
+ * Pictures come in two panes, as the 2026-06-20 gallery did: the main picture large, with Upload and Remove (no main
+ * picture; the pictures stay) under it and the count and kinds; beside it the pictures as a grid, each with its own
+ * buttons inside it - View, Make main, Edit, Delete (Make main and Delete not on the main one) - shown on hover, on a
+ * keyboard's focus in the picture, and always where nothing can hover (a touch screen). Under 560px of its own width
+ * the main picture sits small beside its buttons, over the grid.
+ */
+export function PictureGallery(props) {
+    const files = useOwnerFiles(props);
+    const preferences = useDatePreferences();
+    const { status, data, busy, canWrite, readOnlyReason, editorProblem, actions } = files;
+    const rootRef = useRef(null);
+    useFocusThroughChange(rootRef, busy);
+    // The main picture's original that could not be shown (a file gone since the list was read): the icon stands in.
+    const [coverFailed, setCoverFailed] = useState(null);
+    const documents = props.view ? props.view === "documents" : !files.pictures;
+    const noun = documents ? "file" : "picture";
+    const known = data ? (documents ? "documents" : "pictures") : null;
+    const onViewKnown = useRef(props.onViewKnown);
+    onViewKnown.current = props.onViewKnown;
+    useEffect(() => {
+        if (known)
+            onViewKnown.current?.(known);
+    }, [known]);
+    if (status.kind === "failed") {
+        return (_jsxs("div", { ref: rootRef, className: "nx-files", "data-state": "failed", children: [_jsx("p", { className: "nx-files__note nx-files__note--error", role: "alert", children: status.message }), _jsx("div", { children: _jsx(Button, { size: "sm", onClick: () => void actions.reload(), children: "Try again" }) })] }));
+    }
+    const loading = status.kind === "loading" || status.kind === "idle";
+    const ratio = typeof props.aspect === "number" && props.aspect > 0 ? props.aspect : 1;
+    const shape = { "--nx-picture-ratio": ratio };
+    if (documents) {
+        if (loading) {
+            return (_jsx("div", { ref: rootRef, className: "nx-files", "data-state": "loading", "aria-busy": "true", children: _jsxs("p", { className: "nx-files__note", children: ["Loading the ", noun, "s\u2026"] }) }));
+        }
+        const owned = data;
+        // Held at the limit with its reason, as the pictures' Upload is; pressed, it says the refusal (`hasRoom`).
+        const full = noRoomReason(owned, false);
+        return (_jsxs("div", { ref: rootRef, className: "nx-files", "data-state": "ready", "aria-busy": busy ? "true" : undefined, children: [_jsxs("div", { className: "nx-files__bar", children: [_jsx("p", { className: "nx-files__note", "aria-live": "polite", children: busy ? `${busy}…` : limitsLine(owned) }), canWrite && (_jsx(Button, { variant: "primary", size: "sm", icon: _jsx(InlineIcon, { icon: iconUpload }), "aria-disabled": busy || full ? true : undefined, title: full ?? undefined, onClick: () => (busy ? undefined : void actions.upload()), onPointerEnter: preloadImageEditor, children: "Upload" }))] }), readOnlyReason && _jsx("p", { className: "nx-files__note", children: readOnlyReason }), editorProblem && !busy && (_jsx("p", { className: "nx-files__note nx-files__note--error", role: "alert", children: editorProblem })), owned.files.length === 0 ? (_jsxs("div", { className: "nx-files__empty", children: [_jsx(InlineIcon, { icon: iconFileText }), _jsxs("p", { children: ["No ", noun, "s yet."] }), canWrite && _jsxs("p", { className: "nx-files__note", children: ["Upload ", owned.category.maxCount > 1 ? `up to ${owned.category.maxCount}` : "one", "."] })] })) : (_jsx("ul", { className: "nx-files__list", children: owned.files.map(file => (_jsxs("li", { className: "nx-files__row", children: [isPictureType(file.contentType) ? (_jsx("button", { type: "button", className: "nx-picture", style: { "--nx-picture-h": "40px", "--nx-picture-ratio": 1 }, "aria-label": `View ${file.name}`, onClick: () => void actions.view(file), children: _jsx("img", { src: getFileAdapter().fileUrl(file, "thumbnail"), alt: "", loading: "lazy", decoding: "async" }) })) : (_jsx("span", { className: "nx-picture nx-picture--empty", style: { "--nx-picture-h": "40px", "--nx-picture-ratio": 1 }, "aria-hidden": "true", children: _jsx(InlineIcon, { icon: iconFile }) })), _jsxs("div", { className: "nx-files__row-text", children: [_jsx("a", { className: "nx-files__name", href: getFileAdapter().fileUrl(file, "original"), target: "_blank", rel: "noopener", children: file.name }), _jsxs("span", { className: "nx-files__note", children: [fileKindName(file.contentType), " \u00B7 ", fileSizeText(file.size), file.createdAt && ` · ${formatDateTime(file.createdAt, preferences)}`] })] }), canWrite && (_jsxs("div", { className: "nx-files__actions", children: [_jsx(Button, { size: "sm", variant: "ghost", icon: _jsx(InlineIcon, { icon: iconPencil }), "aria-label": `Rename ${file.name}`, title: "Rename", ...busyProps(busy, () => void actions.rename(file)) }), _jsx(Button, { size: "sm", variant: "ghost", hoverTone: "danger", icon: _jsx(InlineIcon, { icon: iconTrash }), "aria-label": `Delete ${file.name}`, title: "Delete", ...busyProps(busy, () => void actions.remove(file)) })] }))] }, file.id))) }))] }));
+    }
+    const owned = loading ? null : data;
+    const kept = owned?.files ?? [];
+    const primary = kept.find(file => file.isPrimary) ?? null;
+    // A category that keeps one file: a new picture takes the place of the one kept, and Remove deletes it.
+    const single = owned?.category.maxCount === 1;
+    const noRoom = owned ? noRoomReason(owned) : null;
+    const coverUrl = primary ? getFileAdapter().fileUrl(primary, "original") : null;
+    const coverShown = coverUrl && coverFailed !== coverUrl;
+    const editHeld = busy || noRoom ? true : undefined;
+    return (_jsx("div", { ref: rootRef, className: "nx-files nx-files--panes", "data-state": loading ? "loading" : "ready", "aria-busy": loading || busy ? "true" : undefined, children: _jsxs("div", { className: "nx-files__frame", children: [_jsxs("div", { className: "nx-files__side", children: [_jsx("span", { className: cx("nx-picture", "nx-files__cover", !coverShown && "nx-picture--empty", loading && "nx-picture--loading"), style: shape, role: "img", "aria-label": primary ? `The main picture: ${primary.name}` : loading ? "The main picture" : "No main picture", children: coverShown ? _jsx("img", { src: coverUrl, alt: "", decoding: "async", onError: () => setCoverFailed(coverUrl) }) : _jsx(InlineIcon, { icon: iconPhoto }) }), _jsxs("div", { className: "nx-files__about", children: [canWrite && owned && (_jsxs("div", { className: "nx-files__side-actions", children: [_jsx(Button, { variant: "primary", icon: _jsx(InlineIcon, { icon: iconUpload }), "aria-disabled": busy || noRoom ? true : undefined, title: noRoom ?? undefined, onClick: () => (busy ? undefined : void (single && kept.length > 0 ? actions.replace() : actions.upload())), onPointerEnter: preloadImageEditor, onFocus: preloadImageEditor, children: single && kept.length > 0 ? "Replace" : "Upload" }), primary && (_jsx(Button, { hoverTone: "danger", icon: _jsx(InlineIcon, { icon: single ? iconTrash : iconX }), title: single ? undefined : "Show no picture: the pictures are kept", ...busyProps(busy, () => void (single ? actions.remove(primary) : actions.makePrimary(null))), children: single ? "Delete" : "Remove" }))] })), _jsx("p", { className: "nx-files__note", "aria-live": "polite", children: loading ? `Loading the ${noun}s…` : busy ? `${busy}…` : limitsLine(owned) }), readOnlyReason && _jsx("p", { className: "nx-files__note", children: readOnlyReason }), editorProblem && !busy && (_jsx("p", { className: "nx-files__note nx-files__note--error", role: "alert", children: editorProblem }))] })] }), _jsx("div", { className: "nx-files__pane", children: loading ? (_jsx("ul", { className: "nx-files__grid", style: shape, "aria-hidden": "true", children: HELD_TILES.map(index => (_jsx("li", { children: _jsx("span", { className: "nx-table__bone nx-files__bone" }) }, index))) })) : kept.length === 0 ? (_jsxs("div", { className: "nx-files__empty", children: [_jsx(InlineIcon, { icon: iconPhoto }), _jsxs("p", { children: ["No ", noun, "s yet."] }), canWrite && _jsxs("p", { className: "nx-files__note", children: ["Upload ", owned.category.maxCount > 1 ? `up to ${owned.category.maxCount}` : "one", "."] })] })) : (_jsx("ul", { className: "nx-files__grid", style: shape, "aria-label": props.title ? `${props.title}: pictures` : "Pictures", children: kept.map(file => (_jsxs("li", { className: "nx-files__tile", "data-primary": file.isPrimary || undefined, children: [_jsx("span", { className: "nx-files__thumb", children: _jsx("img", { src: getFileAdapter().fileUrl(file, "thumbnail"), alt: "", loading: "lazy", decoding: "async" }) }), file.isPrimary && (_jsx("span", { className: "nx-table__tag nx-files__mark", "data-tone": "primary", children: "Main" })), _jsxs("div", { className: "nx-files__tools", role: "group", "aria-label": file.isPrimary ? `${file.name}, the main picture` : file.name, children: [_jsx(Button, { size: "sm", variant: "ghost", icon: _jsx(InlineIcon, { icon: iconEye }), "aria-label": `View ${file.name}`, title: "View", onClick: () => void actions.view(file), onPointerEnter: preloadImageEditor }), canWrite && !file.isPrimary && _jsx(Button, { size: "sm", variant: "ghost", icon: _jsx(InlineIcon, { icon: iconStar }), "aria-label": `Make ${file.name} the main picture`, title: "Make it the main picture", ...busyProps(busy, () => void actions.makePrimary(file)) }), canWrite && (_jsx(Button, { size: "sm", variant: "ghost", icon: _jsx(InlineIcon, { icon: iconPencil }), "aria-label": `Edit ${file.name}`, title: noRoom ? `Edit. ${noRoom}` : "Edit: saved as a new picture", "aria-disabled": editHeld, onClick: () => (busy ? undefined : void actions.edit(file)), onPointerEnter: preloadImageEditor, onFocus: preloadImageEditor })), canWrite && !file.isPrimary && _jsx(Button, { size: "sm", variant: "ghost", hoverTone: "danger", icon: _jsx(InlineIcon, { icon: iconTrash }), "aria-label": `Delete ${file.name}`, title: "Delete", ...busyProps(busy, () => void actions.remove(file)) })] })] }, file.id))) })) })] }) }));
+}
+/** An owner's documents as a list: `PictureGallery` with `view="documents"`. */
+export function DocumentList(props) {
+    return _jsx(PictureGallery, { ...props, view: "documents" });
+}
+/**
+ * Opens an owner's pictures (or documents) in a window; one window per owner and category. Pictures fill a wide
+ * window edge to edge in their two panes, the grid scrolling; documents are a list in a narrower one. Without `view`,
+ * the title, icon and size follow what the category takes once its files are read: a category that takes PDF says
+ * "Documents".
+ */
+export function openPictureGallery({ popupTitle, ...props }) {
+    const heading = (view) => {
+        const what = view === "documents" ? "Documents" : "Pictures";
+        return {
+            title: popupTitle ?? (props.title ? `${what} · ${props.title}` : what),
+            icon: _jsx(InlineIcon, { icon: view === "documents" ? iconFileText : iconPhoto }),
+            size: view === "documents" ? "lg" : "xl",
+            flush: view !== "documents",
+        };
+    };
+    let shown = props.view ?? "pictures";
+    return openPopup({
+        key: `nx-files:${String(props.module)}:${props.category}:${props.ownerId}`,
+        ...heading(shown),
+        content: popup => (_jsx(PictureGallery, { ...props, onViewKnown: view => {
+                props.onViewKnown?.(view);
+                if (view === shown)
+                    return;
+                shown = view;
+                popup.update(heading(view));
+            } })),
+    });
+}
+/**
+ * A column with each row's picture: every visible row's read in one call per page, and a click opens the row's
+ * gallery. A change there redraws the row's picture without a reload.
+ *
+ * @example
+ * columns: [pictureColumn({ module: NexusModule.Enterprise, category: "branch-picture", rowTitle: row => row.branchName }), ...]
+ */
+export function pictureColumn({ module, category, ownerKey = "id", rowTitle, nameKey, lockReason, onChange, aspect, shape, maxWidth, maxHeight, type, quality, readOnly, view, ...column }) {
+    return {
+        key: "picture",
+        label: "Picture",
+        width: "4.5rem",
+        align: "center",
+        sortable: false,
+        searchable: false,
+        resizable: false,
+        ...column,
+        value: () => null,
+        render: row => {
+            const id = readPath(row, ownerKey);
+            const ownerId = typeof id === "string" || typeof id === "number" ? String(id) : null;
+            if (!ownerId)
+                return null;
+            const title = rowTitle?.(row);
+            const owner = { module, category, ownerId };
+            const named = nameKey ? readPath(row, nameKey) : null;
+            const locked = typeof lockReason === "function" ? lockReason(row) : lockReason;
+            return (_jsx(OwnerPicture, { owner: owner, aspect: aspect, shape: shape, name: typeof named === "string" ? named : null, label: title ? `${title}: pictures` : "Pictures", onClick: () => openPictureGallery({ ...owner, title, aspect, shape, maxWidth, maxHeight, type, quality, readOnly, lockReason: locked ?? null, view, onChange: primary => onChange?.(row, primary) }) }));
+        },
+        text: () => "",
+    };
+}

package/dist/Components/Viewers/QrCodeImage.d.ts

@@ -0,0 +1,22 @@
+import type { CSSProperties } from "react";
+import { type QrLevel } from "../../Helpers/QrCode.ts";
+export interface QrCodeImageProps {
+    /** What the code holds: an authenticator's otpauth:// address, a link, any text, as UTF-8. */
+    value: string;
+    /** What a screen reader says in place of the picture: "QR code to add your account to an authenticator app". */
+    label: string;
+    /** The error correction level, M unless told: L, M, Q and H restore about 7%, 15%, 25% and 30% of a damaged code. */
+    level?: QrLevel;
+    /** The page's own class, for where the code sits: a grid area, a margin. */
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * A QR code as an image: one SVG path of black modules on a white square that holds the quiet zone, 9rem wide unless a
+ * class of the page's says otherwise (`nx-qr`). It stays black on white in a dark theme and in forced colours, since
+ * that is what a phone's camera reads. Nothing in it needs the browser, so a server component can render it. A text
+ * longer than a QR code holds throws, with how much it holds (`encodeQr`).
+ *
+ * @example <QrCodeImage value={setup.otpauthUri} label="QR code to add your account to an authenticator app" />
+ */
+export declare function QrCodeImage({ value, label, level, className, style }: QrCodeImageProps): import("react").JSX.Element;

package/dist/Components/Viewers/QrCodeImage.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { encodeQr, qrPath } from "../../Helpers/QrCode.js";
+/**
+ * A QR code as an image: one SVG path of black modules on a white square that holds the quiet zone, 9rem wide unless a
+ * class of the page's says otherwise (`nx-qr`). It stays black on white in a dark theme and in forced colours, since
+ * that is what a phone's camera reads. Nothing in it needs the browser, so a server component can render it. A text
+ * longer than a QR code holds throws, with how much it holds (`encodeQr`).
+ *
+ * @example <QrCodeImage value={setup.otpauthUri} label="QR code to add your account to an authenticator app" />
+ */
+export function QrCodeImage({ value, label, level, className, style }) {
+    const { viewBox, d } = qrPath(encodeQr(value, level));
+    return (_jsxs("svg", { role: "img", "aria-label": label, viewBox: viewBox, shapeRendering: "crispEdges", className: cx("nx-qr", className), style: style, children: [_jsx("rect", { width: "100%", height: "100%", fill: "#fff" }), _jsx("path", { d: d, fill: "#000" })] }));
+}