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

package/Checkbox/CheckboxGroup.d.ts

@@ -123,7 +123,45 @@ interface CheckboxGroupChildrenInputProps extends CheckboxGroupBaseProps {
 }
 export type CheckboxGroupProps = CheckboxGroupOptionsInputProps | CheckboxGroupChildrenInputProps;
 /**
- * The react component for `mezzanine` checkbox group.
+ * 核取方塊群組元件，用於管理一組具有相同 `name` 的核取方塊。
+ *
+ * 支援透過 `options` 陣列或 `children` 傳入子元件兩種方式渲染選項，並可透過
+ * `layout` 控制水平或垂直排列。啟用 `level` 設定可顯示「全選」控制核取方塊，
+ * 勾選狀態會自動計算 indeterminate 中間態；`onChange` 回呼透過 `event.target.values`
+ * 提供最新已選取的值陣列。
+ *
+ * @example
+ * ```tsx
+ * import CheckboxGroup from '@mezzanine-ui/react/CheckboxGroup';
+ * import Checkbox from '@mezzanine-ui/react/Checkbox';
+ *
+ * // 使用 options 陣列
+ * <CheckboxGroup
+ *   name="fruits"
+ *   defaultValue={['apple']}
+ *   options={[
+ *     { label: '蘋果', value: 'apple' },
+ *     { label: '香蕉', value: 'banana' },
+ *     { label: '橘子', value: 'orange' },
+ *   ]}
+ *   onChange={(e) => console.log(e.target.values)}
+ * />
+ *
+ * // 使用 children 方式，垂直排列
+ * <CheckboxGroup name="options" layout="vertical">
+ *   <Checkbox label="選項一" value="a" />
+ *   <Checkbox label="選項二" value="b" />
+ * </CheckboxGroup>
+ *
+ * // 啟用全選控制
+ * <CheckboxGroup
+ *   name="items"
+ *   options={[{ label: '項目 A', value: 'a' }, { label: '項目 B', value: 'b' }]}
+ *   level={{ active: true, label: '全選' }}
+ * />
+ * ```
+ *
+ * @see {@link Checkbox} 單一核取方塊元件
  */
 declare const CheckboxGroup: import("react").ForwardRefExoticComponent<CheckboxGroupProps & import("react").RefAttributes<HTMLDivElement>>;
 export default CheckboxGroup;

package/Checkbox/CheckboxGroup.js

@@ -23,7 +23,45 @@ const equalityFn = (a, b) => {
     return sortedA.every((val, idx) => val === sortedB[idx]);
 };
 /**
- * The react component for `mezzanine` checkbox group.
+ * 核取方塊群組元件，用於管理一組具有相同 `name` 的核取方塊。
+ *
+ * 支援透過 `options` 陣列或 `children` 傳入子元件兩種方式渲染選項，並可透過
+ * `layout` 控制水平或垂直排列。啟用 `level` 設定可顯示「全選」控制核取方塊，
+ * 勾選狀態會自動計算 indeterminate 中間態；`onChange` 回呼透過 `event.target.values`
+ * 提供最新已選取的值陣列。
+ *
+ * @example
+ * ```tsx
+ * import CheckboxGroup from '@mezzanine-ui/react/CheckboxGroup';
+ * import Checkbox from '@mezzanine-ui/react/Checkbox';
+ *
+ * // 使用 options 陣列
+ * <CheckboxGroup
+ *   name="fruits"
+ *   defaultValue={['apple']}
+ *   options={[
+ *     { label: '蘋果', value: 'apple' },
+ *     { label: '香蕉', value: 'banana' },
+ *     { label: '橘子', value: 'orange' },
+ *   ]}
+ *   onChange={(e) => console.log(e.target.values)}
+ * />
+ *
+ * // 使用 children 方式，垂直排列
+ * <CheckboxGroup name="options" layout="vertical">
+ *   <Checkbox label="選項一" value="a" />
+ *   <Checkbox label="選項二" value="b" />
+ * </CheckboxGroup>
+ *
+ * // 啟用全選控制
+ * <CheckboxGroup
+ *   name="items"
+ *   options={[{ label: '項目 A', value: 'a' }, { label: '項目 B', value: 'b' }]}
+ *   level={{ active: true, label: '全選' }}
+ * />
+ * ```
+ *
+ * @see {@link Checkbox} 單一核取方塊元件
  */
 const CheckboxGroup = forwardRef(function CheckboxGroup(props, ref) {
     var _a, _b, _c, _d, _e;
@@ -174,10 +212,18 @@ const CheckboxGroup = forwardRef(function CheckboxGroup(props, ref) {
             const syntheticEvent = assignCheckboxGroupValuesToEvent(event, newValue, resolvedName);
             onChangeProp(syntheticEvent);
         }
-    }, [canRenderLevelControl, level, onChangeProp, normalizedOptions, resolvedName, setValue, value]);
+    }, [
+        canRenderLevelControl,
+        level,
+        onChangeProp,
+        normalizedOptions,
+        resolvedName,
+        setValue,
+        value,
+    ]);
     return (jsxs("div", { ...rest, ref: ref, "aria-orientation": ariaOrientation, className: cx(checkboxGroupClasses.host, {
             [checkboxGroupClasses.nested]: isLevelActive,
-        }, className), role: role, children: [canRenderLevelControl && !shouldRenderLevelInsideContent && (jsx(Checkbox, { checked: levelChecked, disabled: disabled || (level === null || level === void 0 ? void 0 : level.disabled), id: `${resolvedName}-level-control`, indeterminate: levelIndeterminate, label: (_b = level === null || level === void 0 ? void 0 : level.label) !== null && _b !== void 0 ? _b : '', mode: (_c = level === null || level === void 0 ? void 0 : level.mode) !== null && _c !== void 0 ? _c : 'default', name: `${resolvedName}-level-control`, onChange: handleLevelControlChange })), jsxs("div", { className: cx(checkboxGroupClasses.contentWrapper, checkboxGroupClasses.layout(layout), mode && checkboxGroupClasses.mode(mode)), children: [canRenderLevelControl && shouldRenderLevelInsideContent && (jsxs(Fragment, { children: [jsx(Checkbox, { checked: levelChecked, disabled: disabled || (level === null || level === void 0 ? void 0 : level.disabled), id: `${resolvedName}-level-control`, indeterminate: levelIndeterminate, label: (_d = level === null || level === void 0 ? void 0 : level.label) !== null && _d !== void 0 ? _d : '', mode: (_e = level === null || level === void 0 ? void 0 : level.mode) !== null && _e !== void 0 ? _e : 'default', name: `${resolvedName}-level-control`, onChange: handleLevelControlChange }), isHorizontalLayout && jsx("i", { className: checkboxGroupClasses.levelControlSeparator })] })), jsx(CheckboxGroupContext.Provider, { value: context, children: children })] })] }));
+        }, className), role: role, children: [canRenderLevelControl && !shouldRenderLevelInsideContent && (jsx(Checkbox, { checked: levelChecked, disabled: disabled || (level === null || level === void 0 ? void 0 : level.disabled), id: `${resolvedName}-level-control`, indeterminate: levelIndeterminate, label: (_b = level === null || level === void 0 ? void 0 : level.label) !== null && _b !== void 0 ? _b : '', mode: (_c = level === null || level === void 0 ? void 0 : level.mode) !== null && _c !== void 0 ? _c : 'default', name: `${resolvedName}-level-control`, onChange: handleLevelControlChange })), jsxs("div", { className: cx(checkboxGroupClasses.contentWrapper, checkboxGroupClasses.layout(layout), mode && checkboxGroupClasses.mode(mode)), children: [canRenderLevelControl && shouldRenderLevelInsideContent && (jsxs(Fragment, { children: [jsx(Checkbox, { checked: levelChecked, disabled: disabled || (level === null || level === void 0 ? void 0 : level.disabled), id: `${resolvedName}-level-control`, indeterminate: levelIndeterminate, label: (_d = level === null || level === void 0 ? void 0 : level.label) !== null && _d !== void 0 ? _d : '', mode: (_e = level === null || level === void 0 ? void 0 : level.mode) !== null && _e !== void 0 ? _e : 'default', name: `${resolvedName}-level-control`, onChange: handleLevelControlChange }), isHorizontalLayout && (jsx("i", { className: checkboxGroupClasses.levelControlSeparator }))] })), jsx(CheckboxGroupContext.Provider, { value: context, children: children })] })] }));
 });
 
 export { assignCheckboxGroupValuesToEvent, CheckboxGroup as default };

package/Cropper/Cropper.d.ts

@@ -1,8 +1,8 @@
 import type { ReactElement } from 'react';
-import type { ModalProps } from '../Modal';
+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'> & {
+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/Cropper/Cropper.js

@@ -47,7 +47,6 @@ const CropperModalComponent = forwardRef(function CropperModal(props, ref) {
         ? {
             showModalFooter: true,
             confirmText,
-            showCancelButton: true,
             cancelText,
             onCancel: handleCancel,
             onConfirm: handleConfirm,
@@ -97,12 +96,12 @@ const CropperModalNotifier = (props) => {
         onConfirm: handleConfirm,
         open: true,
     };
-    return (jsx(CropperModal, { ...mergedModalProps }));
+    return jsx(CropperModal, { ...mergedModalProps });
 };
 const cropperModalNotifier = createNotifier({
     render: (notifierProps) => {
         const { key, ...restProps } = notifierProps;
-        return (jsx(CropperModalNotifier, { ...restProps, notifierKey: key }));
+        return jsx(CropperModalNotifier, { ...restProps, notifierKey: key });
     },
 });
 CropperModal.open = (options) => new Promise((resolve) => {

package/Cropper/CropperElement.js

@@ -883,7 +883,7 @@ const CropperElement = forwardRef(function CropperElement(props, ref) {
             return 'grabbing';
         return 'default';
     }, [cropArea, isDragging, isDraggingImage]);
-    return (jsxs("div", { className: cropperClasses.element, ref: elementRef, children: [jsx(Component, { ...rest, className: cx(cropperClasses.host, cropperClasses.size(size), className), onMouseDown: handleMouseDown, ref: composedRef, style: { cursor: cursorStyle, width: '100%', ...rest.style }, children: children }), cropArea && tagPosition && (jsxs(Typography, { className: cropperClasses.tag, color: "text-fixed-light", style: {
+    return (jsxs("div", { className: cropperClasses.element, ref: elementRef, children: [jsx(Component, { ...rest, className: cx(cropperClasses.host, cropperClasses.size(size), className), onMouseDown: handleMouseDown, ref: composedRef, style: { cursor: cursorStyle, width: '100%', ...rest.style }, children: children }), cropArea && tagPosition && (jsxs(Typography, { className: cropperClasses.tag, color: "text-fixed-light", variant: "label-secondary", style: {
                     left: tagPosition.left,
                     top: tagPosition.top,
                 }, children: [Math.round((tagCropArea || cropArea).width), " \u00D7", ' ', Math.round((tagCropArea || cropArea).height), " px"] })), jsx("div", { className: cropperClasses.controls, children: jsx(Slider, { min: MIN_SCALE, max: MAX_SCALE, step: SCALE_STEP, value: scale, onChange: handleSliderChange, suffixIcon: PlusIcon, prefixIcon: MinusIcon }) })] }));

package/Cropper/utils/cropper-calculations.d.ts

@@ -14,7 +14,7 @@ export interface InitialCropAreaResult {
     imagePosition: ImagePosition;
 }
 /**
- * Calculate base scale for image to fit canvas height.
+ * Calculate base scale for image to cover canvas (both dimensions).
  */
 export declare function getBaseScale(rect: DOMRect, img: HTMLImageElement): number;
 /**

package/Cropper/utils/cropper-calculations.js

@@ -1,10 +1,10 @@
 /**
- * Calculate base scale for image to fit canvas height.
+ * Calculate base scale for image to cover canvas (both dimensions).
  */
 function getBaseScale(rect, img) {
-    if (!rect.height)
+    if (!rect.height || !rect.width)
         return 1;
-    return img.height / rect.height;
+    return Math.min(img.height / rect.height, img.width / rect.width);
 }
 /**
  * Calculate base display size of image.
@@ -25,22 +25,24 @@ function calculateInitialCropArea(img, rect, aspectRatio) {
     const baseDisplayHeight = img.height / baseScale;
     const initialOffsetX = (rect.width - baseDisplayWidth) / 2;
     const initialOffsetY = (rect.height - baseDisplayHeight) / 2;
-    let initialWidth = baseDisplayWidth;
-    let initialHeight = baseDisplayHeight;
+    let initialWidth = rect.width;
+    let initialHeight = rect.height;
     if (aspectRatio) {
-        const maxWidthByHeight = baseDisplayHeight * aspectRatio;
-        const maxHeightByWidth = baseDisplayWidth / aspectRatio;
-        if (maxWidthByHeight <= baseDisplayWidth) {
-            initialWidth = maxWidthByHeight;
-            initialHeight = baseDisplayHeight;
+        const maxWidthByCanvasHeight = rect.height * aspectRatio;
+        const maxHeightByCanvasWidth = rect.width / aspectRatio;
+        if (maxWidthByCanvasHeight <= rect.width) {
+            // Height is the limiting factor → crop fills full canvas height
+            initialWidth = maxWidthByCanvasHeight;
+            initialHeight = rect.height;
         }
         else {
-            initialWidth = baseDisplayWidth;
-            initialHeight = maxHeightByWidth;
+            // Width is the limiting factor → crop fills full canvas width
+            initialWidth = rect.width;
+            initialHeight = maxHeightByCanvasWidth;
         }
     }
-    const initialX = initialOffsetX + (baseDisplayWidth - initialWidth) / 2;
-    const initialY = initialOffsetY + (baseDisplayHeight - initialHeight) / 2;
+    const initialX = (rect.width - initialWidth) / 2;
+    const initialY = (rect.height - initialHeight) / 2;
     return {
         baseDisplayHeight,
         baseDisplayWidth,

package/DatePicker/DatePicker.d.ts

@@ -35,8 +35,42 @@ export interface DatePickerProps extends Omit<DatePickerCalendarProps, 'anchor'
     referenceDate?: DateType;
 }
 /**
- * The react component for `mezzanine` date picker.
- * Notice that any component related to date-picker should be used along with `CalendarContext`. <br />
+ * 日期選擇器元件，透過點擊輸入框或日曆圖示開啟日曆彈出層進行日期選取。
+ *
+ * 必須搭配 `CalendarContext`（`CalendarConfigProvider`）使用，以提供語系與格式化函式。
+ * 支援 `day`、`week`、`month`、`quarter`、`half-year`、`year` 等多種選取模式，
+ * 可透過 `isDateDisabled` 等相關 props 限制可選日期範圍，並支援受控（`value`）
+ * 與非受控（`defaultValue`）兩種使用方式。
+ *
+ * @example
+ * ```tsx
+ * import DatePicker from '@mezzanine-ui/react/DatePicker';
+ * import CalendarConfigProvider from '@mezzanine-ui/react/CalendarConfigProvider';
+ *
+ * // 基本用法（需包覆在 CalendarConfigProvider 內）
+ * <CalendarConfigProvider methods={...}>
+ *   <DatePicker onChange={(date) => console.log(date)} />
+ * </CalendarConfigProvider>
+ *
+ * // 受控用法
+ * const [date, setDate] = useState<DateType>();
+ * <CalendarConfigProvider methods={...}>
+ *   <DatePicker value={date} onChange={setDate} />
+ * </CalendarConfigProvider>
+ *
+ * // 月份選取模式，禁用過去月份
+ * <CalendarConfigProvider methods={...}>
+ *   <DatePicker
+ *     mode="month"
+ *     isMonthDisabled={(iso) => iso < '2024-01'}
+ *     onChange={setDate}
+ *   />
+ * </CalendarConfigProvider>
+ * ```
+ *
+ * @see {@link DateRangePicker} 日期範圍選擇器元件
+ * @see {@link DateTimePicker} 日期時間選擇器元件
+ * @see {@link Calendar} 日曆元件
  */
 declare const DatePicker: import("react").ForwardRefExoticComponent<DatePickerProps & import("react").RefAttributes<HTMLDivElement>>;
 export default DatePicker;

package/DatePicker/DatePicker.js

@@ -14,8 +14,42 @@ import PickerTrigger from '../Picker/PickerTrigger.js';
 import cx from 'clsx';
 
 /**
- * The react component for `mezzanine` date picker.
- * Notice that any component related to date-picker should be used along with `CalendarContext`. <br />
+ * 日期選擇器元件，透過點擊輸入框或日曆圖示開啟日曆彈出層進行日期選取。
+ *
+ * 必須搭配 `CalendarContext`（`CalendarConfigProvider`）使用，以提供語系與格式化函式。
+ * 支援 `day`、`week`、`month`、`quarter`、`half-year`、`year` 等多種選取模式，
+ * 可透過 `isDateDisabled` 等相關 props 限制可選日期範圍，並支援受控（`value`）
+ * 與非受控（`defaultValue`）兩種使用方式。
+ *
+ * @example
+ * ```tsx
+ * import DatePicker from '@mezzanine-ui/react/DatePicker';
+ * import CalendarConfigProvider from '@mezzanine-ui/react/CalendarConfigProvider';
+ *
+ * // 基本用法（需包覆在 CalendarConfigProvider 內）
+ * <CalendarConfigProvider methods={...}>
+ *   <DatePicker onChange={(date) => console.log(date)} />
+ * </CalendarConfigProvider>
+ *
+ * // 受控用法
+ * const [date, setDate] = useState<DateType>();
+ * <CalendarConfigProvider methods={...}>
+ *   <DatePicker value={date} onChange={setDate} />
+ * </CalendarConfigProvider>
+ *
+ * // 月份選取模式，禁用過去月份
+ * <CalendarConfigProvider methods={...}>
+ *   <DatePicker
+ *     mode="month"
+ *     isMonthDisabled={(iso) => iso < '2024-01'}
+ *     onChange={setDate}
+ *   />
+ * </CalendarConfigProvider>
+ * ```
+ *
+ * @see {@link DateRangePicker} 日期範圍選擇器元件
+ * @see {@link DateTimePicker} 日期時間選擇器元件
+ * @see {@link Calendar} 日曆元件
  */
 const DatePicker = forwardRef(function DatePicker(props, ref) {
     var _a;

package/DateRangePicker/useDateRangePickerValue.d.ts

@@ -32,6 +32,30 @@ export interface UseDateRangePickerValueProps {
      */
     value?: RangePickerValue;
 }
+/**
+ * 管理日期區間選取器的值狀態與互動邏輯的 Hook。
+ *
+ * 協調「起始日期輸入框」、「結束日期輸入框」與「日曆」三者之間的狀態同步，
+ * 支援鍵盤輸入、日曆點選、hover 預覽以及清除功能。
+ *
+ * @example
+ * ```tsx
+ * import { useDateRangePickerValue } from '@mezzanine-ui/react';
+ *
+ * const {
+ *   value, calendarValue, inputFromValue, inputToValue,
+ *   onCalendarChange, onInputFromChange, onInputToChange, onClear,
+ * } = useDateRangePickerValue({
+ *   format: 'YYYY-MM-DD',
+ *   inputFromRef,
+ *   inputToRef,
+ *   value: rangePickerValue,
+ *   onChange: setRangePickerValue,
+ * });
+ * ```
+ *
+ * @see {@link DateRangePicker} 搭配的元件
+ */
 export declare function useDateRangePickerValue({ format, hasDisabledDateInRange, inputFromRef: _inputFromRef, inputToRef, mode, onChange: onChangeProp, value: valueProp, }: UseDateRangePickerValueProps): {
     calendarValue: string[] | undefined;
     checkIsInRange: (_date: DateType) => boolean;

package/DateRangePicker/useDateRangePickerValue.js

@@ -2,6 +2,30 @@
 import { useState, useCallback, useMemo } from 'react';
 import { useCalendarContext } from '../Calendar/CalendarContext.js';
 
+/**
+ * 管理日期區間選取器的值狀態與互動邏輯的 Hook。
+ *
+ * 協調「起始日期輸入框」、「結束日期輸入框」與「日曆」三者之間的狀態同步，
+ * 支援鍵盤輸入、日曆點選、hover 預覽以及清除功能。
+ *
+ * @example
+ * ```tsx
+ * import { useDateRangePickerValue } from '@mezzanine-ui/react';
+ *
+ * const {
+ *   value, calendarValue, inputFromValue, inputToValue,
+ *   onCalendarChange, onInputFromChange, onInputToChange, onClear,
+ * } = useDateRangePickerValue({
+ *   format: 'YYYY-MM-DD',
+ *   inputFromRef,
+ *   inputToRef,
+ *   value: rangePickerValue,
+ *   onChange: setRangePickerValue,
+ * });
+ * ```
+ *
+ * @see {@link DateRangePicker} 搭配的元件
+ */
 function useDateRangePickerValue({ format, hasDisabledDateInRange, inputFromRef: _inputFromRef, inputToRef, mode, onChange: onChangeProp, value: valueProp, }) {
     var _a, _b;
     const { addDay, formatToString, isBefore, locale } = useCalendarContext();

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] }));
 });

package/Drawer/Drawer.d.ts

@@ -1,9 +1,10 @@
-import React, { type ChangeEventHandler } from 'react';
+import { ButtonIconType, ButtonSize, ButtonVariant } from '@mezzanine-ui/core/button';
 import { DrawerSize } from '@mezzanine-ui/core/drawer';
+import type { DropdownOption } from '@mezzanine-ui/core/dropdown';
 import { IconDefinition } from '@mezzanine-ui/icons';
-import { ButtonIconType, ButtonSize, ButtonVariant } from '@mezzanine-ui/core/button';
-import { NativeElementPropsWithoutKeyAndRef } from '../utils/jsx-types';
+import { type ChangeEventHandler } from 'react';
 import { BackdropProps } from '../Backdrop';
+import { NativeElementPropsWithoutKeyAndRef } from '../utils/jsx-types';
 export interface DrawerProps extends NativeElementPropsWithoutKeyAndRef<'div'>, Pick<BackdropProps, 'container' | 'disableCloseOnBackdropClick' | 'disablePortal' | 'onBackdropClick' | 'onClose' | 'open'> {
     /**
      * Key prop for forcing content remount when data changes.
@@ -116,51 +117,62 @@ export interface DrawerProps extends NativeElementPropsWithoutKeyAndRef<'div'>,
      */
     bottomSecondaryActionVariant?: ButtonVariant;
     /**
-     * The label of the all radio in control bar.
+     * The label of the all radio in filter area.
      */
-    controlBarAllRadioLabel?: string;
+    filterAreaAllRadioLabel?: string;
     /**
-     * The label of the custom button in control bar.
+     * The label of the custom button in filter area.
      */
-    controlBarCustomButtonLabel?: string;
+    filterAreaCustomButtonLabel?: string;
     /**
-     * The default value of the radio group in control bar.
+     * The default value of the radio group in filter area.
      */
-    controlBarDefaultValue?: string;
+    filterAreaDefaultValue?: string;
     /**
-     * Whether the control bar content is empty (for disabling custom button).
+     * Whether the filter area content is empty (for disabling custom button).
      */
-    controlBarIsEmpty?: boolean;
+    filterAreaIsEmpty?: boolean;
     /**
-     * The callback function when the custom button is clicked in control bar.
+     * The callback function when the custom button is clicked in filter area.
      */
-    controlBarOnCustomButtonClick?: VoidFunction;
+    filterAreaOnCustomButtonClick?: VoidFunction;
     /**
-     * The callback function when the radio group value changes in control bar.
+     * The callback function when the radio group value changes in filter area.
      */
-    controlBarOnRadioChange?: ChangeEventHandler<HTMLInputElement>;
+    filterAreaOnRadioChange?: ChangeEventHandler<HTMLInputElement>;
     /**
-     * The label of the read radio in control bar.
+     * The label of the read radio in filter area.
      */
-    controlBarReadRadioLabel?: string;
+    filterAreaReadRadioLabel?: string;
     /**
-     * Controls whether to display the control bar.
+     * Controls whether to display the filter area.
      * @default false
      */
-    controlBarShow?: boolean;
+    filterAreaShow?: boolean;
     /**
-     * Controls whether to display the unread button in control bar.
+     * Controls whether to display the unread button in filter area.
      * @default false
      */
-    controlBarShowUnreadButton?: boolean;
+    filterAreaShowUnreadButton?: boolean;
+    /**
+     * The label of the unread radio in filter area.
+     */
+    filterAreaUnreadRadioLabel?: string;
+    /**
+     * The value of the radio group in filter area.
+     */
+    filterAreaValue?: string;
     /**
-     * The label of the unread radio in control bar.
+     * Options for the filter bar dropdown.
+     * When non-empty, the right-side filter area button is replaced by a Dropdown
+     * triggered by a `DotHorizontalIcon` icon button.
      */
-    controlBarUnreadRadioLabel?: string;
+    filterAreaOptions?: DropdownOption[];
     /**
-     * The value of the radio group in control bar.
+     * Callback fired when a filter bar dropdown option is selected.
+     * Only used when `filterAreaOptions` is non-empty.
      */
-    controlBarValue?: string;
+    filterAreaOnSelect?: (option: DropdownOption) => void;
     /**
      * Controls whether to disable closing drawer while escape key down.
      * @default false
@@ -178,18 +190,51 @@ export interface DrawerProps extends NativeElementPropsWithoutKeyAndRef<'div'>,
      * Controls whether to display the header area.
      */
     isHeaderDisplay?: boolean;
-    /**
-     * Custom render function for the control bar area.
-     * The control bar will be rendered between the header and content areas.
-     * If provided, this will override the default control bar rendering and control bar-related props.
-     * @returns ReactNode - The custom control bar element
-     */
-    renderControlBar?: () => React.ReactNode;
     /**
      * Controls the width of the drawer.
      * @default 'medium'
      */
     size?: DrawerSize;
 }
-declare const Drawer: React.ForwardRefExoticComponent<DrawerProps & React.RefAttributes<HTMLDivElement>>;
+/**
+ * 從螢幕右側滑入的抽屜面板元件。
+ *
+ * 使用 `Backdrop` 作為遮罩層，並以 `Slide` 動畫過渡效果呈現開關狀態。
+ * 支援標題列、篩選區域（含分頁 Radio）、底部操作按鈕區域，以及按下 Escape 鍵關閉。
+ * 當多個 Drawer 同時開啟時，Escape 鍵只會關閉最上層的 Drawer。
+ *
+ * @example
+ * ```tsx
+ * import Drawer from '@mezzanine-ui/react/Drawer';
+ *
+ * // 基本用法
+ * <Drawer open={open} onClose={() => setOpen(false)} isHeaderDisplay headerTitle="詳細資料">
+ *   <p>抽屜內容</p>
+ * </Drawer>
+ *
+ * // 帶有底部操作按鈕
+ * <Drawer
+ *   open={open}
+ *   onClose={() => setOpen(false)}
+ *   isHeaderDisplay
+ *   headerTitle="編輯"
+ *   isBottomDisplay
+ *   bottomPrimaryActionText="確認"
+ *   bottomOnPrimaryActionClick={handleSubmit}
+ *   bottomSecondaryActionText="取消"
+ *   bottomOnSecondaryActionClick={() => setOpen(false)}
+ * >
+ *   <form>表單內容</form>
+ * </Drawer>
+ *
+ * // 使用 contentKey 強制重新掛載內容
+ * <Drawer open={open} onClose={() => setOpen(false)} contentKey={recordId}>
+ *   <RecordDetail id={recordId} />
+ * </Drawer>
+ * ```
+ *
+ * @see {@link Modal} 對話框元件
+ * @see {@link Backdrop} 遮罩層元件
+ */
+declare const Drawer: import("react").ForwardRefExoticComponent<DrawerProps & import("react").RefAttributes<HTMLDivElement>>;
 export default Drawer;