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

package/lib/esm/components/PntRegionSelect/types.d.ts

@@ -0,0 +1,181 @@
+/// <reference types="react" />
+/**
+ * 地区选项数据结构（统一格式）
+ */
+export interface RegionOption {
+    /** 地区代码（唯一标识，如 'CN'、'HK'） */
+    region_code: string;
+    /** 中文名称 */
+    region_ch: string;
+    /** 英文名称 */
+    region_en: string;
+    /** ISO 3166-1 alpha-2 代码 */
+    region_a2_code?: string;
+    /** ISO 3166-1 alpha-3 代码 */
+    region_a3_code?: string;
+    /** 是否禁用（合规区域 creatable=false 时使用） */
+    disabled?: boolean;
+    /** 禁用原因提示 */
+    disabledReason?: string;
+}
+/**
+ * 数据源类型
+ * - default: 全部国家区域（不带任何参数，返回全部 251 个）/api/v5/business/region/query
+ * - business: 业务最终生效的区域（必须传 gameId）/api/v5/business/region/query
+ */
+export type RegionDataSource = 'default' | 'business';
+/**
+ * 标签格式
+ * - name: 中文名
+ * - name_en: 英文名
+ * - name_en_name: 英文名（中文名）
+ * - code: 仅代码
+ */
+export type RegionLabelFormat = 'name' | 'name_en' | 'name_en_name' | 'code';
+/**
+ * 组件文案集合
+ */
+export interface PntRegionSelectTexts {
+    /** 占位提示 */
+    placeholder?: string;
+    /** 全选按钮 */
+    selectAll?: string;
+    /** 反选按钮 */
+    invertSelection?: string;
+    /** 清空按钮 */
+    clearAll?: string;
+    /** 已选数量提示（{count} 为占位符） */
+    selectedCount?: string;
+    /** 搜索无结果提示 */
+    noResult?: string;
+    /** 加载中提示 */
+    loading?: string;
+    /** 批量导入按钮 */
+    importBtn?: string;
+    /** 批量导入弹窗标题 */
+    importTitle?: string;
+    /** 批量导入弹窗说明 */
+    importTip?: string;
+    /** 批量导入输入框占位 */
+    importPlaceholder?: string;
+    /** 解析按钮 */
+    parseBtn?: string;
+    /** 导入确认按钮 */
+    importConfirmBtn?: string;
+    /** 取消按钮 */
+    cancelBtn?: string;
+    /** 解析结果：未匹配 */
+    importUnmatched?: string;
+    /** 解析结果：待导入 */
+    importPending?: string;
+    /** 解析结果：已存在 */
+    importExists?: string;
+    /** 复制未匹配项提示 */
+    copyUnmatchedTip?: string;
+    /** 复制成功提示 */
+    copySuccess?: string;
+    /** 解析结果表格：地区列 */
+    importRegionColumn?: string;
+    /** 解析结果表格：状态列 */
+    importStatusColumn?: string;
+}
+export declare const DEFAULT_TEXTS: Required<PntRegionSelectTexts>;
+/** 英文文案（locale='en' 时使用） */
+export declare const EN_TEXTS: Required<PntRegionSelectTexts>;
+/** 根据 locale 获取默认文案 */
+export declare const getTextsByLocale: (locale: 'zh' | 'en') => Required<PntRegionSelectTexts>;
+/**
+ * 地区选择器组件 Props
+ */
+export interface PntRegionSelectProps {
+    /**
+     * 当前选中值：多选为地区代码数组，单选为单个地区代码
+     * （兼容 TDesign FormItem 注入的单值/多值）
+     */
+    value?: string | string[];
+    /**
+     * 值变化回调：多选时回传 (string[], RegionOption[])，
+     * 单选时回传 (string, RegionOption)
+     */
+    onChange?: (value: string[] | string, options: RegionOption[] | RegionOption) => void;
+    /** 是否多选 @default true */
+    multiple?: boolean;
+    /** 数据源类型 @default 'default' */
+    dataSource?: RegionDataSource;
+    /**
+     * 接口作用域 @default 'business'
+     * - business: 业务级区域查询 /api/v5/business/region/query
+     * - platform: 平台级区域查询 /api/v5/business/region/plat-query
+     */
+    scope?: 'business' | 'platform';
+    /** 业务ID（dataSource='business' 时必传） */
+    gameId?: string | number;
+    /**
+     * 语言设置 @default 'zh'
+     * - zh: 中文（默认文案）
+     * - en: 英文（内置英文文案）
+     * @description 优先级低于 texts prop，高于 PntProvider 全局 locale
+     */
+    locale?: 'zh' | 'en';
+    /**
+     * 外部受控选项列表（传入后跳过内部请求，直接使用该数据；
+     * 适用于选项由父组件获取/过滤的场景）
+     */
+    options?: RegionOption[];
+    /** 是否禁用 @default false */
+    disabled?: boolean;
+    /** 占位文案 */
+    placeholder?: string;
+    /** 最大可选数量（多选时生效） */
+    max?: number;
+    /** 是否可搜索 @default true */
+    filterable?: boolean;
+    /** 标签格式 @default 'name' */
+    labelFormat?: RegionLabelFormat;
+    /** 自定义文案 */
+    texts?: PntRegionSelectTexts;
+    /** 数据加载完成回调 */
+    onLoaded?: (options: RegionOption[]) => void;
+    /** 自定义选项禁用逻辑 */
+    optionDisabled?: (item: RegionOption) => boolean;
+    /** 自定义选项过滤逻辑（内部拉取数据时生效，用于只展示部分区域） */
+    optionFilter?: (item: RegionOption) => boolean;
+    /** 自定义选项 tooltip */
+    optionTooltip?: (item: RegionOption) => string;
+    /**
+     * 是否启用批量导入（仅多选时生效）：
+     * 输入框右侧显示导入按钮，支持粘贴文本按 代码/中文名/英文名 解析匹配
+     * @default false
+     */
+    importable?: boolean;
+    /** 是否在工具栏显示反选按钮（仅多选时生效） @default false */
+    invertible?: boolean;
+    /** 最小折叠数量（多选时透传 TDesign Select） */
+    minCollapsedNum?: number;
+    /** 折叠项自定义渲染（透传 TDesign Select） */
+    collapsedItems?: (props: {
+        value: unknown[];
+        collapsedSelectedItems: unknown[];
+        count: number;
+    }) => React.ReactNode;
+    /** 失焦回调（透传 TDesign Select，常用于表单校验触发） */
+    onBlur?: (context: {
+        value: unknown;
+    }) => void;
+    /** 批量导入弹窗属性透传（如 attach 挂载容器） */
+    importDialogProps?: Record<string, unknown>;
+    /** 自定义类名 */
+    className?: string;
+    /** 自定义样式 */
+    style?: React.CSSProperties;
+    /** 弹层属性透传 */
+    popupProps?: Record<string, unknown>;
+    /**
+     * 对外输出是否保留数据源原始码（含前导零，如 '004'）
+     * - true（默认）: 输出数据源原始码，如 '004'、'012'
+     * - false: 输出归一化码（去前导零），如 '4'、'12'
+     * @description 旧接口存储/提交不带前导零的项目需设为 false
+     * @default true
+     */
+    preserveLeadingZero?: boolean;
+}

package/lib/esm/components/PntRegionSelect/types.js

@@ -0,0 +1,77 @@
+/**
+ * 地区选项数据结构（统一格式）
+ */
+
+/**
+ * 数据源类型
+ * - default: 全部国家区域（不带任何参数，返回全部 251 个）/api/v5/business/region/query
+ * - business: 业务最终生效的区域（必须传 gameId）/api/v5/business/region/query
+ */
+
+/**
+ * 标签格式
+ * - name: 中文名
+ * - name_en: 英文名
+ * - name_en_name: 英文名（中文名）
+ * - code: 仅代码
+ */
+
+/**
+ * 组件文案集合
+ */
+
+export const DEFAULT_TEXTS = {
+  placeholder: '请选择国家/地区',
+  selectAll: '全选',
+  invertSelection: '反选',
+  clearAll: '清空',
+  selectedCount: '已选 {count} 项',
+  noResult: '未找到匹配的地区',
+  loading: '加载中...',
+  importBtn: '批量导入',
+  importTitle: '批量导入国家/地区',
+  importTip: '支持输入地区代码、中文名或英文名，多个地区以换行、逗号或分号分隔',
+  importPlaceholder: '请输入地区代码、中文名或英文名',
+  parseBtn: '解析',
+  importConfirmBtn: '导入',
+  cancelBtn: '取消',
+  importUnmatched: '未匹配',
+  importPending: '待导入',
+  importExists: '已存在',
+  copyUnmatchedTip: '复制未匹配项',
+  copySuccess: '复制成功',
+  importRegionColumn: '地区',
+  importStatusColumn: '状态'
+};
+
+/** 英文文案（locale='en' 时使用） */
+export const EN_TEXTS = {
+  placeholder: 'Please select country/region',
+  selectAll: 'Select All',
+  invertSelection: 'Invert',
+  clearAll: 'Clear',
+  selectedCount: 'Selected {count} item(s)',
+  noResult: 'No matching region found',
+  loading: 'Loading...',
+  importBtn: 'Batch Import',
+  importTitle: 'Batch Import Country/Region',
+  importTip: 'Supports region codes, Chinese names or English names, separated by line breaks, commas or semicolons',
+  importPlaceholder: 'Enter region codes, Chinese names or English names',
+  parseBtn: 'Parse',
+  importConfirmBtn: 'Import',
+  cancelBtn: 'Cancel',
+  importUnmatched: 'Unmatched',
+  importPending: 'Pending',
+  importExists: 'Existed',
+  copyUnmatchedTip: 'Copy unmatched items',
+  copySuccess: 'Copied successfully',
+  importRegionColumn: 'Region',
+  importStatusColumn: 'Status'
+};
+
+/** 根据 locale 获取默认文案 */
+export const getTextsByLocale = locale => locale === 'en' ? EN_TEXTS : DEFAULT_TEXTS;
+
+/**
+ * 地区选择器组件 Props
+ */

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

@@ -0,0 +1,122 @@
+import React, { FC } from 'react';
+import './index.scss';
+interface PntSecureBoxProps {
+    /**
+     * 高敏信息的唯一标识 key
+     * @description 用于标识和存储特定的高敏数据项
+     */
+    dataKey: string;
+    /**
+     * 高敏信息的实际值
+     * @description 初始显示的值，通常为脱敏后的数据
+     */
+    dataValue: string;
+    /**
+     * 环境标识
+     * @description 用于区分不同环境（如：dev, test, production）；可缺省，默认 0
+     */
+    env?: string | number;
+    /**
+     * 游戏 ID
+     * @description 标识具体的游戏项目
+     */
+    gameId: string | number;
+    /**
+     * 自定义渲染函数
+     * @description 接收处理后的数据作为参数，返回需要渲染的 React 元素
+     * @param content - 处理后的数据内容（真实数据或脱敏数据）
+     * @returns React 元素
+     */
+    renderDom: (content: string) => React.ReactNode;
+    /**
+     * 自定义查看按钮文案
+     * @description 用于适配多语言场景，默认为 'View'
+     */
+    viewText?: string;
+    /**
+     * 页面 ID
+     * @description 用于记录操作日志和权限验证
+     */
+    pageId?: string;
+    /**
+     * 明文是否也掩码显示
+     * @description
+     * - false（默认）：非加密值直接展示原值
+     * - true：非加密值也展示 ******，点击后本地揭示（不调接口，防窥屏）
+     */
+    maskPlain?: boolean;
+    /**
+     * 接口变体
+     * @description
+     * - 'business'（默认）：业务级，走 /v3/business/game_info/high-security-decrypt
+     * - 'platform'：平台级（发布记录页等场景），走 /v3/business/game_info/plat-high-security-decrypt
+     */
+    scope?: 'business' | 'platform';
+    /**
+     * 解锁后是否显示复制按钮
+     * @description 默认 true，解锁后按钮文案切换为「复制」；传 false 则解锁后按钮消失（旧行为）
+     */
+    copyable?: boolean;
+    /**
+     * 复制按钮文案
+     * @description 用于适配多语言场景，默认为 'Copy'
+     */
+    copyText?: string;
+    /**
+     * 复制成功后的内联提示文案
+     * @description 仅在使用默认复制（未传 onCopy）时生效；
+     * 传入非空字符串后，复制成功按钮文案临时切换为该文案 2 秒；默认 'Copied'，传 '' 关闭内联提示
+     */
+    copySuccessText?: string;
+    /**
+     * 自定义复制行为
+     * @description 传入后替换默认的 navigator.clipboard.writeText；
+     * 消费方自行处理复制与反馈（此时 copySuccessText 不再生效）
+     */
+    onCopy?: (value: string) => void | Promise<void>;
+    /**
+     * securityData 变化回调
+     * @description 当 securityData 变化时触发（包括解密成功后）；
+     * 回调参数为当前 gameId+env 下的整个 securityData 对象（key 为字段名，value 为明文）；
+     * 消费方可用于同步表单字段、调试等
+     */
+    onSecurityDataChange?: (securityData: Record<string, string>) => void;
+}
+/**
+ * 高敏信息展示统一组件
+ * @description 用于统一处理和展示高敏信息，支持脱敏显示、按需获取真实数据、解锁后复制。
+ * 通过 PntProvider 注入 http 实例，对接 `/api/v3/business/game_info/high-security-decrypt`。
+ *
+ * @param {PntSecureBoxProps} props - 组件属性
+ * @param {string} props.dataKey - 高敏信息的唯一标识 key
+ * @param {string} props.dataValue - 高敏信息的实际值
+ * @param {string | number} props.env - 环境标识
+ * @param {string | number} props.gameId - 游戏 ID
+ * @param {(content: string) => React.ReactNode} props.renderDom - 自定义渲染函数
+ * @param {string} [props.viewText] - 自定义查看按钮文案
+ * @param {string} [props.pageId] - 页面 ID
+ * @param {boolean} [props.copyable=true] - 解锁后是否显示复制按钮
+ * @param {string} [props.copyText] - 复制按钮文案
+ * @param {string} [props.copySuccessText] - 复制成功内联提示文案
+ * @param {(value: string) => void | Promise<void>} [props.onCopy] - 自定义复制行为
+ *
+ * @example
+ * ```tsx
+ * import { PntSecureBox } from '@pnt-team/pnt-component-frontend';
+ *
+ * <PntSecureBox
+ *   dataKey="userPhone"
+ *   dataValue="_high_security_:AAAA...:6542"
+ *   env={2}
+ *   gameId={12345}
+ *   renderDom={(content) => <span>{content}</span>}
+ *   viewText="查看"
+ *   copyText="复制"
+ *   copySuccessText="已复制"
+ * />
+ * ```
+ *
+ * @returns {ReactElement} 高敏信息展示组件
+ */
+declare const PntSecureBox: FC<PntSecureBoxProps>;
+export default PntSecureBox;

package/lib/esm/components/PntSecureBox/index.js

@@ -0,0 +1,166 @@
+import { useHighSecurity } from "../../hooks/useHighSecurity";
+import { isSecurityData } from "../../utils";
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import "./index.scss";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Fragment as _Fragment } from "react/jsx-runtime";
+import { jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * 高敏信息展示统一组件
+ * @description 用于统一处理和展示高敏信息，支持脱敏显示、按需获取真实数据、解锁后复制。
+ * 通过 PntProvider 注入 http 实例，对接 `/api/v3/business/game_info/high-security-decrypt`。
+ *
+ * @param {PntSecureBoxProps} props - 组件属性
+ * @param {string} props.dataKey - 高敏信息的唯一标识 key
+ * @param {string} props.dataValue - 高敏信息的实际值
+ * @param {string | number} props.env - 环境标识
+ * @param {string | number} props.gameId - 游戏 ID
+ * @param {(content: string) => React.ReactNode} props.renderDom - 自定义渲染函数
+ * @param {string} [props.viewText] - 自定义查看按钮文案
+ * @param {string} [props.pageId] - 页面 ID
+ * @param {boolean} [props.copyable=true] - 解锁后是否显示复制按钮
+ * @param {string} [props.copyText] - 复制按钮文案
+ * @param {string} [props.copySuccessText] - 复制成功内联提示文案
+ * @param {(value: string) => void | Promise<void>} [props.onCopy] - 自定义复制行为
+ *
+ * @example
+ * ```tsx
+ * import { PntSecureBox } from '@pnt-team/pnt-component-frontend';
+ *
+ * <PntSecureBox
+ *   dataKey="userPhone"
+ *   dataValue="_high_security_:AAAA...:6542"
+ *   env={2}
+ *   gameId={12345}
+ *   renderDom={(content) => <span>{content}</span>}
+ *   viewText="查看"
+ *   copyText="复制"
+ *   copySuccessText="已复制"
+ * />
+ * ```
+ *
+ * @returns {ReactElement} 高敏信息展示组件
+ */
+const PntSecureBox = prop => {
+  const {
+    dataKey,
+    dataValue,
+    env,
+    gameId,
+    renderDom,
+    viewText,
+    pageId,
+    maskPlain,
+    scope,
+    copyable = true,
+    copyText,
+    copySuccessText = 'Copied',
+    onCopy,
+    onSecurityDataChange
+  } = prop;
+
+  // 缓存读写用的 key：dataKey + 密文后 16 位指纹
+  // 避免不同子渠道使用相同 dataKey（如 "app_key"）但密文不同时缓存冲突
+  const storeKey = isSecurityData(dataValue) ? `${dataKey}#${dataValue.slice(-16)}` : dataKey;
+
+  // 通过 PntProvider 注入的 http 实例请求高敏数据，缓存按 gameId+env 隔离
+  const {
+    securityData,
+    isUnlocked,
+    requestSecurityData
+  } = useHighSecurity({
+    gameId,
+    env,
+    scope
+  });
+
+  // 明文揭示状态（maskPlain 模式下使用，本地 state，不调接口）
+  const [plainViewed, setPlainViewed] = useState(false);
+  // 复制成功内联反馈状态
+  const [copied, setCopied] = useState(false);
+  const copyTimer = useRef(null);
+
+  // 卸载时清理定时器
+  useEffect(() => {
+    return () => {
+      if (copyTimer.current) clearTimeout(copyTimer.current);
+    };
+  }, []);
+  const isSecurity = isSecurityData(dataValue);
+  const unlocked = isSecurity ? isUnlocked(storeKey) : maskPlain ? plainViewed : true;
+  const displayValue = unlocked ? isSecurity ? securityData[storeKey] || '******' : dataValue : '******';
+
+  // securityData 变化时回调，把整个对象抛给消费方
+  useEffect(() => {
+    if (!onSecurityDataChange) return;
+    // 0.0.130 起 storeKey 含密文指纹（dataKey#tail16），内部缓存键不再是纯 dataKey；
+    // 按本 prop 文档契约（key 为字段名），这里把自身条目以原始 dataKey 补一份别名，
+    // 保证消费方 securityData[dataKey] 能取到明文（同 dataKey 多密文时以后解锁的为准）
+    const ownValue = securityData[storeKey];
+    const payload = ownValue !== undefined && securityData[dataKey] !== ownValue ? {
+      ...securityData,
+      [dataKey]: ownValue
+    } : securityData;
+    onSecurityDataChange(payload);
+  }, [securityData, onSecurityDataChange, storeKey, dataKey]);
+  const handleView = () => {
+    if (isSecurity) {
+      requestSecurityData({
+        env,
+        gameId,
+        pageId,
+        forceRefresh: true,
+        param: [{
+          key: dataKey,
+          value: dataValue,
+          cacheKey: storeKey
+        }]
+      });
+    } else if (maskPlain) {
+      setPlainViewed(true);
+    }
+  };
+  const handleCopy = useCallback(async () => {
+    // 待复制的明文值
+    const value = unlocked ? isSecurity ? securityData[storeKey] || '' : dataValue : '';
+    if (onCopy) {
+      await onCopy(value);
+      return;
+    }
+    try {
+      await navigator.clipboard.writeText(value);
+      if (copySuccessText) {
+        if (copyTimer.current) clearTimeout(copyTimer.current);
+        setCopied(true);
+        copyTimer.current = setTimeout(() => setCopied(false), 2000);
+      }
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.warn('[pnt-component-frontend] 复制失败', err);
+    }
+  }, [unlocked, isSecurity, securityData, storeKey, dataValue, onCopy, copySuccessText]);
+
+  // 渲染逻辑：
+  // 1. 敏感数据未解锁：显示查看按钮（viewText）
+  // 2. 敏感数据已解锁 + copyable：显示复制按钮（copyText），复制成功临时显示 copySuccessText
+  // 3. 敏感数据已解锁 + !copyable：不显示按钮（旧行为）
+  // 4. 普通明文（非敏感）：无任何按钮
+  const isSensitive = isSecurity || !!maskPlain;
+  const showViewBtn = !unlocked;
+  const showCopyBtn = unlocked && isSensitive && copyable;
+  return /*#__PURE__*/_jsx("div", {
+    className: "pnt-secure-box",
+    children: /*#__PURE__*/_jsxs(_Fragment, {
+      children: [renderDom(displayValue), showViewBtn && /*#__PURE__*/_jsx("span", {
+        className: "view-icon",
+        onClick: handleView,
+        children: viewText || 'View'
+      }), showCopyBtn && /*#__PURE__*/_jsx("span", {
+        className: "copy-icon",
+        onClick: handleCopy,
+        children: copied && copySuccessText ? copySuccessText : copyText || 'Copy'
+      })]
+    })
+  });
+};
+export default PntSecureBox;

package/lib/esm/components/PntSecureBox/index.scss

@@ -0,0 +1,23 @@
+.pnt-secure-box {
+  position: relative;
+  color: #333;
+  max-width: fit-content;
+
+  .view-icon,
+  .copy-icon {
+    position: absolute;
+    top: 1px;
+    right: -30px;
+    color: #3f8cff !important;
+    cursor: pointer;
+    font-size: small;
+  }
+  .copy-icon {
+    right: -50px;
+  }
+
+  .security-value {
+    position: relative;
+    top: 3px;
+  }
+}

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

@@ -0,0 +1,14 @@
+/**
+ * PntTable — 统一表格组件
+ *
+ * 封装 tdesign-react Table，落地产品规范 12 章 47 条规则：
+ *   排序三态循环、筛选草稿/生效分离、多选三态+翻页清空、分页越界校验、
+ *   请求顺序控制、7 种状态管理、蓝紫双主题、同字段 sort+headerFilter 互斥。
+ *
+ * 零业务侵入：业务项目通过 fetcher 注入数据源，不依赖组件库内部 API。
+ */
+/// <reference types="react" />
+import './index.scss';
+import type { PntTableProps, PntTableRef } from './types';
+export declare const PntTable: import("react").ForwardRefExoticComponent<PntTableProps & import("react").RefAttributes<PntTableRef>>;
+export default PntTable;