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

package/template/src/components/AppTable/cell/customCell/cellLayer.ts

@@ -0,0 +1,358 @@
+import {
+  TABLE_DEFAULT_MAX_COLLAPSE_TAGS,
+  TABLE_OPTION_DEBOUNCE_MS,
+  TABLE_TOOLTIP_OPEN_DELAY_MS,
+} from '@/components/AppTable/engine/cell/constants'
+import type { TableCellLayerAdapter } from '@/components/AppTable/engine/cell/customCell/types'
+import {
+  createTableOptionCoordinator,
+  normalizeTableOptions,
+  type TableOptionLoadResult,
+} from '@/components/AppTable/engine/cell/options'
+import type {
+  TableAction,
+  TableCellContext,
+} from '@/components/AppTable/engine/cell/types'
+import { TABLE_ENGINE_MESSAGES_ZH_CN } from '@/components/AppTable/engine/shared/messages'
+import type {
+  TableOption,
+  TableRow,
+} from '@/components/AppTable/engine/shared/types'
+import type {
+  ITableCellEditorState,
+  ITableCellLayerSession,
+  ITableCellLayerSnapshot,
+} from './types'
+
+interface ICreateTableCellLayerOptions {
+  tableKey: string
+  onActionError?: (objError: unknown) => void
+  onOptionLoadError?: (
+    objError: unknown,
+    objContext: {
+      tableKey: string
+      columnKey: string
+      query: string
+    }
+  ) => void
+}
+
+interface IActiveSelect {
+  columnKey: string
+  remote: boolean
+  load: (
+    strQuery: string,
+    objSignal: AbortSignal
+  ) => Promise<TableOptionLoadResult>
+  onOptionsLoaded?: (arrOptions: readonly TableOption[]) => void
+}
+
+const objInitialSnapshot: ITableCellLayerSnapshot = {
+  editor: {
+    visible: false,
+    type: 'select',
+    value: undefined,
+    componentProps: {},
+    options: [],
+    multiple: false,
+    clearable: true,
+    multipleLimit: 0,
+    searchable: true,
+    collapseTags: false,
+    maxCollapseTags: TABLE_DEFAULT_MAX_COLLAPSE_TAGS,
+    loading: false,
+    remote: false,
+    error: null,
+    debounceMs: TABLE_OPTION_DEBOUNCE_MS,
+    placeholder: TABLE_ENGINE_MESSAGES_ZH_CN.strSelectPlaceholder,
+    rect: null,
+    nSessionId: 0,
+  },
+  menu: {
+    visible: false,
+    anchor: null,
+    trigger: null,
+    actions: [],
+  },
+  tooltip: {
+    visible: false,
+    content: '',
+    anchor: null,
+  },
+}
+
+/** 每张表一个 React 浮层会话；engine 只持有 adapter，UI 订阅不可变快照。 */
+export function createTableCellLayer({
+  tableKey: strTableKey,
+  onActionError: fnOnActionError,
+  onOptionLoadError: fnOnOptionLoadError,
+}: ICreateTableCellLayerOptions): ITableCellLayerSession {
+  let objSnapshot = objInitialSnapshot
+  let nSessionId = 0
+  let bDestroyed = false
+  let objActiveSelect: IActiveSelect | null = null
+  let objSelectController: AbortController | null = null
+  let objTooltipTimer: ReturnType<typeof setTimeout> | undefined
+  const setListeners = new Set<() => void>()
+  const objOptionCoordinator = createTableOptionCoordinator({
+    tableKey: strTableKey,
+  })
+
+  const fnPublish = (objNextSnapshot: ITableCellLayerSnapshot) => {
+    objSnapshot = objNextSnapshot
+    setListeners.forEach((fnListener) => fnListener())
+  }
+
+  const fnUpdateEditor = (objPatch: Partial<ITableCellEditorState>) => {
+    fnPublish({
+      ...objSnapshot,
+      editor: { ...objSnapshot.editor, ...objPatch },
+    })
+  }
+
+  const fnLoadSelectOptions = async (
+    strQuery: string,
+    nExpectedSession: number
+  ) => {
+    const objCurrent = objActiveSelect
+    if (!objCurrent || bDestroyed || nSessionId !== nExpectedSession) return
+    objSelectController?.abort('superseded')
+    const objController = new AbortController()
+    objSelectController = objController
+    fnUpdateEditor({ loading: true, error: null })
+    try {
+      const objResult = await objCurrent.load(strQuery, objController.signal)
+      if (
+        !bDestroyed &&
+        !objController.signal.aborted &&
+        objSelectController === objController &&
+        nSessionId === nExpectedSession
+      ) {
+        fnUpdateEditor({ options: objResult.options })
+        objCurrent.onOptionsLoaded?.(objResult.options)
+      }
+    } catch (objError) {
+      if (
+        !objController.signal.aborted &&
+        !bDestroyed &&
+        nSessionId === nExpectedSession
+      ) {
+        fnUpdateEditor({
+          error:
+            objError instanceof Error ? objError.message : String(objError),
+        })
+        fnOnOptionLoadError?.(objError, {
+          tableKey: strTableKey,
+          columnKey: objCurrent.columnKey,
+          query: strQuery,
+        })
+      }
+    } finally {
+      if (objSelectController === objController) objSelectController = null
+      if (
+        !bDestroyed &&
+        objSelectController === null &&
+        nSessionId === nExpectedSession
+      ) {
+        fnUpdateEditor({ loading: false })
+      }
+    }
+  }
+
+  const fnClose: TableCellLayerAdapter['close'] = (objOptions = {}) => {
+    const fnCancel = objSnapshot.editor.visible
+      ? objSnapshot.editor.cancel
+      : undefined
+    nSessionId += 1
+    objSelectController?.abort('closed')
+    objSelectController = null
+    objActiveSelect = null
+    clearTimeout(objTooltipTimer)
+    objTooltipTimer = undefined
+    fnPublish({
+      editor: {
+        ...objSnapshot.editor,
+        visible: false,
+        loading: false,
+        error: null,
+        componentProps: {},
+        preview: undefined,
+        commit: undefined,
+        cancel: undefined,
+        nSessionId,
+      },
+      menu: {
+        visible: false,
+        anchor: null,
+        trigger: null,
+        actions: [],
+      },
+      tooltip: {
+        visible: false,
+        content: '',
+        anchor: null,
+      },
+    })
+    if (objOptions.cancel !== false) {
+      fnCancel?.({ restoreFocus: objOptions.restoreFocus })
+    }
+  }
+
+  const objAdapter: TableCellLayerAdapter = {
+    async openSelect(objOptions) {
+      if (bDestroyed) return
+      fnClose()
+      const nCurrentSession = nSessionId
+      const objSource = objOptions.source ?? []
+      const arrOptions = Array.isArray(objSource)
+        ? normalizeTableOptions(objSource)
+        : []
+      objActiveSelect = {
+        columnKey: objOptions.columnKey,
+        remote: typeof objSource === 'function',
+        load: (strQuery, objSignal) =>
+          objOptionCoordinator.load({
+            columnKey: objOptions.columnKey,
+            row: objOptions.row,
+            query: strQuery,
+            source: objSource,
+            cache: objOptions.cache,
+            signal: objSignal,
+          }),
+        onOptionsLoaded: objOptions.onOptionsLoaded,
+      }
+      fnPublish({
+        ...objSnapshot,
+        editor: {
+          visible: true,
+          type: 'select',
+          value: objOptions.value,
+          componentProps: { ...(objOptions.componentProps ?? {}) },
+          options: arrOptions,
+          multiple: objOptions.multiple ?? false,
+          clearable: objOptions.clearable ?? true,
+          multipleLimit: objOptions.multipleLimit ?? 0,
+          searchable: objOptions.searchable ?? true,
+          collapseTags: objOptions.collapseTags ?? false,
+          maxCollapseTags:
+            objOptions.maxCollapseTags ?? TABLE_DEFAULT_MAX_COLLAPSE_TAGS,
+          loading: typeof objSource === 'function',
+          remote: typeof objSource === 'function',
+          error: null,
+          debounceMs: objOptions.debounceMs ?? TABLE_OPTION_DEBOUNCE_MS,
+          placeholder:
+            objOptions.placeholder ??
+            TABLE_ENGINE_MESSAGES_ZH_CN.strSelectPlaceholder,
+          rect: objOptions.rect,
+          nSessionId: nCurrentSession,
+          preview: objOptions.preview,
+          commit: objOptions.commit,
+          cancel: objOptions.cancel,
+        },
+      })
+      if (Array.isArray(objSource)) {
+        objOptionCoordinator.remember(objOptions.columnKey, arrOptions)
+      } else {
+        await fnLoadSelectOptions('', nCurrentSession)
+      }
+    },
+    searchSelect(strQuery) {
+      if (!objActiveSelect?.remote) return
+      return fnLoadSelectOptions(strQuery, nSessionId)
+    },
+    getOptionLabel(strColumnKey, objValue) {
+      return objOptionCoordinator.getOption(strColumnKey, objValue)?.label
+    },
+    clearOptionCache(strColumnKey) {
+      objOptionCoordinator.clear(strColumnKey)
+    },
+    openDate(objOptions) {
+      if (bDestroyed) return
+      fnClose()
+      fnPublish({
+        ...objSnapshot,
+        editor: {
+          ...objSnapshot.editor,
+          visible: true,
+          type: objOptions.type ?? 'date',
+          value: objOptions.value,
+          componentProps: { ...(objOptions.componentProps ?? {}) },
+          options: [],
+          multiple: false,
+          clearable: true,
+          loading: false,
+          remote: false,
+          error: null,
+          rect: objOptions.rect,
+          nSessionId,
+          commit: objOptions.commit,
+          cancel: objOptions.cancel,
+        },
+      })
+    },
+    openActionMenu<T extends TableRow>(objOptions: {
+      anchor: HTMLElement
+      actions: TableAction<T>[]
+      context: TableCellContext<T>
+    }) {
+      if (bDestroyed) return
+      fnClose()
+      const objRect = objOptions.anchor.getBoundingClientRect()
+      fnPublish({
+        ...objSnapshot,
+        menu: {
+          visible: true,
+          anchor: { getBoundingClientRect: () => objRect },
+          trigger: objOptions.anchor,
+          actions: objOptions.actions as unknown as readonly TableAction[],
+          context: objOptions.context as unknown as TableCellContext,
+        },
+      })
+    },
+    reportActionError(objError) {
+      fnOnActionError?.(objError)
+    },
+    showTooltip(strContent, objAnchor) {
+      clearTimeout(objTooltipTimer)
+      objTooltipTimer = setTimeout(() => {
+        objTooltipTimer = undefined
+        if (bDestroyed) return
+        fnPublish({
+          ...objSnapshot,
+          tooltip: {
+            visible: true,
+            content: strContent,
+            anchor: objAnchor,
+          },
+        })
+      }, TABLE_TOOLTIP_OPEN_DELAY_MS)
+    },
+    hideTooltip() {
+      clearTimeout(objTooltipTimer)
+      objTooltipTimer = undefined
+      fnPublish({
+        ...objSnapshot,
+        tooltip: { visible: false, content: '', anchor: null },
+      })
+    },
+    close: fnClose,
+    destroy() {
+      bDestroyed = true
+      fnClose()
+      objOptionCoordinator.clear()
+      setListeners.clear()
+    },
+  }
+
+  return {
+    adapter: objAdapter,
+    getSnapshot: () => objSnapshot,
+    subscribe(fnListener) {
+      setListeners.add(fnListener)
+      return () => setListeners.delete(fnListener)
+    },
+    setEditorValue(objValue) {
+      fnUpdateEditor({ value: objValue })
+    },
+  }
+}

package/template/src/components/AppTable/cell/customCell/componentProps.ts

@@ -0,0 +1,30 @@
+import type { InputHTMLAttributes } from 'react'
+import type { TableCellComponentProps } from '@/components/AppTable/engine/cell/customCell/types'
+
+const setControlledProps = new Set([
+  'key',
+  'ref',
+  'value',
+  'defaultValue',
+  'checked',
+  'defaultChecked',
+  'type',
+  'multiple',
+  'onChange',
+  'onInput',
+  'onBlur',
+  'onFocus',
+  'onClick',
+  'onKeyDown',
+])
+
+/** 移除 Handsontable 编辑事务保留项，其余 React input props 保持原值。 */
+export function resolveTableCellComponentBindings(
+  objProps: TableCellComponentProps
+): InputHTMLAttributes<HTMLInputElement> {
+  return Object.fromEntries(
+    Object.entries(objProps).filter(
+      ([strKey]) => !setControlledProps.has(strKey)
+    )
+  ) as InputHTMLAttributes<HTMLInputElement>
+}

package/template/src/components/AppTable/cell/customCell/date/TemporalPickerEditor.tsx

@@ -0,0 +1,54 @@
+import { useEffect, useRef } from 'react'
+import { Input } from '@/components/ui/input'
+import { resolveTableCellComponentBindings } from '../componentProps'
+import type { ITableCellEditorState, ITableCellLayerSession } from '../types'
+
+interface ITemporalPickerEditorProps {
+  objLayer: ITableCellLayerSession
+  objEditor: ITableCellEditorState
+}
+
+function fnToInputValue(objEditor: ITableCellEditorState) {
+  const strValue = String(objEditor.value ?? '')
+  return objEditor.type === 'datetime' ? strValue.replace(' ', 'T') : strValue
+}
+
+function fnToCommittedValue(strValue: string, strType: string) {
+  if (strType !== 'datetime' || !strValue) return strValue
+  const strNormalized = strValue.replace('T', ' ')
+  return strNormalized.length === 16 ? `${strNormalized}:00` : strNormalized
+}
+
+export function TemporalPickerEditor({
+  objLayer,
+  objEditor,
+}: ITemporalPickerEditorProps) {
+  const objInputRef = useRef<HTMLInputElement>(null)
+  const objComponentBindings = resolveTableCellComponentBindings(
+    objEditor.componentProps
+  )
+
+  useEffect(() => {
+    window.requestAnimationFrame(() => {
+      objInputRef.current?.focus()
+      objInputRef.current?.showPicker?.()
+    })
+  }, [objEditor.nSessionId])
+
+  return (
+    <Input
+      {...objComponentBindings}
+      ref={objInputRef}
+      className='table-cell-layer__temporal-picker'
+      type={objEditor.type === 'datetime' ? 'datetime-local' : objEditor.type}
+      step={objEditor.type === 'time' ? 1 : objComponentBindings.step}
+      defaultValue={fnToInputValue(objEditor)}
+      onChange={(objEvent) => {
+        objEditor.commit?.(
+          fnToCommittedValue(objEvent.currentTarget.value, objEditor.type)
+        )
+        objLayer.adapter.close({ cancel: false, restoreFocus: true })
+      }}
+    />
+  )
+}

package/template/src/components/AppTable/cell/customCell/index.ts

@@ -0,0 +1,2 @@
+export { createTableCellLayer } from './cellLayer'
+export { TableCellLayer } from './TableCellLayer'

package/template/src/components/AppTable/cell/customCell/select/SelectCellEditor.tsx

@@ -0,0 +1,225 @@
+import { useEffect, useMemo, useRef, useState } from 'react'
+import { Check, Loader2, X } from 'lucide-react'
+import { cn } from '@/lib/utils'
+import { Button } from '@/components/ui/button'
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from '@/components/ui/command'
+import type { TableOption } from '@/components/AppTable/engine/shared/types'
+import { useAppTableMessages } from '../../../messages'
+import { resolveTableCellComponentBindings } from '../componentProps'
+import type { ITableCellEditorState, ITableCellLayerSession } from '../types'
+
+interface ISelectCellEditorProps {
+  objLayer: ITableCellLayerSession
+  objEditor: ITableCellEditorState
+}
+
+function fnResolveSelectedOptions(
+  arrOptions: readonly TableOption[],
+  objValue: unknown
+) {
+  const objValues = new Set(Array.isArray(objValue) ? objValue : [objValue])
+  return arrOptions.filter((objOption) => objValues.has(objOption.value))
+}
+
+export function SelectCellEditor({
+  objLayer,
+  objEditor,
+}: ISelectCellEditorProps) {
+  const objMessages = useAppTableMessages()
+  const objSearchRef = useRef<HTMLInputElement>(null)
+  const objSearchTimerRef = useRef<number | undefined>(undefined)
+  const [objValue, fnSetValue] = useState(objEditor.value)
+  const [strQuery, fnSetQuery] = useState('')
+  const arrSelectedOptions = useMemo(
+    () => fnResolveSelectedOptions(objEditor.options, objValue),
+    [objEditor.options, objValue]
+  )
+  const arrVisibleOptions = useMemo(() => {
+    if (objEditor.remote || !strQuery.trim()) return objEditor.options
+    const strNormalizedQuery = strQuery.trim().toLocaleLowerCase()
+    return objEditor.options.filter((objOption) =>
+      objOption.label.toLocaleLowerCase().includes(strNormalizedQuery)
+    )
+  }, [objEditor.options, objEditor.remote, strQuery])
+  const objComponentBindings = resolveTableCellComponentBindings(
+    objEditor.componentProps
+  )
+
+  useEffect(() => {
+    window.requestAnimationFrame(() => objSearchRef.current?.focus())
+  }, [])
+
+  useEffect(() => () => window.clearTimeout(objSearchTimerRef.current), [])
+
+  const fnSelectOption = (objOption: TableOption) => {
+    if (objOption.disabled) return
+    if (!objEditor.multiple) {
+      objEditor.commit?.(objOption.value, objOption)
+      objLayer.adapter.close({ cancel: false, restoreFocus: true })
+      return
+    }
+    const arrCurrentValues = Array.isArray(objValue) ? objValue : []
+    const bSelected = arrCurrentValues.some((objCurrentValue) =>
+      Object.is(objCurrentValue, objOption.value)
+    )
+    if (
+      !bSelected &&
+      objEditor.multipleLimit > 0 &&
+      arrCurrentValues.length >= objEditor.multipleLimit
+    ) {
+      return
+    }
+    const arrNextValues = bSelected
+      ? arrCurrentValues.filter(
+          (objCurrentValue) => !Object.is(objCurrentValue, objOption.value)
+        )
+      : [...arrCurrentValues, objOption.value]
+    fnSetValue(arrNextValues)
+    objLayer.setEditorValue(arrNextValues)
+    objEditor.preview?.(
+      arrNextValues,
+      fnResolveSelectedOptions(objEditor.options, arrNextValues)
+    )
+  }
+
+  const fnCommitMultiple = () => {
+    objEditor.commit?.(
+      objValue,
+      fnResolveSelectedOptions(objEditor.options, objValue)
+    )
+    objLayer.adapter.close({ cancel: false, restoreFocus: true })
+  }
+
+  const fnClear = () => {
+    if (objEditor.multiple) {
+      const arrNextValues: unknown[] = []
+      fnSetValue(arrNextValues)
+      objLayer.setEditorValue(arrNextValues)
+      objEditor.preview?.(arrNextValues, [])
+      return
+    }
+    objEditor.commit?.(undefined)
+    objLayer.adapter.close({ cancel: false, restoreFocus: true })
+  }
+
+  return (
+    <div
+      className={cn('table-cell-layer__select', objComponentBindings.className)}
+      style={objComponentBindings.style}
+    >
+      <div className='flex h-full min-h-7 w-full items-center justify-between overflow-hidden bg-background px-2 text-[13px] text-foreground'>
+        <span className='truncate'>
+          {arrSelectedOptions.length
+            ? objEditor.multiple && objEditor.collapseTags
+              ? `${arrSelectedOptions
+                  .slice(0, objEditor.maxCollapseTags)
+                  .map((objOption) => objOption.label)
+                  .join(
+                    '、'
+                  )}${arrSelectedOptions.length > objEditor.maxCollapseTags ? ` +${arrSelectedOptions.length - objEditor.maxCollapseTags}` : ''}`
+              : arrSelectedOptions
+                  .map((objOption) => objOption.label)
+                  .join('、')
+            : objEditor.placeholder}
+        </span>
+        {objEditor.clearable && arrSelectedOptions.length ? (
+          <Button
+            type='button'
+            variant='ghost'
+            size='icon-xs'
+            className='ml-1 shrink-0 text-muted-foreground'
+            aria-label={objMessages.strClearCellSelectionAriaLabel}
+            onClick={fnClear}
+          >
+            <X />
+          </Button>
+        ) : null}
+      </div>
+
+      <Command
+        shouldFilter={false}
+        className='absolute top-[calc(100%+4px)] left-0 z-10 min-w-[max(100%,220px)] border shadow-md'
+      >
+        {objEditor.searchable ? (
+          <div className='relative'>
+            <CommandInput
+              {...objComponentBindings}
+              ref={objSearchRef}
+              className='pr-9'
+              value={strQuery}
+              placeholder={objMessages.strSearchOptions}
+              onValueChange={(strNextQuery) => {
+                fnSetQuery(strNextQuery)
+                if (!objEditor.remote) return
+                window.clearTimeout(objSearchTimerRef.current)
+                objSearchTimerRef.current = window.setTimeout(
+                  () => void objLayer.adapter.searchSelect(strNextQuery),
+                  objEditor.debounceMs
+                )
+              }}
+            />
+            {objEditor.loading ? (
+              <Loader2 className='absolute top-1/2 right-3 size-4 -translate-y-1/2 animate-spin text-muted-foreground' />
+            ) : null}
+          </div>
+        ) : null}
+
+        <CommandList>
+          <CommandEmpty>
+            {objEditor.loading
+              ? objMessages.strLoadingOptions
+              : (objEditor.error ?? objMessages.strNoOptions)}
+          </CommandEmpty>
+          <CommandGroup>
+            {arrVisibleOptions.map((objOption, nOptionIndex) => {
+              const bSelected = arrSelectedOptions.some((objSelected) =>
+                Object.is(objSelected.value, objOption.value)
+              )
+              return (
+                <CommandItem
+                  key={`${String(objOption.value)}-${nOptionIndex}`}
+                  value={`${nOptionIndex}-${objOption.label}`}
+                  disabled={objOption.disabled}
+                  className={cn(bSelected && 'bg-accent/70')}
+                  onSelect={() => fnSelectOption(objOption)}
+                >
+                  <span>{objOption.label}</span>
+                  <Check
+                    aria-hidden='true'
+                    className={cn(
+                      'ml-auto',
+                      bSelected ? 'opacity-100' : 'opacity-0'
+                    )}
+                  />
+                </CommandItem>
+              )
+            })}
+          </CommandGroup>
+        </CommandList>
+
+        {objEditor.multiple ? (
+          <div className='flex justify-end gap-2 border-t p-2'>
+            <Button
+              type='button'
+              size='sm'
+              variant='outline'
+              onClick={() => objLayer.adapter.close({ restoreFocus: true })}
+            >
+              {objMessages.strCancel}
+            </Button>
+            <Button type='button' size='sm' onClick={fnCommitMultiple}>
+              {objMessages.strConfirm}
+            </Button>
+          </div>
+        ) : null}
+      </Command>
+    </div>
+  )
+}

package/template/src/components/AppTable/cell/customCell/tableCellLayer.css

@@ -0,0 +1,20 @@
+.table-cell-layer__editor {
+  position: fixed;
+  z-index: var(--z-index-table-cell-layer);
+  box-sizing: border-box;
+  min-width: 0;
+}
+
+.table-cell-layer__select {
+  position: relative;
+  width: 100%;
+  height: 100%;
+}
+
+.table-cell-layer__temporal-picker {
+  width: 100%;
+  height: 100%;
+  min-height: 0;
+  border-radius: 0;
+  box-shadow: none;
+}