"use client" import * as React from "react" import type { ComponentDocSpec } from "@/lib/design-system/component-doc-types" import { AppShellPreview, SidebarCollapsedPreview, SidebarDrillInPreview, SidebarExpandedPreview, SidebarHoverPeekPreview, SidebarMobilePreview, SidebarSecondaryPanelPreview, } from "@/components/design-system/shell-previews" function ex( section: Omit, children: React.ReactNode, description?: string, ) { return { ...section, children, description } } export const sidebarComponentDoc: ComponentDocSpec = { slug: "sidebar", summary: "Application navigation across expanded, collapsed, mobile, drill-in, and secondary-panel compositions.", sections: [ ex( { id: "expanded", title: "Expanded primary sidebar" }, , "Full labels wrap, one route is active, and section labels use sidebar tokens.", ), ex( { id: "collapsed", title: "Collapsed icon rail" }, , "Every icon-only route keeps an aria-label and Tip. On desktop, hovering or focusing the rail peeks the full panel over the page.", ), ex( { id: "hover-peek", title: "Hover peek" }, , "Hover or focus a collapsed rail to read the full panel. Flush sheet, no scrim, clip reveal, Escape closes.", ), ex( { id: "drill-in", title: "Drill-in navigation" }, , "Flat route families such as Settings replace the primary list and provide one way back.", ), ex( { id: "secondary-panel", title: "Secondary scope panel" }, , "Persistent hierarchy scopes the current hub while the primary product navigation stays visible.", ), ex( { id: "mobile", title: "Mobile and reflow flyout" }, , "The same navigation becomes a dismissible overlay at narrow width and 200 percent zoom.", ), ], anatomy: [ { part: "AppSidebar", description: "Product-aware primary navigation shell." }, { part: "SidebarMenuButton", description: "One active row with Font Awesome idle and active glyphs." }, { part: "SidebarNavLabel", description: "Wraps expanded labels without truncation." }, { part: "SidebarDrillInItems", description: "Flat nested route family with Back and Escape handling." }, { part: "NestedSecondaryPanelShell", description: "Resizable persistent scope hierarchy beside a hub." }, { part: "Nav flyout", description: "Overlay mode for mobile and WCAG reflow." }, { part: "useHoverPeek", description: "Hover and focus peek for collapsed rails. Open delay, close grace, touch exclusion, Escape." }, ], guidelines: { do: [ "Register product navigation in NAV_BY_PRODUCT and use shared nav-active helpers.", "Use SidebarDrillIn for flat route families and SecondaryPanel for persistent hierarchy.", "Dismiss the nav flyout after a leaf route navigation.", "Keep one active row and let expanded labels wrap.", "Peek collapsed rails with useHoverPeek: flush sheet, no scrim, rail-peek-reveal clip animation.", ], dont: [ "Do not wire drill-in and secondaryPanel on the same nav item.", "Do not duplicate route matching with startsWith logic.", "Do not truncate navigation labels or use custom active pills.", "Do not copy sidebar chrome from a legacy screenshot.", "Do not animate width on a peek or let it reflow the content beside the rail.", ], }, accessibility: [ "Collapsed links expose an aria-label and visible Tip.", "Icon buttons meet the 24 pixel target floor.", "Escape closes drill-in, the mobile flyout, and a hover peek.", "Focus-visible inside a collapsed rail opens the peek without moving focus. Reduced motion removes the reveal.", "Resize handles use verticalResizeSeparatorAria with current, minimum, and maximum width.", ], relatedSlugs: ["app-shell", "utility-bar", "page-header", "breadcrumb"], extraImports: [ { label: "Hover peek hook", path: "@exxatdesignux/ui/hooks/use-hover-peek" }, { label: "Sidebar primitives", path: "@exxatdesignux/ui/components/ui/sidebar" }, { label: "Navigation active helpers", path: "@exxatdesignux/ui/lib/nav-active" }, ], } export const appShellComponentDoc: ComponentDocSpec = { slug: "app-shell", summary: "Canonical signed-in shell composition: UtilityBarSlot, product navigation, optional scope panel, SiteHeader bridge, and one page content column.", sections: [ ex( { id: "canonical", title: "Canonical app shell" }, , "The utility bar runs the full width with the page breadcrumb in it. Below, the icon rail, an optional scope panel, and the canvas step lighter left to right. Global utilities and navigation stay outside the page content column.", ), ex( { id: "expanded", title: "Expanded primary sidebar" }, , "With no scope panel the primary sidebar can stay expanded, labels wrapping. Opening a scope panel collapses it back to the rail.", ), ex( { id: "reflow", title: "Reflow and mobile" }, , "At narrow widths and 200 percent zoom the sidebar leaves the layout and opens as a flyout over the page, with a scrim. The canvas takes the full width.", ), ], anatomy: [ { part: "UtilityBarSlot", description: "Global product context, breadcrumb, utilities, and identity." }, { part: "AppSidebar", description: "Primary product navigation: a 48 pixel icon rail that peeks open on hover or focus, or expanded." }, { part: "Secondary panel", description: "Optional persistent scope hierarchy for the active hub. Compacts to an icon strip and peeks open the same way." }, { part: "SiteHeader bridge", description: "Publishes breadcrumb or Back mode into the utility bar." }, { part: "PageHeader", description: "Route identity and page-scoped actions." }, { part: "Main content", description: "One scroll owner for page content." }, ], guidelines: { do: [ "Keep utility and navigation chrome stable while product routes change.", "Use product URL roots and product-namespaced persisted state.", "Allow the sidebar to become an overlay flyout during reflow.", "Step the surfaces lighter left to right: sidebar, scope panel, canvas.", "Mount SystemBannerSlot inside the app shell main region.", ], dont: [ "Do not build a second product shell for one route.", "Do not place product-owned routes at the workspace root.", "Do not keep dual sidebars pinned at 320 pixels or 200 percent zoom.", "Do not add nested page scroll containers.", ], }, accessibility: [ "The shell exposes one main landmark and the route exposes one h1.", "Global utilities and each navigation landmark have distinct accessible names.", "Keyboard users can open, close, and traverse flyout and drill-in navigation.", "Page content reflows without document-level horizontal scrolling.", ], relatedSlugs: ["utility-bar", "sidebar", "page-header", "banner"], }