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

package/template/tests/unit/components/AppTable.test.tsx

@@ -0,0 +1,129 @@
+import { useState } from 'react'
+import { LocaleProvider } from '@/locale'
+import '@/styles/index.css'
+import { expect, it } from 'vitest'
+import { render } from 'vitest-browser-react'
+import { page } from 'vitest/browser'
+import { AppTable, type TableConfiguration } from '@/components/AppTable'
+
+interface IFixtureRow {
+  nId: number
+  strName: string
+}
+
+interface ILocalizedFixtureRow {
+  nId: number
+  nCreatedAt: number
+}
+
+const objConfig = {
+  table: {
+    data: [{ nId: 1, strName: '脚手架公共表格' }],
+    height: 180,
+    columns: [
+      { key: 'nId', label: '编号', readOnly: true },
+      { key: 'strName', label: '名称', readOnly: true },
+    ],
+  },
+  search: false,
+  query: false,
+  toolbar: false,
+  pagination: false,
+  editing: { rowKey: 'nId' },
+} satisfies TableConfiguration<IFixtureRow>
+
+it('renders a consumer table through the public AppTable boundary', async () => {
+  await render(
+    <AppTable tableKey='public-app-table-fixture' config={objConfig} />
+  )
+
+  await expect.element(page.getByText('脚手架公共表格')).toBeVisible()
+  await expect.element(page.getByText('名称').last()).toBeVisible()
+})
+
+it('localizes built-in table controls and preserves per-table overrides', async () => {
+  await render(
+    <LocaleProvider strLocale='en-US' strTimeZone='UTC'>
+      <AppTable
+        tableKey='localized-app-table-fixture'
+        messages={{
+          strSearch: 'Find records',
+          strSelectCurrentPage: 'Select visible records',
+        }}
+        config={{
+          ...objConfig,
+          selection: {},
+          search: {
+            conditions: [{ key: 'strName', label: 'Name', type: 'input' }],
+          },
+          toolbar: {},
+          pagination: {},
+        }}
+      />
+    </LocaleProvider>
+  )
+
+  await expect
+    .element(page.getByRole('button', { name: 'Find records' }))
+    .toBeVisible()
+  await expect
+    .element(page.getByRole('button', { name: 'Reset' }))
+    .toBeVisible()
+  await expect
+    .element(page.getByRole('button', { name: 'Column settings' }))
+    .toBeVisible()
+  await expect.element(page.getByText('1 rows')).toBeVisible()
+  await expect
+    .element(
+      page.getByRole('checkbox', { name: 'Select visible records' }).first()
+    )
+    .toBeVisible()
+  await expect
+    .element(page.getByRole('checkbox', { name: 'Select row 1' }).first())
+    .toBeVisible()
+})
+
+it('recreates cell formatters when LocaleProvider changes', async () => {
+  function LocalizedTableFixture() {
+    const [strLocale, fnSetLocale] = useState<'en-US' | 'zh-CN'>('en-US')
+
+    return (
+      <LocaleProvider strLocale={strLocale} strTimeZone='UTC'>
+        <button type='button' onClick={() => fnSetLocale('zh-CN')}>
+          Switch locale
+        </button>
+        <AppTable<ILocalizedFixtureRow>
+          tableKey='reactive-locale-table-fixture'
+          config={{
+            table: {
+              data: [{ nId: 1, nCreatedAt: Date.UTC(2025, 0, 2, 12) }],
+              height: 180,
+              columns: [
+                {
+                  key: 'nCreatedAt',
+                  label: 'Created at',
+                  readOnly: true,
+                  format: {
+                    type: 'date',
+                    options: { dateStyle: 'long' },
+                  },
+                },
+              ],
+            },
+            search: false,
+            query: false,
+            toolbar: false,
+            pagination: false,
+            editing: { rowKey: 'nId' },
+          }}
+        />
+      </LocaleProvider>
+    )
+  }
+
+  await render(<LocalizedTableFixture />)
+
+  await expect.element(page.getByText('January 2, 2025')).toBeVisible()
+  await page.getByRole('button', { name: 'Switch locale' }).click()
+  await expect.element(page.getByText('2025年1月2日')).toBeVisible()
+})

package/template/tests/unit/components/AppTableLayoutTransition.test.ts

@@ -0,0 +1,118 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { TableGridHost } from '@/components/AppTable/engine/table/controller/tableGridHost'
+
+const { fnCreateHandsontable } = vi.hoisted(() => ({
+  fnCreateHandsontable: vi.fn(),
+}))
+
+vi.mock(
+  '@/components/AppTable/engine/table/grid',
+  async (fnImportOriginal) => ({
+    ...(await fnImportOriginal<
+      typeof import('@/components/AppTable/engine/table/grid')
+    >()),
+    createHandsontable: fnCreateHandsontable,
+  })
+)
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  fnCreateHandsontable.mockReset()
+})
+
+function fnCreateLayoutFixture(strTableKey: string) {
+  let nNextFrame = 0
+  const objFrames = new Map<number, FrameRequestCallback>()
+  const objHooks = new Map<string, () => unknown>()
+  const fnRefresh = vi.fn()
+  const fnRender = vi.fn()
+  const fnLayout = vi.fn()
+  const fnFlush = () => {
+    const arrFrames = [...objFrames.values()]
+    objFrames.clear()
+    arrFrames.forEach((fnFrame) => fnFrame(0))
+  }
+  vi.stubGlobal('requestAnimationFrame', (fnFrame: FrameRequestCallback) => {
+    const nId = ++nNextFrame
+    objFrames.set(nId, fnFrame)
+    return nId
+  })
+  vi.stubGlobal('cancelAnimationFrame', (nId: number) => {
+    objFrames.delete(nId)
+  })
+  fnCreateHandsontable.mockReturnValue({
+    isDestroyed: false,
+    rootElement: { getBoundingClientRect: () => ({ width: 960, height: 480 }) },
+    rootWrapperElement: { isConnected: true },
+    addHook: (strName: string, fnHook: () => unknown) => {
+      objHooks.set(strName, fnHook)
+    },
+    refreshDimensions: fnRefresh,
+    render: fnRender,
+    destroy: vi.fn(),
+  })
+  const objHost = new TableGridHost({
+    tableKey: strTableKey,
+    getRows: () => [],
+    getDataRevision: () => 0,
+  })
+  objHost.mount(document.createElement('div'), {})
+  objHost.subscribeLayout(fnLayout)
+  return {
+    objHost,
+    objHooks,
+    objFrames,
+    fnRefresh,
+    fnRender,
+    fnLayout,
+    fnFlush,
+  }
+}
+
+describe('AppTable layout transition settlement', () => {
+  it('blocks intermediate refreshes and renders only after final dimensions are committed', () => {
+    const { objHost, objHooks, fnRefresh, fnRender, fnLayout, fnFlush } =
+      fnCreateLayoutFixture('upgrade-settle-order')
+    try {
+      objHost.setLayoutTransitioning(true)
+      const fnBeforeRefresh = objHooks.get('beforeRefreshDimensions')!
+      expect(fnBeforeRefresh()).toBe(false)
+      objHost.refreshDimensions()
+      expect(fnRefresh).not.toHaveBeenCalled()
+      objHost.setLayoutTransitioning(false)
+      fnFlush()
+      expect(fnRefresh).not.toHaveBeenCalled()
+      fnFlush()
+      expect(fnRefresh).toHaveBeenCalledOnce()
+      expect(fnRender).not.toHaveBeenCalled()
+      expect(fnBeforeRefresh()).toBe(false)
+      fnFlush()
+      expect(fnRender).toHaveBeenCalledOnce()
+      expect(fnLayout).toHaveBeenCalledOnce()
+      expect(fnBeforeRefresh()).toBeUndefined()
+    } finally {
+      objHost.destroy()
+    }
+  })
+
+  it('cancels settlement when animation restarts or the host is disposed', () => {
+    const { objHost, objFrames, fnRefresh, fnRender, fnFlush } =
+      fnCreateLayoutFixture('upgrade-settle-cancel')
+    try {
+      objHost.setLayoutTransitioning(true)
+      objHost.setLayoutTransitioning(false)
+      fnFlush()
+      objHost.setLayoutTransitioning(true)
+      fnFlush()
+      expect(fnRefresh).not.toHaveBeenCalled()
+      expect(fnRender).not.toHaveBeenCalled()
+      objHost.setLayoutTransitioning(false)
+      expect(objFrames.size).toBe(1)
+    } finally {
+      objHost.destroy()
+    }
+    expect(objFrames.size).toBe(0)
+    fnFlush()
+    expect(fnRefresh).not.toHaveBeenCalled()
+  })
+})

package/template/tests/unit/components/AppTableLocalization.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest'
+import { parseTableTemporalInput } from '@/components/AppTable/engine/cell/customCell/date/renderer'
+import { parseTableFormulaInput } from '@/components/AppTable/engine/cell/formula'
+import { validateTableMultiSelectValue } from '@/components/AppTable/engine/cell/multiSelect'
+import { validateTableSelectValue } from '@/components/AppTable/engine/cell/options'
+import { createTableChangeTracker } from '@/components/AppTable/engine/table/editing/changeSet'
+import { objAppTableMessages } from '@/components/AppTable/messages'
+
+interface ILocalizedRow {
+  nId: number
+  strName: string
+}
+
+const objEnglishMessages = objAppTableMessages['en-US']
+
+describe('AppTable localization contracts', () => {
+  it('uses the supplied engine messages for parsing and option validation', () => {
+    expect(() =>
+      parseTableFormulaInput('=1/0', {}, objEnglishMessages)
+    ).toThrow('Formula cannot divide by zero')
+    expect(() =>
+      parseTableTemporalInput('2025-02-30', 'date', objEnglishMessages)
+    ).toThrow('Enter an existing date')
+    expect(
+      validateTableSelectValue(
+        'missing',
+        [{ label: 'Active', value: 'active' }],
+        {},
+        objEnglishMessages
+      )
+    ).toBe('The selected value is not in the available options')
+    expect(
+      validateTableMultiSelectValue(
+        ['one', 'two'],
+        { maxSelections: 1 },
+        objEnglishMessages
+      )
+    ).toBe('Select at most 1 options')
+  })
+
+  it('localizes missing server results during save settlement', () => {
+    const objRow: ILocalizedRow = { nId: 1, strName: 'Before' }
+    const objTracker = createTableChangeTracker<ILocalizedRow>({
+      rowKey: 'nId',
+      messages: objEnglishMessages,
+    })
+    objTracker.reset([objRow])
+    objRow.strName = 'After'
+    objTracker.trackCell(objRow, 'strName', 'Before', 'After')
+    const objSubmission = objTracker.createSubmission()
+
+    objTracker.applyCommitResult([objRow], { updates: [] }, objSubmission)
+
+    expect(objTracker.getCellError(1, 'strName')).toBe(
+      'The server did not return a result for this updated row'
+    )
+  })
+})

package/template/tests/unit/components/AppTableSensitiveData.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest'
+import { fnCreateSensitiveDataTableColumn } from '@/components/AppTable'
+import { buildTableExportColumns } from '@/components/AppTable/engine/summary/config/export'
+
+interface ISensitiveRow {
+  strId: string
+  strPhone: string
+}
+
+describe('AppTable sensitive data column', () => {
+  it('fixes sensitive columns as read-only and blocks native table copying', () => {
+    const objColumn = fnCreateSensitiveDataTableColumn<ISensitiveRow, string>({
+      fnResolveSensitiveDataProps: ({ value: strPhone }) => ({
+        objMaskingPolicy: { strPreset: 'phone' },
+        objValue: { strState: 'available', strValue: strPhone },
+      }),
+      objColumn: {
+        key: 'strPhone',
+        label: '手机号',
+      },
+    })
+
+    expect(objColumn.copyable).toBe(false)
+    expect(objColumn.exportable).toBe(false)
+    expect(objColumn.readOnly).toBe(true)
+    expect(objColumn.cellComponent).toBeTypeOf('function')
+    expect(
+      buildTableExportColumns(
+        [objColumn],
+        { columnWidths: {} },
+        (objValue) => objValue
+      )
+    ).toEqual([])
+  })
+})

package/template/tests/unit/components/AppTableUpgrade.test.tsx

@@ -0,0 +1,179 @@
+import { createRef, StrictMode } from 'react'
+import { LocaleProvider } from '@/locale'
+import '@/styles/index.css'
+import { describe, expect, it, vi } from 'vitest'
+import { render } from 'vitest-browser-react'
+import { page } from 'vitest/browser'
+import {
+  AppTable,
+  type TableConfiguration,
+  type TableHeight,
+} from '@/components/AppTable'
+import type { TableCellRendererProps } from '@/components/AppTable/config'
+import { createMemoryPreferenceStore } from '@/components/AppTable/engine/preference/preference'
+import type { TableQueryResult } from '@/components/AppTable/engine/search/types'
+import type { TableController } from '@/components/AppTable/engine/table/controller/TableController'
+import { TableComponent } from '@/components/AppTable/table'
+
+interface IUpgradeRow {
+  nId: number
+  strName: string
+}
+
+function NameCell({ row: objRow }: TableCellRendererProps<IUpgradeRow>) {
+  return <span data-testid='upgrade-cell'>{objRow.strName}</span>
+}
+
+const objConfig: TableConfiguration<IUpgradeRow> = {
+  table: {
+    data: [{ nId: 1, strName: 'StrictMode cell' }],
+    height: 'content' satisfies TableHeight,
+    columns: [{ key: 'strName', label: 'Name', cellComponent: NameCell }],
+  },
+  editing: { rowKey: 'nId' },
+  search: false,
+  query: false,
+  toolbar: false,
+  pagination: false,
+}
+
+describe('AppTable upgraded browser behavior', () => {
+  it('keeps React cells alive through StrictMode replay and updates DTO revisions', async () => {
+    const objRef = createRef<TableController<IUpgradeRow>>()
+    const objScreen = await render(
+      <StrictMode>
+        <div style={{ height: 480, width: 800 }}>
+          <TableComponent
+            ref={objRef}
+            tableKey='upgrade-strict-cells'
+            config={objConfig}
+          />
+        </div>
+      </StrictMode>
+    )
+    await expect
+      .element(page.getByTestId('upgrade-cell').first())
+      .toHaveTextContent('StrictMode cell')
+    const objInstance = objRef.current!.instance!
+    const objRow = objRef.current!.getData()[0]
+    objRow.strName = 'Updated in place'
+    objRef.current!.replaceData([objRow])
+    await expect
+      .element(page.getByTestId('upgrade-cell').first())
+      .toHaveTextContent('Updated in place')
+    expect(objRef.current!.instance).toBe(objInstance)
+    await objScreen.unmount()
+    await expect.poll(() => objInstance.isDestroyed).toBe(true)
+  })
+
+  it('changes localized density explicitly and persists the selected option', async () => {
+    const objStore = createMemoryPreferenceStore()
+    const objRef = createRef<TableController<IUpgradeRow>>()
+    const objDensityConfig: TableConfiguration<IUpgradeRow> = {
+      ...objConfig,
+      toolbar: { densityControl: true, columnEditor: false },
+      preference: { store: objStore },
+    }
+    const objView = (
+      <LocaleProvider strLocale='en-US' strTimeZone='UTC'>
+        <div style={{ height: 480, width: 800 }}>
+          <TableComponent
+            ref={objRef}
+            tableKey='upgrade-density'
+            config={objDensityConfig}
+          />
+        </div>
+      </LocaleProvider>
+    )
+    const objScreen = await render(objView)
+    const objDensity = page.getByRole('button', {
+      name: /Change table density/,
+    })
+    await expect.element(objDensity).toBeEnabled()
+    const nComfortableHeight = objRef.current!.instance!.getRowHeight(0)!
+    await objDensity.click()
+    await page
+      .getByRole('menuitemradio', { name: 'Compact', exact: true })
+      .click()
+    await expect.element(objDensity).toHaveTextContent('Density · Compact')
+    await expect
+      .poll(() => objRef.current!.instance!.getRowHeight(0))
+      .toBeLessThan(nComfortableHeight)
+    await objScreen.unmount()
+    await render(objView)
+    await expect
+      .element(page.getByRole('button', { name: /Change table density/ }))
+      .toHaveTextContent('Density · Compact')
+  })
+
+  it('reveals the first remote result at its settled height without flashing empty state', async () => {
+    let fnResolveQuery!: (objResult: TableQueryResult<IUpgradeRow>) => void
+    const objResult = new Promise<TableQueryResult<IUpgradeRow>>(
+      (fnResolve) => {
+        fnResolveQuery = fnResolve
+      }
+    )
+    const fnQuery = vi.fn(() => objResult)
+    await render(
+      <LocaleProvider strLocale='en-US' strTimeZone='UTC'>
+        <div style={{ height: 480, width: 800 }}>
+          <AppTable
+            tableKey='upgrade-remote-height'
+            config={{
+              ...objConfig,
+              table: { ...objConfig.table, data: [] },
+              query: { handler: fnQuery },
+            }}
+          />
+        </div>
+      </LocaleProvider>
+    )
+    await expect.poll(() => fnQuery.mock.calls.length).toBe(1)
+    const objGrid = document.querySelector<HTMLElement>(
+      '[data-slot="table-grid"]'
+    )!
+    expect(objGrid.dataset.heightReady).toBe('false')
+    await expect.element(page.getByText('Loading data')).toBeVisible()
+    await expect.element(page.getByText('No data')).not.toBeInTheDocument()
+    fnResolveQuery({ list: [{ nId: 1, strName: 'Remote result' }], total: 1 })
+    await expect.poll(() => objGrid.dataset.heightReady).toBe('true')
+    await expect.element(page.getByText('Remote result').first()).toBeVisible()
+    expect(objGrid.getBoundingClientRect().height).toBeLessThan(160)
+  })
+
+  it('settles a resized fill table without replacing data or the grid instance', async () => {
+    const objRef = createRef<TableController<IUpgradeRow>>()
+    const objFillConfig: TableConfiguration<IUpgradeRow> = {
+      ...objConfig,
+      table: { ...objConfig.table, height: 'fill' },
+    }
+    const fnView = (bTransitioning: boolean, nHeight: number) => (
+      <div style={{ height: nHeight, width: 800 }}>
+        <TableComponent
+          ref={objRef}
+          tableKey='upgrade-layout-settlement'
+          layoutTransitioning={bTransitioning}
+          config={objFillConfig}
+        />
+      </div>
+    )
+    const objScreen = await render(fnView(false, 480))
+    const objGrid = document.querySelector<HTMLElement>(
+      '[data-slot="table-grid"]'
+    )!
+    await expect
+      .poll(() => objGrid.getBoundingClientRect().height)
+      .toBeGreaterThan(470)
+    const objController = objRef.current!
+    const objInstance = objController.instance
+    const nRevision = objController.dataRevision
+    await objScreen.rerender(fnView(true, 360))
+    await objScreen.rerender(fnView(false, 360))
+    await expect
+      .poll(() => objGrid.getBoundingClientRect().height)
+      .toBeLessThanOrEqual(360)
+    expect(objGrid.getBoundingClientRect().height).toBeGreaterThan(350)
+    expect(objController.instance).toBe(objInstance)
+    expect(objController.dataRevision).toBe(nRevision)
+  })
+})