@_tc/template-core 0.0.1-bate.37 → 0.0.1-bate.39

package/fe/packages/ui/react/components/hooks/useDropdownPositioning.js

@@ -4,6 +4,12 @@ const HIDDEN_POSITION = {
     left: -100,
 };
 const EMPTY_DEPS = [];
+/**
+ * 计算弹窗该放在哪。
+ *
+ * right/left：跟触发元素顶部对齐，往右或往左弹。
+ * bottom/top：放在触发元素下方或上方，再按 start/end 对齐。
+ */
 export const getDefaultDropdownPosition = ({ anchorRect, contentRect, containerRect, viewportWidth, placement, offset, matchAnchorWidth, }) => {
     const isRight = placement.startsWith("right");
     const isLeft = placement.startsWith("left");
@@ -23,6 +29,7 @@ export const getDefaultDropdownPosition = ({ anchorRect, contentRect, containerR
         nextPosition.left = anchorRect.right + offset - containerLeft;
     }
     else if (isLeft) {
+        // 往左弹时，要知道弹窗宽度，才能算出左边应该从哪里开始。
         nextPosition.left = anchorRect.left - (contentRect?.width ?? 0) - offset - containerLeft;
     }
     else if (placement.endsWith("start")) {
@@ -37,6 +44,7 @@ export function useDropdownPositioning({ open, anchorRef, contentRef, placement
     const [position, setPosition] = useState(HIDDEN_POSITION);
     const [ready, setReady] = useState(false);
     const getContentRect = useCallback(() => {
+        // 优先用真实 DOM 尺寸。刚打开时可能还量不到，就允许外部给一个预估尺寸。
         const measuredRect = contentRef.current?.getBoundingClientRect();
         if (measuredRect && measuredRect.height > 0) {
             return measuredRect;
@@ -49,6 +57,7 @@ export function useDropdownPositioning({ open, anchorRef, contentRef, placement
     const updatePosition = useCallback(() => {
         if (!anchorRef.current)
             return;
+        // 每次定位前重新读取位置，这样滚动或窗口变化后不会用旧坐标。
         const anchorRect = anchorRef.current.getBoundingClientRect();
         const contentRect = getContentRect();
         const containerRect = positionMode === "absolute"
@@ -80,16 +89,19 @@ export function useDropdownPositioning({ open, anchorRef, contentRef, placement
     ]);
     useEffect(() => {
         if (!open) {
+            // 关闭时先挪到屏幕外，避免 keepMounted 的弹窗在旧位置闪一下。
             setPosition((returnData.current.position = HIDDEN_POSITION));
             setReady((returnData.current.ready = false));
             return;
         }
+        // 打开后等两帧再量尺寸：先让 DOM 挂上去，再让浏览器完成布局。
         const rafId = requestAnimationFrame(() => requestAnimationFrame(updatePosition));
         return () => cancelAnimationFrame(rafId);
     }, [open, updatePosition]);
     useEffect(() => {
         if (!open)
             return;
+        // 页面滚动、外层容器滚动、窗口缩放时，都重新算一次位置。
         const handleUpdate = () => updatePosition();
         window.addEventListener("scroll", handleUpdate, true);
         window.addEventListener("resize", handleUpdate);
@@ -102,11 +114,13 @@ export function useDropdownPositioning({ open, anchorRef, contentRef, placement
     useEffect(() => {
         if (!open)
             return;
+        // 外部内容变化时，可以通过 watchDeps 主动触发重新定位。
         updatePosition();
     }, [deps, open, updatePosition]);
     useEffect(() => {
         if (!open || !contentRef.current)
             return;
+        // 弹窗打开后内容高度/宽度可能变，尺寸变了就重新定位。
         let rafId = 0;
         const observer = new ResizeObserver(() => {
             rafId = requestAnimationFrame(() => requestAnimationFrame(updatePosition));

package/fe/packages/ui/react/components/hooks/useInputController.d.ts

@@ -4,6 +4,9 @@ interface IParams<T> {
     controlledValue?: string;
     disabled?: boolean;
 }
+/**
+ * 处理ref & 判断是否受控 & 使用的value & value.length
+ */
 export declare const useInputController: <T>(params: IParams<T>) => {
     setRefs: (node: T | null) => void;
     setIsFocused: import("react").Dispatch<import("react").SetStateAction<boolean>>;

package/fe/packages/ui/react/components/hooks/useInputController.js

@@ -1,21 +1,28 @@
 import { useCallback, useMemo, useRef, useState } from 'react';
+/**
+ * 处理ref & 判断是否受控 & 使用的value & value.length
+ */
 export const useInputController = (params) => {
     const { defaultValue, ref, controlledValue } = params;
     const [isFocused, setIsFocused] = useState(false);
     const [internalValue, setInternalValue] = useState(defaultValue || '');
     const controllerRef = useRef(null);
+    // 合并 refs
     const setRefs = useCallback((node) => {
         controllerRef.current = node;
         if (typeof ref === 'function') {
             ref(node);
         }
         else if (ref) {
+            // eslint-disable-next-line react-hooks/immutability
             ref.current = node;
         }
     }, [ref]);
     const isControlledRef = useRef(false);
+    // 外部传了value
     const isControlled = useMemo(() => {
         const r = controlledValue !== undefined;
+        // 当传入的value改变时，更新ref值
         isControlledRef.current = r;
         return r;
     }, [controlledValue]);

package/fe/packages/ui/react/components/testPage/MenuTestPage.js

@@ -2,6 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState } from 'react';
 import { LayoutDashboard, Package, Settings, Users, FileText, BarChart3, ShoppingCart, Bell, HelpCircle, } from 'lucide-react';
 import { Menu } from '../Menu';
+// ─── 示例数据 ────────────────────────────────────────────────────────────────
 const menuItems = [
     {
         key: 'dashboard',
@@ -71,9 +72,11 @@ const iconMenuItems = [
     { key: 'notifications', label: 'Notifications', icon: _jsx(Bell, { className: "h-4 w-4" }) },
     { key: 'help', label: 'Help', icon: _jsx(HelpCircle, { className: "h-4 w-4" }) },
 ];
+// ─── 区块包装 ────────────────────────────────────────────────────────────────
 function Section({ title, description, children }) {
     return (_jsxs("section", { className: "space-y-3", children: [_jsxs("div", { children: [_jsx("h2", { className: "text-lg font-semibold", children: title }), description && _jsx("p", { className: "text-sm text-muted-foreground", children: description })] }), children] }));
 }
+// ─── 页面 ────────────────────────────────────────────────────────────────────
 export default function MenuTestPage() {
     const [selectedKey, setSelectedKey] = useState('dashboard');
     const [collapsed, setCollapsed] = useState(false);

package/fe/packages/ui/react/components/testPage/index.js

@@ -29,9 +29,11 @@ function ThemeSwitcher() {
     }, [mode, theme]);
     return (_jsx(Section, { title: "Theme", children: _jsxs("div", { className: "flex w-full flex-wrap items-center gap-6 rounded-xl border border-border bg-background p-4", children: [_jsxs("div", { className: "flex items-center gap-2", children: [_jsx("span", { className: "text-sm text-muted-foreground", children: "\u6A21\u5F0F" }), _jsx(Button, { variant: mode === 'light' ? 'primary' : 'default', size: "sm", onClick: () => setMode('light'), children: "Light" }), _jsx(Button, { variant: mode === 'dark' ? 'primary' : 'default', size: "sm", onClick: () => setMode('dark'), children: "Dark" })] }), _jsxs("div", { className: "flex items-center gap-2", children: [_jsx("span", { className: "text-sm text-muted-foreground", children: "\u4E3B\u9898" }), _jsx(Button, { variant: theme === 'default' ? 'primary' : 'default', size: "sm", onClick: () => setTheme('default'), children: "Default" }), _jsx(Button, { variant: theme === 'green' ? 'primary' : 'default', size: "sm", onClick: () => setTheme('green'), children: "Green" }), _jsx(Button, { variant: theme === 'gray' ? 'primary' : 'default', size: "sm", onClick: () => setTheme('gray'), children: "Gray" })] }), _jsxs("div", { className: "text-sm text-muted-foreground", children: ["\u5F53\u524D: ", mode, " / ", theme] })] }) }));
 }
+// ─── Section wrapper ────────────────────────────────────────────────────────
 function Section({ title, children }) {
     return (_jsxs("div", { className: "mb-8", children: [_jsx("h2", { className: "text-lg font-semibold mb-3 border-b pb-1", children: title }), _jsx("div", { className: "flex flex-wrap gap-3 items-start", children: children })] }));
 }
+// ─── Button ─────────────────────────────────────────────────────────────────
 function ButtonDemo() {
     const [loading, setLoading] = useState(false);
     return (_jsxs(Section, { title: "Button", children: [_jsx(Button, { children: "default" }), _jsx(Button, { variant: "primary", children: "primary" }), _jsx(Button, { variant: "dashed", children: "dashed" }), _jsx(Button, { variant: "text", children: "text" }), _jsx(Button, { variant: "link", href: "#button", children: "link" }), _jsx(Button, { state: "danger", children: "danger" }), _jsx(Button, { variant: "primary", state: "danger", children: "primary danger" }), _jsx("div", { className: " bg-red-300 p-1.5", children: _jsx(Button, { state: "ghost", children: "ghost" }) }), _jsx(Button, { variant: "primary", state: "ghost", children: "primary ghost" }), _jsx(Button, { disabled: true, children: "disabled" }), _jsx(Button, { loading: loading, onClick: () => {
@@ -39,6 +41,7 @@ function ButtonDemo() {
                     setTimeout(() => setLoading(false), 2000);
                 }, children: "loading (click)" }), _jsx(Button, { size: "sm", children: "sm" }), _jsx(Button, { size: "md", children: "md" }), _jsx(Button, { size: "lg", children: "lg" })] }));
 }
+// ─── Input ───────────────────────────────────────────────────────────────────
 function InputDemo() {
     return (_jsxs(Section, { title: "Input", children: [_jsx(Input, { placeholder: "\u666E\u901A\u8F93\u5165\u6846" }), _jsx(Input, { type: "password", placeholder: "\u5BC6\u7801\u8F93\u5165\u6846" }), _jsx(Input, { disabled: true, placeholder: "\u7981\u7528\u72B6\u6001" })] }));
 }
@@ -47,10 +50,12 @@ function InputNumberDemo() {
     const [ratio, setRatio] = useState(0.25);
     return (_jsxs(Section, { title: "InputNumber", children: [_jsx(InputNumber, { placeholder: "\u57FA\u7840\u6570\u5B57\u8F93\u5165", className: "w-48" }), _jsx(InputNumber, { value: price, onChange: setPrice, precision: 2, min: 0, max: 9999, placeholder: "\u4EF7\u683C", addonAfter: _jsx("span", { className: "text-xs text-muted-foreground", children: "CNY" }), className: "w-56" }), _jsx(InputNumber, { value: ratio, onChange: setRatio, precision: 2, step: 0.05, min: 0, max: 1, allowStep: true, placeholder: "\u6BD4\u4F8B", className: "w-48" }), _jsx(InputNumber, { defaultValue: 10, step: 0.5, precision: 1, allowStep: true, allowClear: true, className: "w-48" }), _jsx(InputNumber, { disabled: true, defaultValue: 88.8, precision: 1, className: "w-48" })] }));
 }
+// ─── Textarea ────────────────────────────────────────────────────────────────
 function TextareaDemo() {
     const [val, setVal] = useState('');
     return (_jsxs(Section, { title: "Textarea", children: [_jsx(Textarea, { placeholder: "\u8BF7\u8F93\u5165\u5185\u5BB9\uFF08\u6700\u591A 500 \u5B57\uFF09", value: val, onChange: (v) => setVal(v), className: "w-80" }), _jsx(Textarea, { placeholder: "\u4E0D\u663E\u793A\u8BA1\u6570", showCount: false, className: "w-80" })] }));
 }
+// ─── Select ──────────────────────────────────────────────────────────────────
 function SelectDemo() {
     const [val, setVal] = useState(undefined);
     const options = [
@@ -60,17 +65,21 @@ function SelectDemo() {
     ];
     return (_jsxs(Section, { title: "Select", children: [_jsx(Select, { options: options, value: val, onChange: setVal, placeholder: "\u8BF7\u9009\u62E9", className: "w-40" }), _jsx(Select, { options: options, placeholder: "\u4E0D\u53EF\u641C\u7D22", searchable: false, className: "w-40" }), _jsx(Select, { options: options, placeholder: "\u4E0D\u53EF\u6E05\u9664", clearable: false, className: "w-40" }), _jsx(Select, { options: options, disabled: true, placeholder: "\u7981\u7528", className: "w-40" }), _jsxs("div", { className: "relative w-64 rounded-lg border border-border bg-muted/30 p-4", children: [_jsx("div", { className: "mb-2 text-sm text-muted-foreground", children: "parent popup container" }), _jsx(Select, { options: options, placeholder: "\u6302\u8F7D\u5230\u7236\u5143\u7D20", getPopupContainer: "parent", className: "w-full" })] })] }));
 }
+// ─── Checkbox ────────────────────────────────────────────────────────────────
 function CheckboxDemo() {
     const [checked, setChecked] = useState(false);
     return (_jsxs(Section, { title: "Checkbox", children: [_jsxs("label", { className: "flex items-center gap-2 cursor-pointer", children: [_jsx(Checkbox, { checked: checked, onChange: (c) => setChecked(c) }), _jsxs("span", { children: ["\u53D7\u63A7: ", checked ? '选中' : '未选中'] })] }), _jsxs("label", { className: "flex items-center gap-2 cursor-pointer", children: [_jsx(Checkbox, { defaultChecked: true }), _jsx("span", { children: "\u975E\u53D7\u63A7\u9ED8\u8BA4\u9009\u4E2D" })] }), _jsxs("label", { className: "flex items-center gap-2 cursor-pointer", children: [_jsx(Checkbox, { indeterminate: true }), _jsx("span", { children: "\u534A\u9009\u72B6\u6001" })] }), _jsxs("label", { className: "flex items-center gap-2 cursor-pointer", children: [_jsx(Checkbox, { disabled: true }), _jsx("span", { children: "\u7981\u7528" })] })] }));
 }
+// ─── Switch ──────────────────────────────────────────────────────────────────
 function SwitchDemo() {
     const [on, setOn] = useState(false);
     return (_jsxs(Section, { title: "Switch", children: [_jsx(Switch, { checked: on, onChange: setOn }), _jsx("span", { className: "self-center text-sm", children: on ? 'ON' : 'OFF' }), _jsx(Switch, { defaultChecked: true }), _jsx(Switch, { disabled: true }), _jsx(Switch, { disabled: true, checked: true })] }));
 }
+// ─── Tooltip ─────────────────────────────────────────────────────────────────
 function TooltipDemo() {
     return (_jsx(Section, { title: "Tooltip", children: ['top', 'bottom', 'left', 'right'].map((p) => (_jsx(Tooltip, { content: `placement: ${p}`, placement: p, children: _jsx(Button, { children: p }) }, p))) }));
 }
+// ─── Dropdown ────────────────────────────────────────────────────────────────
 function DropdownDemo() {
     const items = [
         { key: 'edit', label: '编辑', onClick: () => console.log('edit') },
@@ -79,12 +88,14 @@ function DropdownDemo() {
     ];
     return (_jsxs(Section, { title: "Dropdown", children: [_jsx(Dropdown, { items: items, children: _jsx(Button, { children: "\u64CD\u4F5C \u25BE" }) }), _jsx(Dropdown, { items: items, placement: "bottom-start", children: _jsx(Button, { variant: "text", children: "bottom-start \u25BE" }) })] }));
 }
+// ─── Message ─────────────────────────────────────────────────────────────────
 function MessageDemo() {
     return (_jsxs(Section, { title: "Message (imperative)", children: [_jsx(Button, { onClick: () => message.success('操作成功'), children: "success" }), _jsx(Button, { onClick: () => message.error('操作失败'), children: "error" }), _jsx(Button, { onClick: () => message.warning('警告信息'), children: "warning" }), _jsx(Button, { onClick: () => message.info('提示信息'), children: "info" }), _jsx(Button, { onClick: () => {
                     const id = message.success('5秒后关闭', { duration: 5000 });
                     setTimeout(() => message.close(id), 2000);
                 }, children: "\u63D0\u524D\u5173\u95ED" })] }));
 }
+// ─── Modal ───────────────────────────────────────────────────────────────────
 function ModalDemo() {
     const [open, setOpen] = useState(false);
     return (_jsxs(Section, { title: "Modal", children: [_jsx(Button, { onClick: () => setOpen(true), children: "JSX Modal" }), _jsx(Button, { onClick: () => modal.open({
@@ -101,6 +112,7 @@ function ModalDemo() {
                     },
                 }), children: "modal.confirm" }), _jsxs(Modal, { open: open, onClose: () => setOpen(false), title: "JSX \u5F39\u7A97", children: [_jsx("p", { children: "\u8FD9\u662F\u4E00\u4E2A\u4F7F\u7528 JSX \u63A7\u5236\u7684\u5F39\u7A97\u3002" }), _jsx("div", { className: "mt-4 flex justify-end gap-2", children: _jsx(Button, { onClick: () => setOpen(false), children: "\u5173\u95ED" }) })] })] }));
 }
+// ─── Drawer ──────────────────────────────────────────────────────────────────
 function DrawerDemo() {
     const [placement, setPlacement] = useState('right');
     const [open, setOpen] = useState(false);
@@ -116,6 +128,7 @@ function DrawerDemo() {
                                             { label: '停用', value: 'disabled' },
                                         ] }) })] })] }) })] }));
 }
+// ─── ConfirmDialog ───────────────────────────────────────────────────────────
 function ConfirmDialogDemo() {
     const [open, setOpen] = useState(false);
     return (_jsxs(Section, { title: "ConfirmDialog", children: [_jsx(Button, { onClick: () => setOpen(true), children: "\u6253\u5F00\u786E\u8BA4\u6846" }), _jsx(ConfirmDialog, { open: open, title: "\u5220\u9664\u786E\u8BA4", content: "\u786E\u5B9A\u8981\u5220\u9664\u6B64\u6761\u6570\u636E\u5417\uFF1F\u6B64\u64CD\u4F5C\u4E0D\u53EF\u64A4\u9500\u3002", onOk: () => {
@@ -123,11 +136,13 @@ function ConfirmDialogDemo() {
                     setOpen(false);
                 }, onCancel: () => setOpen(false) })] }));
 }
+// ─── Pagination ───────────────────────────────────────────────────────────────
 function PaginationDemo() {
     const [page, setPage] = useState(1);
     const [pageSize, setPageSize] = useState(10);
     return (_jsx(Section, { title: "Pagination", children: _jsxs("div", { className: "w-full", children: [_jsxs("p", { className: "text-sm mb-2", children: ["\u5F53\u524D\u9875: ", page, " / \u6BCF\u9875: ", pageSize] }), _jsx(Pagination, { current: page, pageSize: pageSize, total: 238, onChange: setPage, onPageSizeChange: setPageSize })] }) }));
 }
+// ─── Table (低层组件) ─────────────────────────────────────────────────────────
 function TableDemo() {
     const rows = [
         { id: 1, name: '张三', role: '管理员', status: '正常' },
@@ -156,6 +171,7 @@ function DataTableDemo() {
                         onChange: (keys) => setSelectedKeys(keys),
                     } })] }) }));
 }
+// ─── Search ───────────────────────────────────────────────────────────────────
 function SearchDemo() {
     return (_jsx(Section, { title: "Search", children: _jsx("div", { className: "w-full", children: _jsxs(Search, { schemas: [
                     { type: 'input', key: 'keyword', label: '关键字', fieldProps: { placeholder: '请输入' } },
@@ -173,6 +189,7 @@ function SearchDemo() {
                     },
                 ], children: [_jsx(Button, { type: "submit", variant: "primary", children: "\u641C\u7D22" }), _jsx(Button, { type: "reset", children: "\u91CD\u7F6E" })] }) }) }));
 }
+// ─── Breadcrumb ───────────────────────────────────────────────────────────────
 function BreadcrumbDemo() {
     const [items, setItems] = useState([
         { id: 'home', label: '首页' },
@@ -181,13 +198,16 @@ function BreadcrumbDemo() {
     ]);
     return (_jsx(Section, { title: "Breadcrumb", children: _jsx(Breadcrumb, { children: _jsx(BreadcrumbList, { children: items.map((item, idx) => (_jsxs(React.Fragment, { children: [_jsx(BreadcrumbItem, { children: _jsx(BreadcrumbPage, { active: item.active, onClose: () => setItems((prev) => prev.filter((i) => i.id !== item.id)), onClick: () => setItems((prev) => prev.map((i) => ({ ...i, active: i.id === item.id }))), className: "cursor-pointer", children: item.label }) }), idx < items.length - 1 && _jsx(BreadcrumbSeparator, {})] }, item.id))) }) }) }));
 }
+// ─── Label ────────────────────────────────────────────────────────────────────
 function LabelDemo() {
     return (_jsxs(Section, { title: "Label", children: [_jsx(Label, { label: "\u6C34\u5E73\u5E03\u5C40", layout: "horizontal", children: _jsx("span", { className: "text-sm", children: "\u5185\u5BB9\u533A\u57DF" }) }), _jsx(Label, { label: "\u5782\u76F4\u5E03\u5C40", layout: "vertical", children: _jsx("span", { className: "text-sm", children: "\u5185\u5BB9\u533A\u57DF" }) })] }));
 }
+// ─── Form ─────────────────────────────────────────────────────────────────────
 function FormDemo() {
     const [form] = useForm();
     return (_jsx(Section, { title: "Form", children: _jsxs(Form, { form: form, onFinish: (v) => console.log('表单值:', v), children: [_jsx(FormItem, { name: "username", label: "\u7528\u6237\u540D", required: true, rules: [{ required: true, message: '请输入用户名' }], children: _jsx(Input, { placeholder: "\u8BF7\u8F93\u5165\u7528\u6237\u540D" }) }), _jsx(FormItem, { name: "password", label: "\u5BC6\u7801", required: true, rules: [{ required: true, message: '请输入密码' }], children: _jsx(Input, { type: "password", placeholder: "\u8BF7\u8F93\u5165\u5BC6\u7801" }) }), _jsx(Button, { type: "submit", children: "\u63D0\u4EA4" })] }) }));
 }
+// ─── SchemaForm ───────────────────────────────────────────────────────────────
 function SchemaFormDemo() {
     const form = useRef(undefined);
     return (_jsx(Section, { title: "SchemaForm", children: _jsx(SchemaForm, { layout: "horizontal", getForm: (f) => {
@@ -215,6 +235,7 @@ function SchemaFormDemo() {
                 },
             ], onFinish: (values) => console.log(values) }) }));
 }
+// ─── TableSearch ─────────────────────────────────────────────────────────────
 function TableSearchDemo() {
     return (_jsx(Section, { title: "TableSearch", children: _jsx(TableSearch, { onSearch: (v) => console.log(v), schemas: [
                 { type: 'input', key: 'q1', label: '字段1', fieldProps: {} },
@@ -227,9 +248,11 @@ function TableSearchDemo() {
                 { type: 'input', key: 'q8', label: '字段8', fieldProps: {} },
             ] }) }));
 }
+// ─── Skeleton ─────────────────────────────────────────────────────────────────
 function SkeletonDemo() {
     return (_jsx(Section, { title: "Skeleton", children: _jsxs("div", { className: "w-full space-y-4", children: [_jsxs("div", { children: [_jsx("p", { className: "text-xs text-gray-500 mb-1", children: "pageloading" }), _jsx(Skeleton, { mode: "pageloading", rows: 3, showTitle: true, showActions: true })] }), _jsxs("div", { children: [_jsx("p", { className: "text-xs text-gray-500 mb-1", children: "tableloading" }), _jsx(Skeleton, { mode: "tableloading", rows: 4 })] }), _jsxs("div", { children: [_jsx("p", { className: "text-xs text-gray-500 mb-1", children: "componentsloading" }), _jsx(Skeleton, { mode: "componentsloading", rows: 2 })] })] }) }));
 }
+// ─── TreeSelect ───────────────────────────────────────────────────────────────
 function TreeSelectDemo() {
     const [value, setValue] = useState(['1.1.1', '1.1.2']);
     const [indeterminate, setIndeterminate] = useState([]);
@@ -269,6 +292,7 @@ function TreeSelectDemo() {
                         setIndeterminate(indeterminate);
                     } })] }) }));
 }
+// ─── PreviewImage ─────────────────────────────────────────────────────────────
 function PreviewImageDemo() {
     const images = [
         'https://images.unsplash.com/photo-1778512828600-4a6540a1a115?w=900&auto=format&fit=crop&q=60&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxmZWF0dXJlZC1waG90b3MtZmVlZHw0fHx8ZW58MHx8fHx8',
@@ -276,12 +300,14 @@ function PreviewImageDemo() {
     ];
     return (_jsx(Section, { title: "PreviewImage", children: _jsx(PreviewImage, { images: images, initialIndex: 0 }) }));
 }
+// ─── ImageUpload ─────────────────────────────────────────────────────────────
 function ImageUploadDemo() {
     return (_jsx(Section, { title: "ImageUpload", children: _jsx(ImageUpload, { accept: ".jpg,.png", maxCount: 4, beforeChange: (f) => {
                 console.log(f);
                 return parseInt(Math.random() * 10 + '') % 2 === 0;
             } }) }));
 }
+// ─── Main ─────────────────────────────────────────────────────────────────────
 const TestPage = () => {
     return (_jsxs("div", { className: "p-6 max-w-5xl mx-auto", children: [_jsx("h1", { className: "text-2xl font-bold mb-6", children: "\u7EC4\u4EF6\u5C55\u793A" }), _jsx(ThemeSwitcher, {}), _jsx(ButtonDemo, {}), _jsx(InputDemo, {}), _jsx(InputNumberDemo, {}), _jsx(TextareaDemo, {}), _jsx(SelectDemo, {}), _jsx(CheckboxDemo, {}), _jsx(SwitchDemo, {}), _jsx(TooltipDemo, {}), _jsx(DropdownDemo, {}), _jsx(MessageDemo, {}), _jsx(ModalDemo, {}), _jsx(DrawerDemo, {}), _jsx(ConfirmDialogDemo, {}), _jsx(PaginationDemo, {}), _jsx(TableDemo, {}), _jsx(DataTableDemo, {}), _jsx(SearchDemo, {}), _jsx(BreadcrumbDemo, {}), _jsx(LabelDemo, {}), _jsx(FormDemo, {}), _jsx(SchemaFormDemo, {}), _jsx(TableSearchDemo, {}), _jsx(SkeletonDemo, {}), _jsx(TreeSelectDemo, {}), _jsx(DateTestPage, {}), _jsx(PreviewImageDemo, {}), _jsx(ImageUploadDemo, {}), _jsx(MenuTestPage, {})] }));
 };

package/fe/packages/ui/react/hooks/useExecuteOnce.d.ts

@@ -5,7 +5,25 @@ export declare const executionPhaseType: {
 };
 type ExecutionPhaseTypeKeys = keyof typeof executionPhaseType;
 export type ExecutionPhaseType = (typeof executionPhaseType)[ExecutionPhaseTypeKeys];
-export default function useExecuteOnce<T>(factory: () => T, options?: {
+/**
+ *
+ * @description 在各个阶段只触发一次
+ *  @demo
+ * ```
+    const count = useExecuteOnce(() => {
+        console.log('123'); // 只会在第一次render时触发
+        return 123
+    })
+
+    // count 123
+
+ * ```
+ */
+export default function useExecuteOnce<T>(factory: () => T, 
+/**
+ * @default executionPhase = render
+ */
+options?: {
     executionPhase: ExecutionPhaseType[] | ExecutionPhaseType;
 }): T | null;
 export {};

package/fe/packages/ui/react/hooks/useExecuteOnce.js

@@ -4,11 +4,32 @@ export const executionPhaseType = {
     render: 'render',
     unMount: 'unMount',
 };
-export default function useExecuteOnce(factory, options) {
+// type ExecutionPhaseType =
+//   (typeof executionPhaseType)[keyof typeof executionPhaseType];
+/**
+ *
+ * @description 在各个阶段只触发一次
+ *  @demo
+ * ```
+    const count = useExecuteOnce(() => {
+        console.log('123'); // 只会在第一次render时触发
+        return 123
+    })
+
+    // count 123
+
+ * ```
+ */
+export default function useExecuteOnce(factory, 
+/**
+ * @default executionPhase = render
+ */
+options) {
     const { executionPhase: pExecutionPhase = executionPhaseType.render } = options ?? {};
     const result = useRef(null);
     const _executionPhase = useMemo(() => (typeof pExecutionPhase === 'string' ? [pExecutionPhase] : pExecutionPhase), [pExecutionPhase]);
     const allowExecution = useRef([]);
+    // 跳过依赖;
     const executionPhase = useRef(_executionPhase);
     const runFN = (phase) => {
         if (!allowExecution.current.includes(phase)) {

package/fe/packages/ui/react/hooks/useRefState.d.ts

@@ -4,6 +4,18 @@ type CallBackFN<T> = (value: T) => void;
 type RefState<T> = RefObject<{
     data: T;
 }>;
+/**
+ *
+ * @demo
+ * ```
+    const [data, setData, dataRef] = useState(0);
+    
+    setData(1, (newData) => {
+        // newData 1
+        // data 0
+    })
+ * ```
+ */
 export default function useRefState<S>(initialState: S | (() => S)): [
     S,
     SetState<S>,

package/fe/packages/ui/react/hooks/useRefState.js

@@ -25,4 +25,5 @@ export default function useRefState(initialState) {
         }
     }, [callbackVersion]);
     return [v, setData, data];
+    // as [ExtractFNType<S>, SetState<S>];
 }

package/fe/packages/ui/react/hooks/useWatch.d.ts

@@ -3,7 +3,15 @@ export type WatchCompare<T> = (value: T, prevValue: T) => boolean;
 export type WatchCompareType = 'identity' | 'shallow';
 export type WatchSelector<TSource, TValue> = (source: TSource) => TValue;
 export type UseWatchOptions<T> = {
+    /**
+     * @default false
+     */
     immediate?: boolean;
+    /**
+     * Return true when the two values should be treated as equal.
+     *
+     * @default Array values use shallow compare, other values use Object.is.
+     */
     compare?: WatchCompareType | WatchCompare<T>;
 };
 export declare const identityCompare: <T>(value: T, prevValue: T) => boolean;

package/fe/packages/ui/react/i18n/I18nProvider.d.ts

@@ -1,11 +1,29 @@
 import type { I18nLanguage, I18nResources } from '../../../common/i18n';
 import { type ReactNode } from 'react';
 export interface I18nProviderProps {
+    /**
+     * 外部控制的显示语言。
+     */
     language?: I18nLanguage;
+    /**
+     * 未命中当前语言文案时的兜底语言。
+     */
     fallbackLanguage?: I18nLanguage;
+    /**
+     * 业务侧注入的多语言资源。
+     */
     resources?: I18nResources;
+    /**
+     * 是否把传入 resources 和现有 resources 合并。默认 true。
+     */
     mergeResources?: boolean;
+    /**
+     * 是否把 language 写入 localStorage。默认 true。
+     */
     persist?: boolean;
+    /**
+     * localStorage key。
+     */
     storageKey?: string;
     children: ReactNode;
 }

package/fe/packages/ui/react/i18n/useI18n.d.ts

@@ -5,5 +5,9 @@ export declare const useI18nStore: import("..").StoreHook<{
     setState: (partial: Partial<import("../../../common/index.js").I18nStore> | ((state: import("../../../common/index.js").I18nStore) => Partial<import("../../../common/index.js").I18nStore>)) => void;
     subscribe: (listener: import("../../../common/index.js").I18nStoreListener) => () => void;
 }>;
+/**
+ * React 组件内使用的翻译 hook。
+ * 会订阅 language、fallbackLanguage、resources，语言或资源变化时触发组件更新。
+ */
 export declare function useI18n(): <T = string>(key: string, fillingData?: I18nInterpolationValues, options?: I18nTranslateOptions) => string | T;
 //# sourceMappingURL=useI18n.d.ts.map

package/fe/packages/ui/react/i18n/useI18n.js

@@ -2,6 +2,10 @@ import { i18nStore, translate } from '../../../common/i18n';
 import { useCallback } from 'react';
 import { createStoreHook } from '../lib/createStoreHook';
 export const useI18nStore = createStoreHook(i18nStore);
+/**
+ * React 组件内使用的翻译 hook。
+ * 会订阅 language、fallbackLanguage、resources，语言或资源变化时触发组件更新。
+ */
 export function useI18n() {
     const language = useI18nStore((state) => state.language);
     const fallbackLanguage = useI18nStore((state) => state.fallbackLanguage);

package/fe/packages/ui/react/index.js

@@ -1,4 +1,6 @@
 export * from './components';
 export * from './i18n';
+// export * from './hooks'
+// export * from './stores'
 export * from './lib/createStoreHook';
 export * from './lib/utils';

package/fe/packages/ui/react/lib/export.d.ts

@@ -1,22 +1,66 @@
+/**
+ * 导出 Excel 工具方法
+ *
+ * 功能：
+ * - 支持导出「当前页」或「当前查询条件下的全部页数据」
+ * - 通过 DataTable 的 columns 控制导出列及顺序
+ *
+ * 使用方式（示例）：
+ * ```ts
+ * await exportToExcel({
+ *   fetchData: (pageNum, pageSize) => getWithdrawList({ ...searchParams, pageNum, pageSize }),
+ *   columns, // 直接复用 DataTable 的 columns
+ *   exportType: 'all', // 'all' 导出全部页；'current' 仅导出当前页
+ *   currentPage,
+ *   pageSize,
+ *   total,
+ *   currentPageData: tableData, // 可选，导出当前页时直接使用现有数据，避免重复请求
+ *   fileName: '提币记录',
+ * })
+ * ```
+ */
 import { type TableColumnDef } from '../components';
 export declare const ExportType: {
+    /**
+     * 当前查询条件下所有页
+     */
     readonly all: 0;
+    /**
+     * 当前页
+     */
     readonly current: 1;
 };
 export type ExportType = (typeof ExportType)[keyof typeof ExportType];
 interface ExportExcelParams<T> {
+    /** 获取数据方法 */
     fetchData: (pageNum: number, pageSize: number, searchParams?: Record<string, any>) => Promise<{
         records: T[];
         total: number;
     }>;
+    /** 直接复用 DataTable 的 columns 配置  会自动过滤 操作栏*/
     columns: TableColumnDef<T>[];
+    /** 导出类型：all=当前查询条件下所有页；current=当前页 */
     exportType: ExportType;
+    /** 当前页码（导出当前页时使用）默认 1 */
     currentPage?: number;
+    /** 每页条数，默认 2000 */
     pageSize?: number;
+    /**
+     * 最大导出条数，超过则停止继续请求
+     * @default 10000
+     */
     maxCount?: number;
+    /**
+     * 当前页已有数据
+     * - 当 exportType === 'current' 且传入该字段时，将直接使用该数据，不会再次请求接口
+     */
     currentPageData?: T[];
+    /** 文件名（不含扩展名），默认：export-YYYYMMDDHHmmss */
     fileName?: string;
 }
+/**
+ * 通用导出 Excel 方法
+ */
 export declare function exportToExcel<T>(options: ExportExcelParams<T>): Promise<void>;
 export {};
 //# sourceMappingURL=export.d.ts.map