create-react-admin-template 0.0.0-stage → 0.1.0

package/template/src/components/AppTable/engine/component/resolver.ts

@@ -0,0 +1,272 @@
+import type { TablePaginationConfig } from '../pagination'
+import type { PreferenceStore } from '../preference'
+import {
+  resolveTableSearchConditions,
+  type TableSearchCondition,
+  type TableSearchResetBehavior,
+} from '../search'
+import type { TableRowSelectionConfig } from '../selection'
+import {
+  resolveTableKey,
+  type TableDensity,
+  type TableFeedbackOptions,
+  type TableLoadingMaskMode,
+  type TableRow,
+  type TableTheme,
+} from '../shared'
+import type { TableExportConfig } from '../summary'
+import type { GridSettings, TableHeight } from '../table'
+import type { TableToolbarButton } from '../toolbar'
+import type { ResolvedTableComponentProps, TableComponentProps } from './types'
+
+/**
+ * AppTable 配置解析器使用的完整默认值合同。
+ *
+ * 数组和对象使用工厂函数，保证每个表格实例拥有独立引用；标量值可由所有实例共享。
+ */
+export interface TableComponentDefaults {
+  /** 创建实例的初始行数据，默认返回新的空数组。 */
+  data: <T extends TableRow>() => T[]
+  /** 创建搜索条件集合，默认返回新的空数组。 */
+  searchConditions: () => TableSearchCondition[]
+  /** 点击重置后是否立即查询，默认 `query`。 */
+  searchResetBehavior: TableSearchResetBehavior
+  /** 创建工具栏业务按钮集合，默认返回新的空数组。 */
+  buttons: <T extends TableRow>() => TableToolbarButton<T>[]
+  /** 配置查询处理器后是否在挂载时自动查询，默认 `true`。 */
+  autoQuery: boolean
+  /** 创建行选择交互选项，默认返回新的空配置。 */
+  selectionOptions: <T extends TableRow>() => TableRowSelectionConfig<T>
+  /** 是否显示左侧业务行号，默认 `true`。 */
+  showIndex: boolean
+  /** 业务列未指定宽度时使用的列宽，默认 `120`。 */
+  defaultColumnWidth: number | string
+  /** 是否显示隔行底色，默认 `true`。 */
+  striped: boolean
+  /** 是否高亮当前点击行，默认 `true`。 */
+  highlightCurrentRow: boolean
+  /** 普通列表头菜单的显示方式，默认 `always`。 */
+  headerMenuTrigger: 'always' | 'hover' | 'hidden'
+  /** 是否自动冻结逻辑起始侧的连续操作列，默认 `false`。 */
+  autoFreezeStartActions: boolean
+  /** 是否自动冻结逻辑结束侧的连续操作列，默认 `true`。 */
+  autoFreezeEndActions: boolean
+  /** 是否汇总框选区域中的数值单元格，默认 `true`。 */
+  summarySelected: boolean
+  /** 是否允许单次编辑事务修改多个单元格，默认 `false`。 */
+  allowBulkEdit: boolean
+  /** 查询、筛选或翻页后是否保留选择，默认 `false`。 */
+  keepSelection: boolean
+  /** 是否渲染工具栏，默认 `true`。 */
+  showToolbar: boolean
+  /** 是否显示列设置入口，默认 `true`。 */
+  showColumnEditor: boolean
+  /** 是否显示密度切换入口，默认 `true`。 */
+  showDensityControl: boolean
+  /** 创建分页配置，默认返回启用标准分页的空配置。 */
+  pagination: () => TablePaginationConfig
+  /** 创建导出配置，默认返回启用标准导出的空配置。 */
+  exportOptions: <T extends TableRow>() => TableExportConfig<T>
+  /** 创建空状态和查询错误反馈配置，默认返回新的空配置。 */
+  feedback: () => TableFeedbackOptions
+  /** 查询期间的表格遮罩策略，默认 `initial`。 */
+  loadingMask: TableLoadingMaskMode
+  /** 创建透传给 Handsontable 的原生设置，默认返回新的空配置。 */
+  settings: () => GridSettings
+  /** 表格主题，默认 `auto`，跟随应用明暗主题。 */
+  theme: TableTheme
+  /** 表格行高密度，默认 `comfortable`。 */
+  density: TableDensity
+  /** 数字、日期、汇总和导出的区域语言，默认 `zh-CN`。 */
+  locale: string
+  /** 创建 Handsontable 许可证 key；应用入口会覆盖默认评估标识。 */
+  licenseKey: () => string
+  /** 网格高度策略，默认按内容收缩。 */
+  height: TableHeight
+}
+
+interface TableComponentResolverDefaults<T extends TableRow> {
+  /** 当前表格实例独立持有的默认业务行数组。 */
+  data: T[]
+  /** 当前 tableKey 没有偏好时依次尝试迁移的历史 key。 */
+  legacyTableKeys: string[]
+  /** 当前实例独立持有的 Handsontable 原生设置。 */
+  settings: GridSettings
+  /** 已创建但尚未合并业务配置的默认搜索条件。 */
+  searchConditions: TableSearchCondition[]
+  /** 当前实例独立持有的空状态和错误反馈配置。 */
+  feedback: TableFeedbackOptions
+  /** 当前实例独立持有的行选择交互配置。 */
+  selectionOptions: TableRowSelectionConfig<T>
+  /** 当前实例独立持有的工具栏业务按钮。 */
+  buttons: TableToolbarButton<T>[]
+  /** 当前实例独立持有的分页配置。 */
+  pagination: TablePaginationConfig
+  /** 当前实例独立持有的导出配置。 */
+  exportOptions: TableExportConfig<T>
+}
+
+interface TableComponentResolverCache {
+  /** 上次解析时使用的搜索条件数组引用。 */
+  searchConditionsSource?: readonly TableSearchCondition[]
+  /** 上次解析时使用的搜索默认值对象引用。 */
+  searchDefaultsSource?: unknown
+  /** 根据条件与默认值解析后的稳定搜索条件数组。 */
+  searchConditions?: TableSearchCondition[]
+  /** 上次解析时使用的偏好配置引用。 */
+  preferenceSource?: unknown
+  /** 归一化后的偏好存储配置；`false` 表示禁用偏好。 */
+  preference:
+    | false
+    | {
+        /** 实际执行偏好读写的存储实现。 */
+        store?: PreferenceStore
+        /** 用户、租户或角色维度的偏好隔离标识。 */
+        userScope?: string
+      }
+}
+
+const createResolverDefaults = <T extends TableRow>(
+  componentDefaults: TableComponentDefaults
+): TableComponentResolverDefaults<T> => ({
+  data: componentDefaults.data<T>(),
+  legacyTableKeys: [],
+  settings: componentDefaults.settings(),
+  searchConditions: componentDefaults.searchConditions(),
+  feedback: componentDefaults.feedback(),
+  selectionOptions: componentDefaults.selectionOptions<T>(),
+  buttons: componentDefaults.buttons<T>(),
+  pagination: componentDefaults.pagination(),
+  exportOptions: componentDefaults.exportOptions<T>(),
+})
+
+/** 将业务分组配置不可变地解析为适配器内部运行态。 */
+const resolveWithDefaults = <T extends TableRow>(
+  { tableKey, controller, config }: Readonly<TableComponentProps<T>>,
+  componentDefaults: TableComponentDefaults,
+  defaults: TableComponentResolverDefaults<T>,
+  cache: TableComponentResolverCache
+): ResolvedTableComponentProps<T> => {
+  const table = config.table
+  const search = config.search === false ? null : (config.search ?? {})
+  const query = config.query === false ? null : (config.query ?? {})
+  const editing = config.editing === false ? null : (config.editing ?? {})
+  const selection =
+    config.selection === false || config.selection === undefined
+      ? null
+      : config.selection
+  const toolbar = config.toolbar === false ? null : (config.toolbar ?? {})
+  const reporting = config.reporting === false ? null : (config.reporting ?? {})
+  const appearance = config.appearance ?? {}
+  const panels = config.panels === false ? null : (config.panels ?? {})
+  const preference = config.preference
+  const searchConditionsSource = search?.conditions ?? defaults.searchConditions
+  if (
+    cache.searchConditionsSource !== searchConditionsSource ||
+    cache.searchDefaultsSource !== search?.defaults
+  ) {
+    cache.searchConditionsSource = searchConditionsSource
+    cache.searchDefaultsSource = search?.defaults
+    cache.searchConditions = resolveTableSearchConditions(
+      searchConditionsSource,
+      {},
+      search?.defaults
+    )
+  }
+  if (cache.preferenceSource !== preference) {
+    cache.preferenceSource = preference
+    cache.preference =
+      preference === false
+        ? false
+        : { store: preference?.store, userScope: preference?.userScope }
+  }
+  return {
+    tableKey: resolveTableKey(tableKey),
+    controller,
+    runtime: config.runtime?.handsontable,
+    legacyTableKeys:
+      preference === false
+        ? defaults.legacyTableKeys
+        : (preference?.legacyKeys ?? defaults.legacyTableKeys),
+    preference: cache.preference,
+    columns: table.columns,
+    dataConfigured: table.data !== undefined,
+    data: table.data ?? defaults.data,
+    settings: table.settings ?? defaults.settings,
+    headerGroups: table.headerGroups,
+    autoMerge: table.autoMerge,
+    mergeCells: table.mergeCells,
+    showIndex: table.showIndex ?? componentDefaults.showIndex,
+    striped: table.striped ?? componentDefaults.striped,
+    highlightCurrentRow:
+      table.highlightCurrentRow ?? componentDefaults.highlightCurrentRow,
+    headerMenuTrigger:
+      table.headerMenuTrigger ?? componentDefaults.headerMenuTrigger,
+    autoFreezeStartActions:
+      table.autoFreezeStartActions ?? componentDefaults.autoFreezeStartActions,
+    fixedColumnsEnd: table.fixedColumnsEnd,
+    autoFreezeEndActions:
+      table.autoFreezeEndActions ?? componentDefaults.autoFreezeEndActions,
+    defaultColumnWidth:
+      table.defaultColumnWidth ?? componentDefaults.defaultColumnWidth,
+    height: table.height ?? componentDefaults.height,
+    showSearch: search !== null,
+    searchConditions: cache.searchConditions!,
+    searchResetBehavior:
+      search?.resetBehavior ?? componentDefaults.searchResetBehavior,
+    searchLayout: search?.layout,
+    beforeSearchSubmit: search?.beforeSubmit,
+    query: query?.handler,
+    autoQuery: query ? (query.auto ?? componentDefaults.autoQuery) : false,
+    loadingMask: query?.loadingMask ?? componentDefaults.loadingMask,
+    feedback: query ? (query.feedback ?? defaults.feedback) : false,
+    commitChanges: editing?.commitChanges,
+    getRowVersion: editing?.getRowVersion,
+    rowKey: editing?.rowKey,
+    allowBulkEdit: editing?.allowBulkEdit ?? componentDefaults.allowBulkEdit,
+    resolveCell: editing?.resolveCell,
+    selectable: selection?.enabled ?? Boolean(selection),
+    selectionOptions: selection?.options ?? defaults.selectionOptions,
+    keepSelection:
+      selection?.keepAcrossQuery ?? componentDefaults.keepSelection,
+    summarySelected:
+      selection?.summarySelectedCells ?? componentDefaults.summarySelected,
+    getQuerySelectionToken: selection?.getQueryToken,
+    showToolbar: toolbar
+      ? (toolbar.visible ?? componentDefaults.showToolbar)
+      : false,
+    buttons: toolbar?.buttons ?? defaults.buttons,
+    showColumnEditor:
+      toolbar?.columnEditor ?? componentDefaults.showColumnEditor,
+    showDensityControl:
+      toolbar?.densityControl ?? componentDefaults.showDensityControl,
+    pagination: config.pagination ?? defaults.pagination,
+    summary: reporting?.summary ?? false,
+    exportOptions: reporting
+      ? (reporting.export ?? defaults.exportOptions)
+      : false,
+    density: appearance.density ?? componentDefaults.density,
+    theme: appearance.theme ?? componentDefaults.theme,
+    locale: appearance.locale ?? componentDefaults.locale,
+    timeZone: appearance.timeZone,
+    bottomPanel: panels === null ? false : panels.bottom,
+    rightPanel: panels === null ? false : panels.right,
+    rowDetailPanel: panels === null ? false : panels.rowDetail,
+    licenseKey: config.runtime?.licenseKey ?? componentDefaults.licenseKey(),
+  }
+}
+
+/**
+ * 创建组件实例级配置解析器。
+ *
+ * 缺省集合与对象在同一组件生命周期内保持引用稳定，避免任意配置变化被误判为
+ * selection、feedback 或 Handsontable settings 变化；不同表实例仍拥有独立默认值。
+ */
+export const createTableEnginePropsResolver = <T extends TableRow>(
+  componentDefaults: TableComponentDefaults
+) => {
+  const defaults = createResolverDefaults<T>(componentDefaults)
+  const cache: TableComponentResolverCache = { preference: {} }
+  return (props: Readonly<TableComponentProps<T>>) =>
+    resolveWithDefaults(props, componentDefaults, defaults, cache)
+}

package/template/src/components/AppTable/engine/component/types.ts

@@ -0,0 +1,384 @@
+import type { TableBottomPanelConfig } from '../bottom'
+import type { TableColumn } from '../columns'
+import type { TablePaginationConfig } from '../pagination'
+import type { PreferenceStore } from '../preference'
+import type { TableRightPanelConfig } from '../right'
+import type {
+  TableQuery,
+  TableQueryParams,
+  TableSearchConditionDefaults,
+  TableSearchCondition,
+  TableSearchResetBehavior,
+  TableSearchSubmitInterceptor,
+} from '../search'
+import type { TableRowSelectionConfig } from '../selection'
+import type {
+  TableDensity,
+  TableFeedbackOptions,
+  TableKeyOf,
+  TableLoadingMaskMode,
+  TableRow,
+  TableTheme,
+} from '../shared'
+import type { TableExportConfig, TableSummaryConfig } from '../summary'
+import type {
+  ChangeSetHandler,
+  GridSettings,
+  TableAutoMergeConfig,
+  TableCellMetaContext,
+  TableCellMetaResult,
+  TableController,
+  TableHeaderGroup,
+  TableMergeCellsResolver,
+  TableHeight,
+  TableRuntimeOptions,
+} from '../table'
+import type { TableToolbarButton } from '../toolbar'
+
+/** 表格网格本身的配置，不包含筛选区、远程查询和工具栏。 */
+export interface TableGridConfig<T extends TableRow = TableRow> {
+  /**
+   * 表格的完整列定义。每列通过稳定 key 对应后端 DTO 字段，并在这里配置标题、宽度、
+   * 显示、编辑、校验、格式化和操作按钮等行为。
+   */
+  columns: TableColumn<T>[]
+  /** 本地初始行数据；远程查询成功后会由查询结果替换，默认空数组。 */
+  data?: T[]
+  /** 透传的 Handsontable 原生设置；组件托管的关键设置最终仍由 engine 覆盖。 */
+  settings?: GridSettings
+  /** 使用稳定列 key 声明多级表头分组，并可开启官方折叠控件。 */
+  headerGroups?: TableHeaderGroup[]
+  /** 按相邻相同字段自动纵向合并；false 表示显式关闭。 */
+  autoMerge?: false | TableAutoMergeConfig<T>
+  /** 任意动态合并纯函数；声明后优先于 autoMerge 和原生 settings.mergeCells。 */
+  mergeCells?: false | TableMergeCellsResolver<T>
+  /** 是否显示左侧业务行号，默认 true。 */
+  showIndex?: boolean
+  /** 是否显示隔行底色，默认 true。 */
+  striped?: boolean
+  /** 是否高亮当前点击行，默认 true。 */
+  highlightCurrentRow?: boolean
+  /** 普通列表头菜单的显示方式，默认 always；操作列和选择列不会显示菜单。 */
+  headerMenuTrigger?: 'always' | 'hover' | 'hidden'
+  /** 是否自动冻结逻辑起始侧连续操作列，默认 false。 */
+  autoFreezeStartActions?: boolean
+  /** 固定逻辑结束侧的可视列数量；显式传 0 会关闭尾部自动冻结。 */
+  fixedColumnsEnd?: number
+  /** 未设置 fixedColumnsEnd 时是否自动冻结尾部连续操作列，默认 true。 */
+  autoFreezeEndActions?: boolean
+  /** 普通业务列未声明 width 时的统一宽度，列自身配置和用户偏好优先。 */
+  defaultColumnWidth?: number | string
+  /** 表格网格高度策略：按内容收缩、填满父容器或固定像素，默认 content。 */
+  height?: TableHeight
+}
+
+/** 页面筛选区配置；条件和布局偏好不与远程查询函数混在一起。 */
+export interface TableSearchConfig {
+  /** 查询条件声明；数组顺序作为首次展示顺序，并可由用户偏好覆盖。 */
+  conditions?: TableSearchCondition[]
+  /** 为同一张表的文本匹配和日期范围提供统一默认值，单个 condition 配置优先。 */
+  defaults?: TableSearchConditionDefaults
+  /** 筛选区标签宽度、折叠高度和展开能力。 */
+  layout?: TableSearchLayoutConfig
+  /** 默认 query；clear 可保留旧版“重置只清空条件”的业务行为。 */
+  resetBehavior?: TableSearchResetBehavior
+  /** 可取消或改写搜索按钮产生的查询；返回 false 时业务可完全接管。 */
+  beforeSubmit?: TableSearchSubmitInterceptor
+}
+
+export interface TableSearchLayoutConfig {
+  /** 筛选表单 label 宽度，默认 auto，长中文标题不会被固定 64px 截断。 */
+  labelWidth?: number | string
+  /** 是否允许展开溢出的查询条件，默认 true。 */
+  expandable?: boolean
+  /** 折叠状态字段区高度；用于判断真实溢出并决定是否显示展开入口。 */
+  collapsedHeight?: number | string
+  /** 展开浮层最大高度，超出后在筛选区内部滚动。 */
+  maxExpandedHeight?: number
+}
+
+/** 数据查询配置，独立于筛选区 UI。 */
+export interface TableDataQueryConfig<T extends TableRow = TableRow> {
+  /** 本地或远程查询函数；收到分页、条件、排序及可取消请求上下文。 */
+  handler?: TableQuery<T>
+  /** 挂载完成后是否自动执行首次查询，配置 query 时默认 true。 */
+  auto?: boolean
+  /** 查询期间的遮罩策略；默认 initial，仅首次空数据查询使用整表遮罩。 */
+  loadingMask?: TableLoadingMaskMode
+  /** 空状态、错误通知和重试文案；false 表示关闭组件内反馈 UI。 */
+  feedback?: false | TableFeedbackOptions
+}
+
+export interface TableEditingConfig<T extends TableRow = TableRow> {
+  /** 稳定行主键字段，供选择、脏数据、校验和冲突定位使用，默认 id。 */
+  rowKey?: TableKeyOf<T>
+  /** 显式保存回调；未提供时表格只在本地维护修改状态。 */
+  commitChanges?: ChangeSetHandler<T>
+  /** 返回后端乐观锁版本，保存冲突时用于识别过期修改。 */
+  getRowVersion?: (row: T) => string | number | undefined
+  /** 是否允许一次粘贴、填充或编辑事务修改多个单元格，默认 false。 */
+  allowBulkEdit?: boolean
+  /** 按行列上下文动态补充只读、renderer 和 className 等单元格元数据。 */
+  resolveCell?: (
+    context: TableCellMetaContext<T>
+  ) => TableCellMetaResult | undefined
+}
+
+export interface TableSelectionConfig<T extends TableRow = TableRow> {
+  /** 是否显示选择列并启用行选择状态机，默认 false。 */
+  enabled?: boolean
+  /** 多选、页全选、点击行、拖动范围和禁选行等选择交互策略。 */
+  options?: TableRowSelectionConfig<T>
+  /** 查询、筛选或翻页后是否保留显式选择，默认 false。 */
+  keepAcrossQuery?: boolean
+  /** 是否在单元格框选结束后计算数字合计，默认 true。 */
+  summarySelectedCells?: boolean
+  /** 为“选择全部匹配数据”生成后端不可变查询令牌。 */
+  getQueryToken?: TableQuerySelectionTokenProvider
+}
+
+export interface TableQuerySelectionTokenContext {
+  /** 当前令牌请求；查询切换、配置切换或组件卸载时会被取消。 */
+  signal: AbortSignal
+  /** 发起请求时的不可变查询签名，服务端可用于诊断。 */
+  querySignature: string
+}
+
+export type TableQuerySelectionTokenProvider = (
+  params: TableQueryParams,
+  context?: TableQuerySelectionTokenContext
+) => string | Promise<string>
+
+export interface TableToolbarConfig<T extends TableRow = TableRow> {
+  /** 是否显示工具栏，默认 true；将 toolbar 设为 false 可整体关闭。 */
+  visible?: boolean
+  /** 左侧业务操作按钮，回调会收到已加载的选中行和完整选择状态。 */
+  buttons?: TableToolbarButton<T>[]
+  /** 是否显示列显隐、排序和冻结设置入口，默认 true。 */
+  columnEditor?: boolean
+  /** 是否显示表格密度切换入口，默认 true。 */
+  densityControl?: boolean
+}
+
+export interface TableReportingConfig<T extends TableRow = TableRow> {
+  /** 表格底部汇总行配置；false 表示不创建汇总能力。 */
+  summary?: TableSummaryConfig<T> | false
+  /** CSV/XLSX 导出配置；false 表示不显示导出入口。 */
+  export?: TableExportConfig<T> | false
+}
+
+export interface TableAppearanceConfig {
+  /** 初始行高密度，已保存的用户偏好优先；默认 comfortable。 */
+  density?: TableDensity
+  /** Handsontable 主题或实例级主题覆盖；默认 auto 跟随页面暗黑模式。 */
+  theme?: TableTheme
+  /** 数字、日期、汇总和导出共享的区域语言，默认 zh-CN。 */
+  locale?: string
+  /** 日期显示、汇总和导出共享的 IANA 时区。 */
+  timeZone?: string
+}
+
+export type TableRowDetailPlacement = 'bottom' | 'right'
+
+/** 行详情面板只描述打开策略，具体内容统一由 `detail` slot 提供。 */
+export interface TableRowDetailPanelConfig {
+  /** 旧版默认从表格底部展开；业务需要时可切换为右侧。 */
+  placement?: TableRowDetailPlacement
+  /** 默认双击任意数据单元格打开；设为 false 后仅允许命令式打开。 */
+  openOnDoubleClick?: boolean
+  /** 详情面板标题，默认“详情”。 */
+  title?: string
+  /** 是否在面板标题栏显示关闭按钮，默认 true。 */
+  closable?: boolean
+}
+
+export interface TablePanelsConfig {
+  /** 表格底部工作区；false 表示不渲染。 */
+  bottom?: false | TableBottomPanelConfig
+  /** 表格右侧工作区；false 表示不渲染。 */
+  right?: false | TableRightPanelConfig
+  /** 行详情的打开位置与触发方式。 */
+  rowDetail?: false | TableRowDetailPanelConfig
+}
+
+export interface TablePreferenceConfig {
+  /** 用户偏好存储实现；默认使用浏览器本地存储。挂载后变更需通过 key 重建组件。 */
+  store?: PreferenceStore
+  /** 偏好命名空间中的用户隔离标识；属于实例身份，挂载后不可热切换。 */
+  userScope?: string
+  /** 当前 tableKey 无数据时按顺序尝试迁移的历史 key；仅在首次加载时读取。 */
+  legacyKeys?: string[]
+}
+
+/** 业务页面唯一配置对象；每个一级字段对应一个独立功能区域。 */
+export interface TableConfiguration<T extends TableRow = TableRow> {
+  /** 网格、列和数据配置；这是唯一必填的功能域。 */
+  table: TableGridConfig<T>
+  /** 筛选区配置；false 表示不渲染筛选区。 */
+  search?: false | TableSearchConfig
+  /** 查询流程配置；false 表示仅使用本地 data。 */
+  query?: false | TableDataQueryConfig<T>
+  /** 编辑、保存、校验身份和批量修改策略；false 表示关闭显式编辑事务。 */
+  editing?: false | TableEditingConfig<T>
+  /** 行选择配置；false 或省略表示不显示选择列。 */
+  selection?: false | TableSelectionConfig<T>
+  /** 工具栏配置；false 表示不渲染工具栏。 */
+  toolbar?: false | TableToolbarConfig<T>
+  /** 分页配置；false 只隐藏分页交互，数据加载策略仍为 page。 */
+  pagination?: false | TablePaginationConfig
+  /** 汇总和导出配置；false 表示关闭整个报表域。 */
+  reporting?: false | TableReportingConfig<T>
+  /** 密度、主题、区域语言和时区配置。 */
+  appearance?: TableAppearanceConfig
+  /** 底部、右侧及行详情工作区配置；false 表示不渲染扩展面板。 */
+  panels?: false | TablePanelsConfig
+  /** 用户个性化存储和旧 key 迁移配置；false 表示禁用偏好持久化。 */
+  preference?: false | TablePreferenceConfig
+  /** 仅承载 Handsontable 运行时模块和许可证，不放业务功能配置。 */
+  runtime?: {
+    /** 项目自定义 Handsontable 扩展模块；官方模块由 engine 统一完整注册。 */
+    handsontable?: TableRuntimeOptions
+    /** Handsontable 许可证 key；省略时使用评估标识，商业生产环境必须由应用显式注入。 */
+    licenseKey?: string
+  }
+}
+
+/** 框架适配组件公开 Props：实例身份与分组配置分离。 */
+export interface TableComponentProps<T extends TableRow = TableRow> {
+  /** 稳定实例身份，用于偏好、缓存、查询令牌和诊断；同一页面必须唯一。 */
+  tableKey: string
+  /** 外部创建的纯 JS 控制器；属于实例身份，挂载后变更需通过框架实例 key 重建。 */
+  controller?: TableController<T>
+  /**
+   * 外层布局正在连续改变表格可用尺寸。启用时暂停尺寸重算，恢复为 false 后精确刷新一次；
+   * 该状态是宿主 UI 的瞬态信号，不会进入业务配置或偏好持久化。
+   */
+  layoutTransitioning?: boolean
+  /** 按功能域组织的完整业务配置。 */
+  config: TableConfiguration<T>
+}
+
+/** 组件内部运行态；公共分组配置只允许通过 resolver 生成该结构。 */
+export interface ResolvedTableComponentProps<T extends TableRow = TableRow> {
+  /** 稳定的偏好/诊断身份，不从路由生成。 */
+  tableKey: string
+  /** 当前 key 无偏好时依次尝试迁移的旧 tableId/组件名。 */
+  legacyTableKeys?: string[]
+  /** 偏好持久化配置；false 表示彻底禁用。 */
+  preference:
+    | false
+    | {
+        /** 偏好读写适配器；省略时使用本地存储。 */
+        store?: PreferenceStore
+        /** 用户、租户或角色隔离域。 */
+        userScope?: string
+      }
+  /** 推荐由 useTable() 提供；低层直接使用时可以省略并由组件内部创建。 */
+  controller?: TableController<T>
+  /** 仅用于组件内部创建的 controller；外部 controller 使用其创建时的 runtime。 */
+  runtime?: TableRuntimeOptions
+  /** 已解析的业务列集合。 */
+  columns: TableColumn<T>[]
+  /** 业务是否显式提供 table.data；外部 Controller 省略时保留自身数据。 */
+  dataConfigured: boolean
+  /** 按稳定列 key 声明的框架无关分组，编译为 v18 NestedHeaders。 */
+  headerGroups?: TableHeaderGroup[]
+  /** 框架无关的相邻行合并规则，编译为 Handsontable mergeCells。 */
+  autoMerge?: false | TableAutoMergeConfig<T>
+  /** 动态合并单元格解析函数；优先级高于 autoMerge。 */
+  mergeCells?: false | TableMergeCellsResolver<T>
+  /** 底部工作区配置。 */
+  bottomPanel?: false | TableBottomPanelConfig
+  /** 右侧工作区配置。 */
+  rightPanel?: false | TableRightPanelConfig
+  /** 行详情面板的打开位置与行为。 */
+  rowDetailPanel?: false | TableRowDetailPanelConfig
+  /** 归一化后的本地或远程查询函数。 */
+  query?: TableQuery<T>
+  /** 为“选择全部查询结果”创建不可变后端快照。 */
+  getQuerySelectionToken?: TableQuerySelectionTokenProvider
+  /** 提供后开启显式保存事务。 */
+  commitChanges?: ChangeSetHandler<T>
+  /** 返回后端乐观锁版本。 */
+  getRowVersion?: (row: T) => string | number | undefined
+  /** 初始本地数据。 */
+  data: T[]
+  /** 是否启用搜索区域；false 时自定义 search slot 也不会渲染。 */
+  showSearch: boolean
+  /** 已声明的筛选条件。 */
+  searchConditions: TableSearchCondition[]
+  /** 搜索重置行为。 */
+  searchResetBehavior: TableSearchResetBehavior
+  /** 搜索区布局参数。 */
+  searchLayout?: TableSearchLayoutConfig
+  /** 搜索提交前拦截器。 */
+  beforeSearchSubmit?: TableSearchSubmitInterceptor
+  /** 工具栏业务按钮。 */
+  buttons: TableToolbarButton<T>[]
+  /** 是否在挂载后自动查询。 */
+  autoQuery: boolean
+  /** 是否启用行选择列。 */
+  selectable: boolean
+  /** 行选择具体交互策略。 */
+  selectionOptions: TableRowSelectionConfig<T>
+  /** 是否显示业务行号。 */
+  showIndex: boolean
+  /** 是否显示隔行底色。 */
+  striped: boolean
+  /** 是否高亮当前点击行。 */
+  highlightCurrentRow: boolean
+  /** 普通列表头菜单展示方式；选择列表头始终不显示菜单。 */
+  headerMenuTrigger: 'always' | 'hover' | 'hidden'
+  /** 自动冻结逻辑起始侧连续操作列，默认 true。 */
+  autoFreezeStartActions: boolean
+  /**
+   * 固定指定数量的逻辑结束侧可视列；显式传 0 会同时关闭尾部操作列自动固定。
+   */
+  fixedColumnsEnd?: number
+  /** 自动固定逻辑结束侧连续操作列，默认 true。 */
+  autoFreezeEndActions: boolean
+  /** 未声明列宽时使用的统一宽度。 */
+  defaultColumnWidth: number | string
+  /** 是否对框选数字单元格计算合计。 */
+  summarySelected: boolean
+  /** 安全默认值：一次粘贴/填充/编辑事务最多修改一个单元格。 */
+  allowBulkEdit: boolean
+  /** 查询、筛选或翻页后是否保留选择。 */
+  keepSelection: boolean
+  /** 稳定行主键字段。 */
+  rowKey?: TableKeyOf<T>
+  /** 是否渲染工具栏。 */
+  showToolbar: boolean
+  /** 是否显示列设置入口。 */
+  showColumnEditor: boolean
+  /** 是否显示密度切换入口。 */
+  showDensityControl: boolean
+  /** 分页配置；false 表示关闭分页。 */
+  pagination: TablePaginationConfig | false
+  /** 汇总配置；false 表示关闭汇总。 */
+  summary: TableSummaryConfig<T> | false
+  /** 导出配置；false 表示关闭导出。 */
+  exportOptions: TableExportConfig<T> | false
+  /** 空状态和表内可访问查询错误通知。 */
+  feedback: false | TableFeedbackOptions
+  /** initial 模式在刷新时保留已有行可操作，也是默认值。 */
+  loadingMask: TableLoadingMaskMode
+  /** 透传给 Handsontable 的原生设置。 */
+  settings: GridSettings
+  /** 与校验、冲突元数据共同合成的单元格级业务策略。 */
+  resolveCell?: (
+    context: TableCellMetaContext<T>
+  ) => TableCellMetaResult | undefined
+  /** 初始密度；已保存的用户偏好优先。 */
+  density: TableDensity
+  /** auto 跟随 html.dark；对象主题会克隆为表格实例级 ThemeBuilder。 */
+  theme: TableTheme
+  /** 显示、导出和远程 provider 共享的 locale，默认 zh-CN。 */
+  locale: string
+  /** 显示、导出和远程 provider 共享的时区。 */
+  timeZone?: string
+  /** Handsontable 许可证 key。 */
+  licenseKey: string
+  /** 网格区域高度策略。 */
+  height: TableHeight
+}