@mezzanine-ui/react 1.0.0-beta.6 → 1.0.0-beta.7

package/AutoComplete/AutoComplete.js

@@ -15,6 +15,7 @@ import Dropdown from '../Dropdown/Dropdown.js';
 import cx from 'clsx';
 
 const MENU_ID_PREFIX = 'mzn-select-autocomplete-menu-id';
+const BLUR_RESET_OPTIONS_DELAY = 120;
 /**
  * Type guard to check if value is array (multiple mode)
  */
@@ -46,7 +47,8 @@ function isOptionSelected(option, value, isMultiple) {
  */
 const AutoComplete = forwardRef(function AutoComplete(props, ref) {
     const { disabled: disabledFromFormControl, fullWidth: fullWidthFromFormControl, required: requiredFromFormControl, severity, } = useContext(FormControlContext) || {};
-    const { addable = false, asyncData = false, className, createSeparators = [',', '+', '\n'], defaultValue, disabled = disabledFromFormControl || false, disabledOptionsFilter = false, emptyText, error = severity === 'error' || false, fullWidth = fullWidthFromFormControl || false, id, keepSearchTextOnBlur = false, inputPosition = 'outside', inputProps, inputRef, loading = false, loadingText, menuMaxHeight, mode = 'single', name, onClear: onClearProp, onChange: onChangeProp, onInsert, onSearch, onSearchTextChange, onVisibilityChange, open: openProp, options: optionsProp, placeholder = '', prefix, required = requiredFromFormControl || false, searchDebounceTime = 300, searchTextControlRef, size, trimOnCreate = true, value: valueProp, createActionText, createActionTextTemplate = '建立 "{text}"', dropdownZIndex, globalPortal = true, onReachBottom, onLeaveBottom, } = props;
+    const { addable = false, asyncData = false, className, clearSearchText = true, createSeparators = [',', '+', '\n'], defaultValue, disabled = disabledFromFormControl || false, disabledOptionsFilter = false, emptyText, error = severity === 'error' || false, fullWidth = fullWidthFromFormControl || false, id, inputPosition = 'outside', inputProps, inputRef, loading = false, loadingText, loadingPosition = 'bottom', menuMaxHeight, mode = 'single', name, onClear: onClearProp, onChange: onChangeProp, onInsert, onSearch, onSearchTextChange, onVisibilityChange, open: openProp, options: optionsProp, overflowStrategy, placeholder = '', prefix, required = requiredFromFormControl || false, searchDebounceTime = 300, searchTextControlRef, size, trimOnCreate = true, value: valueProp, createActionText, createActionTextTemplate = '建立 "{text}"', dropdownZIndex, globalPortal = true, onReachBottom, onLeaveBottom, } = props;
+    const shouldClearSearchTextOnBlur = clearSearchText;
     const [uncontrolledOpen, setUncontrolledOpen] = useState(false);
     const isMultiple = mode === 'multiple';
     const isSingle = !isMultiple;
@@ -142,20 +144,51 @@ const AutoComplete = forwardRef(function AutoComplete(props, ref) {
         return result;
     }, [clearNewlyCreated, isMultiple, isSingle, markUnselected, onChange, value]);
     const nodeRef = useRef(null);
+    const inputElementRef = useRef(null);
     const controlRef = useRef(null);
+    const resetOptionsTimeoutRef = useRef(null);
+    const skipNextMultipleCloseResetRef = useRef(false);
     const composedRef = useComposeRefs([ref, controlRef]);
+    const composedInputRef = useComposeRefs([inputRef, inputElementRef]);
+    const clearPendingOptionsReset = useCallback(() => {
+        if (resetOptionsTimeoutRef.current !== null) {
+            window.clearTimeout(resetOptionsTimeoutRef.current);
+            resetOptionsTimeoutRef.current = null;
+        }
+    }, []);
+    const clearSearchInputDisplay = useCallback(() => {
+        if (inputElementRef.current) {
+            inputElementRef.current.value = '';
+        }
+    }, []);
+    const resetSearchInputs = useCallback(() => {
+        resetCreationInputs();
+        clearSearchInputDisplay();
+    }, [clearSearchInputDisplay, resetCreationInputs]);
+    const resetSearchInputsAndOptions = useCallback(() => {
+        resetSearchInputs();
+        clearPendingOptionsReset();
+        cancelSearch();
+        resetOptionsTimeoutRef.current = window.setTimeout(() => {
+            runSearch('', { immediate: true });
+            resetOptionsTimeoutRef.current = null;
+        }, BLUR_RESET_OPTIONS_DELAY);
+    }, [cancelSearch, clearPendingOptionsReset, resetSearchInputs, runSearch]);
+    useEffect(() => () => {
+        clearPendingOptionsReset();
+    }, [clearPendingOptionsReset]);
     // In single mode, show searchText when focused, otherwise show selected value
     // In multiple mode, always return empty string to avoid displaying "0"
     const renderValue = useMemo(() => {
         if (isSingle
-            && (focused || (keepSearchTextOnBlur && !value && searchText))) {
+            && (focused || (!shouldClearSearchTextOnBlur && !value && searchText))) {
             return () => searchText;
         }
         if (isMultiple) {
             return () => '';
         }
         return undefined;
-    }, [focused, isMultiple, isSingle, keepSearchTextOnBlur, searchText, value]);
+    }, [focused, isMultiple, isSingle, searchText, shouldClearSearchTextOnBlur, value]);
     function getPlaceholder() {
         if (isSingle && focused && isSingleValue(value)) {
             return value.name;
@@ -164,6 +197,7 @@ const AutoComplete = forwardRef(function AutoComplete(props, ref) {
     }
     /** Trigger input props */
     const onSearchInputChange = (e) => {
+        clearPendingOptionsReset();
         const nextSearch = e.target.value;
         /** should sync both search input and value */
         setSearchText(nextSearch);
@@ -180,6 +214,8 @@ const AutoComplete = forwardRef(function AutoComplete(props, ref) {
     };
     const onSearchInputFocus = (e) => {
         var _a;
+        skipNextMultipleCloseResetRef.current = false;
+        clearPendingOptionsReset();
         // When inputPosition is inside, let Dropdown handle the focus event
         // Otherwise, stop propagation to prevent conflicts
         if (inputPosition !== 'inside') {
@@ -195,6 +231,9 @@ const AutoComplete = forwardRef(function AutoComplete(props, ref) {
     };
     const onSearchInputBlur = (e) => {
         var _a, _b, _c;
+        // In multiple mode while dropdown is open, defer clearing to visibility change.
+        // This prevents clearing on intermediate blur triggered by dropdown interactions.
+        const shouldDeferMultipleBlurReset = isMultiple && open;
         // When inputPosition is inside, we need special handling
         if (inputPosition === 'inside') {
             // When open is controlled, prevent default blur behavior to avoid conflicts
@@ -203,33 +242,33 @@ const AutoComplete = forwardRef(function AutoComplete(props, ref) {
                 // Don't let Dropdown's onBlur close the dropdown when controlled
                 // Only call onFocus(false) to update internal state
                 onFocus(false);
-                // Clear search text and insert text when blur if keepSearchTextOnBlur is false
-                if (!keepSearchTextOnBlur) {
-                    resetCreationInputs();
+                // Clear search text and insert text when blur clear behavior is enabled
+                if (shouldClearSearchTextOnBlur && !shouldDeferMultipleBlurReset) {
+                    resetSearchInputsAndOptions();
                 }
                 (_a = inputProps === null || inputProps === void 0 ? void 0 : inputProps.onBlur) === null || _a === void 0 ? void 0 : _a.call(inputProps, e);
                 return;
             }
             // For uncontrolled mode, let Dropdown handle it normally
             // Dropdown's inlineTriggerElement will handle the blur and close logic
-            // Clear search text and insert text when blur if keepSearchTextOnBlur is false
-            if (!keepSearchTextOnBlur) {
-                resetCreationInputs();
+            // Clear search text and insert text when blur clear behavior is enabled
+            if (shouldClearSearchTextOnBlur && !shouldDeferMultipleBlurReset) {
+                resetSearchInputsAndOptions();
             }
             (_b = inputProps === null || inputProps === void 0 ? void 0 : inputProps.onBlur) === null || _b === void 0 ? void 0 : _b.call(inputProps, e);
             return;
         }
         onFocus(false);
-        // Clear search text and insert text when blur if keepSearchTextOnBlur is false
-        if (!keepSearchTextOnBlur) {
-            resetCreationInputs();
+        // Clear search text and insert text when blur clear behavior is enabled
+        if (shouldClearSearchTextOnBlur && !shouldDeferMultipleBlurReset) {
+            resetSearchInputsAndOptions();
         }
         (_c = inputProps === null || inputProps === void 0 ? void 0 : inputProps.onBlur) === null || _c === void 0 ? void 0 : _c.call(inputProps, e);
     };
     const handleClear = useCallback((e) => {
         onClear(e);
-        resetCreationInputs();
-    }, [onClear, resetCreationInputs]);
+        resetSearchInputs();
+    }, [onClear, resetSearchInputs]);
     const onClickSuffixActionIcon = () => {
         toggleOpen((prev) => !prev);
     };
@@ -270,15 +309,9 @@ const AutoComplete = forwardRef(function AutoComplete(props, ref) {
     }, [mode, value]);
     // Disable input when loading
     const isInputDisabled = disabled || isLoading;
-    // For rendering: when loading, force options to empty to show loading status in Dropdown
-    const dropdownOptionsForRender = useMemo(() => {
-        if (isLoading)
-            return [];
-        return dropdownOptions;
-    }, [isLoading, dropdownOptions]);
     const dropdownStatus = isLoading
         ? 'loading'
-        : dropdownOptionsForRender.length === 0
+        : dropdownOptions.length === 0
             ? 'empty'
             : undefined;
     // Handle dropdown option selection
@@ -296,13 +329,24 @@ const AutoComplete = forwardRef(function AutoComplete(props, ref) {
                 onFocus(false);
             }
             else {
+                skipNextMultipleCloseResetRef.current = true;
                 wrappedOnChange(selectedValue);
+                // In multiple mode, keep current filter text after selecting an item.
+                // Search text is cleared only when blur/close actually leaves the scope.
             }
         }
-    }, [mode, onFocus, options, setSearchText, setInsertText, toggleOpen, wrappedOnChange]);
+    }, [
+        mode,
+        onFocus,
+        options,
+        setSearchText,
+        setInsertText,
+        toggleOpen,
+        wrappedOnChange,
+    ]);
     // Active index for dropdown keyboard navigation
     const [activeIndex, setActiveIndex] = useState(null);
-    const setListboxHasVisualFocus = useCallback(() => { }, []);
+    const setListboxHasVisualFocus = useCallback((_focus) => { }, []);
     // Reset activeIndex when options change
     useEffect(() => {
         if (!dropdownOptions.length) {
@@ -339,7 +383,7 @@ const AutoComplete = forwardRef(function AutoComplete(props, ref) {
         handleBulkCreate,
         handleDropdownSelect,
         inputPropsOnKeyDown: inputProps === null || inputProps === void 0 ? void 0 : inputProps.onKeyDown,
-        inputRef,
+        inputRef: inputElementRef,
         mode,
         onFocus,
         open,
@@ -354,13 +398,59 @@ const AutoComplete = forwardRef(function AutoComplete(props, ref) {
         value,
         wrappedOnChange,
     });
+    const onSearchInputKeyDown = useCallback((e) => {
+        var _a, _b;
+        if (e.key === 'Escape') {
+            e.preventDefault();
+            e.stopPropagation();
+            toggleOpen(false);
+            setActiveIndex(null);
+            setListboxHasVisualFocus(false);
+            onFocus(false);
+            (_a = inputElementRef.current) === null || _a === void 0 ? void 0 : _a.blur();
+            (_b = inputProps === null || inputProps === void 0 ? void 0 : inputProps.onKeyDown) === null || _b === void 0 ? void 0 : _b.call(inputProps, e);
+            return;
+        }
+        handleInputKeyDown(e);
+    }, [
+        handleInputKeyDown,
+        inputProps,
+        onFocus,
+        setActiveIndex,
+        setListboxHasVisualFocus,
+        toggleOpen,
+    ]);
     // Handle visibility change from Dropdown to prevent flickering
     const handleVisibilityChange = useCallback((newOpen) => {
+        var _a;
         // Only update if state actually changed to prevent flickering
         if (newOpen !== open) {
             toggleOpen(newOpen);
         }
-    }, [open, toggleOpen]);
+        // In multiple mode, blur/close can be driven by Dropdown visibility updates.
+        // Keep input text cleanup consistent even when native input blur is not triggered.
+        if (!newOpen && isMultiple && shouldClearSearchTextOnBlur) {
+            if (skipNextMultipleCloseResetRef.current) {
+                const menuElement = document.getElementById(menuId);
+                const activeElement = document.activeElement;
+                const activeWithinHost = !!(activeElement
+                    && (((_a = nodeRef.current) === null || _a === void 0 ? void 0 : _a.contains(activeElement))
+                        || (menuElement && menuElement.contains(activeElement))));
+                skipNextMultipleCloseResetRef.current = false;
+                if (activeWithinHost) {
+                    return;
+                }
+            }
+            resetSearchInputsAndOptions();
+        }
+    }, [
+        isMultiple,
+        menuId,
+        open,
+        resetSearchInputsAndOptions,
+        shouldClearSearchTextOnBlur,
+        toggleOpen,
+    ]);
     const handlePasteWithFallback = useCallback((e) => {
         var _a;
         handlePaste(e);
@@ -388,7 +478,6 @@ const AutoComplete = forwardRef(function AutoComplete(props, ref) {
         const alreadySelected = isOptionSelected(matchingOption, value, isMultiple);
         if (!alreadySelected) {
             wrappedOnChange(matchingOption);
-            resetCreationInputs();
             return true;
         }
         return false;
@@ -398,7 +487,6 @@ const AutoComplete = forwardRef(function AutoComplete(props, ref) {
         isSingle,
         onFocus,
         options,
-        resetCreationInputs,
         setSearchText,
         setInsertText,
         toggleOpen,
@@ -416,7 +504,7 @@ const AutoComplete = forwardRef(function AutoComplete(props, ref) {
         onBlur: onSearchInputBlur,
         onChange: onSearchInputChange,
         onFocus: onSearchInputFocus,
-        onKeyDown: handleInputKeyDown,
+        onKeyDown: onSearchInputKeyDown,
         onPaste: handlePasteWithFallback,
         readOnly: false,
         role: 'combobox',
@@ -429,9 +517,9 @@ const AutoComplete = forwardRef(function AutoComplete(props, ref) {
                     ? (createActionText
                         ? createActionText(insertText)
                         : createActionTextTemplate.replace('{text}', insertText))
-                    : undefined, activeIndex: activeIndex, disabled: isInputDisabled, emptyText: emptyText, followText: searchText, inputPosition: inputPosition, isMatchInputValue: true, listboxId: menuId, loadingText: loadingText, maxHeight: menuMaxHeight, mode: mode, onActionCustom: shouldShowCreateAction
+                    : undefined, activeIndex: activeIndex, disabled: isInputDisabled, emptyText: emptyText, followText: searchText, inputPosition: inputPosition, isMatchInputValue: true, listboxId: menuId, loadingText: loadingText, loadingPosition: loadingPosition, maxHeight: menuMaxHeight, mode: mode, onActionCustom: shouldShowCreateAction
                     ? handleActionCustom
-                    : undefined, onItemHover: setActiveIndex, onSelect: handleDropdownSelect, onVisibilityChange: handleVisibilityChange, open: open, options: dropdownOptionsForRender, placement: "bottom", sameWidth: true, showDropdownActions: shouldShowCreateAction, showActionShowTopBar: shouldShowCreateAction, status: dropdownStatus, type: "default", value: dropdownValue, zIndex: dropdownZIndex, globalPortal: globalPortal, onReachBottom: onReachBottom, onLeaveBottom: onLeaveBottom, children: jsx(SelectTrigger, { ref: composedRef, active: open, className: className, clearable: true, isForceClearable: true, disabled: isInputDisabled, fullWidth: fullWidth, inputRef: inputRef, mode: mode, onTagClose: wrappedOnChange, onClear: handleClear, placeholder: getPlaceholder(), prefix: prefix, readOnly: false, required: required, type: error ? 'error' : 'default', inputProps: {
+                    : undefined, onItemHover: setActiveIndex, onSelect: handleDropdownSelect, onVisibilityChange: handleVisibilityChange, open: open, options: dropdownOptions, placement: "bottom", sameWidth: true, showDropdownActions: shouldShowCreateAction, showActionShowTopBar: shouldShowCreateAction, status: dropdownStatus, type: "default", value: dropdownValue, zIndex: dropdownZIndex, globalPortal: globalPortal, onReachBottom: onReachBottom, onLeaveBottom: onLeaveBottom, children: jsx(SelectTrigger, { ref: composedRef, active: open, className: className, clearable: true, disabled: isInputDisabled, fullWidth: fullWidth, inputRef: composedInputRef, mode: mode, onTagClose: wrappedOnChange, onClear: handleClear, overflowStrategy: overflowStrategy, placeholder: getPlaceholder(), prefix: prefix, readOnly: false, required: required, type: error ? 'error' : 'default', inputProps: {
                         ...resolvedInputProps,
                         onClick: (e) => {
                             var _a;

package/Backdrop/Backdrop.js

@@ -15,26 +15,22 @@ const Backdrop = forwardRef(function Backdrop(props, ref) {
     const { children, className, container, disableCloseOnBackdropClick = false, disablePortal, disableScrollLock = false, onBackdropClick, onClose, open = false, variant = 'dark', ...rest } = props;
     // Lock body scroll when backdrop is open
     useScrollLock({ enabled: open && !disableScrollLock });
-    // When using custom container or disablePortal, overlay should be absolutely positioned
-    // When using default Portal (to #mzn-portal-container), overlay uses relative positioning
-    const applyAbsolutePosition = Boolean(disablePortal || container);
-    return (jsx(Portal, { container: container, disablePortal: disablePortal, layer: "default", children: jsxs("div", { ...rest, ref: ref, "aria-hidden": !open, className: cx(backdropClasses.host, {
-                [backdropClasses.hostAbsolute]: applyAbsolutePosition,
+    return (jsx(Portal, { container: container, disablePortal: disablePortal, layer: "default", children: jsx("div", { ...rest, ref: ref, "aria-hidden": !open, className: cx(backdropClasses.host, backdropClasses.hostAbsolute, {
                 [backdropClasses.hostOpen]: open,
-            }, className), role: "presentation", children: [jsx(Fade, { in: open, duration: {
-                        enter: MOTION_DURATION.fast,
-                        exit: MOTION_DURATION.fast,
-                    }, easing: {
-                        enter: MOTION_EASING.standard,
-                        exit: MOTION_EASING.standard,
-                    }, children: jsx("div", { "aria-hidden": "true", className: cx(backdropClasses.backdrop, backdropClasses.backdropVariant(variant)), onClick: (event) => {
-                            if (!disableCloseOnBackdropClick && onClose) {
-                                onClose();
-                            }
-                            if (onBackdropClick) {
-                                onBackdropClick(event);
-                            }
-                        } }) }), jsx("div", { className: backdropClasses.content, children: children })] }) }));
+            }, className), role: "presentation", children: jsxs("div", { className: backdropClasses.main, children: [jsx(Fade, { in: open, duration: {
+                            enter: MOTION_DURATION.fast,
+                            exit: MOTION_DURATION.fast,
+                        }, easing: {
+                            enter: MOTION_EASING.standard,
+                            exit: MOTION_EASING.standard,
+                        }, children: jsx("div", { "aria-hidden": "true", className: cx(backdropClasses.backdrop, backdropClasses.backdropVariant(variant)), onClick: (event) => {
+                                if (!disableCloseOnBackdropClick && onClose) {
+                                    onClose();
+                                }
+                                if (onBackdropClick) {
+                                    onBackdropClick(event);
+                                }
+                            } }) }), jsx("div", { className: backdropClasses.content, children: children })] }) }) }));
 });
 
 export { Backdrop as default };

package/Calendar/CalendarDays.js

@@ -74,7 +74,7 @@ function CalendarDays(props) {
                                         ? (() => {
                                             var _a, _b;
                                             const annotation = renderAnnotations(date);
-                                            return (jsx(Typography, { variant: "annotation", color: (_a = annotation === null || annotation === void 0 ? void 0 : annotation.color) !== null && _a !== void 0 ? _a : 'text-neutral', children: (_b = annotation === null || annotation === void 0 ? void 0 : annotation.value) !== null && _b !== void 0 ? _b : '' }));
+                                            return (jsx(Typography, { variant: "annotation", color: (_a = annotation === null || annotation === void 0 ? void 0 : annotation.color) !== null && _a !== void 0 ? _a : 'text-neutral', children: (_b = annotation === null || annotation === void 0 ? void 0 : annotation.value) !== null && _b !== void 0 ? _b : '--' }));
                                         })()
                                         : null] }) }, `${getMonth(date)}/${getDate(date)}`));
                     }) }, `CALENDAR_DAYS/WEEK_OF/${index}`)))] }) }));

package/Card/BaseCard.d.ts

@@ -0,0 +1,11 @@
+import { ComponentOverridableForwardRefComponentPropsFactory } from '../utils/jsx-types';
+import { BaseCardComponent, BaseCardProps } from './typings';
+export type BaseCardComponentProps<C extends BaseCardComponent = 'div'> = ComponentOverridableForwardRefComponentPropsFactory<BaseCardComponent, C, BaseCardProps>;
+/**
+ * BaseCard is a versatile card component that can be used as a div, link, or custom component.
+ * It supports four types: default, action, overflow, and toggle, each with different header actions.
+ */
+declare const BaseCard: import("react").ForwardRefExoticComponent<Omit<Omit<import("../utils/jsx-types").ComponentPropsWithoutKeyAndRef<"div">, "children" | "title" | "defaultChecked" | "className" | "disabled" | "type" | "checked" | "readOnly" | "options" | "description" | "actionName" | "actionVariant" | "onActionClick" | "onOptionSelect" | "onToggleChange" | "toggleSize" | "toggleLabel" | "toggleSupportingText"> & BaseCardProps, "component"> & {
+    component?: BaseCardComponent | undefined;
+} & import("react").RefAttributes<HTMLDivElement>>;
+export default BaseCard;

package/Card/BaseCard.js

@@ -0,0 +1,48 @@
+'use client';
+import { jsxs, jsx } from 'react/jsx-runtime';
+import { forwardRef } from 'react';
+import { cardClasses } from '@mezzanine-ui/core/card';
+import { DotHorizontalIcon } from '@mezzanine-ui/icons';
+import Button from '../Button/Button.js';
+import Dropdown from '../Dropdown/Dropdown.js';
+import Toggle from '../Toggle/Toggle.js';
+import cx from 'clsx';
+
+/**
+ * BaseCard is a versatile card component that can be used as a div, link, or custom component.
+ * It supports four types: default, action, overflow, and toggle, each with different header actions.
+ */
+const BaseCard = forwardRef(function BaseCard(props, ref) {
+    const { children, className, component: Component = 'div', disabled = false, readOnly = false, title, description, type = 'default', ...rest } = props;
+    const hasHeaderContent = Boolean(title || description);
+    const renderHeaderAction = () => {
+        if (type === 'default') {
+            return null;
+        }
+        if (type === 'action') {
+            const { actionName, actionVariant = 'base-text-link', onActionClick, } = props;
+            return (jsx("div", { className: cardClasses.baseHeaderAction, children: jsx(Button, { disabled: disabled, onClick: (event) => {
+                        event.stopPropagation();
+                        onActionClick === null || onActionClick === void 0 ? void 0 : onActionClick(event);
+                    }, size: "sub", variant: actionVariant, type: "button", children: actionName }) }));
+        }
+        if (type === 'overflow') {
+            const { options, onOptionSelect } = props;
+            return (jsx("div", { className: cardClasses.baseHeaderAction, children: jsx(Dropdown, { disabled: disabled, mode: "single", onSelect: onOptionSelect, options: options, globalPortal: false, children: jsx(Button, { disabled: disabled, icon: DotHorizontalIcon, iconType: "icon-only", size: "sub", variant: "base-text-link", type: "button" }) }) }));
+        }
+        if (type === 'toggle') {
+            const { checked, defaultChecked, onToggleChange, toggleSize, toggleLabel, toggleSupportingText, } = props;
+            return (jsx("div", { className: cardClasses.baseHeaderAction, children: jsx(Toggle, { checked: checked, defaultChecked: defaultChecked, disabled: disabled, label: toggleLabel, onChange: onToggleChange, size: toggleSize, supportingText: toggleSupportingText }) }));
+        }
+        return null;
+    };
+    // Filter out type-specific props before spreading to component
+    const { actionName: _actionName, actionVariant: _actionVariant, onActionClick: _onActionClick, options: _options, onOptionSelect: _onOptionSelect, checked: _checked, defaultChecked: _defaultChecked, onToggleChange: _onToggleChange, toggleSize: _toggleSize, toggleLabel: _toggleLabel, toggleSupportingText: _toggleSupportingText, type: _type, ...componentProps } = rest;
+    return (jsxs(Component, { ...componentProps, ref: ref, "aria-disabled": disabled || undefined, "aria-readonly": readOnly || undefined, className: cx(cardClasses.base, {
+            [cardClasses.baseDisabled]: disabled,
+            [cardClasses.baseReadOnly]: readOnly,
+        }, className), children: [hasHeaderContent && (jsxs("div", { className: cardClasses.baseHeader, children: [jsxs("div", { className: cardClasses.baseHeaderContentWrapper, children: [title && (jsx("span", { className: cardClasses.baseHeaderTitle, children: title })), description && (jsx("span", { className: cardClasses.baseHeaderDescription, children: description }))] }), renderHeaderAction()] })), jsx("div", { className: cardClasses.baseContent, children: children })] }));
+});
+BaseCard.displayName = 'BaseCard';
+
+export { BaseCard as default };

package/Card/BaseCardSkeleton.d.ts

@@ -0,0 +1,14 @@
+import { NativeElementPropsWithoutKeyAndRef } from '../utils/jsx-types';
+export interface BaseCardSkeletonProps extends Omit<NativeElementPropsWithoutKeyAndRef<'div'>, 'children'> {
+    /**
+     * Whether to show content skeleton
+     * @default true
+     */
+    showContent?: boolean;
+}
+/**
+ * Skeleton placeholder for BaseCard component.
+ * Renders a skeleton that mimics the BaseCard layout.
+ */
+declare const BaseCardSkeleton: import("react").ForwardRefExoticComponent<BaseCardSkeletonProps & import("react").RefAttributes<HTMLDivElement>>;
+export default BaseCardSkeleton;

package/Card/BaseCardSkeleton.js

@@ -0,0 +1,18 @@
+'use client';
+import { jsxs, jsx } from 'react/jsx-runtime';
+import { forwardRef } from 'react';
+import { cardClasses } from '@mezzanine-ui/core/card';
+import Skeleton from '../Skeleton/Skeleton.js';
+import cx from 'clsx';
+
+/**
+ * Skeleton placeholder for BaseCard component.
+ * Renders a skeleton that mimics the BaseCard layout.
+ */
+const BaseCardSkeleton = forwardRef(function BaseCardSkeleton(props, ref) {
+    const { className, showContent = true, ...rest } = props;
+    return (jsxs("div", { ...rest, ref: ref, className: cx(cardClasses.base, cardClasses.baseReadOnly, className), children: [jsx("div", { className: cardClasses.baseHeader, children: jsxs("div", { className: cardClasses.baseHeaderContentWrapper, children: [jsx(Skeleton, { height: 20, width: "60%" }), jsx(Skeleton, { height: 16, width: "40%" })] }) }), showContent && (jsxs("div", { className: cardClasses.baseContent, children: [jsx(Skeleton, { height: 16, width: "100%" }), jsx(Skeleton, { height: 16, style: { marginTop: 8 }, width: "80%" })] }))] }));
+});
+BaseCardSkeleton.displayName = 'BaseCardSkeleton';
+
+export { BaseCardSkeleton as default };

package/Card/CardGroup.d.ts

@@ -0,0 +1,47 @@
+import { ReactNode } from 'react';
+/**
+ * Card type for loading skeleton
+ */
+export type CardGroupLoadingType = 'base' | 'four-thumbnail' | 'quick-action' | 'single-thumbnail';
+export interface CardGroupProps {
+    /**
+     * Custom class name
+     */
+    className?: string;
+    /**
+     * Card components to render in the group.
+     * Only accepts BaseCard, QuickActionCard, SingleThumbnailCard, and FourThumbnailCard as children.
+     */
+    children?: ReactNode;
+    /**
+     * Whether to show loading skeletons
+     * @default false
+     */
+    loading?: boolean;
+    /**
+     * Number of skeleton items to render when loading
+     * @default 3
+     */
+    loadingCount?: number;
+    /**
+     * Type of card skeleton to render when loading.
+     * Required when loading is true.
+     */
+    loadingType?: CardGroupLoadingType;
+    /**
+     * Width of each thumbnail skeleton when loadingType is 'single-thumbnail' or 'four-thumbnail'.
+     * @default 360
+     */
+    loadingThumbnailWidth?: number | string;
+    /**
+     * Aspect ratio of thumbnail skeletons when loadingType is 'single-thumbnail' or 'four-thumbnail'.
+     * For single-thumbnail, defaults to '16/9'. For four-thumbnail, defaults to '4/3'.
+     */
+    loadingThumbnailAspectRatio?: string;
+}
+/**
+ * CardGroup is a container for card components.
+ * It uses CSS Grid to layout cards in a horizontal row with consistent spacing.
+ */
+declare const CardGroup: import("react").ForwardRefExoticComponent<CardGroupProps & import("react").RefAttributes<HTMLDivElement>>;
+export default CardGroup;

package/Card/CardGroup.js

@@ -0,0 +1,147 @@
+'use client';
+import { jsxs, jsx } from 'react/jsx-runtime';
+import { cardClasses } from '@mezzanine-ui/core/card';
+import { forwardRef, Children, isValidElement } from 'react';
+import BaseCard from './BaseCard.js';
+import BaseCardSkeleton from './BaseCardSkeleton.js';
+import FourThumbnailCard from './FourThumbnailCard.js';
+import FourThumbnailCardSkeleton from './FourThumbnailCardSkeleton.js';
+import QuickActionCard from './QuickActionCard.js';
+import QuickActionCardSkeleton from './QuickActionCardSkeleton.js';
+import SingleThumbnailCard from './SingleThumbnailCard.js';
+import SingleThumbnailCardSkeleton from './SingleThumbnailCardSkeleton.js';
+import cx from 'clsx';
+
+// List of allowed child component types
+const ALLOWED_CARD_TYPES = [
+    BaseCard,
+    FourThumbnailCard,
+    QuickActionCard,
+    SingleThumbnailCard,
+];
+/**
+ * Get display name of a component for error messages
+ */
+function getComponentDisplayName(child) {
+    const { type } = child;
+    if (typeof type === 'string') {
+        return type;
+    }
+    return (type.displayName ||
+        type.name ||
+        'Unknown');
+}
+/**
+ * Detect the first valid card type from children
+ */
+function getFirstCardType(children) {
+    let firstType = null;
+    Children.forEach(children, (child) => {
+        if (firstType !== null)
+            return;
+        if (!isValidElement(child))
+            return;
+        if (child.type === QuickActionCard) {
+            firstType = QuickActionCard;
+        }
+        else if (child.type === BaseCard) {
+            firstType = BaseCard;
+        }
+        else if (child.type === SingleThumbnailCard) {
+            firstType = SingleThumbnailCard;
+        }
+        else if (child.type === FourThumbnailCard) {
+            firstType = FourThumbnailCard;
+        }
+    });
+    return firstType;
+}
+/**
+ * Get the skeleton component based on loading type
+ */
+function getSkeletonComponent(loadingType) {
+    switch (loadingType) {
+        case 'base':
+            return BaseCardSkeleton;
+        case 'four-thumbnail':
+            return FourThumbnailCardSkeleton;
+        case 'quick-action':
+            return QuickActionCardSkeleton;
+        case 'single-thumbnail':
+            return SingleThumbnailCardSkeleton;
+        default:
+            return BaseCardSkeleton;
+    }
+}
+/**
+ * Get the group class modifier based on loading type
+ */
+function getGroupClassFromLoadingType(loadingType) {
+    switch (loadingType) {
+        case 'four-thumbnail':
+            return cardClasses.groupFourThumbnail;
+        case 'quick-action':
+            return cardClasses.groupQuickAction;
+        case 'single-thumbnail':
+            return cardClasses.groupSingleThumbnail;
+        default:
+            return undefined;
+    }
+}
+/**
+ * CardGroup is a container for card components.
+ * It uses CSS Grid to layout cards in a horizontal row with consistent spacing.
+ */
+const CardGroup = forwardRef(function CardGroup(props, ref) {
+    const { className, children, loading = false, loadingCount = 3, loadingThumbnailAspectRatio, loadingThumbnailWidth, loadingType, } = props;
+    // Detect first card type to determine min-width class
+    const firstCardType = getFirstCardType(children);
+    // Validate children at runtime
+    const validChildren = Children.map(children, (child) => {
+        if (!isValidElement(child)) {
+            return child;
+        }
+        const isAllowedType = ALLOWED_CARD_TYPES.some((allowedType) => child.type === allowedType);
+        if (!isAllowedType) {
+            const displayName = getComponentDisplayName(child);
+            console.warn(`[CardGroup] Invalid child type: <${displayName}>. ` +
+                'CardGroup only accepts Card components (BaseCard, FourThumbnailCard, QuickActionCard, SingleThumbnailCard) as children.');
+            return null;
+        }
+        return child;
+    });
+    // Render loading skeletons
+    const renderSkeletons = () => {
+        if (!loading || !loadingType) {
+            return null;
+        }
+        const SkeletonComponent = getSkeletonComponent(loadingType);
+        // Build props for thumbnail skeletons
+        const thumbnailSkeletonProps = loadingType === 'single-thumbnail' || loadingType === 'four-thumbnail'
+            ? {
+                ...(loadingThumbnailAspectRatio && {
+                    thumbnailAspectRatio: loadingThumbnailAspectRatio,
+                }),
+                ...(loadingThumbnailWidth && {
+                    thumbnailWidth: loadingThumbnailWidth,
+                }),
+            }
+            : undefined;
+        return Array.from({ length: loadingCount }, (_, index) => (jsx(SkeletonComponent, { ...thumbnailSkeletonProps }, `skeleton-${index}`)));
+    };
+    // Determine group class modifier
+    const groupClassModifier = loadingType && loading
+        ? getGroupClassFromLoadingType(loadingType)
+        : undefined;
+    return (jsxs("div", { ref: ref, className: cx(cardClasses.group, {
+            [cardClasses.groupFourThumbnail]: firstCardType === FourThumbnailCard ||
+                groupClassModifier === cardClasses.groupFourThumbnail,
+            [cardClasses.groupQuickAction]: firstCardType === QuickActionCard ||
+                groupClassModifier === cardClasses.groupQuickAction,
+            [cardClasses.groupSingleThumbnail]: firstCardType === SingleThumbnailCard ||
+                groupClassModifier === cardClasses.groupSingleThumbnail,
+        }, className), children: [validChildren, renderSkeletons()] }));
+});
+CardGroup.displayName = 'CardGroup';
+
+export { CardGroup as default };