@vamos-ui/react 0.0.0-stage → 0.3.0

package/dist/media/image-cropper.js

@@ -0,0 +1,170 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as React from "react";
+import Cropper from "react-easy-crop";
+import { FlipHorizontal2, FlipVertical2, RotateCcw, RotateCcwSquare, RotateCwSquare, ZoomIn, ZoomOut } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { useLabels } from "../lib/labels.js";
+import { useLocale } from "../lib/locale.js";
+import { useControllableState } from "../lib/use-controllable-state.js";
+import { IconButton } from "../components/button.js";
+import { Slider } from "../components/slider.js";
+import { isMediaAsset } from "./media-provider.js";
+const cropperLabels = {
+    cropper: "Crop area",
+    toolbar: "Crop tools",
+    instructions: "Drag or use the arrow keys to move the image. Scroll, pinch or use the slider to zoom.",
+    aspect: "Aspect ratio",
+    zoom: "Zoom",
+    zoomIn: "Zoom in",
+    zoomOut: "Zoom out",
+    rotateLeft: "Rotate left",
+    rotateRight: "Rotate right",
+    flipH: "Flip horizontally",
+    flipV: "Flip vertically",
+    reset: "Reset crop",
+    original: "Original",
+    square: "Square",
+    social: "Social",
+    landscape: "Landscape",
+    classic: "Classic",
+    portrait: "Portrait",
+    story: "Story",
+    avatar: "Avatar",
+    summary: "{width} × {height} px",
+};
+const RATIO_NAMES = [
+    [1, "1:1"],
+    [16 / 9, "16:9"],
+    [9 / 16, "9:16"],
+    [4 / 3, "4:3"],
+    [3 / 4, "3:4"],
+    [3 / 2, "3:2"],
+    [2 / 3, "2:3"],
+    [4 / 5, "4:5"],
+    [21 / 9, "21:9"],
+];
+/** `1.91` → "1.91:1" (locale decimal: "1,91:1"), `16/9` → "16:9". */
+export function formatAspectRatio(value, locale = "en-US") {
+    const known = RATIO_NAMES.find(([v]) => Math.abs(v - value) < 0.005);
+    if (known)
+        return known[1];
+    return `${new Intl.NumberFormat(locale, { maximumFractionDigits: 2 }).format(value)}:1`;
+}
+/**
+ * Crops an image to a ratio with drag, pinch, wheel and keyboard (arrows move, the slider zooms),
+ * plus a toolbar: ratio presets, zoom, rotate ±90°, flip, reset. It outputs a **non-destructive**
+ * `CropRect` in source pixels — store it in `asset.crops` and let the loader apply it, or bake a
+ * copy with `getCroppedBlob()`.
+ *
+ * ```tsx
+ * <ImageCropper src={asset} defaultAspect={1.91} onChange={(rect) => adapter.update(asset.id, { crops: { ...asset.crops, og: rect } })} />
+ * ```
+ */
+export const ImageCropper = React.forwardRef(function ImageCropper({ src, value, defaultValue, onChange, aspect: aspectProp, defaultAspect, onAspectChange, presets: presetsProp, shape = "rect", grid = true, minZoom = 1, maxZoom = 4, toolbar = true, transform = true, height = "22rem", labels, className, ...props }, ref) {
+    const t = useLabels("imageCropper", cropperLabels, labels);
+    const { locale } = useLocale();
+    const url = isMediaAsset(src) ? src.url : src;
+    const alt = isMediaAsset(src) ? src.alt : "";
+    const initial = value ?? defaultValue ?? null;
+    const presets = React.useMemo(() => presetsProp ??
+        (shape === "round"
+            ? [{ label: t("avatar"), value: 1 }]
+            : [
+                { label: t("original"), value: "original" },
+                { label: t("square"), value: 1, name: "square" },
+                { label: t("social"), value: 1.91, name: "og" },
+                { label: t("landscape"), value: 16 / 9 },
+                { label: t("classic"), value: 4 / 3 },
+                { label: t("portrait"), value: 4 / 5 },
+            ]), [presetsProp, shape, t]);
+    const [aspectChoice, setAspectChoice] = useControllableState({
+        value: aspectProp,
+        defaultValue: defaultAspect ?? (initial ? initial.width / initial.height : presets[0]?.value ?? 1),
+        onChange: onAspectChange,
+        name: "ImageCropper",
+    });
+    const [natural, setNatural] = React.useState(isMediaAsset(src) && src.width && src.height ? { width: src.width, height: src.height } : null);
+    const [crop, setCrop] = React.useState({ x: 0, y: 0 });
+    const [zoom, setZoom] = React.useState(1);
+    const [rotation, setRotation] = React.useState(initial?.rotation ?? 0);
+    const [flip, setFlip] = React.useState(initial?.flip ?? { h: false, v: false });
+    const [area, setArea] = React.useState(initial);
+    const [resetKey, setResetKey] = React.useState(0);
+    const rotatedNatural = natural ? (Math.abs(rotation % 180) === 90 ? { width: natural.height, height: natural.width } : natural) : null;
+    const rawAspect = aspectChoice === "original" ? (rotatedNatural ? rotatedNatural.width / rotatedNatural.height : 4 / 3) : aspectChoice;
+    const aspect = Number.isFinite(rawAspect) && rawAspect > 0 ? rawAspect : 4 / 3;
+    const activePreset = presets.find((p) => (p.value === "original" ? aspectChoice === "original" : typeof aspectChoice === "number" && Math.abs(p.value - aspectChoice) < 0.005));
+    const latest = React.useRef({ rotation, flip, activePreset, onChange });
+    latest.current = { rotation, flip, activePreset, onChange };
+    const emit = React.useCallback((px) => {
+        const { rotation: r, flip: f, activePreset: p, onChange: cb } = latest.current;
+        const rect = { x: Math.round(px.x), y: Math.round(px.y), width: Math.round(px.width), height: Math.round(px.height), ...(r ? { rotation: r } : null), ...(f.h || f.v ? { flip: f } : null) };
+        setArea(rect);
+        cb?.(rect, p);
+    }, []);
+    const reset = () => {
+        setCrop({ x: 0, y: 0 });
+        setZoom(1);
+        setRotation(0);
+        setFlip({ h: false, v: false });
+        setResetKey((k) => k + 1);
+    };
+    const rotate = (d) => setRotation((r) => (((r + d) % 360) + 360) % 360);
+    const tool = "text-fg-muted hover:text-fg";
+    const nf = React.useMemo(() => new Intl.NumberFormat(locale), [locale]);
+    const instructionsId = React.useId();
+    return (_jsxs("div", { ref: ref, "data-slot": "image-cropper", "data-shape": shape, className: cn("vui-cropper flex flex-col gap-3", className), ...props, children: [_jsxs("div", { "data-slot": "image-cropper-stage", className: "vui-cropper-stage relative overflow-hidden rounded-ui bg-scene", style: { height }, children: [_jsx(Cropper, { image: url, crop: crop, zoom: zoom, rotation: rotation, aspect: aspect, minZoom: minZoom, maxZoom: maxZoom, cropShape: shape, showGrid: grid, zoomSpeed: 0.5, keyboardStep: 8, restrictPosition: true, objectFit: "contain", transform: `translate(${crop.x}px, ${crop.y}px) rotate(${rotation}deg) scale(${zoom * (flip.h ? -1 : 1)}, ${zoom * (flip.v ? -1 : 1)})`, initialCroppedAreaPixels: resetKey === 0 && initial ? { x: initial.x, y: initial.y, width: initial.width, height: initial.height } : undefined, onCropChange: setCrop, onZoomChange: setZoom, onRotationChange: setRotation, onCropComplete: (_, px) => emit(px), onMediaLoaded: (m) => {
+                            if (m.naturalWidth > 0 && m.naturalHeight > 0)
+                                setNatural({ width: m.naturalWidth, height: m.naturalHeight });
+                        }, mediaProps: { alt }, cropperProps: { "aria-label": t("cropper"), "aria-describedby": instructionsId, role: "application" }, classes: { containerClassName: "vui-cropper-container", cropAreaClassName: "vui-cropper-area focus-ring", mediaClassName: "vui-cropper-media" } }, resetKey), _jsx("p", { id: instructionsId, className: "sr-only", children: t("instructions") }), area ? (_jsx("span", { "aria-live": "polite", className: "tabular surface-popover pointer-events-none absolute start-3 bottom-3 rounded-full px-2.5 py-1 text-[11.5px] text-fg-muted", children: t("summary", { width: nf.format(area.width), height: nf.format(area.height) }) })) : null] }), toolbar ? (_jsxs("div", { "data-slot": "image-cropper-toolbar", role: "toolbar", "aria-label": t("toolbar"), className: "flex flex-wrap items-center gap-x-4 gap-y-2.5", children: [presets.length > 1 ? (_jsx("div", { role: "group", "aria-label": t("aspect"), className: "flex flex-wrap items-center gap-1 rounded-ui bg-surface-2 p-1", children: presets.map((p) => {
+                            const ratio = p.value === "original" ? null : formatAspectRatio(p.value, locale);
+                            const selected = activePreset === p;
+                            return (_jsxs("button", { type: "button", "aria-pressed": selected, "data-slot": "image-cropper-preset", onClick: () => setAspectChoice(p.value), className: cn("focus-ring inline-flex h-7 items-center gap-1.5 rounded-ui-sm px-2.5 text-[12.5px] font-medium whitespace-nowrap text-fg-muted transition-colors hover:text-fg", selected && "bg-surface text-fg shadow-sm ring-1 ring-line"), children: [_jsx(PresetGlyph, { ratio: p.value === "original" ? aspect : p.value, round: shape === "round" }), p.label, ratio ? _jsx("span", { className: "tabular font-normal text-fg-subtle", children: ratio }) : null] }, p.label + String(p.value)));
+                        }) })) : null, _jsxs("div", { className: "flex min-w-48 flex-1 items-center gap-1.5", children: [_jsx(IconButton, { label: t("zoomOut"), tooltip: false, size: "sm", className: tool, disabled: zoom <= minZoom, onClick: () => setZoom((z) => Math.max(minZoom, z - 0.25)), children: _jsx(ZoomOut, {}) }), _jsx(Slider, { "aria-label": t("zoom"), size: "sm", min: minZoom, max: maxZoom, step: 0.01, value: [zoom], onValueChange: ([z]) => z !== undefined && setZoom(z), formatValue: (z) => `${nf.format(Math.round(z * 100))}%`, showValue: "never", className: "flex-1" }), _jsx(IconButton, { label: t("zoomIn"), tooltip: false, size: "sm", className: tool, disabled: zoom >= maxZoom, onClick: () => setZoom((z) => Math.min(maxZoom, z + 0.25)), children: _jsx(ZoomIn, {}) })] }), _jsxs("div", { className: "ms-auto flex items-center gap-0.5", children: [transform ? (_jsxs(_Fragment, { children: [_jsx(IconButton, { label: t("rotateLeft"), tooltip: false, size: "sm", className: tool, onClick: () => rotate(-90), children: _jsx(RotateCcwSquare, {}) }), _jsx(IconButton, { label: t("rotateRight"), tooltip: false, size: "sm", className: tool, onClick: () => rotate(90), children: _jsx(RotateCwSquare, {}) }), _jsx(IconButton, { label: t("flipH"), tooltip: false, size: "sm", "aria-pressed": flip.h, className: cn(tool, flip.h && "bg-selected text-fg"), onClick: () => setFlip((f) => ({ ...f, h: !f.h })), children: _jsx(FlipHorizontal2, {}) }), _jsx(IconButton, { label: t("flipV"), tooltip: false, size: "sm", "aria-pressed": flip.v, className: cn(tool, flip.v && "bg-selected text-fg"), onClick: () => setFlip((f) => ({ ...f, v: !f.v })), children: _jsx(FlipVertical2, {}) }), _jsx("span", { "aria-hidden": true, className: "mx-1 h-4 w-px bg-line" })] })) : null, _jsx(IconButton, { label: t("reset"), tooltip: false, size: "sm", className: tool, onClick: reset, children: _jsx(RotateCcw, {}) })] })] })) : null] }));
+});
+function PresetGlyph({ ratio, round }) {
+    const w = ratio >= 1 ? 14 : Math.max(6, 14 * ratio);
+    const h = ratio >= 1 ? Math.max(6, 14 / ratio) : 14;
+    return _jsx("span", { "aria-hidden": true, className: cn("inline-block border-[1.5px] border-current opacity-70", round ? "rounded-full" : "rounded-[2px]"), style: { width: w, height: h } });
+}
+function loadImage(src) {
+    return new Promise((resolve, reject) => {
+        const img = new window.Image();
+        img.crossOrigin = "anonymous";
+        img.onload = () => resolve(img);
+        img.onerror = () => reject(new Error(`Could not load ${src}`));
+        img.src = src;
+    });
+}
+/**
+ * Bakes a `CropRect` into a new image (canvas, rotation- and flip-aware) for "Save as copy".
+ * The source must be same-origin or served with CORS, or the canvas is tainted.
+ */
+export async function getCroppedBlob(src, rect, options = {}) {
+    const { type = "image/webp", quality = 0.9, maxWidth } = options;
+    const img = await loadImage(src);
+    const rad = ((rect.rotation ?? 0) * Math.PI) / 180;
+    const bw = Math.abs(Math.cos(rad) * img.naturalWidth) + Math.abs(Math.sin(rad) * img.naturalHeight);
+    const bh = Math.abs(Math.sin(rad) * img.naturalWidth) + Math.abs(Math.cos(rad) * img.naturalHeight);
+    const stage = document.createElement("canvas");
+    stage.width = Math.round(bw);
+    stage.height = Math.round(bh);
+    const s = stage.getContext("2d");
+    if (!s)
+        throw new Error("Canvas is not available");
+    s.translate(bw / 2, bh / 2);
+    s.rotate(rad);
+    s.scale(rect.flip?.h ? -1 : 1, rect.flip?.v ? -1 : 1);
+    s.drawImage(img, -img.naturalWidth / 2, -img.naturalHeight / 2);
+    const scale = maxWidth && rect.width > maxWidth ? maxWidth / rect.width : 1;
+    const out = document.createElement("canvas");
+    out.width = Math.round(rect.width * scale);
+    out.height = Math.round(rect.height * scale);
+    const o = out.getContext("2d");
+    if (!o)
+        throw new Error("Canvas is not available");
+    o.imageSmoothingQuality = "high";
+    o.drawImage(stage, rect.x, rect.y, rect.width, rect.height, 0, 0, out.width, out.height);
+    return new Promise((resolve, reject) => out.toBlob((b) => (b ? resolve(b) : reject(new Error("Export failed"))), type, quality));
+}

package/dist/media/image-field.d.ts

@@ -0,0 +1,115 @@
+import * as React from "react";
+import { type ImageAspect } from "../components/image.js";
+import { type FocalPoint } from "./focal-point.js";
+import type { CropRect, MediaAdapter, MediaAsset } from "./types.js";
+declare const fieldLabels: {
+    set: string;
+    setRound: string;
+    hint: string;
+    recommended: string;
+    replace: string;
+    crop: string;
+    focal: string;
+    remove: string;
+    alt: string;
+    altMissing: string;
+    altAdd: string;
+    altEdit: string;
+    altDecorative: string;
+    altSave: string;
+    lowRes: string;
+    uploading: string;
+    uploadError: string;
+    dropHint: string;
+    cropTitle: string;
+    cropMode: string;
+    cropMetadata: string;
+    cropMetadataHint: string;
+    cropCopy: string;
+    cropCopyHint: string;
+    cropSave: string;
+    cropTainted: string;
+    focalTitle: string;
+    focalDescription: string;
+    focalSave: string;
+    cancel: string;
+    pickerTitle: string;
+    pickerConfirm: string;
+};
+export type ImageFieldLabels = typeof fieldLabels;
+/** The field's value: the asset plus per-use overrides. */
+export interface ImageFieldValue {
+    asset: MediaAsset;
+    /** Per-use alt text; falls back to `asset.alt`. */
+    alt?: string;
+    /** Per-use focal point; falls back to `asset.focalPoint`. */
+    focal?: FocalPoint;
+    /** Named crop (`asset.crops[name]`) or a rect. */
+    crop?: string | CropRect;
+}
+export interface ImageFieldCropPreset {
+    label: string;
+    value: number;
+    /** Stored as `asset.crops[name]` and referenced by name from the value. */
+    name?: string;
+}
+export declare const imageFieldVariants: (props?: ({
+    size?: "full" | "sm" | "md" | null | undefined;
+    layout?: "inline" | "stacked" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export interface ImageFieldProps {
+    value?: ImageFieldValue | null;
+    defaultValue?: ImageFieldValue | null;
+    onChange?: (value: ImageFieldValue | null) => void;
+    /** Else from `MediaProvider`. */
+    adapter?: MediaAdapter;
+    /** Preview ratio and default crop ratio. Default `"16/9"` (`"1/1"` for `shape="round"`). */
+    aspect?: ImageAspect;
+    /** Crop ratio buttons. Default: the field's aspect only. */
+    cropPresets?: ImageFieldCropPreset[];
+    /** Low-resolution warning below this size (e.g. 1200 × 630 for social cards). */
+    recommended?: {
+        width: number;
+        height: number;
+    };
+    shape?: "rect" | "round";
+    /** `sm` 96px avatar · `md` card · `full` container width. */
+    size?: "sm" | "md" | "full";
+    /** `inline` puts the actions beside the preview (avatars, logos). */
+    layout?: "stacked" | "inline";
+    /** Show the focal-point tool. Default `true` (rect). */
+    focal?: boolean;
+    /**
+     * Crop tool: `true` offers both modes when the adapter can edit, `"metadata"` stores a crop
+     * rect (non-destructive), `"copy"` uploads a cropped copy, `false` hides it. Default `true`.
+     */
+    crop?: boolean | "copy" | "metadata";
+    /** The picker asks for alt text; the field warns while it is missing. */
+    requireAlt?: boolean;
+    /** Default `"image/*"`. */
+    accept?: string;
+    disabled?: boolean;
+    readOnly?: boolean;
+    /** Renders a hidden input with the asset id for native forms. */
+    name?: string;
+    id?: string;
+    required?: boolean;
+    invalid?: boolean;
+    "aria-describedby"?: string;
+    "aria-label"?: string;
+    className?: string;
+    labels?: Partial<ImageFieldLabels>;
+}
+/**
+ * A form field that holds one image: pick from the library or drop a file, preview, replace,
+ * remove, crop to a ratio (non-destructive or as a copy), set a focal point and a per-use alt text.
+ * Works inside `Field` (label, hint, error, required).
+ *
+ * ```tsx
+ * <Field label="Featured image" hint="Shown on the blog index and social cards">
+ *   <ImageField aspect="16/9" recommended={{ width: 1200, height: 630 }} value={cover} onChange={setCover} />
+ * </Field>
+ * ```
+ */
+export declare const ImageField: React.ForwardRefExoticComponent<ImageFieldProps & React.RefAttributes<HTMLDivElement>>;
+export {};

package/dist/media/image-field.js

@@ -0,0 +1,212 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as React from "react";
+import { Crop, Crosshair, ImagePlus, Pencil, RefreshCw, Trash2, TriangleAlert } from "lucide-react";
+import { cva } from "class-variance-authority";
+import { cn } from "../lib/cn.js";
+import { useLabels } from "../lib/labels.js";
+import { useFormat, useLocale } from "../lib/locale.js";
+import { useFieldControl } from "../lib/field-context.js";
+import { useControllableState } from "../lib/use-controllable-state.js";
+import { Button, IconButton } from "../components/button.js";
+import { Dialog, DialogBody, DialogContent, DialogFooter, DialogHeader } from "../components/dialog.js";
+import { Image, aspectRatioOf } from "../components/image.js";
+import { Input } from "../components/input.js";
+import { Progress } from "../components/progress.js";
+import { RadioGroup, RadioGroupItem } from "../components/radio-group.js";
+import { FocalPointPicker } from "./focal-point.js";
+import { ImageCropper, getCroppedBlob } from "./image-cropper.js";
+import { MediaPicker } from "./media-picker.js";
+import { useMedia } from "./media-provider.js";
+import { isAltMissing } from "./media-utils.js";
+import { useUploadQueue } from "./use-upload-queue.js";
+const fieldLabels = {
+    set: "Set image",
+    setRound: "Add photo",
+    hint: "Drop an image here or choose one from the library",
+    recommended: "Recommended {width} × {height} px or larger",
+    replace: "Replace image",
+    crop: "Crop",
+    focal: "Focal point",
+    remove: "Remove image",
+    alt: "Alt text",
+    altMissing: "Missing alt text",
+    altAdd: "Add alt text",
+    altEdit: "Edit alt text",
+    altDecorative: "Decorative image",
+    altSave: "Done",
+    lowRes: "Low resolution: {width} × {height} px. Recommended at least {minWidth} × {minHeight}.",
+    uploading: "Uploading {name}",
+    uploadError: "Upload failed: {reason}",
+    dropHint: "Drop to upload",
+    cropTitle: "Crop image",
+    cropMode: "Save the crop",
+    cropMetadata: "Keep the original, store the crop",
+    cropMetadataHint: "Non-destructive: the original file stays untouched.",
+    cropCopy: "Save as a new copy",
+    cropCopyHint: "Creates a new file in the library.",
+    cropSave: "Apply crop",
+    cropTainted: "This image is hosted elsewhere, so it can't be edited here. Upload it to the library to crop it.",
+    focalTitle: "Set focal point",
+    focalDescription: "Mark the part that must stay in view when layouts crop the image.",
+    focalSave: "Save focal point",
+    cancel: "Cancel",
+    pickerTitle: "Select image",
+    pickerConfirm: "Use image",
+};
+export const imageFieldVariants = cva("vui-image-field group/imgfield relative grid min-w-0 gap-2", {
+    variants: {
+        size: { sm: "w-24", md: "w-full max-w-[22rem]", full: "w-full" },
+        layout: { stacked: "", inline: "grid-cols-[auto_minmax(0,1fr)] items-start gap-x-4" },
+    },
+    // Inline: the preview keeps the size, the row takes the width.
+    compoundVariants: [{ layout: "inline", class: "w-full max-w-md" }],
+    defaultVariants: { size: "md", layout: "stacked" },
+});
+const ratioOf = (aspect, a) => aspectRatioOf(aspect ?? "auto", a?.width, a?.height) ?? (a?.width && a?.height ? a.width / a.height : 16 / 9);
+/**
+ * A form field that holds one image: pick from the library or drop a file, preview, replace,
+ * remove, crop to a ratio (non-destructive or as a copy), set a focal point and a per-use alt text.
+ * Works inside `Field` (label, hint, error, required).
+ *
+ * ```tsx
+ * <Field label="Featured image" hint="Shown on the blog index and social cards">
+ *   <ImageField aspect="16/9" recommended={{ width: 1200, height: 630 }} value={cover} onChange={setCover} />
+ * </Field>
+ * ```
+ */
+export const ImageField = React.forwardRef(function ImageField(props, ref) {
+    const { value: valueProp, defaultValue, onChange, adapter: adapterProp, aspect: aspectProp, cropPresets, recommended, shape = "rect", size = "md", layout = "stacked", focal: focalEnabled = shape !== "round", crop: cropMode = true, requireAlt = false, accept = "image/*", name, className, labels, } = props;
+    const control = useFieldControl({ id: props.id, "aria-describedby": props["aria-describedby"], disabled: props.disabled, readOnly: props.readOnly, required: props.required, "aria-invalid": props.invalid || undefined });
+    const disabled = Boolean(control.disabled);
+    const readOnly = Boolean(control.readOnly);
+    const t = useLabels("imageField", fieldLabels, labels);
+    const f = useFormat();
+    const { locale } = useLocale();
+    const ctx = useMedia();
+    const adapter = adapterProp ?? ctx;
+    const aspect = aspectProp ?? (shape === "round" ? "1/1" : "16/9");
+    const [value, setValue] = useControllableState({ value: valueProp, defaultValue: defaultValue ?? null, onChange, name: "ImageField" });
+    const [pickerOpen, setPickerOpen] = React.useState(false);
+    const [cropOpen, setCropOpen] = React.useState(false);
+    const [focalOpen, setFocalOpen] = React.useState(false);
+    const [editingAlt, setEditingAlt] = React.useState(false);
+    const [over, setOver] = React.useState(false);
+    const altInput = React.useRef(null);
+    const nf = React.useMemo(() => new Intl.NumberFormat(locale), [locale]);
+    const interactive = !disabled && !readOnly;
+    const queue = useUploadQueue(adapter, {
+        accept,
+        guardUnload: true,
+        onUploaded: (asset) => setValue({ asset }),
+    });
+    const current = queue.items.find((it) => it.status === "queued" || it.status === "uploading" || it.status === "processing");
+    const failed = !current ? queue.items.filter((it) => it.status === "error").at(-1) : undefined;
+    const asset = value?.asset;
+    const alt = value?.alt ?? asset?.alt ?? "";
+    const missingAlt = asset ? isAltMissing(asset, alt) : false;
+    const lowRes = asset && recommended && asset.width && asset.height && (asset.width < recommended.width || asset.height < recommended.height);
+    const editable = Boolean(adapter?.capabilities.edit);
+    const cropAvailable = cropMode !== false;
+    const drop = interactive
+        ? {
+            onDragOver: (e) => {
+                if (!Array.from(e.dataTransfer?.types ?? []).includes("Files"))
+                    return;
+                e.preventDefault();
+                setOver(true);
+            },
+            onDragLeave: () => setOver(false),
+            onDrop: (e) => {
+                setOver(false);
+                const file = e.dataTransfer?.files?.[0];
+                if (!file)
+                    return;
+                e.preventDefault();
+                queue.clearDone();
+                queue.add([file]);
+            },
+        }
+        : {};
+    const ratio = ratioOf(aspect, asset);
+    const round = shape === "round";
+    const hintId = React.useId();
+    const describedBy = [control["aria-describedby"], hintId].filter(Boolean).join(" ") || undefined;
+    const empty = (_jsx("button", { type: "button", id: control.id, "data-slot": "image-field-empty", "data-dragging": over ? "" : undefined, "aria-describedby": describedBy, "aria-invalid": control["aria-invalid"], "data-readonly": readOnly ? "" : undefined, disabled: disabled, onClick: () => interactive && setPickerOpen(true), className: cn("vui-image-field-empty focus-ring relative flex w-full flex-col items-center justify-center gap-1.5 overflow-hidden border border-dashed border-field-border bg-surface-2 px-3 text-center text-fg-muted transition-colors", "hover:border-field-border-hover hover:text-fg disabled:cursor-not-allowed disabled:opacity-50", "aria-[invalid=true]:border-danger", round ? "rounded-full" : "rounded-ui", over && "border-ring bg-accent-soft text-fg"), style: { aspectRatio: String(round ? 1 : ratio) }, children: current ? (_jsxs("span", { className: "grid w-full max-w-[14rem] gap-2 px-2", children: [_jsx("span", { className: "truncate text-[12.5px]", children: t("uploading", { name: current.file.name }) }), _jsx(Progress, { "aria-label": t("uploading", { name: current.file.name }), value: current.status === "uploading" ? current.progress * 100 : current.status === "processing" ? null : 0 })] })) : (_jsxs(_Fragment, { children: [props["aria-label"] ? _jsxs("span", { className: "sr-only", children: [props["aria-label"], ", "] }) : null, _jsx(ImagePlus, { "aria-hidden": true, strokeWidth: 1.5, className: size === "sm" ? "size-5" : "size-6" }), _jsx("span", { className: cn("font-medium text-fg", size === "sm" ? "text-[12px]" : "text-[13.5px]"), children: over ? t("dropHint") : round ? t("setRound") : t("set") }), size !== "sm" ? _jsx("span", { className: "max-w-[16rem] text-[12px] leading-snug text-fg-subtle", children: t("hint") }) : null] })) }));
+    const preview = asset ? (_jsx("div", { className: cn("relative", round && "aspect-square"), children: _jsxs("button", { type: "button", id: control.id, "data-slot": "image-field-preview", "data-dragging": over ? "" : undefined, "aria-label": `${t("replace")}${alt ? `: ${alt}` : ""}`, "aria-describedby": describedBy, "aria-invalid": control["aria-invalid"], "data-readonly": readOnly ? "" : undefined, disabled: disabled, onClick: () => interactive && setPickerOpen(true), className: cn("vui-image-field-preview focus-ring group/preview relative block w-full overflow-hidden bg-surface-2 ring-1 ring-line", round ? "rounded-full" : "rounded-ui", interactive ? "cursor-pointer" : "cursor-default", over && "ring-2 ring-ring"), children: [_jsx(Image, { src: asset, alt: "", aspect: round ? "1/1" : aspect, focal: value?.focal ?? asset.focalPoint, crop: value?.crop, sizes: size === "sm" ? "96px" : "(min-width: 768px) 360px, 100vw", placeholder: asset.placeholder ? "blur" : "skeleton" }), interactive ? (_jsx("span", { "aria-hidden": true, className: "vui-image-field-scrim absolute inset-0 flex items-center justify-center opacity-0 transition-opacity group-hover/preview:opacity-100", children: _jsxs("span", { className: "surface-popover inline-flex items-center gap-1.5 rounded-full px-3 py-1.5 text-[12px] font-medium", children: [_jsx(RefreshCw, { className: "size-3.5" }), size === "sm" ? null : t("replace")] }) })) : null, current ? (_jsx("span", { className: "absolute inset-x-3 bottom-3", children: _jsx(Progress, { "aria-label": t("uploading", { name: current.file.name }), value: current.status === "uploading" ? current.progress * 100 : null }) })) : null] }) })) : null;
+    const actions = asset && interactive ? (_jsxs("div", { "data-slot": "image-field-actions", className: cn("flex flex-wrap items-center gap-1", layout === "inline" && "col-start-2"), children: [layout === "inline" ? (_jsxs(Button, { size: "xs", onClick: () => setPickerOpen(true), children: [_jsx(RefreshCw, {}), t("replace")] })) : null, cropAvailable ? (_jsxs(Button, { size: "xs", variant: "ghost", className: "text-fg-muted", onClick: () => setCropOpen(true), children: [_jsx(Crop, {}), t("crop")] })) : null, focalEnabled && !round ? (_jsxs(Button, { size: "xs", variant: "ghost", className: "text-fg-muted", onClick: () => setFocalOpen(true), children: [_jsx(Crosshair, {}), t("focal")] })) : null, _jsx(IconButton, { label: t("remove"), tooltip: false, size: "xs", variant: "ghost", className: "ms-auto text-fg-muted hover:text-danger", onClick: () => setValue(null), children: _jsx(Trash2, {}) })] })) : null;
+    const altLine = asset ? (_jsxs("div", { "data-slot": "image-field-alt", className: cn("grid gap-1 text-[12.5px]", layout === "inline" && "col-start-2"), children: [editingAlt ? (_jsxs("form", { className: "flex items-center gap-1.5", onSubmit: (e) => {
+                    e.preventDefault();
+                    setValue({ ...value, alt: altInput.current?.value ?? "" });
+                    setEditingAlt(false);
+                }, children: [_jsx(Input, { ref: altInput, size: "sm", autoFocus: true, "aria-label": t("alt"), defaultValue: alt, className: "flex-1", onKeyDown: (e) => e.key === "Escape" && (e.stopPropagation(), setEditingAlt(false)) }), _jsx(Button, { size: "sm", type: "submit", children: t("altSave") })] })) : missingAlt ? (_jsxs("p", { className: cn("flex items-center gap-1.5", requireAlt ? "text-warning" : "text-fg-muted"), children: [_jsx(TriangleAlert, { "aria-hidden": true, className: "size-3.5 shrink-0" }), _jsx("span", { children: t("altMissing") }), interactive ? (_jsx(Button, { size: "xs", variant: "link", className: "ms-1", onClick: () => setEditingAlt(true), children: t("altAdd") })) : null] })) : (_jsxs("p", { className: "flex min-w-0 items-baseline gap-1.5 text-fg-muted", children: [_jsx("span", { className: "shrink-0 text-[11px] font-medium tracking-[0.06em] text-fg-subtle uppercase", children: t("alt") }), _jsx("span", { className: "min-w-0 truncate text-fg", children: alt || t("altDecorative") }), interactive ? (_jsx(IconButton, { label: t("altEdit"), tooltip: false, size: "xs", variant: "ghost", className: "-my-1 shrink-0 text-fg-subtle", onClick: () => setEditingAlt(true), children: _jsx(Pencil, {}) })) : null] })), lowRes ? (_jsxs("p", { className: "flex items-start gap-1.5 text-warning", children: [_jsx(TriangleAlert, { "aria-hidden": true, className: "mt-px size-3.5 shrink-0" }), t("lowRes", { width: nf.format(asset.width), height: nf.format(asset.height), minWidth: nf.format(recommended.width), minHeight: nf.format(recommended.height) })] })) : null] })) : null;
+    return (_jsxs("div", { ref: ref, "data-slot": "image-field", "data-shape": shape, "data-state": asset ? "filled" : "empty", className: cn(imageFieldVariants({ size, layout }), className), ...drop, children: [_jsx("div", { className: cn(layout === "inline" && (size === "sm" ? "w-24" : "w-40"), layout === "inline" && "row-span-3 self-start"), children: asset ? preview : empty }), actions, altLine, _jsx("p", { id: hintId, className: cn("text-[12px]", failed ? "text-danger" : "sr-only"), children: failed ? t("uploadError", { reason: failed.error ?? "" }) : recommended ? t("recommended", { width: nf.format(recommended.width), height: nf.format(recommended.height) }) : null }), !asset && recommended && size !== "sm" && !failed ? (_jsx("p", { "aria-hidden": true, className: cn("tabular text-[12px] text-fg-subtle", layout === "inline" && "col-start-2"), children: t("recommended", { width: f.number(recommended.width), height: f.number(recommended.height) }) })) : null, name ? _jsx("input", { type: "hidden", name: name, value: asset?.id ?? "" }) : null, interactive ? (_jsx(MediaPicker, { open: pickerOpen, onOpenChange: setPickerOpen, adapter: adapter, accept: accept, value: asset ? [asset.id] : undefined, requireAlt: requireAlt, title: t("pickerTitle"), confirmLabel: t("pickerConfirm"), onSelect: ([picked]) => picked && setValue({ asset: picked }) })) : null, asset && interactive && cropAvailable ? (_jsx(ImageFieldCropDialog, { open: cropOpen, onOpenChange: setCropOpen, asset: asset, adapter: adapter, aspect: ratio, presets: cropPresets, shape: shape, mode: cropMode === true ? (editable ? "both" : "copy") : cropMode === "metadata" ? "metadata" : "copy", initial: typeof value?.crop === "object" ? value.crop : typeof value?.crop === "string" ? asset.crops?.[value.crop] : undefined, t: t, onApply: (result) => {
+                    if (result.kind === "copy")
+                        setValue({ asset: result.asset, alt: value?.alt });
+                    else
+                        setValue({ ...value, asset: result.asset ?? asset, crop: result.crop });
+                } })) : null, asset && interactive && focalEnabled && !round ? (_jsx(Dialog, { open: focalOpen, onOpenChange: setFocalOpen, children: _jsxs(DialogContent, { size: "lg", children: [_jsx(DialogHeader, { title: t("focalTitle"), description: t("focalDescription") }), focalOpen ? _jsx(ImageFieldFocalBody, { asset: asset, initial: value?.focal ?? asset.focalPoint, t: t, onSave: (focal) => {
+                                setValue({ ...value, focal });
+                                setFocalOpen(false);
+                            }, onCancel: () => setFocalOpen(false) }) : null] }) })) : null] }));
+});
+function ImageFieldFocalBody({ asset, initial, onSave, onCancel, t }) {
+    const [point, setPoint] = React.useState(initial ?? { x: 0.5, y: 0.5 });
+    return (_jsxs(_Fragment, { children: [_jsx(DialogBody, { children: _jsx(FocalPointPicker, { src: asset, value: point, onValueChange: setPoint }) }), _jsxs(DialogFooter, { children: [_jsx(Button, { onClick: onCancel, children: t("cancel") }), _jsx(Button, { variant: "primary", onClick: () => onSave(point), children: t("focalSave") })] })] }));
+}
+/** The crop dialog of Image field: Image cropper + save mode (non-destructive rect or a new copy). */
+function ImageFieldCropDialog({ open, onOpenChange, asset, adapter, aspect, presets, shape, mode, initial, onApply, t, }) {
+    const [rect, setRect] = React.useState(initial ?? null);
+    const [preset, setPreset] = React.useState();
+    const [choice, setChoice] = React.useState(mode === "copy" ? "copy" : "metadata");
+    const [busy, setBusy] = React.useState(false);
+    const [error, setError] = React.useState(null);
+    React.useEffect(() => {
+        if (open) {
+            setError(null);
+            setRect(initial ?? null);
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [open]);
+    const cropperPresets = presets?.map((p) => ({ label: p.label, value: p.value, name: p.name }));
+    const apply = async () => {
+        if (!rect)
+            return;
+        setError(null);
+        if (choice === "metadata") {
+            let saved;
+            if (preset?.name && adapter?.capabilities.edit) {
+                try {
+                    saved = await adapter.update(asset.id, { crops: { ...asset.crops, [preset.name]: rect } });
+                }
+                catch {
+                    /* keep the per-use rect */
+                }
+            }
+            onApply({ kind: "metadata", crop: preset?.name && saved ? preset.name : rect, asset: saved });
+            onOpenChange(false);
+            return;
+        }
+        if (!adapter)
+            return;
+        setBusy(true);
+        try {
+            const blob = await getCroppedBlob(asset.url, rect, { type: asset.mime === "image/png" ? "image/png" : "image/webp" });
+            const ext = blob.type === "image/png" ? "png" : "webp";
+            const file = new File([blob], asset.filename.replace(/\.[^.]+$/, "") + `-crop.${ext}`, { type: blob.type });
+            const copy = await adapter.upload(file, { folderId: asset.folderId ?? null, alt: asset.alt, signal: new AbortController().signal, onProgress: () => { } });
+            onApply({ kind: "copy", asset: copy });
+            onOpenChange(false);
+        }
+        catch {
+            setError(t("cropTainted"));
+        }
+        finally {
+            setBusy(false);
+        }
+    };
+    return (_jsx(Dialog, { open: open, onOpenChange: onOpenChange, children: _jsxs(DialogContent, { size: "xl", mobile: "fullscreen", children: [_jsx(DialogHeader, { title: t("cropTitle") }), _jsxs(DialogBody, { className: "grid gap-4", children: [open ? (_jsx(ImageCropper, { src: asset, defaultValue: initial, defaultAspect: shape === "round" ? 1 : aspect, presets: cropperPresets ?? (shape === "round" ? undefined : []), shape: shape, height: "min(24rem, 50dvh)", onChange: (r, p) => {
+                                setRect(r);
+                                setPreset(p);
+                            } })) : null, mode === "both" ? (_jsxs(RadioGroup, { "aria-label": t("cropMode"), value: choice, onValueChange: (v) => setChoice(v), className: "grid gap-2 sm:grid-cols-2", children: [_jsx(RadioGroupItem, { value: "metadata", label: t("cropMetadata"), description: t("cropMetadataHint") }), _jsx(RadioGroupItem, { value: "copy", label: t("cropCopy"), description: t("cropCopyHint") })] })) : null, error ? (_jsxs("p", { role: "alert", className: "flex items-start gap-1.5 text-[13px] text-danger", children: [_jsx(TriangleAlert, { "aria-hidden": true, className: "mt-0.5 size-3.5 shrink-0" }), error] })) : null] }), _jsxs(DialogFooter, { children: [_jsx(Button, { onClick: () => onOpenChange(false), children: t("cancel") }), _jsx(Button, { variant: "primary", disabled: !rect, loading: busy, onClick: () => void apply(), children: t("cropSave") })] })] }) }));
+}

package/dist/media/index.d.ts

@@ -0,0 +1,19 @@
+export type { MediaKind, MediaAsset, MediaVariant, MediaFolder, MediaQuery, MediaPage, MediaPatch, MediaEvent, MediaCapabilities, MediaAdapter, MediaSource, MediaItem, CropRect, UploadOptions, ImageLoader, } from "./types.js";
+export { MediaProvider, useMedia, isMediaAsset, toMediaSource } from "./media-provider.js";
+export { createMemoryAdapter, type MemoryAdapterOptions } from "./memory-adapter.js";
+export { usePanZoom, type UsePanZoomOptions, type PanZoomState } from "./use-pan-zoom.js";
+export { Gallery, galleryVariants, type GalleryProps, type GalleryLabels } from "./gallery.js";
+export { masonryColumns, justifyRows, responsiveValue, type JustifiedRow, type Responsive } from "./gallery-layout.js";
+export { Lightbox, LightboxTrigger, useLightbox, type LightboxProps, type LightboxTriggerProps, type LightboxLabels } from "./lightbox.js";
+export { VideoPlayer, VideoEmbed, BackgroundVideo, videoPlayerVariants, formatMediaTime, type VideoPlayerProps, type VideoEmbedProps, type BackgroundVideoProps, type VideoSource, type VideoTrack, type HlsConstructor, type VideoPlayerLabels, } from "./video-player.js";
+export { SearchPreview, SocialCardPreview, LengthMeter, LinkPreviewTabs, type LinkPreviewData, type SearchPreviewProps, type SocialCardPreviewProps, type LengthMeterProps, type LinkPreviewTabsProps, type SocialPlatform, type LinkPreviewLabels, } from "./link-preview.js";
+export { measureSerp, measureText, countGraphemes, graphemes, SERP_LIMITS, type SerpMeasure, type SerpField, type SerpDevice } from "./serp.js";
+export { ImageCropper, getCroppedBlob, formatAspectRatio, type ImageCropperProps, type CropPreset, type CroppedBlobOptions, type ImageCropperLabels, } from "./image-cropper.js";
+export { Image, Figure, FigureCaption, ImageLoaderProvider, useImageLoader, useImageSources, getImageSources, type ImageProps } from "../components/image.js";
+export { createRestAdapter, createPresignedUpload, xhrUpload, toSearchParams, type RestAdapterOptions, type PresignedTarget, type PresignedUploadOptions, type XhrUploadOptions } from "./rest-adapter.js";
+export { useUploadQueue, type UploadQueue, type UploadQueueItem, type UploadStatus, type UseUploadQueueOptions } from "./use-upload-queue.js";
+export { mediaKindOf, acceptsMedia, kindsFromAccept, isAltMissing, isDecorative, downscaleImage, DECORATIVE_TAG } from "./media-utils.js";
+export { FocalPointPicker, type FocalPointPickerProps, type FocalPoint, type FocalPointLabels } from "./focal-point.js";
+export { MediaLibrary, MediaDetails, MediaUploadQueue, MediaThumb, MediaFileGlyph, type MediaLibraryProps, type MediaLibraryHandle, type MediaLibraryView, type MediaSelectionMode, type MediaDetailsProps, type MediaUploadQueueProps, type MediaLibraryLabels, type MediaDetailsLabels, type MediaUploadQueueLabels, } from "./media-library.js";
+export { MediaPicker, MediaPickerProvider, useMediaPicker, type MediaPickerProps, type MediaPickerTab, type MediaPickOptions, type MediaPickerLabels } from "./media-picker.js";
+export { ImageField, imageFieldVariants, type ImageFieldProps, type ImageFieldValue, type ImageFieldCropPreset, type ImageFieldLabels } from "./image-field.js";

package/dist/media/index.js

@@ -0,0 +1,23 @@
+// Public API of @vamos-ui/react/media — media contract, adapters and viewers.
+// `Image`, `Figure` and `Carousel` live in the package root (they are light); this subpath holds
+// the heavier media parts and the storage-agnostic MediaAdapter contract (plan 05 · D2).
+export { MediaProvider, useMedia, isMediaAsset, toMediaSource } from "./media-provider.js";
+export { createMemoryAdapter } from "./memory-adapter.js";
+export { usePanZoom } from "./use-pan-zoom.js";
+export { Gallery, galleryVariants } from "./gallery.js";
+export { masonryColumns, justifyRows, responsiveValue } from "./gallery-layout.js";
+export { Lightbox, LightboxTrigger, useLightbox } from "./lightbox.js";
+export { VideoPlayer, VideoEmbed, BackgroundVideo, videoPlayerVariants, formatMediaTime, } from "./video-player.js";
+export { SearchPreview, SocialCardPreview, LengthMeter, LinkPreviewTabs, } from "./link-preview.js";
+export { measureSerp, measureText, countGraphemes, graphemes, SERP_LIMITS } from "./serp.js";
+export { ImageCropper, getCroppedBlob, formatAspectRatio, } from "./image-cropper.js";
+// Convenience re-exports so media code can import everything from one place.
+export { Image, Figure, FigureCaption, ImageLoaderProvider, useImageLoader, useImageSources, getImageSources } from "../components/image.js";
+// Media library · Media picker · Image field (+ adapters, upload queue, focal point)
+export { createRestAdapter, createPresignedUpload, xhrUpload, toSearchParams } from "./rest-adapter.js";
+export { useUploadQueue } from "./use-upload-queue.js";
+export { mediaKindOf, acceptsMedia, kindsFromAccept, isAltMissing, isDecorative, downscaleImage, DECORATIVE_TAG } from "./media-utils.js";
+export { FocalPointPicker } from "./focal-point.js";
+export { MediaLibrary, MediaDetails, MediaUploadQueue, MediaThumb, MediaFileGlyph, } from "./media-library.js";
+export { MediaPicker, MediaPickerProvider, useMediaPicker } from "./media-picker.js";
+export { ImageField, imageFieldVariants } from "./image-field.js";