@mezzanine-ui/react 1.0.0-rc.5 → 1.0.0-rc.7

package/Tooltip/Tooltip.js

@@ -12,7 +12,45 @@ import Popper from '../Popper/Popper.js';
 import cx from 'clsx';
 
 /**
- * The react component for `mezzanine` tooltip.
+ * 滑鼠懸停時顯示的提示框元件。
+ *
+ * 採用 render prop 模式，`children` 為接收 `ref`、`onMouseEnter`、`onMouseLeave` 的函式。
+ * 內部使用 `Popper` 進行定位，並整合 `flip`、`shift` 等 floating-ui middleware 自動調整位置以避免溢出視窗。
+ * 支援自訂偏移量、顯示箭頭及滑鼠離開延遲時間。
+ *
+ * @example
+ * ```tsx
+ * import Tooltip from '@mezzanine-ui/react/Tooltip';
+ *
+ * // 基本用法
+ * <Tooltip title="這是提示文字">
+ *   {({ ref, onMouseEnter, onMouseLeave }) => (
+ *     <button ref={ref} onMouseEnter={onMouseEnter} onMouseLeave={onMouseLeave}>
+ *       Hover me
+ *     </button>
+ *   )}
+ * </Tooltip>
+ *
+ * // 自訂位置與關閉箭頭
+ * <Tooltip title="底部提示" arrow={false} options={{ placement: 'bottom' }}>
+ *   {({ ref, onMouseEnter, onMouseLeave }) => (
+ *     <span ref={ref} onMouseEnter={onMouseEnter} onMouseLeave={onMouseLeave}>
+ *       文字
+ *     </span>
+ *   )}
+ * </Tooltip>
+ *
+ * // 增加滑鼠離開延遲
+ * <Tooltip title="可懸停的提示" mouseLeaveDelay={0.3}>
+ *   {({ ref, onMouseEnter, onMouseLeave }) => (
+ *     <button ref={ref} onMouseEnter={onMouseEnter} onMouseLeave={onMouseLeave}>
+ *       按鈕
+ *     </button>
+ *   )}
+ * </Tooltip>
+ * ```
+ *
+ * @see {@link Popper} 浮動定位元件
  */
 const Tooltip = forwardRef(function Tooltip(props, ref) {
     const { anchor: anchorProp, arrow: showArrow = true, children, className, disablePortal = true, mouseLeaveDelay = 0.1, offsetMainAxis, open = false, options = {}, title, ...rest } = props;

package/Tooltip/useDelayMouseEnterLeave.d.ts

@@ -7,4 +7,21 @@ export interface DelayMouseEnterLeave {
     onTargetEnter(v: React.MouseEvent<HTMLElement, MouseEvent>): void;
     visible: boolean;
 }
+/**
+ * 管理帶有延遲的滑鼠移入／移出可見性狀態的 Hook。
+ *
+ * 在滑鼠離開目標或 Popper 時，會等待 `mouseLeaveDelay` 秒後才隱藏，
+ * 讓使用者有時間將游標移入 Popper 內容區域而不觸發消失。
+ *
+ * @example
+ * ```tsx
+ * import { useDelayMouseEnterLeave } from '@mezzanine-ui/react';
+ *
+ * const { visible, onTargetEnter, onLeave, onPopperEnter } = useDelayMouseEnterLeave({
+ *   mouseLeaveDelay: 0.1,
+ * });
+ * ```
+ *
+ * @see {@link Tooltip} 搭配的元件
+ */
 export declare function useDelayMouseEnterLeave(opt: UseDelayMouseEnterLeave): DelayMouseEnterLeave;

package/Tooltip/useDelayMouseEnterLeave.js

@@ -1,5 +1,22 @@
 import { useState, useRef, useCallback } from 'react';
 
+/**
+ * 管理帶有延遲的滑鼠移入／移出可見性狀態的 Hook。
+ *
+ * 在滑鼠離開目標或 Popper 時，會等待 `mouseLeaveDelay` 秒後才隱藏，
+ * 讓使用者有時間將游標移入 Popper 內容區域而不觸發消失。
+ *
+ * @example
+ * ```tsx
+ * import { useDelayMouseEnterLeave } from '@mezzanine-ui/react';
+ *
+ * const { visible, onTargetEnter, onLeave, onPopperEnter } = useDelayMouseEnterLeave({
+ *   mouseLeaveDelay: 0.1,
+ * });
+ * ```
+ *
+ * @see {@link Tooltip} 搭配的元件
+ */
 function useDelayMouseEnterLeave(opt) {
     const { mouseLeaveDelay = 0.1 } = opt || {};
     /** state that control tooltip visible/invisible */

package/Typography/Typography.d.ts

@@ -36,7 +36,29 @@ interface TypographyPropsBase {
 }
 export type TypographyProps<C extends TypographyComponent = 'p'> = ComponentOverridableForwardRefComponentPropsFactory<TypographyComponent, C, TypographyPropsBase>;
 /**
- * The react component for `mezzanine` typography.
+ * 文字排版元件，提供一致的語意化文字樣式。
+ *
+ * 透過 `variant` 套用設計系統中定義的語意排版類型（如 `h1`、`h2`、`h3`、`body`、`caption` 等），
+ * 並自動推斷對應的 HTML 標籤（`h1–h3` → `<h1>–<h3>`，body 系列 → `<p>`，其餘 → `<span>`）。
+ * 可透過 `color` 套用調色盤中的文字色彩，`align` 控制對齊方式，`ellipsis` 啟用單行截斷省略號。
+ * 支援透過 `component` prop 覆寫根元素標籤。
+ *
+ * @example
+ * ```tsx
+ * import Typography from '@mezzanine-ui/react/Typography';
+ *
+ * // 標題
+ * <Typography variant="h1">頁面標題</Typography>
+ *
+ * // 本文
+ * <Typography variant="body">這是一段說明文字。</Typography>
+ *
+ * // 套用色彩
+ * <Typography variant="body" color="error">錯誤提示訊息</Typography>
+ *
+ * // 單行截斷（需搭配 block 或 inline-block 容器）
+ * <Typography variant="caption" ellipsis display="block">超長文字會在此被截斷顯示省略號...</Typography>
+ * ```
  */
 declare const Typography: import("react").ForwardRefExoticComponent<Omit<Omit<import("../utils/jsx-types").ComponentPropsWithoutKeyAndRef<"p">, keyof TypographyPropsBase> & TypographyPropsBase, "component"> & {
     component?: TypographyComponent | undefined;

package/Typography/Typography.js

@@ -13,7 +13,29 @@ function getComponentFromType(type) {
     return 'span';
 }
 /**
- * The react component for `mezzanine` typography.
+ * 文字排版元件，提供一致的語意化文字樣式。
+ *
+ * 透過 `variant` 套用設計系統中定義的語意排版類型（如 `h1`、`h2`、`h3`、`body`、`caption` 等），
+ * 並自動推斷對應的 HTML 標籤（`h1–h3` → `<h1>–<h3>`，body 系列 → `<p>`，其餘 → `<span>`）。
+ * 可透過 `color` 套用調色盤中的文字色彩，`align` 控制對齊方式，`ellipsis` 啟用單行截斷省略號。
+ * 支援透過 `component` prop 覆寫根元素標籤。
+ *
+ * @example
+ * ```tsx
+ * import Typography from '@mezzanine-ui/react/Typography';
+ *
+ * // 標題
+ * <Typography variant="h1">頁面標題</Typography>
+ *
+ * // 本文
+ * <Typography variant="body">這是一段說明文字。</Typography>
+ *
+ * // 套用色彩
+ * <Typography variant="body" color="error">錯誤提示訊息</Typography>
+ *
+ * // 單行截斷（需搭配 block 或 inline-block 容器）
+ * <Typography variant="caption" ellipsis display="block">超長文字會在此被截斷顯示省略號...</Typography>
+ * ```
  */
 const Typography = forwardRef(function Typography(props, ref) {
     const { align, children, className, color, component, display, ellipsis = false, noWrap = false, variant = 'body', style: styleProp, ...rest } = props;

package/Upload/Upload.d.ts

@@ -2,6 +2,7 @@ import { type UploadItemStatus, type UploadMode, type UploadSize } from '@mezzan
 import { type ReactNode } from 'react';
 import { NativeElementPropsWithoutKeyAndRef } from '../utils/jsx-types';
 import type { UploaderProps } from './Uploader';
+import type { UploadPictureCardAriaLabels } from './UploadPictureCard';
 export interface UploadFile {
     /**
      * The file object.
@@ -51,13 +52,17 @@ export interface UploadProps extends Omit<NativeElementPropsWithoutKeyAndRef<'di
      * @default false
      */
     disabled?: boolean;
+    /**
+     * Hints passed into the Uploader dropzone area. Only visible in dropzone modes (`list`, `card-wall`).
+     */
+    dropzoneHints?: UploaderProps['hints'];
     /**
      * Controlled file list for the upload component.
      * Provide this along with `onChange` to fully control the file state.
      */
     files?: UploadFile[];
     /**
-     * Array of hints to display with the upload component.
+     * Array of hints displayed outside the uploader area. Visible in all modes.
      */
     hints?: UploaderProps['hints'];
     /**
@@ -77,11 +82,6 @@ export interface UploadProps extends Omit<NativeElementPropsWithoutKeyAndRef<'di
      * The react ref passed to input element.
      */
     inputRef?: UploaderProps['inputRef'];
-    /**
-     * Whether to fill the width of the container.
-     * @default false
-     */
-    isFillWidth?: boolean;
     /**
      * Maximum number of files allowed to upload.
      * If exceeded, the excess files will be ignored.
@@ -89,7 +89,8 @@ export interface UploadProps extends Omit<NativeElementPropsWithoutKeyAndRef<'di
     maxFiles?: number;
     /**
      * The display mode for the upload component.
-     * - 'list': Display files as a list using UploadItem
+     * - 'list': Display files as a list using UploadItem (with dropzone)
+     * - 'basic-list': Display files as a list without drag-and-drop
      * - 'button-list': Display uploader as a button with files in list format
      * - 'cards': Display image files as picture cards using UploadPictureCard
      * - 'card-wall': Display uploader at top with image files as picture cards below
@@ -129,6 +130,11 @@ export interface UploadProps extends Omit<NativeElementPropsWithoutKeyAndRef<'di
      * This will be used when a file's status becomes 'error' and no errorIcon is provided.
      */
     errorIcon?: ReactNode;
+    /**
+     * Aria labels passed to picture cards in `cards` / `card-wall` mode.
+     * Useful for customizing text such as "Click to Replace".
+     */
+    ariaLabels?: UploadPictureCardAriaLabels;
     /**
      * Fired when files list changes.
      */

package/Upload/Upload.js

@@ -1,21 +1,25 @@
 'use client';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
-import { forwardRef, useRef, useEffect, useMemo, useCallback } from 'react';
+import { forwardRef, useRef, useState, useEffect, useMemo, useCallback } from 'react';
 import { defaultUploadPictureCardErrorMessage, uploadClasses } from '@mezzanine-ui/core/upload';
 import { DangerousFilledIcon, InfoFilledIcon } from '@mezzanine-ui/icons';
+import { isImageFile } from './upload-utils.js';
 import Uploader from './Uploader.js';
 import UploadItem from './UploadItem.js';
-import { isImageFile } from './upload-utils.js';
 import UploadPictureCard from './UploadPictureCard.js';
 import Icon from '../Icon/Icon.js';
+import MediaPreviewModal from '../Modal/MediaPreviewModal.js';
 import cx from 'clsx';
 
 const Upload = forwardRef(function Upload(props, ref) {
-    const { accept, className, disabled = false, mode = 'list', size = 'main', showFileSize = true, files: controlledFiles = [], onUpload, onDelete, onReload, onDownload, onZoomIn, onChange, id, name, multiple = false, maxFiles, hints, uploaderLabel, uploaderIcon, inputRef, inputProps, onMaxFilesExceeded, errorMessage, errorIcon, ...rest } = props;
+    var _a, _b;
+    const { accept, className, disabled = false, dropzoneHints, mode = 'list', size = 'main', showFileSize = true, files: controlledFiles = [], onUpload, onDelete, onReload, onDownload, onZoomIn, onChange, id, name, multiple = false, maxFiles, hints, uploaderLabel, uploaderIcon, inputRef, inputProps, onMaxFilesExceeded, errorMessage, errorIcon, ariaLabels, ...rest } = props;
     const files = controlledFiles;
     const filesRef = useRef(files);
     const replaceFileIdRef = useRef(null);
     const replaceInputRef = useRef(null);
+    const [previewFile, setPreviewFile] = useState(null);
+    const [isPreviewOpen, setIsPreviewOpen] = useState(false);
     useEffect(() => {
         filesRef.current = files;
     }, [files]);
@@ -224,10 +228,34 @@ const Upload = forwardRef(function Upload(props, ref) {
     }, [findFileById, onDownload]);
     const handleZoomIn = useCallback((fileId) => {
         const file = findFileById(fileId);
-        if (file && file.file) {
+        if (!file)
+            return;
+        setPreviewFile(file);
+        setIsPreviewOpen(true);
+        if (file.file) {
             onZoomIn === null || onZoomIn === void 0 ? void 0 : onZoomIn(fileId, file.file);
         }
     }, [findFileById, onZoomIn]);
+    const [previewObjectUrl, setPreviewObjectUrl] = useState(null);
+    useEffect(() => {
+        if (!previewFile || previewFile.url || !previewFile.file) {
+            setPreviewObjectUrl(null);
+            return;
+        }
+        if (!isImageFile(previewFile.file, previewFile.url)) {
+            setPreviewObjectUrl(null);
+            return;
+        }
+        const url = URL.createObjectURL(previewFile.file);
+        setPreviewObjectUrl(url);
+        return () => {
+            URL.revokeObjectURL(url);
+        };
+    }, [previewFile]);
+    const previewIsImage = previewFile
+        ? isImageFile(previewFile.file, previewFile.url)
+        : false;
+    const previewImageSrc = (_b = (_a = previewFile === null || previewFile === void 0 ? void 0 : previewFile.url) !== null && _a !== void 0 ? _a : previewObjectUrl) !== null && _b !== void 0 ? _b : '';
     const { imageFiles, nonImageFiles } = useMemo(() => {
         const images = [];
         const nonImages = [];
@@ -246,19 +274,23 @@ const Upload = forwardRef(function Upload(props, ref) {
     const uploaderConfig = useMemo(() => {
         const config = {
             list: {
-                isFillWidth: true,
+                mode: 'dropzone',
+                type: 'base',
+            },
+            'basic-list': {
+                mode: 'basic',
                 type: 'base',
             },
             'button-list': {
                 type: 'button',
             },
             cards: {
+                mode: 'basic',
                 type: 'base',
-                isFillWidth: false,
             },
             'card-wall': {
+                mode: 'basic',
                 type: 'base',
-                isFillWidth: false,
             },
         };
         return config[mode];
@@ -266,7 +298,7 @@ const Upload = forwardRef(function Upload(props, ref) {
     const topUploaderConfig = useMemo(() => {
         if (mode === 'card-wall') {
             return {
-                isFillWidth: true,
+                mode: 'dropzone',
                 type: 'base',
             };
         }
@@ -296,18 +328,19 @@ const Upload = forwardRef(function Upload(props, ref) {
         handleDownload,
         handleReload,
     ]);
-    const uploaderElement = (jsx(Uploader, { accept: accept, disabled: effectiveDisabled, id: id, name: name, multiple: multiple, label: uploaderLabel, icon: uploaderIcon, inputRef: inputRef, inputProps: inputProps, hints: hints, onUpload: handleUpload, ...uploaderConfig }));
-    const topUploaderElement = topUploaderConfig ? (jsx(Uploader, { accept: accept, disabled: effectiveDisabled, id: id ? `${id}-top` : undefined, name: name, multiple: multiple, label: uploaderLabel, icon: uploaderIcon, inputRef: inputRef, inputProps: inputProps, hints: hints, onUpload: handleUpload, ...topUploaderConfig })) : null;
+    const uploaderElement = (jsx(Uploader, { accept: accept, disabled: effectiveDisabled, id: id, name: name, multiple: multiple, label: uploaderLabel, icon: uploaderIcon, inputRef: inputRef, inputProps: inputProps, hints: uploaderConfig.mode === 'dropzone' ? dropzoneHints : undefined, onUpload: handleUpload, ...uploaderConfig }));
+    const topUploaderElement = topUploaderConfig ? (jsx(Uploader, { accept: accept, disabled: effectiveDisabled, id: id ? `${id}-top` : undefined, name: name, multiple: multiple, label: uploaderLabel, icon: uploaderIcon, inputRef: inputRef, inputProps: inputProps, hints: dropzoneHints, onUpload: handleUpload, ...topUploaderConfig })) : null;
+    // When a top uploader exists (card-wall mode), the inline card uploader is not needed.
+    const inlineCardUploaderElement = topUploaderElement ? null : uploaderElement;
     const hintsElement = useMemo(() => {
-        if (!hints ||
-            hints.length === 0 ||
-            mode === 'list' ||
-            mode === 'card-wall')
+        if (!hints || hints.length === 0)
             return null;
-        const hintsClassName = mode === 'cards' ? uploadClasses.fillWidthHints : uploadClasses.hints;
+        const hintsClassName = mode === 'list' || mode === 'card-wall' || mode === 'cards'
+            ? uploadClasses.fillWidthHints
+            : uploadClasses.hints;
         return (jsx("ul", { className: hintsClassName, children: hints.map((hint) => (jsxs("li", { className: uploadClasses.hint(hint.type || 'info'), children: [jsx(Icon, { icon: hint.type === 'info' ? InfoFilledIcon : DangerousFilledIcon, color: hint.type === 'info' ? 'info' : 'error', size: 14 }), hint.label] }, hint.label))) }));
     }, [hints, mode]);
-    return (jsxs("div", { ref: ref, className: cx(uploadClasses.host, className, mode === 'cards' && uploadClasses.hostCards), ...rest, children: [topUploaderElement, !shouldUsePictureCard && (jsxs("div", { className: uploadClasses.uploadButtonList, children: [uploaderElement, mode === 'button-list' && hintsElement] })), jsxs("div", { className: cx(uploadClasses.uploadList, shouldUsePictureCard && uploadClasses.uploadListCards), children: [shouldUsePictureCard && (jsxs(Fragment, { children: [imageFiles.map((uploadFile) => (jsx(UploadPictureCard, { file: uploadFile.file, url: uploadFile.url, id: uploadFile.id, status: uploadFile.status, size: size, disabled: disabled, errorMessage: uploadFile.errorMessage, onDelete: () => handleDelete(uploadFile.id), onReload: () => handleReload(uploadFile.id), ...(!isSingleFileCardMode && {
+    return (jsxs("div", { ref: ref, className: cx(uploadClasses.host, className, mode === 'cards' && uploadClasses.hostCards), ...rest, children: [topUploaderElement, mode === 'card-wall' && hintsElement, !shouldUsePictureCard && (jsxs("div", { className: uploadClasses.uploadButtonList, children: [uploaderElement, hintsElement] })), jsxs("div", { className: cx(uploadClasses.uploadList, shouldUsePictureCard && uploadClasses.uploadListCards), children: [shouldUsePictureCard && (jsxs(Fragment, { children: [imageFiles.map((uploadFile) => (jsx(UploadPictureCard, { ariaLabels: ariaLabels, file: uploadFile.file, url: uploadFile.url, id: uploadFile.id, status: uploadFile.status, size: size, disabled: disabled, errorMessage: uploadFile.errorMessage, onDelete: () => handleDelete(uploadFile.id), onReload: () => handleReload(uploadFile.id), ...(!isSingleFileCardMode && {
                                     onDownload: () => handleDownload(uploadFile.id),
                                     onZoomIn: () => handleZoomIn(uploadFile.id),
                                 }), ...(isSingleFileCardMode && {
@@ -317,17 +350,19 @@ const Upload = forwardRef(function Upload(props, ref) {
                                         replaceFileIdRef.current = uploadFile.id;
                                         (_a = replaceInputRef.current) === null || _a === void 0 ? void 0 : _a.click();
                                     },
-                                }) }, uploadFile.id))), !isSingleFileCardMode && uploaderElement, isSingleFileCardMode &&
+                                }) }, uploadFile.id))), nonImageFiles.map((uploadFile) => (jsx(UploadPictureCard, { ariaLabels: ariaLabels, file: uploadFile.file, url: uploadFile.url, id: uploadFile.id, status: uploadFile.status, size: size, disabled: disabled, errorMessage: uploadFile.errorMessage, onDelete: () => handleDelete(uploadFile.id), onReload: () => handleReload(uploadFile.id), ...(!isSingleFileCardMode && {
+                                    onDownload: () => handleDownload(uploadFile.id),
+                                }) }, uploadFile.id))), !isSingleFileCardMode && inlineCardUploaderElement, isSingleFileCardMode &&
                                 imageFiles.length === 0 &&
-                                uploaderElement, isSingleFileCardMode && (jsx("input", { ref: replaceInputRef, accept: accept, style: { display: 'none' }, type: "file", onChange: (e) => {
+                                inlineCardUploaderElement, isSingleFileCardMode && (jsx("input", { ref: replaceInputRef, accept: accept, style: { display: 'none' }, type: "file", onChange: (e) => {
                                     var _a;
                                     const selectedFiles = Array.from((_a = e.target.files) !== null && _a !== void 0 ? _a : []);
                                     e.target.value = '';
                                     if (selectedFiles.length)
                                         handleUpload(selectedFiles);
-                                } }))] })), nonImageFiles.length > 0 && nonImageFiles.map(renderUploadItem), !shouldUsePictureCard &&
+                                } }))] })), !shouldUsePictureCard && nonImageFiles.length > 0 && nonImageFiles.map(renderUploadItem), !shouldUsePictureCard &&
                         imageFiles.length > 0 &&
-                        imageFiles.map(renderUploadItem)] }), mode === 'cards' && hintsElement] }));
+                        imageFiles.map(renderUploadItem)] }), mode === 'cards' && hintsElement, previewFile && previewIsImage && previewImageSrc && (jsx(MediaPreviewModal, { open: isPreviewOpen, onClose: () => setIsPreviewOpen(false), mediaItems: [previewImageSrc] }))] }));
 });
 
 export { Upload as default };

package/Upload/UploadItem.d.ts

@@ -46,9 +46,9 @@ export interface UploadItemProps extends NativeElementPropsWithoutKeyAndRef<'div
      */
     disabled?: boolean;
     /**
-    * The status of the item.
-    * @default 'loading'
-    */
+     * The status of the item.
+     * @default 'loading'
+     */
     status: UploadItemStatus;
     /**
      * The error message to display when status is 'error'.

package/Upload/UploadItem.js

@@ -2,13 +2,14 @@
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 import { uploadItemClasses } from '@mezzanine-ui/core/upload';
 import { forwardRef, useMemo, useRef, useState, useCallback, useEffect } from 'react';
-import { FileIcon, SpinnerIcon, DownloadIcon, ResetIcon, TrashIcon, DangerousFilledIcon } from '@mezzanine-ui/icons';
+import { FileIcon, DownloadIcon, ResetIcon, TrashIcon, DangerousFilledIcon } from '@mezzanine-ui/icons';
 import ClearActions from '../ClearActions/ClearActions.js';
 import Typography from '../Typography/Typography.js';
 import { useIsomorphicLayoutEffect } from '../hooks/useIsomorphicLayoutEffect.js';
 import UploadPictureCard from './UploadPictureCard.js';
 import { isImageFile } from './upload-utils.js';
 import Icon from '../Icon/Icon.js';
+import Spin from '../Spin/Spin.js';
 import Tooltip from '../Tooltip/Tooltip.js';
 import cx from 'clsx';
 
@@ -41,14 +42,12 @@ const UploadItem = forwardRef(function UploadItem(props, ref) {
     }, [(_a = props.file) === null || _a === void 0 ? void 0 : _a.name, props.url]);
     const itemIcon = useMemo(() => {
         if (type === 'thumbnail') {
-            return isImage
-                ? (jsx(UploadPictureCard, { file: props.file, url: props.url, size: "minor", className: uploadItemClasses.thumbnail }))
-                : (jsx("div", { className: uploadItemClasses.thumbnail, children: jsx(Icon, { icon: FileIcon, className: uploadItemClasses.icon, size: 16 }) }));
+            return isImage ? (jsx(UploadPictureCard, { file: props.file, url: props.url, size: "minor", className: uploadItemClasses.thumbnail })) : (jsx("div", { className: uploadItemClasses.thumbnail, children: jsx(Icon, { icon: FileIcon, className: uploadItemClasses.icon, size: 16 }) }));
         }
-        return jsx(Icon, { icon: icon !== null && icon !== void 0 ? icon : FileIcon, className: uploadItemClasses.icon, size: 16 });
+        return (jsx(Icon, { icon: icon !== null && icon !== void 0 ? icon : FileIcon, className: uploadItemClasses.icon, size: 16 }));
     }, [type, icon, props.file, props.url, isImage]);
     const loadingIcon = useMemo(() => {
-        return (jsx("div", { className: uploadItemClasses.loadingIcon, children: jsx(Icon, { icon: SpinnerIcon, color: "brand", spin: true, size: 16 }) }));
+        return (jsx("div", { className: uploadItemClasses.loadingIcon, children: jsx(Spin, { loading: true, size: "minor" }) }));
     }, []);
     const fileNameRef = useRef(null);
     const tooltipRefRef = useRef(null);
@@ -61,7 +60,8 @@ const UploadItem = forwardRef(function UploadItem(props, ref) {
                 tooltipRef(node);
             }
             else if (tooltipRef && 'current' in tooltipRef) {
-                tooltipRef.current = node;
+                tooltipRef.current =
+                    node;
             }
         }
     }, []);
@@ -91,6 +91,8 @@ const UploadItem = forwardRef(function UploadItem(props, ref) {
     const isFinished = useMemo(() => {
         return /done|error/.test(status);
     }, [status]);
+    const shouldShowFileSize = Boolean(showFileSize && isFinished && fileSize);
+    const shouldSingleLineCenter = Boolean(type === 'thumbnail' && fileName && !shouldShowFileSize);
     useEffect(() => {
         if (!props.file && !props.url) {
             console.warn('UploadItem: Both `file` and `url` props are missing. At least one should be provided to display the upload item.');
@@ -112,7 +114,8 @@ const UploadItem = forwardRef(function UploadItem(props, ref) {
                     [uploadItemClasses.alignCenter]: status !== 'done',
                     [uploadItemClasses.error]: status === 'error',
                     [uploadItemClasses.disabled]: disabled,
-                }, className), children: [jsxs("div", { ...rest, "aria-disabled": disabled, className: uploadItemClasses.container, role: "group", tabIndex: disabled ? -1 : 0, children: [jsxs("div", { className: uploadItemClasses.contentWrapper, children: [jsx("div", { className: uploadItemClasses.icon, children: itemIcon }), jsxs("div", { className: uploadItemClasses.content, children: [jsx(Tooltip, { title: isTextTruncated ? fileName : undefined, options: { placement: 'bottom' }, children: ({ onMouseEnter, onMouseLeave, ref: tooltipRef }) => (jsx(Typography, { ref: mergeRefs(tooltipRef), className: uploadItemClasses.name, ellipsis: true, onMouseEnter: onMouseEnter, onMouseLeave: onMouseLeave, children: fileName })) }), showFileSize && isFinished && fileSize && (jsx(Typography, { className: uploadItemClasses.fontSize, children: fileSize }))] })] }), jsxs("div", { className: uploadItemClasses.actions, children: [status === 'loading' && (jsxs(Fragment, { children: [loadingIcon, jsx(ClearActions, { onClick: onCancel, className: uploadItemClasses.closeIcon, role: "button" })] })), status === 'done' && !disabled && (jsx(Icon, { icon: DownloadIcon, size: 16, className: uploadItemClasses.downloadIcon, onClick: onDownload })), status === 'error' && !disabled && (jsx(Icon, { icon: ResetIcon, size: 16, className: uploadItemClasses.resetIcon, onClick: onReload }))] })] }), isFinished && !disabled && (jsx("div", { className: uploadItemClasses.deleteContent, children: jsx(Icon, { icon: TrashIcon, size: 16, className: uploadItemClasses.deleteIcon, onClick: onDelete }) }))] }), status === 'error' && errorMessage && (jsxs("div", { className: uploadItemClasses.errorMessage, children: [jsx(Icon, { icon: errorIcon !== null && errorIcon !== void 0 ? errorIcon : DangerousFilledIcon, size: 14, color: "error", className: uploadItemClasses.errorIcon }), jsx(Typography, { color: "text-error", variant: "caption", className: uploadItemClasses.errorMessageText, children: errorMessage })] }))] }));
+                    [uploadItemClasses.singleLineContent]: shouldSingleLineCenter,
+                }, className), children: [jsxs("div", { ...rest, "aria-disabled": disabled, className: uploadItemClasses.container, role: "group", tabIndex: disabled ? -1 : 0, children: [jsxs("div", { className: uploadItemClasses.contentWrapper, children: [jsx("div", { className: uploadItemClasses.icon, children: itemIcon }), jsxs("div", { className: uploadItemClasses.content, children: [jsx(Tooltip, { title: isTextTruncated ? fileName : undefined, options: { placement: 'bottom' }, children: ({ onMouseEnter, onMouseLeave, ref: tooltipRef }) => (jsx(Typography, { ref: mergeRefs(tooltipRef), className: uploadItemClasses.name, ellipsis: true, onMouseEnter: onMouseEnter, onMouseLeave: onMouseLeave, children: fileName })) }), shouldShowFileSize && (jsx(Typography, { className: uploadItemClasses.fontSize, children: fileSize }))] })] }), jsxs("div", { className: uploadItemClasses.actions, children: [status === 'loading' && (jsxs(Fragment, { children: [loadingIcon, jsx(ClearActions, { onClick: onCancel, className: uploadItemClasses.closeIcon, role: "button" })] })), status === 'done' && !disabled && (jsx(Icon, { icon: DownloadIcon, size: 16, className: uploadItemClasses.downloadIcon, onClick: onDownload })), status === 'error' && !disabled && (jsx(Icon, { icon: ResetIcon, size: 16, className: uploadItemClasses.resetIcon, onClick: onReload }))] })] }), isFinished && !disabled && (jsx("div", { className: uploadItemClasses.deleteContent, children: jsx(Icon, { icon: TrashIcon, size: 16, className: uploadItemClasses.deleteIcon, color: "neutral-solid", onClick: onDelete }) }))] }), status === 'error' && errorMessage && (jsxs("div", { className: uploadItemClasses.errorMessage, children: [jsx(Icon, { icon: errorIcon !== null && errorIcon !== void 0 ? errorIcon : DangerousFilledIcon, size: 14, color: "error", className: uploadItemClasses.errorIcon }), jsx(Typography, { color: "text-error", variant: "caption", className: uploadItemClasses.errorMessageText, children: errorMessage })] }))] }));
 });
 
 export { UploadItem as default };

package/Upload/UploadPictureCard.d.ts

@@ -91,6 +91,11 @@ export interface UploadPictureCardProps extends NativeElementPropsWithoutKeyAndR
      * Error icon to display when status is 'error'.
      */
     errorIcon?: IconDefinition;
+    /**
+     * Whether the upload picture card is readable.
+     * @default false
+     */
+    readable?: boolean;
     /**
      * When delete icon is clicked, this callback will be fired.
      */

package/Upload/UploadPictureCard.js

@@ -1,13 +1,14 @@
 'use client';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
-import { forwardRef, useMemo, useState, useEffect } from 'react';
+import { forwardRef, useCallback, useMemo, useState, useEffect } from 'react';
 import { uploadPictureCardClasses } from '@mezzanine-ui/core/upload';
-import { ImageIcon, FileIcon, SpinnerIcon, ZoomInIcon, DownloadIcon, TrashIcon, ResetIcon } from '@mezzanine-ui/icons';
+import { ImageIcon, FileIcon, ZoomInIcon, DownloadIcon, TrashIcon, ResetIcon } from '@mezzanine-ui/icons';
 import Button from '../Button/Button.js';
 import ClearActions from '../ClearActions/ClearActions.js';
 import Typography from '../Typography/Typography.js';
 import { isImageFile } from './upload-utils.js';
 import Icon from '../Icon/Icon.js';
+import Spin from '../Spin/Spin.js';
 import cx from 'clsx';
 
 /**
@@ -15,7 +16,7 @@ import cx from 'clsx';
  */
 const UploadPictureCard = forwardRef(function UploadPictureCard(props, ref) {
     var _a;
-    const { ariaLabels, className, file, url, status = 'loading', imageFit = 'cover', size = 'main', disabled = false, errorMessage, errorIcon, onDelete, onDownload, onReload, onReplace, onZoomIn, ...rest } = props;
+    const { ariaLabels, className, file, url, status = 'loading', imageFit = 'cover', size = 'main', disabled = false, errorMessage, errorIcon, readable = false, onDelete, onDownload, onReload, onReplace, onZoomIn, ...rest } = props;
     const defaultAriaLabels = {
         cancelUpload: 'Cancel upload',
         clickToReplace: 'Click to Replace',
@@ -26,6 +27,9 @@ const UploadPictureCard = forwardRef(function UploadPictureCard(props, ref) {
         zoomIn: 'Zoom in image',
     };
     const labels = { ...defaultAriaLabels, ...ariaLabels };
+    const handleDelete = useCallback((e) => { e.stopPropagation(); onDelete === null || onDelete === void 0 ? void 0 : onDelete(e); }, [onDelete]);
+    const handleDownload = useCallback((e) => { e.stopPropagation(); onDownload === null || onDownload === void 0 ? void 0 : onDownload(e); }, [onDownload]);
+    const handleZoomIn = useCallback((e) => { e.stopPropagation(); onZoomIn === null || onZoomIn === void 0 ? void 0 : onZoomIn(e); }, [onZoomIn]);
     const isImage = useMemo(() => {
         return isImageFile(file, url);
     }, [file, url]);
@@ -93,17 +97,17 @@ const UploadPictureCard = forwardRef(function UploadPictureCard(props, ref) {
         console.warn('UploadPictureCard: minor size is not supported for non-image files');
         return null;
     }
-    return (jsx("div", { "aria-disabled": disabled, className: cx(uploadPictureCardClasses.host, uploadPictureCardClasses.size(size), disabled && uploadPictureCardClasses.disabled, onReplace && status === 'done' && uploadPictureCardClasses.replaceMode, className), onClick: onReplace && status === 'done' ? onReplace : undefined, onKeyDown: onReplace && status === 'done'
+    return (jsx("div", { "aria-disabled": disabled, className: cx(uploadPictureCardClasses.host, uploadPictureCardClasses.size(size), disabled && uploadPictureCardClasses.disabled, readable && uploadPictureCardClasses.readable, !readable && onReplace && status === 'done' && uploadPictureCardClasses.replaceMode, className), onClick: !readable && onReplace && status === 'done' ? onReplace : undefined, onKeyDown: !readable && onReplace && status === 'done'
             ? (e) => {
                 if (e.key === 'Enter' || e.key === ' ') {
                     e.preventDefault();
                     e.currentTarget.click();
                 }
             }
-            : undefined, ref: ref, role: "group", tabIndex: disabled ? -1 : 0, ...rest, children: jsxs("div", { className: uploadPictureCardClasses.container, children: [isImage && imageUrl && status !== 'error' && (jsx("img", { alt: fileName, src: imageUrl, style: {
+            : undefined, ref: ref, role: "group", tabIndex: disabled || readable ? -1 : 0, ...rest, children: jsxs("div", { className: uploadPictureCardClasses.container, children: [isImage && imageUrl && status !== 'error' && (jsx("img", { alt: fileName, src: imageUrl, style: {
                         objectFit: imageFit,
                         objectPosition: 'center',
-                    } })), status === 'done' && size !== 'minor' && !isImage && (jsxs("div", { className: uploadPictureCardClasses.content, children: [jsx(Icon, { icon: FileIcon, color: "brand", size: 16 }), jsx(Typography, { className: uploadPictureCardClasses.name, ellipsis: true, children: fileName })] })), status === 'error' && size !== 'minor' && (jsxs("div", { className: uploadPictureCardClasses.errorMessage, role: "alert", "aria-live": "polite", children: [jsx(Icon, { icon: errorIconContent, color: "error", size: 16 }), jsx(Typography, { className: uploadPictureCardClasses.errorMessageText, children: errorMessageContent })] })), jsxs("div", { className: cx(uploadPictureCardClasses.actions, uploadPictureCardClasses.actionsStatus(status)), children: [status === 'loading' && size !== 'minor' && (jsxs(Fragment, { children: [jsx(ClearActions, { type: "embedded", variant: "contrast", onClick: onDelete, className: uploadPictureCardClasses.clearActionsIcon, "aria-label": labels.cancelUpload }), jsx("div", { className: uploadPictureCardClasses.loadingIcon, "aria-label": labels.uploading, children: jsx(Icon, { icon: SpinnerIcon, color: "fixed-light", spin: true, size: 32 }) })] })), status === 'done' && size !== 'minor' && (jsxs(Fragment, { children: [jsx("div", { className: uploadPictureCardClasses.tools, children: jsxs("div", { className: uploadPictureCardClasses.toolsContent, children: [onZoomIn && (jsx(Button, { variant: "base-secondary", size: "minor", icon: ZoomInIcon, iconType: "icon-only", onClick: onZoomIn, "aria-label": labels.zoomIn })), onDownload && (jsx(Button, { variant: "base-secondary", size: "minor", iconType: "icon-only", icon: DownloadIcon, onClick: onDownload, "aria-label": labels.download })), jsx(Button, { variant: "base-secondary", size: "minor", iconType: "icon-only", icon: TrashIcon, onClick: onDelete, "aria-label": labels.delete })] }) }), onReplace && (jsx("span", { className: uploadPictureCardClasses.replaceLabel, children: labels.clickToReplace }))] })), status === 'error' && size !== 'minor' && (jsx(Fragment, { children: jsx("div", { className: uploadPictureCardClasses.tools, children: jsxs("div", { className: uploadPictureCardClasses.toolsContent, children: [jsx(Button, { variant: "base-secondary", size: "minor", iconType: "icon-only", icon: ResetIcon, onClick: onReload, "aria-label": labels.reload }), jsx(Button, { variant: "base-secondary", size: "minor", iconType: "icon-only", icon: TrashIcon, onClick: onDelete, "aria-label": labels.delete })] }) }) })), size === 'minor' && (jsx(Icon, { icon: ZoomInIcon, color: "fixed-light", size: 24 }))] })] }) }));
+                    } })), status === 'done' && size !== 'minor' && !isImage && (jsxs("div", { className: uploadPictureCardClasses.content, children: [jsx(Icon, { icon: FileIcon, color: "brand", size: 16 }), jsx(Typography, { className: uploadPictureCardClasses.name, ellipsis: true, children: fileName })] })), status === 'error' && size !== 'minor' && (jsxs("div", { className: uploadPictureCardClasses.errorMessage, role: "alert", "aria-live": "polite", children: [jsx(Icon, { icon: errorIconContent, color: "error", size: 16 }), jsx(Typography, { className: uploadPictureCardClasses.errorMessageText, children: errorMessageContent })] })), jsxs("div", { className: cx(uploadPictureCardClasses.actions, uploadPictureCardClasses.actionsStatus(status)), children: [status === 'loading' && size !== 'minor' && !readable && (jsxs(Fragment, { children: [jsx(ClearActions, { type: "embedded", variant: "contrast", onClick: onDelete, className: uploadPictureCardClasses.clearActionsIcon, "aria-label": labels.cancelUpload }), jsx("div", { className: uploadPictureCardClasses.loadingIcon, "aria-label": labels.uploading, children: jsx(Spin, { loading: true, size: "sub" }) })] })), status === 'done' && size !== 'minor' && !readable && (jsxs(Fragment, { children: [jsx("div", { className: uploadPictureCardClasses.tools, children: jsxs("div", { className: uploadPictureCardClasses.toolsContent, children: [onZoomIn && (jsx(Button, { variant: "base-secondary", size: "minor", icon: ZoomInIcon, iconType: "icon-only", onClick: handleZoomIn, "aria-label": labels.zoomIn })), onDownload && (jsx(Button, { variant: "base-secondary", size: "minor", iconType: "icon-only", icon: DownloadIcon, onClick: handleDownload, "aria-label": labels.download })), jsx(Button, { variant: "base-secondary", size: "minor", iconType: "icon-only", icon: TrashIcon, onClick: handleDelete, "aria-label": labels.delete })] }) }), onReplace && (jsx("span", { className: uploadPictureCardClasses.replaceLabel, children: labels.clickToReplace }))] })), status === 'error' && size !== 'minor' && !readable && (jsx(Fragment, { children: jsx("div", { className: uploadPictureCardClasses.tools, children: jsxs("div", { className: uploadPictureCardClasses.toolsContent, children: [jsx(Button, { variant: "base-secondary", size: "minor", iconType: "icon-only", icon: ResetIcon, onClick: onReload, "aria-label": labels.reload }), jsx(Button, { variant: "base-secondary", size: "minor", iconType: "icon-only", icon: TrashIcon, onClick: onDelete, "aria-label": labels.delete })] }) }) })), size === 'minor' && !readable && (jsx(Icon, { icon: ZoomInIcon, color: "fixed-light", size: 24 }))] })] }) }));
 });
 
 export { UploadPictureCard as default };