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

package/template/src/components/AppTable/reporting/useTableReporting.ts

@@ -0,0 +1,342 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import type { TableIntlFormatter } from '@/components/AppTable/engine/cell/formatting'
+import type { TablePreference } from '@/components/AppTable/engine/preference/types'
+import { isSelectionFullyLoaded } from '@/components/AppTable/engine/selection/selection'
+import type { TableRow } from '@/components/AppTable/engine/shared/types'
+import {
+  buildTableExportActions,
+  buildTableExportColumns,
+  resolveTableExportConfig,
+} from '@/components/AppTable/engine/summary/config/export'
+import {
+  buildTableSummaryColumns,
+  resolveTableSummaryConfig,
+} from '@/components/AppTable/engine/summary/config/summary'
+import type { TableExportAction } from '@/components/AppTable/engine/summary/config/types'
+import { createExcelJsTableWriter } from '@/components/AppTable/engine/summary/excelJs'
+import type {
+  TableExportFormat,
+  TableExportScope,
+  TableExportTask,
+} from '@/components/AppTable/engine/summary/export'
+import type {
+  TableSummaryResult,
+  TableSummaryScope,
+} from '@/components/AppTable/engine/summary/summary'
+import type { TableController } from '@/components/AppTable/engine/table/controller/TableController'
+import type { TableSnapshot } from '@/components/AppTable/engine/table/controller/types'
+import type { ResolvedTableComponentProps, TableColumn } from '../config'
+import { useAppTableMessages } from '../messages'
+
+interface IUseTableReportingOptions<T extends TableRow> {
+  strTableKey: string
+  objController: TableController<T>
+  objSnapshot: TableSnapshot<T>
+  objProps: ResolvedTableComponentProps<T>
+  arrColumns: readonly TableColumn<T>[]
+  objPreference: TablePreference
+  objFormatter: TableIntlFormatter
+  fnOnSummarySuccess?: (objResult: TableSummaryResult) => void
+  fnOnExportSuccess?: (objTask: TableExportTask) => void
+  fnOnExportJob?: (objTask: Extract<TableExportTask, { mode: 'job' }>) => void
+  fnReportError: (objError: unknown) => void
+}
+
+const fnIsAbortError = (objError: unknown) =>
+  typeof DOMException !== 'undefined' &&
+  objError instanceof DOMException &&
+  objError.name === 'AbortError'
+
+/** 将 engine 汇总与导出服务映射为 React 状态和浏览器下载行为。 */
+export function useTableReporting<T extends TableRow>({
+  strTableKey,
+  objController,
+  objSnapshot,
+  objProps,
+  arrColumns,
+  objPreference,
+  objFormatter,
+  fnOnSummarySuccess,
+  fnOnExportSuccess,
+  fnOnExportJob,
+  fnReportError,
+}: IUseTableReportingOptions<T>) {
+  const objMessages = useAppTableMessages()
+  const [objDefaultXlsxWriter] = useState(() => createExcelJsTableWriter<T>())
+  const [objSummaryResult, fnSetSummaryResult] = useState<TableSummaryResult>()
+  const [nSummaryRevision, fnSetSummaryRevision] = useState(-1)
+  const objSummaryTimerRef = useRef<number | undefined>(undefined)
+
+  const arrVisibleColumns = useMemo(
+    () =>
+      arrColumns.filter(
+        (objColumn) => objColumn.enabled !== false && !objColumn.hidden
+      ),
+    [arrColumns]
+  )
+  const objSummaryOptions = useMemo(
+    () =>
+      resolveTableSummaryConfig(objProps.summary, {
+        locale: objProps.locale,
+        timeZone: objProps.timeZone,
+        label: objMessages.strSummary,
+      }),
+    [
+      objMessages.strSummary,
+      objProps.locale,
+      objProps.summary,
+      objProps.timeZone,
+    ]
+  )
+  const arrSummaryColumns = useMemo(
+    () =>
+      buildTableSummaryColumns(
+        objSummaryOptions,
+        arrVisibleColumns,
+        (objValue, objFormat) => objFormatter.format(objValue, objFormat)
+      ),
+    [arrVisibleColumns, objFormatter, objSummaryOptions]
+  )
+  const strSummaryLabel = objSummaryOptions?.label ?? objMessages.strSummary
+  const objExportConfig = useMemo(
+    () =>
+      resolveTableExportConfig(objProps.exportOptions, {
+        remote: Boolean(objProps.query),
+        defaultXlsxWriter: objDefaultXlsxWriter,
+        locale: objProps.locale,
+        timeZone: objProps.timeZone,
+      }),
+    [
+      objDefaultXlsxWriter,
+      objProps.exportOptions,
+      objProps.locale,
+      objProps.query,
+      objProps.timeZone,
+    ]
+  )
+  const arrExportColumns = useMemo(
+    () =>
+      buildTableExportColumns(
+        arrVisibleColumns,
+        objPreference,
+        (objValue, objFormat) => objFormatter.format(objValue, objFormat)
+      ),
+    [arrVisibleColumns, objFormatter, objPreference]
+  )
+  const bHasSelection =
+    objSnapshot.selection.mode === 'allMatching' ||
+    objSnapshot.selection.keys.size > 0
+  const arrExportActions = useMemo<TableExportAction[]>(
+    () =>
+      buildTableExportActions({
+        config: objExportConfig,
+        remote: Boolean(objProps.query),
+        hasSelection: bHasSelection,
+        selectionFullyLoaded: isSelectionFullyLoaded(objSnapshot.selection),
+        scopeLabels: {
+          range: objMessages.strExportRange,
+          page: objMessages.strExportPage,
+          selection: objMessages.strExportSelection,
+          all: objMessages.strExportAll,
+        },
+      }),
+    [
+      bHasSelection,
+      objExportConfig,
+      objMessages,
+      objProps.query,
+      objSnapshot.selection,
+    ]
+  )
+
+  const fnSummarize = useCallback(
+    async (
+      strScope: TableSummaryScope = objSummaryOptions?.scope ?? 'page'
+    ) => {
+      if (!arrSummaryColumns.length) {
+        const objEmpty: TableSummaryResult = {
+          scope: strScope,
+          source: 'local',
+          values: {},
+          formattedValues: {},
+        }
+        fnSetSummaryResult(undefined)
+        fnSetSummaryRevision(-1)
+        return objEmpty
+      }
+      const nDataRevision = objController.dataRevision
+      const objResult = await objController.summarize({
+        scope: strScope,
+        columns: arrSummaryColumns,
+        locale: objSummaryOptions?.locale,
+        timeZone: objSummaryOptions?.timeZone,
+      })
+      if (nDataRevision !== objController.dataRevision) return objResult
+      fnSetSummaryRevision(nDataRevision)
+      fnSetSummaryResult(objResult)
+      fnOnSummarySuccess?.(objResult)
+      return objResult
+    },
+    [arrSummaryColumns, fnOnSummarySuccess, objController, objSummaryOptions]
+  )
+
+  const fnRefreshSummary = useCallback(() => {
+    window.clearTimeout(objSummaryTimerRef.current)
+    objSummaryTimerRef.current = window.setTimeout(() => {
+      objSummaryTimerRef.current = undefined
+      void fnSummarize().catch((objError: unknown) => {
+        if (!fnIsAbortError(objError)) fnReportError(objError)
+      })
+    }, 80)
+  }, [fnReportError, fnSummarize])
+
+  useEffect(() => {
+    fnRefreshSummary()
+    return () => window.clearTimeout(objSummaryTimerRef.current)
+  }, [
+    fnRefreshSummary,
+    objSnapshot.dataRevision,
+    objSummaryOptions?.scope,
+    objSummaryOptions?.locale,
+    objSummaryOptions?.timeZone,
+  ])
+
+  const fnGetRangeExportData = useCallback(() => {
+    const objInstance = objController.instance
+    const setPhysicalRows = new Set<number>()
+    const setSelectedProperties = new Set<string>()
+    ;(objInstance?.getSelected() ?? []).forEach((arrRange) => {
+      const nStartRow = Math.max(0, Math.min(arrRange[0], arrRange[2]))
+      const nEndRow = Math.max(arrRange[0], arrRange[2])
+      for (let nRow = nStartRow; nRow <= nEndRow; nRow += 1) {
+        setPhysicalRows.add(objInstance?.toPhysicalRow(nRow) ?? nRow)
+      }
+      const nStartColumn = Math.max(0, Math.min(arrRange[1], arrRange[3]))
+      const nEndColumn = Math.max(arrRange[1], arrRange[3])
+      for (let nColumn = nStartColumn; nColumn <= nEndColumn; nColumn += 1) {
+        const objProperty = objInstance?.colToProp(nColumn)
+        if (
+          typeof objProperty === 'string' &&
+          objProperty !== '__tableSelection'
+        ) {
+          setSelectedProperties.add(objProperty)
+        }
+      }
+    })
+    const arrRows = [...setPhysicalRows]
+      .sort((nLeft, nRight) => nLeft - nRight)
+      .flatMap((nRow) =>
+        objSnapshot.rows[nRow] ? [objSnapshot.rows[nRow]!] : []
+      )
+    const arrColumns = [...setSelectedProperties].flatMap((strProperty) => {
+      const objColumn = arrExportColumns.find(
+        (objEntry) => String(objEntry.key) === strProperty
+      )
+      return objColumn ? [objColumn] : []
+    })
+    return { arrRows, arrColumns }
+  }, [arrExportColumns, objController, objSnapshot.rows])
+
+  const fnDownloadExport = useCallback(
+    (objTask: Extract<TableExportTask, { mode: 'download' }>) => {
+      if (!objTask.blob && !objTask.url) {
+        throw new Error('[TableComponent] Export download has no blob or URL.')
+      }
+      const strObjectUrl = objTask.blob
+        ? URL.createObjectURL(objTask.blob)
+        : undefined
+      const objExternalUrl = objTask.url
+        ? new URL(objTask.url, window.location.href)
+        : null
+      if (
+        objExternalUrl &&
+        !['http:', 'https:', 'blob:'].includes(objExternalUrl.protocol)
+      ) {
+        throw new Error('[TableComponent] Export URL uses an unsafe protocol.')
+      }
+      const objAnchor = document.createElement('a')
+      objAnchor.href = strObjectUrl ?? objExternalUrl!.href
+      objAnchor.download = objTask.fileName
+      objAnchor.rel = 'noopener noreferrer'
+      objAnchor.click()
+      if (strObjectUrl) {
+        window.setTimeout(() => URL.revokeObjectURL(strObjectUrl), 0)
+      }
+    },
+    []
+  )
+
+  const fnExecuteExport = useCallback(
+    async (
+      strScope: TableExportScope = 'page',
+      strFormat: TableExportFormat = 'csv',
+      strFileName?: string
+    ) => {
+      if (strScope === 'selection' && !bHasSelection) {
+        throw new Error(
+          '[TableComponent] Select at least one row before export.'
+        )
+      }
+      const objRange = strScope === 'range' ? fnGetRangeExportData() : undefined
+      if (
+        strScope === 'range' &&
+        (!objRange?.arrRows.length || !objRange.arrColumns.length)
+      ) {
+        throw new Error('[TableComponent] Select a cell range before export.')
+      }
+      const objConfiguredFileName = objExportConfig?.fileName
+      const objTask = await objController.exportData({
+        scope: strScope,
+        format: strFormat,
+        fileName:
+          strFileName ??
+          (typeof objConfiguredFileName === 'function'
+            ? objConfiguredFileName()
+            : (objConfiguredFileName ?? strTableKey)),
+        sheetName: objExportConfig?.sheetName,
+        columns: arrExportColumns,
+        rangeRows: objRange?.arrRows,
+        rangeColumns: objRange?.arrColumns,
+        locale: objExportConfig?.locale,
+        timeZone: objExportConfig?.timeZone,
+      })
+      if (objTask.mode === 'download') fnDownloadExport(objTask)
+      else fnOnExportJob?.(objTask)
+      fnOnExportSuccess?.(objTask)
+      return objTask
+    },
+    [
+      arrExportColumns,
+      bHasSelection,
+      fnDownloadExport,
+      fnGetRangeExportData,
+      fnOnExportJob,
+      fnOnExportSuccess,
+      objController,
+      objExportConfig,
+      strTableKey,
+    ]
+  )
+
+  const fnRunExportAction = useCallback(
+    (objAction: TableExportAction) => {
+      void fnExecuteExport(objAction.scope, objAction.format).catch(
+        fnReportError
+      )
+    },
+    [fnExecuteExport, fnReportError]
+  )
+
+  return {
+    objSummaryOptions,
+    arrSummaryColumns,
+    strSummaryLabel,
+    objSummaryResult,
+    nSummaryRevision,
+    arrExportActions,
+    fnSummarize,
+    fnRefreshSummary,
+    fnExecuteExport,
+    fnRunExportAction,
+  }
+}

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

@@ -0,0 +1,301 @@
+import {
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type AnimationEvent,
+  type CSSProperties,
+  type KeyboardEvent,
+} from 'react'
+import { Loader2 } from 'lucide-react'
+import { Button } from '@/components/ui/button'
+import {
+  isTableSearchContentOverflowing,
+  shouldSubmitTableSearchOnEnter,
+} from '@/components/AppTable/engine/search/searchInteraction'
+import type { TableSearchModel } from '@/components/AppTable/engine/search/types'
+import type { TableOption } from '@/components/AppTable/engine/shared/types'
+import type { TableSearchCondition, TableSearchLayoutConfig } from '../config'
+import { useAppTableMessages } from '../messages'
+import { TableSearchConditionEditor } from './TableSearchConditionEditor'
+import { TableSearchFields } from './TableSearchFields'
+import { TABLE_SEARCH_LAYOUT } from './constants'
+import './tableSearchBar.css'
+import type { ITableSearchConditionPreferenceChange } from './types'
+
+interface ITableSearchBarProps {
+  strTableKey: string
+  arrConditions: readonly TableSearchCondition[]
+  arrAllConditions: readonly TableSearchCondition[]
+  arrHiddenConditionKeys: readonly string[]
+  arrConditionOrder: readonly string[]
+  objModel: TableSearchModel
+  objRemoteOptions: Readonly<Record<string, readonly TableOption[]>>
+  objRemoteLoading: Readonly<Record<string, boolean>>
+  objLayout?: TableSearchLayoutConfig
+  bLoading: boolean
+  bLayoutTransitioning?: boolean
+  fnOnChange: (strKey: string, objValue: unknown) => void
+  fnOnRemoteQuery: (
+    objCondition: TableSearchCondition,
+    strQuery: string
+  ) => void
+  fnOnConditionsChange: (
+    objValue: ITableSearchConditionPreferenceChange
+  ) => void
+  fnOnReset: () => void
+  fnOnSearch: () => void
+}
+
+function fnToCssSize(
+  objValue: number | string | undefined,
+  strFallback: string
+) {
+  return typeof objValue === 'number'
+    ? `${objValue}px`
+    : (objValue ?? strFallback)
+}
+
+function fnMeasureLabelContentWidth(objLabel: HTMLElement) {
+  const objRange = document.createRange()
+  objRange.selectNodeContents(objLabel)
+  return Math.ceil(objRange.getBoundingClientRect().width)
+}
+
+export function TableSearchBar({
+  strTableKey,
+  arrConditions,
+  arrAllConditions,
+  arrHiddenConditionKeys,
+  arrConditionOrder,
+  objModel,
+  objRemoteOptions,
+  objRemoteLoading,
+  objLayout,
+  bLoading,
+  bLayoutTransitioning = false,
+  fnOnChange,
+  fnOnRemoteQuery,
+  fnOnConditionsChange,
+  fnOnReset,
+  fnOnSearch,
+}: ITableSearchBarProps) {
+  const objMessages = useAppTableMessages()
+  const objFieldsRef = useRef<HTMLDivElement>(null)
+  const [bExpanded, fnSetExpanded] = useState(false)
+  const [bExpandedReady, fnSetExpandedReady] = useState(false)
+  const [bCollapsing, fnSetCollapsing] = useState(false)
+  const [bShowExpand, fnSetShowExpand] = useState(false)
+  const [nExpandedHeight, fnSetExpandedHeight] = useState(0)
+  const objLayoutTransitioningRef = useRef(bLayoutTransitioning)
+  useLayoutEffect(() => {
+    objLayoutTransitioningRef.current = bLayoutTransitioning
+  }, [bLayoutTransitioning])
+  const bExpandable = objLayout?.expandable ?? TABLE_SEARCH_LAYOUT.expandable
+  const strCollapsedHeight = fnToCssSize(
+    objLayout?.collapsedHeight,
+    TABLE_SEARCH_LAYOUT.collapsedHeight
+  )
+  const objLabelWidth = objLayout?.labelWidth ?? TABLE_SEARCH_LAYOUT.labelWidth
+  const objSearchBarStyle = {
+    '--table-search-collapsed-height': strCollapsedHeight,
+    '--table-search-expanded-height': `${nExpandedHeight}px`,
+    '--table-search-label-width': fnToCssSize(
+      objLabelWidth,
+      TABLE_SEARCH_LAYOUT.labelWidth
+    ),
+  } as CSSProperties
+
+  useLayoutEffect(() => {
+    const objFields = objFieldsRef.current
+    if (!objFields) return
+    if (objLabelWidth !== 'auto') {
+      objFields.style.removeProperty('--table-search-label-width')
+      return
+    }
+    const arrLabels = Array.from(
+      objFields.querySelectorAll<HTMLElement>('.table-search-bar__label')
+    )
+    const nLabelWidth = Math.max(
+      0,
+      ...arrLabels.map(fnMeasureLabelContentWidth)
+    )
+    if (nLabelWidth > 0) {
+      objFields.style.setProperty(
+        '--table-search-label-width',
+        `${nLabelWidth}px`
+      )
+    }
+  }, [arrConditions, objLabelWidth])
+
+  useEffect(() => {
+    const objFields = objFieldsRef.current
+    if (!objFields) return
+    const fnMeasure = () => {
+      if (objLayoutTransitioningRef.current) return
+      const nCollapsedBottom =
+        objFields.getBoundingClientRect().top + objFields.clientHeight
+      Array.from(objFields.children).forEach((objChild) => {
+        if (!(objChild instanceof HTMLElement)) return
+        const bHidden =
+          bExpandable &&
+          !bExpanded &&
+          objChild.getBoundingClientRect().bottom > nCollapsedBottom + 1
+        objChild.inert = bHidden
+        if (bHidden) objChild.setAttribute('aria-hidden', 'true')
+        else objChild.removeAttribute('aria-hidden')
+      })
+      if (bExpanded) return
+      if (!bExpandable) {
+        fnSetShowExpand(false)
+        return
+      }
+      fnSetShowExpand(
+        isTableSearchContentOverflowing(
+          objFields.scrollHeight,
+          objFields.clientHeight
+        )
+      )
+    }
+    const nFrame = window.requestAnimationFrame(fnMeasure)
+    const objObserver = new ResizeObserver(fnMeasure)
+    objObserver.observe(objFields)
+    return () => {
+      window.cancelAnimationFrame(nFrame)
+      objObserver.disconnect()
+    }
+  }, [
+    arrConditions,
+    bExpandable,
+    bExpanded,
+    bLayoutTransitioning,
+    strCollapsedHeight,
+  ])
+
+  const fnToggleExpanded = () => {
+    if (bExpanded) {
+      fnSetExpandedReady(false)
+      fnSetCollapsing(true)
+      return
+    }
+    const objFields = objFieldsRef.current
+    if (!objFields) return
+    fnSetExpandedHeight(
+      Math.max(
+        objFields.clientHeight + TABLE_SEARCH_LAYOUT.expandedContentPadding,
+        Math.min(
+          objFields.scrollHeight + TABLE_SEARCH_LAYOUT.expandedContentPadding,
+          objLayout?.maxExpandedHeight ?? TABLE_SEARCH_LAYOUT.maxExpandedHeight,
+          window.innerHeight - TABLE_SEARCH_LAYOUT.viewportReservedHeight
+        )
+      )
+    )
+    fnSetExpandedReady(false)
+    fnSetCollapsing(false)
+    fnSetExpanded(true)
+  }
+  const fnHandleExpandAnimationEnd = (
+    objEvent: AnimationEvent<HTMLDivElement>
+  ) => {
+    if (objEvent.target !== objEvent.currentTarget) return
+    if (bCollapsing) {
+      fnSetExpanded(false)
+      fnSetCollapsing(false)
+      return
+    }
+    if (bExpanded) fnSetExpandedReady(true)
+  }
+  const fnHandleKeyDown = (objEvent: KeyboardEvent<HTMLFormElement>) => {
+    if (
+      objEvent.key === 'Enter' &&
+      shouldSubmitTableSearchOnEnter(objEvent.nativeEvent)
+    ) {
+      objEvent.preventDefault()
+      fnOnSearch()
+    }
+  }
+
+  return (
+    <form
+      className='table-search-bar'
+      style={objSearchBarStyle}
+      onSubmit={(objEvent) => {
+        objEvent.preventDefault()
+        fnOnSearch()
+      }}
+      onKeyDown={fnHandleKeyDown}
+    >
+      <div className='table-search-bar__layout'>
+        <div
+          className='table-search-bar__fields-shell'
+          data-expanded={bExpanded || undefined}
+          data-unrestricted={!bExpandable || undefined}
+        >
+          <div
+            ref={objFieldsRef}
+            id={`${strTableKey.replace(/[^a-zA-Z0-9_-]/g, '-')}-search-fields`}
+            className='table-search-bar__fields'
+            data-expanded={bExpanded || undefined}
+            data-open={bExpandedReady || undefined}
+            data-collapsing={bCollapsing || undefined}
+            data-unrestricted={!bExpandable || undefined}
+            onAnimationEnd={fnHandleExpandAnimationEnd}
+          >
+            <TableSearchFields
+              strTableKey={strTableKey}
+              arrConditions={arrConditions}
+              objModel={objModel}
+              objRemoteOptions={objRemoteOptions}
+              objRemoteLoading={objRemoteLoading}
+              fnOnChange={fnOnChange}
+              fnOnRemoteQuery={fnOnRemoteQuery}
+            />
+          </div>
+        </div>
+
+        <div className='table-search-bar__actions'>
+          <Button
+            type='submit'
+            className='table-search-bar__form-action'
+            disabled={bLoading}
+          >
+            {bLoading ? <Loader2 className='animate-spin' /> : null}
+            {objMessages.strSearch}
+          </Button>
+          <Button
+            type='button'
+            variant='outline'
+            className='table-search-bar__form-action'
+            onClick={fnOnReset}
+          >
+            {objMessages.strReset}
+          </Button>
+          {bExpandable && (bShowExpand || bExpanded) ? (
+            <Button
+              type='button'
+              variant='link'
+              size='sm'
+              className='px-1.5'
+              aria-expanded={bExpanded}
+              aria-controls={`${strTableKey.replace(/[^a-zA-Z0-9_-]/g, '-')}-search-fields`}
+              onClick={fnToggleExpanded}
+            >
+              {bExpanded ? objMessages.strCollapse : objMessages.strExpand}
+            </Button>
+          ) : null}
+          <TableSearchConditionEditor
+            arrConditions={arrAllConditions}
+            arrHiddenConditionKeys={arrHiddenConditionKeys}
+            arrConditionOrder={arrConditionOrder}
+            fnOnChange={(objValue) => {
+              fnSetExpanded(false)
+              fnSetExpandedReady(false)
+              fnSetCollapsing(false)
+              fnOnConditionsChange(objValue)
+            }}
+          />
+        </div>
+      </div>
+    </form>
+  )
+}