Initial Commit
This commit is contained in:
96
openspec/changes/enterprise-react-contacts/proposal.md
Normal file
96
openspec/changes/enterprise-react-contacts/proposal.md
Normal file
@@ -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
|
||||
```
|
||||
111
openspec/changes/enterprise-react-contacts/tasks.md
Normal file
111
openspec/changes/enterprise-react-contacts/tasks.md
Normal file
@@ -0,0 +1,111 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user