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

// 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

ContactsUiError — codes: CONTACTS_LOAD_FAILED, CONTACTS_SAVE_FAILED, AUDIENCE_RESOLVE_FAILED.
Full test coverage — ContactDetail, GroupMembershipPanel, useAudienceResolver all tested (main branch had zero coverage for these three).
Configurable tree indentation — --contacts-tree-indent CSS variable + indentPx prop on GroupTreeEditor.
ContactsErrorBoundary — exported wrapper via @suaveplan/react-error-boundary.
Virtualized ContactList — uses @suaveplan/react-virtual for > 500 rows.
OTel counters — contacts.create, contacts.update, contacts.delete, contacts.search, groups.rename, audience.resolve.
Playwright E2E — list filter + pagination, tree expand/collapse/rename, membership add/remove, audience preview, keyboard-only, mobile viewport.

File layout

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

3.7 KiB Raw Blame History