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

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

@@ -0,0 +1,258 @@
+import { describe, expect, it, vi } from 'vitest'
+import { compileTableGridSettings } from '@/components/AppTable/engine/config/grid/compiler'
+import { createTableGridDefaultSettings } from '@/components/AppTable/engine/config/grid/defaults'
+import { TABLE_GRID_HOOK_OWNERSHIP } from '@/components/AppTable/engine/config/grid/ownership'
+import { diffTableGridRuntimeSettings } from '@/components/AppTable/engine/config/grid/runtimeDelta'
+import { runTableLocalQuery } from '@/components/AppTable/engine/search/localQuery'
+import { createExcelJsTableWriter } from '@/components/AppTable/engine/summary/excelJs'
+import { createTableCsvAsync } from '@/components/AppTable/engine/summary/export'
+import { createTableSelectionSumTask } from '@/components/AppTable/engine/summary/selectionSum'
+import { sumTableNumericValuesAsync } from '@/components/AppTable/engine/summary/summary'
+import { createFixedEndSemanticReconciler } from '@/components/AppTable/engine/table/layout/fixedEndOverlayAccessibility'
+import {
+  measureTableGridContentHeight,
+  resolveTableGridHeight,
+  resolveTableInitialGridHeight,
+} from '@/components/AppTable/engine/table/layout/height'
+import { createTableLayoutScheduler } from '@/components/AppTable/engine/table/layout/layoutScheduler'
+
+describe('AppTable upstream upgrade invariants', () => {
+  it('resolves content, fill and fixed heights with bounded row measurement', () => {
+    expect(resolveTableInitialGridHeight('content')).toBe(160)
+    expect(resolveTableInitialGridHeight('fill')).toBe(160)
+    expect(resolveTableInitialGridHeight(480)).toBe(480)
+    expect(resolveTableInitialGridHeight(0)).toBe(1)
+    expect(
+      resolveTableGridHeight({
+        height: 'content',
+        contentHeight: 240,
+        availableHeight: 600,
+      })
+    ).toBe(240)
+    expect(
+      resolveTableGridHeight({
+        height: 'content',
+        contentHeight: 800,
+        availableHeight: 600,
+      })
+    ).toBe(600)
+    expect(
+      resolveTableGridHeight({
+        height: 'fill',
+        contentHeight: 240,
+        availableHeight: 600,
+      })
+    ).toBe(600)
+    expect(
+      resolveTableGridHeight({
+        height: 480,
+        contentHeight: 240,
+        availableHeight: 400,
+      })
+    ).toBe(400)
+
+    const fnGetRowHeight = vi.fn(() => 42)
+    expect(
+      measureTableGridContentHeight({
+        instance: {
+          countRows: () => 1_000_000,
+          getRowHeight: fnGetRowHeight,
+          stylesHandler: { getDefaultRowHeight: () => 42 },
+        },
+        rowCount: 1_000_000,
+        headerHeight: 42,
+        horizontalScrollbarHeight: 0,
+        availableHeight: 400,
+      })
+    ).toBe(400)
+    expect(fnGetRowHeight.mock.calls.length).toBeLessThan(10)
+  })
+
+  it('preserves native row heights and excludes data from runtime settings deltas', () => {
+    const objDefaults = createTableGridDefaultSettings()
+    expect(objDefaults.autoRowSize).toBe(true)
+    expect(objDefaults.rowHeights).toBeUndefined()
+    const objSettings = compileTableGridSettings({
+      defaults: objDefaults,
+      consumer: { minRowHeights: 48 },
+      controlled: { height: 240 },
+      internalHooks: {},
+      hookPolicies: TABLE_GRID_HOOK_OWNERSHIP,
+    })
+    expect(objSettings.rowHeights).toBeUndefined()
+    expect(objSettings.minRowHeights).toBe(48)
+    expect(
+      diffTableGridRuntimeSettings(
+        { data: [{ nId: 1 }], colHeaders: ['ID'], height: 240, readOnly: true },
+        { data: [{ nId: 2 }], colHeaders: ['ID'], height: 360 }
+      )
+    ).toEqual({ height: 360, readOnly: undefined })
+  })
+
+  it('coalesces layout work, waits for quiet frames and cancels disposal work', () => {
+    let nNextHandle = 0
+    const objFrames = new Map<number, FrameRequestCallback>()
+    const fnFrame = vi.fn()
+    const fnSettled = vi.fn()
+    const fnFlush = () => {
+      const arrFrames = [...objFrames.values()]
+      objFrames.clear()
+      arrFrames.forEach((fnCallback) => fnCallback(0))
+    }
+    const objScheduler = createTableLayoutScheduler({
+      onFrame: fnFrame,
+      onSettled: fnSettled,
+      requestFrame: (fnCallback) => {
+        const nHandle = ++nNextHandle
+        objFrames.set(nHandle, fnCallback)
+        return nHandle
+      },
+      cancelFrame: (nHandle) => {
+        objFrames.delete(nHandle)
+      },
+    })
+    for (let nIndex = 0; nIndex < 15; nIndex += 1) objScheduler.scheduleFrame()
+    fnFlush()
+    expect(fnFrame).toHaveBeenCalledOnce()
+    objScheduler.scheduleSettled()
+    fnFlush()
+    objScheduler.scheduleSettled()
+    fnFlush()
+    expect(fnSettled).not.toHaveBeenCalled()
+    fnFlush()
+    expect(fnSettled).toHaveBeenCalledOnce()
+    objScheduler.scheduleFrame()
+    objScheduler.scheduleSettled()
+    objScheduler.cancel()
+    expect(objFrames.size).toBe(0)
+  })
+
+  it('reasserts hidden semantics after Handsontable reuses a fixed-end cell', () => {
+    const objCell = document.createElement('td')
+    const objButton = document.createElement('button')
+    objCell.append(objButton)
+    const objSemantics = createFixedEndSemanticReconciler()
+    objSemantics.setActive(true)
+    objSemantics.updateElement(objCell, true)
+    expect(objCell.getAttribute('aria-hidden')).toBe('true')
+    objCell.removeAttribute('aria-hidden')
+    objSemantics.updateElement(objCell, true)
+    expect(objCell.getAttribute('aria-hidden')).toBe('true')
+    expect(objCell.inert).toBe(true)
+    objSemantics.updateElement(objCell, false)
+    expect(objCell.hasAttribute('aria-hidden')).toBe(false)
+    expect(objCell.inert).toBe(false)
+  })
+
+  it('keeps local sorting stable and cancels a superseded large query', async () => {
+    const arrRows = [
+      { nId: 1, strDepartment: '研发', nScore: 10 },
+      { nId: 2, strDepartment: '市场', nScore: 8 },
+      { nId: 3, strDepartment: '研发平台', nScore: 10 },
+      { nId: 4, strDepartment: '研发', nScore: 6 },
+    ]
+    const arrResult = await runTableLocalQuery(
+      arrRows,
+      {
+        page: 1,
+        pageSize: 20,
+        where: [
+          { field: 'strDepartment', operator: 'contains', value: '研发' },
+        ],
+        sort: [{ field: 'nScore', direction: 'desc' }],
+      },
+      { yieldInterval: 1 }
+    )
+    expect(arrResult.map((objRow) => objRow.nId)).toEqual([1, 3, 4])
+    expect(arrRows.map((objRow) => objRow.nId)).toEqual([1, 2, 3, 4])
+    const objAbort = new AbortController()
+    const objTask = runTableLocalQuery(
+      arrRows,
+      { page: 1, pageSize: 20, where: [] },
+      { signal: objAbort.signal, yieldInterval: 1 }
+    )
+    objAbort.abort('superseded')
+    await expect(objTask).rejects.toBe('superseded')
+  })
+
+  it('preserves CSV escaping and formula protection while allowing cancellation', async () => {
+    const arrColumns = [{ key: 'strName', label: 'Name' }] as const
+    const arrRows = [{ strName: '=1+1' }, { strName: 'a,"b"' }]
+    expect(
+      await createTableCsvAsync(arrRows, arrColumns, { yieldInterval: 1 })
+    ).toBe('\uFEFFName\r\n\'=1+1\r\n"a,""b"""')
+    const objAbort = new AbortController()
+    const objTask = createTableCsvAsync(arrRows, arrColumns, {
+      signal: objAbort.signal,
+      yieldInterval: 1,
+    })
+    objAbort.abort('export-cancelled')
+    await expect(objTask).rejects.toBe('export-cancelled')
+  })
+
+  it('uses decimal-safe async sums and publishes only the latest selection', async () => {
+    expect(
+      await sumTableNumericValuesAsync([0.1, [0.2, 'ignored']], {
+        yieldInterval: 1,
+      })
+    ).toBe('0.3')
+    const objTask = createTableSelectionSumTask(2)
+    const fnStale = vi.fn()
+    const fnLatest = vi.fn()
+    objTask.calculate({
+      ranges: [[0, 0, 0, 9_999]],
+      getValue: () => 1,
+      onResult: fnStale,
+    })
+    objTask.calculate({
+      ranges: [[0, 0, 0, 2]],
+      getValue: () => 2,
+      onResult: fnLatest,
+    })
+    await expect.poll(() => fnLatest.mock.calls.length).toBe(1)
+    expect(fnLatest).toHaveBeenCalledWith('6')
+    expect(fnStale).not.toHaveBeenCalled()
+    objTask.cancel()
+  })
+
+  it('writes readable XLSX with formula protection and cancels row assembly', async () => {
+    const objExcelJs = (await import('exceljs')).default
+    const fnWrite = createExcelJsTableWriter<{ strName: string }>()
+    const objAbort = new AbortController()
+    const arrColumns = [{ key: 'strName', label: 'Name' }] as const
+    const objBlob = await fnWrite({
+      fileName: 'upgrade.xlsx',
+      rows: [{ strName: '=1+1' }],
+      columns: arrColumns,
+      sheetName: 'Upgrade',
+      signal: objAbort.signal,
+    })
+    const objWorkbook = new objExcelJs.Workbook()
+    await objWorkbook.xlsx.load(await objBlob.arrayBuffer())
+    expect(objWorkbook.getWorksheet('Upgrade')!.getCell('A2').value).toBe(
+      "'=1+1"
+    )
+
+    let nFormatted = 0
+    const objTask = fnWrite({
+      fileName: 'cancelled.xlsx',
+      rows: Array.from({ length: 1_000 }, () => ({ strName: 'row' })),
+      columns: [
+        {
+          key: 'strName',
+          label: 'Name',
+          format: (objValue) => {
+            nFormatted += 1
+            if (nFormatted === 1)
+              queueMicrotask(() => objAbort.abort('cancel-xlsx'))
+            return objValue
+          },
+        },
+      ],
+      sheetName: 'Cancelled',
+      signal: objAbort.signal,
+    })
+    await expect(objTask).rejects.toBe('cancel-xlsx')
+    expect(nFormatted).toBeLessThan(1_000)
+  })
+})

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

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest'
+import { render } from 'vitest-browser-react'
+import { ThemeProvider } from '@/context/ThemeProvider'
+import { BrandLogo } from '@/components/BrandLogo'
+
+describe('BrandLogo', () => {
+  it('falls back to the brand initial when the configured asset fails', async () => {
+    const objScreen = await render(
+      <ThemeProvider>
+        <BrandLogo strClassName='size-8' />
+      </ThemeProvider>
+    )
+    const objLogo = objScreen.container.querySelector<HTMLImageElement>(
+      '[data-slot="brand-logo"]'
+    )
+
+    expect(objLogo).not.toBeNull()
+    objLogo?.dispatchEvent(new Event('error'))
+
+    await expect
+      .element(objScreen.getByText('E', { exact: true }))
+      .toHaveAttribute('data-slot', 'brand-logo-fallback')
+  })
+})

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

@@ -0,0 +1,80 @@
+import { usePermission } from '@/permissions'
+import { beforeEach, describe, expect, it } from 'vitest'
+import { render } from 'vitest-browser-react'
+import { useAuthStore } from '@/stores/authStore'
+import { Can } from '@/components/Can'
+
+function fnCreatePermissionSession(arrPermissions: string[]) {
+  return {
+    objUser: {
+      arrPermissions,
+      arrRoleCodes: ['admin'],
+      strId: 'user-1',
+      strAccount: '138****0000',
+      strDisplayName: '管理员',
+      strRole: 'admin',
+    },
+    strAccessToken: 'access-token',
+    strRefreshToken: 'refresh-token',
+    nAccessTokenExpiresAt: Date.now() + 60_000,
+    nRefreshTokenExpiresAt: Date.now() + 60_000,
+  }
+}
+
+describe('operation permission controls', () => {
+  beforeEach(() => {
+    useAuthStore.getState().fnClearSession()
+  })
+
+  it('hides denied content and supports a safe fallback', async () => {
+    useAuthStore
+      .getState()
+      .fnEstablishSession(fnCreatePermissionSession(['feature:item:read']))
+    const objScreen = await render(
+      <Can
+        objRequirement='feature:item:write'
+        objFallback={<span>无操作权限</span>}
+      >
+        <button>编辑</button>
+      </Can>
+    )
+
+    await expect.element(objScreen.getByText('无操作权限')).toBeVisible()
+    expect(objScreen.getByRole('button', { name: '编辑' }).query()).toBeNull()
+  })
+
+  it('requires the caller to apply the disabled state to the real control', async () => {
+    useAuthStore
+      .getState()
+      .fnEstablishSession(fnCreatePermissionSession(['feature:item:read']))
+    const objScreen = await render(
+      <Can objRequirement='feature:item:write' strDeniedBehavior='disable'>
+        {({ bIsDisabled }) => <button disabled={bIsDisabled}>编辑</button>}
+      </Can>
+    )
+    const objButton = objScreen.getByRole('button', { name: '编辑' })
+
+    await expect.element(objButton).toBeDisabled()
+  })
+
+  it('reacts to refreshed permissions without a second permission store', async () => {
+    function PermissionStatus() {
+      const bCanWrite = usePermission('feature:item:write')
+      return <span>{bCanWrite ? '允许写入' : '禁止写入'}</span>
+    }
+
+    useAuthStore
+      .getState()
+      .fnEstablishSession(fnCreatePermissionSession(['feature:item:read']))
+    const objScreen = await render(<PermissionStatus />)
+    await expect.element(objScreen.getByText('禁止写入')).toBeVisible()
+
+    const objCurrentUser = useAuthStore.getState().objUser
+    useAuthStore.getState().fnUpdateUser({
+      ...objCurrentUser!,
+      arrPermissions: ['feature:item:read', 'feature:item:write'],
+    })
+
+    await expect.element(objScreen.getByText('允许写入')).toBeVisible()
+  })
+})

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

@@ -0,0 +1,56 @@
+import '@/styles/index.css'
+import { describe, expect, it } from 'vitest'
+import { render } from 'vitest-browser-react'
+import {
+  Dialog,
+  DialogBody,
+  DialogContent,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog'
+
+describe('Dialog', () => {
+  it('keeps the header and footer fixed while the body scrolls', async () => {
+    await render(
+      <Dialog defaultOpen>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>布局测试</DialogTitle>
+          </DialogHeader>
+          <DialogBody>
+            <div style={{ height: '180vh' }}>可滚动内容</div>
+          </DialogBody>
+          <DialogFooter>固定操作区</DialogFooter>
+        </DialogContent>
+      </Dialog>
+    )
+    const objContent = document.querySelector<HTMLElement>(
+      '[data-slot="dialog-content"]'
+    )!
+    const objHeader = document.querySelector<HTMLElement>(
+      '[data-slot="dialog-header"]'
+    )!
+    const objBody = document.querySelector<HTMLElement>(
+      '[data-slot="dialog-body"]'
+    )!
+    const objFooter = document.querySelector<HTMLElement>(
+      '[data-slot="dialog-footer"]'
+    )!
+    const nHeaderTop = objHeader.getBoundingClientRect().top
+    const nFooterTop = objFooter.getBoundingClientRect().top
+
+    expect(objContent).toHaveClass('flex', 'overflow-hidden')
+    expect(objHeader).toHaveClass('py-4')
+    expect(objBody).toHaveClass('min-h-0', 'flex-1', 'overflow-y-auto')
+    expect(objFooter).toHaveClass('py-3')
+    expect(objBody.scrollHeight).toBeGreaterThan(objBody.clientHeight)
+
+    objBody.scrollTop = objBody.scrollHeight
+    objBody.dispatchEvent(new Event('scroll'))
+
+    await expect.poll(() => objBody.scrollTop).toBeGreaterThan(0)
+    expect(objHeader.getBoundingClientRect().top).toBeCloseTo(nHeaderTop, 4)
+    expect(objFooter.getBoundingClientRect().top).toBeCloseTo(nFooterTop, 4)
+  })
+})

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

@@ -0,0 +1,64 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { describe, expect, it } from 'vitest'
+import { render } from 'vitest-browser-react'
+import { EnumCatalogProvider, fnCreateEnumCatalogSource } from '@/api/enums'
+import { EnumBadge } from '@/components/EnumBadge'
+import { EnumText } from '@/components/EnumText'
+
+describe('enum presentation components', () => {
+  it('renders typed enum text and a safe semantic badge tone', async () => {
+    const objQueryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    })
+    const objSource = fnCreateEnumCatalogSource(async () => ({
+      enums: {
+        'activity.status': [
+          {
+            color: 'success',
+            label: '已启用',
+            sortOrder: 1,
+            value: 1,
+          },
+        ],
+      },
+      locale: 'zh-CN',
+      version: 'v1',
+    }))
+    const objScreen = await render(
+      <QueryClientProvider client={objQueryClient}>
+        <EnumCatalogProvider objSource={objSource}>
+          <EnumText objValue={1} strEnumKey='activity.status' />
+          <EnumBadge objValue={1} strEnumKey='activity.status' />
+        </EnumCatalogProvider>
+      </QueryClientProvider>
+    )
+
+    await expect.element(objScreen.getByText('已启用').first()).toBeVisible()
+    await expect
+      .element(objScreen.getByText('已启用').last())
+      .toHaveAttribute('data-tone', 'success')
+  })
+
+  it('falls back to the raw value when the enum key is missing', async () => {
+    const objQueryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    })
+    const objSource = fnCreateEnumCatalogSource(async () => ({
+      enums: {},
+      locale: 'zh-CN',
+      version: 'v1',
+    }))
+    const objScreen = await render(
+      <QueryClientProvider client={objQueryClient}>
+        <EnumCatalogProvider objSource={objSource}>
+          <EnumText objValue={false} strEnumKey='missing.key' />
+        </EnumCatalogProvider>
+      </QueryClientProvider>
+    )
+
+    await expect.element(objScreen.getByText('false')).toBeVisible()
+    await expect
+      .element(objScreen.getByText('false'))
+      .toHaveAttribute('data-state', 'missing')
+  })
+})

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

@@ -0,0 +1,51 @@
+import { FileCapabilityError } from '@/files'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { fnCreateFilePreview } from '@/components/FilePreview'
+
+describe('file preview adapters', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('creates and disposes built-in image previews', async () => {
+    const fnCreateObjectUrl = vi
+      .spyOn(URL, 'createObjectURL')
+      .mockReturnValue('blob:preview')
+    const fnRevokeObjectUrl = vi.spyOn(URL, 'revokeObjectURL')
+
+    const objResource = await fnCreateFilePreview({
+      objBlob: new Blob(['image'], { type: 'image/png' }),
+      strFileName: 'avatar.png',
+    })
+
+    expect(objResource).toMatchObject({
+      strKind: 'image',
+      strUrl: 'blob:preview',
+    })
+    expect(fnCreateObjectUrl).toHaveBeenCalledOnce()
+    objResource.fnDispose?.()
+    expect(fnRevokeObjectUrl).toHaveBeenCalledWith('blob:preview')
+  })
+
+  it('rejects and disposes an untrusted external preview URL', async () => {
+    const fnDispose = vi.fn()
+
+    await expect(
+      fnCreateFilePreview({
+        arrAdapters: [
+          {
+            fnCanPreview: () => true,
+            fnCreatePreview: async () => ({
+              fnDispose,
+              strKind: 'external',
+              strUrl: 'https://untrusted.example/preview',
+            }),
+          },
+        ],
+        objBlob: new Blob(['office']),
+        strFileName: 'report.docx',
+      })
+    ).rejects.toBeInstanceOf(FileCapabilityError)
+    expect(fnDispose).toHaveBeenCalledOnce()
+  })
+})

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

@@ -0,0 +1,47 @@
+import '@/styles/index.css'
+import { describe, expect, it, vi } from 'vitest'
+import { render } from 'vitest-browser-react'
+import { page, userEvent } from 'vitest/browser'
+import { ThemeProvider } from '@/context/ThemeProvider'
+import { JsonEditor } from '@/components/JsonEditor'
+
+describe('JsonEditor', () => {
+  it('formats valid JSON through the controlled change callback', async () => {
+    const fnOnChange = vi.fn()
+
+    await render(
+      <ThemeProvider>
+        <JsonEditor strValue='{"enabled":true}' fnOnChange={fnOnChange} />
+      </ThemeProvider>
+    )
+
+    await userEvent.click(page.getByRole('button', { name: '格式化' }))
+
+    expect(fnOnChange).toHaveBeenCalledWith(
+      JSON.stringify({ enabled: true }, null, 2)
+    )
+  })
+
+  it('disables editing and formatting in read-only mode', async () => {
+    await render(
+      <ThemeProvider>
+        <JsonEditor
+          strValue='{}'
+          bIsReadOnly
+          strAriaLabel='只读 JSON'
+          fnOnChange={vi.fn()}
+        />
+      </ThemeProvider>
+    )
+
+    const objEditorContent = document.querySelector<HTMLElement>(
+      '[data-slot="json-editor"] .cm-content'
+    )
+
+    expect(objEditorContent).not.toBeNull()
+    expect(objEditorContent).toHaveAttribute('contenteditable', 'false')
+    await expect
+      .element(page.getByRole('button', { name: '格式化' }))
+      .toBeDisabled()
+  })
+})

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

@@ -0,0 +1,36 @@
+import { LocaleProvider } from '@/locale'
+import { expect, it } from 'vitest'
+import { render } from 'vitest-browser-react'
+import { AppDataTable } from '@/components/AppDataTable'
+import { FileUpload } from '@/components/FileUpload'
+import { PasswordInput } from '@/components/PasswordInput'
+
+it('renders shared component defaults from the active LocaleProvider', async () => {
+  const objScreen = await render(
+    <LocaleProvider strLocale='en-US' strTimeZone='UTC'>
+      <AppDataTable
+        arrColumns={[
+          {
+            strHeader: 'Name',
+            strKey: 'name',
+            fnRender: (objRow: { strName: string }) => objRow.strName,
+          },
+        ]}
+        arrRows={[]}
+        fnGetRowKey={(objRow) => objRow.strName}
+        strAriaLabel='Users'
+      />
+      <FileUpload fnUpload={async () => 'uploaded'} />
+      <PasswordInput aria-label='Password' />
+    </LocaleProvider>
+  )
+
+  await expect.element(objScreen.getByText('No data')).toBeVisible()
+  await expect.element(objScreen.getByText('Select file')).toBeVisible()
+  await expect
+    .element(objScreen.getByRole('button', { name: 'Show password' }))
+    .toBeVisible()
+  await expect
+    .element(objScreen.getByRole('region', { name: /horizontal scrolling/ }))
+    .toBeVisible()
+})