Site-wide Cmd+K implementation summary

site-command-palette-summary.md

Site-wide Cmd+K navigation — implementation summary

Goal

Add fast Cmd/Ctrl+K navigation to pages using the default site navbar, while leaving Finance, PHR, and other layouts with their own navbar/palette untouched.

The command palette should:

• search immediately from an already-hydrated in-memory payload
• avoid a new endpoint, eager background fetch, or extra database query
• cover a broader registry of stable destinations
• never hydrate authenticated, permission-gated, or admin-only destinations for users who cannot access them
• share the existing navigation, shortcut, search, and URL-safety primitives

Architecture decisions

1. Extracted the inline Blade navigation block into App\Services\Navigation\SiteNavigationBuilder.

   • The builder accepts ?User.
   • Existing navItems and accountMenuItems behavior is preserved.
   • The existing client-company lookup remains the only dynamic navigation query.

2. Added a sibling commandDestinations hydration key.

   • Shape: { group, label, href, keywords? }.
   • This keeps navbar item schemas and rendering behavior unchanged.
   • The registry contains only stable routes and performs no database queries.
   • Guest, authenticated, permission, and admin gating happens before JSON serialization.

3. Added the destination shape explicitly to the Zod AppInitialDataSchema.

   • This avoids Zod silently stripping the new payload.

4. Added a default-navbar command palette.

   • Uses MillerCommandPalette.
   • Reuses useMillerCommandPaletteShortcut.
   • Uses the generic commandFilter.
   • Sanitizes every selected URL through safeHref.
   • Merges navbar links, account links, and registry destinations.
   • Skips structural group/divider rows.
   • Deduplicates by href while retaining searchable aliases and keywords.

5. Added a responsive Search trigger immediately before the theme toggle.

   • Cmd+K on Apple platforms and Ctrl+K elsewhere.
   • Finance/PHR/custom layouts are mutually exclusive because they do not mount the default navbar entry point.

Registry scope

The static registry augments normal navbar destinations with stable public pages and, only when authorized, additional PHR, Finance, class-action, and client-management pages.

Named routes are checked with Route::has() and generated with relative route(..., absolute: false) URLs. Tests verify every resulting destination resolves to a registered GET route.

Tests added

PHP

• guest payload includes public command destinations only
• authenticated payload includes authenticated destinations
• finance entries follow feature permissions
• admin-only entries are server-gated
• registered destinations resolve to GET routes
• existing financial-planning navbar assertions remain unchanged

Jest

• navbar/dropdown/account flattening
• structural group/divider skipping
• href deduplication and keyword merging
• command filtering
• Cmd+K keyboard opening
• selection/navigation
• hostile href sanitization

Validation

Local validation completed:

• TypeScript type-check
• ESLint
• production Vite build
• Pint
• PHPStan
• focused PHP tests
• full Jest suite: 517 suites / 4,415 tests

The full backend suite was delegated to PR CI at the user’s request. All PR checks subsequently passed, including backend tests/static checks and frontend build/static/tests.

Workflow

Work was performed without modifying the primary checkout:

1. Created an integration worktree and committed the hydration contract.
2. Ran two file-disjoint worktree agents in parallel:
   • PHP navigation extraction, registry, and PHPUnit coverage
   • TypeScript palette, row builder, and Jest coverage
3. Cherry-picked both tracks into the integration branch.
4. Wired the navbar trigger on the integration branch.
5. Pushed one stacked branch and opened one draft PR.
6. Removed all task worktrees; the primary checkout remained clean.

Commits

• b2172f40 — define site command destination hydration
• edb3de25 — build site command destination registry
• e3f3571f — add site command palette frontend
• fd61d477 — wire site command palette into navbar

Result

PR #1666 — Add site-wide command navigation was merged after all CI checks passed.