@pnt-team/pnt-component-frontend 0.0.138 → 0.0.140

package/lib/esm/components/PntTable/useTableCore.js

@@ -0,0 +1,499 @@
+/**
+ * useTableCore — PntTable 核心逻辑
+ *
+ * 负责：请求顺序控制、排序三态、筛选草稿/生效分离、多选三态、分页越界校验、7 种状态管理。
+ * 纯 React Hook，不依赖 TDesign DOM，方便单测和版本降级。
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+// ============================================================
+// 内部类型
+// ============================================================
+
+// ============================================================
+// 请求顺序控制
+// ============================================================
+
+class RequestManager {
+  requestIdCounter = 0;
+  abortController = null;
+  nextId() {
+    // 取消上一请求
+    if (this.abortController) {
+      try {
+        this.abortController.abort();
+      } catch {
+        /* noop */
+      }
+    }
+    this.abortController = new AbortController();
+    return ++this.requestIdCounter;
+  }
+  isLatest(id) {
+    return id === this.requestIdCounter;
+  }
+  abortCurrent() {
+    if (this.abortController) {
+      try {
+        this.abortController.abort();
+      } catch {
+        /* noop */
+      }
+      this.abortController = null;
+    }
+  }
+}
+
+// ============================================================
+// 排序三态循环（TBL-04.01）
+// ============================================================
+
+export function cycleSort(currentField, currentDir, targetField) {
+  if (currentField !== targetField) {
+    // 切换字段：从升序开始，清上一列
+    return {
+      field: targetField,
+      direction: 'asc'
+    };
+  }
+  // 同字段：三态循环
+  if (currentDir === undefined || currentDir === null) return {
+    field: targetField,
+    direction: 'asc'
+  };
+  if (currentDir === 'asc') return {
+    field: targetField,
+    direction: 'desc'
+  };
+  // 第三态：清除排序
+  return null;
+}
+
+// ============================================================
+// 分页越界校验（TBL-07.04）
+// ============================================================
+
+export function clampPage(page, total, pageSize) {
+  const maxPage = Math.max(1, Math.ceil(total / pageSize));
+  if (page < 1) return 1;
+  if (page > maxPage) return maxPage;
+  return page;
+}
+export function validateJumpPage(page, total, pageSize) {
+  const maxPage = Math.max(1, Math.ceil(total / pageSize));
+  if (!Number.isInteger(page) || page < 1 || page > maxPage) {
+    return `请输入 1–${maxPage} 的整数页码`;
+  }
+  return null;
+}
+
+// ============================================================
+// 互斥校验（TBL-01.03）
+// ============================================================
+
+export function validateColumnConflicts(columns) {
+  const errors = [];
+  columns.forEach(col => {
+    if (col.sort && col.headerFilter) {
+      errors.push(`[PntTable] 列 "${col.key}" 同时配置了 sort 和 headerFilter，违反 TBL-01.03 互斥规则。` + ` 如需该字段同时排序+筛选，表头保留 sort，筛选移至 externalFilter（独立查询区）。`);
+    }
+  });
+  return errors;
+}
+
+// ============================================================
+// 核心 Hook
+// ============================================================
+
+export function useTableCore(props) {
+  const {
+    tableId,
+    rowKey,
+    columns,
+    dataMode,
+    fetcher,
+    data: clientData,
+    total: clientTotal,
+    initialPage = 1,
+    pageSize: initialPageSize = 10,
+    businessId,
+    env,
+    timezone,
+    onQueryChange,
+    onSelectionChange,
+    selectable = false,
+    currentPageOnly = true
+  } = props;
+  const reqMgrRef = useRef(new RequestManager());
+  const [requestId, setRequestId] = useState(0);
+  const [state, setState] = useState(() => {
+    const initialRows = dataMode === 'client' ? clientData ?? [] : [];
+    return {
+      data: initialRows,
+      total: dataMode === 'client' ? clientTotal ?? clientData?.length ?? 0 : 0,
+      status: dataMode === 'client' ? initialRows.length === 0 ? 'empty' : 'normal' : 'loading',
+      error: null,
+      sort: null,
+      appliedFilters: {},
+      page: initialPage,
+      pageSize: initialPageSize,
+      selection: new Set()
+    };
+  });
+
+  // client 模式：props.data 变化时同步行数据，并重算空态
+  useEffect(() => {
+    if (dataMode !== 'client') return;
+    const rows = clientData ?? [];
+    setState(prev => {
+      const hasAppliedFilter = Object.values(prev.appliedFilters).some(v => v !== undefined && v !== null && v !== '');
+      return {
+        ...prev,
+        data: rows,
+        total: clientTotal ?? rows.length,
+        status: rows.length === 0 ? hasAppliedFilter ? 'empty-with-filter' : 'empty' : 'normal',
+        error: null
+      };
+    });
+  }, [dataMode, clientData, clientTotal]);
+  const setStatePartial = useCallback(patch => {
+    setState(prev => ({
+      ...prev,
+      ...patch
+    }));
+  }, []);
+
+  // ============================================================
+  // 数据获取
+  // ============================================================
+
+  const triggerFetch = useCallback(async (trigger, snapshot) => {
+    if (dataMode !== 'server' || !fetcher) return;
+    const thisReqId = reqMgrRef.current.nextId();
+    const query = {
+      query: {},
+      // 独立查询区（组件不维护，由业务项目维护并透传）
+      filters: snapshot.appliedFilters,
+      sort: snapshot.sort,
+      page: snapshot.page,
+      pageSize: snapshot.pageSize,
+      businessId,
+      env,
+      timezone
+    };
+    onQueryChange?.(query, {
+      tableId,
+      trigger,
+      requestId: thisReqId
+    });
+    setStatePartial({
+      status: snapshot.page > 1 || requestId > 0 ? 'refreshing' : 'loading'
+    });
+    try {
+      const res = await fetcher(query);
+
+      // 旧请求晚到 → 丢弃（TBL-09.06）
+      if (!reqMgrRef.current.isLatest(thisReqId)) return;
+      if (res.noPermission) {
+        setStatePartial({
+          status: 'no-permission',
+          error: null,
+          data: [],
+          total: 0
+        });
+        setRequestId(thisReqId);
+        return;
+      }
+      if (res.code !== undefined && res.code !== 0) {
+        // 文案由组件层按 locale/texts 兜底，core 只透传原始错误信息
+        setStatePartial({
+          status: 'error',
+          error: res.msg || ''
+        });
+        setRequestId(thisReqId);
+        return;
+      }
+      const rows = res.rows ?? [];
+      setStatePartial({
+        data: rows,
+        total: res.total ?? rows.length,
+        status: rows.length === 0 ? Object.values(snapshot.appliedFilters).some(v => v !== undefined && v !== null && v !== '') ? 'empty-with-filter' : 'empty' : 'normal',
+        error: null
+      });
+      setRequestId(thisReqId);
+    } catch (err) {
+      if (!reqMgrRef.current.isLatest(thisReqId)) return;
+      if (err?.name === 'AbortError') return;
+      setStatePartial({
+        status: 'error',
+        error: err?.message || ''
+      });
+      setRequestId(thisReqId);
+    }
+  }, [dataMode, fetcher, tableId, businessId, env, timezone, onQueryChange, requestId, setStatePartial]);
+
+  // 初始加载
+  useEffect(() => {
+    if (dataMode === 'server' && fetcher) {
+      const page = initialPage;
+      const pageSize = state.pageSize;
+      setStatePartial({
+        page,
+        pageSize
+      });
+      triggerFetch('initial', {
+        sort: null,
+        appliedFilters: {},
+        page,
+        pageSize
+      });
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [tableId, dataMode]);
+
+  // ============================================================
+  // 排序
+  // ============================================================
+
+  const toggleSort = useCallback(field => {
+    if (dataMode !== 'server') return;
+    const col = columns.find(c => c.key === field);
+    if (!col || col.sort === false) return;
+    setState(prev => {
+      const newSort = cycleSort(prev.sort?.field ?? null, prev.sort?.direction, field);
+      const clearedSelection = currentPageOnly ? new Set() : prev.selection;
+      const clearedPage = prev.sort?.field !== field ? prev.page : prev.page; // 换字段才回 1
+      const newPage = newSort ? 1 : clearedPage; // 有排序就回 1（TBL-04.05）
+
+      // 翻页/排序变更回 1 页 + 清勾选
+      const next = {
+        ...prev,
+        sort: newSort,
+        page: newPage,
+        selection: clearedSelection
+      };
+      if (newSort) {
+        triggerFetch('sort', {
+          sort: newSort,
+          appliedFilters: next.appliedFilters,
+          page: newPage,
+          pageSize: next.pageSize
+        });
+      } else if (prev.sort) {
+        // 第三态清除排序
+        triggerFetch('sort', {
+          sort: null,
+          appliedFilters: next.appliedFilters,
+          page: newPage,
+          pageSize: next.pageSize
+        });
+      }
+      return next;
+    });
+  }, [dataMode, columns, triggerFetch, currentPageOnly]);
+
+  // ============================================================
+  // 筛选（草稿/生效分离）
+  // ============================================================
+
+  const applyFilters = useCallback(filters => {
+    // 归一化：空多选归一为不限（TBL-05.03）
+    const normalized = {};
+    Object.entries(filters).forEach(([k, v]) => {
+      if (Array.isArray(v) && v.length === 0) return;
+      if (v === undefined || v === null || v === '') return;
+      normalized[k] = v;
+    });
+    setState(prev => {
+      const clearedSelection = currentPageOnly ? new Set() : prev.selection;
+      const next = {
+        ...prev,
+        appliedFilters: normalized,
+        page: 1,
+        // 筛选变更回 1 页（TBL-04.05）
+        selection: clearedSelection
+      };
+      triggerFetch('filter', {
+        sort: next.sort,
+        appliedFilters: normalized,
+        page: 1,
+        pageSize: next.pageSize
+      });
+      return next;
+    });
+  }, [triggerFetch, currentPageOnly]);
+  const resetFilters = useCallback(() => {
+    setState(prev => {
+      const clearedSelection = currentPageOnly ? new Set() : prev.selection;
+      const next = {
+        ...prev,
+        appliedFilters: {},
+        page: 1,
+        selection: clearedSelection
+      };
+      triggerFetch('reset', {
+        sort: next.sort,
+        appliedFilters: {},
+        page: 1,
+        pageSize: next.pageSize
+      });
+      return next;
+    });
+  }, [triggerFetch, currentPageOnly]);
+
+  // ============================================================
+  // 分页
+  // ============================================================
+
+  const setPage = useCallback(page => {
+    if (dataMode !== 'server') return;
+    setState(prev => {
+      const validated = clampPage(page, prev.total, prev.pageSize);
+      if (validated === prev.page) return prev;
+      const clearedSelection = currentPageOnly ? new Set() : prev.selection;
+      const next = {
+        ...prev,
+        page: validated,
+        selection: clearedSelection
+      };
+      triggerFetch('pagination', {
+        sort: next.sort,
+        appliedFilters: next.appliedFilters,
+        page: validated,
+        pageSize: next.pageSize
+      });
+      return next;
+    });
+  }, [dataMode, triggerFetch, currentPageOnly]);
+  const setPageSize = useCallback(size => {
+    if (dataMode !== 'server') return;
+    setState(prev => {
+      if (size === prev.pageSize) return prev;
+      const clearedSelection = currentPageOnly ? new Set() : prev.selection;
+      // pageSize 变更回 1 页（TBL-07.02）
+      const next = {
+        ...prev,
+        pageSize: size,
+        page: 1,
+        selection: clearedSelection
+      };
+      triggerFetch('page-size', {
+        sort: next.sort,
+        appliedFilters: next.appliedFilters,
+        page: 1,
+        pageSize: size
+      });
+      return next;
+    });
+  }, [dataMode, triggerFetch, currentPageOnly]);
+
+  // ============================================================
+  // 多选（三态）
+  // ============================================================
+
+  const toggleRow = useCallback((key, selected) => {
+    if (!selectable) return;
+    setState(prev => {
+      const next = new Set(prev.selection);
+      if (selected) next.add(key);else next.delete(key);
+      const selArr = Array.from(next);
+      onSelectionChange?.(selArr, {
+        tableId,
+        pageKeys: prev.data.map(r => String(r[rowKey])),
+        disabledKeys: [],
+        trigger: 'select'
+      });
+      return {
+        ...prev,
+        selection: next
+      };
+    });
+  }, [selectable, onSelectionChange, tableId, rowKey]);
+  const selectAllOnPage = useCallback((rowKeys, disabledKeys) => {
+    if (!selectable) return;
+    const selectableKeys = rowKeys.filter(k => !disabledKeys.includes(k));
+    setState(prev => {
+      const allSelected = selectableKeys.every(k => prev.selection.has(k));
+      const next = new Set(prev.selection);
+      if (allSelected) {
+        selectableKeys.forEach(k => next.delete(k));
+      } else {
+        selectableKeys.forEach(k => next.add(k));
+      }
+      const selArr = Array.from(next);
+      onSelectionChange?.(selArr, {
+        tableId,
+        pageKeys: rowKeys,
+        disabledKeys,
+        trigger: allSelected ? 'select-all' : 'select-all'
+      });
+      return {
+        ...prev,
+        selection: next
+      };
+    });
+  }, [selectable, onSelectionChange, tableId]);
+  const clearSelection = useCallback(() => {
+    setState(prev => ({
+      ...prev,
+      selection: new Set()
+    }));
+    onSelectionChange?.([], {
+      tableId,
+      pageKeys: [],
+      disabledKeys: [],
+      trigger: 'reset'
+    });
+  }, [onSelectionChange, tableId]);
+  const isAllSelectedOnPage = useCallback((rowKeys, disabledKeys) => {
+    const selectableKeys = rowKeys.filter(k => !disabledKeys.includes(k));
+    if (selectableKeys.length === 0) return false;
+    return selectableKeys.every(k => state.selection.has(k));
+  }, [state.selection]);
+  const isIndeterminateOnPage = useCallback((rowKeys, disabledKeys) => {
+    const selectableKeys = rowKeys.filter(k => !disabledKeys.includes(k));
+    if (selectableKeys.length === 0) return false;
+    const selectedCount = selectableKeys.filter(k => state.selection.has(k)).length;
+    return selectedCount > 0 && selectedCount < selectableKeys.length;
+  }, [state.selection]);
+  const refresh = useCallback(() => {
+    setState(prev => {
+      const clearedSelection = currentPageOnly ? new Set() : prev.selection;
+      const next = {
+        ...prev,
+        selection: clearedSelection
+      };
+      triggerFetch('reset', {
+        sort: next.sort,
+        appliedFilters: next.appliedFilters,
+        page: next.page,
+        pageSize: next.pageSize
+      });
+      return next;
+    });
+  }, [triggerFetch, currentPageOnly]);
+  return useMemo(() => ({
+    data: state.data,
+    total: state.total,
+    status: state.status,
+    error: state.error,
+    sort: state.sort,
+    appliedFilters: state.appliedFilters,
+    page: state.page,
+    pageSize: state.pageSize,
+    selection: Array.from(state.selection),
+    requestId,
+    toggleSort,
+    applyFilters,
+    resetFilters,
+    setPage,
+    setPageSize,
+    toggleRow,
+    selectAllOnPage,
+    clearSelection,
+    refresh,
+    isAllSelectedOnPage,
+    isIndeterminateOnPage
+  }), [state, requestId, toggleSort, applyFilters, resetFilters, setPage, setPageSize, toggleRow, selectAllOnPage, clearSelection, refresh, isAllSelectedOnPage, isIndeterminateOnPage]);
+}

package/lib/esm/components/PntUpload/index.d.ts

@@ -0,0 +1,149 @@
+import type { CosScene } from "../../api/cos";
+import type { FileNameStrategy, PntCosUploadOptions } from "../PntCosUploader";
+import React, { FC } from 'react';
+import './index.scss';
+/**
+ * PntUpload 文案集合
+ * @description 所有内部展示文案均可通过 texts prop 自定义，用于多语言场景
+ */
+export interface PntUploadTexts {
+    /** 上传中文案 */
+    uploading?: string;
+    /** 上传失败文案 */
+    uploadFailed?: string;
+    /** 文件大小超出限制文案 */
+    sizeInvalid?: string;
+    /** 文件类型不支持文案 */
+    typeInvalid?: string;
+    /** 选择文件文案（无文件时） */
+    selectFile?: string;
+    /** 重新选择文案（已有文件时，非图片模式） */
+    reselect?: string;
+}
+/**
+ * 校验/上传失败阶段
+ */
+export type PntUploadErrorPhase = 'validate' | 'upload';
+export interface PntUploadProps {
+    /**
+     * 当前已上传文件 URL（受控）
+     */
+    value?: string;
+    /**
+     * 上传成功回调
+     * @param fileUrl 上传后的可访问 URL
+     * @param cosKey COS 对象 Key
+     * @param file 原始文件
+     */
+    onChange?: (fileUrl: string, cosKey: string, file: File) => void;
+    /**
+     * 删除回调
+     * @description 由消费方清空 value
+     */
+    onRemove?: () => void;
+    /**
+     * 异常回调（校验失败 / 上传失败）
+     * @param err 错误对象（校验失败时 message 为对应文案）
+     * @param phase 失败阶段：validate=本地校验，upload=凭证获取或 COS 上传
+     * @param file 原始文件
+     */
+    onError?: (err: Error, phase: PntUploadErrorPhase, file: File) => void;
+    /**
+     * 业务场景（透传给 PntCosUploader）
+     */
+    scene: CosScene;
+    /**
+     * 业务类型路径 key（透传给 PntCosUploader）
+     */
+    pathKey?: string;
+    /**
+     * 业务上下文（透传给 PntCosUploader）
+     */
+    context?: Record<string, string | number>;
+    /**
+     * 网关 audience（透传给 PntCosUploader）
+     * @default '/player-network'
+     */
+    audience?: string;
+    /**
+     * 文件类型限制
+     * @description 支持 MIME（'image/png'）、通配（'image/*'）、扩展名（'.zip'），可传数组
+     */
+    accept?: string | string[];
+    /**
+     * 文件大小限制（字节）
+     */
+    sizeLimit?: number;
+    /**
+     * 是否为图片预览模式
+     * @description true 使用 PntImage 预览；false 使用文件名 + 选择区域
+     * @default true
+     */
+    imagePreview?: boolean;
+    /**
+     * 图片预览区样式（imagePreview=true 生效，一般控制宽高）
+     */
+    previewStyle?: React.CSSProperties;
+    /**
+     * 默认占位图（imagePreview=true 生效）
+     */
+    defaultImg?: string;
+    /**
+     * 文件名生成策略（透传给 PntCosUploader）
+     * @default 'uuid'
+     */
+    fileNameStrategy?: FileNameStrategy;
+    /**
+     * 是否走 CDN 域名拼接（透传给 PntCosUploader）
+     * @default true
+     */
+    useCdn?: boolean;
+    /**
+     * 自定义凭证获取函数（透传给 PntCosUploader）
+     */
+    getCredential?: PntCosUploadOptions['getCredential'];
+    /**
+     * 自定义凭证响应归一化（透传给 PntCosUploader）
+     */
+    normalizeCredential?: PntCosUploadOptions['normalizeCredential'];
+    /**
+     * 多语言文案
+     * @description 传入即覆盖默认中文文案；仅对应字段会覆盖，未传字段仍用默认值
+     */
+    texts?: PntUploadTexts;
+    /**
+     * 禁用上传与删除
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * 自定义样式
+     */
+    style?: React.CSSProperties;
+    /**
+     * 自定义类名
+     */
+    className?: string;
+}
+/**
+ * PntUpload 业务上传组件
+ * @description 基于 TDesign Upload + PntImage + usePntCosUploader，
+ * 内置 COS 凭证获取、直传、进度、校验、错误处理；支持图片预览 / 文件两种模式
+ *
+ * @example
+ * ```tsx
+ * <PntUpload
+ *   scene="default"
+ *   pathKey="marketing_icon"
+ *   context={{ gameId }}
+ *   accept="image/png"
+ *   sizeLimit={500 * 1024}
+ *   imagePreview
+ *   value={iconUrl}
+ *   onChange={(url) => setIconUrl(url)}
+ *   onRemove={() => setIconUrl('')}
+ * />
+ * ```
+ */
+declare const PntUpload: FC<PntUploadProps>;
+export default PntUpload;