@pnt-team/pnt-component-frontend 0.0.130 → 0.0.133

package/lib/cjs/components/PntTable/types.d.ts

@@ -0,0 +1,225 @@
+/**
+ * PntTable 类型定义
+ *
+ * 统一表格组件的类型契约。设计目标：
+ *   1. 对齐产品规范 12 章 47 条规则（管理端组件规范）
+ *   2. 兼容 tdesign-react 1.3.0–1.18.2 跨版本
+ *   3. 零业务侵入：业务项目通过 fetcher 注入数据源，不依赖组件库内部 API
+ */
+import type { CSSProperties, ReactNode } from 'react';
+/** 主题 */
+export type PntTableTheme = 'business' | 'internal';
+/** 数据模式 */
+export type PntTableDataMode = 'server' | 'client';
+/** 表格状态 */
+export type PntTableStatus = 'normal' | 'empty' | 'empty-with-filter' | 'loading' | 'refreshing' | 'error' | 'no-permission';
+/** 排序方向 */
+export type PntSortDirection = 'asc' | 'desc';
+/** 排序字段（单列，TBL-04.02 禁止多列排序） */
+export interface PntSortInfo {
+    field: string;
+    direction: PntSortDirection;
+}
+/** 筛选值 */
+export type PntFilterValue = string | number | (string | number)[];
+/** 表头筛选选项 */
+export interface PntFilterOption {
+    label: string;
+    /** 选项值；checkAll 项可不传（tdesign 会自动处理为空值） */
+    value?: string | number;
+    /** 标记为「全部」选项（选中后清空筛选值，对应 tdesign filter.list 的 checkAll:true） */
+    checkAll?: boolean;
+}
+/** 表头筛选配置 */
+export interface PntTableFilterConfig {
+    /** 筛选模式：单选 Radio / 多选 Checkbox；传 'custom' 时走自定义 component */
+    mode: 'single' | 'multiple' | 'custom';
+    /** 静态选项（single/multiple 模式必填），支持 checkAll 项 */
+    options?: PntFilterOption[];
+    /** 异步加载选项（选项 > 8 项时建议用） */
+    fetcher?: () => Promise<PntFilterOption[]>;
+    /** 是否支持关键词搜索（选项 > 8 项时自动开启） */
+    searchable?: boolean;
+    /** 自定义筛选组件（mode='custom' 时必填），会透传给 tdesign filter.component */
+    component?: (props: any) => ReactNode;
+    /** 透传给 tdesign Table.filter 的额外属性（showConfirmAndReset / popupProps / resetValue / classNames 等） */
+    extra?: Record<string, any>;
+}
+/** 受控多选配置 */
+export interface PntTableSelectConfig {
+    /** 受控初始选中（client 模式常用） */
+    selectedRowKeys?: (string | number)[];
+    /** 判断某行是否禁用勾选（禁用行不参与全选） */
+    disabledRowKeysFn?: (row: any) => boolean;
+    /** 仅当前页（默认 true；翻页自动清空勾选） */
+    currentPageOnly?: boolean;
+}
+export interface PntTableColumn {
+    /** 字段 key（必填） */
+    key: string;
+    /** 列标题（必填） */
+    title: ReactNode;
+    /** 列宽（必填，TBL-02.06 建议档位） */
+    width: number;
+    /** 固定 */
+    fixed?: 'left' | 'right';
+    /** 数据类型：影响对齐和比较口径 */
+    type?: 'text' | 'number' | 'money' | 'percent' | 'date' | 'datetime' | 'enum';
+    /** 对齐（默认按 type 推断） */
+    align?: 'left' | 'right' | 'center';
+    /** 单行截断（默认 true）；2 = 最多 2 行 */
+    ellipsis?: boolean | 2;
+    /** 表头说明文案（TBL-03.04，点击打开 tooltip） */
+    help?: string;
+    /** 可排序 */
+    sort?: boolean;
+    /** 表头筛选 */
+    headerFilter?: PntTableFilterConfig;
+    /** 外置筛选（同字段需排序又需筛选时用，独立查询区） */
+    externalFilter?: boolean;
+    /** 列宽允许拖拽调整（扩展变体，二期实现） */
+    resizable?: boolean;
+    /** 列可隐藏（列设置功能） */
+    hidable?: boolean;
+    /** 是否系统必需列（列设置中不可隐藏） */
+    required?: boolean;
+    /** 自定义单元格渲染 */
+    cell?: (row: any, index: number) => ReactNode;
+    /** 列级权限策略 */
+    permission?: {
+        required?: string;
+        fallback?: 'hide' | 'disabled';
+    };
+}
+export interface PntTableQuery {
+    /** 外置查询条件（独立查询区草稿模式） */
+    query: Record<string, unknown>;
+    /** 表头筛选已生效条件 */
+    filters: Record<string, unknown>;
+    /** 排序：单列 { field, direction } 或 null */
+    sort: PntSortInfo | null;
+    /** 当前页（从 1 开始） */
+    page: number;
+    /** 每页条数 */
+    pageSize: number;
+    /** 业务 ID（必传） */
+    businessId?: string | number;
+    /** 环境（必传） */
+    env?: number;
+    /** 时区（必传） */
+    timezone?: string;
+}
+export interface PntTableResponse {
+    /** 数据行 */
+    rows: any[];
+    /** 筛选后的总记录数 */
+    total: number;
+    /** 错误码（0 或未传 = 成功） */
+    code?: number;
+    /** 错误信息 */
+    msg?: string;
+    /** 无权限时标记 */
+    noPermission?: boolean;
+}
+export type PntTableFetcher = (query: PntTableQuery) => Promise<PntTableResponse>;
+export type PntTableQueryTrigger = 'sort' | 'filter' | 'pagination' | 'page-size' | 'external-query' | 'reset' | 'initial';
+export interface PntTableQueryMeta {
+    tableId: string;
+    trigger: PntTableQueryTrigger;
+    /** 请求序号，用于请求顺序控制 */
+    requestId: number;
+}
+export interface PntTableSelectionMeta {
+    tableId: string;
+    /** 当前页所有 rowKey */
+    pageKeys: string[];
+    /** 当前页禁用行 rowKey */
+    disabledKeys: string[];
+    trigger: 'select' | 'select-all' | 'page-change' | 'reset' | 'refresh';
+}
+/** 业务代码通过 ref 获取的 PntTable 句柄 */
+export interface PntTableRef {
+    /** 强制刷新（服务端重拉、客户端重新应用排序/筛选） */
+    refresh: () => void;
+    /** 清空所有表头筛选 + 重置排序 + page=1 */
+    reset: () => void;
+    /** 获取当前表格查询快照（调试/埋点用） */
+    getQuerySnapshot: () => {
+        sort: PntSortInfo | null;
+        filters: Record<string, unknown>;
+        page: number;
+        pageSize: number;
+        total: number;
+    };
+}
+export interface PntTableProps {
+    /** 表格唯一 ID（契约要求） */
+    tableId: string;
+    /** 主题：业务侧蓝 / 内部平台紫 */
+    theme: PntTableTheme;
+    /** 业务唯一字段，用作 rowKey（禁止用行号） */
+    rowKey: string;
+    /** 列定义 */
+    columns: PntTableColumn[];
+    /** 数据模式：server（后端分页）/ client（前端全量） */
+    dataMode: PntTableDataMode;
+    /** 数据源：server 模式传 fetcher */
+    fetcher?: PntTableFetcher;
+    /** client 模式直接传 data */
+    data?: any[];
+    /** client 模式下的总数（可选，不传则用 data.length） */
+    total?: number;
+    /** 固定操作栏：操作列固定最右（默认 false，显式列需加 fixed: 'right'） */
+    fixedAction?: boolean;
+    /** 固定左侧识别列（默认 false） */
+    fixedLeft?: boolean;
+    /** 排序（默认 true；也可按列单独 col.sort: false 禁用） */
+    sortable?: boolean;
+    /** 表头筛选（默认 true；也可按列单独 col.headerFilter 配置） */
+    filterable?: boolean;
+    /** 多选行（默认 false；传对象可配置禁用行/受控初始选中） */
+    selectable?: boolean | PntTableSelectConfig;
+    /** 多选仅当前页（默认 true；翻页自动清空勾选，TBL-06.03）—— selectable 为对象时以 PntTableSelectConfig.currentPageOnly 为准 */
+    currentPageOnly?: boolean;
+    /** 分页（默认 true） */
+    pageable?: boolean;
+    /** 初始页码（默认 1，用于恢复路由/会话态） */
+    initialPage?: number;
+    /** 默认每页条数（默认 10） */
+    pageSize?: number;
+    /** 可选每页条数档位（默认 [10, 20, 50]） */
+    pageSizeOptions?: number[];
+    /** 自定义空态内容（优先级高于 emptyText） */
+    empty?: ReactNode;
+    /** 空态文案（默认 "暂无数据"） */
+    emptyText?: string;
+    /** 有条件空态提示（默认 "调整条件或重置查询"） */
+    emptyWithFilterHint?: string;
+    /** 是否显示边框（默认 false） */
+    bordered?: boolean;
+    /** 表格尺寸 */
+    size?: 'small' | 'medium' | 'large';
+    /** 表体最大高度（超则内部滚动，表头吸顶） */
+    bodyMaxHeight?: number;
+    /** 受控加载态（组件内部自动管理首次加载/刷新/骨架） */
+    loading?: boolean;
+    /** 受控错误态 */
+    error?: string | null;
+    /** 业务 ID（fetcher 自动透传） */
+    businessId?: string | number;
+    /** 环境 */
+    env?: number;
+    /** 时区 */
+    timezone?: string;
+    onQueryChange?: (query: PntTableQuery, meta: PntTableQueryMeta) => void;
+    onSelectionChange?: (selection: any[], meta: PntTableSelectionMeta) => void;
+    onRowAction?: (action: string, row: any, meta: {
+        tableId: string;
+        rowKey: string;
+    }) => void;
+    attach?: HTMLElement;
+    className?: string;
+    style?: CSSProperties;
+    /** 行样式类名（透传 TDesign rowClassName） */
+    rowClassName?: (row: any, index: number) => string;
+}

package/lib/cjs/components/PntTable/types.js

@@ -0,0 +1,17 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/components/PntTable/types.ts
+var types_exports = {};
+module.exports = __toCommonJS(types_exports);

package/lib/cjs/components/PntTable/useTableCore.d.ts

@@ -0,0 +1,38 @@
+/**
+ * useTableCore — PntTable 核心逻辑
+ *
+ * 负责：请求顺序控制、排序三态、筛选草稿/生效分离、多选三态、分页越界校验、7 种状态管理。
+ * 纯 React Hook，不依赖 TDesign DOM，方便单测和版本降级。
+ */
+import type { PntSortDirection, PntSortInfo, PntTableColumn, PntTableProps, PntTableStatus } from './types';
+export declare function cycleSort(currentField: string | null, currentDir: PntSortDirection | undefined, targetField: string): {
+    field: string;
+    direction: PntSortDirection;
+} | null;
+export declare function clampPage(page: number, total: number, pageSize: number): number;
+export declare function validateJumpPage(page: number, total: number, pageSize: number): string | null;
+export declare function validateColumnConflicts(columns: PntTableColumn[]): string[];
+export interface UseTableCoreResult {
+    data: any[];
+    total: number;
+    status: PntTableStatus;
+    error: string | null;
+    sort: PntSortInfo | null;
+    appliedFilters: Record<string, any>;
+    page: number;
+    pageSize: number;
+    selection: string[];
+    requestId: number;
+    toggleSort: (field: string) => void;
+    applyFilters: (filters: Record<string, any>) => void;
+    resetFilters: () => void;
+    setPage: (page: number) => void;
+    setPageSize: (size: number) => void;
+    toggleRow: (rowKey: string, selected: boolean) => void;
+    selectAllOnPage: (rowKeys: string[], disabledKeys: string[]) => void;
+    clearSelection: () => void;
+    refresh: () => void;
+    isAllSelectedOnPage: (rowKeys: string[], disabledKeys: string[]) => boolean;
+    isIndeterminateOnPage: (rowKeys: string[], disabledKeys: string[]) => boolean;
+}
+export declare function useTableCore(props: Pick<PntTableProps, 'tableId' | 'rowKey' | 'columns' | 'dataMode' | 'fetcher' | 'data' | 'initialPage' | 'pageSize' | 'pageSizeOptions' | 'businessId' | 'env' | 'timezone' | 'onQueryChange' | 'onSelectionChange' | 'selectable' | 'currentPageOnly' | 'total'>): UseTableCoreResult;