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

package/Stepper/useStepper.d.ts

@@ -11,6 +11,24 @@ export interface UseStepperOptions {
      */
     totalSteps?: number;
 }
+/**
+ * 管理多步驟流程狀態的 Hook。
+ *
+ * 維護當前步驟索引，並提供 `nextStep`、`prevStep`、`goToStep` 等導航方法，
+ * 同時暴露 `isFirstStep` 與 `isLastStep` 兩個旗標以簡化邊界判斷。
+ *
+ * @example
+ * ```tsx
+ * import { useStepper } from '@mezzanine-ui/react';
+ *
+ * const { currentStep, nextStep, prevStep, isFirstStep, isLastStep } = useStepper({
+ *   totalSteps: 3,
+ *   defaultStep: 0,
+ * });
+ * ```
+ *
+ * @see {@link Stepper} 搭配的元件
+ */
 export declare const useStepper: ({ defaultStep, totalSteps, }: UseStepperOptions) => {
     currentStep: number;
     goToStep: (step: number) => void;

package/Stepper/useStepper.js

@@ -1,5 +1,23 @@
 import { useState } from 'react';
 
+/**
+ * 管理多步驟流程狀態的 Hook。
+ *
+ * 維護當前步驟索引，並提供 `nextStep`、`prevStep`、`goToStep` 等導航方法，
+ * 同時暴露 `isFirstStep` 與 `isLastStep` 兩個旗標以簡化邊界判斷。
+ *
+ * @example
+ * ```tsx
+ * import { useStepper } from '@mezzanine-ui/react';
+ *
+ * const { currentStep, nextStep, prevStep, isFirstStep, isLastStep } = useStepper({
+ *   totalSteps: 3,
+ *   defaultStep: 0,
+ * });
+ * ```
+ *
+ * @see {@link Stepper} 搭配的元件
+ */
 const useStepper = ({ defaultStep = 0, totalSteps = Number.MAX_VALUE, }) => {
     const [currentStep, setCurrentStep] = useState(defaultStep);
     const goToStep = (step) => {

package/Tab/Tab.d.ts

@@ -33,7 +33,39 @@ export interface TabProps extends Omit<NativeElementPropsWithoutKeyAndRef<'div'>
     size?: 'main' | 'sub';
 }
 /**
- * The react component for `mezzanine` tab.
+ * 頁籤導航元件，透過底部滑動指示條標示當前選取的頁籤。
+ *
+ * 以 `TabItem` 作為子元件定義每個頁籤項目，支援水平（`horizontal`）與垂直（`vertical`）
+ * 兩種排列方向。可透過 `activeKey`（受控）或 `defaultActiveKey`（非受控）指定當前頁籤，
+ * `onChange` 回呼在切換時接收新的 `activeKey` 與索引。
+ *
+ * @example
+ * ```tsx
+ * import Tab from '@mezzanine-ui/react/Tab';
+ * import TabItem from '@mezzanine-ui/react/TabItem';
+ *
+ * // 基本用法（非受控）
+ * <Tab defaultActiveKey="home">
+ *   <TabItem key="home">首頁</TabItem>
+ *   <TabItem key="profile">個人資料</TabItem>
+ *   <TabItem key="settings">設定</TabItem>
+ * </Tab>
+ *
+ * // 受控用法
+ * const [activeKey, setActiveKey] = useState<Key>('tab1');
+ * <Tab activeKey={activeKey} onChange={(key) => setActiveKey(key)}>
+ *   <TabItem key="tab1">頁籤一</TabItem>
+ *   <TabItem key="tab2">頁籤二</TabItem>
+ * </Tab>
+ *
+ * // 垂直方向
+ * <Tab direction="vertical" size="sub">
+ *   <TabItem key="a">分類 A</TabItem>
+ *   <TabItem key="b">分類 B</TabItem>
+ * </Tab>
+ * ```
+ *
+ * @see {@link TabItem} 頁籤項目元件
  */
 declare const Tab: import("react").ForwardRefExoticComponent<TabProps & import("react").RefAttributes<HTMLDivElement>>;
 export default Tab;

package/Tab/Tab.js

@@ -6,7 +6,39 @@ import { flattenChildren } from '../utils/flatten-children.js';
 import cx from 'clsx';
 
 /**
- * The react component for `mezzanine` tab.
+ * 頁籤導航元件，透過底部滑動指示條標示當前選取的頁籤。
+ *
+ * 以 `TabItem` 作為子元件定義每個頁籤項目，支援水平（`horizontal`）與垂直（`vertical`）
+ * 兩種排列方向。可透過 `activeKey`（受控）或 `defaultActiveKey`（非受控）指定當前頁籤，
+ * `onChange` 回呼在切換時接收新的 `activeKey` 與索引。
+ *
+ * @example
+ * ```tsx
+ * import Tab from '@mezzanine-ui/react/Tab';
+ * import TabItem from '@mezzanine-ui/react/TabItem';
+ *
+ * // 基本用法（非受控）
+ * <Tab defaultActiveKey="home">
+ *   <TabItem key="home">首頁</TabItem>
+ *   <TabItem key="profile">個人資料</TabItem>
+ *   <TabItem key="settings">設定</TabItem>
+ * </Tab>
+ *
+ * // 受控用法
+ * const [activeKey, setActiveKey] = useState<Key>('tab1');
+ * <Tab activeKey={activeKey} onChange={(key) => setActiveKey(key)}>
+ *   <TabItem key="tab1">頁籤一</TabItem>
+ *   <TabItem key="tab2">頁籤二</TabItem>
+ * </Tab>
+ *
+ * // 垂直方向
+ * <Tab direction="vertical" size="sub">
+ *   <TabItem key="a">分類 A</TabItem>
+ *   <TabItem key="b">分類 B</TabItem>
+ * </Tab>
+ * ```
+ *
+ * @see {@link TabItem} 頁籤項目元件
  */
 const Tab = forwardRef(function Tab(props, ref) {
     const { activeKey: activeKeyProp, children, className, defaultActiveKey = 0, direction = 'horizontal', onChange, size = 'main', ...rest } = props;

package/Table/Table.d.ts

@@ -1,9 +1,57 @@
 import { type TableDataSource } from '@mezzanine-ui/core/table';
 import type { TableProps } from './typings';
 /**
- * Table is a high-performance data table component with support for
- * virtual scrolling, column resizing, fixed columns, row selection,
- * sorting, expandable rows, and drag-and-drop row reordering.
+ * 資料表格元件，支援排序、選取、展開、虛擬捲動與拖曳排序等功能。
+ *
+ * 透過 `columns` 定義欄位結構，`dataSource` 傳入資料列；可搭配 `rowSelection`
+ * 啟用勾選功能、`expandable` 展開子列、`scroll.virtualized` 開啟虛擬捲動以渲染大量資料。
+ * `draggable` 與 `pinnable` 為互斥選項，無法同時啟用。
+ *
+ * @example
+ * ```tsx
+ * import Table from '@mezzanine-ui/react/Table';
+ *
+ * // 基本用法
+ * <Table
+ *   columns={[
+ *     { key: 'name', title: '名稱', dataIndex: 'name', width: 200 },
+ *     { key: 'age', title: '年齡', dataIndex: 'age', width: 100 },
+ *   ]}
+ *   dataSource={[
+ *     { key: '1', name: 'Alice', age: 30 },
+ *     { key: '2', name: 'Bob', age: 25 },
+ *   ]}
+ * />
+ *
+ * // 啟用虛擬捲動（大資料量）
+ * <Table
+ *   columns={columns}
+ *   dataSource={largeData}
+ *   scroll={{ y: 400, virtualized: true }}
+ * />
+ *
+ * // 勾選列 + 批次操作
+ * <Table
+ *   columns={columns}
+ *   dataSource={data}
+ *   rowSelection={{
+ *     mode: 'checkbox',
+ *     selectedRowKeys,
+ *     onChange: setSelectedRowKeys,
+ *   }}
+ * />
+ *
+ * // 可展開子列
+ * <Table
+ *   columns={columns}
+ *   dataSource={data}
+ *   expandable={{
+ *     expandedRowRender: (row) => <div>{row.detail}</div>,
+ *   }}
+ * />
+ * ```
+ *
+ * @see {@link Pagination} 搭配 `pagination` prop 使用分頁元件
  */
 export declare const Table: <T extends TableDataSource = TableDataSource>(props: TableProps<T> & {
     ref?: React.ForwardedRef<HTMLDivElement>;

package/Table/Table.js

@@ -244,7 +244,7 @@ function TableInner(props, ref) {
         pagination: pagination || undefined,
         pinnable: pinnableState,
         resizable,
-        rowState,
+        rowState: rowState,
         rowHeight,
         scroll,
         scrollContainerRef,
@@ -421,9 +421,57 @@ function TableInner(props, ref) {
     return (jsx(DragDropContext, { onDragEnd: handleDragEnd, children: jsx(Droppable, { droppableId: "mzn-table-dnd", children: (provided) => (jsx(TableSuperContext.Provider, { value: superContextValue, children: renderMainTable(provided) })) }) }));
 }
 /**
- * Table is a high-performance data table component with support for
- * virtual scrolling, column resizing, fixed columns, row selection,
- * sorting, expandable rows, and drag-and-drop row reordering.
+ * 資料表格元件，支援排序、選取、展開、虛擬捲動與拖曳排序等功能。
+ *
+ * 透過 `columns` 定義欄位結構，`dataSource` 傳入資料列；可搭配 `rowSelection`
+ * 啟用勾選功能、`expandable` 展開子列、`scroll.virtualized` 開啟虛擬捲動以渲染大量資料。
+ * `draggable` 與 `pinnable` 為互斥選項，無法同時啟用。
+ *
+ * @example
+ * ```tsx
+ * import Table from '@mezzanine-ui/react/Table';
+ *
+ * // 基本用法
+ * <Table
+ *   columns={[
+ *     { key: 'name', title: '名稱', dataIndex: 'name', width: 200 },
+ *     { key: 'age', title: '年齡', dataIndex: 'age', width: 100 },
+ *   ]}
+ *   dataSource={[
+ *     { key: '1', name: 'Alice', age: 30 },
+ *     { key: '2', name: 'Bob', age: 25 },
+ *   ]}
+ * />
+ *
+ * // 啟用虛擬捲動（大資料量）
+ * <Table
+ *   columns={columns}
+ *   dataSource={largeData}
+ *   scroll={{ y: 400, virtualized: true }}
+ * />
+ *
+ * // 勾選列 + 批次操作
+ * <Table
+ *   columns={columns}
+ *   dataSource={data}
+ *   rowSelection={{
+ *     mode: 'checkbox',
+ *     selectedRowKeys,
+ *     onChange: setSelectedRowKeys,
+ *   }}
+ * />
+ *
+ * // 可展開子列
+ * <Table
+ *   columns={columns}
+ *   dataSource={data}
+ *   expandable={{
+ *     expandedRowRender: (row) => <div>{row.detail}</div>,
+ *   }}
+ * />
+ * ```
+ *
+ * @see {@link Pagination} 搭配 `pagination` prop 使用分頁元件
  */
 const Table = forwardRef(TableInner);
 

package/Table/hooks/useTableDataSource.d.ts

@@ -10,12 +10,12 @@ export interface TableTransitionState {
 export interface UseTableDataSourceOptions<T extends TableDataSource> {
     /** Initial data source */
     initialData?: T[];
-    /** Duration of highlight animation in ms
-     * @default 1000
+    /** Duration of highlight animation in ms (stay phase)
+     * @default 700 — matches `long` motion token
      */
     highlightDuration?: number;
-    /** Duration of fade out animation in ms
-     * @default 200
+    /** Duration of fade out animation in ms (exit phase)
+     * @default 150 — matches `fast` motion token
      */
     fadeOutDuration?: number;
 }

package/Table/hooks/useTableDataSource.js

@@ -3,7 +3,7 @@ import { useState, useRef, useEffect, useCallback, useMemo } from 'react';
 import { getRowKey } from '@mezzanine-ui/core/table';
 
 function useTableDataSource(options = {}) {
-    const { initialData = [], highlightDuration = 1000, fadeOutDuration = 200, } = options;
+    const { initialData = [], highlightDuration = 700, fadeOutDuration = 150, } = options;
     // Internal data source that includes items being deleted (for animation)
     const [internalData, setInternalData] = useState(initialData);
     // Track adding keys

package/Tag/Tag.d.ts

@@ -1,6 +1,32 @@
 import { TagProps } from './typings';
 /**
- * The react component for `mezzanine` tag.
+ * 標籤元件，用於分類、篩選或標記內容，支援靜態、計數、可關閉及可新增四種模式。
+ *
+ * 透過 `type` prop 切換顯示模式：`static` 純標籤（預設）、`counter` 帶數字的標籤、
+ * `dismissable` 含關閉按鈕、`addable` 含新增按鈕。`overflow-counter` 適用於收合多餘標籤並顯示剩餘數量。
+ * `dismissable` 與 `addable` 模式支援 `active` 和 `disabled` 狀態。
+ *
+ * @example
+ * ```tsx
+ * import Tag from '@mezzanine-ui/react/Tag';
+ *
+ * // 靜態標籤
+ * <Tag type="static" label="設計" />
+ *
+ * // 計數標籤
+ * <Tag type="counter" label="待處理" count={3} />
+ *
+ * // 可關閉標籤
+ * <Tag type="dismissable" label="React" onClose={() => removeTag('React')} />
+ *
+ * // 可新增標籤（按鈕形式）
+ * <Tag type="addable" label="新增標籤" onClick={handleAdd} />
+ *
+ * // 收合溢出的標籤數量
+ * <Tag type="overflow-counter" count={5} onClick={handleExpand} />
+ * ```
+ *
+ * @see {@link TagGroup} 以群組方式管理多個標籤
  */
 declare const Tag: import("react").ForwardRefExoticComponent<TagProps & import("react").RefAttributes<HTMLButtonElement | HTMLSpanElement>>;
 export default Tag;

package/Tag/Tag.js

@@ -10,7 +10,33 @@ import cx from 'clsx';
 const getTagType = (props) => { var _a; return (_a = props.type) !== null && _a !== void 0 ? _a : 'static'; };
 const isTagType = (props, current) => getTagType(props) === current;
 /**
- * The react component for `mezzanine` tag.
+ * 標籤元件，用於分類、篩選或標記內容，支援靜態、計數、可關閉及可新增四種模式。
+ *
+ * 透過 `type` prop 切換顯示模式：`static` 純標籤（預設）、`counter` 帶數字的標籤、
+ * `dismissable` 含關閉按鈕、`addable` 含新增按鈕。`overflow-counter` 適用於收合多餘標籤並顯示剩餘數量。
+ * `dismissable` 與 `addable` 模式支援 `active` 和 `disabled` 狀態。
+ *
+ * @example
+ * ```tsx
+ * import Tag from '@mezzanine-ui/react/Tag';
+ *
+ * // 靜態標籤
+ * <Tag type="static" label="設計" />
+ *
+ * // 計數標籤
+ * <Tag type="counter" label="待處理" count={3} />
+ *
+ * // 可關閉標籤
+ * <Tag type="dismissable" label="React" onClose={() => removeTag('React')} />
+ *
+ * // 可新增標籤（按鈕形式）
+ * <Tag type="addable" label="新增標籤" onClick={handleAdd} />
+ *
+ * // 收合溢出的標籤數量
+ * <Tag type="overflow-counter" count={5} onClick={handleExpand} />
+ * ```
+ *
+ * @see {@link TagGroup} 以群組方式管理多個標籤
  */
 const Tag = forwardRef(function Tag(props, ref) {
     const { active, className, disabled, onClick, onClose: _onClose, readOnly, size = 'main', type: _type, ...rest } = props;

package/Tag/typings.d.ts

@@ -36,42 +36,70 @@ type TagPropsStatic = TagSpanHostProps & {
     onClick?: never;
 };
 type TagPropsCounter = TagSpanHostProps & {
+    /** 標籤類型：計數器模式。 */
     type: 'counter';
+    /** 標籤顯示的文字。 */
     label: string;
+    /** 計數器顯示的數字。 */
     count: number;
+    /** 此模式下不適用。 */
     active?: never;
+    /** 此模式下不適用。 */
     disabled?: never;
+    /** 此模式下不適用。 */
     onClose?: never;
+    /** 此模式下不適用。 */
     onClick?: never;
+    /** 此模式下不適用。 */
     readOnly?: never;
 };
 type TagPropsOverflowCounter = TagButtonHostProps & {
+    /** 標籤類型：溢出計數器模式，顯示隱藏的項目數量。 */
     type: 'overflow-counter';
+    /** 溢出的項目數量。 */
     count: number;
+    /**
+     * 是否禁用。
+     * @default false
+     */
     disabled?: boolean;
+    /** 點擊時的回呼函式。 */
     onClick?: MouseEventHandler<HTMLButtonElement>;
+    /**
+     * 是否為唯讀。
+     * @default false
+     */
     readOnly?: boolean;
+    /** 此模式下不適用。 */
     active?: never;
+    /** 此模式下不適用。 */
     label?: never;
+    /** 此模式下不適用。 */
     onClose?: never;
 };
 type TagPropsDismissable = TagSpanHostProps & {
+    /** 標籤類型：可關閉模式。 */
     type: 'dismissable';
     active?: boolean;
     disabled?: boolean;
     readOnly?: never;
     label: string;
     onClose: MouseEventHandler<HTMLButtonElement>;
+    /** 此模式下不適用。 */
     count?: never;
+    /** 此模式下不適用。 */
     onClick?: never;
 };
 type TagPropsAddable = TagButtonHostProps & {
+    /** 標籤類型：可新增模式。 */
     type: 'addable';
     active?: boolean;
     disabled?: boolean;
     label: string;
     onClick?: MouseEventHandler<HTMLButtonElement>;
+    /** 此模式下不適用。 */
     count?: never;
+    /** 此模式下不適用。 */
     onClose?: never;
     readOnly?: never;
 };

package/Textarea/Textarea.d.ts

@@ -15,12 +15,39 @@ export type TextareaProps = Omit<NativeElementPropsWithoutKeyAndRef<'textarea'>,
     /** ReadOnly state of the textarea, Only available on default type. */
     readOnly?: boolean;
 } | {
+    /** 文字區域類型：警告或錯誤狀態。 */
     type: 'warning' | 'error';
+    /** 警告/錯誤狀態下不適用。 */
     disabled?: never;
+    /** 警告/錯誤狀態下不適用。 */
     readOnly?: never;
 });
 /**
- * The react component for `mezzanine` textarea.
+ * 多行文字輸入區域元件，支援禁用、唯讀、警告與錯誤等視覺狀態。
+ *
+ * 以 `TextField` 作為外框容器，`type` 控制視覺樣式（`default`、`warning`、`error`），
+ * `disabled` 與 `readOnly` 僅在 `type="default"` 時有效。`resize` prop 對應原生 CSS
+ * `resize` 屬性，設為非 `none` 時會顯示右下角的調整大小拖曳圖示。
+ *
+ * @example
+ * ```tsx
+ * import Textarea from '@mezzanine-ui/react/Textarea';
+ *
+ * // 基本用法
+ * <Textarea placeholder="請輸入內容..." rows={4} />
+ *
+ * // 允許垂直縮放
+ * <Textarea resize="vertical" rows={3} />
+ *
+ * // 錯誤狀態
+ * <Textarea type="error" value={text} onChange={(e) => setText(e.target.value)} />
+ *
+ * // 禁用狀態
+ * <Textarea disabled placeholder="此欄位已停用" />
+ * ```
+ *
+ * @see {@link Input} 單行文字輸入元件
+ * @see {@link FormField} 表單欄位容器，可整合 label 與錯誤訊息
  */
 declare const Textarea: import("react").ForwardRefExoticComponent<TextareaProps & import("react").RefAttributes<HTMLDivElement>>;
 export default Textarea;

package/Textarea/Textarea.js

@@ -9,7 +9,31 @@ import Icon from '../Icon/Icon.js';
 import cx from 'clsx';
 
 /**
- * The react component for `mezzanine` textarea.
+ * 多行文字輸入區域元件，支援禁用、唯讀、警告與錯誤等視覺狀態。
+ *
+ * 以 `TextField` 作為外框容器，`type` 控制視覺樣式（`default`、`warning`、`error`），
+ * `disabled` 與 `readOnly` 僅在 `type="default"` 時有效。`resize` prop 對應原生 CSS
+ * `resize` 屬性，設為非 `none` 時會顯示右下角的調整大小拖曳圖示。
+ *
+ * @example
+ * ```tsx
+ * import Textarea from '@mezzanine-ui/react/Textarea';
+ *
+ * // 基本用法
+ * <Textarea placeholder="請輸入內容..." rows={4} />
+ *
+ * // 允許垂直縮放
+ * <Textarea resize="vertical" rows={3} />
+ *
+ * // 錯誤狀態
+ * <Textarea type="error" value={text} onChange={(e) => setText(e.target.value)} />
+ *
+ * // 禁用狀態
+ * <Textarea disabled placeholder="此欄位已停用" />
+ * ```
+ *
+ * @see {@link Input} 單行文字輸入元件
+ * @see {@link FormField} 表單欄位容器，可整合 label 與錯誤訊息
  */
 const Textarea = forwardRef(function Textarea(props, ref) {
     const { className, disabled, readOnly, textareaClassName, textareaRef: textareaRefProp, type = 'default', resize = 'none', ...textareaProps } = props;

package/TimePicker/TimePicker.js

@@ -204,7 +204,7 @@ const TimePicker = forwardRef(function TimePicker(props, ref) {
         }
     };
     const suffixIcon = (jsx(Icon, { "aria-label": "Open time picker", icon: ClockIcon, onClick: readOnly ? undefined : onIconClick }));
-    return (jsxs(Fragment, { children: [jsx(PickerTrigger, { ...restTriggerProps, ref: triggerComposedRef, className: className, clearable: clearable, disabled: disabled, error: error, format: resolvedFormat, fullWidth: fullWidth, inputProps: resolvedInputProps, inputRef: inputRef, hoverValue: open && !inputValue && pendingValue
+    return (jsxs(Fragment, { children: [jsx(PickerTrigger, { ...restTriggerProps, ref: triggerComposedRef, className: className, clearable: clearable, disabled: disabled, error: error, forceShowClearable: !!internalValue, format: resolvedFormat, fullWidth: fullWidth, hideSuffixWhenClearable: clearable, inputProps: resolvedInputProps, inputRef: inputRef, hoverValue: open && !inputValue && pendingValue
                     ? ((_b = formatToString(locale, pendingValue, resolvedFormat)) !== null && _b !== void 0 ? _b : undefined)
                     : undefined, onChange: (e) => {
                     const val = e.target.value;

package/TimeRangePicker/TimeRangePicker.js

@@ -150,7 +150,7 @@ const TimeRangePicker = forwardRef(function TimeRangePicker(props, ref) {
     });
     /** Suffix icon */
     const suffixIcon = (jsx(Icon, { "aria-label": "Open time picker", icon: ClockIcon, onClick: readOnly ? undefined : onIconClick }));
-    return (jsxs(Fragment, { children: [jsx(RangePickerTrigger, { className: className, clearable: clearable, disabled: disabled, error: error, errorMessagesFrom: errorMessagesFrom, errorMessagesTo: errorMessagesTo, format: resolvedFormat, fullWidth: fullWidth, inputFromPlaceholder: inputFromPlaceholder, inputFromProps: inputFromProps, inputFromRef: inputFromRef, inputFromValue: inputFromValue, inputToPlaceholder: inputToPlaceholder, inputToProps: inputToProps, inputToRef: inputToRef, inputToValue: inputToValue, onClear: onClearHandler, onFromFocus: onFromFocusHandler, onIconClick: onIconClick, onInputFromChange: onInputFromChange, onInputToChange: onInputToChange, onToFocus: onToFocusHandler, prefix: prefix, readOnly: readOnly, ref: triggerComposedRef, required: required, size: size, suffixActionIcon: suffixIcon, validateFrom: validateFrom, validateTo: validateTo }), focusedInput && (jsx(TimePickerPanel, { anchor: panelAnchor, fadeProps: fadeProps, hideHour: hideHour, hideMinute: hideMinute, hideSecond: hideSecond, hourStep: hourStep, minuteStep: minuteStep, onChange: onPanelChange, onCancel: onCancel, onConfirm: onConfirm, open: open, popperProps: popperProps, ref: panelRef, secondStep: secondStep, value: panelValue }))] }));
+    return (jsxs(Fragment, { children: [jsx(RangePickerTrigger, { className: className, clearable: clearable, disabled: disabled, error: error, errorMessagesFrom: errorMessagesFrom, errorMessagesTo: errorMessagesTo, forceShowClearable: internalValue.some(Boolean), format: resolvedFormat, fullWidth: fullWidth, hideSuffixWhenClearable: clearable, inputFromPlaceholder: inputFromPlaceholder, inputFromProps: inputFromProps, inputFromRef: inputFromRef, inputFromValue: inputFromValue, inputToPlaceholder: inputToPlaceholder, inputToProps: inputToProps, inputToRef: inputToRef, inputToValue: inputToValue, onClear: onClearHandler, onFromFocus: onFromFocusHandler, onIconClick: onIconClick, onInputFromChange: onInputFromChange, onInputToChange: onInputToChange, onToFocus: onToFocusHandler, prefix: prefix, readOnly: readOnly, ref: triggerComposedRef, required: required, size: size, suffixActionIcon: suffixIcon, validateFrom: validateFrom, validateTo: validateTo }), focusedInput && (jsx(TimePickerPanel, { anchor: panelAnchor, fadeProps: fadeProps, hideHour: hideHour, hideMinute: hideMinute, hideSecond: hideSecond, hourStep: hourStep, minuteStep: minuteStep, onChange: onPanelChange, onCancel: onCancel, onConfirm: onConfirm, open: open, popperProps: popperProps, ref: panelRef, secondStep: secondStep, value: panelValue }))] }));
 });
 
 export { TimeRangePicker as default };

package/Toggle/Toggle.d.ts

@@ -40,7 +40,40 @@ export interface ToggleProps extends Omit<NativeElementPropsWithoutKeyAndRef<'di
     supportingText?: string;
 }
 /**
- * The react component for `mezzanine` toggle.
+ * 切換開關元件，用於表示開／關二元狀態。
+ *
+ * 支援受控（`checked` + `onChange`）與非受控（`defaultChecked`）兩種用法；
+ * `label` 顯示於開關右側，`supportingText` 顯示於 label 下方作為輔助說明。
+ * `disabled` 可透過 `FormControlContext` 自動繼承，無需手動傳入。
+ *
+ * @example
+ * ```tsx
+ * import Toggle from '@mezzanine-ui/react/Toggle';
+ *
+ * // 受控用法
+ * <Toggle
+ *   checked={enabled}
+ *   onChange={(e) => setEnabled(e.target.checked)}
+ *   label="啟用通知"
+ * />
+ *
+ * // 非受控用法（預設開啟）
+ * <Toggle defaultChecked label="自動儲存" />
+ *
+ * // 帶輔助說明文字
+ * <Toggle
+ *   checked={darkMode}
+ *   onChange={(e) => setDarkMode(e.target.checked)}
+ *   label="深色模式"
+ *   supportingText="切換介面主題配色"
+ * />
+ *
+ * // 停用狀態
+ * <Toggle disabled label="此功能暫不開放" />
+ * ```
+ *
+ * @see {@link useSwitchControlValue} 管理 Toggle 受控／非受控值狀態的 hook
+ * @see {@link Checkbox} 多選框元件，適用於多選場景
  */
 declare const Toggle: import("react").ForwardRefExoticComponent<ToggleProps & import("react").RefAttributes<HTMLDivElement>>;
 export default Toggle;

package/Toggle/Toggle.js

@@ -8,7 +8,40 @@ import { FormControlContext } from '../Form/FormControlContext.js';
 import cx from 'clsx';
 
 /**
- * The react component for `mezzanine` toggle.
+ * 切換開關元件，用於表示開／關二元狀態。
+ *
+ * 支援受控（`checked` + `onChange`）與非受控（`defaultChecked`）兩種用法；
+ * `label` 顯示於開關右側，`supportingText` 顯示於 label 下方作為輔助說明。
+ * `disabled` 可透過 `FormControlContext` 自動繼承，無需手動傳入。
+ *
+ * @example
+ * ```tsx
+ * import Toggle from '@mezzanine-ui/react/Toggle';
+ *
+ * // 受控用法
+ * <Toggle
+ *   checked={enabled}
+ *   onChange={(e) => setEnabled(e.target.checked)}
+ *   label="啟用通知"
+ * />
+ *
+ * // 非受控用法（預設開啟）
+ * <Toggle defaultChecked label="自動儲存" />
+ *
+ * // 帶輔助說明文字
+ * <Toggle
+ *   checked={darkMode}
+ *   onChange={(e) => setDarkMode(e.target.checked)}
+ *   label="深色模式"
+ *   supportingText="切換介面主題配色"
+ * />
+ *
+ * // 停用狀態
+ * <Toggle disabled label="此功能暫不開放" />
+ * ```
+ *
+ * @see {@link useSwitchControlValue} 管理 Toggle 受控／非受控值狀態的 hook
+ * @see {@link Checkbox} 多選框元件，適用於多選場景
  */
 const Toggle = forwardRef(function Toggle(props, ref) {
     const { disabled: disabledFromFormControl } = useContext(FormControlContext) || {};

package/Tooltip/Tooltip.d.ts

@@ -35,7 +35,45 @@ export interface TooltipProps extends Omit<PopperProps, 'arrow' | 'children' | '
     title?: ReactNode;
 }
 /**
- * The react component for `mezzanine` tooltip.
+ * 滑鼠懸停時顯示的提示框元件。
+ *
+ * 採用 render prop 模式，`children` 為接收 `ref`、`onMouseEnter`、`onMouseLeave` 的函式。
+ * 內部使用 `Popper` 進行定位，並整合 `flip`、`shift` 等 floating-ui middleware 自動調整位置以避免溢出視窗。
+ * 支援自訂偏移量、顯示箭頭及滑鼠離開延遲時間。
+ *
+ * @example
+ * ```tsx
+ * import Tooltip from '@mezzanine-ui/react/Tooltip';
+ *
+ * // 基本用法
+ * <Tooltip title="這是提示文字">
+ *   {({ ref, onMouseEnter, onMouseLeave }) => (
+ *     <button ref={ref} onMouseEnter={onMouseEnter} onMouseLeave={onMouseLeave}>
+ *       Hover me
+ *     </button>
+ *   )}
+ * </Tooltip>
+ *
+ * // 自訂位置與關閉箭頭
+ * <Tooltip title="底部提示" arrow={false} options={{ placement: 'bottom' }}>
+ *   {({ ref, onMouseEnter, onMouseLeave }) => (
+ *     <span ref={ref} onMouseEnter={onMouseEnter} onMouseLeave={onMouseLeave}>
+ *       文字
+ *     </span>
+ *   )}
+ * </Tooltip>
+ *
+ * // 增加滑鼠離開延遲
+ * <Tooltip title="可懸停的提示" mouseLeaveDelay={0.3}>
+ *   {({ ref, onMouseEnter, onMouseLeave }) => (
+ *     <button ref={ref} onMouseEnter={onMouseEnter} onMouseLeave={onMouseLeave}>
+ *       按鈕
+ *     </button>
+ *   )}
+ * </Tooltip>
+ * ```
+ *
+ * @see {@link Popper} 浮動定位元件
  */
 declare const Tooltip: import("react").ForwardRefExoticComponent<TooltipProps & import("react").RefAttributes<HTMLDivElement>>;
 export default Tooltip;