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

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

@@ -0,0 +1,151 @@
+import '@/styles/index.css'
+import { describe, expect, it } from 'vitest'
+import { render } from 'vitest-browser-react'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu'
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from '@/components/ui/popover'
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select'
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from '@/components/ui/tooltip'
+import { AppDialog } from '@/components/AppDialog'
+
+function fnReadLayer(strVariable: string) {
+  return Number.parseInt(
+    getComputedStyle(document.documentElement).getPropertyValue(strVariable),
+    10
+  )
+}
+
+function fnReadElementLayer(strSelector: string) {
+  const objElement = document.querySelector<HTMLElement>(strSelector)
+  return objElement
+    ? Number.parseInt(getComputedStyle(objElement).zIndex, 10)
+    : undefined
+}
+
+describe('overlay layers', () => {
+  it('keeps the semantic layer scale above Handsontable overlays', () => {
+    const nTableCellLayer = fnReadLayer('--z-index-table-cell-layer')
+    const nTableCellMenu = fnReadLayer('--z-index-table-cell-menu')
+    const nTableCellTooltip = fnReadLayer('--z-index-table-cell-tooltip')
+    const nModalOverlay = fnReadLayer('--z-index-modal-overlay')
+    const nModal = fnReadLayer('--z-index-modal')
+    const nPopover = fnReadLayer('--z-index-popover')
+    const nTooltip = fnReadLayer('--z-index-tooltip')
+
+    expect(nTableCellLayer).toBeGreaterThan(180)
+    expect(nTableCellMenu).toBeGreaterThan(nTableCellLayer)
+    expect(nTableCellTooltip).toBeGreaterThan(nTableCellMenu)
+    expect(nModalOverlay).toBeGreaterThan(nTableCellTooltip)
+    expect(nModal).toBeGreaterThan(nModalOverlay)
+    expect(nPopover).toBeGreaterThan(nModal)
+    expect(nTooltip).toBeGreaterThan(nPopover)
+  })
+
+  it('applies the shared layer to portaled popovers', async () => {
+    await render(
+      <>
+        <div
+          data-testid='handsontable-overlay'
+          style={{ position: 'fixed', inset: 0, zIndex: 180 }}
+        />
+        <Popover defaultOpen>
+          <PopoverTrigger>打开浮层</PopoverTrigger>
+          <PopoverContent>浮层内容</PopoverContent>
+        </Popover>
+      </>
+    )
+
+    await expect
+      .poll(() => fnReadElementLayer('[data-slot="popover-content"]'))
+      .toBe(fnReadLayer('--z-index-popover'))
+
+    const objContent = document.querySelector<HTMLElement>(
+      '[data-slot="popover-content"]'
+    )!
+    const objRect = objContent.getBoundingClientRect()
+    const objTopElement = document.elementFromPoint(
+      objRect.left + objRect.width / 2,
+      objRect.top + objRect.height / 2
+    )
+    expect(
+      objTopElement === objContent || objContent.contains(objTopElement)
+    ).toBe(true)
+  })
+
+  it('applies the shared layer to portaled dropdown menus', async () => {
+    await render(
+      <DropdownMenu defaultOpen>
+        <DropdownMenuTrigger>打开菜单</DropdownMenuTrigger>
+        <DropdownMenuContent>
+          <DropdownMenuItem>菜单项</DropdownMenuItem>
+        </DropdownMenuContent>
+      </DropdownMenu>
+    )
+
+    await expect
+      .poll(() => fnReadElementLayer('[data-slot="dropdown-menu-content"]'))
+      .toBe(fnReadLayer('--z-index-popover'))
+  })
+
+  it('applies the shared layer to portaled selects', async () => {
+    await render(
+      <Select defaultOpen defaultValue='first'>
+        <SelectTrigger>
+          <SelectValue />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value='first'>第一项</SelectItem>
+        </SelectContent>
+      </Select>
+    )
+
+    await expect
+      .poll(() => fnReadElementLayer('[data-slot="select-content"]'))
+      .toBe(fnReadLayer('--z-index-popover'))
+  })
+
+  it('keeps modal content and tooltips in their semantic layers', async () => {
+    await render(
+      <>
+        <AppDialog bOpen fnOnOpenChange={() => undefined} strTitle='测试弹窗'>
+          弹窗内容
+        </AppDialog>
+        <TooltipProvider>
+          <Tooltip defaultOpen>
+            <TooltipTrigger>查看提示</TooltipTrigger>
+            <TooltipContent>提示内容</TooltipContent>
+          </Tooltip>
+        </TooltipProvider>
+      </>
+    )
+
+    await expect
+      .poll(() => fnReadElementLayer('[data-slot="dialog-overlay"]'))
+      .toBe(fnReadLayer('--z-index-modal-overlay'))
+    expect(fnReadElementLayer('[data-slot="dialog-content"]')).toBe(
+      fnReadLayer('--z-index-modal')
+    )
+    expect(fnReadElementLayer('[data-slot="tooltip-content"]')).toBe(
+      fnReadLayer('--z-index-tooltip')
+    )
+  })
+})

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

@@ -0,0 +1,143 @@
+import { ApiError } from '@/api'
+import { LocaleProvider } from '@/locale'
+import { describe, expect, it, vi } from 'vitest'
+import { render } from 'vitest-browser-react'
+import { userEvent } from 'vitest/browser'
+import { Button } from '@/components/ui/button'
+import {
+  PageEmptyState,
+  PageErrorState,
+  PageLoadingState,
+  type IPageEmptyStateProps,
+  type IPageErrorStateProps,
+  type TPageLoadingStateProps,
+} from '@/components/PageFeedback'
+import { fnExpectNoAccessibilityViolations } from '../../setup/accessibility'
+
+describe('PageFeedback', () => {
+  it('renders an accessible localized first-loading state', async () => {
+    const objLoadingProps: TPageLoadingStateProps = {}
+    const objScreen = await render(
+      <LocaleProvider strLocale='zh-CN' strTimeZone='UTC'>
+        <PageLoadingState {...objLoadingProps} />
+      </LocaleProvider>
+    )
+
+    const objStatus = objScreen.getByRole('status')
+    await expect.element(objStatus).toHaveAttribute('aria-busy', 'true')
+    await expect.element(objScreen.getByText('正在加载页面数据')).toBeVisible()
+    await fnExpectNoAccessibilityViolations(objScreen.container)
+  })
+
+  it('keeps successful empty-state actions owned by the feature', async () => {
+    const fnOnCreate = vi.fn()
+    const objEmptyProps: IPageEmptyStateProps = {
+      objAction: <Button onClick={fnOnCreate}>新建记录</Button>,
+    }
+    const objScreen = await render(
+      <LocaleProvider strLocale='zh-CN' strTimeZone='UTC'>
+        <PageEmptyState {...objEmptyProps} />
+      </LocaleProvider>
+    )
+
+    await expect.element(objScreen.getByText('暂无结果')).toBeVisible()
+    await userEvent.click(objScreen.getByRole('button', { name: '新建记录' }))
+    expect(fnOnCreate).toHaveBeenCalledOnce()
+  })
+
+  it('shows request context and manual retry for a retriable API error', async () => {
+    const fnOnRetry = vi.fn()
+    const objError = new ApiError({
+      bRetriable: true,
+      nStatus: 503,
+      strCode: 'SERVICE_UNAVAILABLE',
+      strKind: 'http',
+      strMessage: '服务暂时不可用。',
+      strRequestId: 'request-42',
+    })
+    const objErrorProps: IPageErrorStateProps = {
+      fnOnRetry,
+      objError,
+    }
+    const objScreen = await render(
+      <LocaleProvider strLocale='zh-CN' strTimeZone='UTC'>
+        <PageErrorState {...objErrorProps} />
+      </LocaleProvider>
+    )
+
+    await expect.element(objScreen.getByRole('alert')).toBeVisible()
+    await expect.element(objScreen.getByText('服务暂时不可用。')).toBeVisible()
+    await expect
+      .element(objScreen.getByText('请求 ID：request-42'))
+      .toBeVisible()
+    await userEvent.click(objScreen.getByRole('button', { name: '重试' }))
+    expect(fnOnRetry).toHaveBeenCalledOnce()
+    await fnExpectNoAccessibilityViolations(objScreen.container)
+  })
+
+  it('blocks duplicate retry actions while retrying', async () => {
+    const objScreen = await render(
+      <LocaleProvider strLocale='zh-CN' strTimeZone='UTC'>
+        <PageErrorState
+          bIsRetrying
+          fnOnRetry={() => undefined}
+          objError={
+            new ApiError({
+              bRetriable: true,
+              strCode: 'NETWORK_ERROR',
+              strKind: 'network',
+              strMessage: '网络连接失败。',
+            })
+          }
+        />
+      </LocaleProvider>
+    )
+
+    await expect
+      .element(objScreen.getByRole('button', { name: '正在重试…' }))
+      .toBeDisabled()
+  })
+
+  it('does not offer retry for a non-retriable permission error', async () => {
+    const objScreen = await render(
+      <LocaleProvider strLocale='zh-CN' strTimeZone='UTC'>
+        <PageErrorState
+          fnOnRetry={() => undefined}
+          objError={
+            new ApiError({
+              bRetriable: false,
+              nStatus: 403,
+              strCode: 'FORBIDDEN',
+              strKind: 'http',
+              strMessage: '当前账号无权执行此操作。',
+            })
+          }
+        />
+      </LocaleProvider>
+    )
+
+    await expect
+      .element(objScreen.getByText('当前账号无权执行此操作。'))
+      .toBeVisible()
+    expect(objScreen.getByRole('button', { name: '重试' }).elements()).toEqual(
+      []
+    )
+  })
+
+  it('does not expose an unknown internal error message', async () => {
+    const objScreen = await render(
+      <LocaleProvider strLocale='en-US' strTimeZone='UTC'>
+        <PageErrorState objError={new Error('secret database details')} />
+      </LocaleProvider>
+    )
+
+    await expect
+      .element(
+        objScreen.getByText('The page could not be loaded. Try again later.')
+      )
+      .toBeVisible()
+    expect(objScreen.getByText('secret database details').elements()).toEqual(
+      []
+    )
+  })
+})

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

@@ -0,0 +1,272 @@
+import { useState } from 'react'
+import { LocaleProvider } from '@/locale'
+import { describe, expect, it, vi } from 'vitest'
+import { render } from 'vitest-browser-react'
+import { userEvent } from 'vitest/browser'
+import {
+  AppPageForm,
+  type IFormProp,
+  type IPageFormFileConfig,
+} from '@/components/AppPageForm'
+import { PageForm } from '@/components/AppPageForm/PageForm'
+
+interface ITestFormModel {
+  strName: string
+  strStatus: string
+}
+
+interface IFileFormModel {
+  objAttachment: { strFileId: string; strFileName: string } | null
+}
+
+const fnSubmit = vi.fn()
+const objConfig: IFormProp<ITestFormModel> = {
+  confirmButtonText: '创建模型',
+  onAdd: fnSubmit,
+  formItems: [
+    {
+      label: '模型名称',
+      prop: 'strName',
+      required: true,
+      placeholder: '输入模型名称',
+    },
+    {
+      label: '状态',
+      prop: 'strStatus',
+      type: 'select',
+      options: [
+        { label: '运行中', value: 'online' },
+        { label: '已停用', value: 'offline' },
+      ],
+    },
+  ],
+}
+
+function TestPageForm() {
+  const [objModel, fnSetModel] = useState<ITestFormModel>({
+    strName: '',
+    strStatus: 'online',
+  })
+
+  return (
+    <PageForm model={objModel} config={objConfig} onModelChange={fnSetModel} />
+  )
+}
+
+function TestPageFormWithDirtyState({
+  fnOnDirtyChange,
+}: {
+  fnOnDirtyChange: (bIsDirty: boolean) => void
+}) {
+  const [objModel, fnSetModel] = useState<ITestFormModel>({
+    strName: '',
+    strStatus: 'online',
+  })
+
+  return (
+    <PageForm
+      model={objModel}
+      config={objConfig}
+      onModelChange={(objNextModel) => fnSetModel({ ...objNextModel })}
+      onDirtyChange={fnOnDirtyChange}
+    />
+  )
+}
+
+describe('PageForm', () => {
+  it('writes uploaded values through the public file field and resets dirty state', async () => {
+    const fnUpload = vi.fn(
+      async ({ arrFiles }: { arrFiles: readonly File[] }) => ({
+        strFileId: 'file-1',
+        strFileName: arrFiles[0]?.name ?? '',
+      })
+    )
+    const fnOnDirtyChange = vi.fn<(bIsDirty: boolean) => void>()
+    const fnOnModelChange = vi.fn<(objModel: IFileFormModel) => void>()
+
+    function FileForm() {
+      const [objModel, fnSetModel] = useState<IFileFormModel>({
+        objAttachment: null,
+      })
+      const objFileFieldConfig: IPageFormFileConfig<
+        IFileFormModel,
+        NonNullable<IFileFormModel['objAttachment']>
+      > = {
+        fnUpload,
+        strSelectText: '选择附件',
+        objValidation: {
+          arrAcceptedExtensions: ['.pdf'],
+          nMaxFiles: 1,
+        },
+      }
+      const objFileConfig: IFormProp<IFileFormModel> = {
+        formItems: [
+          {
+            label: '合同附件',
+            prop: 'objAttachment',
+            type: 'file',
+            required: true,
+            fileConfig: objFileFieldConfig,
+          },
+        ],
+      }
+
+      return (
+        <AppPageForm
+          model={objModel}
+          config={objFileConfig}
+          onModelChange={(objNextModel) => {
+            fnOnModelChange(objNextModel)
+            fnSetModel(objNextModel)
+          }}
+          onDirtyChange={fnOnDirtyChange}
+        />
+      )
+    }
+
+    const objScreen = await render(<FileForm />)
+    const objFile = new File(['contract'], 'contract.pdf', {
+      type: 'application/pdf',
+    })
+
+    await userEvent.upload(objScreen.getByLabelText('合同附件'), objFile)
+
+    await expect.poll(() => fnUpload.mock.calls.length).toBe(1)
+    await expect
+      .poll(() => fnOnModelChange.mock.calls.at(-1)?.[0])
+      .toEqual({
+        objAttachment: {
+          strFileId: 'file-1',
+          strFileName: 'contract.pdf',
+        },
+      })
+    await expect.poll(() => fnOnDirtyChange.mock.calls.at(-1)?.[0]).toBe(true)
+    await expect.element(objScreen.getByText('contract.pdf')).toBeVisible()
+
+    await userEvent.click(objScreen.getByRole('button', { name: '重置' }))
+
+    await expect.poll(() => fnOnDirtyChange.mock.calls.at(-1)?.[0]).toBe(false)
+    await expect
+      .poll(() => document.body.textContent?.includes('contract.pdf'))
+      .toBe(false)
+  })
+
+  it('reports dirty transitions and clears them after a successful submit', async () => {
+    const fnOnDirtyChange = vi.fn<(bIsDirty: boolean) => void>()
+    const objScreen = await render(
+      <TestPageFormWithDirtyState fnOnDirtyChange={fnOnDirtyChange} />
+    )
+
+    await expect.poll(() => fnOnDirtyChange.mock.calls.at(-1)?.[0]).toBe(false)
+    await userEvent.type(objScreen.getByLabelText('模型名称'), 'GPT Test')
+    await expect.poll(() => fnOnDirtyChange.mock.calls.at(-1)?.[0]).toBe(true)
+
+    await userEvent.click(objScreen.getByRole('button', { name: '创建模型' }))
+    await expect.poll(() => fnOnDirtyChange.mock.calls.at(-1)?.[0]).toBe(false)
+  })
+
+  it('allows custom actions to be rendered below the fields', async () => {
+    const objScreen = await render(
+      <PageForm
+        model={{ strName: '', strStatus: 'online' }}
+        config={objConfig}
+        actionsPlacement='bottom'
+        renderActions={({ submit: fnSubmitForm }) => (
+          <button type='button' onClick={() => void fnSubmitForm()}>
+            自定义保存
+          </button>
+        )}
+      />
+    )
+    const objActions = document.querySelector('.hgw-page-form__actions')
+
+    expect(objActions).not.toBeNull()
+    expect(objActions).toHaveAttribute('data-placement', 'bottom')
+    await expect
+      .element(objScreen.getByRole('button', { name: '自定义保存' }))
+      .toBeVisible()
+    expect(
+      objScreen
+        .getByLabelText('模型名称')
+        .element()
+        .compareDocumentPosition(objActions!) & Node.DOCUMENT_POSITION_FOLLOWING
+    ).toBeTruthy()
+  })
+
+  it('validates required fields and submits the controlled model', async () => {
+    fnSubmit.mockClear()
+    const objScreen = await render(<TestPageForm />)
+
+    await userEvent.click(objScreen.getByRole('button', { name: '创建模型' }))
+    await expect
+      .element(objScreen.getByRole('alert'))
+      .toHaveTextContent('模型名称不能为空')
+    expect(fnSubmit).not.toHaveBeenCalled()
+
+    await userEvent.type(objScreen.getByLabelText('模型名称'), 'GPT Test')
+    await userEvent.selectOptions(
+      objScreen.getByRole('combobox', { name: '状态' }),
+      'page-form-option-1'
+    )
+    await userEvent.click(objScreen.getByRole('button', { name: '创建模型' }))
+
+    expect(fnSubmit).toHaveBeenCalledOnce()
+    expect(fnSubmit).toHaveBeenCalledWith(
+      { strName: 'GPT Test', strStatus: 'offline' },
+      expect.objectContaining({ formType: 'add' })
+    )
+  })
+
+  it('localizes default actions, feedback and validation messages', async () => {
+    const objScreen = await render(
+      <LocaleProvider strLocale='en-US' strTimeZone='UTC'>
+        <PageForm
+          model={{ strName: '' }}
+          config={{
+            onAdd: () => undefined,
+            formItems: [
+              {
+                label: 'Name',
+                prop: 'strName',
+                required: true,
+              },
+            ],
+          }}
+        />
+      </LocaleProvider>
+    )
+
+    await expect
+      .element(objScreen.getByRole('button', { name: 'Confirm' }))
+      .toBeVisible()
+    await expect
+      .element(objScreen.getByRole('button', { name: 'Reset' }))
+      .toBeVisible()
+
+    await userEvent.click(objScreen.getByRole('button', { name: 'Confirm' }))
+    await expect
+      .element(objScreen.getByRole('alert'))
+      .toHaveTextContent('Name is required')
+  })
+
+  it('keeps form-level message overrides above Locale defaults', async () => {
+    const objScreen = await render(
+      <LocaleProvider strLocale='en-US' strTimeZone='UTC'>
+        <PageForm
+          model={{ strName: '' }}
+          config={{
+            messages: { strConfirm: 'Apply changes' },
+            formItems: [],
+          }}
+        />
+      </LocaleProvider>
+    )
+
+    await expect
+      .element(objScreen.getByRole('button', { name: 'Apply changes' }))
+      .toBeVisible()
+    await expect
+      .element(objScreen.getByRole('button', { name: 'Reset' }))
+      .toBeVisible()
+  })
+})

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

@@ -0,0 +1,74 @@
+import { describe, expect, it, vi } from 'vitest'
+import { createPageFormController } from '@/components/AppPageForm/controller'
+import type { IFormProp } from '@/components/AppPageForm/types'
+
+interface ITestFormModel {
+  strName: string
+}
+
+describe('PageForm core controller', () => {
+  it('tracks fields against the external or successfully submitted baseline', async () => {
+    const objController = createPageFormController<ITestFormModel>(
+      {
+        onAdd: () => undefined,
+        formItems: [{ label: '名称', prop: 'strName' }],
+      },
+      { strName: '初始名称' },
+      'add'
+    )
+
+    expect(objController.getSnapshot()).toMatchObject({
+      isDirty: false,
+      dirtyFields: [],
+    })
+    objController.updateField('strName', '修改后')
+    expect(objController.getSnapshot()).toMatchObject({
+      isDirty: true,
+      dirtyFields: ['strName'],
+    })
+    objController.updateField('strName', '初始名称')
+    expect(objController.hasDirtyChanges()).toBe(false)
+
+    objController.updateField('strName', '已保存名称')
+    await expect(objController.submit()).resolves.toMatchObject({
+      status: 'success',
+    })
+    expect(objController.hasDirtyChanges()).toBe(false)
+    objController.updateField('strName', '再次修改')
+    objController.reset()
+    expect(objController.getSnapshot()).toMatchObject({
+      model: { strName: '已保存名称' },
+      isDirty: false,
+      dirtyFields: [],
+    })
+  })
+
+  it('prevents duplicate submissions while the first handler is running', async () => {
+    let fnResolveSubmit: () => void = () => undefined
+    const objSubmitGate = new Promise<void>((fnResolve) => {
+      fnResolveSubmit = fnResolve
+    })
+    const fnOnAdd = vi.fn(() => objSubmitGate)
+    const objConfig: IFormProp<ITestFormModel> = {
+      onAdd: fnOnAdd,
+      formItems: [{ label: '名称', prop: 'strName', required: true }],
+    }
+    const objController = createPageFormController(
+      objConfig,
+      { strName: 'GPT Test' },
+      'add'
+    )
+
+    const objFirstSubmission = objController.submit()
+    await vi.waitFor(() => expect(fnOnAdd).toHaveBeenCalledOnce())
+
+    await expect(objController.submit()).resolves.toMatchObject({
+      status: 'busy',
+    })
+    fnResolveSubmit()
+    await expect(objFirstSubmission).resolves.toMatchObject({
+      status: 'success',
+      model: { strName: 'GPT Test' },
+    })
+  })
+})