@mezzanine-ui/react 1.0.0-beta.3 → 1.0.0-beta.5

package/FilterArea/FilterArea.d.ts

@@ -0,0 +1,58 @@
+import { ComponentPropsWithoutRef, ReactElement } from 'react';
+import { FilterAreaActionsAlign, FilterAreaSize } from '@mezzanine-ui/core/filter-area';
+import { NativeElementPropsWithoutKeyAndRef } from '../utils/jsx-types';
+import { FilterLineProps } from './FilterLine';
+export interface FilterAreaProps extends Omit<NativeElementPropsWithoutKeyAndRef<'div'>, 'children' | 'onSubmit' | 'onReset'> {
+    /**
+     * The alignment of the actions.
+     * @default 'end'
+     */
+    actionsAlign?: FilterAreaActionsAlign;
+    /**
+     * The content of the filter area, must be FilterLine component(s).
+     */
+    children: ReactElement<FilterLineProps> | ReactElement<FilterLineProps>[];
+    /**
+     * Whether the form has been modified from its initial state.
+     * When false, the reset button will be disabled.
+     * @default true
+     */
+    isDirty?: boolean;
+    /**
+     * Callback function triggered when the form is reset.
+     * Used to clear all filter conditions and restore to initial state.
+     */
+    onReset?: () => void;
+    /**
+     * Callback function triggered when the form is submitted.
+     * FilterArea itself does not manage form state; the parent component should collect
+     * filter values and handle submission logic. If using react-hook-form, values will be
+     * handled through FormProvider's handleSubmit.
+     */
+    onSubmit?: () => void;
+    /**
+     * The text of the reset button.
+     */
+    resetText?: string;
+    /**
+     * The size of the filter area.
+     * @default 'main'
+     */
+    size?: FilterAreaSize;
+    /**
+     * The text of the submit button.
+     */
+    submitText?: string;
+    /**
+     * The type of the reset button.
+     * @default 'button'
+     */
+    resetButtonType?: ComponentPropsWithoutRef<'button'>['type'];
+    /**
+     * The type of the submit button.
+     * @default 'button'
+     */
+    submitButtonType?: ComponentPropsWithoutRef<'button'>['type'];
+}
+declare const FilterArea: import("react").ForwardRefExoticComponent<FilterAreaProps & import("react").RefAttributes<HTMLDivElement>>;
+export default FilterArea;

package/FilterArea/FilterArea.js

@@ -0,0 +1,31 @@
+'use client';
+import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
+import { forwardRef, useMemo, Children, useState, useCallback } from 'react';
+import { filterAreaClasses } from '@mezzanine-ui/core/filter-area';
+import { ChevronUpIcon, ChevronDownIcon } from '@mezzanine-ui/icons';
+import Button from '../Button/Button.js';
+import cx from 'clsx';
+
+const FilterArea = forwardRef(function FilterArea(props, ref) {
+    const { actionsAlign = 'end', children, className, isDirty = true, onReset, onSubmit, resetText = 'Reset', size = 'main', submitText = 'Search', resetButtonType = 'button', submitButtonType = 'button', ...rest } = props;
+    const filterLines = useMemo(() => Children.toArray(children), [children]);
+    const hasMultipleLines = filterLines.length > 1;
+    const [expanded, setExpanded] = useState(false);
+    const handleToggleExpanded = useCallback(() => {
+        setExpanded((prev) => !prev);
+    }, []);
+    const handleSubmit = useCallback(() => {
+        if (onSubmit) {
+            onSubmit();
+        }
+    }, [onSubmit]);
+    const renderAction = () => {
+        return (jsxs("div", { className: cx(filterAreaClasses.actions, filterAreaClasses.actionsAlign(actionsAlign), { [filterAreaClasses.actionsExpanded]: expanded }), children: [jsx(Button, { onClick: handleSubmit, size: size, type: submitButtonType, children: submitText }), jsx(Button, { disabled: !isDirty, onClick: onReset, size: size, type: resetButtonType, variant: "base-secondary", children: resetText }), hasMultipleLines && (jsx(Button, { "aria-expanded": expanded, "aria-label": expanded ? 'Collapse filters' : 'Expand filters', icon: expanded ? ChevronUpIcon : ChevronDownIcon, iconType: "icon-only", onClick: handleToggleExpanded, size: size, title: expanded ? 'Collapse filters' : 'Expand filters', type: "button", variant: "base-ghost" }))] }));
+    };
+    const firstLine = filterLines[0];
+    return (jsx("div", { ...rest, ref: ref, className: cx(filterAreaClasses.host, className, {
+            [filterAreaClasses.size(size)]: size,
+        }), children: expanded ? (jsxs(Fragment, { children: [filterLines, renderAction()] })) : (jsx(Fragment, { children: firstLine && (jsxs("div", { className: filterAreaClasses.row, children: [firstLine, renderAction()] })) })) }));
+});
+
+export { FilterArea as default };

package/FilterArea/FilterLine.d.ts

@@ -0,0 +1,11 @@
+import { ReactElement } from 'react';
+import { NativeElementPropsWithoutKeyAndRef } from '../utils/jsx-types';
+import { FilterProps } from './Filter';
+export interface FilterLineProps extends Omit<NativeElementPropsWithoutKeyAndRef<'div'>, 'children'> {
+    /**
+     * The content of the filter line, must be Filter component(s).
+     */
+    children: ReactElement<FilterProps> | ReactElement<FilterProps>[];
+}
+declare const FilterLine: import("react").ForwardRefExoticComponent<FilterLineProps & import("react").RefAttributes<HTMLDivElement>>;
+export default FilterLine;

package/FilterArea/FilterLine.js

@@ -0,0 +1,13 @@
+'use client';
+import { jsx } from 'react/jsx-runtime';
+import { forwardRef, useMemo } from 'react';
+import { filterAreaClasses } from '@mezzanine-ui/core/filter-area';
+import cx from 'clsx';
+
+const FilterLine = forwardRef(function FilterLine(props, ref) {
+    const { className, children, ...rest } = props;
+    const lineClassName = useMemo(() => cx(filterAreaClasses.line, className), [className]);
+    return (jsx("div", { ...rest, ref: ref, className: lineClassName, children: children }));
+});
+
+export { FilterLine as default };

package/FilterArea/index.d.ts

@@ -0,0 +1,6 @@
+export { default as FilterArea } from './FilterArea';
+export type { FilterAreaProps } from './FilterArea';
+export { default as FilterLine } from './FilterLine';
+export type { FilterLineProps } from './FilterLine';
+export { default as Filter } from './Filter';
+export type { FilterProps } from './Filter';

package/FilterArea/index.js

@@ -0,0 +1,3 @@
+export { default as FilterArea } from './FilterArea.js';
+export { default as FilterLine } from './FilterLine.js';
+export { default as Filter } from './Filter.js';

package/Form/useSelectValueControl.d.ts

@@ -2,19 +2,18 @@ import { MouseEvent } from 'react';
 import { SelectValue } from '../Select/typings';
 export interface UseSelectBaseValueControl {
     onClear?(e: MouseEvent<Element>): void;
-    onChange?(newOptions: SelectValue[] | SelectValue): any;
     onClose?(): void;
 }
 export type UseSelectMultipleValueControl = UseSelectBaseValueControl & {
     defaultValue?: SelectValue[];
     mode: 'multiple';
-    onChange?(newOptions: SelectValue[]): any;
+    onChange?(newOptions: SelectValue[]): void;
     value?: SelectValue[];
 };
 export type UseSelectSingleValueControl = UseSelectBaseValueControl & {
     defaultValue?: SelectValue;
     mode: 'single';
-    onChange?(newOption: SelectValue): any;
+    onChange?(newOption: SelectValue | null): void;
     value?: SelectValue | null;
 };
 export type UseSelectValueControl = UseSelectMultipleValueControl | UseSelectSingleValueControl;
@@ -22,7 +21,7 @@ export interface SelectBaseValueControl {
     onClear(e: MouseEvent<Element>): void;
 }
 export type SelectMultipleValueControl = SelectBaseValueControl & {
-    onChange: (v: SelectValue | null) => SelectValue[];
+    onChange: (v: SelectValue | SelectValue[] | null) => SelectValue[];
     value: SelectValue[];
 };
 export type SelectSingleValueControl = SelectBaseValueControl & {

package/Form/useSelectValueControl.js

@@ -9,55 +9,67 @@ function useSelectBaseValueControl(props) {
         equalityFn,
         value: valueProp,
     });
-    return {
-        value,
-        onChange: (chooseOption) => {
+    if (mode === 'multiple') {
+        const onChangeMultiple = (chooseOption) => {
             var _a;
             if (!chooseOption) {
-                if (mode === 'multiple') {
-                    return [];
-                }
-                return null;
+                return [];
             }
-            let newValue = mode === 'multiple' ? [] : null;
-            switch (mode) {
-                case 'multiple': {
-                    const existedValueIdx = ((_a = value) !== null && _a !== void 0 ? _a : []).findIndex((v) => v.id === chooseOption.id);
-                    if (~existedValueIdx) {
-                        newValue = [
-                            ...value.slice(0, existedValueIdx),
-                            ...value.slice(existedValueIdx + 1),
-                        ];
-                    }
-                    else {
-                        newValue = [...value, chooseOption];
-                    }
-                    if (typeof onChange === 'function')
-                        onChange(newValue);
-                    break;
+            let newValue = [];
+            if (Array.isArray(chooseOption)) {
+                newValue = chooseOption;
+            }
+            else {
+                const existedValueIdx = ((_a = value) !== null && _a !== void 0 ? _a : []).findIndex((v) => v.id === chooseOption.id);
+                if (~existedValueIdx) {
+                    newValue = [
+                        ...value.slice(0, existedValueIdx),
+                        ...value.slice(existedValueIdx + 1),
+                    ];
                 }
-                default: {
-                    newValue = chooseOption;
-                    if (typeof onClose === 'function') {
-                        /** single selection should close modal when clicked */
-                        onClose();
-                    }
-                    if (typeof onChange === 'function')
-                        onChange(newValue);
-                    break;
+                else {
+                    newValue = [...value, chooseOption];
                 }
             }
+            if (typeof onChange === 'function')
+                onChange(newValue);
             setValue(newValue);
             return newValue;
-        },
+        };
+        return {
+            value: value,
+            onChange: onChangeMultiple,
+            onClear: (e) => {
+                e.stopPropagation();
+                setValue([]);
+                onChange === null || onChange === void 0 ? void 0 : onChange([]);
+                if (typeof onClearProp === 'function') {
+                    onClearProp(e);
+                }
+            },
+        };
+    }
+    const onChangeSingle = (chooseOption) => {
+        if (!chooseOption) {
+            return null;
+        }
+        const newValue = chooseOption;
+        if (typeof onClose === 'function') {
+            /** single selection should close modal when clicked */
+            onClose();
+        }
+        if (typeof onChange === 'function')
+            onChange(newValue);
+        setValue(newValue);
+        return newValue;
+    };
+    return {
+        value: value,
+        onChange: onChangeSingle,
         onClear: (e) => {
             e.stopPropagation();
-            if (mode === 'multiple') {
-                setValue([]);
-            }
-            else {
-                setValue(null);
-            }
+            setValue(null);
+            onChange === null || onChange === void 0 ? void 0 : onChange(null);
             if (typeof onClearProp === 'function') {
                 onClearProp(e);
             }

package/Input/Input.d.ts

@@ -17,6 +17,7 @@ export interface InputBaseProps extends Omit<TextFieldProps, 'children' | 'clear
     /**
      * Formatter function to transform the value for display.
      * Common use cases: currency formatting (1000 → "1,000"), phone numbers, etc.
+     * Default to formatting number with commas for "currency" variant.
      * @example
      * formatter={(value) => value.replace(/\B(?=(\d{3})+(?!\d))/g, ',')}
      */
@@ -49,6 +50,7 @@ export interface InputBaseProps extends Omit<TextFieldProps, 'children' | 'clear
     /**
      * Parser function to extract the raw value from formatted display value.
      * Should reverse the formatter transformation.
+     * Default to removing commas for "currency" formatting.
      * @example
      * parser={(value) => value.replace(/,/g, '')}
      */
@@ -113,10 +115,10 @@ export type NumberInputProps = InputBaseProps & NumberInput & {
     variant: 'number';
 };
 /**
- * 5. Unit Input - Input with unit text and spinner buttons
+ * 5. Currency Input - Input with unit text and spinner buttons
  */
-export type UnitInputProps = InputBaseProps & NumberInput & TextFieldAffixProps & {
-    variant: 'unit';
+export type CurrencyInputProps = InputBaseProps & NumberInput & TextFieldAffixProps & {
+    variant: 'currency';
     /**
      * Whether to show spinner buttons.
      * @default false
@@ -201,7 +203,7 @@ export type WithPasswordStrengthIndicator = {
 export type PasswordInputProps = InputBaseProps & ClearableInput & WithPasswordStrengthIndicator & {
     variant: 'password';
 };
-export type InputProps = BaseInputProps | WithAffixInputProps | SearchInputProps | NumberInputProps | UnitInputProps | ActionInputProps | SelectInputProps | PasswordInputProps;
+export type InputProps = BaseInputProps | WithAffixInputProps | SearchInputProps | NumberInputProps | CurrencyInputProps | ActionInputProps | SelectInputProps | PasswordInputProps;
 /**
  * The react component for `mezzanine` input.
  */

package/Input/Input.js

@@ -2,9 +2,11 @@
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 import { inputClasses } from '@mezzanine-ui/core/input';
 import { EyeIcon, EyeInvisibleIcon, SearchIcon } from '@mezzanine-ui/icons';
-import { forwardRef, useRef, useState, useCallback } from 'react';
+import { forwardRef, useRef, useState, useMemo, useCallback } from 'react';
 import { useInputWithClearControlValue } from '../Form/useInputWithClearControlValue.js';
 import { useComposeRefs } from '../hooks/useComposeRefs.js';
+import { formatNumberWithCommas } from '../utils/format-number-with-commas.js';
+import { parseNumberWithCommas } from '../utils/parse-number-with-commas.js';
 import Icon from '../Icon/Icon.js';
 import Dropdown from '../Dropdown/Dropdown.js';
 import SelectButton from './SelectButton/SelectButton.js';
@@ -18,7 +20,7 @@ import cx from 'clsx';
  * The react component for `mezzanine` input.
  */
 const Input = forwardRef(function Input(props, ref) {
-    const { active, className, defaultValue, disabled = false, error = false, formatter, fullWidth = true, id, inputProps, inputType, inputRef: inputRefProp, name, onChange: onChangeProp, parser, placeholder, readonly, size = 'main', typing, variant = 'base', value: valueProp, } = props;
+    const { active, className, defaultValue, disabled = false, error = false, formatter: formatterProp, fullWidth = true, id, inputProps, inputType, inputRef: inputRefProp, name, onChange: onChangeProp, parser: parserProp, placeholder, readonly, size = 'main', typing, variant = 'base', value: valueProp, } = props;
     const inputRef = useRef(null);
     const [showPassword, setShowPassword] = useState(false);
     const [value, onChange, onClearFromHook] = useInputWithClearControlValue({
@@ -28,6 +30,22 @@ const Input = forwardRef(function Input(props, ref) {
         value: valueProp,
     });
     // Handle formatter/parser logic
+    const formatter = useMemo(() => {
+        if (formatterProp)
+            return formatterProp;
+        if (variant === 'currency') {
+            return (value) => formatNumberWithCommas(value);
+        }
+        return undefined;
+    }, [formatterProp, variant]);
+    const parser = useMemo(() => {
+        if (parserProp)
+            return parserProp;
+        if (variant === 'currency') {
+            return (value) => { var _a, _b; return (_b = (_a = parseNumberWithCommas(value)) === null || _a === void 0 ? void 0 : _a.toString()) !== null && _b !== void 0 ? _b : ''; };
+        }
+        return undefined;
+    }, [parserProp, variant]);
     const handleChange = useCallback((event) => {
         let newValue = event.target.value;
         // Parse the formatted value back to raw value if parser is provided
@@ -106,20 +124,20 @@ const Input = forwardRef(function Input(props, ref) {
             };
             break;
         }
-        case 'unit': {
-            const unitProps = props;
-            const { step = 1, max, min, onSpinUp, onSpinDown } = unitProps;
+        case 'currency': {
+            const currencyProps = props;
+            const { step = 1, max, min, onSpinUp, onSpinDown } = currencyProps;
             // 預設置右對齊
             inputStyle = { textAlign: 'right' };
             // 允許填入 prefix/suffix
-            prefix = unitProps.prefix;
-            suffix = unitProps.suffix;
+            prefix = currencyProps.prefix;
+            suffix = currencyProps.suffix;
             defaultInputProps = {
                 min: min,
                 max: max,
                 step: step,
             };
-            if (unitProps.showSpinner) {
+            if (currencyProps.showSpinner) {
                 const handleSpinUp = () => {
                     const currentValue = parseFloat(value || '0');
                     const newValue = currentValue + step;
@@ -140,7 +158,7 @@ const Input = forwardRef(function Input(props, ref) {
                     }
                     onSpinDown === null || onSpinDown === void 0 ? void 0 : onSpinDown();
                 };
-                suffix = (jsxs(Fragment, { children: [unitProps.suffix, jsxs("div", { className: inputClasses.spinners, children: [jsx(SpinnerButton, { type: "up", size: size, disabled: disabled, onClick: handleSpinUp }), jsx(SpinnerButton, { type: "down", size: size, disabled: disabled, onClick: handleSpinDown })] })] }));
+                suffix = (jsxs(Fragment, { children: [currencyProps.suffix, jsxs("div", { className: inputClasses.spinners, children: [jsx(SpinnerButton, { type: "up", size: size, disabled: disabled, onClick: handleSpinUp }), jsx(SpinnerButton, { type: "down", size: size, disabled: disabled, onClick: handleSpinDown })] })] }));
             }
             break;
         }
@@ -159,7 +177,7 @@ const Input = forwardRef(function Input(props, ref) {
         }
         case 'select': {
             const selectProps = props;
-            const { selectButton, options, dropdownWidth = 120, dropdownMaxHeight = 114 } = selectProps;
+            const { selectButton, options, dropdownWidth = 120, dropdownMaxHeight = 114, } = selectProps;
             const defaultOptions = options || [];
             const selectedOptions = defaultOptions.length > 0
                 ? defaultOptions.map((option) => ({

package/Input/index.d.ts

@@ -1,3 +1,3 @@
 export type { InputSize, InputStrength } from '@mezzanine-ui/core/input';
-export type { InputBaseProps, ClearableInput, NumberInput, BaseInputProps, WithAffixInputProps, SearchInputProps, NumberInputProps, UnitInputProps, ActionInputProps, SelectInputProps, WithPasswordStrengthIndicator, PasswordInputProps, InputProps, } from './Input';
+export type { InputBaseProps, ClearableInput, NumberInput, BaseInputProps, WithAffixInputProps, SearchInputProps, NumberInputProps, CurrencyInputProps, ActionInputProps, SelectInputProps, WithPasswordStrengthIndicator, PasswordInputProps, InputProps, } from './Input';
 export { default } from './Input';

package/Modal/MediaPreviewModal.d.ts

@@ -0,0 +1,54 @@
+import { NativeElementPropsWithoutKeyAndRef } from '../utils/jsx-types';
+import { ModalContainerProps } from './useModalContainer';
+export interface MediaPreviewModalProps extends Omit<ModalContainerProps, 'children'>, NativeElementPropsWithoutKeyAndRef<'div'> {
+    /**
+     * The current index of the media being displayed (controlled mode).
+     * If provided along with onNext/onPrev, the component operates in controlled mode.
+     */
+    currentIndex?: number;
+    /**
+     * The default index when the modal opens (uncontrolled mode).
+     * @default 0
+     */
+    defaultIndex?: number;
+    /**
+     * Whether to disable the next navigation button.
+     * @default false
+     */
+    disableNext?: boolean;
+    /**
+     * Whether to disable the previous navigation button.
+     * @default false
+     */
+    disablePrev?: boolean;
+    /**
+     * Array of media items to display.
+     * Each item should be a valid image URL or React node.
+     */
+    mediaItems: (string | React.ReactNode)[];
+    /**
+     * Callback fired when the index changes (uncontrolled mode).
+     */
+    onIndexChange?: (index: number) => void;
+    /**
+     * Callback fired when the next navigation button is clicked (controlled mode).
+     * If provided, the component operates in controlled mode.
+     */
+    onNext?: () => void;
+    /**
+     * Callback fired when the previous navigation button is clicked (controlled mode).
+     * If provided, the component operates in controlled mode.
+     */
+    onPrev?: () => void;
+    /**
+     * Whether to show the pagination indicator.
+     * @default true
+     */
+    showPaginationIndicator?: boolean;
+}
+/**
+ * The react component for `mezzanine` media preview modal.
+ * Displays media items with navigation controls and a close button.
+ */
+declare const MediaPreviewModal: import("react").ForwardRefExoticComponent<MediaPreviewModalProps & import("react").RefAttributes<HTMLDivElement>>;
+export default MediaPreviewModal;

package/Modal/MediaPreviewModal.js

@@ -0,0 +1,158 @@
+'use client';
+import { jsx, jsxs } from 'react/jsx-runtime';
+import { forwardRef, useState, useEffect, useRef, useMemo } from 'react';
+import { ChevronLeftIcon, ChevronRightIcon } from '@mezzanine-ui/icons';
+import { modalClasses } from '@mezzanine-ui/core/modal';
+import { MOTION_DURATION, MOTION_EASING } from '@mezzanine-ui/system/motion';
+import useModalContainer from './useModalContainer.js';
+import ClearActions from '../ClearActions/ClearActions.js';
+import Icon from '../Icon/Icon.js';
+import Fade from '../Transition/Fade.js';
+import cx from 'clsx';
+
+/**
+ * The react component for `mezzanine` media preview modal.
+ * Displays media items with navigation controls and a close button.
+ */
+const MediaPreviewModal = forwardRef(function MediaPreviewModal(props, ref) {
+    const { className, container, currentIndex: controlledIndex, defaultIndex = 0, disableCloseOnBackdropClick = false, disableCloseOnEscapeKeyDown = false, disableNext = false, disablePortal = false, disablePrev = false, mediaItems, onBackdropClick, onClose, onIndexChange, onNext, onPrev, open, showPaginationIndicator = true, ...rest } = props;
+    const { Container: ModalContainer } = useModalContainer();
+    // Determine if component is in controlled mode
+    const isControlled = controlledIndex !== undefined;
+    // Internal state for uncontrolled mode
+    const [internalIndex, setInternalIndex] = useState(defaultIndex);
+    // Use controlled index if provided, otherwise use internal state
+    const currentIndex = isControlled ? controlledIndex : internalIndex;
+    // Reset internal index when modal opens in uncontrolled mode
+    useEffect(() => {
+        if (open && !isControlled) {
+            setInternalIndex(defaultIndex);
+        }
+    }, [open, isControlled, defaultIndex]);
+    // Built-in navigation handlers for uncontrolled mode
+    const handleNext = () => {
+        if (onNext) {
+            // Controlled mode: use provided callback
+            onNext();
+        }
+        else {
+            // Uncontrolled mode: update internal state
+            const nextIndex = Math.min(currentIndex + 1, mediaItems.length - 1);
+            setInternalIndex(nextIndex);
+            onIndexChange === null || onIndexChange === void 0 ? void 0 : onIndexChange(nextIndex);
+        }
+    };
+    const handlePrev = () => {
+        if (onPrev) {
+            // Controlled mode: use provided callback
+            onPrev();
+        }
+        else {
+            // Uncontrolled mode: update internal state
+            const prevIndex = Math.max(currentIndex - 1, 0);
+            setInternalIndex(prevIndex);
+            onIndexChange === null || onIndexChange === void 0 ? void 0 : onIndexChange(prevIndex);
+        }
+    };
+    // Auto-calculate disable states for uncontrolled mode
+    const isNextDisabled = disableNext || currentIndex >= mediaItems.length - 1;
+    const isPrevDisabled = disablePrev || currentIndex <= 0;
+    const [displayedIndices, setDisplayedIndices] = useState([
+        currentIndex,
+    ]);
+    const [activeIndex, setActiveIndex] = useState(currentIndex);
+    const preloadedUrls = useRef(new Set());
+    // Helper function to preload a single image
+    const preloadImage = (url) => {
+        if (preloadedUrls.current.has(url))
+            return;
+        const img = new Image();
+        img.src = url;
+        preloadedUrls.current.add(url);
+    };
+    // Preload images: prioritize current and adjacent, then load others
+    useEffect(() => {
+        if (!open)
+            return;
+        // Priority 1: Current and adjacent images
+        const priorityIndices = [
+            currentIndex - 1,
+            currentIndex,
+            currentIndex + 1,
+        ].filter((idx) => idx >= 0 && idx < mediaItems.length);
+        priorityIndices.forEach((idx) => {
+            const media = mediaItems[idx];
+            if (typeof media === 'string') {
+                preloadImage(media);
+            }
+        });
+        // Priority 2: All other images (load after a short delay)
+        const loadRemainingTimer = setTimeout(() => {
+            mediaItems.forEach((media, idx) => {
+                if (typeof media === 'string' && !priorityIndices.includes(idx)) {
+                    preloadImage(media);
+                }
+            });
+        }, 500);
+        return () => clearTimeout(loadRemainingTimer);
+    }, [open, currentIndex, mediaItems]);
+    useEffect(() => {
+        if (currentIndex !== activeIndex) {
+            // First, add new index to displayedIndices (will render with in=false)
+            setDisplayedIndices((prev) => prev.includes(currentIndex) ? prev : [...prev, currentIndex]);
+            // Use requestAnimationFrame to ensure DOM is updated before triggering animation
+            let rafId1 = null;
+            let rafId2 = null;
+            rafId1 = requestAnimationFrame(() => {
+                rafId2 = requestAnimationFrame(() => {
+                    setActiveIndex(currentIndex);
+                });
+            });
+            // Clean up old images after transition completes
+            const cleanupTimer = setTimeout(() => {
+                setDisplayedIndices([currentIndex]);
+            }, MOTION_DURATION.fast + 100);
+            return () => {
+                clearTimeout(cleanupTimer);
+                if (rafId1 !== null) {
+                    cancelAnimationFrame(rafId1);
+                }
+                if (rafId2 !== null) {
+                    cancelAnimationFrame(rafId2);
+                }
+            };
+        }
+        return undefined;
+    }, [currentIndex, activeIndex]);
+    // Memoize media elements to prevent unnecessary re-renders
+    const mediaElements = useMemo(() => {
+        return mediaItems.map((media, index) => {
+            if (typeof media === 'string') {
+                return {
+                    index,
+                    element: (jsx("img", { alt: `Media ${index + 1}`, className: modalClasses.mediaPreviewImage, src: media })),
+                };
+            }
+            return {
+                index,
+                element: jsx("div", { className: modalClasses.mediaPreviewImage, children: media }),
+            };
+        });
+    }, [mediaItems]);
+    const renderMedia = (index) => {
+        const mediaElement = mediaElements.find((item) => item.index === index);
+        if (!mediaElement)
+            return null;
+        const isCurrent = index === activeIndex;
+        return (jsx(Fade, { duration: {
+                enter: MOTION_DURATION.fast,
+                exit: MOTION_DURATION.fast,
+            }, easing: {
+                enter: MOTION_EASING.entrance,
+                exit: MOTION_EASING.exit,
+            }, in: isCurrent, children: mediaElement.element }, index));
+    };
+    return (jsxs(ModalContainer, { className: modalClasses.overlay, container: container, disableCloseOnBackdropClick: disableCloseOnBackdropClick, disableCloseOnEscapeKeyDown: disableCloseOnEscapeKeyDown, disablePortal: disablePortal, onBackdropClick: onBackdropClick, onClose: onClose, open: open, ref: ref, children: [jsx("div", { ...rest, className: cx(modalClasses.host, modalClasses.mediaPreview, className), role: "dialog", children: jsx("div", { className: modalClasses.mediaPreviewContent, children: jsx("div", { className: modalClasses.mediaPreviewMediaContainer, children: displayedIndices.map((index) => renderMedia(index)) }) }) }), jsx(ClearActions, { className: modalClasses.mediaPreviewCloseButton, onClick: onClose, type: "embedded", variant: "contrast" }), mediaItems.length > 1 && (jsx("button", { "aria-disabled": isPrevDisabled, "aria-label": "Previous media", className: cx(modalClasses.mediaPreviewNavButton, modalClasses.mediaPreviewNavButtonPrev), disabled: isPrevDisabled, onClick: handlePrev, title: "Previous", type: "button", children: jsx(Icon, { icon: ChevronLeftIcon, size: 16, color: "fixed-light" }) })), mediaItems.length > 1 && (jsx("button", { "aria-disabled": isNextDisabled, "aria-label": "Next media", className: cx(modalClasses.mediaPreviewNavButton, modalClasses.mediaPreviewNavButtonNext), disabled: isNextDisabled, onClick: handleNext, title: "Next", type: "button", children: jsx(Icon, { icon: ChevronRightIcon, size: 16, color: "fixed-light" }) })), showPaginationIndicator && mediaItems.length > 1 && (jsxs("div", { "aria-label": `Page ${currentIndex + 1} of ${mediaItems.length}`, className: modalClasses.mediaPreviewPaginationIndicator, children: [currentIndex + 1, "/", mediaItems.length] }))] }));
+});
+
+export { MediaPreviewModal as default };

package/Modal/Modal.js

@@ -25,7 +25,7 @@ const Modal = forwardRef(function Modal(props, ref) {
                 }, className), role: "dialog", children: [showModalHeader && (jsx(ModalHeader, { showStatusTypeIcon: showStatusTypeIcon, statusTypeIconLayout: statusTypeIconLayout, supportingText: supportingText, supportingTextAlign: supportingTextAlign, title: title, titleAlign: titleAlign })), modalType === 'extendedSplit' && (jsxs("div", { className: modalClasses.modalBodyContainerExtendedSplit, children: [jsx("div", { className: modalClasses.modalBodyContainerExtendedSplitRight, children: extendedSplitRightSideContent }), jsxs("div", { className: modalClasses.modalBodyContainerExtendedSplitLeft, children: [jsx("div", { className: modalClasses.modalBodyContainerExtendedSplitLeftSideContent, children: extendedSplitLeftSideContent }), showModalFooter && renderModalFooter()] })] })), (modalType === 'standard' ||
                         modalType === 'verification' ||
                         modalType === 'extended' ||
-                        modalType === 'mediaPreview') && (jsxs(Fragment, { children: [jsx("div", { className: modalClasses.modalBodyContainer, children: children }), showModalFooter && renderModalFooter()] })), showDismissButton && (jsx(ClearActions, { onClick: onClose, className: modalClasses.closeIcon, variant: "base" }))] }) }) }));
+                        modalType === 'mediaPreview') && (jsxs(Fragment, { children: [children && (jsx("div", { className: modalClasses.modalBodyContainer, children: children })), showModalFooter && renderModalFooter()] })), showDismissButton && (jsx(ClearActions, { onClick: onClose, className: modalClasses.closeIcon, variant: "base" }))] }) }) }));
 });
 
 export { Modal as default };

package/Modal/index.d.ts

@@ -5,6 +5,8 @@ export type { ModalFooterProps } from './ModalFooter';
 export { default as ModalFooter } from './ModalFooter';
 export type { ModalHeaderProps } from './ModalHeader';
 export { default as ModalHeader } from './ModalHeader';
+export type { MediaPreviewModalProps } from './MediaPreviewModal';
+export { default as MediaPreviewModal } from './MediaPreviewModal';
 export { default as useModalContainer } from './useModalContainer';
 export type { ModalContainerProps } from './useModalContainer';
 export type { ModalProps } from './Modal';

package/Modal/index.js

@@ -1,5 +1,6 @@
 export { default as ModalBodyForVerification } from './ModalBodyForVerification.js';
 export { default as ModalFooter } from './ModalFooter.js';
 export { default as ModalHeader } from './ModalHeader.js';
+export { default as MediaPreviewModal } from './MediaPreviewModal.js';
 export { default as useModalContainer } from './useModalContainer.js';
 export { default } from './Modal.js';