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

package/Upload/Uploader.d.ts

@@ -1,5 +1,5 @@
 import { ChangeEventHandler, ReactNode, Ref } from 'react';
-import { type UploaderHintType, type UploadPictureControl, type UploadType } from '@mezzanine-ui/core/upload';
+import { type UploaderHintType, type UploaderMode, type UploadPictureControl, type UploadType } from '@mezzanine-ui/core/upload';
 import { type IconDefinition } from '@mezzanine-ui/icons';
 import { NativeElementPropsWithoutKeyAndRef } from '../utils/jsx-types';
 type UploaderInputElementProps = Omit<NativeElementPropsWithoutKeyAndRef<'input'>, 'accept' | 'disabled' | 'multiple' | 'onChange' | 'type' | `aria-${'disabled'}`> & {
@@ -42,7 +42,7 @@ export interface UploaderLabel {
      */
     error?: string;
     /**
-     * Label text for "Click to upload" when isFillWidth is true.
+     * Label text for "Click to upload" in `mode="dropzone"`.
      * @default 'Click to upload'
      */
     clickToUpload?: string;
@@ -87,20 +87,31 @@ export interface UploaderProps extends Omit<NativeElementPropsWithoutKeyAndRef<'
      * @example 'image/*', '.pdf,.doc,.docx'
      */
     accept?: string;
+    /**
+     * Provide `controllerRef` if you need detail data of file.
+     */
+    controllerRef?: Ref<UploadPictureControl | null>;
     /**
      * Whether the input is disabled.
      * @default false
      */
     disabled?: boolean;
     /**
-     * The id of input element.
+     * Array of hints to display outside the uploader (below the label element).
      */
-    id?: string;
+    externalHints?: UploaderHint[];
     /**
-     * Whether to fill the width of the container.
-     * @default false
+     * Array of hints to display with the upload component.
+     */
+    hints?: UploaderHint[];
+    /**
+     * Icon configuration for different actions and states.
      */
-    isFillWidth?: boolean;
+    icon?: UploaderIcon;
+    /**
+     * The id of input element.
+     */
+    id?: string;
     /**
      * Since at Mezzanine we use a host element to wrap our input, most derived props will be passed to the host element.
      * If you need direct control to the input element, use this prop to provide to it.
@@ -110,37 +121,25 @@ export interface UploaderProps extends Omit<NativeElementPropsWithoutKeyAndRef<'
      * The react ref passed to input element.
      */
     inputRef?: React.Ref<HTMLInputElement>;
+    /**
+     * Label configuration for different states.
+     */
+    label?: UploaderLabel;
     /**
      * The name attribute of the input element.
      */
     name?: string;
+    /**
+     * The mode for upload component.
+     * @default 'basic'
+     * @example 'basic' | 'dropzone'
+     */
+    mode?: UploaderMode;
     /**
      * Whether can select multiple files to upload.
      * @default false
      */
     multiple?: boolean;
-    /**
-     * The type for upload component.
-     * @default 'base'
-     * @example 'base' | 'button'
-     */
-    type?: UploadType;
-    /**
-     * Array of hints to display with the upload component.
-     */
-    hints?: UploaderHint[];
-    /**
-     * Label configuration for different states.
-     */
-    label?: UploaderLabel;
-    /**
-     * Icon configuration for different actions and states.
-     */
-    icon?: UploaderIcon;
-    /**
-     * Provide `controllerRef` if you need detail data of file.
-     */
-    controllerRef?: Ref<UploadPictureControl | null>;
     /**
      * Invoked by input change event.
      */
@@ -150,9 +149,11 @@ export interface UploaderProps extends Omit<NativeElementPropsWithoutKeyAndRef<'
      */
     onUpload?: (files: File[]) => void;
     /**
-     * Fired after user deletes file.
+     * The type for upload component.
+     * @default 'base'
+     * @example 'base' | 'button'
      */
-    onDelete?: () => void;
+    type?: UploadType;
 }
 /**
  * The react component for `mezzanine` uploader.

package/Upload/Uploader.js

@@ -2,7 +2,7 @@
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 import { forwardRef, useId, useRef, useState, useMemo } from 'react';
 import { uploaderClasses } from '@mezzanine-ui/core/upload';
-import { UploadIcon } from '@mezzanine-ui/icons';
+import { UploadIcon, InfoFilledIcon, DangerousFilledIcon } from '@mezzanine-ui/icons';
 import Button from '../Button/Button.js';
 import Typography from '../Typography/Typography.js';
 import { composeRefs } from '../utils/composeRefs.js';
@@ -14,7 +14,7 @@ import cx from 'clsx';
  */
 const Uploader = forwardRef(function Uploader(props, ref) {
     var _a, _b, _c;
-    const { accept, className, disabled = false, id, inputProps, inputRef: inputRefProp, isFillWidth = false, multiple = false, name, type, hints, label: labelConfig, icon: iconConfig, controllerRef: _controllerRef, onChange: onChangeProp, onUpload, onDelete: _onDelete, ...rest } = props;
+    const { accept, className, controllerRef: _controllerRef, disabled = false, externalHints, id, hints, icon: iconConfig, inputProps, inputRef: inputRefProp, label: labelConfig, mode = 'basic', multiple = false, name, onChange: onChangeProp, onUpload, type, ...rest } = props;
     const { name: nameFromInputProps, id: idFromInputProps, ...restInputProps } = inputProps || {};
     // Generate unique id if not provided
     const generatedId = useId();
@@ -23,6 +23,7 @@ const Uploader = forwardRef(function Uploader(props, ref) {
     const [isDragging, setIsDragging] = useState(false);
     const composedInputRef = useMemo(() => composeRefs([inputRefProp, inputElementRef]), [inputRefProp]);
     const resolvedName = (_b = name !== null && name !== void 0 ? name : nameFromInputProps) !== null && _b !== void 0 ? _b : finalInputId;
+    const isDropzone = mode === 'dropzone';
     const handleChange = (event) => {
         if (onChangeProp) {
             onChangeProp(event);
@@ -98,7 +99,7 @@ const Uploader = forwardRef(function Uploader(props, ref) {
     }, [iconConfig]);
     const uploadLabel = (labelConfig === null || labelConfig === void 0 ? void 0 : labelConfig.uploadLabel)
         ? labelConfig === null || labelConfig === void 0 ? void 0 : labelConfig.uploadLabel
-        : isFillWidth
+        : isDropzone
             ? 'Drag the file here or'
             : 'Upload';
     const clickToUploadLabel = (_c = labelConfig === null || labelConfig === void 0 ? void 0 : labelConfig.clickToUpload) !== null && _c !== void 0 ? _c : 'Click to upload';
@@ -109,12 +110,12 @@ const Uploader = forwardRef(function Uploader(props, ref) {
             inputElementRef.current.click();
         }
     };
-    return (jsx("label", { className: cx(uploaderClasses.host, type && uploaderClasses.type(type), type !== 'button' && isFillWidth && uploaderClasses.fillWidth, isDragging && uploaderClasses.dragging, type !== 'button' && disabled && uploaderClasses.disabled, className), onDragEnter: handleDragEnter, onDragLeave: handleDragLeave, onDragOver: handleDragOver, onDrop: handleDrop, ref: ref, ...rest, children: jsxs(Fragment, { children: [type === 'base'
-                    && isFillWidth
-                    && jsxs("div", { className: uploaderClasses.uploadContent, children: [uploadIcon, jsxs(Typography, { className: uploaderClasses.uploadLabel, children: [uploadLabel && jsxs(Fragment, { children: [uploadLabel, ' '] }), jsx("span", { className: uploaderClasses.clickToUpload, children: clickToUploadLabel })] }), hints === null || hints === void 0 ? void 0 : hints.map((hint, index) => (jsx(Typography, { className: uploaderClasses.fillWidthHints, children: hint.label }, index)))] }), type === 'base'
-                    && !isFillWidth
-                    && jsxs("div", { className: uploaderClasses.uploadContent, children: [uploadIcon, jsx(Typography, { className: uploaderClasses.uploadLabel, children: uploadLabel })] }), type === 'button'
-                    && (jsxs(Button, { disabled: disabled, onClick: handleClickToUpload, children: [uploadIcon, jsx(Typography, { children: uploadLabel })] })), jsx("input", { ...restInputProps, accept: accept, "aria-disabled": disabled, className: uploaderClasses.input, disabled: disabled, id: finalInputId, multiple: multiple, name: resolvedName, onChange: handleChange, ref: composedInputRef, type: "file" })] }) }));
+    return (jsxs(Fragment, { children: [jsx("label", { className: cx(uploaderClasses.host, type && uploaderClasses.type(type), type !== 'button' && isDropzone && uploaderClasses.fillWidth, isDragging && uploaderClasses.dragging, type !== 'button' && disabled && uploaderClasses.disabled, className), onDragEnter: handleDragEnter, onDragLeave: handleDragLeave, onDragOver: handleDragOver, onDrop: handleDrop, ref: ref, ...rest, children: jsxs(Fragment, { children: [type === 'base'
+                            && isDropzone
+                            && jsxs("div", { className: uploaderClasses.uploadContent, children: [uploadIcon, jsxs(Typography, { className: uploaderClasses.uploadLabel, children: [uploadLabel && jsxs(Fragment, { children: [uploadLabel, ' '] }), jsx("span", { className: uploaderClasses.clickToUpload, children: clickToUploadLabel })] }), hints === null || hints === void 0 ? void 0 : hints.map((hint, index) => (jsx(Typography, { className: uploaderClasses.fillWidthHints, children: hint.label }, index)))] }), type === 'base'
+                            && !isDropzone
+                            && jsxs("div", { className: uploaderClasses.uploadContent, children: [uploadIcon, jsx(Typography, { className: uploaderClasses.uploadLabel, children: uploadLabel })] }), type === 'button'
+                            && (jsx(Button, { disabled: disabled, iconType: "leading", icon: UploadIcon, onClick: handleClickToUpload, children: jsx(Typography, { align: "center", color: "text-fixed-light", variant: "button-highlight", className: uploaderClasses.uploadButtonText, children: uploadLabel }) })), jsx("input", { ...restInputProps, accept: accept, "aria-disabled": disabled, className: uploaderClasses.input, disabled: disabled, id: finalInputId, multiple: multiple, name: resolvedName, onChange: handleChange, ref: composedInputRef, type: "file" })] }) }), externalHints && externalHints.length > 0 && (jsx("ul", { className: uploaderClasses.externalHints, children: externalHints.map((hint) => (jsxs("li", { className: uploaderClasses.externalHint(hint.type || 'info'), children: [jsx(Icon, { icon: hint.type === 'info' ? InfoFilledIcon : DangerousFilledIcon, color: hint.type === 'info' ? 'info' : 'error', size: 14 }), hint.label] }, hint.label))) }))] }));
 });
 
 export { Uploader as default };

package/hooks/useClickAway.d.ts

@@ -2,4 +2,20 @@ import { RefObject, DependencyList } from 'react';
 export type ClickAwayEvent = MouseEvent | TouchEvent | PointerEvent;
 export type ClickAwayHandler = (event: ClickAwayEvent) => void;
 export type ClickAwayHandlerFactory = () => ClickAwayHandler | undefined;
+/**
+ * 偵測點擊發生在指定容器外部的 Hook。
+ *
+ * 監聽 `click` 與 `touchend` 事件，當點擊目標不在 `containerRef` 的 DOM 節點內時，
+ * 呼叫 `factory` 回傳的處理器；若 `factory` 回傳 `undefined` 則不掛載任何監聽器。
+ *
+ * @example
+ * ```tsx
+ * import { useClickAway } from '@mezzanine-ui/react';
+ *
+ * const containerRef = useRef<HTMLDivElement>(null);
+ * useClickAway(() => {
+ *   if (open) return () => setOpen(false);
+ * }, containerRef, [open]);
+ * ```
+ */
 export declare function useClickAway(factory: ClickAwayHandlerFactory, containerRef: RefObject<HTMLElement | null>, deps?: DependencyList): void;

package/hooks/useClickAway.js

@@ -1,5 +1,21 @@
 import { useDocumentEvents } from './useDocumentEvents.js';
 
+/**
+ * 偵測點擊發生在指定容器外部的 Hook。
+ *
+ * 監聽 `click` 與 `touchend` 事件，當點擊目標不在 `containerRef` 的 DOM 節點內時，
+ * 呼叫 `factory` 回傳的處理器；若 `factory` 回傳 `undefined` 則不掛載任何監聽器。
+ *
+ * @example
+ * ```tsx
+ * import { useClickAway } from '@mezzanine-ui/react';
+ *
+ * const containerRef = useRef<HTMLDivElement>(null);
+ * useClickAway(() => {
+ *   if (open) return () => setOpen(false);
+ * }, containerRef, [open]);
+ * ```
+ */
 function useClickAway(factory, containerRef, deps) {
     useDocumentEvents(() => {
         const clickAwayHandler = factory();

package/hooks/useComposeRefs.d.ts

@@ -1,2 +1,17 @@
 import { ComposableRef, ComposedRef } from '../utils/composeRefs';
+/**
+ * 將多個 React ref 合併成單一 callback ref 的 Hook。
+ *
+ * 回傳一個穩定的 callback ref（依賴陣列永遠為空），
+ * 每次渲染時仍能正確呼叫最新的 ref 集合，適用於需要同時傳遞 forwardRef 與內部 ref 的情境。
+ *
+ * @example
+ * ```tsx
+ * import { useComposeRefs } from '@mezzanine-ui/react';
+ *
+ * const internalRef = useRef<HTMLDivElement>(null);
+ * const composedRef = useComposeRefs([internalRef, forwardedRef]);
+ * return <div ref={composedRef} />;
+ * ```
+ */
 export declare function useComposeRefs<T>(refs: ComposableRef<T>[]): ComposedRef<T>;

package/hooks/useComposeRefs.js

@@ -1,6 +1,21 @@
 import { useRef, useCallback } from 'react';
 import { composeRefs } from '../utils/composeRefs.js';
 
+/**
+ * 將多個 React ref 合併成單一 callback ref 的 Hook。
+ *
+ * 回傳一個穩定的 callback ref（依賴陣列永遠為空），
+ * 每次渲染時仍能正確呼叫最新的 ref 集合，適用於需要同時傳遞 forwardRef 與內部 ref 的情境。
+ *
+ * @example
+ * ```tsx
+ * import { useComposeRefs } from '@mezzanine-ui/react';
+ *
+ * const internalRef = useRef<HTMLDivElement>(null);
+ * const composedRef = useComposeRefs([internalRef, forwardedRef]);
+ * return <div ref={composedRef} />;
+ * ```
+ */
 function useComposeRefs(refs) {
     const refsRef = useRef(refs);
     refsRef.current = refs;

package/hooks/useDocumentEscapeKeyDown.d.ts

@@ -1,3 +1,18 @@
 import { DependencyList } from 'react';
 export type DocumentEscapeKeyDownHandlerFactory = () => ((event: KeyboardEvent) => void) | undefined;
+/**
+ * 在 document 上監聽 Escape 鍵按下事件的 Hook。
+ *
+ * 當鍵盤觸發 `keydown` 且 `event.key === 'Escape'` 時，呼叫 `factory` 回傳的處理器並阻止預設行為；
+ * 若 `factory` 回傳 `undefined` 則不掛載任何監聽器。
+ *
+ * @example
+ * ```tsx
+ * import { useDocumentEscapeKeyDown } from '@mezzanine-ui/react';
+ *
+ * useDocumentEscapeKeyDown(() => {
+ *   if (open) return () => setOpen(false);
+ * }, [open]);
+ * ```
+ */
 export declare function useDocumentEscapeKeyDown(factory: DocumentEscapeKeyDownHandlerFactory, deps?: DependencyList): void;

package/hooks/useDocumentEscapeKeyDown.js

@@ -1,5 +1,20 @@
 import { useDocumentEvents } from './useDocumentEvents.js';
 
+/**
+ * 在 document 上監聽 Escape 鍵按下事件的 Hook。
+ *
+ * 當鍵盤觸發 `keydown` 且 `event.key === 'Escape'` 時，呼叫 `factory` 回傳的處理器並阻止預設行為；
+ * 若 `factory` 回傳 `undefined` 則不掛載任何監聽器。
+ *
+ * @example
+ * ```tsx
+ * import { useDocumentEscapeKeyDown } from '@mezzanine-ui/react';
+ *
+ * useDocumentEscapeKeyDown(() => {
+ *   if (open) return () => setOpen(false);
+ * }, [open]);
+ * ```
+ */
 function useDocumentEscapeKeyDown(factory, deps) {
     useDocumentEvents(() => {
         const handler = factory();

package/hooks/useDocumentEvents.d.ts

@@ -2,4 +2,20 @@ import { DependencyList } from 'react';
 export type DocumentEventHandlersFactory = () => {
     [event in keyof DocumentEventMap]?: (event: DocumentEventMap[event]) => void;
 } | undefined;
+/**
+ * 在 document 上批次註冊／移除事件監聽器的 Hook。
+ *
+ * `factory` 回傳一個事件名稱到處理器的映射物件；依賴項變化時舊監聽器會先被移除，
+ * 再重新掛載新的；若 `factory` 回傳 `undefined` 則不掛載任何監聽器。
+ *
+ * @example
+ * ```tsx
+ * import { useDocumentEvents } from '@mezzanine-ui/react';
+ *
+ * useDocumentEvents(() => ({
+ *   click: handleClick,
+ *   keydown: handleKeyDown,
+ * }), [handleClick, handleKeyDown]);
+ * ```
+ */
 export declare function useDocumentEvents(factory: DocumentEventHandlersFactory, deps?: DependencyList): void;

package/hooks/useDocumentEvents.js

@@ -1,5 +1,21 @@
 import { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect.js';
 
+/**
+ * 在 document 上批次註冊／移除事件監聽器的 Hook。
+ *
+ * `factory` 回傳一個事件名稱到處理器的映射物件；依賴項變化時舊監聽器會先被移除，
+ * 再重新掛載新的；若 `factory` 回傳 `undefined` 則不掛載任何監聽器。
+ *
+ * @example
+ * ```tsx
+ * import { useDocumentEvents } from '@mezzanine-ui/react';
+ *
+ * useDocumentEvents(() => ({
+ *   click: handleClick,
+ *   keydown: handleKeyDown,
+ * }), [handleClick, handleKeyDown]);
+ * ```
+ */
 function useDocumentEvents(factory, deps) {
     useIsomorphicLayoutEffect(() => {
         const handlers = factory();

package/hooks/useDocumentTabKeyDown.d.ts

@@ -1,3 +1,18 @@
 import { DependencyList } from 'react';
 export type DocumentTabKeyDownHandlerFactory = () => ((event: KeyboardEvent) => void) | undefined;
+/**
+ * 在 document 上監聽 Tab 鍵按下事件的 Hook。
+ *
+ * 當鍵盤觸發 `keydown` 且 `event.key === 'Tab'` 時，呼叫 `factory` 回傳的處理器；
+ * 若 `factory` 回傳 `undefined` 則不掛載任何監聽器。
+ *
+ * @example
+ * ```tsx
+ * import { useDocumentTabKeyDown } from '@mezzanine-ui/react';
+ *
+ * useDocumentTabKeyDown(() => {
+ *   if (open) return (e) => trapFocus(e);
+ * }, [open]);
+ * ```
+ */
 export declare function useDocumentTabKeyDown(factory: DocumentTabKeyDownHandlerFactory, deps?: DependencyList): void;

package/hooks/useDocumentTabKeyDown.js

@@ -1,5 +1,20 @@
 import { useDocumentEvents } from './useDocumentEvents.js';
 
+/**
+ * 在 document 上監聽 Tab 鍵按下事件的 Hook。
+ *
+ * 當鍵盤觸發 `keydown` 且 `event.key === 'Tab'` 時，呼叫 `factory` 回傳的處理器；
+ * 若 `factory` 回傳 `undefined` 則不掛載任何監聽器。
+ *
+ * @example
+ * ```tsx
+ * import { useDocumentTabKeyDown } from '@mezzanine-ui/react';
+ *
+ * useDocumentTabKeyDown(() => {
+ *   if (open) return (e) => trapFocus(e);
+ * }, [open]);
+ * ```
+ */
 function useDocumentTabKeyDown(factory, deps) {
     useDocumentEvents(() => {
         const handler = factory();

package/hooks/useIsomorphicLayoutEffect.d.ts

@@ -1,2 +1,18 @@
 import { useLayoutEffect } from 'react';
+/**
+ * 在瀏覽器環境使用 `useLayoutEffect`、在 SSR 環境降級為 `useEffect` 的 Hook。
+ *
+ * 用於需要在 DOM 繪製前同步執行副作用的場景（例如讀取 layout 資訊），
+ * 同時避免伺服器端渲染時因 `useLayoutEffect` 產生警告。
+ *
+ * @example
+ * ```tsx
+ * import { useIsomorphicLayoutEffect } from '@mezzanine-ui/react';
+ *
+ * useIsomorphicLayoutEffect(() => {
+ *   // 在 DOM 更新後、繪製前同步執行
+ *   measureElement();
+ * }, [deps]);
+ * ```
+ */
 export declare const useIsomorphicLayoutEffect: typeof useLayoutEffect;

package/hooks/useIsomorphicLayoutEffect.js

@@ -1,5 +1,21 @@
 import { useLayoutEffect, useEffect } from 'react';
 
+/**
+ * 在瀏覽器環境使用 `useLayoutEffect`、在 SSR 環境降級為 `useEffect` 的 Hook。
+ *
+ * 用於需要在 DOM 繪製前同步執行副作用的場景（例如讀取 layout 資訊），
+ * 同時避免伺服器端渲染時因 `useLayoutEffect` 產生警告。
+ *
+ * @example
+ * ```tsx
+ * import { useIsomorphicLayoutEffect } from '@mezzanine-ui/react';
+ *
+ * useIsomorphicLayoutEffect(() => {
+ *   // 在 DOM 更新後、繪製前同步執行
+ *   measureElement();
+ * }, [deps]);
+ * ```
+ */
 const useIsomorphicLayoutEffect = typeof window !== 'undefined' &&
     window.document &&
     !!window.document.createElement

package/hooks/useLastCallback.d.ts

@@ -1 +1,16 @@
+/**
+ * 回傳一個引用永遠穩定但呼叫時使用最新版本 callback 的 Hook。
+ *
+ * 內部以 ref 儲存最新的 callback，對外回傳一個依賴陣列為空的 `useCallback` wrapper，
+ * 可安全地傳遞給子元件或事件處理器而不觸發不必要的 re-render。
+ *
+ * @example
+ * ```tsx
+ * import { useLastCallback } from '@mezzanine-ui/react';
+ *
+ * const stableOnChange = useLastCallback((value: string) => {
+ *   doSomethingWith(value);
+ * });
+ * ```
+ */
 export declare function useLastCallback<F extends (...args: any[]) => any>(callback: F): (...args: Parameters<F>) => ReturnType<F>;

package/hooks/useLastCallback.js

@@ -1,6 +1,21 @@
 import { useCallback } from 'react';
 import { useLastValue } from './useLastValue.js';
 
+/**
+ * 回傳一個引用永遠穩定但呼叫時使用最新版本 callback 的 Hook。
+ *
+ * 內部以 ref 儲存最新的 callback，對外回傳一個依賴陣列為空的 `useCallback` wrapper，
+ * 可安全地傳遞給子元件或事件處理器而不觸發不必要的 re-render。
+ *
+ * @example
+ * ```tsx
+ * import { useLastCallback } from '@mezzanine-ui/react';
+ *
+ * const stableOnChange = useLastCallback((value: string) => {
+ *   doSomethingWith(value);
+ * });
+ * ```
+ */
 function useLastCallback(callback) {
     const lastCallback = useLastValue(callback);
     return useCallback(

package/hooks/useLastValue.d.ts

@@ -1,3 +1,21 @@
+/**
+ * 追蹤並回傳最新值的 ref Hook。
+ *
+ * 每次渲染時同步更新 ref 的 `current` 屬性，
+ * 可用於在非同步回調或 effect 中存取最新的 prop 或 state，而無需將其加入依賴陣列。
+ *
+ * @example
+ * ```tsx
+ * import { useLastValue } from '@mezzanine-ui/react';
+ *
+ * const latestCount = useLastValue(count);
+ * useEffect(() => {
+ *   setTimeout(() => {
+ *     console.log(latestCount.current); // 總是最新的值
+ *   }, 1000);
+ * }, []);
+ * ```
+ */
 export declare function useLastValue<T>(value: T): {
     readonly current: T;
 };

package/hooks/useLastValue.js

@@ -1,5 +1,23 @@
 import { useRef } from 'react';
 
+/**
+ * 追蹤並回傳最新值的 ref Hook。
+ *
+ * 每次渲染時同步更新 ref 的 `current` 屬性，
+ * 可用於在非同步回調或 effect 中存取最新的 prop 或 state，而無需將其加入依賴陣列。
+ *
+ * @example
+ * ```tsx
+ * import { useLastValue } from '@mezzanine-ui/react';
+ *
+ * const latestCount = useLastValue(count);
+ * useEffect(() => {
+ *   setTimeout(() => {
+ *     console.log(latestCount.current); // 總是最新的值
+ *   }, 1000);
+ * }, []);
+ * ```
+ */
 function useLastValue(value) {
     const ref = useRef(value);
     ref.current = value;

package/hooks/usePreviousValue.d.ts

@@ -1 +1,15 @@
+/**
+ * 回傳上一次渲染時的值的 Hook。
+ *
+ * 以 `useEffect` 在渲染完成後更新 ref，因此在本次渲染中取得的是前一次的值，
+ * 適用於需要比較前後值差異的情境。
+ *
+ * @example
+ * ```tsx
+ * import { usePreviousValue } from '@mezzanine-ui/react';
+ *
+ * const previousCount = usePreviousValue(count);
+ * // previousCount 為 count 上一次渲染的值
+ * ```
+ */
 export declare function usePreviousValue<T>(value: T): T;

package/hooks/usePreviousValue.js

@@ -1,5 +1,19 @@
 import { useRef, useEffect } from 'react';
 
+/**
+ * 回傳上一次渲染時的值的 Hook。
+ *
+ * 以 `useEffect` 在渲染完成後更新 ref，因此在本次渲染中取得的是前一次的值，
+ * 適用於需要比較前後值差異的情境。
+ *
+ * @example
+ * ```tsx
+ * import { usePreviousValue } from '@mezzanine-ui/react';
+ *
+ * const previousCount = usePreviousValue(count);
+ * // previousCount 為 count 上一次渲染的值
+ * ```
+ */
 function usePreviousValue(value) {
     const ref = useRef(value);
     useEffect(() => {

package/hooks/useScrollLock.d.ts

@@ -11,13 +11,15 @@ interface ScrollLockOptions {
     reserveScrollBarGap?: boolean;
 }
 /**
- * Hook to lock/unlock body scroll
- * Handles multiple concurrent locks (nested modals/overlays)
- * Prevents layout shift by reserving scrollbar width
- * Handles iOS rubber band scrolling
+ * 鎖定／解鎖頁面捲動的 Hook。
+ *
+ * 支援多層巢狀鎖定（nested modals/overlays），保留捲軸寬度以防止版面偏移，
+ * 並針對 iOS Safari 的 rubber band scrolling 進行特別處理。
  *
  * @example
  * ```tsx
+ * import { useScrollLock } from '@mezzanine-ui/react';
+ *
  * function Modal({ open }) {
  *   useScrollLock({ enabled: open });
  *   return <div>...</div>;

package/hooks/useScrollLock.js

@@ -93,13 +93,15 @@ function isIOS() {
     return isIOSDevice || isSafariOnMac;
 }
 /**
- * Hook to lock/unlock body scroll
- * Handles multiple concurrent locks (nested modals/overlays)
- * Prevents layout shift by reserving scrollbar width
- * Handles iOS rubber band scrolling
+ * 鎖定／解鎖頁面捲動的 Hook。
+ *
+ * 支援多層巢狀鎖定（nested modals/overlays），保留捲軸寬度以防止版面偏移，
+ * 並針對 iOS Safari 的 rubber band scrolling 進行特別處理。
  *
  * @example
  * ```tsx
+ * import { useScrollLock } from '@mezzanine-ui/react';
+ *
  * function Modal({ open }) {
  *   useScrollLock({ enabled: open });
  *   return <div>...</div>;

package/hooks/useTopStack.d.ts

@@ -1 +1,18 @@
+/**
+ * 管理多個浮層 z-index 堆疊順序的 Hook。
+ *
+ * 每個元件呼叫此 Hook 時會取得一個唯一的 seed 值；當 `open` 為 `true` 時，
+ * 該 seed 會被推入全域堆疊，回傳的函式可用於查詢自己是否位於最頂層。
+ *
+ * @example
+ * ```tsx
+ * import useTopStack from '@mezzanine-ui/react/hooks/useTopStack';
+ *
+ * const isTopStack = useTopStack(open);
+ * // 在 Escape 鍵處理時，只有最頂層的浮層才關閉
+ * useDocumentEscapeKeyDown(() => {
+ *   if (isTopStack()) return () => setOpen(false);
+ * }, [isTopStack]);
+ * ```
+ */
 export default function useTopStack(open?: boolean): () => boolean;

package/hooks/useTopStack.js

@@ -2,6 +2,23 @@ import { useMemo, useEffect, useCallback } from 'react';
 
 let seedStack = [];
 let seed = 1;
+/**
+ * 管理多個浮層 z-index 堆疊順序的 Hook。
+ *
+ * 每個元件呼叫此 Hook 時會取得一個唯一的 seed 值；當 `open` 為 `true` 時，
+ * 該 seed 會被推入全域堆疊，回傳的函式可用於查詢自己是否位於最頂層。
+ *
+ * @example
+ * ```tsx
+ * import useTopStack from '@mezzanine-ui/react/hooks/useTopStack';
+ *
+ * const isTopStack = useTopStack(open);
+ * // 在 Escape 鍵處理時，只有最頂層的浮層才關閉
+ * useDocumentEscapeKeyDown(() => {
+ *   if (isTopStack()) return () => setOpen(false);
+ * }, [isTopStack]);
+ * ```
+ */
 function useTopStack(open) {
     const modalSeed = useMemo(() => {
         // eslint-disable-next-line react-hooks/globals

package/hooks/useWindowWidth.d.ts

@@ -1 +1,15 @@
+/**
+ * 追蹤目前視窗寬度的 Hook。
+ *
+ * 在元件掛載時以 `window.innerWidth` 初始化，並監聽 `resize` 事件持續更新，
+ * 元件卸載時自動移除監聽器。
+ *
+ * @example
+ * ```tsx
+ * import { useWindowWidth } from '@mezzanine-ui/react';
+ *
+ * const width = useWindowWidth();
+ * const isMobile = width !== undefined && width < 768;
+ * ```
+ */
 export declare function useWindowWidth(): number | undefined;