@mezzanine-ui/react 1.0.0-beta.2 → 1.0.0-beta.4

package/FilterArea/Filter.d.ts

@@ -0,0 +1,32 @@
+import { ReactElement } from 'react';
+import { FilterAlign, FilterSpan } from '@mezzanine-ui/core/filter-area';
+import { NativeElementPropsWithoutKeyAndRef } from '../utils/jsx-types';
+import { FormFieldProps } from '../Form';
+export interface FilterProps extends Omit<NativeElementPropsWithoutKeyAndRef<'div'>, 'children'> {
+    /**
+     * Layout control - Vertical alignment of the field.
+     * @default 'stretch'
+     */
+    align?: FilterAlign;
+    /**
+     * The content of the filter field.
+     */
+    children: ReactElement<FormFieldProps> | ReactElement<FormFieldProps>[];
+    /**
+     * Layout control - Whether the field should automatically expand to fill the entire row (equivalent to span={12}).
+     * @default false
+     */
+    grow?: boolean;
+    /**
+     * Layout control - Minimum width of the field.
+     */
+    minWidth?: string | number;
+    /**
+     * Layout control - Number of columns the field occupies in the Grid (1-12, Grid has 12 columns total).
+     * This property is ignored when grow is true.
+     * @default 2
+     */
+    span?: FilterSpan;
+}
+declare const Filter: import("react").ForwardRefExoticComponent<FilterProps & import("react").RefAttributes<HTMLDivElement>>;
+export default Filter;

package/FilterArea/Filter.js

@@ -0,0 +1,23 @@
+'use client';
+import { jsx } from 'react/jsx-runtime';
+import { forwardRef, useMemo } from 'react';
+import { filterAreaClasses, filterAreaPrefix } from '@mezzanine-ui/core/filter-area';
+import cx from 'clsx';
+
+const Filter = forwardRef(function Filter(props, ref) {
+    const { align = 'stretch', children, className, grow = false, minWidth, span = 2, ...rest } = props;
+    const filterClassName = useMemo(() => cx(filterAreaClasses.filter, {
+        [filterAreaClasses.filterGrow]: grow,
+        [filterAreaClasses.filterAlign(align)]: align,
+    }, className), [align, className, grow]);
+    const style = useMemo(() => ({
+        ...(minWidth && { minWidth: typeof minWidth === 'number' ? `${minWidth}px` : minWidth }),
+        ...(!grow && {
+            [`--${filterAreaPrefix}-filter-span`]: span,
+        }),
+        ...rest.style,
+    }), [grow, minWidth, rest.style, span]);
+    return (jsx("div", { ...rest, ref: ref, className: filterClassName, style: style, children: children }));
+});
+
+export { Filter as default };

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/FormField.js

@@ -20,7 +20,9 @@ const FormField = forwardRef(function FormField(props, ref) {
     return (jsx("div", { ...rest, ref: ref, className: cx(formFieldClasses.host, formFieldClasses.size(size), {
             [formFieldClasses.disabled]: disabled,
             [formFieldClasses.fullWidth]: fullWidth,
-        }, className), children: jsxs(FormControlContext.Provider, { value: formControl, children: [jsx(FormLabel, { className: formFieldClasses.labelArea, htmlFor: name, informationIcon: labelInformationIcon, informationText: labelInformationText, labelText: label, optionalMarker: labelOptionalMarker }), jsxs("div", { className: cx(formFieldClasses.dataEntry), children: [children, jsxs("div", { className: cx(formFieldClasses.hintTextAndCounterArea), children: [(hintText || hintTextIcon) && (jsx(FormHintText, { hintText: hintText, hintTextIcon: hintTextIcon, severity: severity })), counter && (jsx("span", { className: cx(formFieldClasses.counter, formFieldClasses.counterColor(counterColor || FormFieldCounterColor.INFO)), children: counter }))] })] })] }) }));
+        }, className), children: jsxs(FormControlContext.Provider, { value: formControl, children: [jsx(FormLabel, { className: formFieldClasses.labelArea, htmlFor: name, informationIcon: labelInformationIcon, informationText: labelInformationText, labelText: label, optionalMarker: labelOptionalMarker }), jsxs("div", { className: cx(formFieldClasses.dataEntry), children: [children, hintText || hintTextIcon || counter ? (jsxs("div", { className: cx(formFieldClasses.hintTextAndCounterArea, {
+                                [formFieldClasses.hintTextAndCounterArea + '--align-right']: !(hintText || hintTextIcon) && counter,
+                            }), children: [(hintText || hintTextIcon) && (jsx(FormHintText, { hintText: hintText, hintTextIcon: hintTextIcon, severity: severity })), counter && (jsx("span", { className: cx(formFieldClasses.counter, formFieldClasses.counterColor(counterColor || FormFieldCounterColor.INFO)), children: counter }))] })) : null] })] }) }));
 });
 
 export { FormField as default };

package/Input/Input.d.ts

@@ -1,9 +1,11 @@
-import { Ref, ChangeEventHandler } from 'react';
-import { NativeElementPropsWithoutKeyAndRef } from '../utils/jsx-types';
+import { DropdownOption } from '@mezzanine-ui/core/dropdown';
+import { ChangeEventHandler, Ref } from 'react';
+import { PopperPlacement } from '../Popper';
 import { TextFieldAffixProps, TextFieldProps } from '../TextField';
+import { NativeElementPropsWithoutKeyAndRef } from '../utils/jsx-types';
 import { ActionButtonProps } from './ActionButton';
-import { SelectButtonProps } from './SelectButton';
 import { PasswordStrengthIndicatorProps } from './PasswordStrengthIndicator';
+import { SelectButtonProps } from './SelectButton';
 /**
  * Base props shared by all Input variants
  */
@@ -15,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, ',')}
      */
@@ -47,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, '')}
      */
@@ -111,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
@@ -152,6 +156,30 @@ export type SelectInputProps = InputBaseProps & {
     selectButton: SelectButtonProps & {
         position: 'prefix' | 'suffix' | 'both';
     };
+    /**
+     * The options of the dropdown.
+     */
+    options?: DropdownOption[];
+    /**
+     * The selected value of the dropdown.
+     */
+    selectedValue?: string;
+    /**
+     * The onChange event handler of the dropdown.
+     */
+    onSelect?: (value: string) => void;
+    /**
+     * The width of the dropdown.
+     */
+    dropdownWidth?: number | string;
+    /**
+     * The max height of the dropdown.
+     */
+    dropdownMaxHeight?: number | string;
+    /**
+     * The placement of the dropdown.
+     */
+    dropdownPlacement?: PopperPlacement;
 };
 /**
  * 8. Password Input - Password input with visibility toggle
@@ -175,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

@@ -1,11 +1,14 @@
 'use client';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
-import { forwardRef, useRef, useState, useCallback } from 'react';
 import { inputClasses } from '@mezzanine-ui/core/input';
-import { useComposeRefs } from '../hooks/useComposeRefs.js';
-import { useInputWithClearControlValue } from '../Form/useInputWithClearControlValue.js';
 import { EyeIcon, EyeInvisibleIcon, SearchIcon } from '@mezzanine-ui/icons';
+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';
 import ActionButton from './ActionButton/ActionButton.js';
 import SpinnerButton from './SpinnerButton/SpinnerButton.js';
@@ -17,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({
@@ -27,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
@@ -105,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;
@@ -139,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;
         }
@@ -158,16 +177,31 @@ const Input = forwardRef(function Input(props, ref) {
         }
         case 'select': {
             const selectProps = props;
-            const { selectButton } = selectProps;
+            const { selectButton, options, dropdownWidth = 120, dropdownMaxHeight = 114, } = selectProps;
+            const defaultOptions = options || [];
+            const selectedOptions = defaultOptions.length > 0
+                ? defaultOptions.map((option) => ({
+                    ...option,
+                    ...(option.id === selectProps.selectedValue
+                        ? { checkSite: 'suffix' }
+                        : {}),
+                }))
+                : [];
             if (selectButton.position === 'both' ||
                 selectButton.position === 'prefix') {
                 const { ...restSelectButtonProps } = selectButton;
-                prefixExternalButton = (jsx(SelectButton, { ...restSelectButtonProps, disabled: restSelectButtonProps.disabled || disabled, size: size }));
+                prefixExternalButton = (jsx(Dropdown, { options: selectedOptions, value: selectProps.selectedValue, customWidth: dropdownWidth, maxHeight: dropdownMaxHeight, placement: "bottom-start", onSelect: (option) => {
+                        var _a;
+                        (_a = selectProps.onSelect) === null || _a === void 0 ? void 0 : _a.call(selectProps, option.id);
+                    }, children: jsx(SelectButton, { ...restSelectButtonProps, disabled: restSelectButtonProps.disabled || disabled, size: size }) }));
             }
             if (selectButton.position === 'both' ||
                 selectButton.position === 'suffix') {
                 const { ...restSelectButtonProps } = selectButton;
-                suffixExternalButton = (jsx(SelectButton, { ...restSelectButtonProps, disabled: restSelectButtonProps.disabled || disabled, size: size }));
+                suffixExternalButton = (jsx(Dropdown, { options: selectedOptions, value: selectProps.selectedValue, customWidth: dropdownWidth, maxHeight: dropdownMaxHeight, placement: "bottom-start", onSelect: (option) => {
+                        var _a;
+                        (_a = selectProps.onSelect) === null || _a === void 0 ? void 0 : _a.call(selectProps, option.id);
+                    }, children: jsx(SelectButton, { ...restSelectButtonProps, disabled: restSelectButtonProps.disabled || disabled, size: size }) }));
             }
             break;
         }

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 };