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

package/Section/index.d.ts

@@ -1,2 +1,4 @@
 export type { SectionProps } from './Section';
 export { default } from './Section';
+export { default as SectionGroup } from './SectionGroup';
+export type { SectionGroupProps } from './SectionGroup';

package/Section/index.js

@@ -1 +1,2 @@
 export { default } from './Section.js';
+export { default as SectionGroup } from './SectionGroup.js';

package/Select/Select.d.ts

@@ -1,4 +1,4 @@
-import { DropdownOption, DropdownType } from '@mezzanine-ui/core/dropdown/dropdown';
+import { DropdownLoadingPosition, DropdownOption, DropdownType } from '@mezzanine-ui/core/dropdown/dropdown';
 import { SelectInputSize } from '@mezzanine-ui/core/select';
 import { FormElementFocusHandlers } from '../Form';
 import { SelectTriggerInputProps, SelectTriggerProps, SelectValue } from './typings';
@@ -59,6 +59,28 @@ export interface SelectBaseProps extends Omit<SelectTriggerProps, 'active' | 'in
      * @default true
      */
     globalPortal?: boolean;
+    /**
+     * Whether the dropdown is in a loading state.
+     * @default false
+     */
+    loading?: boolean;
+    /**
+     * The position of the loading indicator.
+     * @default 'bottom'
+     */
+    loadingPosition?: DropdownLoadingPosition;
+    /**
+     * The text displayed while loading.
+     */
+    loadingText?: string;
+    /**
+     * Callback fired when the dropdown list leaves the bottom.
+     */
+    onLeaveBottom?: () => void;
+    /**
+     * Callback fired when the dropdown list reaches the bottom.
+     */
+    onReachBottom?: () => void;
 }
 export type SelectMultipleProps = SelectBaseProps & {
     /**
@@ -107,5 +129,37 @@ export type SelectSingleProps = SelectBaseProps & {
     value?: SelectValue | null;
 };
 export type SelectProps = SelectMultipleProps | SelectSingleProps;
+/**
+ * 下拉選擇元件，支援單選與多選兩種模式。
+ *
+ * 透過 `mode` 切換 `single`（單選，預設）或 `multiple`（多選，以標籤呈現已選項目）。
+ * 傳入 `options` 陣列即可自動建立下拉選單；多選模式下若 options 含有 `children` 巢狀結構，
+ * 會自動切換為樹狀選取（`type: 'tree'`）並為所有選項加上勾選框。
+ * 支援 `clearable`、`readOnly`、`loading` 狀態，以及透過 `renderValue` 自訂顯示文字。
+ *
+ * @example
+ * ```tsx
+ * import Select from '@mezzanine-ui/react/Select';
+ *
+ * const options = [
+ *   { id: '1', name: '選項一' },
+ *   { id: '2', name: '選項二' },
+ *   { id: '3', name: '選項三' },
+ * ];
+ *
+ * // 單選
+ * <Select options={options} placeholder="請選擇" onChange={(val) => console.log(val)} />
+ *
+ * // 多選
+ * <Select mode="multiple" options={options} placeholder="可多選" onChange={(vals) => console.log(vals)} />
+ *
+ * // 帶搜尋功能（搭配 AutoComplete）
+ * <Select options={options} clearable placeholder="選擇或搜尋" />
+ * ```
+ *
+ * @see {@link AutoComplete} 支援自由輸入文字的搜尋下拉元件
+ * @see {@link Dropdown} Select 底層使用的下拉清單容器元件
+ * @see {@link useSelectValueControl} 用於在受控模式下管理選取值的 Hook
+ */
 declare const Select: import("react").ForwardRefExoticComponent<SelectProps & import("react").RefAttributes<HTMLDivElement>>;
 export default Select;

package/Select/Select.js

@@ -11,9 +11,44 @@ import { FormControlContext } from '../Form/FormControlContext.js';
 import Dropdown from '../Dropdown/Dropdown.js';
 import cx from 'clsx';
 
+/**
+ * 下拉選擇元件，支援單選與多選兩種模式。
+ *
+ * 透過 `mode` 切換 `single`（單選，預設）或 `multiple`（多選，以標籤呈現已選項目）。
+ * 傳入 `options` 陣列即可自動建立下拉選單；多選模式下若 options 含有 `children` 巢狀結構，
+ * 會自動切換為樹狀選取（`type: 'tree'`）並為所有選項加上勾選框。
+ * 支援 `clearable`、`readOnly`、`loading` 狀態，以及透過 `renderValue` 自訂顯示文字。
+ *
+ * @example
+ * ```tsx
+ * import Select from '@mezzanine-ui/react/Select';
+ *
+ * const options = [
+ *   { id: '1', name: '選項一' },
+ *   { id: '2', name: '選項二' },
+ *   { id: '3', name: '選項三' },
+ * ];
+ *
+ * // 單選
+ * <Select options={options} placeholder="請選擇" onChange={(val) => console.log(val)} />
+ *
+ * // 多選
+ * <Select mode="multiple" options={options} placeholder="可多選" onChange={(vals) => console.log(vals)} />
+ *
+ * // 帶搜尋功能（搭配 AutoComplete）
+ * <Select options={options} clearable placeholder="選擇或搜尋" />
+ * ```
+ *
+ * @see {@link AutoComplete} 支援自由輸入文字的搜尋下拉元件
+ * @see {@link Dropdown} Select 底層使用的下拉清單容器元件
+ * @see {@link useSelectValueControl} 用於在受控模式下管理選取值的 Hook
+ */
 const Select = forwardRef(function Select(props, ref) {
     const { disabled: disabledFromFormControl, fullWidth: fullWidthFromFormControl, required: requiredFromFormControl, severity, } = useContext(FormControlContext) || {};
-    const { className, clearable = false, defaultValue, disabled = disabledFromFormControl || false, error = severity === 'error' || false, fullWidth = fullWidthFromFormControl || false, inputProps, inputRef, menuMaxHeight, mode = 'single', onBlur, onChange: onChangeProp, onClear: onClearProp, onFocus, onScroll, options: optionsProp, placeholder = '', prefix, readOnly = false, renderValue, required = requiredFromFormControl || false, size, suffixActionIcon, type = 'default', value: valueProp, dropdownZIndex, globalPortal = true, } = props;
+    const { className, clearable = false, defaultValue, disabled = disabledFromFormControl || false, error = severity === 'error' || false, fullWidth = fullWidthFromFormControl || false, inputProps, inputRef, loading = false, loadingPosition = 'bottom', loadingText, menuMaxHeight, mode = 'single', onBlur, onChange: onChangeProp, onClear: onClearProp, onFocus, onLeaveBottom, onReachBottom, onScroll, options: optionsProp, placeholder = '', prefix, readOnly = false, renderValue, required = requiredFromFormControl || false, overflowStrategy, size, suffixActionIcon, type = 'default', value: valueProp, dropdownZIndex, globalPortal = true, } = props;
+    const dropdownStatus = loading
+        ? 'loading'
+        : undefined;
     const [open, toggleOpen] = useState(false);
     const onOpen = useCallback(() => {
         // Prevent opening when readOnly is true
@@ -221,7 +256,7 @@ const Select = forwardRef(function Select(props, ref) {
         onChange,
         value,
     }), [onChange, value]);
-    return (jsx(SelectControlContext.Provider, { value: context, children: jsx("div", { ref: nodeRef, className: cx(selectClasses.host, fullWidth && selectClasses.hostFullWidth, mode && selectClasses.hostMode(mode)), children: jsx(Dropdown, { disabled: readOnly || disabled, maxHeight: menuMaxHeight, mode: mode, onScroll: onScroll, onSelect: handleDropdownSelect, onVisibilityChange: handleVisibilityChange, open: readOnly ? false : open, options: options, sameWidth: true, type: dropdownType, value: dropdownValue, zIndex: dropdownZIndex, globalPortal: globalPortal, children: jsx(SelectTrigger, { ref: composedRef, active: !readOnly && open, className: className, clearable: clearable, disabled: disabled, error: error, fullWidth: fullWidth, inputRef: inputRef, mode: mode, onTagClose: onChange, onClear: onClear, onKeyDown: onKeyDownTextField, prefix: prefix, readOnly: readOnly, ...(mode === 'single' && renderValue ? { renderValue } : {}), required: required, inputProps: resolvedInputProps, size: size, suffixActionIcon: suffixActionIcon, value: value === null ? undefined : value, placeholder: getPlaceholder() }) }) }) }));
+    return (jsx(SelectControlContext.Provider, { value: context, children: jsx("div", { ref: nodeRef, className: cx(selectClasses.host, fullWidth && selectClasses.hostFullWidth, mode && selectClasses.hostMode(mode)), children: jsx(Dropdown, { disabled: readOnly || disabled, globalPortal: globalPortal, loadingPosition: loadingPosition, loadingText: loadingText, maxHeight: menuMaxHeight, mode: mode, onLeaveBottom: onLeaveBottom, onReachBottom: onReachBottom, onScroll: onScroll, onSelect: handleDropdownSelect, onVisibilityChange: handleVisibilityChange, open: readOnly ? false : open, options: options, sameWidth: true, status: dropdownStatus, type: dropdownType, value: dropdownValue, zIndex: dropdownZIndex, children: jsx(SelectTrigger, { ref: composedRef, active: !readOnly && open, className: className, clearable: clearable, disabled: disabled, error: error, fullWidth: fullWidth, inputRef: inputRef, mode: mode, onTagClose: onChange, onClear: onClear, onKeyDown: onKeyDownTextField, prefix: prefix, readOnly: readOnly, ...(mode === 'single' && renderValue ? { renderValue } : {}), required: required, inputProps: resolvedInputProps, overflowStrategy: overflowStrategy, size: size, suffixActionIcon: suffixActionIcon, value: value === null ? undefined : value, placeholder: getPlaceholder() }) }) }) }));
 });
 
 export { Select as default };

package/Select/typings.d.ts

@@ -4,11 +4,15 @@ import Icon, { IconProps } from '../Icon';
 import { TextFieldProps } from '../TextField';
 import { NativeElementPropsWithoutKeyAndRef } from '../utils/jsx-types';
 export interface SelectValue<T = string> {
+    /** 選項的唯一識別值。 */
     id: T;
+    /** 選項的顯示文字。 */
     name: string;
 }
 export interface SelectControl<T = string> {
+    /** 當前選取的值，單選為 SelectValue | null，多選為 SelectValue[]。 */
     value: SelectValue<T>[] | SelectValue<T> | null;
+    /** 選取變更時的回呼函式。 */
     onChange: (v: SelectValue<T> | null) => SelectValue<T>[] | SelectValue<T> | null;
 }
 export type SelectTriggerInputProps = Omit<NativeElementPropsWithoutKeyAndRef<'input'>, 'autoComplete' | 'children' | 'defaultValue' | 'disabled' | 'required' | 'type' | 'value' | `aria-${'autocomplete' | 'disabled' | 'haspopup' | 'multiline' | 'required'}`>;
@@ -59,7 +63,12 @@ export interface SelectTriggerBaseProps extends Omit<TextFieldProps, 'active' |
      * @default false
      */
     required?: boolean;
+    /** 觸發器輸入框中的搜尋/篩選文字，用於過濾下拉選項。 */
     searchText?: string;
+    /**
+     * 多選模式下是否在已選標籤後顯示文字輸入框，啟用行內搜尋。
+     * @default false
+     */
     showTextInputAfterTags?: boolean;
     /** Suffix icon click event handler */
     suffixAction?: VoidFunction;

package/{Selection/Selection.d.ts → SelectionCard/SelectionCard.d.ts}

@@ -1,8 +1,8 @@
-import { ChangeEventHandler, MouseEvent, Ref } from 'react';
+import { CSSProperties, ChangeEventHandler, MouseEvent, Ref } from 'react';
 import { NativeElementPropsWithoutKeyAndRef } from '../utils/jsx-types';
-import { SelectionDirection, SelectionImageObjectFit, SelectionType } from '@mezzanine-ui/core/selection';
+import { SelectionCardDirection, SelectionCardImageObjectFit, SelectionCardType } from '@mezzanine-ui/core/selection-card';
 import type { IconDefinition } from '@mezzanine-ui/icons';
-export interface SelectionPropsBase extends Omit<NativeElementPropsWithoutKeyAndRef<'label'>, 'onChange'> {
+export interface SelectionCardPropsBase extends Omit<NativeElementPropsWithoutKeyAndRef<'label'>, 'onChange'> {
     /**
      * Whether the selection is checked.
      */
@@ -16,7 +16,7 @@ export interface SelectionPropsBase extends Omit<NativeElementPropsWithoutKeyAnd
      * The type of selection.
      * @default 'radio'
      */
-    selector: SelectionType;
+    selector: SelectionCardType;
     /**
      * If true, selection will be disabled
      * @default false
@@ -26,7 +26,7 @@ export interface SelectionPropsBase extends Omit<NativeElementPropsWithoutKeyAnd
      * The direction of selection.
      * @default 'horizontal'
      */
-    direction?: SelectionDirection;
+    direction?: SelectionCardDirection;
     /**
      * The image of selection. Supports image URL.
      */
@@ -35,7 +35,7 @@ export interface SelectionPropsBase extends Omit<NativeElementPropsWithoutKeyAnd
      * The object fit of selection image.
      * @default 'cover'
      */
-    imageObjectFit?: SelectionImageObjectFit;
+    imageObjectFit?: SelectionCardImageObjectFit;
     /**
      * The custom icon of selection.
      */
@@ -54,10 +54,22 @@ export interface SelectionPropsBase extends Omit<NativeElementPropsWithoutKeyAnd
      * The accessible text of selection.
      */
     text: string;
+    /**
+     * The max width of the text element.
+     * @example '112px' // 8 Chinese characters at 14px
+     * @example '168px' // 24 English letters at 14px
+     */
+    textMaxWidth?: CSSProperties['maxWidth'];
     /**
      * The accessible description of selection.
      */
     supportingText?: string;
+    /**
+     * The max width of the supporting text element.
+     * @example '144px' // 12 Chinese characters at 12px
+     * @example '216px' // 36 English letters at 12px
+     */
+    supportingTextMaxWidth?: CSSProperties['maxWidth'];
     /**
      * Whether the selection is readonly.
      * @default false
@@ -76,7 +88,7 @@ export interface SelectionPropsBase extends Omit<NativeElementPropsWithoutKeyAnd
      * @important When using with react-hook-form's `register`, pass the ref through this prop:
      * ```tsx
      * const { register } = useForm();
-     * <Selection inputRef={register('fieldName').ref} name="fieldName" />
+     * <SelectionCard inputRef={register('fieldName').ref} name="fieldName" />
      * ```
      */
     inputRef?: Ref<HTMLInputElement>;
@@ -85,14 +97,14 @@ export interface SelectionPropsBase extends Omit<NativeElementPropsWithoutKeyAnd
      */
     onChange?: ChangeEventHandler<HTMLInputElement>;
 }
-export interface SelectionProps extends SelectionPropsBase {
+export interface SelectionCardProps extends SelectionCardPropsBase {
     /**
      * Callback when the selection is clicked.
      */
     onClick?: (event: MouseEvent<HTMLLabelElement>) => void;
 }
 /**
- * The react component for `mezzanine` selection.
+ * The react component for `mezzanine` selection card.
  */
-declare const Selection: import("react").ForwardRefExoticComponent<SelectionProps & import("react").RefAttributes<HTMLLabelElement>>;
-export default Selection;
+declare const SelectionCard: import("react").ForwardRefExoticComponent<SelectionCardProps & import("react").RefAttributes<HTMLLabelElement>>;
+export default SelectionCard;

package/{Selection/Selection.js → SelectionCard/SelectionCard.js}

@@ -2,19 +2,19 @@
 import { jsxs, jsx } from 'react/jsx-runtime';
 import { forwardRef, useId, useMemo } from 'react';
 import Typography from '../Typography/Typography.js';
-import { selectionClasses } from '@mezzanine-ui/core/selection';
+import { selectionCardClasses } from '@mezzanine-ui/core/selection-card';
 import { FileIcon } from '@mezzanine-ui/icons';
 import Icon from '../Icon/Icon.js';
 import cx from 'clsx';
 
-// Icon size constant for Selection component
+// Icon size constant for SelectionCard component
 // Note: This value is component-specific and doesn't have a corresponding design token
 const SELECTION_ICON_SIZE = 26;
 /**
- * The react component for `mezzanine` selection.
+ * The react component for `mezzanine` selection card.
  */
-const Selection = forwardRef(function Selection(props, ref) {
-    const { checked: checkedProp, className, defaultChecked = false, disabled = false, direction = 'horizontal', id, image, imageObjectFit = 'cover', inputRef: inputRefProp, name, onChange: onChangeProp, readonly = false, selector = 'radio', supportingText, text, value, customIcon, onClick, ...rest } = props;
+const SelectionCard = forwardRef(function SelectionCard(props, ref) {
+    const { checked: checkedProp, className, defaultChecked = false, disabled = false, direction = 'horizontal', id, image, imageObjectFit = 'cover', inputRef: inputRefProp, name, onChange: onChangeProp, readonly = false, selector = 'radio', supportingText, supportingTextMaxWidth, text, textMaxWidth, value, customIcon, onClick, ...rest } = props;
     const generatedId = useId();
     const inputId = id !== null && id !== void 0 ? id : generatedId;
     const textId = useMemo(() => `${inputId}-text`, [inputId]);
@@ -25,22 +25,22 @@ const Selection = forwardRef(function Selection(props, ref) {
     };
     const haveImage = useMemo(() => Boolean(image && typeof image === 'string' && image.trim().length > 0), [image]);
     if (!text) {
-        console.error('Selection: `text` (title) is required.');
+        console.error('SelectionCard: `text` (title) is required.');
         return null;
     }
     if (!supportingText) {
-        console.warn('Selection: `supportingText` is optional but strongly recommended for better accessibility.');
+        console.warn('SelectionCard: `supportingText` is optional but strongly recommended for better accessibility.');
     }
-    return (jsxs("label", { ...rest, ref: ref, htmlFor: inputId, className: cx(selectionClasses.host, selectionClasses.direction(direction), {
-            [selectionClasses.disabled]: disabled,
-            [selectionClasses.readonly]: readonly,
-        }, className), ...(disabled && { 'aria-disabled': true }), ...(onClick && { onClick }), children: [jsxs("div", { className: selectionClasses.container, children: [haveImage
-                        ? jsx("img", { src: image, alt: text, className: selectionClasses.selectionImage, style: { objectFit: imageObjectFit } })
-                        : jsx(Icon, { "aria-hidden": "true", className: selectionClasses.icon, color: "neutral-solid", icon: customIcon || FileIcon, size: SELECTION_ICON_SIZE }), jsxs("div", { className: selectionClasses.content, children: [jsx(Typography, { className: selectionClasses.text, color: "text-neutral-solid", display: "block", ellipsis: true, id: textId, variant: "body-highlight", children: text }), supportingText && (jsx(Typography, { className: selectionClasses.supportingText, color: "text-neutral", display: "block", ellipsis: true, id: supportingTextId, variant: "caption", children: supportingText }))] })] }), !readonly && (jsx("input", { ref: inputRefProp, type: selector, name: name, id: inputId, className: selectionClasses.input, disabled: disabled, ...(checkedProp !== undefined
+    return (jsxs("label", { ...rest, ref: ref, htmlFor: inputId, className: cx(selectionCardClasses.host, selectionCardClasses.direction(direction), {
+            [selectionCardClasses.disabled]: disabled,
+            [selectionCardClasses.readonly]: readonly,
+        }, className), ...(disabled && { 'aria-disabled': true }), ...(onClick && { onClick }), children: [jsxs("div", { className: selectionCardClasses.container, children: [haveImage
+                        ? jsx("img", { src: image, alt: text, className: selectionCardClasses.selectionImage, style: { objectFit: imageObjectFit } })
+                        : jsx(Icon, { "aria-hidden": "true", className: selectionCardClasses.icon, color: "neutral-solid", icon: customIcon || FileIcon, size: SELECTION_ICON_SIZE }), jsxs("div", { className: selectionCardClasses.content, children: [jsx(Typography, { className: selectionCardClasses.text, color: "text-neutral-solid", display: "block", ellipsis: true, id: textId, style: textMaxWidth !== undefined ? { maxWidth: textMaxWidth } : undefined, variant: "body-highlight", children: text }), supportingText && (jsx(Typography, { className: selectionCardClasses.supportingText, color: "text-neutral", display: "block", ellipsis: true, id: supportingTextId, style: supportingTextMaxWidth !== undefined ? { maxWidth: supportingTextMaxWidth } : undefined, variant: "caption", children: supportingText }))] })] }), !readonly && (jsx("input", { ref: inputRefProp, type: selector, name: name, id: inputId, className: selectionCardClasses.input, disabled: disabled, ...(checkedProp !== undefined
                     ? { checked: checkedProp }
                     : { defaultChecked }), value: value, onChange: onInputChange, ...(isRadioOrCheckbox && checkedProp !== undefined
                     ? { 'aria-checked': checkedProp }
                     : {}), "aria-labelledby": textId, "aria-describedby": supportingText ? supportingTextId : undefined }))] }));
 });
 
-export { Selection as default };
+export { SelectionCard as default };

package/SelectionCard/SelectionCardGroup.d.ts

@@ -0,0 +1,28 @@
+import { ComponentProps, ReactElement } from 'react';
+import { NativeElementPropsWithoutKeyAndRef } from '../utils/jsx-types';
+import SelectionCard, { SelectionCardProps } from './SelectionCard';
+export interface SelectionCardGroupBaseProps extends Omit<NativeElementPropsWithoutKeyAndRef<'div'>, 'children'> {
+    /**
+     * The class name of the selection group.
+     */
+    className?: string;
+}
+export interface SelectionCardGroupProps extends SelectionCardGroupBaseProps {
+    /**
+     * The selections in the group.
+     * Only SelectionCard components are allowed.
+     * When provided, will take priority over selections prop.
+     */
+    children?: ReactElement<ComponentProps<typeof SelectionCard>> | ReactElement<ComponentProps<typeof SelectionCard>>[];
+    /**
+     * The selections array.
+     * When provided, SelectionCard components will be automatically rendered.
+     * Will be ignored if children is provided.
+     */
+    selections?: SelectionCardProps[];
+}
+/**
+ * The react component for `mezzanine` selection card group.
+ */
+declare const SelectionCardGroup: import("react").ForwardRefExoticComponent<SelectionCardGroupProps & import("react").RefAttributes<HTMLDivElement>>;
+export default SelectionCardGroup;

package/SelectionCard/index.d.ts

@@ -0,0 +1,12 @@
+import { PropsWithoutRef, ReactElement, RefAttributes } from 'react';
+import SelectionCard, { SelectionCardProps, SelectionCardPropsBase } from './SelectionCard';
+export type { SelectionCardDirection, SelectionCardType, } from '@mezzanine-ui/core/selection-card';
+export type { SelectionCardProps, SelectionCardPropsBase };
+/**
+ * @remark
+ * Add type alias here for parsable to react docgen typescript.
+ */
+type GenericSelectionCard = (props: PropsWithoutRef<SelectionCardProps> & RefAttributes<HTMLLabelElement>) => ReactElement<any>;
+export { SelectionCard };
+declare const _default: GenericSelectionCard;
+export default _default;

package/SelectionCard/index.js

@@ -0,0 +1,5 @@
+import SelectionCard from './SelectionCard.js';
+
+
+
+export { SelectionCard, SelectionCard as default };

package/Separator/Separator.d.ts

@@ -8,7 +8,25 @@ export interface SeparatorProps extends NativeElementPropsWithoutKeyAndRef<'hr'>
     orientation?: SeparatorOrientation;
 }
 /**
- * The react component for `mezzanine` separator.
+ * 水平或垂直分隔線元件。
+ *
+ * 以 `<hr>` 元素為基礎，透過 `orientation` prop 切換水平與垂直方向。
+ * 垂直方向時會自動設置 `aria-orientation="vertical"` 以符合無障礙規範。
+ *
+ * @example
+ * ```tsx
+ * import Separator from '@mezzanine-ui/react/Separator';
+ *
+ * // 水平分隔線（預設）
+ * <Separator />
+ *
+ * // 垂直分隔線
+ * <div style={{ display: 'flex', alignItems: 'center' }}>
+ *   <span>左側內容</span>
+ *   <Separator orientation="vertical" />
+ *   <span>右側內容</span>
+ * </div>
+ * ```
  */
 declare const Separator: import("react").ForwardRefExoticComponent<SeparatorProps & import("react").RefAttributes<HTMLHRElement>>;
 export default Separator;

package/Separator/Separator.js

@@ -4,7 +4,25 @@ import { forwardRef } from 'react';
 import cx from 'clsx';
 
 /**
- * The react component for `mezzanine` separator.
+ * 水平或垂直分隔線元件。
+ *
+ * 以 `<hr>` 元素為基礎，透過 `orientation` prop 切換水平與垂直方向。
+ * 垂直方向時會自動設置 `aria-orientation="vertical"` 以符合無障礙規範。
+ *
+ * @example
+ * ```tsx
+ * import Separator from '@mezzanine-ui/react/Separator';
+ *
+ * // 水平分隔線（預設）
+ * <Separator />
+ *
+ * // 垂直分隔線
+ * <div style={{ display: 'flex', alignItems: 'center' }}>
+ *   <span>左側內容</span>
+ *   <Separator orientation="vertical" />
+ *   <span>右側內容</span>
+ * </div>
+ * ```
  */
 const Separator = forwardRef(function Separator(props, ref) {
     const { className, orientation = 'horizontal', ...rest } = props;

package/Slider/Slider.d.ts

@@ -39,9 +39,13 @@ export interface SliderBaseProps extends Omit<NativeElementPropsWithoutKeyAndRef
     withTick?: number | number[];
 }
 export type SliderWithInputProps = SliderBaseProps & {
+    /** 此配置下不適用。 */
     onPrefixIconClick?: never;
+    /** 此配置下不適用。 */
     onSuffixIconClick?: never;
+    /** 此配置下不適用。 */
     prefixIcon?: never;
+    /** 此配置下不適用。 */
     suffixIcon?: never;
     /**
      * Whether to show input box to allow user to input value.
@@ -68,14 +72,20 @@ export type SliderWithIconProps = SliderBaseProps & {
     withInput?: never;
 };
 export type SliderWithoutAddonsProps = SliderBaseProps & {
+    /** 此配置下不適用。 */
     onPrefixIconClick?: never;
+    /** 此配置下不適用。 */
     onSuffixIconClick?: never;
+    /** 此配置下不適用。 */
     prefixIcon?: never;
+    /** 此配置下不適用。 */
     suffixIcon?: never;
+    /** 此配置下不適用。 */
     withInput?: never;
 };
 export type SliderAddonProps = SliderWithInputProps | SliderWithIconProps | SliderWithoutAddonsProps;
 export type SingleSliderProps = SliderAddonProps & {
+    /** 滑桿值變更時的回呼函式。 */
     onChange?: (value: SingleSliderValue) => void;
     /**
      * The value of the slider.
@@ -83,6 +93,7 @@ export type SingleSliderProps = SliderAddonProps & {
     value: UseSingleSliderProps['value'];
 };
 export type RangeSliderProps = SliderAddonProps & {
+    /** 範圍滑桿值變更時的回呼函式，回傳 [min, max] 元組。 */
     onChange?: (value: RangeSliderValue) => void;
     /**
      * The value of the slider.

package/Slider/useSlider.d.ts

@@ -27,5 +27,26 @@ export interface UseSliderResult {
     handlePress: (e: any, index?: number | undefined) => void;
     railRef: RefObject<HTMLDivElement | null>;
 }
+/**
+ * 管理 Slider 拖曳互動與 CSS 變數計算的 Hook。
+ *
+ * 支援單值（`SingleSliderValue`）與範圍值（`RangeSliderValue`）兩種模式，
+ * 處理滑鼠／觸控拖曳事件並計算出對應的 CSS 自訂屬性供樣式使用。
+ *
+ * @example
+ * ```tsx
+ * import { useSlider } from '@mezzanine-ui/react';
+ *
+ * const { cssVars, handlePress, handleClickTrackOrRail, railRef } = useSlider({
+ *   min: 0,
+ *   max: 100,
+ *   step: 1,
+ *   value: sliderValue,
+ *   onChange: (v) => setSliderValue(v),
+ * });
+ * ```
+ *
+ * @see {@link Slider} 搭配的元件
+ */
 export declare function useSlider(props: UseRangeSliderProps): UseSliderResult;
 export declare function useSlider(props: UseSingleSliderProps): UseSliderResult;

package/Spin/Spin.d.ts

@@ -1,8 +1,14 @@
-import { IconProps } from '../Icon';
 import { BackdropProps } from '../Backdrop';
 import { NativeElementPropsWithoutKeyAndRef } from '../utils/jsx-types';
 import { GeneralSize } from '@mezzanine-ui/system/size';
 export interface SpinProps extends NativeElementPropsWithoutKeyAndRef<'div'> {
+    /**
+     * Custom color for the spinner arc animation.
+     * Sets the `--mzn-spin--color` CSS variable on the ring element.
+     * Accepts any valid CSS color value.
+     * @default palette icon brand color
+     */
+    color?: string;
     /**
      * Customize description content
      */
@@ -21,15 +27,18 @@ export interface SpinProps extends NativeElementPropsWithoutKeyAndRef<'div'> {
      * @default false
      */
     stretch?: boolean;
-    /**
-     * Custom icon props
-     */
-    iconProps?: Omit<IconProps, 'icon' | 'spin'>;
     /**
      * Whether Spin is loading.
      * @default false
      */
     loading?: boolean;
+    /**
+     * Custom color for the spinner track (the non-animated ring background).
+     * Sets the `--mzn-spin--track-color` CSS variable on the ring element.
+     * Accepts any valid CSS color value.
+     * @default transparent
+     */
+    trackColor?: string;
     /**
      * Custom backdrop props (only display when nested children)
      */

package/Spin/Spin.js

@@ -1,24 +1,22 @@
 import { jsxs, jsx } from 'react/jsx-runtime';
 import { forwardRef, useRef } from 'react';
-import { SpinnerIcon } from '@mezzanine-ui/icons';
 import { iconClasses } from '@mezzanine-ui/core/spin';
 import { useComposeRefs } from '../hooks/useComposeRefs.js';
-import Icon from '../Icon/Icon.js';
 import Backdrop from '../Backdrop/Backdrop.js';
 import cx from 'clsx';
 
 const Spin = forwardRef(function Spin(props, ref) {
     const hostRef = useRef(null);
-    const { children, className, description, descriptionClassName, stretch = false, size = 'main', iconProps = {}, loading = false, backdropProps = {}, } = props;
-    const { className: iconClassName, color: iconColor, size: iconSize, style: iconStyle, ...iconPropsRest } = iconProps;
+    const { children, className, color, description, descriptionClassName, stretch = false, size = 'main', loading = false, trackColor, backdropProps = {}, } = props;
     const isNestedPattern = typeof children !== 'undefined';
     const composedHostRef = useComposeRefs([ref, hostRef]);
+    const ringVars = {
+        ...(color && { '--mzn-spin--color': color }),
+        ...(trackColor && { '--mzn-spin--track-color': trackColor }),
+    };
     const spinElement = loading ? (jsxs("div", { ref: isNestedPattern ? null : ref, className: cx(iconClasses.spin, iconClasses.size(size), {
             [iconClasses.stretch]: stretch,
-        }), children: [jsx(Icon, { ...iconPropsRest, className: cx(iconClasses.icon, iconClassName), color: iconColor, icon: SpinnerIcon, spin: true, style: {
-                    ...(iconSize ? { fontSize: `${iconSize}px` } : {}),
-                    ...(iconStyle || {}),
-                } }), description ? (jsx("span", { className: cx(iconClasses.description, descriptionClassName), children: description })) : null] })) : null;
+        }), children: [jsx("span", { className: iconClasses.spinnerRing, style: ringVars, children: jsx("span", { className: iconClasses.spinnerTail }) }), description ? (jsx("span", { className: cx(iconClasses.description, descriptionClassName), children: description })) : null] })) : null;
     if (isNestedPattern) {
         return (jsxs("div", { ref: composedHostRef, className: cx(iconClasses.host, {
                 [iconClasses.stretch]: stretch,

package/Stepper/Stepper.d.ts

@@ -1,6 +1,39 @@
 import { StepperProps } from './typings';
 /**
- * The react component for `mezzanine` stepper.
+ * 步驟進度指示器元件，以線性流程呈現多個步驟的完成狀態。
+ *
+ * 子元件必須為 `<Step />` 元件；`currentStep` 控制當前進行中的步驟（零基索引），
+ * 之前的步驟自動標記為已完成，之後的步驟為待處理。支援 `horizontal`（水平）與
+ * `vertical`（垂直）排列，以及 `number`（數字）與 `dot`（圓點）兩種指示器樣式。
+ *
+ * @example
+ * ```tsx
+ * import Stepper from '@mezzanine-ui/react/Stepper';
+ * import Step from '@mezzanine-ui/react/Step';
+ *
+ * // 水平數字步驟條
+ * <Stepper currentStep={1}>
+ *   <Step title="填寫資料" description="請輸入基本資訊" />
+ *   <Step title="確認內容" description="核對填寫資料" />
+ *   <Step title="完成送出" />
+ * </Stepper>
+ *
+ * // 垂直圓點步驟條
+ * <Stepper currentStep={0} orientation="vertical" type="dot">
+ *   <Step title="步驟一" />
+ *   <Step title="步驟二" />
+ *   <Step title="步驟三" />
+ * </Stepper>
+ *
+ * // 監聽步驟變化
+ * <Stepper currentStep={step} onStepChange={(idx) => console.log('step:', idx)}>
+ *   <Step title="A" />
+ *   <Step title="B" />
+ *   <Step title="C" />
+ * </Stepper>
+ * ```
+ *
+ * @see {@link useStepper} 管理步驟狀態的 hook
  */
 declare const Stepper: import("react").ForwardRefExoticComponent<StepperProps & import("react").RefAttributes<HTMLDivElement>>;
 export default Stepper;

package/Stepper/Stepper.js

@@ -5,7 +5,40 @@ import { useStepDistance } from './useStepDistance.js';
 import cx from 'clsx';
 
 /**
- * The react component for `mezzanine` stepper.
+ * 步驟進度指示器元件，以線性流程呈現多個步驟的完成狀態。
+ *
+ * 子元件必須為 `<Step />` 元件；`currentStep` 控制當前進行中的步驟（零基索引），
+ * 之前的步驟自動標記為已完成，之後的步驟為待處理。支援 `horizontal`（水平）與
+ * `vertical`（垂直）排列，以及 `number`（數字）與 `dot`（圓點）兩種指示器樣式。
+ *
+ * @example
+ * ```tsx
+ * import Stepper from '@mezzanine-ui/react/Stepper';
+ * import Step from '@mezzanine-ui/react/Step';
+ *
+ * // 水平數字步驟條
+ * <Stepper currentStep={1}>
+ *   <Step title="填寫資料" description="請輸入基本資訊" />
+ *   <Step title="確認內容" description="核對填寫資料" />
+ *   <Step title="完成送出" />
+ * </Stepper>
+ *
+ * // 垂直圓點步驟條
+ * <Stepper currentStep={0} orientation="vertical" type="dot">
+ *   <Step title="步驟一" />
+ *   <Step title="步驟二" />
+ *   <Step title="步驟三" />
+ * </Stepper>
+ *
+ * // 監聽步驟變化
+ * <Stepper currentStep={step} onStepChange={(idx) => console.log('step:', idx)}>
+ *   <Step title="A" />
+ *   <Step title="B" />
+ *   <Step title="C" />
+ * </Stepper>
+ * ```
+ *
+ * @see {@link useStepper} 管理步驟狀態的 hook
  */
 const Stepper = forwardRef(function Stepper(props, ref) {
     const { children, className, currentStep = 0, onStepChange, orientation = 'horizontal', type = 'number', ...rest } = props;