106 lines
5.5 KiB
Markdown
106 lines
5.5 KiB
Markdown
---
|
|
spec: docs/specs/ui/requirements/settings-discovery.md
|
|
created: 2026-08-05
|
|
status: 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
|
|
|
|
- [x] [Task 01 — catalog and search](task-01-catalog-and-search.md)
|
|
- [x] [Task 02 — tree and target navigation](task-02-tree-and-target-navigation.md)
|
|
- [x] [Task 03 — command palette](task-03-command-palette.md)
|
|
- [x] [Task 04 — general and standalone coverage](task-04-general-target-coverage.md)
|
|
- [x] [Task 05 — dynamic, integration, system, and account coverage](task-05-domain-target-coverage.md)
|
|
- [x] [Task 06 — browser and mobile E2E](task-06-browser-mobile-e2e.md)
|
|
- [x] [Task 07 — capitalized dynamic labels](task-07-capitalized-dynamic-labels.md)
|
|
- [x] [Task 08 — separate Cmd+K Settings section](task-08-command-palette-settings-group.md)
|
|
- [x] [Task 09 — compact Settings search field](task-09-compact-settings-search.md)
|
|
- [x] [Task 10 — subtle Settings result motion](task-10-settings-result-motion.md)
|
|
|
|
All tasks execute sequentially in this conversation. No subagents are authorized.
|