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

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

@@ -0,0 +1,27 @@
+.pnt-business-select {
+  width: 100%;
+}
+
+.pnt-business-select-option-label {
+  display: block;
+  width: 100%;
+}
+
+/* 弹层内容样式：loading / total-wrapper 统一高度与排版 */
+.pnt-business-select-popup {
+  .t-popup__content {
+    .total-wrapper,
+    .t-loading {
+      height: 36px;
+      font-weight: 400;
+      line-height: 20px;
+      display: flex;
+      align-items: center;
+      padding: 0 14px;
+    }
+    .total-wrapper {
+      color: #808191;
+      font-size: 14px;
+    }
+  }
+}

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

@@ -0,0 +1,134 @@
+import { type CosScene, type GetCosCredentialParams, type NormalizeCredential, type NormalizedCosCredential } from "../../api/cos";
+import { usePntConfig, type PntHttpLike } from "../../config";
+/**
+ * 文件名生成策略
+ * @description 内置三种策略；如需自定义可传函数
+ * - uuid: UUID v4 + 原扩展名（默认，最简单）
+ * - md5: 文件内容 MD5 + 原扩展名（与 pnt-tools CosApi 原策略一致）
+ * - timestamp: 时间戳(36进制)+自增计数器 + 原扩展名（与 SDK 定制场景原策略一致）
+ */
+export type FileNameStrategy = 'uuid' | 'md5' | 'timestamp' | ((file: File) => string | Promise<string>);
+/**
+ * COS 上传配置
+ */
+export interface PntCosUploadOptions {
+    /**
+     * 业务场景，决定走哪个凭证接口
+     * @description 内置 4 个 scene，消费方可传 string 自定义并配合 getCredential 使用
+     */
+    scene: CosScene;
+    /**
+     * 业务类型路径 key
+     * @description 通用场景透传给后端 path map 选取对应业务路径；
+     * sdk_customize 场景作为受控目录（filePath）下的子目录继续拼接
+     */
+    pathKey?: string;
+    /**
+     * 业务上下文参数（gameId/env/updType 等）
+     * @description 按 scene 不同传递给后端；default/default_download 下 gameId 自动映射到 x-service-type 请求头
+     */
+    context?: Record<string, string | number>;
+    /**
+     * 网关 audience
+     * @default '/player-network'
+     * @description 账号管理等子系统需覆盖为对应 audience（如 '/laas-pnt'）
+     */
+    audience?: string;
+    /**
+     * 文件名生成策略
+     * @default 'uuid'
+     */
+    fileNameStrategy?: FileNameStrategy;
+    /**
+     * 是否走 CDN 域名拼接
+     * @description true 且凭证返回 cosHost 时用 cosHost + cosKey；否则用 COS putObject 返回的 Location
+     * @default true
+     */
+    useCdn?: boolean;
+    /**
+     * 自定义凭证获取函数（覆盖内置 scene 路由）
+     * @description 后端接口非内置 scene 时使用；返回归一化后的凭证
+     */
+    getCredential?: (http: ReturnType<typeof usePntConfig>['http'], params: GetCosCredentialParams) => Promise<NormalizedCosCredential>;
+    /**
+     * 自定义凭证响应归一化
+     * @description 后端字段不标准时使用；入参为内置 scene 接口返回的原始 data，需返回归一化凭证
+     */
+    normalizeCredential?: NormalizeCredential;
+}
+/**
+ * COS 上传结果
+ */
+export interface PntCosUploadResult {
+    /** 上传后的可访问 URL */
+    fileUrl: string;
+    /** COS 对象 Key */
+    cosKey: string;
+    /** 原始文件名 */
+    fileName: string;
+}
+/**
+ * 单次请求覆盖参数
+ * @description 上传/下载入口的 gameId/task_id/pathKey 常来自表单或表格行数据，
+ * 可通过该参数在单次调用覆盖 hook 初始化时的配置
+ */
+export interface PntCosRequestOverrides {
+    /** 覆盖业务上下文（与初始化 context 浅合并，如行级 gameId/task_id） */
+    context?: Record<string, string | number>;
+    /** 覆盖网关 audience */
+    audience?: string;
+    /** 覆盖凭证场景 */
+    scene?: CosScene;
+    /** 覆盖业务路径 key */
+    pathKey?: string;
+}
+/**
+ * COS 上传器实例
+ */
+export interface PntCosUploader {
+    /**
+     * 上传文件到 COS
+     * @param file 原始文件
+     * @param onProgress 上传进度回调（0~100）
+     * @param overrides 单次调用覆盖配置（表单/行级 gameId 等）
+     */
+    upload: (file: File, onProgress?: (percent: number) => void, overrides?: PntCosRequestOverrides) => Promise<PntCosUploadResult>;
+    /**
+     * 获取文件预签名下载 URL（临时）
+     * @param cosKey COS 对象 Key，或完整 URL（自动剥离域名）
+     * @param overrides 单次调用覆盖配置（行级 gameId/task_id 等）
+     */
+    getDownloadUrl: (cosKey: string, overrides?: PntCosRequestOverrides) => Promise<string>;
+}
+export type { CosScene, GetCosCredentialParams, NormalizeCredential, NormalizedCosCredential, };
+export { normalizeSnakeCredential } from "../../api/cos";
+/**
+ * 创建 COS 直传器实例（不依赖 React）
+ * @description 与 usePntCosUploader 共用同一套核心逻辑，适用于 class 兼容层、
+ * 工具函数、非 React 入口等场景；React 组件请优先使用 usePntCosUploader
+ *
+ * @param http 消费方 axios 实例（约定响应拦截器已解包 response.data）
+ * @param options 上传配置（固定值），或返回配置的 getter（需要动态配置时使用）
+ *
+ * @example
+ * ```ts
+ * const uploader = createPntCosUploader(http, { scene: 'default', pathKey: 'marketing_icon' });
+ * const { fileUrl } = await uploader.upload(file);
+ * ```
+ */
+export declare const createPntCosUploader: (http: PntHttpLike, options: PntCosUploadOptions | (() => PntCosUploadOptions)) => PntCosUploader;
+/**
+ * COS 直传 Service Hook
+ * @description 内置凭证获取 + COS SDK 初始化 + 文件名策略 + URL 拼接，
+ * 收敛各项目重复的 4 份自实现；http 实例由 PntProvider 注入
+ *
+ * @param options 上传配置
+ *
+ * @example
+ * ```ts
+ * const uploader = usePntCosUploader({ scene: 'default', pathKey: 'marketing_icon' });
+ * const { fileUrl, cosKey } = await uploader.upload(file, (p) => setProgress(p));
+ * ```
+ */
+export declare const usePntCosUploader: (options: PntCosUploadOptions) => PntCosUploader;
+export default usePntCosUploader;

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

@@ -0,0 +1,300 @@
+import { fetchCosCredential } from "../../api/cos";
+import { usePntConfig } from "../../config";
+import { useMemo, useRef } from 'react';
+import { v4 as uuidV4 } from 'uuid';
+
+// cos-js-sdk-v5 / crypto-js 改为运行时动态 import（见 createCosClient / computeFileMd5）：
+// 不用上传功能的项目无需安装这两个包，Vite/webpack 不会把动态 import 当作硬依赖解析
+
+// ==========================================
+// 类型定义
+// ==========================================
+
+/**
+ * 文件名生成策略
+ * @description 内置三种策略；如需自定义可传函数
+ * - uuid: UUID v4 + 原扩展名（默认，最简单）
+ * - md5: 文件内容 MD5 + 原扩展名（与 pnt-tools CosApi 原策略一致）
+ * - timestamp: 时间戳(36进制)+自增计数器 + 原扩展名（与 SDK 定制场景原策略一致）
+ */
+
+/**
+ * COS 上传配置
+ */
+
+/**
+ * COS 上传结果
+ */
+
+/**
+ * 单次请求覆盖参数
+ * @description 上传/下载入口的 gameId/task_id/pathKey 常来自表单或表格行数据，
+ * 可通过该参数在单次调用覆盖 hook 初始化时的配置
+ */
+
+/**
+ * COS 上传器实例
+ */
+
+export { normalizeSnakeCredential } from "../../api/cos";
+
+// ==========================================
+// 工具函数
+// ==========================================
+
+/** 去除首尾斜杠 */
+const trimSlash = (seg, leading = true) => seg.replace(/\/$/, '').replace(leading ? /^\// : '', '');
+
+/**
+ * 提取文件扩展名（含点号）
+ */
+const getFileExt = filename => {
+  const idx = filename.lastIndexOf('.');
+  return idx > -1 ? filename.slice(idx) : '';
+};
+
+/**
+ * timestamp 策略计数器（同一会话内自增，避免同毫秒碰撞）
+ */
+let _timestampCounter = 0;
+const generateTimestampName = () => `${Date.now().toString(36)}${(_timestampCounter++).toString(36)}`;
+
+/**
+ * 计算文件内容 MD5（基于 crypto-js，与 pnt-tools CosApi 原策略一致）
+ * @description crypto-js 动态 import：仅 md5 文件名策略触发时加载
+ */
+const computeFileMd5 = async file => {
+  const {
+    default: CryptoJS
+  } = await import('crypto-js');
+  const buffer = await file.arrayBuffer();
+  return CryptoJS.MD5(CryptoJS.lib.WordArray.create(buffer)).toString();
+};
+
+/**
+ * 根据策略生成文件名（不含路径前缀）
+ */
+const generateFileName = async (file, strategy) => {
+  if (typeof strategy === 'function') {
+    return strategy(file);
+  }
+  const ext = getFileExt(file.name);
+  switch (strategy) {
+    case 'md5':
+      {
+        const md5 = await computeFileMd5(file);
+        return `${md5}${ext}`;
+      }
+    case 'timestamp':
+      return `${generateTimestampName()}${ext}`;
+    case 'uuid':
+    default:
+      return `${uuidV4()}${ext}`;
+  }
+};
+
+/**
+ * 拼接 COS Key 的目录前缀
+ * @description 优先级：filePath（可继续拼 pathKey 子目录） > path[pathKey] > 空
+ */
+const resolveBasePath = (cred, pathKey) => {
+  if (cred.filePath) {
+    // sdk_customize：受控目录前缀 + 业务自定义子目录
+    const prefix = cred.filePath.replace(/\/$/, '');
+    return pathKey ? `${prefix}/${trimSlash(pathKey)}` : prefix;
+  }
+  if (pathKey && cred.path) {
+    return cred.path[pathKey] || '';
+  }
+  return '';
+};
+
+/**
+ * 从 URL 或完整 Key 中剥离域名，得到纯 COS Key
+ */
+const stripHost = key => key.replace(/^https?:\/\/[^/]+/, '');
+
+/**
+ * 用归一化凭证构造 COS SDK 实例
+ * @description cos-js-sdk-v5 动态 import：仅实际上传/下载触发时加载
+ */
+const createCosClient = async cred => {
+  const {
+    default: COS
+  } = await import('cos-js-sdk-v5');
+  return new COS({
+    getAuthorization: (_, callback) => {
+      callback({
+        TmpSecretId: cred.secretId,
+        TmpSecretKey: cred.secretKey,
+        SecurityToken: cred.sessionToken,
+        StartTime: cred.startTime,
+        ExpiredTime: cred.expiredTime
+      });
+    },
+    Protocol: 'https:',
+    FileParallelLimit: 3,
+    ChunkParallelLimit: 3,
+    ChunkSize: 1024 * 1024,
+    ProgressInterval: 1
+  });
+};
+
+// ==========================================
+// createPntCosUploader 工厂（框架无关，可在非 React 上下文使用）
+// ==========================================
+
+/**
+ * 创建 COS 直传器实例（不依赖 React）
+ * @description 与 usePntCosUploader 共用同一套核心逻辑，适用于 class 兼容层、
+ * 工具函数、非 React 入口等场景；React 组件请优先使用 usePntCosUploader
+ *
+ * @param http 消费方 axios 实例（约定响应拦截器已解包 response.data）
+ * @param options 上传配置（固定值），或返回配置的 getter（需要动态配置时使用）
+ *
+ * @example
+ * ```ts
+ * const uploader = createPntCosUploader(http, { scene: 'default', pathKey: 'marketing_icon' });
+ * const { fileUrl } = await uploader.upload(file);
+ * ```
+ */
+export const createPntCosUploader = (http, options) => {
+  const getOptions = () => typeof options === 'function' ? options() : options;
+  const upload = async (file, onProgress, overrides) => {
+    const opts = getOptions();
+    const {
+      scene,
+      pathKey,
+      context,
+      audience,
+      fileNameStrategy = 'uuid',
+      useCdn = true,
+      getCredential,
+      normalizeCredential
+    } = opts;
+    // 单次调用覆盖（表单/行级 gameId、动态 pathKey 等），context 浅合并
+    const mergedContext = {
+      ...context,
+      ...overrides?.context
+    };
+    const mergedScene = overrides?.scene ?? scene;
+    const mergedAudience = overrides?.audience ?? audience;
+    const mergedPathKey = overrides?.pathKey ?? pathKey;
+
+    // 1. 获取凭证
+    const credParams = {
+      scene: mergedScene,
+      pathKey: mergedPathKey,
+      context: mergedContext,
+      audience: mergedAudience,
+      contentLength: file.size
+    };
+    const cred = getCredential ? await getCredential(http, credParams) : await fetchCosCredential(http, credParams, normalizeCredential);
+
+    // 2. 构造 COS Key
+    const basePath = resolveBasePath(cred, mergedPathKey);
+    const fileName = await generateFileName(file, fileNameStrategy);
+    const cosKey = basePath ? `${basePath.replace(/\/$/, '')}/${fileName}` : fileName;
+
+    // 3. putObject 上传
+    const cos = await createCosClient(cred);
+    return new Promise((resolve, reject) => {
+      cos.putObject({
+        Bucket: cred.bucket,
+        Region: cred.region,
+        Key: cosKey,
+        Body: file,
+        onProgress: onProgress ? progressData => {
+          onProgress(Math.round(progressData.percent * 100));
+        } : undefined
+      }, (err, data) => {
+        if (err) {
+          reject(err);
+          return;
+        }
+        // URL 拼接：useCdn 且凭证带 cosHost 时走 CDN；否则用 COS Location
+        const fileUrl = useCdn && cred.cosHost ? `${cred.cosHost.replace(/\/$/, '')}/${cosKey}` : `https://${data.Location}`;
+        resolve({
+          fileUrl,
+          cosKey,
+          fileName: file.name
+        });
+      });
+    });
+  };
+  const getDownloadUrl = async (cosKey, overrides) => {
+    const opts = getOptions();
+    const {
+      scene,
+      pathKey,
+      context,
+      audience,
+      getCredential
+    } = opts;
+    // 单次调用覆盖（表格行级 gameId/task_id 等），context 浅合并
+    const mergedContext = {
+      ...context,
+      ...overrides?.context
+    };
+    const mergedScene = overrides?.scene ?? scene;
+    const mergedAudience = overrides?.audience ?? audience;
+    const mergedPathKey = overrides?.pathKey ?? pathKey;
+    // 下载凭证默认走 default_download 接口；sdk_customize 保持原 scene；
+    // 消费方传了 getCredential 时完全由其决定
+    const credParams = {
+      scene: getCredential ? mergedScene : mergedScene === 'sdk_customize' ? mergedScene : 'default_download',
+      pathKey: mergedPathKey,
+      context: mergedContext,
+      audience: mergedAudience,
+      fileUrl: cosKey
+    };
+    const cred = getCredential ? await getCredential(http, credParams) : await fetchCosCredential(http, credParams);
+    const cos = await createCosClient(cred);
+    return new Promise((resolve, reject) => {
+      cos.getObjectUrl({
+        Bucket: cred.bucket,
+        Region: cred.region,
+        Key: stripHost(cosKey),
+        Sign: true
+      }, (err, data) => {
+        if (err) {
+          reject(err);
+          return;
+        }
+        resolve(data.Url);
+      });
+    });
+  };
+  return {
+    upload,
+    getDownloadUrl
+  };
+};
+
+// ==========================================
+// usePntCosUploader Hook
+// ==========================================
+
+/**
+ * COS 直传 Service Hook
+ * @description 内置凭证获取 + COS SDK 初始化 + 文件名策略 + URL 拼接，
+ * 收敛各项目重复的 4 份自实现；http 实例由 PntProvider 注入
+ *
+ * @param options 上传配置
+ *
+ * @example
+ * ```ts
+ * const uploader = usePntCosUploader({ scene: 'default', pathKey: 'marketing_icon' });
+ * const { fileUrl, cosKey } = await uploader.upload(file, (p) => setProgress(p));
+ * ```
+ */
+export const usePntCosUploader = options => {
+  const {
+    http
+  } = usePntConfig();
+  // 用 ref 持有配置，避免 options 内联字面量导致 uploader 重建
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  return useMemo(() => createPntCosUploader(http, () => optionsRef.current), [http]);
+};
+export default usePntCosUploader;

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

@@ -0,0 +1,114 @@
+import React, { FunctionComponent, ReactNode, Ref } from 'react';
+import './index.scss';
+interface PntGeneralLayoutProps {
+    /**
+     * 自定义类名
+     */
+    className?: string;
+    /**
+     * 头部标题内容
+     * @description 传入后将渲染 Layout Header 区域
+     */
+    headerTitle?: ReactNode;
+    /**
+     * 是否显示返回按钮
+     * @default false
+     */
+    showBackButton?: boolean;
+    /**
+     * 返回按钮点击回调
+     */
+    onBackButtonClick?: (() => void) | undefined;
+    /**
+     * 是否显示头部底部分割线
+     * @default true
+     */
+    headerBordered?: boolean;
+    /**
+     * 子头部内容
+     * @description 位于 Header 下方，常用于放置面包屑、Tab 等
+     */
+    subHeaderContent?: ReactNode;
+    /**
+     * 头部右侧操作区
+     * @description 常用于放置按钮组
+     */
+    operation?: ReactNode;
+    /**
+     * 内容区 ref
+     */
+    bodyRef?: Ref<HTMLDivElement>;
+    /**
+     * 页面主体内容
+     */
+    children?: ReactNode;
+    /**
+     * 内容区自定义样式
+     */
+    bodyStyle?: React.CSSProperties;
+    /**
+     * 内容区内边距
+     * @description 数字按 px 处理；需要全出血内容时可传 '24px 0'
+     * @default 24
+     */
+    bodyPadding?: number | string;
+    /**
+     * 内容区卡片圆角（px）
+     * @description 作用于 body 内 t-card / tea-card / 各业务 wrapper、block 容器
+     * @default 4
+     */
+    cardRadius?: number;
+    /**
+     * 底部按钮样式模式
+     * @description fixed-统一下按钮尺寸（高 36px、最小宽 92px、加粗中号字）；
+     * auto-不约束按钮尺寸，仅保留按钮间距
+     * @default 'fixed'
+     */
+    footerButton?: 'fixed' | 'auto';
+    /**
+     * 底部内容
+     * @description 传入后将渲染 Layout Footer 区域，常用于放置操作按钮
+     */
+    footer?: ReactNode;
+}
+/**
+ * 通用页面布局组件（L3 布局组件）
+ * @description 提供标准的「头部 + 子头部 + 内容区 + 底部」页面布局结构，
+ * 基于 TDesign Layout（flex column）封装，内容区自动填满剩余高度，
+ * 适用于后台管理系统的列表页、详情页、表单页等场景。
+ *
+ * @example
+ * ```tsx
+ * // 基础用法：仅内容区
+ * <PntGeneralLayout>
+ *   <div>页面内容</div>
+ * </PntGeneralLayout>
+ *
+ * // 带标题和操作按钮
+ * <PntGeneralLayout
+ *   headerTitle="页面标题"
+ *   operation={<><Button>保存</Button><Button>取消</Button></>}
+ * >
+ *   <Form />
+ * </PntGeneralLayout>
+ *
+ * // 带返回按钮和底部
+ * <PntGeneralLayout
+ *   headerTitle="详情页"
+ *   showBackButton
+ *   onBackButtonClick={() => history.back()}
+ *   footer={<><Button>提交</Button><Button>重置</Button></>}
+ * >
+ *   <Detail />
+ * </PntGeneralLayout>
+ *
+ * // 全出血内容区（无头部边线、内容无左右内边距、底部按钮不强制尺寸）
+ * <PntGeneralLayout
+ *   headerBordered={false}
+ *   bodyPadding="24px 0"
+ *   footerButton="auto"
+ * />
+ * ```
+ */
+declare const PntGeneralLayout: FunctionComponent<PntGeneralLayoutProps>;
+export default PntGeneralLayout;

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

@@ -0,0 +1,103 @@
+import React from 'react';
+import { ArrowLeftIcon } from 'tdesign-icons-react';
+import { Layout } from 'tdesign-react';
+import "./index.scss";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * 通用页面布局组件（L3 布局组件）
+ * @description 提供标准的「头部 + 子头部 + 内容区 + 底部」页面布局结构，
+ * 基于 TDesign Layout（flex column）封装，内容区自动填满剩余高度，
+ * 适用于后台管理系统的列表页、详情页、表单页等场景。
+ *
+ * @example
+ * ```tsx
+ * // 基础用法：仅内容区
+ * <PntGeneralLayout>
+ *   <div>页面内容</div>
+ * </PntGeneralLayout>
+ *
+ * // 带标题和操作按钮
+ * <PntGeneralLayout
+ *   headerTitle="页面标题"
+ *   operation={<><Button>保存</Button><Button>取消</Button></>}
+ * >
+ *   <Form />
+ * </PntGeneralLayout>
+ *
+ * // 带返回按钮和底部
+ * <PntGeneralLayout
+ *   headerTitle="详情页"
+ *   showBackButton
+ *   onBackButtonClick={() => history.back()}
+ *   footer={<><Button>提交</Button><Button>重置</Button></>}
+ * >
+ *   <Detail />
+ * </PntGeneralLayout>
+ *
+ * // 全出血内容区（无头部边线、内容无左右内边距、底部按钮不强制尺寸）
+ * <PntGeneralLayout
+ *   headerBordered={false}
+ *   bodyPadding="24px 0"
+ *   footerButton="auto"
+ * />
+ * ```
+ */
+const PntGeneralLayout = prop => {
+  const {
+    className,
+    headerTitle,
+    showBackButton = false,
+    onBackButtonClick,
+    headerBordered = true,
+    subHeaderContent,
+    operation,
+    bodyRef,
+    children,
+    bodyStyle,
+    bodyPadding = 24,
+    cardRadius = 4,
+    footerButton = 'fixed',
+    footer
+  } = prop;
+  const {
+    Header,
+    Footer
+  } = Layout;
+  const layoutClassName = ['pnt-general-layout', !headerBordered && 'pnt-general-layout--borderless', footerButton === 'auto' && 'pnt-general-layout--footer-auto', className].filter(Boolean).join(' ');
+  const cssVars = {
+    '--pnt-layout-body-padding': typeof bodyPadding === 'number' ? `${bodyPadding}px` : bodyPadding,
+    '--pnt-layout-card-radius': `${cardRadius}px`
+  };
+  return /*#__PURE__*/_jsxs(Layout, {
+    className: layoutClassName,
+    style: cssVars,
+    children: [headerTitle && /*#__PURE__*/_jsxs(Header, {
+      children: [/*#__PURE__*/_jsxs("span", {
+        className: "header-title",
+        children: [showBackButton && /*#__PURE__*/_jsx(ArrowLeftIcon, {
+          className: "goback-icon",
+          size: "24px",
+          onClick: onBackButtonClick
+        }), /*#__PURE__*/_jsx("span", {
+          className: "title",
+          children: headerTitle
+        })]
+      }), operation && /*#__PURE__*/_jsx("span", {
+        className: "header-operation",
+        children: operation
+      })]
+    }), subHeaderContent && /*#__PURE__*/_jsx("div", {
+      className: "general-layout-sub-header",
+      children: subHeaderContent
+    }), /*#__PURE__*/_jsx("div", {
+      className: "general-layout-body",
+      ref: bodyRef,
+      style: bodyStyle,
+      children: children
+    }), footer && /*#__PURE__*/_jsx(Footer, {
+      children: footer
+    })]
+  });
+};
+export default PntGeneralLayout;