@jini-ai/admin 0.4.12 → 0.4.13

package/dist/media/react/hooks/LibraryTab.hooks.js

@@ -3,13 +3,104 @@ import { MEDIA_QUERY_KEYS, useMediaLibraryQuery } from './MediaQuery.hooks.js';
 import { useEffect, useLayoutEffect, useRef, useState } from 'react';
 import { useController } from '../../../core/react/use-controller.js';
 import { createLibraryController } from '../../controllers/library.controller.js';
-import { useSharedMediaLibrary } from './MediaPage.hooks.js';
+import { settleFromCache, useSharedMediaLibrary } from './MediaPage.hooks.js';
 import { useMediaPorts } from './MediaPorts.hooks.js';
 import { mediaMessagesEn } from '../../messages.en.js';
 import { canRestoreMedia } from '../../rules.js';
+const EMPTY_LABELS = {
+    images: 'No images yet. Upload an image to see it here.',
+    videos: 'No videos yet. Upload a video to see it here.',
+    all: 'No media found',
+};
+function contentFilter({ params }, _optional = {}) {
+    return params.filter === 'images' || params.filter === 'videos' ? params.filter : 'all';
+}
+function libraryPermissions({ permissions, api }, _optional = {}) {
+    return {
+        canUpload: permissions.includes('media.upload'),
+        canEdit: permissions.includes('media.update'),
+        canTrash: permissions.includes('media.trash'),
+        canRestore: permissions.includes('media.restore') && canRestoreMedia({ api }),
+        canPurge: permissions.includes('media.delete.force'),
+    };
+}
+/** Focuses the card with `id`, else whichever card now sits at `index`, else the grid itself. */
+function focusCard({ grid, index }, { id } = {}) {
+    const cards = Array.from(grid?.querySelectorAll('[data-jini-part="media.card"]') ?? []);
+    const byId = id === undefined ? undefined : cards.find(card => card.dataset.mediaId === id);
+    const target = byId ?? cards[Math.min(index, cards.length - 1)] ?? grid;
+    target?.focus({ preventScroll: true });
+}
+function queryView({ snapshot }, _optional = {}) {
+    return {
+        statusFilter: snapshot?.query.status ?? 'all',
+        orderBy: snapshot?.query.orderBy ?? 'created',
+        search: snapshot?.query.search ?? '',
+    };
+}
+function progressView({ snapshot, filter }, _optional = {}) {
+    return {
+        loading: !snapshot || (snapshot.items === null && snapshot.loading && !snapshot.error),
+        busy: snapshot?.busy ?? false,
+        untyped: filter !== 'all' && snapshot?.hasUntyped === true,
+    };
+}
+function purgeDialogView({ snapshot }, _optional = {}) {
+    const pending = snapshot?.pendingPurge;
+    return { open: !!pending, pending: snapshot?.busy ?? false, ...(pending ? { filename: pending.title } : {}) };
+}
+function queryHandlers({ controller }, _optional = {}) {
+    return {
+        onStatus: ({ value }) => {
+            const { status: _status, ...query } = controller?.getSnapshot().query ?? {};
+            void controller?.setQuery({ query: { ...query, ...(value === 'active' || value === 'trashed' ? { status: value } : {}) } });
+        },
+        onSearch: ({ value: search }) => {
+            void controller?.setQuery({ query: { ...controller.getSnapshot().query, search } });
+        },
+        onOrder: ({ value }) => {
+            void controller?.setQuery({ query: { ...controller.getSnapshot().query, orderBy: value === 'alphabetical' ? 'alphabetical' : 'created' } });
+        },
+    };
+}
+function cardActions({ items, pendingIds, can, controller, announce, onEdit, onPreview }, _optional = {}) {
+    return items.map((item, index) => {
+        const write = (run, verb) => {
+            void run?.then(saved => { if (saved)
+                announce({ message: `${verb} ${item.title}`, focus: { id: item.id, index } }); });
+        };
+        return {
+            item,
+            busy: pendingIds.includes(item.id),
+            ...(can.canEdit ? { onEdit: () => onEdit(item) } : {}),
+            onPreview: () => onPreview(index),
+            ...(can.canTrash ? { onTrash: () => write(controller?.trash({ id: item.id }), 'Trashed') } : {}),
+            ...(can.canRestore ? { onRestore: () => write(controller?.restore({ id: item.id }), 'Restored') } : {}),
+            ...(can.canPurge ? { onPurge: () => controller?.requestPurge({ item }) } : {}),
+        };
+    });
+}
+/** Once a write has settled and the grid re-rendered, return focus to the affected card. */
+function useFocusAfterWrites({ gridRef, snapshot }, _optional = {}) {
+    const [focusAfterAction, setFocusAfterAction] = useState(null);
+    useLayoutEffect(() => {
+        if (!focusAfterAction || snapshot?.busy || snapshot?.loading)
+            return;
+        focusCard({ grid: gridRef.current, index: focusAfterAction.index }, { id: focusAfterAction.id });
+        setFocusAfterAction(null);
+    }, [focusAfterAction, snapshot?.busy, snapshot?.loading, snapshot?.items]);
+    const [focusAfterPurge, setFocusAfterPurge] = useState(null);
+    useLayoutEffect(() => {
+        if (focusAfterPurge === null || snapshot?.pendingPurge || snapshot?.busy)
+            return;
+        focusCard({ grid: gridRef.current, index: focusAfterPurge });
+        setFocusAfterPurge(null);
+    }, [focusAfterPurge, snapshot?.pendingPurge, snapshot?.busy, snapshot?.items]);
+    return { setFocusAfterAction, setFocusAfterPurge };
+}
 export function useLibraryTab({ params, permissions = [] }, _optional = {}) {
     const { mediaApi, mediaEvents } = useMediaPorts();
-    const filter = params.filter === 'images' || params.filter === 'videos' ? params.filter : 'all';
+    const filter = contentFilter({ params });
     const shared = useSharedMediaLibrary();
     const cached = useMediaLibraryQuery({ api: mediaApi }, { enabled: !shared });
     const invalidate = useInvalidate();
@@ -25,28 +116,10 @@ export function useLibraryTab({ params, permissions = [] }, _optional = {}) {
     const { controller, snapshot } = shared ?? local;
     useEffect(() => !shared ? mediaEvents?.subscribe({ onRefresh: () => invalidate({ key: MEDIA_QUERY_KEYS.root }) }) : undefined, [mediaEvents, controller, shared, invalidate]);
     useEffect(() => { if (!shared)
-        local.controller?.settleLibrary({ ...(cached.query.data ? { all: cached.query.data } : {}), error: cached.query.error }); }, [shared, local.controller, cached.query.data, cached.query.error]);
+        settleFromCache({ controller: local.controller, query: cached.query }); }, [shared, local.controller, cached.query.data, cached.query.error]);
     const gridRef = useRef(null);
     const [success, setSuccess] = useState(null);
-    const [focusAfterAction, setFocusAfterAction] = useState(null);
-    useLayoutEffect(() => {
-        if (!focusAfterAction || snapshot?.busy || snapshot?.loading)
-            return;
-        const cards = Array.from(gridRef.current?.querySelectorAll('[data-jini-part="media.card"]') ?? []);
-        const target = cards.find(card => card.dataset.mediaId === focusAfterAction.id) ?? cards[Math.min(focusAfterAction.index, cards.length - 1)] ?? gridRef.current;
-        target?.focus({ preventScroll: true });
-        setFocusAfterAction(null);
-    }, [focusAfterAction, snapshot?.busy, snapshot?.loading, snapshot?.items]);
-    const [focusAfterPurge, setFocusAfterPurge] = useState(null);
-    useLayoutEffect(() => {
-        if (focusAfterPurge === null || snapshot?.pendingPurge || snapshot?.busy)
-            return;
-        const grid = gridRef.current;
-        const cards = grid?.querySelectorAll('[data-jini-part="media.card"]');
-        const target = cards?.[Math.min(focusAfterPurge, cards.length - 1)] ?? grid;
-        target?.focus({ preventScroll: true });
-        setFocusAfterPurge(null);
-    }, [focusAfterPurge, snapshot?.pendingPurge, snapshot?.busy, snapshot?.items]);
+    const { setFocusAfterAction, setFocusAfterPurge } = useFocusAfterWrites({ gridRef, snapshot });
     useEffect(() => {
         // A shared page controller survives tab unmounts. Re-entering after an error must
         // be a recovery opportunity even when its cached filter already matches this tab.
@@ -58,32 +131,9 @@ export function useLibraryTab({ params, permissions = [] }, _optional = {}) {
     // buttons move the number without re-deriving "what's next" from an item reference.
     const [lightboxIndex, setLightboxIndex] = useState(null);
     const items = snapshot?.items ?? [], pendingIds = snapshot?.pendingIds ?? [];
-    const canUpload = permissions.includes('media.upload');
-    const canEdit = permissions.includes('media.update');
-    const canTrash = permissions.includes('media.trash');
-    const canRestore = permissions.includes('media.restore') && canRestoreMedia({ api: mediaApi });
-    const canPurge = permissions.includes('media.delete.force');
-    const actions = items.map((item, index) => ({
-        item,
-        busy: pendingIds.includes(item.id),
-        ...(canEdit ? { onEdit: () => setEditing(item) } : {}),
-        onPreview: () => setLightboxIndex(index),
-        ...(canTrash
-            ? {
-                onTrash: () => {
-                    void controller?.trash({ id: item.id }).then(saved => { if (saved) {
-                        setSuccess(`Trashed ${item.title}`);
-                        setFocusAfterAction({ id: item.id, index });
-                    } });
-                },
-            }
-            : {}),
-        ...(canRestore ? { onRestore: () => { void controller?.restore({ id: item.id }).then(saved => { if (saved) {
-                setSuccess(`Restored ${item.title}`);
-                setFocusAfterAction({ id: item.id, index });
-            } }); } } : {}),
-        ...(canPurge ? { onPurge: () => controller?.requestPurge({ item }) } : {}),
-    }));
+    const can = libraryPermissions({ permissions, api: mediaApi });
+    const announce = ({ message, focus }) => { setSuccess(message); setFocusAfterAction(focus); };
+    const actions = cardActions({ items, pendingIds, can, controller, announce, onEdit: setEditing, onPreview: setLightboxIndex });
     function closeEdit() {
         setEditing(null);
     }
@@ -99,18 +149,12 @@ export function useLibraryTab({ params, permissions = [] }, _optional = {}) {
             setFocusAfterAction({ id: item.id, index: Math.max(0, items.findIndex(row => row.id === item.id)) });
     }
     return {
-        emptyLabel: filter === 'images' ? 'No images yet. Upload an image to see it here.'
-            : filter === 'videos' ? 'No videos yet. Upload a video to see it here.' : 'No media found',
-        canUpload,
+        emptyLabel: EMPTY_LABELS[filter],
+        canUpload: can.canUpload,
         success,
         gridRef,
         onRetry: () => { void controller?.load(); },
-        statusFilter: snapshot?.query.status ?? 'all',
-        onStatus: ({ value }) => {
-            const { status: _status, ...query } = controller?.getSnapshot().query ?? {};
-            void controller?.setQuery({ query: { ...query, ...(value === 'active' || value === 'trashed' ? { status: value } : {}) } });
-        },
-        canPurge,
+        canPurge: can.canPurge,
         controller,
         snapshot,
         actions,
@@ -122,19 +166,12 @@ export function useLibraryTab({ params, permissions = [] }, _optional = {}) {
         lightboxIndex,
         onNavigate: setLightboxIndex,
         closeLightbox: () => setLightboxIndex(null),
-        onSearch: ({ value: search }) => {
-            void controller?.setQuery({ query: { ...controller.getSnapshot().query, search } });
-        },
-        orderBy: snapshot?.query.orderBy ?? 'created',
-        onOrder: ({ value }) => {
-            void controller?.setQuery({ query: { ...controller.getSnapshot().query, orderBy: value === 'alphabetical' ? 'alphabetical' : 'created' } });
-        },
-        search: snapshot?.query.search ?? '',
-        loading: !snapshot || (snapshot.items === null && snapshot.loading && !snapshot.error),
-        busy: snapshot?.busy ?? false,
-        untyped: filter !== 'all' && snapshot?.hasUntyped === true,
+        ...queryHandlers({ controller }),
+        ...queryView({ snapshot }),
+        ...progressView({ snapshot, filter }),
+        purgeDialog: purgeDialogView({ snapshot }),
         async upload({ input, alt }) {
-            if (!canUpload)
+            if (!can.canUpload)
                 return false;
             const result = await controller?.upload({ input, ...(alt === undefined ? {} : { alt }) }) ?? false;
             if (result)
@@ -145,7 +182,7 @@ export function useLibraryTab({ params, permissions = [] }, _optional = {}) {
         confirmPurge: () => {
             const item = controller?.getSnapshot().pendingPurge;
             // The controller refuses to purge without a pending item, so there is nothing to announce.
-            if (!canPurge || !controller || !item)
+            if (!can.canPurge || !controller || !item)
                 return;
             const index = items.findIndex(row => row.id === item.id);
             return controller.confirmPurge({ confirmed: true }).then(saved => {

package/dist/media/react/hooks/MediaCard.hooks.d.ts

@@ -13,14 +13,26 @@ export interface MediaCardProps {
     readonly onPurge?: () => void;
     readonly onChoose?: () => void;
 }
+type PreviewStage = 'image' | 'video' | 'unsupported';
 export declare function useMediaCard(props: MediaCardProps, _optional?: Record<string, never>): {
-    busy: boolean;
-    byteSize: string | null;
-    uploadDate: string | null;
-    metadataSeparator: string;
-    preview: () => void | undefined;
-    canPreview: boolean;
-    imagePreview: boolean;
+    statusClassName: string;
+    statusLabel: "active" | "trashed";
+    statusTone: "warning" | "success";
+    trashed: boolean;
+    menuItems: {
+        onPress: () => void;
+        disabled: boolean;
+        attrs?: {
+            'data-jini-variant': string;
+        };
+        id: string;
+        label: string;
+    }[];
+    src: string | undefined;
+    stage: PreviewStage;
+    onImageError: () => void;
+    onVideoError: () => void;
+    alt: string;
     handles: {
         expand: string;
         edit: string;
@@ -43,32 +55,15 @@ export declare function useMediaCard(props: MediaCardProps, _optional?: Record<s
         'data-agent-element': string;
         'data-agent-label': string;
     };
-    menuItems: ({
-        id: string;
-        label: string;
-        onPress: () => void;
-        disabled: boolean;
-        attrs?: never;
-    } | {
-        id: string;
-        label: string;
-        attrs: {
-            'data-jini-variant': string;
-        };
-        onPress: () => void;
-        disabled: boolean;
-    })[];
-    src: string | undefined;
-    stage: "video" | "image" | "unsupported";
+    canPreview: boolean;
+    imagePreview: boolean;
     image: boolean | "" | undefined;
     video: boolean | "" | undefined;
-    onImageError: () => void;
-    onVideoError: () => void;
-    alt: string;
-    statusClassName: string;
-    statusLabel: "active" | "trashed";
-    statusTone: "warning" | "success";
-    trashed: boolean;
+    preview: () => void | undefined;
+    byteSize: string | null;
+    uploadDate: string | null;
+    metadataSeparator: string;
+    busy: boolean;
     item: MediaAsset;
     handleBase?: string;
     locale?: string;
@@ -80,4 +75,5 @@ export declare function useMediaCard(props: MediaCardProps, _optional?: Record<s
     onPurge?: () => void;
     onChoose?: () => void;
 };
+export {};
 //# sourceMappingURL=MediaCard.hooks.d.ts.map

package/dist/media/react/hooks/MediaCard.hooks.js

@@ -1,5 +1,52 @@
 import { useState } from 'react';
 import { safeMediaUrl, formatByteSize, formatUploadDate, mediaRowHandles } from '../../rules.js';
+function menuItems({ props }, _optional = {}) {
+    const disabled = props.busy === true, trashed = props.item.status === 'trashed';
+    const entries = [
+        { id: 'edit', label: 'Edit metadata', onPress: props.onEdit, shown: true },
+        { id: 'trash', label: 'Trash', onPress: props.onTrash, shown: !trashed },
+        // Restore belongs only in a trashed card's menu; active cards have nothing to restore.
+        { id: 'restore', label: 'Restore', onPress: props.onRestore, shown: trashed },
+        { id: 'purge', label: 'Delete permanently', onPress: props.onPurge, shown: trashed },
+    ];
+    return entries.flatMap(({ id, label, onPress, shown }) => onPress && shown
+        ? [{ id, label, ...(id === 'purge' ? { attrs: { 'data-jini-variant': 'danger' } } : {}), onPress, disabled }]
+        : []);
+}
+function metadata({ item }, { locale = 'en-US' } = {}) {
+    const byteSize = item.byteSize === undefined ? null : formatByteSize({ bytes: item.byteSize }, { locale });
+    const uploadDate = formatUploadDate({ createdAt: item.createdAt }, { locale });
+    return { byteSize, uploadDate, metadataSeparator: byteSize && uploadDate ? ' · ' : '' };
+}
+function previewFlags({ src, stage }, { onPreview } = {}) {
+    const previewable = !!onPreview && !!src;
+    return {
+        canPreview: previewable && stage !== 'unsupported',
+        imagePreview: previewable && stage === 'image',
+        image: src && stage === 'image',
+        video: src && stage === 'video',
+    };
+}
+function statusView({ item }, _optional = {}) {
+    const trashed = item.status === 'trashed';
+    return {
+        statusClassName: `jini-status jini-status-${item.status}`,
+        statusLabel: item.status,
+        statusTone: trashed ? 'warning' : 'success',
+        trashed,
+    };
+}
+function agentAttrs({ handleBase, title }, _optional = {}) {
+    return {
+        handles: { expand: `${handleBase}-expand`, edit: `${handleBase}-edit`, menu: `${handleBase}-menu` },
+        previewAttrs: { 'data-jini-part': 'media.preview', 'data-agent-element': `${handleBase}-expand`,
+            'data-agent-label': 'Open this asset larger in the lightbox', 'aria-label': `View "${title}" larger` },
+        editAttrs: { 'data-jini-part': 'media.edit', 'data-agent-element': `${handleBase}-edit`,
+            'data-agent-label': 'Open the edit form for this asset as a modal', 'aria-label': `Edit "${title}"` },
+        menuLabel: `Actions for "${title}"`,
+        menuAttrs: { 'data-agent-element': `${handleBase}-menu`, 'data-agent-label': `Actions for "${title}"` },
+    };
+}
 export function useMediaCard(props, _optional = {}) {
     /** Preview optimistically: image -> video -> placeholder. The list supplies no reliable media
      * kind, and the byte route guarantees GET rather than HEAD, so probing headers would assume an
@@ -12,41 +59,20 @@ export function useMediaCard(props, _optional = {}) {
     // immediately when the versioned URL changes, including in an already-open lightbox.
     const stage = probe.src === src ? probe.stage : 'image';
     const handleBase = props.handleBase ?? mediaRowHandles({ media: [props.item] })[0];
-    const byteSize = props.item.byteSize === undefined ? null : formatByteSize({ bytes: props.item.byteSize }, { locale: props.locale ?? 'en-US' });
-    const uploadDate = formatUploadDate({ createdAt: props.item.createdAt }, { locale: props.locale ?? 'en-US' });
     return {
         ...props,
         busy: props.busy === true,
-        byteSize, uploadDate,
-        metadataSeparator: byteSize && uploadDate ? ' · ' : '',
+        ...metadata({ item: props.item }, { locale: props.locale }),
         preview: () => props.onPreview?.(),
-        canPreview: !!props.onPreview && !!src && stage !== 'unsupported',
-        imagePreview: !!props.onPreview && !!src && stage === 'image',
-        handles: { expand: `${handleBase}-expand`, edit: `${handleBase}-edit`, menu: `${handleBase}-menu` },
-        previewAttrs: { 'data-jini-part': 'media.preview', 'data-agent-element': `${handleBase}-expand`,
-            'data-agent-label': 'Open this asset larger in the lightbox', 'aria-label': `View "${props.item.title}" larger` },
-        editAttrs: { 'data-jini-part': 'media.edit', 'data-agent-element': `${handleBase}-edit`,
-            'data-agent-label': 'Open the edit form for this asset as a modal', 'aria-label': `Edit "${props.item.title}"` },
-        menuLabel: `Actions for "${props.item.title}"`,
-        menuAttrs: { 'data-agent-element': `${handleBase}-menu`, 'data-agent-label': `Actions for "${props.item.title}"` },
-        menuItems: [
-            ...(props.onEdit ? [{ id: 'edit', label: 'Edit metadata', onPress: props.onEdit, disabled: props.busy === true }] : []),
-            ...(props.onTrash && props.item.status !== 'trashed' ? [{ id: 'trash', label: 'Trash', onPress: props.onTrash, disabled: props.busy === true }] : []),
-            // Restore belongs only in a trashed card's menu; active cards have nothing to restore.
-            ...(props.onRestore && props.item.status === 'trashed' ? [{ id: 'restore', label: 'Restore', onPress: props.onRestore, disabled: props.busy === true }] : []),
-            ...(props.onPurge && props.item.status === 'trashed' ? [{ id: 'purge', label: 'Delete permanently', attrs: { 'data-jini-variant': 'danger' }, onPress: props.onPurge, disabled: props.busy === true }] : []),
-        ],
+        ...previewFlags({ src, stage }, { onPreview: props.onPreview }),
+        ...agentAttrs({ handleBase, title: props.item.title }),
+        menuItems: menuItems({ props }),
         src,
         stage,
-        image: src && stage === 'image',
-        video: src && stage === 'video',
         onImageError: () => setProbe({ src, stage: 'video' }),
         onVideoError: () => setProbe({ src, stage: 'unsupported' }),
         alt: props.item.alt || props.item.title || 'Untitled asset',
-        statusClassName: `jini-status jini-status-${props.item.status}`,
-        statusLabel: props.item.status,
-        statusTone: props.item.status === 'trashed' ? 'warning' : 'success',
-        trashed: props.item.status === 'trashed',
+        ...statusView({ item: props.item }),
     };
 }
 //# sourceMappingURL=MediaCard.hooks.js.map

package/dist/media/react/hooks/MediaGrid.hooks.d.ts

@@ -14,8 +14,8 @@ export declare function useMediaGrid(props: MediaGridProps, _optional?: Record<s
         locale?: string;
         busy?: boolean;
         onPurge?: () => void;
-        onEdit?: () => void;
         onPreview?: () => void;
+        onEdit?: () => void;
         onTrash?: () => void;
         onRestore?: () => void;
         onChoose?: () => void;

package/dist/media/react/hooks/MediaLightbox.hooks.d.ts

@@ -7,21 +7,17 @@ export interface MediaLightboxProps {
     readonly onNavigate: (index: number) => void;
     readonly onClose: () => void;
 }
+/** Resolves the open asset and the shared lightbox's set props. Clamping, keyboard, focus and
+ * the open/close lifecycle live in `@jini-ai/ui`'s `useLightbox`. */
 export declare function useMediaLightbox(props: MediaLightboxProps, _optional?: Record<string, never>): {
     item: MediaAsset | null;
-    open: boolean;
-    hasPrev: boolean;
-    hasNext: boolean;
-    previous: () => void;
-    next: () => void;
-    items: readonly MediaAsset[];
-    api: MediaApiPort;
-    activeIndex: number | null;
-    onNavigate: (index: number) => void;
-    onClose: () => void;
-    dialogRef: import("react").RefObject<HTMLDialogElement | null>;
-    closeRef: import("react").RefObject<HTMLButtonElement | null>;
-    title: string;
-    position: string;
+    lightbox: {
+        open: boolean;
+        title: string;
+        index: number;
+        count: number;
+        onNavigate: (index: number) => void;
+        onClose: () => void;
+    };
 };
 //# sourceMappingURL=MediaLightbox.hooks.d.ts.map

package/dist/media/react/hooks/MediaLightbox.hooks.js

@@ -1,63 +1,16 @@
-import { useEffect, useRef } from 'react';
+/** Resolves the open asset and the shared lightbox's set props. Clamping, keyboard, focus and
+ * the open/close lifecycle live in `@jini-ai/ui`'s `useLightbox`. */
 export function useMediaLightbox(props, _optional = {}) {
     const item = props.activeIndex === null ? null : props.items[props.activeIndex] ?? null;
-    function go(index) {
-        // Clamps rather than wrapping: staying on the last asset is the less surprising
-        // default for an operator navigating a specific set of uploads, not a slideshow.
-        if (index >= 0 && index < props.items.length) {
-            const focusedPart = dialogRef.current?.ownerDocument.activeElement?.getAttribute('data-jini-part');
-            // Keep focus in the dialog when the focused arrow disappears at a boundary.
-            // Interior navigation leaves focus where the operator put it.
-            if ((index === 0 && focusedPart === 'media.lightbox.previous') ||
-                (index === props.items.length - 1 && focusedPart === 'media.lightbox.next'))
-                closeRef.current?.focus({ preventScroll: true });
-            props.onNavigate(index);
-        }
-    }
-    const closeRef = useRef(null);
-    const dialogRef = useRef(null);
-    const open = !!item;
-    useEffect(() => {
-        // Close exists at every position, so it is a stable initial focus target. Only
-        // opening focuses it; navigation must preserve the operator's current focus.
-        if (open)
-            closeRef.current?.focus();
-    }, [open]);
-    // Dialog owns open/close/focus, keyed on open rather than index: navigation must not
-    // reopen an already-open dialog or recapture its trigger from inside the lightbox.
-    useEffect(() => {
-        const dialog = dialogRef.current;
-        if (!dialog || !item)
-            return;
-        const onKey = (event) => {
-            if (event.key !== 'ArrowLeft' && event.key !== 'ArrowRight')
-                return;
-            event.preventDefault();
-            if (props.activeIndex !== null)
-                go(props.activeIndex + (event.key === 'ArrowRight' ? 1 : -1));
-            // Native video controls may also seek while focused, as in the legacy lightbox.
-            // Preview stage remains private, so do not silently infer it from contentType.
-        };
-        dialog.ownerDocument.addEventListener('keydown', onKey);
-        return () => dialog.ownerDocument.removeEventListener('keydown', onKey);
-    }, [props.activeIndex, props.items, props.onNavigate, !!item]);
     return {
-        dialogRef,
-        closeRef,
-        title: item ? `Media preview: ${item.title}` : 'Media preview',
-        position: item && props.activeIndex !== null ? `${props.activeIndex + 1} / ${props.items.length}` : '',
-        ...props,
         item,
-        open: !!item,
-        hasPrev: props.activeIndex !== null && props.activeIndex > 0,
-        hasNext: props.activeIndex !== null && props.activeIndex + 1 < props.items.length,
-        previous: () => {
-            if (props.activeIndex !== null)
-                go(props.activeIndex - 1);
-        },
-        next: () => {
-            if (props.activeIndex !== null)
-                go(props.activeIndex + 1);
+        lightbox: {
+            open: !!item,
+            title: item?.title ?? '',
+            index: props.activeIndex ?? 0,
+            count: props.items.length,
+            onNavigate: props.onNavigate,
+            onClose: props.onClose,
         },
     };
 }

package/dist/media/react/hooks/MediaPage.hooks.d.ts

@@ -1,3 +1,4 @@
+import { useMediaLibraryQuery } from './MediaQuery.hooks.js';
 import type { ReactNode } from 'react';
 import type { ModulePageProps } from '../../../core/react/bind-react.js';
 import { createLibraryController } from '../../controllers/library.controller.js';
@@ -10,6 +11,11 @@ export declare function useSharedMediaLibrary(_required?: Record<string, never>,
     controller: ReturnType<typeof createLibraryController> | null;
     snapshot: LibraryState | null;
 } | null;
+/** Feeds the cached library read into a controller; an absent read leaves `all` untouched. */
+export declare function settleFromCache({ controller, query }: {
+    controller: ReturnType<typeof createLibraryController> | null;
+    query: ReturnType<typeof useMediaLibraryQuery>['query'];
+}, _optional?: Record<string, never>): void;
 export interface MediaPageProps extends ModulePageProps {
     readonly headerActions?: ReactNode;
 }

package/dist/media/react/hooks/MediaPage.hooks.js

@@ -10,30 +10,31 @@ export const MediaLibraryContext = createContext(null);
 export function useSharedMediaLibrary(_required = {}, _optional = {}) {
     return useContext(MediaLibraryContext);
 }
+/** Feeds the cached library read into a controller; an absent read leaves `all` untouched. */
+export function settleFromCache({ controller, query }, _optional = {}) {
+    controller?.settleLibrary({ ...(query.data ? { all: query.data } : {}), error: query.error });
+}
 export function useMediaPage(props, _optional = {}) {
     const [localTab, setLocalTab] = useState('all');
     const { mediaApi, mediaEvents, mediaProviders } = useMediaPorts();
     const cached = useMediaLibraryQuery({ api: mediaApi }, { enabled: props.description.visible });
     const providers = useMediaProvidersQuery({ port: mediaProviders }, { enabled: props.description.visible && props.description.grants.includes('media.providers') });
     const invalidate = useInvalidate();
-    const library = useController({ create: () => createLibraryController({ api: cached.api }, { query: { filter: requestedFilter({ tabId: props.requestedTab ?? localTab }) } }), dependencies: [cached.api] }, { start: ({ controller }) => { if (props.description.visible)
+    const tabId = props.requestedTab ?? localTab;
+    const library = useController({ create: () => createLibraryController({ api: cached.api }, { query: { filter: requestedFilter({ tabId }) } }), dependencies: [cached.api] }, { start: ({ controller }) => { if (props.description.visible)
             void controller.load(); } });
     useEffect(() => props.description.visible ? mediaEvents?.subscribe({ onRefresh: () => { invalidate({ key: MEDIA_QUERY_KEYS.root }); } }) : undefined, [props.description.visible, mediaEvents, library.controller, invalidate]);
-    useEffect(() => { library.controller?.settleLibrary({ ...(cached.query.data ? { all: cached.query.data } : {}), error: cached.query.error }); }, [library.controller, cached.query.data, cached.query.error]);
+    useEffect(() => { settleFromCache({ controller: library.controller, query: cached.query }); }, [library.controller, cached.query.data, cached.query.error]);
     /* An unavailable read is not evidence of a zero catalogue. */
     const providerCount = providers.query.data?.length ?? null;
-    const visible = props.description.visible
-        ? props.description.tabs.filter((tab) => tab.visible)
-        : [];
-    const requested = resolveActiveTab({ tabId: props.requestedTab ?? localTab });
-    const active = visible.find((tab) => tab.id.endsWith(`.${requested}`)) ?? visible[0];
+    const { visible, active } = visibleTabs({ description: props.description, tabId });
     const tabs = visible.map((tab) => {
-        const id = tab.id.slice(tab.id.lastIndexOf('.') + 1);
+        const id = shortTabId({ id: tab.id });
         return {
             ...tab,
             id,
             handle: `media-tab-${id}`,
-            icon: createElement(id === 'images' ? ImageIcon : id === 'videos' ? VideoIcon : id === 'external-providers' ? CloudIcon : AllIcon, {}),
+            icon: createElement(TAB_ICONS.get(id) ?? AllIcon, {}),
             count: id === 'external-providers' ? providerCount : library.snapshot?.counts?.[id],
             selected: active?.id === tab.id,
             onPress: () => {
@@ -42,10 +43,11 @@ export function useMediaPage(props, _optional = {}) {
             },
         };
     });
-    const id = active?.id.slice(active.id.lastIndexOf('.') + 1);
+    const id = active && shortTabId({ id: active.id });
     useEffect(() => {
-        if (props.description.visible && (id === 'all' || id === 'images' || id === 'videos') && library.controller?.getSnapshot().query.filter !== id)
-            void library.controller?.setQuery({ query: { ...library.controller.getSnapshot().query, filter: id } });
+        const filter = libraryFilter({ id });
+        if (props.description.visible && filter && library.controller?.getSnapshot().query.filter !== filter)
+            void library.controller?.setQuery({ query: { ...library.controller.getSnapshot().query, filter } });
     }, [id, library.controller, props.description.visible]);
     return {
         library,
@@ -58,6 +60,21 @@ export function useMediaPage(props, _optional = {}) {
         denied: !props.description.visible,
     };
 }
+const TAB_ICONS = new Map([['images', ImageIcon], ['videos', VideoIcon], ['external-providers', CloudIcon]]);
+/** Module tab ids are namespaced (`media.images`); the page and its tabs use the last segment. */
+function shortTabId({ id }, _optional = {}) {
+    return id.slice(id.lastIndexOf('.') + 1);
+}
+function libraryFilter({ id }, _optional = {}) {
+    return id === 'all' || id === 'images' || id === 'videos' ? id : undefined;
+}
+function visibleTabs({ description, tabId }, _optional = {}) {
+    const visible = description.visible
+        ? description.tabs.filter((tab) => tab.visible)
+        : [];
+    const requested = resolveActiveTab({ tabId });
+    return { visible, active: visible.find((tab) => tab.id.endsWith(`.${requested}`)) ?? visible[0] };
+}
 function requestedFilter({ tabId }) {
     const tab = resolveActiveTab({ tabId });
     return tab === 'external-providers' ? 'all' : tab;