@vkzstudio/muza-ui 1.0.43 → 1.0.45

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

@@ -1,27 +1,49 @@
 import * as React from 'react';
+/**
+ * Internal base props shared by both `file` and `url` variants of FileItem.
+ * Not exported — FileItem is an internal sub-component of FileUpload.
+ */
 interface FileItemBaseProps {
+    /** Whether the file has finished uploading. Controls which action buttons render. */
     uploaded?: boolean;
+    /** Upload progress in percent (0–100). Renders a progress bar while strictly between 0 and 100. */
     progress?: number;
+    /** Controls the item's min-height variant. */
     size?: 'sm' | 'base' | 'lg';
+    /** Prevents interaction and applies disabled styling. */
     disabled?: boolean;
+    /** Hides the delete button; download button remains available for uploaded items. */
     readOnly?: boolean;
+    /** Hint message displayed below the item with secondary styling. */
     note?: React.ReactNode;
+    /** Error message displayed below the item with error styling. */
     error?: React.ReactNode;
     /** Secondary text displayed below the file name (e.g., file size). */
     secondaryText?: React.ReactNode;
+    /** Fires when the delete button is clicked. */
     onDelete: () => void;
+    /**
+     * When provided, replaces the default download behavior. Use when the consumer
+     * needs to mint a fresh URL (e.g., short-lived authed URL fetched by UUID) or
+     * pull the authoritative copy from a server instead of using the local blob.
+     */
+    onDownload?: () => void;
+    /** Fires when an internal error occurs (e.g., download failure). */
     onError?: (error: string, file?: File) => void;
 }
+/** Internal props for a FileItem backed by a local `File` object. */
 interface FileItemFileProps extends FileItemBaseProps {
     source: 'file';
     file: File;
 }
+/** Internal props for a FileItem backed by a remote URL (already-uploaded file). */
 interface FileItemUrlProps extends FileItemBaseProps {
     source: 'url';
     url: string;
     name: string;
     type?: string;
 }
+/** Discriminated union: `source: 'file'` uses a local File, `source: 'url'` references a remote URL. */
 type FileItemProps = FileItemFileProps | FileItemUrlProps;
 export declare const FileItem: (props: FileItemProps) => import("react/jsx-runtime").JSX.Element;
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"FileItem.d.ts","sourceRoot":"","sources":["../../../src/components/FileUpload/FileItem.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AA8C9B,UAAU,iBAAiB;IACzB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,IAAI,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAAA;IAC3B,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,IAAI,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IACtB,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IACvB,sEAAsE;IACtE,aAAa,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC/B,QAAQ,EAAE,MAAM,IAAI,CAAA;IACpB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,IAAI,KAAK,IAAI,CAAA;CAC/C;AAED,UAAU,iBAAkB,SAAQ,iBAAiB;IACnD,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,IAAI,CAAA;CACX;AAED,UAAU,gBAAiB,SAAQ,iBAAiB;IAClD,MAAM,EAAE,KAAK,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,KAAK,aAAa,GAAG,iBAAiB,GAAG,gBAAgB,CAAA;AAsEzD,eAAO,MAAM,QAAQ,GAAI,OAAO,aAAa,4CAuO5C,CAAA"}
+{"version":3,"file":"FileItem.d.ts","sourceRoot":"","sources":["../../../src/components/FileUpload/FileItem.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AA8C9B;;;GAGG;AACH,UAAU,iBAAiB;IACzB,qFAAqF;IACrF,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,mGAAmG;IACnG,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAAA;IAC3B,yDAAyD;IACzD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,qFAAqF;IACrF,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,oEAAoE;IACpE,IAAI,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IACtB,iEAAiE;IACjE,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IACvB,sEAAsE;IACtE,aAAa,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC/B,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,IAAI,CAAA;IACpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,IAAI,CAAA;IACvB,oEAAoE;IACpE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,IAAI,KAAK,IAAI,CAAA;CAC/C;AAED,qEAAqE;AACrE,UAAU,iBAAkB,SAAQ,iBAAiB;IACnD,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,IAAI,CAAA;CACX;AAED,oFAAoF;AACpF,UAAU,gBAAiB,SAAQ,iBAAiB;IAClD,MAAM,EAAE,KAAK,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,wGAAwG;AACxG,KAAK,aAAa,GAAG,iBAAiB,GAAG,gBAAgB,CAAA;AAsEzD,eAAO,MAAM,QAAQ,GAAI,OAAO,aAAa,4CAiO5C,CAAA"}

package/dist/components/FileUpload/FileItem.js

@@ -1,12 +1,12 @@
 import { jsxs as f, jsx as t } from "react/jsx-runtime";
 import * as p from "react";
-import { cva as O } from "class-variance-authority";
-import { useMuzaTranslations as _ } from "../../translations/TranslationContext.js";
-import { Flex as U } from "../Flex/Flex.js";
+import { cva as _ } from "class-variance-authority";
+import { useMuzaTranslations as B } from "../../translations/TranslationContext.js";
+import { Flex as z } from "../Flex/Flex.js";
 import { cn as a } from "../../utils/cn.js";
-import { GalleryOutline as B, FileTextBold as M, CloseCircleBold as j, DownloadMinimalisticBold as I, TrashBinTrashBold as R } from "@solar-icons/react-perf";
+import { GalleryOutline as M, FileTextBold as j, CloseCircleBold as D, DownloadMinimalisticBold as I, TrashBinTrashBold as R } from "@solar-icons/react-perf";
 import { Typography as u } from "../Typography/Typography.js";
-const D = (e, l, i) => {
+const S = (e, l, i) => {
   let n = null, o = null;
   try {
     n = URL.createObjectURL(e), o = document.createElement("a"), o.href = n, o.download = e.name, o.style.display = "none", document.body.appendChild(o), o.click();
@@ -16,7 +16,7 @@ const D = (e, l, i) => {
   } finally {
     o && document.body.contains(o) && document.body.removeChild(o), n && URL.revokeObjectURL(n);
   }
-}, S = O(
+}, A = _(
   [
     "flex flex-1 items-center gap-sm rounded-full border transition-colors",
     "relative pr-comp-input-p-hor pl-comp-input-p-hor",
@@ -63,7 +63,7 @@ const D = (e, l, i) => {
   "bg-none cursor-pointer disabled:cursor-not-allowed",
   "text-comp-file-upload-icon-def-secondary",
   "disabled:text-comp-file-upload-icon-def-disabled"
-]), A = /\.(jpe?g|png|gif|webp|svg|bmp|ico|avif|tiff?)$/i, z = /\.(pdf|docx?|txt|rtf|odt|xlsx?|csv|pptx?|md|tex)$/i, E = [
+]), F = /\.(jpe?g|png|gif|webp|svg|bmp|ico|avif|tiff?)$/i, E = /\.(pdf|docx?|txt|rtf|odt|xlsx?|csv|pptx?|md|tex)$/i, L = [
   "application/pdf",
   "application/msword",
   "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
@@ -76,7 +76,7 @@ const D = (e, l, i) => {
   "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
   "application/vnd.ms-powerpoint",
   "application/vnd.openxmlformats-officedocument.presentationml.presentation"
-], P = (e) => {
+], q = (e) => {
   const {
     uploaded: l,
     progress: i,
@@ -87,37 +87,38 @@ const D = (e, l, i) => {
     error: s,
     secondaryText: y,
     onDelete: g,
-    onError: L
-  } = e, m = _(), [v, w] = p.useState(!1), N = e.source === "file" ? e.file.name : e.name, b = e.source === "url" ? (e.type ?? "").startsWith("image/") || A.test(e.name) : e.file.type.startsWith("image/"), T = e.source === "url" ? E.includes(e.type ?? "") || z.test(e.name) : E.includes(e.file.type) || z.test(e.file.name), d = e.source === "file" ? e.file : e.url, C = p.useMemo(() => o ? "disabled" : s ? "error" : typeof i == "number" && i > 0 && i < 100 ? "loading" : "default", [o, s, i]), x = p.useMemo(() => {
+    onDownload: v,
+    onError: T
+  } = e, m = B(), [w, N] = p.useState(!1), k = e.source === "file" ? e.file.name : e.name, b = e.source === "url" ? (e.type ?? "").startsWith("image/") || F.test(e.name) : e.file.type.startsWith("image/"), C = e.source === "url" ? L.includes(e.type ?? "") || E.test(e.name) : L.includes(e.file.type) || E.test(e.file.name), d = e.source === "file" ? e.file : e.url, O = p.useMemo(() => o ? "disabled" : s ? "error" : typeof i == "number" && i > 0 && i < 100 ? "loading" : "default", [o, s, i]), x = p.useMemo(() => {
     if (b)
       return typeof d == "string" ? d : URL.createObjectURL(d);
   }, [b, d]);
-  return p.useEffect(() => w(!1), [d]), /* @__PURE__ */ f(U, { gap: "sm", direction: "column", component: "li", children: [
+  return p.useEffect(() => N(!1), [d]), /* @__PURE__ */ f(z, { gap: "sm", direction: "column", component: "li", children: [
     /* @__PURE__ */ f(
       "div",
       {
         className: a(
-          S({
-            variant: C,
+          A({
+            variant: O,
             size: n
           })
         ),
         children: [
-          x && !v && /* @__PURE__ */ t(
+          x && !w && /* @__PURE__ */ t(
             "img",
             {
               src: x,
-              alt: N,
+              alt: k,
               width: 24,
               height: 24,
-              onError: () => w(!0),
+              onError: () => N(!0),
               className: a("size-icon-medium shrink-0 rounded-xs object-cover", {
                 "opacity-50 saturate-0": o
               })
             }
           ),
-          x && v && /* @__PURE__ */ t(
-            B,
+          x && w && /* @__PURE__ */ t(
+            M,
             {
               className: a(
                 "size-icon-medium shrink-0 text-comp-file-upload-icon-def-secondary",
@@ -127,8 +128,8 @@ const D = (e, l, i) => {
               )
             }
           ),
-          !b && T && /* @__PURE__ */ t(
-            M,
+          !b && C && /* @__PURE__ */ t(
+            j,
             {
               className: a(
                 "size-icon-medium shrink-0 text-comp-file-upload-icon-def-secondary",
@@ -138,7 +139,7 @@ const D = (e, l, i) => {
               )
             }
           ),
-          /* @__PURE__ */ f(U, { direction: "column", className: "min-w-0 flex-1 justify-center", children: [
+          /* @__PURE__ */ f(z, { direction: "column", className: "min-w-0 flex-1 justify-center", children: [
             /* @__PURE__ */ t(
               u,
               {
@@ -148,7 +149,7 @@ const D = (e, l, i) => {
                 variant: "body",
                 weight: "medium",
                 fixY: !0,
-                children: N
+                children: k
               }
             ),
             y && /* @__PURE__ */ t(
@@ -177,7 +178,7 @@ const D = (e, l, i) => {
                 "focus-visible:text-comp-file-upload-icon-def-focused",
                 "disabled:text-comp-file-upload-icon-def-disabled"
               ),
-              children: /* @__PURE__ */ t(j, { className: "size-icon-medium" })
+              children: /* @__PURE__ */ t(D, { className: "size-icon-medium" })
             }
           ),
           l && /* @__PURE__ */ f("div", { className: "flex gap-xl", children: [
@@ -186,24 +187,20 @@ const D = (e, l, i) => {
               {
                 type: "button",
                 disabled: o,
-                onClick: () => e.source === "url" ? (() => {
-                  try {
-                    const k = new URL(
-                      e.url,
-                      window.location.origin
-                    );
-                    ["http:", "https:", "blob:"].includes(k.protocol) && window.open(
-                      k.href,
-                      "_blank",
-                      "noopener,noreferrer"
-                    );
-                  } catch {
+                onClick: () => {
+                  if (v) {
+                    v();
+                    return;
                   }
-                })() : D(
-                  e.file,
-                  L,
-                  m.fileUpload.downloadError
-                ),
+                  if (e.source === "url")
+                    try {
+                      const U = new URL(e.url, window.location.origin);
+                      ["http:", "https:", "blob:"].includes(U.protocol) && window.open(U.href, "_blank", "noopener,noreferrer");
+                    } catch {
+                    }
+                  else
+                    S(e.file, T, m.fileUpload.downloadError);
+                },
                 "aria-label": m.fileUpload.downloadButtonAriaLabel,
                 className: a(
                   h,
@@ -273,5 +270,5 @@ const D = (e, l, i) => {
   ] });
 };
 export {
-  P as FileItem
+  q as FileItem
 };

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

@@ -9,117 +9,212 @@ declare const fileUploadVariants: (props?: ({
 /**
  * Represents a remote file that is already uploaded and accessible via URL.
  * Used to display previously-uploaded files without re-fetching them as `File` objects.
+ *
+ * @example
+ * const urls: PreselectedUrl[] = [
+ *   { url: 'https://cdn.example.com/photo.jpg', name: 'photo.jpg', type: 'image/jpeg', secondaryText: '3.2 MB' },
+ *   { url: 'https://cdn.example.com/report.pdf', name: 'report.pdf', type: 'application/pdf' },
+ * ]
  */
 export interface PreselectedUrl {
-    /** Direct URL to the file. */
+    /** Direct URL to the file. Used for opening the file in a new tab on download. */
     url: string;
-    /** Display name for the file. */
+    /** Display name shown in the file list item. */
     name: string;
-    /** MIME type — if starts with `"image/"`, shows thumbnail. Falls back to extension sniffing from name. */
+    /**
+     * MIME type used to pick the file icon. If it starts with `"image/"` the item renders a
+     * thumbnail from `url`. When omitted, the extension in `name` is used as a fallback.
+     */
     type?: string;
-    /** File size in bytes (for display). */
+    /** File size in bytes. Currently informational; not rendered directly — use `secondaryText` for display. */
     size?: number;
-    /** Secondary text displayed below the file name (e.g., formatted file size). */
+    /** Secondary text displayed below the file name (e.g., formatted file size like `'3.2 MB'`). */
     secondaryText?: React.ReactNode;
 }
+/**
+ * Upload status for a single file in `FileUpload`, matched by index to `preselectedFiles`.
+ *
+ * @example
+ * // Second file is 75% uploaded, first and third are done
+ * const status: FileUploadStatus[] = [
+ *   { uploaded: true },
+ *   { uploaded: false, progress: 75 },
+ *   { uploaded: true },
+ * ]
+ */
+export interface FileUploadStatus {
+    /** Whether the file has finished uploading. Controls the icon (close vs download/trash). */
+    uploaded: boolean;
+    /** Upload progress in percent (0–100). Renders a progress bar under the item while strictly between 0 and 100. */
+    progress?: number;
+}
 /**
  * Props for the FileUpload component.
  * Extends standard div attributes except `onDrop`, `onError`, and `onChange`
  * (replaced by component-specific callbacks).
  */
 export interface FileUploadProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onDrop' | 'onError' | 'onChange'>, Omit<VariantProps<typeof fileUploadVariants>, 'isDragActive'> {
-    /** Fires when files are dropped or selected. Receives array of accepted files. */
+    /**
+     * Fires when files are dropped or selected (after internal validation). Receives the
+     * array of newly accepted files from the current interaction only — not the cumulative
+     * list. Use `onChange` for the full list after each change.
+     *
+     * @example
+     * <FileUpload onDrop={(files) => uploadToServer(files)} />
+     */
     onDrop?: (acceptedFiles: File[]) => void;
     /**
-     * Accepted file types as MIME type strings.
+     * Accepted file types as MIME type strings. Accepts either a single MIME type or an array.
+     * Wildcards (`image/*`, `video/*`) are supported.
      *
      * @example
-     * accept="image/*"
-     * accept={['image/*', 'application/pdf']}
+     * <FileUpload accept="image/*" />
+     * <FileUpload accept={['image/*', 'application/pdf']} />
      */
     accept?: string | string[];
-    /** Allows selecting multiple files simultaneously. @default true */
+    /** Allows selecting multiple files simultaneously. When `false`, the dropzone hides after the first file is selected. @default true */
     multiple?: boolean;
-    /** Maximum allowed file size in bytes. */
+    /**
+     * Maximum allowed file size in bytes. Files exceeding this size are rejected and trigger `onError`.
+     *
+     * @example
+     * <FileUpload maxSize={5 * 1024 * 1024} /> // 5 MB
+     */
     maxSize?: number;
     /** Custom error message when a file exceeds `maxSize`. Defaults to a translated message with the size in MB. */
     maxSizeErrorMessage?: string;
-    /** Maximum number of files allowed. When reached, the dropzone is hidden. */
+    /** Maximum number of files allowed (counts both `preselectedFiles` and `preselectedUrls`). When reached, the dropzone is hidden. */
     maxFiles?: number;
-    /** Custom error message when file count exceeds `maxFiles`. Defaults to a translated message. */
+    /** Custom error message when file count exceeds `maxFiles`. Defaults to a translated message with the count. */
     maxFilesErrorMessage?: string;
     /** Controls the visual size of file items in the list. @default 'base' */
     size?: 'sm' | 'base' | 'lg';
-    /** Prevents interaction and applies disabled styling. @default false */
+    /** Prevents interaction and applies disabled styling to the dropzone and all file items. @default false */
     disabled?: boolean;
-    /** Hides the dropzone and shows only uploaded files without delete buttons. @default false */
+    /** Hides the dropzone and shows only uploaded files without delete buttons. Download buttons remain available. @default false */
     readOnly?: boolean;
     /** Title text displayed inside the dropzone area. Defaults to a translated string. */
     title?: string;
-    /** Label displayed above the upload area. */
+    /** Label displayed above the upload area via `FormField`. */
     label?: string;
-    /** Subtitle text displayed below the title inside the dropzone. */
+    /** Subtitle text displayed below the title inside the dropzone (typically used for supported formats hint). */
     subtitle?: string;
-    /** Applies error border and text styling to the dropzone. */
+    /** Applies error border and text styling to the dropzone. Independent of per-file errors in `itemErrors`. */
     error?: boolean;
     /** Marks the field as required and displays a red asterisk next to the label. @default false */
     required?: boolean;
     /** Hides the required asterisk even when `required` is true. @default false */
     disableRequiredAsterisk?: boolean;
     /**
-     * Additional options passed to react-dropzone.
-     * Props managed by the component (`onDrop`, `accept`, `multiple`, `maxSize`, `disabled`) are excluded.
+     * Additional options passed to the underlying react-dropzone hook. Props already managed by
+     * `FileUpload` (`onDrop`, `accept`, `multiple`, `maxSize`, `maxFiles`, `disabled`) are excluded.
+     *
      * @see DropzoneOptions
      */
     dropzoneOptions?: Omit<DropzoneOptions, 'onDrop' | 'accept' | 'multiple' | 'maxSize' | 'maxFiles' | 'disabled'>;
     /** Files displayed in the list on mount. @default [] */
     preselectedFiles?: File[];
     /**
-     * Upload status for each file, matched by index to `preselectedFiles`.
-     * Each entry contains `uploaded` (boolean) and optional `progress` (0-100).
+     * Upload status for each file, matched by index to `preselectedFiles`. Omit or pass an empty
+     * array to treat all files as not-yet-uploaded.
+     *
+     * @example
+     * <FileUpload
+     *   preselectedFiles={[file1, file2]}
+     *   fileStatus={[{ uploaded: true }, { uploaded: false, progress: 42 }]}
+     * />
+     *
+     * @see FileUploadStatus
      * @default []
      */
-    fileStatus?: {
-        uploaded: boolean;
-        progress?: number;
-    }[];
+    fileStatus?: FileUploadStatus[];
     /**
-     * Per-file error messages keyed by File reference.
+     * Per-file error messages keyed by File reference. Displayed below the file item with error styling.
      *
      * @example
-     * const errors = new Map<File, string>([[file, 'Upload failed']])
-     * <FileUpload itemErrors={errors} />
+     * const itemErrors = new Map<File, React.ReactNode>([[file, 'Upload failed']])
+     * <FileUpload itemErrors={itemErrors} />
      */
     itemErrors?: Map<File, React.ReactNode>;
     /**
-     * Per-file hint messages keyed by File reference.
+     * Per-file hint messages keyed by File reference. Displayed below the file item with secondary styling.
      *
      * @example
-     * const hints = new Map<File, string>([[file, 'Will be optimized']])
-     * <FileUpload itemHints={hints} />
+     * const itemHints = new Map<File, React.ReactNode>([[file, 'Will be optimized before upload']])
+     * <FileUpload itemHints={itemHints} />
      */
     itemHints?: Map<File, React.ReactNode>;
     /**
-     * Per-file secondary text keyed by File reference (e.g., formatted file size).
+     * Per-file secondary text keyed by File reference (e.g., formatted file size). Displayed below the file name inside the item.
      *
      * @example
-     * const texts = new Map<File, React.ReactNode>([[file, '7 MB']])
-     * <FileUpload itemSecondaryTexts={texts} />
+     * const itemSecondaryTexts = new Map<File, React.ReactNode>([[file, '7 MB']])
+     * <FileUpload itemSecondaryTexts={itemSecondaryTexts} />
      */
     itemSecondaryTexts?: Map<File, React.ReactNode>;
-    /** Fires when an error occurs. Receives the error message and the optional file that caused it. */
+    /**
+     * Fires when an error occurs (file too large, too many files, processing or deletion failure).
+     * Receives the error message and the optional file that caused it.
+     *
+     * @example
+     * <FileUpload onError={(msg, file) => toast({ variant: 'error', text: msg })} />
+     */
     onError?: (error: string, file?: File) => void;
-    /** Fires when a file is deleted. Receives the deleted file and its index. */
+    /** Fires when a `File` item is removed. Receives the deleted file and its index in `preselectedFiles`. */
     onDelete?: (file: File, index: number) => void;
-    /** Fires when the file list changes. Receives the updated array of all files. */
+    /**
+     * Fires when the internal file list changes (after drop or delete). Receives the full updated array,
+     * including previously-selected files.
+     *
+     * @example
+     * <FileUpload onChange={(files) => setValue('attachments', files)} />
+     */
     onChange?: (files: File[]) => void;
-    /** Already-uploaded files to display via URL, without needing `File` objects. @default [] */
+    /**
+     * Already-uploaded files to display via URL, without needing `File` objects. Rendered before
+     * `preselectedFiles` in the list.
+     *
+     * @see PreselectedUrl
+     * @default []
+     */
     preselectedUrls?: PreselectedUrl[];
-    /** Fires when a URL-backed item is deleted. Receives the item and its index in the `preselectedUrls` array. */
+    /** Fires when a URL-backed item is removed. Receives the item and its index in `preselectedUrls`. @see PreselectedUrl */
     onDeleteUrl?: (item: PreselectedUrl, index: number) => void;
-    /** Extra content rendered inline next to the label (e.g. a tooltip icon). */
+    /**
+     * Fires when the download button is clicked on a URL-backed item. When provided,
+     * replaces the default `window.open` behavior — use this when the URL needs to be
+     * minted on demand (e.g., short-lived authed URLs fetched by UUID).
+     *
+     * @example
+     * <FileUpload
+     *   preselectedUrls={items}
+     *   onDownloadUrl={async (_item, index) => {
+     *     const fresh = await fetchAuthedUrl(items[index].uuid)
+     *     window.open(fresh, '_blank', 'noopener,noreferrer')
+     *   }}
+     * />
+     *
+     * @see PreselectedUrl
+     */
+    onDownloadUrl?: (item: PreselectedUrl, index: number) => void;
+    /**
+     * Fires when the download button is clicked on an uploaded `File` item. When provided,
+     * replaces the default blob-download behavior — use this when the authoritative copy
+     * lives on a server and should be fetched rather than streamed from the local `File`.
+     *
+     * @example
+     * <FileUpload
+     *   preselectedFiles={files}
+     *   onDownloadFile={async (file) => {
+     *     const fresh = await fetchAuthedUrl(file.name)
+     *     window.open(fresh, '_blank', 'noopener,noreferrer')
+     *   }}
+     * />
+     */
+    onDownloadFile?: (file: File, index: number) => void;
+    /** Extra content rendered inline next to the label (e.g. a tooltip icon). Takes precedence over `infoTooltip`. */
     labelExtra?: React.ReactNode;
-    /** Tooltip content shown in an info icon next to the label. Overridden by `labelExtra` if both are provided. */
+    /** Tooltip content shown in an info icon next to the label. Ignored when `labelExtra` is provided. */
     infoTooltip?: string;
 }
 declare const FileUpload: React.ForwardRefExoticComponent<FileUploadProps & React.RefAttributes<HTMLDivElement>>;

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

@@ -1 +1 @@
-{"version":3,"file":"FileUpload.d.ts","sourceRoot":"","sources":["../../../src/components/FileUpload/FileUpload.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"FileUpload.d.ts","sourceRoot":"","sources":["../../../src/components/FileUpload/FileUpload.tsx"],"names":[],"mappings":"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"}