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

package/template/src/components/AppTable/columns/TableColumnEditor.tsx

@@ -0,0 +1,257 @@
+import { useMemo, useState } from 'react'
+import { ArrowDown, ArrowUp, Columns3, Search } from 'lucide-react'
+import { Button } from '@/components/ui/button'
+import { Checkbox } from '@/components/ui/checkbox'
+import { Input } from '@/components/ui/input'
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from '@/components/ui/popover'
+import {
+  reorderTableColumnsByFilteredIndex,
+  type TableColumn,
+} from '@/components/AppTable/engine/columns/column'
+import type { TableRow } from '@/components/AppTable/engine/shared/types'
+import { useAppTableMessages } from '../messages'
+
+interface ITableColumnEditorProps<T extends TableRow> {
+  arrColumns: TableColumn<T>[]
+  nFrozenRows: number
+  nRowCount: number
+  fnOnColumnsChange: (arrColumns: TableColumn<T>[]) => void
+  fnOnResetColumns: () => void
+  fnOnFrozenRowsChange: (nCount: number) => void
+}
+
+const fnCloneColumns = <T extends TableRow>(arrColumns: TableColumn<T>[]) =>
+  arrColumns.map((objColumn) => ({ ...objColumn }))
+
+/** React 列设置面板；交互状态留在视图层，持久化统一交给偏好会话。 */
+export function TableColumnEditor<T extends TableRow>({
+  arrColumns,
+  nFrozenRows,
+  nRowCount,
+  fnOnColumnsChange,
+  fnOnResetColumns,
+  fnOnFrozenRowsChange,
+}: ITableColumnEditorProps<T>) {
+  const objMessages = useAppTableMessages()
+  const [bOpen, fnSetOpen] = useState(false)
+  const [strSearch, fnSetSearch] = useState('')
+  const [arrDraftColumns, fnSetDraftColumns] = useState(() =>
+    fnCloneColumns(arrColumns)
+  )
+  const arrFilteredColumns = useMemo(() => {
+    const strKeyword = strSearch.trim().toLocaleLowerCase()
+    if (!strKeyword) return arrDraftColumns
+    return arrDraftColumns.filter(
+      (objColumn) =>
+        objColumn.label.toLocaleLowerCase().includes(strKeyword) ||
+        String(objColumn.key).toLocaleLowerCase().includes(strKeyword)
+    )
+  }, [arrDraftColumns, strSearch])
+  const nVisibleColumnCount = arrDraftColumns.filter(
+    (objColumn) => !objColumn.hidden
+  ).length
+
+  const fnHandleOpenChange = (bNextOpen: boolean) => {
+    if (bNextOpen) {
+      fnSetDraftColumns(fnCloneColumns(arrColumns))
+      fnSetSearch('')
+    }
+    fnSetOpen(bNextOpen)
+  }
+  const fnSetColumnVisible = (strKey: string, bVisible: boolean) => {
+    fnSetDraftColumns((arrCurrent) =>
+      arrCurrent.map((objColumn) =>
+        String(objColumn.key) === strKey
+          ? { ...objColumn, hidden: !bVisible }
+          : objColumn
+      )
+    )
+  }
+  const fnSetFilteredVisibility = (bVisible: boolean) => {
+    const objFilteredKeys = new Set(
+      arrFilteredColumns.map((objColumn) => String(objColumn.key))
+    )
+    fnSetDraftColumns((arrCurrent) =>
+      arrCurrent.map((objColumn) =>
+        objFilteredKeys.has(String(objColumn.key))
+          ? { ...objColumn, hidden: !bVisible }
+          : objColumn
+      )
+    )
+  }
+  const fnMoveColumn = (strKey: string, nOffset: number) => {
+    const arrFilteredKeys = arrFilteredColumns.map((objColumn) =>
+      String(objColumn.key)
+    )
+    const nCurrentIndex = arrFilteredKeys.indexOf(strKey)
+    fnSetDraftColumns((arrCurrent) =>
+      reorderTableColumnsByFilteredIndex(
+        arrCurrent,
+        arrFilteredKeys,
+        nCurrentIndex,
+        nCurrentIndex + nOffset
+      )
+    )
+  }
+  const fnConfirm = () => {
+    if (!nVisibleColumnCount) return
+    fnOnColumnsChange(fnCloneColumns(arrDraftColumns))
+    fnSetOpen(false)
+  }
+  const fnReset = () => {
+    fnOnResetColumns()
+    fnSetOpen(false)
+  }
+
+  return (
+    <Popover open={bOpen} onOpenChange={fnHandleOpenChange}>
+      <PopoverTrigger asChild>
+        <Button type='button' variant='ghost' size='sm'>
+          <Columns3 />
+          {objMessages.strColumnSettings}
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent
+        align='end'
+        className='w-[min(340px,calc(100vw-24px))] p-3'
+      >
+        <div
+          className='grid gap-3'
+          aria-label={objMessages.strColumnSettingsPanel}
+        >
+          <div className='relative'>
+            <Search className='pointer-events-none absolute top-1/2 left-3 size-4 -translate-y-1/2 text-muted-foreground' />
+            <Input
+              value={strSearch}
+              className='pl-9'
+              placeholder={objMessages.strSearchColumns}
+              aria-label={objMessages.strSearchColumns}
+              onChange={(objEvent) => fnSetSearch(objEvent.target.value)}
+            />
+          </div>
+
+          <div className='flex min-h-7 items-center justify-between gap-3 text-xs text-muted-foreground'>
+            <span>
+              {objMessages.fnVisibleCount(
+                nVisibleColumnCount,
+                arrDraftColumns.length
+              )}
+            </span>
+            <div className='flex items-center'>
+              <Button
+                type='button'
+                variant='link'
+                size='xs'
+                onClick={() => fnSetFilteredVisibility(true)}
+              >
+                {objMessages.strShowAll}
+              </Button>
+              <Button
+                type='button'
+                variant='link'
+                size='xs'
+                onClick={() => fnSetFilteredVisibility(false)}
+              >
+                {objMessages.strHideAll}
+              </Button>
+            </div>
+          </div>
+
+          <div className='max-h-72 overflow-y-auto rounded-md border'>
+            {arrFilteredColumns.length ? (
+              arrFilteredColumns.map((objColumn, nIndex) => {
+                const strKey = String(objColumn.key)
+                return (
+                  <div
+                    key={strKey}
+                    className='flex min-h-9 items-center justify-between gap-2 border-b px-2 last:border-b-0'
+                  >
+                    <label className='flex min-w-0 flex-1 cursor-pointer items-center gap-2 text-sm'>
+                      <Checkbox
+                        checked={!objColumn.hidden}
+                        aria-label={objMessages.fnShowColumnAriaLabel(
+                          objColumn.label
+                        )}
+                        onCheckedChange={(bChecked) =>
+                          fnSetColumnVisible(strKey, bChecked === true)
+                        }
+                      />
+                      <span className='truncate'>{objColumn.label}</span>
+                    </label>
+                    <div className='flex shrink-0 items-center'>
+                      <Button
+                        type='button'
+                        variant='ghost'
+                        size='icon-xs'
+                        aria-label={objMessages.fnMoveColumnUpAriaLabel(
+                          objColumn.label
+                        )}
+                        disabled={nIndex === 0}
+                        onClick={() => fnMoveColumn(strKey, -1)}
+                      >
+                        <ArrowUp />
+                      </Button>
+                      <Button
+                        type='button'
+                        variant='ghost'
+                        size='icon-xs'
+                        aria-label={objMessages.fnMoveColumnDownAriaLabel(
+                          objColumn.label
+                        )}
+                        disabled={nIndex === arrFilteredColumns.length - 1}
+                        onClick={() => fnMoveColumn(strKey, 1)}
+                      >
+                        <ArrowDown />
+                      </Button>
+                    </div>
+                  </div>
+                )
+              })
+            ) : (
+              <div className='grid min-h-20 place-items-center px-3 text-sm text-muted-foreground'>
+                {objMessages.strNoMatchingColumns}
+              </div>
+            )}
+          </div>
+
+          <label className='flex items-center justify-between gap-3 border-t pt-3 text-sm'>
+            <span>{objMessages.strFreezeTopRows}</span>
+            <Input
+              type='number'
+              min={0}
+              max={nRowCount}
+              value={nFrozenRows}
+              className='w-24'
+              aria-label={objMessages.strFreezeTopRows}
+              onChange={(objEvent) =>
+                fnOnFrozenRowsChange(Number(objEvent.target.value))
+              }
+            />
+          </label>
+
+          <div className='flex items-center justify-end gap-2 border-t pt-3'>
+            {!nVisibleColumnCount ? (
+              <span className='mr-auto text-xs text-destructive'>
+                {objMessages.strKeepOneColumn}
+              </span>
+            ) : null}
+            <Button type='button' variant='outline' onClick={fnReset}>
+              {objMessages.strRestoreDefaults}
+            </Button>
+            <Button
+              type='button'
+              disabled={!nVisibleColumnCount}
+              onClick={fnConfirm}
+            >
+              {objMessages.strConfirm}
+            </Button>
+          </div>
+        </div>
+      </PopoverContent>
+    </Popover>
+  )
+}

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

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

package/template/src/components/AppTable/columns/useTableColumnPreferenceActions.ts

@@ -0,0 +1,85 @@
+import { useCallback } from 'react'
+import { type TablePreferenceUpdater } from '@/components/AppTable/engine/preference/preference'
+import { type TablePreference } from '@/components/AppTable/engine/preference/types'
+import { type TableRow } from '@/components/AppTable/engine/shared/types'
+import { buildTableNestedHeaders } from '@/components/AppTable/engine/table/layout/nestedHeaders'
+import type { ResolvedTableComponentProps, TableColumn } from '../config'
+import { useAppTableMessages } from '../messages'
+
+interface IUseTableColumnPreferenceActionsOptions<T extends TableRow> {
+  objProps: ResolvedTableComponentProps<T>
+  nRowCount: number
+  fnUpdatePreference: (
+    fnUpdater: TablePreferenceUpdater
+  ) => Promise<TablePreference>
+  fnReportError: (objError: unknown) => void
+}
+
+/** React 列设置命令；列投影仍由统一偏好会话负责，避免产生第二份列状态。 */
+export function useTableColumnPreferenceActions<T extends TableRow>({
+  objProps,
+  nRowCount,
+  fnUpdatePreference,
+  fnReportError,
+}: IUseTableColumnPreferenceActionsOptions<T>) {
+  const objMessages = useAppTableMessages()
+  const fnApplyColumnChanges = useCallback(
+    (arrColumns: TableColumn<T>[]) => {
+      try {
+        buildTableNestedHeaders({
+          columns: arrColumns.map((objColumn) => ({
+            key: String(objColumn.key),
+            label: objColumn.label,
+            visible: !objColumn.hidden,
+          })),
+          groups: objProps.headerGroups ?? [],
+          selectionLabel: objProps.selectable
+            ? objMessages.strSelectionColumn
+            : undefined,
+        })
+      } catch (objError) {
+        fnReportError(objError)
+        return
+      }
+      void fnUpdatePreference((objCurrent) => ({
+        ...objCurrent,
+        columnOrder: arrColumns.map((objColumn) => String(objColumn.key)),
+        hiddenColumns: arrColumns
+          .filter((objColumn) => objColumn.hidden)
+          .map((objColumn) => String(objColumn.key)),
+      }))
+    },
+    [fnReportError, fnUpdatePreference, objMessages, objProps]
+  )
+
+  const fnResetColumnPreference = useCallback(() => {
+    void fnUpdatePreference((objCurrent) => ({
+      ...objCurrent,
+      columnOrder: [],
+      hiddenColumns: [],
+      columnWidths: {},
+      frozenColumns: [],
+      frozenRows: 0,
+    }))
+  }, [fnUpdatePreference])
+
+  const fnSetFrozenRows = useCallback(
+    (nCount: number) => {
+      const nNormalizedCount = Math.min(
+        nRowCount,
+        Math.max(0, Math.trunc(Number(nCount) || 0))
+      )
+      void fnUpdatePreference((objCurrent) => ({
+        ...objCurrent,
+        frozenRows: nNormalizedCount,
+      }))
+    },
+    [fnUpdatePreference, nRowCount]
+  )
+
+  return {
+    fnApplyColumnChanges,
+    fnResetColumnPreference,
+    fnSetFrozenRows,
+  }
+}

package/template/src/components/AppTable/config/defaults.ts

@@ -0,0 +1,46 @@
+import type { GridSettings } from 'handsontable'
+import { fnResolveAdvancedTableLicense } from '@/components/AppTable/config/license'
+import { TABLE_COLUMN_DEFAULTS } from '@/components/AppTable/engine/columns/constants'
+import type { TableComponentDefaults } from '@/components/AppTable/engine/component/resolver'
+import { TABLE_COMPONENT_DEFAULTS } from '@/components/AppTable/engine/config/constants'
+import type { TablePaginationConfig } from '@/components/AppTable/engine/pagination/types'
+import type { TableSearchCondition } from '@/components/AppTable/engine/search/types'
+import type { TableRowSelectionConfig } from '@/components/AppTable/engine/selection/types'
+import type { TableFeedbackOptions } from '@/components/AppTable/engine/shared/feedback'
+import type { TableRow } from '@/components/AppTable/engine/shared/types'
+import type { TableExportConfig } from '@/components/AppTable/engine/summary/config/types'
+import type { TableToolbarButton } from '@/components/AppTable/engine/toolbar/types'
+
+/** 运行时默认值独立于 AppTable 组合入口，由配置解析器和测试共享。 */
+export const tableComponentDefaults: TableComponentDefaults = {
+  data: <T extends TableRow>(): T[] => [],
+  searchConditions: (): TableSearchCondition[] => [],
+  searchResetBehavior: TABLE_COMPONENT_DEFAULTS.searchResetBehavior,
+  buttons: <T extends TableRow>(): TableToolbarButton<T>[] => [],
+  autoQuery: TABLE_COMPONENT_DEFAULTS.autoQuery,
+  selectionOptions: <T extends TableRow>(): TableRowSelectionConfig<T> => ({}),
+  showIndex: TABLE_COMPONENT_DEFAULTS.showIndex,
+  defaultColumnWidth: TABLE_COLUMN_DEFAULTS.defaultWidth,
+  striped: TABLE_COMPONENT_DEFAULTS.striped,
+  highlightCurrentRow: TABLE_COMPONENT_DEFAULTS.highlightCurrentRow,
+  headerMenuTrigger: TABLE_COMPONENT_DEFAULTS.headerMenuTrigger,
+  autoFreezeStartActions: TABLE_COMPONENT_DEFAULTS.autoFreezeStartActions,
+  autoFreezeEndActions: TABLE_COMPONENT_DEFAULTS.autoFreezeEndActions,
+  summarySelected: TABLE_COMPONENT_DEFAULTS.summarySelected,
+  allowBulkEdit: TABLE_COMPONENT_DEFAULTS.allowBulkEdit,
+  keepSelection: TABLE_COMPONENT_DEFAULTS.keepSelection,
+  showToolbar: TABLE_COMPONENT_DEFAULTS.showToolbar,
+  showColumnEditor: TABLE_COMPONENT_DEFAULTS.showColumnEditor,
+  showDensityControl: TABLE_COMPONENT_DEFAULTS.showDensityControl,
+  pagination: (): TablePaginationConfig => ({}),
+  exportOptions: <T extends TableRow>(): TableExportConfig<T> => ({}),
+  feedback: (): TableFeedbackOptions => ({}),
+  loadingMask: TABLE_COMPONENT_DEFAULTS.loadingMask,
+  settings: (): GridSettings => ({}),
+  theme: TABLE_COMPONENT_DEFAULTS.theme,
+  density: TABLE_COMPONENT_DEFAULTS.density,
+  locale: TABLE_COMPONENT_DEFAULTS.locale,
+  // 默认配置不读取构建环境；商业许可证统一由 AppTable 应用边界注入。
+  licenseKey: () => fnResolveAdvancedTableLicense({}),
+  height: TABLE_COMPONENT_DEFAULTS.height,
+}

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

@@ -0,0 +1,2 @@
+export { createTableComponentPropsResolver } from './resolver'
+export type * from './types'

package/template/src/components/AppTable/config/license.ts

@@ -0,0 +1,39 @@
+interface IResolveAdvancedTableLicenseOptions {
+  /** Handsontable 许可证 key；开发环境省略时使用官方评估标识。 */
+  strKey?: string
+  /** 是否处于生产环境；为 true 时禁止使用评估许可证。 */
+  bProduction?: boolean
+}
+
+declare global {
+  interface ImportMetaEnv {
+    /** Handsontable 许可证；生产环境必须配置项目获得的商业 key。 */
+    readonly VITE_HANDSONTABLE_LICENSE_KEY?: string
+  }
+}
+
+const strHandsontableEvaluationLicense = 'non-commercial-and-evaluation'
+
+class AdvancedTableLicenseRequiredError extends Error {
+  readonly strCode = 'TABLE_HANDSONTABLE_LICENSE_REQUIRED'
+
+  constructor() {
+    super('A commercial Handsontable license key is required in production.')
+    this.name = 'AdvancedTableLicenseRequiredError'
+  }
+}
+
+/** 解析高级表格许可证，并阻止评估许可证进入生产运行时。 */
+export function fnResolveAdvancedTableLicense({
+  bProduction = false,
+  strKey,
+}: IResolveAdvancedTableLicenseOptions) {
+  const strNormalizedKey = strKey?.trim()
+  if (
+    bProduction &&
+    (!strNormalizedKey || strNormalizedKey === strHandsontableEvaluationLicense)
+  ) {
+    throw new AdvancedTableLicenseRequiredError()
+  }
+  return strNormalizedKey || strHandsontableEvaluationLicense
+}

package/template/src/components/AppTable/config/resolver.ts

@@ -0,0 +1,25 @@
+import { createTableEnginePropsResolver } from '@/components/AppTable/engine/component/resolver'
+import type { TableRow } from '@/components/AppTable/engine/shared/types'
+import { tableComponentDefaults } from './defaults'
+import type { ResolvedTableComponentProps, TableComponentProps } from './types'
+
+/** 创建 React 实例级解析器；engine 解析公共合同，适配层只追加框架面板。 */
+export const createTableComponentPropsResolver = <T extends TableRow>() => {
+  const fnResolveEngine = createTableEnginePropsResolver<T>(
+    tableComponentDefaults
+  )
+  return (
+    props: Readonly<TableComponentProps<T>>
+  ): ResolvedTableComponentProps<T> => {
+    const objEngineProps = fnResolveEngine(props)
+    const objPanels =
+      props.config.panels === false ? undefined : props.config.panels
+    return {
+      ...objEngineProps,
+      bottomPanel: props.config.panels === false ? false : objPanels?.bottom,
+      rightPanel: props.config.panels === false ? false : objPanels?.right,
+      rowDetailPanel:
+        props.config.panels === false ? false : objPanels?.rowDetail,
+    }
+  }
+}