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

package/Dropdown/DropdownItem.js

@@ -33,7 +33,7 @@ function truncateArrayDepth(input, maxDepth = 3, warn = true) {
             // Stop going deeper once maximum depth is reached, remove children
             return options.map(({ children: _children, ...option }) => option);
         }
-        return options.map(option => {
+        return options.map((option) => {
             if (!option.children)
                 return option;
             return {
@@ -65,13 +65,15 @@ function truncateArrayDepth(input, maxDepth = 3, warn = true) {
     return truncate(input);
 }
 function DropdownItem(props) {
-    const { activeIndex, disabled = false, listboxId, listboxLabel, mode = 'single', options, toggleCheckedOnClick, value, type, maxHeight, actionConfig, onHover, onSelect, followText, headerContent, status, loadingText, emptyText, emptyIcon, loadingPosition = 'full', onReachBottom, onLeaveBottom, onScroll, scrollbarDefer = true, scrollbarDisabled = false, scrollbarMaxWidth, scrollbarOptions, } = props;
+    const { activeIndex, keyboardActiveIndex, disabled = false, listboxId, listboxLabel, mode = 'single', options, toggleCheckedOnClick, value, type, maxHeight, minWidth, actionConfig, onHover, onSelect, followText, headerContent, status, loadingText, emptyText, emptyIcon, loadingPosition = 'full', onReachBottom, onLeaveBottom, onScroll, scrollbarDefer = true, scrollbarDisabled = false, scrollbarMaxWidth, scrollbarOptions, } = props;
+    const { expandedNodes: expandedNodesProp, onToggleExpand: onToggleExpandProp, } = props;
     const optionsContent = truncateArrayDepth(options, 3);
     const listRef = useRef(null);
     const listWrapperRef = useRef(null);
     const viewportRef = useRef(null);
     const wasAtBottomRef = useRef(false);
-    const [expandedNodes, setExpandedNodes] = useState(new Set());
+    const [internalExpandedNodes, setInternalExpandedNodes] = useState(new Set());
+    const expandedNodes = expandedNodesProp !== null && expandedNodesProp !== void 0 ? expandedNodesProp : internalExpandedNodes;
     const hasActions = Boolean(actionConfig === null || actionConfig === void 0 ? void 0 : actionConfig.showActions);
     const hasHeader = Boolean(headerContent);
     const shouldUseScrollbar = maxHeight && !scrollbarDisabled;
@@ -79,7 +81,11 @@ function DropdownItem(props) {
     const [actionRef, actionHeight] = useElementHeight(hasActions && !!maxHeight);
     const [headerRef, headerHeight] = useElementHeight(hasHeader && !!maxHeight);
     const toggleExpand = useCallback((optionId) => {
-        setExpandedNodes((prev) => {
+        if (onToggleExpandProp) {
+            onToggleExpandProp(optionId);
+            return;
+        }
+        setInternalExpandedNodes((prev) => {
             const next = new Set(prev);
             if (next.has(optionId)) {
                 next.delete(optionId);
@@ -89,7 +95,7 @@ function DropdownItem(props) {
             }
             return next;
         });
-    }, []);
+    }, [onToggleExpandProp]);
     const visibleShortcutOptions = useMemo(() => {
         const result = [];
         const collectDefault = (optionList) => {
@@ -164,10 +170,10 @@ function DropdownItem(props) {
         });
         if (!mainToken)
             return false;
-        if (requireMeta !== event.metaKey
-            || requireCtrl !== event.ctrlKey
-            || requireAlt !== event.altKey
-            || requireShift !== event.shiftKey) {
+        if (requireMeta !== event.metaKey ||
+            requireCtrl !== event.ctrlKey ||
+            requireAlt !== event.altKey ||
+            requireShift !== event.shiftKey) {
             return false;
         }
         const mainCode = keycode(mainToken);
@@ -179,7 +185,8 @@ function DropdownItem(props) {
             return true;
         }
         const eventKeyName = keycode(eventCode);
-        return typeof eventKeyName === 'string' && eventKeyName.toLowerCase() === mainToken;
+        return (typeof eventKeyName === 'string' &&
+            eventKeyName.toLowerCase() === mainToken);
     }, []);
     const renderGroupedOptions = (optionList, startIndex) => {
         let currentIndex = startIndex;
@@ -190,10 +197,13 @@ function DropdownItem(props) {
             if (hasChildren) {
                 groupElements.push(jsx(Typography, { variant: "body", className: dropdownClasses.groupLabel, children: groupOption.name }, groupOption.id));
                 (_a = groupOption.children) === null || _a === void 0 ? void 0 : _a.forEach((option) => {
-                    var _a, _b, _c;
+                    var _a, _b, _c, _d;
                     currentIndex += 1;
                     const optionIndex = currentIndex;
-                    const isActive = optionIndex === activeIndex;
+                    const isActive = optionIndex ===
+                        (keyboardActiveIndex !== undefined
+                            ? keyboardActiveIndex
+                            : activeIndex);
                     const isSelected = Array.isArray(value)
                         ? value.includes(option.id)
                         : value === option.id;
@@ -204,7 +214,7 @@ function DropdownItem(props) {
                             if (disabled)
                                 return;
                             onSelect === null || onSelect === void 0 ? void 0 : onSelect(option);
-                        }, checkSite: "none", validate: (_b = option.validate) !== null && _b !== void 0 ? _b : 'default', onMouseEnter: () => onHover === null || onHover === void 0 ? void 0 : onHover(optionIndex), showUnderline: (_c = option.showUnderline) !== null && _c !== void 0 ? _c : false, appendContent: shortcutText }, option.id));
+                        }, checkSite: (_b = option === null || option === void 0 ? void 0 : option.checkSite) !== null && _b !== void 0 ? _b : 'suffix', validate: (_c = option.validate) !== null && _c !== void 0 ? _c : 'default', onMouseEnter: () => onHover === null || onHover === void 0 ? void 0 : onHover(optionIndex), showUnderline: (_d = option.showUnderline) !== null && _d !== void 0 ? _d : false, appendContent: shortcutText }, option.id));
                 });
             }
             return groupElements;
@@ -230,37 +240,49 @@ function DropdownItem(props) {
     }, []);
     const renderTreeOptions = (optionList, depth, startIndex) => {
         let currentIndex = startIndex;
-        const selectedIds = Array.isArray(value) ? value.map((id) => String(id)) : value ? [String(value)] : [];
+        const selectedIds = Array.isArray(value)
+            ? value.map((id) => String(id))
+            : value
+                ? [String(value)]
+                : [];
         const elements = (optionList !== null && optionList !== void 0 ? optionList : []).flatMap((option) => {
-            var _a, _b, _c;
+            var _a, _b, _c, _d;
             currentIndex += 1;
             const optionIndex = currentIndex;
             const level = Math.min(depth, 2);
-            const isActive = optionIndex === activeIndex;
+            const isActive = optionIndex ===
+                (keyboardActiveIndex !== undefined ? keyboardActiveIndex : activeIndex);
             const hasChildren = Boolean(option.children && option.children.length > 0);
             const isExpanded = hasChildren && expandedNodes.has(option.id);
             let prependIcon = undefined;
             if (hasChildren && level !== 2) {
                 prependIcon = isExpanded ? CaretDownIcon : CaretRightIcon;
             }
-            const checkSite = option.showCheckbox ? 'prefix' : 'none';
+            const checkSite = option.showCheckbox
+                ? 'prefix'
+                : ((_a = option.checkSite) !== null && _a !== void 0 ? _a : (mode === 'single' ? 'suffix' : 'none'));
             const shortcutText = option.shortcutText
                 ? option.shortcutText
-                : shortcutTextHandler((_a = option.shortcutKeys) !== null && _a !== void 0 ? _a : []);
+                : shortcutTextHandler((_b = option.shortcutKeys) !== null && _b !== void 0 ? _b : []);
             const selectionState = hasChildren && mode === 'multiple'
                 ? calculateNodeSelectionState(option, selectedIds)
                 : {
                     checked: selectedIds.includes(String(option.id)),
                     indeterminate: false,
                 };
-            const resolvedToggleCheckedOnClick = toggleCheckedOnClick !== null && toggleCheckedOnClick !== void 0 ? toggleCheckedOnClick : !(hasChildren
-                && type === 'tree'
-                && mode === 'multiple'
-                && option.showCheckbox);
-            const card = (jsx(DropdownItemCard, { active: isActive, checked: selectionState.checked, indeterminate: selectionState.indeterminate, disabled: disabled, id: `${listboxId}-option-${optionIndex}`, label: option.name, level: level, mode: mode, name: option.name, toggleCheckedOnClick: resolvedToggleCheckedOnClick, onClick: () => {
+            const resolvedToggleCheckedOnClick = toggleCheckedOnClick !== null && toggleCheckedOnClick !== void 0 ? toggleCheckedOnClick : !(hasChildren &&
+                type === 'tree' &&
+                mode === 'multiple' &&
+                option.showCheckbox);
+            const card = (jsx(DropdownItemCard, { active: isActive, checked: selectionState.checked, className: !hasChildren && level === 1
+                    ? dropdownClasses.cardLeafLevel1
+                    : undefined, indeterminate: selectionState.indeterminate, disabled: disabled, id: `${listboxId}-option-${optionIndex}`, label: option.name, level: level, mode: mode, name: option.name, toggleCheckedOnClick: resolvedToggleCheckedOnClick, onClick: () => {
                     if (disabled)
                         return;
-                    if (hasChildren && type === 'tree' && mode === 'multiple' && option.showCheckbox) {
+                    if (hasChildren &&
+                        type === 'tree' &&
+                        mode === 'multiple' &&
+                        option.showCheckbox) {
                         toggleExpand(option.id);
                     }
                     else if (hasChildren && type === 'tree') {
@@ -270,7 +292,10 @@ function DropdownItem(props) {
                         // In `tree` + `multiple` mode, `DropdownItemCard` already triggers selection via
                         // `onCheckedChange` when row is clicked (it toggles checked first, then calls `onClick`),
                         // so calling `onSelect` here would cause it to fire twice for leaf nodes.
-                        if (!(type === 'tree' && mode === 'multiple')) {
+                        // In `multiple` mode, row click also triggers `onCheckedChange` when
+                        // `toggleCheckedOnClick` is enabled, so avoid firing `onSelect` twice.
+                        if (!(type === 'tree' && mode === 'multiple') &&
+                            !(mode === 'multiple' && resolvedToggleCheckedOnClick)) {
                             onSelect === null || onSelect === void 0 ? void 0 : onSelect(option);
                         }
                     }
@@ -278,7 +303,7 @@ function DropdownItem(props) {
                     if (!disabled) {
                         onSelect === null || onSelect === void 0 ? void 0 : onSelect(option);
                     }
-                }, followText: followText, checkSite: checkSite, onMouseEnter: () => onHover === null || onHover === void 0 ? void 0 : onHover(optionIndex), prependIcon: prependIcon, showUnderline: (_b = option.showUnderline) !== null && _b !== void 0 ? _b : false, validate: (_c = option.validate) !== null && _c !== void 0 ? _c : 'default', appendContent: shortcutText }, option.id));
+                }, followText: followText, checkSite: checkSite, onMouseEnter: () => onHover === null || onHover === void 0 ? void 0 : onHover(optionIndex), prependIcon: prependIcon, showUnderline: (_c = option.showUnderline) !== null && _c !== void 0 ? _c : false, validate: (_d = option.validate) !== null && _d !== void 0 ? _d : 'default', appendContent: shortcutText }, option.id));
             if (hasChildren && isExpanded && type === 'tree') {
                 const childResult = renderTreeOptions(option.children, depth + 1, currentIndex);
                 currentIndex = childResult.nextIndex;
@@ -297,11 +322,12 @@ function DropdownItem(props) {
             const isSelected = Array.isArray(value)
                 ? value.includes(option.id)
                 : value === option.id;
-            const isActive = optionIndex === activeIndex;
+            const isActive = optionIndex ===
+                (keyboardActiveIndex !== undefined ? keyboardActiveIndex : activeIndex);
             const shortcutText = option.shortcutText
                 ? option.shortcutText
                 : shortcutTextHandler((_a = option.shortcutKeys) !== null && _a !== void 0 ? _a : []);
-            const checkSite = (_b = option === null || option === void 0 ? void 0 : option.checkSite) !== null && _b !== void 0 ? _b : 'none';
+            const checkSite = (_b = option === null || option === void 0 ? void 0 : option.checkSite) !== null && _b !== void 0 ? _b : 'suffix';
             return (jsx(DropdownItemCard, { followText: followText, active: isActive, checked: isSelected, disabled: disabled, id: `${listboxId}-option-${optionIndex}`, label: option.name, mode: mode, name: option.name, toggleCheckedOnClick: toggleCheckedOnClick, onClick: () => {
                     if (disabled)
                         return;
@@ -328,13 +354,17 @@ function DropdownItem(props) {
     // Show bottom loading when status is loading and loadingPosition is bottom
     const shouldShowBottomLoading = status === 'loading' && loadingPosition === 'bottom';
     const listStyle = useMemo(() => {
-        if (!maxHeight) {
-            return undefined;
+        const styles = {};
+        if (maxHeight) {
+            styles.maxHeight =
+                typeof maxHeight === 'number' ? `${maxHeight}px` : maxHeight;
         }
-        return {
-            maxHeight: typeof maxHeight === 'number' ? `${maxHeight}px` : maxHeight,
-        };
-    }, [maxHeight]);
+        if (minWidth !== undefined) {
+            styles['--mzn-dropdown-list-min-width'] =
+                typeof minWidth === 'number' ? `${minWidth}px` : minWidth;
+        }
+        return Object.keys(styles).length > 0 ? styles : undefined;
+    }, [maxHeight, minWidth]);
     const listWrapperStyle = useMemo(() => {
         if (!maxHeight) {
             return undefined;
@@ -358,7 +388,8 @@ function DropdownItem(props) {
             if (event.repeat)
                 return;
             const targetOption = visibleShortcutOptions.find((option) => {
-                if (!Array.isArray(option.shortcutKeys) || option.shortcutKeys.length === 0) {
+                if (!Array.isArray(option.shortcutKeys) ||
+                    option.shortcutKeys.length === 0) {
                     return false;
                 }
                 return option.shortcutKeys.some((shortcut) => matchShortcut(event, shortcut));
@@ -367,7 +398,9 @@ function DropdownItem(props) {
                 return;
             event.preventDefault();
             event.stopPropagation();
-            if (type === 'tree' && targetOption.children && targetOption.children.length > 0) {
+            if (type === 'tree' &&
+                targetOption.children &&
+                targetOption.children.length > 0) {
                 toggleExpand(targetOption.id);
                 return;
             }
@@ -377,7 +410,14 @@ function DropdownItem(props) {
         return () => {
             listElement.removeEventListener('keydown', handleKeyDown);
         };
-    }, [disabled, matchShortcut, onSelect, type, toggleExpand, visibleShortcutOptions]);
+    }, [
+        disabled,
+        matchShortcut,
+        onSelect,
+        type,
+        toggleExpand,
+        visibleShortcutOptions,
+    ]);
     const handleViewportReady = useCallback((viewport) => {
         viewportRef.current = viewport;
         listWrapperRef.current = viewport;
@@ -416,7 +456,9 @@ function DropdownItem(props) {
             return;
         }
         const listWrapperElement = listWrapperRef.current;
-        if (!listWrapperElement || !maxHeight || (!onReachBottom && !onLeaveBottom && !onScroll)) {
+        if (!listWrapperElement ||
+            !maxHeight ||
+            (!onReachBottom && !onLeaveBottom && !onScroll)) {
             return;
         }
         // Initialize wasAtBottom state by checking current position
@@ -453,7 +495,8 @@ function DropdownItem(props) {
         };
     }, [maxHeight, onReachBottom, onLeaveBottom, onScroll, shouldUseScrollbar]);
     const scrollbarEvents = useMemo(() => {
-        if (!shouldUseScrollbar || (!onReachBottom && !onLeaveBottom && !onScroll)) {
+        if (!shouldUseScrollbar ||
+            (!onReachBottom && !onLeaveBottom && !onScroll)) {
             return undefined;
         }
         return {
@@ -479,10 +522,15 @@ function DropdownItem(props) {
                 wasAtBottomRef.current = isAtBottom;
             },
         };
-    }, [getIsAtBottom, shouldUseScrollbar, onReachBottom, onLeaveBottom, onScroll]);
-    return (jsxs("ul", { "aria-label": listboxLabel || (optionsContent.length === 0 ? 'Dropdown options' : undefined), className: dropdownClasses.list, id: listboxId, ref: listRef, role: "listbox", style: listStyle, tabIndex: -1, children: [hasHeader && (jsx("li", { className: dropdownClasses.listHeader, role: "presentation", ref: headerRef, children: jsx("div", { className: dropdownClasses.listHeaderInner, children: headerContent }) })), maxHeight
-                ? (shouldUseScrollbar ? (jsx(Scrollbar, { className: dropdownClasses.listWrapper, defer: scrollbarDefer, disabled: false, events: scrollbarEvents, maxHeight: listWrapperStyle === null || listWrapperStyle === void 0 ? void 0 : listWrapperStyle.maxHeight, maxWidth: scrollbarMaxWidth, onViewportReady: handleViewportReady, options: scrollbarOptions, children: shouldShowFullStatus ? (jsx(DropdownStatus, { status: status, loadingText: loadingText, emptyText: emptyText, emptyIcon: emptyIcon })) : (jsxs(Fragment, { children: [renderedOptions, shouldShowBottomLoading && (jsx("li", { className: dropdownClasses.loadingMore, "aria-live": "polite", role: "status", children: jsx(DropdownStatus, { status: "loading", loadingText: loadingText }) }))] })) })) : (jsx("div", { ref: listWrapperRef, className: dropdownClasses.listWrapper, style: listWrapperStyle, children: shouldShowFullStatus ? (jsx(DropdownStatus, { status: status, loadingText: loadingText, emptyText: emptyText, emptyIcon: emptyIcon })) : (jsxs(Fragment, { children: [renderedOptions, shouldShowBottomLoading && (jsx("li", { className: dropdownClasses.loadingMore, "aria-live": "polite", role: "status", children: jsx(DropdownStatus, { status: "loading", loadingText: loadingText }) }))] })) })))
-                : shouldShowFullStatus ? (jsx(DropdownStatus, { status: status, loadingText: loadingText, emptyText: emptyText, emptyIcon: emptyIcon })) : (jsxs(Fragment, { children: [renderedOptions, shouldShowBottomLoading && (jsx("li", { className: dropdownClasses.loadingMore, "aria-live": "polite", role: "status", children: jsx(DropdownStatus, { status: "loading", loadingText: loadingText }) }))] })), hasActions && (jsx("div", { ref: actionRef, children: jsx(DropdownAction, { ...actionConfig }) }))] }));
+    }, [
+        getIsAtBottom,
+        shouldUseScrollbar,
+        onReachBottom,
+        onLeaveBottom,
+        onScroll,
+    ]);
+    return (jsxs("ul", { "aria-label": listboxLabel ||
+            (optionsContent.length === 0 ? 'Dropdown options' : undefined), className: dropdownClasses.list, id: listboxId, ref: listRef, role: "listbox", style: listStyle, tabIndex: -1, children: [hasHeader && (jsx("li", { className: dropdownClasses.listHeader, role: "presentation", ref: headerRef, children: jsx("div", { className: dropdownClasses.listHeaderInner, children: headerContent }) })), maxHeight ? (shouldUseScrollbar ? (jsx(Scrollbar, { className: dropdownClasses.listWrapper, defer: scrollbarDefer, disabled: false, events: scrollbarEvents, maxHeight: listWrapperStyle === null || listWrapperStyle === void 0 ? void 0 : listWrapperStyle.maxHeight, maxWidth: scrollbarMaxWidth, onViewportReady: handleViewportReady, options: scrollbarOptions, children: shouldShowFullStatus ? (jsx(DropdownStatus, { status: status, loadingText: loadingText, emptyText: emptyText, emptyIcon: emptyIcon })) : (jsxs(Fragment, { children: [renderedOptions, shouldShowBottomLoading && (jsx("li", { className: dropdownClasses.loadingMore, "aria-live": "polite", role: "status", children: jsx(DropdownStatus, { status: "loading", loadingText: loadingText }) }))] })) })) : (jsx("div", { ref: listWrapperRef, className: dropdownClasses.listWrapper, style: listWrapperStyle, children: shouldShowFullStatus ? (jsx(DropdownStatus, { status: status, loadingText: loadingText, emptyText: emptyText, emptyIcon: emptyIcon })) : (jsxs(Fragment, { children: [renderedOptions, shouldShowBottomLoading && (jsx("li", { className: dropdownClasses.loadingMore, "aria-live": "polite", role: "status", children: jsx(DropdownStatus, { status: "loading", loadingText: loadingText }) }))] })) }))) : shouldShowFullStatus ? (jsx(DropdownStatus, { status: status, loadingText: loadingText, emptyText: emptyText, emptyIcon: emptyIcon })) : (jsxs(Fragment, { children: [renderedOptions, shouldShowBottomLoading && (jsx("li", { className: dropdownClasses.loadingMore, "aria-live": "polite", role: "status", children: jsx(DropdownStatus, { status: "loading", loadingText: loadingText }) }))] })), hasActions && (jsx("div", { ref: actionRef, children: jsx(DropdownAction, { ...actionConfig }) }))] }));
 }
 
 export { DropdownItem as default };

package/Dropdown/DropdownItemCard.d.ts

@@ -3,8 +3,9 @@ import { type IconDefinition } from '@mezzanine-ui/icons';
 export interface DropdownItemCardProps {
     /**
      * Whether the option is currently active (highlighted by keyboard navigation).
-     * This controls the aria-selected attribute according to W3C ARIA spec.
-     * When an option is referenced by aria-activedescendant, it should have aria-selected="true".
+     * Used to apply visual highlight and drive the `--active` CSS modifier.
+     * Note: keyboard focus position is communicated to screen readers via `aria-activedescendant`
+     * on the trigger element, not via `aria-selected` on the option itself.
      */
     active?: boolean;
     /**

package/Dropdown/DropdownItemCard.js

@@ -57,8 +57,10 @@ function DropdownItemCard(props) {
             ];
     }, [cardLabel, followText]);
     const showPrependContent = useMemo(() => {
-        return prependIcon || (checkSite === 'prefix' && mode === 'multiple');
-    }, [prependIcon, checkSite, mode]);
+        return (prependIcon ||
+            (checkSite === 'prefix' && mode === 'multiple') ||
+            (checkSite === 'prefix' && mode === 'single' && isChecked));
+    }, [prependIcon, checkSite, mode, isChecked]);
     const showAppendContent = useMemo(() => {
         return appendContent || appendIcon || (checkSite === 'suffix' && isChecked);
     }, [appendContent, appendIcon, checkSite, isChecked]);
@@ -105,11 +107,12 @@ function DropdownItemCard(props) {
             return;
         if (event.key === 'Enter' || event.key === ' ') {
             event.preventDefault();
-            onClick === null || onClick === void 0 ? void 0 : onClick();
+            handleClick();
         }
     };
-    return (jsxs(Fragment, { children: [jsx("li", { ...(labelId ? { 'aria-labelledby': labelId } : {}), ...(ariaLabel ? { 'aria-label': ariaLabel } : {}), "aria-selected": active, className: cx(dropdownClasses.card, dropdownClasses.cardLevel(level), {
+    return (jsxs(Fragment, { children: [jsx("li", { ...(labelId ? { 'aria-labelledby': labelId } : {}), ...(ariaLabel ? { 'aria-label': ariaLabel } : {}), "aria-selected": isChecked, className: cx(dropdownClasses.card, dropdownClasses.cardLevel(level), {
                     [dropdownClasses.cardActive]: active || isChecked,
+                    [dropdownClasses.cardKeyboardActive]: active,
                     [dropdownClasses.cardDisabled]: disabled,
                     [dropdownClasses.cardDanger]: validate === 'danger',
                 }, className), id: id, role: "option", tabIndex: -1, onMouseEnter: onMouseEnter, onClick: handleClick, onKeyDown: handleKeyDown, children: jsxs("div", { className: dropdownClasses.cardContainer, children: [showPrependContent && (jsxs("div", { className: dropdownClasses.cardPrependContent, children: [prependIcon && jsx(Icon, { icon: prependIcon, color: iconColor }), checkSite === 'prefix' && mode === 'multiple' && (jsx(Checkbox, { checked: isChecked, disabled: disabled, indeterminate: indeterminate, onChange: handleCheckboxChange, ...(onCheckedChange
@@ -117,7 +120,7 @@ function DropdownItemCard(props) {
                                             onClick: (event) => event.stopPropagation(),
                                             onMouseDown: (event) => event.stopPropagation(),
                                         }
-                                        : {}) }))] })), jsxs("div", { className: dropdownClasses.cardBody, children: [cardLabel &&
+                                        : {}) })), checkSite === 'prefix' && mode === 'single' && isChecked && (jsx(Icon, { icon: CheckedIcon, color: appendIconColor, size: 16 }))] })), jsxs("div", { className: dropdownClasses.cardBody, children: [cardLabel &&
                                     renderHighlightedText(labelParts, dropdownClasses.cardTitle, labelId), subTitleParts.length > 0 &&
                                     renderHighlightedText(subTitleParts, dropdownClasses.cardDescription)] }), showAppendContent && (jsxs("div", { className: dropdownClasses.cardAppendContent, children: [appendContent && (jsx(Typography, { color: "text-neutral-light", children: appendContent })), appendIcon && jsx(Icon, { icon: appendIcon, color: iconColor }), checkSite === 'suffix' && isChecked && (jsx(Icon, { icon: CheckedIcon, color: appendIconColor, size: 16 }))] }))] }) }), showUnderline && (jsx("li", { role: "presentation", "aria-hidden": "true", children: jsx(Separator, { orientation: "horizontal", className: dropdownClasses.cardUnderline }) }))] }));
 }

package/Dropdown/dropdownKeydownHandler.d.ts

@@ -11,6 +11,12 @@ export declare function createDropdownKeydownHandler(params: {
     open: boolean;
     options: DropdownOption[];
     setActiveIndex: Dispatch<SetStateAction<number | null>>;
+    /**
+     * Optional setter for keyboard-only active index.
+     * When provided, it is updated alongside `setActiveIndex` on arrow key navigation,
+     * and cleared on Escape / directional keys that exit the list.
+     */
+    setKeyboardActiveIndex?: Dispatch<SetStateAction<number | null>>;
     setListboxHasVisualFocus: (focus: boolean) => void;
     setOpen: (open: boolean) => void;
 }): (e: React.KeyboardEvent<HTMLInputElement>) => void;

package/Dropdown/dropdownKeydownHandler.js

@@ -3,7 +3,7 @@
  * Keeps logic centralized in DropdownItem for easy reuse.
  */
 function createDropdownKeydownHandler(params) {
-    const { activeIndex, onEnterSelect, onEscape, open, options, setActiveIndex, setListboxHasVisualFocus, setOpen, } = params;
+    const { activeIndex, onEnterSelect, onEscape, open, options, setActiveIndex, setKeyboardActiveIndex, setListboxHasVisualFocus, setOpen, } = params;
     return (e) => {
         if (options.length === 0)
             return;
@@ -15,13 +15,14 @@ function createDropdownKeydownHandler(params) {
                     setOpen(true);
                     setListboxHasVisualFocus(true);
                     setActiveIndex(() => 0);
+                    setKeyboardActiveIndex === null || setKeyboardActiveIndex === void 0 ? void 0 : setKeyboardActiveIndex(() => 0);
                     return;
                 }
                 setListboxHasVisualFocus(true);
                 setActiveIndex((prev) => {
-                    if (prev === null)
-                        return 0;
-                    return prev >= options.length - 1 ? 0 : prev + 1;
+                    const next = prev === null ? 0 : prev >= options.length - 1 ? 0 : prev + 1;
+                    setKeyboardActiveIndex === null || setKeyboardActiveIndex === void 0 ? void 0 : setKeyboardActiveIndex(() => next);
+                    return next;
                 });
                 break;
             }
@@ -32,13 +33,18 @@ function createDropdownKeydownHandler(params) {
                     setOpen(true);
                     setListboxHasVisualFocus(true);
                     setActiveIndex(() => options.length - 1);
+                    setKeyboardActiveIndex === null || setKeyboardActiveIndex === void 0 ? void 0 : setKeyboardActiveIndex(() => options.length - 1);
                     return;
                 }
                 setListboxHasVisualFocus(true);
                 setActiveIndex((prev) => {
-                    if (prev === null)
-                        return options.length - 1;
-                    return prev <= 0 ? options.length - 1 : prev - 1;
+                    const next = prev === null
+                        ? options.length - 1
+                        : prev <= 0
+                            ? options.length - 1
+                            : prev - 1;
+                    setKeyboardActiveIndex === null || setKeyboardActiveIndex === void 0 ? void 0 : setKeyboardActiveIndex(() => next);
+                    return next;
                 });
                 break;
             }
@@ -64,6 +70,7 @@ function createDropdownKeydownHandler(params) {
             case 'ArrowRight': {
                 setListboxHasVisualFocus(false);
                 setActiveIndex(() => null);
+                setKeyboardActiveIndex === null || setKeyboardActiveIndex === void 0 ? void 0 : setKeyboardActiveIndex(() => null);
                 break;
             }
         }

package/FilterArea/Filter.d.ts

@@ -13,7 +13,7 @@ export interface FilterProps extends Omit<NativeElementPropsWithoutKeyAndRef<'di
      */
     children: ReactElement<FormFieldProps> | ReactElement<FormFieldProps>[];
     /**
-     * Layout control - Whether the field should automatically expand to fill the entire row (equivalent to span={12}).
+     * Layout control - Whether the field should automatically expand to fill the entire row (equivalent to span={6}).
      * @default false
      */
     grow?: boolean;
@@ -22,11 +22,34 @@ export interface FilterProps extends Omit<NativeElementPropsWithoutKeyAndRef<'di
      */
     minWidth?: string | number;
     /**
-     * Layout control - Number of columns the field occupies in the Grid (1-12, Grid has 12 columns total).
+     * Layout control - Number of columns the field occupies in the Grid (1-6, Grid has 6 columns total).
      * This property is ignored when grow is true.
      * @default 2
      */
     span?: FilterSpan;
 }
+/**
+ * 單一篩選條件元件，用於在 FilterLine 中定義欄位的佔位寬度。
+ *
+ * 使用 6 欄 Grid，`span` 決定欄位佔用幾欄（1–6）；
+ * `grow` 設為 `true` 時欄位自動填滿整行。
+ * 從 FilterAreaContext 繼承 `size`，統一套用至內部的輸入元件。
+ *
+ * @example
+ * ```tsx
+ * import { Filter } from '@mezzanine-ui/react';
+ * import { FormField } from '@mezzanine-ui/react';
+ * import Input from '@mezzanine-ui/react/Input';
+ *
+ * <Filter span={2}>
+ *   <FormField label="名稱" name="name" layout="horizontal">
+ *     <Input placeholder="請輸入" />
+ *   </FormField>
+ * </Filter>
+ * ```
+ *
+ * @see {@link FilterLine} 包含 Filter 的行容器
+ * @see {@link FilterArea} 管理整個篩選器的容器
+ */
 declare const Filter: import("react").ForwardRefExoticComponent<FilterProps & import("react").RefAttributes<HTMLDivElement>>;
 export default Filter;

package/FilterArea/Filter.js

@@ -5,6 +5,29 @@ import { filterAreaClasses, filterAreaPrefix } from '@mezzanine-ui/core/filter-a
 import FilterAreaContext from './FilterAreaContext.js';
 import cx from 'clsx';
 
+/**
+ * 單一篩選條件元件，用於在 FilterLine 中定義欄位的佔位寬度。
+ *
+ * 使用 6 欄 Grid，`span` 決定欄位佔用幾欄（1–6）；
+ * `grow` 設為 `true` 時欄位自動填滿整行。
+ * 從 FilterAreaContext 繼承 `size`，統一套用至內部的輸入元件。
+ *
+ * @example
+ * ```tsx
+ * import { Filter } from '@mezzanine-ui/react';
+ * import { FormField } from '@mezzanine-ui/react';
+ * import Input from '@mezzanine-ui/react/Input';
+ *
+ * <Filter span={2}>
+ *   <FormField label="名稱" name="name" layout="horizontal">
+ *     <Input placeholder="請輸入" />
+ *   </FormField>
+ * </Filter>
+ * ```
+ *
+ * @see {@link FilterLine} 包含 Filter 的行容器
+ * @see {@link FilterArea} 管理整個篩選器的容器
+ */
 const Filter = forwardRef(function Filter(props, ref) {
     var _a;
     const { align = 'stretch', children, className, grow = false, minWidth, span = 2, ...rest } = props;

package/FilterArea/FilterArea.d.ts

@@ -1,5 +1,5 @@
 import { ComponentPropsWithoutRef, ReactElement } from 'react';
-import { FilterAreaActionsAlign, FilterAreaSize } from '@mezzanine-ui/core/filter-area';
+import { FilterAreaActionsAlign, FilterAreaRowAlign, 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'> {
@@ -24,14 +24,14 @@ export interface FilterAreaProps extends Omit<NativeElementPropsWithoutKeyAndRef
      */
     onReset?: () => void;
     /**
-     * Callback function triggered when the form is submitted.
+     * Callback function triggered when the submit button is clicked.
      * 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.
+     * filter values and handle submission logic.
      */
     onSubmit?: () => void;
     /**
      * The text of the reset button.
+     * @default 'Reset'
      */
     resetText?: string;
     /**
@@ -41,6 +41,7 @@ export interface FilterAreaProps extends Omit<NativeElementPropsWithoutKeyAndRef
     size?: FilterAreaSize;
     /**
      * The text of the submit button.
+     * @default 'Search'
      */
     submitText?: string;
     /**
@@ -48,11 +49,49 @@ export interface FilterAreaProps extends Omit<NativeElementPropsWithoutKeyAndRef
      * @default 'button'
      */
     resetButtonType?: ComponentPropsWithoutRef<'button'>['type'];
+    /**
+     * The vertical alignment of the row (cross-axis align-items).
+     * @default 'center'
+     */
+    rowAlign?: FilterAreaRowAlign;
     /**
      * The type of the submit button.
      * @default 'button'
      */
     submitButtonType?: ComponentPropsWithoutRef<'button'>['type'];
 }
+/**
+ * 篩選器容器元件，管理多個 FilterLine 的展示與收合。
+ *
+ * 預設僅顯示第一行（`FilterLine`），多行時自動出現展開／收合切換按鈕。
+ * 透過 `size` 統一控制內部所有表單欄位的尺寸；
+ * 透過 `actionsAlign` 調整「送出／重設」按鈕區塊的對齊；
+ * 透過 `isDirty` 控制重設按鈕的啟用狀態（`false` 時禁用）。
+ *
+ * @example
+ * ```tsx
+ * import { Filter, FilterArea, FilterLine } from '@mezzanine-ui/react';
+ * import { FormField } from '@mezzanine-ui/react';
+ * import Input from '@mezzanine-ui/react/Input';
+ *
+ * <FilterArea
+ *   submitText="搜尋"
+ *   resetText="重設"
+ *   onSubmit={handleSubmit}
+ *   onReset={handleReset}
+ * >
+ *   <FilterLine>
+ *     <Filter span={2}>
+ *       <FormField label="名稱" name="name" layout="horizontal">
+ *         <Input placeholder="請輸入" />
+ *       </FormField>
+ *     </Filter>
+ *   </FilterLine>
+ * </FilterArea>
+ * ```
+ *
+ * @see {@link FilterLine} 用於組成 FilterArea 的單行條件列
+ * @see {@link Filter} 包裝單一篩選欄位的元件
+ */
 declare const FilterArea: import("react").ForwardRefExoticComponent<FilterAreaProps & import("react").RefAttributes<HTMLDivElement>>;
 export default FilterArea;

package/FilterArea/FilterArea.js

@@ -7,8 +7,41 @@ import Button from '../Button/Button.js';
 import FilterAreaContext from './FilterAreaContext.js';
 import cx from 'clsx';
 
+/**
+ * 篩選器容器元件，管理多個 FilterLine 的展示與收合。
+ *
+ * 預設僅顯示第一行（`FilterLine`），多行時自動出現展開／收合切換按鈕。
+ * 透過 `size` 統一控制內部所有表單欄位的尺寸；
+ * 透過 `actionsAlign` 調整「送出／重設」按鈕區塊的對齊；
+ * 透過 `isDirty` 控制重設按鈕的啟用狀態（`false` 時禁用）。
+ *
+ * @example
+ * ```tsx
+ * import { Filter, FilterArea, FilterLine } from '@mezzanine-ui/react';
+ * import { FormField } from '@mezzanine-ui/react';
+ * import Input from '@mezzanine-ui/react/Input';
+ *
+ * <FilterArea
+ *   submitText="搜尋"
+ *   resetText="重設"
+ *   onSubmit={handleSubmit}
+ *   onReset={handleReset}
+ * >
+ *   <FilterLine>
+ *     <Filter span={2}>
+ *       <FormField label="名稱" name="name" layout="horizontal">
+ *         <Input placeholder="請輸入" />
+ *       </FormField>
+ *     </Filter>
+ *   </FilterLine>
+ * </FilterArea>
+ * ```
+ *
+ * @see {@link FilterLine} 用於組成 FilterArea 的單行條件列
+ * @see {@link Filter} 包裝單一篩選欄位的元件
+ */
 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 { actionsAlign = 'end', children, className, isDirty = true, onReset, onSubmit, resetText = 'Reset', rowAlign = 'center', size = 'main', submitText = 'Search', resetButtonType = 'button', submitButtonType = 'button', ...rest } = props;
     const filterLines = useMemo(() => Children.toArray(children), [children]);
     const contextValue = useMemo(() => ({ size }), [size]);
     const hasMultipleLines = filterLines.length > 1;
@@ -27,7 +60,7 @@ const FilterArea = forwardRef(function FilterArea(props, ref) {
     const firstLine = filterLines[0];
     return (jsx(FilterAreaContext.Provider, { value: contextValue, children: jsx("div", { ...rest, ref: ref, className: cx(filterAreaClasses.host, className, {
                 [filterAreaClasses.size(size)]: size,
-            }), children: expanded ? (jsxs(Fragment, { children: [filterLines, jsx("div", { className: filterAreaClasses.row, children: renderAction() })] })) : (jsx(Fragment, { children: firstLine && (jsxs("div", { className: filterAreaClasses.row, children: [firstLine, renderAction()] })) })) }) }));
+            }), children: expanded ? (jsxs(Fragment, { children: [filterLines, jsx("div", { className: cx(filterAreaClasses.row, filterAreaClasses.rowAlign(rowAlign)), children: renderAction() })] })) : (jsx(Fragment, { children: firstLine && (jsxs("div", { className: cx(filterAreaClasses.row, filterAreaClasses.rowAlign(rowAlign)), children: [firstLine, renderAction()] })) })) }) }));
 });
 
 export { FilterArea as default };