@cardinali-studio/adminkit 1.0.0

package/dist/form/media/useMediaLibrary.js

@@ -0,0 +1,495 @@
+/* Lo STATO della libreria media, separato da come si vede.
+ *
+ * Serviva perché le due parti non stanno più nello stesso pezzo di schermo: le cartelle sono la
+ * seconda colonna dell'admin, la griglia è la terza, e in mezzo c'è la barra del guscio. Con
+ * tutto dentro un componente solo, l'unico modo di dividerle sarebbe stato duplicare lo stato —
+ * cioè avere due idee diverse di quale cartella si sta guardando.
+ *
+ * Il modale di scelta (`MediaBrowser`) chiama questo stesso hook e mette i due pezzi affiancati:
+ * una sola implementazione, due impaginazioni.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { api, uploadQueue, ApiError } from "../../api.js";
+import { storageKey } from "../../config.js";
+/* Quanti file per richiesta nelle operazioni lunghe (cestina, sposta). Ogni file costa al
+ * server tre operazioni su R2 — legge, riscrive altrove, cancella — su oggetti da qualche MB.
+ * Dieci tiene una richiesta sotto i pochi secondi, che è la soglia oltre la quale chi guarda
+ * pensa che sia bloccato. Alzarlo fa tornare il difetto: richieste lunghe che muoiono a metà. */
+const CHUNK = 10;
+export const SORT_LABELS = {
+    uploaded: "caricamento", capturedAt: "scatto", name: "nome", size: "peso",
+};
+/* Dove eravamo l'ultima volta. Stessa convenzione delle preferenze di ordinamento
+ * (`sortKey`/`sortDir`): una chiave sola, il nome del prefisso, niente di più.
+ *
+ * Il prefisso del namespace lo decide il sito che monta il kit (`setStoragePrefix` in
+ * `config.ts`): qui dentro non può esserci il nome di un cliente. */
+const LAST_PREFIX = "lastPrefix";
+export function useMediaLibrary({ mode, multiple = true, active = true, remember = false }) {
+    const [prefix, setPrefix] = useState("");
+    const [folders, setFolders] = useState([]);
+    const [files, setFiles] = useState([]);
+    const [subfolders, setSubfolders] = useState([]);
+    const [selected, setSelected] = useState(new Set());
+    const [busy, setBusy] = useState(false);
+    const [loaded, setLoaded] = useState(false);
+    const [error, setError] = useState(null);
+    const [progress, setProgress] = useState(null);
+    const [uploadOpen, setUploadOpen] = useState(false);
+    const [viewing, setViewing] = useState(null);
+    // Le preferenze di ordinamento restano dov'erano — il prefisso che il sito dichiara al
+    // bootstrap ricostruisce le chiavi di prima: la memoria muscolare di chi usa il pannello
+    // tutti i giorni non ha motivo di azzerarsi per una riorganizzazione dei sorgenti.
+    const [sortKey, setSortKey] = useState(() => localStorage.getItem(storageKey("sortKey")) || "uploaded");
+    const [sortDir, setSortDir] = useState(() => localStorage.getItem(storageKey("sortDir")) || "desc");
+    /* I nomi per esteso già visti. Servono al percorso in alto: dentro `food/piatti-2024/`
+     * l'elenco delle cartelle non contiene più né l'una né l'altra — `folders` ha il primo livello
+     * e `subfolders` i FIGLI di dove sei — quindi senza memoria il percorso mostrerebbe gli slug,
+     * cioè proprio ciò che l'etichetta serve a non far vedere. */
+    const seenLabels = useRef({});
+    /* `fallback` serve solo al primo caricamento con la cartella ricordata: quella cartella può
+     * essere stata rinominata o cestinata da allora, e riaprirsi su un prefisso che non esiste
+     * più mostra una griglia vuota senza dire perché. In quel caso si torna alla radice. */
+    const load = useCallback(async (p, fallback = false) => {
+        setBusy(true);
+        setError(null);
+        try {
+            const [a, f] = await Promise.all([api.assets(p), api.folders()]);
+            if (fallback && p && !(f.folders ?? []).some((x) => p === x.prefix || p.startsWith(x.prefix))) {
+                setBusy(false);
+                return load("");
+            }
+            for (const x of [...(f.folders ?? []), ...(a.folders ?? [])]) {
+                if (x.label)
+                    seenLabels.current[x.prefix] = x.label;
+            }
+            if (p && a.label)
+                seenLabels.current[p] = a.label;
+            setFiles(a.files ?? []);
+            setSubfolders(a.folders ?? []);
+            setFolders(f.folders ?? []);
+            setPrefix(p);
+            setSelected(new Set());
+            setViewing(null);
+            setLoaded(true);
+            /* Scrive SOLO chi ricorda, cioè il modale di scelta. Scrivendo anche dalla vista «Media»
+             * il suo caricamento iniziale — che parte dalla radice — cancellerebbe la cartella
+             * ricordata: aprire i media una volta basterebbe a far ripartire il selettore da capo. */
+            if (remember) {
+                try {
+                    localStorage.setItem(storageKey(LAST_PREFIX), p);
+                }
+                catch { /* niente da fare */ }
+            }
+        }
+        catch (e) {
+            setError(e instanceof ApiError ? e.message : String(e));
+        }
+        finally {
+            setBusy(false);
+        }
+    }, [remember]);
+    /* Caricamento PIGRO come per la home: chi apre l'admin sulle pagine non paga l'elenco del
+     * bucket. `loaded` e non `files.length`, altrimenti una cartella vuota ritenterebbe all'infinito.
+     *
+     * Chi sceglie una foto riparte dalla cartella dell'ultima volta: mettendo insieme una gallery
+     * si torna venti volte nella stessa cartella, e ricominciare ogni volta dalla radice è venti
+     * navigazioni identiche. La vista «Media» invece riparte dalla radice: là si guarda la
+     * libreria, e il punto di partenza è l'insieme.
+     *
+     * `error` è nella guardia perché un caricamento FALLITO non imposta `loaded`: senza, l'effetto
+     * si ritroverebbe nelle stesse condizioni che l'hanno fatto partire e riproverebbe in un ciclo
+     * — una raffica di richieste al bucket proprio mentre qualcosa non funziona. Chi vuole
+     * riprovare lo chiede: il pulsante di ricarica azzera `error` e questo effetto riparte. */
+    useEffect(() => {
+        if (!active || loaded || busy || error)
+            return;
+        let start = "";
+        if (remember) {
+            try {
+                start = localStorage.getItem(storageKey(LAST_PREFIX)) || "";
+            }
+            catch {
+                start = "";
+            }
+        }
+        void load(start, true);
+    }, [active, loaded, busy, error, load, remember]);
+    useEffect(() => { localStorage.setItem(storageKey("sortKey"), sortKey); localStorage.setItem(storageKey("sortDir"), sortDir); }, [sortKey, sortDir]);
+    /* Chiudere o ricaricare mentre un'operazione è in corso la interrompe: il gruppo in volo non
+     * arriva mai. Ora ogni gruppo è definitivo, quindi si perde poco — ma vale comunque la pena
+     * chiedere, perché è esattamente il gesto che uno fa quando "non sta succedendo niente". */
+    useEffect(() => {
+        if (!progress)
+            return;
+        const warn = (e) => { e.preventDefault(); };
+        addEventListener("beforeunload", warn);
+        return () => removeEventListener("beforeunload", warn);
+    }, [progress]);
+    const shown = useMemo(() => {
+        const list = mode === "pick" ? files.filter((f) => (f.type ?? "").startsWith("image/")) : files.slice();
+        const dir = sortDir === "asc" ? 1 : -1;
+        return list.sort((a, b) => {
+            const x = a[sortKey] ?? "", y = b[sortKey] ?? "";
+            return (x < y ? -1 : x > y ? 1 : 0) * dir;
+        });
+    }, [files, sortKey, sortDir, mode]);
+    /* Aggiornamento FUNZIONALE, non `setSelected(new Set(selected))`: due click ravvicinati
+     * finiscono nello stesso batch di React e leggerebbero entrambi lo stesso stato vecchio,
+     * quindi il secondo cancellerebbe il primo. Con un umano che clicca piano non si vedrebbe
+     * quasi mai — motivo per cui è un bug peggiore, non migliore. */
+    const toggle = useCallback((key) => {
+        setSelected((prev) => {
+            const next = new Set(prev);
+            if (next.has(key))
+                next.delete(key);
+            else {
+                if (!multiple && mode === "pick")
+                    next.clear();
+                next.add(key);
+            }
+            return next;
+        });
+    }, [multiple, mode]);
+    /* «Seleziona tutto» prende anche le SOTTOCARTELLE mostrate, non solo le foto: sono lì, si
+     * vedono, e sarebbe strano che «tutto» ne escludesse una parte. Nel modale di scelta no —
+     * là si scelgono foto. */
+    const setAll = useCallback((on) => {
+        if (!on)
+            return setSelected(new Set());
+        const ids = mode === "manage" ? subfolders.map((f) => f.prefix) : [];
+        setSelected(new Set([...ids, ...shown.map((f) => f.key)]));
+    }, [shown, subfolders, mode]);
+    const upload = useCallback(async (list) => {
+        const arr = Array.from(list);
+        if (!arr.length)
+            return true;
+        setProgress({ done: 0, total: arr.length, verb: "Carico" });
+        const errs = [];
+        try {
+            await uploadQueue(prefix, arr, (done, total, _r, err) => {
+                setProgress({ done, total, verb: "Carico" });
+                if (err)
+                    errs.push(err);
+            });
+        }
+        finally {
+            setProgress(null);
+            // SEMPRE, anche se qualcosa è fallito: dopo un'operazione a metà l'elenco che si vede è
+            // una bugia, ed è peggio dell'errore.
+            await load(prefix);
+        }
+        // Dopo `load`, che azzera il messaggio: prima veniva scritto e subito cancellato.
+        if (errs.length)
+            setError(`Non caricati: ${errs.join("; ")}`);
+        return errs.length === 0;
+    }, [prefix, load]);
+    const labelOf = useCallback((p) => {
+        const f = folders.find((x) => x.prefix === p) ?? subfolders.find((x) => x.prefix === p);
+        return f?.label || seenLabels.current[p] || p.replace(/\/$/, "").split("/").pop() || "";
+    }, [folders, subfolders, prefix]);
+    /* Il nome si manda com'è stato scritto: lo slug della chiave lo calcola il server, e resta
+     * un dettaglio del bucket. Chi ha scritto «Hospitality & Interiors» continua a leggere
+     * «Hospitality & Interiors».
+     *
+     * DOVE si crea è un parametro, non lo stato della navigazione. Prima il pulsante nella colonna
+     * creava una cartella di primo livello o una sottocartella a seconda di dove ti trovavi: lo
+     * stesso pulsante, due effetti diversi, e nessun modo di saperlo prima di premerlo. Ora ce ne
+     * sono due, ognuno con il suo posto — la colonna crea al primo livello, quello sopra la
+     * griglia crea dentro la cartella aperta, a qualunque profondità. */
+    const newFolder = useCallback(async (parent) => {
+        const dove = parent ? ` dentro «${labelOf(parent)}»` : "";
+        const name = prompt(`Nome della cartella${dove}`);
+        if (!name || !name.trim())
+            return;
+        try {
+            await api.createFolder(parent, name.trim(), { label: name.trim() });
+            await load(prefix);
+        }
+        catch (e) {
+            setError(e instanceof ApiError ? e.message : String(e));
+        }
+    }, [prefix, load, labelOf]);
+    /* Nella selezione convivono file e cartelle, e si riconoscono da soli: la chiave di una
+     * cartella finisce con "/". Ogni operazione da qui in poi le separa in due liste. */
+    const filesIn = (ids) => ids.filter((id) => !id.endsWith("/"));
+    const foldersIn = (ids) => ids.filter((id) => id.endsWith("/"));
+    /** Le chiavi dei file dentro una cartella, a QUALUNQUE profondità. */
+    const keysUnder = async (p) => (await api.assets(p, { recursive: true })).files.map((f) => f.key);
+    /* Cancellazione: prima si CHIEDE dove sono usati quei file, e lo si dice. Cancellare una foto
+     * che è nella home senza avvisare è il modo classico per far comparire un buco in produzione
+     * senza che nessuno colleghi le due cose.
+     *
+     * POI SI PROCEDE A GRUPPI, ed è la parte che conta. Cestinare è get + put + delete per file:
+     * ottanta foto in una richiesta sola ci mettono decine di secondi, la richiesta muore per
+     * strada — o la interrompe chi ricarica la pagina non vedendo succedere niente — e restano
+     * spostate a metà. A gruppi di CHUNK ogni richiesta dura pochi secondi ed è DEFINITIVA: quel
+     * che è passato è passato, e ricaricare non disfa niente.
+     *
+     * I riferimenti nelle pagine si puliscono UNA volta sola, prima, con `refsOnly`: è quella la
+     * parte che costa un commit, e un commit per gruppo vorrebbe dire otto build per una
+     * cancellazione. */
+    const remove = useCallback(async (ids) => {
+        if (!ids.length)
+            return;
+        setBusy(true);
+        // L'errore va tenuto da parte: `load` in coda azzera il messaggio, quindi va rimesso DOPO,
+        // o l'operazione fallisce in silenzio e l'elenco aggiornato sembra dire che è andata bene.
+        let failure = null;
+        try {
+            const prefixes = foldersIn(ids);
+            const keys = filesIn(ids);
+            // Una cartella si cancella con TUTTO quello che contiene, a qualunque profondità: fermarsi
+            // al primo livello lascerebbe file orfani sotto un prefisso che non si vede più.
+            for (const p of prefixes)
+                keys.push(...(await keysUnder(p)));
+            const quante = [
+                prefixes.length
+                    ? (prefixes.length === 1 ? `la cartella «${labelOf(prefixes[0])}»` : `${prefixes.length} cartelle`)
+                    : "",
+                keys.length ? (keys.length === 1 ? "1 foto" : `${keys.length} foto`) : "",
+            ].filter(Boolean).join(" e ");
+            /* La scansione è parte della sicurezza dell'operazione, non un controllo decorativo. Se
+             * GitHub non è leggibile non si procede: il server applica la stessa regola prima di
+             * toccare R2, ma fermarsi qui evita una conferma che verrebbe subito rifiutata. */
+            const u = await api.usage({ keys, prefixes });
+            if (u.blockers?.length) {
+                throw new Error("Prima di eliminare queste foto devi sostituirle nel contenuto:\n"
+                    + u.blockers.map((b) => `• ${b.label}: ${b.reason}`).join("\n"));
+            }
+            /* LA RIGA IN PIÙ QUANDO LE FOTO SONO IN USO, e non è pignoleria.
+             *
+             * Le foto stanno nel bucket, che è uno solo: non esiste una versione "in bozza" di un
+             * file. Eliminarne una la toglie SUBITO dal sito pubblicato, mentre la ripulitura dei
+             * riferimenti nelle pagine resta sulla bozza finché non si pubblica — quindi per quel
+             * tempo le pagine online chiedono una foto che non c'è più.
+             *
+             * La finestra esisteva anche prima (durava la build, un paio di minuti); ora dura fino
+             * alla pubblicazione, cioè quanto decide chi sta lavorando. Non si aggiunge macchinario
+             * per chiuderla: si dice, e si dice SOLO quando è vero — un avviso che compare sempre
+             * smette di essere letto, e allora non avvisa più di niente. */
+            const msg = u.count
+                ? `Eliminare ${quante}?\n\nATTENZIONE: ${u.count} di queste foto sono usate in: ${u.pages.join(", ")}.\n`
+                    + `I riferimenti verranno rimossi da quelle sorgenti.\n\n`
+                    + `Le foto spariscono subito dal sito online; le pagine si sistemano quando pubblichi.`
+                : `Eliminare ${quante}?`;
+            if (!confirm(`${msg}\n\nLe foto vanno nel cestino e si possono recuperare.`))
+                return;
+            let refsToken;
+            if (keys.length) {
+                setProgress({ done: 0, total: keys.length, verb: "Cestino" });
+                const preflight = await api.remove({ keys }, { refsOnly: true });
+                if (!preflight.refsToken)
+                    throw new Error("Il server non ha confermato la verifica dei riferimenti.");
+                refsToken = preflight.refsToken;
+                let done = 0;
+                for (let i = 0; i < keys.length; i += CHUNK) {
+                    const group = keys.slice(i, i + CHUNK);
+                    const r = await api.remove({ keys: group }, { skipRefs: true, refsToken: preflight.refsToken });
+                    done += r.trashed ?? group.length;
+                    setProgress({ done, total: keys.length, verb: "Cestino" });
+                }
+                if (done < keys.length) {
+                    failure = `Cestinate ${done} foto su ${keys.length}: le altre sono ancora lì, riprova.`;
+                }
+            }
+            // La spazzata sui prefissi porta via i `.keep` — cioè le cartelle vuote rimaste.
+            if (prefixes.length) {
+                // Se sotto il prefisso comparisse nel frattempo un file non verificato, il server
+                // rifiuterebbe la richiesta: il token autorizza soltanto le chiavi del preflight.
+                await api.remove({ prefixes }, { skipRefs: true, ...(refsToken ? { refsToken } : {}) });
+            }
+        }
+        catch (e) {
+            failure = e instanceof ApiError ? e.message : String(e);
+        }
+        finally {
+            setProgress(null);
+            setBusy(false);
+            // SEMPRE, anche dopo un errore: l'elenco di prima è una bugia, perché una parte dei file
+            // può essere passata davvero.
+            await load(prefix);
+            if (failure)
+                setError(failure);
+        }
+    }, [prefix, load, labelOf]);
+    /* SPOSTARE UNA CARTELLA è spostare tutto ciò che contiene: in R2 la cartella non esiste, è un
+     * pezzo di chiave. Cambia quindi l'indirizzo pubblico di ogni foto dentro, ed è per questo che
+     * i riferimenti nelle pagine si riscrivono nello stesso giro — altrimenti le gallery che le
+     * usano si svuotano.
+     *
+     * Lo slug della destinazione lo calcola il SERVER, creando la cartella: client e server non
+     * possono avere due idee diverse di come si fa uno slug. Le sottocartelle si ricreano prima di
+     * spostare i file, dalla più vicina alla radice, perché la loro etichetta vive nel `.keep` e
+     * non seguirebbe i file da sola.
+     *
+     * Restituisce un messaggio d'errore, o null se è andata. */
+    const moveFolder = useCallback(async (from, destParent, newLabel) => {
+        const name = (newLabel ?? labelOf(from)).trim();
+        if (!name)
+            return null;
+        if (destParent === from || destParent.startsWith(from)) {
+            return "Una cartella non si può spostare dentro sé stessa.";
+        }
+        const created = await api.createFolder(destParent, name, { label: name });
+        const dest = created.prefix;
+        if (dest === from) {
+            // Stesso posto e stesso slug: è cambiato solo il nome per esteso.
+            await api.createFolder(destParent, name, { label: name, relabel: true });
+            return null;
+        }
+        if (created.exists)
+            return `C'è già una cartella «${name}» in quella posizione.`;
+        const inside = await api.assets(from, { recursive: true });
+        for (const sub of [...inside.folders].sort((a, b) => a.prefix.length - b.prefix.length)) {
+            const rel = sub.prefix.slice(from.length); // "b/" oppure "b/c/"
+            const subName = rel.replace(/\/$/, "").split("/").pop();
+            await api.createFolder(dest + rel.replace(/[^/]+\/$/, ""), sub.label || subName, {
+                label: sub.label || subName,
+            });
+        }
+        // I file si spostano raggruppati per sottocartella: `move` accetta UNA destinazione, e chi
+        // sta in "b/" deve ritrovarsi in "<nuova>/b/", non tutto appiattito nella radice.
+        const byDir = {};
+        for (const f of inside.files) {
+            const rel = f.key.slice(from.length);
+            const cut = rel.lastIndexOf("/");
+            const dir = cut >= 0 ? rel.slice(0, cut + 1) : "";
+            (byDir[dir] ||= []).push(f.key);
+        }
+        const total = inside.files.length;
+        const verb = newLabel ? "Rinomino" : "Sposto";
+        let done = 0;
+        setProgress({ done, total, verb });
+        const urlMap = {};
+        const copyFailures = [];
+        for (const [dir, keys] of Object.entries(byDir)) {
+            for (let i = 0; i < keys.length; i += CHUNK) {
+                const group = keys.slice(i, i + CHUNK);
+                const r = await api.move(group, dest + dir, { skipRefs: true });
+                Object.assign(urlMap, r.urlMap ?? {});
+                copyFailures.push(...(r.failed ?? []));
+                done += r.moved ?? 0;
+                setProgress({ done, total, verb });
+            }
+        }
+        const applied = Object.keys(urlMap).length ? await api.moveApplyRefs(urlMap) : null;
+        const cleanupFailures = applied?.failed ?? [];
+        if (copyFailures.length || cleanupFailures.length) {
+            return [
+                copyFailures.length ? `${copyFailures.length} file non sono stati copiati` : "",
+                cleanupFailures.length ? `${cleanupFailures.length} originali sono rimasti come duplicati` : "",
+            ].filter(Boolean).join("; ") + ". La cartella originale è stata conservata.";
+        }
+        // I `.keep` della vecchia cartella, che altrimenti la lascerebbero nell'elenco, vuota.
+        await api.remove({ prefixes: [from] }, { skipRefs: true });
+        return null;
+    }, [labelOf]);
+    /* Spostare NON è solo copiare l'oggetto: la Function sposta il file dentro R2 e nello stesso
+     * giro riscrive i riferimenti /media/<vecchia> nelle pagine. Vale per i file come per le
+     * cartelle, che nella selezione stanno insieme. */
+    const move = useCallback(async (ids, dest) => {
+        if (!ids.length)
+            return;
+        const keys = filesIn(ids);
+        const prefixes = foldersIn(ids);
+        setBusy(true);
+        let failure = null;
+        try {
+            for (const p of prefixes) {
+                const err = await moveFolder(p, dest);
+                if (err)
+                    failure = err;
+            }
+            if (keys.length) {
+                // La radice non è una destinazione valida per un FILE: la Function la rifiuta, e senza
+                // questo controllo il rifiuto arriverebbe come un errore criptico a metà operazione.
+                if (!dest) {
+                    failure = "Le foto devono stare in una cartella.";
+                }
+                else {
+                    setProgress({ done: 0, total: keys.length, verb: "Sposto" });
+                    // A gruppi per la stessa ragione della cancellazione. Ogni gruppo COPIA conservando
+                    // gli originali e restituisce la mappa scelta dal server; la chiamata finale aggiorna
+                    // i riferimenti in un commit solo e soltanto dopo elimina gli originali.
+                    let done = 0;
+                    const urlMap = {};
+                    const copyFailures = [];
+                    for (let i = 0; i < keys.length; i += CHUNK) {
+                        const group = keys.slice(i, i + CHUNK);
+                        const r = await api.move(group, dest, { skipRefs: true });
+                        Object.assign(urlMap, r.urlMap ?? {});
+                        copyFailures.push(...(r.failed ?? []));
+                        done += r.moved ?? 0;
+                        setProgress({ done, total: keys.length, verb: "Sposto" });
+                    }
+                    const applied = Object.keys(urlMap).length ? await api.moveApplyRefs(urlMap) : null;
+                    const cleanupFailures = applied?.failed ?? [];
+                    if (copyFailures.length || cleanupFailures.length) {
+                        failure = [
+                            copyFailures.length ? `${copyFailures.length} file non spostati` : "",
+                            cleanupFailures.length ? `${cleanupFailures.length} originali rimasti come duplicati` : "",
+                        ].filter(Boolean).join("; ") + ".";
+                    }
+                }
+            }
+        }
+        catch (e) {
+            failure = e instanceof ApiError ? e.message : String(e);
+        }
+        finally {
+            setProgress(null);
+            setBusy(false);
+            await load(prefix);
+            if (failure)
+                setError(failure);
+        }
+    }, [prefix, load, moveFolder]);
+    /* Rinominare è spostare nello stesso posto con un nome nuovo: stessa strada, stesse cautele.
+     * Se il nome nuovo dà lo stesso slug (è cambiata solo una maiuscola, o un «&»), non si sposta
+     * niente e si riscrive la sola etichetta. */
+    const renameFolder = useCallback(async (from, label) => {
+        if (!label.trim())
+            return;
+        setBusy(true);
+        let failure = null;
+        try {
+            failure = await moveFolder(from, from.replace(/[^/]+\/$/, ""), label);
+        }
+        catch (e) {
+            failure = e instanceof ApiError ? e.message : String(e);
+        }
+        finally {
+            setProgress(null);
+            setBusy(false);
+            await load(prefix);
+            if (failure)
+                setError(failure);
+        }
+    }, [prefix, load, moveFolder]);
+    /** Cestina una cartella con tutto quello che contiene. È `remove` con una lista di uno. */
+    const removeFolder = useCallback((target) => remove([target]), [remove]);
+    const step = useCallback((delta) => {
+        setViewing((i) => {
+            if (i === null)
+                return null;
+            const n = i + delta;
+            return n < 0 || n >= shown.length ? i : n;
+        });
+    }, [shown.length]);
+    return {
+        mode, multiple, prefix, folders, subfolders, shown, selected, busy, error, progress,
+        sortKey, sortDir, uploadOpen, viewing,
+        go: (p) => void load(p),
+        reload: () => void load(prefix),
+        toggle, setAll,
+        setSort: setSortKey,
+        flipDir: () => setSortDir((d) => (d === "asc" ? "desc" : "asc")),
+        upload,
+        setUploadOpen,
+        view: setViewing,
+        step,
+        move, remove, newFolder, renameFolder, removeFolder, labelOf,
+        clearError: () => setError(null),
+    };
+}

package/dist/form/prose/ProseBar.d.ts

@@ -0,0 +1,21 @@
+/** Dove sta la selezione sullo schermo, in coordinate del viewport. */
+export interface ProseSpot {
+    x: number;
+    top: number;
+    bottom: number;
+}
+export interface ProseBarProps {
+    spot: ProseSpot;
+    /** Com'è già formattato il testo selezionato: i bottoni lo mostrano accesi. */
+    bold: boolean;
+    italic: boolean;
+    /** L'indirizzo del link su cui è appoggiata la selezione, se ce n'è uno. */
+    href: string | null;
+    onBold: () => void;
+    onItalic: () => void;
+    onLink: (href: string) => void;
+    onUnlink: () => void;
+    /** Aperto il dialogo, il campo perde il fuoco: chi lo possiede deve tenersi la selezione. */
+    onHold: (holding: boolean) => void;
+}
+export declare function ProseBar({ spot, bold, italic, href, onBold, onItalic, onLink, onUnlink, onHold }: ProseBarProps): import("react").JSX.Element;

package/dist/form/prose/ProseBar.js

@@ -0,0 +1,111 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/* La barra che compare sopra il testo selezionato, e il dialogo del link.
+ *
+ * ── Dove sta ───────────────────────────────────────────────────────────────────────────────
+ * Appartiene alla PAGINA, non al campo: è disegnata in un portal su `document.body` e
+ * posizionata con `position: fixed`. Dentro il campo sarebbe prigioniera del suo `overflow` —
+ * su una selezione in cima al testo verrebbe tagliata a metà, o peggio, coprirebbe le parole che
+ * chi scrive sta guardando. Fuori, può sporgere dal riquadro e restare intera.
+ *
+ * Chi la posiziona è `ProseArea`, che sa dov'è la selezione; qui si riceve solo il punto e da che
+ * parte stare. La regola è una sola e vale sempre: **la barra non copre mai il testo
+ * selezionato** — sopra se c'è spazio, sotto altrimenti.
+ *
+ * ── Perché i bottoni non rubano il fuoco ──────────────────────────────────────────────────
+ * Ogni comando fa `preventDefault` sul `mousedown`. Senza, premere B toglierebbe il fuoco alla
+ * textarea, la selezione svanirebbe, e il comando si troverebbe niente da formattare. È il
+ * difetto classico di questo tipo di barra, e si paga una riga per non averlo.
+ *
+ * ── Il dialogo del link ────────────────────────────────────────────────────────────────────
+ * Tre schede, come in qualunque CMS che il cliente possa aver già usato: una pagina del sito, un
+ * indirizzo web, un'email. Le pagine arrivano dal contesto (`ProsePages`) e non da una prop,
+ * perché questo componente vive dentro widget annidati anche di tre livelli.
+ *
+ * NON c'è «apri in una nuova finestra»: il testo si salva come markdown, e il markdown non ha
+ * un modo di dirlo. Prometterlo con una casella che poi non produce niente è peggio che non
+ * offrirlo — se un giorno serve, si fa con un render hook sui link nel sito, non qui.
+ */
+import { useContext, useEffect, useMemo, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import { isSafeHref } from "../../prose.js";
+import { ProsePages } from "./pages.js";
+/* Quanto è alta la barra, per decidere se ci sta sopra la selezione. Misurarla davvero
+   vorrebbe dire disegnarla, leggerla e spostarla — un salto visibile a ogni selezione. È
+   un'altezza fissa dichiarata nel CSS (`--ak-prose-bar-h`), quindi qui si può sapere. */
+const BAR_H = 40;
+const GAP = 10;
+export function ProseBar({ spot, bold, italic, href, onBold, onItalic, onLink, onUnlink, onHold }) {
+    const [dialog, setDialog] = useState(false);
+    const above = spot.top - GAP - BAR_H >= 8;
+    const close = () => { setDialog(false); onHold(false); };
+    /* Il dialogo si apre AL POSTO della barra: due superfici sovrapposte sullo stesso testo si
+       contendono lo sguardo, e quella che conta in quel momento è una sola. */
+    if (dialog) {
+        return (_jsx(LinkDialog, { href: href, onClose: close, onSave: (value) => { setDialog(false); onLink(value); }, onUnlink: () => { setDialog(false); onUnlink(); } }));
+    }
+    const hold = (event) => event.preventDefault();
+    return createPortal(_jsxs("div", { className: "ak-prose-bar", role: "toolbar", "aria-label": "Formattazione del testo", style: {
+            left: `${spot.x}px`,
+            top: `${above ? spot.top - GAP : spot.bottom + GAP}px`,
+            transform: `translate(-50%, ${above ? "-100%" : "0"})`,
+        }, children: [_jsx("button", { type: "button", className: "ak-prose-btn is-bold" + (bold ? " is-on" : ""), "aria-pressed": bold, onMouseDown: hold, onClick: onBold, title: "Grassetto", children: "B" }), _jsx("button", { type: "button", className: "ak-prose-btn is-italic" + (italic ? " is-on" : ""), "aria-pressed": italic, onMouseDown: hold, onClick: onItalic, title: "Corsivo", children: "I" }), _jsx("span", { className: "ak-prose-sep", "aria-hidden": "true" }), _jsxs("button", { type: "button", className: "ak-prose-btn is-link" + (href ? " is-on" : ""), onMouseDown: hold, onClick: () => { onHold(true); setDialog(true); }, title: href ? "Modifica il collegamento" : "Aggiungi un collegamento", children: [_jsx(LinkIcon, {}), " Link"] })] }), document.body);
+}
+function LinkIcon() {
+    return (_jsxs("svg", { viewBox: "0 0 16 16", width: "14", height: "14", "aria-hidden": "true", fill: "none", stroke: "currentColor", strokeWidth: "1.5", strokeLinecap: "round", children: [_jsx("path", { d: "M6.8 9.2a2.6 2.6 0 0 0 3.7 0l2-2a2.6 2.6 0 0 0-3.7-3.7l-1 1" }), _jsx("path", { d: "M9.2 6.8a2.6 2.6 0 0 0-3.7 0l-2 2a2.6 2.6 0 0 0 3.7 3.7l1-1" })] }));
+}
+function tabOf(href) {
+    if (!href)
+        return "page";
+    if (href.startsWith("mailto:"))
+        return "mail";
+    if (/^https?:/i.test(href))
+        return "web";
+    return "page";
+}
+function LinkDialog({ href, onClose, onSave, onUnlink }) {
+    const pages = useContext(ProsePages);
+    const [tab, setTab] = useState(() => tabOf(href));
+    const [page, setPage] = useState(() => (tabOf(href) === "page" ? href ?? "" : ""));
+    const [web, setWeb] = useState(() => (tabOf(href) === "web" ? href ?? "" : ""));
+    const [mail, setMail] = useState(() => (tabOf(href) === "mail" ? (href ?? "").replace(/^mailto:/i, "") : ""));
+    const first = useRef(null);
+    useEffect(() => {
+        first.current?.focus();
+        const onKey = (event) => { if (event.key === "Escape")
+            onClose(); };
+        addEventListener("keydown", onKey);
+        return () => removeEventListener("keydown", onKey);
+    }, [onClose]);
+    /* Cosa si sta per scrivere, calcolato una volta: lo usano sia il bottone (per sapere se può
+       essere premuto) sia il salvataggio. Due espressioni separate sarebbero due occasioni di
+       dire cose diverse — un bottone attivo che poi non fa niente. */
+    const value = useMemo(() => {
+        if (tab === "page")
+            return page.trim();
+        if (tab === "mail") {
+            const address = mail.trim();
+            return address ? `mailto:${address}` : "";
+        }
+        const url = web.trim();
+        // Un indirizzo battuto senza schema è un indirizzo web, non un percorso interno: chi scrive
+        // `esempio.it` intende quel sito, e senza questo otterrebbe un link rotto.
+        return url && !/^[a-z]+:/i.test(url) && !url.startsWith("/") && !url.startsWith("#")
+            ? `https://${url}`
+            : url;
+    }, [tab, page, web, mail]);
+    const valid = isSafeHref(value);
+    /* Un link interno che non corrisponde a nessuna pagina dell'elenco — una pagina tolta dal
+       menu, messa offline, o un'ancora scritta a mano — resta come voce sua. Senza, il menu
+       ripiegherebbe sulla riga vuota e «Aggiorna» cancellerebbe in silenzio un indirizzo che
+       nessuno voleva toccare. */
+    const options = useMemo(() => {
+        const start = tabOf(href) === "page" ? (href ?? "") : "";
+        return start && !pages.some((item) => item.href === start)
+            ? [{ href: start, label: start }, ...pages]
+            : pages;
+    }, [pages, href]);
+    return createPortal(_jsx("div", { className: "ak-prose-modal", role: "presentation", onMouseDown: (e) => { if (e.target === e.currentTarget)
+            onClose(); }, children: _jsxs("div", { className: "ak-prose-card", role: "dialog", "aria-modal": "true", "aria-labelledby": "ak-link-title", children: [_jsxs("header", { children: [_jsx("h2", { id: "ak-link-title", children: "Collegamento" }), _jsx("button", { type: "button", onClick: onClose, "aria-label": "Chiudi", children: "\u00D7" })] }), _jsx("div", { className: "ak-prose-tabs", role: "tablist", children: [["page", "Pagina"], ["web", "Sito web"], ["mail", "Email"]].map(([id, label]) => (_jsx("button", { type: "button", role: "tab", "aria-selected": tab === id, className: "ak-prose-tab" + (tab === id ? " is-on" : ""), onClick: () => setTab(id), children: label }, id))) }), _jsxs("div", { className: "ak-prose-body", children: [tab === "page" && (options.length ? (_jsxs("select", { ref: first, className: "ak-input", value: page, onChange: (event) => setPage(event.target.value), children: [_jsx("option", { value: "", children: "Scegli una pagina\u2026" }), options.map((item) => (_jsx("option", { value: item.href, children: item.label }, item.href)))] })) : (_jsx("p", { className: "ak-hint", children: "Nessuna pagina a cui collegarsi." }))), tab === "web" && (_jsx("input", { ref: first, className: "ak-input", placeholder: "https://www.esempio.com", value: web, onChange: (event) => setWeb(event.target.value), onKeyDown: (event) => { if (event.key === "Enter" && valid)
+                                onSave(value); } })), tab === "mail" && (_jsx("input", { ref: first, className: "ak-input", type: "email", placeholder: "nome@esempio.com", value: mail, onChange: (event) => setMail(event.target.value), onKeyDown: (event) => { if (event.key === "Enter" && valid)
+                                onSave(value); } }))] }), _jsxs("footer", { children: [href ? (_jsx("button", { type: "button", className: "ak-prose-unlink", onClick: onUnlink, children: "Togli il collegamento" })) : _jsx("span", {}), _jsxs("div", { children: [_jsx("button", { type: "button", className: "ak-btn", onClick: onClose, children: "Annulla" }), _jsx("button", { type: "button", className: "ak-btn ak-btn-primary", disabled: !valid, onClick: () => onSave(value), children: href ? "Aggiorna" : "Crea" })] })] })] }) }), document.body);
+}

package/dist/form/prose/ProseField.d.ts

@@ -0,0 +1,11 @@
+export interface ProseFieldProps {
+    /** Il testo in markdown: è questo che si salva. */
+    value: string;
+    onChange: (next: string) => void;
+    className?: string;
+    /** Altezza minima, in righe. Il campo cresce col testo: non scorre mai dentro sé stesso. */
+    rows?: number;
+    placeholder?: string;
+    maxLength?: number;
+}
+export declare function ProseField({ value, onChange, className, rows, placeholder, maxLength }: ProseFieldProps): import("react").JSX.Element;