@vamos-ui/react 0.0.0-stage → 0.3.0

package/dist/components/file-upload.d.ts

@@ -0,0 +1,256 @@
+import * as React from "react";
+import { type LabelFn } from "../lib/labels.js";
+/** One file in the list: a new local file or an existing server file (no `file`). */
+export interface UploadFile {
+    /** Stable key (generated for new files). */
+    key: string;
+    /** The local file; absent for files that already live on the server. */
+    file?: File;
+    /** NFC-normalised file name. */
+    name: string;
+    size: number;
+    type: string;
+    status: "queued" | "uploading" | "done" | "error";
+    /** 0–100 while uploading. */
+    progress?: number;
+    error?: string;
+    /** Id returned by `upload`. */
+    remoteId?: string;
+    url?: string;
+    /** Object URL for image thumbnails (created and revoked by the component). */
+    previewUrl?: string;
+}
+export type FileRejectionReason = "type" | "size" | "small" | "count";
+export interface FileRejection {
+    file: File;
+    reason: FileRejectionReason;
+    /** Localized message ("Brochure.mov: this file type isn't supported (only PDF or PNG)"). */
+    message: string;
+}
+/** Uploads one file. Report progress (0–100) and honour the abort signal. */
+export type UploadHandler = (file: File, ctx: {
+    signal: AbortSignal;
+    onProgress: (percent: number) => void;
+}) => Promise<{
+    id: string;
+    url?: string;
+}>;
+declare const uploadLabels: {
+    drop: string;
+    dropOne: string;
+    browse: string;
+    choose: string;
+    chooseOne: string;
+    dragActive: string;
+    noFile: string;
+    hintTypes: string;
+    hintSize: string;
+    hintCount: string;
+    images: string;
+    videos: string;
+    audio: string;
+    rejectType: string;
+    rejectSize: string;
+    rejectSmall: string;
+    rejectCount: string;
+    queued: string;
+    uploading: string;
+    done: string;
+    attached: string;
+    failed: string;
+    retry: string;
+    retryShort: string;
+    progress: string;
+    remove: string;
+    cancel: string;
+    announceDone: string;
+    announceError: string;
+    dismiss: string;
+    replace: string;
+    removeImage: string;
+    imageAlt: string;
+};
+export type FileUploadLabels = typeof uploadLabels;
+/** Splits an `accept` value into lowercase tokens: `"image/*,.pdf"` → `["image/*", ".pdf"]`. */
+export declare function parseAccept(accept?: string | string[]): string[];
+/** True when the file matches one of the accept tokens (extension, exact MIME or `type/*`). */
+export declare function matchesAccept(file: {
+    name: string;
+    type: string;
+}, tokens: string[]): boolean;
+/** Turns a File into a queued `UploadFile` (NFC-normalised name, image preview). */
+export declare function toUploadFile(file: File, status?: UploadFile["status"]): UploadFile;
+export interface UseFileDropzoneOptions {
+    accept?: string | string[];
+    maxSize?: number;
+    minSize?: number;
+    /** Remaining slots (`maxFiles − current`). `undefined` = unlimited. */
+    remaining?: number;
+    maxFiles?: number;
+    multiple?: boolean;
+    disabled?: boolean;
+    onFiles: (files: File[]) => void;
+    onReject?: (rejections: FileRejection[]) => void;
+    labels?: Partial<FileUploadLabels>;
+}
+/**
+ * Drag-and-drop + file picker wiring with localized rejections. Spread `rootProps` on the drop
+ * target, `inputProps` on a hidden `<input type="file">`, and call `open()` from a button.
+ */
+export declare function useFileDropzone({ accept, maxSize, minSize, remaining, maxFiles, multiple, disabled, onFiles, onReject, labels }: UseFileDropzoneOptions): {
+    rootProps: {
+        "data-dragging": string | undefined;
+        onDragEnter: (e: React.DragEvent) => void;
+        onDragOver: (e: React.DragEvent) => void;
+        onDragLeave: (e: React.DragEvent) => void;
+        onDrop: (e: React.DragEvent) => void;
+    };
+    inputProps: {
+        ref: React.RefObject<HTMLInputElement | null>;
+        type: "file";
+        accept: string | undefined;
+        multiple: boolean;
+        disabled: boolean | undefined;
+        tabIndex: number;
+        "aria-hidden": boolean;
+        className: string;
+        onChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
+    };
+    inputRef: React.RefObject<HTMLInputElement | null>;
+    dragging: boolean;
+    open: () => void;
+    take: (list: FileList | File[] | null) => void;
+    hint: (opts?: {
+        maxFiles?: number;
+    }) => string;
+    t: LabelFn<{
+        drop: string;
+        dropOne: string;
+        browse: string;
+        choose: string;
+        chooseOne: string;
+        dragActive: string;
+        noFile: string;
+        hintTypes: string;
+        hintSize: string;
+        hintCount: string;
+        images: string;
+        videos: string;
+        audio: string;
+        rejectType: string;
+        rejectSize: string;
+        rejectSmall: string;
+        rejectCount: string;
+        queued: string;
+        uploading: string;
+        done: string;
+        attached: string;
+        failed: string;
+        retry: string;
+        retryShort: string;
+        progress: string;
+        remove: string;
+        cancel: string;
+        announceDone: string;
+        announceError: string;
+        dismiss: string;
+        replace: string;
+        removeImage: string;
+        imageAlt: string;
+    }>;
+};
+export interface FileUploadProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "defaultValue" | "onChange"> {
+    /** MIME types / extensions: `"image/*,.pdf"` or `["image/png", ".pdf"]`. */
+    accept?: string | string[];
+    /** Max bytes per file. */
+    maxSize?: number;
+    minSize?: number;
+    maxFiles?: number;
+    /** Default `true` (unless `maxFiles` is 1). */
+    multiple?: boolean;
+    value?: UploadFile[];
+    defaultValue?: UploadFile[];
+    onValueChange?: (files: UploadFile[]) => void;
+    /**
+     * Uploads each file as soon as it is added (with progress, retry and cancel). Without it, files
+     * go with the form: the hidden file input named `name` holds them for a plain submit.
+     */
+    upload?: UploadHandler;
+    /** Parallel uploads. Default 3. */
+    concurrency?: number;
+    onReject?: (rejections: FileRejection[]) => void;
+    /** `"dropzone"` (default) · `"button"` · `"compact"` (one line, like an input). */
+    variant?: "dropzone" | "button" | "compact";
+    /** Replaces the generated hint ("PNG or PDF · up to 10 MB"). */
+    hint?: React.ReactNode;
+    /** Show the file list. Default true. */
+    showList?: boolean;
+    name?: string;
+    id?: string;
+    disabled?: boolean;
+    invalid?: boolean;
+    required?: boolean;
+    labels?: Partial<FileUploadLabels>;
+    "aria-describedby"?: string;
+}
+/**
+ * Pick or drop files, see them upload, retry or remove them. The drop target is a real button
+ * (Enter / Space opens the picker); dragging is an enhancement. Rejections (type, size, count)
+ * come back as localized messages, file sizes are locale-formatted and names NFC-normalised
+ * (macOS sends decomposed "ş" / "ğ").
+ *
+ * ```tsx
+ * <Field label="Documents">
+ *   <FileUpload accept=".pdf,image/*" maxSize={10_000_000} upload={uploadToS3} />
+ * </Field>
+ * <FileUpload name="cv" accept=".pdf" maxFiles={1} />   // no upload → sent with the form
+ * ```
+ */
+export declare const FileUpload: React.ForwardRefExoticComponent<FileUploadProps & React.RefAttributes<HTMLDivElement>>;
+/** `FileUpload` with `variant="button"`. */
+export declare const FileUploadButton: React.ForwardRefExoticComponent<Omit<FileUploadProps, "variant"> & React.RefAttributes<HTMLDivElement>>;
+/** The list of files under a FileUpload (usable alone for attachment lists). */
+export declare const FileUploadList: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLUListElement> & React.RefAttributes<HTMLUListElement>>;
+export interface FileUploadItemProps extends Omit<React.LiHTMLAttributes<HTMLLIElement>, "children"> {
+    file: UploadFile;
+    onRemove?: () => void;
+    onRetry?: () => void;
+    /** No `upload` handler: done files read "Ready to send". */
+    formMode?: boolean;
+    labels?: Partial<FileUploadLabels>;
+}
+/** One file row: thumbnail or type icon, name, size, status, progress and actions. */
+export declare const FileUploadItem: React.ForwardRefExoticComponent<FileUploadItemProps & React.RefAttributes<HTMLLIElement>>;
+export interface ImageUploadProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "defaultValue" | "onChange"> {
+    value?: UploadFile | null;
+    defaultValue?: UploadFile | null;
+    onValueChange?: (file: UploadFile | null) => void;
+    /** CSS aspect ratio: `"16/9"` (default), `"1/1"`, `"4/5"`. */
+    aspect?: string;
+    /** Default `"image/png,image/jpeg,image/webp"`. */
+    accept?: string | string[];
+    maxSize?: number;
+    upload?: UploadHandler;
+    onReject?: (rejections: FileRejection[]) => void;
+    /** Replaces the generated hint. */
+    hint?: React.ReactNode;
+    /** `cover` (default) crops to the frame; `contain` shows the whole image (logos). */
+    fit?: "cover" | "contain";
+    name?: string;
+    id?: string;
+    disabled?: boolean;
+    invalid?: boolean;
+    required?: boolean;
+    labels?: Partial<FileUploadLabels>;
+    "aria-describedby"?: string;
+}
+/**
+ * A single image with a live preview: cover images, avatars, logos. Replace and Remove sit on the
+ * image; the empty state is a drop target. The base of the media group's Image field.
+ *
+ * ```tsx
+ * <Field label="Cover image"><ImageUpload aspect="16/9" maxSize={5_000_000} upload={uploadImage} /></Field>
+ * ```
+ */
+export declare const ImageUpload: React.ForwardRefExoticComponent<ImageUploadProps & React.RefAttributes<HTMLDivElement>>;
+export {};