81 lines
2.7 KiB
Markdown
81 lines
2.7 KiB
Markdown
# OpenSpec Change: enterprise-react-modal
|
|
|
|
- **Change ID**: enterprise-react-modal
|
|
- **Package**: `@suaveplan/react-modal`
|
|
- **Category**: react
|
|
- **Target path**: `react/ui/react-modal`
|
|
- **Status**: PROPOSED
|
|
- **Date**: 2026-04-24
|
|
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-modal.md`
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Deliver `@suaveplan/react-modal` on genesis from scratch at enterprise quality. A focused React modal/dialog system: base `Modal` (portal, focus-trap, ESC-close, focus-restoration), `Dialog` (title/actions slots), `ConfirmDialog` (confirm/cancel preset), and `ModalProvider`/`ModalContext` for stacked modals by ID. Every component uses `@suaveplan/react-translate` for i18n. Genesis adds Playwright real-browser focus-trap + scroll-lock tests, `@suaveplan/error`-backed `ModalError`, and OTel span events.
|
|
|
|
---
|
|
|
|
## Current-state audit (genesis)
|
|
|
|
Package does not exist on genesis — fresh build.
|
|
|
|
---
|
|
|
|
## Available workspace deps on genesis
|
|
|
|
| Package | Role |
|
|
|---|---|
|
|
| `@suaveplan/error` (`workspace:^`) | `ModalError` |
|
|
| `@suaveplan/react-translate` (`workspace:^`) | i18n default copy |
|
|
| `zod` (`catalog:forms`) | Props schemas |
|
|
| `@opentelemetry/api` (`catalog:observability`) | `modal.open` / `modal.close` span |
|
|
|
|
External: `tslib catalog:build`. React 18 peer.
|
|
|
|
---
|
|
|
|
## Preserved public API surface
|
|
|
|
```ts
|
|
Modal — portal + focus-trap + ESC close + scroll-lock + focus-restore
|
|
Dialog — title / description / actions slots on top of Modal
|
|
ConfirmDialog — confirm / cancel preset with onConfirm / onCancel callbacks
|
|
ModalContext — open(id, element) / close(id) / closeAll() / isOpen(id)
|
|
ModalProvider — stacked modal management
|
|
|
|
// Types
|
|
ModalProps, DialogProps, ConfirmDialogProps, ModalContextValue, ModalProviderProps
|
|
```
|
|
|
|
---
|
|
|
|
## New additions for genesis
|
|
|
|
1. **`ModalError`** with code `MODAL_CONTEXT_MISSING` (thrown when hooks used outside provider).
|
|
2. **OTel `modal.open` / `modal.close` span events** — attribute `modal.id`.
|
|
3. **Scroll-lock utility** (`disableBodyScroll` / `enableBodyScroll`) tested in isolation.
|
|
4. **Playwright E2E** — focus-trap cycling, ESC close, scroll-lock verification, stacked modals (open two, close inner, outer still open).
|
|
|
|
---
|
|
|
|
## File layout
|
|
|
|
```text
|
|
react/ui/react-modal/
|
|
package.json
|
|
tsconfig.json
|
|
vitest.config.ts
|
|
src/
|
|
index.ts
|
|
modal/ (tsx + types + md + test + stories + index)
|
|
dialog/ (tsx + types + md + test + stories + index)
|
|
confirm-dialog/ (tsx + types + md + test + stories + index)
|
|
modal-context/ (tsx + types + md + test + stories + index)
|
|
utils/
|
|
scroll-lock/ (ts + md + test + index)
|
|
focus-trap/ (ts + md + test + index)
|
|
e2e/
|
|
modal.spec.ts
|
|
```
|