Рецепт: доступное модальное окно на React

import { useEffect, useId, useRef, type ReactNode } from 'react'
import './Modal.css'

type ModalProps = {
  open: boolean
  onClose: () => void
  title: string
  description?: string
  closeOnBackdrop?: boolean
  closeLabel?: string
  children: ReactNode
}

export function Modal({
  open,
  onClose,
  title,
  description,
  closeOnBackdrop = true,
  closeLabel = 'Закрыть',
  children,
}: ModalProps) {
  const dialogRef = useRef<HTMLDialogElement>(null)
  const pressedOnBackdrop = useRef(false)
  const titleId = useId()
  const descriptionId = useId()

  useEffect(() => {
    const dialog = dialogRef.current
    if (!open || !dialog) return

    dialog.showModal() // верхний слой, ::backdrop, страница под окном становится inert
    dialog.querySelector<HTMLElement>('[data-autofocus]')?.focus()

    // close() возвращает фокус элементу, который был в фокусе до showModal()
    return () => dialog.close()
  }, [open])

  return (
    <dialog
      ref={dialogRef}
      className="modal"
      aria-labelledby={titleId}
      aria-describedby={description ? descriptionId : undefined}
      // любое закрытие (Esc, кнопка, подложка, form method="dialog") приходит сюда
      onClose={onClose}
      onPointerDown={(event) => {
        pressedOnBackdrop.current = event.target === event.currentTarget
      }}
      onClick={(event) => {
        // клик по подложке: и нажатие, и отпускание — вне содержимого окна
        if (closeOnBackdrop && pressedOnBackdrop.current && event.target === event.currentTarget) {
          event.currentTarget.close()
        }
      }}
    >
      <div className="modal__body">
        <div className="modal__header">
          <h2 id={titleId} className="modal__title">
            {title}
          </h2>
          <button
            type="button"
            className="modal__close"
            aria-label={closeLabel}
            onClick={() => dialogRef.current?.close()}
          >
            ×
          </button>
        </div>
        {description && <p id={descriptionId}>{description}</p>}
        {children}
      </div>
    </dialog>
  )
}

.modal {
  width: min(32rem, calc(100vw - 2rem));
  max-height: calc(100dvh - 2rem);
  padding: 0; /* отступы — у .modal__body, чтобы клик по самому <dialog> означал подложку */
  border: none;
  border-radius: 12px;
  background: #fff;
  color: #1a1a1a;
}

.modal::backdrop {
  background: rgb(0 0 0 / 0.5);
}

.modal__body {
  padding: 1.5rem;
}

.modal__header {
  display: flex;
  align-items: start;
  justify-content: space-between;
  gap: 1rem;
}

.modal__title {
  margin: 0;
  font-size: 1.25rem;
}

.modal__close {
  min-width: 44px;
  min-height: 44px;
  border: none;
  background: transparent;
  font-size: 1.5rem;
  cursor: pointer;
}

/* блокировка прокрутки страницы, пока открыто модальное окно */
:root:has(.modal:modal) {
  overflow: hidden;
}

/* анимация — только если пользователь не просил уменьшить движение */
@media (prefers-reduced-motion: no-preference) {
  .modal,
  .modal::backdrop {
    transition:
      opacity 200ms ease-out,
      transform 200ms ease-out,
      overlay 200ms ease-out allow-discrete,
      display 200ms ease-out allow-discrete;
  }

  .modal,
  .modal::backdrop {
    opacity: 0;
  }

  .modal {
    transform: translateY(8px);
  }

  .modal[open],
  .modal[open]::backdrop {
    opacity: 1;
    transform: none;
  }

  @starting-style {
    .modal[open],
    .modal[open]::backdrop {
      opacity: 0;
    }

    .modal[open] {
      transform: translateY(8px);
    }
  }
}

import { useState, type FormEvent } from 'react'
import { Modal } from './components/Modal'

export default function App() {
  const [open, setOpen] = useState(false)
  const [status, setStatus] = useState('')

  function handleSubmit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault()
    const phone = String(new FormData(event.currentTarget).get('phone'))
    // здесь — отправка заявки на сервер
    setStatus(`Заявка принята, перезвоним на ${phone}`)
    setOpen(false)
  }

  return (
    <main>
      <h1>Салон красоты</h1>
      <button type="button" onClick={() => setOpen(true)}>
        Записаться
      </button>
      <p role="status">{status}</p>

      <Modal
        open={open}
        onClose={() => setOpen(false)}
        title="Запись на приём"
        description="Оставьте телефон — администратор перезвонит и подберёт время."
      >
        <form onSubmit={handleSubmit}>
          <label htmlFor="phone">Телефон</label>
          <input id="phone" name="phone" type="tel" autoComplete="tel" required data-autofocus />
          <button type="submit">Отправить</button>
        </form>
      </Modal>
    </main>
  )
}

npm create vite@latest modal-demo -- --template react-ts
cd modal-demo
npm install
npm install -D vitest @vitest/browser-playwright @testing-library/react @testing-library/dom axe-core
npm install -D @playwright/test @axe-core/playwright
npx playwright install chromium firefox webkit

import react from '@vitejs/plugin-react'
import { playwright } from '@vitest/browser-playwright'
import { defineConfig } from 'vitest/config'

export default defineConfig({
  plugins: [react()],
  test: {
    include: ['src/**/*.test.tsx'],
    browser: {
      enabled: true,
      provider: playwright(),
      headless: true,
      instances: [{ browser: 'chromium' }],
    },
  },
})

import { cleanup, render, screen } from '@testing-library/react'
import axe from 'axe-core'
import { useState } from 'react'
import { afterEach, expect, test } from 'vitest'
import { page, userEvent } from 'vitest/browser'
import { Modal } from './Modal'

function Demo() {
  const [open, setOpen] = useState(false)
  return (
    <main>
      <button type="button" onClick={() => setOpen(true)}>
        Записаться
      </button>
      <Modal
        open={open}
        onClose={() => setOpen(false)}
        title="Запись на приём"
        description="Оставьте телефон — администратор перезвонит."
      >
        <label htmlFor="phone">Телефон</label>
        <input id="phone" type="tel" data-autofocus />
      </Modal>
    </main>
  )
}

afterEach(cleanup)

async function openModal() {
  render(<Demo />)
  const opener = screen.getByRole('button', { name: 'Записаться' })
  opener.focus() // открываем с клавиатуры: так проверяется возврат фокуса
  await userEvent.keyboard('{Enter}')
  const dialog = screen.getByRole<HTMLDialogElement>('dialog', { name: 'Запись на приём' })
  return { opener, dialog }
}

test('открывается модально, с подписью, описанием и фокусом внутри', async () => {
  const { dialog } = await openModal()
  expect(dialog.matches(':modal')).toBe(true)
  expect(dialog).toHaveAccessibleDescription('Оставьте телефон — администратор перезвонит.')
  expect(document.activeElement).toBe(screen.getByLabelText('Телефон'))
  expect(getComputedStyle(document.documentElement).overflow).toBe('hidden')
})

test('Esc закрывает окно и возвращает фокус на кнопку', async () => {
  const { opener, dialog } = await openModal()
  await userEvent.keyboard('{Escape}')
  await expect.poll(() => dialog.open).toBe(false)
  await expect.poll(() => document.activeElement).toBe(opener)
  expect(getComputedStyle(document.documentElement).overflow).not.toBe('hidden')

  // состояние React синхронизировано: окно открывается повторно
  await userEvent.keyboard('{Enter}')
  expect(dialog.open).toBe(true)
})

test('кнопка «Закрыть» закрывает окно', async () => {
  const { opener, dialog } = await openModal()
  await userEvent.click(screen.getByRole('button', { name: 'Закрыть' }))
  await expect.poll(() => dialog.open).toBe(false)
  expect(document.activeElement).toBe(opener)
})

test('клик по подложке закрывает, клик внутри — нет', async () => {
  const { dialog } = await openModal()
  await userEvent.click(screen.getByText('Оставьте телефон — администратор перезвонит.'))
  expect(dialog.open).toBe(true)

  // точка в 10 px левее и выше окна — это ::backdrop
  await userEvent.click(page.elementLocator(dialog), { position: { x: -10, y: -10 } })
  await expect.poll(() => dialog.open).toBe(false)
})

test('axe: нарушений доступности в открытом окне нет', async () => {
  const { dialog } = await openModal()
  // ждём конца анимации появления: на полупрозрачном тексте axe видит плохой контраст
  await Promise.all(dialog.getAnimations({ subtree: true }).map((animation) => animation.finished))
  const results = await axe.run(dialog)
  expect(results.violations).toEqual([])
})

import { defineConfig, devices } from '@playwright/test'

export default defineConfig({
  testDir: './e2e',
  use: { baseURL: 'http://localhost:5180' },
  webServer: { command: 'npm run dev -- --port 5180 --strictPort', url: 'http://localhost:5180' },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
  ],
})

import { AxeBuilder } from '@axe-core/playwright'
import { expect, test } from '@playwright/test'

test.beforeEach(async ({ page }) => {
  await page.goto('/')
})

test('клавиатура: фокус внутрь, Tab не уходит на страницу, Esc возвращает фокус', async ({ page }) => {
  const opener = page.getByRole('button', { name: 'Записаться' })
  await opener.focus()
  await page.keyboard.press('Enter')

  const dialog = page.getByRole('dialog', { name: 'Запись на приём' })
  await expect(dialog).toBeVisible()
  await expect(page.getByLabel('Телефон')).toBeFocused()

  for (let i = 0; i < 6; i++) {
    await page.keyboard.press('Tab')
    const leaked = await page.evaluate(() => {
      const active = document.activeElement
      return active !== null && active !== document.body && !document.querySelector('dialog')!.contains(active)
    })
    expect(leaked).toBe(false)
  }

  await page.keyboard.press('Escape')
  await expect(dialog).toBeHidden()
  await expect(opener).toBeFocused()
})

test('прокрутка страницы заблокирована, пока окно открыто', async ({ page }) => {
  await page.evaluate(() => (document.body.style.minHeight = '300vh'))
  await page.getByRole('button', { name: 'Записаться' }).click()
  await page.mouse.move(20, 20)
  await page.mouse.wheel(0, 600)
  await page.waitForTimeout(300)
  expect(await page.evaluate(() => window.scrollY)).toBe(0)

  await page.keyboard.press('Escape')
  await page.mouse.wheel(0, 600)
  await expect.poll(() => page.evaluate(() => window.scrollY)).toBeGreaterThan(0)
})

test('prefers-reduced-motion: reduce отключает переход', async ({ page }) => {
  const duration = () => page.locator('dialog').evaluate((el) => getComputedStyle(el).transitionDuration)
  expect(await duration()).not.toBe('0s')
  await page.emulateMedia({ reducedMotion: 'reduce' })
  expect(await duration()).toBe('0s')
})

test('форма: отправка закрывает окно и возвращает фокус', async ({ page }) => {
  const opener = page.getByRole('button', { name: 'Записаться' })
  await opener.focus()
  await page.keyboard.press('Enter')
  await page.getByLabel('Телефон').fill('+7 700 000 00 00')
  await page.keyboard.press('Enter')
  await expect(page.getByRole('dialog')).toBeHidden()
  await expect(page.getByRole('status')).toHaveText('Заявка принята, перезвоним на +7 700 000 00 00')
  await expect(opener).toBeFocused()
})

test('axe: страница с открытым окном без нарушений', async ({ page }) => {
  await page.getByRole('button', { name: 'Записаться' }).click()
  const dialog = page.getByRole('dialog', { name: 'Запись на приём' })
  await expect(dialog).toBeVisible()
  await dialog.evaluate((el) => Promise.all(el.getAnimations({ subtree: true }).map((a) => a.finished)))
  const results = await new AxeBuilder({ page }).analyze()
  expect(results.violations).toEqual([])
})

npx vitest run        # компонентные тесты в Chromium
npx playwright test    # сценарии в Chromium, Firefox и WebKit

import { useState } from 'react'
import { Modal } from './Modal'

export function CancelBookingButton({ onConfirm }: { onConfirm: () => void }) {
  const [open, setOpen] = useState(false)

  return (
    <>
      <button type="button" onClick={() => setOpen(true)}>
        Отменить запись
      </button>
      <Modal
        open={open}
        onClose={() => setOpen(false)}
        title="Отменить запись?"
        description="Время освободится, и его сможет занять другой клиент."
        closeOnBackdrop={false}
      >
        {/* фокус — на безопасное действие (рекомендация APG для необратимых шагов) */}
        <button type="button" data-autofocus onClick={() => setOpen(false)}>
          Оставить запись
        </button>
        <button
          type="button"
          onClick={() => {
            onConfirm()
            setOpen(false)
          }}
        >
          Да, отменить
        </button>
      </Modal>
    </>
  )
}