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

package/AutoComplete/AutoComplete.d.ts

@@ -21,6 +21,8 @@ export interface AutoCompleteBaseProps extends Omit<SelectTriggerProps, 'active'
     asyncData?: boolean;
     /**
      * Whether to clear search text when leaving the textfield/dropdown scope.
+     * When `false`, typed text persists after blur. In `single` mode, a clearable
+     * icon will appear if the user has typed text without selecting an option.
      * @default true
      */
     clearSearchText?: boolean;
@@ -46,7 +48,10 @@ export interface AutoCompleteBaseProps extends Omit<SelectTriggerProps, 'active'
      */
     id?: string;
     /**
-     * The position of the input.
+     * The position of the search input relative to the dropdown.
+     * - `'outside'`: input is always visible above the dropdown (default trigger layout).
+     * - `'inside'`: input is rendered inside the dropdown panel; the trigger shows only
+     *   the selected value(s) and opens the dropdown on click.
      * @default 'outside'
      */
     inputPosition?: DropdownInputPosition;
@@ -86,10 +91,10 @@ export interface AutoCompleteBaseProps extends Omit<SelectTriggerProps, 'active'
      */
     name?: string;
     /**
-     * insert callback whenever insert icon is clicked
-     * receives the text to insert and current options, returns the updated options array
-     * should remove previously created but unselected options
-     * The returned options will be used to update the component's options prop
+     * Callback fired when the user confirms a new item creation.
+     * Receives the typed text and the current options array; must return the updated options array.
+     * Use this to append the new item to your options state.
+     * Required when `addable` is true; omitting it will disable the creation feature.
      */
     onInsert?(text: string, currentOptions: SelectValue[]): SelectValue[];
     /**
@@ -178,9 +183,10 @@ export interface AutoCompleteBaseProps extends Omit<SelectTriggerProps, 'active'
      */
     onLeaveBottom?: () => void;
     /**
-     * Called on blur when addable mode has unselected created items.
-     * Receives the cleaned options (unselected created items already removed).
-     * Use this to update your options state.
+     * Called when the dropdown closes (on blur or Escape) and `addable` mode has
+     * items that were created but never selected.
+     * Receives the cleaned options array with unselected created items already removed.
+     * Use this to sync your options state and strip the dangling created entries.
      * Only called when `addable` is true and there are unselected created items.
      */
     onRemoveCreated?(cleanedOptions: SelectValue[]): void;
@@ -245,7 +251,8 @@ export type AutoCompleteProps = AutoCompleteMultipleProps | AutoCompleteSinglePr
 /**
  * 自動完成輸入元件，在使用者輸入時即時顯示符合的下拉選項。
  *
- * 支援 `single`（單選）與 `multiple`（多選標籤）兩種模式；設定 `addable` 與 `onInsert`
+ * 支援 `single`（單選）與 `multiple`（多選標籤）兩種模式；`inputPosition` 控制搜尋輸入框
+ * 位於下拉選單外（`'outside'`，預設）或內（`'inside'`）。設定 `addable` 與 `onInsert`
  * 可讓使用者動態建立不在選項清單中的項目。`asyncData` 搭配 `onSearch` 可實現非同步搜尋，
  * 輸入時觸發 debounce 查詢並顯示 loading 狀態。若僅需從固定選項中搜尋，請改用 `Select` 元件。
  *
@@ -270,6 +277,15 @@ export type AutoCompleteProps = AutoCompleteMultipleProps | AutoCompleteSinglePr
  *   onChange={setSelectedList}
  * />
  *
+ * // 搜尋框置於下拉選單內（inside 模式）
+ * <AutoComplete
+ *   mode="multiple"
+ *   inputPosition="inside"
+ *   options={options}
+ *   value={selectedList}
+ *   onChange={setSelectedList}
+ * />
+ *
  * // 非同步搜尋
  * <AutoComplete
  *   mode="single"

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';
@@ -32,7 +33,8 @@ function isSingleValue(value) {
 /**
  * 自動完成輸入元件，在使用者輸入時即時顯示符合的下拉選項。
  *
- * 支援 `single`（單選）與 `multiple`（多選標籤）兩種模式；設定 `addable` 與 `onInsert`
+ * 支援 `single`（單選）與 `multiple`（多選標籤）兩種模式；`inputPosition` 控制搜尋輸入框
+ * 位於下拉選單外（`'outside'`，預設）或內（`'inside'`）。設定 `addable` 與 `onInsert`
  * 可讓使用者動態建立不在選項清單中的項目。`asyncData` 搭配 `onSearch` 可實現非同步搜尋，
  * 輸入時觸發 debounce 查詢並顯示 loading 狀態。若僅需從固定選項中搜尋，請改用 `Select` 元件。
  *
@@ -57,6 +59,15 @@ function isSingleValue(value) {
  *   onChange={setSelectedList}
  * />
  *
+ * // 搜尋框置於下拉選單內（inside 模式）
+ * <AutoComplete
+ *   mode="multiple"
+ *   inputPosition="inside"
+ *   options={options}
+ *   value={selectedList}
+ *   onChange={setSelectedList}
+ * />
+ *
  * // 非同步搜尋
  * <AutoComplete
  *   mode="single"
@@ -268,7 +279,10 @@ const AutoComplete = forwardRef(function AutoComplete(props, ref) {
     }, [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)
@@ -279,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(() => {
@@ -299,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;
@@ -330,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);
@@ -412,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';
@@ -427,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') {
@@ -445,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);
@@ -478,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) => {
@@ -490,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(() => {
@@ -524,6 +571,7 @@ const AutoComplete = forwardRef(function AutoComplete(props, ref) {
         searchText,
         searchTextExistWithoutOption,
         setActiveIndex,
+        setKeyboardActiveIndex,
         setInsertText,
         setListboxHasVisualFocus,
         setSearchText,
@@ -539,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
@@ -568,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);
@@ -589,6 +650,7 @@ const AutoComplete = forwardRef(function AutoComplete(props, ref) {
         menuId,
         open,
         resetSearchInputsAndOptions,
+        setKeyboardActiveIndex,
         shouldClearSearchTextOnBlur,
         toggleOpen,
     ]);
@@ -621,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/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;

package/Breadcrumb/typings.d.ts

@@ -45,7 +45,7 @@ export type BreadcrumbLinkItemProps = Omit<NativeElementPropsWithoutKeyAndRef<'a
      */
     target?: '_blank' | '_parent' | '_self' | '_top' | string;
 };
-export type BreadcrumbDropdownProps = Omit<DropdownProps, 'children'> & {
+export type BreadcrumbDropdownProps = Omit<DropdownProps, 'children' | 'onScroll'> & {
     className?: string;
     current?: boolean;
     href?: never;

package/COMPONENTS.md

@@ -110,7 +110,7 @@
 | SelectTriggerTags         | `SelectTriggerTags`         | 多選 Select 的標籤顯示區域                                                               | —                                                         |
 | SelectionCard             | `SelectionCard`             | 可選取的卡片元件，作為 Checkbox/Radio 的卡片式替代                                       | —                                                         |
 | Slider                    | `Slider`                    | 滑桿元件，支援單點與範圍兩種模式                                                         | `useSlider`                                               |
-| Switch                    | `Switch`                    | 開關切換元件（對應 Toggle）                                                              | `useSwitchControlValue`                                   |
+| Toggle                    | `Toggle`                    | 切換開關元件，用於表示開／關二元狀態                                                     | `useSwitchControlValue`                                   |
 | Textarea                  | `Textarea`                  | 多行文字輸入框，支援自動調整高度與字數限制                                               | `useInputControlValue`                                    |
 | TextField                 | `TextField`                 | 文字欄位基底元件，提供通用的邊框/尺寸/狀態樣式                                           | —                                                         |
 | TimePicker                | `TimePicker`                | 時間選擇器，點擊觸發 TimePanel 面板選取時間                                              | `usePickerValue`                                          |
@@ -220,7 +220,7 @@
 | `useSelectValueControl`         | Select                  | 受控單選 / 多選值管理      |
 | `useCheckboxControlValue`       | Checkbox、CheckboxGroup | 受控勾選狀態管理           |
 | `useRadioControlValue`          | Radio、RadioGroup       | 受控 radio 選取管理        |
-| `useSwitchControlValue`         | Switch（Toggle）        | 受控開關狀態管理           |
+| `useSwitchControlValue`         | Toggle                  | 受控開關狀態管理           |
 | `useAutoCompleteValueControl`   | AutoComplete            | 受控自動完成值管理         |
 | `useCustomControlValue`         | 任意元件                | 泛用受控值 hook            |
 | `useControlValueState`          | 任意元件                | 基礎受控 / 非受控狀態管理  |

package/Checkbox/Checkbox.js

@@ -1,6 +1,6 @@
 'use client';
 import { jsxs, jsx } from 'react/jsx-runtime';
-import { forwardRef, useContext, useId, useEffect, useMemo, useRef } from 'react';
+import { forwardRef, useContext, useId, useEffect, useMemo, useRef, useCallback } from 'react';
 import { checkboxClasses } from '@mezzanine-ui/core/checkbox';
 import { CheckedIcon } from '@mezzanine-ui/icons';
 import { useCheckboxControlValue } from '../Form/useCheckboxControlValue.js';
@@ -110,6 +110,24 @@ const Checkbox = forwardRef(function Checkbox(props, ref) {
         };
     }, [withEditInput, editableInput, resolvedName, finalInputId]);
     const shouldShowEditableInput = withEditInput && defaultEditableInput;
+    const prevIsCheckedRef = useRef(isChecked);
+    useEffect(() => {
+        if (isChecked && !prevIsCheckedRef.current && shouldShowEditableInput && editableInputRef.current) {
+            editableInputRef.current.focus();
+        }
+        prevIsCheckedRef.current = isChecked;
+    }, [isChecked, shouldShowEditableInput]);
+    const handleEditableInputMouseDown = useCallback((event) => {
+        var _a, _b;
+        (_b = (_a = defaultEditableInput === null || defaultEditableInput === void 0 ? void 0 : defaultEditableInput.inputProps) === null || _a === void 0 ? void 0 : _a.onMouseDown) === null || _b === void 0 ? void 0 : _b.call(_a, event);
+        if (event.defaultPrevented) {
+            return;
+        }
+        if (!isChecked && !disabled && inputElementRef.current) {
+            event.preventDefault(); // 阻止原生 focus-on-mousedown，讓 useEffect 統一控制 focus 時機
+            inputElementRef.current.click();
+        }
+    }, [defaultEditableInput, disabled, isChecked]);
     return (jsxs("div", { className: cx(checkboxClasses.host, className, {
             [checkboxClasses.checked]: isChecked,
             [checkboxClasses.indeterminate]: isIndeterminate,
@@ -119,10 +137,13 @@ const Checkbox = forwardRef(function Checkbox(props, ref) {
         }, checkboxClasses.size(size)), children: [jsxs("label", { ref: ref, ...rest, className: checkboxClasses.labelContainer, children: [jsx("div", { className: checkboxClasses.inputContainer, children: jsxs("div", { className: checkboxClasses.inputContent, children: [jsx("input", { ...restInputProps, "aria-checked": isIndeterminate ? 'mixed' : checked, "aria-disabled": disabled, checked: isChecked, className: checkboxClasses.input, disabled: disabled, id: finalInputId, name: resolvedName, onChange: onChange, ref: composedInputRef, type: "checkbox", value: value }), mode === 'chip' && isChecked && (jsx(Icon, { "aria-hidden": "true", className: cx(checkboxClasses.icon, checkboxClasses.chipIcon), color: "brand", icon: CheckedIcon, size: 16 })), mode !== 'chip' && isChecked && (jsx(Icon, { "aria-hidden": "true", className: checkboxClasses.icon, color: "fixed-light", icon: CheckedIcon, size: 9 })), mode !== 'chip' && isIndeterminate && (jsx("span", { "aria-hidden": "true", className: checkboxClasses.indeterminateLine }))] }) }), (label || description) && (jsxs("span", { className: checkboxClasses.textContainer, children: [label && (jsx(Typography, { className: checkboxClasses.label, color: labelColor, variant: "label-primary", children: label })), description && mode !== 'chip' && !shouldShowEditableInput && (jsx(Typography, { className: checkboxClasses.description, color: "text-neutral", variant: "caption", children: description }))] }))] }), shouldShowEditableInput &&
                 defaultEditableInput &&
                 mode !== 'chip' &&
-                !indeterminate && (jsx("div", { className: checkboxClasses.editableInputContainer, children: jsx(Input, { ...defaultEditableInput, ...((!isChecked || disabled) &&
+                !indeterminate && (jsx("label", { className: checkboxClasses.editableInputContainer, htmlFor: finalInputId, children: jsx(Input, { ...defaultEditableInput, ...(disabled &&
                         defaultEditableInput.disabled !== true
                         ? { disabled: true }
-                        : {}), inputRef: composeRefs([
+                        : {}), inputProps: {
+                        ...defaultEditableInput.inputProps,
+                        onMouseDown: handleEditableInputMouseDown,
+                    }, inputRef: composeRefs([
                         defaultEditableInput.inputRef,
                         editableInputRef,
                     ]), variant: "base" }) }))] }));

package/Cropper/Cropper.d.ts

@@ -2,7 +2,7 @@ import type { ReactElement } from 'react';
 import type { ModalHeaderLayoutProps, ModalProps } from '../Modal';
 import { ComponentOverridableForwardRefComponentPropsFactory } from '../utils/jsx-types';
 import { CropArea, CropperComponent, CropperPropsBase } from './typings';
-export type CropperModalProps = Omit<ModalProps, 'children' | 'modalType' | 'extendedSplitLeftSideContent' | 'extendedSplitRightSideContent' | 'onCancel' | 'onConfirm' | 'showCancelButton' | 'showModalFooter' | 'showModalHeader' | 'confirmText' | 'title'> & ModalHeaderLayoutProps & {
+export type CropperModalProps = Omit<ModalProps, 'children' | 'modalType' | 'extendedSplitLeftSideContent' | 'extendedSplitRightSideContent' | 'extendedSplitSidebarPosition' | 'onCancel' | 'onConfirm' | 'showCancelButton' | 'showModalFooter' | 'showModalHeader' | 'confirmText' | 'title'> & ModalHeaderLayoutProps & {
     /**
      * The text for the cancel button.
      */

package/Description/Description.d.ts

@@ -22,7 +22,7 @@ export type DescriptionProps = DistributiveOmit<DescriptionTitleProps, 'classNam
      */
     orientation?: DescriptionOrientation;
     /**
-     * Controls the text size of the description content
+     * Controls the text size of both the title and the description content
      * @default 'main'
      */
     size?: DescriptionSize;

package/Description/Description.js

@@ -14,7 +14,7 @@ const Description = forwardRef(function Description(props, ref) {
             size: (_a = children.props.size) !== null && _a !== void 0 ? _a : size,
         })
         : children;
-    return (jsx(DescriptionContext.Provider, { value: { size }, children: jsxs("div", { className: cx(descriptionClasses.host, descriptionClasses.orientation(orientation), className), ref: ref, children: [jsx(DescriptionTitle, { ...rest, children: title }), injectedChildren] }) }));
+    return (jsx(DescriptionContext.Provider, { value: { size }, children: jsxs("div", { className: cx(descriptionClasses.host, descriptionClasses.orientation(orientation), className), ref: ref, children: [jsx(DescriptionTitle, { ...rest, size: size, children: title }), injectedChildren] }) }));
 });
 
 export { Description as default };

package/Description/DescriptionTitle.d.ts

@@ -1,5 +1,5 @@
 import { IconDefinition } from '@mezzanine-ui/icons';
-import { DescriptionWidthType } from '@mezzanine-ui/core/description';
+import { DescriptionSize, DescriptionWidthType } from '@mezzanine-ui/core/description';
 import { BadgeDotVariant } from '@mezzanine-ui/core/badge';
 import { Placement } from '@floating-ui/react-dom';
 interface DescriptionTitleBaseProps {
@@ -15,6 +15,11 @@ interface DescriptionTitleBaseProps {
      * Title text
      */
     children: string;
+    /**
+     * Controls the text size of the title.
+     * @default 'main'
+     */
+    size?: DescriptionSize;
     /**
      * Controls the layout width behavior of the title
      * @default 'stretch'

package/Description/DescriptionTitle.js

@@ -8,8 +8,8 @@ import Icon from '../Icon/Icon.js';
 import cx from 'clsx';
 
 const DescriptionTitle = forwardRef(function DescriptionTitle(props, ref) {
-    const { badge, className, children, icon, tooltip, tooltipPlacement, widthType = 'stretch', } = props;
-    return (jsxs("div", { className: cx(descriptionClasses.titleHost, descriptionClasses.titleWidth(widthType), className), ref: ref, children: [badge ? (jsx(Badge, { variant: badge, text: children, className: descriptionClasses.titleText })) : (jsx("span", { className: descriptionClasses.titleText, children: children })), icon ? (tooltip ? (jsx(Tooltip, { title: tooltip, options: {
+    const { badge, className, children, icon, size, tooltip, tooltipPlacement, widthType = 'stretch', } = props;
+    return (jsxs("div", { className: cx(descriptionClasses.titleHost, descriptionClasses.titleWidth(widthType), size && descriptionClasses.titleSize(size), className), ref: ref, children: [badge ? (jsx(Badge, { variant: badge, text: children, size: size, className: descriptionClasses.titleText })) : (jsx("span", { className: descriptionClasses.titleText, children: children })), icon ? (tooltip ? (jsx(Tooltip, { title: tooltip, options: {
                     placement: tooltipPlacement !== null && tooltipPlacement !== void 0 ? tooltipPlacement : 'top',
                 }, children: ({ onMouseEnter, onMouseLeave, ref }) => (jsx(Icon, { ref: ref, icon: icon, onMouseEnter: onMouseEnter, onMouseLeave: onMouseLeave, size: 16 })) })) : (jsx(Icon, { icon: icon, size: 16 }))) : null] }));
 });