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

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

@@ -0,0 +1,33 @@
+/** engine 与 React 层共享的稳定默认值。 */
+export const TABLE_DEFAULT_LOCALE = 'zh-CN'
+export const TABLE_DEFAULT_ROW_KEY = 'id'
+export const TABLE_DEFAULT_DIMENSION = '100%'
+export const TABLE_DEFAULT_VIEWPORT_ROW_OFFSET = 5
+
+/**
+ * engine 与 React 层共享的组件级标量默认值。
+ *
+ * 集合和运行时许可证仍由每个组件实例创建；这里仅保存不可变标量，避免适配包复制后
+ * 出现同一配置在不同框架中采用不同默认行为。
+ */
+export const TABLE_COMPONENT_DEFAULTS = Object.freeze({
+  searchResetBehavior: 'query' as const,
+  autoQuery: true,
+  showIndex: true,
+  striped: true,
+  highlightCurrentRow: true,
+  headerMenuTrigger: 'always' as const,
+  autoFreezeStartActions: false,
+  autoFreezeEndActions: true,
+  summarySelected: true,
+  allowBulkEdit: false,
+  keepSelection: false,
+  showToolbar: true,
+  showColumnEditor: true,
+  showDensityControl: true,
+  loadingMask: 'initial' as const,
+  theme: 'auto' as const,
+  density: 'comfortable' as const,
+  locale: TABLE_DEFAULT_LOCALE,
+  height: 'content' as const,
+})

package/template/src/components/AppTable/engine/config/grid/compiler.ts

@@ -0,0 +1,65 @@
+import type { GridSettings } from '../../table/grid'
+import { composeTableGridHook, type TableGridHook } from '../../table/hooks'
+import type { CompileTableGridSettingsOptions } from './types'
+
+/**
+ * 编译最终 Handsontable settings。
+ *
+ * 优先级为 `defaults < consumer < controlled < internalHooks`。consumer 是安装版本原生
+ * `GridSettings`，所以未知的新配置天然透传；只有列在 controlled 中的字段才会被组件
+ * 接管。内部 hook 必须登记所有权，不能依赖对象展开顺序。
+ */
+export const compileTableGridSettings = ({
+  defaults,
+  consumer,
+  controlled,
+  internalHooks,
+  hookPolicies,
+}: CompileTableGridSettingsOptions): GridSettings => {
+  // beforeAutofill 的 false 取消信号由组件合同补齐，但 Handsontable v18 声明文件遗漏；
+  // 先从官方 GridSettings 对象展开中排除，再在下面的统一 hook 合成边界写入。
+  const { beforeAutofill: _beforeAutofill, ...officialInternalHooks } =
+    internalHooks
+  const result: GridSettings = {
+    ...defaults,
+    ...consumer,
+    ...controlled,
+    ...officialInternalHooks,
+  }
+
+  if (result.nestedRows) {
+    // Handsontable 官方明确说明 NestedRows 不能与本地排序、过滤组合使用。
+    result.columnSorting = false
+    result.filters = false
+  }
+
+  for (const [name, internalValue] of Object.entries(internalHooks)) {
+    if (typeof internalValue !== 'function') continue
+    const policy = Reflect.get(hookPolicies, name) as
+      | {
+          strategy?: 'compose' | 'internal'
+          order?: 'internal-first' | 'consumer-first'
+          stopOnFalse?: boolean
+        }
+      | undefined
+    if (!policy) {
+      throw new Error(
+        `[TableComponent] Internal Handsontable hook "${name}" has no ownership policy.`
+      )
+    }
+    if (policy.strategy === 'internal') continue
+    const consumerValue = Reflect.get(consumer, name)
+    Reflect.set(
+      result,
+      name,
+      composeTableGridHook(
+        internalValue as TableGridHook,
+        typeof consumerValue === 'function'
+          ? (consumerValue as TableGridHook)
+          : undefined,
+        policy
+      )
+    )
+  }
+  return result
+}

package/template/src/components/AppTable/engine/config/grid/defaults.ts

@@ -0,0 +1,82 @@
+import type { GridSettings } from '../../table/grid'
+import {
+  TABLE_DEFAULT_DIMENSION,
+  TABLE_DEFAULT_LOCALE,
+  TABLE_DEFAULT_VIEWPORT_ROW_OFFSET,
+} from '../constants'
+
+const escapeTableHtml = (value: string) =>
+  value.replace(
+    /[&<>"']/g,
+    (character) =>
+      ({
+        '&': '&amp;',
+        '<': '&lt;',
+        '>': '&gt;',
+        '"': '&quot;',
+        "'": '&#39;',
+      })[character]!
+  )
+
+/**
+ * Handsontable v18 默认会把菜单、粘贴和部分插件文本写入 innerHTML。
+ * 产品默认只允许其 alignment 菜单使用的 selected 标记，其余标签全部降级为文本；
+ * 确实需要富 HTML 的业务仍可通过原生 settings.sanitizer 显式覆盖。
+ */
+const sanitizeTableGridHtml = (html: string, context = '') => {
+  if (typeof document === 'undefined') return escapeTableHtml(html)
+  const template = document.createElement('template')
+  template.innerHTML = html
+  const serialize = (node: Node): string => {
+    if (node.nodeType === Node.TEXT_NODE) {
+      return escapeTableHtml(node.textContent ?? '')
+    }
+    if (!(node instanceof HTMLElement)) return ''
+    const content = [...node.childNodes].map(serialize).join('')
+    return context === 'contextMenu' &&
+      node.tagName === 'SPAN' &&
+      node.classList.length === 1 &&
+      node.classList.contains('selected')
+      ? `<span class="selected">${content}</span>`
+      : content
+  }
+  return [...template.content.childNodes].map(serialize).join('')
+}
+
+/**
+ * 创建产品级 Handsontable 默认值。
+ *
+ * 这些值全部允许原生 `settings` 覆盖。这里不读取数据和业务状态，因此 Handsontable
+ * 新增普通 setting 时会自然透传，不需要同步扩充此函数的参数列表。
+ */
+export const createTableGridDefaultSettings = (): GridSettings => ({
+  language: TABLE_DEFAULT_LOCALE,
+  width: TABLE_DEFAULT_DIMENSION,
+  height: TABLE_DEFAULT_DIMENSION,
+  stretchH: 'all',
+  navigableHeaders: true,
+  tabNavigation: true,
+  autoWrapRow: true,
+  autoWrapCol: true,
+  viewportRowRenderingOffset: TABLE_DEFAULT_VIEWPORT_ROW_OFFSET,
+  // 行高、文本换行和滚动范围统一由 Handsontable 测量，避免适配层维护第二套高度真相。
+  autoRowSize: true,
+  autoColumnSize: false,
+  filters: true,
+  dropdownMenu: true,
+  columnSorting: true,
+  manualColumnResize: true,
+  manualColumnMove: true,
+  manualColumnFreeze: true,
+  manualRowResize: true,
+  sanitizer: sanitizeTableGridHtml,
+  contextMenu: [
+    'copy',
+    'cut',
+    'undo',
+    'redo',
+    'freeze_column',
+    'unfreeze_column',
+    'alignment',
+  ],
+})

package/template/src/components/AppTable/engine/config/grid/ownership.ts

@@ -0,0 +1,35 @@
+import type { TableGridHookOwnershipPolicies } from './types'
+
+/**
+ * 内部 hook 的显式所有权台账。
+ *
+ * 新增内部 hook 时必须在这里选择组合顺序；否则编译器会直接报错，避免对象展开把
+ * 业务方 hook 静默覆盖。`cells` 内部会主动读取 consumer cells，因此不能二次组合。
+ */
+export const TABLE_GRID_HOOK_OWNERSHIP = {
+  cells: { strategy: 'internal' },
+  beforeCopy: { strategy: 'compose' },
+  beforePaste: { strategy: 'compose', order: 'consumer-first' },
+  beforeAutofill: { strategy: 'compose', order: 'consumer-first' },
+  afterFilter: { strategy: 'compose' },
+  afterDropdownMenuShow: { strategy: 'compose' },
+  afterScrollHorizontally: { strategy: 'compose' },
+  afterScrollVertically: { strategy: 'compose' },
+  afterViewRender: { strategy: 'compose' },
+  beforeChange: { strategy: 'compose', order: 'consumer-first' },
+  beforeCreateRow: { strategy: 'compose', order: 'consumer-first' },
+  afterChange: { strategy: 'compose' },
+  afterRenderer: { strategy: 'compose' },
+  afterGetColHeader: { strategy: 'compose' },
+  afterOnCellMouseOver: { strategy: 'compose' },
+  afterOnCellMouseOut: { strategy: 'compose' },
+  afterOnCellMouseUp: { strategy: 'compose' },
+  afterSelectionEnd: { strategy: 'compose' },
+  afterDeselect: { strategy: 'compose' },
+  afterColumnResize: { strategy: 'compose' },
+  beforeColumnMove: { strategy: 'compose' },
+  beforeColumnSort: { strategy: 'compose', order: 'consumer-first' },
+  afterColumnMove: { strategy: 'compose' },
+  afterColumnFreeze: { strategy: 'compose' },
+  afterColumnUnfreeze: { strategy: 'compose' },
+} satisfies TableGridHookOwnershipPolicies

package/template/src/components/AppTable/engine/config/grid/runtimeDelta.ts

@@ -0,0 +1,34 @@
+import type { GridSettings } from '../../table/grid'
+
+const TABLE_GRID_RUNTIME_EXCLUDED_KEYS = new Set<keyof GridSettings>(['data'])
+
+const isRuntimeSettingEqual = (previous: unknown, next: unknown) => {
+  if (Object.is(previous, next)) return true
+  if (!Array.isArray(previous) || !Array.isArray(next)) return false
+  return (
+    previous.length === next.length &&
+    previous.every((item, index) => Object.is(item, next[index]))
+  )
+}
+
+/** data 由专用投影管线更新，其余字段仅在真正变化时同步到 Handsontable。 */
+export const diffTableGridRuntimeSettings = (
+  previous: GridSettings,
+  next: GridSettings
+): GridSettings => {
+  const delta: GridSettings = {}
+  const keys = new Set([
+    ...Reflect.ownKeys(previous),
+    ...Reflect.ownKeys(next),
+  ] as Array<keyof GridSettings>)
+  keys.forEach((key) => {
+    if (TABLE_GRID_RUNTIME_EXCLUDED_KEYS.has(key)) return
+    if (!isRuntimeSettingEqual(previous[key], next[key])) {
+      Reflect.set(delta, key, next[key])
+    }
+  })
+  return delta
+}
+
+export const hasTableGridRuntimeSettings = (settings: GridSettings) =>
+  Reflect.ownKeys(settings).length > 0

package/template/src/components/AppTable/engine/config/grid/types.ts

@@ -0,0 +1,30 @@
+import type { Events } from 'handsontable'
+import type { GridSettings } from '../../table/grid'
+import type {
+  ComposeTableGridHookOptions,
+  TableGridHooks,
+} from '../../table/hooks'
+
+/** 内部 hook 的所有权决定其是否与调用方 hook 组合。 */
+export interface TableGridHookOwnership extends ComposeTableGridHookOptions {
+  /** compose 组合调用方 hook；internal 则只保留组件一致性逻辑。 */
+  strategy: 'compose' | 'internal'
+}
+
+export type TableGridHookOwnershipPolicies = Partial<
+  Record<keyof Events, TableGridHookOwnership>
+>
+
+/** settings 编译器的四层输入，优先级从上到下递增。 */
+export interface CompileTableGridSettingsOptions {
+  /** 组件统一基础默认值，优先级最低。 */
+  defaults: GridSettings
+  /** 业务通过 table.settings 传入的原生 Handsontable 配置。 */
+  consumer: GridSettings
+  /** 数据、列、主题等必须由组件托管的配置。 */
+  controlled: GridSettings
+  /** 组件内部为交互和一致性提供的 Hooks。 */
+  internalHooks: TableGridHooks
+  /** 每个 Hook 的组合顺序、取消语义和所有权策略。 */
+  hookPolicies: TableGridHookOwnershipPolicies
+}

package/template/src/components/AppTable/engine/pagination/config.ts

@@ -0,0 +1,75 @@
+import {
+  TABLE_DEFAULT_ALL_ROWS_LIMIT,
+  TABLE_DEFAULT_PAGE_SIZE,
+  TABLE_DEFAULT_PAGE_SIZES,
+} from './constants'
+import type {
+  ResolvedTablePaginationConfig,
+  TablePaginationConfig,
+  TablePageSize,
+} from './types'
+
+/** 同时保护 JavaScript 调用方、持久化配置和被断言绕过的 TypeScript 输入。 */
+export const isTablePageSize = (value: unknown): value is TablePageSize =>
+  typeof value === 'number' && Number.isInteger(value) && value > 0
+
+const toPositiveInteger = (value: unknown, fallback: number) => {
+  const number = Number(value)
+  return Number.isFinite(number) && number > 0
+    ? Math.max(1, Math.trunc(number))
+    : fallback
+}
+
+const normalizeConfiguredPageSize = (
+  value: unknown,
+  fallback: number
+): number => (isTablePageSize(value) ? value : fallback)
+
+const normalizeSiblingCount = (value: unknown) => {
+  const number = Number(value)
+  return Number.isFinite(number)
+    ? Math.min(3, Math.max(0, Math.trunc(number)))
+    : 1
+}
+
+export const normalizeTableTotal = (value: unknown) => {
+  const number = Number(value)
+  return Number.isFinite(number) && number >= 0 ? Math.trunc(number) : 0
+}
+
+/**
+ * 解析分页公共配置，不修改调用方数组。
+ *
+ * 无效 pageSize 回退到产品默认值；pageSizes 去重并剔除非正整数，同时确保当前
+ * pageSize 一定出现在下拉选项中，避免选择器展示值与候选项不一致。
+ */
+export const resolveTablePaginationConfig = (
+  config: TablePaginationConfig | false | undefined
+): ResolvedTablePaginationConfig => {
+  const source = config === false ? {} : (config ?? {})
+  const pageSize = normalizeConfiguredPageSize(
+    source.pageSize,
+    TABLE_DEFAULT_PAGE_SIZE
+  )
+  const normalizedSizes = (
+    source.pageSizes?.length ? source.pageSizes : TABLE_DEFAULT_PAGE_SIZES
+  ).filter(isTablePageSize)
+  const pageSizes = [...new Set(normalizedSizes)]
+  if (!pageSizes.includes(pageSize)) pageSizes.unshift(pageSize)
+  const mode = source.mode === 'all' ? 'all' : 'page'
+
+  return {
+    // all 模式没有分页交互；即使 JavaScript 调用方传入非法组合也在运行时归一化。
+    enabled: mode === 'page' && config !== false && source.enabled !== false,
+    mode,
+    maxRows: toPositiveInteger(source.maxRows, TABLE_DEFAULT_ALL_ROWS_LIMIT),
+    pageSize,
+    pageSizes,
+    showTotal: source.showTotal !== false,
+    showPageSize: source.showPageSize !== false,
+    showPageNumbers: source.showPageNumbers !== false,
+    showJumper: source.showJumper !== false,
+    siblingCount: normalizeSiblingCount(source.siblingCount),
+    queryOnChange: source.queryOnChange !== false,
+  }
+}

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

@@ -0,0 +1,5 @@
+export const TABLE_DEFAULT_PAGE_SIZE = 20
+export const TABLE_DEFAULT_PAGE_SIZES: readonly number[] = [
+  20, 50, 100, 500, 1000,
+]
+export const TABLE_DEFAULT_ALL_ROWS_LIMIT = 5000

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

@@ -0,0 +1,3 @@
+export * from './config'
+export * from './constants'
+export * from './types'

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

@@ -0,0 +1,70 @@
+/** 正整数分页条数；运行时解析器会过滤非法值。 */
+export type TablePageSize = number
+
+export type TablePaginationDataMode = 'page' | 'all'
+
+interface TablePaginationBaseConfig {
+  /** all 模式允许的最大行数；超限或后端截断时查询失败且不覆盖旧数据。 */
+  maxRows?: number
+  /** 每页条数候选值，可按业务和后端能力自由配置。 */
+  pageSizes?: readonly TablePageSize[]
+  /** 初始每页条数，默认 20，并可被用户偏好覆盖。 */
+  pageSize?: TablePageSize
+  /** 是否显示总条数，默认 true。 */
+  showTotal?: boolean
+  /** 是否显示每页条数选择器，默认 true。 */
+  showPageSize?: boolean
+  /** 是否显示数字页码，默认 true。 */
+  showPageNumbers?: boolean
+  /** 是否显示页码跳转器，默认 true。 */
+  showJumper?: boolean
+  /** 当前页两侧保留的数字页码数量，默认 1。 */
+  siblingCount?: number
+  /** 页码或每页条数改变后是否自动查询；设为 false 时只发送事件。 */
+  queryOnChange?: boolean
+}
+
+/** 按页加载；enabled 只控制分页 UI，不改变请求的 page/pageSize。 */
+export interface TablePagedPaginationConfig extends TablePaginationBaseConfig {
+  /** 是否显示分页交互，默认 `true`；关闭后仍按页请求数据。 */
+  enabled?: boolean
+  /** 按页加载模式，默认 `page`。 */
+  mode?: 'page'
+}
+
+/** 全量加载没有可切换的页码，类型层禁止同时开启分页 UI。 */
+export interface TableAllRowsPaginationConfig extends TablePaginationBaseConfig {
+  /** 全量模式固定不显示分页交互。 */
+  enabled?: false
+  /** 一次请求全部数据，并受 `maxRows` 安全上限约束。 */
+  mode: 'all'
+}
+
+export type TablePaginationConfig =
+  | TablePagedPaginationConfig
+  | TableAllRowsPaginationConfig
+
+export interface ResolvedTablePaginationConfig {
+  /** 规范化后的分页启用状态。 */
+  enabled: boolean
+  /** 规范化后的数据加载模式。 */
+  mode: TablePaginationDataMode
+  /** all 模式的最大安全行数。 */
+  maxRows: number
+  /** 规范化、去重后的每页条数候选项。 */
+  pageSizes: TablePageSize[]
+  /** 规范化后的当前每页条数。 */
+  pageSize: TablePageSize
+  /** 是否显示总条数。 */
+  showTotal: boolean
+  /** 是否显示每页条数选择器。 */
+  showPageSize: boolean
+  /** 是否显示数字页码。 */
+  showPageNumbers: boolean
+  /** 是否显示页码跳转器。 */
+  showJumper: boolean
+  /** 当前页两侧保留的数字页码数量。 */
+  siblingCount: number
+  /** 分页变化后是否触发查询。 */
+  queryOnChange: boolean
+}

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

@@ -0,0 +1,2 @@
+export * from './preference'
+export type * from './types'