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

package/fe/packages/ui/react/components/Pagination/Pagination.d.ts

@@ -1,10 +1,17 @@
 export interface PaginationProps {
+    /** 当前页码 */
     current: number;
+    /** 每页显示数量 */
     pageSize: number;
+    /** 总数据量 */
     total: number;
+    /** 页码改变回调 */
     onChange: (page: number) => void;
+    /** 每页显示数量改变回调 */
     onPageSizeChange?: (pageSize: number) => void;
+    /** 每页显示数量选项 */
     pageSizeOptions?: number[];
+    /** 自定义类名 */
     className?: string;
 }
 export declare function Pagination({ current, pageSize, total, onChange, onPageSizeChange, pageSizeOptions, className, }: PaginationProps): import("react/jsx-runtime").JSX.Element | null;

package/fe/packages/ui/react/components/Pagination/Pagination.js

@@ -5,16 +5,20 @@ import { Button } from '../Button';
 import { Select } from '../Select';
 export function Pagination({ current, pageSize, total, onChange, onPageSizeChange, pageSizeOptions = [10, 20, 50, 100], className, }) {
     const totalPages = Math.ceil(total / pageSize);
+    // 生成页码数组
     const getPageNumbers = () => {
         const pages = [];
-        const maxVisible = 7;
+        const maxVisible = 7; // 最多显示7个页码
         if (totalPages <= maxVisible) {
+            // 总页数少于等于7，显示所有页码
             for (let i = 1; i <= totalPages; i++) {
                 pages.push(i);
             }
         }
         else {
+            // 总页数大于7，需要省略
             if (current <= 4) {
+                // 当前页在前面
                 for (let i = 1; i <= 5; i++) {
                     pages.push(i);
                 }
@@ -22,6 +26,7 @@ export function Pagination({ current, pageSize, total, onChange, onPageSizeChang
                 pages.push(totalPages);
             }
             else if (current >= totalPages - 3) {
+                // 当前页在后面
                 pages.push(1);
                 pages.push('...');
                 for (let i = totalPages - 4; i <= totalPages; i++) {
@@ -29,6 +34,7 @@ export function Pagination({ current, pageSize, total, onChange, onPageSizeChang
                 }
             }
             else {
+                // 当前页在中间
                 pages.push(1);
                 pages.push('...');
                 for (let i = current - 1; i <= current + 1; i++) {
@@ -58,6 +64,7 @@ export function Pagination({ current, pageSize, total, onChange, onPageSizeChang
     const handlePageSizeChange = (newPageSize) => {
         if (newPageSize !== undefined && typeof newPageSize === 'number' && newPageSize !== pageSize && onPageSizeChange) {
             onPageSizeChange(newPageSize);
+            // 当改变 pageSize 时，通常需要重置到第一页
             if (current !== 1) {
                 onChange(1);
             }

package/fe/packages/ui/react/components/Popup/Popup.js

@@ -6,9 +6,11 @@ import { getDefaultDropdownPosition, useDropdownPositioning, } from "../hooks/us
 const DEFAULT_POPUP_CLASSNAME = cn("fixed z-[9999]", "bg-background rounded-lg shadow-lg border border-gray-200", "animate-in fade-in-0 zoom-in-95");
 const canUseDocument = () => typeof document !== "undefined";
 export function Popup({ open, anchorRef, children, className, style, placement = "bottom-end", offset = 8, keepMounted = false, closeOnClickOutside = true, closeOnEscape = true, matchAnchorWidth = false, position, positioning, strategy = getDefaultDropdownPosition, contentRef, container, positionMode = "fixed", hoverBridge = 0, hoverBridgePlacement = "auto", onOpenChange, }) {
+    // 默认自己保存弹窗 DOM；如果外部传了 contentRef，就用外部的。
     const internalContentRef = useRef(null);
     const panelRef = contentRef ?? internalContentRef;
     const containerRef = useMemo(() => ({ current: container ?? null }), [container]);
+    // 默认用 useDropdownPositioning 算位置；也允许外部直接传 position 或 positioning 接管。
     const internalPositioning = useDropdownPositioning({
         open,
         anchorRef,
@@ -26,6 +28,7 @@ export function Popup({ open, anchorRef, children, className, style, placement =
     useEffect(() => {
         if (!open || !closeOnClickOutside)
             return;
+        // 点到触发元素和弹窗外面，就通知外部关闭。
         const handleClickOutside = (event) => {
             const target = event.target;
             const clickedAnchor = anchorRef.current?.contains(target);
@@ -40,6 +43,7 @@ export function Popup({ open, anchorRef, children, className, style, placement =
     useEffect(() => {
         if (!open || !closeOnEscape)
             return;
+        // 按 Esc 时关闭，常见弹窗交互都需要这个。
         const handleKeyDown = (event) => {
             if (event.key === "Escape") {
                 onOpenChange?.(false);
@@ -49,21 +53,29 @@ export function Popup({ open, anchorRef, children, className, style, placement =
         return () => document.removeEventListener("keydown", handleKeyDown);
     }, [closeOnEscape, onOpenChange, open]);
     const mergedStyle = useMemo(() => ({
+        // 定位样式优先来自 hook，也可以被外部 position/style 覆盖。
         ...resolvedPositioning?.position,
         ...position,
         ...style,
     }), [position, resolvedPositioning?.position, style]);
+    // hoverBridge 是透明桥。鼠标从触发元素移动到弹窗时，中间有间距也不会断 hover。
     const showHorizontalHoverBridge = hoverBridge > 0 &&
         (placement.startsWith("right") || placement.startsWith("left"));
     const showBothHorizontalHoverBridges = showHorizontalHoverBridge && hoverBridgePlacement === "horizontal";
     if (!keepMounted && !open) {
+        // 不需要常驻 DOM 时，关闭就不渲染。
         return null;
     }
     const portalContainer = container ?? (canUseDocument() ? document.body : undefined);
     if (!portalContainer) {
         return null;
     }
-    return createPortal(_jsxs("div", { ref: panelRef, className: cn("tc-ui-popup", DEFAULT_POPUP_CLASSNAME, positionMode === "absolute" && "absolute", !resolvedPositioning?.ready && "invisible", keepMounted && !open && "hidden", className), style: mergedStyle, children: [hoverBridge > 0 && (_jsx("div", { "aria-hidden": "true", className: cn("absolute bg-transparent", placement.startsWith("bottom") && "left-0 right-0 top-0 -translate-y-full", placement.startsWith("top") && "bottom-0 left-0 right-0 translate-y-full", placement.startsWith("right") && "bottom-0 left-0 top-0 -translate-x-full", placement.startsWith("left") && "bottom-0 right-0 top-0 translate-x-full"), style: placement.startsWith("right") || placement.startsWith("left")
+    // 用 portal 把弹窗挂到指定容器；没传 container 就挂到 body。
+    return createPortal(_jsxs("div", { ref: panelRef, className: cn("tc-ui-popup", DEFAULT_POPUP_CLASSNAME, positionMode === "absolute" && "absolute", !resolvedPositioning?.ready && "invisible", keepMounted && !open && "hidden", className), style: mergedStyle, children: [hoverBridge > 0 && (
+            // 默认只补当前 placement 方向上的透明桥。
+            _jsx("div", { "aria-hidden": "true", className: cn("absolute bg-transparent", placement.startsWith("bottom") && "left-0 right-0 top-0 -translate-y-full", placement.startsWith("top") && "bottom-0 left-0 right-0 translate-y-full", placement.startsWith("right") && "bottom-0 left-0 top-0 -translate-x-full", placement.startsWith("left") && "bottom-0 right-0 top-0 translate-x-full"), style: placement.startsWith("right") || placement.startsWith("left")
                     ? { width: hoverBridge }
-                    : { height: hoverBridge } })), showBothHorizontalHoverBridges && (_jsx("div", { "aria-hidden": "true", className: "absolute bottom-0 right-0 top-0 translate-x-full bg-transparent", style: { width: hoverBridge } })), children] }), portalContainer);
+                    : { height: hoverBridge } })), showBothHorizontalHoverBridges && (
+            // 横向弹窗可能动态从右改到左，这里左右都补桥，避免鼠标移过去时弹窗关闭。
+            _jsx("div", { "aria-hidden": "true", className: "absolute bottom-0 right-0 top-0 translate-x-full bg-transparent", style: { width: hoverBridge } })), children] }), portalContainer);
 }

package/fe/packages/ui/react/components/Search/Search.d.ts

@@ -6,6 +6,9 @@ export type SearchProps<T> = {
     defaultValue?: T;
     schemas: MOmit<FormFieldSchema<T>, 'rules' | 'required'>[];
     children?: ReactNode;
+    /**
+     * 获取表单实例的回调
+     */
     getForm?: (form: FormInstance<T>) => void;
     btnsClassName?: string;
 };

package/fe/packages/ui/react/components/Select/Select.d.ts

@@ -1,7 +1,9 @@
 import React from 'react';
 export type SelectOption = {
+    /** 展示内容；传 ReactNode 时建议同时提供 searchText 用于搜索 */
     label: React.ReactNode;
     value: string | number;
+    /** 搜索文本；优先级高于 label */
     searchText?: string;
 };
 export type SelectProps = {
@@ -12,8 +14,11 @@ export type SelectProps = {
     onChange?: (value: string | number | undefined) => void;
     className?: string;
     disabled?: boolean;
+    /** 开启清除 默认开启*/
     clearable?: boolean;
+    /** 是否支持搜索 默认开启 */
     searchable?: boolean;
+    /** 自定义弹出容器，传 parent 时挂载到当前 Select 的父元素，不传则默认挂载到 document.body */
     getPopupContainer?: 'parent' | (() => HTMLElement);
 };
 declare const Select: React.ForwardRefExoticComponent<SelectProps & React.RefAttributes<HTMLDivElement>>;

package/fe/packages/ui/react/components/Select/Select.js

@@ -34,6 +34,7 @@ const Select = forwardRef(({ options, value: controlledValue, defaultValue, plac
             container.style.position = previousPosition;
         };
     }, [isParentPopupContainer]);
+    // 合并 refs
     const setRefs = useCallback((node) => {
         selectRef.current = node;
         if (typeof ref === 'function') {
@@ -45,6 +46,7 @@ const Select = forwardRef(({ options, value: controlledValue, defaultValue, plac
     }, [ref]);
     const isControlled = controlledValue !== undefined;
     const value = isControlled ? controlledValue : internalValue;
+    // 获取当前选中的选项
     const selectedOption = options.find((opt) => opt.value === value);
     const displayText = selectedOption ? selectedOption.label : placeholder || '';
     const filteredOptions = useMemo(() => {
@@ -72,6 +74,7 @@ const Select = forwardRef(({ options, value: controlledValue, defaultValue, plac
         containerRef: isParentPopupContainer ? popupContainerRef : undefined,
         positionMode: isParentPopupContainer ? 'absolute' : 'fixed',
     });
+    // 展开时更新位置并获取焦点
     useEffect(() => {
         if (isOpen) {
             requestAnimationFrame(() => {
@@ -103,6 +106,7 @@ const Select = forwardRef(({ options, value: controlledValue, defaultValue, plac
         event.stopPropagation();
         if (disabled)
             return;
+        // 清除时 重置内外状态
         setInternalValue(undefined);
         onChange?.(undefined);
     }, [disabled, onChange]);

package/fe/packages/ui/react/components/Skeleton/Skeleton.d.ts

@@ -1,9 +1,24 @@
 import type { HTMLAttributes } from 'react';
 export type SkeletonMode = 'pageloading' | 'tableloading' | 'componentsloading';
 export interface SkeletonProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * 骨架屏模式
+     * @default 'componentsloading'
+     */
     mode?: SkeletonMode;
+    /**
+     * 行数（仅对 pageloading 和 tableloading 有效）
+     */
     rows?: number;
+    /**
+     * 是否显示标题骨架（仅对 pageloading 有效）
+     * @default true
+     */
     showTitle?: boolean;
+    /**
+     * 是否显示操作栏骨架（仅对 pageloading 有效）
+     * @default true
+     */
     showActions?: boolean;
 }
 export declare const Skeleton: {

package/fe/packages/ui/react/components/Skeleton/Skeleton.js

@@ -7,7 +7,7 @@ const PageLoadingSkeleton = ({ rows = 5, showTitle = true, showActions = true })
     return (_jsxs("div", { className: "w-full space-y-6 p-6", children: [showTitle && (_jsxs("div", { className: "flex items-center justify-between", children: [_jsx(SkeletonItem, { className: "h-8 w-48" }), showActions && (_jsxs("div", { className: "flex gap-3", children: [_jsx(SkeletonItem, { className: "h-10 w-24" }), _jsx(SkeletonItem, { className: "h-10 w-24" })] }))] })), _jsxs("div", { className: "flex gap-4", children: [_jsx(SkeletonItem, { className: "h-10 flex-1" }), _jsx(SkeletonItem, { className: "h-10 w-24" }), _jsx(SkeletonItem, { className: "h-10 w-24" })] }), _jsx("div", { className: "space-y-4", children: Array.from({ length: rows }).map((_, index) => (_jsxs("div", { className: "flex gap-4", children: [_jsx(SkeletonItem, { className: "h-20 flex-1" }), _jsx(SkeletonItem, { className: "h-20 w-32" }), _jsx(SkeletonItem, { className: "h-20 w-32" })] }, index))) }), _jsxs("div", { className: "flex items-center justify-between", children: [_jsx(SkeletonItem, { className: "h-4 w-32" }), _jsxs("div", { className: "flex gap-2", children: [_jsx(SkeletonItem, { className: "h-8 w-8" }), _jsx(SkeletonItem, { className: "h-8 w-8" }), _jsx(SkeletonItem, { className: "h-8 w-8" })] })] })] }));
 };
 const TableLoadingSkeleton = ({ rows = 5 }) => {
-    const columnCount = 6;
+    const columnCount = 6; // 默认列数，可以根据需要调整
     return (_jsx("div", { className: "w-full", children: _jsx("div", { className: "bg-background rounded-[20px] overflow-hidden", children: _jsxs(Table, { containerClassName: "rounded-b-none", children: [_jsx(TableHeader, { children: _jsx(TableRow, { children: Array.from({ length: columnCount }).map((_, index) => (_jsx(TableHead, { children: _jsx(SkeletonText, { width: index === 0 ? 120 : index === columnCount - 1 ? 80 : 150 }) }, index))) }) }), _jsx(TableBody, { children: Array.from({ length: rows }).map((_, rowIndex) => (_jsx(TableRow, { children: Array.from({ length: columnCount }).map((_, colIndex) => (_jsx(TableCell, { children: colIndex === columnCount - 1 ? (_jsxs("div", { className: "flex gap-2", children: [_jsx(SkeletonItem, { className: "h-8 w-16" }), _jsx(SkeletonItem, { className: "h-8 w-16" })] })) : (_jsx(SkeletonText, { width: colIndex === 0 ? 120 : colIndex === 1 ? '80%' : 150 })) }, colIndex))) }, rowIndex))) })] }) }) }));
 };
 const ComponentsLoadingSkeleton = ({ rows = 3 }) => {

package/fe/packages/ui/react/components/TableSearch/TableSearch.d.ts

@@ -5,6 +5,10 @@ import { type DropdownItem } from '../Dropdown';
 import type { FormFieldSchema } from '../Form';
 import type { SearchProps } from '../Search/Search';
 export type TableSearchSchema<T> = MOmit<FormFieldSchema<T>, 'rules' | 'required'> & {
+    /**
+     * - 字段是否常驻
+     * - 如果都没有则去前四个
+     */
     isPermanent?: boolean;
 };
 type TableSearchProps<T> = MOmit<SearchProps<T>, 'children' | 'schemas'> & {
@@ -12,18 +16,51 @@ type TableSearchProps<T> = MOmit<SearchProps<T>, 'children' | 'schemas'> & {
     onReset?: () => void;
     renderActionBtnArea?: () => ReactNode;
     schemas: TableSearchSchema<T>[];
+    /**
+     * 导出Excel按钮的下拉菜单项
+     */
     exportMenuItems?: DropdownItem[];
     btnConfig?: Partial<{
+        /**
+         * 导出Excel按钮的文案
+         */
         export?: ReactNode;
+        /**
+         * 收起按钮的文案
+         */
         collapse?: ReactNode;
+        /**
+         * 展开按钮的icon
+         */
         expandIcon?: ReactNode;
+        /**
+         * 展开按钮的文案
+         */
         expand?: ReactNode;
+        /**
+         * 重置按钮的文案
+         */
         reset?: ReactNode;
+        /**
+         * 查询按钮的文案
+         */
         search?: ReactNode;
     }>;
+    /**
+     * 备选边界
+     */
     expandBoundaries?: number;
+    /**
+     *
+     * @param exportType 导出类型
+     * @param searchData 当前查询条件
+     * @returns
+     */
     onExport?: (exportType: ExportType, searchData: T) => void;
     additionalButtons?: ReactNode;
+    /**
+     * 默认是否展开 @default true
+     */
     defaultExpand?: boolean;
 };
 declare const TableSearch: <T extends object>(props: TableSearchProps<T>) => import("react/jsx-runtime").JSX.Element;

package/fe/packages/ui/react/components/TableSearch/TableSearch.js

@@ -91,6 +91,7 @@ const TableSearch = (props) => {
     }, [expandBoundaries, schemas]);
     const showExpandedBtn = schemas.length > expandBoundaries;
     let SSchemas;
+    // 有展开
     if (showExpandedBtn) {
         SSchemas = isExpanded
             ? schemas
@@ -113,6 +114,8 @@ const TableSearch = (props) => {
     }
     return (_jsx("div", { className: "tc-ui-table-search", children: _jsxs(Search, { getForm: (form) => {
                 formRef.current = form;
-            }, schemas: SSchemas, ...searchProps, children: [showExpandedBtn && (_jsx(Button, { variant: "default", size: "sm", onClick: handleExpand, rightIcon: _jsx("span", { className: cn('transition-transform duration-200', isExpanded && 'rotate-180'), children: btnConfig.expandIcon }), children: isExpanded ? btnConfig.collapseBtn : btnConfig.expandBtn }, "expandedBtn")), _jsx(Button, { variant: "primary", size: "sm", onClick: handleSearch, children: btnConfig.searchBtn }), _jsx(Button, { variant: "default", size: "sm", onClick: handleReset, children: btnConfig.resetBtn }), renderActionBtnArea ? (renderActionBtnArea()) : (_jsx(Dropdown, { items: defaultExportItems, placement: "bottom-end", children: _jsx(Button, { variant: "default", size: "sm", rightIcon: _jsx(ChevronDown, { className: "h-4 w-4" }), children: btnConfig.exportBtn }) })), additionalButtons] }) }));
+            }, schemas: SSchemas, ...searchProps, children: [showExpandedBtn && (_jsx(Button, { variant: "default", size: "sm", onClick: handleExpand, rightIcon: _jsx("span", { className: cn('transition-transform duration-200', isExpanded && 'rotate-180'), children: btnConfig.expandIcon }), children: isExpanded ? btnConfig.collapseBtn : btnConfig.expandBtn }, "expandedBtn")), _jsx(Button, { variant: "primary", size: "sm", onClick: handleSearch, children: btnConfig.searchBtn }), _jsx(Button, { variant: "default", size: "sm", onClick: handleReset, children: btnConfig.resetBtn }), renderActionBtnArea ? (renderActionBtnArea()) : (
+                //  导出Excel按钮
+                _jsx(Dropdown, { items: defaultExportItems, placement: "bottom-end", children: _jsx(Button, { variant: "default", size: "sm", rightIcon: _jsx(ChevronDown, { className: "h-4 w-4" }), children: btnConfig.exportBtn }) })), additionalButtons] }) }));
 };
 export default TableSearch;

package/fe/packages/ui/react/components/Textarea/Textarea.d.ts

@@ -1,20 +1,66 @@
 import type { ChangeEvent, TextareaHTMLAttributes } from "react";
 export type TextareaProps = Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, "value" | "onChange" | "defaultValue"> & {
     value?: string;
+    /**
+     *
+     * @param v textarea value
+     * @param e changeEvent
+     */
     onChange?: (v: string, e: ChangeEvent<HTMLTextAreaElement>) => void;
+    /**
+     * 只有初始化时会使用
+     * 如果会改变请使用value
+     */
     defaultValue?: string;
+    /**
+     * 最大字符数限制
+     * @default 500
+     */
     maxLength?: number;
+    /**
+     * 是否显示字符计数器
+     * @default true
+     */
     showCount?: boolean;
+    /**
+     * 占位符文本
+     */
     placeholder?: string;
+    /**
+     * 原生 textarea 节点的自定义 className
+     */
     textareaClassName?: string;
 };
 declare const Textarea: import("react").ForwardRefExoticComponent<Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, "value" | "defaultValue" | "onChange"> & {
     value?: string;
+    /**
+     *
+     * @param v textarea value
+     * @param e changeEvent
+     */
     onChange?: (v: string, e: ChangeEvent<HTMLTextAreaElement>) => void;
+    /**
+     * 只有初始化时会使用
+     * 如果会改变请使用value
+     */
     defaultValue?: string;
+    /**
+     * 最大字符数限制
+     * @default 500
+     */
     maxLength?: number;
+    /**
+     * 是否显示字符计数器
+     * @default true
+     */
     showCount?: boolean;
+    /**
+     * 占位符文本
+     */
     placeholder?: string;
+    /**
+     * 原生 textarea 节点的自定义 className
+     */
     textareaClassName?: string;
 } & import("react").RefAttributes<HTMLTextAreaElement>>;
 export { Textarea };

package/fe/packages/ui/react/components/Textarea/Textarea.js

@@ -10,6 +10,7 @@ const Textarea = forwardRef(({ className, textareaClassName, value: controlledVa
     });
     const handleChange = useCallback((e) => {
         const newValue = e.target.value;
+        // 如果设置了 maxLength，限制输入长度
         if (maxLength && newValue.length > maxLength) {
             return;
         }

package/fe/packages/ui/react/components/Tooltip/Tooltip.d.ts

@@ -1,8 +1,24 @@
 export interface TooltipProps {
+    /**
+     * 提示内容
+     */
     content: React.ReactNode;
+    /**
+     * 触发元素
+     */
     children: React.ReactElement;
+    /**
+     * 提示位置
+     * @default 'right'
+     */
     placement?: "top" | "bottom" | "left" | "right";
+    /**
+     * 是否显示
+     */
     visible?: boolean;
+    /**
+     * 类名
+     */
     className?: string;
 }
 export declare function Tooltip({ content, children, placement, visible, className, }: TooltipProps): import("react/jsx-runtime").JSX.Element;

package/fe/packages/ui/react/components/Tooltip/Tooltip.js

@@ -26,12 +26,18 @@ export function Tooltip({ content, children, placement = "right", visible, class
         }
     }, [visible]);
     useEffect(() => {
+        // 显示时
         if (isVisible && triggerRef.current && tooltipRef.current) {
+            // 使用 requestAnimationFrame 确保 DOM 已更新
             requestAnimationFrame(() => {
                 if (!triggerRef.current || !tooltipRef.current)
                     return;
                 const triggerRect = triggerRef.current.getBoundingClientRect();
                 const tooltipRect = tooltipRef.current.getBoundingClientRect();
+                // const scrollY = window.scrollY;
+                // const scrollX = window.scrollX;
+                // const viewportWidth = window.innerWidth;
+                // const viewportHeight = window.innerHeight;
                 const padding = 8;
                 let top = 0;
                 let left = 0;
@@ -51,6 +57,7 @@ export function Tooltip({ content, children, placement = "right", visible, class
                         left = triggerRect.left - tooltipRect.width - padding;
                         break;
                     case "right":
+                        // 直接使用元素所在元素
                         top = triggerRect.top;
                         left = triggerRect.right + padding;
                         break;
@@ -58,6 +65,7 @@ export function Tooltip({ content, children, placement = "right", visible, class
                 setPosition({ top, left });
             });
         }
+        // 隐藏时 重置定位定制 去除重影
         if (!isVisible) {
             const top = -100, left = -100;
             setPosition({ top, left });

package/fe/packages/ui/react/components/TreeSelect/TreeSelect.d.ts

@@ -5,14 +5,20 @@ export interface TreeNode {
     children?: TreeNode[];
 }
 export interface TreeSelectProps {
+    /** 树形数据 */
     data: TreeNode[];
+    /** 已选中的节点 ID 数组 */
     value?: (string | number)[];
+    /** 选中状态改变回调，返回选中的 keys 和半选的 keys */
     onChange?: (keys: {
         checked: (string | number)[];
         indeterminate: (string | number)[];
     }) => void;
+    /** 节点文本字段名 */
     labelField?: 'name' | 'desctext';
+    /** 是否可以选择 */
     checkable?: boolean;
+    /** 自定义类名 */
     className?: string;
 }
 export declare function TreeSelect({ data, value, onChange, labelField, checkable, className, }: TreeSelectProps): import("react/jsx-runtime").JSX.Element;

package/fe/packages/ui/react/components/TreeSelect/TreeSelect.js

@@ -21,6 +21,7 @@ export function TreeSelect({ data, value = [], onChange, labelField = 'name', ch
         traverse(data, null);
         return { nodeMap: nodeM, parentMap: parentM };
     }, [data]);
+    // 获取节点的所有子节点 ID
     const getDescendantIds = useCallback((node) => {
         const ids = [];
         const traverse = (n) => {
@@ -54,6 +55,7 @@ export function TreeSelect({ data, value = [], onChange, labelField = 'name', ch
         };
         checkedSet.forEach((id) => traverseUp(id));
     }, [nodeMap, parentMap]);
+    // 切换展开/折叠
     const toggleExpand = useCallback((nodeId) => {
         setExpandedKeys((prev) => {
             const newSet = new Set(prev);
@@ -91,6 +93,7 @@ export function TreeSelect({ data, value = [], onChange, labelField = 'name', ch
         traverse(data);
         return indeterminateKeys;
     }, [data]);
+    // 切换选中状态
     const toggleCheck = useCallback((node) => {
         if (!checkable || !onChange)
             return;
@@ -109,6 +112,7 @@ export function TreeSelect({ data, value = [], onChange, labelField = 'name', ch
         const indeterminateKeys = getIndeterminateKeys(nextChecked);
         onChange({ checked: Array.from(nextChecked), indeterminate: indeterminateKeys });
     }, [value, onChange, checkable, getDescendantIds, updateParentSelection, getIndeterminateKeys]);
+    // 判断节点是否选中
     const isNodeChecked = useCallback((nodeId) => {
         return value.includes(nodeId);
     }, [value]);
@@ -127,6 +131,7 @@ export function TreeSelect({ data, value = [], onChange, labelField = 'name', ch
         const { total, checked } = getDescendantCount(node);
         return checked > 0 && checked < total;
     }, [value]);
+    // 渲染树节点
     function renderTreeNode(node, level = 0) {
         const hasChildren = node.children && node.children.length > 0;
         const isExpanded = expandedKeys.has(node.id);
@@ -147,6 +152,7 @@ export function TreeSelect({ data, value = [], onChange, labelField = 'name', ch
                                 }
                             }, children: labelField === 'desctext' ? node.desctext || node.name : node.name })] }), hasChildren && isExpanded && _jsx("div", { children: node.children.map((child) => renderTreeNode(child, level + 1)) })] }, node.id));
     }
+    // 如果没有数据
     if (!data || data.length === 0) {
         return _jsx("div", { className: cn('tc-ui-tree-select p-8 text-center text-sm text-muted-foreground', className), children: "No data" });
     }

package/fe/packages/ui/react/components/Upload/Upload.d.ts

@@ -1,13 +1,40 @@
 import type { ChangeEvent, ReactNode, RefObject } from 'react';
 export interface FileUploadProps {
+    /**
+     * 文件 input 的 ref，用于父组件重置 value 等
+     */
     inputRef?: RefObject<HTMLInputElement | null>;
+    /**
+     * input 的 accept 属性，默认接收任意文件
+     */
     accept?: string;
+    /**
+     * 是否支持多选
+     */
     multiple?: boolean;
+    /**
+     * 选择文件时的回调
+     */
     onChange?: (event: ChangeEvent<HTMLInputElement>) => void;
+    /**
+     * 选择文件按钮文案
+     */
     selectLabel: ReactNode;
+    /**
+     * label 的自定义 className
+     */
     labelClassName?: string;
+    /**
+     * 是否展示清空按钮
+     */
     showClear?: boolean;
+    /**
+     * 清空按钮点击回调
+     */
     onClear?: () => void;
+    /**
+     * 清空按钮文案
+     */
     clearLabel?: ReactNode;
 }
 export declare function FileUpload({ inputRef, accept, multiple, onChange, selectLabel, labelClassName, showClear, onClear, clearLabel, }: FileUploadProps): import("react/jsx-runtime").JSX.Element;

package/fe/packages/ui/react/components/breadcrumb/breadcrumb.js

@@ -3,6 +3,7 @@ import { useI18n } from '../../i18n';
 import { useBreadcrumb } from '../../hooks/useBreadcrumb';
 import { useLanguage } from '../../hooks/useLanguage';
 import { cn } from '../../lib/utils';
+// import useUserStore from '@tc/ui-react/stores/user'
 import { ChevronRight, MoreHorizontal } from 'lucide-react';
 import { forwardRef } from 'react';
 import { useNavigate } from 'react-router-dom';
@@ -46,13 +47,18 @@ export function SimpleBreadcrumb({ className }) {
     const handleBreadcrumbClose = (id) => {
         const itemToRemove = items.find((item) => item.id === id);
         const isActive = itemToRemove?.active;
+        // 先计算剩余的面包屑项（在删除之前）
         const remainingItems = items.filter((item) => item.id !== id);
+        // 立即删除该项，确保状态及时更新
         removeItem(id);
+        // 如果删除的是当前激活的项，需要跳转
         if (isActive) {
             if (remainingItems.length > 0) {
+                // 有剩余项，跳转到最后一个
                 const targetItem = remainingItems.at(-1);
                 const targetPath = targetItem.path;
                 if (targetPath) {
+                    // 使用 setTimeout 确保删除操作先完成
                     setTimeout(() => {
                         navigate(targetPath);
                         setActiveItem(targetItem.id);
@@ -60,7 +66,10 @@ export function SimpleBreadcrumb({ className }) {
                 }
             }
             else {
+                // 获取首页路径（第一个权限页面）
                 setTimeout(() => {
+                    // todo
+                    // navigate(useUserStore.getState().userPagePermissions[0]?.menuUrl || '/')
                 }, 0);
             }
         }

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

@@ -38,6 +38,12 @@ export type UseDropdownPositioningResult = {
     ready: boolean;
     updatePosition: () => void;
 };
+/**
+ * 计算弹窗该放在哪。
+ *
+ * right/left：跟触发元素顶部对齐，往右或往左弹。
+ * bottom/top：放在触发元素下方或上方，再按 start/end 对齐。
+ */
 export declare const getDefaultDropdownPosition: DropdownPositioningStrategy;
 export declare function useDropdownPositioning({ open, anchorRef, contentRef, placement, offset, matchAnchorWidth, strategy, estimateSize, watchDeps, containerRef, positionMode, }: UseDropdownPositioningOptions): UseDropdownPositioningResult;
 //# sourceMappingURL=useDropdownPositioning.d.ts.map