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

package/Accordion/Accordion.d.ts

@@ -41,5 +41,41 @@ export interface AccordionProps extends Omit<NativeElementPropsWithoutKeyAndRef<
      */
     actions?: AccordionTitleProps['actions'];
 }
+/**
+ * 手風琴元件，提供可展開／收合的內容區塊。
+ *
+ * 可透過 `title` prop 快速設定標題文字，或以 `AccordionTitle` 子元件進行客製化；
+ * 內容區域使用 `AccordionContent` 子元件包裹。支援受控（`expanded`）與非受控
+ * （`defaultExpanded`）兩種模式，以及 `size` 控制整體尺寸，`actions` 可在標題右側
+ * 插入操作按鈕（僅限 `Button` 或 `Dropdown`）。
+ *
+ * @example
+ * ```tsx
+ * import Accordion from '@mezzanine-ui/react/Accordion';
+ * import AccordionTitle from '@mezzanine-ui/react/AccordionTitle';
+ * import AccordionContent from '@mezzanine-ui/react/AccordionContent';
+ *
+ * // 使用 title prop（最簡單的方式）
+ * <Accordion title="常見問題">
+ *   <p>這裡是問題的詳細說明內容。</p>
+ * </Accordion>
+ *
+ * // 使用子元件客製化
+ * <Accordion defaultExpanded>
+ *   <AccordionTitle>進階設定</AccordionTitle>
+ *   <AccordionContent>
+ *     <p>展開後顯示的內容。</p>
+ *   </AccordionContent>
+ * </Accordion>
+ *
+ * // 受控模式
+ * const [expanded, setExpanded] = useState(false);
+ * <Accordion expanded={expanded} onChange={setExpanded} title="收費方案">
+ *   <p>詳細收費說明。</p>
+ * </Accordion>
+ * ```
+ *
+ * @see {@link AccordionGroup} 管理多個手風琴的群組元件
+ */
 declare const Accordion: React.ForwardRefExoticComponent<AccordionProps & React.RefAttributes<HTMLDivElement>>;
 export default Accordion;

package/Accordion/Accordion.js

@@ -46,6 +46,42 @@ const resolveChildren = (children) => {
         content,
     };
 };
+/**
+ * 手風琴元件，提供可展開／收合的內容區塊。
+ *
+ * 可透過 `title` prop 快速設定標題文字，或以 `AccordionTitle` 子元件進行客製化；
+ * 內容區域使用 `AccordionContent` 子元件包裹。支援受控（`expanded`）與非受控
+ * （`defaultExpanded`）兩種模式，以及 `size` 控制整體尺寸，`actions` 可在標題右側
+ * 插入操作按鈕（僅限 `Button` 或 `Dropdown`）。
+ *
+ * @example
+ * ```tsx
+ * import Accordion from '@mezzanine-ui/react/Accordion';
+ * import AccordionTitle from '@mezzanine-ui/react/AccordionTitle';
+ * import AccordionContent from '@mezzanine-ui/react/AccordionContent';
+ *
+ * // 使用 title prop（最簡單的方式）
+ * <Accordion title="常見問題">
+ *   <p>這裡是問題的詳細說明內容。</p>
+ * </Accordion>
+ *
+ * // 使用子元件客製化
+ * <Accordion defaultExpanded>
+ *   <AccordionTitle>進階設定</AccordionTitle>
+ *   <AccordionContent>
+ *     <p>展開後顯示的內容。</p>
+ *   </AccordionContent>
+ * </Accordion>
+ *
+ * // 受控模式
+ * const [expanded, setExpanded] = useState(false);
+ * <Accordion expanded={expanded} onChange={setExpanded} title="收費方案">
+ *   <p>詳細收費說明。</p>
+ * </Accordion>
+ * ```
+ *
+ * @see {@link AccordionGroup} 管理多個手風琴的群組元件
+ */
 const Accordion = forwardRef(function Accordion(props, ref) {
     const { actions, children: childrenProp, className, defaultExpanded = false, disabled = false, expanded: expandedProp, onChange, size = 'main', title, ...rest } = props;
     const [expanded, toggleExpanded] = useState(defaultExpanded !== null && defaultExpanded !== void 0 ? defaultExpanded : false);
@@ -70,7 +106,7 @@ const Accordion = forwardRef(function Accordion(props, ref) {
             toggleExpanded: onToggleExpanded,
         });
     }, [disabled, expandedProp, expanded, onToggleExpanded, resolvedTitle]);
-    return (jsx("div", { ...rest, ref: ref, className: cx(accordionClasses.host, accordionClasses.size(size), className), children: jsxs(AccordionControlContext.Provider, { value: contextValue, children: [title ? (jsx(AccordionTitle, { actions: actions, children: title })) : (resolvedTitle), jsx(Fade, { duration: {
+    return (jsx("div", { ...rest, ref: ref, className: cx(accordionClasses.host, accordionClasses.size(size), { [accordionClasses.hostDisabled]: disabled }, className), children: jsxs(AccordionControlContext.Provider, { value: contextValue, children: [title ? (jsx(AccordionTitle, { actions: actions, children: title })) : (resolvedTitle), jsx(Fade, { duration: {
                         enter: MOTION_DURATION.moderate,
                         exit: MOTION_DURATION.moderate,
                     }, easing: {

package/AlertBanner/AlertBanner.d.ts

@@ -86,7 +86,36 @@ export type AlertBannerType = ((props: AlertBannerData) => ReactElement | null)
     key?: Key;
 }) => Key>;
 /**
- * The react component for `mezzanine` alert banner.
+ * 頁面層級的橫幅式警示訊息元件。
+ *
+ * 預設透過 `Portal` 渲染至 `alert` layer，支援 `info`、`warning`、`error` 三種嚴重程度。
+ * 提供最多 2 個操作按鈕與關閉按鈕，並在顯示及關閉時套用進入／離開動畫。
+ * 也可透過靜態方法 `AlertBanner.info()`、`AlertBanner.warning()`、`AlertBanner.error()` 以命令式方式觸發。
+ *
+ * @example
+ * ```tsx
+ * import AlertBanner from '@mezzanine-ui/react/AlertBanner';
+ *
+ * // 基本用法（JSX）
+ * <AlertBanner severity="info" message="系統將於今晚進行維護" />
+ *
+ * // 帶有操作按鈕
+ * <AlertBanner
+ *   severity="warning"
+ *   message="您有未儲存的變更"
+ *   actions={[
+ *     { content: '儲存', onClick: handleSave },
+ *     { content: '捨棄', onClick: handleDiscard },
+ *   ]}
+ * />
+ *
+ * // 命令式呼叫
+ * AlertBanner.error('操作失敗，請稍後再試');
+ * AlertBanner.info('資料已更新', { closable: true });
+ * ```
+ *
+ * @see {@link InlineMessage} 行內訊息元件
+ * @see {@link Message} 全域提示訊息元件
  */
 export declare const AlertBannerComponent: import("react").ForwardRefExoticComponent<AlertBannerProps & import("react").RefAttributes<HTMLDivElement>>;
 declare const AlertBanner: AlertBannerType;

package/AlertBanner/AlertBanner.js

@@ -2,9 +2,11 @@
 import { jsx, jsxs } from 'react/jsx-runtime';
 import { useCallback, forwardRef, useState, useRef, useEffect } from 'react';
 import { alertBannerIcons, alertBannerClasses, alertBannerGroupClasses } from '@mezzanine-ui/core/alert-banner';
+import { MOTION_EASING } from '@mezzanine-ui/system/motion';
 import Button from '../Button/Button.js';
 import ClearActions from '../ClearActions/ClearActions.js';
 import { useComposeRefs } from '../hooks/useComposeRefs.js';
+import { reflow } from '../Transition/reflow.js';
 import Icon from '../Icon/Icon.js';
 import Portal from '../Portal/Portal.js';
 import cx from 'clsx';
@@ -29,18 +31,53 @@ function sortAlertNotifiers(notifiers) {
     });
 }
 /**
- * The react component for `mezzanine` alert banner.
+ * 頁面層級的橫幅式警示訊息元件。
+ *
+ * 預設透過 `Portal` 渲染至 `alert` layer，支援 `info`、`warning`、`error` 三種嚴重程度。
+ * 提供最多 2 個操作按鈕與關閉按鈕，並在顯示及關閉時套用進入／離開動畫。
+ * 也可透過靜態方法 `AlertBanner.info()`、`AlertBanner.warning()`、`AlertBanner.error()` 以命令式方式觸發。
+ *
+ * @example
+ * ```tsx
+ * import AlertBanner from '@mezzanine-ui/react/AlertBanner';
+ *
+ * // 基本用法（JSX）
+ * <AlertBanner severity="info" message="系統將於今晚進行維護" />
+ *
+ * // 帶有操作按鈕
+ * <AlertBanner
+ *   severity="warning"
+ *   message="您有未儲存的變更"
+ *   actions={[
+ *     { content: '儲存', onClick: handleSave },
+ *     { content: '捨棄', onClick: handleDiscard },
+ *   ]}
+ * />
+ *
+ * // 命令式呼叫
+ * AlertBanner.error('操作失敗，請稍後再試');
+ * AlertBanner.info('資料已更新', { closable: true });
+ * ```
+ *
+ * @see {@link InlineMessage} 行內訊息元件
+ * @see {@link Message} 全域提示訊息元件
  */
 const AlertBannerComponent = forwardRef(function AlertBanner(props, ref) {
     var _a;
     const { actions, className, closable = true, disablePortal = false, icon, message, onClose, severity, ...rest } = props;
     const [visible, setVisible] = useState(true);
-    const [isExiting, setIsExiting] = useState(false);
-    const [isEntering, setIsEntering] = useState(false);
     const nodeRef = useRef(null);
+    const wrapperRef = useRef(null);
     const composedRef = useComposeRefs([ref, nodeRef]);
     const handleClose = useCallback(() => {
-        setIsExiting(true);
+        const wrapper = wrapperRef.current;
+        if (wrapper) {
+            wrapper.style.height = `${wrapper.scrollHeight}px`;
+            wrapper.style.overflow = 'hidden';
+            reflow(wrapper);
+            wrapper.style.transition = `height 250ms ${MOTION_EASING.exit}`;
+            wrapper.style.height = '0px';
+        }
         setTimeout(() => {
             setVisible(false);
             if (onClose) {
@@ -54,16 +91,23 @@ const AlertBannerComponent = forwardRef(function AlertBanner(props, ref) {
         }
     }, [actions]);
     useEffect(() => {
-        if (visible && !isExiting && nodeRef.current) {
-            // Force reflow to ensure initial state is applied
-            // eslint-disable-next-line @typescript-eslint/no-unused-expressions
-            nodeRef.current.offsetHeight;
-            // Trigger entering animation in next frame
+        if (visible && nodeRef.current && wrapperRef.current) {
+            const wrapper = wrapperRef.current;
+            const inner = nodeRef.current;
+            wrapper.style.height = '0px';
+            wrapper.style.overflow = 'hidden';
+            reflow(wrapper);
             requestAnimationFrame(() => {
-                setIsEntering(true);
+                wrapper.style.transition = `height 250ms ${MOTION_EASING.entrance}`;
+                wrapper.style.height = `${inner.scrollHeight}px`;
+                setTimeout(() => {
+                    wrapper.style.height = 'auto';
+                    wrapper.style.overflow = 'visible';
+                    wrapper.style.transition = '';
+                }, 250);
             });
         }
-    }, [visible, isExiting]);
+    }, [visible]);
     if (!visible) {
         return null;
     }
@@ -77,7 +121,7 @@ const AlertBannerComponent = forwardRef(function AlertBanner(props, ref) {
         }) })) : null;
     const clearActionsArea = showCloseButton ? (jsx(ClearActions, { className: alertBannerClasses.close, onClick: handleClose, type: "standard", variant: "inverse" })) : null;
     const { maxCount: _maxCount, instanceKey: _instanceKey, ...restProps } = rest;
-    const content = (jsxs("div", { ...restProps, ref: composedRef, "aria-live": "polite", className: cx(alertBannerClasses.host, alertBannerClasses.severity(severity), isExiting && alertBannerClasses.exiting, isEntering && !isExiting && alertBannerClasses.entering, className), role: "status", children: [jsxs("div", { className: alertBannerClasses.body, children: [jsx(Icon, { className: alertBannerClasses.icon, icon: resolvedIcon }), jsx("span", { className: alertBannerClasses.message, children: message })] }), jsxs("div", { className: alertBannerClasses.controls, children: [actionsArea, clearActionsArea] })] }));
+    const content = (jsx("div", { ref: wrapperRef, className: alertBannerClasses.wrapper, children: jsxs("div", { ...restProps, ref: composedRef, "aria-live": "polite", className: cx(alertBannerClasses.host, alertBannerClasses.severity(severity), className), role: "status", children: [jsxs("div", { className: alertBannerClasses.body, children: [jsx(Icon, { className: alertBannerClasses.icon, icon: resolvedIcon }), jsx("span", { className: alertBannerClasses.message, children: message })] }), jsxs("div", { className: alertBannerClasses.controls, children: [actionsArea, clearActionsArea] })] }) }));
     if (disablePortal) {
         return content;
     }

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;
@@ -243,9 +249,67 @@ export type AutoCompleteSingleProps = AutoCompleteBaseProps & {
 };
 export type AutoCompleteProps = AutoCompleteMultipleProps | AutoCompleteSingleProps;
 /**
- * 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
  */
 declare const AutoComplete: import("react").ForwardRefExoticComponent<AutoCompleteProps & import("react").RefAttributes<HTMLDivElement>>;
 export default AutoComplete;