docs(20): finalize phase plan (state, roadmap waves, patterns)

.planning/ROADMAP.md

@@ -762,7 +762,11 @@ Plans:
 **Plans:** 3 plans
 
 Plans:
+**Wave 1**
 
 - [ ] 20-01-PLAN.md — Server: PATCH /api/admin/members/:id (displayName + is_admin) with last-admin demotion guard (TDD) + isAdmin in GET /members
 - [ ] 20-02-PLAN.md — PWA API client: AdminMember.isAdmin field + updateMemberProfile fetcher (last-admin sentinel)
+
+**Wave 2** *(blocked on Wave 1 completion)*
+
 - [ ] 20-03-PLAN.md — PWA: unified MemberEditorSheet (edit/create, per-section saves) + decluttered tappable Members panel; retire Rotate/Reset-password buttons

.planning/STATE.md

@@ -5,8 +5,8 @@ milestone_name: Operability & Polish
 current_phase: 18
 current_phase_name: Auto timezone detection and ability to change timezone
 status: executing
-stopped_at: Phase 20 context gathered
+stopped_at: Phase 20 UI-SPEC approved
-last_updated: "2026-06-18T20:42:23.831Z"
+last_updated: "2026-06-18T21:06:24.292Z"
 last_activity: 2026-06-18
 last_activity_desc: Phase 17 complete, transitioned to Phase 18
 progress:
@@ -30,7 +30,7 @@ See: .planning/PROJECT.md (updated 2026-06-16)
 
 Phase: 18 — Auto timezone detection and ability to change timezone
 Plan: Not started
-Status: Executing Phase 17
+Status: Ready to execute
 Last activity: 2026-06-18 — Phase 17 complete, transitioned to Phase 18
 
 ### ✅ Resolved Checkpoint — Phase 15 Plan 15-03 Task 2 (human-action)
@@ -274,9 +274,9 @@ Recent decisions affecting current work:
 
 ## Session Continuity
 
-Last session: 2026-06-18T20:42:23.817Z
+Last session: 2026-06-18T20:51:46.755Z
-Stopped at: Phase 20 context gathered
+Stopped at: Phase 20 UI-SPEC approved
-Resume file: .planning/phases/20-admin-member-editor-form-declutter/20-CONTEXT.md
+Resume file: .planning/phases/20-admin-member-editor-form-declutter/20-UI-SPEC.md
 
 ## Operator Next Steps
 

.planning/phases/20-admin-member-editor-form-declutter/20-PATTERNS.md

@@ -0,0 +1,276 @@
+# Phase 20: Admin Member Editor & Form Declutter - Pattern Map
+
+**Mapped:** 2026-06-18
+**Files analyzed:** 5 (2 new surfaces, 3 modified)
+**Analogs found:** 5 / 5 (all in-repo, recent)
+
+> No RESEARCH.md for this phase — this is a client-side rework over existing `/api/admin` endpoints. Every new file copies a concrete in-repo analog; no external pattern is needed.
+
+---
+
+## File Classification
+
+| New/Modified File | Role | Data Flow | Closest Analog | Match Quality |
+|-------------------|------|-----------|----------------|---------------|
+| `apps/pwa/src/components/MemberEditorSheet.tsx` (NEW) | component (dialog/sheet) | request-response (form → mutation) | `apps/pwa/src/components/CredentialSheet.tsx` + `ResetPasswordSheet` (in `AdminPage.tsx`) | exact |
+| `apps/api/src/routes/admin.ts` — new `PATCH /members/:id` (NEW route, MODIFIED file) | route (member-profile update) | CRUD (update) | `admin.ts` `POST /members/:id/password` (`:225`) + last-admin count in `auth/user.ts:151` | exact |
+| `apps/pwa/src/routes/AdminPage.tsx` (MODIFIED) | route/page (MemberRow + triggers) | request-response | `ListCard.tsx` (tappable row + ChevronRight) + existing `MemberRow` (`:1151`) | exact |
+| `apps/pwa/src/api/client.ts` (MODIFIED) | api client (type + fetcher) | request-response | `fetchAdminResetPassword` (`:218`) / `fetchCreateMember` (`:184`) | exact |
+| `apps/api/src/routes/admin.ts` — `GET /members` adds `isAdmin` (MODIFIED) | route | CRUD (read) | `admin.ts` `GET /members` (`:102`) | exact (same handler) |
+
+---
+
+## Pattern Assignments
+
+### `apps/pwa/src/components/MemberEditorSheet.tsx` (component, dialog/sheet)
+
+**Primary analog:** `apps/pwa/src/components/CredentialSheet.tsx`
+**Secondary analog:** `ResetPasswordSheet` inside `apps/pwa/src/routes/AdminPage.tsx:1391` (password+confirm+mismatch logic to fold into the "Set new password" section per D-06).
+
+This is the central new file. Copy the **entire dialog scaffold** from CredentialSheet, then compose the three edit-mode sections (Profile / Set new password / App password) + the create-mode form from existing field/mutation snippets.
+
+**Imports pattern** (`CredentialSheet.tsx:25-35`):
+```typescript
+import { useState, useEffect, useRef, useCallback } from 'react';
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { Loader2 } from 'lucide-react';
+import {
+  saveCredential,
+  type SaveCredentialPayload,
+} from '../api/client.js';
+import { useIsPhone } from '../hooks/useIsPhone.js';
+import { useFocusTrap } from '../hooks/useFocusTrap.js';
+```
+For Phase 20 also import the new `updateMemberProfile` fetcher + existing `fetchAdminResetPassword`, and add `ChevronRight`/`Plus` are NOT needed here (those go in AdminPage).
+
+**`mode` prop pattern** — model the create/edit discriminator on `CredentialSheetMode` (`CredentialSheet.tsx:37`). UI-SPEC §Surface B wants a single `mode: 'edit' | 'create'` prop (id present = edit). Mirror the `headingFor(mode)` switch (`CredentialSheet.tsx:54-58`) for "Edit member" / "Add member" copy.
+
+**Dialog scaffold — copy verbatim** (`CredentialSheet.tsx`):
+- `useFocusTrap(dialogRef)` wiring (`:88-89`) + `onKeyDown={handleDialogKeyDown}` on the dialog div (`:186`)
+- `handleClose` via `useCallback` that clears form state, calls `onClose()`, and returns focus to `triggerRef.current` (`:94-103`)
+- Escape-to-close effect (`:106-115`)
+- Focus-heading-on-open effect (`:118-122`)
+- Backdrop div (`:169-178`) — note UI-SPEC §Surface B wants `rgba(0,0,0,0.32)` / `--color-overlay`, which matches `ResetPasswordSheet:1459` (`var(--color-overlay, rgba(0,0,0,0.32))`), NOT CredentialSheet's `rgba(0,0,0,0.4)`. Prefer the ResetPasswordSheet overlay token.
+- Phone-vs-desktop sheet style object (`:187-217`) — copy exactly (borderRadius `12px 12px 0 0` phone / `12px` desktop, `maxWidth 480px`, zIndex 301, `padding var(--space-6)`, desktop `maxHeight: calc(100dvh - var(--space-8)); overflowY: auto`)
+- `h2 ref={headingRef} tabIndex={-1}` heading (`:220-233`)
+- Member subtitle block (`:236-247`) — edit mode only
+
+**Section divider** (UI-SPEC §Surface B): `border-top: 1px solid var(--color-border-subtle)`, `margin: var(--space-6) 0`. Section headings reuse `sectionLabelStyle` from `AdminPage.tsx:46-53` (13px/600/uppercase/`--color-text-muted`) — UI-SPEC Accessibility note says use `<div>` not `<h3>` to avoid heading-hierarchy issues under the `<h2>`.
+
+**Text input field pattern** (`CredentialSheet.tsx:250-283` email field; `AdminPage.tsx:477-495` display-name field) — label (13px/600) + input (`min-height 44px`, `border-radius var(--space-1)`, `padding var(--space-3) var(--space-4)`, `border` flips to `--color-destructive` on error).
+
+**Password section (Section 2)** — copy `ResetPasswordSheet`'s new-password + confirm fields and mismatch logic:
+```typescript
+// AdminPage.tsx:1426-1443 — mutation with client-side mismatch guard
+const resetMutation = useMutation({
+  mutationFn: async () => {
+    if (newPassword !== confirmPassword) throw new Error('mismatch');
+    await fetchAdminResetPassword(member.id, newPassword);
+  },
+  onSuccess: () => { handleClose(); onSuccess?.(); },
+  onError: (err) => {
+    const msg = err instanceof Error ? err.message : 'server';
+    if (msg === 'mismatch') setError('Passwords do not match.');
+    else setError('Something went wrong. Please try again.');
+  },
+});
+```
+UI-SPEC adds a `< 8 chars` guard ("Password must be at least 8 characters.") — mirror the create-member length check at `AdminPage.tsx:267-269`. Fields use `autoComplete="new-password"`, never prefilled (T-10-15/16). **Per-section** save (not handleClose-on-success) — Section 2 success keeps the sheet open and fires toast "Password updated." Only render this section when `member.hasLocalCredential === true`.
+
+**App-password section (Section 3)** — copy CredentialSheet's email + password fields (`:249-320`), the "Validating against CalDAV…" `Loader2` inline state (`:337-345`), the helper link to Fastmail device tokens (`:351-362`), and the FAILURE_TEXT copy (`:65-66`). The mutation maps to `saveCredential` (`:124-153`) — admin mode requires `userId: memberId`. Prefill `fastmailEmail` read-only convenience in edit mode (Claude's-discretion D — the stored `fastmailEmail` exists on `memberCredentials.fastmail_email`, but is NOT currently returned by `GET /members`; the password field is never prefilled).
+
+**Create-mode form (single form, no dividers)** — copy the four fields + mutation from `AdminPage.tsx:260-306` (`createMemberMutation`): display name / username / initial password / confirm. Maps to `fetchCreateMember` (`client.ts:184`). Reuse the exact error mapping (`mismatch` / `short` / `conflict` → "That username is already in use.").
+
+**Per-section Save button** (`CredentialSheet.tsx:397-419`): accent `--color-member-0` background when enabled, `--color-border` when disabled, white text, `min-height 44px`, `border-radius var(--space-1)`, inline `Loader2 size={14}` while pending (pattern at `AdminPage.tsx:651-657`).
+
+**Cancel button** (`CredentialSheet.tsx:375-395`): no background, `--color-text-secondary`, `min-height 44px`.
+
+---
+
+### `apps/api/src/routes/admin.ts` — NEW `PATCH /members/:id` (route, CRUD update)
+
+**Primary analog:** `POST /members/:id/password` (`admin.ts:225-269`) — same `:id` param shape, same `requireAdmin` boundary, same noEchoHook posture, same existence-check-then-update flow.
+**Secondary analog:** the admin-count query in `auth/user.ts:151-156` — reuse for the D-03 last-admin guard.
+
+**Route handler shape — copy** (`admin.ts:225-269`):
+```typescript
+const updateMemberSchema = z.object({
+  displayName: z.string().min(1).max(256).optional(),
+  isAdmin: z.boolean().optional(),
+});
+
+adminRouter.patch(
+  '/members/:id',
+  zValidator('json', updateMemberSchema, noEchoHook),
+  async (c) => {
+    const targetId = parsePositiveIntParam(c.req.param('id')); // :87
+    if (targetId === null) return c.json({ error: 'Invalid member id' }, 400);
+    const { displayName, isAdmin } = c.req.valid('json');
+    // ... existence check + last-admin guard + update
+  },
+);
+```
+- `parsePositiveIntParam` already exists (`admin.ts:87-92`) — reuse, do NOT re-implement.
+- `requireAdmin` is already mounted router-wide (`admin.ts:47`) — the new route inherits it automatically; **no new boundary** (D-02).
+- `noEchoHook` (`admin.ts:75-79`) — apply even though no password is in this body, for consistency with the other admin write routes.
+
+**Last-admin guard (D-03) — adapt from `auth/user.ts:151-156`:**
+```typescript
+// Count remaining admins; reject demotion of the only admin.
+const [{ count }] = await db
+  .select({ count: sql<number>`COUNT(*)` })
+  .from(users)
+  .where(eq(users.isAdmin, true))
+  .limit(1);
+```
+When `isAdmin === false` is requested for a target that is currently an admin AND `Number(count) <= 1`, return 409 (or 422) `{ error: ... }`. UI-SPEC client maps this to "Cannot remove admin — at least one admin must remain." Note: `sql` and `eq` are already imported (`admin.ts:28`).
+
+**Update + error handling** — mirror the try/catch + 503 fallback of the password route (`admin.ts:249-268`). Build a partial `set({ ... })` from whichever of `displayName` / `isAdmin` is present. Verify the target user exists (404 if not), matching the password route's `if (!credRow) return 404` shape (`:245`).
+
+**Verb choice (Claude's discretion, D-02):** Hono supports `adminRouter.patch(...)`. The repo's existing admin writes use `POST` (`/members`, `/credentials`) and `PUT` (`/calendars/:id/shared`, `/config/timezone`); a `PATCH` for partial member update is idiomatic and consistent with REST, but `POST /members/:id` is equally acceptable — planner's call.
+
+---
+
+### `apps/api/src/routes/admin.ts` — `GET /members` adds `isAdmin` (route, CRUD read)
+
+**Analog:** the existing handler itself (`admin.ts:102-124`). Add `isAdmin` to the select and the mapped object:
+```typescript
+.select({
+  id: users.id,
+  displayName: users.displayName,
+  color: users.color,
+  isAdmin: users.isAdmin,            // NEW — feeds the editor toggle initial state (D-02)
+  credentialId: memberCredentials.id,
+  localCredId: localCredentials.id,
+})
+// ...
+const members = rows.map((row) => ({
+  id: row.id,
+  displayName: row.displayName,
+  color: row.color,
+  isAdmin: row.isAdmin,              // NEW
+  hasCredential: row.credentialId !== null,
+  hasLocalCredential: row.localCredId !== null,
+}));
+```
+`users.isAdmin` already exists in the schema (`db/schema.ts:56`, `boolean('is_admin')`). No join change needed — it's a column on the base `users` table already in the FROM.
+
+---
+
+### `apps/pwa/src/api/client.ts` (api client — type + fetcher)
+
+**Analog for the type:** `AdminMember` interface (`client.ts:563-569`). Add `isAdmin: boolean`:
+```typescript
+export interface AdminMember {
+  id: number;
+  displayName: string | null;
+  color: string;
+  isAdmin: boolean;        // NEW — Phase 20 (drives editor admin toggle initial state)
+  hasCredential: boolean;
+  hasLocalCredential: boolean;
+}
+```
+
+**Analog for the new fetcher:** `fetchAdminResetPassword` (`client.ts:218-234`) — same `:id` path, same POST/PATCH-with-json shape, same error handling. New `updateMemberProfile`:
+```typescript
+export async function updateMemberProfile(
+  memberId: number,
+  body: { displayName?: string; isAdmin?: boolean },
+): Promise<void> {
+  const res = await fetch(`/api/admin/members/${memberId}`, {
+    method: 'PATCH',                                   // match the chosen route verb
+    headers: { 'Content-Type': 'application/json' },
+    credentials: 'include',
+    redirect: 'manual',
+    body: JSON.stringify(body),
+  });
+  if (res.type === 'opaqueredirect' || res.status === 401) throw new SessionExpiredError();
+  if (res.status === 409 || res.status === 422) throw new Error('last-admin'); // D-03 guard
+  if (!res.ok) throw new Error(`updateMemberProfile failed: ${res.status}`);
+}
+```
+The `SessionExpiredError` + `handleAuthResponse` conventions are already in this file (used by every fetcher). Map the last-admin 409/422 to a sentinel the editor's onError can branch on (mirrors the `conflict` sentinel pattern at `client.ts:206`).
+
+---
+
+### `apps/pwa/src/routes/AdminPage.tsx` (route/page — MemberRow rework + triggers)
+
+**MemberRow → tappable row analog:** `apps/pwa/src/components/ListCard.tsx` — a whole-row `<button>`/tappable surface with a trailing `ChevronRight`.
+
+**ChevronRight affordance — copy** (`ListCard.tsx:139-144`):
+```typescript
+<ChevronRight
+  size={16}
+  color="var(--color-text-muted)"
+  aria-hidden="true"
+  style={{ flexShrink: 0, marginLeft: 'var(--space-2)' }}
+/>
+```
+Import: `import { ChevronRight, Plus } from 'lucide-react';` (both already used elsewhere — `ListCard.tsx:21`, `ListsIndex.tsx:24`).
+
+**Row interaction (UI-SPEC §Surface A):** make the row `role="button"`, `aria-label="Edit {displayName}"`, `tabIndex={0}`, `cursor: pointer`, Enter/Space opens the editor. The existing `CalendarRadioRow` (`AdminPage.tsx:1298-1318`) is a good in-file template for the `role` + `onKeyDown` Enter/Space handler:
+```typescript
+onKeyDown={(e) => {
+  if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); onSelect(); }
+}}
+```
+
+**Keep** the avatar swatch (`AdminPage.tsx:1167-1176`, `var(--color-member-${colorIndex})`) and the credential status badge (`:1193-1235`, CheckCircle/AlertCircle "Credential set" / "No credential"). **Remove** the entire action-button cluster (`:1238-1285`: "Rotate"/"Add credential" + "Reset password").
+
+**New Admin badge (UI-SPEC §Surface A):** when `member.isAdmin`, render an inline "Admin" pill (12px/600, `--color-member-0` text on `--color-surface-dim`, `border-radius 4px`, `padding 2px 6px`) — same shape as the "Shared" badge in `ListCard.tsx:124-133`.
+
+**"Add member" trigger button (UI-SPEC §Surface A):** ghost button with `<Plus size={16}>` prefix, `1px solid var(--color-border)`, `border-radius 8px`, `padding var(--space-3) var(--space-4)`, `min-height 44px`, `--color-surface` bg / `--color-surface-dim` hover. The `Plus`-prefixed button pattern is at `CalendarShell.tsx:451-456`.
+
+**Sheet wiring & state** — replace the dual `CredentialSheet` + `ResetPasswordSheet` mounting (`AdminPage.tsx:1111-1137`) with a single `MemberEditorSheet`. Reuse the existing `triggerRef` capture pattern (`:252-258`, `openSheet`) so focus returns to the tapped row on close. Add an `addMemberTriggerRef` for the create-mode trigger (focus returns there on cancel, per UI-SPEC Interaction Contract).
+
+**Remove from this file:** the entire inline Add-member form (`:443-662`, the "Local Accounts" section body), the `ResetPasswordSheet` component definition (`:1375-1677`), and all create-form local state (`createDisplayName` … `createError`, `:94-98`) — these move into `MemberEditorSheet`.
+
+---
+
+## Shared Patterns
+
+### TanStack Query mutation + invalidation
+**Source:** `CredentialSheet.tsx:124-153` and `AdminPage.tsx` mutations.
+**Apply to:** every per-section save in `MemberEditorSheet`.
+```typescript
+const m = useMutation({
+  mutationFn: async () => { /* call client fetcher */ },
+  onSuccess: () => {
+    void queryClient.invalidateQueries({ queryKey: ['admin', 'members'] });
+    void queryClient.invalidateQueries({ queryKey: ['me'] }); // credential/app-password changes only
+    showToast('…');  // per-section toast; sheet STAYS open (per-section save model, D-05)
+  },
+  onError: (err) => { /* map sentinel → inline error string */ },
+});
+```
+Profile/password saves invalidate only `['admin','members']`; app-password save also invalidates `['me']` (needsProviderSetup refresh — `CredentialSheet.tsx:146-147`).
+
+### Success toast (D-08)
+**Source:** `AdminPage.tsx:66-76` (`showToast` + auto-dismiss effect) and the toast JSX (`:1068-1109`).
+**Apply to:** all editor saves. Keep `showToast` in `AdminPage` and pass an `onToast`/`onSuccess` callback into `MemberEditorSheet` (the way `ResetPasswordSheet` receives `onSuccess` at `AdminPage.tsx:1134`), OR lift the toast into the sheet — planner's call. Toast copy per UI-SPEC: "Profile saved." / "Password updated." / "App password saved." / "Member added."
+
+### Write-only password handling (T-10-15 / T-10-16)
+**Source:** `CredentialSheet.tsx:299-319` (app password), `AdminPage.tsx:1544-1563` (reset password).
+**Apply to:** every password/app-password field in the editor. Never prefill, `autoComplete="new-password"`, never log, blank = unchanged (D-05).
+
+### Server admin boundary (no new boundary — D-02)
+**Source:** `apps/api/src/lib/requireAdmin.ts` + `admin.ts:47` (`adminRouter.use('*', requireAdmin)`).
+**Apply to:** the new `PATCH /members/:id` — it inherits the router-wide guard automatically. Do not add a second guard.
+
+### noEchoHook for admin write routes
+**Source:** `admin.ts:75-79`.
+**Apply to:** the new member-profile route's `zValidator`.
+
+---
+
+## No Analog Found
+
+None. Every new file and route has a direct, recent in-repo analog. The only genuinely new logic is the **D-03 last-admin guard**, and even that adapts the existing admin-count query from `apps/api/src/auth/user.ts:151-156`.
+
+---
+
+## Metadata
+
+**Analog search scope:** `apps/pwa/src/components/`, `apps/pwa/src/routes/`, `apps/pwa/src/api/`, `apps/pwa/src/hooks/`, `apps/api/src/routes/`, `apps/api/src/lib/`, `apps/api/src/auth/`, `apps/api/src/db/`
+**Files scanned:** ~12
+**Pattern extraction date:** 2026-06-18