@exxatdesignux/ui 0.2.19 → 0.4.0

package/template/components/{app-sidebar.tsx → sidebar/app-sidebar.tsx}

@@ -67,8 +67,8 @@ import { useModKeyLabel } from "@/hooks/use-mod-key-label"
 import { useLocationHash } from "@/hooks/use-location-hash"
 import { useSidebarReflowZoom } from "@/hooks/use-sidebar-reflow-zoom"
 import { useProduct, type Product } from "@/contexts/product-context"
-import { NavUser } from "@/components/nav-user"
-import { useSecondaryPanel } from "@/components/secondary-panel"
+import { NavUser } from "./nav-user"
+import { useSecondaryPanel } from "./secondary-panel"
 import { ExxatProductLogo, ExxatProductMark } from "@/components/exxat-product-logo"
 import { motionHeaderEnter } from "@/lib/motion-ui"
 import { customProductBrandConfig, productBrandLabel } from "@/lib/product-brand"
@@ -106,21 +106,57 @@ function normalizedLocationHash(locationHash: string): string {
 }
 
 /**
- * Paths where a sibling sidebar row uses `#fragment` on the same pathname
- * (e.g. Settings vs Tokens & themes). The plain-path row must not stay active
- * when the hash belongs to that sibling.
+ * Path → set of hash fragments claimed by *another* nav item at the same path.
+ *
+ * Why: several rows deliberately share a route and disambiguate via `#fragment`.
+ * Example: `Tokens & themes → /settings#appearance` and `Settings → /settings`
+ * both render under the same page. Without a registry, when the user is on
+ * `/settings#appearance` the no-fragment "Settings" row matches by path-equality
+ * (line below: `pathname === pathOnly`) and lights up too — so *both* rows
+ * appear active.
+ *
+ * The registry is computed once from the static nav config and consulted by
+ * `isNavActive` to make the no-fragment item defer when a hash-bearing sibling
+ * claims the current `location.hash`.
  */
-const NAV_EXCLUSIVE_HASH_BY_PATH: Readonly<Record<string, readonly string[]>> = {
-  "/settings": ["appearance"],
-  "/help": ["more"],
+const NAV_HASH_CLAIMS: ReadonlyMap<string, ReadonlySet<string>> = (() => {
+  const map = new Map<string, Set<string>>()
+  const record = (url: string) => {
+    const p = navUrlPath(url)
+    const f = navUrlFragment(url)
+    if (!p || f === null) return
+    let set = map.get(p)
+    if (!set) { set = new Set<string>(); map.set(p, set) }
+    set.add(f)
+  }
+  const walk = (items: ReadonlyArray<{ url?: string; children?: ReadonlyArray<{ url?: string; children?: unknown }> }>) => {
+    for (const it of items) {
+      if (typeof it.url === "string") record(it.url)
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      if (Array.isArray((it as any).children)) walk((it as any).children)
+    }
+  }
+  walk(NAV_PRIMARY)
+  walk(NAV_DOCUMENTS)
+  walk(NAV_QUICK_ACTIONS)
+  walk(NAV_SECONDARY)
+  return map
+})()
+
+/** True when another nav item at the same path claims the current location hash. */
+function navHasMoreSpecificMatch(pathname: string, locationHash: string): boolean {
+  const claims = NAV_HASH_CLAIMS.get(pathname)
+  if (!claims) return false
+  const h = normalizedLocationHash(locationHash)
+  if (h === "") return false
+  return claims.has(h)
 }
 
 /**
  * Whether `pathname` (+ optional `location.hash`) matches a sidebar `href`.
  * When several links share the same path (e.g. `/settings`), disambiguate with `#fragment`
  * in each `href` — those rows use the `frag !== null` branch below.
- * For `href` without `#…`, an in-page hash (e.g. QB view tabs) does not clear the match,
- * except when the hash is reserved for a hash-sibling row on that path.
+ * For `href` without `#…`, an in-page hash (e.g. QB view tabs) does not clear the match.
  */
 function isNavActive(pathname: string, url: string, locationHash = ""): boolean {
   const pathOnly = navUrlPath(url)
@@ -140,15 +176,18 @@ function isNavActive(pathname: string, url: string, locationHash = ""): boolean
     return pathname === pathOnly && h === frag
   }
 
-  if (pathOnly === "/") return pathname === "/" && h === ""
-  /** Exact path match — ignore `location.hash` when the nav `href` has no `#…` fragment (QB view tabs use hash). */
-  if (pathname === pathOnly) {
-    if (h !== "") {
-      const exclusive = NAV_EXCLUSIVE_HASH_BY_PATH[pathOnly]
-      if (exclusive?.includes(h)) return false
-    }
-    return true
+  if (pathOnly === "/") {
+    if (pathname !== "/" || h !== "") return false
+    return !navHasMoreSpecificMatch(pathname, locationHash)
   }
+  /**
+   * Exact path match — ignore `location.hash` when the nav `href` has no `#…` fragment (QB view tabs use hash).
+   * EXCEPTION: when another nav item at the same path claims the current hash
+   * (e.g. `Tokens & themes → /settings#appearance` while we're evaluating
+   * `Settings → /settings`), defer to that more-specific row — otherwise both
+   * would light up. See `NAV_HASH_CLAIMS`.
+   */
+  if (pathname === pathOnly) return !navHasMoreSpecificMatch(pathname, locationHash)
   // Design system library — active on hub and detail routes.
   if (pathOnly === "/library") {
     return pathname.startsWith("/library/")
@@ -184,7 +223,7 @@ function isCollapsibleChildActive(
 
   if (!isNavActive(pathname, child.url, locationHash)) return false
 
-  /** Hub entry (`/question-bank`) must not stay “active” on `/question-bank/library` etc. */
+  /** Hub entry (`/library`) must not stay “active” on `/library/all` etc. */
   if (parent.primaryHubChildKey && child.key === parent.primaryHubChildKey) {
     const hubPath = navUrlPath(parent.url)
     if (hubPath) {
@@ -315,7 +354,7 @@ function CollapsibleNavItem({ item, pathname }: { item: NavLinkItem; pathname: s
   const iconRailCollapsed = state === "collapsed" && !isMobile
   // In the icon rail the parent icon is the ONLY visible thing for this item
   // (no sub-list, no labels) — so it must reflect "I'm somewhere inside this
-  // section" by lighting up on any descendant route (e.g. `/question-bank/library`),
+  // section" by lighting up on any descendant route (e.g. `/library/all`),
   // not only on the parent URL itself. In the expanded view we keep the
   // parent neutral and let the active child row carry `data-active` (see
   // `isCollapsibleParentMenuButtonActive`).
@@ -440,7 +479,7 @@ function CollapsibleNavItem({ item, pathname }: { item: NavLinkItem; pathname: s
                 </span>
                 <span>{item.title}</span>
                 <i
-                  className="fa-light fa-chevron-right ml-auto text-xs text-current transition-transform duration-200 ease-out group-data-[state=open]/collapsible:rotate-90 motion-reduce:transition-none"
+                  className="fa-light fa-chevron-right ms-auto text-xs text-current transition-transform duration-200 ease-out group-data-[state=open]/collapsible:rotate-90 motion-reduce:transition-none"
                   aria-hidden="true"
                 />
               </SidebarMenuButton>
@@ -844,58 +883,60 @@ function ProductLogoButton() {
 
   return (
     <DropdownMenu>
-      <DropdownMenuTrigger asChild>
-        <SidebarMenuButton
-          size="lg"
-          tooltip={iconRail ? current.label : undefined}
-          className={cn(
-            "py-2 text-sidebar-foreground data-[state=open]:bg-sidebar-accent data-[state=open]:text-sidebar-accent-foreground",
-            expandedOrMobile &&
-              "h-auto min-h-12 !overflow-visible items-center [&>span:last-child]:!overflow-visible [&>span:last-child]:!whitespace-normal [&>span:last-child]:text-clip",
-            "group-data-[collapsible=icon]:items-center group-data-[collapsible=icon]:justify-center",
-            iconRail &&
-              "group-data-[collapsible=icon]:!size-9 group-data-[collapsible=icon]:!min-h-9 group-data-[collapsible=icon]:!max-h-9 group-data-[collapsible=icon]:!p-0 group-data-[collapsible=icon]:overflow-visible",
-          )}
-          aria-label={`Current product: ${current.label}. Switch product`}
-          suppressHydrationWarning
-        >
-          {iconRail ? (
-            // Match the school selector footprint in the icon rail (32px frame,
-            // 28px mark — same visual weight as the avatar with inset padding).
-            <span className="flex size-8 shrink-0 items-center justify-center">
-              <ExxatProductMark product={current.id} className="size-7" />
-            </span>
-          ) : (
-            <span className="flex min-h-0 min-w-0 flex-1 items-stretch gap-2">
-              <span
-                className="flex min-h-0 min-w-0 flex-1 items-center justify-start overflow-visible"
-                aria-hidden="true"
-              >
-                <ExxatProductLogo
-                  product={current.id}
-                  variant="mutedSuffix"
-                  className="w-auto max-w-[min(100%,280px)] object-left object-contain"
-                />
-              </span>
-              <span
-                className="flex w-6 shrink-0 items-center justify-center self-stretch text-muted-foreground"
-                aria-hidden="true"
-              >
-                <i
-                  className="fa-light fa-chevron-down block text-xs leading-none"
-                  aria-hidden="true"
-                />
-              </span>
-            </span>
-          )}
-        </SidebarMenuButton>
-      </DropdownMenuTrigger>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <DropdownMenuTrigger asChild>
+            <SidebarMenuButton
+              size="lg"
+              className={cn(
+                "py-2 text-sidebar-foreground data-[state=open]:bg-sidebar-accent data-[state=open]:text-sidebar-accent-foreground",
+                expandedOrMobile &&
+                  "h-auto min-h-12 !overflow-visible items-center [&>span:last-child]:!overflow-visible [&>span:last-child]:!whitespace-normal [&>span:last-child]:text-clip",
+                "group-data-[collapsible=icon]:items-center group-data-[collapsible=icon]:justify-center",
+                iconRail &&
+                  "group-data-[collapsible=icon]:!size-9 group-data-[collapsible=icon]:!min-h-9 group-data-[collapsible=icon]:!max-h-9 group-data-[collapsible=icon]:!p-0 group-data-[collapsible=icon]:overflow-visible",
+              )}
+              aria-label={`Current product: ${current.label}. Switch product`}
+              suppressHydrationWarning
+            >
+              {iconRail ? (
+                // Match the school selector footprint in the icon rail (32px frame,
+                // 28px mark — same visual weight as the avatar with inset padding).
+                <span className="flex size-8 shrink-0 items-center justify-center">
+                  <ExxatProductMark product={current.id} className="size-7" />
+                </span>
+              ) : (
+                <span className="flex min-h-0 min-w-0 flex-1 items-stretch gap-2">
+                  <span
+                    className="flex min-h-0 min-w-0 flex-1 items-center justify-start overflow-visible"
+                    aria-hidden="true"
+                  >
+                    <ExxatProductLogo
+                      product={current.id}
+                      variant="mutedSuffix"
+                      className="w-auto max-w-[min(100%,280px)] object-left object-contain"
+                    />
+                  </span>
+                  <span
+                    className="flex w-6 shrink-0 items-center justify-center self-stretch text-muted-foreground"
+                    aria-hidden="true"
+                  >
+                    <i
+                      className="fa-light fa-chevron-down block text-xs leading-none"
+                      aria-hidden="true"
+                    />
+                  </span>
+                </span>
+              )}
+            </SidebarMenuButton>
+          </DropdownMenuTrigger>
+        </TooltipTrigger>
+        <TooltipContent side="right" align="center" hidden={state !== "collapsed" || isMobile}>
+          {current.label}
+        </TooltipContent>
+      </Tooltip>
 
-      <DropdownMenuContent
-        align="start"
-        side={iconRail ? "right" : "bottom"}
-        sideOffset={iconRail ? 8 : 4}
-      >
+      <DropdownMenuContent align="start" side="right" sideOffset={8}>
         <DropdownMenuLabel className="text-xs text-muted-foreground">
           Switch product
         </DropdownMenuLabel>
@@ -913,7 +954,7 @@ function ProductLogoButton() {
               className="w-auto shrink-0 max-w-[min(100%,260px)]"
             />
             {p.id === product && (
-              <i className="fa-solid fa-check ml-auto text-brand text-xs" aria-hidden="true" />
+              <i className="fa-solid fa-check ms-auto text-brand text-xs" aria-hidden="true" />
             )}
           </DropdownMenuItem>
         ))}

package/template/components/sidebar/index.ts

@@ -0,0 +1,16 @@
+// Barrel re-export for the sidebar shell.
+// Consumers SHOULD import via `@/components/sidebar`; per-file paths still
+// work as escape hatch (e.g. `@/components/sidebar/secondary-panel`).
+//
+// See apps/web/docs/components-audit-2026-05.md §2.3.
+export * from "./app-sidebar"
+export * from "./app-sidebar-dynamic"
+export * from "./sidebar-shell"
+export * from "./sidebar-auto-collapse"
+export * from "./sidebar-auto-open"
+export * from "./nav-main"
+export * from "./nav-secondary"
+export * from "./nav-documents"
+export * from "./nav-user"
+export * from "./secondary-nav"
+export * from "./secondary-panel"

package/template/components/{secondary-nav.tsx → sidebar/secondary-nav.tsx}

@@ -293,7 +293,7 @@ export function SecondaryNavPanel({
             title={section.action.label}
             onClick={section.action.onClick}
             className={cn(
-              "inline-flex size-6 items-center justify-center rounded-md -mr-1",
+              "inline-flex size-6 items-center justify-center rounded-md -me-1",
               "text-muted-foreground hover:text-interactive-hover-foreground hover:bg-interactive-hover-strong",
               "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
             )}
@@ -318,7 +318,7 @@ export function SecondaryNavPanel({
               placeholder={section.searchPlaceholder ?? "Search"}
               aria-label={`Search ${section.label}`}
               className={cn(
-                "w-full h-7 pl-7 pr-2 rounded-md text-xs bg-background border border-border",
+                "w-full h-7 ps-7 pe-2 rounded-md text-xs bg-background border border-border",
                 "placeholder:text-muted-foreground/70",
                 "focus:outline-none focus:ring-2 focus:ring-ring focus:border-transparent"
               )}

package/template/components/sidebar/secondary-panel.tsx

@@ -0,0 +1,316 @@
+"use client"
+
+/**
+ * SecondaryPanel — nested rail between the primary icon sidebar and content.
+ * Full width shows hub scope nav; **compact** matches the primary sidebar icon rail (`w-12`).
+ *
+ * Chrome uses {@link NestedSecondaryPanelShell}. Library body stays in
+ * `library-secondary-nav.tsx` (domain-specific), not duplicated here.
+ */
+
+import * as React from "react"
+import { useSidebar } from "@/components/ui/sidebar"
+import { Tip } from "@/components/ui/tip"
+import { Button } from "@/components/ui/button"
+import { LibrarySecondaryNav } from "@/components/library-secondary-nav"
+import { TokensSecondaryNav } from "@/components/tokens-secondary-nav"
+import { NestedSecondaryPanelShell } from "@/components/templates/nested-secondary-panel-shell"
+import { useSidebarReflowZoom } from "@/hooks/use-sidebar-reflow-zoom"
+import type { LibraryItem } from "@/lib/mock/library"
+import type { LibraryFolder } from "@/lib/mock/library-folders"
+
+export type LibraryFolderBridge = {
+  folders: LibraryFolder[]
+  onFoldersChange: React.Dispatch<React.SetStateAction<LibraryFolder[]>>
+  items: LibraryItem[]
+  onItemsChange: React.Dispatch<React.SetStateAction<LibraryItem[]>>
+}
+
+export type LibraryAccessBridge = {
+  openManageAccess: () => void
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Context
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type ClosePanelOptions = {
+  /**
+   * Main app sidebar after the secondary panel closes.
+   * - `restore` (default): snap back to the user's saved preference
+   *   (`sidebar_state_v2` cookie, or `defaultOpen` if unset). Use this when
+   *   leaving a page whose secondary panel caused an incidental collapse — the
+   *   rail returns to the state the user explicitly set elsewhere via ⌘B / the
+   *   sidebar button.
+   * - `leave`: only clear the active panel — keep the rail in whatever state it
+   *   was in (rare; prefer `restore`).
+   * - `expand`: force the full primary rail open. Use only when the product
+   *   explicitly wants the wide rail after dismiss.
+   * - `collapse`: keep the icon rail. Use when the next route also wants compact.
+   */
+  mainSidebar?: "restore" | "expand" | "collapse" | "leave"
+}
+
+interface SecondaryPanelContextValue {
+  /** Currently active panel id, or null if none */
+  activePanel: string | null
+  /** Open a panel by id (always exits compact / full-width). */
+  openPanel: (id: string) => void
+  /** Close the panel (programmatic / route cleanup). */
+  closePanel: (opts?: ClosePanelOptions) => void
+  /** Icon-only nested rail while the panel stays “open”. Cleared by {@link openPanel} / {@link closePanel}. */
+  secondaryPanelCompact: boolean
+  /** Narrow icon rail (primary-sidebar-style); keeps {@link activePanel} mounted. */
+  collapseActiveSecondaryPanel: () => void
+  /** Library folder tree shared with the secondary nav while the hub is mounted. */
+  libraryFolderBridge: LibraryFolderBridge | null
+  setLibraryFolderBridge: (bridge: LibraryFolderBridge | null) => void
+  /** Opens the hub collaborators sheet from the secondary nav. */
+  libraryAccessBridge: LibraryAccessBridge | null
+  setLibraryAccessBridge: (bridge: LibraryAccessBridge | null) => void
+}
+
+const SecondaryPanelContext = React.createContext<SecondaryPanelContextValue>({
+  activePanel: null,
+  openPanel: () => {},
+  closePanel: () => {},
+  secondaryPanelCompact: false,
+  collapseActiveSecondaryPanel: () => {},
+  libraryFolderBridge: null,
+  setLibraryFolderBridge: () => {},
+  libraryAccessBridge: null,
+  setLibraryAccessBridge: () => {},
+})
+
+export function useSecondaryPanel() {
+  return React.useContext(SecondaryPanelContext)
+}
+
+export function SecondaryPanelProvider({ children }: { children: React.ReactNode }) {
+  const [activePanel, setActivePanel] = React.useState<string | null>(null)
+  const [secondaryPanelCompact, setSecondaryPanelCompact] = React.useState(false)
+  const [libraryFolderBridge, setLibraryFolderBridge] =
+    React.useState<LibraryFolderBridge | null>(null)
+  const [libraryAccessBridge, setLibraryAccessBridge] =
+    React.useState<LibraryAccessBridge | null>(null)
+  const { setOpen, restoreSavedOpen } = useSidebar()
+
+  /**
+   * Browser zoom ≥ 200% (or very short viewport) — same `useSidebarReflowZoom`
+   * signal the primary sidebar uses (WCAG 1.4.10). At that scale the 16rem
+   * secondary rail crowds out primary content, so we **auto-collapse it to
+   * the icon variant on entering high zoom**. We don't keep overriding —
+   * users can re-expand once collapsed; the next zoom-out → zoom-in cycle
+   * re-collapses. This matches the pattern users get from clicking the
+   * panel's own "Collapse to icons" button.
+   */
+  const reflowZoom = useSidebarReflowZoom()
+  const wasReflowZoomRef = React.useRef(false)
+  React.useEffect(() => {
+    if (reflowZoom && !wasReflowZoomRef.current) {
+      setSecondaryPanelCompact(true)
+    }
+    wasReflowZoomRef.current = reflowZoom
+  }, [reflowZoom])
+
+  const openPanel = React.useCallback(
+    (id: string) => {
+      // High zoom → keep the icon rail (auto-collapse rule above). At normal
+      // zoom this stays the legacy behavior (full-width on open).
+      setSecondaryPanelCompact(reflowZoom)
+      setActivePanel(id)
+      // `persist: false` — collapsing the rail to make room for the secondary
+      // panel is an incidental layout side-effect; the user's saved
+      // expanded/collapsed preference (cookie) must not be overwritten by it.
+      setOpen(false, { persist: false }) // collapse main sidebar to icon rail
+    },
+    [setOpen, reflowZoom],
+  )
+
+  const closePanel = React.useCallback((opts?: ClosePanelOptions) => {
+    setSecondaryPanelCompact(false)
+    setActivePanel(null)
+    /**
+     * Default = `restore`. `openPanel` collapsed the rail with `persist: false`
+     * (the saved cookie is untouched), so on close we ask the sidebar context
+     * to re-apply whatever the user truly saved. This makes the visual collapse
+     * scoped to the page that needed it — leave the page → rail comes back to
+     * the user's preference.
+     */
+    const mainSidebar = opts?.mainSidebar ?? "restore"
+    if (mainSidebar === "leave") return
+    if (mainSidebar === "restore") {
+      restoreSavedOpen()
+      return
+    }
+    if (mainSidebar === "collapse") {
+      setOpen(false, { persist: false })
+      return
+    }
+    setOpen(true, { persist: false }) // mainSidebar === "expand"
+  }, [restoreSavedOpen, setOpen])
+
+  const collapseActiveSecondaryPanel = React.useCallback(() => {
+    setSecondaryPanelCompact(true)
+  }, [])
+
+  const value = React.useMemo(
+    () => ({
+      activePanel,
+      openPanel,
+      closePanel,
+      secondaryPanelCompact,
+      collapseActiveSecondaryPanel,
+      libraryFolderBridge,
+      setLibraryFolderBridge,
+      libraryAccessBridge,
+      setLibraryAccessBridge,
+    }),
+    [
+      activePanel,
+      openPanel,
+      closePanel,
+      secondaryPanelCompact,
+      collapseActiveSecondaryPanel,
+      libraryFolderBridge,
+      libraryAccessBridge,
+    ],
+  )
+
+  return (
+    <SecondaryPanelContext.Provider value={value}>
+      {children}
+    </SecondaryPanelContext.Provider>
+  )
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// SecondaryPanel — the actual rendered panel
+// ─────────────────────────────────────────────────────────────────────────────
+
+function LibraryPanel() {
+  const { collapseActiveSecondaryPanel, secondaryPanelCompact } = useSecondaryPanel()
+
+  if (secondaryPanelCompact) {
+    return <LibrarySecondaryNav />
+  }
+
+  return (
+    <>
+      <div className="flex items-center justify-between gap-2 px-4 pt-4 pb-2">
+        <h2
+          className="text-xl font-semibold leading-tight text-sidebar-foreground"
+          style={{ fontFamily: "var(--font-heading)" }}
+        >
+          Library
+        </h2>
+        <Tip label="Collapse to icons" side="bottom">
+          <Button
+            type="button"
+            size="icon"
+            variant="ghost"
+            onClick={() => collapseActiveSecondaryPanel()}
+            aria-label="Collapse to icons"
+          >
+            <i className="fa-light fa-angles-left" aria-hidden="true" />
+          </Button>
+        </Tip>
+      </div>
+      <LibrarySecondaryNav />
+    </>
+  )
+}
+
+function TokensPanel() {
+  const { collapseActiveSecondaryPanel, secondaryPanelCompact } = useSecondaryPanel()
+
+  if (secondaryPanelCompact) {
+    return <TokensSecondaryNav />
+  }
+
+  return (
+    <>
+      <div className="flex items-center justify-between gap-2 px-4 pt-4 pb-2">
+        <h2
+          className="text-xl font-semibold leading-tight text-sidebar-foreground"
+          style={{ fontFamily: "var(--font-heading)" }}
+        >
+          Tokens
+        </h2>
+        <Tip label="Collapse to icons" side="bottom">
+          <Button
+            type="button"
+            size="icon"
+            variant="ghost"
+            onClick={() => collapseActiveSecondaryPanel()}
+            aria-label="Collapse to icons"
+          >
+            <i className="fa-light fa-angles-left" aria-hidden="true" />
+          </Button>
+        </Tip>
+      </div>
+      <TokensSecondaryNav />
+    </>
+  )
+}
+
+/** Register panel components by id when a route opts into `secondaryPanel` in nav. */
+const PANELS: Record<string, React.FC> = {
+  "library": LibraryPanel,
+  tokens: TokensPanel,
+}
+
+export function SecondaryPanel() {
+  const { activePanel, secondaryPanelCompact } = useSecondaryPanel()
+  const PanelContent = activePanel ? PANELS[activePanel] : null
+
+  return (
+    <NestedSecondaryPanelShell open={Boolean(activePanel)} compact={secondaryPanelCompact}>
+      {PanelContent ? <PanelContent /> : null}
+    </NestedSecondaryPanelShell>
+  )
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Auto-open hook — pages call this to show/hide a panel on mount/unmount
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function useAutoPanel(panelId: string) {
+  const { openPanel, closePanel } = useSecondaryPanel()
+
+  React.useEffect(() => {
+    openPanel(panelId)
+    return () => {
+      closePanel()
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [panelId])
+}
+
+/** Sync hub folder state into the library secondary nav while the route is mounted. */
+export function LibraryFolderBridge({
+  folders,
+  onFoldersChange,
+  items,
+  onItemsChange,
+}: LibraryFolderBridge) {
+  const { setLibraryFolderBridge } = useSecondaryPanel()
+
+  React.useEffect(() => {
+    setLibraryFolderBridge({ folders, onFoldersChange, items, onItemsChange })
+    return () => setLibraryFolderBridge(null)
+  }, [folders, onFoldersChange, items, onItemsChange, setLibraryFolderBridge])
+
+  return null
+}
+
+export function LibraryAccessBridge({ openManageAccess }: LibraryAccessBridge) {
+  const { setLibraryAccessBridge } = useSecondaryPanel()
+
+  React.useEffect(() => {
+    setLibraryAccessBridge({ openManageAccess })
+    return () => setLibraryAccessBridge(null)
+  }, [openManageAccess, setLibraryAccessBridge])
+
+  return null
+}

package/template/components/sidebar/sidebar-auto-collapse.tsx

@@ -0,0 +1,27 @@
+"use client"
+
+import { useEffect, useRef } from "react"
+import { useSidebar } from "@/components/ui/sidebar"
+
+/**
+ * Collapses the sidebar on mount. Restores previous state on unmount.
+ * Use on focused full-page forms / wizards so the sidebar collapses when
+ * entering and reverts to whatever it was when leaving.
+ *
+ * Both transitions pass `{ persist: false }` so the visual collapse never
+ * overwrites the user's saved sidebar preference (the `sidebar_state_v2`
+ * cookie). Only an explicit toggle (⌘B / sidebar button) persists.
+ */
+export function SidebarAutoCollapse() {
+  const { open, setOpen } = useSidebar()
+  const prevOpen = useRef(open)
+
+  useEffect(() => {
+    prevOpen.current = open
+    setOpen(false, { persist: false })
+    return () => { setOpen(prevOpen.current, { persist: false }) }
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  return null
+}

package/template/components/{sidebar-auto-open.tsx → sidebar/sidebar-auto-open.tsx}

@@ -3,7 +3,8 @@
 import { useEffect, useRef } from "react"
 import { useSidebar } from "@/components/ui/sidebar"
 
-/** Reopens the sidebar once when the data-list page mounts (after returning from new-placement). */
+/** Reopens the sidebar once on mount — pair with `SidebarAutoCollapse` on focused
+ *  full-page forms / wizards so leaving the form restores the sidebar. */
 export function SidebarAutoOpen() {
   const { setOpen } = useSidebar()
   const ran = useRef(false)

package/template/components/{sidebar-shell.tsx → sidebar/sidebar-shell.tsx}

@@ -2,7 +2,7 @@
 
 /**
  * SidebarShell — SidebarProvider with layout-aware widths.
- * Desktop expanded/collapsed is persisted in the `sidebar_state` cookie by `@exxatdesignux/ui`
+ * Desktop expanded/collapsed is persisted in the `sidebar_state_v2` cookie by `@exxatdesignux/ui`
  * `SidebarProvider` (read on mount + write on toggle). `(app)/layout` passes
  * `defaultOpen` from the same cookie on the server so SSR matches the first client paint.
  */

package/template/components/site-header.tsx

@@ -107,7 +107,7 @@ export function SiteHeader({
           />
         )}
 
-        <div className="ml-auto shrink-0">
+        <div className="ms-auto shrink-0">
           <AskLeoToggle />
         </div>
       </div>