jpmschweitzerandClaude Opus 4.8
a99bd60974
Record the decomposition: ClideAnchoredOverlay is the shared base every anchored surface adopts; content matches the surface — ClideMenu for menus, a new ClideTypeahead for the slash/@ typeaheads, bespoke for quick-open and the theme picker. Re-scopes T-288 accordingly. The base blockers (focus race, follower untappable in the test harness) are what to fix first. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
3.5 KiB
3.5 KiB
Design Decisions
User-facing surface — UX, UI conventions, and the public shape of clide-owned widget primitives.
D-88: clide-owned anchored popover + menu primitive
- Date: 2026-06-08
- Decision: Anchored, non-modal popovers (dropdowns, pickers, typeaheads, the command palette) build on two clide-owned primitives in
lib/widgets/:ClideAnchoredOverlay(positioning + lifecycle — aLayerLink/CompositedTransformFolloweror centredPositioned, a full-screen tap-away barrier,OverlayEntrybookkeeping, focus capture, Esc-to-close, and auto-flip on viewport bounds) andClideMenu+ClideMenuListController(a dropdown-token row surface with arrow/enter/escape nav, skip-disabled/separator, active mark, and a reusable nav controller for surfaces that keep bespoke rows). No Material/Cupertino. Modal, centred dialogs (session / project / branch pickers) stay on the kernelDialogRouter— a separate concern. - Rationale: Nine surfaces had hand-rolled the same anchored-overlay + row-list + barrier + keyboard-nav pattern (menu-bar dropdowns, theme picker, slash + @ typeaheads, quick-open, three modal pickers), each re-deriving positioning, dismissal, and nav — divergent a11y, inconsistent dismissal, and a
pumpAndSettle-hostile spread of ad-hoc overlays. Owning one primitive (per "own the rendering stack", D-5) makes the behaviour uniform and testable once, and turns the tenth surface (the T-275 permission-mode picker) into a few lines instead of another hand-roll. - Cost: A migration sweep across the existing surfaces (menu bar, theme picker, typeaheads, quick-open); the typeaheads keep their text-completion/key pipeline and only delegate anchoring + body, so the primitive must stay composable (a bare lifecycle wrapper + an optional turnkey menu), not a monolith. New UI authors must reach for the primitive rather than rolling another overlay.
- Raised by: 2026-06-08 — user, while building the T-275 permission-mode picker: "since we don't do Material doesn't mean we can't make components of our own." Realises the "own the rendering stack" guardrail at the component level. Tracked by epic T-286.
- Amendment (2026-06-08): The shared piece is
ClideAnchoredOverlay(positioning + lifecycle) — that is what every anchored surface adopts. Content is NOT universallyClideMenu; it matches the surface's shape, to avoid bending divergent surfaces into a menu (the theme-picker migration was reverted for exactly this friction):ClideMenu— selectable-list menus only (menu bar, permission picker).ClideTypeahead(a second shared content component, to add) — the slash and @ typeaheads are near-duplicate caret-anchored completion surfaces; they share this, notClideMenu.- Quick-open / command palette — bespoke content (centred filter + fuzzy + two-column rows); uses only the
ClideAnchoredOverlaybase. - Theme picker — toggle + live-apply list; its own small content (or
ClideMenuif it ever fits cleanly), on the base. Revised goal: everything anchored sharesClideAnchoredOverlay; content components match the surface. The blockers to clear first (focus capture racing content autofocus; follower content untappable in thecanSizeOverlaytest harness) live in the base, not in any content component. Tracked by T-288. Raised by the user: "should those then not just be a different shared component from the others?"