niuma-ui 1.0.1 → 1.0.2

package/src/composables/createRsDialog.ts

@@ -0,0 +1,357 @@
+import { createApp, h, ref, type App } from 'vue'
+import RsConfigProvider from '../components/RsConfigProvider.vue'
+import RsConfirmDialog from '../components/RsConfirmDialog.vue'
+import RsDialog from '../components/RsDialog.vue'
+import type { RsConfirmOptions } from '../components/dialog-utils'
+import type { RsDialogBeforeClose, RsDialogCloseReason, RsDialogWidth } from '../components/dialog-utils'
+import type { RsFeedbackTone } from '../components/overlay-utils'
+import { defaultLocale, type RsLocale } from '../locale/types'
+import type { RsThemeMode } from '../theme/types'
+
+export type RsConfirmResult = boolean
+
+export type RsConfirmInput = RsConfirmOptions | string
+
+export interface RsDialogOpenOptions {
+  title?: string
+  subtitle?: string
+  description?: string
+  width?: RsDialogWidth
+  tone?: RsFeedbackTone
+  /**
+   * 布局。默认 window（工作窗）。
+   * confirm 仅作历史兼容；新代码的确认/提示请用 rsConfirm / RsConfirmDialog。
+   */
+  layout?: 'window' | 'confirm'
+  showOverlay?: boolean
+  /** 遮罩不透明度 0–1 */
+  overlayOpacity?: number
+  /** 遮罩模糊；number 为 px */
+  overlayBlur?: number | string
+  showClose?: boolean
+  closeOnOverlayClick?: boolean
+  closeOnEsc?: boolean
+  showFooter?: boolean
+  showCancel?: boolean
+  showConfirm?: boolean
+  cancelText?: string
+  confirmText?: string
+  confirmVariant?: 'primary' | 'danger'
+  autoCloseOnConfirm?: boolean
+  beforeClose?: RsDialogBeforeClose
+  teleportTo?: string | HTMLElement
+  /** 默认插槽对应 #body 的渲染函数 */
+  body?: () => unknown
+  footer?: () => unknown
+  onConfirm?: () => void | Promise<void>
+  onCancel?: () => void
+  onAfterClose?: (reason: RsDialogCloseReason) => void
+  /** 命令式挂载时覆盖主题；默认读 document data-rs-theme */
+  theme?: RsThemeMode
+  /** 命令式挂载时覆盖语言；默认读 document data-rs-locale */
+  locale?: RsLocale
+}
+
+export interface RsDialogHandle {
+  close: (reason?: RsDialogCloseReason) => Promise<boolean>
+  destroy: () => void
+}
+
+/** tone 快捷方法：可传完整选项或纯文案（作为 description） */
+export interface RsConfirmApi {
+  (options?: RsConfirmOptions): Promise<RsConfirmResult>
+  warning: (options?: RsConfirmInput) => Promise<RsConfirmResult>
+  danger: (options?: RsConfirmInput) => Promise<RsConfirmResult>
+  info: (options?: RsConfirmInput) => Promise<RsConfirmResult>
+  success: (options?: RsConfirmInput) => Promise<RsConfirmResult>
+  error: (options?: RsConfirmInput) => Promise<RsConfirmResult>
+  confirm: (options?: RsConfirmInput) => Promise<RsConfirmResult>
+}
+
+function readDomTheme(): RsThemeMode {
+  if (typeof document === 'undefined') return 'light'
+  return document.documentElement.getAttribute('data-rs-theme') === 'dark' ? 'dark' : 'light'
+}
+
+function readDomLocale(): RsLocale {
+  if (typeof document === 'undefined') return defaultLocale
+  const value = document.documentElement.getAttribute('data-rs-locale')
+  return value === 'en-US' || value === 'zh-CN' ? value : defaultLocale
+}
+
+function mountHost(
+  render: () => unknown,
+  config?: { theme?: RsThemeMode; locale?: RsLocale },
+): { app: App; container: HTMLDivElement; destroy: () => void } {
+  const container = document.createElement('div')
+  document.body.appendChild(container)
+
+  // themeScope=local：不覆盖主应用的 document 主题；Portal 仍靠页面已有 data-rs-theme。
+  // ConfigProvider 负责 provide locale，使命令式实例的 i18n 默认文案正确。
+  const theme = config?.theme ?? readDomTheme()
+  const locale = config?.locale ?? readDomLocale()
+
+  const app = createApp({
+    setup() {
+      return () =>
+        h(
+          RsConfigProvider,
+          { theme, locale, themeScope: 'local' },
+          { default: () => render() },
+        )
+    },
+  })
+  app.mount(container)
+  const destroy = () => {
+    app.unmount()
+    container.remove()
+  }
+  return { app, container, destroy }
+}
+
+function normalizeConfirmInput(
+  options: RsConfirmInput | undefined,
+  defaults: Partial<RsConfirmOptions>,
+): RsConfirmOptions {
+  if (typeof options === 'string') {
+    return { ...defaults, description: options }
+  }
+  return { ...defaults, ...(options ?? {}) }
+}
+
+/**
+ * 命令式确认框（基于 RsConfirmDialog）。
+ * resolve(true) 为确认，resolve(false) 为取消/关闭。
+ * 若传入 onConfirm 且返回 Promise，确认期间自动 loading，成功后关闭。
+ */
+function rsConfirmCore(options: RsConfirmOptions = {}): Promise<RsConfirmResult> {
+  return new Promise((resolve) => {
+    const open = ref(true)
+    const loading = ref(options.confirmLoading ?? false)
+    let settled = false
+    let confirmed = false
+    const hasAsyncConfirm = typeof options.onConfirm === 'function'
+
+    const settle = (value: boolean) => {
+      if (settled) return
+      settled = true
+      open.value = false
+      if (!value) options.onCancel?.()
+      // 等关闭帧后再销毁，避免动画被硬切
+      window.setTimeout(() => destroy(), 200)
+      resolve(value)
+    }
+
+    const { destroy } = mountHost(
+      () =>
+        h(
+          RsConfirmDialog,
+          {
+            open: open.value,
+            'onUpdate:open': (value: boolean) => {
+              open.value = value
+              if (!value) {
+                // 等同 tick 内的 confirm/cancel 事件先落定，避免 Action 关闭抢先 resolve(false)
+                queueMicrotask(() => settle(confirmed))
+              }
+            },
+            title: options.title,
+            subtitle: options.subtitle,
+            description: options.description,
+            tone: options.tone,
+            icon: options.icon,
+            width: options.width,
+            confirmText: options.confirmText,
+            cancelText: options.cancelText,
+            confirmVariant: options.confirmVariant,
+            showCancel: options.showCancel,
+            confirmLoading: loading.value,
+            beforeClose: options.beforeClose,
+            // 有异步 onConfirm 时由我们在结束后关闭，避免提前关掉
+            autoCloseOnConfirm: !hasAsyncConfirm,
+            showOverlay: options.showOverlay ?? true,
+            overlayOpacity: options.overlayOpacity,
+            overlayBlur: options.overlayBlur,
+            teleportTo: options.teleportTo === false ? false : options.teleportTo,
+            onConfirm: () => {
+              if (!hasAsyncConfirm) {
+                confirmed = true
+                return
+              }
+              loading.value = true
+              void Promise.resolve()
+                .then(() => options.onConfirm?.())
+                .then(() => {
+                  confirmed = true
+                  settle(true)
+                })
+                .catch(() => {
+                  loading.value = false
+                })
+            },
+            onCancel: () => {
+              confirmed = false
+            },
+          },
+          options.extra
+            ? {
+                extra: () => options.extra?.(),
+              }
+            : undefined,
+        ),
+      { theme: options.theme, locale: options.locale },
+    )
+  })
+}
+
+/**
+ * 命令式确认 / 提示 API。
+ * - rsConfirm(options) 基础调用
+ * - rsConfirm.warning / .danger / .confirm 双按钮确认
+ * - rsConfirm.info / .success / .error 默认单按钮提示（showCancel: false）
+ */
+export const rsConfirm: RsConfirmApi = Object.assign(rsConfirmCore, {
+  warning: (options?: RsConfirmInput) =>
+    rsConfirmCore(
+      normalizeConfirmInput(options, {
+        tone: 'danger',
+        confirmVariant: 'danger',
+        showOverlay: true,
+      }),
+    ),
+  danger: (options?: RsConfirmInput) =>
+    rsConfirmCore(
+      normalizeConfirmInput(options, {
+        tone: 'danger',
+        confirmVariant: 'danger',
+        showOverlay: true,
+      }),
+    ),
+  info: (options?: RsConfirmInput) =>
+    rsConfirmCore(
+      normalizeConfirmInput(options, {
+        tone: 'info',
+        confirmVariant: 'primary',
+        showCancel: false,
+        showOverlay: true,
+      }),
+    ),
+  success: (options?: RsConfirmInput) =>
+    rsConfirmCore(
+      normalizeConfirmInput(options, {
+        tone: 'success',
+        confirmVariant: 'primary',
+        showCancel: false,
+        showOverlay: true,
+      }),
+    ),
+  error: (options?: RsConfirmInput) =>
+    rsConfirmCore(
+      normalizeConfirmInput(options, {
+        tone: 'danger',
+        confirmVariant: 'danger',
+        showCancel: false,
+        showOverlay: true,
+      }),
+    ),
+  confirm: (options?: RsConfirmInput) =>
+    rsConfirmCore(
+      normalizeConfirmInput(options, {
+        tone: 'warning',
+        confirmVariant: 'primary',
+        showOverlay: true,
+      }),
+    ),
+})
+
+/**
+ * 命令式打开 RsDialog；适合临时表单/说明层。
+ * 确认/危险提示请用 rsConfirm，不要传 layout: 'confirm'。
+ * 复杂长期状态仍建议声明式使用组件。
+ */
+export function openRsDialog(options: RsDialogOpenOptions = {}): RsDialogHandle {
+  const open = ref(true)
+  let destroyed = false
+  let dialogExpose: { close?: (reason?: RsDialogCloseReason) => Promise<boolean> } | null = null
+  const layout = options.layout ?? 'window'
+
+  if (import.meta.env.DEV && layout === 'confirm') {
+    console.warn(
+      '[openRsDialog] layout:"confirm" 已弃用。确认/提示请使用 rsConfirm / RsConfirmDialog；本 API 仅用于工作窗/表单。',
+    )
+  }
+
+  const { destroy: unmount } = mountHost(
+    () =>
+      h(
+        RsDialog,
+        {
+          ref: (instance: unknown) => {
+            dialogExpose = instance as typeof dialogExpose
+          },
+          open: open.value,
+          'onUpdate:open': (value: boolean) => {
+            open.value = value
+            if (!value && !destroyed) {
+              window.setTimeout(() => destroy(), 200)
+            }
+          },
+          title: options.title,
+          description:
+            [options.subtitle, options.description].filter(Boolean).join('\n\n') ||
+            options.description,
+          width: options.width ?? 'md',
+          tone: options.tone,
+          layout,
+          resizable: layout === 'window',
+          fullscreenable: layout === 'window',
+          showOverlay: options.showOverlay ?? true,
+          overlayOpacity: options.overlayOpacity,
+          overlayBlur: options.overlayBlur,
+          showClose: options.showClose,
+          closeOnOverlayClick: options.closeOnOverlayClick,
+          closeOnEsc: options.closeOnEsc,
+          showFooter: options.showFooter ?? true,
+          showCancel: options.showCancel,
+          showConfirm: options.showConfirm,
+          cancelText: options.cancelText,
+          confirmText: options.confirmText,
+          confirmVariant: options.confirmVariant,
+          autoCloseOnConfirm: options.autoCloseOnConfirm ?? true,
+          beforeClose: options.beforeClose,
+          teleportTo: options.teleportTo,
+          deferBodyMount: false,
+          onConfirm: () => {
+            void options.onConfirm?.()
+          },
+          onCancel: () => {
+            options.onCancel?.()
+          },
+          onAfterClose: (reason: RsDialogCloseReason) => {
+            options.onAfterClose?.(reason)
+          },
+        },
+        {
+          body: options.body,
+          footer: options.footer,
+        },
+      ),
+    { theme: options.theme, locale: options.locale },
+  )
+
+  function destroy(): void {
+    if (destroyed) return
+    destroyed = true
+    unmount()
+  }
+
+  return {
+    async close(reason: RsDialogCloseReason = 'programmatic') {
+      if (destroyed) return false
+      if (dialogExpose?.close) return dialogExpose.close(reason)
+      open.value = false
+      return true
+    },
+    destroy,
+  }
+}

package/src/composables/createRsTableEditEmitBridge.ts

@@ -0,0 +1,38 @@
+/**
+ * 将 Vue emit 适配为 useRsTableEditActions 所需的 edit emit 袋。
+ */
+
+import type { EmitFn } from 'vue'
+import type { RsTableEmits } from '../components/table/rs-table-props'
+import type { RsTableRowData } from '../components/table-utils'
+import type { UseRsTableEditActionsOptions } from './useRsTableEditActions'
+
+type EditEmitBag<T extends RsTableRowData> = UseRsTableEditActionsOptions<T>['emit']
+
+/**
+ * 创建编辑 emit 桥（避免 RsTable 内联一长串箭头函数）。
+ *
+ * 入参用 Vue `EmitFn<RsTableEmits>`，与 `defineEmits` 产物对齐；
+ * 勿用手写 overload 接口承接（交叉重载在参数位逆变，会报 cellView ̸∈ update:columnOrder）。
+ */
+export function createRsTableEditEmitBridge<T extends RsTableRowData>(
+  emit: EmitFn<RsTableEmits<T>>,
+): EditEmitBag<T> {
+  return {
+    cellView: (row, column, index) => emit('cellView', row, column, index),
+    cellEditStart: (row, column, index) => emit('cellEditStart', row, column, index),
+    cellEditDialog: (row, column, index, draft) =>
+      emit('cellEditDialog', row, column, index, draft),
+    cellEditCommit: (row, column, index, value, previous) =>
+      emit('cellEditCommit', row, column, index, value, previous),
+    cellEditCancel: (row, column, index) => emit('cellEditCancel', row, column, index),
+    cellEditInvalid: (row, column, index, message, value) =>
+      emit('cellEditInvalid', row, column, index, message, value),
+    cellEditBatchCommit: (column, changes) => emit('cellEditBatchCommit', column, changes),
+    cellEditUndo: (entry) => emit('cellEditUndo', entry),
+    cellEditRedo: (entry) => emit('cellEditRedo', entry),
+    cellEditReject: (row, index, reason) => emit('cellEditReject', row, index, reason),
+    rowEditCommit: (row, index, changes) => emit('rowEditCommit', row, index, changes),
+    rowEditRollback: (row, index) => emit('rowEditRollback', row, index),
+  }
+}

package/src/composables/useRsLoadingBar.ts

@@ -0,0 +1,36 @@
+import { inject, type InjectionKey, type ShallowRef } from 'vue'
+
+export type RsLoadingBarApi = {
+  start: () => void
+  finish: () => void
+  error: () => void
+}
+
+export const RS_LOADING_BAR_KEY: InjectionKey<ShallowRef<RsLoadingBarApi | null>> =
+  Symbol('rs-loading-bar')
+
+/**
+ * useRsLoadingBar 读取最近的 RsLoadingBar 实例 API。
+ * 调用方须位于 RsLoadingBar 默认插槽的后代树中；
+ * 未挂载或未包裹时返回空操作实现，避免调用方崩溃。
+ */
+export function useRsLoadingBar(): RsLoadingBarApi {
+  const injected = inject(RS_LOADING_BAR_KEY, null)
+  const noop: RsLoadingBarApi = {
+    start() {},
+    finish() {},
+    error() {},
+  }
+  if (!injected) return noop
+  return {
+    start() {
+      injected.value?.start()
+    },
+    finish() {
+      injected.value?.finish()
+    },
+    error() {
+      injected.value?.error()
+    },
+  }
+}

package/src/composables/useRsTable.ts

@@ -0,0 +1,134 @@
+/**
+ * RsTable 公开面编排（对标 AG Grid api / TanStack table instance）。
+ *
+ * 职责：
+ * - FeatureHost：全局模块 + 实例 features 生命周期与贡献袋
+ * - RsTableApi：统一 create / provide，避免 expose 与 inject 漂移
+ *
+ * 内核装配（Columns / Engine / Virtual）见 useRsTableCore；本文件保持公开面轻量。
+ */
+
+import { inject, provide, type InjectionKey } from 'vue'
+import type { RsContextMenuItem } from '../components/context-menu-utils'
+import type { RsTableRowData } from '../components/table-utils'
+import {
+  createRsTableApi,
+  RS_TABLE_API_KEY,
+  type RsTableApi,
+} from '../components/table/rs-table-api'
+import {
+  createRsTableFeatureHost,
+  type RsTableFeatureHost,
+  type RsTableOverlayContribution,
+  type RsTableToolbarItem,
+} from '../components/table/rs-table-feature-host'
+import { resolveInstanceFeatures } from '../components/table/rs-table-module-registry'
+import {
+  createBuiltinTableFeatures,
+  type RsTableBuiltinFeatureId,
+  type RsTableFeature,
+} from '../components/table/table-features'
+import type { RsTableAnalyticsSnapshot } from './useRsTableSelectionSource'
+
+export type { RsTableApi }
+export { RS_TABLE_API_KEY, RS_TABLE_API_VERSION, isRsTableApi } from '../components/table/rs-table-api'
+export { RsTableModuleRegistry, resolveInstanceFeatures } from '../components/table/rs-table-module-registry'
+
+/**
+ * useRsTable 返回的公开面：Feature 宿主 + API 工厂。
+ */
+export interface UseRsTableSurface<T extends RsTableRowData = RsTableRowData> {
+  featureHost: RsTableFeatureHost<T>
+  /**
+   * 绑定内置 id + 实例/全局 features；返回 dispose。
+   * 应在 watch(immediate) 中调用，替换旧 dispose。
+   */
+  bindFeatures: (options: {
+    builtinIds: RsTableBuiltinFeatureId[]
+    instanceFeatures?: RsTableFeature<T>[] | null
+    getViewRows: () => T[]
+    getSelectedRows: () => T[]
+    getAnalyticsSnapshot: () => RsTableAnalyticsSnapshot<T>
+    subscribeAnalytics: (listener: (snap: RsTableAnalyticsSnapshot<T>) => void) => () => void
+  }) => () => void
+  /** 合并 props 自定义菜单与 feature 贡献 */
+  mergeContextMenuItems: (
+    baseItems: RsContextMenuItem[],
+    menuCtx: { row: T | null; selectedRows: T[] },
+  ) => RsContextMenuItem[]
+  /** 由内部实现装配冻结 API，并可选 provide */
+  createApi: (
+    impl: Omit<RsTableApi<T>, 'apiVersion' | 'getActiveFeatureIds'> & {
+      getActiveFeatureIds?: () => string[]
+    },
+    options?: { provide?: boolean },
+  ) => RsTableApi<T>
+  getActiveFeatureIds: () => string[]
+  /** 实例级 toolbar 贡献（多表互不共享） */
+  getToolbarItems: () => RsTableToolbarItem[]
+  /** 实例级 overlay 贡献 */
+  getOverlayContributions: () => RsTableOverlayContribution[]
+}
+
+/**
+ * 创建表格公开面（每个 RsTable 实例调用一次）。
+ */
+export function useRsTable<T extends RsTableRowData = RsTableRowData>(): UseRsTableSurface<T> {
+  const featureHost = createRsTableFeatureHost<T>()
+
+  function bindFeatures(options: {
+    builtinIds: RsTableBuiltinFeatureId[]
+    instanceFeatures?: RsTableFeature<T>[] | null
+    getViewRows: () => T[]
+    getSelectedRows: () => T[]
+    getAnalyticsSnapshot: () => RsTableAnalyticsSnapshot<T>
+    subscribeAnalytics: (listener: (snap: RsTableAnalyticsSnapshot<T>) => void) => () => void
+  }): () => void {
+    // 合并顺序：全局模块 → 内置 → 实例 features（同 id 后者覆盖）
+    const features = resolveInstanceFeatures<T>([
+      ...createBuiltinTableFeatures<T>(options.builtinIds),
+      ...(options.instanceFeatures ?? []),
+    ])
+    const ctx = featureHost.createContext({
+      getViewRows: options.getViewRows,
+      getSelectedRows: options.getSelectedRows,
+      getAnalyticsSnapshot: options.getAnalyticsSnapshot,
+      subscribeAnalytics: options.subscribeAnalytics,
+    })
+    return featureHost.setup(features, ctx)
+  }
+
+  function createApi(
+    impl: Omit<RsTableApi<T>, 'apiVersion' | 'getActiveFeatureIds'> & {
+      getActiveFeatureIds?: () => string[]
+    },
+    options?: { provide?: boolean },
+  ): RsTableApi<T> {
+    const api = createRsTableApi<T>({
+      ...impl,
+      getActiveFeatureIds: impl.getActiveFeatureIds ?? (() => featureHost.getActiveFeatureIds()),
+    })
+    if (options?.provide !== false) {
+      provide(RS_TABLE_API_KEY as InjectionKey<RsTableApi<T>>, api)
+    }
+    return api
+  }
+
+  return {
+    featureHost,
+    bindFeatures,
+    mergeContextMenuItems: (base, menuCtx) => featureHost.mergeContextMenuItems(base, menuCtx),
+    createApi,
+    getActiveFeatureIds: () => featureHost.getActiveFeatureIds(),
+    getToolbarItems: () => featureHost.getToolbarItems(),
+    getOverlayContributions: () => featureHost.getOverlayContributions(),
+  }
+}
+
+/**
+ * 子树内注入表格 API（插槽/子组件用）。
+ * 未 provide 时返回 undefined。
+ */
+export function useRsTableApi<T extends RsTableRowData = RsTableRowData>(): RsTableApi<T> | undefined {
+  return inject(RS_TABLE_API_KEY as InjectionKey<RsTableApi<T>>, undefined)
+}

package/src/composables/useRsTableA11y.ts

@@ -0,0 +1,52 @@
+/**
+ * RsTable 无障碍基线：region / grid 语义与 loading busy。
+ *
+ * 与 useRsTableGridKeyboard + 单元格 role=gridcell 配合，形成可漫游网格。
+ * tabindex 放在 role=grid 的 table 上（复合控件可聚焦），勿放在 region 壳层。
+ */
+
+import { computed, type ComputedRef, type Ref } from 'vue'
+
+export interface UseRsTableA11yOptions {
+  /** 显式无障碍名称；空则回退 defaultLabel */
+  ariaLabel: () => string | undefined
+  defaultLabel: () => string
+  loading: () => boolean
+  /** 业务行数（view / dataRows） */
+  rowCount: Ref<number> | ComputedRef<number> | (() => number)
+  /** 可见数据列数 */
+  colCount: Ref<number> | ComputedRef<number> | (() => number)
+}
+
+function read(source: Ref<number> | ComputedRef<number> | (() => number)): number {
+  return typeof source === 'function' ? source() : source.value
+}
+
+/**
+ * 壳层 / table 元素无障碍属性。
+ */
+export function useRsTableA11y(options: UseRsTableA11yOptions) {
+  const resolvedLabel = computed(
+    () => options.ariaLabel()?.trim() || options.defaultLabel(),
+  )
+
+  const shellA11y = computed(() => ({
+    role: 'region' as const,
+    'aria-label': resolvedLabel.value,
+    'aria-busy': options.loading() ? true : undefined,
+  }))
+
+  const tableA11y = computed(() => ({
+    role: 'grid' as const,
+    tabindex: 0,
+    'aria-rowcount': Math.max(0, read(options.rowCount)),
+    'aria-colcount': Math.max(0, read(options.colCount)),
+    'aria-label': resolvedLabel.value,
+  }))
+
+  return {
+    resolvedLabel,
+    shellA11y,
+    tableA11y,
+  }
+}

package/src/composables/useRsTableChartBridge.ts

@@ -0,0 +1,79 @@
+/**
+ * 表格图表桥：订阅 SelectionSource，产出库无关 chart series。
+ *
+ * 业务页可：
+ * - 把 series 丢给 ECharts option 组装
+ * - 或在图表点击时用 point.key 反查行做联动筛选
+ *
+ * 性能：series 随 sourceRows 浅引用变化重算；defs 建议业务侧稳定引用。
+ */
+
+import { computed, type ComputedRef, type Ref } from 'vue'
+import type { RsTableRowData } from '../components/table-utils'
+import {
+  buildTableChartSeriesList,
+  type RsTableChartSeries,
+  type RsTableChartSeriesDef,
+} from '../components/table/table-chart-utils'
+import {
+  useRsTableSelectionSource,
+  type RsTableAnalyticsSnapshot,
+} from './useRsTableSelectionSource'
+
+export interface UseRsTableChartBridgeOptions<T extends RsTableRowData> {
+  viewRows: Ref<T[]> | ComputedRef<T[]>
+  selectedRows?: Ref<T[]> | ComputedRef<T[]>
+  /** 系列定义列表；变化会触发重算 */
+  seriesDefs: Ref<RsTableChartSeriesDef[]> | ComputedRef<RsTableChartSeriesDef[]> | RsTableChartSeriesDef[]
+}
+
+function readDefs(
+  defs:
+    | Ref<RsTableChartSeriesDef[]>
+    | ComputedRef<RsTableChartSeriesDef[]>
+    | RsTableChartSeriesDef[],
+): RsTableChartSeriesDef[] {
+  if (Array.isArray(defs)) return defs
+  return defs.value ?? []
+}
+
+/**
+ * 选中联动图表桥。
+ *
+ * @returns selection 源 + series 列表 + getSnapshot
+ */
+export function useRsTableChartBridge<T extends RsTableRowData>(
+  options: UseRsTableChartBridgeOptions<T>,
+) {
+  const selection = useRsTableSelectionSource<T>({
+    viewRows: options.viewRows,
+    selectedRows: options.selectedRows,
+  })
+
+  const series = computed<RsTableChartSeries[]>(() =>
+    buildTableChartSeriesList(selection.sourceRows.value, readDefs(options.seriesDefs)),
+  )
+
+  /** 按 id 取单系列，便于模板绑定 */
+  function getSeriesById(id: string): RsTableChartSeries | undefined {
+    return series.value.find((item) => item.id === id)
+  }
+
+  function getSnapshot(): RsTableAnalyticsSnapshot<T> & { series: RsTableChartSeries[] } {
+    return {
+      ...selection.getSnapshot(),
+      series: series.value,
+    }
+  }
+
+  return {
+    ...selection,
+    series,
+    getSeriesById,
+    getSnapshot,
+  }
+}
+
+export type RsTableChartBridgeApi<T extends RsTableRowData> = ReturnType<
+  typeof useRsTableChartBridge<T>
+>