Initial Commit

openspec/changes/enterprise-react-contacts/proposal.md

@@ -0,0 +1,96 @@
+# OpenSpec Change: enterprise-react-contacts
+
+- **Change ID**: enterprise-react-contacts
+- **Package**: `@suaveplan/react-contacts`
+- **Category**: react
+- **Target path**: `react/platform/react-contacts`
+- **Status**: PROPOSED
+- **Date**: 2026-04-24
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-contacts.md`
+
+---
+
+## Summary
+
+Deliver `@suaveplan/react-contacts` on genesis from scratch at enterprise quality. React UI for `@suaveplan/contacts`: `ContactList` (searchable/paginated), `ContactDetail`, `ContactTagInput`, `GroupTreeEditor` (expand/collapse/rename/delete/add-child), `GroupMembershipPanel`, and four hooks (`useContacts`, `useGroups`, `useGroupTree`, `useAudienceResolver`). Genesis adds missing tests for `ContactDetail`, `GroupMembershipPanel`, and `useAudienceResolver` (main branch had zero coverage for these three), adds configurable tree indentation (CSS variable + prop), `ContactsErrorBoundary`, OTel counters, virtualized `ContactList` via `@suaveplan/react-virtual`, and Playwright E2E.
+
+---
+
+## Current-state audit (genesis)
+
+Package does not exist on genesis — fresh build.
+
+---
+
+## Available workspace deps on genesis
+
+| Package | Role |
+|---|---|
+| `@suaveplan/error` (`workspace:^`) | `ContactsUiError` |
+| `@suaveplan/contacts` (`workspace:^`) | Contact engine + schemas |
+| `@suaveplan/react-translate` (`workspace:^`) | i18n for all UI strings |
+| `@suaveplan/react-virtual` (`workspace:^`) | Virtualized `ContactList` |
+| `@suaveplan/react-error-boundary` (`workspace:^`) | `ContactsErrorBoundary` |
+| `@opentelemetry/api` (`catalog:observability`) | `contacts.*` counters + spans |
+| `zod` (`catalog:forms`) | Boundary validation |
+| `tslib` (`catalog:build`) | TS helpers |
+
+External: React 18 peer.
+
+---
+
+## Preserved public API surface
+
+```ts
+// Components
+ContactList, ContactDetail, ContactTagInput,
+GroupTreeEditor, GroupMembershipPanel, ContactsErrorBoundary
+
+// Hooks
+useContacts, useGroups, useGroupTree, useAudienceResolver
+
+// Types
+ContactDetailProps, ContactListProps, ContactTagInputProps,
+GroupMembershipPanelProps, GroupTreeEditorProps,
+UseContactsConfig, UseContactsResult,
+UseGroupsConfig, UseGroupsResult,
+UseGroupTreeResult,
+UseAudienceResolverConfig, UseAudienceResolverResult
+```
+
+---
+
+## New additions for genesis
+
+1. **`ContactsUiError`** — codes: `CONTACTS_LOAD_FAILED`, `CONTACTS_SAVE_FAILED`, `AUDIENCE_RESOLVE_FAILED`.
+2. **Full test coverage** — `ContactDetail`, `GroupMembershipPanel`, `useAudienceResolver` all tested (main branch had zero coverage for these three).
+3. **Configurable tree indentation** — `--contacts-tree-indent` CSS variable + `indentPx` prop on `GroupTreeEditor`.
+4. **`ContactsErrorBoundary`** — exported wrapper via `@suaveplan/react-error-boundary`.
+5. **Virtualized `ContactList`** — uses `@suaveplan/react-virtual` for > 500 rows.
+6. **OTel counters** — `contacts.create`, `contacts.update`, `contacts.delete`, `contacts.search`, `groups.rename`, `audience.resolve`.
+7. **Playwright E2E** — list filter + pagination, tree expand/collapse/rename, membership add/remove, audience preview, keyboard-only, mobile viewport.
+
+---
+
+## File layout
+
+```text
+react/platform/react-contacts/
+  package.json
+  tsconfig.json
+  vitest.config.ts
+  src/
+    index.ts
+    types/
+    components/
+      contact-list/ (tsx + types + md + test + stories + index)
+      contact-detail/ (tsx + types + md + test + stories + index)
+      contact-tag-input/ (tsx + types + md + test + stories + index)
+      group-tree-editor/ (tsx + types + md + test + stories + index)
+      group-membership-panel/ (tsx + types + md + test + stories + index)
+      contacts-error-boundary/ (tsx + types + md + test + index)
+    hooks/
+      use-contacts/ use-groups/ use-group-tree/ use-audience-resolver/
+  e2e/
+    contacts.spec.ts
+```