feat: nav-suite : sidebar layout variant + search dialog + mobile bar

[Shewart]

Summary

Two Phase-2 primitives landed together because they're tightly UX-coupled: a sidebar layout variant (drops the top nav; brand + search + collapse live in the sidebar itself, floating shadcn sidebar-04 aesthetic) and a full search dialog with build-time index + Cmd+K + fuzzy match. Consumer flips between the classic top-nav look and the new floating sidebar via one enum value.

Combined into one branch because both surfaces need to know where search lives — TopNav puts a search chip in the header, Sidebar puts it in the sidebar. Designing both together avoids awkward intermediate states.

What's in it

Layout variant

• New DocsLayoutVariant enum (TopNav | Sidebar) on ShellDocsOptions. TopNav remains the default.
• DocsLayout.razor branches on the variant. TopNav → <DocsHeader /> at top + sidebar underneath (unchanged). Sidebar → no top nav, <DocsSidebarHeader /> mounted at the top of the sidebar with brand + search chip + collapse toggle.
• Page bg treatment inverted for Sidebar variant per fumadocs pattern: page = plain --background, sidebar = the only "floating" card (--card bg, subtle border + shadow, inset margins). Content sits flush.

Sidebar collapse

• New SidebarCollapseState scoped service — IsCollapsed, Toggle, Expand, Collapse, OnChange event.
• Collapse toggle button in DocsSidebarHeader (top-right of the sidebar header row) with a panel-left-close lucide icon.
• Collapsed: sidebar fully hidden, grid template columns switches to single-column, content expands. Floating reopen toolbar (top-left, card bg + border + shadow) surfaces two buttons: reopen-sidebar + search.
• Idempotent — flipping doesn't disturb content or scroll position.

Mobile bar (Sidebar variant only)

• New <DocsMobileBar /> component. Sticky top row visible only below 1024px.
• Three tools: hamburger (opens mobile drawer), search icon (opens Cmd+K dialog), <ThemeToggle /> (pushed right).
• Backdrop-blurred bg + border-bottom so it reads distinctly against scrolled content.
• Above 1024px: display: none, desktop keeps the sidebar-only chrome.

Search primitives

• SearchIndex in ShellDocs.Core — walks the navigation graph, emits one SearchEntry per page + per h2/h3 heading (headings extracted via fenced-code-safe regex against the markdown files at graph-build time).
• Each entry carries Url, Title, Description, Section (parent page/section title), Kind (Page | Heading).
• Registered as singleton in AddShellDocs.
• New SearchState scoped service — global open/close state observed by the dialog and any trigger (header chip, sidebar chip, Cmd+K keyboard, mobile bar).
• <SearchDialog /> component — modal overlay + backdrop, input row with kbd hint, ranked results list with page/heading icons + section subtitle, keyboard-driven (↑/↓ navigate, Enter open, Esc close, mouse hover also highlights).
• Client-side fuzzy match: substring hit on title = massive boost, per-token AND against title/section/description, page slightly outranks heading on ties. Handles ~500-entry indexes without perceptible lag.
• Global Cmd+K / Ctrl+K keyboard shortcut wired via shelldocs.js (bridges to Blazor via DotNetObjectReference).

Polish carried in

• Package selector chevron — swapped the stacked "select" chevrons for a single chevron-down polyline that rotates 180° when the dropdown opens. Same geometry + spring easing as the collapsible section toggles — consistent iconography across all sidebar controls.
• Unicode arrow purge — kbd hints in the search dialog footer, Home hero CTAs, Showcase CTA, and 404 back-links now use SVG lucide arrows instead of Unicode ↑↓→←. Kept CLI-console arrows (terminal aesthetic) and doc-comment arrows.
• TOC title sticky bg — swapped the fading gradient for solid --background so content scrolls fully hidden beneath it (fumadocs pattern).
• Sidebar footer visibility — added display: flex; flex-direction: column on the Sidebar-variant .docs-sidebar-slot + flex: 1; min-height: 0 on the child <nav>. Fixes the theme toggle disappearing below the fold when the sidebar tree got tall.
• Home CTA buttons — SVGs sized explicitly via .btn svg { width: 0.9rem; height: 0.9rem; } after arrow icons ballooned to the default 24×24 and wrapped labels across three lines.

Preview app

• Program.cs flips to LayoutVariant = DocsLayoutVariant.Sidebar so the new layout is the default demo. Flip to TopNav to switch back.
• Home/Blog/Showcase gain proper button-icon sizing per the fix above.

Tests

• SearchIndexTests.cs — 5 tests. Builds a temp markdown tree via NavigationGraphBuilder, verifies SearchIndex.FromGraph emits one entry per page, headings for h2/h3 with anchored URLs, section attribution, and description carry-through.
• Full suite: 99 passing (was 94, +5).

Notes

• Sidebar-variant collapsed state is fully hidden, not icon-rail. Rail mode is bumped to feat/sidebar-collapse-icon-rail follow-up. Ship the base + reopen toolbar first, iterate.
• Search index is header + title depth only, not body text. Full body-text indexing + build-time search-index.json emission is feat/search-index-build follow-up. Header + title matching covers 80% of docs-site search intent.
• No Ctrl+B shortcut for collapse yet — deferred to the icon-rail follow-up so both land together.
• ThemeState change scoped for sidebar-variant only? — no, ThemeToggle behaviour is unchanged. The mobile bar simply renders one alongside the other buttons.

Test plan

• dotnet build shelldocs.slnx — clean
• dotnet test — 99 passing
• Preview app on Sidebar variant — brand + search + collapse-toggle visible in the sidebar header, floating card aesthetic
• Collapse toggle hides sidebar, floating reopen toolbar appears top-left with reopen + search icons
• Cmd/Ctrl+K opens search dialog from any docs page; type "tabs" or "callout", ↑↓ ranks, Enter navigates, Esc closes
• Header search chip (TopNav variant) opens same dialog
• TOC title stays visible while content scrolls beneath, no bleed-through
• Theme toggle visible at bottom of sidebar in Sidebar variant
• Mobile view (< 1024px) in Sidebar variant — mobile bar sticks at top with hamburger + search + theme
• Manual: flip LayoutVariant to TopNav, confirm classic look still works untouched

Next branch: feat/content-primitives — the small markdown components every docs page needs (Callout proper, Card, LinkCard, Tabs, Steps, FileTree). ~1 day of work, biggest immediate DX win for consumers.