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

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

@@ -0,0 +1,535 @@
+import { isTablePageSize } from '../pagination/config'
+import { normalizeTableDensity } from '../shared/theme'
+import type { TablePreference } from './types'
+
+const TABLE_PREFERENCE_SCHEMA_VERSION = 3
+
+const LEGACY_LOCAL_STORAGE_KEY = 'pure-admin:table-component'
+
+export interface PreferenceKey {
+  /** 用户、租户或角色隔离域，避免不同主体共享同一份表格偏好。 */
+  userScope: string
+  /** 表格稳定标识，对应一张业务表格的独立偏好记录。 */
+  tableKey: string
+}
+
+export interface StoredTablePreference {
+  /** 偏好数据结构版本，用于按顺序执行迁移。 */
+  schemaVersion: number
+  /** 最近一次成功保存的 ISO 时间。 */
+  updatedAt: string
+  /** 已持久化的表格偏好内容。 */
+  value: TablePreference
+}
+
+export interface PreferenceStore {
+  /** 按用户域和表格 key 读取偏好；不存在时返回 null。 */
+  load(key: PreferenceKey): Promise<StoredTablePreference | null>
+  /** 原子保存指定表格的完整偏好。 */
+  save(key: PreferenceKey, value: StoredTablePreference): Promise<void>
+  /** 删除指定表格偏好，使组件恢复默认配置。 */
+  remove(key: PreferenceKey): Promise<void>
+}
+
+interface StorageLike {
+  /** 读取字符串值；接口与 Web Storage 保持一致。 */
+  getItem(key: string): string | null
+  /** 写入字符串值；接口与 Web Storage 保持一致。 */
+  setItem(key: string, value: string): void
+  /** 可选删除能力，便于注入精简的自定义存储实现。 */
+  removeItem?(key: string): void
+}
+
+interface PreferenceMigration {
+  /** 迁移支持的起始 schema 版本。 */
+  from: number
+  /** 迁移完成后的 schema 版本，必须大于 from。 */
+  to: number
+  /** 将上一版本偏好转换为下一版本的纯函数。 */
+  migrate(value: TablePreference): TablePreference
+}
+
+export type PreferenceStatus = 'idle' | 'loading' | 'ready' | 'failed'
+
+export interface PreferenceSnapshot {
+  /** 当前偏好协调器所处的读取或保存状态。 */
+  readonly status: PreferenceStatus
+  /** 最近一次存储操作错误；无错误时为 null。 */
+  readonly error: unknown
+  /** 当前偏好的防御性副本。 */
+  readonly value: TablePreference
+}
+
+export type TablePreferenceUpdater = (
+  current: TablePreference
+) => TablePreference
+
+/**
+ * engine 与 React 调用方共享的偏好会话契约。
+ *
+ * 会话是单张表唯一的读写入口；update 基于会话内的最新值执行，避免多个功能模块
+ * 分别保存旧快照时互相覆盖。
+ */
+export interface TablePreferenceSession {
+  readonly status: PreferenceStatus
+  readonly error: unknown
+  readonly snapshot: PreferenceSnapshot
+  load(): Promise<TablePreference>
+  update(updater: TablePreferenceUpdater): Promise<TablePreference>
+  reset(): Promise<TablePreference>
+  flush(): Promise<void>
+  subscribe(listener: () => void): () => void
+}
+
+interface PreferenceCoordinatorOptions {
+  /** 实际执行本地或远程读写的偏好存储适配器。 */
+  store: PreferenceStore
+  /** 当前用户域与表格 key 组成的存储主键。 */
+  key: PreferenceKey
+  /** 组件或路由改名后用于查找历史数据的旧表格 key，按顺序匹配。 */
+  legacyTableKeys?: string[]
+  /** 没有存储数据或读取失败时使用的安全默认偏好。 */
+  fallback: TablePreference
+  /** 自定义版本迁移链；未传时使用组件内置迁移。 */
+  migrations?: PreferenceMigration[]
+}
+
+const normalizeKeyList = (value: unknown) =>
+  Array.isArray(value)
+    ? [
+        ...new Set(
+          value.flatMap((item) => {
+            const key = typeof item === 'string' ? item.trim() : ''
+            return key ? [key] : []
+          })
+        ),
+      ]
+    : []
+
+const normalizePositiveInteger = (value: unknown) => {
+  const number = Number(value)
+  return Number.isInteger(number) && number > 0 ? number : undefined
+}
+
+const normalizeNonNegativeInteger = (value: unknown) => {
+  const number = Number(value)
+  return Number.isInteger(number) && number >= 0 ? number : 0
+}
+
+const normalizeColumnWidths = (value: unknown) => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {}
+  return Object.fromEntries(
+    Object.entries(value).flatMap(([rawKey, rawWidth]) => {
+      const key = rawKey.trim()
+      const width = Number(rawWidth)
+      return key && Number.isFinite(width) && width > 0 ? [[key, width]] : []
+    })
+  )
+}
+
+type UnknownPreference = Record<string, unknown>
+
+const isUnknownPreference = (value: unknown): value is UnknownPreference =>
+  Boolean(value && typeof value === 'object' && !Array.isArray(value))
+
+const hasOwn = (value: UnknownPreference, key: string) =>
+  Object.prototype.hasOwnProperty.call(value, key)
+
+/**
+ * 旧版 columnSort/queryItemSort 保存的是 `{ 字段: 从 1 开始的序号 }`。
+ * 新版只保存稳定 key 数组，这里按序号排序；非法值不能影响其他有效字段的迁移。
+ */
+const normalizeLegacyOrder = (value: unknown): string[] => {
+  if (!isUnknownPreference(value)) return []
+  return Object.entries(value)
+    .flatMap(([rawKey, rawOrder], sourceIndex) => {
+      const key = rawKey.trim()
+      const order = Number(rawOrder)
+      return key && Number.isFinite(order) ? [{ key, order, sourceIndex }] : []
+    })
+    .sort(
+      (left, right) =>
+        left.order - right.order || left.sourceIndex - right.sourceIndex
+    )
+    .map(({ key }) => key)
+}
+
+/** 旧版隐藏配置只持久化值为 true 的字段。 */
+const normalizeLegacyHiddenKeys = (value: unknown): string[] => {
+  if (!isUnknownPreference(value)) return []
+  return Object.entries(value).flatMap(([rawKey, hidden]) => {
+    const key = rawKey.trim()
+    return key && hidden === true ? [key] : []
+  })
+}
+
+/**
+ * 将真实旧版 `storageTable[tableId]` 字段转换为新版领域结构。
+ *
+ * 新字段始终优先，避免已经迁移过的用户数据被同一对象里残留的旧字段覆盖。
+ * freezeColKey 是视觉列数量，无法在没有列定义时可靠转换为稳定列 key，因此不猜测迁移。
+ */
+const migrateLegacyTablePreference = (value: unknown): UnknownPreference => {
+  if (!isUnknownPreference(value)) return {}
+  const {
+    cellWidth,
+    columnSort,
+    columnHidden,
+    queryItemSort,
+    queryItemHideKey,
+    freezeColKey: _freezeColKey,
+    freezeRowKey,
+    ...current
+  } = value
+
+  return {
+    ...current,
+    columnOrder: hasOwn(value, 'columnOrder')
+      ? value.columnOrder
+      : normalizeLegacyOrder(columnSort),
+    hiddenColumns: hasOwn(value, 'hiddenColumns')
+      ? value.hiddenColumns
+      : normalizeLegacyHiddenKeys(columnHidden),
+    columnWidths: hasOwn(value, 'columnWidths')
+      ? value.columnWidths
+      : cellWidth,
+    searchOrder: hasOwn(value, 'searchOrder')
+      ? value.searchOrder
+      : normalizeLegacyOrder(queryItemSort),
+    hiddenSearchConditions: hasOwn(value, 'hiddenSearchConditions')
+      ? value.hiddenSearchConditions
+      : normalizeLegacyHiddenKeys(queryItemHideKey),
+    frozenRows: hasOwn(value, 'frozenRows') ? value.frozenRows : freezeRowKey,
+  }
+}
+
+const clonePreference = (value: TablePreference): TablePreference => ({
+  ...value,
+  columnOrder: normalizeKeyList(value.columnOrder),
+  hiddenColumns: normalizeKeyList(value.hiddenColumns),
+  columnWidths: normalizeColumnWidths(value.columnWidths),
+  frozenColumns: normalizeKeyList(value.frozenColumns),
+  searchOrder: normalizeKeyList(value.searchOrder),
+  hiddenSearchConditions: normalizeKeyList(value.hiddenSearchConditions),
+})
+
+const normalizePreference = (value: unknown): TablePreference => {
+  const source = isUnknownPreference(value) ? value : {}
+  return {
+    pageSize: isTablePageSize(source.pageSize) ? source.pageSize : undefined,
+    columnOrder: normalizeKeyList(source.columnOrder),
+    hiddenColumns: normalizeKeyList(source.hiddenColumns),
+    columnWidths: normalizeColumnWidths(source.columnWidths),
+    frozenColumns: normalizeKeyList(source.frozenColumns),
+    frozenRows: normalizeNonNegativeInteger(source.frozenRows),
+    searchOrder: normalizeKeyList(source.searchOrder),
+    hiddenSearchConditions: normalizeKeyList(source.hiddenSearchConditions),
+    density: normalizeTableDensity(source.density),
+    bottomHeight: normalizePositiveInteger(source.bottomHeight),
+    rightWidth: normalizePositiveInteger(source.rightWidth),
+  }
+}
+
+const isStoredPreference = (value: unknown): value is StoredTablePreference =>
+  Boolean(
+    value &&
+    typeof value === 'object' &&
+    'schemaVersion' in value &&
+    'value' in value
+  )
+
+/**
+ * 把旧版 `storageTable[tableKey]` 的裸配置包装成带 schemaVersion 的新结构。
+ * tableKey 保持不变，确保迁移时仍能找到用户历史偏好。
+ */
+const normalizeStoredPreference = (
+  value: unknown
+): StoredTablePreference | null => {
+  if (!value || typeof value !== 'object') return null
+  if (isStoredPreference(value)) {
+    return {
+      schemaVersion: Number(value.schemaVersion) || 1,
+      updatedAt: value.updatedAt || new Date(0).toISOString(),
+      value: normalizePreference(value.value),
+    }
+  }
+  return {
+    schemaVersion: 1,
+    updatedAt: new Date(0).toISOString(),
+    value: normalizePreference(migrateLegacyTablePreference(value)),
+  }
+}
+
+const defaultMigrations: PreferenceMigration[] = [
+  {
+    from: 1,
+    to: 2,
+    migrate: normalizePreference,
+  },
+  {
+    from: 2,
+    to: 3,
+    migrate: normalizePreference,
+  },
+]
+
+const migrateStoredPreference = (
+  stored: StoredTablePreference,
+  migrations: PreferenceMigration[] = defaultMigrations
+): StoredTablePreference => {
+  let current = {
+    ...stored,
+    value: clonePreference(stored.value),
+  }
+  while (current.schemaVersion < TABLE_PREFERENCE_SCHEMA_VERSION) {
+    const migration = migrations.find(
+      (item) => item.from === current.schemaVersion
+    )
+    if (!migration || migration.to <= migration.from) {
+      throw new Error(
+        `[TableComponent] Missing preference migration from schema v${current.schemaVersion}.`
+      )
+    }
+    current = {
+      schemaVersion: migration.to,
+      updatedAt: current.updatedAt,
+      value: migration.migrate(current.value),
+    }
+  }
+  if (current.schemaVersion > TABLE_PREFERENCE_SCHEMA_VERSION) {
+    throw new Error(
+      `[TableComponent] Preference schema v${current.schemaVersion} is newer than supported v${TABLE_PREFERENCE_SCHEMA_VERSION}.`
+    )
+  }
+  return current
+}
+
+const localRootKey = (userScope: string) =>
+  `he:table-component:preference:${userScope}`
+
+/** 创建实例内存储；用于显式关闭持久化后仍保留统一的会话与重置语义。 */
+export const createMemoryPreferenceStore = (): PreferenceStore => {
+  const values = new Map<string, StoredTablePreference>()
+  const resolveKey = ({ userScope, tableKey }: PreferenceKey) =>
+    `${userScope}\u0000${tableKey}`
+  return {
+    async load(key) {
+      return values.get(resolveKey(key)) ?? null
+    },
+    async save(key, value) {
+      values.set(resolveKey(key), value)
+    },
+    async remove(key) {
+      values.delete(resolveKey(key))
+    },
+  }
+}
+
+export const createLocalPreferenceStore = (
+  storage?: StorageLike
+): PreferenceStore => {
+  const parseRoot = (raw: string | null): UnknownPreference => {
+    if (!raw) return {}
+    const parsed: unknown = JSON.parse(raw)
+    return isUnknownPreference(parsed) ? parsed : {}
+  }
+  const readRoot = (userScope: string) => {
+    const raw = (storage ?? globalThis.localStorage).getItem(
+      localRootKey(userScope)
+    )
+    return parseRoot(raw)
+  }
+
+  return {
+    async load(key) {
+      const current = readRoot(key.userScope)[key.tableKey]
+      if (current) return normalizeStoredPreference(current)
+      const legacyRaw = (storage ?? globalThis.localStorage).getItem(
+        LEGACY_LOCAL_STORAGE_KEY
+      )
+      const legacyRoot = parseRoot(legacyRaw)
+      return normalizeStoredPreference(legacyRoot[key.tableKey])
+    },
+    async save(key, value) {
+      const root = readRoot(key.userScope)
+      root[key.tableKey] = value
+      ;(storage ?? globalThis.localStorage).setItem(
+        localRootKey(key.userScope),
+        JSON.stringify(root)
+      )
+    },
+    async remove(key) {
+      const root = readRoot(key.userScope)
+      delete root[key.tableKey]
+      ;(storage ?? globalThis.localStorage).setItem(
+        localRootKey(key.userScope),
+        JSON.stringify(root)
+      )
+    },
+  }
+}
+
+/**
+ * 偏好读取、迁移和串行写入协调器。
+ *
+ * 读取失败时继续返回安全默认值，但状态保持 failed，后续保存会被阻止，避免用默认
+ * 空配置覆盖远端历史数据；写操作排队执行，防止连续拖拽列宽时后发请求被先发请求
+ * 反向覆盖。
+ */
+class PreferenceCoordinator implements TablePreferenceSession {
+  status: PreferenceStatus = 'idle'
+  error: unknown = null
+  private value: TablePreference
+  private writeQueue: Promise<void> = Promise.resolve()
+  private pendingWrite: Promise<void> = Promise.resolve()
+  private readonly listeners = new Set<() => void>()
+
+  constructor(private readonly options: PreferenceCoordinatorOptions) {
+    this.value = normalizePreference(options.fallback)
+  }
+
+  get snapshot(): PreferenceSnapshot {
+    return {
+      status: this.status,
+      error: this.error,
+      value: clonePreference(this.value),
+    }
+  }
+
+  subscribe(listener: () => void) {
+    this.listeners.add(listener)
+    return () => {
+      this.listeners.delete(listener)
+    }
+  }
+
+  private notify() {
+    this.listeners.forEach((listener) => listener())
+  }
+
+  async load(): Promise<TablePreference> {
+    this.status = 'loading'
+    this.error = null
+    this.notify()
+    try {
+      let stored = await this.options.store.load(this.options.key)
+      let migratedFromKey: string | undefined
+      if (!stored) {
+        // 组件改名时按顺序寻找旧 key，命中后会自动写回当前 key。
+        for (const tableKey of this.options.legacyTableKeys ?? []) {
+          stored = await this.options.store.load({
+            ...this.options.key,
+            tableKey,
+          })
+          if (stored) {
+            migratedFromKey = tableKey
+            break
+          }
+        }
+      }
+
+      this.status = 'ready'
+      if (!stored) {
+        this.notify()
+        return clonePreference(this.value)
+      }
+      const migrated = migrateStoredPreference(
+        stored,
+        this.options.migrations ?? defaultMigrations
+      )
+      this.value = normalizePreference(migrated.value)
+
+      if (migratedFromKey || migrated.schemaVersion !== stored.schemaVersion) {
+        await this.save(this.value)
+      } else {
+        this.notify()
+      }
+      return clonePreference(this.value)
+    } catch (error) {
+      this.status = 'failed'
+      this.error = error
+      this.notify()
+      return clonePreference(this.value)
+    }
+  }
+
+  private assertReady(operation: 'save' | 'remove') {
+    if (this.status !== 'ready') {
+      throw new Error(
+        `[TableComponent] Preference ${operation} blocked while status is "${this.status}".`
+      )
+    }
+  }
+
+  private enqueueSave(value: TablePreference) {
+    const write = this.writeQueue.then(() =>
+      this.options.store.save(this.options.key, {
+        schemaVersion: TABLE_PREFERENCE_SCHEMA_VERSION,
+        updatedAt: new Date().toISOString(),
+        value,
+      })
+    )
+    this.pendingWrite = write
+    this.writeQueue = write.catch(() => {})
+    return write
+  }
+
+  /** @deprecated 新代码应使用 update，避免调用方提交过期的完整快照。 */
+  async save(value: TablePreference) {
+    this.assertReady('save')
+    const normalized = normalizePreference(value)
+    // 先更新内存快照，后续 update 即使在远程写入完成前也能基于最新值合并。
+    this.value = normalized
+    this.error = null
+    this.notify()
+    try {
+      await this.enqueueSave(normalized)
+      this.error = null
+      this.notify()
+    } catch (error) {
+      this.error = error
+      this.notify()
+      throw error
+    }
+  }
+
+  async update(updater: TablePreferenceUpdater) {
+    this.assertReady('save')
+    const next = normalizePreference(updater(clonePreference(this.value)))
+    await this.save(next)
+    return clonePreference(next)
+  }
+
+  async reset() {
+    this.assertReady('remove')
+    const write = this.writeQueue.then(() =>
+      this.options.store.remove(this.options.key)
+    )
+    this.pendingWrite = write
+    this.writeQueue = write.catch(() => {})
+    try {
+      await write
+      this.value = normalizePreference(this.options.fallback)
+      this.error = null
+      this.notify()
+      return clonePreference(this.value)
+    } catch (error) {
+      this.error = error
+      this.notify()
+      throw error
+    }
+  }
+
+  /** @deprecated 使用 reset。 */
+  async remove() {
+    await this.reset()
+  }
+
+  async flush() {
+    await this.pendingWrite
+  }
+}
+
+export const createPreferenceCoordinator = (
+  options: PreferenceCoordinatorOptions
+) => new PreferenceCoordinator(options)

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

@@ -0,0 +1,28 @@
+import type { TablePageSize } from '../pagination/types'
+import type { TableDensity } from '../shared/theme'
+
+/** 按 tableKey 持久化的用户个性化设置，不包含业务数据和临时 UI 状态。 */
+export interface TablePreference {
+  /** 用户上次选择的每页条数。 */
+  pageSize?: TablePageSize
+  /** 按稳定列 key 保存的可视列顺序。 */
+  columnOrder: string[]
+  /** 用户隐藏但仍可在列设置中恢复的列 key。 */
+  hiddenColumns: string[]
+  /** 按稳定列 key 保存的像素宽度。 */
+  columnWidths: Record<string, number>
+  /** 从逻辑起始侧冻结的连续列 key。 */
+  frozenColumns?: string[]
+  /** 从顶部冻结的数据行数量。 */
+  frozenRows?: number
+  /** 按条件 key 保存的筛选项顺序。 */
+  searchOrder?: string[]
+  /** 用户隐藏的筛选条件 key。 */
+  hiddenSearchConditions?: string[]
+  /** 用户最后选择的表格密度。 */
+  density?: TableDensity
+  /** 用户调整后的底部工作区高度。 */
+  bottomHeight?: number
+  /** 用户调整后的右侧工作区宽度。 */
+  rightWidth?: number
+}

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

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

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

@@ -0,0 +1,18 @@
+export interface TableRightPanelConfig {
+  /** 默认关闭，只有业务明确要求时才初始展开。 */
+  defaultOpen?: boolean
+  /** 面板宽度，支持像素数或 CSS 长度。 */
+  width?: number | string
+  /** 是否允许用户拖动左边缘调整面板宽度，默认 true。 */
+  resizable?: boolean
+  /** 用户拖动时允许的最小像素宽度。 */
+  minWidth?: number
+  /** 用户拖动时允许的最大像素宽度。 */
+  maxWidth?: number
+  /** 右侧面板头部标题。 */
+  title?: string
+  /** 是否显示关闭入口，默认 true。 */
+  closable?: boolean
+  /** 查询时默认收起，设为 false 可保留面板状态。 */
+  collapseOnQuery?: boolean
+}

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

@@ -0,0 +1,64 @@
+import { resolveTableSearchConditionLabels } from './query'
+import type {
+  TableDateRangeBoundary,
+  TableQueryOperator,
+  TableSearchCondition,
+} from './types'
+
+export interface TableSearchConditionDefaults {
+  /** input 和未声明 type 的文本条件默认匹配方式。 */
+  inputOperator?: TableQueryOperator
+  /** dateRange 默认边界处理方式。 */
+  dateRangeBoundary?: TableDateRangeBoundary
+}
+
+class TableSearchConfigError extends Error {
+  readonly code = 'TABLE_SEARCH_CONFIG_INVALID'
+
+  constructor(message: string) {
+    super(`[TableComponent] ${message}`)
+    this.name = 'TableSearchConfigError'
+  }
+}
+
+/** 校验、复制并补全搜索条件标题，避免 preference 和查询模型修改业务原对象。 */
+export const resolveTableSearchConditions = (
+  conditions: readonly TableSearchCondition[],
+  columnLabels: Readonly<Record<string, string>> = {},
+  defaults: Readonly<TableSearchConditionDefaults> = {}
+): TableSearchCondition[] => {
+  const keys = new Set<string>()
+  return resolveTableSearchConditionLabels(conditions, columnLabels).map(
+    (condition) => {
+      if (!condition.key.trim()) {
+        throw new TableSearchConfigError('Search condition key is required.')
+      }
+      if (keys.has(condition.key)) {
+        throw new TableSearchConfigError(
+          `Duplicate search condition key "${condition.key}".`
+        )
+      }
+      keys.add(condition.key)
+      const textCondition =
+        condition.type === 'input' || condition.type === undefined
+      return {
+        ...condition,
+        operator:
+          condition.operator ??
+          (textCondition ? defaults.inputOperator : undefined),
+        dateRangeBoundary:
+          condition.dateRangeBoundary ??
+          (condition.type === 'dateRange'
+            ? defaults.dateRangeBoundary
+            : undefined),
+        operatorOptions: condition.operatorOptions?.map((option) => ({
+          ...option,
+        })),
+        options: condition.options?.map((option) => ({ ...option })),
+        defaultValue: Array.isArray(condition.defaultValue)
+          ? [...condition.defaultValue]
+          : condition.defaultValue,
+      }
+    }
+  )
+}

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

@@ -0,0 +1,8 @@
+/** 搜索领域、键盘和布局默认值；engine 与 React 层共享，避免各自写入魔法值。 */
+export const TABLE_SEARCH_DEFAULTS = {
+  contentOverflowTolerance: 1,
+  imeProcessKeyCode: 229,
+  inputOperator: 'include',
+  dateRangeBoundary: 'raw',
+  resetBehavior: 'query',
+} as const

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

@@ -0,0 +1,7 @@
+export * from './config'
+export * from './constants'
+export * from './query'
+export * from './localQuery'
+export * from './remoteQuery'
+export * from './searchInteraction'
+export type * from './types'