@jini-ai/admin 0.3.10 → 0.4.0

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

@@ -0,0 +1,84 @@
+import type { MediaApiPort } from '../../ports.js';
+import type { MediaAsset, MediaMetadataPatch, UploadInput } from '../../models.js';
+export interface EditMediaPanelProps {
+    readonly api: MediaApiPort;
+    readonly item: MediaAsset;
+    readonly onSaved: (required?: {
+        message?: string;
+    }) => void | Promise<void>;
+    readonly onClose: () => void;
+}
+export declare function useEditMediaPanel(props: EditMediaPanelProps, _optional?: Record<string, never>): {
+    snapshot: Readonly<{
+        draft: MediaMetadataPatch;
+        saving: boolean;
+        error: string | null;
+    }> | null;
+    fields: {
+        value: string;
+        attrs: {
+            'aria-invalid'?: boolean;
+            'data-jini-autofocus'?: boolean;
+            'data-jini-part': string;
+            'data-agent-element': string;
+        };
+        onValueChange: ({ value }: {
+            value: string;
+        }, _optional?: Record<string, never>) => void;
+        placeholder?: string;
+        type: "number" | "text";
+        ref?: import("react").RefObject<HTMLInputElement | null>;
+        fieldId: string;
+        label: string;
+    }[];
+    fieldRows: {
+        id: number;
+        className: string;
+        fields: {
+            value: string;
+            attrs: {
+                'aria-invalid'?: boolean;
+                'data-jini-autofocus'?: boolean;
+                'data-jini-part': string;
+                'data-agent-element': string;
+            };
+            onValueChange: ({ value }: {
+                value: string;
+            }, _optional?: Record<string, never>) => void;
+            placeholder?: string;
+            type: "number" | "text";
+            ref?: import("react").RefObject<HTMLInputElement | null>;
+            fieldId: string;
+            label: string;
+        }[];
+    }[];
+    copies: {
+        isLink: boolean;
+        buttonLabel: string;
+        attrs: {
+            'data-agent-element': string;
+            'aria-label': string;
+        };
+        copy(): Promise<void>;
+        id: string;
+        label: string;
+        value: string;
+        noun: string;
+    }[];
+    hint: string | null;
+    saving: boolean;
+    title: string;
+    canReplace: boolean;
+    onSave(): Promise<void>;
+    replace({ input }: {
+        input: UploadInput;
+    }, _optional?: Record<string, never>): Promise<boolean>;
+    close(): void;
+    api: MediaApiPort;
+    item: MediaAsset;
+    onSaved: (required?: {
+        message?: string;
+    }) => void | Promise<void>;
+    onClose: () => void;
+};
+//# sourceMappingURL=EditMediaPanel.hooks.d.ts.map

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

@@ -0,0 +1,105 @@
+import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { useController } from '../../../react/use-controller.js';
+import { createEditMediaController } from '../../controllers/edit-media.controller.js';
+import { canReplaceMedia, mediaEmbedSnippet, parseOptionalPixelSize, safeMediaUrl } from '../../rules.js';
+import { parseMediaHtmlAttributes, describeMediaHtmlAttributeError } from '../../html-attributes.js';
+export function useEditMediaPanel(props, _optional = {}) {
+    const { controller, snapshot } = useController({
+        create: () => createEditMediaController({ api: props.api, item: props.item }),
+        dependencies: [props.api, props.item.id],
+    });
+    const [copied, setCopied] = useState({});
+    const timers = useRef(new Map());
+    const mounted = useRef(false);
+    useEffect(() => {
+        mounted.current = true;
+        return () => { mounted.current = false; for (const timer of timers.current.values())
+            clearTimeout(timer); timers.current.clear(); };
+    }, []);
+    const saving = !snapshot || snapshot.saving;
+    const titleRef = useRef(null);
+    const ready = !!snapshot;
+    useLayoutEffect(() => {
+        // The controller attaches after the first render. Title is initially disabled;
+        // focus it once the draft is ready, rather than letting a later copy button win.
+        if (!ready)
+            return;
+        titleRef.current?.focus({ preventScroll: true });
+        const dialog = titleRef.current?.closest('dialog');
+        if (dialog)
+            dialog.scrollTop = 0;
+    }, [ready]);
+    // Live hint ONLY: invalid attributes must never gate saving unrelated dirty metadata.
+    // The server revalidates atomically and reports errors through the usual save banner.
+    const parsed = parseMediaHtmlAttributes({ text: snapshot?.draft.htmlAttributes ?? '' });
+    const hint = parsed.error ? describeMediaHtmlAttributeError({ error: parsed.error }) : null;
+    const fields = [
+        { key: 'title', label: 'Title', handle: 'title' },
+        { key: 'alt', label: 'Alt', handle: 'alt' },
+        { key: 'slug', label: 'Slug', handle: 'slug' },
+        { key: 'caption', label: 'Caption', handle: 'caption' },
+        { key: 'credit', label: 'Credit', handle: 'credit' },
+        { key: 'width', label: 'Width (px)', handle: 'width' },
+        { key: 'height', label: 'Height (px)', handle: 'height' },
+        { key: 'cssClass', label: 'CSS class (optional)', handle: 'css-class' },
+        { key: 'htmlAttributes', label: 'HTML attributes (optional)', handle: 'html-attributes' },
+    ].map(({ key, label, handle }) => ({
+        fieldId: key, label, ...(key === 'title' ? { ref: titleRef } : {}), type: key === 'width' || key === 'height' ? 'number' : 'text',
+        ...(key === 'width' || key === 'height' ? { placeholder: 'native' } : {}),
+        value: String(snapshot?.draft[key] ?? ''),
+        attrs: { 'data-jini-part': `media.editor.${key}`, 'data-agent-element': `media-edit-${handle}`,
+            ...(key === 'title' ? { 'data-jini-autofocus': true } : {}),
+            ...(key === 'htmlAttributes' ? { 'aria-invalid': !!hint } : {}) },
+        onValueChange: ({ value }, _optional = {}) => {
+            const next = key === 'width' || key === 'height' ? parseOptionalPixelSize({ value })
+                : key === 'cssClass' || key === 'htmlAttributes' ? value.trim() === '' ? null : value : value;
+            controller?.setDraft({ patch: { [key]: next } });
+        },
+    }));
+    // Server-computed public URL, never the authenticated original route. Trashed assets
+    // and hosts without a public transform expose no link or copy action at all.
+    const publicUrl = props.item.status === 'active' && props.item.publicUrl
+        ? safeMediaUrl({ url: props.item.publicUrl }) : undefined;
+    const embed = mediaEmbedSnippet({ slug: props.item.slug });
+    // Visible text is the legacy "Copy"/"Copied" on every row; the accessible name keeps
+    // the value's noun so three identical buttons stay distinguishable, even mid-feedback.
+    const copies = [
+        { id: 'url', label: 'File URL', value: publicUrl, noun: 'URL' },
+        { id: 'embed', label: 'Embed code', value: embed, noun: 'embed code' },
+        { id: 'hash', label: 'sha256', value: props.item.sha256, noun: 'hash' },
+    ].filter((row) => !!row.value)
+        .map(row => ({ ...row, isLink: row.id === 'url', buttonLabel: copied[row.id] ? 'Copied' : 'Copy',
+        attrs: { 'data-agent-element': `media-edit-copy-${row.id}`,
+            'aria-label': `${copied[row.id] ? 'Copied' : 'Copy'} ${row.noun}` },
+        async copy() {
+            try {
+                await navigator.clipboard.writeText(row.value);
+                if (!mounted.current)
+                    return;
+                setCopied(current => ({ ...current, [row.id]: true }));
+                clearTimeout(timers.current.get(row.id));
+                timers.current.set(row.id, setTimeout(() => {
+                    timers.current.delete(row.id);
+                    setCopied(current => ({ ...current, [row.id]: false }));
+                }, 1500));
+            }
+            catch {
+                // Clipboard may be denied/insecure. The full value stays selectable for manual copy.
+            }
+        },
+    }));
+    const fieldRows = [[0, 1], [2], [3, 4], [5, 6], [7], [8]].map((indexes, index) => ({ id: index, className: indexes.length > 1 ? 'jini-field-row' : 'jini-field-group-row', fields: indexes.map(i => fields[i]) }));
+    return { ...props, snapshot, fields, fieldRows, copies, hint, saving, title: `Editing "${props.item.title}"`,
+        canReplace: canReplaceMedia({ api: props.api }),
+        async onSave() { if (await controller?.save())
+            await props.onSaved(); },
+        async replace({ input }, _optional = {}) {
+            const result = (await controller?.replace({ upload: input })) ?? false;
+            if (result)
+                await props.onSaved({ message: `Replaced ${props.item.title}` });
+            return result;
+        },
+        close() { if (!saving)
+            props.onClose(); }, };
+}
+//# sourceMappingURL=EditMediaPanel.hooks.js.map

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

@@ -0,0 +1,103 @@
+import type { TabViewProps } from '../../../react/bind-react.js';
+import { createLibraryController } from '../../controllers/library.controller.js';
+import type { MediaAsset } from '../../models.js';
+export declare function useLibraryTab({ params, permissions }: TabViewProps, _optional?: Record<string, never>): {
+    emptyLabel: string;
+    canUpload: boolean;
+    success: string | null;
+    gridRef: import("react").RefObject<HTMLDivElement | null>;
+    onRetry: () => void;
+    statusFilter: string;
+    onStatus: ({ value }: {
+        value: string;
+    }) => void;
+    canPurge: boolean;
+    controller: {
+        getSnapshot: () => Readonly<import("../../index.js").LibraryState>;
+        subscribe: ({ listener }: {
+            listener: () => void;
+        }) => () => void;
+        load: (_required?: Record<string, never>, _optional?: Record<string, never>) => Promise<void>;
+        setQuery({ query }: {
+            query: import("../../models.js").MediaQuery;
+        }, _optional?: Record<string, never>): Promise<void>;
+        upload({ input, alt }: {
+            input: import("../../models.js").UploadInput;
+            alt?: string;
+        }, _optional?: Record<string, never>): Promise<boolean>;
+        trash({ id }: {
+            id: string;
+        }, _optional?: Record<string, never>): Promise<boolean>;
+        restore({ id }: {
+            id: string;
+        }, _optional?: Record<string, never>): Promise<boolean>;
+        requestPurge({ item }: {
+            item: MediaAsset;
+        }, _optional?: Record<string, never>): void;
+        cancelPurge(_required?: Record<string, never>, _optional?: Record<string, never>): void;
+        confirmPurge({ confirmed }: {
+            confirmed: boolean;
+        }, _optional?: Record<string, never>): Promise<boolean>;
+        dispose(_required?: Record<string, never>, _optional?: Record<string, never>): void;
+    } | null;
+    snapshot: import("../../index.js").LibraryState | null;
+    actions: {
+        onPurge?: () => void | undefined;
+        onRestore?: () => void;
+        onTrash?: () => void;
+        onPreview: () => void;
+        onEdit?: () => void;
+        item: MediaAsset;
+        busy: boolean;
+    }[];
+    items: readonly MediaAsset[];
+    mediaApi: import("../../ports.js").MediaApiPort;
+    editing: MediaAsset | null;
+    closeEdit: () => void;
+    saved: ({ message }?: {
+        message?: string;
+    }) => Promise<void>;
+    lightboxIndex: number | null;
+    onNavigate: import("react").Dispatch<import("react").SetStateAction<number | null>>;
+    closeLightbox: () => void;
+    onSearch: ({ value: search }: {
+        value: string;
+    }) => void;
+    orderBy: import("../../models.js").MediaOrderBy;
+    onOrder: ({ value }: {
+        value: string;
+    }) => void;
+    onOrderCreated: () => void;
+    onOrderAlphabetical: () => void;
+    search: string;
+    loading: boolean;
+    busy: boolean;
+    untyped: boolean;
+    upload({ input, alt }: Parameters<ReturnType<typeof createLibraryController>["upload"]>[0]): Promise<boolean>;
+    cancelPurge: () => void | undefined;
+    confirmPurge: () => Promise<void> | undefined;
+    t: {
+        readonly media: "Media";
+        readonly all: "All";
+        readonly images: "Images";
+        readonly videos: "Videos";
+        readonly providers: "External Providers";
+        readonly upload: "Upload";
+        readonly title: "Title";
+        readonly alt: "Alt text";
+        readonly save: "Save";
+        readonly cancel: "Cancel";
+        readonly empty: "No media found";
+        readonly loading: "Loading media…";
+        readonly choose: "Choose media";
+        readonly trash: "Trash";
+        readonly purge: "Delete permanently";
+        readonly purgeWarning: "This permanently deletes the file. This cannot be undone.";
+        readonly edit: "Edit metadata";
+        readonly preview: "View larger";
+        readonly replace: "Replace file";
+        readonly unavailable: "Provider service unavailable";
+        readonly untyped: "Some assets have no recorded content type and only appear under All.";
+    };
+};
+//# sourceMappingURL=LibraryTab.hooks.d.ts.map

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

@@ -0,0 +1,164 @@
+import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { useController } from '../../../react/use-controller.js';
+import { createLibraryController } from '../../controllers/library.controller.js';
+import { useSharedMediaLibrary } from './MediaPage.hooks.js';
+import { useMediaPorts } from './MediaPorts.hooks.js';
+import { mediaMessagesEn } from '../../messages.en.js';
+import { canRestoreMedia } from '../../rules.js';
+export function useLibraryTab({ params, permissions = [] }, _optional = {}) {
+    const { mediaApi, mediaEvents } = useMediaPorts();
+    const filter = params.filter === 'images' || params.filter === 'videos' ? params.filter : 'all';
+    const shared = useSharedMediaLibrary();
+    const local = useController({
+        create: () => createLibraryController({ api: mediaApi }, { query: { filter } }),
+        dependencies: [mediaApi, filter],
+    }, {
+        start: ({ controller }) => {
+            if (!shared)
+                void controller.load();
+        },
+    });
+    const { controller, snapshot } = shared ?? local;
+    useEffect(() => !shared ? mediaEvents?.subscribe({ onRefresh: () => { void controller?.load(); } }) : undefined, [mediaEvents, controller, shared]);
+    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]);
+    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.
+        if (controller?.getSnapshot().error && !controller.getSnapshot().loading)
+            void controller.load();
+    }, [controller]);
+    const [editing, setEditing] = useState(null);
+    // Lightbox — an index into the list, not the item itself, so arrow-key/navigation
+    // buttons move the number without re-deriving "what's next" from an item reference.
+    const [lightboxIndex, setLightboxIndex] = useState(null);
+    const items = snapshot?.items ?? [];
+    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: snapshot?.pendingIds.includes(item.id) ?? false,
+        ...(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 }) } : {}),
+    }));
+    function closeEdit() {
+        setEditing(null);
+    }
+    async function saved({ message } = {}) {
+        const item = editing;
+        closeEdit();
+        // Reread the authoritative version after replacement before announcing completion;
+        // both card and lightbox obtain their versioned byte URL from the refreshed rows.
+        await controller?.load();
+        if (message)
+            setSuccess(message);
+        if (item)
+            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,
+        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,
+        controller,
+        snapshot,
+        actions,
+        items,
+        mediaApi,
+        editing,
+        closeEdit,
+        saved,
+        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' } });
+        },
+        onOrderCreated: () => {
+            void controller?.setQuery({
+                query: { ...controller.getSnapshot().query, orderBy: 'created' },
+            });
+        },
+        onOrderAlphabetical: () => {
+            void controller?.setQuery({
+                query: { ...controller.getSnapshot().query, orderBy: 'alphabetical' },
+            });
+        },
+        search: snapshot?.query.search ?? '',
+        loading: !snapshot || (snapshot.items === null && snapshot.loading && !snapshot.error),
+        busy: snapshot?.busy ?? false,
+        untyped: filter !== 'all' && snapshot?.hasUntyped === true,
+        async upload({ input, alt }) {
+            if (!canUpload)
+                return false;
+            const result = await controller?.upload({ input, ...(alt === undefined ? {} : { alt }) }) ?? false;
+            if (result)
+                gridRef.current?.focus({ preventScroll: true });
+            return result;
+        },
+        cancelPurge: () => controller?.cancelPurge(),
+        confirmPurge: () => {
+            if (!canPurge || !controller)
+                return;
+            const item = controller.getSnapshot().pendingPurge;
+            const index = items.findIndex(row => row.id === item?.id);
+            return controller.confirmPurge({ confirmed: true }).then(saved => {
+                if (saved) {
+                    setSuccess(item ? `Deleted permanently ${item.title}` : 'Deleted permanently');
+                    setFocusAfterPurge(Math.max(0, index));
+                }
+            });
+        },
+        t: mediaMessagesEn,
+    };
+}
+//# sourceMappingURL=LibraryTab.hooks.js.map

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

@@ -0,0 +1,79 @@
+import type { MediaAsset } from '../../models.js';
+import type { MediaApiPort } from '../../ports.js';
+export interface MediaCardProps {
+    readonly item: MediaAsset;
+    readonly handleBase?: string;
+    readonly api: MediaApiPort;
+    readonly busy?: boolean;
+    readonly onEdit?: () => void;
+    readonly onPreview?: () => void;
+    readonly onTrash?: () => void;
+    readonly onRestore?: () => void;
+    readonly onPurge?: () => void;
+    readonly onChoose?: () => void;
+}
+export declare function useMediaCard(props: MediaCardProps, _optional?: Record<string, never>): {
+    busy: boolean;
+    byteSize: string | null;
+    preview: () => void | undefined;
+    canPreview: boolean;
+    imagePreview: boolean;
+    handles: {
+        expand: string;
+        edit: string;
+        menu: string;
+    };
+    previewAttrs: {
+        'data-jini-part': string;
+        'data-agent-element': string;
+        'data-agent-label': string;
+        'aria-label': string;
+    };
+    editAttrs: {
+        'data-jini-part': string;
+        'data-agent-element': string;
+        'data-agent-label': string;
+        'aria-label': string;
+    };
+    menuLabel: string;
+    menuAttrs: {
+        '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: "image" | "video" | "unsupported";
+    image: boolean | "" | undefined;
+    video: boolean | "" | undefined;
+    onImageError: () => void;
+    onVideoError: () => void;
+    alt: string;
+    statusClassName: string;
+    statusLabel: "active" | "trashed";
+    statusTone: "success" | "warning";
+    trashed: boolean;
+    item: MediaAsset;
+    handleBase?: string;
+    api: MediaApiPort;
+    onEdit?: () => void;
+    onPreview?: () => void;
+    onTrash?: () => void;
+    onRestore?: () => void;
+    onPurge?: () => void;
+    onChoose?: () => void;
+};
+//# sourceMappingURL=MediaCard.hooks.d.ts.map

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

@@ -0,0 +1,63 @@
+import { useState } from 'react';
+import { safeMediaUrl, formatByteSize, mediaRowHandles } from '../../rules.js';
+export function useMediaCard(props, _optional = {}) {
+    /** Historical preview rationale, retained with the ported fallback chain:
+   * The hard problem this rewrite had to solve: **the media list response carried no content type**
+   * (neither `media` nor `asset_blobs` stored one — upload validated `contentType` then discarded
+   * it), so nothing in `AdminMedia` told the client whether a given asset was an image, a video, or
+   * something unpreviewable. `MediaPreview` below resolves this client-side with an optimistic
+   * render-and-fall-back chain (`<img>` → onError → `<video>` → onError → placeholder) rather than a
+   * HEAD probe per card. Chosen over the HEAD approach because: (1) the byte route's documented
+   * contract covers GET — sniffing/Range were specified for that, not for HEAD, so building on HEAD
+   * would be assuming a behavior nobody confirmed; (2) a HEAD-first design means every card blocks on
+   * a round trip before any pixel paints, working against the fixed-aspect-box + lazy-loading this
+   * grid needs anyway, whereas the optimistic path costs nothing extra for the common case (a real
+   * image just loads) and only "wastes" a request for the video/unsupported minority — and even then,
+   * a browser's image decoder typically fails off the header bytes rather than pulling the whole
+   * file; (3) it composes for free with the server's security defusal: a sniffed HTML/SVG comes back
+   * as `application/octet-stream` with `Content-Disposition: attachment`, which is not a valid image
+   * OR video MIME, so it fails both probes and lands on the placeholder with zero special-casing —
+   * this file never needs to detect "is this the defused case" itself.
+     */
+    const src = safeMediaUrl({ url: props.api.originalUrl({ id: props.item.id, version: props.item.version }) });
+    const [probe, setProbe] = useState({ src, stage: 'image' });
+    // New bytes can change media type under the same id. Retry the fallback from image
+    // 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];
+    return {
+        ...props,
+        busy: props.busy === true,
+        byteSize: props.item.byteSize === undefined ? null : formatByteSize({ bytes: props.item.byteSize }),
+        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 is owner-requested beyond legacy; it lives only in a trashed card's menu, so
+            // the card itself keeps the legacy look and active cards' menus stay legacy-identical.
+            ...(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 }] : []),
+        ],
+        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',
+    };
+}
+//# sourceMappingURL=MediaCard.hooks.js.map

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

@@ -0,0 +1,10 @@
+import type { RefObject } from 'react';
+import type { DialogProps } from '@jini-ai/ui-kit/react';
+export interface MediaDialogProps extends Omit<DialogProps, 'ref'> {
+    readonly dialogRef?: RefObject<HTMLDialogElement | null>;
+}
+export declare function useMediaDialog(props: MediaDialogProps, _optional?: Record<string, never>): {
+    open: boolean;
+    dialogProps: DialogProps;
+};
+//# sourceMappingURL=MediaDialog.hooks.d.ts.map

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

@@ -0,0 +1,20 @@
+import { useLayoutEffect, useRef } from 'react';
+export function useMediaDialog(props, _optional = {}) {
+    const localRef = useRef(null);
+    const ref = props.dialogRef ?? localRef;
+    useLayoutEffect(() => {
+        const dialog = ref.current;
+        if (!props.open || !dialog)
+            return;
+        // The kit default contributes a Close even when a feature provides its guarded,
+        // agent-addressable Cancel/Close. Hide only that known default marker; custom kit
+        // views keep their own structure. Retain the kit's modal/pending/focus lifecycle.
+        const duplicate = dialog.querySelector('[data-jini-part="kit.dialog-close"]');
+        if (duplicate)
+            duplicate.hidden = true;
+        dialog.querySelector('[data-jini-autofocus]')?.focus({ preventScroll: true });
+        dialog.scrollTop = 0;
+    }, [props.open, ref]);
+    return { open: props.open, dialogProps: { ...props, ref } };
+}
+//# sourceMappingURL=MediaDialog.hooks.js.map

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

@@ -0,0 +1,28 @@
+import type { Ref } from 'react';
+import type { MediaCardProps } from './MediaCard.hooks.js';
+export interface MediaGridProps {
+    readonly gridRef?: Ref<HTMLDivElement>;
+    readonly actions: readonly Omit<MediaCardProps, 'api'>[];
+    readonly api: MediaCardProps['api'];
+    readonly busy?: boolean;
+    readonly emptyLabel?: string;
+}
+export declare function useMediaGrid(props: MediaGridProps, _optional?: Record<string, never>): {
+    actions: {
+        handleBase: string;
+        busy?: boolean;
+        item: import("../../models.js").MediaAsset;
+        onEdit?: () => void;
+        onPreview?: () => void;
+        onTrash?: () => void;
+        onRestore?: () => void;
+        onPurge?: () => void;
+        onChoose?: () => void;
+    }[];
+    gridRef?: Ref<HTMLDivElement>;
+    api: MediaCardProps["api"];
+    busy?: boolean;
+    emptyLabel?: string;
+    className: string;
+};
+//# sourceMappingURL=MediaGrid.hooks.d.ts.map