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

package/AutoComplete/AutoComplete.js

@@ -11,6 +11,7 @@ import { useAutoCompleteCreation, getFullParsedList } from './useAutoCompleteCre
 import { useAutoCompleteKeyboard } from './useAutoCompleteKeyboard.js';
 import { useAutoCompleteSearch } from './useAutoCompleteSearch.js';
 import { useCreationTracker } from './useCreationTracker.js';
+import AutoCompleteInsideTrigger from './AutoCompleteInside.js';
 import { FormControlContext } from '../Form/FormControlContext.js';
 import Dropdown from '../Dropdown/Dropdown.js';
 import cx from 'clsx';
@@ -30,9 +31,67 @@ function isSingleValue(value) {
     return value !== null && value !== undefined && !Array.isArray(value);
 }
 /**
- * The AutoComplete component for react. <br />
- * Note that if you need search for ONLY given options, not included your typings,
- * should considering using the `Select` component with `onSearch` prop.
+ * 自動完成輸入元件，在使用者輸入時即時顯示符合的下拉選項。
+ *
+ * 支援 `single`（單選）與 `multiple`（多選標籤）兩種模式；`inputPosition` 控制搜尋輸入框
+ * 位於下拉選單外（`'outside'`，預設）或內（`'inside'`）。設定 `addable` 與 `onInsert`
+ * 可讓使用者動態建立不在選項清單中的項目。`asyncData` 搭配 `onSearch` 可實現非同步搜尋，
+ * 輸入時觸發 debounce 查詢並顯示 loading 狀態。若僅需從固定選項中搜尋，請改用 `Select` 元件。
+ *
+ * @example
+ * ```tsx
+ * import AutoComplete from '@mezzanine-ui/react/AutoComplete';
+ *
+ * // 單選基本用法
+ * <AutoComplete
+ *   mode="single"
+ *   options={[{ id: '1', name: 'Apple' }, { id: '2', name: 'Banana' }]}
+ *   value={selected}
+ *   onChange={setSelected}
+ *   placeholder="請搜尋..."
+ * />
+ *
+ * // 多選模式
+ * <AutoComplete
+ *   mode="multiple"
+ *   options={options}
+ *   value={selectedList}
+ *   onChange={setSelectedList}
+ * />
+ *
+ * // 搜尋框置於下拉選單內（inside 模式）
+ * <AutoComplete
+ *   mode="multiple"
+ *   inputPosition="inside"
+ *   options={options}
+ *   value={selectedList}
+ *   onChange={setSelectedList}
+ * />
+ *
+ * // 非同步搜尋
+ * <AutoComplete
+ *   mode="single"
+ *   asyncData
+ *   options={asyncOptions}
+ *   onSearch={async (text) => { const res = await fetchOptions(text); setAsyncOptions(res); }}
+ *   value={selected}
+ *   onChange={setSelected}
+ * />
+ *
+ * // 可新增選項
+ * <AutoComplete
+ *   mode="multiple"
+ *   addable
+ *   options={options}
+ *   onInsert={(text, current) => [...current, { id: text, name: text }]}
+ *   value={selectedList}
+ *   onChange={setSelectedList}
+ * />
+ * ```
+ *
+ * @see {@link Select} 從固定選項清單中選取時使用
+ * @see {@link Input} 純文字輸入欄位
+ * @see {@link useAutoCompleteValueControl} 管理 AutoComplete 內部值狀態的 hook
  */
 const AutoComplete = forwardRef(function AutoComplete(props, ref) {
     const { disabled: disabledFromFormControl, fullWidth: fullWidthFromFormControl, required: requiredFromFormControl, severity, } = useContext(FormControlContext) || {};
@@ -60,7 +119,7 @@ const AutoComplete = forwardRef(function AutoComplete(props, ref) {
                 ? (st) => {
                     var _a;
                     const full = getFullParsedList(st, createSeparators, trimOnCreate);
-                    return full.length > 1 ? (_a = full[0]) !== null && _a !== void 0 ? _a : undefined : undefined;
+                    return full.length > 1 ? ((_a = full[0]) !== null && _a !== void 0 ? _a : undefined) : undefined;
                 }
                 : undefined,
             mode: 'multiple',
@@ -208,13 +267,22 @@ const AutoComplete = forwardRef(function AutoComplete(props, ref) {
             return;
         clearUnselected();
         onRemoveCreated(cleanedOptions);
-    }, [clearUnselected, creationEnabled, filterUnselected, onRemoveCreated, optionsProp]);
+    }, [
+        clearUnselected,
+        creationEnabled,
+        filterUnselected,
+        onRemoveCreated,
+        optionsProp,
+    ]);
     useEffect(() => () => {
         clearPendingOptionsReset();
     }, [clearPendingOptionsReset]);
     useEffect(() => {
         var _a;
-        if (!isMultiple)
+        // Multiple mode bridge only applies to SelectTrigger (tags) rendering.
+        // In `inputPosition="inside"` we render a plain Input trigger, so the hidden
+        // SelectTrigger input bridge is not needed.
+        if (!isMultiple || inputPosition === 'inside')
             return;
         const hiddenTriggerInput = (_a = nodeRef.current) === null || _a === void 0 ? void 0 : _a.querySelector(`.${selectClasses.triggerInput}`);
         if (!hiddenTriggerInput)
@@ -225,7 +293,7 @@ const AutoComplete = forwardRef(function AutoComplete(props, ref) {
             return;
         hiddenTriggerInput.value = bridgeValue;
         hiddenTriggerInput.dispatchEvent(new Event('change', { bubbles: true }));
-    }, [isMultiple, searchText, value]);
+    }, [inputPosition, isMultiple, searchText, value]);
     // 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(() => {
@@ -245,6 +313,27 @@ const AutoComplete = forwardRef(function AutoComplete(props, ref) {
         shouldClearSearchTextOnBlur,
         value,
     ]);
+    const insideInputValue = useMemo(() => {
+        // Inside trigger is a plain Input, so we must decide what to display.
+        // - multiple: always show current search text
+        // - single: show search text when focused (or when clear-on-blur is disabled)
+        if (isMultiple)
+            return searchText;
+        if (isSingle &&
+            (focused || (!shouldClearSearchTextOnBlur && !value && searchText))) {
+            return searchText;
+        }
+        if (isSingleValue(value))
+            return value.name;
+        return '';
+    }, [
+        focused,
+        isMultiple,
+        isSingle,
+        searchText,
+        shouldClearSearchTextOnBlur,
+        value,
+    ]);
     function getPlaceholder() {
         if (isSingle && focused && isSingleValue(value)) {
             return value.name;
@@ -276,8 +365,8 @@ const AutoComplete = forwardRef(function AutoComplete(props, ref) {
             e.stopPropagation();
         }
         // Only open if not already open to avoid flickering
-        // When inputPosition is inside, Dropdown will handle opening via inlineTriggerElement
-        if (inputPosition !== 'inside' && !open) {
+        // Ensure inside/uncontrolled can open from the native input focus.
+        if (!open) {
             toggleOpen(true);
         }
         onFocus(true);
@@ -337,12 +426,11 @@ const AutoComplete = forwardRef(function AutoComplete(props, ref) {
     const firstPendingText = hasStepByStepBulkSeparator
         ? getPendingCreateList(insertText)[0]
         : undefined;
-    const searchTextExistWithoutOption = !!((firstPendingText
+    const searchTextExistWithoutOption = !!(firstPendingText
         ? firstPendingText &&
-            options.find((option) => option.name === firstPendingText) ===
-                undefined
+            options.find((option) => option.name === firstPendingText) === undefined
         : searchText &&
-            options.find((option) => option.name === searchText) === undefined));
+            options.find((option) => option.name === searchText) === undefined);
     const shouldShowCreateAction = !!(searchTextExistWithoutOption &&
         creationEnabled &&
         (firstPendingText !== null && firstPendingText !== void 0 ? firstPendingText : insertText));
@@ -359,11 +447,13 @@ const AutoComplete = forwardRef(function AutoComplete(props, ref) {
                 id: option.id,
                 name: option.name,
             };
-            // Set checkSite based on mode
-            // Multiple mode: show checkbox at prepend
-            // Single mode: show checked icon at append when selected
+            // Set checkSite based on mode and input position.
+            // - inside + multiple: keep multiple behavior, but render single-like checked icon
+            //   at suffix to match product visual expectation.
+            // - outside + multiple: render checkbox at prefix.
+            // - single: render checked icon at suffix.
             if (mode === 'multiple') {
-                result.checkSite = 'prefix';
+                result.checkSite = inputPosition === 'inside' ? 'suffix' : 'prefix';
             }
             else {
                 result.checkSite = 'suffix';
@@ -374,7 +464,7 @@ const AutoComplete = forwardRef(function AutoComplete(props, ref) {
             }
             return result;
         });
-    }, [isCreated, mode, options]);
+    }, [inputPosition, isCreated, mode, options]);
     // Get selected value for dropdown
     const dropdownValue = useMemo(() => {
         if (mode === 'multiple') {
@@ -392,7 +482,8 @@ const AutoComplete = forwardRef(function AutoComplete(props, ref) {
     const shouldForceClearable = isMultiple
         ? (isMultipleValue(value) && value.length > 0) ||
             searchText.trim().length > 0
-        : isSingleValue(value);
+        : isSingleValue(value) ||
+            (!shouldClearSearchTextOnBlur && searchText.trim().length > 0);
     // Handle dropdown option selection
     const handleDropdownSelect = useCallback((option) => {
         const selectedValue = options.find((opt) => opt.id === option.id);
@@ -425,11 +516,15 @@ const AutoComplete = forwardRef(function AutoComplete(props, ref) {
     ]);
     // Active index for dropdown keyboard navigation
     const [activeIndex, setActiveIndex] = useState(null);
+    // Keyboard-only active index: only set by arrow key navigation, not mouse hover.
+    // Drives the focus ring (--keyboard-active CSS class) separately from hover highlight.
+    const [keyboardActiveIndex, setKeyboardActiveIndex] = useState(null);
     const setListboxHasVisualFocus = useCallback((_focus) => { }, []);
-    // Reset activeIndex when options change
+    // Reset activeIndex and keyboardActiveIndex when options change
     useEffect(() => {
         if (!dropdownOptions.length) {
             setActiveIndex(null);
+            setKeyboardActiveIndex(null);
             return;
         }
         setActiveIndex((prev) => {
@@ -437,6 +532,11 @@ const AutoComplete = forwardRef(function AutoComplete(props, ref) {
                 return null;
             return Math.min(prev, dropdownOptions.length - 1);
         });
+        setKeyboardActiveIndex((prev) => {
+            if (prev === null)
+                return null;
+            return Math.min(prev, dropdownOptions.length - 1);
+        });
     }, [dropdownOptions.length]);
     // Scroll to active option when activeIndex changes
     useEffect(() => {
@@ -471,6 +571,7 @@ const AutoComplete = forwardRef(function AutoComplete(props, ref) {
         searchText,
         searchTextExistWithoutOption,
         setActiveIndex,
+        setKeyboardActiveIndex,
         setInsertText,
         setListboxHasVisualFocus,
         setSearchText,
@@ -486,19 +587,29 @@ const AutoComplete = forwardRef(function AutoComplete(props, ref) {
             e.stopPropagation();
             toggleOpen(false);
             setActiveIndex(null);
+            setKeyboardActiveIndex(null);
             setListboxHasVisualFocus(false);
             onFocus(false);
+            if (isMultiple && shouldClearSearchTextOnBlur) {
+                resetSearchInputsAndOptions();
+                cleanupUnselectedCreated();
+            }
             (_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);
     }, [
+        cleanupUnselectedCreated,
         handleInputKeyDown,
         inputProps,
+        isMultiple,
         onFocus,
+        resetSearchInputsAndOptions,
         setActiveIndex,
+        setKeyboardActiveIndex,
         setListboxHasVisualFocus,
+        shouldClearSearchTextOnBlur,
         toggleOpen,
     ]);
     // Handle visibility change from Dropdown to prevent flickering
@@ -515,6 +626,9 @@ const AutoComplete = forwardRef(function AutoComplete(props, ref) {
         }
         // 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) {
+            setKeyboardActiveIndex(null);
+        }
         if (!newOpen && isMultiple && shouldClearSearchTextOnBlur) {
             if (skipNextMultipleCloseResetRef.current) {
                 const menuElement = document.getElementById(menuId);
@@ -536,6 +650,7 @@ const AutoComplete = forwardRef(function AutoComplete(props, ref) {
         menuId,
         open,
         resetSearchInputsAndOptions,
+        setKeyboardActiveIndex,
         shouldClearSearchTextOnBlur,
         toggleOpen,
     ]);
@@ -568,22 +683,27 @@ const AutoComplete = forwardRef(function AutoComplete(props, ref) {
                     ? createActionText
                         ? createActionText(createActionDisplayText)
                         : createActionTextTemplate.replace('{text}', createActionDisplayText)
-                    : 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: asyncData && isLoading ? [] : 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, isForceClearable: shouldForceClearable, inputRef: composedInputRef, mode: mode, onTagClose: wrappedOnChange, onClear: handleClear, overflowStrategy: isMultiple ? (overflowStrategy !== null && overflowStrategy !== void 0 ? overflowStrategy : 'wrap') : overflowStrategy, placeholder: getPlaceholder(), prefix: prefix, readOnly: false, required: required, type: error ? 'error' : 'default', inputProps: {
+                    : undefined, activeIndex: activeIndex, keyboardActiveIndex: keyboardActiveIndex, 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: asyncData && isLoading ? [] : dropdownOptions, placement: "bottom", sameWidth: true, showDropdownActions: shouldShowCreateAction, showActionShowTopBar: shouldShowCreateAction, status: dropdownStatus, toggleCheckedOnClick: inputPosition === 'inside' && mode === 'multiple' ? false : undefined, type: "default", value: dropdownValue, zIndex: dropdownZIndex, globalPortal: globalPortal, onReachBottom: onReachBottom, onLeaveBottom: onLeaveBottom, children: inputPosition === 'inside' ? (jsx(AutoCompleteInsideTrigger, { active: open, className: className, clearable: shouldForceClearable, disabled: isInputDisabled, error: error, fullWidth: fullWidth, inputRef: composedInputRef, onClear: handleClear, placeholder: getPlaceholder(), resolvedInputProps: {
+                        ...resolvedInputProps,
+                        onClick: (e) => {
+                            var _a;
+                            (_a = resolvedInputProps.onClick) === null || _a === void 0 ? void 0 : _a.call(resolvedInputProps, e);
+                        },
+                    }, size: size, value: insideInputValue })) : (jsx(SelectTrigger, { ref: composedRef, active: open, className: className, clearable: true, disabled: isInputDisabled, fullWidth: fullWidth, isForceClearable: shouldForceClearable, inputRef: composedInputRef, mode: mode, onTagClose: wrappedOnChange, onClear: handleClear, overflowStrategy: isMultiple ? (overflowStrategy !== null && overflowStrategy !== void 0 ? overflowStrategy : 'wrap') : overflowStrategy, placeholder: getPlaceholder(), prefix: prefix, readOnly: false, required: required, type: error ? 'error' : 'default', inputProps: {
                         ...resolvedInputProps,
                         onClick: (e) => {
                             var _a;
                             // When inputPosition is inside, let Dropdown handle the click event
                             // Otherwise, stop propagation to prevent conflicts
-                            if (inputPosition !== 'inside') {
-                                e.stopPropagation();
-                            }
+                            // This branch is only rendered when `inputPosition !== 'inside'`.
+                            e.stopPropagation();
                             (_a = resolvedInputProps.onClick) === null || _a === void 0 ? void 0 : _a.call(resolvedInputProps, e);
                         },
                     }, searchText: searchText, size: size, showTextInputAfterTags: true, suffixAction: onClickSuffixActionIcon, value: mode === 'multiple' &&
                         isMultipleValue(value) &&
                         value.length === 0
                         ? undefined
-                        : (value !== null && value !== void 0 ? value : undefined), ...(mode === 'single' && renderValue ? { renderValue } : {}) }) }) }) }));
+                        : (value !== null && value !== void 0 ? value : undefined), ...(mode === 'single' && renderValue ? { renderValue } : {}) })) }) }) }));
 });
 
 export { AutoComplete as default };

package/AutoComplete/AutoCompleteInside.d.ts

@@ -0,0 +1,54 @@
+import { type MouseEventHandler, type Ref } from 'react';
+import type { InputProps } from '../Input';
+import type { SelectTriggerInputProps } from '../Select/typings';
+export interface AutoCompleteInsideTriggerProps {
+    /**
+     * Disabled state for the input.
+     */
+    disabled: boolean;
+    /**
+     * Error state for the input.
+     */
+    error: boolean;
+    /**
+     * Whether the trigger should render as active (focused/open).
+     */
+    active: boolean;
+    /**
+     * Input display value (usually the current search text).
+     */
+    value: string;
+    /**
+     * Input placeholder text.
+     */
+    placeholder?: string;
+    /**
+     * Input variant sizing.
+     */
+    size?: InputProps['size'];
+    /**
+     * Whether the input should occupy full width.
+     */
+    fullWidth?: boolean;
+    /**
+     * Additional class name for the trigger.
+     */
+    className?: string;
+    /**
+     * Input ref (points to the underlying <input/> element).
+     */
+    inputRef?: Ref<HTMLInputElement>;
+    /**
+     * Props forwarded to the underlying input element.
+     */
+    resolvedInputProps: SelectTriggerInputProps;
+    /**
+     * Whether to show the clear icon.
+     */
+    clearable: boolean;
+    /**
+     * Input clear handler.
+     */
+    onClear?: MouseEventHandler;
+}
+export default function AutoCompleteInsideTrigger(props: AutoCompleteInsideTriggerProps): import("react/jsx-runtime").JSX.Element;

package/AutoComplete/AutoCompleteInside.js

@@ -0,0 +1,17 @@
+'use client';
+import { jsx } from 'react/jsx-runtime';
+import Input from '../Input/Input.js';
+
+function extractIdAndName(props) {
+    const { id, name, readOnly, onChange, ...rest } = props;
+    return { id, name, readOnly, onChange, rest };
+}
+function AutoCompleteInsideTrigger(props) {
+    const { active, className, clearable, disabled, error, fullWidth, inputRef, onClear, placeholder, resolvedInputProps, size, value, } = props;
+    const { id, name, readOnly, onChange, rest } = extractIdAndName(resolvedInputProps);
+    return (jsx(Input, { active: active, className: className, ...(disabled ? { disabled: true } : {}), error: error, fullWidth: fullWidth, id: id, name: name, placeholder: placeholder, readonly: readOnly || undefined, onChange: onChange, size: size, value: value, clearable: clearable, onClear: onClear, 
+        // keep clear icon visibility behavior consistent with SelectTrigger
+        forceShowClearable: clearable, inputRef: inputRef, inputProps: rest }));
+}
+
+export { AutoCompleteInsideTrigger as default };

package/AutoComplete/useAutoCompleteKeyboard.d.ts

@@ -19,6 +19,7 @@ type UseAutoCompleteKeyboardParams = {
     searchText: string;
     searchTextExistWithoutOption: boolean;
     setActiveIndex: Dispatch<SetStateAction<number | null>>;
+    setKeyboardActiveIndex?: Dispatch<SetStateAction<number | null>>;
     setListboxHasVisualFocus: (focus: boolean) => void;
     setInsertText: (value: string) => void;
     setSearchText: (value: string) => void;
@@ -27,7 +28,7 @@ type UseAutoCompleteKeyboardParams = {
     value: SelectValue[] | SelectValue | null | undefined;
     wrappedOnChange: (chooseOption: SelectValue | null) => SelectValue[] | SelectValue | null;
 };
-export declare function useAutoCompleteKeyboard({ activeIndex, addable, createSeparators, dropdownOptions, handleActionCustom, handleBulkCreate, handleDropdownSelect, inputPropsOnKeyDown, inputRef, mode, onFocus, open, processBulkCreate, searchText, searchTextExistWithoutOption, setActiveIndex, setInsertText, setListboxHasVisualFocus, setSearchText, stepByStepBulkCreate, toggleOpen, value, wrappedOnChange, }: UseAutoCompleteKeyboardParams): {
+export declare function useAutoCompleteKeyboard({ activeIndex, addable, createSeparators, dropdownOptions, handleActionCustom, handleBulkCreate, handleDropdownSelect, inputPropsOnKeyDown, inputRef, mode, onFocus, open, processBulkCreate, searchText, searchTextExistWithoutOption, setActiveIndex, setKeyboardActiveIndex, setInsertText, setListboxHasVisualFocus, setSearchText, stepByStepBulkCreate, toggleOpen, value, wrappedOnChange, }: UseAutoCompleteKeyboardParams): {
     handleInputKeyDown: (e: KeyboardEvent<HTMLInputElement>) => void;
 };
 export {};

package/AutoComplete/useAutoCompleteKeyboard.js

@@ -4,7 +4,7 @@ import { createDropdownKeydownHandler } from '../Dropdown/dropdownKeydownHandler
 function isMultipleValue(value) {
     return Array.isArray(value);
 }
-function useAutoCompleteKeyboard({ activeIndex, addable, createSeparators, dropdownOptions, handleActionCustom, handleBulkCreate, handleDropdownSelect, inputPropsOnKeyDown, inputRef, mode, onFocus, open, processBulkCreate, searchText, searchTextExistWithoutOption, setActiveIndex, setInsertText, setListboxHasVisualFocus, setSearchText, stepByStepBulkCreate = false, toggleOpen, value, wrappedOnChange, }) {
+function useAutoCompleteKeyboard({ activeIndex, addable, createSeparators, dropdownOptions, handleActionCustom, handleBulkCreate, handleDropdownSelect, inputPropsOnKeyDown, inputRef, mode, onFocus, open, processBulkCreate, searchText, searchTextExistWithoutOption, setActiveIndex, setKeyboardActiveIndex, setInsertText, setListboxHasVisualFocus, setSearchText, stepByStepBulkCreate = false, toggleOpen, value, wrappedOnChange, }) {
     const handleKeyDown = useCallback((e) => createDropdownKeydownHandler({
         activeIndex,
         onEnterSelect: (option) => {
@@ -18,6 +18,7 @@ function useAutoCompleteKeyboard({ activeIndex, addable, createSeparators, dropd
             var _a;
             toggleOpen(false);
             setActiveIndex(null);
+            setKeyboardActiveIndex === null || setKeyboardActiveIndex === void 0 ? void 0 : setKeyboardActiveIndex(null);
             setListboxHasVisualFocus(false);
             if (inputRef && typeof inputRef !== 'function') {
                 (_a = inputRef.current) === null || _a === void 0 ? void 0 : _a.blur();
@@ -26,6 +27,7 @@ function useAutoCompleteKeyboard({ activeIndex, addable, createSeparators, dropd
         open,
         options: dropdownOptions,
         setActiveIndex,
+        setKeyboardActiveIndex,
         setListboxHasVisualFocus,
         setOpen: (newOpen) => {
             if (newOpen && !open) {
@@ -44,6 +46,7 @@ function useAutoCompleteKeyboard({ activeIndex, addable, createSeparators, dropd
         onFocus,
         open,
         setActiveIndex,
+        setKeyboardActiveIndex,
         setListboxHasVisualFocus,
         toggleOpen,
     ]);

package/Backdrop/Backdrop.d.ts

@@ -33,7 +33,39 @@ export interface BackdropProps extends Pick<PortalProps, 'children' | 'container
     variant?: BackdropVariant;
 }
 /**
- * The react component for `mezzanine` backdrop.
+ * 用於 Modal、Drawer 等覆蓋層元件的遮罩底層元件。
+ *
+ * 透過 `Portal` 渲染至指定的 DOM 容器，並使用 `Fade` 動畫處理顯示與隱藏過渡。
+ * 開啟時會自動鎖定 body 捲動（可透過 `disableScrollLock` 停用）。
+ * 點擊遮罩時預設觸發 `onClose`，可透過 `disableCloseOnBackdropClick` 停用此行為。
+ *
+ * @example
+ * ```tsx
+ * import Backdrop from '@mezzanine-ui/react/Backdrop';
+ *
+ * // 基本用法
+ * <Backdrop open={open} onClose={() => setOpen(false)}>
+ *   <div>浮層內容</div>
+ * </Backdrop>
+ *
+ * // 使用淺色遮罩並停用點擊關閉
+ * <Backdrop
+ *   open={open}
+ *   onClose={() => setOpen(false)}
+ *   variant="light"
+ *   disableCloseOnBackdropClick
+ * >
+ *   <div>強制顯示的內容</div>
+ * </Backdrop>
+ *
+ * // 渲染至自訂容器
+ * <Backdrop open={open} onClose={() => setOpen(false)} container={containerRef}>
+ *   <div>相對定位的浮層</div>
+ * </Backdrop>
+ * ```
+ *
+ * @see {@link Modal} 對話框元件
+ * @see {@link Drawer} 抽屜面板元件
  */
 declare const Backdrop: import("react").ForwardRefExoticComponent<BackdropProps & import("react").RefAttributes<HTMLDivElement>>;
 export default Backdrop;

package/Backdrop/Backdrop.js

@@ -9,7 +9,39 @@ import Fade from '../Transition/Fade.js';
 import cx from 'clsx';
 
 /**
- * The react component for `mezzanine` backdrop.
+ * 用於 Modal、Drawer 等覆蓋層元件的遮罩底層元件。
+ *
+ * 透過 `Portal` 渲染至指定的 DOM 容器，並使用 `Fade` 動畫處理顯示與隱藏過渡。
+ * 開啟時會自動鎖定 body 捲動（可透過 `disableScrollLock` 停用）。
+ * 點擊遮罩時預設觸發 `onClose`，可透過 `disableCloseOnBackdropClick` 停用此行為。
+ *
+ * @example
+ * ```tsx
+ * import Backdrop from '@mezzanine-ui/react/Backdrop';
+ *
+ * // 基本用法
+ * <Backdrop open={open} onClose={() => setOpen(false)}>
+ *   <div>浮層內容</div>
+ * </Backdrop>
+ *
+ * // 使用淺色遮罩並停用點擊關閉
+ * <Backdrop
+ *   open={open}
+ *   onClose={() => setOpen(false)}
+ *   variant="light"
+ *   disableCloseOnBackdropClick
+ * >
+ *   <div>強制顯示的內容</div>
+ * </Backdrop>
+ *
+ * // 渲染至自訂容器
+ * <Backdrop open={open} onClose={() => setOpen(false)} container={containerRef}>
+ *   <div>相對定位的浮層</div>
+ * </Backdrop>
+ * ```
+ *
+ * @see {@link Modal} 對話框元件
+ * @see {@link Drawer} 抽屜面板元件
  */
 const Backdrop = forwardRef(function Backdrop(props, ref) {
     const { children, className, container, disableCloseOnBackdropClick = false, disablePortal, disableScrollLock = false, onBackdropClick, onClose, open = false, variant = 'dark', ...rest } = props;

package/Badge/Badge.d.ts

@@ -1,6 +1,31 @@
 import { BadgeCountVariant } from '@mezzanine-ui/core/badge';
 /**
- * The react component for `mezzanine` badge.
+ * 徽章元件，用於顯示數字計數、狀態圓點或文字標籤。
+ *
+ * 支援四種 variant 類型：count（數字計數）、dot（狀態圓點）、dot 含文字以及 text（純文字標籤）。
+ * 計數型徽章可設定 `overflowCount` 限制最大顯示數值；當 `count` 為 0 時徽章自動隱藏。
+ * 使用 `children` 時（僅限 dot 型），徽章會以覆疊方式出現在子元素右上角。
+ *
+ * @example
+ * ```tsx
+ * import Badge from '@mezzanine-ui/react/Badge';
+ *
+ * // 數字計數徽章
+ * <Badge variant="count-alert" count={5} />
+ *
+ * // 超出上限顯示 99+
+ * <Badge variant="count-brand" count={120} overflowCount={99} />
+ *
+ * // 狀態圓點（附著於圖示右上角）
+ * <Badge variant="dot-alert">
+ *   <BellIcon />
+ * </Badge>
+ *
+ * // 文字徽章
+ * <Badge variant="text-brand" text="NEW" />
+ * ```
+ *
+ * @see {@link BadgeContainer} 搭配容器元件使用絕對定位覆疊效果
  */
 declare const Badge: import("react").ForwardRefExoticComponent<(Omit<Omit<NativeElementPropsWithoutKeyAndRef<"span">, "children"> & {
     children?: never;

package/Badge/Badge.js

@@ -11,7 +11,32 @@ const isCountVariant = (variant) => [
     'count-info',
 ].includes(variant);
 /**
- * The react component for `mezzanine` badge.
+ * 徽章元件，用於顯示數字計數、狀態圓點或文字標籤。
+ *
+ * 支援四種 variant 類型：count（數字計數）、dot（狀態圓點）、dot 含文字以及 text（純文字標籤）。
+ * 計數型徽章可設定 `overflowCount` 限制最大顯示數值；當 `count` 為 0 時徽章自動隱藏。
+ * 使用 `children` 時（僅限 dot 型），徽章會以覆疊方式出現在子元素右上角。
+ *
+ * @example
+ * ```tsx
+ * import Badge from '@mezzanine-ui/react/Badge';
+ *
+ * // 數字計數徽章
+ * <Badge variant="count-alert" count={5} />
+ *
+ * // 超出上限顯示 99+
+ * <Badge variant="count-brand" count={120} overflowCount={99} />
+ *
+ * // 狀態圓點（附著於圖示右上角）
+ * <Badge variant="dot-alert">
+ *   <BellIcon />
+ * </Badge>
+ *
+ * // 文字徽章
+ * <Badge variant="text-brand" text="NEW" />
+ * ```
+ *
+ * @see {@link BadgeContainer} 搭配容器元件使用絕對定位覆疊效果
  */
 const Badge = forwardRef(function Badge(props, ref) {
     const { children, count, className, overflowCount, size, text, variant, ...rest } = props;

package/Badge/typings.d.ts

@@ -37,11 +37,20 @@ type BadgeCountProps = {
     variant: BadgeCountVariant;
 };
 type BadgeTextProps = {
+    /** 此變體下不適用。 */
     children?: never;
+    /** 此變體下不適用。 */
     count?: never;
+    /** 此變體下不適用。 */
     overflowCount?: never;
+    /**
+     * 文字徽章的尺寸。
+     * @default 'main'
+     */
     size?: BadgeTextSize;
+    /** 徽章顯示的文字內容。 */
     text: string;
+    /** 文字徽章的視覺變體。 */
     variant: BadgeTextVariant;
 };
 type BadgeDotWithTextProps = {
@@ -57,11 +66,17 @@ type BadgeDotWithTextProps = {
     variant: BadgeDotVariant;
 };
 type BadgeDotProps = {
+    /** 徽章附著的子元素，圓點會顯示在子元素右上角。 */
     children?: ReactNode;
+    /** 此變體下不適用。 */
     count?: never;
+    /** 此變體下不適用。 */
     overflowCount?: never;
+    /** 此變體下不適用。 */
     size?: never;
+    /** 此變體下不適用。 */
     text?: never;
+    /** 圓點徽章的視覺變體。 */
     variant: BadgeDotVariant;
 };
 export {};

package/Breadcrumb/BreadcrumbDropdown.d.ts

@@ -1,4 +1,4 @@
-declare const BreadcrumbDropdown: import("react").ForwardRefExoticComponent<Omit<import("../Dropdown").DropdownProps, "children"> & {
+declare const BreadcrumbDropdown: import("react").ForwardRefExoticComponent<Omit<import("../Dropdown").DropdownProps, "children" | "onScroll"> & {
     className?: string;
     current?: boolean;
     href?: never;

package/Breadcrumb/BreadcrumbOverflowMenuDropdown.d.ts

@@ -1,4 +1,4 @@
-declare const BreadcrumbOverflowMenuDropdown: import("react").ForwardRefExoticComponent<Omit<import("../Dropdown").DropdownProps, "children"> & {
+declare const BreadcrumbOverflowMenuDropdown: import("react").ForwardRefExoticComponent<Omit<import("../Dropdown").DropdownProps, "children" | "onScroll"> & {
     className?: string;
     current?: boolean;
     href?: never;