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

package/Drawer/Drawer.js

@@ -1,19 +1,61 @@
 import { jsx, jsxs } from 'react/jsx-runtime';
-import { forwardRef, useState, useEffect, useMemo } from 'react';
 import { drawerClasses } from '@mezzanine-ui/core/drawer';
-import { useDocumentEscapeKeyDown } from '../hooks/useDocumentEscapeKeyDown.js';
-import useTopStack from '../hooks/useTopStack.js';
-import ClearActions from '../ClearActions/ClearActions.js';
+import { DotHorizontalIcon } from '@mezzanine-ui/icons';
+import { MOTION_EASING, MOTION_DURATION } from '@mezzanine-ui/system/motion';
+import { forwardRef, useState, useEffect, useMemo } from 'react';
 import Button from '../Button/Button.js';
+import ClearActions from '../ClearActions/ClearActions.js';
 import Radio from '../Radio/Radio.js';
 import RadioGroup from '../Radio/RadioGroup.js';
-import { MOTION_EASING, MOTION_DURATION } from '@mezzanine-ui/system/motion';
+import { useDocumentEscapeKeyDown } from '../hooks/useDocumentEscapeKeyDown.js';
+import useTopStack from '../hooks/useTopStack.js';
+import Dropdown from '../Dropdown/Dropdown.js';
 import Backdrop from '../Backdrop/Backdrop.js';
 import Slide from '../Transition/Slide.js';
 import cx from 'clsx';
 
+/**
+ * 從螢幕右側滑入的抽屜面板元件。
+ *
+ * 使用 `Backdrop` 作為遮罩層，並以 `Slide` 動畫過渡效果呈現開關狀態。
+ * 支援標題列、篩選區域（含分頁 Radio）、底部操作按鈕區域，以及按下 Escape 鍵關閉。
+ * 當多個 Drawer 同時開啟時，Escape 鍵只會關閉最上層的 Drawer。
+ *
+ * @example
+ * ```tsx
+ * import Drawer from '@mezzanine-ui/react/Drawer';
+ *
+ * // 基本用法
+ * <Drawer open={open} onClose={() => setOpen(false)} isHeaderDisplay headerTitle="詳細資料">
+ *   <p>抽屜內容</p>
+ * </Drawer>
+ *
+ * // 帶有底部操作按鈕
+ * <Drawer
+ *   open={open}
+ *   onClose={() => setOpen(false)}
+ *   isHeaderDisplay
+ *   headerTitle="編輯"
+ *   isBottomDisplay
+ *   bottomPrimaryActionText="確認"
+ *   bottomOnPrimaryActionClick={handleSubmit}
+ *   bottomSecondaryActionText="取消"
+ *   bottomOnSecondaryActionClick={() => setOpen(false)}
+ * >
+ *   <form>表單內容</form>
+ * </Drawer>
+ *
+ * // 使用 contentKey 強制重新掛載內容
+ * <Drawer open={open} onClose={() => setOpen(false)} contentKey={recordId}>
+ *   <RecordDetail id={recordId} />
+ * </Drawer>
+ * ```
+ *
+ * @see {@link Modal} 對話框元件
+ * @see {@link Backdrop} 遮罩層元件
+ */
 const Drawer = forwardRef((props, ref) => {
-    const { bottomGhostActionDisabled, bottomGhostActionIcon, bottomGhostActionIconType, bottomGhostActionLoading, bottomGhostActionSize, bottomGhostActionText, bottomGhostActionVariant = 'base-ghost', bottomOnGhostActionClick, bottomOnPrimaryActionClick, bottomOnSecondaryActionClick, bottomPrimaryActionDisabled, bottomPrimaryActionIcon, bottomPrimaryActionIconType, bottomPrimaryActionLoading, bottomPrimaryActionSize, bottomPrimaryActionText, bottomPrimaryActionVariant = 'base-primary', bottomSecondaryActionDisabled, bottomSecondaryActionIcon, bottomSecondaryActionIconType, bottomSecondaryActionLoading, bottomSecondaryActionSize, bottomSecondaryActionText, bottomSecondaryActionVariant = 'base-secondary', children, className, container, contentKey, controlBarAllRadioLabel, controlBarCustomButtonLabel = '全部已讀', controlBarDefaultValue, controlBarIsEmpty = false, controlBarOnCustomButtonClick, controlBarOnRadioChange, controlBarReadRadioLabel, controlBarShow = false, controlBarShowUnreadButton = false, controlBarUnreadRadioLabel, controlBarValue, disableCloseOnBackdropClick = false, disableCloseOnEscapeKeyDown = false, disablePortal, headerTitle, isBottomDisplay, isHeaderDisplay, onBackdropClick, onClose, open, renderControlBar: customRenderControlBar, size = 'medium', ...rest } = props;
+    const { bottomGhostActionDisabled, bottomGhostActionIcon, bottomGhostActionIconType, bottomGhostActionLoading, bottomGhostActionSize, bottomGhostActionText, bottomGhostActionVariant = 'base-ghost', bottomOnGhostActionClick, bottomOnPrimaryActionClick, bottomOnSecondaryActionClick, bottomPrimaryActionDisabled, bottomPrimaryActionIcon, bottomPrimaryActionIconType, bottomPrimaryActionLoading, bottomPrimaryActionSize, bottomPrimaryActionText, bottomPrimaryActionVariant = 'base-primary', bottomSecondaryActionDisabled, bottomSecondaryActionIcon, bottomSecondaryActionIconType, bottomSecondaryActionLoading, bottomSecondaryActionSize, bottomSecondaryActionText, bottomSecondaryActionVariant = 'base-secondary', filterAreaOnSelect, filterAreaOptions = [], children, className, container, contentKey, filterAreaAllRadioLabel, filterAreaCustomButtonLabel = '全部已讀', filterAreaDefaultValue, filterAreaIsEmpty = false, filterAreaOnCustomButtonClick, filterAreaOnRadioChange, filterAreaReadRadioLabel, filterAreaShow = false, filterAreaShowUnreadButton = false, filterAreaUnreadRadioLabel, filterAreaValue, disableCloseOnBackdropClick = false, disableCloseOnEscapeKeyDown = false, disablePortal, headerTitle, isBottomDisplay, isHeaderDisplay, onBackdropClick, onClose, open, size = 'medium', ...rest } = props;
     const [exited, setExited] = useState(true);
     const [openCount, setOpenCount] = useState(0);
     // Track open state changes to auto-remount content when drawer reopens
@@ -27,47 +69,43 @@ const Drawer = forwardRef((props, ref) => {
      * Escape keydown close: escape will only close the top drawer
      */
     const checkIsOnTheTop = useTopStack(open);
-    const renderControlBar = useMemo(() => {
-        // If custom renderControlBar is provided, use it
-        if (customRenderControlBar) {
-            return customRenderControlBar;
-        }
-        // Default control bar implementation
-        if (!controlBarShow) {
+    const renderFilterArea = useMemo(() => {
+        if (!filterAreaShow) {
             return undefined;
         }
         return () => {
             const radios = [];
-            if (controlBarAllRadioLabel) {
-                radios.push(jsx(Radio, { type: "segment", value: "all", children: controlBarAllRadioLabel }, "all"));
+            if (filterAreaAllRadioLabel) {
+                radios.push(jsx(Radio, { type: "segment", value: "all", children: filterAreaAllRadioLabel }, "all"));
             }
-            if (controlBarReadRadioLabel) {
-                radios.push(jsx(Radio, { type: "segment", value: "read", children: controlBarReadRadioLabel }, "read"));
+            if (filterAreaReadRadioLabel) {
+                radios.push(jsx(Radio, { type: "segment", value: "read", children: filterAreaReadRadioLabel }, "read"));
             }
-            if (controlBarUnreadRadioLabel && controlBarShowUnreadButton) {
-                radios.push(jsx(Radio, { type: "segment", value: "unread", children: controlBarUnreadRadioLabel }, "unread"));
+            if (filterAreaUnreadRadioLabel && filterAreaShowUnreadButton) {
+                radios.push(jsx(Radio, { type: "segment", value: "unread", children: filterAreaUnreadRadioLabel }, "unread"));
             }
             const hasRadios = radios.length > 0;
-            const hasButton = controlBarOnCustomButtonClick !== undefined;
+            const hasButton = filterAreaOptions.length > 0 || filterAreaOnCustomButtonClick !== undefined;
             // Don't render if neither radios nor button are provided
             if (!hasRadios && !hasButton) {
                 return null;
             }
-            return (jsxs("div", { className: cx(drawerClasses.controlBar, !hasRadios && hasButton && drawerClasses.controlBarButtonOnly), children: [hasRadios && (jsx(RadioGroup, { defaultValue: controlBarDefaultValue !== null && controlBarDefaultValue !== void 0 ? controlBarDefaultValue : 'all', onChange: controlBarOnRadioChange, size: "minor", type: "segment", value: controlBarValue, children: radios })), hasButton && (jsx(Button, { disabled: controlBarIsEmpty, onClick: controlBarOnCustomButtonClick, size: "minor", type: "button", variant: "base-ghost", children: controlBarCustomButtonLabel }))] }));
+            return (jsxs("div", { className: cx(drawerClasses.filterArea, !hasRadios && hasButton && drawerClasses.filterAreaButtonOnly), children: [hasRadios && (jsx(RadioGroup, { defaultValue: filterAreaDefaultValue !== null && filterAreaDefaultValue !== void 0 ? filterAreaDefaultValue : 'all', onChange: filterAreaOnRadioChange, size: "minor", type: "segment", value: filterAreaValue, children: radios })), hasButton && (filterAreaOptions.length > 0 ? (jsx(Dropdown, { onSelect: filterAreaOnSelect, options: filterAreaOptions, placement: "bottom-end", children: jsx(Button, { icon: DotHorizontalIcon, iconType: "icon-only", size: "minor", type: "button", variant: "base-ghost" }) })) : (jsx(Button, { disabled: filterAreaIsEmpty, onClick: filterAreaOnCustomButtonClick, size: "minor", type: "button", variant: "base-ghost", children: filterAreaCustomButtonLabel })))] }));
         };
     }, [
-        controlBarAllRadioLabel,
-        controlBarCustomButtonLabel,
-        controlBarDefaultValue,
-        controlBarIsEmpty,
-        controlBarOnCustomButtonClick,
-        controlBarOnRadioChange,
-        controlBarReadRadioLabel,
-        controlBarShow,
-        controlBarShowUnreadButton,
-        controlBarUnreadRadioLabel,
-        controlBarValue,
-        customRenderControlBar,
+        filterAreaAllRadioLabel,
+        filterAreaCustomButtonLabel,
+        filterAreaDefaultValue,
+        filterAreaIsEmpty,
+        filterAreaOnCustomButtonClick,
+        filterAreaOnRadioChange,
+        filterAreaReadRadioLabel,
+        filterAreaShow,
+        filterAreaShowUnreadButton,
+        filterAreaUnreadRadioLabel,
+        filterAreaValue,
+        filterAreaOnSelect,
+        filterAreaOptions,
     ]);
     useDocumentEscapeKeyDown(() => {
         if (!open || disableCloseOnEscapeKeyDown || !onClose) {
@@ -89,7 +127,7 @@ const Drawer = forwardRef((props, ref) => {
             }, easing: {
                 enter: MOTION_EASING.entrance,
                 exit: MOTION_EASING.exit,
-            }, in: open, onEntered: () => setExited(false), onExited: () => setExited(true), ref: ref, children: jsxs("div", { ...rest, className: cx(drawerClasses.host, drawerClasses.right, drawerClasses.size(size), className), children: [isHeaderDisplay && (jsxs("div", { className: drawerClasses.header, children: [headerTitle, jsx(ClearActions, { onClick: onClose })] })), renderControlBar === null || renderControlBar === void 0 ? void 0 : renderControlBar(), jsx("div", { className: drawerClasses.content, children: children }, contentKey !== undefined ? contentKey : openCount), isBottomDisplay && (jsxs("div", { className: drawerClasses.bottom, children: [jsx("div", { children: bottomGhostActionText && bottomOnGhostActionClick && (jsx(Button, { disabled: bottomGhostActionDisabled, icon: bottomGhostActionIcon, iconType: bottomGhostActionIconType, loading: bottomGhostActionLoading, onClick: bottomOnGhostActionClick, size: bottomGhostActionSize, type: "button", variant: bottomGhostActionVariant, children: bottomGhostActionText })) }), jsxs("div", { className: drawerClasses['bottom__actions'], children: [bottomSecondaryActionText && bottomOnSecondaryActionClick && (jsx(Button, { disabled: bottomSecondaryActionDisabled, icon: bottomSecondaryActionIcon, iconType: bottomSecondaryActionIconType, loading: bottomSecondaryActionLoading, onClick: bottomOnSecondaryActionClick, size: bottomSecondaryActionSize, type: "button", variant: bottomSecondaryActionVariant, children: bottomSecondaryActionText })), bottomPrimaryActionText && bottomOnPrimaryActionClick && (jsx(Button, { disabled: bottomPrimaryActionDisabled, icon: bottomPrimaryActionIcon, iconType: bottomPrimaryActionIconType, loading: bottomPrimaryActionLoading, onClick: bottomOnPrimaryActionClick, size: bottomPrimaryActionSize, type: "button", variant: bottomPrimaryActionVariant, children: bottomPrimaryActionText }))] })] }))] }) }) }));
+            }, in: open, onEntered: () => setExited(false), onExited: () => setExited(true), ref: ref, children: jsxs("div", { ...rest, className: cx(drawerClasses.host, drawerClasses.right, drawerClasses.size(size), className), children: [isHeaderDisplay && (jsxs("div", { className: drawerClasses.header, children: [headerTitle, jsx(ClearActions, { onClick: onClose })] })), renderFilterArea === null || renderFilterArea === void 0 ? void 0 : renderFilterArea(), jsx("div", { className: drawerClasses.content, children: children }, contentKey !== undefined ? contentKey : openCount), isBottomDisplay && (jsxs("div", { className: drawerClasses.bottom, children: [jsx("div", { children: bottomGhostActionText && bottomOnGhostActionClick && (jsx(Button, { disabled: bottomGhostActionDisabled, icon: bottomGhostActionIcon, iconType: bottomGhostActionIconType, loading: bottomGhostActionLoading, onClick: bottomOnGhostActionClick, size: bottomGhostActionSize, type: "button", variant: bottomGhostActionVariant, children: bottomGhostActionText })) }), jsxs("div", { className: drawerClasses['bottom__actions'], children: [bottomSecondaryActionText && bottomOnSecondaryActionClick && (jsx(Button, { disabled: bottomSecondaryActionDisabled, icon: bottomSecondaryActionIcon, iconType: bottomSecondaryActionIconType, loading: bottomSecondaryActionLoading, onClick: bottomOnSecondaryActionClick, size: bottomSecondaryActionSize, type: "button", variant: bottomSecondaryActionVariant, children: bottomSecondaryActionText })), bottomPrimaryActionText && bottomOnPrimaryActionClick && (jsx(Button, { disabled: bottomPrimaryActionDisabled, icon: bottomPrimaryActionIcon, iconType: bottomPrimaryActionIconType, loading: bottomPrimaryActionLoading, onClick: bottomOnPrimaryActionClick, size: bottomPrimaryActionSize, type: "button", variant: bottomPrimaryActionVariant, children: bottomPrimaryActionText }))] })] }))] }) }) }));
 });
 
 export { Drawer as default };

package/Dropdown/Dropdown.d.ts

@@ -26,9 +26,17 @@ export interface DropdownProps extends DropdownItemSharedProps {
      */
     actionText?: string;
     /**
-     * The active option index for hover/focus state.
+     * The active option index for hover/focus state and Enter selection.
+     * Can be set by both keyboard navigation and mouse hover (e.g. in AutoComplete).
      */
     activeIndex?: number | null;
+    /**
+     * The keyboard-only active index.
+     * When provided, only this index triggers the focus ring (`--keyboard-active` CSS class).
+     * Mouse hover updates `activeIndex` for Enter selection but should not update this.
+     * When omitted, falls back to the internal uncontrolled index (set only by built-in keyboard navigation).
+     */
+    keyboardActiveIndex?: number | null;
     /**
      * The children of the dropdown.
      * This can be a button or an input.
@@ -70,6 +78,13 @@ export interface DropdownProps extends DropdownItemSharedProps {
      * The max height of the dropdown list.
      */
     maxHeight?: number | string;
+    /**
+     * Override the default `min-width` of the dropdown list.
+     * Accepts a number (pixels) or any valid CSS length string.
+     * Pass `0` to remove the minimum width constraint entirely — useful when `sameWidth` controls the width.
+     * @default spacing token `size-container-tiny`
+     */
+    minWidth?: number | string;
     /**
      * Whether the dropdown is open (controlled).
      */
@@ -222,4 +237,51 @@ export interface DropdownProps extends DropdownItemSharedProps {
      */
     scrollbarOptions?: import('overlayscrollbars').PartialOptions;
 }
+/**
+ * 下拉選單元件，以 `Button` 或 `Input` 作為觸發元素，點擊後展開選項列表。
+ *
+ * 支援受控（`open`）與非受控兩種開關模式，可透過 `type` 切換單選或多選行為，
+ * 並透過 `inputPosition` 選擇彈出（outside）或內嵌（inside）的輸入框位置。
+ * 可搭配 `showDropdownActions` 顯示確認／取消操作列，以及 `status` 設定
+ * 載入中或空狀態的顯示內容。
+ *
+ * @example
+ * ```tsx
+ * import Dropdown from '@mezzanine-ui/react/Dropdown';
+ * import Button from '@mezzanine-ui/react/Button';
+ * import Input from '@mezzanine-ui/react/Input';
+ *
+ * // 以 Button 為觸發元素
+ * <Dropdown
+ *   options={[{ label: '選項一', value: '1' }, { label: '選項二', value: '2' }]}
+ *   onSelect={(option) => console.log(option)}
+ * >
+ *   <Button>請選擇</Button>
+ * </Dropdown>
+ *
+ * // 以 Input 為觸發元素，同寬展開
+ * <Dropdown
+ *   options={[{ label: '台北', value: 'tpe' }, { label: '台中', value: 'txg' }]}
+ *   sameWidth
+ *   onSelect={(opt) => setValue(opt.value)}
+ * >
+ *   <Input placeholder="搜尋城市" />
+ * </Dropdown>
+ *
+ * // 多選模式搭配操作列
+ * <Dropdown
+ *   type="multiple"
+ *   options={options}
+ *   showDropdownActions
+ *   actionConfirmText="確認"
+ *   actionCancelText="取消"
+ *   onActionConfirm={handleConfirm}
+ * >
+ *   <Button>多選</Button>
+ * </Dropdown>
+ * ```
+ *
+ * @see {@link Select} 封裝好選取邏輯的選擇器元件
+ * @see {@link AutoComplete} 具備自動補全功能的輸入元件
+ */
 export default function Dropdown(props: DropdownProps): import("react/jsx-runtime").JSX.Element;

package/Dropdown/Dropdown.js

@@ -24,8 +24,55 @@ function getElementRef(element) {
     // React 18: ref is on the element itself
     return propsRef !== null && propsRef !== void 0 ? propsRef : element.ref;
 }
+/**
+ * 下拉選單元件，以 `Button` 或 `Input` 作為觸發元素，點擊後展開選項列表。
+ *
+ * 支援受控（`open`）與非受控兩種開關模式，可透過 `type` 切換單選或多選行為，
+ * 並透過 `inputPosition` 選擇彈出（outside）或內嵌（inside）的輸入框位置。
+ * 可搭配 `showDropdownActions` 顯示確認／取消操作列，以及 `status` 設定
+ * 載入中或空狀態的顯示內容。
+ *
+ * @example
+ * ```tsx
+ * import Dropdown from '@mezzanine-ui/react/Dropdown';
+ * import Button from '@mezzanine-ui/react/Button';
+ * import Input from '@mezzanine-ui/react/Input';
+ *
+ * // 以 Button 為觸發元素
+ * <Dropdown
+ *   options={[{ label: '選項一', value: '1' }, { label: '選項二', value: '2' }]}
+ *   onSelect={(option) => console.log(option)}
+ * >
+ *   <Button>請選擇</Button>
+ * </Dropdown>
+ *
+ * // 以 Input 為觸發元素，同寬展開
+ * <Dropdown
+ *   options={[{ label: '台北', value: 'tpe' }, { label: '台中', value: 'txg' }]}
+ *   sameWidth
+ *   onSelect={(opt) => setValue(opt.value)}
+ * >
+ *   <Input placeholder="搜尋城市" />
+ * </Dropdown>
+ *
+ * // 多選模式搭配操作列
+ * <Dropdown
+ *   type="multiple"
+ *   options={options}
+ *   showDropdownActions
+ *   actionConfirmText="確認"
+ *   actionCancelText="取消"
+ *   onActionConfirm={handleConfirm}
+ * >
+ *   <Button>多選</Button>
+ * </Dropdown>
+ * ```
+ *
+ * @see {@link Select} 封裝好選取邏輯的選擇器元件
+ * @see {@link AutoComplete} 具備自動補全功能的輸入元件
+ */
 function Dropdown(props) {
-    const { activeIndex: activeIndexProp, id, children, options = [], type = 'default', toggleCheckedOnClick, maxHeight, disabled = false, showDropdownActions = false, actionCancelText, actionConfirmText, actionText, actionClearText, actionCustomButtonProps, showActionShowTopBar, isMatchInputValue = false, inputPosition = 'outside', placement = 'bottom-start', customWidth, sameWidth = false, listboxId: listboxIdProp, listboxLabel, onClose, onOpen, open: openProp, onVisibilityChange, onSelect, onActionConfirm, onActionCancel, onActionCustom, onActionClear, onItemHover, zIndex, status, loadingText, emptyText, emptyIcon, loadingPosition = 'full', followText: followTextProp, globalPortal = true, onReachBottom, onLeaveBottom, onScroll, mode, value, scrollbarDefer, scrollbarDisabled, scrollbarMaxWidth, scrollbarOptions, } = props;
+    const { activeIndex: activeIndexProp, keyboardActiveIndex: keyboardActiveIndexProp, id, children, options = [], type = 'default', toggleCheckedOnClick, maxHeight, minWidth, disabled = false, showDropdownActions = false, actionCancelText, actionConfirmText, actionText, actionClearText, actionCustomButtonProps, showActionShowTopBar, isMatchInputValue = false, inputPosition = 'outside', placement = 'bottom-start', customWidth, sameWidth = false, listboxId: listboxIdProp, listboxLabel, onClose, onOpen, open: openProp, onVisibilityChange, onSelect, onActionConfirm, onActionCancel, onActionCustom, onActionClear, onItemHover, zIndex, status, loadingText, emptyText, emptyIcon, loadingPosition = 'full', followText: followTextProp, globalPortal = true, onReachBottom, onLeaveBottom, onScroll, mode, value, scrollbarDefer, scrollbarDisabled, scrollbarMaxWidth, scrollbarOptions, } = props;
     const isInline = inputPosition === 'inside';
     const inputId = useId();
     const defaultListboxId = `${inputId}-listbox`;
@@ -60,14 +107,49 @@ function Dropdown(props) {
     const [uncontrolledOpen, setUncontrolledOpen] = useState(false);
     const isOpenControlled = openProp !== undefined;
     const isOpen = isOpenControlled ? !!openProp : uncontrolledOpen;
-    // Keep setter for uncontrolled mode support (e.g., keyboard navigation)
-    // Currently not used in handleItemHover to prevent style conflicts
-    const [uncontrolledActiveIndex, _setUncontrolledActiveIndex] = useState(activeIndexProp !== null && activeIndexProp !== void 0 ? activeIndexProp : null);
+    const [uncontrolledActiveIndex, setUncontrolledActiveIndex] = useState(activeIndexProp !== null && activeIndexProp !== void 0 ? activeIndexProp : null);
     const isActiveIndexControlled = activeIndexProp !== undefined;
     const mergedActiveIndex = isActiveIndexControlled
         ? activeIndexProp
         : uncontrolledActiveIndex;
+    // For keyboard-only visual focus (focus ring). When not externally controlled,
+    // `uncontrolledActiveIndex` is already set only by keyboard (never by hover).
+    const mergedKeyboardActiveIndex = keyboardActiveIndexProp !== undefined
+        ? keyboardActiveIndexProp
+        : uncontrolledActiveIndex;
     const containerRef = useRef(null);
+    // Expansion state for tree type (lifted here so keyboard nav can track visible options)
+    const [expandedNodes, setExpandedNodes] = useState(new Set());
+    const handleToggleExpand = useCallback((optionId) => {
+        setExpandedNodes((prev) => {
+            const next = new Set(prev);
+            if (next.has(optionId)) {
+                next.delete(optionId);
+            }
+            else {
+                next.add(optionId);
+            }
+            return next;
+        });
+    }, []);
+    // Flat list of navigable options, respecting tree expansion state
+    const flatNavigableOptions = useMemo(() => {
+        const opts = options;
+        if (type === 'grouped') {
+            return opts.flatMap((g) => { var _a; return (_a = g.children) !== null && _a !== void 0 ? _a : []; });
+        }
+        if (type === 'tree') {
+            const flatten = (items) => items.flatMap((item) => {
+                var _a;
+                if (((_a = item.children) === null || _a === void 0 ? void 0 : _a.length) && expandedNodes.has(item.id)) {
+                    return [item, ...flatten(item.children)];
+                }
+                return [item];
+            });
+            return flatten(opts);
+        }
+        return opts;
+    }, [options, type, expandedNodes]);
     const ariaActivedescendant = useMemo(() => {
         if (mergedActiveIndex !== null && mergedActiveIndex >= 0) {
             return `${listboxId}-option-${mergedActiveIndex}`;
@@ -190,10 +272,16 @@ function Dropdown(props) {
     const popperControllerRef = useRef(null);
     // Extract combobox props logic to avoid duplication
     const getComboboxProps = useMemo(() => {
-        // Only access the type property to check if it's a Button component
         const isInput = children.type !== Button;
-        if (!isInput)
-            return {};
+        if (!isInput) {
+            // Button trigger: expose listbox ARIA so screen readers can navigate
+            return {
+                'aria-haspopup': 'listbox',
+                'aria-expanded': isOpen,
+                'aria-controls': listboxId,
+                'aria-activedescendant': ariaActivedescendant,
+            };
+        }
         return {
             role: 'combobox',
             'aria-controls': listboxId,
@@ -206,18 +294,99 @@ function Dropdown(props) {
     const handleItemHover = useCallback((index) => {
         onItemHover === null || onItemHover === void 0 ? void 0 : onItemHover(index);
     }, [onItemHover]);
+    // Reset active index when dropdown closes (uncontrolled only)
+    useEffect(() => {
+        if (!isOpen && !isActiveIndexControlled) {
+            setUncontrolledActiveIndex(null);
+        }
+    }, [isOpen, isActiveIndexControlled]);
+    // Scroll the active option into view whenever activeIndex changes
+    useEffect(() => {
+        if (!isOpen || mergedActiveIndex === null)
+            return;
+        requestAnimationFrame(() => {
+            var _a;
+            (_a = document
+                .getElementById(`${listboxId}-option-${mergedActiveIndex}`)) === null || _a === void 0 ? void 0 : _a.scrollIntoView({ block: 'nearest' });
+        });
+    }, [mergedActiveIndex, isOpen, listboxId]);
+    // Built-in keyboard navigation (only when activeIndex is not controlled externally)
+    const handleBuiltinKeyDown = useCallback((event) => {
+        var _a;
+        if (isActiveIndexControlled)
+            return;
+        const count = flatNavigableOptions.length;
+        if (!isOpen) {
+            if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+                event.preventDefault();
+                setOpen(true);
+            }
+            return;
+        }
+        if (count === 0)
+            return;
+        switch (event.key) {
+            case 'ArrowDown': {
+                event.preventDefault();
+                setUncontrolledActiveIndex((prev) => prev === null ? 0 : (prev + 1) % count);
+                break;
+            }
+            case 'ArrowUp': {
+                event.preventDefault();
+                setUncontrolledActiveIndex((prev) => prev === null ? count - 1 : (prev - 1 + count) % count);
+                break;
+            }
+            case 'Enter': {
+                if (mergedActiveIndex !== null && mergedActiveIndex >= 0) {
+                    const activeOption = flatNavigableOptions[mergedActiveIndex];
+                    if (activeOption) {
+                        event.preventDefault();
+                        if (type === 'tree' && ((_a = activeOption.children) === null || _a === void 0 ? void 0 : _a.length)) {
+                            handleToggleExpand(activeOption.id);
+                        }
+                        else {
+                            onSelect === null || onSelect === void 0 ? void 0 : onSelect(activeOption);
+                            if (mode !== 'multiple') {
+                                setOpen(false);
+                            }
+                        }
+                    }
+                }
+                break;
+            }
+            case 'Escape': {
+                event.preventDefault();
+                setOpen(false);
+                break;
+            }
+        }
+    }, [
+        isActiveIndexControlled,
+        isOpen,
+        flatNavigableOptions,
+        mergedActiveIndex,
+        type,
+        mode,
+        handleToggleExpand,
+        onSelect,
+        setOpen,
+    ]);
     // Extract shared DropdownItem props to avoid duplication
     const baseDropdownItemProps = useMemo(() => ({
         actionConfig,
         activeIndex: mergedActiveIndex,
+        keyboardActiveIndex: mergedKeyboardActiveIndex,
         disabled,
+        expandedNodes,
         followText,
         listboxId,
         listboxLabel,
         maxHeight,
+        minWidth,
         sameWidth,
         onHover: handleItemHover,
         onSelect,
+        onToggleExpand: handleToggleExpand,
         onReachBottom,
         onLeaveBottom,
         onScroll,
@@ -238,13 +407,17 @@ function Dropdown(props) {
     }), [
         actionConfig,
         mergedActiveIndex,
+        mergedKeyboardActiveIndex,
         disabled,
         followText,
         listboxId,
         listboxLabel,
         maxHeight,
+        minWidth,
         sameWidth,
         handleItemHover,
+        handleToggleExpand,
+        expandedNodes,
         onSelect,
         onReachBottom,
         onLeaveBottom,
@@ -270,6 +443,7 @@ function Dropdown(props) {
         const childRef = getElementRef(childWithRef);
         const composedRef = composeRefs([anchorRef, childRef]);
         const originalOnClick = childProps.onClick;
+        const originalOnKeyDown = childProps.onKeyDown;
         return cloneElement(childWithRef, {
             ref: composedRef,
             ...getComboboxProps,
@@ -281,8 +455,14 @@ function Dropdown(props) {
                     setOpen((prev) => !prev);
                 }
             },
+            onKeyDown: (event) => {
+                originalOnKeyDown === null || originalOnKeyDown === void 0 ? void 0 : originalOnKeyDown(event);
+                if (event === null || event === void 0 ? void 0 : event.defaultPrevented)
+                    return;
+                handleBuiltinKeyDown(event);
+            },
         });
-    }, [children, getComboboxProps, isInline, setOpen]);
+    }, [children, getComboboxProps, handleBuiltinKeyDown, isInline, setOpen]);
     const inlineTriggerElement = useMemo(() => {
         if (!isInline) {
             return null;
@@ -294,6 +474,7 @@ function Dropdown(props) {
         const originalOnBlur = childProps.onBlur;
         const originalOnClick = childProps.onClick;
         const originalOnFocus = childProps.onFocus;
+        const originalOnKeyDown = childProps.onKeyDown;
         return cloneElement(childWithRef, {
             ref: composedRef,
             ...getComboboxProps,
@@ -327,8 +508,21 @@ function Dropdown(props) {
                     return;
                 setOpen(true);
             },
+            onKeyDown: (event) => {
+                originalOnKeyDown === null || originalOnKeyDown === void 0 ? void 0 : originalOnKeyDown(event);
+                if (event === null || event === void 0 ? void 0 : event.defaultPrevented)
+                    return;
+                handleBuiltinKeyDown(event);
+            },
         });
-    }, [children, getComboboxProps, isInline, isOpenControlled, setOpen]);
+    }, [
+        children,
+        getComboboxProps,
+        handleBuiltinKeyDown,
+        isInline,
+        isOpenControlled,
+        setOpen,
+    ]);
     useDocumentEvents(() => {
         if (!isOpen) {
             return;

package/Dropdown/DropdownItem.d.ts

@@ -9,9 +9,26 @@ export interface DropdownItemProps<T extends DropdownType | undefined = Dropdown
      */
     actionConfig?: DropdownActionProps;
     /**
-     * The active option index for hover/focus state.
+     * The active option index for hover/focus state and Enter selection.
      */
     activeIndex: number | null;
+    /**
+     * Keyboard-only active index. When provided, only this index applies the
+     * focus ring (`--keyboard-active`) and active background via `DropdownItemCard`'s `active` prop.
+     * Mouse hover should update `activeIndex` (for Enter selection) but NOT this value.
+     * Falls back to `activeIndex` when not provided (backward-compatible).
+     */
+    keyboardActiveIndex?: number | null;
+    /**
+     * Controlled set of expanded node IDs for tree type.
+     * When provided, expansion state is managed externally.
+     */
+    expandedNodes?: Set<string>;
+    /**
+     * Callback to toggle the expansion of a tree node.
+     * Required when `expandedNodes` is provided.
+     */
+    onToggleExpand?: (id: string) => void;
     /**
      * The text to follow.
      */
@@ -33,6 +50,13 @@ export interface DropdownItemProps<T extends DropdownType | undefined = Dropdown
      * The max height of the dropdown list.
      */
     maxHeight?: number | string;
+    /**
+     * Override the default `min-width` of the dropdown list.
+     * Accepts a number (pixels) or any valid CSS length string.
+     * Pass `0` to remove the minimum width constraint entirely.
+     * @default spacing token `size-container-tiny`
+     */
+    minWidth?: number | string;
     /**
      * Whether to set the same width as its anchor element.
      * @default false
@@ -40,7 +64,7 @@ export interface DropdownItemProps<T extends DropdownType | undefined = Dropdown
     sameWidth?: boolean;
     /**
      * Callback when hovering option index changes.
-    */
+     */
     onHover?: (index: number) => void;
     /**
      * Options to render.