# 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
```