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

package/AutoComplete/AutoComplete.d.ts

@@ -5,7 +5,7 @@ import { PopperProps } from '../Popper';
 import type { SelectTriggerInputProps, SelectTriggerProps } from '../Select/typings';
 import { SelectValue } from '../Select/typings';
 import { PickRenameMulti } from '../utils/general';
-export interface AutoCompleteBaseProps extends Omit<SelectTriggerProps, 'active' | 'clearable' | 'forceHideSuffixActionIcon' | 'mode' | 'onClick' | 'onKeyDown' | 'onChange' | 'renderValue' | 'inputProps' | 'suffixActionIcon' | 'value'>, PickRenameMulti<Pick<PopperProps, 'options'>, {
+export interface AutoCompleteBaseProps extends Omit<SelectTriggerProps, 'active' | 'clearable' | 'forceHideSuffixActionIcon' | 'fullWidth' | 'mode' | 'onClick' | 'onKeyDown' | 'onChange' | 'renderValue' | 'inputProps' | 'suffixActionIcon' | 'value'>, PickRenameMulti<Pick<PopperProps, 'options'>, {
     options: 'popperOptions';
 }> {
     /**

package/AutoComplete/AutoComplete.js

@@ -7,11 +7,11 @@ import { useAutoCompleteValueControl } from '../Form/useAutoCompleteValueControl
 import { useComposeRefs } from '../hooks/useComposeRefs.js';
 import { SelectControlContext } from '../Select/SelectControlContext.js';
 import SelectTrigger from '../Select/SelectTrigger.js';
+import AutoCompleteInsideTrigger from './AutoCompleteInside.js';
 import { useAutoCompleteCreation, getFullParsedList } from './useAutoCompleteCreation.js';
 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';
@@ -94,8 +94,8 @@ function isSingleValue(value) {
  * @see {@link useAutoCompleteValueControl} 管理 AutoComplete 內部值狀態的 hook
  */
 const AutoComplete = forwardRef(function AutoComplete(props, ref) {
-    const { disabled: disabledFromFormControl, fullWidth: fullWidthFromFormControl, required: requiredFromFormControl, severity, } = useContext(FormControlContext) || {};
-    const { addable = false, asyncData = false, className, clearSearchText = true, createSeparators = [',', '+', '\n'], defaultValue, disabled = disabledFromFormControl || false, disabledOptionsFilter = false, emptyText = '沒有符合的項目', error = severity === 'error' || false, fullWidth = fullWidthFromFormControl || false, id, inputPosition = 'outside', inputProps, inputRef, loading = false, loadingText = '載入中...', loadingPosition = 'bottom', menuMaxHeight, mode = 'single', name, onClear: onClearProp, onChange: onChangeProp, onInsert, onSearch, onSearchTextChange, onVisibilityChange, open: openProp, options: optionsProp, overflowStrategy, placeholder = '', prefix, required = requiredFromFormControl || false, searchDebounceTime = 300, searchTextControlRef, size, stepByStepBulkCreate = false, trimOnCreate = true, value: valueProp, createActionText, createActionTextTemplate = '建立 "{text}"', dropdownZIndex, globalPortal = true, onReachBottom, onLeaveBottom, onRemoveCreated, } = props;
+    const { disabled: disabledFromFormControl, required: requiredFromFormControl, severity, } = useContext(FormControlContext) || {};
+    const { addable = false, asyncData = false, className, clearSearchText = true, createSeparators = [',', '+', '\n'], defaultValue, disabled = disabledFromFormControl || false, disabledOptionsFilter = false, emptyText = '沒有符合的項目', error = severity === 'error' || false, id, inputPosition = 'outside', inputProps, inputRef, loading = false, loadingText = '載入中...', loadingPosition = 'bottom', menuMaxHeight, mode = 'single', name, onClear: onClearProp, onChange: onChangeProp, onInsert, onSearch, onSearchTextChange, onVisibilityChange, open: openProp, options: optionsProp, overflowStrategy, placeholder = '', prefix, required = requiredFromFormControl || false, searchDebounceTime = 300, searchTextControlRef, size, stepByStepBulkCreate = false, trimOnCreate = true, value: valueProp, createActionText, createActionTextTemplate = '建立 "{text}"', dropdownZIndex, globalPortal = true, onReachBottom, onLeaveBottom, onRemoveCreated, } = props;
     const shouldClearSearchTextOnBlur = clearSearchText;
     const [uncontrolledOpen, setUncontrolledOpen] = useState(false);
     const isMultiple = mode === 'multiple';
@@ -676,20 +676,19 @@ const AutoComplete = forwardRef(function AutoComplete(props, ref) {
         role: 'combobox',
     };
     return (jsx(SelectControlContext.Provider, { value: context, children: jsx("div", { ref: nodeRef, className: cx(autocompleteClasses.host, {
-                [autocompleteClasses.hostFullWidth]: fullWidth,
                 [autocompleteClasses.hostInsideClosed]: inputPosition === 'inside' && !open,
                 [autocompleteClasses.hostMode(mode)]: mode,
             }), children: jsx(Dropdown, { actionText: shouldShowCreateAction
                     ? createActionText
                         ? createActionText(createActionDisplayText)
                         : createActionTextTemplate.replace('{text}', createActionDisplayText)
-                    : 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: {
+                    : 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, 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: {
+                    }, size: size, value: insideInputValue })) : (jsx(SelectTrigger, { ref: composedRef, active: open, className: className, clearable: true, disabled: isInputDisabled, fullWidth: true, 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;

package/AutoComplete/AutoCompleteInside.d.ts

@@ -26,10 +26,6 @@ export interface AutoCompleteInsideTriggerProps {
      * Input variant sizing.
      */
     size?: InputProps['size'];
-    /**
-     * Whether the input should occupy full width.
-     */
-    fullWidth?: boolean;
     /**
      * Additional class name for the trigger.
      */

package/AutoComplete/AutoCompleteInside.js

@@ -7,9 +7,9 @@ function extractIdAndName(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 { active, className, clearable, disabled, error, 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, 
+    return (jsx(Input, { active: active, className: className, ...(disabled ? { disabled: true } : {}), error: error, fullWidth: true, 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 }));
 }

package/COMPONENTS.md

@@ -4,18 +4,18 @@
 
 ## General（基礎）
 
-| 元件             | 匯入名稱           | 說明                                                                                  |
-| ---------------- | ------------------ | ------------------------------------------------------------------------------------- |
-| Button           | `Button`           | 動作觸發按鈕，支援 primary / secondary / ghost / destructive / inverse 變體與多種尺寸 |
-| ButtonGroup      | `ButtonGroup`      | 將多個 Button 組合為群組，支援水平或垂直排列                                          |
-| Cropper          | `Cropper`          | 圖片裁切元件，支援自訂裁切區域與輸出尺寸                                              |
-| Icon             | `Icon`             | SVG 圖示元件，搭配 `@mezzanine-ui/icons` 使用，支援顏色與大小控制                     |
-| Layout           | `Layout`           | 頁面整體佈局容器，提供左側面板、主要內容區、右側面板的三欄結構                        |
-| LayoutLeftPanel  | `LayoutLeftPanel`  | 佈局左側面板區塊                                                                      |
-| LayoutMain       | `LayoutMain`       | 佈局主要內容區塊                                                                      |
-| LayoutRightPanel | `LayoutRightPanel` | 佈局右側面板區塊                                                                      |
-| Separator        | `Separator`        | 水平或垂直分隔線，用於視覺上區隔內容區塊                                              |
-| Typography       | `Typography`       | 文字排版元件，支援 h1–h6 / body / caption 等語意層級與顏色變體                        |
+| 元件             | 匯入名稱           | 說明                                                                                                                                                                                                  |
+| ---------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Button           | `Button`           | 動作觸發按鈕，支援 primary / secondary / ghost / destructive / inverse 變體與多種尺寸                                                                                                                 |
+| ButtonGroup      | `ButtonGroup`      | 將多個 Button 組合為群組，支援水平或垂直排列                                                                                                                                                          |
+| Cropper          | `Cropper`          | 圖片裁切元件，支援自訂裁切區域與輸出尺寸                                                                                                                                                              |
+| Icon             | `Icon`             | SVG 圖示元件，搭配 `@mezzanine-ui/icons` 使用，支援顏色與大小控制                                                                                                                                     |
+| Layout           | `Layout`           | 頁面整體佈局容器，提供左側面板、主要內容區、右側面板的三欄結構                                                                                                                                        |
+| LayoutLeftPanel  | `LayoutLeftPanel`  | 佈局左側面板區塊                                                                                                                                                                                      |
+| LayoutMain       | `LayoutMain`       | 佈局主要內容區塊                                                                                                                                                                                      |
+| LayoutRightPanel | `LayoutRightPanel` | 佈局右側面板區塊                                                                                                                                                                                      |
+| Separator        | `Separator`        | 水平或垂直分隔線，用於視覺上區隔內容區塊                                                                                                                                                              |
+| Typography       | `Typography`       | 文字排版元件，`variant` 為語意排版類型（`TypographySemanticType`），僅支援 `h1`、`h2`、`h3`（無 h4–h6），並提供 body / caption / annotation / button / input / label / text-link 系列共 21 種 variant |
 
 ## Navigation（導航）
 
@@ -110,7 +110,7 @@
 | SelectTriggerTags         | `SelectTriggerTags`         | 多選 Select 的標籤顯示區域                                                               | —                                                         |
 | SelectionCard             | `SelectionCard`             | 可選取的卡片元件，作為 Checkbox/Radio 的卡片式替代                                       | —                                                         |
 | Slider                    | `Slider`                    | 滑桿元件，支援單點與範圍兩種模式                                                         | `useSlider`                                               |
-| Toggle                    | `Toggle`                    | 切換開關元件，用於表示開／關二元狀態                                                     | `useSwitchControlValue`                                   |
+| Toggle                    | `Toggle`                    | 切換開關元件，用於表示開／關二元狀態（原名為 Switch）                                    | `useSwitchControlValue`                                   |
 | Textarea                  | `Textarea`                  | 多行文字輸入框，支援自動調整高度與字數限制                                               | `useInputControlValue`                                    |
 | TextField                 | `TextField`                 | 文字欄位基底元件，提供通用的邊框/尺寸/狀態樣式                                           | —                                                         |
 | TimePicker                | `TimePicker`                | 時間選擇器，點擊觸發 TimePanel 面板選取時間                                              | `usePickerValue`                                          |
@@ -180,6 +180,7 @@
 | Scale                  | `Scale`                  | 縮放動畫                                                                             |
 | Slide                  | `Slide`                  | 滑動動畫，Drawer 使用此元件進行進出場                                                |
 | Translate              | `Translate`              | 位移動畫                                                                             |
+| createNotifier         | `createNotifier`         | 工廠函式，建立通知管理器實例，用於指令式顯示 toast / 通知訊息                        |
 
 ---
 
@@ -265,3 +266,15 @@
 | `useTableSuperContext`         | 取得 Table 的上層 Context                             |
 | `useTableDataSource`           | 管理 Table 的資料來源、排序與篩選                     |
 | `useTableRowSelection`         | 管理 Table 的列選取狀態                               |
+
+---
+
+## 內部元件（不建議使用）
+
+以下元件僅可透過 sub-path import 存取，為 mezzanine 內部使用。
+
+| 元件          | 替代方案                   | 說明          |
+| ------------- | -------------------------- | ------------- |
+| ContentHeader | 自行組合 PageHeader 或自訂 | 頁面級別標頭  |
+| ClearActions  | 自行組合 Button            | 清除/關閉按鈕 |
+| Scrollbar     | 瀏覽器原生捲軸或自訂       | 自訂捲軸元件  |

package/Checkbox/Checkbox.js

@@ -117,6 +117,23 @@ const Checkbox = forwardRef(function Checkbox(props, ref) {
         }
         prevIsCheckedRef.current = isChecked;
     }, [isChecked, shouldShowEditableInput]);
+    const handleChipHostClick = useCallback((e) => {
+        var _a;
+        if (disabled)
+            return;
+        if (e.target === e.currentTarget) {
+            (_a = inputElementRef.current) === null || _a === void 0 ? void 0 : _a.click();
+        }
+    }, [disabled]);
+    const handleChipHostKeyDown = useCallback((e) => {
+        var _a;
+        if (disabled)
+            return;
+        if (e.target === e.currentTarget && (e.key === 'Enter' || e.key === ' ')) {
+            e.preventDefault();
+            (_a = inputElementRef.current) === null || _a === void 0 ? void 0 : _a.click();
+        }
+    }, [disabled]);
     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);
@@ -134,7 +151,7 @@ const Checkbox = forwardRef(function Checkbox(props, ref) {
             [checkboxClasses.disabled]: disabled,
             [checkboxClasses.mode(mode)]: mode !== 'default',
             ...(severity && { [checkboxClasses.severity(severity)]: true }),
-        }, 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 &&
+        }, checkboxClasses.size(size)), onClick: mode === 'chip' ? handleChipHostClick : undefined, onKeyDown: mode === 'chip' ? handleChipHostKeyDown : undefined, 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("label", { className: checkboxClasses.editableInputContainer, htmlFor: finalInputId, children: jsx(Input, { ...defaultEditableInput, ...(disabled &&

package/Dropdown/Dropdown.js

@@ -221,17 +221,19 @@ function Dropdown(props) {
     const offsetMiddleware = useMemo(() => {
         return offset({ mainAxis: 4 });
     }, []);
-    // Set z-index for popper to ensure it appears above other elements
+    // Set z-index for popper only when explicitly provided via the `zIndex` prop.
+    // When not provided, do NOT apply any inline z-index so that elements inside
+    // the portal stack purely by DOM order — this ensures Modals opened from
+    // a Dropdown always appear on top without a z-index fight.
     const zIndexMiddleware = useMemo(() => {
-        const zIndexValue = zIndex !== null && zIndex !== void 0 ? zIndex : 1;
+        if (zIndex === undefined || zIndex === null)
+            return null;
+        const zIndexNum = typeof zIndex === 'number'
+            ? zIndex
+            : parseInt(zIndex, 10) || zIndex;
         return {
             name: 'zIndex',
             fn: ({ elements }) => {
-                const zIndexNum = typeof zIndexValue === 'number'
-                    ? zIndexValue
-                    : typeof zIndexValue === 'string'
-                        ? parseInt(zIndexValue, 10) || zIndexValue
-                        : 1;
                 Object.assign(elements.floating.style, {
                     zIndex: zIndexNum,
                 });
@@ -558,7 +560,7 @@ function Dropdown(props) {
                     placement: popoverPlacement,
                     middleware: [
                         offsetMiddleware,
-                        zIndexMiddleware,
+                        ...(zIndexMiddleware ? [zIndexMiddleware] : []),
                         ...(customWidthMiddleware ? [customWidthMiddleware] : []),
                         ...(sameWidthMiddleware ? [sameWidthMiddleware] : []),
                     ],

package/Dropdown/DropdownItem.js

@@ -530,7 +530,7 @@ function DropdownItem(props) {
         onScroll,
     ]);
     return (jsxs("ul", { "aria-label": listboxLabel ||
-            (optionsContent.length === 0 ? 'Dropdown options' : undefined), className: dropdownClasses.list, id: listboxId, ref: listRef, role: "listbox", style: listStyle, tabIndex: -1, children: [hasHeader && (jsx("li", { className: dropdownClasses.listHeader, role: "presentation", ref: headerRef, children: jsx("div", { className: dropdownClasses.listHeaderInner, children: headerContent }) })), maxHeight ? (shouldUseScrollbar ? (jsx(Scrollbar, { className: dropdownClasses.listWrapper, defer: scrollbarDefer, disabled: false, events: scrollbarEvents, maxHeight: listWrapperStyle === null || listWrapperStyle === void 0 ? void 0 : listWrapperStyle.maxHeight, maxWidth: scrollbarMaxWidth, onViewportReady: handleViewportReady, options: scrollbarOptions, children: shouldShowFullStatus ? (jsx(DropdownStatus, { status: status, loadingText: loadingText, emptyText: emptyText, emptyIcon: emptyIcon })) : (jsxs(Fragment, { children: [renderedOptions, shouldShowBottomLoading && (jsx("li", { className: dropdownClasses.loadingMore, "aria-live": "polite", role: "status", children: jsx(DropdownStatus, { status: "loading", loadingText: loadingText }) }))] })) })) : (jsx("div", { ref: listWrapperRef, className: dropdownClasses.listWrapper, style: listWrapperStyle, children: shouldShowFullStatus ? (jsx(DropdownStatus, { status: status, loadingText: loadingText, emptyText: emptyText, emptyIcon: emptyIcon })) : (jsxs(Fragment, { children: [renderedOptions, shouldShowBottomLoading && (jsx("li", { className: dropdownClasses.loadingMore, "aria-live": "polite", role: "status", children: jsx(DropdownStatus, { status: "loading", loadingText: loadingText }) }))] })) }))) : shouldShowFullStatus ? (jsx(DropdownStatus, { status: status, loadingText: loadingText, emptyText: emptyText, emptyIcon: emptyIcon })) : (jsxs(Fragment, { children: [renderedOptions, shouldShowBottomLoading && (jsx("li", { className: dropdownClasses.loadingMore, "aria-live": "polite", role: "status", children: jsx(DropdownStatus, { status: "loading", loadingText: loadingText }) }))] })), hasActions && (jsx("div", { ref: actionRef, children: jsx(DropdownAction, { ...actionConfig }) }))] }));
+            (optionsContent.length === 0 ? 'Dropdown options' : undefined), className: dropdownClasses.list, id: listboxId, ref: listRef, role: "listbox", style: listStyle, tabIndex: -1, children: [hasHeader && (jsx("li", { className: dropdownClasses.listHeader, role: "presentation", ref: headerRef, children: jsx("div", { className: dropdownClasses.listHeaderInner, children: headerContent }) })), maxHeight ? (shouldUseScrollbar ? (jsx(Scrollbar, { className: dropdownClasses.listWrapper, defer: scrollbarDefer, disabled: false, events: scrollbarEvents, maxHeight: listWrapperStyle === null || listWrapperStyle === void 0 ? void 0 : listWrapperStyle.maxHeight, maxWidth: scrollbarMaxWidth, onViewportReady: handleViewportReady, options: scrollbarOptions, children: shouldShowFullStatus ? (jsx(DropdownStatus, { status: status, loadingText: loadingText, emptyText: emptyText, emptyIcon: emptyIcon })) : (jsxs(Fragment, { children: [renderedOptions, shouldShowBottomLoading && (jsx("li", { className: dropdownClasses.loadingMore, "aria-live": "polite", role: "status", children: jsx(DropdownStatus, { status: "loading", loadingText: loadingText }) }))] })) })) : (jsx("div", { ref: listWrapperRef, className: dropdownClasses.listWrapper, style: listWrapperStyle, children: shouldShowFullStatus ? (jsx(DropdownStatus, { status: status, loadingText: loadingText, emptyText: emptyText, emptyIcon: emptyIcon })) : (jsxs(Fragment, { children: [renderedOptions, shouldShowBottomLoading && (jsx("li", { className: dropdownClasses.loadingMore, "aria-live": "polite", role: "status", children: jsx(DropdownStatus, { status: "loading", loadingText: loadingText }) }))] })) }))) : shouldShowFullStatus ? (jsx(DropdownStatus, { status: status, loadingText: loadingText, emptyText: emptyText, emptyIcon: emptyIcon })) : (jsxs(Fragment, { children: [renderedOptions, shouldShowBottomLoading && (jsx("li", { className: dropdownClasses.loadingMore, "aria-live": "polite", role: "status", children: jsx(DropdownStatus, { status: "loading", loadingText: loadingText }) }))] })), hasActions && (jsx("div", { ref: actionRef, style: { position: 'relative', zIndex: 0 }, children: jsx(DropdownAction, { ...actionConfig }) }))] }));
 }
 
 export { DropdownItem as default };

package/Navigation/Navigation.js

@@ -131,7 +131,7 @@ const Navigation = forwardRef((props, ref) => {
                 handleCollapseChange,
                 setActivatedPath: combineSetActivatedPath,
                 optionsAnchorComponent,
-            }, children: [headerComponent, jsx(NavigationOptionLevelContext.Provider, { value: navigationOptionLevelContextDefaultValues, children: jsxs("div", { ref: contentRef, className: navigationClasses.content, children: [filter && (jsx(Input, { size: "sub", variant: "search", className: cx(navigationClasses.searchInput), value: filterText, onChange: (e) => setFilterText(e.target.value) })), jsx(Scrollbar, { disabled: collapsed, style: { flex: '1 1 0', minHeight: 0 }, children: jsxs("ul", { className: navigationClasses.list, children: [items, collapsed &&
+            }, children: [headerComponent, jsx(NavigationOptionLevelContext.Provider, { value: navigationOptionLevelContextDefaultValues, children: jsxs("div", { ref: contentRef, className: navigationClasses.content, children: [filter && (jsx("div", { className: navigationClasses.searchInput, children: jsx(Input, { size: "sub", variant: "search", value: filterText, onChange: (e) => setFilterText(e.target.value) }) })), jsx(Scrollbar, { disabled: collapsed, style: { flex: '1 1 0', minHeight: 0 }, children: jsxs("ul", { className: navigationClasses.list, children: [items, collapsed &&
                                             visibleCount !== null &&
                                             visibleCount < level1Items.length && (jsx(NavigationOverflowMenu, { items: collapsedMenuItems }))] }) })] }) }), footerComponent] }) }));
 });

package/Navigation/NavigationOption.js

@@ -104,7 +104,7 @@ const NavigationOption = forwardRef((props, ref) => {
                             if (!children)
                                 setActivatedPath(currentPath);
                         }
-                    }, onMouseEnter: onMouseEnter, onMouseLeave: onMouseLeave, ref: tooltipChildRef, role: "menuitem", tabIndex: 0, children: [icon && jsx(Icon, { className: navigationOptionClasses.icon, icon: icon }), jsx("span", { className: navigationOptionClasses.titleWrapper, children: jsx(Fade, { ref: titleRef, in: collapsed === false || !icon, children: jsx("span", { className: navigationOptionClasses.title, children: title }) }) }), badge, children && (jsx(Icon, { className: navigationOptionClasses.toggleIcon, icon: GroupToggleIcon }))] })) }), children && !collapsed && (jsx(Collapse, { lazyMount: true, className: cx(navigationOptionClasses.childrenWrapper), in: open, children: jsx(NavigationOptionLevelContext.Provider, { value: {
+                    }, onMouseEnter: onMouseEnter, onMouseLeave: onMouseLeave, ref: tooltipChildRef, role: "menuitem", tabIndex: 0, children: [icon && jsx(Icon, { className: navigationOptionClasses.icon, icon: icon }), jsx("span", { className: navigationOptionClasses.titleWrapper, children: jsx(Fade, { ref: titleRef, in: collapsed === false || !icon, children: jsx("span", { className: navigationOptionClasses.title, children: collapsed && !icon ? Array.from(title).slice(0, 2).join('') : title }) }) }), badge, children && (jsx(Icon, { className: navigationOptionClasses.toggleIcon, icon: GroupToggleIcon }))] })) }), children && !collapsed && (jsx(Collapse, { lazyMount: true, className: cx(navigationOptionClasses.childrenWrapper), in: open, children: jsx(NavigationOptionLevelContext.Provider, { value: {
                         level: currentLevel,
                         path: currentPath,
                     }, children: jsx("ul", { className: navigationOptionClasses.group, children: items }) }) }))] }));

package/PATTERNS.md

@@ -0,0 +1,759 @@
+# Mezzanine UI 常用 UI 模式
+
+> 此檔案為 [`COMPONENTS.md`](./COMPONENTS.md) 的伴隨文件，提供常見 UI 場景的實作範例。
+>
+> 基於 **v1.0.0**（`@mezzanine-ui/react`）
+
+## 目錄
+
+- [佈局模式（Layout Patterns）](#佈局模式layout-patterns)
+- [表單模式（Form Patterns）](#表單模式form-patterns)
+- [表格模式（Table Patterns）](#表格模式table-patterns)
+- [對話框模式（Dialog Patterns）](#對話框模式dialog-patterns)
+- [導航模式（Navigation Patterns）](#導航模式navigation-patterns)
+- [載入狀態（Loading States）](#載入狀態loading-states)
+- [錯誤處理（Error Handling）](#錯誤處理error-handling)
+- [通知提示（Notifications）](#通知提示notifications)
+
+---
+
+## 佈局模式（Layout Patterns）
+
+### 完整頁面佈局 + 右側面板
+
+`Layout` 元件是頂層佈局容器。`Navigation`、`Layout.LeftPanel`、`Layout.Main`、`Layout.RightPanel` 均作為 `Layout` 的直接子元件傳入，順序可任意，`Layout` 會自動排序至正確的 DOM 位置。
+
+```tsx
+import { useState } from 'react';
+import { Layout, Navigation, NavigationFooter, NavigationHeader, NavigationOption, NavigationOptionCategory, Button, Table } from '@mezzanine-ui/react';
+import { HomeIcon, SettingIcon } from '@mezzanine-ui/icons';
+
+function AppWithRightPanel() {
+  const [rightPanelOpen, setRightPanelOpen] = useState(false);
+  const [selectedItem, setSelectedItem] = useState<DataItem | null>(null);
+
+  const handleItemClick = (item: DataItem): void => {
+    setSelectedItem(item);
+    setRightPanelOpen(true);
+  };
+
+  return (
+    <Layout>
+      <Navigation>
+        <NavigationHeader title="品牌名稱" />
+        <NavigationOptionCategory title="主選單">
+          <NavigationOption icon={HomeIcon} title="首頁" />
+          <NavigationOption icon={SettingIcon} title="設定" />
+        </NavigationOptionCategory>
+        <NavigationFooter />
+      </Navigation>
+
+      <Layout.Main>
+        <Table
+          columns={columns}
+          dataSource={data}
+          onRow={(record) => ({
+            onClick: () => handleItemClick(record),
+          })}
+        />
+      </Layout.Main>
+
+      <Layout.RightPanel defaultWidth={400} open={rightPanelOpen}>
+        {selectedItem && (
+          <>
+            <h2>{selectedItem.name}</h2>
+            <p>{selectedItem.description}</p>
+            <Button onClick={() => setRightPanelOpen(false)}>關閉</Button>
+          </>
+        )}
+      </Layout.RightPanel>
+    </Layout>
+  );
+}
+```
+
+### 雙側面板佈局（左 + 右）
+
+```tsx
+import { useState } from 'react';
+import { Layout, Navigation, NavigationFooter, NavigationHeader, NavigationOption } from '@mezzanine-ui/react';
+import { FileIcon, HomeIcon, UserIcon } from '@mezzanine-ui/icons';
+
+function AppWithDualPanels() {
+  const [activatedPath, setActivatedPath] = useState(['首頁']);
+  const [leftOpen, setLeftOpen] = useState(true);
+  const [rightOpen, setRightOpen] = useState(false);
+
+  return (
+    <Layout>
+      <Navigation
+        activatedPath={activatedPath}
+        onOptionClick={(path) => {
+          if (path) setActivatedPath(path);
+        }}
+      >
+        <NavigationHeader title="Mezzanine" />
+        <NavigationOption icon={HomeIcon} title="首頁" />
+        <NavigationOption icon={FileIcon} title="文件" />
+        <NavigationOption icon={UserIcon} title="會員管理" />
+        <NavigationFooter />
+      </Navigation>
+
+      <Layout.LeftPanel defaultWidth={240} open={leftOpen}>
+        <div>
+          <h2>左側面板</h2>
+          <button onClick={() => setLeftOpen(false)}>關閉</button>
+        </div>
+      </Layout.LeftPanel>
+
+      <Layout.Main>
+        <div>
+          <h1>主要內容</h1>
+          {!leftOpen && <button onClick={() => setLeftOpen(true)}>開啟左側</button>}
+          {!rightOpen && <button onClick={() => setRightOpen(true)}>開啟右側</button>}
+        </div>
+      </Layout.Main>
+
+      <Layout.RightPanel defaultWidth={320} open={rightOpen}>
+        <div>
+          <h2>右側面板</h2>
+          <button onClick={() => setRightOpen(false)}>關閉</button>
+        </div>
+      </Layout.RightPanel>
+    </Layout>
+  );
+}
+```
+
+> **Props 說明（LayoutRightPanel / LayoutLeftPanel）**
+>
+> | Prop             | 型別                               | 說明                          |
+> | ---------------- | ---------------------------------- | ----------------------------- |
+> | `children`       | `ReactNode`                        | 面板內容                      |
+> | `className`      | `string`                           | 自訂 class                    |
+> | `defaultWidth`   | `number`                           | 初始寬度（px），最小值 240    |
+> | `onWidthChange`  | `(width: number) => void`          | 拖曳調整寬度時的回呼          |
+> | `open`           | `boolean`                          | 控制面板顯示 / 隱藏           |
+> | `scrollbarProps` | `Omit<ScrollbarProps, 'children'>` | 傳遞給內部 Scrollbar 的 props |
+
+---
+
+## 表單模式（Form Patterns）
+
+### 基本表單
+
+```tsx
+import { useState } from 'react';
+import { Button, FormField, Input, Select } from '@mezzanine-ui/react';
+
+const typeOptions = [
+  { id: 'personal', name: '個人' },
+  { id: 'business', name: '企業' },
+];
+
+function BasicForm() {
+  const [email, setEmail] = useState('');
+  const [name, setName] = useState('');
+  const [type, setType] = useState<{ id: string; name: string } | null>(null);
+
+  const handleSubmit = () => {
+    // 處理表單送出
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <FormField label="姓名" name="name" required>
+        <Input onChange={(e) => setName(e.target.value)} placeholder="請輸入姓名" value={name} />
+      </FormField>
+
+      <FormField hintText="我們不會公開您的 Email" label="Email" name="email" required>
+        <Input onChange={(e) => setEmail(e.target.value)} placeholder="請輸入 Email" value={email} />
+      </FormField>
+
+      <FormField label="類型" name="type">
+        <Select onChange={(value) => setType(value)} options={typeOptions} placeholder="請選擇類型" value={type} />
+      </FormField>
+
+      <div style={{ display: 'flex', gap: 8, justifyContent: 'flex-end' }}>
+        <Button onClick={() => {}} variant="base-secondary">
+          取消
+        </Button>
+        <Button onClick={handleSubmit} variant="base-primary">
+          送出
+        </Button>
+      </div>
+    </form>
+  );
+}
+```
+
+### 表單驗證
+
+```tsx
+import { useState } from 'react';
+import { FormField, Input } from '@mezzanine-ui/react';
+import type { SeverityWithInfo } from '@mezzanine-ui/system/severity';
+
+function FormWithValidation() {
+  const [email, setEmail] = useState('');
+  const [error, setError] = useState('');
+
+  const validateEmail = (value: string) => {
+    if (!value) {
+      setError('Email 為必填');
+      return false;
+    }
+    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) {
+      setError('Email 格式不正確');
+      return false;
+    }
+    setError('');
+    return true;
+  };
+
+  const severity: SeverityWithInfo = error ? 'error' : 'info';
+
+  return (
+    <FormField hintText={error || undefined} label="Email" name="email" required severity={severity}>
+      <Input
+        onChange={(e) => {
+          setEmail(e.target.value);
+          validateEmail(e.target.value);
+        }}
+        placeholder="請輸入 Email"
+        value={email}
+      />
+    </FormField>
+  );
+}
+```
+
+### 搜尋表單
+
+```tsx
+import { useState } from 'react';
+import { Button, Input } from '@mezzanine-ui/react';
+
+function SearchForm() {
+  const [keyword, setKeyword] = useState('');
+
+  const handleSearch = () => {
+    // 執行搜尋
+  };
+
+  return (
+    <div style={{ display: 'flex', gap: 8 }}>
+      <Input clearable onChange={(e) => setKeyword(e.target.value)} placeholder="搜尋..." value={keyword} variant="search" />
+      <Button onClick={handleSearch} variant="base-primary">
+        搜尋
+      </Button>
+    </div>
+  );
+}
+```
+
+---
+
+## 表格模式（Table Patterns）
+
+### 基本資料表格
+
+```tsx
+import { useState } from 'react';
+import { Button, Modal, Table, Tag } from '@mezzanine-ui/react';
+
+function DataTable() {
+  const [deleteTarget, setDeleteTarget] = useState<DataItem | null>(null);
+
+  const handleDeleteConfirm = () => {
+    if (deleteTarget) {
+      handleDelete(deleteTarget.id);
+      setDeleteTarget(null);
+    }
+  };
+
+  const columns = [
+    {
+      dataIndex: 'name',
+      title: '名稱',
+    },
+    {
+      dataIndex: 'status',
+      render: (status: string) => <Tag label={status === 'active' ? '啟用' : '停用'} type="static" />,
+      title: '狀態',
+    },
+    {
+      dataIndex: 'createdAt',
+      render: (date: string) => new Date(date).toLocaleDateString(),
+      title: '建立時間',
+    },
+    {
+      render: (_: unknown, record: DataItem) => (
+        <div style={{ display: 'flex', gap: 8 }}>
+          <Button onClick={() => handleEdit(record)} size="minor" variant="base-text-link">
+            編輯
+          </Button>
+          <Button onClick={() => setDeleteTarget(record)} size="minor" variant="destructive-text-link">
+            刪除
+          </Button>
+        </div>
+      ),
+      title: '操作',
+    },
+  ];
+
+  const data = [
+    { createdAt: '2024-01-01', id: '1', name: '項目 1', status: 'active' },
+    { createdAt: '2024-01-02', id: '2', name: '項目 2', status: 'inactive' },
+  ];
+
+  return (
+    <>
+      <Table columns={columns} dataSource={data} />
+      <Modal cancelText="取消" confirmText="刪除" modalType="standard" onCancel={() => setDeleteTarget(null)} onClose={() => setDeleteTarget(null)} onConfirm={handleDeleteConfirm} open={!!deleteTarget} showModalFooter showModalHeader size="narrow" title="確認刪除">
+        確定要刪除「{deleteTarget?.name}」嗎？
+      </Modal>
+    </>
+  );
+}
+```
+
+### 可選取表格
+
+```tsx
+import { useState } from 'react';
+import { Button, Table } from '@mezzanine-ui/react';
+import type { TableRowSelection } from '@mezzanine-ui/react';
+
+function SelectableTable() {
+  const [selectedKeys, setSelectedKeys] = useState<string[]>([]);
+
+  const rowSelection: TableRowSelection = {
+    onChange: (keys) => setSelectedKeys(keys as string[]),
+    selectedRowKeys: selectedKeys,
+  };
+
+  const handleBatchDelete = () => {
+    // 批次刪除選取項目
+  };
+
+  return (
+    <div>
+      {selectedKeys.length > 0 && (
+        <div style={{ marginBottom: 16 }}>
+          <span>已選取 {selectedKeys.length} 筆</span>
+          <Button onClick={handleBatchDelete} size="sub" variant="destructive-secondary">
+            批次刪除
+          </Button>
+        </div>
+      )}
+      <Table columns={columns} dataSource={data} rowSelection={rowSelection} />
+    </div>
+  );
+}
+```
+
+### 分頁表格
+
+```tsx
+import { useEffect, useState } from 'react';
+import { Pagination, Table, usePagination } from '@mezzanine-ui/react';
+
+function PaginatedTable() {
+  const [data, setData] = useState([]);
+  const [total, setTotal] = useState(0);
+  const [currentPage, setCurrentPage] = useState(1);
+
+  const pagination = usePagination({
+    current: currentPage,
+    onChange: (page) => {
+      setCurrentPage(page);
+      fetchData(page, 10);
+    },
+    pageSize: 10,
+    total,
+  });
+
+  useEffect(() => {
+    fetchData(1, 10);
+  }, []);
+
+  return (
+    <div>
+      <Table columns={columns} dataSource={data} />
+      <div style={{ display: 'flex', justifyContent: 'flex-end', marginTop: 16 }}>
+        <Pagination {...pagination} />
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+## 對話框模式（Dialog Patterns）
+
+### 確認對話框
+
+```tsx
+import { Modal } from '@mezzanine-ui/react';
+
+function ConfirmModal({ onClose, onConfirm, open }) {
+  return (
+    <Modal cancelText="取消" confirmText="刪除" modalType="standard" onCancel={onClose} onClose={onClose} onConfirm={onConfirm} open={open} showModalFooter showModalHeader size="narrow" title="確認刪除">
+      確定要刪除此項目嗎？此操作無法復原。
+    </Modal>
+  );
+}
+```
+
+### 表單對話框
+
+```tsx
+import { useState } from 'react';
+import { FormField, Input, Modal } from '@mezzanine-ui/react';
+
+function FormModal({ onClose, onSubmit, open }) {
+  const [loading, setLoading] = useState(false);
+  const [name, setName] = useState('');
+
+  const handleSubmit = async () => {
+    setLoading(true);
+    try {
+      await onSubmit({ name });
+      onClose();
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <Modal cancelText="取消" confirmText="確認" loading={loading} modalType="standard" onCancel={onClose} onClose={onClose} onConfirm={handleSubmit} open={open} showModalFooter showModalHeader title="新增項目">
+      <FormField label="名稱" name="name" required>
+        <Input onChange={(e) => setName(e.target.value)} placeholder="請輸入名稱" value={name} />
+      </FormField>
+    </Modal>
+  );
+}
+```
+
+### 抽屜詳情頁
+
+```tsx
+import { Button, Description, DescriptionContent, DescriptionGroup, Drawer, DrawerBody, DrawerFooter, DrawerHeader } from '@mezzanine-ui/react';
+
+function DetailDrawer({ data, onClose, open }) {
+  return (
+    <Drawer onClose={onClose} open={open}>
+      <DrawerHeader title="項目詳情" />
+      <DrawerBody>
+        <DescriptionGroup>
+          <Description title="名稱">
+            <DescriptionContent>{data?.name}</DescriptionContent>
+          </Description>
+          <Description title="狀態">
+            <DescriptionContent>{data?.status}</DescriptionContent>
+          </Description>
+          <Description title="建立時間">
+            <DescriptionContent>{data?.createdAt}</DescriptionContent>
+          </Description>
+        </DescriptionGroup>
+      </DrawerBody>
+      <DrawerFooter>
+        <Button onClick={onClose} variant="base-secondary">
+          取消
+        </Button>
+        <Button onClick={() => handleEdit(data)} variant="base-primary">
+          編輯
+        </Button>
+      </DrawerFooter>
+    </Drawer>
+  );
+}
+```
+
+---
+
+## 導航模式（Navigation Patterns）
+
+### 側邊導航
+
+```tsx
+import { useState } from 'react';
+import { Navigation, NavigationFooter, NavigationHeader, NavigationOption, NavigationOptionCategory, NavigationUserMenu } from '@mezzanine-ui/react';
+import { FileIcon, HomeIcon, SettingIcon } from '@mezzanine-ui/icons';
+
+function SideNavigation() {
+  const [activeKey, setActiveKey] = useState('home');
+
+  return (
+    <Navigation>
+      <NavigationHeader title="品牌名稱" />
+
+      <NavigationOptionCategory title="主選單">
+        <NavigationOption active={activeKey === 'home'} icon={HomeIcon} onTriggerClick={() => setActiveKey('home')} title="首頁" />
+        <NavigationOption active={activeKey === 'documents'} icon={FileIcon} onTriggerClick={() => setActiveKey('documents')} title="文件" />
+      </NavigationOptionCategory>
+
+      <NavigationOptionCategory title="設定">
+        <NavigationOption active={activeKey === 'settings'} icon={SettingIcon} onTriggerClick={() => setActiveKey('settings')} title="系統設定" />
+      </NavigationOptionCategory>
+
+      <NavigationFooter>
+        <NavigationUserMenu imgSrc="/avatar.png" />
+      </NavigationFooter>
+    </Navigation>
+  );
+}
+```
+
+### 分頁導航（Tab）
+
+```tsx
+import { useState } from 'react';
+import { Tab, TabItem } from '@mezzanine-ui/react';
+import type { Key } from 'react';
+
+function TabNavigation() {
+  const [activeKey, setActiveKey] = useState<Key>('overview');
+
+  return (
+    <div>
+      <Tab activeKey={activeKey} onChange={(key) => setActiveKey(key)}>
+        <TabItem key="overview">總覽</TabItem>
+        <TabItem key="details">詳細資訊</TabItem>
+        <TabItem key="history">歷史紀錄</TabItem>
+      </Tab>
+
+      {activeKey === 'overview' && <OverviewContent />}
+      {activeKey === 'details' && <DetailsContent />}
+      {activeKey === 'history' && <HistoryContent />}
+    </div>
+  );
+}
+```
+
+---
+
+## 載入狀態（Loading States）
+
+### 頁面載入
+
+```tsx
+import { useState } from 'react';
+import { Skeleton, Spin } from '@mezzanine-ui/react';
+
+function PageLoading() {
+  const [loading, setLoading] = useState(true);
+  const [data, setData] = useState(null);
+
+  if (loading) {
+    return (
+      <div style={{ padding: 24, textAlign: 'center' }}>
+        <Spin description="載入中..." loading />
+      </div>
+    );
+  }
+
+  return <PageContent data={data} />;
+}
+
+// 或使用骨架屏
+function PageWithSkeleton() {
+  const [loading, setLoading] = useState(true);
+
+  if (loading) {
+    return (
+      <div style={{ padding: 24 }}>
+        <Skeleton height={24} width={200} />
+        <Skeleton height={16} style={{ marginTop: 16 }} width="100%" />
+        <Skeleton height={16} style={{ marginTop: 8 }} width="100%" />
+        <Skeleton height={16} style={{ marginTop: 8 }} width="80%" />
+      </div>
+    );
+  }
+
+  return <PageContent />;
+}
+```
+
+### 按鈕載入
+
+```tsx
+import { useState } from 'react';
+import { Button } from '@mezzanine-ui/react';
+
+function SubmitButton() {
+  const [loading, setLoading] = useState(false);
+
+  const handleClick = async () => {
+    setLoading(true);
+    try {
+      await submitData();
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <Button loading={loading} onClick={handleClick} variant="base-primary">
+      送出
+    </Button>
+  );
+}
+```
+
+---
+
+## 錯誤處理（Error Handling）
+
+### 表單錯誤
+
+```tsx
+import { FormField, Input, InlineMessageGroup } from '@mezzanine-ui/react';
+
+function FormWithErrors({ errors }) {
+  const nameError = errors.find((e) => e.field === 'name');
+
+  return (
+    <div>
+      {errors.length > 0 && (
+        <InlineMessageGroup
+          items={errors.map((err) => ({
+            content: err.message,
+            key: err.field,
+            severity: 'error' as const,
+          }))}
+        />
+      )}
+
+      <FormField hintText={nameError?.message} label="名稱" name="name" required severity={nameError ? 'error' : 'info'}>
+        <Input placeholder="請輸入名稱" />
+      </FormField>
+    </div>
+  );
+}
+```
+
+### 空狀態
+
+```tsx
+import { Button, Empty } from '@mezzanine-ui/react';
+
+function EmptyState() {
+  return (
+    <Empty title="尚無資料" type="initial-data">
+      <Button onClick={() => handleCreate()}>建立第一筆資料</Button>
+    </Empty>
+  );
+}
+```
+
+### 結果狀態頁
+
+```tsx
+import { ResultState } from '@mezzanine-ui/react';
+
+function SuccessResult() {
+  return (
+    <ResultState
+      actions={{
+        primaryButton: { children: '繼續新增', onClick: () => reset() },
+        secondaryButton: { children: '返回列表', onClick: () => navigate('/list') },
+      }}
+      description="您的變更已成功儲存"
+      title="操作成功"
+      type="success"
+    />
+  );
+}
+
+function ErrorResult() {
+  return (
+    <ResultState
+      actions={{
+        secondaryButton: { children: '重試', onClick: () => retry() },
+      }}
+      description="發生錯誤，請稍後再試"
+      title="操作失敗"
+      type="error"
+    />
+  );
+}
+```
+
+---
+
+## 通知提示（Notifications）
+
+### Message 訊息提示
+
+```tsx
+import { Button, Message } from '@mezzanine-ui/react';
+
+function NotificationExample() {
+  const handleSave = async () => {
+    try {
+      await saveData();
+      Message.success('儲存成功');
+    } catch (error) {
+      Message.error('儲存失敗，請稍後再試');
+    }
+  };
+
+  return (
+    <Button onClick={handleSave} variant="base-primary">
+      儲存
+    </Button>
+  );
+}
+```
+
+### 通知中心
+
+```tsx
+import { Button, NotificationCenter } from '@mezzanine-ui/react';
+
+function NotificationExample() {
+  const showNotification = () => {
+    NotificationCenter.success({
+      description: '您的變更已成功儲存',
+      duration: 5000,
+      title: '操作成功',
+    });
+  };
+
+  const showError = () => {
+    NotificationCenter.error({
+      description: '發生錯誤，請聯絡系統管理員',
+      duration: 0, // 不自動關閉
+      title: '操作失敗',
+    });
+  };
+
+  return (
+    <div>
+      <Button onClick={showNotification}>顯示成功通知</Button>
+      <Button onClick={showError}>顯示錯誤通知</Button>
+    </div>
+  );
+}
+```
+
+### AlertBanner 警示橫幅
+
+```tsx
+import { useState } from 'react';
+import { AlertBanner } from '@mezzanine-ui/react';
+
+function PageWithBanner() {
+  const [showBanner, setShowBanner] = useState(true);
+
+  return (
+    <div>
+      {showBanner && <AlertBanner message="系統將於今晚 22:00 進行維護，預計停機 2 小時。" onClose={() => setShowBanner(false)} severity="warning" />}
+      <PageContent />
+    </div>
+  );
+}
+```

package/README.md

@@ -28,13 +28,12 @@ Create a `main.scss` and import it at your app entry point:
 
 :root {
   @include mzn-system.common-variables('default');
-  @include mzn-system.colors();
-  @include mzn-system.palette-variables(light);
+  @include mzn-system.colors(light);
 }
 
 /* Optional: dark mode */
 [data-theme='dark'] {
-  @include mzn-system.palette-variables(dark);
+  @include mzn-system.colors(dark);
 }
 
 /* Optional: compact density */

package/llms.txt

@@ -43,8 +43,8 @@ import {
   NavigationUserMenu,
 } from '@mezzanine-ui/react/Navigation';
 
-// ContentHeader (page-level header with back button + action slots)
-import ContentHeader from '@mezzanine-ui/react/ContentHeader';
+// ContentHeader (deprecated — sub-path import only, not in main barrel export)
+// import ContentHeader from '@mezzanine-ui/react/ContentHeader';
 
 // Form layout tokens from core (used with FormField)
 import {
@@ -76,8 +76,8 @@ Required styles — create a `main.scss` and import it at your app entry point.
 }
 
 /* Optional: light/dark palette theming */
-:root { @include mzn-system.palette-variables(light); }
-[data-theme='dark'] { @include mzn-system.palette-variables(dark); }
+:root { @include mzn-system.colors(light); }
+[data-theme='dark'] { @include mzn-system.colors(dark); }
 
 /* Optional: compact density */
 [data-density='compact'] { @include mzn-system.common-variables(compact); }
@@ -171,11 +171,25 @@ Message.error('操作失敗，請稍後再試');
 
 ## Common Pitfalls for AI Assistants
 
-**Typography `variant` is not h1–h6.** The prop is named `variant` but its type is `TypographySemanticType` — a design-system semantic scale, not HTML heading levels. Valid values are `h1`, `h2`, `h3` (no h4/h5/h6), then `body`, `body-highlight`, `body-mono`, `caption`, `caption-highlight`, `annotation`, `annotation-highlight`, `button`, `input`, `label-primary`, `label-secondary`, and a few others. Never use `h4`, `h5`, or `h6`.
+**Typography `variant` only has h1–h3, not h4–h6.** The prop type is `TypographySemanticType` — a design-system semantic scale, not HTML heading levels. The complete set of valid values is:
+
+| Group | Variants |
+|-------|---------|
+| Heading | `h1`, `h2`, `h3` |
+| Body | `body`, `body-highlight`, `body-mono`, `body-mono-highlight` |
+| Text link | `text-link-body`, `text-link-caption` |
+| Caption | `caption`, `caption-highlight` |
+| Annotation | `annotation`, `annotation-highlight` |
+| Button | `button`, `button-highlight` |
+| Input | `input`, `input-mono`, `input-highlight` |
+| Label | `label-primary`, `label-primary-highlight`, `label-secondary` |
+
+Never use `h4`, `h5`, or `h6` — they do not exist.
 ```tsx
-<Typography variant="h1">Title</Typography>      // ✅
-<Typography variant="body">Body text</Typography> // ✅
-<Typography variant="h5">Subtitle</Typography>    // ❌ h5 does not exist
+<Typography variant="h1">Title</Typography>            // ✅
+<Typography variant="body-highlight">Bold</Typography> // ✅
+<Typography variant="text-link-body">Link</Typography> // ✅
+<Typography variant="h5">Subtitle</Typography>         // ❌ h5 does not exist
 ```
 
 **Button icons use `icon` + `iconType`, not `prefix`/`suffix` JSX.** Pass an icon definition object (from `@mezzanine-ui/icons`) to the `icon` prop and set position via `iconType`: `"leading"` | `"trailing"` | `"icon-only"`. Do not wrap `<Icon />` in `prefix` or `suffix` props — those props do not exist on Button.
@@ -196,5 +210,6 @@ import { PlusIcon } from '@mezzanine-ui/icons';
 ## Further Reference
 
 - Full component index with descriptions: `packages/react/COMPONENTS.md`
+- Common UI pattern examples (Layout, Form, Table, Dialog, etc.): `packages/react/PATTERNS.md`
 - Complete prop types and JSDoc: `*.d.ts` files in the published package (or `packages/react/src/<ComponentName>/index.tsx`)
 - GitHub: https://github.com/Mezzanine-UI/mezzanine

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mezzanine-ui/react",
-  "version": "1.0.0-rc.8",
+  "version": "1.0.0",
   "description": "React components for mezzanine-ui",
   "author": "Mezzanine",
   "repository": {
@@ -32,9 +32,9 @@
     "@floating-ui/dom": "^1.7.4",
     "@floating-ui/react-dom": "^2.1.6",
     "@hello-pangea/dnd": "^18.0.1",
-    "@mezzanine-ui/core": "1.0.0-rc.8",
-    "@mezzanine-ui/icons": "1.0.0-rc.8",
-    "@mezzanine-ui/system": "1.0.0-rc.8",
+    "@mezzanine-ui/core": "1.0.0",
+    "@mezzanine-ui/icons": "1.0.0",
+    "@mezzanine-ui/system": "1.0.0",
     "@tanstack/react-virtual": "^3.13.13",
     "@types/react-transition-group": "^4.4.12",
     "clsx": "^2.1.1",