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

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

@@ -0,0 +1,580 @@
+import {
+  hasPageFormObservers,
+  mergePageFormItemPatch,
+  resolvePageFormConfig,
+} from './config'
+import type {
+  IFormItem,
+  IFormProp,
+  PageFormControllerSnapshot,
+  PageFormMode,
+  PageFormRecord,
+  PageFormSubmitOptions,
+  PageFormSubmitOutcome,
+  PageFormSubscriptionOptions,
+  PageFormValidationResult,
+  ResolvedIFormProp,
+} from './types'
+import { validatePageForm } from './validation'
+
+const validResult = (): PageFormValidationResult => ({
+  valid: true,
+  issues: [],
+})
+
+const isPlainObject = (value: object) => {
+  const prototype = Object.getPrototypeOf(value)
+  return prototype === Object.prototype || prototype === null
+}
+
+/** 比较表单字段值；浏览器对象按稳定值或引用比较，不做 JSON 序列化。 */
+const isPageFormValueEqual = (
+  left: unknown,
+  right: unknown,
+  seen = new WeakMap<object, WeakSet<object>>()
+): boolean => {
+  if (Object.is(left, right)) return true
+  if (
+    !left ||
+    !right ||
+    typeof left !== 'object' ||
+    typeof right !== 'object'
+  ) {
+    return false
+  }
+  if (Object.getPrototypeOf(left) !== Object.getPrototypeOf(right)) return false
+  const paired = seen.get(left)
+  if (paired?.has(right)) return true
+  if (paired) paired.add(right)
+  else seen.set(left, new WeakSet([right]))
+  if (left instanceof Date && right instanceof Date) {
+    return Object.is(left.getTime(), right.getTime())
+  }
+  if (left instanceof RegExp && right instanceof RegExp) {
+    return left.source === right.source && left.flags === right.flags
+  }
+  if (left instanceof ArrayBuffer && right instanceof ArrayBuffer) {
+    if (left.byteLength !== right.byteLength) return false
+    return new Uint8Array(left).every(
+      (nValue, nIndex) => nValue === new Uint8Array(right)[nIndex]
+    )
+  }
+  if (ArrayBuffer.isView(left) && ArrayBuffer.isView(right)) {
+    if (
+      left.constructor !== right.constructor ||
+      left.byteLength !== right.byteLength
+    ) {
+      return false
+    }
+    const arrLeft = new Uint8Array(
+      left.buffer,
+      left.byteOffset,
+      left.byteLength
+    )
+    const arrRight = new Uint8Array(
+      right.buffer,
+      right.byteOffset,
+      right.byteLength
+    )
+    return arrLeft.every((nValue, nIndex) => nValue === arrRight[nIndex])
+  }
+  if (left instanceof Map && right instanceof Map) {
+    if (left.size !== right.size) return false
+    return [...left.entries()].every(([objKey, objValue], nIndex) => {
+      const objRightEntry = [...right.entries()][nIndex]
+      return Boolean(
+        objRightEntry &&
+        isPageFormValueEqual(objKey, objRightEntry[0], seen) &&
+        isPageFormValueEqual(objValue, objRightEntry[1], seen)
+      )
+    })
+  }
+  if (left instanceof Set && right instanceof Set) {
+    if (left.size !== right.size) return false
+    const arrRight = [...right]
+    return [...left].every((objValue, nIndex) =>
+      isPageFormValueEqual(objValue, arrRight[nIndex], seen)
+    )
+  }
+  if (!Array.isArray(left) && !isPlainObject(left)) return false
+  const arrLeftKeys = Reflect.ownKeys(left)
+  const arrRightKeys = Reflect.ownKeys(right)
+  if (
+    arrLeftKeys.length !== arrRightKeys.length ||
+    arrLeftKeys.some((objKey) => !arrRightKeys.includes(objKey))
+  ) {
+    return false
+  }
+  return arrLeftKeys.every((objKey) =>
+    isPageFormValueEqual(
+      Reflect.get(left, objKey),
+      Reflect.get(right, objKey),
+      seen
+    )
+  )
+}
+
+/**
+ * Clone mutable form data without destroying browser/native values.
+ * File、Blob and custom class instances are intentionally kept by reference;
+ * turning them into plain objects would lose their prototype and internal data.
+ */
+export const clonePageFormModel = <T>(source: T): T => {
+  const seen = new WeakMap<object, unknown>()
+
+  const clone = (value: unknown): unknown => {
+    if (!value || typeof value !== 'object') return value
+    if (value instanceof Date) return new Date(value)
+    if (value instanceof RegExp) return new RegExp(value.source, value.flags)
+    if (value instanceof ArrayBuffer) return value.slice(0)
+    if (ArrayBuffer.isView(value)) {
+      if (value instanceof DataView) {
+        return new DataView(
+          value.buffer.slice(
+            value.byteOffset,
+            value.byteOffset + value.byteLength
+          )
+        )
+      }
+      const TypedArray = value.constructor as {
+        new (source: ArrayLike<number>): ArrayBufferView
+      }
+      return new TypedArray(value as unknown as ArrayLike<number>)
+    }
+    if (seen.has(value)) return seen.get(value)
+
+    if (Array.isArray(value)) {
+      const result = new Array<unknown>(value.length)
+      seen.set(value, result)
+      value.forEach((item, index) => {
+        result[index] = clone(item)
+      })
+      return result
+    }
+    if (value instanceof Map) {
+      const result = new Map<unknown, unknown>()
+      seen.set(value, result)
+      value.forEach((item, key) => result.set(clone(key), clone(item)))
+      return result
+    }
+    if (value instanceof Set) {
+      const result = new Set<unknown>()
+      seen.set(value, result)
+      value.forEach((item) => result.add(clone(item)))
+      return result
+    }
+    if (!isPlainObject(value)) return value
+
+    const result = Object.create(Object.getPrototypeOf(value)) as object
+    seen.set(value, result)
+    Reflect.ownKeys(value).forEach((key) => {
+      const descriptor = Object.getOwnPropertyDescriptor(value, key)
+      if (!descriptor) return
+      Object.defineProperty(
+        result,
+        key,
+        'value' in descriptor
+          ? { ...descriptor, value: clone(descriptor.value) }
+          : descriptor
+      )
+    })
+    return result
+  }
+
+  return clone(source) as T
+}
+
+export class PageFormController<
+  TModel extends PageFormRecord = PageFormRecord,
+> {
+  private model: TModel
+  private initialModel: TModel
+  private formType: PageFormMode
+  private loading = false
+  private validation = validResult()
+  private readonly setDirtyFields = new Set<string>()
+  private revision = 0
+  private configRevision = 0
+  private hasDynamicConfig: boolean
+  private resolvedConfigCache?: {
+    revision: number
+    value: ResolvedIFormProp<TModel>
+  }
+  private validationController?: AbortController
+  private submitController?: AbortController
+  private dependencies: Readonly<Record<string, unknown>>
+  private sharedSnapshot?: PageFormControllerSnapshot<TModel>
+  private readonly listeners = new Map<
+    (snapshot: PageFormControllerSnapshot<TModel>) => void,
+    NonNullable<PageFormSubscriptionOptions['snapshot']>
+  >()
+  private readonly itemPatches = new Map<
+    string,
+    Partial<Omit<IFormItem<TModel>, 'prop'>>
+  >()
+
+  constructor(
+    private config: IFormProp<TModel>,
+    model: TModel,
+    formType: PageFormMode = 'add',
+    dependencies: Readonly<Record<string, unknown>> = {}
+  ) {
+    this.model = clonePageFormModel(model)
+    this.initialModel = clonePageFormModel(model)
+    this.formType = formType
+    this.dependencies = clonePageFormModel(dependencies)
+    this.hasDynamicConfig = hasPageFormObservers(config)
+  }
+
+  subscribe(
+    listener: (snapshot: PageFormControllerSnapshot<TModel>) => void,
+    options: PageFormSubscriptionOptions = {}
+  ) {
+    const mode = options.snapshot ?? 'isolated'
+    this.listeners.set(listener, mode)
+    listener(mode === 'shared' ? this.getSharedSnapshot() : this.getSnapshot())
+    return () => this.listeners.delete(listener)
+  }
+
+  private notify() {
+    this.sharedSnapshot = undefined
+    let isolatedSnapshot: PageFormControllerSnapshot<TModel> | undefined
+    let sharedSnapshot: PageFormControllerSnapshot<TModel> | undefined
+    this.listeners.forEach((mode, listener) => {
+      if (mode === 'shared') {
+        sharedSnapshot ??= this.getSharedSnapshot()
+        listener(sharedSnapshot)
+        return
+      }
+      isolatedSnapshot ??= this.getSnapshot()
+      listener(isolatedSnapshot)
+    })
+  }
+
+  private invalidateValidation(reason: string, reevaluateConfig = true) {
+    this.revision += 1
+    if (reevaluateConfig) this.configRevision += 1
+    this.validationController?.abort(reason)
+    this.validationController = undefined
+    this.submitController?.abort(reason)
+  }
+
+  private createSnapshot(model: TModel): PageFormControllerSnapshot<TModel> {
+    return {
+      model,
+      formType: this.formType,
+      loading: this.loading,
+      isDirty: this.setDirtyFields.size > 0,
+      dirtyFields: [...this.setDirtyFields],
+      validation: {
+        ...this.validation,
+        issues: [...this.validation.issues],
+        firstIssue: this.validation.firstIssue
+          ? { ...this.validation.firstIssue }
+          : undefined,
+      },
+      revision: this.revision,
+    }
+  }
+
+  getSnapshot(): PageFormControllerSnapshot<TModel> {
+    return this.createSnapshot(clonePageFormModel(this.model))
+  }
+
+  /**
+   * React renderers may use this stable snapshot to avoid cloning the whole
+   * model on each input. The returned model is controller-owned and read-only by contract.
+   */
+  getSharedSnapshot(): PageFormControllerSnapshot<TModel> {
+    this.sharedSnapshot ??= this.createSnapshot(this.model)
+    return this.sharedSnapshot
+  }
+
+  getResolvedConfig(): ResolvedIFormProp<TModel> {
+    if (this.resolvedConfigCache?.revision === this.configRevision) {
+      return this.resolvedConfigCache.value
+    }
+    const value = resolvePageFormConfig(
+      this.config,
+      {
+        model: this.model,
+        formType: this.formType,
+        dependencies: this.dependencies,
+      },
+      this.itemPatches
+    )
+    this.resolvedConfigCache = { revision: this.configRevision, value }
+    return value
+  }
+
+  renderForm(config: IFormProp<TModel>) {
+    this.config = { ...this.config, ...config, inited: true }
+    this.hasDynamicConfig = hasPageFormObservers(this.config, this.itemPatches)
+    this.invalidateValidation('config-updated')
+    this.notify()
+  }
+
+  /** Controlled renderers use full replacement; public renderForm stays incremental. */
+  replaceConfig(config: IFormProp<TModel>) {
+    this.config = config
+    this.hasDynamicConfig = hasPageFormObservers(this.config, this.itemPatches)
+    this.invalidateValidation('config-replaced')
+    this.notify()
+  }
+
+  setFormType(formType: PageFormMode) {
+    if (this.formType === formType) return
+    this.invalidateValidation('form-type-updated', this.hasDynamicConfig)
+    this.formType = formType
+    this.notify()
+  }
+
+  setDependencies(dependencies: Readonly<Record<string, unknown>>) {
+    this.invalidateValidation('dependencies-updated', this.hasDynamicConfig)
+    this.dependencies = clonePageFormModel(dependencies)
+    this.notify()
+  }
+
+  replaceModel(model: TModel, resetInitial = false) {
+    this.invalidateValidation('model-replaced', this.hasDynamicConfig)
+    this.model = clonePageFormModel(model)
+    if (resetInitial) {
+      this.initialModel = clonePageFormModel(model)
+      this.setDirtyFields.clear()
+    } else {
+      this.recalculateDirtyFields()
+    }
+    this.validation = validResult()
+    this.notify()
+  }
+
+  updateField(prop: string, value: unknown) {
+    this.invalidateValidation('model-updated', this.hasDynamicConfig)
+    this.model = { ...this.model, [prop]: value } as TModel
+    if (
+      isPageFormValueEqual(
+        Reflect.get(this.model, prop),
+        Reflect.get(this.initialModel, prop)
+      )
+    ) {
+      this.setDirtyFields.delete(prop)
+    } else {
+      this.setDirtyFields.add(prop)
+    }
+    if (this.validation.issues.some((item) => item.prop === prop)) {
+      const issues = this.validation.issues.filter((item) => item.prop !== prop)
+      this.validation = {
+        valid: issues.length === 0,
+        issues,
+        firstIssue: issues[0],
+      }
+    }
+    this.notify()
+  }
+
+  updateFormItem(
+    prop: string,
+    patch: Partial<Omit<IFormItem<TModel>, 'prop'>>
+  ) {
+    const current = this.itemPatches.get(prop) ?? {}
+    this.itemPatches.set(prop, mergePageFormItemPatch(current, patch))
+    this.hasDynamicConfig = hasPageFormObservers(this.config, this.itemPatches)
+    this.invalidateValidation('form-item-updated')
+    this.notify()
+  }
+
+  async validate(): Promise<PageFormValidationResult> {
+    this.validationController?.abort('superseded')
+    const controller = new AbortController()
+    const revision = this.revision
+    const cancelled = Symbol('page-form-validation-cancelled')
+    this.validationController = controller
+    let onAbort: (() => void) | undefined
+    try {
+      const result = await Promise.race([
+        validatePageForm(
+          clonePageFormModel(this.model),
+          this.config,
+          this.formType,
+          controller.signal,
+          this.itemPatches,
+          this.dependencies
+        ),
+        new Promise<typeof cancelled>((resolve) => {
+          onAbort = () => resolve(cancelled)
+          controller.signal.addEventListener('abort', onAbort, { once: true })
+        }),
+      ])
+      if (
+        result === cancelled ||
+        controller.signal.aborted ||
+        this.validationController !== controller ||
+        this.revision !== revision
+      ) {
+        return { valid: false, issues: [], cancelled: true }
+      }
+      this.validationController = undefined
+      this.validation = {
+        valid: result.valid,
+        issues: result.issues.map((item) => ({ ...item })),
+        firstIssue: result.firstIssue ? { ...result.firstIssue } : undefined,
+      }
+      this.notify()
+      return this.validation
+    } catch (error) {
+      if (controller.signal.aborted) {
+        return { valid: false, issues: [], cancelled: true }
+      }
+      if (this.validationController === controller) {
+        this.validationController = undefined
+      }
+      throw error
+    } finally {
+      if (onAbort) controller.signal.removeEventListener('abort', onAbort)
+    }
+  }
+
+  reset() {
+    this.invalidateValidation('reset', this.hasDynamicConfig)
+    this.model = clonePageFormModel(this.initialModel)
+    this.setDirtyFields.clear()
+    this.validation = validResult()
+    this.notify()
+    return clonePageFormModel(this.model)
+  }
+
+  async submit(
+    options: PageFormSubmitOptions<TModel> = {}
+  ): Promise<PageFormSubmitOutcome<TModel>> {
+    const outcome = (
+      status: PageFormSubmitOutcome<TModel>['status'],
+      details: Partial<PageFormSubmitOutcome<TModel>> = {}
+    ): PageFormSubmitOutcome<TModel> => ({
+      status,
+      model: clonePageFormModel(this.model),
+      ...details,
+    })
+    if (this.loading) return outcome('busy')
+    if (this.getResolvedConfig().disableSubmit) return outcome('disabled')
+    const controller = new AbortController()
+    this.submitController = controller
+    this.loading = true
+    this.notify()
+    let releaseInFinally = true
+    const release = () => {
+      if (this.submitController !== controller) return
+      this.submitController = undefined
+      this.loading = false
+      this.notify()
+    }
+    try {
+      if (!options.skipValidation) {
+        const validation = await this.validate()
+        if (validation.cancelled || controller.signal.aborted) {
+          return outcome('cancelled', { validation })
+        }
+        if (!validation.valid) return outcome('invalid', { validation })
+      }
+
+      const revision = this.revision
+      const model = clonePageFormModel(this.model)
+      options.onValidated?.(clonePageFormModel(model), this.formType)
+      if (controller.signal.aborted || this.revision !== revision) {
+        return outcome('cancelled')
+      }
+      const handler =
+        this.config.onConfirm ??
+        (this.formType === 'add' ? this.config.onAdd : this.config.onEdit)
+      if (!handler) return outcome('unhandled', { model })
+      const handlerModel = clonePageFormModel(model)
+      const context = {
+        model: handlerModel,
+        formType: this.formType,
+        dependencies: this.dependencies,
+        signal: controller.signal,
+      }
+      const handlerPromise = Promise.resolve().then(() =>
+        handler(handlerModel, context)
+      )
+      let handlerSettled = false
+      void handlerPromise.then(
+        () => {
+          handlerSettled = true
+        },
+        () => {
+          handlerSettled = true
+        }
+      )
+      const cancelled = Symbol('page-form-submit-cancelled')
+      let onAbort: (() => void) | undefined
+      let result: unknown | typeof cancelled
+      try {
+        result = await Promise.race([
+          handlerPromise,
+          new Promise<typeof cancelled>((resolve) => {
+            onAbort = () => resolve(cancelled)
+            controller.signal.addEventListener('abort', onAbort, {
+              once: true,
+            })
+          }),
+        ])
+      } catch (error) {
+        if (!controller.signal.aborted) throw error
+        result = cancelled
+      } finally {
+        if (onAbort) controller.signal.removeEventListener('abort', onAbort)
+      }
+      if (result === cancelled) {
+        if (!handlerSettled) {
+          releaseInFinally = false
+          void handlerPromise.then(release, release)
+        }
+        return outcome('cancelled')
+      }
+      if (controller.signal.aborted || this.revision !== revision) {
+        return outcome('cancelled')
+      }
+      this.initialModel = clonePageFormModel(model)
+      this.setDirtyFields.clear()
+      return outcome('success', { model, result })
+    } finally {
+      if (releaseInFinally) release()
+    }
+  }
+
+  destroy() {
+    this.invalidateValidation('destroyed', false)
+    this.listeners.clear()
+  }
+
+  /** 当前模型是否与最近一次外部基线或成功提交结果不同。 */
+  hasDirtyChanges() {
+    return this.setDirtyFields.size > 0
+  }
+
+  private recalculateDirtyFields() {
+    this.setDirtyFields.clear()
+    const setProps = new Set([
+      ...Reflect.ownKeys(this.initialModel),
+      ...Reflect.ownKeys(this.model),
+    ])
+    setProps.forEach((objProp) => {
+      if (
+        typeof objProp === 'string' &&
+        !isPageFormValueEqual(
+          Reflect.get(this.model, objProp),
+          Reflect.get(this.initialModel, objProp)
+        )
+      ) {
+        this.setDirtyFields.add(objProp)
+      }
+    })
+  }
+}
+
+export const createPageFormController = <TModel extends PageFormRecord>(
+  config: IFormProp<TModel>,
+  model: TModel,
+  formType: PageFormMode = 'add',
+  dependencies: Readonly<Record<string, unknown>> = {}
+) => new PageFormController(config, model, formType, dependencies)

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

@@ -0,0 +1,2 @@
+export { AppPageForm } from './AppPageForm'
+export type { IFormProp, IPageFormFileConfig } from './types'

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

@@ -0,0 +1,90 @@
+import type { TAppLocale } from '@/locale'
+import type { IPageFormMessages } from './types'
+
+const fnPrefix = (strLabel: string | undefined, strMessage: string) =>
+  strLabel ? `${strLabel}${strMessage}` : strMessage
+
+/** PageForm 内建中英文文案；业务显式配置会覆盖对应字段。 */
+const objPageFormMessages: Readonly<Record<TAppLocale, IPageFormMessages>> =
+  Object.freeze({
+    'en-US': Object.freeze({
+      strConfirm: 'Confirm',
+      strReset: 'Reset',
+      strCreateSuccess: 'Created successfully',
+      strSaveSuccess: 'Saved successfully',
+      strSubmitFailed: 'Submission failed. Please try again later.',
+      strResetSuccess: 'Initial values restored',
+      strSubmitting: 'Submitting…',
+      strSelectPlaceholder: 'Please select',
+      strSearchPlaceholder: 'Enter keywords to search',
+      strLoading: 'Loading…',
+      strFieldFallback: 'This field',
+      fnSearchAriaLabel: (strLabel) => `Search ${strLabel}`,
+      fnRequired: (strLabel) =>
+        strLabel ? `${strLabel} is required` : 'This field is required',
+      fnNumber: (strLabel) =>
+        strLabel ? `${strLabel} must be a number` : 'Must be a number',
+      fnPositiveNumber: (strLabel) =>
+        strLabel ? `${strLabel} must be positive` : 'Must be positive',
+      fnPositiveInt: (strLabel) =>
+        strLabel
+          ? `${strLabel} must be a positive integer`
+          : 'Must be a positive integer',
+      fnInvalidFormat: (strLabel) =>
+        strLabel ? `${strLabel} has an invalid format` : 'Invalid format',
+      fnInvalidEmail: () => 'Invalid email address',
+      fnInvalidPhone: () => 'Invalid phone number',
+      fnNoChinese: (strLabel) =>
+        strLabel
+          ? `${strLabel} cannot contain Chinese characters`
+          : 'Cannot contain Chinese characters',
+      fnLengthGreaterThan: (nLength, strLabel) =>
+        strLabel
+          ? `${strLabel} must be longer than ${nLength} characters`
+          : `Must be longer than ${nLength} characters`,
+      fnDecimalsLimit: (nPlaces, strLabel) =>
+        strLabel
+          ? `${strLabel} can have at most ${nPlaces} decimal places`
+          : `Can have at most ${nPlaces} decimal places`,
+      fnMaxValue: (nMaximum, strLabel) =>
+        strLabel
+          ? `${strLabel} cannot exceed ${nMaximum}`
+          : `Cannot exceed ${nMaximum}`,
+    } satisfies IPageFormMessages),
+    'zh-CN': Object.freeze({
+      strConfirm: '确定',
+      strReset: '重置',
+      strCreateSuccess: '创建成功',
+      strSaveSuccess: '保存成功',
+      strSubmitFailed: '提交失败，请稍后重试',
+      strResetSuccess: '已恢复初始数据',
+      strSubmitting: '提交中…',
+      strSelectPlaceholder: '请选择',
+      strSearchPlaceholder: '输入关键字搜索',
+      strLoading: '加载中…',
+      strFieldFallback: '该字段',
+      fnSearchAriaLabel: (strLabel) => `${strLabel}搜索`,
+      fnRequired: (strLabel) => fnPrefix(strLabel, '不能为空'),
+      fnNumber: (strLabel) => fnPrefix(strLabel, '必须为数字'),
+      fnPositiveNumber: (strLabel) => fnPrefix(strLabel, '必须为正数'),
+      fnPositiveInt: (strLabel) => fnPrefix(strLabel, '必须为正整数'),
+      fnInvalidFormat: (strLabel) => fnPrefix(strLabel, '格式不正确'),
+      fnInvalidEmail: () => '邮箱格式不正确',
+      fnInvalidPhone: () => '手机号格式不正确',
+      fnNoChinese: (strLabel) => fnPrefix(strLabel, '不能包含中文'),
+      fnLengthGreaterThan: (nLength, strLabel) =>
+        fnPrefix(strLabel, `长度必须大于${nLength}`),
+      fnDecimalsLimit: (nPlaces, strLabel) =>
+        fnPrefix(strLabel, `最多保留${nPlaces}位小数`),
+      fnMaxValue: (nMaximum, strLabel) =>
+        fnPrefix(strLabel, `不能大于${nMaximum}`),
+    } satisfies IPageFormMessages),
+  })
+
+/** 按 Locale 合并局部覆盖，返回可直接由控制器消费的完整文案。 */
+export function resolvePageFormMessages(
+  strLocale: TAppLocale,
+  objOverrides?: Partial<IPageFormMessages>
+): IPageFormMessages {
+  return { ...objPageFormMessages[strLocale], ...objOverrides }
+}