@vamos-ui/react 0.0.0-stage → 0.2.0

package/dist/media/media-picker.d.ts

@@ -0,0 +1,96 @@
+import * as React from "react";
+import { type MediaLibraryLabels } from "./media-library.js";
+import type { MediaAdapter, MediaAsset } from "./types.js";
+declare const pickerLabels: {
+    title: string;
+    titleImage: string;
+    titleImages: string;
+    library: string;
+    upload: string;
+    url: string;
+    uploadTitle: string;
+    uploadHint: string;
+    uploadButton: string;
+    uploadAccept: string;
+    urlLabel: string;
+    urlHint: string;
+    urlPlaceholder: string;
+    urlImport: string;
+    urlImporting: string;
+    urlError: string;
+    cancel: string;
+    confirm: string;
+    confirmImage: string;
+    selected: string;
+    maxHint: string;
+    remove: string;
+    more: string;
+    altTitle: string;
+    altDescription: string;
+    altFor: string;
+    decorative: string;
+    shortcut: string;
+};
+export type MediaPickerLabels = typeof pickerLabels;
+export type MediaPickerTab = "library" | "upload" | "url";
+export interface MediaPickerProps {
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** Else from `MediaProvider`. */
+    adapter?: MediaAdapter;
+    multiple?: boolean;
+    /** Selection limit with `multiple`. */
+    max?: number;
+    /** `"image/*"`: library filter and upload restriction. */
+    accept?: string;
+    /** Preselected asset ids. */
+    value?: string[];
+    /** Called with the chosen assets on confirm (alt text already saved when `requireAlt`). */
+    onSelect?: (assets: MediaAsset[]) => void;
+    /** Dialog title. Default "Select image(s)" / "Select media". */
+    title?: string;
+    /** Confirm button text ("Set featured image"). Default is pluralised: "Insert 2 images". */
+    confirmLabel?: string;
+    /** Tabs to show, in order. Default library + upload (+ "url" when the adapter can sideload). */
+    tabs?: MediaPickerTab[];
+    /** Ask for alt text on images that have none before confirming. */
+    requireAlt?: boolean;
+    /** `md` 720px · `lg` 1080px (with details panel) · `full`. Default `"lg"`. */
+    size?: "md" | "lg" | "full";
+    /** Optional trigger (rendered as `DialogTrigger asChild`). */
+    children?: React.ReactNode;
+    labels?: Partial<MediaPickerLabels>;
+    libraryLabels?: Partial<MediaLibraryLabels>;
+}
+/**
+ * A dialog that picks one or more files for a field: featured image, gallery blocks, logos,
+ * profile photos, attachments. Library, Upload and From URL tabs; new uploads are selected
+ * automatically; optional alt-text check before confirming. ⌘/Ctrl + Enter confirms.
+ *
+ * ```tsx
+ * <MediaPicker accept="image/*" confirmLabel="Set featured image" onSelect={([asset]) => setCover(asset)}>
+ *   <Button>Choose image</Button>
+ * </MediaPicker>
+ * ```
+ */
+export declare function MediaPicker({ open: openProp, defaultOpen, onOpenChange, adapter: adapterProp, multiple, max, accept, value, onSelect, title, confirmLabel, tabs: tabsProp, requireAlt, size, children, labels, libraryLabels, }: MediaPickerProps): React.JSX.Element;
+export type MediaPickOptions = Omit<MediaPickerProps, "open" | "defaultOpen" | "onOpenChange" | "onSelect" | "children">;
+type PickFn = (options?: MediaPickOptions) => Promise<MediaAsset[]>;
+/**
+ * Hosts one Media picker for `useMediaPicker()`. Put it once near the app root, inside `MediaProvider`.
+ */
+export declare function MediaPickerProvider({ children, adapter }: {
+    children: React.ReactNode;
+    adapter?: MediaAdapter;
+}): React.JSX.Element;
+/**
+ * Opens the picker from code and resolves with the chosen assets (`[]` when cancelled).
+ *
+ * ```ts
+ * const pick = useMediaPicker();
+ * const [logo] = await pick({ accept: "image/*", confirmLabel: "Use as logo" });
+ * ```
+ */
+export declare function useMediaPicker(): PickFn;
+export {};

package/dist/media/media-picker.js

@@ -0,0 +1,209 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { Link2, TriangleAlert, Upload, X } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { useLabels } from "../lib/labels.js";
+import { useFormat } from "../lib/locale.js";
+import { useControllableState } from "../lib/use-controllable-state.js";
+import { FieldContextReset } from "../lib/field-context.js";
+import { Alert } from "../components/alert.js";
+import { Button } from "../components/button.js";
+import { Checkbox } from "../components/checkbox.js";
+import { Dialog, DialogBody, DialogContent, DialogFooter, DialogHeader, DialogTrigger } from "../components/dialog.js";
+import { Input } from "../components/input.js";
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "../components/tabs.js";
+import { MediaLibrary, MediaThumb } from "./media-library.js";
+import { useMedia } from "./media-provider.js";
+import { DECORATIVE_TAG, isAltMissing } from "./media-utils.js";
+const pickerLabels = {
+    title: "Select media",
+    titleImage: "Select image",
+    titleImages: "Select images",
+    library: "Library",
+    upload: "Upload",
+    url: "From URL",
+    uploadTitle: "Drop files to upload",
+    uploadHint: "or choose them from your computer. They are added to the library and selected.",
+    uploadButton: "Choose files",
+    uploadAccept: "Accepted: {accept}",
+    urlLabel: "File URL",
+    urlHint: "Paste a link to an image or file. It is copied into the library.",
+    urlPlaceholder: "https://",
+    urlImport: "Import",
+    urlImporting: "Importing…",
+    urlError: "That URL couldn't be imported. Check the link and try again.",
+    cancel: "Cancel",
+    confirm: "{count, plural, =0 {Insert} one {Insert file} other {Insert # files}}",
+    confirmImage: "{count, plural, =0 {Insert} one {Insert image} other {Insert # images}}",
+    selected: "{count, plural, =0 {Nothing selected} one {# selected} other {# selected}}",
+    maxHint: "Up to {max}",
+    remove: "Remove {name} from selection",
+    more: "+{count}",
+    altTitle: "{count, plural, one {An image needs alt text} other {# images need alt text}}",
+    altDescription: "Describe each image, or mark it as decorative.",
+    altFor: "Alt text for {name}",
+    decorative: "Decorative",
+    shortcut: "Ctrl + Enter to confirm",
+};
+/**
+ * A dialog that picks one or more files for a field: featured image, gallery blocks, logos,
+ * profile photos, attachments. Library, Upload and From URL tabs; new uploads are selected
+ * automatically; optional alt-text check before confirming. ⌘/Ctrl + Enter confirms.
+ *
+ * ```tsx
+ * <MediaPicker accept="image/*" confirmLabel="Set featured image" onSelect={([asset]) => setCover(asset)}>
+ *   <Button>Choose image</Button>
+ * </MediaPicker>
+ * ```
+ */
+export function MediaPicker({ open: openProp, defaultOpen, onOpenChange, adapter: adapterProp, multiple = false, max, accept, value, onSelect, title, confirmLabel, tabs: tabsProp, requireAlt = false, size = "lg", children, labels, libraryLabels, }) {
+    const [open, setOpen] = useControllableState({ value: openProp, defaultValue: defaultOpen ?? false, onChange: onOpenChange, name: "MediaPicker" });
+    return (_jsxs(Dialog, { open: open, onOpenChange: setOpen, children: [children ? _jsx(DialogTrigger, { asChild: true, children: children }) : null, open ? (_jsx(MediaPickerContent, { adapter: adapterProp, multiple: multiple, max: max, accept: accept, value: value, title: title, confirmLabel: confirmLabel, tabs: tabsProp, requireAlt: requireAlt, size: size, labels: labels, libraryLabels: libraryLabels, onCancel: () => setOpen(false), onConfirm: (assets) => {
+                    onSelect?.(assets);
+                    setOpen(false);
+                } })) : null] }));
+}
+const SIZE_W = { md: "45rem", lg: "67.5rem", full: "none" };
+function MediaPickerContent({ adapter: adapterProp, multiple, max, accept, value, title, confirmLabel, tabs: tabsProp, requireAlt, size = "lg", labels, libraryLabels, onCancel, onConfirm }) {
+    const t = useLabels("mediaPicker", pickerLabels, labels);
+    const f = useFormat();
+    const ctx = useMedia();
+    const adapter = adapterProp ?? ctx;
+    const imagesOnly = Boolean(accept && accept.split(",").every((r) => r.trim().startsWith("image/")));
+    const tabs = tabsProp ?? ["library", "upload", ...(adapter?.sideload ? ["url"] : [])];
+    const [tab, setTab] = React.useState(tabs[0] ?? "library");
+    const [ids, setIds] = React.useState(value ?? []);
+    const [assets, setAssets] = React.useState(new Map());
+    const [altDrafts, setAltDrafts] = React.useState({});
+    const [decorative, setDecorative] = React.useState({});
+    const [saving, setSaving] = React.useState(false);
+    const library = React.useRef(null);
+    const searchRef = React.useRef(null);
+    // Preselected ids the library hasn't loaded yet.
+    React.useEffect(() => {
+        if (!adapter || !value?.length)
+            return;
+        const load = adapter.getMany ? adapter.getMany(value) : Promise.all(value.map((id) => adapter.get(id)));
+        load.then((list) => setAssets((m) => new Map([...m, ...list.map((a) => [a.id, a])]))).catch(() => { });
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [adapter]);
+    const chosen = ids.map((id) => assets.get(id)).filter((a) => Boolean(a));
+    const needsAlt = requireAlt ? chosen.filter((a) => isAltMissing(a) && !decorative[a.id]) : [];
+    const unresolved = needsAlt.filter((a) => !(altDrafts[a.id] ?? "").trim());
+    const canConfirm = chosen.length > 0 && unresolved.length === 0 && !saving;
+    const confirm = async () => {
+        if (!canConfirm)
+            return;
+        let out = chosen;
+        if (requireAlt && adapter) {
+            setSaving(true);
+            try {
+                out = await Promise.all(chosen.map(async (a) => {
+                    if (decorative[a.id])
+                        return adapter.update(a.id, { alt: "", tags: [...(a.tags ?? []).filter((x) => x !== DECORATIVE_TAG), DECORATIVE_TAG] });
+                    const draft = altDrafts[a.id]?.trim();
+                    return draft && isAltMissing(a) ? adapter.update(a.id, { alt: draft }) : a;
+                }));
+            }
+            finally {
+                setSaving(false);
+            }
+        }
+        onConfirm(out);
+    };
+    const dialogTitle = title ?? (imagesOnly ? (multiple ? t("titleImages") : t("titleImage")) : t("title"));
+    const buttonText = confirmLabel ?? t(imagesOnly ? "confirmImage" : "confirm", { count: chosen.length });
+    const tabLabel = { library: t("library"), upload: t("upload"), url: t("url") };
+    const onFiles = (files) => {
+        if (!files?.length)
+            return;
+        library.current?.addFiles(files);
+        setTab("library");
+    };
+    return (_jsx(DialogContent, { size: size === "full" ? "full" : "xl", mobile: "fullscreen", className: "vui-media-picker", style: { "--dialog-w": SIZE_W[size] }, onOpenAutoFocus: (e) => {
+            e.preventDefault();
+            searchRef.current?.focus();
+        }, onKeyDown: (e) => {
+            if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) {
+                e.preventDefault();
+                void confirm();
+            }
+        }, children: _jsxs(FieldContextReset, { children: [_jsx(DialogHeader, { title: dialogTitle }), _jsxs(Tabs, { value: tab, onValueChange: (v) => setTab(v), className: "flex min-h-0 flex-1 flex-col", children: [tabs.length > 1 ? (_jsx(TabsList, { className: "mx-6 shrink-0", children: tabs.map((k) => (_jsx(TabsTrigger, { value: k, children: tabLabel[k] }, k))) })) : null, _jsxs(DialogBody, { flush: true, className: "flex min-h-0 flex-1 flex-col", children: [_jsx(TabsContent, { value: "library", forceMount: true, className: "min-h-0 flex-1 p-4 data-[state=inactive]:hidden", children: _jsx(MediaLibrary, { handleRef: library, adapter: adapter, searchRef: searchRef, selection: multiple ? "multiple" : "single", max: multiple ? max : undefined, accept: accept, selected: ids, onSelectedChange: (next, list) => {
+                                            setIds(next);
+                                            setAssets((m) => new Map([...m, ...list.map((a) => [a.id, a])]));
+                                        }, selectUploaded: true, detailsPanel: size === "md" ? false : "side", height: "min(30rem, 52dvh)", labels: libraryLabels, className: "shadow-none" }) }), tabs.includes("upload") ? (_jsx(TabsContent, { value: "upload", className: "p-4", children: _jsx(PickerDropzone, { accept: accept, multiple: Boolean(multiple), onFiles: onFiles, t: t }) })) : null, tabs.includes("url") && adapter?.sideload ? (_jsx(TabsContent, { value: "url", className: "p-6", children: _jsx(PickerUrlForm, { adapter: adapter, t: t, onImported: (asset) => {
+                                            setAssets((m) => new Map(m).set(asset.id, asset));
+                                            library.current?.addAssets([asset], { select: true });
+                                            setTab("library");
+                                        } }) })) : null] })] }), needsAlt.length ? (_jsxs("div", { "data-slot": "media-picker-alt", className: "border-t border-line px-6 py-3", children: [_jsx(Alert, { tone: "warning", title: t("altTitle", { count: needsAlt.length }), children: t("altDescription") }), _jsx("ul", { className: "mt-3 grid max-h-40 gap-2 overflow-y-auto", children: needsAlt.map((a) => (_jsxs("li", { className: "grid grid-cols-[2.25rem_minmax(0,1fr)_auto] items-center gap-3", children: [_jsx("span", { className: "size-9 overflow-hidden rounded-ui-sm ring-1 ring-line", children: _jsx(MediaThumb, { asset: a, rounded: "none" }) }), _jsx(Input, { size: "sm", "aria-label": t("altFor", { name: a.filename }), placeholder: a.filename, value: altDrafts[a.id] ?? "", onChange: (e) => setAltDrafts((d) => ({ ...d, [a.id]: e.target.value })) }), _jsx(Checkbox, { size: "sm", label: t("decorative"), checked: Boolean(decorative[a.id]), onCheckedChange: (c) => setDecorative((d) => ({ ...d, [a.id]: c === true })) })] }, a.id))) })] })) : null, _jsxs(DialogFooter, { align: "between", className: "gap-3", children: [_jsxs("div", { "data-slot": "media-picker-tray", className: "flex min-w-0 items-center gap-2", children: [chosen.length ? (_jsxs("ul", { "aria-label": t("selected", { count: chosen.length }), className: "flex items-center -space-x-1.5", children: [chosen.slice(0, 6).map((a) => (_jsxs("li", { className: "group/tray relative size-9 overflow-hidden rounded-ui-sm bg-surface-2 ring-2 ring-[var(--popover)]", children: [_jsx(MediaThumb, { asset: a, rounded: "none" }), _jsx("button", { type: "button", "aria-label": t("remove", { name: a.filename }), onClick: () => setIds((l) => l.filter((id) => id !== a.id)), className: "focus-ring absolute inset-0 flex items-center justify-center bg-[color-mix(in_srgb,var(--scene)_70%,transparent)] text-fg opacity-0 transition-opacity group-hover/tray:opacity-100 focus-visible:opacity-100", children: _jsx(X, { className: "size-3.5" }) })] }, a.id))), chosen.length > 6 ? _jsx("li", { className: "tabular flex size-9 items-center justify-center rounded-ui-sm bg-surface-2 text-[11.5px] text-fg-muted ring-2 ring-[var(--popover)]", children: t("more", { count: chosen.length - 6 }) }) : null] })) : null, _jsxs("span", { className: "tabular truncate text-[12.5px] text-fg-muted", children: [t("selected", { count: chosen.length }), multiple && max ? ` · ${t("maxHint", { max: f.number(max) })}` : null] })] }), _jsxs("div", { className: "flex items-center gap-2", children: [_jsx(Button, { onClick: onCancel, children: t("cancel") }), _jsx(Button, { variant: "primary", disabled: !canConfirm, loading: saving, onClick: () => void confirm(), "aria-keyshortcuts": "Control+Enter Meta+Enter", title: t("shortcut"), children: buttonText })] })] })] }) }));
+}
+function PickerDropzone({ accept, multiple, onFiles, t }) {
+    const input = React.useRef(null);
+    const [over, setOver] = React.useState(false);
+    return (_jsxs("div", { "data-slot": "media-picker-dropzone", "data-dragging": over ? "" : undefined, onDragOver: (e) => {
+            e.preventDefault();
+            setOver(true);
+        }, onDragLeave: () => setOver(false), onDrop: (e) => {
+            e.preventDefault();
+            setOver(false);
+            onFiles(e.dataTransfer.files);
+        }, className: cn("vui-media-dropzone flex min-h-72 flex-col items-center justify-center gap-3 rounded-ui border border-dashed border-field-border bg-surface-2 px-6 py-10 text-center transition-colors", over && "border-ring bg-accent-soft"), children: [_jsx("span", { className: "flex size-11 items-center justify-center rounded-full bg-surface text-fg-muted ring-1 ring-line", children: _jsx(Upload, { "aria-hidden": true, className: "size-5" }) }), _jsxs("div", { className: "grid gap-1", children: [_jsx("p", { className: "text-[15px] font-semibold text-fg", children: t("uploadTitle") }), _jsx("p", { className: "max-w-sm text-[13px] text-fg-muted", children: t("uploadHint") })] }), _jsx(Button, { variant: "secondary", onClick: () => input.current?.click(), children: t("uploadButton") }), accept ? _jsx("p", { className: "text-[12px] text-fg-subtle", children: t("uploadAccept", { accept }) }) : null, _jsx("input", { ref: input, type: "file", hidden: true, tabIndex: -1, "aria-hidden": true, accept: accept, multiple: multiple, onChange: (e) => {
+                    onFiles(e.target.files);
+                    e.target.value = "";
+                } })] }));
+}
+function PickerUrlForm({ adapter, onImported, t }) {
+    const [url, setUrl] = React.useState("");
+    const [state, setState] = React.useState("idle");
+    const id = React.useId();
+    const hintId = React.useId();
+    const valid = /^https?:\/\/\S+\.\S+/.test(url.trim());
+    const submit = async (e) => {
+        e.preventDefault();
+        if (!valid || !adapter.sideload)
+            return;
+        setState("loading");
+        try {
+            const asset = await adapter.sideload(url.trim(), { signal: new AbortController().signal, onProgress: () => { } });
+            setState("idle");
+            setUrl("");
+            onImported(asset);
+        }
+        catch {
+            setState("error");
+        }
+    };
+    return (_jsxs("form", { onSubmit: submit, className: "mx-auto grid max-w-xl gap-2 py-6", children: [_jsx("label", { htmlFor: id, className: "text-[13px] font-medium text-fg", children: t("urlLabel") }), _jsxs("div", { className: "flex gap-2", children: [_jsx(Input, { id: id, type: "url", inputMode: "url", leading: _jsx(Link2, { "aria-hidden": true }), placeholder: t("urlPlaceholder"), value: url, "aria-describedby": hintId, invalid: state === "error", onChange: (e) => setUrl(e.target.value), className: "flex-1" }), _jsx(Button, { type: "submit", variant: "secondary", disabled: !valid, loading: state === "loading", loadingText: t("urlImporting"), children: t("urlImport") })] }), _jsx("p", { id: hintId, className: cn("text-[12.5px]", state === "error" ? "text-danger" : "text-fg-muted"), children: state === "error" ? (_jsxs("span", { className: "inline-flex items-center gap-1.5", children: [_jsx(TriangleAlert, { "aria-hidden": true, className: "size-3.5" }), t("urlError")] })) : (t("urlHint")) })] }));
+}
+const PickerContext = React.createContext(null);
+/**
+ * Hosts one Media picker for `useMediaPicker()`. Put it once near the app root, inside `MediaProvider`.
+ */
+export function MediaPickerProvider({ children, adapter }) {
+    const [request, setRequest] = React.useState(null);
+    const pick = React.useCallback((options = {}) => new Promise((resolve) => setRequest({ options, resolve })), []);
+    return (_jsxs(PickerContext.Provider, { value: pick, children: [children, _jsx(MediaPicker, { adapter: adapter, ...request?.options, open: Boolean(request), onOpenChange: (o) => {
+                    if (!o && request) {
+                        request.resolve([]);
+                        setRequest(null);
+                    }
+                }, onSelect: (assets) => {
+                    request?.resolve(assets);
+                    setRequest(null);
+                } })] }));
+}
+/**
+ * Opens the picker from code and resolves with the chosen assets (`[]` when cancelled).
+ *
+ * ```ts
+ * const pick = useMediaPicker();
+ * const [logo] = await pick({ accept: "image/*", confirmLabel: "Use as logo" });
+ * ```
+ */
+export function useMediaPicker() {
+    const pick = React.useContext(PickerContext);
+    if (!pick)
+        throw new Error("useMediaPicker() needs a <MediaPickerProvider> above it.");
+    return pick;
+}

package/dist/media/media-provider.d.ts

@@ -0,0 +1,23 @@
+import * as React from "react";
+import type { MediaAdapter, MediaAsset, MediaItem, MediaSource } from "./types.js";
+/**
+ * Provides the media adapter to Media library, Media picker, Image field, Gallery and the editor.
+ * `VamosProvider media={adapter}` works too; this provider wins when both are set.
+ *
+ * ```tsx
+ * <MediaProvider adapter={createMemoryAdapter({ seed })}>…</MediaProvider>
+ * ```
+ */
+export declare function MediaProvider({ adapter, children }: {
+    adapter: MediaAdapter;
+    children: React.ReactNode;
+}): React.JSX.Element;
+/** The adapter from `MediaProvider`, else from `VamosProvider media`. */
+export declare function useMedia(): MediaAdapter | undefined;
+/** `true` for a full `MediaAsset` (has `id` + `url`). */
+export declare function isMediaAsset(item: unknown): item is MediaAsset;
+/** Normalises an asset or a plain source to the fields viewers need. */
+export declare function toMediaSource(item: MediaItem, index?: number): MediaSource & {
+    id: string;
+    kind: "image" | "video";
+};

package/dist/media/media-provider.js

@@ -0,0 +1,44 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { useMediaAdapter } from "../lib/provider.js";
+const MediaContext = React.createContext(undefined);
+/**
+ * Provides the media adapter to Media library, Media picker, Image field, Gallery and the editor.
+ * `VamosProvider media={adapter}` works too; this provider wins when both are set.
+ *
+ * ```tsx
+ * <MediaProvider adapter={createMemoryAdapter({ seed })}>…</MediaProvider>
+ * ```
+ */
+export function MediaProvider({ adapter, children }) {
+    return _jsx(MediaContext.Provider, { value: adapter, children: children });
+}
+/** The adapter from `MediaProvider`, else from `VamosProvider media`. */
+export function useMedia() {
+    const own = React.useContext(MediaContext);
+    const app = useMediaAdapter();
+    return own ?? app;
+}
+/** `true` for a full `MediaAsset` (has `id` + `url`). */
+export function isMediaAsset(item) {
+    return typeof item === "object" && item !== null && "url" in item && "id" in item && "mime" in item;
+}
+/** Normalises an asset or a plain source to the fields viewers need. */
+export function toMediaSource(item, index = 0) {
+    if (isMediaAsset(item)) {
+        return {
+            id: item.id,
+            src: item.url,
+            alt: item.alt,
+            width: item.width,
+            height: item.height,
+            caption: item.caption,
+            kind: item.kind === "video" ? "video" : "image",
+            placeholder: item.placeholder,
+            focalPoint: item.focalPoint,
+            poster: item.variants?.poster?.url ?? item.variants?.thumb?.url,
+        };
+    }
+    return { ...item, id: item.id ?? `${index}:${item.src}`, kind: item.kind ?? "image" };
+}

package/dist/media/media-utils.d.ts

@@ -0,0 +1,39 @@
+import type { MediaAsset, MediaKind } from "./types.js";
+/** MIME → the kit's media kind. */
+export declare function mediaKindOf(mime: string, filename?: string): MediaKind;
+/**
+ * `true` when a file or asset matches an `accept` string (`"image/*,.pdf,application/zip"`).
+ * An empty accept matches everything.
+ */
+export declare function acceptsMedia(accept: string | undefined, item: {
+    mime?: string;
+    type?: string;
+    filename?: string;
+    name?: string;
+}): boolean;
+/** Kinds an accept string allows (`"image/*"` → `["image"]`), or `undefined` when it is mixed/any. */
+export declare function kindsFromAccept(accept: string | undefined): MediaKind[] | undefined;
+/** `"2026-11-04T09:12:00Z"` → `"2026-11"`. */
+export declare const monthKey: (iso: string) => string;
+/** A `YYYY-MM` key as a Date in the middle of the month (no time-zone edge). */
+export declare const monthDate: (key: string) => Date;
+/** Short file extension label for tiles without a preview ("PDF", "DOCX"). */
+export declare function extensionOf(filename: string): string;
+/** Best small preview URL of an asset (thumb variant → medium → original), images only. */
+export declare function thumbUrl(asset: MediaAsset): string | undefined;
+/** Tag that marks an image as intentionally decorative (`alt=""` on purpose). */
+export declare const DECORATIVE_TAG = "decorative";
+export declare const isDecorative: (asset: MediaAsset) => boolean;
+/** Missing alt text matters for images only; `""` marked decorative (tag) is fine. */
+export declare function isAltMissing(asset: MediaAsset, alt?: string): boolean;
+export declare const clientId: (prefix?: string) => string;
+/** Reads an image file's pixel size (client only). */
+export declare function readImageSize(file: Blob): Promise<{
+    width: number;
+    height: number;
+} | null>;
+/**
+ * Downscales a raster image so its longer side is at most `maxDimension` (canvas, zero deps).
+ * Returns the original file for SVG/GIF, non-images, small images, or when canvas is unavailable.
+ */
+export declare function downscaleImage(file: File, maxDimension: number, quality?: number): Promise<File>;

package/dist/media/media-utils.js

@@ -0,0 +1,145 @@
+/** MIME → the kit's media kind. */
+export function mediaKindOf(mime, filename = "") {
+    const m = mime.toLowerCase();
+    if (m.startsWith("image/"))
+        return "image";
+    if (m.startsWith("video/"))
+        return "video";
+    if (m.startsWith("audio/"))
+        return "audio";
+    if (/pdf|word|sheet|excel|presentation|powerpoint|text|csv|rtf|opendocument/.test(m))
+        return "document";
+    if (/zip|tar|rar|7z|gzip|compressed/.test(m))
+        return "archive";
+    const ext = filename.toLowerCase().split(".").pop() ?? "";
+    if (["jpg", "jpeg", "png", "gif", "webp", "avif", "svg", "heic"].includes(ext))
+        return "image";
+    if (["pdf", "doc", "docx", "xls", "xlsx", "ppt", "pptx", "txt", "csv"].includes(ext))
+        return "document";
+    if (["zip", "rar", "7z", "tar", "gz"].includes(ext))
+        return "archive";
+    return "other";
+}
+/**
+ * `true` when a file or asset matches an `accept` string (`"image/*,.pdf,application/zip"`).
+ * An empty accept matches everything.
+ */
+export function acceptsMedia(accept, item) {
+    if (!accept || !accept.trim())
+        return true;
+    const mime = (item.mime ?? item.type ?? "").toLowerCase();
+    const name = (item.filename ?? item.name ?? "").toLowerCase();
+    return accept.split(",").some((raw) => {
+        const rule = raw.trim().toLowerCase();
+        if (!rule)
+            return false;
+        if (rule === "*" || rule === "*/*")
+            return true;
+        if (rule.startsWith("."))
+            return name.endsWith(rule);
+        if (rule.endsWith("/*"))
+            return mime.startsWith(rule.slice(0, -1));
+        return mime === rule;
+    });
+}
+/** Kinds an accept string allows (`"image/*"` → `["image"]`), or `undefined` when it is mixed/any. */
+export function kindsFromAccept(accept) {
+    if (!accept)
+        return undefined;
+    const kinds = new Set();
+    for (const raw of accept.split(",")) {
+        const rule = raw.trim().toLowerCase();
+        if (!rule)
+            continue;
+        if (rule.startsWith("image/"))
+            kinds.add("image");
+        else if (rule.startsWith("video/"))
+            kinds.add("video");
+        else if (rule.startsWith("audio/"))
+            kinds.add("audio");
+        else
+            return undefined;
+    }
+    return kinds.size ? [...kinds] : undefined;
+}
+/** `"2026-11-04T09:12:00Z"` → `"2026-11"`. */
+export const monthKey = (iso) => iso.slice(0, 7);
+/** A `YYYY-MM` key as a Date in the middle of the month (no time-zone edge). */
+export const monthDate = (key) => new Date(`${key}-15T12:00:00Z`);
+/** Short file extension label for tiles without a preview ("PDF", "DOCX"). */
+export function extensionOf(filename) {
+    const ext = filename.includes(".") ? filename.split(".").pop() ?? "" : "";
+    return ext.slice(0, 5).toUpperCase();
+}
+/** Best small preview URL of an asset (thumb variant → medium → original), images only. */
+export function thumbUrl(asset) {
+    if (asset.kind !== "image" && !asset.variants?.thumb && !asset.variants?.poster)
+        return undefined;
+    return asset.variants?.thumb?.url ?? asset.variants?.medium?.url ?? asset.variants?.poster?.url ?? (asset.kind === "image" ? asset.url : undefined);
+}
+/** Tag that marks an image as intentionally decorative (`alt=""` on purpose). */
+export const DECORATIVE_TAG = "decorative";
+export const isDecorative = (asset) => Boolean(asset.tags?.includes(DECORATIVE_TAG));
+/** Missing alt text matters for images only; `""` marked decorative (tag) is fine. */
+export function isAltMissing(asset, alt = asset.alt) {
+    return asset.kind === "image" && !alt.trim() && !isDecorative(asset);
+}
+/** Stable id for client-side records. */
+let seq = 0;
+export const clientId = (prefix = "u") => `${prefix}_${Date.now().toString(36)}${(seq++).toString(36)}`;
+/** Reads an image file's pixel size (client only). */
+export function readImageSize(file) {
+    if (typeof window === "undefined" || typeof URL === "undefined" || !URL.createObjectURL)
+        return Promise.resolve(null);
+    return new Promise((resolve) => {
+        const url = URL.createObjectURL(file);
+        const img = new window.Image();
+        img.onload = () => {
+            resolve(img.naturalWidth ? { width: img.naturalWidth, height: img.naturalHeight } : null);
+            URL.revokeObjectURL(url);
+        };
+        img.onerror = () => {
+            resolve(null);
+            URL.revokeObjectURL(url);
+        };
+        img.src = url;
+    });
+}
+/**
+ * Downscales a raster image so its longer side is at most `maxDimension` (canvas, zero deps).
+ * Returns the original file for SVG/GIF, non-images, small images, or when canvas is unavailable.
+ */
+export async function downscaleImage(file, maxDimension, quality = 0.9) {
+    if (!file.type.startsWith("image/") || /svg|gif/.test(file.type) || typeof document === "undefined")
+        return file;
+    const size = await readImageSize(file);
+    if (!size || Math.max(size.width, size.height) <= maxDimension)
+        return file;
+    const scale = maxDimension / Math.max(size.width, size.height);
+    const url = URL.createObjectURL(file);
+    try {
+        const img = await new Promise((resolve, reject) => {
+            const el = new window.Image();
+            el.onload = () => resolve(el);
+            el.onerror = () => reject(new Error("decode"));
+            el.src = url;
+        });
+        const canvas = document.createElement("canvas");
+        canvas.width = Math.round(size.width * scale);
+        canvas.height = Math.round(size.height * scale);
+        const ctx = canvas.getContext("2d");
+        if (!ctx)
+            return file;
+        ctx.imageSmoothingQuality = "high";
+        ctx.drawImage(img, 0, 0, canvas.width, canvas.height);
+        const type = file.type === "image/png" ? "image/png" : file.type === "image/webp" ? "image/webp" : "image/jpeg";
+        const blob = await new Promise((resolve) => canvas.toBlob(resolve, type, quality));
+        return blob ? new File([blob], file.name, { type, lastModified: file.lastModified }) : file;
+    }
+    catch {
+        return file;
+    }
+    finally {
+        URL.revokeObjectURL(url);
+    }
+}

package/dist/media/memory-adapter.d.ts

@@ -0,0 +1,22 @@
+import type { MediaAdapter, MediaAsset, MediaFolder } from "./types.js";
+export interface MemoryAdapterOptions {
+    /** Initial assets. */
+    seed?: MediaAsset[];
+    folders?: MediaFolder[];
+    /** Simulated latency in ms. Default 120 (0 in tests is fine). */
+    latency?: number;
+    /** Simulated upload duration in ms. Default 900. */
+    uploadDuration?: number;
+    /** Locale for search folding (Turkish İ/ı). Default "en-US". */
+    locale?: string;
+    capabilities?: Partial<MediaAdapter["capabilities"]>;
+}
+/**
+ * An in-memory adapter for docs, demos, prototypes and tests: object URLs for uploads,
+ * simulated progress, locale-aware search. Nothing persists.
+ *
+ * ```ts
+ * const adapter = createMemoryAdapter({ seed: assets, locale: "tr-TR" });
+ * ```
+ */
+export declare function createMemoryAdapter(options?: MemoryAdapterOptions): MediaAdapter;