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

package/template/src/components/AppPageForm/validation.ts

@@ -0,0 +1,233 @@
+import { resolvePageFormConfig } from './config'
+import type {
+  IFormItem,
+  IFormProp,
+  PageFormMode,
+  PageFormRecord,
+  PageFormRule,
+  PageFormValidateFactory,
+  PageFormValidationIssue,
+  PageFormValidationResult,
+  ResolvedIFormItem,
+  IPageFormMessages,
+} from './types'
+
+const isEmptyPageFormValue = (value: unknown) =>
+  value === undefined ||
+  value === null ||
+  value === '' ||
+  (Array.isArray(value) && value.length === 0)
+
+const decimalPlaces = (value: unknown) => {
+  const source = String(value).trim().toLowerCase()
+  const match = source.match(/^[+-]?(\d+)(?:\.(\d*))?(?:e([+-]?\d+))?$/)
+  if (!match) return 0
+  const fractionLength = match[2]?.length ?? 0
+  const exponent = Number(match[3] ?? 0)
+  return Math.max(0, fractionLength - exponent)
+}
+
+const issue = <TModel extends PageFormRecord>(
+  item: ResolvedIFormItem<TModel>,
+  code: string,
+  message: string
+): PageFormValidationIssue => ({ prop: item.prop, code, message })
+
+const validatePageFormValue = <TModel extends PageFormRecord>(
+  value: unknown,
+  item: ResolvedIFormItem<TModel>,
+  messages: IPageFormMessages
+): PageFormValidationIssue | undefined => {
+  const label = item.label || messages.strFieldFallback
+  if (item.required && isEmptyPageFormValue(value)) {
+    return issue(item, 'required', messages.fnRequired(label))
+  }
+  if (isEmptyPageFormValue(value)) return
+
+  const source = String(value)
+  const numeric = Number(value)
+  const needsNumber =
+    item.isNumber ||
+    item.isPositiveNumber ||
+    item.isPositiveInt ||
+    item.decimalsLimit !== undefined
+  if (needsNumber && (!source.trim() || !Number.isFinite(numeric))) {
+    return issue(item, 'isNumber', messages.fnNumber(label))
+  }
+  if (item.isPositiveNumber && numeric <= 0) {
+    return issue(item, 'isPositiveNumber', messages.fnPositiveNumber(label))
+  }
+  if (item.isPositiveInt && (!Number.isInteger(numeric) || numeric <= 0)) {
+    return issue(item, 'isPositiveInt', messages.fnPositiveInt(label))
+  }
+  if (item.isEmail && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(source)) {
+    return issue(item, 'isEmail', messages.fnInvalidFormat(label))
+  }
+  if (item.isPhone && !/^1[3-9]\d{9}$/.test(source)) {
+    return issue(item, 'isPhone', messages.fnInvalidFormat(label))
+  }
+  if (item.notChinese && /[\u3400-\u9fff]/u.test(source)) {
+    return issue(item, 'notChinese', messages.fnNoChinese(label))
+  }
+  if (
+    item.lengthGreaterThan !== undefined &&
+    source.length <= item.lengthGreaterThan
+  ) {
+    return issue(
+      item,
+      'lengthGreaterThan',
+      messages.fnLengthGreaterThan(item.lengthGreaterThan, label)
+    )
+  }
+  if (
+    item.decimalsLimit !== undefined &&
+    item.decimalsLimit >= 0 &&
+    decimalPlaces(value) > item.decimalsLimit
+  ) {
+    return issue(
+      item,
+      'decimalsLimit',
+      messages.fnDecimalsLimit(item.decimalsLimit, label)
+    )
+  }
+}
+
+const validatorRule = (
+  predicate: (value: unknown) => boolean,
+  message: string
+): PageFormRule => ({
+  trigger: ['blur', 'change'],
+  validator: (_rule, value, callback) =>
+    predicate(value) || isEmptyPageFormValue(value)
+      ? callback()
+      : callback(new Error(message)),
+})
+
+const createPageFormValidate = (
+  messages: IPageFormMessages
+): PageFormValidateFactory => ({
+  required: () => ({ required: true, message: messages.fnRequired() }),
+  isNumber: () =>
+    validatorRule(
+      (value) => Number.isFinite(Number(value)),
+      messages.fnNumber()
+    ),
+  isPositiveNumber: () =>
+    validatorRule((value) => Number(value) > 0, messages.fnPositiveNumber()),
+  isPositiveInt: () =>
+    validatorRule(
+      (value) => Number.isInteger(Number(value)) && Number(value) > 0,
+      messages.fnPositiveInt()
+    ),
+  isEmail: () =>
+    validatorRule(
+      (value) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(String(value)),
+      messages.fnInvalidEmail()
+    ),
+  isPhone: () =>
+    validatorRule(
+      (value) => /^1[3-9]\d{9}$/.test(String(value)),
+      messages.fnInvalidPhone()
+    ),
+  notChinese: () =>
+    validatorRule(
+      (value) => !/[\u3400-\u9fff]/u.test(String(value)),
+      messages.fnNoChinese()
+    ),
+  lengthGreaterThan: (length) =>
+    validatorRule(
+      (value) => String(value).length > length,
+      messages.fnLengthGreaterThan(length)
+    ),
+  decimalsLimit: (places) =>
+    validatorRule(
+      (value) => decimalPlaces(value) <= places,
+      messages.fnDecimalsLimit(places)
+    ),
+  maxValue: (maximum) =>
+    validatorRule(
+      (value) => Number(value) <= maximum,
+      messages.fnMaxValue(maximum)
+    ),
+})
+
+const resolvePageFormRules = <TModel extends PageFormRecord>(
+  item: ResolvedIFormItem<TModel>,
+  messages: IPageFormMessages
+) => item.rules?.(createPageFormValidate(messages)) ?? []
+
+const runPageFormRule = async (
+  rule: PageFormRule,
+  value: unknown,
+  messages: IPageFormMessages
+): Promise<string | undefined> => {
+  if (rule.required && isEmptyPageFormValue(value)) {
+    return rule.message ?? messages.fnRequired()
+  }
+  const validator = rule.validator
+  if (!validator) return
+
+  return new Promise<string | undefined>((resolve) => {
+    let settled = false
+    const finish = (error?: unknown) => {
+      if (settled) return
+      settled = true
+      resolve(
+        error instanceof Error
+          ? error.message
+          : error === undefined
+            ? undefined
+            : String(error)
+      )
+    }
+
+    try {
+      const callbackMode = validator.length >= 3
+      const returned = validator(rule, value, finish)
+      if (returned && typeof returned.then === 'function') {
+        returned.then(() => {
+          if (!callbackMode) finish()
+        }, finish)
+      } else if (!callbackMode) {
+        finish()
+      }
+    } catch (error) {
+      finish(error)
+    }
+  })
+}
+
+export const validatePageForm = async <TModel extends PageFormRecord>(
+  model: TModel,
+  config: IFormProp<TModel>,
+  formType: PageFormMode,
+  signal: AbortSignal,
+  patches?: ReadonlyMap<string, Partial<Omit<IFormItem<TModel>, 'prop'>>>,
+  dependencies: Readonly<Record<string, unknown>> = {}
+): Promise<PageFormValidationResult> => {
+  const resolved = resolvePageFormConfig(
+    config,
+    { model, formType, dependencies },
+    patches
+  )
+  const issues: PageFormValidationIssue[] = []
+  for (const item of resolved.formItems) {
+    if (signal.aborted) throw signal.reason
+    if (!item.vIf) continue
+    const value = (model as Record<string, unknown>)[item.prop]
+    const builtInIssue = validatePageFormValue(value, item, resolved.messages)
+    if (builtInIssue) {
+      issues.push(builtInIssue)
+      continue
+    }
+    for (const rule of resolvePageFormRules(item, resolved.messages)) {
+      const message = await runPageFormRule(rule, value, resolved.messages)
+      if (signal.aborted) throw signal.reason
+      if (message) {
+        issues.push(issue(item, 'rules', message))
+        break
+      }
+    }
+  }
+  return { valid: issues.length === 0, issues, firstIssue: issues[0] }
+}

package/template/src/components/AppTable/AppTable.tsx

@@ -0,0 +1,26 @@
+import { useMemo } from 'react'
+import type { TableConfiguration } from './config'
+import { fnResolveAdvancedTableLicense } from './config/license'
+import type { TableRow } from './engine/shared/types'
+import { TableComponent, type ITableComponentProps } from './table'
+
+export function AppTable<T extends TableRow = TableRow>({
+  config: objConfig,
+  ...objProps
+}: ITableComponentProps<T>) {
+  const objLicensedConfig = useMemo<TableConfiguration<T>>(
+    () => ({
+      ...objConfig,
+      runtime: {
+        ...objConfig.runtime,
+        licenseKey: fnResolveAdvancedTableLicense({
+          bProduction: import.meta.env.PROD,
+          strKey: import.meta.env.VITE_HANDSONTABLE_LICENSE_KEY,
+        }),
+      },
+    }),
+    [objConfig]
+  )
+
+  return <TableComponent {...objProps} config={objLicensedConfig} />
+}

package/template/src/components/AppTable/SOURCE.md

@@ -0,0 +1,72 @@
+# Table source snapshot
+
+来源仓库、固定 revision、导入日期、同步范围和再分发状态只记录在
+[`tools/component-governance/manifest.json`](../../../tools/component-governance/manifest.json)，
+避免文档与构建门禁各自保存一份版本事实。
+
+The snapshot intentionally excludes the Vue adapter, examples, publishing
+configuration, and repository tooling. The original package split has been
+reorganized for application ownership: framework-independent behavior lives in
+`engine/`; React capabilities are grouped directly by table domain (`table/`,
+`search/`, `selection/`, `toolbar/`, and related directories); shared
+configuration and styles live in `config/` and `styles/`. Application Features
+must import the public `AppTable` boundary instead of these implementation
+directories.
+The upstream React package's copied shadcn primitives and `cn` helper are also
+excluded; the table implementation uses the application's shared `components/ui` and
+`lib/utils` implementations.
+
+The source repository did not contain a `LICENSE` or `NOTICE` file at the
+recorded commit. Treat this snapshot as internal company code until ownership
+and redistribution terms are documented. Handsontable retains its own license
+requirements and production key policy. The release gate is recorded in
+[`docs/component-source-governance.md`](../../../docs/component-source-governance.md).
+
+同步前执行：
+
+```bash
+pnpm components:diff -- \
+  --component AppTable \
+  --source-root /absolute/path/to/table-component
+```
+
+完成选择性移植和评审后才更新清单，并执行 `pnpm components:check` 与清单列出的回归
+命令。
+
+## 本轮选择性同步
+
+已合并 StrictMode 单元格会话生命周期、框架单元格增量更新、配置差量更新、首次远程查询
+高度收敛、统一固定尾列 overlay、边框与重复无障碍语义修复，以及布局动画后的最终测量。
+本地筛选/排序、CSV/XLSX 导出和大选区求和使用可取消的分片任务。
+
+继续保留全局 Locale 和单表文案覆盖、敏感列、未保存离开保护、许可证注入以及现有公共
+入口。新密度菜单提供紧凑、标准、舒适三个明确选项，并持久化选择；偏好加载完成前禁用。
+没有复制 Vue、示例、发布工具、上游 shadcn primitives 或包专用 `base.css`，应用已有全局
+Tailwind Preflight。未恢复本地裁剪的无用受管配置 builder；补回运行时真正需要的配置差量
+比较和异步求和依赖。
+
+## 高度与交互迁移
+
+- `table.height` 统一为 `'content' | 'fill' | number`，`TableHeight` 可从公共入口导入。
+  默认 `content`：内容少时收缩，内容超出父容器时内部滚动；`fill` 填满父容器可用高度。
+- 移除 `table.maxHeight` 和任意 CSS 高度字符串。把 CSS 高度/最大高度放到父容器，再选择
+  `content` 或 `fill`。原来的 `height: '100%'` 对应 `height: 'fill'`。
+- 数字高度继续支持，但不超过父容器可用空间。行高由 Handsontable 测量，仍支持通过
+  `table.settings.rowHeights` 或 `minRowHeights` 显式覆盖。
+- 侧栏等宿主布局动画可传入瞬态 `layoutTransitioning`：动画期间为 `true`，结束或取消时
+  恢复 `false`。该信号不会进入业务配置或偏好；尺寸稳定后合并刷新并重新测量换行行高。
+- 固定尾列现在只使用 Core overlay；不要再依赖原生 `fixedColumnsEnd` 设置或旧 sticky
+  DOM 标记判断是否固定。通过可见尾列、操作可用性和唯一可访问语义验证行为。
+
+```tsx
+<div className='h-[480px] min-h-0'>
+  <AppTable
+    tableKey='orders'
+    config={{ ...objConfig, table: { ...objConfig.table, height: 'content' } }}
+  />
+</div>
+```
+
+本项目现有业务表格使用数字高度，无需迁移业务配置。验证覆盖公共入口、Locale、
+StrictMode、密度持久化、首次查询、高度策略、布局收敛与取消、稳定本地排序、CSV/XLSX
+安全导出及选区任务竞态；测试路径统一记录在来源清单中。

package/template/src/components/AppTable/cell/customCell/TableCellLayer.tsx

@@ -0,0 +1,73 @@
+import { useSyncExternalStore } from 'react'
+import { createPortal } from 'react-dom'
+import { ActionDropdownCell } from './actions/ActionDropdownCell'
+import { TemporalPickerEditor } from './date/TemporalPickerEditor'
+import { SelectCellEditor } from './select/SelectCellEditor'
+import './tableCellLayer.css'
+import { TooltipCell } from './tooltip/TooltipCell'
+import type { ITableCellLayerSession } from './types'
+import { useCellLayerLifecycle } from './useCellLayerLifecycle'
+
+interface ITableCellLayerProps {
+  objLayer: ITableCellLayerSession
+}
+
+/** 一张表只渲染一个 React Portal，承载全部复杂单元格交互。 */
+export function TableCellLayer({ objLayer }: ITableCellLayerProps) {
+  const objSnapshot = useSyncExternalStore(
+    objLayer.subscribe,
+    objLayer.getSnapshot,
+    objLayer.getSnapshot
+  )
+  useCellLayerLifecycle(objLayer, objSnapshot)
+
+  if (typeof document === 'undefined') return null
+  const objEditorRect = objSnapshot.editor.rect
+
+  return createPortal(
+    <>
+      {objSnapshot.editor.visible && objEditorRect ? (
+        <div
+          data-table-cell-layer='editor'
+          className='table-cell-layer__editor hgw-table-theme hgw-table-portal'
+          style={{
+            top: objEditorRect.top,
+            left: objEditorRect.left,
+            width: objEditorRect.width,
+            height: objEditorRect.height,
+          }}
+          onMouseDown={(objEvent) => objEvent.stopPropagation()}
+          onClick={(objEvent) => objEvent.stopPropagation()}
+        >
+          {objSnapshot.editor.type === 'select' ? (
+            <SelectCellEditor
+              key={objSnapshot.editor.nSessionId}
+              objLayer={objLayer}
+              objEditor={objSnapshot.editor}
+            />
+          ) : (
+            <TemporalPickerEditor
+              key={objSnapshot.editor.nSessionId}
+              objLayer={objLayer}
+              objEditor={objSnapshot.editor}
+            />
+          )}
+        </div>
+      ) : null}
+
+      <div
+        data-table-cell-layer='menu'
+        className='hgw-table-theme hgw-table-portal'
+      >
+        <ActionDropdownCell objLayer={objLayer} />
+      </div>
+      <div
+        data-table-cell-layer='tooltip'
+        className='hgw-table-theme hgw-table-portal'
+      >
+        <TooltipCell objLayer={objLayer} />
+      </div>
+    </>,
+    document.body
+  )
+}

package/template/src/components/AppTable/cell/customCell/actions/ActionDropdownCell.tsx

@@ -0,0 +1,104 @@
+import { cn } from '@/lib/utils'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu'
+import type {
+  TableAction,
+  TableCellContext,
+} from '@/components/AppTable/engine/cell/types'
+import { runTableAction } from '@/components/AppTable/engine/shared/action'
+import type { ITableCellLayerSession } from '../types'
+
+interface IActionDropdownCellProps {
+  objLayer: ITableCellLayerSession
+}
+
+function fnResolveActionValue<TValue>(
+  objValue: TValue | ((objContext: TableCellContext) => TValue) | undefined,
+  objContext: TableCellContext
+) {
+  return typeof objValue === 'function'
+    ? (objValue as (objResolvedContext: TableCellContext) => TValue)(objContext)
+    : objValue
+}
+
+export function ActionDropdownCell({ objLayer }: IActionDropdownCellProps) {
+  const objMenu = objLayer.getSnapshot().menu
+  if (!objMenu.visible || !objMenu.anchor || !objMenu.context) return null
+  const objRect = objMenu.anchor.getBoundingClientRect()
+
+  return (
+    <DropdownMenu
+      open
+      onOpenChange={(bOpen) => {
+        if (!bOpen) objLayer.adapter.close()
+      }}
+    >
+      <DropdownMenuTrigger asChild>
+        <button
+          type='button'
+          tabIndex={-1}
+          aria-hidden='true'
+          className='pointer-events-none fixed opacity-0'
+          style={{
+            top: objRect.top,
+            left: objRect.left,
+            width: objRect.width,
+            height: objRect.height,
+          }}
+        />
+      </DropdownMenuTrigger>
+      <DropdownMenuContent
+        data-table-cell-layer='menu-content'
+        align='start'
+        side='bottom'
+        collisionPadding={8}
+        className='z-(--z-index-table-cell-menu) min-w-40'
+        onCloseAutoFocus={(objEvent) => objEvent.preventDefault()}
+      >
+        {objMenu.actions.map((objAction: TableAction) => {
+          const strLabel =
+            fnResolveActionValue(objAction.label, objMenu.context!) ?? ''
+          const strTitle = fnResolveActionValue(
+            objAction.title,
+            objMenu.context!
+          )
+          const bDisabled = Boolean(
+            fnResolveActionValue(objAction.disabled, objMenu.context!)
+          )
+          return (
+            <DropdownMenuItem
+              key={objAction.key}
+              title={strTitle}
+              disabled={bDisabled}
+              variant={objAction.type === 'danger' ? 'destructive' : 'default'}
+              className={cn(
+                objAction.type === 'success' && 'text-emerald-600',
+                objAction.type === 'warning' && 'text-amber-600',
+                objAction.type === 'info' && 'text-muted-foreground',
+                objAction.size === 'small' && 'text-xs',
+                objAction.size === 'large' && 'text-base',
+                objAction.className
+              )}
+              onSelect={() => {
+                objLayer.adapter.close()
+                runTableAction(
+                  () => objAction.onClick(objMenu.context!),
+                  (objError) => objLayer.adapter.reportActionError(objError)
+                )
+              }}
+            >
+              {objAction.icon ? (
+                <i className={objAction.icon} aria-hidden='true' />
+              ) : null}
+              <span>{strLabel}</span>
+            </DropdownMenuItem>
+          )
+        })}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}