# OpenSpec Change: enterprise-react-admin-forms

- **Change ID**: enterprise-react-admin-forms
- **Package**: `@suaveplan/react-admin-forms`
- **Category**: react
- **Target path**: `react/forms/react-admin-forms`
- **Status**: PROPOSED
- **Date**: 2026-04-24
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-admin-forms.md`

---

## Summary

Deliver `@suaveplan/react-admin-forms` on genesis from scratch at enterprise quality. Comprehensive admin-panel form library: ~30 domain forms across auth, content moderation, events, finance, notifications, payments, security, subscriptions, tenants, users, vaults, and store — all built on React Hook Form + Zod + `@suaveplan/api-schemas`. Ships accessibility-first shared components (`Accessible*` family), `AdminFormsProvider`, `formStorage` abstraction, and per-form Zod schemas. Genesis adds missing form component tests, missing domain stories (events, payment, subscription, tenant, vault, store), removes the `react-translate.mock.ts` mock, and adds Playwright E2E for the auth form suite.

---

## Current-state audit (genesis)

Package does not exist on genesis — fresh build.

---

## Available workspace deps on genesis

| Package | Role |
|---|---|
| `@suaveplan/error` (`workspace:^`) | `AdminFormError` |
| `@suaveplan/api-schemas` (`workspace:^`) | Shared API schemas |
| `@suaveplan/react-forms` (`workspace:^`) | Base form primitives |
| `@suaveplan/react-translate` (`workspace:^`) | i18n (real, no mocks) |
| `@suaveplan/react-ui` (`workspace:^`) | UI primitives |
| `zod` (`catalog:forms`) | Per-form schemas |

External: `@hookform/resolvers catalog:forms`, `lucide-react catalog:ui`, `react-hook-form catalog:forms`, `tslib catalog:build`. React 18 peer.

---

## Preserved public API surface

### Auth forms

`LoginForm`, `RegisterForm`, `ResetPasswordForm`, `ChangePasswordForm`, `SessionForm`, `UpdateProfileForm`, `UserManagementForm`, `AccountLinkingForm`

### Content forms

`EventLoggingForm`, `MessageModerationForm`, `PostModerationForm`

### Other domain forms

`EventForm`, `RsvpForm`, `BankAccountForm`, `DeviceTokenForm`, `NotificationConfigForm`, `PushNotificationForm`, `PaymentIntentForm`, `RefundForm`, `RoleManagementForm`, `SiteSecurityForm`, `SubscriptionForm`, `TenantForm`, `FriendManagementForm`, `GroupManagementForm`, `UserSettingsForm`, `VaultForm`, `VaultItemForm`, `ProductForm`

### Shared components

13 `Accessible*` primitives, `AdminFormsProvider`, `formStorage`

---

## New additions for genesis

1. **Form component tests** — `.test.tsx` for every form component (not just schemas).
2. **Complete Storybook coverage** — events, payment, subscription, tenant, vault, store forms.
3. **Real `@suaveplan/react-translate`** — no `react-translate.mock.ts`; tests use real provider.
4. **`AdminFormError`** — codes: `ADMIN_FORM_SUBMIT_FAILED`, `ADMIN_FORM_VALIDATION_FAILED`, `ADMIN_FORM_STORAGE_FAILED`.
5. **Playwright E2E** — full auth form suite (login, register, password reset).

---

## File layout

```text
react/forms/react-admin-forms/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    core/
      context/ (AdminFormsProvider)
      storage/ (formStorage — localStorage/sessionStorage/IndexedDB)
    shared/
      components/ (13 Accessible* components)
    auth/ content/ events/ finance/ notifications/
    payment/ security/ subscription/ tenant/ users/ vault/ store/
    (each domain: forms/ + schemas/ + types/)
  tests/
    integration.test.tsx
  e2e/
    auth-forms.spec.ts
```