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

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

@@ -0,0 +1,632 @@
+import type { ComponentType, ReactNode } from 'react'
+import type { IFileValidationOptions, TFileUploadRequest } from '@/files'
+import type { PageFormController } from './controller'
+
+/** 业务 DTO 只需是对象，不要求声明无意义的字符串索引签名。 */
+export type PageFormRecord = object
+export type PageFormMode = 'add' | 'edit'
+export type PageFormSize = 'medium' | 'small' | 'mini'
+export type PageFormInputType = 'text' | 'number' | 'password' | 'textarea'
+export type PageFormFieldType =
+  | 'input'
+  | 'select'
+  | 'date'
+  | 'datetime'
+  | 'file'
+  | 'component'
+  | 'radio'
+  | 'remoteSelect'
+export type PageFormQueryWay = 'eq' | 'like' | 'notEqual' | 'start' | 'end'
+
+export interface PageFormContext<
+  TModel extends PageFormRecord = PageFormRecord,
+> {
+  model: TModel
+  formType: PageFormMode
+  /** 由调用方注入的外部依赖，供 watch/Observer/远程缓存键共同消费。 */
+  dependencies?: Readonly<Record<string, unknown>>
+  /** 仅提交 handler 和远程请求提供；Observer 求值时通常为空。 */
+  signal?: AbortSignal
+}
+
+export type PageFormFeedbackOption<TContext> =
+  | boolean
+  | string
+  | ((context: TContext) => string | false | null | undefined)
+
+export interface PageFormSuccessFeedbackContext<
+  TModel extends PageFormRecord = PageFormRecord,
+> extends PageFormContext<TModel> {
+  result: unknown
+}
+
+export interface PageFormErrorFeedbackContext<
+  TModel extends PageFormRecord = PageFormRecord,
+> extends PageFormContext<TModel> {
+  error: unknown
+  prop?: string
+}
+
+export interface PageFormFeedbackConfig<
+  TModel extends PageFormRecord = PageFormRecord,
+> {
+  success?: PageFormFeedbackOption<PageFormSuccessFeedbackContext<TModel>>
+  error?: PageFormFeedbackOption<PageFormErrorFeedbackContext<TModel>>
+  remoteError?: PageFormFeedbackOption<PageFormErrorFeedbackContext<TModel>>
+  reset?: PageFormFeedbackOption<PageFormContext<TModel>>
+}
+
+/** PageForm 所有内建可见文案和校验句式。 */
+export interface IPageFormMessages {
+  /** 默认确认按钮文案。 */
+  strConfirm: string
+  /** 默认重置按钮文案。 */
+  strReset: string
+  /** 新增提交成功提示。 */
+  strCreateSuccess: string
+  /** 编辑提交成功提示。 */
+  strSaveSuccess: string
+  /** 非 Error 异常的提交失败兜底提示。 */
+  strSubmitFailed: string
+  /** 恢复初始表单后的提示。 */
+  strResetSuccess: string
+  /** 提交进行中的按钮文案。 */
+  strSubmitting: string
+  /** 单选控件未选择时的占位文案。 */
+  strSelectPlaceholder: string
+  /** 远程选择器的搜索占位文案。 */
+  strSearchPlaceholder: string
+  /** 远程选项加载状态文案。 */
+  strLoading: string
+  /** 字段缺少 label 时用于校验消息的名称。 */
+  strFieldFallback: string
+  /** 生成远程选择搜索框的无障碍名称。 */
+  fnSearchAriaLabel: (strLabel: string) => string
+  /** 生成必填校验消息。 */
+  fnRequired: (strLabel?: string) => string
+  /** 生成数字校验消息。 */
+  fnNumber: (strLabel?: string) => string
+  /** 生成正数校验消息。 */
+  fnPositiveNumber: (strLabel?: string) => string
+  /** 生成正整数校验消息。 */
+  fnPositiveInt: (strLabel?: string) => string
+  /** 生成字段格式校验消息。 */
+  fnInvalidFormat: (strLabel?: string) => string
+  /** 生成邮箱格式校验消息。 */
+  fnInvalidEmail: () => string
+  /** 生成手机号格式校验消息。 */
+  fnInvalidPhone: () => string
+  /** 生成禁止中文字符的校验消息。 */
+  fnNoChinese: (strLabel?: string) => string
+  /** 生成最小字符长度校验消息。 */
+  fnLengthGreaterThan: (nLength: number, strLabel?: string) => string
+  /** 生成小数位数上限校验消息。 */
+  fnDecimalsLimit: (nPlaces: number, strLabel?: string) => string
+  /** 生成数值上限校验消息。 */
+  fnMaxValue: (nMaximum: number, strLabel?: string) => string
+}
+
+/** listen 由表单控制器求值，并显式接收当前表单上下文。 */
+export type Observer<T, TModel extends PageFormRecord = PageFormRecord> =
+  | T
+  | { listen: (context: PageFormContext<TModel>) => T }
+
+export interface IOption<TValue = unknown> {
+  label: string
+  value: TValue
+  disabled?: boolean
+  [key: string]: unknown
+}
+
+export interface PageFormQueryCondition {
+  way: PageFormQueryWay
+  key: string
+  value: unknown
+}
+
+export interface PageFormQuery {
+  limit: number
+  conditions: PageFormQueryCondition[]
+  eq: (key: string, value: unknown) => PageFormQuery
+  like: (key: string, value: unknown) => PageFormQuery
+  notEqual: (key: string, value: unknown) => PageFormQuery
+  start: (key: string, value: unknown) => PageFormQuery
+  end: (key: string, value: unknown) => PageFormQuery
+  toJson: () => Record<string, unknown>
+}
+
+export interface PageFormDateShortcut {
+  text: string
+  value: Date | (() => Date)
+}
+
+export interface PageFormPickerOptions {
+  disabledDate?: (date: Date) => boolean
+  shortcuts?: readonly PageFormDateShortcut[]
+  [key: string]: unknown
+}
+
+export interface IComponentConfig {
+  [key: string]: unknown
+}
+
+export type PageFormRuleCallback = (error?: Error) => void
+
+export interface PageFormRule {
+  required?: boolean
+  trigger?: string | string[]
+  message?: string
+  validator?: (
+    rule: PageFormRule,
+    value: unknown,
+    callback: PageFormRuleCallback
+  ) => void | Promise<void>
+}
+
+export interface PageFormValidateFactory {
+  required: () => PageFormRule
+  isNumber: () => PageFormRule
+  isPositiveNumber: () => PageFormRule
+  isPositiveInt: () => PageFormRule
+  isEmail: () => PageFormRule
+  isPhone: () => PageFormRule
+  notChinese: () => PageFormRule
+  lengthGreaterThan: (length: number) => PageFormRule
+  decimalsLimit: (places: number) => PageFormRule
+  maxValue: (maximum: number) => PageFormRule
+}
+
+export interface PageFormRemoteRequest<
+  TModel extends PageFormRecord = PageFormRecord,
+> extends PageFormContext<TModel> {
+  field: ResolvedIFormItem<TModel>
+  api: string
+  query: PageFormQuery
+  keyword?: string
+  value?: unknown
+  values?: readonly unknown[]
+  signal: AbortSignal
+}
+
+export type PageFormRemoteOptionLoader<
+  TModel extends PageFormRecord = PageFormRecord,
+> = (
+  request: PageFormRemoteRequest<TModel>
+) => Promise<readonly Record<string, unknown>[]>
+
+interface ICommonSelectConfig {
+  onChange?: (
+    selection: Record<string, unknown> | readonly Record<string, unknown>[]
+  ) => void
+  clearable?: boolean
+  filterable?: boolean
+  size?: PageFormSize
+  multiple?: boolean
+  placeholder?: string
+}
+
+export interface IRemoteSelectConfig<
+  TModel extends PageFormRecord = PageFormRecord,
+> extends ICommonSelectConfig {
+  api: string
+  beforeQuery?: (param: PageFormQuery) => void | boolean
+  afterQuery?: (
+    options: readonly Record<string, unknown>[],
+    request: PageFormRemoteRequest<TModel>
+  ) =>
+    | void
+    | readonly Record<string, unknown>[]
+    | Promise<void | readonly Record<string, unknown>[]>
+  labelKey: string
+  valueKey: string
+  searchKey?: string
+  limit?: number
+  dynamicQuery?: boolean
+  mandatoryQuery?: boolean
+  queryWay?: PageFormQueryWay
+  /** 远程数据实际依赖的 model/dependencies 路径；未声明时不会因普通输入失效。 */
+  dependencies?: readonly string[]
+  /** 复杂依赖可直接生成稳定的缓存键，优先级高于 dependencies。 */
+  contextKey?: (context: PageFormContext<TModel>) => unknown
+}
+
+/** PageForm 内建文件字段的上传配置。 */
+export interface IPageFormFileConfig<
+  TModel extends PageFormRecord = PageFormRecord,
+  TFileValue = unknown,
+> {
+  /**
+   * 上传适配器，必须返回最终写入当前表单字段的值。
+   *
+   * Feature 应在这里调用 Swagger 生成客户端，并把响应映射为文件 ID、对象 Key
+   * 或稳定 DTO；PageForm 不假设后端上传响应结构。
+   */
+  fnUpload: TFileUploadRequest<TFileValue>
+  /** 上传或浏览器体验校验失败后的字段级回调。 */
+  fnOnError?: (objError: Error, objContext: PageFormContext<TModel>) => void
+  /** 浏览器体验校验规则；不能替代后端鉴权、扫描和真实内容校验。 */
+  objValidation?: IFileValidationOptions
+  /** FileUpload 外层容器附加类名。 */
+  strClassName?: string
+  /** 文件选择按钮文案；省略时跟随全局 Locale。 */
+  strSelectText?: string
+}
+
+export interface IFormItem<TModel extends PageFormRecord = PageFormRecord> {
+  label: Observer<string, TModel>
+  prop: string
+  inputType?: Observer<PageFormInputType, TModel>
+  inputWidth?: string
+  onblur?: (value: unknown) => void
+  rows?: number
+  type?: Observer<PageFormFieldType, TModel>
+  /** 自定义控件注册键；由 React 字段渲染器完成映射。 */
+  renderer?: string
+  /** 直接传入 React 组件；可复用配置应优先使用 renderer 注册键。 */
+  component?: unknown
+  placeholder?: Observer<string, TModel>
+  filterable?: Observer<boolean, TModel>
+  multiple?: Observer<boolean, TModel>
+  options?: Observer<readonly IOption[], TModel>
+  optionsQuery?: Promise<readonly IOption[]>
+  onChange?: (value: unknown) => void
+  lengthGreaterThan?: Observer<number, TModel>
+  clearable?: Observer<boolean, TModel>
+  maxLength?: Observer<number, TModel>
+  size?: Observer<PageFormSize, TModel>
+  readonly?: Observer<boolean, TModel>
+  disabled?: Observer<boolean, TModel>
+  required?: Observer<boolean, TModel>
+  isEmail?: Observer<boolean, TModel>
+  isPhone?: Observer<boolean, TModel>
+  isNumber?: Observer<boolean, TModel>
+  isPositiveNumber?: Observer<boolean, TModel>
+  isPositiveInt?: Observer<boolean, TModel>
+  decimalsLimit?: Observer<number, TModel>
+  notChinese?: Observer<boolean, TModel>
+  vIf?: Observer<boolean, TModel>
+  vShow?: Observer<boolean, TModel>
+  block?: Observer<boolean, TModel>
+  dateConfig?: {
+    format?: string
+    value_format?: string
+    pickerOptions?: PageFormPickerOptions
+  }
+  rules?: (validate: PageFormValidateFactory) => readonly PageFormRule[]
+  componentConfig?: Observer<IComponentConfig, TModel>
+  remoteSelectConfig?: Observer<IRemoteSelectConfig<TModel>, TModel>
+  /** `type: 'file'` 使用的上传适配器与体验校验配置。 */
+  fileConfig?: Observer<IPageFormFileConfig<TModel>, TModel>
+}
+
+export interface IFormProp<TModel extends PageFormRecord = PageFormRecord> {
+  inited?: boolean
+  itemWidth?: 150 | 200 | 250 | 300 | 350 | 400
+  maxHeight?: string | number
+  labelWidth?: string | number
+  height?: string | number
+  width?: string | number
+  maxWidth?: string | number
+  overflow?: string
+  submitLoading?: boolean
+  /** 校验失败时由表单视图滚动到第一个错误字段，默认开启。 */
+  scrollToFirstError?: boolean
+  /** 表单视图的内置反馈策略；事件始终照常触发。 */
+  feedback?: PageFormFeedbackConfig<TModel>
+  /** 覆盖 PageForm 内建文案；未提供字段跟随全局 Locale。 */
+  messages?: Partial<IPageFormMessages>
+  /** 声明需要注入 PageFormContext.dependencies 的外部依赖。 */
+  watch?: readonly ({ name: string; deep?: boolean } | string)[]
+  inline?: boolean
+  formItems?: readonly IFormItem<TModel>[]
+  onAdd?: (
+    model: TModel,
+    context: PageFormContext<TModel>
+  ) => unknown | Promise<unknown>
+  onEdit?: (
+    model: TModel,
+    context: PageFormContext<TModel>
+  ) => unknown | Promise<unknown>
+  onConfirm?: (
+    model: TModel,
+    context: PageFormContext<TModel>
+  ) => unknown | Promise<unknown>
+  confirmButtonText?: Observer<string, TModel>
+  resetButtonText?: Observer<string, TModel>
+  preventAll?: Observer<boolean, TModel>
+  resetBtn?: Observer<boolean, TModel>
+  disableSubmit?: Observer<boolean, TModel>
+  enterToSubmit?: Observer<boolean, TModel>
+}
+
+type ResolvedObserverKeys =
+  | 'label'
+  | 'inputType'
+  | 'type'
+  | 'placeholder'
+  | 'filterable'
+  | 'multiple'
+  | 'options'
+  | 'lengthGreaterThan'
+  | 'clearable'
+  | 'maxLength'
+  | 'size'
+  | 'readonly'
+  | 'disabled'
+  | 'required'
+  | 'isEmail'
+  | 'isPhone'
+  | 'isNumber'
+  | 'isPositiveNumber'
+  | 'isPositiveInt'
+  | 'decimalsLimit'
+  | 'notChinese'
+  | 'vIf'
+  | 'vShow'
+  | 'block'
+  | 'componentConfig'
+  | 'remoteSelectConfig'
+  | 'fileConfig'
+
+export interface ResolvedIFormItem<
+  TModel extends PageFormRecord = PageFormRecord,
+> extends Omit<IFormItem<TModel>, ResolvedObserverKeys> {
+  label: string
+  inputType: PageFormInputType
+  type: PageFormFieldType
+  placeholder: string
+  filterable: boolean
+  multiple: boolean
+  options: readonly IOption[]
+  lengthGreaterThan?: number
+  clearable: boolean
+  maxLength?: number
+  size: PageFormSize
+  readonly: boolean
+  disabled: boolean
+  required: boolean
+  isEmail: boolean
+  isPhone: boolean
+  isNumber: boolean
+  isPositiveNumber: boolean
+  isPositiveInt: boolean
+  decimalsLimit?: number
+  notChinese: boolean
+  vIf: boolean
+  vShow: boolean
+  block: boolean
+  componentConfig: IComponentConfig
+  remoteSelectConfig?: IRemoteSelectConfig<TModel>
+  /** 已按当前表单上下文解析的文件上传配置。 */
+  fileConfig?: IPageFormFileConfig<TModel>
+}
+
+type ResolvedFormPropKeys =
+  | 'formItems'
+  | 'messages'
+  | 'confirmButtonText'
+  | 'resetButtonText'
+  | 'preventAll'
+  | 'resetBtn'
+  | 'disableSubmit'
+  | 'enterToSubmit'
+
+export interface ResolvedIFormProp<
+  TModel extends PageFormRecord = PageFormRecord,
+> extends Omit<IFormProp<TModel>, ResolvedFormPropKeys> {
+  inited: boolean
+  formItems: readonly ResolvedIFormItem<TModel>[]
+  itemWidth: 150 | 200 | 250 | 300 | 350 | 400
+  labelWidth: string | number
+  height: string | number
+  width: string | number
+  maxWidth: string | number
+  inline: boolean
+  /** 已按当前 Locale 和局部覆盖合并的完整文案。 */
+  messages: IPageFormMessages
+  confirmButtonText: string
+  resetButtonText: string
+  preventAll: boolean
+  resetBtn: boolean
+  disableSubmit: boolean
+  enterToSubmit: boolean
+}
+
+export interface PageFormValidationIssue {
+  prop: string
+  code: string
+  message: string
+}
+
+export interface PageFormValidationResult {
+  valid: boolean
+  issues: readonly PageFormValidationIssue[]
+  firstIssue?: PageFormValidationIssue
+  /** 当前校验已被更新后的状态取代，不应当被当作校验失败或系统异常。 */
+  cancelled?: boolean
+}
+
+export type PageFormSubmitStatus =
+  | 'success'
+  | 'invalid'
+  | 'cancelled'
+  | 'disabled'
+  | 'busy'
+  | 'unhandled'
+
+export interface PageFormSubmitOutcome<TModel extends PageFormRecord> {
+  status: PageFormSubmitStatus
+  model: TModel
+  result?: unknown
+  validation?: PageFormValidationResult
+}
+
+export interface PageFormSubmitOptions<TModel extends PageFormRecord> {
+  skipValidation?: boolean
+  onValidated?: (model: TModel, formType: PageFormMode) => void
+}
+
+export interface PageFormControllerSnapshot<
+  TModel extends PageFormRecord = PageFormRecord,
+> {
+  model: TModel
+  formType: PageFormMode
+  loading: boolean
+  /** 当前模型是否偏离最近一次外部基线或成功提交结果。 */
+  isDirty: boolean
+  /** 与当前基线不同的顶层字段名。 */
+  dirtyFields: readonly string[]
+  validation: PageFormValidationResult
+  /** 每次影响求值结果的状态变化都会递增，可用作派生数据缓存键。 */
+  revision: number
+}
+
+export interface PageFormSubscriptionOptions {
+  /**
+   * isolated 为默认安全边界；shared 供渲染层读取稳定快照，调用方不得修改 model。
+   */
+  snapshot?: 'isolated' | 'shared'
+}
+
+export interface PageFormOptionsSnapshot {
+  fieldOptions: Readonly<Record<string, readonly IOption[]>>
+  remoteOptions: Readonly<Record<string, readonly Record<string, unknown>[]>>
+  loading: Readonly<Record<string, boolean>>
+}
+
+/** 自定义字段渲染器收到的完整渲染上下文。 */
+export interface PageFormFieldRendererProps<
+  TModel extends PageFormRecord = PageFormRecord,
+> {
+  /** 已解析默认值与观察器的字段配置。 */
+  item: ResolvedIFormItem<TModel>
+  /** 当前表单模型快照。 */
+  model: TModel
+  /** 当前字段值。 */
+  value: unknown
+  /** 当前字段是否禁止交互。 */
+  disabled: boolean
+  /** 当前字段的远程选项是否加载中。 */
+  loading: boolean
+  /** 当前字段的静态选项。 */
+  options: readonly IOption[]
+  /** 当前字段已加载的远程选项。 */
+  remoteOptions: readonly Readonly<Record<string, unknown>>[]
+  /** 当前字段的第一条校验问题。 */
+  issue?: PageFormValidationIssue
+  /** 更新字段值并触发表单模型通知。 */
+  update: (value: unknown) => void
+  /** 通知字段失焦并执行对应校验。 */
+  blur: () => void
+  /** 按关键字请求远程选项。 */
+  remoteQuery: (keyword: string) => void
+  /** 在远程选择器打开时确保初始选项可用。 */
+  remoteOpen: () => void
+}
+
+/** 单个字段的 React 渲染函数。 */
+export type PageFormFieldRenderer<
+  TModel extends PageFormRecord = PageFormRecord,
+> = (props: PageFormFieldRendererProps<TModel>) => ReactNode
+
+/** 自定义操作区收到的表单命令和状态。 */
+export interface PageFormRenderContext<
+  TModel extends PageFormRecord = PageFormRecord,
+> {
+  /** 当前表单模型快照。 */
+  model: TModel
+  /** 表单是否正在提交。 */
+  loading: boolean
+  /** 当前模型是否存在未保存修改。 */
+  isDirty: boolean
+  /** 执行校验与提交。 */
+  submit: () => Promise<PageFormSubmitOutcome<TModel> | undefined>
+  /** 恢复初始模型并返回重置后的值。 */
+  reset: () => TModel
+}
+
+/** 表单操作区位置；none 表示完全由调用方渲染操作。 */
+export type PageFormActionsPlacement = 'top' | 'bottom' | 'none'
+
+/** 通过 ref 暴露给组合组件的命令式表单能力。 */
+export interface PageFormHandle<
+  TModel extends PageFormRecord = PageFormRecord,
+> {
+  /** 校验当前模型但不提交。 */
+  validate: () => Promise<PageFormValidationResult>
+  /** 校验并提交当前模型。 */
+  submit: () => Promise<PageFormSubmitOutcome<TModel> | undefined>
+  /** 恢复初始模型。 */
+  reset: () => TModel
+  /** 更新单个字段的运行时配置。 */
+  updateFormItem: PageFormController<TModel>['updateFormItem']
+  /** 获取当前表单控制器，用于高级集成。 */
+  getController: () => PageFormController<TModel>
+  /** 当前模型是否存在未保存修改。 */
+  isDirty: () => boolean
+}
+
+/** PageForm 的 React 组件属性。 */
+export interface PageFormProps<TModel extends PageFormRecord = PageFormRecord> {
+  /** 受控表单模型。 */
+  model: TModel
+  /** 字段、校验和提交策略配置。 */
+  config: IFormProp<TModel>
+  /** 当前新增、编辑或查看模式。 */
+  formType?: PageFormMode
+  /** 外部提交流程是否仍在执行。 */
+  submitLoading?: boolean
+  /** 是否接入应用级路由和浏览器离开保护，默认开启。 */
+  bProtectUnsavedChanges?: boolean
+  /** 供字段观察器读取的额外依赖。 */
+  dependencies?: Readonly<Record<string, unknown>>
+  /** 远程选择字段的统一加载器。 */
+  remoteOptionLoader?: PageFormRemoteOptionLoader<TModel>
+  /** 按组件名称注册的自定义字段组件。 */
+  renderers?: Readonly<
+    Record<string, ComponentType<PageFormFieldRendererProps<TModel>>>
+  >
+  /** 按字段类型替换默认控件渲染器。 */
+  controlRenderers?: Partial<
+    Record<PageFormFieldType, PageFormFieldRenderer<TModel>>
+  >
+  /** 表单根节点附加类名。 */
+  className?: string
+  /** 默认操作区的渲染位置。 */
+  actionsPlacement?: PageFormActionsPlacement
+  /** 受控模型变化回调。 */
+  onModelChange?: (model: TModel) => void
+  /** 单个字段变化回调。 */
+  onChange?: (prop: string, value: unknown, model: TModel) => void
+  /** dirty 状态变化时通知业务组合层。 */
+  onDirtyChange?: (
+    bIsDirty: boolean,
+    snapshot: PageFormControllerSnapshot<TModel>
+  ) => void
+  /** 提交开始且校验通过后的通知。 */
+  onSubmit?: (model: TModel, formType: PageFormMode) => void
+  /** 提交处理器成功后的通知。 */
+  onSuccess?: (result: unknown, model: TModel) => void
+  /** 校验失败后的通知。 */
+  onValidationFailed?: (snapshot: PageFormControllerSnapshot<TModel>) => void
+  /** 模型重置后的通知。 */
+  onReset?: (model: TModel) => void
+  /** 提交或选项加载之外的运行时错误回调。 */
+  onError?: (error: unknown) => void
+  /** 远程字段加载错误回调。 */
+  onRemoteError?: (error: unknown, prop: string) => void
+  /** 完全自定义表单操作区。 */
+  renderActions?: (context: PageFormRenderContext<TModel>) => ReactNode
+  /** 渲染表单右侧扩展区域。 */
+  renderRight?: (model: TModel) => ReactNode
+  /** 渲染表单底部扩展区域。 */
+  renderFooter?: (model: TModel) => ReactNode
+  /** 按字段覆盖默认渲染；返回 undefined 时继续使用默认控件。 */
+  renderField?: (
+    props: PageFormFieldRendererProps<TModel>
+  ) => ReactNode | undefined
+}
+
+/** 项目级 AppPageForm 属性，保留完整 PageForm 类型推导。 */
+export type TAppPageFormProps<TModel extends PageFormRecord = PageFormRecord> =
+  PageFormProps<TModel>