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

package/FilterArea/Filter.js

@@ -1,11 +1,37 @@
 'use client';
 import { jsx } from 'react/jsx-runtime';
-import { forwardRef, useMemo } from 'react';
+import { forwardRef, useContext, useMemo, Children, isValidElement, cloneElement } from 'react';
 import { filterAreaClasses, filterAreaPrefix } from '@mezzanine-ui/core/filter-area';
+import FilterAreaContext from './FilterAreaContext.js';
 import cx from 'clsx';
 
+/**
+ * 單一篩選條件元件，用於在 FilterLine 中定義欄位的佔位寬度。
+ *
+ * 使用 6 欄 Grid，`span` 決定欄位佔用幾欄（1–6）；
+ * `grow` 設為 `true` 時欄位自動填滿整行。
+ * 從 FilterAreaContext 繼承 `size`，統一套用至內部的輸入元件。
+ *
+ * @example
+ * ```tsx
+ * import { Filter } from '@mezzanine-ui/react';
+ * import { FormField } from '@mezzanine-ui/react';
+ * import Input from '@mezzanine-ui/react/Input';
+ *
+ * <Filter span={2}>
+ *   <FormField label="名稱" name="name" layout="horizontal">
+ *     <Input placeholder="請輸入" />
+ *   </FormField>
+ * </Filter>
+ * ```
+ *
+ * @see {@link FilterLine} 包含 Filter 的行容器
+ * @see {@link FilterArea} 管理整個篩選器的容器
+ */
 const Filter = forwardRef(function Filter(props, ref) {
+    var _a;
     const { align = 'stretch', children, className, grow = false, minWidth, span = 2, ...rest } = props;
+    const { size } = ((_a = useContext(FilterAreaContext)) !== null && _a !== void 0 ? _a : {});
     const filterClassName = useMemo(() => cx(filterAreaClasses.filter, {
         [filterAreaClasses.filterGrow]: grow,
         [filterAreaClasses.filterAlign(align)]: align,
@@ -17,7 +43,22 @@ const Filter = forwardRef(function Filter(props, ref) {
         }),
         ...rest.style,
     }), [grow, minWidth, rest.style, span]);
-    return (jsx("div", { ...rest, ref: ref, className: filterClassName, style: style, children: children }));
+    const sizedChildren = useMemo(() => {
+        if (!size)
+            return children;
+        return Children.map(children, (formField) => {
+            const sizedInputs = Children.map(formField.props.children, (inputChild) => {
+                if (!isValidElement(inputChild))
+                    return inputChild;
+                const { size: ownSize } = inputChild.props;
+                if (ownSize !== undefined)
+                    return inputChild;
+                return cloneElement(inputChild, { size });
+            });
+            return cloneElement(formField, {}, sizedInputs);
+        });
+    }, [children, size]);
+    return (jsx("div", { ...rest, ref: ref, className: filterClassName, style: style, children: sizedChildren }));
 });
 
 export { Filter as default };

package/FilterArea/FilterArea.d.ts

@@ -1,5 +1,5 @@
 import { ComponentPropsWithoutRef, ReactElement } from 'react';
-import { FilterAreaActionsAlign, FilterAreaSize } from '@mezzanine-ui/core/filter-area';
+import { FilterAreaActionsAlign, FilterAreaRowAlign, FilterAreaSize } from '@mezzanine-ui/core/filter-area';
 import { NativeElementPropsWithoutKeyAndRef } from '../utils/jsx-types';
 import { FilterLineProps } from './FilterLine';
 export interface FilterAreaProps extends Omit<NativeElementPropsWithoutKeyAndRef<'div'>, 'children' | 'onSubmit' | 'onReset'> {
@@ -24,14 +24,14 @@ export interface FilterAreaProps extends Omit<NativeElementPropsWithoutKeyAndRef
      */
     onReset?: () => void;
     /**
-     * Callback function triggered when the form is submitted.
+     * Callback function triggered when the submit button is clicked.
      * FilterArea itself does not manage form state; the parent component should collect
-     * filter values and handle submission logic. If using react-hook-form, values will be
-     * handled through FormProvider's handleSubmit.
+     * filter values and handle submission logic.
      */
     onSubmit?: () => void;
     /**
      * The text of the reset button.
+     * @default 'Reset'
      */
     resetText?: string;
     /**
@@ -41,6 +41,7 @@ export interface FilterAreaProps extends Omit<NativeElementPropsWithoutKeyAndRef
     size?: FilterAreaSize;
     /**
      * The text of the submit button.
+     * @default 'Search'
      */
     submitText?: string;
     /**
@@ -48,11 +49,49 @@ export interface FilterAreaProps extends Omit<NativeElementPropsWithoutKeyAndRef
      * @default 'button'
      */
     resetButtonType?: ComponentPropsWithoutRef<'button'>['type'];
+    /**
+     * The vertical alignment of the row (cross-axis align-items).
+     * @default 'center'
+     */
+    rowAlign?: FilterAreaRowAlign;
     /**
      * The type of the submit button.
      * @default 'button'
      */
     submitButtonType?: ComponentPropsWithoutRef<'button'>['type'];
 }
+/**
+ * 篩選器容器元件，管理多個 FilterLine 的展示與收合。
+ *
+ * 預設僅顯示第一行（`FilterLine`），多行時自動出現展開／收合切換按鈕。
+ * 透過 `size` 統一控制內部所有表單欄位的尺寸；
+ * 透過 `actionsAlign` 調整「送出／重設」按鈕區塊的對齊；
+ * 透過 `isDirty` 控制重設按鈕的啟用狀態（`false` 時禁用）。
+ *
+ * @example
+ * ```tsx
+ * import { Filter, FilterArea, FilterLine } from '@mezzanine-ui/react';
+ * import { FormField } from '@mezzanine-ui/react';
+ * import Input from '@mezzanine-ui/react/Input';
+ *
+ * <FilterArea
+ *   submitText="搜尋"
+ *   resetText="重設"
+ *   onSubmit={handleSubmit}
+ *   onReset={handleReset}
+ * >
+ *   <FilterLine>
+ *     <Filter span={2}>
+ *       <FormField label="名稱" name="name" layout="horizontal">
+ *         <Input placeholder="請輸入" />
+ *       </FormField>
+ *     </Filter>
+ *   </FilterLine>
+ * </FilterArea>
+ * ```
+ *
+ * @see {@link FilterLine} 用於組成 FilterArea 的單行條件列
+ * @see {@link Filter} 包裝單一篩選欄位的元件
+ */
 declare const FilterArea: import("react").ForwardRefExoticComponent<FilterAreaProps & import("react").RefAttributes<HTMLDivElement>>;
 export default FilterArea;

package/FilterArea/FilterArea.js

@@ -4,11 +4,46 @@ import { forwardRef, useMemo, Children, useState, useCallback } from 'react';
 import { filterAreaClasses } from '@mezzanine-ui/core/filter-area';
 import { ChevronUpIcon, ChevronDownIcon } from '@mezzanine-ui/icons';
 import Button from '../Button/Button.js';
+import FilterAreaContext from './FilterAreaContext.js';
 import cx from 'clsx';
 
+/**
+ * 篩選器容器元件，管理多個 FilterLine 的展示與收合。
+ *
+ * 預設僅顯示第一行（`FilterLine`），多行時自動出現展開／收合切換按鈕。
+ * 透過 `size` 統一控制內部所有表單欄位的尺寸；
+ * 透過 `actionsAlign` 調整「送出／重設」按鈕區塊的對齊；
+ * 透過 `isDirty` 控制重設按鈕的啟用狀態（`false` 時禁用）。
+ *
+ * @example
+ * ```tsx
+ * import { Filter, FilterArea, FilterLine } from '@mezzanine-ui/react';
+ * import { FormField } from '@mezzanine-ui/react';
+ * import Input from '@mezzanine-ui/react/Input';
+ *
+ * <FilterArea
+ *   submitText="搜尋"
+ *   resetText="重設"
+ *   onSubmit={handleSubmit}
+ *   onReset={handleReset}
+ * >
+ *   <FilterLine>
+ *     <Filter span={2}>
+ *       <FormField label="名稱" name="name" layout="horizontal">
+ *         <Input placeholder="請輸入" />
+ *       </FormField>
+ *     </Filter>
+ *   </FilterLine>
+ * </FilterArea>
+ * ```
+ *
+ * @see {@link FilterLine} 用於組成 FilterArea 的單行條件列
+ * @see {@link Filter} 包裝單一篩選欄位的元件
+ */
 const FilterArea = forwardRef(function FilterArea(props, ref) {
-    const { actionsAlign = 'end', children, className, isDirty = true, onReset, onSubmit, resetText = 'Reset', size = 'main', submitText = 'Search', resetButtonType = 'button', submitButtonType = 'button', ...rest } = props;
+    const { actionsAlign = 'end', children, className, isDirty = true, onReset, onSubmit, resetText = 'Reset', rowAlign = 'center', size = 'main', submitText = 'Search', resetButtonType = 'button', submitButtonType = 'button', ...rest } = props;
     const filterLines = useMemo(() => Children.toArray(children), [children]);
+    const contextValue = useMemo(() => ({ size }), [size]);
     const hasMultipleLines = filterLines.length > 1;
     const [expanded, setExpanded] = useState(false);
     const handleToggleExpanded = useCallback(() => {
@@ -23,9 +58,9 @@ const FilterArea = forwardRef(function FilterArea(props, ref) {
         return (jsxs("div", { className: cx(filterAreaClasses.actions, filterAreaClasses.actionsAlign(actionsAlign), { [filterAreaClasses.actionsExpanded]: expanded }), children: [jsx(Button, { onClick: handleSubmit, size: size, type: submitButtonType, children: submitText }), jsx(Button, { disabled: !isDirty, onClick: onReset, size: size, type: resetButtonType, variant: "base-secondary", children: resetText }), hasMultipleLines && (jsx(Button, { "aria-expanded": expanded, "aria-label": expanded ? 'Collapse filters' : 'Expand filters', icon: expanded ? ChevronUpIcon : ChevronDownIcon, iconType: "icon-only", onClick: handleToggleExpanded, size: size, title: expanded ? 'Collapse filters' : 'Expand filters', type: "button", variant: "base-ghost" }))] }));
     };
     const firstLine = filterLines[0];
-    return (jsx("div", { ...rest, ref: ref, className: cx(filterAreaClasses.host, className, {
-            [filterAreaClasses.size(size)]: size,
-        }), children: expanded ? (jsxs(Fragment, { children: [filterLines, jsx("div", { className: filterAreaClasses.row, children: renderAction() })] })) : (jsx(Fragment, { children: firstLine && (jsxs("div", { className: filterAreaClasses.row, children: [firstLine, renderAction()] })) })) }));
+    return (jsx(FilterAreaContext.Provider, { value: contextValue, children: jsx("div", { ...rest, ref: ref, className: cx(filterAreaClasses.host, className, {
+                [filterAreaClasses.size(size)]: size,
+            }), children: expanded ? (jsxs(Fragment, { children: [filterLines, jsx("div", { className: cx(filterAreaClasses.row, filterAreaClasses.rowAlign(rowAlign)), children: renderAction() })] })) : (jsx(Fragment, { children: firstLine && (jsxs("div", { className: cx(filterAreaClasses.row, filterAreaClasses.rowAlign(rowAlign)), children: [firstLine, renderAction()] })) })) }) }));
 });
 
 export { FilterArea as default };

package/FilterArea/FilterAreaContext.d.ts

@@ -0,0 +1,6 @@
+import type { FilterAreaSize } from '@mezzanine-ui/core/filter-area';
+export interface FilterAreaContextValue {
+    size?: FilterAreaSize;
+}
+declare const FilterAreaContext: import("react").Context<FilterAreaContextValue | undefined>;
+export default FilterAreaContext;

package/FilterArea/FilterAreaContext.js

@@ -0,0 +1,6 @@
+'use client';
+import { createContext } from 'react';
+
+const FilterAreaContext = createContext(undefined);
+
+export { FilterAreaContext as default };

package/FilterArea/FilterLine.d.ts

@@ -7,5 +7,24 @@ export interface FilterLineProps extends Omit<NativeElementPropsWithoutKeyAndRef
      */
     children: ReactElement<FilterProps> | ReactElement<FilterProps>[];
 }
+/**
+ * 篩選器中的單行條件列，包含一或多個 Filter 欄位。
+ *
+ * 透過 Grid 排版將 Filter 子元件橫向排列；
+ * 需作為 FilterArea 的直接子元件使用。
+ *
+ * @example
+ * ```tsx
+ * import { Filter, FilterLine } from '@mezzanine-ui/react';
+ *
+ * <FilterLine>
+ *   <Filter span={2}>...</Filter>
+ *   <Filter span={3}>...</Filter>
+ * </FilterLine>
+ * ```
+ *
+ * @see {@link FilterArea} 管理多個 FilterLine 的容器元件
+ * @see {@link Filter} 包裝單一篩選欄位的元件
+ */
 declare const FilterLine: import("react").ForwardRefExoticComponent<FilterLineProps & import("react").RefAttributes<HTMLDivElement>>;
 export default FilterLine;

package/FilterArea/FilterLine.js

@@ -4,6 +4,25 @@ import { forwardRef, useMemo } from 'react';
 import { filterAreaClasses } from '@mezzanine-ui/core/filter-area';
 import cx from 'clsx';
 
+/**
+ * 篩選器中的單行條件列，包含一或多個 Filter 欄位。
+ *
+ * 透過 Grid 排版將 Filter 子元件橫向排列；
+ * 需作為 FilterArea 的直接子元件使用。
+ *
+ * @example
+ * ```tsx
+ * import { Filter, FilterLine } from '@mezzanine-ui/react';
+ *
+ * <FilterLine>
+ *   <Filter span={2}>...</Filter>
+ *   <Filter span={3}>...</Filter>
+ * </FilterLine>
+ * ```
+ *
+ * @see {@link FilterArea} 管理多個 FilterLine 的容器元件
+ * @see {@link Filter} 包裝單一篩選欄位的元件
+ */
 const FilterLine = forwardRef(function FilterLine(props, ref) {
     const { className, children, ...rest } = props;
     const lineClassName = useMemo(() => cx(filterAreaClasses.line, className), [className]);

package/FilterArea/index.d.ts

@@ -1,6 +1,6 @@
+export { default as Filter } from './Filter';
+export type { FilterProps } from './Filter';
 export { default as FilterArea } from './FilterArea';
 export type { FilterAreaProps } from './FilterArea';
 export { default as FilterLine } from './FilterLine';
 export type { FilterLineProps } from './FilterLine';
-export { default as Filter } from './Filter';
-export type { FilterProps } from './Filter';

package/FilterArea/index.js

@@ -1,3 +1,3 @@
+export { default as Filter } from './Filter.js';
 export { default as FilterArea } from './FilterArea.js';
 export { default as FilterLine } from './FilterLine.js';
-export { default as Filter } from './Filter.js';

package/Form/FormField.d.ts

@@ -1,4 +1,4 @@
-import { ControlFieldSlotLayout, FormFieldCounterColor, FormFieldDensity, FormFieldLabelSpacing, FormFieldLayout } from '@mezzanine-ui/core/form';
+import { ControlFieldSlotColumns, ControlFieldSlotLayout, FormFieldCounterColor, FormFieldDensity, FormFieldLabelSpacing, FormFieldLayout } from '@mezzanine-ui/core/form';
 import { NativeElementPropsWithoutKeyAndRef } from '../utils/jsx-types';
 import { IconDefinition } from '@mezzanine-ui/icons';
 import { SeverityWithInfo } from '@mezzanine-ui/system/severity';
@@ -13,6 +13,12 @@ export interface FormFieldProps extends NativeElementPropsWithoutKeyAndRef<'div'
      * @default FormFieldCounterColor.INFO
      */
     counterColor?: FormFieldCounterColor;
+    /**
+     * The number of equal-width columns in the control field slot.
+     * Children are laid out in a CSS Grid with equal-width columns; items wrap into additional rows as needed.
+     * Omit this prop for single-column (default) layout.
+     */
+    controlFieldSlotColumns?: ControlFieldSlotColumns;
     /**
      * The layout variant for the control field slot.
      * Controls the visual styling and appearance of the input control area.
@@ -101,7 +107,42 @@ export interface FormFieldProps extends NativeElementPropsWithoutKeyAndRef<'div'
     severity?: SeverityWithInfo;
 }
 /**
- * The React component for `mezzanine` form field.
+ * 表單欄位容器元件，整合標籤、提示文字與錯誤狀態。
+ *
+ * 透過 `FormControlContext` 將 `disabled`、`required`、`severity` 等狀態向下傳遞給子元件。
+ * 支援水平、垂直與延伸三種排版方式，並可選擇性顯示字數計數器與提示文字圖示。
+ * 當 `disabled` 為 `true` 時，提示訊息將不會顯示。
+ *
+ * @example
+ * ```tsx
+ * import FormField from '@mezzanine-ui/react/Form';
+ * import { TextField } from '@mezzanine-ui/react/TextField';
+ *
+ * // 基本水平排版
+ * <FormField name="username" label="使用者名稱">
+ *   <TextField placeholder="請輸入使用者名稱" />
+ * </FormField>
+ *
+ * // 帶有錯誤提示的垂直排版
+ * <FormField
+ *   name="email"
+ *   label="電子郵件"
+ *   layout="vertical"
+ *   severity="error"
+ *   hintText="電子郵件格式不正確"
+ * >
+ *   <TextField placeholder="請輸入電子郵件" />
+ * </FormField>
+ *
+ * // 帶有字數計數器
+ * <FormField name="bio" label="自我介紹" counter="50/200">
+ *   <TextField placeholder="請輸入自我介紹" />
+ * </FormField>
+ * ```
+ *
+ * @see {@link FormLabel} 表單標籤元件
+ * @see {@link FormHintText} 表單提示文字元件
+ * @see {@link FormControlContext} 表單控制狀態 Context
  */
 declare const FormField: import("react").ForwardRefExoticComponent<FormFieldProps & import("react").RefAttributes<HTMLDivElement>>;
 export default FormField;

package/Form/FormField.js

@@ -7,10 +7,45 @@ import FormLabel from './FormLabel.js';
 import cx from 'clsx';
 
 /**
- * The React component for `mezzanine` form field.
+ * 表單欄位容器元件，整合標籤、提示文字與錯誤狀態。
+ *
+ * 透過 `FormControlContext` 將 `disabled`、`required`、`severity` 等狀態向下傳遞給子元件。
+ * 支援水平、垂直與延伸三種排版方式，並可選擇性顯示字數計數器與提示文字圖示。
+ * 當 `disabled` 為 `true` 時，提示訊息將不會顯示。
+ *
+ * @example
+ * ```tsx
+ * import FormField from '@mezzanine-ui/react/Form';
+ * import { TextField } from '@mezzanine-ui/react/TextField';
+ *
+ * // 基本水平排版
+ * <FormField name="username" label="使用者名稱">
+ *   <TextField placeholder="請輸入使用者名稱" />
+ * </FormField>
+ *
+ * // 帶有錯誤提示的垂直排版
+ * <FormField
+ *   name="email"
+ *   label="電子郵件"
+ *   layout="vertical"
+ *   severity="error"
+ *   hintText="電子郵件格式不正確"
+ * >
+ *   <TextField placeholder="請輸入電子郵件" />
+ * </FormField>
+ *
+ * // 帶有字數計數器
+ * <FormField name="bio" label="自我介紹" counter="50/200">
+ *   <TextField placeholder="請輸入自我介紹" />
+ * </FormField>
+ * ```
+ *
+ * @see {@link FormLabel} 表單標籤元件
+ * @see {@link FormHintText} 表單提示文字元件
+ * @see {@link FormControlContext} 表單控制狀態 Context
  */
 const FormField = forwardRef(function FormField(props, ref) {
-    const { children, className, counter, counterColor, controlFieldSlotLayout = ControlFieldSlotLayout.MAIN, density, disabled = false, fullWidth = false, hintText, hintTextIcon, showHintTextIcon, label, labelInformationIcon, labelInformationText, labelOptionalMarker, labelSpacing = FormFieldLabelSpacing.MAIN, layout = FormFieldLayout.HORIZONTAL, name, required = false, severity = 'info', ...rest } = props;
+    const { children, className, counter, counterColor, controlFieldSlotColumns, controlFieldSlotLayout = ControlFieldSlotLayout.MAIN, density, disabled = false, fullWidth = false, hintText, hintTextIcon, showHintTextIcon, label, labelInformationIcon, labelInformationText, labelOptionalMarker, labelSpacing = FormFieldLabelSpacing.MAIN, layout = FormFieldLayout.HORIZONTAL, name, required = false, severity = 'info', ...rest } = props;
     const formControl = {
         disabled,
         fullWidth,
@@ -28,7 +63,9 @@ const FormField = forwardRef(function FormField(props, ref) {
     return (jsx("div", { ...rest, ref: ref, className: cx(formFieldClasses.host, formFieldClasses.layout(layout), densityClass, {
             [formFieldClasses.disabled]: disabled,
             [formFieldClasses.fullWidth]: fullWidth,
-        }, className), children: jsxs(FormControlContext.Provider, { value: formControl, children: [label && (jsx(FormLabel, { className: cx(formFieldClasses.labelArea, labelSpacingClass), htmlFor: name, informationIcon: labelInformationIcon, informationText: labelInformationText, labelText: label, optionalMarker: labelOptionalMarker })), jsxs("div", { className: cx(formFieldClasses.dataEntry), children: [jsx("div", { className: cx(`${formFieldClasses.controlFieldSlot}--${controlFieldSlotLayout}`), children: children }), hintText || hintTextIcon || counter ? (jsxs("div", { className: cx(formFieldClasses.hintTextAndCounterArea, {
+        }, className), children: jsxs(FormControlContext.Provider, { value: formControl, children: [label && (jsx(FormLabel, { className: cx(formFieldClasses.labelArea, labelSpacingClass), htmlFor: name, informationIcon: labelInformationIcon, informationText: labelInformationText, labelText: label, optionalMarker: labelOptionalMarker })), jsxs("div", { className: cx(formFieldClasses.dataEntry), children: [jsx("div", { className: cx(`${formFieldClasses.controlFieldSlot}--${controlFieldSlotLayout}`, controlFieldSlotColumns
+                                ? formFieldClasses.controlFieldSlotColumns(controlFieldSlotColumns)
+                                : undefined), children: children }), hintText || hintTextIcon || counter ? (jsxs("div", { className: cx(formFieldClasses.hintTextAndCounterArea, {
                                 [formFieldClasses.hintTextAndCounterArea + '--align-right']: !(hintText || hintTextIcon) && counter,
                             }), children: [(hintText || hintTextIcon) && (jsx(FormHintText, { hintText: hintText, hintTextIcon: hintTextIcon, severity: severity, showHintTextIcon: showHintTextIcon })), counter && (jsx("span", { className: cx(formFieldClasses.counter, formFieldClasses.counterColor(counterColor || FormFieldCounterColor.INFO)), children: counter }))] })) : null] })] }) }));
 });

package/Form/typings.d.ts

@@ -1,4 +1,6 @@
 export type FormElementFocusHandlers = {
+    /** 元素失去焦點時觸發。 */
     onBlur?: VoidFunction;
+    /** 元素取得焦點時觸發。 */
     onFocus?: VoidFunction;
 };

package/Form/useAutoCompleteValueControl.d.ts

@@ -40,4 +40,24 @@ export type AutoCompleteSingleValueControl = AutoCompleteBaseValueControl & {
     onChange: (v: SelectValue | null) => SelectValue | null;
     value: SelectValue | null;
 };
+/**
+ * 管理 AutoComplete 搜尋文字與選取值的受控狀態 Hook。
+ *
+ * 根據 `mode` 支援單選（`single`）與多選（`multiple`），並內建選項過濾邏輯、
+ * 焦點狀態追蹤以及清除功能，回傳完整的操作介面供 AutoComplete 元件使用。
+ *
+ * @example
+ * ```tsx
+ * import { useAutoCompleteValueControl } from '@mezzanine-ui/react';
+ *
+ * const control = useAutoCompleteValueControl({
+ *   mode: 'single',
+ *   options: [{ id: '1', name: 'Option A' }],
+ *   disabledOptionsFilter: false,
+ *   onChange: (option) => console.log(option),
+ * });
+ * ```
+ *
+ * @see {@link AutoComplete} 搭配的元件
+ */
 export declare const useAutoCompleteValueControl: (props: UseAutoCompleteValueControl) => AutoCompleteMultipleValueControl | AutoCompleteSingleValueControl;

package/Form/useAutoCompleteValueControl.js

@@ -94,6 +94,26 @@ function useAutoCompleteBaseValueControl(props) {
         value,
     };
 }
+/**
+ * 管理 AutoComplete 搜尋文字與選取值的受控狀態 Hook。
+ *
+ * 根據 `mode` 支援單選（`single`）與多選（`multiple`），並內建選項過濾邏輯、
+ * 焦點狀態追蹤以及清除功能，回傳完整的操作介面供 AutoComplete 元件使用。
+ *
+ * @example
+ * ```tsx
+ * import { useAutoCompleteValueControl } from '@mezzanine-ui/react';
+ *
+ * const control = useAutoCompleteValueControl({
+ *   mode: 'single',
+ *   options: [{ id: '1', name: 'Option A' }],
+ *   disabledOptionsFilter: false,
+ *   onChange: (option) => console.log(option),
+ * });
+ * ```
+ *
+ * @see {@link AutoComplete} 搭配的元件
+ */
 const useAutoCompleteValueControl = (props) => {
     if (props.mode === 'multiple') {
         // eslint-disable-next-line react-hooks/rules-of-hooks

package/Form/useCheckboxControlValue.d.ts

@@ -8,4 +8,23 @@ export interface UseCheckboxControlValueProps extends UseSwitchControlValueProps
     checkboxGroup?: CheckboxGroupControlContextValue;
     value?: string;
 }
+/**
+ * 管理 Checkbox 勾選狀態的受控 Hook。
+ *
+ * 支援獨立使用與在 CheckboxGroup 內使用兩種情境：
+ * 當傳入 `checkboxGroup` 上下文時，會自動從群組的 `value` 陣列中計算出當前勾選狀態。
+ *
+ * @example
+ * ```tsx
+ * import { useCheckboxControlValue } from '@mezzanine-ui/react';
+ *
+ * const [checked, handleChange] = useCheckboxControlValue({
+ *   defaultChecked: false,
+ *   onChange: (e) => console.log(e.target.checked),
+ * });
+ * ```
+ *
+ * @see {@link Checkbox} 搭配的元件
+ * @see {@link CheckboxGroup} 搭配的元件
+ */
 export declare function useCheckboxControlValue(props: UseCheckboxControlValueProps): readonly [boolean, (event: import("react").ChangeEvent<HTMLInputElement>) => void];

package/Form/useCheckboxControlValue.js

@@ -1,5 +1,24 @@
 import { useSwitchControlValue } from './useSwitchControlValue.js';
 
+/**
+ * 管理 Checkbox 勾選狀態的受控 Hook。
+ *
+ * 支援獨立使用與在 CheckboxGroup 內使用兩種情境：
+ * 當傳入 `checkboxGroup` 上下文時，會自動從群組的 `value` 陣列中計算出當前勾選狀態。
+ *
+ * @example
+ * ```tsx
+ * import { useCheckboxControlValue } from '@mezzanine-ui/react';
+ *
+ * const [checked, handleChange] = useCheckboxControlValue({
+ *   defaultChecked: false,
+ *   onChange: (e) => console.log(e.target.checked),
+ * });
+ * ```
+ *
+ * @see {@link Checkbox} 搭配的元件
+ * @see {@link CheckboxGroup} 搭配的元件
+ */
 function useCheckboxControlValue(props) {
     const { checkboxGroup, checked: checkedProp, defaultChecked, onChange: onChangeProp, value, } = props;
     const { onChange: onChangeFromGroup } = checkboxGroup || {};

package/Form/useControlValueState.d.ts

@@ -3,4 +3,20 @@ export interface UseControlValueStateProps<V> {
     equalityFn?: (a: V, b: V) => boolean;
     value?: V;
 }
+/**
+ * 受控／非受控狀態的底層管理 Hook。
+ *
+ * 接受 `value`（受控）與 `defaultValue`（非受控）兩種模式，
+ * 並在 `value` 從外部更新時自動同步內部 state。
+ *
+ * @example
+ * ```tsx
+ * import { useControlValueState } from '@mezzanine-ui/react';
+ *
+ * const [value, setValue, equalityFn] = useControlValueState({
+ *   defaultValue: '',
+ *   value: controlledValue,
+ * });
+ * ```
+ */
 export declare function useControlValueState<V>(props: UseControlValueStateProps<V>): readonly [V, import("react").Dispatch<import("react").SetStateAction<V>>, (a: V, b: V) => boolean];

package/Form/useControlValueState.js

@@ -1,5 +1,21 @@
 import { useState } from 'react';
 
+/**
+ * 受控／非受控狀態的底層管理 Hook。
+ *
+ * 接受 `value`（受控）與 `defaultValue`（非受控）兩種模式，
+ * 並在 `value` 從外部更新時自動同步內部 state。
+ *
+ * @example
+ * ```tsx
+ * import { useControlValueState } from '@mezzanine-ui/react';
+ *
+ * const [value, setValue, equalityFn] = useControlValueState({
+ *   defaultValue: '',
+ *   value: controlledValue,
+ * });
+ * ```
+ */
 function useControlValueState(props) {
     const { defaultValue, equalityFn = (a, b) => a === b, value: valueProp, } = props;
     const [value, setValue] = useState(() => typeof valueProp !== 'undefined' ? valueProp : defaultValue);

package/Form/useCustomControlValue.d.ts

@@ -2,4 +2,21 @@ import { UseControlValueStateProps } from './useControlValueState';
 export interface UseCustomControlValueProps<V> extends UseControlValueStateProps<V> {
     onChange?: (value: V) => void;
 }
+/**
+ * 通用型別受控值管理 Hook。
+ *
+ * 支援任意型別的受控（`value`）與非受控（`defaultValue`）狀態，
+ * 並透過 `equalityFn` 避免不必要的 re-render 與 `onChange` 呼叫。
+ *
+ * @example
+ * ```tsx
+ * import { useCustomControlValue } from '@mezzanine-ui/react';
+ *
+ * const [value, onChange] = useCustomControlValue<number>({
+ *   defaultValue: 0,
+ *   value: controlledNumber,
+ *   onChange: (v) => console.log(v),
+ * });
+ * ```
+ */
 export declare function useCustomControlValue<V>(props: UseCustomControlValueProps<V>): readonly [V, (nextValue: V) => void, (a: V, b: V) => boolean];

package/Form/useCustomControlValue.js

@@ -1,6 +1,23 @@
 import { useLastCallback } from '../hooks/useLastCallback.js';
 import { useControlValueState } from './useControlValueState.js';
 
+/**
+ * 通用型別受控值管理 Hook。
+ *
+ * 支援任意型別的受控（`value`）與非受控（`defaultValue`）狀態，
+ * 並透過 `equalityFn` 避免不必要的 re-render 與 `onChange` 呼叫。
+ *
+ * @example
+ * ```tsx
+ * import { useCustomControlValue } from '@mezzanine-ui/react';
+ *
+ * const [value, onChange] = useCustomControlValue<number>({
+ *   defaultValue: 0,
+ *   value: controlledNumber,
+ *   onChange: (v) => console.log(v),
+ * });
+ * ```
+ */
 function useCustomControlValue(props) {
     const { onChange: onChangeProp } = props;
     const [value, setValue, equalityFn] = useControlValueState(props);

package/Form/useInputControlValue.d.ts

@@ -4,4 +4,23 @@ export interface UseInputControlValueProps<E extends HTMLInputElement | HTMLText
     defaultValue?: string;
     onChange?: ChangeEventHandler<E>;
 }
+/**
+ * 管理 Input／Textarea 文字值的受控狀態 Hook。
+ *
+ * 支援受控（`value`）與非受控（`defaultValue`）兩種用法，
+ * 回傳當前文字值與穩定的 `onChange` 事件處理器。
+ *
+ * @example
+ * ```tsx
+ * import { useInputControlValue } from '@mezzanine-ui/react';
+ *
+ * function MyInput({ value, onChange }) {
+ *   const [inputValue, handleChange] = useInputControlValue({ value, onChange });
+ *   return <input value={inputValue} onChange={handleChange} />;
+ * }
+ * ```
+ *
+ * @see {@link Input} 搭配的元件
+ * @see {@link Textarea} 搭配的元件
+ */
 export declare function useInputControlValue<E extends HTMLInputElement | HTMLTextAreaElement>(props: UseInputControlValueProps<E>): readonly [string, (event: import("react").ChangeEvent<E>) => void];