niuma-ui 1.0.0 → 1.0.2

package/src/components/table/table-chart-utils.ts

@@ -0,0 +1,165 @@
+/**
+ * 表格 → 图表系列纯函数（库无关）。
+ *
+ * 产出结构可直接喂给 ECharts / Chart.js 等：
+ * - pie / 普通 bar：points[{ name, value }]
+ * - 分类轴 bar：categories + values
+ *
+ * 不引入任何图表依赖，避免拖重内核。
+ */
+
+import type { RsTableRowData } from '../table-utils'
+
+/** 图表意图类型（渲染层自行映射到具体库） */
+export type RsTableChartKind = 'bar' | 'pie' | 'line'
+
+/** 单点：饼图扇区 / 柱条 */
+export interface RsTableChartPoint {
+  /** 分类名（展示） */
+  name: string
+  /** 聚合值 */
+  value: number
+  /** 原始分类 key（与 name 通常相同，供下钻） */
+  key: string
+  /** 该分类下的行数（便于 tooltip） */
+  count: number
+}
+
+/** 一组图表系列 */
+export interface RsTableChartSeries {
+  id: string
+  kind: RsTableChartKind
+  points: RsTableChartPoint[]
+  /** 分类轴（与 points 顺序一致） */
+  categories: string[]
+  /** 数值轴（与 points 顺序一致） */
+  values: number[]
+}
+
+export type RsTableChartValueAgg = 'count' | 'sum' | 'avg' | 'min' | 'max'
+
+/**
+ * 图表系列定义。
+ * - categoryField：分组字段
+ * - valueField + valueAgg：度量；仅 count 时可省略 valueField
+ */
+export interface RsTableChartSeriesDef {
+  id: string
+  kind: RsTableChartKind
+  categoryField: string
+  valueField?: string
+  valueAgg?: RsTableChartValueAgg
+  /** 最多保留前 N 类，其余合并为 otherLabel；0/不传表示不截断 */
+  topN?: number
+  otherLabel?: string
+  /** 空分类展示名 */
+  emptyCategoryLabel?: string
+}
+
+function readField(row: RsTableRowData, field: string): unknown {
+  return (row as Record<string, unknown>)[field]
+}
+
+function toNumber(value: unknown): number | null {
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  if (typeof value === 'string' && value.trim() !== '') {
+    const n = Number(value)
+    return Number.isFinite(n) ? n : null
+  }
+  return null
+}
+
+function categoryKey(raw: unknown, emptyLabel: string): string {
+  if (raw == null || raw === '') return emptyLabel
+  return String(raw)
+}
+
+interface Bucket {
+  key: string
+  name: string
+  count: number
+  nums: number[]
+}
+
+function aggregateBucket(bucket: Bucket, agg: RsTableChartValueAgg): number {
+  if (agg === 'count') return bucket.count
+  if (!bucket.nums.length) return 0
+  if (agg === 'sum') return bucket.nums.reduce((a, b) => a + b, 0)
+  if (agg === 'avg') return bucket.nums.reduce((a, b) => a + b, 0) / bucket.nums.length
+  if (agg === 'min') return Math.min(...bucket.nums)
+  if (agg === 'max') return Math.max(...bucket.nums)
+  return 0
+}
+
+/**
+ * 按分类字段对行做聚合，生成库无关图表系列。
+ *
+ * @param rows 通常为 SelectionSource.sourceRows（选中优先）
+ * @param def 系列定义
+ */
+export function buildTableChartSeries<T extends RsTableRowData>(
+  rows: readonly T[],
+  def: RsTableChartSeriesDef,
+): RsTableChartSeries {
+  const emptyLabel = def.emptyCategoryLabel ?? '(空)'
+  const agg = def.valueAgg ?? (def.valueField ? 'sum' : 'count')
+  const map = new Map<string, Bucket>()
+
+  for (let i = 0; i < rows.length; i += 1) {
+    const row = rows[i] as T
+    const key = categoryKey(readField(row, def.categoryField), emptyLabel)
+    let bucket = map.get(key)
+    if (!bucket) {
+      bucket = { key, name: key, count: 0, nums: [] }
+      map.set(key, bucket)
+    }
+    bucket.count += 1
+    if (def.valueField && agg !== 'count') {
+      const n = toNumber(readField(row, def.valueField))
+      if (n != null) bucket.nums.push(n)
+    }
+  }
+
+  let points: RsTableChartPoint[] = [...map.values()].map((bucket) => ({
+    key: bucket.key,
+    name: bucket.name,
+    value: aggregateBucket(bucket, agg),
+    count: bucket.count,
+  }))
+
+  // 按 value 降序，便于 topN / 饼图可读性
+  points.sort((a, b) => b.value - a.value || a.name.localeCompare(b.name))
+
+  const topN = def.topN ?? 0
+  if (topN > 0 && points.length > topN) {
+    const head = points.slice(0, topN)
+    const rest = points.slice(topN)
+    const otherValue = rest.reduce((s, p) => s + p.value, 0)
+    const otherCount = rest.reduce((s, p) => s + p.count, 0)
+    head.push({
+      key: '__other__',
+      name: def.otherLabel ?? '其他',
+      value: otherValue,
+      count: otherCount,
+    })
+    points = head
+  }
+
+  return {
+    id: def.id,
+    kind: def.kind,
+    points,
+    categories: points.map((p) => p.name),
+    values: points.map((p) => p.value),
+  }
+}
+
+/**
+ * 批量构建多组系列（同一 sourceRows，多套分组/度量）。
+ */
+export function buildTableChartSeriesList<T extends RsTableRowData>(
+  rows: readonly T[],
+  defs: readonly RsTableChartSeriesDef[],
+): RsTableChartSeries[] {
+  return defs.map((def) => buildTableChartSeries(rows, def))
+}

package/src/components/table/table-features.ts

@@ -0,0 +1,284 @@
+/**
+ * RsTable 特性插件协议。
+ *
+ * 目标：新能力以 feature 注册，避免继续向 RsTable.vue 堆分支。
+ *
+ * 已迁出 composable 的内置能力（行为真源）：
+ * - virtual → useRsTableVirtual + useRsTableColumnVirtual + useRsTableScrollLayout
+ * - contextMenu → useRsTableContextMenu
+ * - summary → useRsTableSummary
+ * - sort/selection/filter/tree → useRsTableEngine / useRsTableColumns / useRsTableInteraction
+ * - edit → useTableEdit + useRsTableEditActions
+ * - analytics / chart → useRsTableSelectionSource + useRsTableChartBridge（表外）
+ *
+ * Feature.setup 用于生命周期登记与扩展点；重逻辑不在此重复执行。
+ *
+ * 视图分层（世界级演进）：
+ * - Core / Shell / EditLayer = 行为真源
+ * - RsTableColGroup / Header / Body / BodyRow = 纯视图，不持业务状态
+ */
+
+import type { RsContextMenuItem } from '../context-menu-utils'
+import type { RsTableRowData } from '../table-utils'
+import type { RsTableAnalyticsSnapshot } from '../../composables/useRsTableSelectionSource'
+import type {
+  RsTableOverlayContribution,
+  RsTableToolbarItem,
+} from './rs-table-feature-host'
+import {
+  buildTableChartSeriesList,
+  type RsTableChartSeries,
+  type RsTableChartSeriesDef,
+} from './table-chart-utils'
+
+/**
+ * 表格特性插件上下文（只读查询 + 订阅 + 有限贡献点）。
+ * Feature 不得直接操作表格 DOM；图表/指标通过 snapshot / subscribe 接入。
+ */
+export interface RsTableFeatureContext<T extends RsTableRowData = RsTableRowData> {
+  /** 当前筛选/排序后的业务行（Engine.viewRows） */
+  getViewRows: () => T[]
+  /** 当前选中行 */
+  getSelectedRows: () => T[]
+  /**
+   * 分析快照：含 sourceRows（选中优先）与 sourceMode。
+   * 柱状图/饼图等应消费 sourceRows，而不是直接绑原始 data。
+   */
+  getAnalyticsSnapshot: () => RsTableAnalyticsSnapshot<T>
+  /**
+   * 订阅分析快照变化（浅层：view/selected 引用或 sourceMode）。
+   * @returns teardown
+   */
+  subscribeAnalytics: (listener: (snap: RsTableAnalyticsSnapshot<T>) => void) => () => void
+  /**
+   * 向右键菜单贡献项（setup 时调用）。
+   * - 传入数组：静态追加
+   * - 传入函数：每次打开菜单时动态贡献（可 push 到 items）
+   */
+  contributeContextMenuItems?: (
+    contributor:
+      | RsContextMenuItem[]
+      | ((
+          items: RsContextMenuItem[],
+          menuCtx: { row: T | null; selectedRows: T[] },
+        ) => void),
+  ) => void
+  /**
+   * 向工具条贡献项（实例级；多表互不共享贡献袋）。
+   */
+  contributeToolbarItems?: (
+    contributor: RsTableToolbarItem[] | ((items: RsTableToolbarItem[]) => void),
+  ) => void
+  /**
+   * 向 overlay 旁路贡献挂载描述（图表壳等，不直接改表格 DOM）。
+   */
+  contributeOverlay?: (
+    contributor:
+      | RsTableOverlayContribution[]
+      | ((items: RsTableOverlayContribution[]) => void),
+  ) => void
+}
+
+/**
+ * 企业级表格特性插件接口。
+ *
+ * @property id 稳定标识，与 props 开关 / 遥测对齐
+ * @property setup 挂载时调用；可返回 teardown
+ */
+export interface RsTableFeature<T extends RsTableRowData = RsTableRowData> {
+  id: string
+  setup(ctx: RsTableFeatureContext<T>): void | (() => void)
+}
+
+/**
+ * 内置特性 id（与 RsTable props 开关映射）。
+ * analytics 不进内置 props 开关：由业务通过 ChartBridge / Feature 外挂。
+ */
+export type RsTableBuiltinFeatureId =
+  | 'selection'
+  | 'sort'
+  | 'filter'
+  | 'virtual'
+  | 'edit'
+  | 'tree'
+  | 'contextMenu'
+  | 'summary'
+
+/** 已有独立 composable 承载的内置 id（feature 仅作登记） */
+export const RS_TABLE_FEATURE_COMPOSABLE_MAP: Record<
+  RsTableBuiltinFeatureId,
+  string | null
+> = {
+  selection: 'useRsTableEngine',
+  sort: 'useRsTableEngine',
+  filter: 'useRsTableEngine',
+  virtual: 'useRsTableVirtual+useRsTableColumnVirtual+useRsTableScrollLayout',
+  edit: 'useTableEdit+useRsTableEditActions',
+  tree: 'useRsTableEngine+useRsTableInteraction',
+  contextMenu: 'useRsTableContextMenu',
+  summary: 'useRsTableSummary',
+}
+
+/** 列布局/拖拽非 builtin feature id，但属内核横切能力 */
+export const RS_TABLE_COLUMN_SHELL = {
+  layout: 'useRsTableColumnLayout',
+  resize: 'useRsTableColumnResize',
+} as const
+
+/** 表外分析/图表扩展入口（不进 RsTable 内核渲染） */
+export const RS_TABLE_ANALYTICS_SHELL = {
+  selectionSource: 'useRsTableSelectionSource',
+  chartBridge: 'useRsTableChartBridge',
+  chartUtils: 'table-chart-utils',
+} as const
+
+/**
+ * 按 props 开关解析应启用的内置特性 id 列表。
+ */
+export function resolveBuiltinTableFeatures(flags: {
+  selectable?: boolean
+  sortableColumns?: boolean
+  filterable?: boolean
+  virtual?: boolean | 'auto'
+  editable?: boolean
+  tree?: boolean
+  contextMenu?: boolean
+  summary?: boolean
+}): RsTableBuiltinFeatureId[] {
+  const ids: RsTableBuiltinFeatureId[] = []
+  if (flags.selectable) ids.push('selection')
+  if (flags.sortableColumns !== false) ids.push('sort')
+  if (flags.filterable) ids.push('filter')
+  if (flags.virtual !== false) ids.push('virtual')
+  if (flags.editable) ids.push('edit')
+  if (flags.tree) ids.push('tree')
+  if (flags.contextMenu !== false) ids.push('contextMenu')
+  if (flags.summary) ids.push('summary')
+  return ids
+}
+
+/**
+ * 依次 setup 特性列表，并返回统一 teardown（逆序 dispose）。
+ */
+export function setupTableFeatures<T extends RsTableRowData>(
+  features: RsTableFeature<T>[],
+  ctx: RsTableFeatureContext<T>,
+): () => void {
+  const teardowns: Array<() => void> = []
+  for (const feature of features) {
+    const dispose = feature.setup(ctx)
+    if (typeof dispose === 'function') teardowns.push(dispose)
+  }
+  return () => {
+    for (const dispose of teardowns.reverse()) dispose()
+  }
+}
+
+/**
+ * 创建已绑定 composable 真源的内置 feature。
+ */
+export function createBuiltinTableFeatures<T extends RsTableRowData>(
+  ids: RsTableBuiltinFeatureId[],
+): RsTableFeature<T>[] {
+  return ids.map((id) => ({
+    id,
+    setup(ctx) {
+      if (import.meta.env.DEV && id === 'summary') {
+        void ctx.getAnalyticsSnapshot()
+      }
+    },
+  }))
+}
+
+/**
+ * 创建分析/图表旁路 feature：setup 时订阅 snapshot，交由业务 listener。
+ * 用于把「选中 → 图表」挂到统一生命周期，而不改 RsTable 模板。
+ */
+export function createAnalyticsTableFeature<T extends RsTableRowData>(options: {
+  id?: string
+  onSnapshot: (snap: RsTableAnalyticsSnapshot<T>) => void
+}): RsTableFeature<T> {
+  return {
+    id: options.id ?? 'analytics',
+    setup(ctx) {
+      return ctx.subscribeAnalytics(options.onSnapshot)
+    },
+  }
+}
+
+/**
+ * 创建右键菜单贡献 feature（静态项或动态函数）。
+ */
+export function createContextMenuTableFeature<T extends RsTableRowData>(options: {
+  id?: string
+  items:
+    | RsContextMenuItem[]
+    | ((
+        items: RsContextMenuItem[],
+        menuCtx: { row: T | null; selectedRows: T[] },
+      ) => void)
+}): RsTableFeature<T> {
+  return {
+    id: options.id ?? 'contextMenuExtra',
+    setup(ctx) {
+      ctx.contributeContextMenuItems?.(options.items)
+    },
+  }
+}
+
+/** 创建工具条贡献 feature */
+export function createToolbarTableFeature(options: {
+  id?: string
+  items: RsTableToolbarItem[] | ((items: RsTableToolbarItem[]) => void)
+}): RsTableFeature {
+  return {
+    id: options.id ?? 'toolbarExtra',
+    setup(ctx) {
+      ctx.contributeToolbarItems?.(options.items)
+    },
+  }
+}
+
+/** 创建 overlay 贡献 feature（图表旁路挂载点等） */
+export function createOverlayTableFeature(options: {
+  id?: string
+  items:
+    | RsTableOverlayContribution[]
+    | ((items: RsTableOverlayContribution[]) => void)
+}): RsTableFeature {
+  return {
+    id: options.id ?? 'overlayExtra',
+    setup(ctx) {
+      ctx.contributeOverlay?.(options.items)
+    },
+  }
+}
+
+/**
+ * 官方图表 Feature：订阅 analytics → 库无关 series，并登记 overlay 挂载点。
+ * 不捆绑 ECharts/Chart.js；业务用 onSeries 映射 option。
+ */
+export function createChartSeriesTableFeature<T extends RsTableRowData>(options: {
+  id?: string
+  seriesDefs: RsTableChartSeriesDef[] | (() => RsTableChartSeriesDef[])
+  onSeries: (
+    series: RsTableChartSeries[],
+    snap: RsTableAnalyticsSnapshot<T>,
+  ) => void
+  /** overlay 登记；默认 key=chart / slot=chart */
+  overlay?: RsTableOverlayContribution
+}): RsTableFeature<T> {
+  return {
+    id: options.id ?? 'chartSeries',
+    setup(ctx) {
+      ctx.contributeOverlay?.([
+        options.overlay ?? { key: 'chart', slot: 'chart', meta: { kind: 'series' } },
+      ])
+      return ctx.subscribeAnalytics((snap) => {
+        const defs =
+          typeof options.seriesDefs === 'function' ? options.seriesDefs() : options.seriesDefs
+        options.onSeries(buildTableChartSeriesList(snap.sourceRows, defs), snap)
+      })
+    },
+  }
+}

package/src/components/table/table-summary-utils.ts

@@ -0,0 +1,194 @@
+/**
+ * RsTable 列汇总纯函数：聚合算法、footer 单元格构建、兼容性警告。
+ *
+ * 不依赖 Vue；由 RsTable 在 computed 中调用。
+ * 聚合范围约定为「当前 viewRows」（筛选/排序后的业务行），不含 group/expand 伪行。
+ */
+
+import type { RsTableColumn, RsTableRowData } from '../table-utils'
+import { resolveColumnRawValue } from './table-edit-utils'
+
+/** 列汇总类型：内置数值聚合 + custom reduce */
+export type RsTableSummaryType = 'sum' | 'avg' | 'count' | 'min' | 'max' | 'custom'
+
+/**
+ * 列级汇总配置（挂在 `RsTableColumn.summary`）。
+ *
+ * - sum/avg/min/max：从行字段取可解析数字；无可解析值时单元格为空
+ * - count：行数（不读字段）
+ * - custom：必须提供 `reduce`
+ */
+export interface RsTableColumnSummary<T extends RsTableRowData = RsTableRowData> {
+  type: RsTableSummaryType
+  /** 展示格式化；未传时用默认 String(value) */
+  formatter?: (value: number | string, rows: T[]) => string
+  /** type=custom 时必填；返回值再经 formatter（若有） */
+  reduce?: (rows: T[]) => string | number
+}
+
+/**
+ * 汇总数据来源：
+ * - client：本地对 viewRows 聚合
+ * - server：直接展示业务传入的 summaryData，不做本地 reduce
+ */
+export type RsTableSummaryMode = 'client' | 'server'
+
+/** 服务端汇总：列 key → 展示值（null/undefined 显示为空） */
+export type RsTableSummaryData = Record<string, string | number | null | undefined>
+
+/** 单列汇总单元格结果（供 footer 行渲染） */
+export interface RsTableSummaryCell {
+  key: string
+  /** 原始聚合值；无数据时为 null */
+  value: string | number | null
+  /** 已格式化的展示文案 */
+  text: string
+}
+
+/** 将未知值解析为有限数字；失败返回 null（跳过该行） */
+function toNumber(value: unknown): number | null {
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  if (typeof value === 'string' && value.trim() !== '') {
+    const n = Number(value)
+    return Number.isFinite(n) ? n : null
+  }
+  return null
+}
+
+/**
+ * 收集列上可解析的数值序列。
+ * 取值路径与编辑/复制一致：resolveColumnRawValue（dataIndex / key）。
+ */
+function collectNumericValues<T extends RsTableRowData>(
+  rows: readonly T[],
+  column: RsTableColumn<T>,
+): number[] {
+  const nums: number[] = []
+  for (let i = 0; i < rows.length; i += 1) {
+    const raw = resolveColumnRawValue(rows[i] as T, column, i)
+    const n = toNumber(raw)
+    if (n != null) nums.push(n)
+  }
+  return nums
+}
+
+/**
+ * 对单列做汇总。列未配置 `summary` 时返回 null（由调用方填空单元格）。
+ *
+ * @param column 含可选 summary 的列定义
+ * @param rows 参与聚合的业务行（通常为 Engine.viewRows）
+ */
+export function aggregateColumnSummary<T extends RsTableRowData>(
+  column: RsTableColumn<T> & { summary?: RsTableColumnSummary<T> },
+  rows: readonly T[],
+): RsTableSummaryCell | null {
+  const config = column.summary
+  if (!config) return null
+
+  let value: string | number | null = null
+
+  if (config.type === 'custom') {
+    value = config.reduce ? config.reduce(rows as T[]) : null
+  } else if (config.type === 'count') {
+    value = rows.length
+  } else {
+    const nums = collectNumericValues(rows, column)
+    if (nums.length === 0) {
+      value = null
+    } else if (config.type === 'sum') {
+      value = nums.reduce((a, b) => a + b, 0)
+    } else if (config.type === 'avg') {
+      value = nums.reduce((a, b) => a + b, 0) / nums.length
+    } else if (config.type === 'min') {
+      value = Math.min(...nums)
+    } else if (config.type === 'max') {
+      value = Math.max(...nums)
+    }
+  }
+
+  const text =
+    value == null
+      ? ''
+      : config.formatter
+        ? config.formatter(value, rows as T[])
+        : String(value)
+
+  return { key: column.key, value, text }
+}
+
+/**
+ * 计算整行 footer 汇总单元格（与 displayColumns 一一对应）。
+ *
+ * - client：按 columns.summary 对 rows 聚合；无 summary 的列 text 为空
+ * - server：优先读 summaryData[key]；仍可用列上 formatter；忽略本地 sum/avg 等
+ *
+ * @returns 与 columns 等长的单元格数组
+ */
+export function buildTableSummaryCells<T extends RsTableRowData>(options: {
+  columns: Array<RsTableColumn<T> & { summary?: RsTableColumnSummary<T> }>
+  rows: readonly T[]
+  mode: RsTableSummaryMode
+  summaryData?: RsTableSummaryData | null
+}): RsTableSummaryCell[] {
+  const { columns, rows, mode, summaryData } = options
+  if (mode === 'server') {
+    return columns.map((column) => {
+      if (!column.summary && summaryData?.[column.key] === undefined) {
+        return { key: column.key, value: null, text: '' }
+      }
+      const raw = summaryData?.[column.key]
+      const value = raw == null ? null : raw
+      const text =
+        value == null
+          ? ''
+          : column.summary?.formatter
+            ? column.summary.formatter(value as string | number, rows as T[])
+            : String(value)
+      return { key: column.key, value, text }
+    })
+  }
+
+  return columns.map((column) => {
+    const cell = aggregateColumnSummary(column, rows)
+    return cell ?? { key: column.key, value: null, text: '' }
+  })
+}
+
+/**
+ * 是否存在任何可展示的汇总配置。
+ *
+ * - client：任一列带 summary
+ * - server：summaryData 非空对象
+ *
+ * 用于决定是否启用 summary feature / 渲染内置汇总行。
+ */
+export function hasTableSummaryConfig<T extends RsTableRowData>(options: {
+  columns: Array<RsTableColumn<T> & { summary?: RsTableColumnSummary<T> }>
+  mode: RsTableSummaryMode
+  summaryData?: RsTableSummaryData | null
+}): boolean {
+  if (options.mode === 'server') {
+    return Boolean(options.summaryData && Object.keys(options.summaryData).length > 0)
+  }
+  return options.columns.some((column) => Boolean(column.summary))
+}
+
+/**
+ * summary 与互斥/易误解能力的兼容矩阵检查（仅 DEV 警告）。
+ *
+ * - tree：合计基于已展开的 viewRows，不含折叠子节点
+ * - detail expandable：合计不含 expand 明细槽内容
+ */
+export function warnSummaryCompatibility(flags: {
+  summaryEnabled: boolean
+  tree: boolean
+  detailExpandable: boolean
+}): void {
+  if (!flags.summaryEnabled) return
+  if (flags.tree) {
+    console.warn('[RsTable] summary 与 treeConfig 同开时，合计基于展平行 viewRows，不含折叠子节点')
+  }
+  if (flags.detailExpandable) {
+    console.warn('[RsTable] summary 与 detail expandable 同开时，合计不含 expand 明细槽内容')
+  }
+}