niuma-ui 1.0.1 → 1.1.0

package/src/components/table/RsTableBodyRow.vue

@@ -18,6 +18,13 @@ defineProps<{
   columnStyleMap: Map<string, Record<string, string> | undefined>
   showRowDragHandle: boolean
   expandable: boolean
+  /** 树表模式：在指定数据列内缩进展开 */
+  treeMode?: boolean
+  treeDepth?: number
+  treeHasChildren?: boolean
+  treeIndent?: number
+  treeColumnKey?: string | null
+  treeLoading?: boolean
   selectable: boolean
   showIndex: boolean
   showEditGutter: boolean
@@ -34,6 +41,8 @@ defineProps<{
   selected: boolean
   highlighted: boolean
   expanded: boolean
+  /** 树级联半选 */
+  indeterminate?: boolean
   disabled: boolean
   rowDragByRow: boolean
   dragging: boolean
@@ -99,7 +108,9 @@ const emit = defineEmits<{
 
 <template>
   <tr
+    role="row"
     class="rs-table__row"
+    :data-row-key="rowKey"
     :class="{
       'rs-table__row--selected': selected,
       'rs-table__row--highlighted': highlighted && !selected,
@@ -157,12 +168,19 @@ const emit = defineEmits<{
       :style="selectLeadStyle"
       @click.stop
     >
-      <label class="rs-table__checkbox" :class="{ 'rs-table__checkbox--checked': selected }">
+      <label
+        class="rs-table__checkbox"
+        :class="{
+          'rs-table__checkbox--checked': selected,
+          'rs-table__checkbox--indeterminate': indeterminate && !selected,
+        }"
+      >
         <input
           :type="selectionType"
           class="rs-table__checkbox-input"
           :name="isRadioSelection ? 'rs-table-radio' : undefined"
           :checked="selected"
+          :indeterminate="Boolean(indeterminate && !selected)"
           :disabled="!canSelect"
           :aria-label="selectRowLabel"
           @change="emit('toggleSelect')"
@@ -218,7 +236,9 @@ const emit = defineEmits<{
     <td
       v-for="column in columns"
       :key="column.key"
+      role="gridcell"
       class="rs-table__td rs-table__td--data"
+      :data-col-key="column.key"
       :class="[
         columnTdClassMap.get(column.key),
         {
@@ -226,10 +246,12 @@ const emit = defineEmits<{
           'rs-table__td--editing': editingColKey === column.key,
           'rs-table__td--focused': focusColKey === column.key && editingColKey !== column.key,
           'rs-table__td--invalid': !!getCellError(rowKey, column.key),
+          'rs-table__td--tree': treeMode && treeColumnKey === column.key,
         },
       ]"
       :style="columnStyleMap.get(column.key)"
       :draggable="rowDragByRow"
+      :tabindex="focusColKey === column.key && editingColKey !== column.key ? 0 : -1"
       :aria-selected="focusColKey === column.key || editingColKey === column.key ? 'true' : undefined"
       @click.stop="emit('cellClick', column.key, $event)"
       @dblclick.stop="emit('cellDblclick', column.key, $event)"
@@ -237,7 +259,74 @@ const emit = defineEmits<{
       @dragstart="rowDragByRow ? emit('rowDragStart', $event) : undefined"
       @dragend="rowDragByRow ? emit('rowDragEnd') : undefined"
     >
+      <div
+        v-if="treeMode && treeColumnKey === column.key"
+        class="rs-table__tree-cell"
+        :style="{ paddingInlineStart: `${(treeDepth ?? 0) * (treeIndent ?? 20)}px` }"
+      >
+        <button
+          v-if="treeHasChildren"
+          type="button"
+          class="rs-table__expand-btn rs-table__tree-toggle"
+          :class="{
+            'rs-table__expand-btn--expanded': expanded,
+            'rs-table__tree-toggle--loading': treeLoading,
+          }"
+          :disabled="treeLoading"
+          :aria-label="expanded ? collapseRowLabel : expandRowLabel"
+          @click.stop="emit('toggleExpand')"
+        >
+          ›
+        </button>
+        <span
+          v-else
+          class="rs-table__tree-leaf"
+          aria-hidden="true"
+        />
+        <span
+          :class="[
+            'rs-table__tree-content',
+            { 'rs-table__cell-tip': cellTooltipEnabled(column, rowIndex) },
+            { 'rs-table__cell-tip--editing': editingColKey === column.key },
+          ]"
+          :data-rs-table-tip-mode="cellTooltipEnabled(column, rowIndex) ? cellTooltipMode(column, rowIndex) : undefined"
+          :data-rs-table-tip-text="cellTooltipText(column, row, rowIndex)"
+          :title="getCellError(rowKey, column.key) || cellTooltipFallbackTitle(column, row, rowIndex)"
+        >
+          <RsTableCell
+            :column="column"
+            :row="row"
+            :row-index="rowIndex"
+            :row-key="rowKey"
+            :table-editable="tableEditable"
+            :editing="editingColKey === column.key"
+            :dirty="isCellDirty(rowKey, column.key)"
+            :focused="focusColKey === column.key"
+            :draft="getCellDraft(rowKey, column.key)"
+            :has-custom-slot="hasColumnSlot(column.key)"
+            :has-edit-slot="hasEditSlot(column.key)"
+            :edit-trigger="editTrigger"
+            :row-commit="rowCommit"
+            :allow-null="allowNull"
+            :focus-mode="focusMode"
+            :null-label="nullLabel"
+            :error-message="getCellError(rowKey, column.key) ?? null"
+            :validating="isCellValidating(rowKey, column.key)"
+            @start-edit="emit('cellStartEdit', column.key)"
+            @commit="emit('cellCommit', column.key, $event)"
+            @cancel="emit('cellCancel', column.key)"
+            @update-draft="emit('cellUpdateDraft', column.key, $event)"
+            @navigate="emit('cellNavigate', column.key, $event)"
+          >
+            <slot :name="column.key" :row="row" :column="column" :index="rowIndex" />
+            <template v-if="hasEditSlot(column.key)" #editor="scope">
+              <slot :name="`edit-${column.key}`" v-bind="scope" />
+            </template>
+          </RsTableCell>
+        </span>
+      </div>
       <span
+        v-else
         :class="[
           { 'rs-table__cell-tip': cellTooltipEnabled(column, rowIndex) },
           { 'rs-table__cell-tip--editing': editingColKey === column.key },

package/src/components/table/RsTableColGroup.vue

@@ -0,0 +1,41 @@
+<script setup lang="ts" generic="T extends import('../table-utils').RsTableRowData">
+import { useRsTableView } from './rs-table-view-context'
+
+const view = useRsTableView<T>()
+</script>
+
+<template>
+  <colgroup v-if="view.useFixedColumnLayout">
+    <col v-if="view.showRowDragHandle" :style="{ width: `${view.prefixWidths.drag}px` }">
+    <col v-if="view.detailExpandable" :style="{ width: `${view.prefixWidths.expand}px` }">
+    <col v-if="view.showSelectColumn" :style="{ width: `${view.prefixWidths.select}px` }">
+    <col
+      v-if="view.showEditGutterColumn"
+      data-col-key="gutter"
+      :style="{ width: `${view.resolvedGutterWidth}px` }"
+    >
+    <col
+      v-else-if="view.showIndexColumn"
+      :style="{ width: `${view.resolvedIndexWidth}px` }"
+    >
+    <col v-if="view.showRowStatusColumn" :style="{ width: `${view.prefixWidths.status}px` }">
+    <col
+      v-if="view.columnPadLeft > 0"
+      class="rs-table__col-pad"
+      :style="{ width: `${view.columnPadLeft}px` }"
+    >
+    <col
+      v-for="column in view.visibleDataColumns"
+      :key="column.key"
+      :data-col-key="column.key"
+      :style="{
+        width: `${view.resolvedDataColumnWidth(column.key, column.width ?? column.minWidth)}px`,
+      }"
+    >
+    <col
+      v-if="view.columnPadRight > 0"
+      class="rs-table__col-pad"
+      :style="{ width: `${view.columnPadRight}px` }"
+    >
+  </colgroup>
+</template>

package/src/components/table/RsTableHeader.vue

@@ -0,0 +1,158 @@
+<script setup lang="ts" generic="T extends import('../table-utils').RsTableRowData">
+import RsIcon from '../RsIcon.vue'
+import RsTableHeaderFilter from './RsTableHeaderFilter.vue'
+import { useRsTableView } from './rs-table-view-context'
+
+const view = useRsTableView<T>()
+</script>
+
+<template>
+  <thead
+    class="rs-table__head"
+    @pointerover.passive="view.onHeaderPointerOver($event)"
+    @pointerout.passive="view.onHeaderPointerOut($event)"
+  >
+    <tr role="row">
+      <th
+        v-if="view.showRowDragHandle"
+        role="columnheader"
+        class="rs-table__th rs-table__th--drag"
+        :style="view.dragLeadHeaderStyle"
+      />
+      <th
+        v-if="view.detailExpandable"
+        role="columnheader"
+        class="rs-table__th rs-table__th--expand"
+        :style="view.expandLeadHeaderStyle"
+      />
+      <th
+        v-if="view.showSelectColumn"
+        role="columnheader"
+        class="rs-table__th rs-table__th--selection"
+        :style="view.selectLeadHeaderStyle"
+      >
+        <label
+          v-if="!view.isRadioSelection"
+          class="rs-table__checkbox"
+          :class="{
+            'rs-table__checkbox--checked': view.selectAllState === 'checked',
+            'rs-table__checkbox--indeterminate': view.selectAllState === 'indeterminate',
+          }"
+        >
+          <input
+            type="checkbox"
+            class="rs-table__checkbox-input"
+            :checked="view.selectAllState === 'checked'"
+            :aria-label="view.headerLabels.selectAll"
+            @change="view.onToggleSelectAll()"
+          >
+          <span class="rs-table__checkbox-box" aria-hidden="true" />
+        </label>
+      </th>
+      <th
+        v-if="view.showEditGutterColumn"
+        role="columnheader"
+        class="rs-table__th rs-table__th--gutter rs-table__cell--center"
+        :style="view.gutterLeadHeaderStyle"
+      />
+      <th
+        v-else-if="view.showIndexColumn"
+        role="columnheader"
+        class="rs-table__th rs-table__th--index rs-table__cell--center"
+        :style="view.indexLeadHeaderStyle"
+      >
+        {{ view.headerLabels.index }}
+      </th>
+      <th
+        v-if="view.showRowStatusColumn"
+        role="columnheader"
+        class="rs-table__th rs-table__th--status rs-table__cell--center"
+      >
+        {{ view.headerLabels.rowStatus }}
+      </th>
+      <th
+        v-if="view.columnPadLeft > 0"
+        role="presentation"
+        class="rs-table__th rs-table__col-pad"
+        :style="{ width: `${view.columnPadLeft}px`, minWidth: `${view.columnPadLeft}px` }"
+      />
+      <th
+        v-for="column in view.visibleDataColumns"
+        :key="column.key"
+        role="columnheader"
+        :data-col-key="column.key"
+        class="rs-table__th"
+        :class="[
+          `rs-table__cell--${column.align ?? 'left'}`,
+          { 'rs-table__th--sortable': column.sortable },
+          { 'rs-table__th--filterable': column.filterable },
+          { 'rs-table__cell--fixed': column.fixed },
+          { 'rs-table__th--dragging': view.dragColumnKey === column.key },
+          { 'rs-table__th--drop-target': view.dropColumnKey === column.key },
+        ]"
+        :style="view.columnHeaderStyleMap.get(column.key)"
+        @dragover="view.onColumnDragOver(column.key, $event)"
+        @drop="view.onColumnDrop(column.key, $event)"
+      >
+        <span
+          v-if="view.columnDraggable"
+          class="rs-table__column-drag-handle"
+          draggable="true"
+          :aria-label="view.headerLabels.dragColumn"
+          @click.stop
+          @dragstart.stop="view.onColumnDragStart(column.key, $event)"
+          @dragend.stop="view.onColumnDragEnd()"
+        />
+        <slot :name="`header-${column.key}`" :column="column">
+          <span
+            v-if="column.headerTip"
+            class="rs-table__th-label rs-table__th-label--tip"
+            :data-rs-table-header-tip="column.headerTip"
+          >{{ column.title }}</span>
+          <span v-else class="rs-table__th-label">{{ column.title }}</span>
+        </slot>
+        <span v-if="column.filterable || column.sortable" class="rs-table__header-actions">
+          <RsTableHeaderFilter
+            v-if="column.filterable"
+            :model-value="view.columnFilterValue(column.key)"
+            :column-title="column.title"
+            :filter-label="view.headerLabels.filterColumn"
+            :placeholder="view.headerLabels.filterPlaceholder"
+            :clear-label="view.headerLabels.filterClear"
+            :apply-label="view.headerLabels.filterApply"
+            :active="view.isColumnFilterActive(view.columnFiltersState, column.key)"
+            @update:model-value="view.updateColumnFilter(column.key, $event)"
+          />
+          <button
+            v-if="column.sortable"
+            type="button"
+            class="rs-table__sort"
+            :class="{ 'rs-table__sort--active': !!view.sortOrderFor(column.key) }"
+            :title="column.title"
+            :aria-label="column.title"
+            @click.stop="view.onHeaderClick(column)"
+          >
+            <RsIcon :name="view.sortIconName(column.key)" size="sm" />
+            <span
+              v-if="view.multiSort && view.sortPriorityFor(column.key) > 1"
+              class="rs-table__sort-priority"
+            >
+              {{ view.sortPriorityFor(column.key) }}
+            </span>
+          </button>
+        </span>
+        <span
+          v-if="view.resizable"
+          class="rs-table__resize-handle"
+          @mousedown.stop="view.onResizeStart(column.key, $event)"
+          @click.stop
+        />
+      </th>
+      <th
+        v-if="view.columnPadRight > 0"
+        class="rs-table__th rs-table__col-pad"
+        :style="{ width: `${view.columnPadRight}px`, minWidth: `${view.columnPadRight}px` }"
+      />
+    </tr>
+  </thead>
+</template>

package/src/components/table/RsTableHeaderFilter.vue

@@ -87,7 +87,7 @@ function onEditorEnter(): void {
 .rs-table-header-filter__title {
   margin: 0 0 0.5rem;
   font-size: var(--rs-font-size-sm);
-  font-weight: 600;
+  font-weight: var(--rs-font-weight-semibold);
   color: var(--rs-fg);
 }
 .rs-table-header-filter__field {

package/src/components/table/RsTableSummaryRow.vue

@@ -0,0 +1,52 @@
+<script setup lang="ts" generic="T extends import('../table-utils').RsTableRowData">
+/**
+ * 表格 footer 汇总行：按列渲染 summaryCells.text。
+ *
+ * 前缀列（拖拽/展开/选择/序号等）用 colspan 占位，与表体列对齐；
+ * padLeft / padRight 对齐列虚拟滚动的左右垫片。
+ */
+import type { RsTableColumn } from '../table-utils'
+import type { RsTableSummaryCell } from './table-summary-utils'
+
+defineProps<{
+  /** 与表体一致的展示列（通常为 displayColumns） */
+  columns: RsTableColumn<T>[]
+  /** 与 columns 按 key 对应的汇总单元格 */
+  cells: RsTableSummaryCell[]
+  /** 前缀列占位 colspan（拖拽/展开/选择/序号/状态等） */
+  prefixColspan?: number
+  /** 列虚拟左侧垫片宽度（px） */
+  padLeft?: number
+  /** 列虚拟右侧垫片宽度（px） */
+  padRight?: number
+}>()
+</script>
+
+<template>
+  <tr class="rs-table__summary-row">
+    <td
+      v-if="(prefixColspan ?? 0) > 0"
+      class="rs-table__summary-cell rs-table__summary-cell--prefix"
+      :colspan="prefixColspan"
+    />
+    <td
+      v-if="(padLeft ?? 0) > 0"
+      class="rs-table__summary-cell rs-table__summary-cell--pad"
+      :style="{ width: `${padLeft}px`, minWidth: `${padLeft}px` }"
+    />
+    <td
+      v-for="column in columns"
+      :key="column.key"
+      class="rs-table__summary-cell"
+      :class="column.align ? `rs-table__summary-cell--${column.align}` : undefined"
+      :data-col-key="column.key"
+    >
+      {{ cells.find((c) => c.key === column.key)?.text ?? '' }}
+    </td>
+    <td
+      v-if="(padRight ?? 0) > 0"
+      class="rs-table__summary-cell rs-table__summary-cell--pad"
+      :style="{ width: `${padRight}px`, minWidth: `${padRight}px` }"
+    />
+  </tr>
+</template>

package/src/components/table/rs-table-api.ts

@@ -0,0 +1,99 @@
+/**
+ * RsTable 公开 API 契约（对标 AG Grid GridApi / TanStack table 实例）。
+ *
+ * 设计原则（大厂共性）：
+ * - 业务与第三方只依赖本接口，不依赖 SFC 内部变量
+ * - 加性演进：新增方法用可选字段或 bump RS_TABLE_API_VERSION
+ * - 查询与命令分离：getXxx 无副作用；setXxx / commitXxx 为命令
+ *
+ * 兼容承诺：同主版本内不删除、不改语义已有方法签名。
+ */
+
+import type { RsTableStagedCell } from '../../composables/useTableEdit'
+import type { RsTableAnalyticsSnapshot } from '../../composables/useRsTableSelectionSource'
+import type { RsTableColumn, RsTableRowData } from '../table-utils'
+
+/** 公开 API 语义版本（与 package 版本解耦，专指 TableApi 契约） */
+export const RS_TABLE_API_VERSION = '1.0.0' as const
+
+/**
+ * 表格实例 API：ref / expose / provide / inject 共用同一形状。
+ */
+export interface RsTableApi<T extends RsTableRowData = RsTableRowData> {
+  readonly apiVersion: typeof RS_TABLE_API_VERSION
+
+  // -- 行查询 --
+  getRowByKey: (rowKey: string) => T | undefined
+  getRowByIndex: (index: number) => T | undefined
+  getColumnValues: (colKey: string) => unknown[]
+  getCellValue: (rowKey: string, colKey: string) => unknown
+
+  // -- 视图 / 选中（分析与图表真源）--
+  /** 筛选/排序后的业务行（不含 group/expand 伪行） */
+  getViewRows: () => T[]
+  getSelectedRows: () => T[]
+  getSelectedRowKeys: () => string[]
+  getAnalyticsSnapshot: () => RsTableAnalyticsSnapshot<T>
+  subscribeAnalytics: (listener: (snap: RsTableAnalyticsSnapshot<T>) => void) => () => void
+
+  // -- 高亮 --
+  getHighlightedRowKey: () => string | undefined
+  setHighlightedRowKey: (key: string | undefined) => void
+
+  // -- 编辑 --
+  cancelCellEdit: () => void
+  cancelAllEdits: () => void
+  getDirtyCellKeys: () => string[]
+  getCellError: (rowKey: string, colKey: string) => string | undefined
+  setCellError: (rowKey: string, colKey: string, message: string | null) => void
+  stageCell: (cell: RsTableStagedCell) => void
+  rejectRowEdit: (rowKey: string, reason?: string) => void
+  undoEdit: () => void
+  redoEdit: () => void
+  commitRowEdits: (rowKey: string) => void
+  rollbackRowEdits: (rowKey: string) => void
+
+  // -- 扩展元数据（可选，便于遥测）--
+  getActiveFeatureIds?: () => string[]
+  /** 实例 Feature 贡献的工具条项 */
+  getToolbarItems?: () => import('./rs-table-feature-host').RsTableToolbarItem[]
+  /** 实例 Feature 贡献的 overlay 描述 */
+  getOverlayContributions?: () => import('./rs-table-feature-host').RsTableOverlayContribution[]
+}
+
+/** provide/inject 键：子组件或插槽内拿表格 API */
+export const RS_TABLE_API_KEY: unique symbol = Symbol('rsTableApi')
+
+/**
+ * 由 RsTable 内部装配公开 API（单一出口，避免 expose 与 inject 漂移）。
+ */
+export function createRsTableApi<T extends RsTableRowData>(
+  impl: Omit<RsTableApi<T>, 'apiVersion'> & { apiVersion?: typeof RS_TABLE_API_VERSION },
+): RsTableApi<T> {
+  return {
+    apiVersion: impl.apiVersion ?? RS_TABLE_API_VERSION,
+    ...impl,
+  }
+}
+
+/** 类型守卫：判断未知对象是否像 RsTableApi */
+export function isRsTableApi<T extends RsTableRowData = RsTableRowData>(
+  value: unknown,
+): value is RsTableApi<T> {
+  if (!value || typeof value !== 'object') return false
+  const api = value as Partial<RsTableApi<T>>
+  return (
+    typeof api.getViewRows === 'function' &&
+    typeof api.getSelectedRows === 'function' &&
+    typeof api.getAnalyticsSnapshot === 'function'
+  )
+}
+
+/** 列定义辅助：标记某列参与图表分类（文档/约定，不强制运行时） */
+export type RsTableColumnChartMeta = {
+  chartCategory?: boolean
+  chartValue?: boolean
+}
+
+export type RsTableColumnWithChartMeta<T extends RsTableRowData = RsTableRowData> = RsTableColumn<T> &
+  RsTableColumnChartMeta

package/src/components/table/rs-table-compat-matrix.ts

@@ -0,0 +1,71 @@
+/**
+ * RsTable 公开契约兼容矩阵（单一真源）。
+ *
+ * - 测试锁定这些键：删除/改名 = 失败，须 bump RS_TABLE_API_VERSION
+ * - 文档与 CI 共用，避免矩阵与实现漂移
+ */
+
+import { RS_TABLE_API_VERSION } from './rs-table-api'
+import { RS_TABLE_PROP_DEFAULTS } from './rs-table-props'
+
+/** 当前锁定的 API 契约版本（与 createRsTableApi 一致） */
+export const RS_TABLE_COMPAT_API_VERSION = RS_TABLE_API_VERSION
+
+/**
+ * 1.0.x 必选 Api 方法（加性可选方法不在此列）。
+ * 删减任一项视为 breaking。
+ */
+export const RS_TABLE_API_REQUIRED_METHODS = [
+  'getRowByKey',
+  'getRowByIndex',
+  'getColumnValues',
+  'getCellValue',
+  'getViewRows',
+  'getSelectedRows',
+  'getSelectedRowKeys',
+  'getAnalyticsSnapshot',
+  'subscribeAnalytics',
+  'getHighlightedRowKey',
+  'setHighlightedRowKey',
+  'cancelCellEdit',
+  'cancelAllEdits',
+  'getDirtyCellKeys',
+  'getCellError',
+  'setCellError',
+  'stageCell',
+  'rejectRowEdit',
+  'undoEdit',
+  'redoEdit',
+  'commitRowEdits',
+  'rollbackRowEdits',
+] as const
+
+/** 1.0.x 加性可选 Api（可缺省，但若存在须为函数） */
+export const RS_TABLE_API_OPTIONAL_METHODS = [
+  'getActiveFeatureIds',
+  'getToolbarItems',
+  'getOverlayContributions',
+] as const
+
+/**
+ * 稳定 emit 名（同主版本不删）。
+ * 新增 emit 可追加到测试期望的超集校验。
+ */
+export const RS_TABLE_STABLE_EMITS = [
+  'rowClick',
+  'rowDblclick',
+  'cellView',
+  'update:selectedRowKeys',
+  'selectionChange',
+  'loadMore',
+  'cellEditCommit',
+  'cellEditCancel',
+  'rowEditCommit',
+  'rowEditRollback',
+] as const
+
+/** 带默认值的 props 键（与 RS_TABLE_PROP_DEFAULTS 同步校验） */
+export const RS_TABLE_DEFAULTED_PROP_KEYS = Object.keys(RS_TABLE_PROP_DEFAULTS).sort()
+
+export type RsTableApiRequiredMethod = (typeof RS_TABLE_API_REQUIRED_METHODS)[number]
+export type RsTableApiOptionalMethod = (typeof RS_TABLE_API_OPTIONAL_METHODS)[number]

package/src/components/table/rs-table-echarts-adapter.ts

@@ -0,0 +1,81 @@
+/**
+ * RsTable 系列 → ECharts option 纯映射（不依赖 echarts 包）。
+ *
+ * 业务侧：`import('echarts').then(e => e.init(el).setOption(option))`
+ * 内核保持库无关；本文件只产出普通 JSON 可序列化结构。
+ */
+
+import type { RsTableChartSeries } from './table-chart-utils'
+
+/** 最小 ECharts option 面（刻意放宽，避免绑定具体 echarts 类型版本） */
+export type RsTableEChartsOption = {
+  tooltip?: { trigger?: string }
+  legend?: { data?: string[] }
+  xAxis?: { type?: string; data?: string[] } | Array<{ type?: string; data?: string[] }>
+  yAxis?: { type?: string } | Array<{ type?: string }>
+  series: Array<{
+    id?: string
+    name?: string
+    type: 'bar' | 'line' | 'pie'
+    data: Array<number | { name: string; value: number }>
+  }>
+}
+
+export interface MapRsTableSeriesToEChartsOptions {
+  /** 多系列时是否共用类目轴（默认 true；饼图忽略） */
+  sharedCategoryAxis?: boolean
+  /** tooltip.trigger，默认按首系列推断 */
+  tooltipTrigger?: 'item' | 'axis'
+}
+
+function mapKind(kind: RsTableChartSeries['kind']): 'bar' | 'line' | 'pie' {
+  if (kind === 'pie') return 'pie'
+  if (kind === 'line') return 'line'
+  return 'bar'
+}
+
+/**
+ * 将库无关 series 映射为可直接 setOption 的 ECharts option。
+ */
+export function mapRsTableSeriesToEChartsOption(
+  seriesList: readonly RsTableChartSeries[],
+  options: MapRsTableSeriesToEChartsOptions = {},
+): RsTableEChartsOption {
+  if (!seriesList.length) {
+    return { series: [] }
+  }
+
+  const allPie = seriesList.every((s) => s.kind === 'pie')
+  const tooltipTrigger =
+    options.tooltipTrigger ?? (allPie ? 'item' : 'axis')
+
+  if (allPie) {
+    return {
+      tooltip: { trigger: tooltipTrigger },
+      legend: { data: seriesList.flatMap((s) => s.categories) },
+      series: seriesList.map((s) => ({
+        id: s.id,
+        name: s.id,
+        type: 'pie' as const,
+        data: s.points.map((p) => ({ name: p.name, value: p.value })),
+      })),
+    }
+  }
+
+  const shared = options.sharedCategoryAxis !== false
+  const primary = seriesList[0]!
+  return {
+    tooltip: { trigger: tooltipTrigger },
+    legend: { data: seriesList.map((s) => s.id) },
+    xAxis: shared
+      ? { type: 'category', data: primary.categories }
+      : seriesList.map((s) => ({ type: 'category', data: s.categories })),
+    yAxis: { type: 'value' },
+    series: seriesList.map((s) => ({
+      id: s.id,
+      name: s.id,
+      type: mapKind(s.kind),
+      data: s.values,
+    })),
+  }
+}