@arcfusionz/arc-primitive-ui 0.2.12 → 0.2.14

package/dist/components/FileUpload/FileUpload.d.ts

@@ -0,0 +1,190 @@
+import { ButtonProps } from "../Button/Button.js";
+import "../Button/index.js";
+import { ComponentPropsWithoutRef, ReactNode } from "react";
+import { useRender } from "@base-ui/react/use-render";
+//#region src/components/FileUpload/FileUpload.d.ts
+/** Built-in reasons a file is rejected. `validate` may add more of these. */
+type FileUploadRejectionCode = "file-invalid-type" | "file-too-small" | "file-too-large" | "too-many-files";
+/** A file that failed validation, with every reason it failed. */
+interface FileUploadRejection {
+  file: File;
+  errors: FileUploadRejectionCode[];
+}
+/** Per-file lifecycle the consumer drives while uploading. */
+type FileUploadItemStatus = "idle" | "uploading" | "success" | "error";
+/** State exposed on the root element as `data-*` and to the `render` callback. */
+interface FileUploadRenderState extends Record<string, unknown> {
+  /** A file is being dragged over the dropzone. */
+  dragging: boolean;
+  /** The upload is disabled. */
+  disabled: boolean;
+  /** The upload is marked invalid. */
+  invalid: boolean;
+  /** No files are selected. */
+  empty: boolean;
+}
+/** `1023 B`, `1.5 KB`, `12 MB` — a compact, locale-neutral size readout. */
+declare function formatFileSize(bytes: number): string;
+/** Public view of the upload's state and controls, for custom compositions. */
+interface FileUploadHandle {
+  /** The currently selected files. */
+  files: File[];
+  /** A file is being dragged over the dropzone. */
+  isDragging: boolean;
+  /** The upload is disabled. */
+  disabled: boolean;
+  /** The upload is marked invalid. */
+  invalid: boolean;
+  /** Open the native file picker. */
+  open: () => void;
+  /** Remove one file from the selection. */
+  remove: (file: File) => void;
+  /** Clear the whole selection. */
+  clear: () => void;
+}
+/**
+ * Read the enclosing `FileUpload`'s state and controls — for building custom
+ * pieces the flat parts don't cover (a file counter, an "Upload all" button, a
+ * dropzone that hides once a file is chosen). Must be called under `FileUpload`.
+ */
+declare function useFileUpload(): FileUploadHandle;
+interface FileUploadProps extends Omit<ComponentPropsWithoutRef<"div">, "className" | "onChange" | "defaultValue" | "children"> {
+  /** Accepted types as the native `accept` string, e.g. `"image/*,.pdf"`. Enforced client-side too, so dropped files are gated the same as picked ones. */
+  accept?: string;
+  /** Allow selecting more than one file. When `false` (default) a new selection replaces the current one. */
+  multiple?: boolean;
+  /** Cap the number of files kept (only applies when `multiple`). Extra files are rejected with `too-many-files`. */
+  maxFiles?: number;
+  /** Reject files larger than this many bytes with `file-too-large`. */
+  maxSize?: number;
+  /** Reject files smaller than this many bytes with `file-too-small`. */
+  minSize?: number;
+  /** Extra validation run after the built-in checks; return the codes a file fails, or `null` to accept it. */
+  validate?: (file: File) => FileUploadRejectionCode[] | null;
+  /** Enable drag-and-drop onto the dropzone. Defaults to `true`. */
+  allowDrop?: boolean;
+  /** Prevent a file dropped outside the dropzone from navigating the browser. Defaults to `true`. */
+  preventDocumentDrop?: boolean;
+  /** Let the user pick a whole directory (`webkitdirectory`; Chromium/WebKit only). */
+  directory?: boolean;
+  /** Open the device camera on mobile instead of the file browser. */
+  capture?: "user" | "environment";
+  /** Controlled list of selected files. Pair with `onValueChange`. */
+  value?: File[];
+  /** Initial selection for the uncontrolled case. */
+  defaultValue?: File[];
+  /** Called whenever the selection changes (accepted files added, or a file removed). */
+  onValueChange?: (files: File[]) => void;
+  /** Called with the files newly accepted in a selection or drop. */
+  onAccept?: (files: File[]) => void;
+  /** Called with the files rejected in a selection or drop and why. */
+  onReject?: (rejections: FileUploadRejection[]) => void;
+  /** Disable the whole control. Inherited from a surrounding `Field` when unset. */
+  disabled?: boolean;
+  /** Mark the control invalid (destructive styling). Inherited from a surrounding `Field` when unset. */
+  invalid?: boolean;
+  /** Convey the field is required. Inherited from a surrounding `Field` when unset. */
+  required?: boolean;
+  /** `name` for the hidden input so the selection submits with a native form. */
+  name?: string;
+  /** Accessible name for the hidden file input. */
+  inputLabel?: string;
+  /** Replace the rendered root `div` or inspect `{ dragging, disabled, invalid, empty }`. */
+  render?: useRender.RenderProp<FileUploadRenderState>;
+  /** Compose the pieces: `FileUploadDropzone`, `FileUploadList`, `FileUploadTrigger`. */
+  children?: ReactNode;
+  className?: string;
+}
+/**
+ * Drag-and-drop / browse file selection built on a native input. Owns the
+ * selected-file list, drag interaction, and client-side validation (`accept`,
+ * `maxSize`/`minSize`, `maxFiles`, custom `validate`); the actual upload stays
+ * with the consumer, reflected per file through `FileUploadItem`. The empty
+ * dropzone is a `SystemState` (`upload` / `upload-error`).
+ *
+ * Accessibility: the input is visually hidden and the `FileUploadTrigger`
+ * button is the focusable, keyboard-operable control (drag-and-drop is a
+ * pointer enhancement). Announce added or rejected files yourself — the
+ * component is not a live region. Inside a `Field` it inherits
+ * `disabled`/`invalid`/`required`.
+ */
+declare const FileUpload: import("react").ForwardRefExoticComponent<FileUploadProps & import("react").RefAttributes<HTMLDivElement>>;
+interface FileUploadDropzoneVariantsOptions {
+  className?: string;
+}
+/**
+ * Class list for an element styled as the dashed drop area — for building a
+ * bespoke dropzone while keeping the brand's border, hover, and drag/invalid
+ * looks. The drag state hooks are `data-dragging` / `data-invalid` /
+ * `data-disabled`.
+ */
+declare function fileUploadDropzoneVariants({ className }?: FileUploadDropzoneVariantsOptions): string;
+interface FileUploadDropzoneProps extends Omit<ComponentPropsWithoutRef<"div">, "className"> {
+  /** Replace the default `SystemState` prompt + `FileUploadTrigger`. */
+  children?: ReactNode;
+  className?: string;
+}
+/**
+ * The dashed drop area. Clicking anywhere in it opens the picker (a pointer
+ * convenience); the `FileUploadTrigger` inside is the focusable control for
+ * keyboard and assistive tech. With no `children` it renders a `SystemState`
+ * (`upload`, or `upload-error` when invalid) with a browse button; pass
+ * `children` to supply your own prompt. Highlights via `data-dragging` while a
+ * file is dragged over it.
+ */
+declare const FileUploadDropzone: import("react").ForwardRefExoticComponent<FileUploadDropzoneProps & import("react").RefAttributes<HTMLDivElement>>;
+type FileUploadTriggerProps = ButtonProps;
+/**
+ * Button that opens the file picker. Rendered inside `FileUploadDropzone` by
+ * default; use it on its own for a compact "attach a file" control with no drop
+ * area. Defaults to the `outline` variant and an upload-icon + "Browse files"
+ * label. A custom label opts into an icon via `startIcon`; pass
+ * `startIcon={null}` to remove the default one. Inherits the upload's
+ * `disabled` state.
+ */
+declare const FileUploadTrigger: import("react").ForwardRefExoticComponent<ButtonProps & import("react").RefAttributes<HTMLButtonElement>>;
+interface FileUploadListProps extends Omit<ComponentPropsWithoutRef<"ul">, "className" | "children"> {
+  /**
+   * Omit to auto-render a `FileUploadItem` per selected file. Pass a function
+   * `(file, index) => ReactNode` to render items with your own upload
+   * `status`/`progress`, or pass elements to render them verbatim.
+   */
+  children?: ReactNode | ((file: File, index: number) => ReactNode);
+  className?: string;
+}
+/**
+ * Container for the selected files. `role="list"` is set explicitly so the
+ * list semantics survive the `flex` reset in Safari/VoiceOver. Renders nothing
+ * while empty in the default (auto or render-prop) mode.
+ */
+declare const FileUploadList: import("react").ForwardRefExoticComponent<FileUploadListProps & import("react").RefAttributes<HTMLUListElement>>;
+interface FileUploadItemProps extends Omit<ComponentPropsWithoutRef<"li">, "className" | "children"> {
+  /** The file this row represents (name, size, and type come from it). */
+  file: File;
+  /** Upload lifecycle you drive: `uploading` shows a progress bar, `success`/`error` a status icon. */
+  status?: FileUploadItemStatus;
+  /** Completion 0–100 while `status="uploading"`. Omit for an indeterminate bar. */
+  progress?: number;
+  /** Message shown while `status="error"`, in place of the size. */
+  error?: ReactNode;
+  /** Show the remove button. Defaults to `true`. */
+  removable?: boolean;
+  /** Remove handler. Defaults to removing this file from the selection. */
+  onRemove?: () => void;
+  /** Accessible name for the remove button. Defaults to `Remove {file name}`. */
+  removeLabel?: string;
+  /** Leading visual. Defaults to an auto thumbnail for images, else a file icon. */
+  preview?: ReactNode;
+  /** Replace the entire row body. */
+  children?: ReactNode;
+  className?: string;
+}
+/**
+ * One selected file: a thumbnail (auto-generated for images) or file icon, the
+ * name, and — depending on `status` — its size, an upload progress bar, or an
+ * error message, plus a remove button. `status`/`progress`/`error` are
+ * consumer-driven so the row reflects real upload state.
+ */
+declare const FileUploadItem: import("react").ForwardRefExoticComponent<FileUploadItemProps & import("react").RefAttributes<HTMLLIElement>>;
+//#endregion
+export { FileUpload, FileUploadDropzone, FileUploadDropzoneProps, FileUploadDropzoneVariantsOptions, FileUploadHandle, FileUploadItem, FileUploadItemProps, FileUploadItemStatus, FileUploadList, FileUploadListProps, FileUploadProps, FileUploadRejection, FileUploadRejectionCode, FileUploadRenderState, FileUploadTrigger, FileUploadTriggerProps, fileUploadDropzoneVariants, formatFileSize, useFileUpload };