@wangcheng051/plugin-kit 0.0.0-stage → 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,320 @@
+/**
+ * @wangcheng051/plugin-kit 类型声明
+ *
+ * 本包为纯 JS/JSX 实现，此文件为手写声明，用于给 TypeScript 使用方提供类型提示。
+ * 手写声明不会随源码自动更新，改动 src 的导出后请同步本文件；
+ * `npm run build` / `npm run verify:types` 会校验两者是否一致。
+ */
+
+import type * as React from 'react';
+import type { ThemeConfig } from 'antd';
+
+/* ------------------------------------------------------------------ *
+ * 单元格渲染器相关类型
+ * ------------------------------------------------------------------ */
+
+/** 标签列的选项 */
+export interface TagOption {
+  label: React.ReactNode;
+  value: string | number | boolean;
+  color?: string;
+}
+
+/** 操作列的按钮 */
+export interface ColumnAction {
+  key: string;
+  text: React.ReactNode;
+  onClick?: (action: ColumnAction, record?: any) => void;
+}
+
+/* ------------------------------------------------------------------ *
+ * 单元格渲染器
+ * ------------------------------------------------------------------ */
+
+export interface CellProps {
+  value?: any;
+  record?: any;
+  color?: string;
+  options?: TagOption[];
+  digits?: number;
+  showSymbol?: boolean;
+  percent?: boolean;
+  length?: number;
+  actions?: ColumnAction[];
+  onClick?: (value: any) => void;
+}
+
+/** 文本渲染（默认） */
+export function TextCell(props: CellProps): React.ReactElement;
+
+/** 金额渲染（负数标红） */
+export function MoneyCell(props: CellProps): React.ReactElement;
+
+/** 数字渲染（自动千分位） */
+export function NumberCell(props: CellProps): React.ReactElement;
+
+/** 标签渲染 */
+export function TagCell(props: CellProps): React.ReactElement;
+
+/** 长文本省略 + tooltip */
+export function EllipsisCell(props: CellProps): React.ReactElement;
+
+/** 链接单元格 */
+export function LinkCell(props: CellProps): React.ReactElement;
+
+/** 操作列渲染（按钮组） */
+export function ActionCell(props: CellProps): React.ReactElement;
+
+/* ------------------------------------------------------------------ *
+ * 主题
+ * ------------------------------------------------------------------ */
+
+/** ag-grid 经典主题名 */
+export type AgGridTheme =
+  | 'alpine'
+  | 'balham'
+  | 'material'
+  | 'quartz'
+  | 'classic';
+
+/** 行高密度 */
+export type TableDensity = 'compact' | 'normal' | 'relaxed';
+
+/** antd 5 主题配置 */
+export const crmTheme: ThemeConfig;
+
+/** 状态预设 */
+export const STATUS_PRESETS: Record<
+  string,
+  { color: string; text: string }
+>;
+
+/** 字典状态常见色值映射 */
+export const DICT_COLOR_MAP: Record<string, string>;
+
+/** v31 可用的经典主题名 */
+export const AG_GRID_THEMES: AgGridTheme[];
+
+/** 默认主题 */
+export const DEFAULT_AG_GRID_THEME: AgGridTheme;
+
+/**
+ * 生成 ag-grid 容器所需的 className。
+ */
+export function agGridClass(
+  theme?: AgGridTheme,
+  extra?: string,
+): string;
+
+/** 行高预设（compact / normal / relaxed） */
+export const ROW_HEIGHT_PRESETS: Record<TableDensity, number>;
+
+/* ------------------------------------------------------------------ *
+ * 工具函数
+ * ------------------------------------------------------------------ */
+
+/** 空值判断：null / undefined / '' / NaN / 空数组 */
+export function isEmpty(value: any): boolean;
+
+/** 安全取值，path 支持 'a.b.c' 形式 */
+export function get<T = any>(obj: any, path: string, defaultValue?: T): T;
+
+/** 数字千分位格式化 */
+export function formatNumber(value: number | string | null | undefined, digits?: number): string;
+
+/** 金额格式化（人民币） */
+export function formatMoney(
+  value: number | string | null | undefined,
+  options?: {
+    digits?: number;
+    symbol?: string;
+    showSymbol?: boolean;
+    showZeroZero?: boolean;
+  },
+): string;
+
+/** 百分比格式化，0.1234 -> '12.34%' */
+export function formatPercent(
+  value: number | string | null | undefined,
+  digits?: number,
+): string;
+
+/** 数组按键分组，返回 { key: item[] } */
+export function groupBy<T = any>(
+  list: T[],
+  keyFn: string | ((item: T) => string | number),
+): Record<string, T[]>;
+
+/** 过滤对象中的空值字段 */
+export function omitEmpty<T extends Record<string, any>>(obj: T): Partial<T>;
+
+/** 防抖 */
+export function debounce<T extends (...args: any[]) => any>(
+  fn: T,
+  wait?: number,
+): (...args: Parameters<T>) => void;
+
+/** 类名拼接 */
+export function cx(...args: any[]): string;
+
+/**
+ * 按 key 生成 Map，便于 O(1) 查找。
+ * key 优先取 obj[key]，取不到时回退到 obj.id。
+ */
+export function MayList<T = any>(
+  objectsArray?: T[],
+  key?: string,
+): Map<string | number, T>;
+
+/**
+ * 深拷贝（保留函数引用）。
+ * 遇到函数时返回原引用而非复制 —— 列配置里的 render 组件函数必须保留引用。
+ */
+export function deepClone<T>(value: T): T;
+
+/* ------------------------------------------------------------------ *
+ * CRM 业务列表组件
+ * ------------------------------------------------------------------ */
+
+/** 列配置项（业务列表用，字段较 ag-grid 版更宽松） */
+export interface BusinessColumnConfig {
+  field: string;
+  key?: string;
+  cnDisplay?: string;
+  enDisplay?: string;
+  /** 是否默认显示 */
+  visible?: boolean;
+  /** 是否隐藏 */
+  hide?: boolean;
+  /** 锁定位置（合计行不统计） */
+  lockPosition?: boolean;
+  /** 自定义渲染 */
+  render?: (params: any) => React.ReactNode;
+  [key: string]: any;
+}
+
+/** 列表接口请求方法 */
+export type TableRequest = (
+  params: any,
+  url?: string,
+) => Promise<{ response: any }>;
+
+/** 列配置查询接口 */
+export type GetColConfigRequest = (
+  configKey?: string,
+) => Promise<{ response: any }>;
+
+/** 列配置保存接口 */
+export type SaveColConfigRequest = (params: any) => void | Promise<any>;
+
+/** 排序状态 */
+export interface SortInfo {
+  colId?: string;
+  sort?: 'asc' | 'desc' | null;
+}
+
+/** useTableModule 的入参 */
+export interface UseTableModuleProps {
+  /** sessionStorage 存储 key */
+  sessionKey?: string;
+  /** 自定义单元格渲染，如 { companyName: (params) => node } */
+  renderKey?: Record<string, (params: any) => React.ReactNode>;
+  /** 自定义请求参数转换 */
+  setParamsList?: (params: any) => any;
+  /** 列配置的业务标识 */
+  configKey?: string;
+  /** 列表接口地址 */
+  tableUrl?: string;
+  /** 列表接口请求方法 */
+  tableRequest?: TableRequest;
+  /** 查询列配置接口 */
+  getColConfigRequest?: GetColConfigRequest;
+  /** 保存列配置接口 */
+  saveColConfigRequest?: SaveColConfigRequest;
+}
+
+/** useTableModule 返回值 */
+export interface UseTableModuleResult {
+  /** 列设置按钮渲染函数 */
+  SettingTableRender: (props?: any) => React.ReactElement;
+  /** 表格渲染函数 */
+  TableListRender: (props?: any) => React.ReactElement;
+  /** 重新拉取列表 */
+  getTableData: () => Promise<any> | void;
+  /** 重新拉取列配置 */
+  getColConfig: () => void;
+  /** 保存列配置 */
+  saveColConfig: () => void;
+  /** 重置搜索条件 */
+  resetSesstion: () => void;
+  /** 当前列表数据 */
+  tableData: any[];
+  /** 设置 loading */
+  setloading: (loading: boolean) => void;
+  /** 当前 loading 状态 */
+  loading: boolean;
+  /** 当前列定义 */
+  columnDefs: BusinessColumnConfig[];
+  /** 当前请求参数（ref） */
+  paramsCurrent: { current: any };
+  /** 分页总条数 */
+  total?: number;
+  /** 当前筛选条件 */
+  filterKey: any[];
+}
+
+/**
+ * CRM 列表 Hook：统一管理列配置、排序、分页、高级搜索与 session 持久化。
+ *
+ * 所有业务接口均需注入，插件包不依赖任何业务工程。
+ */
+export function useTableModule(
+  props?: UseTableModuleProps,
+  defaultProps?: UseTableModuleProps,
+): UseTableModuleResult;
+
+/** TableList 属性 */
+export interface TableListProps {
+  columnDefs?: BusinessColumnConfig[];
+  loading?: boolean;
+  customBottomTotal?: boolean;
+  onChange?: (params: any) => void;
+  tableRef?: React.MutableRefObject<any>;
+  tableData?: any[];
+  pagination?: boolean | { current?: number; pageSize?: number; total?: number };
+  reset?: Record<string, any>;
+  customColumn?: any[];
+  filterSearchRender?: Record<string, any>;
+  setfilterKey?: (keys: any[]) => void;
+  filterKey?: any[];
+  [key: string]: any;
+}
+
+/** 表格组件 */
+export function TableList(props: TableListProps): React.ReactElement;
+
+/** 列设置组件 */
+export function SettingTable(props: {
+  onChange?: (params: any) => void;
+  columRef?: React.MutableRefObject<any>;
+  [key: string]: any;
+}): React.ReactElement;
+
+/** 自定义表头组件 */
+export function CustomHeader(props: any): React.ReactElement;
+
+/** 列表页自定义搜索插槽 */
+export function OtherSlot(props: {
+  dataIndex?: string;
+  language?: boolean;
+  onChange?: (value: any) => void;
+  value?: any;
+  [key: string]: any;
+}): React.ReactElement;
+
+/** 升序图标 */
+export const SortAscending: React.ComponentType<any>;
+/** 降序图标 */
+export const SortDescending: React.ComponentType<any>;
+/** 未排序图标 */
+export const SortUnSort: React.ComponentType<any>;