suaveplan/openspec/changes/enterprise-react-contacts/tasks.md

Tasks: enterprise-react-contacts

Change ID: enterprise-react-contacts Package: @suaveplan/react-contacts Target path: react/platform/react-contacts Prerequisite packages on Verdaccio: @suaveplan/error, @suaveplan/contacts, @suaveplan/react-translate, @suaveplan/react-virtual, @suaveplan/react-error-boundary

---

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
• 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

1. Scaffold

• Create directory tree. Write package.json at 0.1.0, tsconfig.json, vitest.config.ts, scripts.
• Dependencies: @suaveplan/error workspace:^, @suaveplan/contacts workspace:^, @suaveplan/react-translate workspace:^, @suaveplan/react-virtual workspace:^, @suaveplan/react-error-boundary workspace:^, @opentelemetry/api catalog:observability, zod catalog:forms, tslib catalog:build.

---

2. Error codes and types

• Define ContactsUiError; codes: CONTACTS_LOAD_FAILED, CONTACTS_SAVE_FAILED, AUDIENCE_RESOLVE_FAILED.
• Define all prop types: ContactDetailProps, ContactListProps, ContactTagInputProps, GroupMembershipPanelProps, GroupTreeEditorProps, UseContactsConfig, UseContactsResult, UseGroupsConfig, UseGroupsResult, UseGroupTreeResult, UseAudienceResolverConfig, UseAudienceResolverResult.

---

3. Hooks

useContacts

• CRUD + server search via ContactManager. OTel spans: contacts.create, contacts.update, contacts.delete, contacts.search. Zod-validates create/update payloads via @suaveplan/contacts schemas.
• Write use-contacts.test.ts (≤500 lines): CRUD, search, error states, Zod rejection. { timeout: 10000 }.
• Write use-contacts.md.

useGroups

• Group CRUD via ContactManager. OTel groups.rename counter.
• Write use-groups.test.ts (≤500 lines). { timeout: 10000 }.
• Write use-groups.md.

useGroupTree

• Converts flat group list to tree; maintains visible-node flattening for virtual rendering.
• Write test + md.

useAudienceResolver

• Resolves group → contact list with preview count. OTel audience.resolve span. Throws ContactsUiError(AUDIENCE_RESOLVE_FAILED) on engine error.
• Write use-audience-resolver.test.ts (≤500 lines): resolves contacts, count preview, error state. { timeout: 10000 }.
• Write use-audience-resolver.md.

---

4. Components

ContactsErrorBoundary

• Wrapper via @suaveplan/react-error-boundary; localised error message + retry button.
• Write test + md.

ContactTagInput

• Token-style tag input with autocomplete suggestions from useContacts. All labels via useTranslation.
• Write test, stories (default, with-suggestions, max-tags, playground), md.

GroupMembershipPanel

• Add/remove contacts in a group with membership count. All labels via useTranslation.
• Write group-membership-panel.test.tsx (≤500 lines): renders members, add fires useGroups, remove fires useGroups. { timeout: 5000 }.
• Write stories (default, empty, readonly, playground), md.

GroupTreeEditor

• Hierarchical tree with role="tree" / role="treeitem". Keyboard navigation: Up/Down/Left/Right/Home/End. indentPx prop + --contacts-tree-indent CSS variable. All labels via useTranslation.
• Write test, stories (default, deep-tree, collapsed, keyboard, playground), md.

ContactDetail

• Full contact view with tag-apply flow, group membership list, channel info. All labels via useTranslation.
• Write contact-detail.test.tsx (≤500 lines): renders contact fields, tag apply calls useContacts, group list renders. { timeout: 5000 }.
• Write stories (default, with-tags, with-groups, playground), md.

ContactList

• Virtualised via @suaveplan/react-virtual for >500 rows. Searchable (fuzzy on displayName/firstName/lastName), paginated. Select/edit/delete handlers. All labels via useTranslation.
• Write contact-list.test.tsx (≤500 lines): renders contacts, search filters list, virtualisation renders visible rows, pagination. { timeout: 10000 }.
• Write stories (default, filtered, large-dataset, empty, playground), md.

---

5. E2E

• e2e/contacts.spec.ts — Playwright:
  • Filter contact list by name; verify results narrow.
  • Expand and rename a group in GroupTreeEditor using keyboard.
  • Add a contact to a group via GroupMembershipPanel; verify count updates.
  • Resolve audience in AudienceSelector; verify preview count.
  • Navigate the full list and detail using keyboard only.
  • Verify mobile viewport single-column layout.

---

6. Verify and publish

• bunx turbo lint typecheck test --filter=@suaveplan/react-contacts — green.
• bunx turbo test:coverage --filter=@suaveplan/react-contacts — 100%.
• bun scripts/publish.ts --package @suaveplan/react-contacts.
• Archive change folder.