Files

T

Carlos Florêncio 832734bb67 docs: migrate legacy specs and add product context (#2964 )

2026-08-24 11:09:03 +00:00

5.5 KiB

Raw Permalink Blame History

spec, created, status

spec	created	status
docs/specs/ui/requirements/settings-discovery.md	2026-08-05	completed

Implementation Plan: Settings Discovery

Overview

Build a dedicated first-party settings catalog, then consume it from tree search and search-only Cmd+K commands. Stable hash targets connect both surfaces to rendered controls. Work proceeds from pure catalog/search contracts through UI integration, coverage, localization, and production-build desktop/mobile E2E.

Frontend

Discovery catalog and search

Create apps/web/lib/settings-discovery/ with typed definitions, domain-split catalogs, dynamic resolution, deterministic Unicode-aware search, exclusions, and target/navigation helpers. Reuse catalog route metadata from general-nav.ts and Settings tree groups rather than retaining parallel deep-link lists.

Settings tree and exact targets

Add the sticky search/result UI to SettingsTree. Add a provider/registration protocol under components/settings/ that handles initial, delayed, repeated, soft-navigation, and browser-history targets independently of usePathname, whose snapshot deliberately excludes fragments. Cross-page links retain navigation-guard; same-page fragments bypass leave confirmation.

Command palette

Extend CommandItem with display context and search-only visibility. Generate granular commands from the catalog, preserve the existing top-level destination and legacy aliases, and load dynamic settings data only while the Commands palette is open. When a query is present, keep regular matches in Commands and render search-only catalog matches under their localized Settings group.

Coverage and localization

Index every canonical first-party settings page and stable inline control, with explicit exclusions for transient/generated/plugin-owned UI. Resolve all copy at render time, regenerate pseudo locale, and keep current values out of searchable terms.

Mobile design contract

Desktop outcome: search the permanent Settings tree and land on an exact control. Phone entry point: the existing SettingsMobileMenu full-height Sheet. Nearest shipped exemplar: components/kanban/mobile-menu-sheet.tsx contributes fixed-header/internal-scroll geometry, while the existing Settings Sheet remains because this is dense hierarchical navigation rather than a short temporary choice. Shared catalog/filter/target logic serves both. Navigation Sheet and page content each retain one existing scroll owner; controls are at least 44 px; the Sheet closes when selection completes. mobile-settings-discovery.spec.ts proves equivalent value and containment.

Tests

Pure catalog/search unit tests cover IDs, parents, targets, canonical routes, permissions, dynamic encoding, exact/prefix/alias/context ranking, Unicode, and exclusions.
Target-navigation tests cover initial/delayed/repeated hashes, same/cross-page routing, focus, highlight cleanup, history, and reduced motion.
Existing Settings-tree and command-panel tests cover unchanged normal state, search-only density, breadcrumbs, ranking, and stable late registration.

E2E tests

apps/web/e2e/tests/settings/settings-discovery.spec.ts: desktop tree filtering, exact landing, Escape/clear, history, and unsaved-navigation guard.
apps/web/e2e/tests/settings/mobile-settings-discovery.spec.ts: phone Sheet search, exact landing, 44 px targets, containment, one scroll owner, and no horizontal overflow.
apps/web/e2e/tests/command-panel.spec.ts: search-only absence at rest and exact setting command landing after typing.

Verification results

Focused unit/integration suite: 12 files and 85 tests passed.
Broad settings and integration-domain suites passed.
pnpm run lint, pnpm run typecheck, pnpm run i18n:check, and pnpm run i18n:ratchet passed.
Public-doc validation passed after documenting Settings and Cmd+K discovery in Get Started.
pnpm run build completed a production Vite build.
Desktop Settings discovery E2E: 3 tests passed.
Mobile Settings discovery E2E: 1 test passed.
Cmd+K discovery and legacy-alias E2E: 2 tests passed.
Cmd+K sectioning follow-up: 14 focused component tests and 1 fresh-build browser test passed; typecheck, focused ESLint, i18n checks, and the new-code ratchet passed.
Settings-search polish follow-up: desktop and mobile production-browser tests passed after a fresh build; visual checks confirmed compact desktop density and retained 44 px phone targets.
Settings-result motion follow-up: focused unit coverage and fresh-build desktop/mobile browser tests passed; the browser test proves a 160 ms row reflow and an animation-free reduced-motion update.

Implementation waves

All tasks execute sequentially in this conversation. No subagents are authorized.

5.5 KiB Raw Permalink Blame History