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

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

@@ -0,0 +1,91 @@
+import type {
+  IOption,
+  PageFormContext,
+  PageFormOptionsSnapshot,
+  PageFormRecord,
+  ResolvedIFormItem,
+} from './types'
+
+const getPathValue = (source: unknown, path: string): unknown =>
+  path.split('.').reduce<unknown>((current, key) => {
+    if (!current || typeof current !== 'object') return undefined
+    return (current as Record<string, unknown>)[key]
+  }, source)
+
+export const createContextCacheKey = <TModel extends PageFormRecord>(
+  item: ResolvedIFormItem<TModel>,
+  context: PageFormContext<TModel>
+) => {
+  const remote = item.remoteSelectConfig
+  if (!remote) return undefined
+  if (remote.contextKey) return remote.contextKey(context)
+  return (remote.dependencies ?? []).map((path) =>
+    path.startsWith('dependencies.')
+      ? getPathValue(context.dependencies, path.slice('dependencies.'.length))
+      : getPathValue(context.model, path)
+  )
+}
+
+export const isSameCacheKey = (left: unknown, right: unknown): boolean =>
+  Object.is(left, right) ||
+  (Array.isArray(left) &&
+    Array.isArray(right) &&
+    left.length === right.length &&
+    left.every((value, index) => isSameCacheKey(value, right[index])))
+
+export const isSameRemoteConfig = <TModel extends PageFormRecord>(
+  left: ResolvedIFormItem<TModel>['remoteSelectConfig'],
+  right: ResolvedIFormItem<TModel>['remoteSelectConfig']
+) => {
+  if (left === right) return true
+  if (!left || !right) return false
+  const keys = [
+    'api',
+    'labelKey',
+    'valueKey',
+    'searchKey',
+    'limit',
+    'dynamicQuery',
+    'mandatoryQuery',
+    'queryWay',
+  ] as const
+  return (
+    keys.every((key) => Object.is(left[key], right[key])) &&
+    isSameCacheKey(left.dependencies, right.dependencies)
+  )
+}
+
+export const awaitAbortable = <T>(
+  promise: PromiseLike<T>,
+  signal: AbortSignal
+) => {
+  if (signal.aborted) return Promise.reject(signal.reason)
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => reject(signal.reason)
+    signal.addEventListener('abort', onAbort, { once: true })
+    promise.then(
+      (value) => {
+        signal.removeEventListener('abort', onAbort)
+        resolve(value)
+      },
+      (error: unknown) => {
+        signal.removeEventListener('abort', onAbort)
+        reject(signal.aborted ? signal.reason : error)
+      }
+    )
+  })
+}
+
+export const freezeRemoteOptions = (
+  options: readonly Record<string, unknown>[]
+): readonly Readonly<Record<string, unknown>>[] =>
+  Object.freeze(options.map((option) => Object.freeze({ ...option })))
+
+export const freezeFieldOptions = (options: readonly IOption[]) =>
+  Object.freeze(options.map((option) => Object.freeze({ ...option })))
+
+export const createOptionsSnapshot = (): PageFormOptionsSnapshot => ({
+  fieldOptions: {},
+  remoteOptions: {},
+  loading: {},
+})

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

@@ -0,0 +1,397 @@
+import {
+  awaitAbortable,
+  createContextCacheKey,
+  createOptionsSnapshot,
+  freezeFieldOptions,
+  freezeRemoteOptions,
+  isSameCacheKey,
+  isSameRemoteConfig,
+} from './optionUtils'
+import { createPageFormQuery } from './query'
+import type {
+  IOption,
+  PageFormContext,
+  PageFormOptionsSnapshot,
+  PageFormRecord,
+  PageFormRemoteOptionLoader,
+  ResolvedIFormItem,
+} from './types'
+
+type RemoteQuery = {
+  keyword?: string
+  value?: unknown
+  values?: readonly unknown[]
+}
+
+/**
+ * 框架无关的 optionsQuery、远程查询、取消、初始缓存和已选值补查状态机。
+ * React 渲染层只负责把稳定快照映射到控件。
+ */
+class PageFormOptionsController<
+  TModel extends PageFormRecord = PageFormRecord,
+> {
+  private snapshot = createOptionsSnapshot()
+  private readonly originRemoteOptions: Record<
+    string,
+    readonly Record<string, unknown>[]
+  > = {}
+  private readonly controllers = new Map<string, AbortController>()
+  private readonly remoteEnsures = new Map<
+    string,
+    { key: unknown; promise: Promise<void> }
+  >()
+  private readonly remoteContexts = new Map<
+    string,
+    {
+      key: unknown
+      config: ResolvedIFormItem<TModel>['remoteSelectConfig']
+      loader: PageFormRemoteOptionLoader<TModel> | undefined
+    }
+  >()
+  private readonly listeners = new Set<
+    (snapshot: PageFormOptionsSnapshot) => void
+  >()
+
+  constructor(
+    private remoteOptionLoader?: PageFormRemoteOptionLoader<TModel>
+  ) {}
+
+  subscribe(listener: (snapshot: PageFormOptionsSnapshot) => void) {
+    this.listeners.add(listener)
+    listener(this.snapshot)
+    return () => this.listeners.delete(listener)
+  }
+
+  getSnapshot() {
+    return this.snapshot
+  }
+
+  setRemoteOptionLoader(loader?: PageFormRemoteOptionLoader<TModel>) {
+    if (this.remoteOptionLoader === loader) return
+    this.remoteOptionLoader = loader
+    this.invalidateRemote()
+  }
+
+  private invalidateRemote(prop?: string) {
+    if (prop === undefined) this.remoteEnsures.clear()
+    else this.remoteEnsures.delete(prop)
+    const matches = (key: string) =>
+      prop === undefined || key === `remote:${prop}`
+    this.controllers.forEach((controller, key) => {
+      if (!matches(key)) return
+      controller.abort('invalidated')
+      this.controllers.delete(key)
+    })
+
+    const remoteOptions = { ...this.snapshot.remoteOptions }
+    const loading = { ...this.snapshot.loading }
+    const props =
+      prop === undefined
+        ? new Set([
+            ...Object.keys(this.originRemoteOptions),
+            ...Object.keys(remoteOptions),
+            ...this.remoteContexts.keys(),
+          ])
+        : new Set([prop])
+    props.forEach((key) => {
+      delete this.originRemoteOptions[key]
+      delete remoteOptions[key]
+      delete loading[key]
+      this.remoteContexts.delete(key)
+    })
+    this.replaceSnapshot({
+      fieldOptions: this.snapshot.fieldOptions,
+      remoteOptions,
+      loading,
+    })
+  }
+
+  /** Clear option state when renderForm/updateFormItem changes its source. */
+  invalidate(prop?: string) {
+    if (prop === undefined) this.remoteEnsures.clear()
+    else this.remoteEnsures.delete(prop)
+    const matches = (key: string) =>
+      prop === undefined || key === `field:${prop}` || key === `remote:${prop}`
+    this.controllers.forEach((controller, key) => {
+      if (!matches(key)) return
+      controller.abort('invalidated')
+      this.controllers.delete(key)
+    })
+
+    if (prop === undefined) {
+      Object.keys(this.originRemoteOptions).forEach(
+        (key) => delete this.originRemoteOptions[key]
+      )
+      this.remoteContexts.clear()
+      this.replaceSnapshot(createOptionsSnapshot())
+      return
+    }
+
+    delete this.originRemoteOptions[prop]
+    this.remoteContexts.delete(prop)
+    const fieldOptions = { ...this.snapshot.fieldOptions }
+    const remoteOptions = { ...this.snapshot.remoteOptions }
+    const loading = { ...this.snapshot.loading }
+    delete fieldOptions[prop]
+    delete remoteOptions[prop]
+    delete loading[prop]
+    this.replaceSnapshot({ fieldOptions, remoteOptions, loading })
+  }
+
+  private replaceSnapshot(snapshot: PageFormOptionsSnapshot) {
+    this.snapshot = {
+      fieldOptions: Object.freeze({ ...snapshot.fieldOptions }),
+      remoteOptions: Object.freeze({ ...snapshot.remoteOptions }),
+      loading: Object.freeze({ ...snapshot.loading }),
+    }
+    this.listeners.forEach((listener) => listener(this.snapshot))
+  }
+
+  private publish(
+    patch: Partial<{
+      fieldOptions: Record<string, readonly IOption[]>
+      remoteOptions: Record<string, readonly Record<string, unknown>[]>
+      loading: Record<string, boolean>
+    }>
+  ) {
+    this.snapshot = {
+      fieldOptions: Object.freeze({
+        ...this.snapshot.fieldOptions,
+        ...patch.fieldOptions,
+      }),
+      remoteOptions: Object.freeze({
+        ...this.snapshot.remoteOptions,
+        ...patch.remoteOptions,
+      }),
+      loading: Object.freeze({ ...this.snapshot.loading, ...patch.loading }),
+    }
+    this.listeners.forEach((listener) => listener(this.snapshot))
+  }
+
+  private begin(key: string, prop: string) {
+    this.controllers.get(key)?.abort('superseded')
+    const controller = new AbortController()
+    this.controllers.set(key, controller)
+    this.publish({ loading: { [prop]: true } })
+    return controller
+  }
+
+  private finish(key: string, prop: string, controller: AbortController) {
+    if (this.controllers.get(key) !== controller) return
+    this.controllers.delete(key)
+    this.publish({ loading: { [prop]: false } })
+  }
+
+  async loadFieldOptions(item: ResolvedIFormItem<TModel>) {
+    if (!item.optionsQuery) return item.options
+    const key = `field:${item.prop}`
+    const controller = this.begin(key, item.prop)
+    try {
+      const options = await awaitAbortable(item.optionsQuery, controller.signal)
+      const frozen = freezeFieldOptions(options)
+      this.publish({ fieldOptions: { [item.prop]: frozen } })
+      return frozen
+    } catch (error) {
+      throw controller.signal.aborted ? controller.signal.reason : error
+    } finally {
+      this.finish(key, item.prop, controller)
+    }
+  }
+
+  private localRemoteSearch(item: ResolvedIFormItem<TModel>, keyword: string) {
+    const remote = item.remoteSelectConfig
+    if (!remote) return []
+    const options = this.originRemoteOptions[item.prop] ?? []
+    const result = Object.freeze(
+      options.filter((option) =>
+        String(option[remote.searchKey ?? remote.labelKey] ?? '')
+          .toLocaleLowerCase()
+          .includes(keyword.toLocaleLowerCase())
+      )
+    )
+    this.publish({ remoteOptions: { [item.prop]: result } })
+    return result
+  }
+
+  async loadRemoteOptions(
+    item: ResolvedIFormItem<TModel>,
+    context: PageFormContext<TModel>,
+    requestValue: RemoteQuery = {}
+  ) {
+    const remote = item.remoteSelectConfig
+    if (!remote) return []
+    if (
+      requestValue.keyword &&
+      remote.dynamicQuery === false &&
+      this.originRemoteOptions[item.prop]
+    ) {
+      return this.localRemoteSearch(item, requestValue.keyword)
+    }
+    if (
+      requestValue.keyword === '' &&
+      remote.mandatoryQuery !== true &&
+      this.originRemoteOptions[item.prop]
+    ) {
+      const options = this.originRemoteOptions[item.prop]!
+      this.publish({ remoteOptions: { [item.prop]: options } })
+      return options
+    }
+    if (!this.remoteOptionLoader) {
+      throw new Error(
+        `PageForm remoteOptionLoader is required for remote field "${item.prop}"`
+      )
+    }
+
+    const key = `remote:${item.prop}`
+    const controller = this.begin(key, item.prop)
+    const query = createPageFormQuery(remote.limit ?? 1000)
+    const queryWay = remote.queryWay ?? 'like'
+    if (requestValue.keyword) {
+      query[queryWay](remote.searchKey ?? remote.labelKey, requestValue.keyword)
+    }
+    if (requestValue.value !== undefined && requestValue.value !== null) {
+      query[queryWay](remote.valueKey, requestValue.value)
+    }
+    if (requestValue.values?.length) {
+      query.eq(remote.valueKey, requestValue.values)
+    }
+    const request = {
+      ...context,
+      field: item,
+      api: remote.api,
+      query,
+      keyword: requestValue.keyword,
+      value: requestValue.value,
+      values: requestValue.values,
+      signal: controller.signal,
+    }
+
+    try {
+      if (remote.beforeQuery?.(query) === false) {
+        if (requestValue.value === undefined && !requestValue.values?.length) {
+          const empty = Object.freeze([]) as readonly Record<string, unknown>[]
+          this.publish({ remoteOptions: { [item.prop]: empty } })
+          delete this.originRemoteOptions[item.prop]
+        }
+        return []
+      }
+      let options = await awaitAbortable(
+        this.remoteOptionLoader(request),
+        controller.signal
+      )
+      const afterOptions = remote.afterQuery
+        ? await awaitAbortable(
+            Promise.resolve(remote.afterQuery(options, request)),
+            controller.signal
+          )
+        : undefined
+      if (afterOptions) options = afterOptions
+      const frozen = freezeRemoteOptions(options)
+      if (
+        requestValue.value !== undefined ||
+        Boolean(requestValue.values?.length)
+      ) {
+        const current = this.snapshot.remoteOptions[item.prop] ?? []
+        const mergedByValue = new Map<unknown, Record<string, unknown>>()
+        ;[...frozen, ...current].forEach((option) => {
+          const value = option[remote.valueKey]
+          if (!mergedByValue.has(value)) mergedByValue.set(value, option)
+        })
+        this.publish({
+          remoteOptions: {
+            [item.prop]: Object.freeze([...mergedByValue.values()]),
+          },
+        })
+      } else {
+        this.publish({ remoteOptions: { [item.prop]: frozen } })
+        if (requestValue.keyword === undefined) {
+          this.originRemoteOptions[item.prop] = frozen
+        }
+      }
+      return frozen
+    } catch (error) {
+      throw controller.signal.aborted ? controller.signal.reason : error
+    } finally {
+      this.finish(key, item.prop, controller)
+    }
+  }
+
+  async ensureRemoteOptions(
+    item: ResolvedIFormItem<TModel>,
+    context: PageFormContext<TModel>,
+    contextKey: unknown = createContextCacheKey(item, context)
+  ) {
+    const remote = item.remoteSelectConfig
+    if (!remote) return
+    const cachedContext = this.remoteContexts.get(item.prop)
+    if (
+      !cachedContext ||
+      !isSameCacheKey(cachedContext.key, contextKey) ||
+      !isSameRemoteConfig(cachedContext.config, remote) ||
+      cachedContext.loader !== this.remoteOptionLoader
+    ) {
+      this.invalidateRemote(item.prop)
+      this.remoteContexts.set(item.prop, {
+        key: contextKey,
+        config: remote,
+        loader: this.remoteOptionLoader,
+      })
+    }
+    const pending = this.remoteEnsures.get(item.prop)
+    if (pending && isSameCacheKey(pending.key, contextKey)) {
+      return pending.promise
+    }
+    const promise = (async () => {
+      if (!this.snapshot.remoteOptions[item.prop]) {
+        await this.loadRemoteOptions(item, context)
+      }
+      const value = (context.model as Record<string, unknown>)[item.prop]
+      if (value === undefined || value === null || value === '') return
+      const selectedValues = Array.isArray(value) ? value : [value]
+      const options = this.snapshot.remoteOptions[item.prop] ?? []
+      const missing = selectedValues.filter(
+        (selected) =>
+          !options.some((option) => option[remote.valueKey] === selected)
+      )
+      if (missing.length === 1) {
+        await this.loadRemoteOptions(item, context, { value: missing[0] })
+      } else if (missing.length > 1) {
+        await this.loadRemoteOptions(item, context, { values: missing })
+      }
+    })()
+    this.remoteEnsures.set(item.prop, { key: contextKey, promise })
+    try {
+      await promise
+    } finally {
+      if (this.remoteEnsures.get(item.prop)?.promise === promise) {
+        this.remoteEnsures.delete(item.prop)
+      }
+    }
+  }
+
+  resolveSelection(item: ResolvedIFormItem<TModel>, value: unknown) {
+    const remote = item.remoteSelectConfig
+    if (!remote) return Array.isArray(value) ? [] : {}
+    const options = this.snapshot.remoteOptions[item.prop] ?? []
+    return Array.isArray(value)
+      ? value
+          .map((selected) =>
+            options.find((option) => option[remote.valueKey] === selected)
+          )
+          .filter(
+            (option): option is Record<string, unknown> => option !== undefined
+          )
+      : (options.find((option) => option[remote.valueKey] === value) ?? {})
+  }
+
+  destroy() {
+    this.controllers.forEach((controller) => controller.abort('destroyed'))
+    this.controllers.clear()
+    this.remoteEnsures.clear()
+    this.listeners.clear()
+  }
+}
+
+export const createPageFormOptionsController = <TModel extends PageFormRecord>(
+  loader?: PageFormRemoteOptionLoader<TModel>
+) => new PageFormOptionsController(loader)

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

@@ -0,0 +1,44 @@
+import type {
+  PageFormQuery,
+  PageFormQueryCondition,
+  PageFormQueryWay,
+} from './types'
+
+/** 默认的框架无关查询对象，供远端 options loader 读取。 */
+class DefaultPageFormQuery implements PageFormQuery {
+  readonly conditions: PageFormQueryCondition[] = []
+
+  constructor(public readonly limit: number) {}
+
+  private add(way: PageFormQueryWay, key: string, value: unknown) {
+    this.conditions.push({ way, key, value })
+    return this
+  }
+
+  eq(key: string, value: unknown) {
+    return this.add('eq', key, value)
+  }
+
+  like(key: string, value: unknown) {
+    return this.add('like', key, value)
+  }
+
+  notEqual(key: string, value: unknown) {
+    return this.add('notEqual', key, value)
+  }
+
+  start(key: string, value: unknown) {
+    return this.add('start', key, value)
+  }
+
+  end(key: string, value: unknown) {
+    return this.add('end', key, value)
+  }
+
+  toJson() {
+    return { limit: this.limit, conditions: [...this.conditions] }
+  }
+}
+
+export const createPageFormQuery = (limit = 1000): PageFormQuery =>
+  new DefaultPageFormQuery(limit)

package/template/src/components/AppPageForm/style.css

@@ -0,0 +1,119 @@
+.hgw-page-form {
+  display: grid;
+  gap: 1.25rem;
+  width: 100%;
+}
+
+.hgw-page-form__actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  justify-content: flex-end;
+}
+
+.hgw-page-form__actions button,
+.hgw-page-form input,
+.hgw-page-form select,
+.hgw-page-form textarea {
+  min-height: 2.25rem;
+  font: inherit;
+  color: inherit;
+  background: transparent;
+  border: 1px solid color-mix(in srgb, currentcolor 22%, transparent);
+  border-radius: 0.375rem;
+}
+
+.hgw-page-form__actions button {
+  padding: 0.4rem 0.8rem;
+  cursor: pointer;
+}
+
+.hgw-page-form input,
+.hgw-page-form select,
+.hgw-page-form textarea {
+  width: 100%;
+  padding: 0.4rem 0.65rem;
+}
+
+.hgw-page-form__content {
+  display: grid;
+  gap: 1.5rem;
+}
+
+.hgw-page-form__content.has-right {
+  grid-template-columns: minmax(0, 1fr) minmax(14rem, 18rem);
+}
+
+.hgw-page-form__fields {
+  display: grid;
+  gap: 1rem 1.25rem;
+  min-width: 0;
+}
+
+.hgw-page-form__field {
+  display: grid;
+  gap: 0.4rem;
+  align-content: start;
+  min-width: 0;
+}
+
+.hgw-page-form__field.is-hidden {
+  display: none;
+}
+
+.hgw-page-form__field.is-block {
+  grid-column: 1 / -1;
+}
+
+.hgw-page-form__field > label {
+  font-weight: 600;
+}
+
+.hgw-page-form__field > label > span,
+.hgw-page-form__error,
+.hgw-page-form__feedback.is-error {
+  color: #dc2626;
+}
+
+.hgw-page-form__radio {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.75rem;
+}
+
+.hgw-page-form__radio label {
+  display: inline-flex;
+  gap: 0.35rem;
+  align-items: center;
+}
+
+.hgw-page-form__radio input {
+  width: auto;
+}
+
+.hgw-page-form__remote-select {
+  display: grid;
+  gap: 0.4rem;
+}
+
+.hgw-page-form__error,
+.hgw-page-form__feedback {
+  margin: 0;
+  font-size: 0.875rem;
+}
+
+.hgw-page-form__feedback {
+  padding: 0.6rem 0.75rem;
+  border: 1px solid currentcolor;
+  border-radius: 0.375rem;
+}
+
+.hgw-page-form__feedback.is-success {
+  color: #15803d;
+}
+
+@media (width <= 768px) {
+  .hgw-page-form__content.has-right {
+    grid-template-columns: minmax(0, 1fr);
+  }
+}