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

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

@@ -0,0 +1,145 @@
+import { describe, expect, it, vi } from 'vitest'
+import { fnResolveAdvancedTableLicense } from '@/components/AppTable/config/license'
+import { createTableController } from '@/components/AppTable/engine/table/controller/TableController'
+import {
+  assertTableRowIdentity,
+  resolveCanonicalTableRowKey,
+} from '@/components/AppTable/engine/table/controller/tableIdentity'
+import { createTableValidation } from '@/components/AppTable/engine/table/editing/validation'
+
+interface ITestRow {
+  nId: number
+}
+
+interface IValidationTestRow extends ITestRow {
+  strCode: string
+}
+
+describe('TableComponent core invariants', () => {
+  it('rejects duplicate row identities before stateful features initialize', () => {
+    const arrRows: ITestRow[] = [{ nId: 1 }, { nId: 1 }]
+
+    expect(() => assertTableRowIdentity(arrRows, 'nId')).toThrow(
+      'Duplicate rowKey "1"'
+    )
+  })
+
+  it('requires all stateful domains to share one row key resolver', () => {
+    const fnRowKey = (objRow: ITestRow) => objRow.nId
+
+    expect(resolveCanonicalTableRowKey([fnRowKey, fnRowKey])).toBe(fnRowKey)
+    expect(() =>
+      resolveCanonicalTableRowKey([
+        (objRow: ITestRow) => objRow.nId,
+        (objRow: ITestRow) => objRow.nId,
+      ])
+    ).toThrow('must share one canonical rowKey resolver')
+  })
+
+  it('allows evaluation locally but requires a commercial production key', () => {
+    expect(fnResolveAdvancedTableLicense({})).toBe(
+      'non-commercial-and-evaluation'
+    )
+    expect(() =>
+      fnResolveAdvancedTableLicense({
+        bProduction: true,
+        strKey: 'non-commercial-and-evaluation',
+      })
+    ).toThrow('commercial Handsontable license key is required')
+    expect(
+      fnResolveAdvancedTableLicense({
+        bProduction: true,
+        strKey: 'commercial-license-key',
+      })
+    ).toBe('commercial-license-key')
+  })
+
+  it('limits async validation concurrency while preserving row order', async () => {
+    let nActive = 0
+    let nMaxActive = 0
+    const arrReleases: Array<() => void> = []
+    const objValidation = createTableValidation<IValidationTestRow>({
+      rowKey: 'nId',
+      asyncConcurrency: 3,
+      columns: [
+        {
+          prop: 'strCode',
+          validator: () =>
+            new Promise<string>((fnResolve) => {
+              nActive += 1
+              nMaxActive = Math.max(nMaxActive, nActive)
+              arrReleases.push(() => {
+                nActive -= 1
+                fnResolve('编码不可用')
+              })
+            }),
+        },
+      ],
+    })
+    const objRun = objValidation.validate(
+      Array.from({ length: 6 }, (_objUnusedValue, nIndex) => ({
+        nId: nIndex + 1,
+        strCode: `code-${nIndex}`,
+      })),
+      new AbortController().signal
+    )
+
+    await vi.waitFor(() => expect(arrReleases).toHaveLength(3))
+    arrReleases
+      .splice(0, 3)
+      .reverse()
+      .forEach((fnRelease) => fnRelease())
+    await vi.waitFor(() => expect(arrReleases).toHaveLength(3))
+    arrReleases
+      .splice(0)
+      .reverse()
+      .forEach((fnRelease) => fnRelease())
+
+    const objResult = await objRun
+    expect(nMaxActive).toBe(3)
+    expect(objResult.issues.map((objIssue) => objIssue.rowKey)).toEqual([
+      1, 2, 3, 4, 5, 6,
+    ])
+  })
+
+  it('settles a save before rerendering selected rows', async () => {
+    let bRejectSelection = false
+    const objRow = { nId: 1, strName: '旧名称' }
+    const objController = createTableController({
+      tableKey: 'commit-without-selection-revalidation',
+      initialData: [objRow],
+      selection: {
+        rowKey: 'nId',
+        isRowSelectable: () => {
+          if (bRejectSelection) throw new Error('selection policy failed')
+          return true
+        },
+      },
+      editing: {
+        rowKey: 'nId',
+        commitChanges: async () => ({
+          updates: [
+            {
+              rowKey: 1,
+              success: true,
+              row: { nId: 1, strName: '已保存' },
+            },
+          ],
+        }),
+      },
+    })
+    objController.toggleRowSelection(objRow, true)
+    objRow.strName = '编辑后'
+    objController.recordChanges([[0, 'strName', '旧名称', '编辑后']])
+    bRejectSelection = true
+
+    await expect(objController.saveChanges()).resolves.toBeDefined()
+    expect(objController.hasDirtyChanges()).toBe(false)
+    expect(objController.getData()).toEqual([{ nId: 1, strName: '已保存' }])
+    expect(objController.getLoadedSelectedRows()).toEqual([
+      { nId: 1, strName: '已保存' },
+    ])
+    expect(objController.snapshot.error).toBeNull()
+    objController.destroy()
+  })
+})

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

@@ -0,0 +1,27 @@
+import '@/styles/index.css'
+import { describe, it } from 'vitest'
+import { render } from 'vitest-browser-react'
+import { Button } from '@/components/ui/button'
+import { fnExpectNoAccessibilityViolations } from '../../setup/accessibility'
+
+describe('semantic theme colors', () => {
+  it.each(['light', 'dark'] as const)(
+    'keeps %s action and muted text pairs accessible',
+    async (strTheme) => {
+      const objScreen = await render(
+        <div
+          className={`${strTheme === 'dark' ? 'dark' : ''}bg-background p-4 text-foreground`}
+        >
+          <div className='flex gap-2'>
+            <Button>主要操作</Button>
+            <Button variant='secondary'>次要操作</Button>
+            <Button variant='destructive'>危险操作</Button>
+          </div>
+          <p className='mt-2 text-sm text-muted-foreground'>辅助说明文字</p>
+        </div>
+      )
+
+      await fnExpectNoAccessibilityViolations(objScreen.container)
+    }
+  )
+})

package/template/tests/unit/config/RuntimeConfigErrorPage.test.tsx

@@ -0,0 +1,23 @@
+import { RuntimeConfigErrorPage } from '@/config/RuntimeConfigErrorPage'
+import { expect, test } from 'vitest'
+import { render } from 'vitest-browser-react'
+
+test('runtime configuration failure explains how to recover', async () => {
+  const objScreen = await render(
+    <RuntimeConfigErrorPage
+      strCode='invalid_config'
+      strMessage='runtime-config.json 配置不符合契约。'
+    />
+  )
+
+  await expect
+    .element(objScreen.getByRole('alert'))
+    .toHaveTextContent('应用运行时配置不可用')
+  await expect
+    .element(objScreen.getByText('invalid_config'))
+    .toBeInTheDocument()
+  await expect.element(objScreen.getByText(/v0\.1\.0/)).toBeInTheDocument()
+  await expect
+    .element(objScreen.getByRole('button', { name: '重新加载' }))
+    .toBeInTheDocument()
+})

package/template/tests/unit/config/appConfig.test.ts

@@ -0,0 +1,98 @@
+import { fnApplyAppDocumentMetadata, objAppConfig } from '@/config/appConfig'
+import { describe, expect, it } from 'vitest'
+
+describe('application configuration', () => {
+  it('provides one consistent contract for branding and persistence', () => {
+    expect(objAppConfig.brand).toEqual({
+      strId: 'enterprise-admin',
+      strName: 'Enterprise Admin',
+      strDescription: '企业管理控制台',
+      strLogoUrl: '/logo.svg',
+      strDarkLogoUrl: '/logo.svg',
+      strFaviconUrl: '/favicon.ico',
+      objTheme: {
+        objLight: {
+          strPrimaryColor: '#4068d5',
+          strPrimaryForegroundColor: '#ffffff',
+          strSecondaryColor: '#49beff',
+          strSecondaryForegroundColor: '#102a43',
+          strBrowserThemeColor: '#ffffff',
+        },
+        objDark: {
+          strPrimaryColor: '#8aadff',
+          strPrimaryForegroundColor: '#0f172a',
+          strSecondaryColor: '#49beff',
+          strSecondaryForegroundColor: '#102a43',
+          strBrowserThemeColor: '#000000',
+        },
+      },
+    })
+    expect(objAppConfig.api).toEqual({ strBaseUrl: '' })
+    expect(objAppConfig.observability).toEqual({
+      bEnabled: false,
+    })
+    expect(objAppConfig.locale).toEqual({
+      strLocale: 'zh-CN',
+      strTimeZone: 'Asia/Shanghai',
+    })
+    expect(objAppConfig.release).toMatchObject({
+      strVersion: '0.1.0',
+      strEnvironment: 'local',
+    })
+    expect(objAppConfig.release.strCommit).toBeTruthy()
+    expect(Date.parse(objAppConfig.release.strBuildTime)).not.toBeNaN()
+    expect(objAppConfig.navigation.strDefaultAuthenticatedPath).toBe(
+      '/dashboard'
+    )
+    expect(objAppConfig.auth).toEqual({
+      strAudience: 'admin-api',
+      strClientId: 'react-admin',
+      strScope: 'openid profile offline_access',
+      strSessionStorage: 'session',
+      strSignInPath: '/api/v1/auth/first-party-login',
+      strRefreshPath: '/api/v1/auth/refresh-token',
+      strSignOutPath: '/api/v1/auth/logout',
+    })
+    expect(objAppConfig.storage).toEqual({
+      strAuthSessionKey: 'enterprise-admin.auth-session',
+      strTenantWorkspaceKey: 'enterprise-admin.tenant-workspace',
+      strThemeKey: 'enterprise-admin.theme',
+      strUiPreferenceKey: 'enterprise-admin.ui-preferences',
+    })
+    expect(Object.isFrozen(objAppConfig.brand.objTheme.objDark)).toBe(true)
+  })
+
+  it('applies the runtime brand to document metadata and favicon links', () => {
+    const arrIconLinks = Array.from(
+      document.querySelectorAll<HTMLLinkElement>('link[rel~="icon"]')
+    )
+    const objExistingIconLinks = new Set(arrIconLinks)
+    const arrPreviousHrefs = arrIconLinks.map((objLink) =>
+      objLink.getAttribute('href')
+    )
+
+    try {
+      fnApplyAppDocumentMetadata()
+
+      expect(document.documentElement.dataset.brand).toBe('enterprise-admin')
+      expect(document.title).toBe('Enterprise Admin')
+      expect(
+        Array.from(
+          document.querySelectorAll<HTMLLinkElement>('link[rel~="icon"]')
+        ).every((objLink) => objLink.getAttribute('href') === '/favicon.ico')
+      ).toBe(true)
+    } finally {
+      delete document.documentElement.dataset.brand
+      arrIconLinks.forEach((objLink, nIndex) => {
+        const strPreviousHref = arrPreviousHrefs[nIndex]
+        if (strPreviousHref === null) objLink.removeAttribute('href')
+        else objLink.setAttribute('href', strPreviousHref)
+      })
+      document
+        .querySelectorAll<HTMLLinkElement>('link[rel~="icon"]')
+        .forEach((objLink) => {
+          if (!objExistingIconLinks.has(objLink)) objLink.remove()
+        })
+    }
+  })
+})

package/template/tests/unit/config/appTableContracts.test.mjs

@@ -0,0 +1,120 @@
+import assert from 'node:assert/strict'
+import { readFile } from 'node:fs/promises'
+import nodePath from 'node:path'
+import test from 'node:test'
+
+const strProjectRoot = nodePath.resolve(import.meta.dirname, '../../..')
+const arrContractFiles = [
+  'src/components/AppTable/config/types.ts',
+  'src/components/AppTable/engine/component/resolver.ts',
+  'src/components/AppTable/engine/columns/column.ts',
+  'src/components/AppTable/engine/pagination/types.ts',
+  'src/components/AppTable/engine/search/types.ts',
+  'src/components/AppTable/engine/selection/types.ts',
+  'src/components/AppTable/engine/summary/config/types.ts',
+  'src/components/AppTable/engine/summary/export.ts',
+  'src/components/AppTable/engine/summary/summary.ts',
+  'src/components/AppTable/engine/table/editing/types.ts',
+  'src/components/AppTable/engine/toolbar/types.ts',
+  'src/components/AppTable/table/components/types.ts',
+  'src/components/AppTable/engine/table/controller/types.ts',
+]
+const arrFullyDocumentedFiles = [
+  'src/components/AppTable/engine/component/resolver.ts',
+]
+
+function fnIsAuditedType(objTypeScript, objNode, bRequireExport) {
+  const bIsSupportedDeclaration =
+    objTypeScript.isInterfaceDeclaration(objNode) ||
+    objTypeScript.isTypeAliasDeclaration(objNode)
+
+  return Boolean(
+    bIsSupportedDeclaration &&
+    (!bRequireExport ||
+      objNode.modifiers?.some(
+        (objModifier) =>
+          objModifier.kind === objTypeScript.SyntaxKind.ExportKeyword
+      ))
+  )
+}
+
+function fnHasJsDoc(objTypeScript, objSourceFile, objNode) {
+  if (objTypeScript.getJSDocCommentsAndTags(objNode).length) return true
+
+  const arrCommentRanges =
+    objTypeScript.getLeadingCommentRanges(
+      objSourceFile.text,
+      objNode.getFullStart()
+    ) ?? []
+
+  return arrCommentRanges.some((objRange) =>
+    objSourceFile.text.slice(objRange.pos, objRange.end).startsWith('/**')
+  )
+}
+
+function fnIsExtractFilterMember(objTypeScript, objSourceFile, objNode) {
+  for (
+    let objParent = objNode.parent;
+    objParent;
+    objParent = objParent.parent
+  ) {
+    if (
+      objTypeScript.isTypeReferenceNode(objParent) &&
+      objParent.typeName.getText(objSourceFile) === 'Extract'
+    ) {
+      return true
+    }
+  }
+
+  return false
+}
+
+test('audited AppTable contract fields include JSDoc', async () => {
+  const objTypeScript = await import('typescript')
+  const arrUndocumentedFields = []
+
+  for (const strRelativePath of arrContractFiles) {
+    const strFilePath = nodePath.join(strProjectRoot, strRelativePath)
+    const strSource = await readFile(strFilePath, 'utf8')
+    const objSourceFile = objTypeScript.createSourceFile(
+      strFilePath,
+      strSource,
+      objTypeScript.ScriptTarget.Latest,
+      true
+    )
+    const bRequireExport = !arrFullyDocumentedFiles.includes(strRelativePath)
+
+    for (const objDeclaration of objSourceFile.statements) {
+      if (!fnIsAuditedType(objTypeScript, objDeclaration, bRequireExport)) {
+        continue
+      }
+
+      const fnVisit = (objNode) => {
+        const bIsContractField =
+          objTypeScript.isPropertySignature(objNode) ||
+          objTypeScript.isMethodSignature(objNode)
+
+        if (
+          bIsContractField &&
+          !fnIsExtractFilterMember(objTypeScript, objSourceFile, objNode) &&
+          !fnHasJsDoc(objTypeScript, objSourceFile, objNode)
+        ) {
+          const nLine =
+            objSourceFile.getLineAndCharacterOfPosition(objNode.getStart())
+              .line + 1
+          const strFieldName =
+            objNode.name?.getText(objSourceFile) ?? '<member>'
+          arrUndocumentedFields.push(
+            `${strRelativePath}:${nLine} ${objDeclaration.name.text}.${strFieldName}`
+          )
+        }
+
+        objTypeScript.forEachChild(objNode, fnVisit)
+      }
+
+      fnVisit(objDeclaration)
+    }
+  }
+
+  assert.deepEqual(arrUndocumentedFields, [])
+})

package/template/tests/unit/config/bundleBudget.test.mjs

@@ -0,0 +1,190 @@
+import { loadConfigFromFile } from 'vite'
+import assert from 'node:assert/strict'
+import { spawnSync } from 'node:child_process'
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import test from 'node:test'
+import { fileURLToPath } from 'node:url'
+import { fnCheckBundleBudgets } from '../../../tools/bundle/check.mjs'
+
+const strProjectRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../..'
+)
+const strBundleScript = path.resolve(strProjectRoot, 'tools/bundle/check.mjs')
+
+const fnWriteJson = (strFilePath, objValue) =>
+  writeFile(strFilePath, `${JSON.stringify(objValue, null, 2)}\n`, 'utf8')
+
+const fnCreateFixture = async (objTestContext) => {
+  const strFixtureRoot = await mkdtemp(
+    path.join(os.tmpdir(), 'react-admin-bundle-budget-')
+  )
+  objTestContext.after(() =>
+    rm(strFixtureRoot, { force: true, recursive: true })
+  )
+  const strDistRoot = path.resolve(strFixtureRoot, 'dist')
+  const strBudgetsPath = path.resolve(strFixtureRoot, 'budgets.json')
+  await Promise.all([
+    mkdir(path.resolve(strDistRoot, '.vite'), { recursive: true }),
+    mkdir(path.resolve(strDistRoot, 'assets'), { recursive: true }),
+  ])
+  const objManifest = {
+    '_shared.js': {
+      file: 'assets/shared.js',
+      name: 'shared',
+    },
+    'index.html': {
+      file: 'assets/index.js',
+      imports: ['_shared.js'],
+      css: ['assets/index.css'],
+      src: 'index.html',
+      isEntry: true,
+    },
+    'src/features/auth/index.ts': {
+      file: 'assets/auth.js',
+      imports: ['_shared.js'],
+      src: 'src/features/auth/index.ts',
+      isDynamicEntry: true,
+    },
+  }
+  const objBudgets = {
+    nSchemaVersion: 1,
+    arrBudgets: [
+      {
+        strId: 'sign-in-js',
+        strLabel: '登录旅程 JavaScript',
+        strOwner: '认证 Feature',
+        strKind: 'javascript',
+        arrEntries: ['index.html', 'src/features/auth/index.ts'],
+        nMaxGzipBytes: 10_000,
+      },
+      {
+        strId: 'bootstrap-css',
+        strLabel: '应用启动 CSS',
+        strOwner: '全局样式',
+        strKind: 'stylesheet',
+        arrEntries: ['index.html'],
+        nMaxGzipBytes: 10_000,
+      },
+    ],
+  }
+  await Promise.all([
+    fnWriteJson(path.resolve(strDistRoot, '.vite/manifest.json'), objManifest),
+    fnWriteJson(strBudgetsPath, objBudgets),
+    writeFile(path.resolve(strDistRoot, 'assets/index.js'), 'entry'.repeat(40)),
+    writeFile(
+      path.resolve(strDistRoot, 'assets/shared.js'),
+      'shared'.repeat(40)
+    ),
+    writeFile(path.resolve(strDistRoot, 'assets/auth.js'), 'auth'.repeat(40)),
+    writeFile(
+      path.resolve(strDistRoot, 'assets/index.css'),
+      'body{}'.repeat(40)
+    ),
+  ])
+  return { objBudgets, objManifest, strBudgetsPath, strDistRoot }
+}
+
+test('bundle budgets measure static journey graphs and deduplicate shared chunks', async (objTestContext) => {
+  const { strBudgetsPath, strDistRoot } = await fnCreateFixture(objTestContext)
+
+  const objReport = await fnCheckBundleBudgets({
+    strBudgetsPath,
+    strDistRoot,
+  })
+  const objJavaScriptResult = objReport.arrResults.find(
+    (objResult) => objResult.strId === 'sign-in-js'
+  )
+
+  assert.equal(objReport.bPassed, true)
+  assert.equal(objJavaScriptResult.arrAssets.length, 3)
+  assert.equal(
+    objJavaScriptResult.arrAssets.filter(
+      (objAsset) => objAsset.strAssetPath === 'assets/shared.js'
+    ).length,
+    1
+  )
+  assert.equal(objJavaScriptResult.nGzipBytes > 0, true)
+})
+
+test('bundle budgets report exceeded journeys with their largest owners', async (objTestContext) => {
+  const { objBudgets, strBudgetsPath, strDistRoot } =
+    await fnCreateFixture(objTestContext)
+  objBudgets.arrBudgets[0].nMaxGzipBytes = 1
+  await fnWriteJson(strBudgetsPath, objBudgets)
+
+  const objReport = await fnCheckBundleBudgets({
+    strBudgetsPath,
+    strDistRoot,
+  })
+  const objExceededResult = objReport.arrResults[0]
+
+  assert.equal(objReport.bPassed, false)
+  assert.equal(objExceededResult.bPassed, false)
+  assert.equal(objExceededResult.arrAssets.length, 3)
+  assert.equal(typeof objExceededResult.arrAssets[0].strOwner, 'string')
+})
+
+test('bundle budgets reject missing entries and unsafe artifact paths', async (objTestContext) => {
+  const { objBudgets, objManifest, strBudgetsPath, strDistRoot } =
+    await fnCreateFixture(objTestContext)
+  objBudgets.arrBudgets[0].arrEntries = ['src/features/missing/index.ts']
+  await fnWriteJson(strBudgetsPath, objBudgets)
+
+  await assert.rejects(
+    fnCheckBundleBudgets({ strBudgetsPath, strDistRoot }),
+    (objError) => {
+      assert.equal(objError.strCode, 'BUNDLE_MANIFEST_ENTRY_MISSING')
+      assert.match(objError.message, /src\/features\/missing/)
+      return true
+    }
+  )
+
+  objManifest['index.html'].file = '../outside.js'
+  await Promise.all([
+    fnWriteJson(path.resolve(strDistRoot, '.vite/manifest.json'), objManifest),
+    fnWriteJson(strBudgetsPath, {
+      ...objBudgets,
+      arrBudgets: [
+        {
+          ...objBudgets.arrBudgets[0],
+          arrEntries: ['index.html'],
+        },
+      ],
+    }),
+  ])
+  await assert.rejects(
+    fnCheckBundleBudgets({ strBudgetsPath, strDistRoot }),
+    (objError) => objError.strCode === 'BUNDLE_MANIFEST_INVALID'
+  )
+})
+
+test('production build owns the manifest and bundle budget gate', async () => {
+  const [objPackage, objLoadedConfig] = await Promise.all([
+    readFile(path.resolve(strProjectRoot, 'package.json'), 'utf8').then(
+      JSON.parse
+    ),
+    loadConfigFromFile(
+      { command: 'build', mode: 'production' },
+      path.resolve(strProjectRoot, 'vite.config.ts'),
+      strProjectRoot,
+      'silent'
+    ),
+  ])
+  const objInvalidResult = spawnSync(
+    process.execPath,
+    [strBundleScript, '--write'],
+    { cwd: strProjectRoot, encoding: 'utf8' }
+  )
+
+  assert.equal(
+    objPackage.scripts['bundle:check'],
+    'node tools/bundle/check.mjs'
+  )
+  assert.match(objPackage.scripts.build, /vite build && pnpm bundle:check/)
+  assert.equal(objLoadedConfig?.config.build?.manifest, true)
+  assert.equal(objInvalidResult.status, 1)
+  assert.match(objInvalidResult.stderr, /BUNDLE_BUDGET_ARGUMENT_INVALID/)
+})