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

package/template/src/components/AppTable/engine/columns/config/validation.ts

@@ -0,0 +1,106 @@
+import {
+  resolveTableMultiSelectConfig,
+  validateTableMultiSelectValue,
+  validateTableSelectValue,
+  validateTableTemporalValue,
+  type TableTemporalType,
+} from '../../cell'
+import {
+  TABLE_ENGINE_MESSAGES_ZH_CN,
+  type TableEngineMessages,
+} from '../../shared/messages'
+import type { TableRow } from '../../shared/types'
+import type {
+  RowKeyResolver,
+  TableCellValidator,
+  TableValidationOptions,
+} from '../../table/editing'
+import type { TableColumn } from '../column'
+import { resolveTableColumns } from './columns'
+import { resolveTableColumnTemporalType } from './temporal'
+
+type TableBuiltInValidator = (value: unknown) => true | string
+
+const resolveTableBuiltInValidator = <T extends TableRow>(
+  column: TableColumn<T>,
+  temporalType: TableTemporalType | undefined,
+  messages: TableEngineMessages
+): TableBuiltInValidator | undefined => {
+  switch (column.renderer) {
+    case 'select':
+      return (value) =>
+        validateTableSelectValue(
+          value,
+          column.options,
+          {
+            clearable: column.optionClearable,
+            allowUnknownValue: column.allowUnknownOption,
+          },
+          messages
+        )
+    case 'multiSelect': {
+      const config = resolveTableMultiSelectConfig(
+        column.options,
+        column.multiSelect
+      )
+      return (value) => validateTableMultiSelectValue(value, config, messages)
+    }
+    default:
+      return temporalType
+        ? (value) => validateTableTemporalValue(value, temporalType, messages)
+        : undefined
+  }
+}
+
+/** 内置协议校验先于业务 validator，避免业务代码接收到结构无效的值。 */
+const createTableColumnValidator = <T extends TableRow>(
+  column: TableColumn<T>,
+  temporalType: TableTemporalType | undefined,
+  messages: TableEngineMessages
+): TableCellValidator<T> | undefined => {
+  const builtInValidator = resolveTableBuiltInValidator(
+    column,
+    temporalType,
+    messages
+  )
+  const customValidator = column.validation?.validator
+  if (!builtInValidator && !customValidator) return
+
+  return async (value, context) => {
+    if (builtInValidator) {
+      const result = builtInValidator(value)
+      if (result !== true) return result
+    }
+    return customValidator ? customValidator(value, context) : true
+  }
+}
+
+/** 将列声明不可变地编译为 Controller 保存前校验配置。 */
+export const buildTableValidationOptions = <T extends TableRow>(
+  columns: readonly TableColumn<T>[],
+  rowKey: RowKeyResolver<T>,
+  messages: TableEngineMessages = TABLE_ENGINE_MESSAGES_ZH_CN
+): TableValidationOptions<T> => ({
+  rowKey,
+  messages,
+  columns: resolveTableColumns(columns).flatMap((column) => {
+    const temporalType = resolveTableColumnTemporalType(column)
+    const validator = createTableColumnValidator(
+      column,
+      column.readOnly !== true ? temporalType : undefined,
+      messages
+    )
+    if (!column.required && !column.validation && !validator) return []
+    const { validator: _customValidator, ...validation } =
+      column.validation ?? {}
+    return [
+      {
+        prop: String(column.key),
+        label: column.label,
+        required: column.required,
+        ...validation,
+        validator,
+      },
+    ]
+  }),
+})

package/template/src/components/AppTable/engine/columns/constants.ts

@@ -0,0 +1,6 @@
+/** 列推导与内置辅助列的稳定默认值。 */
+export const TABLE_COLUMN_DEFAULTS = {
+  autocompleteVisibleRows: 8,
+  selectionWidth: 54,
+  defaultWidth: 120,
+} as const

package/template/src/components/AppTable/engine/columns/gridColumns.ts

@@ -0,0 +1,332 @@
+import type Handsontable from 'handsontable'
+import type { ColumnSettings } from 'handsontable'
+import type { BaseRenderer } from 'handsontable/renderers'
+import {
+  createColumnRenderer,
+  createTableLayerEditor,
+  resolveTableActionColumnWidth,
+} from '../cell'
+import type { TableCellLayerAdapter } from '../cell/customCell/types'
+import type { TableValueFormat } from '../cell/formatting'
+import {
+  isPrimitiveTableOptionSource,
+  resolveTableMultiSelectConfig,
+} from '../cell/multiSelect'
+import type { TableEngineMessages } from '../shared/messages'
+import type { TableRow } from '../shared/types'
+import {
+  assertTableColumnConfiguration,
+  isTableControlledEditorColumn,
+  resolveTableAutocompleteConfig,
+  type TableColumn,
+} from './column'
+import { TABLE_COLUMN_DEFAULTS } from './constants'
+import { resolveTableRendererPolicy } from './rendererPolicies'
+
+interface BuildTableGridColumnsOptions<T extends TableRow> {
+  /** 需要编译为 Handsontable ColumnSettings 的业务列。 */
+  columns: readonly TableColumn<T>[]
+  /** 用户偏好中保存的列宽，优先于列初始宽度。 */
+  columnWidths?: Readonly<Record<string, number>>
+  /** 普通业务列未声明宽度时使用的统一默认值。 */
+  defaultColumnWidth?: number | string
+  /** 是否在业务列前插入行选择列。 */
+  selectable?: boolean
+  /** 选择列使用的框架适配渲染器。 */
+  selectionRenderer?: BaseRenderer
+  /** 获取当前 Handsontable 实例，供视觉行转物理行。 */
+  getInstance: () => Handsontable | null
+  /** 获取当前最新行数据，避免闭包持有过期数组。 */
+  getRows: () => readonly T[]
+  /** 受控编辑器提交值时调用的统一事务入口。 */
+  updateCell: (visualRow: number, key: string, value: unknown) => boolean
+  /** 承载框架组件编辑器的浮层适配器。 */
+  layer: TableCellLayerAdapter
+  /** 表格统一的值格式化函数。 */
+  formatValue: (value: unknown, format?: TableValueFormat) => unknown
+  /** 纯 DOM renderer 和受控编辑器使用的可见文案。 */
+  messages: TableEngineMessages
+}
+
+/**
+ * 只保留 Handsontable ColumnSettings，避免业务配置被 `...column` 当作未知设置下传。
+ *
+ * 这些字段由 TableComponent engine、renderer 或 React 层消费；新增业务列字段时也应
+ * 在这里显式剥离，让传入 Handsontable 的对象始终符合它自己的公开类型合同。
+ */
+const resolveHandsontableColumnSettings = <T extends TableRow>(
+  column: TableColumn<T>
+): ColumnSettings => {
+  const {
+    key: _key,
+    label: _label,
+    enabled: _enabled,
+    renderer: _renderer,
+    readOnly: _readOnly,
+    hidden: _hidden,
+    required: _required,
+    validation: _validation,
+    summary: _summary,
+    formatter: _formatter,
+    format: _format,
+    options: _options,
+    optionCache: _optionCache,
+    optionDebounceMs: _optionDebounceMs,
+    optionPlaceholder: _optionPlaceholder,
+    componentProps: _componentProps,
+    optionClearable: _optionClearable,
+    allowUnknownOption: _allowUnknownOption,
+    multiple: _multiple,
+    multiSelect: _multiSelect,
+    autocomplete: _autocomplete,
+    itemList: _itemList,
+    step: _step,
+    confirmInput: _confirmInput,
+    actions: _actions,
+    buttonLimit: _buttonLimit,
+    foldActions: _foldActions,
+    moreActionLabel: _moreActionLabel,
+    links: _links,
+    link: _link,
+    onChange: _onChange,
+    editorTrigger: _editorTrigger,
+    numberInput: _numberInput,
+    formulaInput: _formulaInput,
+    parseValue: _parseValue,
+    acceptChange: _acceptChange,
+    deriveChanges: _deriveChanges,
+    transfer: _transfer,
+    allowInput: _allowInput,
+    allowPaste: _allowPaste,
+    allowAutofill: _allowAutofill,
+    ...settings
+  } = column
+  return settings
+}
+
+/** 显式宽度优先；操作列未配置宽度时按可见按钮数量估算。 */
+const resolveGridColumnWidth = <T extends TableRow>(
+  column: TableColumn<T>,
+  columnWidths: Readonly<Record<string, number>>,
+  defaultColumnWidth: number | string
+) => {
+  const configuredWidth = columnWidths[String(column.key)] ?? column.width
+  if (configuredWidth !== undefined) return configuredWidth
+  if (column.renderer === 'button' || column.actions?.length) {
+    return resolveTableActionColumnWidth(column.actions?.length ?? 0, {
+      limit: column.buttonLimit,
+      fold: column.foldActions,
+    })
+  }
+  return defaultColumnWidth
+}
+
+/**
+ * 受控展示型 renderer 强制只读；普通列保持历史默认值 true，避免缺少 editor 时
+ * Handsontable 意外开放文本编辑。
+ */
+const resolveGridColumnReadOnly = <T extends TableRow>(
+  column: TableColumn<T>
+) => {
+  if (typeof column.renderer !== 'function') {
+    const policy = resolveTableRendererPolicy(column.renderer)
+    if (policy.pasteOnly) return false
+    if (policy.readOnly) return true
+  }
+  return typeof column.readOnly === 'boolean' ? column.readOnly : true
+}
+
+/**
+ * 将业务 formatter 包装为 Handsontable valueGetter。
+ * 排序、筛选后必须将 visualRow 转回 physicalRow 才能取得正确源数据。
+ */
+const createFormatterValueGetter = <T extends TableRow>(
+  column: TableColumn<T>,
+  getInstance: () => Handsontable | null,
+  getRows: () => readonly T[]
+): ColumnSettings['valueGetter'] => {
+  if (!column.formatter) return column.valueGetter
+  return (
+    value: unknown,
+    visualRow: number,
+    visualColumn: number,
+    cellMeta: Parameters<NonNullable<ColumnSettings['valueGetter']>>[3]
+  ) => {
+    const instance = getInstance()
+    const physicalRow = instance?.toPhysicalRow(visualRow) ?? visualRow
+    // NestedRows 的物理行经过插件映射，优先从官方数据 API 取得父/子行对象。
+    const sourceRow =
+      (instance?.getSourceDataAtRow?.(physicalRow) as T | undefined) ??
+      getRows()[physicalRow]
+    const resolvedValue = column.valueGetter
+      ? Reflect.apply(column.valueGetter, instance ?? {}, [
+          value,
+          visualRow,
+          visualColumn,
+          cellMeta,
+        ])
+      : value
+    return sourceRow
+      ? column.formatter?.(resolvedValue, sourceRow, physicalRow)
+      : resolvedValue
+  }
+}
+
+/** 原生 multiselect 插件需要独立列协议，不能继续携带框架层 renderer 配置。 */
+const createNativeMultiSelectColumn = <T extends TableRow>(
+  column: TableColumn<T>,
+  width: number | string | undefined,
+  readOnly: boolean
+): ColumnSettings | undefined => {
+  if (column.renderer !== 'multiSelect') return
+  const config = resolveTableMultiSelectConfig(
+    column.options,
+    column.multiSelect
+  )
+  if (config.engine !== 'native') return
+  if (!isPrimitiveTableOptionSource(column.options)) return
+  const settings = resolveHandsontableColumnSettings(column)
+  return {
+    ...settings,
+    data: column.key,
+    width,
+    readOnly,
+    type: 'multiselect',
+    source: [...column.options],
+    maxSelections: config.maxSelections,
+    searchInput: config.searchInput,
+    placeholder: config.placeholder ?? column.optionPlaceholder,
+    visibleRows: config.visibleRows,
+    enterCommits: config.enterCommits,
+    filteringCaseSensitive: config.filteringCaseSensitive,
+    sourceSortFunction: config.sourceSortFunction,
+  }
+}
+
+/** 将统一列声明转换为 Handsontable 原生 autocomplete 配置。 */
+const createAutocompleteColumn = <T extends TableRow>(
+  column: TableColumn<T>,
+  width: number | string | undefined,
+  readOnly: boolean
+): ColumnSettings | undefined => {
+  if (column.renderer !== 'autocomplete' || !column.autocomplete) return
+  const autocomplete = resolveTableAutocompleteConfig(column.autocomplete)
+  const settings = resolveHandsontableColumnSettings(column)
+  return {
+    ...settings,
+    data: column.key,
+    width,
+    readOnly,
+    type: 'autocomplete',
+    source: autocomplete.source,
+    strict: autocomplete.strict,
+    filter: autocomplete.filter,
+    visibleRows: autocomplete.visibleRows,
+    allowInvalid: autocomplete.allowInvalid,
+    trimDropdown: autocomplete.trimDropdown,
+  }
+}
+
+/** 密码列默认禁止复制，调用方可通过 copyable 显式放开。 */
+const createPasswordColumn = <T extends TableRow>(
+  column: TableColumn<T>,
+  width: number | string | undefined,
+  readOnly: boolean
+): ColumnSettings | undefined => {
+  if (column.renderer !== 'password') return
+  const settings = resolveHandsontableColumnSettings(column)
+  return {
+    ...settings,
+    data: column.key,
+    width,
+    readOnly,
+    type: 'password',
+    copyable: column.copyable ?? false,
+  }
+}
+
+/** 受控编辑器统一交给浮层适配器；纯展示 renderer 明确禁用原生 editor。 */
+const resolveGridColumnEditor = <T extends TableRow>(
+  column: TableColumn<T>,
+  layer: TableCellLayerAdapter,
+  updateCell: (visualRow: number, key: string, value: unknown) => boolean,
+  messages: TableEngineMessages
+) => {
+  if (isTableControlledEditorColumn(column)) {
+    return createTableLayerEditor(column, { layer, updateCell, messages })
+  }
+  if (typeof column.renderer !== 'function') {
+    return resolveTableRendererPolicy(column.renderer).disableNativeEditor
+      ? false
+      : column.editor
+  }
+  return column.editor
+}
+
+/** 构建 Handsontable 列配置，不依赖 React 状态 API。 */
+export const buildTableGridColumns = <T extends TableRow>({
+  columns: sourceColumns,
+  columnWidths = {},
+  defaultColumnWidth = TABLE_COLUMN_DEFAULTS.defaultWidth,
+  selectable = false,
+  selectionRenderer,
+  getInstance,
+  getRows,
+  updateCell,
+  layer,
+  formatValue,
+  messages,
+}: BuildTableGridColumnsOptions<T>): ColumnSettings[] => {
+  const columns: ColumnSettings[] = sourceColumns.map((column) => {
+    assertTableColumnConfiguration(column)
+    const settings = resolveHandsontableColumnSettings(column)
+    const width = resolveGridColumnWidth(
+      column,
+      columnWidths,
+      defaultColumnWidth
+    )
+    const readOnly = resolveGridColumnReadOnly(column)
+    // 原生插件列优先返回完整配置，其余列走 TableComponent 的统一渲染链。
+    const nativeColumn =
+      createNativeMultiSelectColumn(column, width, readOnly) ??
+      createAutocompleteColumn(column, width, readOnly) ??
+      createPasswordColumn(column, width, readOnly)
+    if (nativeColumn) return nativeColumn
+
+    return {
+      ...settings,
+      data: column.key,
+      width,
+      readOnly,
+      valueGetter: createFormatterValueGetter(column, getInstance, getRows),
+      editor: resolveGridColumnEditor(column, layer, updateCell, messages),
+      renderer: createColumnRenderer(column, {
+        updateCell,
+        layer,
+        formatValue,
+        messages,
+      }),
+    }
+  })
+
+  if (selectable) {
+    if (!selectionRenderer) {
+      throw new Error(
+        '[TableComponent] selectionRenderer is required when selectable is enabled.'
+      )
+    }
+    // 选择列是网格内部的虚拟首列，不属于业务 columns，也不能参与编辑。
+    columns.unshift({
+      data: '__tableSelection',
+      width: TABLE_COLUMN_DEFAULTS.selectionWidth,
+      readOnly: true,
+      columnSorting: {
+        indicator: false,
+        headerAction: false,
+      },
+      renderer: selectionRenderer,
+    })
+  }
+
+  return columns
+}

package/template/src/components/AppTable/engine/columns/index.ts

@@ -0,0 +1,4 @@
+export * from './column'
+export * from './constants'
+export * from './config'
+export * from './gridColumns'

package/template/src/components/AppTable/engine/columns/rendererPolicies.ts

@@ -0,0 +1,129 @@
+/** TableComponent 内置的单元格展示和编辑类型。 */
+export type TableRendererType =
+  /** 普通文本单元格，支持统一格式化和内容溢出提示。 */
+  | 'text'
+  /** 单链接或多链接单元格，支持安全跳转、点击和双击动作。 */
+  | 'link'
+  /** 操作列按钮，超出可见数量的动作会折叠进“更多”菜单。 */
+  | 'button'
+  /** 单选单元格，使用框架浮层选择器编辑本地或远程选项。 */
+  | 'select'
+  /** 多选单元格，支持搜索、选择上限和标签折叠。 */
+  | 'multiSelect'
+  /** 日期单元格，使用框架日期选择器编辑。 */
+  | 'date'
+  /** 时间单元格，使用框架时间选择器编辑。 */
+  | 'time'
+  /** 日期时间单元格，使用框架日期时间选择器编辑。 */
+  | 'datetime'
+  /** 密码单元格，使用 Handsontable 原生密码掩码展示。 */
+  | 'password'
+  /** 自动完成单元格，使用 Handsontable 原生候选列表编辑。 */
+  | 'autocomplete'
+  /** 开关单元格，点击后在保持原始值类型的前提下切换状态。 */
+  | 'switch'
+  /** 条目列表单元格，将数组或分隔文本按条目展示，可为每项绑定点击动作。 */
+  | 'itemList'
+  /** 步骤流程单元格，使用方向分隔符展示业务步骤和溢出提示。 */
+  | 'step'
+  /** 带确认按钮的输入结果单元格，可按配置点击或双击确认。 */
+  | 'confirmInput'
+  /** 仅接受粘贴写入并提供确认动作的输入结果单元格。 */
+  | 'pasteConfirmInput'
+
+interface TableRendererPolicy {
+  /** 是否通过框架浮层提供编辑器。 */
+  readonly layerEditor: boolean
+  /** 是否关闭 Handsontable 原生 editor。 */
+  readonly disableNativeEditor: boolean
+  /** 是否强制只读展示。 */
+  readonly readOnly: boolean
+  /** 是否默认关闭输入、粘贴和自动填充。 */
+  readonly managedMutation: boolean
+  /** 是否只允许粘贴事务。 */
+  readonly pasteOnly: boolean
+}
+
+const DEFAULT_RENDERER_POLICY: Readonly<TableRendererPolicy> = {
+  layerEditor: false,
+  disableNativeEditor: false,
+  readOnly: false,
+  managedMutation: false,
+  pasteOnly: false,
+}
+
+const defineTableRendererPolicy = (
+  overrides: Partial<TableRendererPolicy> = {}
+): Readonly<TableRendererPolicy> => ({
+  ...DEFAULT_RENDERER_POLICY,
+  ...overrides,
+})
+
+/** Renderer 行为策略的唯一配置表；新增 renderer 时 TypeScript 会要求补齐策略。 */
+const TABLE_RENDERER_POLICIES = {
+  text: DEFAULT_RENDERER_POLICY,
+  password: DEFAULT_RENDERER_POLICY,
+  autocomplete: DEFAULT_RENDERER_POLICY,
+  select: defineTableRendererPolicy({
+    layerEditor: true,
+    disableNativeEditor: true,
+    managedMutation: true,
+  }),
+  multiSelect: defineTableRendererPolicy({
+    layerEditor: true,
+    disableNativeEditor: true,
+    managedMutation: true,
+  }),
+  date: defineTableRendererPolicy({
+    layerEditor: true,
+    disableNativeEditor: true,
+    managedMutation: true,
+  }),
+  time: defineTableRendererPolicy({
+    layerEditor: true,
+    disableNativeEditor: true,
+    managedMutation: true,
+  }),
+  datetime: defineTableRendererPolicy({
+    layerEditor: true,
+    disableNativeEditor: true,
+    managedMutation: true,
+  }),
+  switch: defineTableRendererPolicy({
+    disableNativeEditor: true,
+    managedMutation: true,
+  }),
+  button: defineTableRendererPolicy({
+    disableNativeEditor: true,
+    readOnly: true,
+    managedMutation: true,
+  }),
+  link: defineTableRendererPolicy({
+    disableNativeEditor: true,
+    readOnly: true,
+    managedMutation: true,
+  }),
+  itemList: defineTableRendererPolicy({
+    disableNativeEditor: true,
+    readOnly: true,
+    managedMutation: true,
+  }),
+  step: defineTableRendererPolicy({
+    disableNativeEditor: true,
+    readOnly: true,
+    managedMutation: true,
+  }),
+  confirmInput: defineTableRendererPolicy({
+    disableNativeEditor: true,
+    managedMutation: true,
+  }),
+  pasteConfirmInput: defineTableRendererPolicy({
+    managedMutation: true,
+    pasteOnly: true,
+  }),
+} satisfies Record<TableRendererType, Readonly<TableRendererPolicy>>
+
+/** 返回指定内置 renderer 的编辑、只读和写入控制策略。 */
+export const resolveTableRendererPolicy = (
+  renderer: TableRendererType = 'text'
+) => TABLE_RENDERER_POLICIES[renderer]