@vamos-ui/react 0.0.0-stage → 0.2.0

package/dist/media/types.d.ts

@@ -0,0 +1,183 @@
+export type MediaKind = "image" | "video" | "audio" | "document" | "archive" | "other";
+/** A non-destructive crop, in source pixels. Applied by the loader, never baked into the file. */
+export interface CropRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Degrees, clockwise. */
+    rotation?: number;
+    flip?: {
+        h: boolean;
+        v: boolean;
+    };
+}
+export interface MediaVariant {
+    url: string;
+    width: number;
+    height: number;
+    format?: string;
+    size?: number;
+}
+export interface MediaAsset {
+    id: string;
+    kind: MediaKind;
+    mime: string;
+    filename: string;
+    /** Bytes. */
+    size: number;
+    /** The original file. */
+    url: string;
+    /** Required for image/video so layouts never shift. */
+    width?: number;
+    height?: number;
+    /** Seconds. */
+    duration?: number;
+    /** `""` = intentionally decorative. */
+    alt: string;
+    title?: string;
+    caption?: string;
+    description?: string;
+    /** 0..1 in image space; default `{ x: 0.5, y: 0.5 }`. Not mirrored in RTL. */
+    focalPoint?: {
+        x: number;
+        y: number;
+    };
+    /** LQIP data URL (server-generated; the kit never decodes hashes). */
+    placeholder?: string;
+    dominantColor?: string;
+    /** "thumb" | "medium" | "large" | "og" | custom. */
+    variants?: Record<string, MediaVariant>;
+    /** Named non-destructive crops ("og", "square"). */
+    crops?: Record<string, CropRect>;
+    folderId?: string | null;
+    tags?: string[];
+    createdAt: string;
+    updatedAt?: string;
+    uploadedBy?: {
+        id: string;
+        name: string;
+        avatarUrl?: string;
+    };
+    usage?: {
+        count: number;
+        items?: {
+            type: string;
+            id: string;
+            title: string;
+            href?: string;
+        }[];
+    };
+    status?: "ready" | "processing" | "failed";
+}
+export interface MediaFolder {
+    id: string;
+    name: string;
+    parentId?: string | null;
+    count?: number;
+}
+export interface MediaQuery {
+    search?: string;
+    kind?: MediaKind | MediaKind[];
+    /** `"image/*,.pdf"` */
+    accept?: string;
+    folderId?: string | null;
+    /** `"2026-11"` */
+    month?: string;
+    uploadedBy?: string;
+    unattached?: boolean;
+    sort?: "newest" | "oldest" | "name" | "size";
+    cursor?: string;
+    limit?: number;
+}
+export interface MediaPage {
+    items: MediaAsset[];
+    nextCursor?: string;
+    total?: number;
+}
+export interface UploadOptions {
+    folderId?: string | null;
+    alt?: string;
+    signal: AbortSignal;
+    onProgress: (p: {
+        loaded: number;
+        total: number;
+    }) => void;
+}
+/**
+ * Builds an image URL. The signature matches the Next.js image loader, so one function works
+ * with `<Image>` from the kit and with `next/image`.
+ */
+export type ImageLoader = (p: {
+    src: string;
+    width: number;
+    quality?: number;
+    focal?: {
+        x: number;
+        y: number;
+    };
+    crop?: CropRect;
+    format?: "auto" | "webp" | "avif";
+}) => string;
+export type MediaPatch = Partial<Pick<MediaAsset, "alt" | "title" | "caption" | "description" | "focalPoint" | "crops" | "folderId" | "tags">>;
+export type MediaEvent = {
+    type: "updated" | "removed" | "ready";
+    asset?: MediaAsset;
+    id?: string;
+};
+export interface MediaCapabilities {
+    maxFileSize?: number;
+    accept?: string;
+    folders: boolean;
+    replace: boolean;
+    edit: boolean;
+    trash: boolean;
+    bulk: boolean;
+}
+export interface MediaAdapter {
+    list(q: MediaQuery, opts?: {
+        signal?: AbortSignal;
+    }): Promise<MediaPage>;
+    get(id: string): Promise<MediaAsset>;
+    getMany?(ids: string[]): Promise<MediaAsset[]>;
+    /** Single-step or presigned internally. */
+    upload(file: File, opts: UploadOptions): Promise<MediaAsset>;
+    update(id: string, patch: MediaPatch): Promise<MediaAsset>;
+    remove(ids: string[], opts?: {
+        permanent?: boolean;
+    }): Promise<void>;
+    /** Same id, new file. */
+    replace?(id: string, file: File, opts: UploadOptions): Promise<MediaAsset>;
+    /** "From URL" tab. */
+    sideload?(url: string, opts: UploadOptions): Promise<MediaAsset>;
+    folders?: {
+        list(): Promise<MediaFolder[]>;
+        create(name: string, parentId?: string | null): Promise<MediaFolder>;
+        rename?(id: string, name: string): Promise<MediaFolder>;
+        remove?(id: string): Promise<void>;
+    };
+    /** Dynamic CDNs (imgproxy, Cloudinary, Cloudflare Images). */
+    loader?: ImageLoader;
+    /** Optional AI alt-text suggestion. */
+    suggestAlt?(id: string): Promise<string>;
+    subscribe?(cb: (e: MediaEvent) => void): () => void;
+    capabilities: MediaCapabilities;
+}
+/** Anything the viewers accept: a full asset or a plain source. */
+export interface MediaSource {
+    src: string;
+    alt: string;
+    width?: number;
+    height?: number;
+    caption?: string;
+    kind?: "image" | "video";
+    placeholder?: string;
+    focalPoint?: {
+        x: number;
+        y: number;
+    };
+    /** Poster for video items. */
+    poster?: string;
+    id?: string;
+}
+export type MediaItem = MediaAsset | MediaSource;

package/dist/media/types.js

@@ -0,0 +1,3 @@
+// The storage-agnostic media contract (plan 05 · D2). Type-only: importing it costs nothing at runtime.
+// Media library, Media picker, Image field, Gallery and the block editor all consume `MediaAdapter`.
+export {};

package/dist/media/use-pan-zoom.d.ts

@@ -0,0 +1,51 @@
+import * as React from "react";
+export interface PanZoomState {
+    scale: number;
+    x: number;
+    y: number;
+}
+export interface UsePanZoomOptions {
+    /** Default 1. */
+    min?: number;
+    /** Default 3. */
+    max?: number;
+    /** Button / key step. Default 0.5. */
+    step?: number;
+    /** Double click / double tap toggles between 1× and this. Default 2. */
+    doubleTapScale?: number;
+    /** Turn the gestures off (state is kept at 1×). */
+    disabled?: boolean;
+}
+/**
+ * Pointer pan + pinch + wheel zoom + double-tap for one element (Lightbox stage, cropper preview,
+ * hierarchy chart). Put `bind` on the viewport and `style` on the content.
+ *
+ * ```tsx
+ * const pz = usePanZoom({ max: 4 });
+ * <div {...pz.bind}><img style={pz.style} /></div>
+ * ```
+ */
+export declare function usePanZoom({ min, max, step, doubleTapScale, disabled }?: UsePanZoomOptions): {
+    state: PanZoomState;
+    scale: number;
+    zoomed: boolean;
+    panning: boolean;
+    zoomTo: (scale: number, origin?: {
+        x: number;
+        y: number;
+    }) => void;
+    zoomIn: () => void;
+    zoomOut: () => void;
+    reset: () => void;
+    canZoomIn: boolean;
+    canZoomOut: boolean;
+    bind: {
+        ref: (node: HTMLElement | null) => void;
+        onPointerDown: (e: React.PointerEvent<HTMLElement>) => void;
+        onPointerMove: (e: React.PointerEvent<HTMLElement>) => void;
+        onPointerUp: (e: React.PointerEvent<HTMLElement>) => void;
+        onPointerCancel: (e: React.PointerEvent<HTMLElement>) => void;
+        style: React.CSSProperties;
+    };
+    style: React.CSSProperties;
+};

package/dist/media/use-pan-zoom.js

@@ -0,0 +1,156 @@
+"use client";
+import * as React from "react";
+const clamp = (n, lo, hi) => Math.min(hi, Math.max(lo, n));
+/**
+ * Pointer pan + pinch + wheel zoom + double-tap for one element (Lightbox stage, cropper preview,
+ * hierarchy chart). Put `bind` on the viewport and `style` on the content.
+ *
+ * ```tsx
+ * const pz = usePanZoom({ max: 4 });
+ * <div {...pz.bind}><img style={pz.style} /></div>
+ * ```
+ */
+export function usePanZoom({ min = 1, max = 3, step = 0.5, doubleTapScale = 2, disabled = false } = {}) {
+    const [state, setState] = React.useState({ scale: 1, x: 0, y: 0 });
+    const [panning, setPanning] = React.useState(false);
+    const viewport = React.useRef(null);
+    const pointers = React.useRef(new Map());
+    const gesture = React.useRef(null);
+    const lastTap = React.useRef(0);
+    const stateRef = React.useRef(state);
+    stateRef.current = state;
+    const bound = React.useCallback((s) => {
+        const el = viewport.current;
+        const scale = clamp(s.scale, min, max);
+        if (!el || scale <= 1)
+            return { scale, x: 0, y: 0 };
+        const r = el.getBoundingClientRect();
+        const mx = (r.width * (scale - 1)) / 2;
+        const my = (r.height * (scale - 1)) / 2;
+        return { scale, x: clamp(s.x, -mx, mx), y: clamp(s.y, -my, my) };
+    }, [min, max]);
+    /** Zoom to `scale`, keeping the point `origin` (px from the viewport centre) still. */
+    const zoomTo = React.useCallback((scale, origin = { x: 0, y: 0 }) => {
+        setState((prev) => {
+            const next = clamp(scale, min, max);
+            const k = next / prev.scale;
+            return bound({ scale: next, x: origin.x - (origin.x - prev.x) * k, y: origin.y - (origin.y - prev.y) * k });
+        });
+    }, [bound, min, max]);
+    const reset = React.useCallback(() => setState({ scale: 1, x: 0, y: 0 }), []);
+    const zoomIn = React.useCallback(() => zoomTo(stateRef.current.scale + step), [zoomTo, step]);
+    const zoomOut = React.useCallback(() => zoomTo(stateRef.current.scale - step), [zoomTo, step]);
+    const originOf = (clientX, clientY) => {
+        const r = viewport.current?.getBoundingClientRect();
+        if (!r)
+            return { x: 0, y: 0 };
+        return { x: clientX - (r.left + r.width / 2), y: clientY - (r.top + r.height / 2) };
+    };
+    const onPointerDown = (e) => {
+        if (disabled || (e.pointerType === "mouse" && e.button !== 0))
+            return;
+        pointers.current.set(e.pointerId, { x: e.clientX, y: e.clientY });
+        const pts = [...pointers.current.values()];
+        const s = stateRef.current;
+        if (pts.length === 2) {
+            const [a, b] = pts;
+            gesture.current = { dist: Math.hypot(a.x - b.x, a.y - b.y), scale: s.scale, x: s.x, y: s.y, px: (a.x + b.x) / 2, py: (a.y + b.y) / 2 };
+        }
+        else if (pts.length === 1) {
+            const now = Date.now();
+            if (now - lastTap.current < 280) {
+                lastTap.current = 0;
+                if (s.scale > 1)
+                    reset();
+                else
+                    zoomTo(doubleTapScale, originOf(e.clientX, e.clientY));
+                return;
+            }
+            lastTap.current = now;
+            gesture.current = { dist: 0, scale: s.scale, x: s.x, y: s.y, px: e.clientX, py: e.clientY };
+            if (s.scale > 1) {
+                e.currentTarget.setPointerCapture?.(e.pointerId);
+                setPanning(true);
+            }
+        }
+    };
+    const onPointerMove = (e) => {
+        if (disabled || !pointers.current.has(e.pointerId) || !gesture.current)
+            return;
+        pointers.current.set(e.pointerId, { x: e.clientX, y: e.clientY });
+        const pts = [...pointers.current.values()];
+        const g = gesture.current;
+        if (pts.length >= 2 && g.dist > 0) {
+            const [a, b] = pts;
+            const dist = Math.hypot(a.x - b.x, a.y - b.y);
+            const scale = clamp((g.scale * dist) / g.dist, min, max);
+            const o = originOf(g.px, g.py);
+            const k = scale / g.scale;
+            setState(bound({ scale, x: o.x - (o.x - g.x) * k + ((a.x + b.x) / 2 - g.px), y: o.y - (o.y - g.y) * k + ((a.y + b.y) / 2 - g.py) }));
+        }
+        else if (stateRef.current.scale > 1) {
+            setState(bound({ scale: stateRef.current.scale, x: g.x + (e.clientX - g.px), y: g.y + (e.clientY - g.py) }));
+        }
+    };
+    const end = (e) => {
+        pointers.current.delete(e.pointerId);
+        if (pointers.current.size === 0) {
+            gesture.current = null;
+            setPanning(false);
+        }
+        else {
+            const [p] = [...pointers.current.values()];
+            const s = stateRef.current;
+            if (p)
+                gesture.current = { dist: 0, scale: s.scale, x: s.x, y: s.y, px: p.x, py: p.y };
+        }
+    };
+    // Wheel needs a non-passive listener to prevent page scroll.
+    const wheelHandler = React.useRef(() => { });
+    wheelHandler.current = (e) => {
+        if (disabled)
+            return;
+        e.preventDefault();
+        const factor = Math.exp(-e.deltaY * (e.ctrlKey ? 0.01 : 0.0025));
+        zoomTo(stateRef.current.scale * factor, originOf(e.clientX, e.clientY));
+    };
+    const listener = React.useRef(null);
+    const ref = React.useCallback((node) => {
+        if (viewport.current && listener.current)
+            viewport.current.removeEventListener("wheel", listener.current);
+        viewport.current = node;
+        if (node) {
+            listener.current = (e) => wheelHandler.current(e);
+            node.addEventListener("wheel", listener.current, { passive: false });
+        }
+    }, []);
+    React.useEffect(() => {
+        if (disabled)
+            reset();
+    }, [disabled, reset]);
+    return {
+        state,
+        scale: state.scale,
+        zoomed: state.scale > 1.001,
+        panning,
+        zoomTo,
+        zoomIn,
+        zoomOut,
+        reset,
+        canZoomIn: state.scale < max - 0.001,
+        canZoomOut: state.scale > min + 0.001,
+        bind: {
+            ref,
+            onPointerDown,
+            onPointerMove,
+            onPointerUp: end,
+            onPointerCancel: end,
+            style: { touchAction: state.scale > 1 ? "none" : "pan-y" },
+        },
+        style: {
+            transform: `translate3d(${state.x}px, ${state.y}px, 0) scale(${state.scale})`,
+            transition: panning ? "none" : "transform 180ms cubic-bezier(0.2, 0.8, 0.2, 1)",
+            cursor: state.scale > 1 ? (panning ? "grabbing" : "grab") : "zoom-in",
+        },
+    };
+}

package/dist/media/use-upload-queue.d.ts

@@ -0,0 +1,64 @@
+import type { MediaAdapter, MediaAsset } from "./types.js";
+export type UploadStatus = "queued" | "uploading" | "processing" | "done" | "error" | "canceled";
+export interface UploadQueueItem {
+    id: string;
+    file: File;
+    status: UploadStatus;
+    /** 0..1 */
+    progress: number;
+    asset?: MediaAsset;
+    /** Human-readable reason (validation or server error). */
+    error?: string;
+    /** Rejected by a client-side check (type, size, validate): can't be retried. */
+    rejected?: boolean;
+    folderId?: string | null;
+}
+export interface UseUploadQueueOptions {
+    /** Parallel uploads. Default 3. */
+    concurrency?: number;
+    /** Client-side downscale: the longer side is at most this many pixels (canvas, JPEG/PNG/WebP only). */
+    maxDimension?: number;
+    /** `"image/*,.pdf"`: files that don't match are rejected before upload. */
+    accept?: string;
+    /** Bytes. Default: `adapter.capabilities.maxFileSize`. */
+    maxFileSize?: number;
+    /** Return an error message to reject a file, or `null`. */
+    validate?: (file: File) => string | null;
+    /** Called once per finished upload. */
+    onUploaded?: (asset: MediaAsset, item: UploadQueueItem) => void;
+    /** Guard page unload while uploads run. Default `true`. */
+    guardUnload?: boolean;
+    /** Rejection messages (Media library passes its labels). */
+    messages?: {
+        type?: string;
+        size?: string;
+        failed?: string;
+    };
+}
+export interface UploadQueue {
+    add(files: File[] | FileList, options?: {
+        folderId?: string | null;
+    }): void;
+    items: UploadQueueItem[];
+    cancel(id: string): void;
+    retry(id: string): void;
+    /** Removes finished, failed and canceled rows. */
+    clearDone(): void;
+    /** Uploads still queued or running. */
+    active: number;
+    /** Finished uploads in this batch. */
+    done: number;
+    /** Rows that count towards the batch (everything except canceled). */
+    total: number;
+}
+/**
+ * Upload queue for any `MediaAdapter`: concurrency, progress, cancel, retry, client-side checks
+ * (type, size, custom) and optional downscale. Media library, the editor's paste handler and
+ * Image field all use it.
+ *
+ * ```tsx
+ * const queue = useUploadQueue(adapter, { accept: "image/*", maxDimension: 2560 });
+ * <input type="file" multiple onChange={(e) => e.target.files && queue.add(e.target.files)} />
+ * ```
+ */
+export declare function useUploadQueue(adapter: MediaAdapter | undefined, options?: UseUploadQueueOptions): UploadQueue;

package/dist/media/use-upload-queue.js

@@ -0,0 +1,115 @@
+"use client";
+import * as React from "react";
+import { useLatest } from "../lib/use-controllable-state.js";
+import { acceptsMedia, clientId, downscaleImage } from "./media-utils.js";
+/**
+ * Upload queue for any `MediaAdapter`: concurrency, progress, cancel, retry, client-side checks
+ * (type, size, custom) and optional downscale. Media library, the editor's paste handler and
+ * Image field all use it.
+ *
+ * ```tsx
+ * const queue = useUploadQueue(adapter, { accept: "image/*", maxDimension: 2560 });
+ * <input type="file" multiple onChange={(e) => e.target.files && queue.add(e.target.files)} />
+ * ```
+ */
+export function useUploadQueue(adapter, options = {}) {
+    const { concurrency = 3, guardUnload = true } = options;
+    const [items, setItems] = React.useState([]);
+    const itemsRef = React.useRef(items);
+    itemsRef.current = items;
+    const controllers = React.useRef(new Map());
+    const running = React.useRef(new Set());
+    const opts = useLatest(options);
+    const adapterRef = useLatest(adapter);
+    const patch = React.useCallback((id, next) => {
+        setItems((list) => list.map((it) => (it.id === id ? { ...it, ...next } : it)));
+    }, []);
+    const start = React.useCallback(async (item) => {
+        const a = adapterRef.current;
+        if (!a)
+            return;
+        const ctrl = new AbortController();
+        controllers.current.set(item.id, ctrl);
+        running.current.add(item.id);
+        patch(item.id, { status: "uploading", progress: 0, error: undefined });
+        try {
+            const max = opts.current.maxDimension;
+            const file = max ? await downscaleImage(item.file, max) : item.file;
+            const asset = await a.upload(file, {
+                folderId: item.folderId,
+                signal: ctrl.signal,
+                onProgress: ({ loaded, total }) => {
+                    const p = total > 0 ? Math.min(1, loaded / total) : 0;
+                    patch(item.id, p >= 1 ? { progress: 1, status: "processing" } : { progress: p });
+                },
+            });
+            patch(item.id, { status: "done", progress: 1, asset });
+            opts.current.onUploaded?.(asset, { ...item, status: "done", asset });
+        }
+        catch (err) {
+            if (ctrl.signal.aborted || err?.name === "AbortError")
+                patch(item.id, { status: "canceled" });
+            else
+                patch(item.id, { status: "error", error: err?.message || opts.current.messages?.failed || "Upload failed" });
+        }
+        finally {
+            controllers.current.delete(item.id);
+            running.current.delete(item.id);
+        }
+    }, [adapterRef, opts, patch]);
+    // Pump: start queued items while there is room.
+    React.useEffect(() => {
+        const free = concurrency - running.current.size;
+        if (free <= 0)
+            return;
+        items
+            .filter((it) => it.status === "queued" && !running.current.has(it.id))
+            .slice(0, free)
+            .forEach((it) => void start(it));
+    }, [items, concurrency, start]);
+    const active = items.filter((it) => it.status === "queued" || it.status === "uploading" || it.status === "processing").length;
+    React.useEffect(() => {
+        if (!guardUnload || !active || typeof window === "undefined")
+            return;
+        const onBefore = (e) => {
+            e.preventDefault();
+            e.returnValue = "";
+        };
+        window.addEventListener("beforeunload", onBefore);
+        return () => window.removeEventListener("beforeunload", onBefore);
+    }, [active, guardUnload]);
+    React.useEffect(() => {
+        const map = controllers.current;
+        return () => map.forEach((c) => c.abort());
+    }, []);
+    const add = React.useCallback((files, o) => {
+        const { accept, validate, messages } = opts.current;
+        const maxSize = opts.current.maxFileSize ?? adapterRef.current?.capabilities.maxFileSize;
+        const next = Array.from(files).map((file) => {
+            let error = null;
+            if (!acceptsMedia(accept, file))
+                error = messages?.type ?? "This file type isn't allowed here";
+            else if (maxSize && file.size > maxSize)
+                error = messages?.size ?? "File is too large";
+            else
+                error = validate?.(file) ?? null;
+            return { id: clientId("up"), file, folderId: o?.folderId, status: error ? "error" : "queued", progress: 0, error: error ?? undefined, rejected: Boolean(error) || undefined };
+        });
+        setItems((list) => [...list, ...next]);
+    }, [adapterRef, opts]);
+    const cancel = React.useCallback((id) => {
+        const c = controllers.current.get(id);
+        if (c)
+            c.abort();
+        else
+            setItems((list) => list.map((it) => (it.id === id && it.status === "queued" ? { ...it, status: "canceled" } : it)));
+    }, []);
+    const retry = React.useCallback((id) => {
+        setItems((list) => list.map((it) => (it.id === id && !it.rejected && (it.status === "error" || it.status === "canceled") ? { ...it, status: "queued", progress: 0, error: undefined } : it)));
+    }, []);
+    const clearDone = React.useCallback(() => {
+        setItems((list) => list.filter((it) => it.status === "queued" || it.status === "uploading" || it.status === "processing"));
+    }, []);
+    const counted = items.filter((it) => it.status !== "canceled");
+    return { add, items, cancel, retry, clearDone, active, done: counted.filter((it) => it.status === "done").length, total: counted.length };
+}