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

package/template/src/components/AppTable/search/tableSearchBar.css

@@ -0,0 +1,164 @@
+.table-search-bar {
+  position: relative;
+  z-index: 3;
+  flex: none;
+  padding: 16px 20px;
+  margin: 0;
+  container-type: inline-size;
+  background: var(--background);
+  border-bottom: 1px solid var(--border);
+}
+
+.table-search-bar__layout {
+  display: grid;
+  grid-template-columns: minmax(280px, 1fr) max-content;
+  gap: 16px 24px;
+  align-items: start;
+}
+
+.table-search-bar__fields-shell {
+  position: relative;
+  min-width: 0;
+  height: var(--table-search-collapsed-height);
+}
+
+.table-search-bar__fields-shell[data-unrestricted='true'] {
+  height: auto;
+}
+
+.table-search-bar__fields {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
+  gap: 16px 24px;
+  width: 100%;
+  min-width: 0;
+  max-height: var(--table-search-collapsed-height);
+  overflow: clip;
+  overflow-clip-margin: 4px;
+}
+
+.table-search-bar__fields[data-unrestricted='true'] {
+  max-height: none;
+  overflow: visible;
+  overflow-clip-margin: 0;
+}
+
+.table-search-bar__fields[data-expanded='true'] {
+  position: absolute;
+  top: -12px;
+  right: -12px;
+  left: -12px;
+  z-index: 2;
+  box-sizing: border-box;
+  width: auto;
+  max-height: var(--table-search-expanded-height);
+  padding: 12px;
+  overflow: hidden;
+  overflow-clip-margin: 0;
+  background: var(--background);
+  border-radius: var(--radius-md);
+  box-shadow:
+    0 0 0 1px var(--border),
+    0 4px 8px rgb(0 0 0 / 10%);
+  animation: table-search-expand 180ms cubic-bezier(0.25, 1, 0.5, 1) both;
+}
+
+.table-search-bar__fields[data-expanded='true'][data-open='true'] {
+  overflow: auto;
+}
+
+.table-search-bar__fields[data-expanded='true'][data-collapsing='true'] {
+  pointer-events: none;
+  animation: table-search-collapse 130ms cubic-bezier(0.4, 0, 1, 1) forwards;
+}
+
+.table-search-bar__field {
+  display: grid;
+  grid-template-columns: var(--table-search-label-width) minmax(0, 1fr);
+  gap: 12px;
+  min-height: var(--table-search-collapsed-height);
+}
+
+.table-search-bar__label {
+  line-height: var(--table-search-collapsed-height);
+}
+
+.table-search-bar__actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  align-items: center;
+  min-height: var(--table-search-collapsed-height);
+}
+
+.table-search-bar__form-action {
+  height: var(--table-search-collapsed-height);
+}
+
+@keyframes table-search-expand {
+  from {
+    max-height: calc(var(--table-search-collapsed-height) + 24px);
+  }
+
+  to {
+    max-height: var(--table-search-expanded-height);
+  }
+}
+
+@keyframes table-search-collapse {
+  from {
+    max-height: var(--table-search-expanded-height);
+  }
+
+  to {
+    max-height: calc(var(--table-search-collapsed-height) + 24px);
+  }
+}
+
+@container (width <= 640px) {
+  .table-search-bar__layout {
+    grid-template-columns: minmax(0, 1fr);
+  }
+
+  .table-search-bar__actions {
+    justify-content: flex-end;
+  }
+
+  .table-search-bar__fields-shell[data-expanded='true'] {
+    height: auto;
+  }
+
+  .table-search-bar__fields[data-expanded='true'] {
+    position: static;
+    max-height: none;
+    padding: 0;
+    overflow: visible;
+    background: transparent;
+    border: 0;
+    box-shadow: none;
+  }
+}
+
+@container (width <= 520px) {
+  .table-search-bar {
+    padding: 12px 16px;
+  }
+
+  .table-search-bar__layout {
+    gap: 12px;
+  }
+
+  .table-search-bar__fields {
+    grid-template-columns: 1fr;
+  }
+
+  .table-search-bar__actions {
+    justify-content: flex-start;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .table-search-bar__fields[data-expanded='true'] {
+    animation-duration: 0.01ms;
+  }
+}

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

@@ -0,0 +1,7 @@
+/** AppTable 搜索区字段顺序和隐藏状态发生变化时的偏好快照。 */
+export interface ITableSearchConditionPreferenceChange {
+  /** 按显示优先级排列的搜索字段 key。 */
+  arrOrder: string[]
+  /** 当前被用户隐藏的搜索字段 key。 */
+  arrHidden: string[]
+}

package/template/src/components/AppTable/search/useTableQuery.ts

@@ -0,0 +1,373 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { resolveTablePaginationConfig } from '@/components/AppTable/engine/pagination/config'
+import { type TablePreferenceUpdater } from '@/components/AppTable/engine/preference/preference'
+import { runTableLocalQuery } from '@/components/AppTable/engine/search/localQuery'
+import {
+  buildTableQueryParams,
+  createSearchModel,
+} from '@/components/AppTable/engine/search/query'
+import type {
+  TableQueryParams,
+  TableQueryResult,
+  TableSearchCondition,
+  TableSearchModel,
+} from '@/components/AppTable/engine/search/types'
+import type { SelectionState } from '@/components/AppTable/engine/selection/types'
+import type {
+  TableOption,
+  TableRow,
+} from '@/components/AppTable/engine/shared/types'
+import type { TableController } from '@/components/AppTable/engine/table/controller/TableController'
+import type { ResolvedTableComponentProps } from '../config'
+
+interface IUseTableQueryOptions<T extends TableRow> {
+  strTableKey: string
+  objController: TableController<T>
+  objProps: ResolvedTableComponentProps<T>
+  arrSearchConditions: readonly TableSearchCondition[]
+  arrAllSearchConditions: readonly TableSearchCondition[]
+  fnOnQuery?: (objParams: TableQueryParams) => void
+  fnOnQuerySuccess?: (objResult: TableQueryResult<T>) => void
+  fnOnDataChange?: (arrRows: T[]) => void
+  fnOnSelectionChange?: (arrRows: T[], objSelection: SelectionState<T>) => void
+  fnBeforeQuery?: () => void
+  fnReportError: (objError: unknown) => void
+  fnClearError: () => void
+  bPreferenceReady: boolean
+  nPreferredPageSize: number
+  fnUpdatePreference: (updater: TablePreferenceUpdater) => Promise<unknown>
+}
+
+export function useTableQuery<T extends TableRow>({
+  strTableKey,
+  objController,
+  objProps,
+  arrSearchConditions,
+  arrAllSearchConditions,
+  fnOnQuery,
+  fnOnQuerySuccess,
+  fnOnDataChange,
+  fnOnSelectionChange,
+  fnBeforeQuery,
+  fnReportError,
+  fnClearError,
+  bPreferenceReady,
+  nPreferredPageSize,
+  fnUpdatePreference,
+}: IUseTableQueryOptions<T>) {
+  const objLocalRowsRef = useRef<readonly T[]>(objProps.data)
+  const objSearchConditionTypesRef = useRef(
+    new Map(
+      arrAllSearchConditions.map((objCondition) => [
+        objCondition.key,
+        objCondition.type ?? 'input',
+      ])
+    )
+  )
+  const objRemoteAbortControllersRef = useRef(
+    new Map<string, AbortController>()
+  )
+  const objLocalQueryAbortControllerRef = useRef<AbortController | undefined>(
+    undefined
+  )
+  const [objSearchModel, fnSetSearchModel] = useState<TableSearchModel>(() =>
+    createSearchModel(arrAllSearchConditions)
+  )
+  const [nPage, fnSetPage] = useState(1)
+  const [nPageSize, fnSetPageSize] = useState(nPreferredPageSize)
+  const bAutoQueryStartedRef = useRef(false)
+  const [bInitialQuerySettled, fnSetInitialQuerySettled] = useState(
+    () => !objProps.query || !objProps.autoQuery
+  )
+  const bInitialQuerySettledRef = useRef(bInitialQuerySettled)
+  const [objRemoteOptions, fnSetRemoteOptions] = useState<
+    Record<string, readonly TableOption[]>
+  >({})
+  const [objRemoteLoading, fnSetRemoteLoading] = useState<
+    Record<string, boolean>
+  >({})
+  const objPagination = useMemo(
+    () => resolveTablePaginationConfig(objProps.pagination),
+    [objProps.pagination]
+  )
+
+  useEffect(() => {
+    objLocalQueryAbortControllerRef.current?.abort('source-changed')
+    objLocalRowsRef.current = objProps.data
+  }, [objProps.data])
+
+  useEffect(() => {
+    if (bPreferenceReady) fnSetPageSize(nPreferredPageSize)
+  }, [bPreferenceReady, nPreferredPageSize])
+
+  useEffect(() => {
+    fnSetSearchModel((objCurrent) => {
+      const objNext: TableSearchModel = { ...objCurrent }
+      const objNextKeys = new Set(
+        arrAllSearchConditions.map((objCondition) => objCondition.key)
+      )
+      Object.keys(objNext).forEach((strKey) => {
+        if (!objNextKeys.has(strKey)) Reflect.deleteProperty(objNext, strKey)
+      })
+      arrAllSearchConditions.forEach((objCondition) => {
+        const strType = objCondition.type ?? 'input'
+        if (
+          !Object.prototype.hasOwnProperty.call(objNext, objCondition.key) ||
+          objSearchConditionTypesRef.current.get(objCondition.key) !== strType
+        ) {
+          objNext[objCondition.key] = createSearchModel([objCondition])[
+            objCondition.key
+          ]
+        }
+      })
+      objSearchConditionTypesRef.current = new Map(
+        arrAllSearchConditions.map((objCondition) => [
+          objCondition.key,
+          objCondition.type ?? 'input',
+        ])
+      )
+      return objNext
+    })
+  }, [arrAllSearchConditions])
+
+  useEffect(
+    () => () => {
+      objRemoteAbortControllersRef.current.forEach((objAbortController) =>
+        objAbortController.abort('destroyed')
+      )
+      objLocalQueryAbortControllerRef.current?.abort('destroyed')
+    },
+    []
+  )
+
+  const fnLoadRemoteSearchOptions = useCallback(
+    async (objCondition: TableSearchCondition, strQuery = '') => {
+      if (!objCondition.loadOptions) return
+      objRemoteAbortControllersRef.current
+        .get(objCondition.key)
+        ?.abort('superseded')
+      const objAbortController = new AbortController()
+      objRemoteAbortControllersRef.current.set(
+        objCondition.key,
+        objAbortController
+      )
+      fnSetRemoteLoading((objCurrent) => ({
+        ...objCurrent,
+        [objCondition.key]: true,
+      }))
+      try {
+        const arrOptions = await objCondition.loadOptions({
+          query: strQuery,
+          signal: objAbortController.signal,
+          tableKey: strTableKey,
+          conditionKey: objCondition.key,
+        })
+        if (!objAbortController.signal.aborted) {
+          fnSetRemoteOptions((objCurrent) => ({
+            ...objCurrent,
+            [objCondition.key]: arrOptions,
+          }))
+        }
+      } catch (objError) {
+        if (!objAbortController.signal.aborted) fnReportError(objError)
+      } finally {
+        if (
+          objRemoteAbortControllersRef.current.get(objCondition.key) ===
+          objAbortController
+        ) {
+          fnSetRemoteLoading((objCurrent) => ({
+            ...objCurrent,
+            [objCondition.key]: false,
+          }))
+        }
+      }
+    },
+    [fnReportError, strTableKey]
+  )
+
+  const fnRunQuery = useCallback(
+    async (
+      nNextPage = nPage,
+      nNextPageSize = nPageSize,
+      objNextSearchModel = objSearchModel,
+      bInterceptSearch = false
+    ) => {
+      fnClearError()
+      let objParams = buildTableQueryParams(
+        objPagination.mode === 'all' ? 1 : nNextPage,
+        objPagination.mode === 'all'
+          ? objPagination.maxRows + 1
+          : nNextPageSize,
+        [...arrSearchConditions],
+        objNextSearchModel
+      )
+      if (bInterceptSearch && objProps.beforeSearchSubmit) {
+        const objIntercepted = await objProps.beforeSearchSubmit({
+          model: { ...objNextSearchModel },
+          params: objParams,
+        })
+        if (objIntercepted === false) return false
+        if (objIntercepted && typeof objIntercepted === 'object') {
+          objParams = objIntercepted
+        }
+      }
+      fnBeforeQuery?.()
+      fnOnQuery?.(objParams)
+      if (nNextPageSize !== nPageSize) {
+        void fnUpdatePreference((objCurrent) => ({
+          ...objCurrent,
+          pageSize: nNextPageSize,
+        }))
+      }
+      fnSetPage(nNextPage)
+      fnSetPageSize(nNextPageSize)
+      let objLocalQueryAbortController: AbortController | undefined
+      try {
+        if (objProps.query) {
+          objLocalQueryAbortControllerRef.current?.abort('remote-query')
+          const objOutcome = await objController.runQuery(objParams, {
+            ...(objPagination.mode === 'all'
+              ? {
+                  maxRows: objPagination.maxRows,
+                  requireComplete: true,
+                }
+              : {}),
+          })
+          if (objOutcome.status !== 'applied' || !objOutcome.result) {
+            return false
+          }
+          if (!objProps.keepSelection) objController.clearSelection()
+          fnOnSelectionChange?.(
+            objController.getLoadedSelectedRows(),
+            objController.getSelection()
+          )
+          // 回调继续收到独立外层数组，不能把 provider 的可变结果直接暴露给业务侧。
+          fnOnDataChange?.(objController.getData())
+          fnOnQuerySuccess?.(objOutcome.result)
+          return true
+        }
+        objController.cancelQuery()
+        objLocalQueryAbortControllerRef.current?.abort('superseded')
+        objLocalQueryAbortController = new AbortController()
+        objLocalQueryAbortControllerRef.current = objLocalQueryAbortController
+        const arrFilteredRows = await runTableLocalQuery(
+          objLocalRowsRef.current,
+          objParams,
+          { signal: objLocalQueryAbortController.signal }
+        )
+        if (
+          objLocalQueryAbortController.signal.aborted ||
+          objLocalQueryAbortControllerRef.current !==
+            objLocalQueryAbortController
+        ) {
+          return false
+        }
+        const arrPageRows = objPagination.enabled
+          ? arrFilteredRows.slice(
+              (nNextPage - 1) * nNextPageSize,
+              nNextPage * nNextPageSize
+            )
+          : arrFilteredRows
+        objController.replaceData(arrPageRows, arrFilteredRows.length)
+        if (!objProps.keepSelection) {
+          objController.clearSelection()
+        }
+        fnOnSelectionChange?.(
+          objController.getLoadedSelectedRows(),
+          objController.getSelection()
+        )
+        const objResult = { list: arrPageRows, total: arrFilteredRows.length }
+        fnOnDataChange?.(arrPageRows)
+        fnOnQuerySuccess?.(objResult)
+        return true
+      } catch (objError) {
+        if (objLocalQueryAbortController?.signal.aborted) return false
+        fnReportError(objError)
+        return false
+      } finally {
+        if (
+          objLocalQueryAbortController &&
+          objLocalQueryAbortControllerRef.current ===
+            objLocalQueryAbortController
+        ) {
+          objLocalQueryAbortControllerRef.current = undefined
+        }
+        // 只在当前活动请求已经结束时开放首次呈现。若本次请求被更新的查询取代，
+        // Controller 仍处于 loading，交由最后完成的请求解除门控。
+        if (
+          !bInitialQuerySettledRef.current &&
+          !objController.snapshot.loading
+        ) {
+          bInitialQuerySettledRef.current = true
+          fnSetInitialQuerySettled(true)
+        }
+      }
+    },
+    [
+      fnClearError,
+      fnOnQuery,
+      fnOnQuerySuccess,
+      fnOnDataChange,
+      fnOnSelectionChange,
+      fnBeforeQuery,
+      fnReportError,
+      fnUpdatePreference,
+      nPage,
+      nPageSize,
+      objController,
+      objPagination.enabled,
+      objPagination.maxRows,
+      objPagination.mode,
+      objProps,
+      objSearchModel,
+      arrSearchConditions,
+    ]
+  )
+
+  const fnChangePagination = useCallback(
+    async (nNextPage: number, nNextPageSize: number) => {
+      if (objPagination.queryOnChange) {
+        return fnRunQuery(nNextPage, nNextPageSize)
+      }
+      if (nNextPageSize !== nPageSize) {
+        void fnUpdatePreference((objCurrent) => ({
+          ...objCurrent,
+          pageSize: nNextPageSize,
+        }))
+      }
+      fnSetPage(nNextPage)
+      fnSetPageSize(nNextPageSize)
+      return true
+    },
+    [fnRunQuery, fnUpdatePreference, nPageSize, objPagination.queryOnChange]
+  )
+
+  useEffect(() => {
+    if (
+      !bPreferenceReady ||
+      !objProps.autoQuery ||
+      bAutoQueryStartedRef.current
+    )
+      return
+    const nAutoQueryTimer = window.setTimeout(() => {
+      if (bAutoQueryStartedRef.current) return
+      bAutoQueryStartedRef.current = true
+      void fnRunQuery(1, nPreferredPageSize)
+    }, 0)
+    return () => window.clearTimeout(nAutoQueryTimer)
+  }, [bPreferenceReady, fnRunQuery, nPreferredPageSize, objProps.autoQuery])
+
+  return {
+    objPagination,
+    objSearchModel,
+    fnSetSearchModel,
+    nPage,
+    nPageSize,
+    objRemoteOptions,
+    objRemoteLoading,
+    bInitialQuerySettled,
+    fnLoadRemoteSearchOptions,
+    fnRunQuery,
+    fnChangePagination,
+  }
+}

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

@@ -0,0 +1 @@
+export { useTableSelection } from './useTableSelection'