@orthacms/media-admin 0.0.0-reserve.0

package/dist/lib/hooks/useMediaLibrary/index.d.ts

@@ -0,0 +1,83 @@
+import { KIND_FILTER_ALL, type MediaKind, type MediaSort } from '../../constants';
+import type { MediaFolder } from '../../types/mediaFolder';
+/** The selected kind filter — a {@link MediaKind} or the "all" sentinel. */
+export type KindFilter = MediaKind | typeof KIND_FILTER_ALL;
+/** Per-surface tuning for {@link useMediaLibrary}. */
+export type MediaLibraryOptions = {
+    /**
+     * Assets per request. The library page lets the user choose; a surface with
+     * no pager of its own (the picker dialog) passes a large one and browses by
+     * searching instead.
+     */
+    pageSize?: number;
+};
+/**
+ * The Media Library's data layer and every action the UI can take. Folders and
+ * the open folder's assets are fetched from `@orthacms/media-server` via the
+ * gateway (TanStack Query); mutations post to the API and invalidate the cache.
+ * View/search/sort/filter/selection/navigation stay local UI state. The returned
+ * shape mirrors the former mock store exactly, so no component changed.
+ *
+ * @param enabled - gates the reads (false until the caller confirms `media:read`).
+ */
+export declare function useMediaLibrary(enabled?: boolean, { pageSize: initialPageSize }?: MediaLibraryOptions): {
+    folders: MediaFolder[];
+    assets: import("../../types/mediaAsset").MediaAsset[];
+    currentFolderId: string;
+    currentFolder: MediaFolder | null;
+    breadcrumbs: MediaFolder[];
+    childFolders: MediaFolder[];
+    visibleAssets: import("../../types/mediaAsset").MediaAsset[];
+    folderCounts: Map<string, number>;
+    total: number;
+    page: number;
+    pageCount: number;
+    pageSize: number;
+    setPage: (next: number) => void;
+    setPageSize: (next: number) => void;
+    isLoading: boolean;
+    /**
+     * True while the grid on screen is not yet the answer to the controls
+     * as they now read — the debounce window, then the request.
+     *
+     * `isFetching` alone is a poor cue for a search box: it only goes true
+     * *after* the debounce commits, so for the first 300ms of typing
+     * nothing visible happens at all and the old results sit there looking
+     * like the new ones. Or-ing in the un-committed keystrokes is what
+     * makes the grid say "not this, yet" from the first letter.
+     */
+    isRefreshing: boolean;
+    isError: boolean;
+    reload: () => void;
+    selectedIds: Set<string>;
+    selectedAssets: import("../../types/mediaAsset").MediaAsset[];
+    toggleSelect: (id: string) => void;
+    clearSelection: () => void;
+    detailAsset: import("../../types/mediaAsset").MediaAsset | null;
+    openDetail: (id: string) => void;
+    closeDetail: () => void;
+    search: string;
+    setSearch: (next: string) => void;
+    sort: MediaSort;
+    setSort: (next: MediaSort) => void;
+    kindFilter: KindFilter;
+    setKindFilter: (next: KindFilter) => void;
+    navigateTo: (folderId: string) => void;
+    createFolder: (name: string, parentId?: string) => Promise<boolean>;
+    renameFolder: (id: string, name: string) => Promise<boolean>;
+    renameAsset: (id: string, name: string) => Promise<boolean>;
+    setAssetAlt: (id: string, alt: string) => Promise<boolean>;
+    deleteAssets: (ids: string[]) => Promise<boolean>;
+    deleteFolder: (id: string) => Promise<boolean>;
+    duplicateAssets: (ids: string[]) => Promise<boolean>;
+    moveAssets: (ids: string[], folderId: string) => Promise<boolean>;
+    uploadFiles: (uploads: import("../../infrastructure/mediaGateway").StagedUpload[]) => void;
+    uploadItems: import("../../types/upload").UploadItem[];
+    uploadSummary: import("../../types/upload").UploadSummary;
+    retryUpload: (id: string) => void;
+    cancelUpload: (id: string) => void;
+    dismissUploads: () => void;
+};
+/** The full store + actions returned by {@link useMediaLibrary}. */
+export type MediaLibraryStore = ReturnType<typeof useMediaLibrary>;
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/hooks/useMediaLibrary/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/hooks/useMediaLibrary/index.ts"],"names":[],"mappings":"AAWA,OAAO,EAEH,eAAe,EAIf,KAAK,SAAS,EACd,KAAK,SAAS,EACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAM3D,4EAA4E;AAC5E,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,OAAO,eAAe,CAAC;AAE5D,sDAAsD;AACtD,MAAM,MAAM,mBAAmB,GAAG;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AA0BF;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC3B,OAAO,UAAO,EACd,EACI,QAAQ,EAAE,eAA0C,EACvD,GAAE,mBAAwB;;;;;;;;;;;;;oBA8JhB,MAAM;wBASN,MAAM;;IA6Lb;;;;;;;;;OASG;;;;;;uBAvI+B,MAAM;;;qBASR,MAAM;;;sBA1D/B,MAAM;;oBAiBN,SAAS;;0BATT,UAAU;2BAmBN,MAAM;yBAiFV,MAAM,aAAY,MAAM;uBAK1B,MAAM,QAAQ,MAAM;sBASpB,MAAM,QAAQ,MAAM;sBAKpB,MAAM,OAAO,MAAM;wBAclB,MAAM,EAAE;uBAvBT,MAAM;2BAmBL,MAAM,EAAE;sBALR,MAAM,EAAE,YAAY,MAAM;;;;;;;EA4FvC;AAED,oEAAoE;AACpE,MAAM,MAAM,iBAAiB,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC"}

package/dist/lib/hooks/useMediaLibrary/index.js

@@ -0,0 +1,341 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { defineMessages, useIntl } from 'react-intl';
+import { keepPreviousData, useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { toast } from '@orthacms/design-system';
+import { useDebouncedValue } from '@orthacms/utils-admin';
+import { useCurrentWorkspace } from '@orthacms/workspaces-admin';
+import { DEFAULT_ASSETS_PAGE_SIZE, KIND_FILTER_ALL, MEDIA_SORT, ROOT_FOLDER_ID, SEARCH_DEBOUNCE_MS } from '../../constants';
+import { mediaKeys } from '../../infrastructure/mediaKeys';
+import { httpMediaGateway } from '../../infrastructure/httpMediaGateway';
+import { apiMessage } from '../../infrastructure/apiMessage';
+import { useUploadQueue } from '../useUploadQueue';
+/**
+ * Resolves a mutation to whether it **succeeded**, so a caller can hold its
+ * confirmation until the server has agreed.
+ *
+ * Every action below returns this. Firing a success toast at dispatch time is
+ * what produced "Renamed to “a/b.txt”" beside "Request failed with status code
+ * 400" on the same screen: the rejection is already handled by `onError`, so
+ * the failure branch here only has to swallow it.
+ */
+function settle(promise) {
+    return promise.then(() => true, () => false);
+}
+/** Intl descriptor for a failed media mutation. */
+const messages = defineMessages({
+    error: {
+        id: 'media.error.mutation',
+        defaultMessage: 'Something went wrong. Please try again.'
+    }
+});
+/**
+ * The Media Library's data layer and every action the UI can take. Folders and
+ * the open folder's assets are fetched from `@orthacms/media-server` via the
+ * gateway (TanStack Query); mutations post to the API and invalidate the cache.
+ * View/search/sort/filter/selection/navigation stay local UI state. The returned
+ * shape mirrors the former mock store exactly, so no component changed.
+ *
+ * @param enabled - gates the reads (false until the caller confirms `media:read`).
+ */
+export function useMediaLibrary(enabled = true, { pageSize: initialPageSize = DEFAULT_ASSETS_PAGE_SIZE } = {}) {
+    const intl = useIntl();
+    const workspaceId = useCurrentWorkspace().id;
+    const queryClient = useQueryClient();
+    const [currentFolderId, setCurrentFolderId] = useState(ROOT_FOLDER_ID);
+    const [selectedIds, setSelectedIds] = useState(() => new Set());
+    const [search, setSearchState] = useState('');
+    const [sort, setSortState] = useState(MEDIA_SORT.Newest);
+    const [kindFilter, setKindFilterState] = useState(KIND_FILTER_ALL);
+    const [detailAssetId, setDetailAssetId] = useState(null);
+    const [page, setPageState] = useState(1);
+    const [pageSize, setPageSizeState] = useState(initialPageSize);
+    // The box updates on every keystroke; the request waits for a pause. Search
+    // is a round trip now, so without this every letter typed is a query — and
+    // the results would flicker through the prefixes on the way to the word.
+    const debouncedSearch = useDebouncedValue(search, SEARCH_DEBOUNCE_MS);
+    const foldersQuery = useQuery({
+        queryKey: mediaKeys.folders(workspaceId),
+        queryFn: () => httpMediaGateway.listFolders(),
+        enabled
+    });
+    // Everything the server filters, orders and pages by, in one object — used
+    // as both the request and the cache key, so the two cannot disagree.
+    const listParams = useMemo(() => ({
+        search: debouncedSearch.trim(),
+        kind: kindFilter,
+        sort,
+        page,
+        pageSize
+    }), [debouncedSearch, kindFilter, sort, page, pageSize]);
+    const assetsQuery = useQuery({
+        queryKey: mediaKeys.assets(workspaceId, currentFolderId, listParams),
+        queryFn: () => httpMediaGateway.listAssets({
+            folderId: currentFolderId,
+            ...listParams
+        }),
+        // Paging without this blanks the grid between pages, which on a fast
+        // connection reads as a flicker and on a slow one as a broken folder.
+        placeholderData: keepPreviousData,
+        enabled
+    });
+    const folders = useMemo(() => foldersQuery.data?.folders ?? [], [foldersQuery.data]);
+    /** The assets on the open page — already searched, filtered and sorted. */
+    const assets = useMemo(() => assetsQuery.data?.items ?? [], [assetsQuery.data]);
+    /** How many assets match across the whole folder, not just this page. */
+    const total = assetsQuery.data?.total ?? 0;
+    const pageCount = Math.max(1, Math.ceil(total / pageSize));
+    const folderCounts = useMemo(() => foldersQuery.data?.folderCounts ?? new Map(), [foldersQuery.data]);
+    /** Refetch folders + the visible assets after any mutation. */
+    const invalidate = useCallback(() => {
+        queryClient.invalidateQueries({ queryKey: mediaKeys.all(workspaceId) });
+    }, [queryClient, workspaceId]);
+    /**
+     * Surfaces a mutation failure and resyncs from the server. The API's own
+     * sentence wins over our generic copy — `apiMessage` reads it off the
+     * response body, because `ApiError.message` is only the transport's
+     * "Request failed with status code 400".
+     */
+    const onError = useCallback((error) => {
+        toast.error(apiMessage(error) ?? intl.formatMessage(messages.error));
+        invalidate();
+    }, [intl, invalidate]);
+    /** The open folder record, or `null` at the synthetic root. */
+    const currentFolder = useMemo(() => folders.find((f) => f.id === currentFolderId) ?? null, [folders, currentFolderId]);
+    /** Ancestor chain (root → current), used by the breadcrumbs. */
+    const breadcrumbs = useMemo(() => {
+        const chain = [];
+        let cursor = currentFolder;
+        while (cursor) {
+            chain.unshift(cursor);
+            const parentId = cursor.parentId;
+            cursor =
+                parentId === ROOT_FOLDER_ID
+                    ? null
+                    : (folders.find((f) => f.id === parentId) ?? null);
+        }
+        return chain;
+    }, [currentFolder, folders]);
+    /** Folders directly inside the open folder. */
+    const childFolders = useMemo(() => folders
+        .filter((f) => f.parentId === currentFolderId)
+        .sort((a, b) => a.name.localeCompare(b.name)), [folders, currentFolderId]);
+    /**
+     * The assets to draw. The server has already searched, filtered, sorted and
+     * paged them, so this is the page as it came back.
+     *
+     * It used to be a `filter` + `sort` over one fixed page of 100, which is
+     * what made "oldest first" return the newest hundred in ascending order and
+     * let a search miss a file that plainly existed. Neither is fixable in the
+     * browser: the answer depends on rows the browser was never sent.
+     */
+    const visibleAssets = assets;
+    /** The asset backing the detail drawer, if open. */
+    const detailAsset = useMemo(() => assets.find((a) => a.id === detailAssetId) ?? null, [assets, detailAssetId]);
+    /** Currently selected assets (within the open folder). */
+    const selectedAssets = useMemo(() => assets.filter((a) => selectedIds.has(a.id)), [assets, selectedIds]);
+    const clearSelection = useCallback(() => setSelectedIds(new Set()), []);
+    /**
+     * Moves to another page, and drops the selection with it.
+     *
+     * A selection that outlived the page it was made on would be invisible and
+     * still armed: the bar counts only what is on screen (`selectedAssets` is
+     * derived from the loaded page), so ids left behind on page 1 would vanish
+     * from the count on page 2 and silently return later — and Delete would
+     * take files the user could not see. Every control that changes *which*
+     * assets are listed clears it, for the same reason.
+     */
+    const setPage = useCallback((next) => {
+        setPageState(next);
+        clearSelection();
+    }, [clearSelection]);
+    /** Re-pages the listing from the top; a new size makes old page numbers meaningless. */
+    const setPageSize = useCallback((next) => {
+        setPageSizeState(next);
+        setPageState(1);
+        clearSelection();
+    }, [clearSelection]);
+    /**
+     * Narrowing the list invalidates the page you were on — page 4 of an
+     * unfiltered folder is usually past the end of the filtered one, and the
+     * user would land on an empty grid having just typed a search that matches.
+     */
+    const setSearch = useCallback((next) => {
+        setSearchState(next);
+        setPageState(1);
+        clearSelection();
+    }, [clearSelection]);
+    const setKindFilter = useCallback((next) => {
+        setKindFilterState(next);
+        setPageState(1);
+        clearSelection();
+    }, [clearSelection]);
+    /** Re-orders the whole result set, so page 2 is a different two dozen assets. */
+    const setSort = useCallback((next) => {
+        setSortState(next);
+        setPageState(1);
+        clearSelection();
+    }, [clearSelection]);
+    /** Navigate into a folder (or root), back to page 1, dropping the selection. */
+    const navigateTo = useCallback((folderId) => {
+        setCurrentFolderId(folderId);
+        setPageState(1);
+        clearSelection();
+    }, [clearSelection]);
+    /**
+     * Pulls the page back into range when the result set shrinks under it.
+     *
+     * Deleting the last three assets on page 5, or a search narrowing to two
+     * pages, otherwise leaves the pager on a page the server answers with an
+     * empty `items` — a folder that reads as empty while its own header says it
+     * holds ninety files. Guarded on `isFetching` so it settles on the response
+     * rather than on the stale `keepPreviousData` total mid-flight.
+     */
+    useEffect(() => {
+        if (assetsQuery.isFetching)
+            return;
+        if (page > pageCount)
+            setPageState(pageCount);
+    }, [page, pageCount, assetsQuery.isFetching]);
+    const toggleSelect = useCallback((id) => {
+        setSelectedIds((prev) => {
+            const next = new Set(prev);
+            if (next.has(id))
+                next.delete(id);
+            else
+                next.add(id);
+            return next;
+        });
+    }, []);
+    const openDetail = useCallback((id) => setDetailAssetId(id), []);
+    const closeDetail = useCallback(() => setDetailAssetId(null), []);
+    // --- Mutations (post to the API, then invalidate the cache) ---------------
+    const createFolderM = useMutation({
+        mutationFn: httpMediaGateway.createFolder,
+        onSuccess: invalidate,
+        onError
+    });
+    const renameFolderM = useMutation({
+        mutationFn: httpMediaGateway.renameFolder,
+        onSuccess: invalidate,
+        onError
+    });
+    const deleteFolderM = useMutation({
+        mutationFn: httpMediaGateway.deleteFolder,
+        onSuccess: invalidate,
+        onError
+    });
+    const renameAssetM = useMutation({
+        mutationFn: httpMediaGateway.renameAsset,
+        onSuccess: invalidate,
+        onError
+    });
+    const moveAssetsM = useMutation({
+        mutationFn: httpMediaGateway.moveAssets,
+        onSuccess: invalidate,
+        onError
+    });
+    const duplicateAssetsM = useMutation({
+        mutationFn: httpMediaGateway.duplicateAssets,
+        onSuccess: invalidate,
+        onError
+    });
+    const deleteAssetsM = useMutation({
+        mutationFn: httpMediaGateway.deleteAssets,
+        onSuccess: invalidate,
+        onError
+    });
+    const updateAssetM = useMutation({
+        mutationFn: httpMediaGateway.updateAsset,
+        onSuccess: invalidate,
+        onError
+    });
+    // Uploads don't go through `useMutation`: the banner needs per-file progress
+    // and independent per-file failure, which a single mutation can't express.
+    const uploads = useUploadQueue(currentFolderId, invalidate);
+    const createFolder = useCallback((name, parentId = currentFolderId) => settle(createFolderM.mutateAsync({ name, parentId })), [createFolderM, currentFolderId]);
+    const renameFolder = useCallback((id, name) => settle(renameFolderM.mutateAsync({ id, name })), [renameFolderM]);
+    const deleteFolder = useCallback((id) => settle(deleteFolderM.mutateAsync(id)), [deleteFolderM]);
+    const renameAsset = useCallback((id, name) => settle(renameAssetM.mutateAsync({ id, name })), [renameAssetM]);
+    const setAssetAlt = useCallback((id, alt) => settle(updateAssetM.mutateAsync({ id, alt })), [updateAssetM]);
+    const moveAssets = useCallback((ids, folderId) => settle(moveAssetsM.mutateAsync({ ids, folderId })), [moveAssetsM]);
+    const duplicateAssets = useCallback((ids) => settle(duplicateAssetsM.mutateAsync(ids)), [duplicateAssetsM]);
+    const deleteAssets = useCallback((ids) => {
+        const done = settle(deleteAssetsM.mutateAsync(ids));
+        // Drop them from the selection; the drawer closes on its own once the
+        // refetch removes the row (detailAsset derives to null).
+        setSelectedIds((prev) => {
+            const next = new Set(prev);
+            ids.forEach((id) => next.delete(id));
+            return next;
+        });
+        return done;
+    }, [deleteAssetsM]);
+    const uploadFiles = uploads.enqueue;
+    return {
+        // data
+        folders,
+        assets,
+        currentFolderId,
+        currentFolder,
+        breadcrumbs,
+        childFolders,
+        visibleAssets,
+        folderCounts,
+        // paging
+        total,
+        page,
+        pageCount,
+        pageSize,
+        setPage,
+        setPageSize,
+        // load state
+        isLoading: foldersQuery.isPending || assetsQuery.isPending,
+        /**
+         * True while the grid on screen is not yet the answer to the controls
+         * as they now read — the debounce window, then the request.
+         *
+         * `isFetching` alone is a poor cue for a search box: it only goes true
+         * *after* the debounce commits, so for the first 300ms of typing
+         * nothing visible happens at all and the old results sit there looking
+         * like the new ones. Or-ing in the un-committed keystrokes is what
+         * makes the grid say "not this, yet" from the first letter.
+         */
+        isRefreshing: assetsQuery.isFetching || search.trim() !== debouncedSearch.trim(),
+        isError: foldersQuery.isError || assetsQuery.isError,
+        reload: invalidate,
+        // selection
+        selectedIds,
+        selectedAssets,
+        toggleSelect,
+        clearSelection,
+        // detail drawer
+        detailAsset,
+        openDetail,
+        closeDetail,
+        // browse controls
+        search,
+        setSearch,
+        sort,
+        setSort,
+        kindFilter,
+        setKindFilter,
+        // navigation
+        navigateTo,
+        // mutations
+        createFolder,
+        renameFolder,
+        renameAsset,
+        setAssetAlt,
+        deleteAssets,
+        deleteFolder,
+        duplicateAssets,
+        moveAssets,
+        uploadFiles,
+        // upload queue (progress banner)
+        uploadItems: uploads.items,
+        uploadSummary: uploads.summary,
+        retryUpload: uploads.retry,
+        cancelUpload: uploads.cancel,
+        dismissUploads: uploads.dismissSettled
+    };
+}

package/dist/lib/hooks/usePendingMediaUploads/index.d.ts

@@ -0,0 +1,26 @@
+import type { EntryPresave } from '@orthacms/content-admin';
+/** The id the media plugin's presave contribution is registered (and keyed) under. */
+export declare const MEDIA_PRESAVE_ID = "media.entry.presave";
+/**
+ * The media plugin's contribution to the entry **save**: files chosen on a media
+ * field are staged here and uploaded only when the record is saved or published.
+ *
+ * Why deferred — an upload is a write. Uploading the moment a file is picked
+ * fills the Media Library with assets for a record the user then abandons, and a
+ * media field is the one control where "I picked something" and "I saved" used
+ * to mean two different write moments. Staging keeps the whole record one commit.
+ *
+ * A staged file gets a **placeholder uuid**, which is what the form value holds
+ * ({@link PendingUpload}) — so client validation, the Changed badge, and the
+ * publish gate treat it exactly like an attached asset. `commit` (run by
+ * `ContentEntryView` before the write) uploads every staged file the values
+ * still reference, `UPLOAD_CONCURRENCY` at a time, and returns the values with
+ * the placeholders swapped for real asset ids. One failed file aborts the save
+ * with a toast naming it; the files that did upload remember their asset id, so
+ * a retry doesn't upload them twice.
+ *
+ * Mounted once per entry view through `ENTRY_PRESAVE_SLOT`, so the staging (and
+ * its object-URL previews) survive the Media tab unmounting on a tab switch.
+ */
+export declare function usePendingMediaUploads(): EntryPresave;
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/hooks/usePendingMediaUploads/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/hooks/usePendingMediaUploads/index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAmB5D,sFAAsF;AACtF,eAAO,MAAM,gBAAgB,wBAAwB,CAAC;AA+DtD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,sBAAsB,IAAI,YAAY,CAmJrD"}

package/dist/lib/hooks/usePendingMediaUploads/index.js

@@ -0,0 +1,217 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { defineMessages, useIntl } from 'react-intl';
+import { useQueryClient } from '@tanstack/react-query';
+import { toast } from '@orthacms/design-system';
+import { useCurrentWorkspace } from '@orthacms/workspaces-admin';
+import { mediaValueIds, toMediaValueRef } from '@orthacms/content-domain';
+import { ROOT_FOLDER_ID, UPLOAD_CONCURRENCY } from '../../constants';
+import { httpMediaGateway } from '../../infrastructure/httpMediaGateway';
+import { mediaKeys } from '../../infrastructure/mediaKeys';
+/** Intl descriptors for the save-time upload step, co-located. */
+const messages = defineMessages({
+    failed: {
+        id: 'media.pending.failed',
+        defaultMessage: 'Could not upload {name} — the record was not saved. Try again.'
+    }
+});
+/** The id the media plugin's presave contribution is registered (and keyed) under. */
+export const MEDIA_PRESAVE_ID = 'media.entry.presave';
+/** Everything staged that the values actually still reference, in no order. */
+function referenced(values, pending) {
+    // Through the kernel: a media value is `{ id, alt?, decorative? }` as well
+    // as a bare id since `ORT-83`, and reading only strings meant a staged file
+    // attached to a field was no longer *referenced* by it — so the save
+    // uploaded nothing and wrote a record pointing at a placeholder.
+    const ids = new Set();
+    for (const value of Object.values(values))
+        for (const id of mediaValueIds(value))
+            ids.add(id);
+    return [...ids]
+        .map((id) => pending.get(id))
+        .filter((entry) => !!entry);
+}
+/** Swap every placeholder id in the values for the asset it resolved to. */
+function resolveValues(values, resolved) {
+    if (resolved.size === 0)
+        return values;
+    const out = { ...values };
+    /**
+     * Swaps one value's placeholder for the real asset id, **keeping whatever
+     * else the value carries** — the alt text and the decorative flag an author
+     * typed against the staged file belong to the asset it became.
+     */
+    const swap = (item) => {
+        const ref = toMediaValueRef(item);
+        if (!ref)
+            return { value: item, changed: false };
+        const id = resolved.get(ref.id);
+        if (!id)
+            return { value: item, changed: false };
+        return {
+            // A bare id in, a bare id out: only widen the shape where the author
+            // actually said something, so an untouched attach keeps the wire
+            // form it had.
+            value: typeof item === 'string' ? id : { ...ref, id },
+            changed: true
+        };
+    };
+    for (const [name, value] of Object.entries(values)) {
+        if (Array.isArray(value)) {
+            let changed = false;
+            const next = value.map((item) => {
+                const swapped = swap(item);
+                if (swapped.changed)
+                    changed = true;
+                return swapped.value;
+            });
+            if (changed)
+                out[name] = next;
+        }
+        else {
+            const swapped = swap(value);
+            if (swapped.changed)
+                out[name] = swapped.value;
+        }
+    }
+    return out;
+}
+/**
+ * The media plugin's contribution to the entry **save**: files chosen on a media
+ * field are staged here and uploaded only when the record is saved or published.
+ *
+ * Why deferred — an upload is a write. Uploading the moment a file is picked
+ * fills the Media Library with assets for a record the user then abandons, and a
+ * media field is the one control where "I picked something" and "I saved" used
+ * to mean two different write moments. Staging keeps the whole record one commit.
+ *
+ * A staged file gets a **placeholder uuid**, which is what the form value holds
+ * ({@link PendingUpload}) — so client validation, the Changed badge, and the
+ * publish gate treat it exactly like an attached asset. `commit` (run by
+ * `ContentEntryView` before the write) uploads every staged file the values
+ * still reference, `UPLOAD_CONCURRENCY` at a time, and returns the values with
+ * the placeholders swapped for real asset ids. One failed file aborts the save
+ * with a toast naming it; the files that did upload remember their asset id, so
+ * a retry doesn't upload them twice.
+ *
+ * Mounted once per entry view through `ENTRY_PRESAVE_SLOT`, so the staging (and
+ * its object-URL previews) survive the Media tab unmounting on a tab switch.
+ */
+export function usePendingMediaUploads() {
+    const intl = useIntl();
+    const workspace = useCurrentWorkspace();
+    const queryClient = useQueryClient();
+    const [pending, setPending] = useState(() => new Map());
+    // `commit` runs across awaits and after `settle`; it reads the map through a
+    // ref so it never works from a render-stale copy.
+    const pendingRef = useRef(pending);
+    pendingRef.current = pending;
+    const write = useCallback((next) => {
+        pendingRef.current = next;
+        setPending(next);
+    }, []);
+    const stage = useCallback((files) => {
+        const next = new Map(pendingRef.current);
+        const ids = files.map((file) => {
+            const id = crypto.randomUUID();
+            next.set(id, {
+                id,
+                file,
+                previewUrl: file.type.startsWith('image/')
+                    ? URL.createObjectURL(file)
+                    : undefined
+            });
+            return id;
+        });
+        write(next);
+        return ids;
+    }, [write]);
+    const drop = useCallback((id) => {
+        const entry = pendingRef.current.get(id);
+        if (!entry)
+            return;
+        if (entry.previewUrl)
+            URL.revokeObjectURL(entry.previewUrl);
+        const next = new Map(pendingRef.current);
+        next.delete(id);
+        write(next);
+    }, [write]);
+    const commit = useCallback(async ({ values }) => {
+        const queue = referenced(values, pendingRef.current);
+        if (queue.length === 0)
+            return values;
+        const resolved = new Map();
+        const uploaded = new Map();
+        const failed = [];
+        // A small pool of workers over one shared cursor — the same shape as
+        // the library's upload queue, minus the progress bookkeeping (the
+        // save's busy cover is the status surface here).
+        let cursor = 0;
+        const worker = async () => {
+            for (;;) {
+                const entry = queue[cursor++];
+                if (!entry)
+                    return;
+                if (entry.uploadedId) {
+                    resolved.set(entry.id, entry.uploadedId);
+                    continue;
+                }
+                try {
+                    const asset = await httpMediaGateway.uploadFile(ROOT_FOLDER_ID, entry.file);
+                    resolved.set(entry.id, asset.id);
+                    uploaded.set(entry.id, asset);
+                }
+                catch {
+                    failed.push(entry);
+                }
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(UPLOAD_CONCURRENCY, queue.length) }, worker));
+        if (uploaded.size > 0) {
+            // The library gained assets even if the save is about to fail.
+            queryClient.invalidateQueries({
+                queryKey: mediaKeys.all(workspace.id)
+            });
+            // Remember each asset id against its placeholder, so a retry
+            // after a failed write attaches it instead of re-uploading.
+            const next = new Map(pendingRef.current);
+            for (const [placeholder, asset] of uploaded) {
+                const entry = next.get(placeholder);
+                if (entry)
+                    next.set(placeholder, {
+                        ...entry,
+                        uploadedId: asset.id
+                    });
+            }
+            write(next);
+        }
+        if (failed.length > 0) {
+            for (const entry of failed) {
+                toast.error(intl.formatMessage(messages.failed, {
+                    name: entry.file.name
+                }));
+            }
+            throw new Error('media upload failed');
+        }
+        return resolveValues(values, resolved);
+    }, [intl, queryClient, workspace.id, write]);
+    /** The write landed — the saved record carries the ids, so drop the staging. */
+    const settle = useCallback(() => {
+        for (const entry of pendingRef.current.values()) {
+            if (entry.previewUrl)
+                URL.revokeObjectURL(entry.previewUrl);
+        }
+        write(new Map());
+    }, [write]);
+    // Leaving the editor with files still staged would otherwise leak every
+    // preview blob for the tab's life.
+    useEffect(() => () => {
+        // Read through the ref *inside* the cleanup — the map at mount time
+        // is always the empty one.
+        for (const entry of pendingRef.current.values()) {
+            if (entry.previewUrl)
+                URL.revokeObjectURL(entry.previewUrl);
+        }
+    }, []);
+    const handle = { pending, stage, drop };
+    return { commit, settle, handle };
+}