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

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

@@ -0,0 +1,145 @@
+import { getTableRowValue } from '../shared/row'
+import {
+  TABLE_TASK_YIELD_INTERVAL,
+  yieldTableMainThread,
+} from '../shared/scheduler'
+import type { TableRow } from '../shared/types'
+import type { TableQueryParams } from './types'
+
+const throwIfAborted = (signal?: AbortSignal) => {
+  if (signal?.aborted) throw signal.reason
+}
+
+const matchesTableWhere = (
+  value: unknown,
+  where: TableQueryParams['where'][number]
+) => {
+  const target = where.value
+  const normalizedValue = String(value ?? '').toLocaleLowerCase()
+  const normalizedTarget = String(target ?? '').toLocaleLowerCase()
+
+  switch (where.operator) {
+    case 'eq':
+      return Object.is(value, target) || normalizedValue === normalizedTarget
+    case 'ne':
+      return !(Object.is(value, target) || normalizedValue === normalizedTarget)
+    case 'include':
+    case 'contains':
+      return normalizedValue.includes(normalizedTarget)
+    case 'notInclude':
+      return !normalizedValue.includes(normalizedTarget)
+    case 'startsWith':
+      return normalizedValue.startsWith(normalizedTarget)
+    case 'endsWith':
+      return normalizedValue.endsWith(normalizedTarget)
+    case 'gt':
+      return Number(value) > Number(target)
+    case 'gte':
+      return Number(value) >= Number(target)
+    case 'lt':
+      return Number(value) < Number(target)
+    case 'lte':
+      return Number(value) <= Number(target)
+    case 'in':
+      return Array.isArray(target)
+        ? target.some((entry) => Object.is(entry, value))
+        : false
+    case 'notIn':
+      return Array.isArray(target)
+        ? !target.some((entry) => Object.is(entry, value))
+        : true
+    case 'between':
+      return Array.isArray(target) && target.length === 2
+        ? String(value) >= String(target[0]) &&
+            String(value) <= String(target[1])
+        : true
+  }
+}
+
+const compareTableRows = <T extends TableRow>(
+  left: T,
+  right: T,
+  sort: NonNullable<TableQueryParams['sort']>
+) => {
+  for (const item of sort) {
+    const result = String(
+      getTableRowValue(left, item.field) ?? ''
+    ).localeCompare(
+      String(getTableRowValue(right, item.field) ?? ''),
+      'zh-CN',
+      { numeric: true }
+    )
+    if (result !== 0) return item.direction === 'asc' ? result : -result
+  }
+  return 0
+}
+
+/** 可取消的稳定归并排序；大型本地查询不会被一次原生 sort 长任务独占主线程。 */
+const sortTableRows = async <T extends TableRow>(
+  rows: T[],
+  sort: NonNullable<TableQueryParams['sort']>,
+  signal: AbortSignal | undefined,
+  yieldInterval: number
+) => {
+  if (rows.length < 2) return rows
+  let source = [...rows]
+  let target = new Array<T>(rows.length)
+  let operations = 0
+
+  for (let width = 1; width < rows.length; width *= 2) {
+    for (let start = 0; start < rows.length; start += width * 2) {
+      const middle = Math.min(start + width, rows.length)
+      const end = Math.min(start + width * 2, rows.length)
+      let left = start
+      let right = middle
+      let write = start
+      while (left < middle || right < end) {
+        target[write++] =
+          right >= end ||
+          (left < middle &&
+            compareTableRows(source[left]!, source[right]!, sort) <= 0)
+            ? source[left++]!
+            : source[right++]!
+        operations += 1
+        if (operations % yieldInterval === 0) {
+          throwIfAborted(signal)
+          await yieldTableMainThread()
+        }
+      }
+    }
+    ;[source, target] = [target, source]
+    throwIfAborted(signal)
+  }
+  return source
+}
+
+/** 在主线程分片执行本地筛选和排序；大数据跨页查询仍应优先使用远程 provider。 */
+export const runTableLocalQuery = async <T extends TableRow>(
+  rows: readonly T[],
+  params: TableQueryParams,
+  options: { signal?: AbortSignal; yieldInterval?: number } = {}
+) => {
+  const yieldInterval = Math.max(
+    1,
+    options.yieldInterval ?? TABLE_TASK_YIELD_INTERVAL
+  )
+  const filtered: T[] = []
+  for (let index = 0; index < rows.length; index += 1) {
+    const row = rows[index]!
+    if (
+      params.where.every((where) =>
+        matchesTableWhere(getTableRowValue(row, where.field), where)
+      )
+    ) {
+      filtered.push(row)
+    }
+    if ((index + 1) % yieldInterval === 0) {
+      throwIfAborted(options.signal)
+      await yieldTableMainThread()
+    }
+  }
+  throwIfAborted(options.signal)
+  return params.sort?.length
+    ? sortTableRows(filtered, params.sort, options.signal, yieldInterval)
+    : filtered
+}

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

@@ -0,0 +1,203 @@
+import { cloneTableValue } from '../shared/valueSnapshot'
+import type {
+  TableQueryOperator,
+  TableQueryParams,
+  TableSearchCondition,
+  TableSearchModel,
+  TableSort,
+  TableWhere,
+} from './types'
+
+/** 创建与调用方完全断开引用的查询参数快照，避免请求或报表 provider 反向改写状态。 */
+export const createTableQueryParamsSnapshot = (
+  params: Readonly<TableQueryParams>
+): TableQueryParams => ({
+  page: params.page,
+  pageSize: params.pageSize,
+  where: params.where.map(({ field, operator, value }) => ({
+    field,
+    operator,
+    value: cloneTableValue(value),
+  })),
+  ...(params.sort?.length
+    ? {
+        sort: params.sort.map(({ field, direction }) => ({ field, direction })),
+      }
+    : {}),
+})
+
+const normalizeQueryIdentityValue = (
+  value: unknown,
+  ancestors: WeakSet<object>
+): unknown => {
+  if (value === null || typeof value !== 'object') return value
+  if (value instanceof Date) return value.toISOString()
+  if (ancestors.has(value)) {
+    throw new Error('[TableComponent] Query values must not contain cycles.')
+  }
+  ancestors.add(value)
+  const normalized = Array.isArray(value)
+    ? value.map((item) => normalizeQueryIdentityValue(item, ancestors))
+    : Object.fromEntries(
+        Object.keys(value)
+          .sort()
+          .map((key) => [
+            key,
+            normalizeQueryIdentityValue(
+              Reflect.get(value as object, key),
+              ancestors
+            ),
+          ])
+      )
+  ancestors.delete(value)
+  return normalized
+}
+
+/**
+ * 生成不包含分页位置的稳定结果集身份。相同筛选/排序即使对象键顺序不同也得到同一值。
+ */
+export const createTableQueryIdentity = (params: Readonly<TableQueryParams>) =>
+  JSON.stringify(
+    normalizeQueryIdentityValue(
+      { where: params.where, sort: params.sort ?? [] },
+      new WeakSet()
+    )
+  )
+
+export const resolveTableSearchConditionLabels = (
+  conditions: readonly TableSearchCondition[],
+  columnLabels: Readonly<Record<string, string>> = {}
+): TableSearchCondition[] =>
+  conditions.map((condition) => ({
+    ...condition,
+    label:
+      condition.label?.trim() || columnLabels[condition.key] || condition.key,
+  }))
+
+const isEmptySearchValue = (value: unknown): boolean =>
+  value === undefined ||
+  value === null ||
+  value === '' ||
+  (Array.isArray(value) && value.length === 0)
+
+const isConditionSearchValue = (
+  value: unknown
+): value is { operator: TableQueryOperator; value: unknown } =>
+  Boolean(
+    value &&
+    typeof value === 'object' &&
+    'operator' in value &&
+    'value' in value
+  )
+
+const getDefaultOperator = (
+  condition: TableSearchCondition,
+  value: unknown
+): TableQueryOperator => {
+  if (condition.operator) return condition.operator
+  if (condition.type === 'dateRange') return 'between'
+  if (
+    condition.type === 'multiSelect' ||
+    (condition.type === 'remoteSelect' && condition.remoteMultiple) ||
+    Array.isArray(value)
+  )
+    return 'in'
+  return condition.type === 'input' || condition.type === undefined
+    ? 'include'
+    : 'eq'
+}
+
+const normalizeTableWhereResult = (
+  result: TableWhere | TableWhere[] | null | undefined
+): TableWhere[] => {
+  if (!result) return []
+  return Array.isArray(result) ? result : [result]
+}
+
+const appendDateRangeBoundary = (
+  value: unknown,
+  boundary: TableSearchCondition['dateRangeBoundary']
+) => {
+  if (boundary !== 'day' || !Array.isArray(value) || value.length !== 2) {
+    return value
+  }
+  const [start, end] = value
+  return [
+    typeof start === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(start)
+      ? `${start} 00:00:00`
+      : start,
+    typeof end === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(end)
+      ? `${end} 23:59:59`
+      : end,
+  ]
+}
+
+/** 将筛选模型编译为后端无关的 where 数组，空值不会生成条件。 */
+const buildTableWhere = (
+  conditions: TableSearchCondition[],
+  model: TableSearchModel
+): TableWhere[] =>
+  conditions.flatMap((condition) => {
+    const modelValue = model[condition.key]
+    const rawValue = isConditionSearchValue(modelValue)
+      ? modelValue.value
+      : modelValue
+    const normalizedValue =
+      typeof rawValue === 'string' ? rawValue.trim() : rawValue
+    if (isEmptySearchValue(normalizedValue)) return []
+    const value = appendDateRangeBoundary(
+      normalizedValue,
+      condition.dateRangeBoundary
+    )
+    if (condition.toWhere) {
+      // 自定义转换允许返回单条、多条或空结果，这里统一成 flatMap 所需数组。
+      return normalizeTableWhereResult(condition.toWhere(value, condition))
+    }
+    return [
+      {
+        field: condition.key,
+        operator: isConditionSearchValue(modelValue)
+          ? modelValue.operator
+          : getDefaultOperator(condition, value),
+        value,
+      },
+    ]
+  })
+
+export const buildTableQueryParams = (
+  page: number,
+  pageSize: number,
+  conditions: TableSearchCondition[],
+  model: TableSearchModel,
+  sort: readonly TableSort[] = []
+): TableQueryParams => {
+  const params: TableQueryParams = {
+    page,
+    pageSize,
+    where: buildTableWhere(conditions, model),
+  }
+  if (sort.length) params.sort = [...sort]
+  return params
+}
+
+export const createSearchModel = (
+  conditions: readonly TableSearchCondition[]
+): TableSearchModel =>
+  Object.fromEntries(
+    conditions.map((condition) => [
+      condition.key,
+      condition.type === 'condition'
+        ? {
+            operator:
+              condition.operator ??
+              condition.operatorOptions?.[0]?.value ??
+              'include',
+            value: Array.isArray(condition.defaultValue)
+              ? [...condition.defaultValue]
+              : condition.defaultValue,
+          }
+        : Array.isArray(condition.defaultValue)
+          ? [...condition.defaultValue]
+          : condition.defaultValue,
+    ])
+  )

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

@@ -0,0 +1,99 @@
+import type { TableRow } from '../shared/types'
+import type {
+  TableQuery,
+  TableQueryContext,
+  TableQueryParams,
+  TableQueryResult,
+} from './types'
+
+export type RemoteQueryStatus = 'applied' | 'aborted' | 'stale'
+
+/**
+ * 一次远程查询的可观察结果。
+ *
+ * `stale` 表示请求虽然已经返回，但在它之后又发起了更新的请求，因此调用方不得
+ * 再用该结果覆盖表格；`aborted` 表示请求被主动取消。这两个状态都不是业务异常。
+ */
+export interface RemoteQueryOutcome<T extends TableRow = TableRow> {
+  /** 请求应用结果；stale 和 aborted 都不应覆盖当前表格数据。 */
+  status: RemoteQueryStatus
+  /** 控制器为本次查询分配的递增请求序号。 */
+  requestId: number
+  /** status 为 applied 时返回的业务查询结果。 */
+  result?: TableQueryResult<T>
+}
+
+interface RemoteQueryRunnerOptions {
+  /** 当前表格稳定标识，会传入每次查询的上下文。 */
+  tableKey: string
+}
+
+const normalizeResult = <T extends TableRow>(
+  value: TableQueryResult<T> | { data: TableQueryResult<T> }
+): TableQueryResult<T> => ('data' in value ? value.data : value)
+
+const isAbortError = (error: unknown) =>
+  error instanceof DOMException
+    ? error.name === 'AbortError'
+    : error instanceof Error && error.name === 'AbortError'
+
+/**
+ * 框架无关的远程查询执行器，采用“最后一次请求生效”策略。
+ *
+ * 每次 `run()` 都会取消上一次请求，并通过递增的 requestId 再做一层竞态保护。
+ * 即使业务请求库没有正确响应 AbortSignal，迟到结果也只会返回 `stale`，不会污染
+ * 当前数据。所有 React 查询入口共同复用这里的并发语义。
+ */
+class RemoteQueryRunner<T extends TableRow = TableRow> {
+  private requestId = 0
+  private controller: AbortController | null = null
+
+  constructor(
+    private readonly query: TableQuery<T>,
+    private readonly options: RemoteQueryRunnerOptions
+  ) {}
+
+  get currentRequestId() {
+    return this.requestId
+  }
+
+  async run(params: TableQueryParams): Promise<RemoteQueryOutcome<T>> {
+    // AbortSignal 负责尽快释放网络资源，requestId 负责兜底拦截无法真正取消的请求。
+    this.controller?.abort()
+    const controller = new AbortController()
+    const requestId = ++this.requestId
+    this.controller = controller
+
+    const context: TableQueryContext = {
+      signal: controller.signal,
+      requestId,
+      tableKey: this.options.tableKey,
+    }
+
+    try {
+      const result = normalizeResult(await this.query(params, context))
+      if (requestId !== this.requestId) return { status: 'stale', requestId }
+      return { status: 'applied', requestId, result }
+    } catch (error) {
+      if (controller.signal.aborted || isAbortError(error)) {
+        return { status: 'aborted', requestId }
+      }
+      if (requestId !== this.requestId) return { status: 'stale', requestId }
+      throw error
+    } finally {
+      if (this.controller === controller) this.controller = null
+    }
+  }
+
+  /** 取消当前请求并推进请求世代，同时保留 provider 与递增 requestId。 */
+  cancel() {
+    this.controller?.abort()
+    this.controller = null
+    this.requestId += 1
+  }
+}
+
+export const createRemoteQueryRunner = <T extends TableRow>(
+  query: TableQuery<T>,
+  options: RemoteQueryRunnerOptions
+) => new RemoteQueryRunner(query, options)

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

@@ -0,0 +1,46 @@
+import { TABLE_SEARCH_DEFAULTS } from './constants'
+
+interface TableSearchEnterEvent {
+  defaultPrevented?: boolean
+  isComposing?: boolean
+  keyCode?: number
+  target?: unknown
+}
+
+const SEARCH_ENTER_EXCLUSION =
+  ".el-select, .el-date-editor, [role='combobox'], [role='listbox']"
+
+export const shouldSubmitTableSearchOnEnter = (
+  event: TableSearchEnterEvent
+) => {
+  if (
+    event.defaultPrevented ||
+    event.isComposing ||
+    event.keyCode === TABLE_SEARCH_DEFAULTS.imeProcessKeyCode
+  ) {
+    return false
+  }
+  const target = event.target
+  if (!target || (typeof target !== 'object' && typeof target !== 'function')) {
+    return true
+  }
+  const isContentEditable = Reflect.get(target, 'isContentEditable')
+  const tagName = Reflect.get(target, 'tagName')
+  if (
+    isContentEditable === true ||
+    (typeof tagName === 'string' && tagName.toUpperCase() === 'TEXTAREA')
+  ) {
+    return false
+  }
+  const closest = Reflect.get(target, 'closest')
+  return (
+    typeof closest !== 'function' ||
+    !Reflect.apply(closest, target, [SEARCH_ENTER_EXCLUSION])
+  )
+}
+
+export const isTableSearchContentOverflowing = (
+  scrollHeight: number,
+  clientHeight: number,
+  tolerance = TABLE_SEARCH_DEFAULTS.contentOverflowTolerance
+) => scrollHeight > clientHeight + tolerance

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

@@ -0,0 +1,155 @@
+import type { TableOption, TableRow } from '../shared/types'
+
+/** 搜索表单的动态值集合；读取后必须按条件类型收窄。 */
+export type TableSearchModel = Record<string, unknown>
+
+export type TableQueryOperator =
+  | 'eq'
+  | 'ne'
+  | 'include'
+  | 'notInclude'
+  | 'startsWith'
+  | 'endsWith'
+  | 'contains'
+  | 'gt'
+  | 'gte'
+  | 'lt'
+  | 'lte'
+  | 'in'
+  | 'notIn'
+  | 'between'
+
+/** 日期范围提交给后端时是否补齐自然日的起止时间。 */
+export type TableDateRangeBoundary = 'raw' | 'day'
+
+/** 点击重置后只清空条件，或清空并立即重新查询。 */
+export type TableSearchResetBehavior = 'clear' | 'query'
+
+export interface TableSearchCondition {
+  /** 搜索字段稳定 key，默认同时作为提交给后端的 field。 */
+  key: string
+  /** 未填写时先继承同 key 表格列标题，仍不存在则回退为 key。 */
+  label?: string
+  /** 搜索控件类型，默认 input；custom 需要由框架适配层的 renderer 或插槽提供 UI。 */
+  type?:
+    | 'input'
+    | 'condition'
+    | 'select'
+    | 'multiSelect'
+    | 'remoteSelect'
+    | 'date'
+    | 'dateRange'
+    | 'datetime'
+    | 'custom'
+  /** 默认查询运算符；不同控件类型会在未配置时使用各自安全默认值。 */
+  operator?: TableQueryOperator
+  /** condition 控件允许用户切换的运算符及显示文案。 */
+  operatorOptions?: Array<{
+    /** 运算符下拉项文案。 */
+    label: string
+    /** 提交给后端的稳定运算符值。 */
+    value: TableQueryOperator
+  }>
+  /** 输入控件的占位文案。 */
+  placeholder?: string
+  /** 是否允许清空当前条件值，默认 true。 */
+  clearable?: boolean
+  /** select/multiSelect 使用的静态候选项。 */
+  options?: TableOption[]
+  /** remoteSelect 的可取消远程选项加载器。 */
+  loadOptions?: TableSearchOptionLoader
+  /** remoteSelect 是否允许多选，默认 false。 */
+  remoteMultiple?: boolean
+  /** 搜索模型首次创建时写入的默认值。 */
+  defaultValue?: unknown
+  /** dateRange 专用；day 会生成 00:00:00 到 23:59:59，默认 raw。 */
+  dateRangeBoundary?: TableDateRangeBoundary
+  /** 自定义 UI 或特殊后端条件的纯函数转换出口，不能在这里操作 React 状态。 */
+  toWhere?: (
+    value: unknown,
+    condition: TableSearchCondition
+  ) => TableWhere | TableWhere[] | null | undefined
+}
+
+export interface TableSearchOptionRequest {
+  /** 用户当前输入的远程搜索文本。 */
+  query: string
+  /** 新请求或组件销毁时会中止的信号。 */
+  signal: AbortSignal
+  /** 发起搜索的表格稳定 key。 */
+  tableKey: string
+  /** 发起搜索的条件稳定 key。 */
+  conditionKey: string
+}
+
+export type TableSearchOptionLoader = (
+  request: TableSearchOptionRequest
+) => Promise<readonly TableOption[]>
+
+export interface TableWhere<TValue = unknown> {
+  /** 后端查询字段名。 */
+  field: string
+  /** 后端与前端共同约定的查询运算符。 */
+  operator: TableQueryOperator
+  /** 未经字符串化的查询值。 */
+  value: TValue
+}
+
+export interface TableSort {
+  /** 后端排序字段名。 */
+  field: string
+  /** 排序方向。 */
+  direction: 'asc' | 'desc'
+}
+
+/** 远程查询的稳定请求结构，可由 React 页面直接提交给业务 API。 */
+export interface TableQueryParams {
+  /** 从 1 开始的当前页码。 */
+  page: number
+  /** 每页请求条数。 */
+  pageSize: number
+  /** 由搜索模型编译出的结构化查询条件。 */
+  where: TableWhere[]
+  /** 远程排序优先级列表；数组顺序表示多列排序优先级。 */
+  sort?: TableSort[]
+}
+
+export interface TableSearchSubmitContext {
+  /** 当前只读搜索表单模型。 */
+  model: Readonly<TableSearchModel>
+  /** 即将提交的完整查询参数。 */
+  params: Readonly<TableQueryParams>
+}
+
+/** 返回 false 取消内置查询，返回 params 改写请求，void 继续使用原请求。 */
+export type TableSearchSubmitInterceptor = (
+  context: TableSearchSubmitContext
+) => false | void | TableQueryParams | Promise<false | void | TableQueryParams>
+
+export interface TableQueryResult<T extends TableRow = TableRow> {
+  /** 当前请求返回的业务行列表。 */
+  list: T[]
+  /** 当前筛选条件下的后端总条数。 */
+  total: number
+}
+
+/** engine 提供给查询函数的实例身份与并发控制上下文。 */
+export interface TableQueryContext {
+  /** 新查询或组件销毁时会中止的信号。 */
+  signal: AbortSignal
+  /** 当前实例单调递增的请求编号，用于识别晚到响应。 */
+  requestId: number
+  /** 发起查询的表格稳定 key。 */
+  tableKey: string
+}
+
+export type TableQuery<T extends TableRow = TableRow> = (
+  params: TableQueryParams,
+  context: TableQueryContext
+) => Promise<
+  | TableQueryResult<T>
+  | {
+      /** 兼容常见 HTTP 客户端响应包装的查询结果。 */
+      data: TableQueryResult<T>
+    }
+>

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

@@ -0,0 +1,13 @@
+import type { TableRow } from '../shared/types'
+import type { RowKeyResolver } from '../table/editing'
+import type { TableSelectionOptions } from './selection'
+
+/** 将公开选择配置收敛为纯 JS Selection 状态机的输入。 */
+export const buildTableSelectionOptions = <T extends TableRow>(
+  rowKey: RowKeyResolver<T>,
+  options: Pick<TableSelectionOptions<T>, 'multiple' | 'isRowSelectable'> = {}
+): TableSelectionOptions<T> => ({
+  rowKey,
+  multiple: options.multiple,
+  isRowSelectable: options.isRowSelectable,
+})

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

@@ -0,0 +1,4 @@
+export * from './selection'
+export * from './selectionHeader'
+export * from './types'
+export * from './config'