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