@exxatdesignux/ui 0.2.18 → 0.3.0

package/src/components/ui/list-page-view-frame.tsx

@@ -0,0 +1,64 @@
+"use client"
+
+/**
+ * ListPageViewFrame — shared horizontal gutter + optional centered max-width
+ * for list-hub **view bodies** (folder icon grid, finder panel chrome,
+ * OS-style folder explorer, dashboard slices, etc.).
+ *
+ * MUST be used instead of ad-hoc `mx-4 lg:mx-6` + `mx-auto max-w-*` pairs on
+ * each page — see `apps/web/AGENTS.md` §4.5 and
+ * `.cursor/rules/exxat-list-page-view-shells.mdc`.
+ *
+ * MUST NOT wrap `DataTable` when its toolbar already applies the same inset
+ * (avoid double gutter); use this for **non-table** view branches or
+ * **sections below** the shared toolbar.
+ *
+ * Promotion note: this file lived at
+ * `apps/web/components/data-views/list-page-view-frame.tsx` until
+ * 2026-05-20. It moved into `@exxatdesignux/ui` because the gutter / max-
+ * width contract is entity-agnostic and other consumers (a future docs
+ * site, partner apps) need the same rhythm without dragging in the whole
+ * `data-views/` family.
+ */
+
+import * as React from "react"
+
+import { cn } from "../../lib/utils"
+
+/** Default horizontal rhythm for view bodies under `ListPageTemplate` (matches `FolderGridView`). */
+export const LIST_PAGE_VIEW_FRAME_GUTTER = "mx-4 mb-6 lg:mx-6"
+
+/** Typical max width for icon grids / dense tile views on ultra-wide monitors. */
+export const LIST_PAGE_VIEW_FRAME_MAX_ICON_GRID = "max-w-6xl"
+
+/** Slightly wider shell when a view includes toolbar + breadcrumbs + grid (e.g. OS folder explorer). */
+export const LIST_PAGE_VIEW_FRAME_MAX_WIDE = "max-w-7xl"
+
+export interface ListPageViewFrameProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode
+  /**
+   * When set, children are wrapped in `mx-auto w-full min-w-0` + this
+   * max-width so the block stays centered inside the primary page column.
+   */
+  maxWidthClassName?: string
+  /** Override outer gutter; default `LIST_PAGE_VIEW_FRAME_GUTTER`. */
+  gutterClassName?: string
+}
+
+export function ListPageViewFrame({
+  children,
+  className,
+  maxWidthClassName,
+  gutterClassName = LIST_PAGE_VIEW_FRAME_GUTTER,
+  ...rest
+}: ListPageViewFrameProps) {
+  return (
+    <div className={cn(gutterClassName, className)} {...rest}>
+      {maxWidthClassName ? (
+        <div className={cn("mx-auto w-full min-w-0", maxWidthClassName)}>{children}</div>
+      ) : (
+        children
+      )}
+    </div>
+  )
+}

package/src/components/ui/page-header.tsx

@@ -0,0 +1,244 @@
+"use client"
+
+/**
+ * PageHeader — Full-width content area header.
+ *
+ * Sits at the top of a page's main content, BELOW the breadcrumb / topbar.
+ * Uses Ivy Presto (Adobe Fonts) for the title via the `--font-heading`
+ * CSS variable.
+ *
+ * **Variant `collaboration`** — optional access line + collaborator faces
+ * (or **Add collaborator** when the roster is empty) ahead of the primary
+ * `actions` slot. The full **Invite people** flow lives in the consuming
+ * page's `actions` overflow menu — this primitive only renders the face row.
+ *
+ * WCAG 2.1 AA:
+ *  - `<h1>` landmark — one per page (WCAG 1.3.1)
+ *  - Sufficient colour contrast >= 4.5:1 on title + subtitle (SC 1.4.3)
+ *  - Face row: `role="group"` + aggregate `aria-label`; each face has a
+ *    `Tooltip` name (SC 4.1.2)
+ *
+ * Promotion note: this file lived at `apps/web/components/page-header.tsx`
+ * until 2026-05-20. It moved into `@exxatdesignux/ui` so other apps (and
+ * future docs sites) can compose hub headers without duplicating the
+ * collaboration variant, h1 styling, or face-row a11y wiring. The
+ * `CollaboratorAccessRole` union is duplicated here as a narrow string
+ * literal so the primitive stays free of `apps/web/lib/` couplings — the
+ * authoritative role labels / icons / capability helpers continue to live
+ * in `apps/web/lib/collaborator-access.ts`.
+ */
+
+import * as React from "react"
+
+import { Avatar, AvatarFallback, AvatarImage } from "./avatar"
+import { Button } from "./button"
+import { Separator } from "./separator"
+import { Tooltip, TooltipContent, TooltipTrigger } from "./tooltip"
+import { cn } from "../../lib/utils"
+
+/**
+ * Library access role for shared hubs. Mirrors
+ * `apps/web/lib/collaborator-access.ts > CollaboratorAccessRole` — kept
+ * structurally identical so the apps/web type and this type are mutually
+ * assignable wherever consumers pass collaborator rosters to `PageHeader`.
+ */
+export type PageHeaderCollaboratorAccessRole =
+  | "owner"
+  | "editor"
+  | "commenter"
+  | "viewer"
+
+export type PageHeaderVariant = "default" | "collaboration"
+
+export interface PageHeaderCollaborator {
+  id: string
+  name: string
+  imageUrl?: string | null
+  initials?: string
+  email?: string
+  access?: PageHeaderCollaboratorAccessRole
+  /** Org / directory role tags (e.g. Faculty, Program coordinator). */
+  roles?: string[]
+}
+
+export interface PageHeaderProps {
+  /** Primary page title — rendered as `<h1>` in Ivy Presto serif. */
+  title: string
+  /** Short descriptor or date shown below the title (and below `accessInfo` when set). */
+  subtitle?: React.ReactNode
+  /** Layout preset — `collaboration` enables access line + face row ahead of `actions`. */
+  variant?: PageHeaderVariant
+  /**
+   * Role / access copy or badges — rendered between the title and subtitle
+   * when `variant="collaboration"` (e.g. lock icon + "Editors can modify").
+   */
+  accessInfo?: React.ReactNode
+  /** People with access — shown as a horizontal row of faces when `variant="collaboration"`. */
+  collaborators?: PageHeaderCollaborator[]
+  /** Max faces before a `+N` chip — default 3. */
+  collaboratorDisplayLimit?: number
+  /** Opens the invite collaborators sheet when a face, overflow chip, or empty-state CTA is activated. */
+  onCollaboratorsOpen?: () => void
+  /** Label for the empty-roster header control — default `"Add collaborator"`. */
+  addCollaboratorLabel?: string
+  /** Optional slot for right-aligned actions (buttons, selectors, etc.). */
+  actions?: React.ReactNode
+  /** Extra className for the outer wrapper. */
+  className?: string
+  /** When false, the title + subtitle are visually hidden (actions remain). */
+  showTitleBlock?: boolean
+}
+
+function PageHeaderCollaborationAccess({
+  people,
+  limit,
+  onOpenCollaborators,
+  addCollaboratorLabel,
+}: {
+  people: PageHeaderCollaborator[]
+  limit: number
+  onOpenCollaborators?: () => void
+  addCollaboratorLabel: string
+}) {
+  if (people.length === 0) {
+    return (
+      <div
+        role="group"
+        aria-label="People with access"
+        className="flex shrink-0 items-center"
+      >
+        <Button
+          type="button"
+          variant="outline"
+          size="lg"
+          onClick={onOpenCollaborators}
+          disabled={!onOpenCollaborators}
+        >
+          <i className="fa-light fa-user-plus" aria-hidden="true" />
+          {addCollaboratorLabel}
+        </Button>
+      </div>
+    )
+  }
+
+  const visible = people.slice(0, limit)
+  const overflow = Math.max(0, people.length - visible.length)
+  const names = people.map((p) => p.name).join(", ")
+
+  return (
+    <div
+      role="group"
+      aria-label={names ? `People with access: ${names}` : "People with access"}
+      className="flex shrink-0 items-center gap-2 sm:gap-2.5"
+    >
+      <div className="flex shrink-0 items-center gap-1.5">
+        {visible.map((c) => (
+          <Tooltip key={c.id}>
+            <TooltipTrigger asChild>
+              <button
+                type="button"
+                className="relative shrink-0 rounded-full focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background"
+                aria-label={`Open collaborators — ${c.name}`}
+                onClick={onOpenCollaborators}
+                disabled={!onOpenCollaborators}
+              >
+                <Avatar size="sm" shape="circle" className="pointer-events-none">
+                  {c.imageUrl ? (
+                    <AvatarImage src={c.imageUrl} alt="" referrerPolicy="no-referrer" />
+                  ) : null}
+                  <AvatarFallback className="text-xs font-semibold">
+                    {(c.initials ?? c.name.slice(0, 2)).toUpperCase()}
+                  </AvatarFallback>
+                </Avatar>
+              </button>
+            </TooltipTrigger>
+            <TooltipContent side="bottom">{c.name}</TooltipContent>
+          </Tooltip>
+        ))}
+        {overflow > 0 && (
+          <button
+            type="button"
+            className="flex size-6 shrink-0 items-center justify-center rounded-full bg-muted text-[11px] font-semibold tabular-nums text-muted-foreground ring-1 ring-border/60 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background"
+            aria-label={`Open collaborators — ${overflow} more people with access`}
+            onClick={onOpenCollaborators}
+            disabled={!onOpenCollaborators}
+          >
+            +{overflow}
+          </button>
+        )}
+      </div>
+    </div>
+  )
+}
+
+export function PageHeader({
+  title,
+  subtitle,
+  variant = "default",
+  accessInfo,
+  collaborators,
+  collaboratorDisplayLimit = 3,
+  onCollaboratorsOpen,
+  addCollaboratorLabel = "Add collaborator",
+  actions,
+  className,
+  showTitleBlock = true,
+}: PageHeaderProps) {
+  const isCollaboration = variant === "collaboration"
+  const showAccess = Boolean(isCollaboration && accessInfo)
+  const showCollaborationAccess = isCollaboration
+  const showActionsColumn = Boolean(actions) || showCollaborationAccess
+  const showCollaboratorActionsSeparator =
+    showCollaborationAccess && Boolean(actions)
+
+  return (
+    <div
+      className={cn(
+        "flex flex-col gap-1 px-4 pt-2 pb-4 lg:px-6",
+        "sm:flex-row sm:items-end sm:gap-4",
+        showTitleBlock ? "sm:justify-between" : "sm:justify-end",
+        className,
+      )}
+    >
+      {/* Title block — hidden visually when showTitleBlock is false; keep h1 for a11y. */}
+      <div className={cn("flex min-w-0 flex-col gap-0.5", !showTitleBlock && "sr-only")}>
+        <h1
+          className="text-2xl font-semibold tracking-tight leading-tight text-foreground"
+          style={{ fontFamily: "var(--font-heading)" }}
+          suppressHydrationWarning
+        >
+          {title}
+        </h1>
+        {showAccess && (
+          <div className="flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1 text-xs leading-snug text-muted-foreground">
+            {accessInfo}
+          </div>
+        )}
+        {subtitle && (
+          <p className="text-sm text-muted-foreground leading-none">{subtitle}</p>
+        )}
+      </div>
+
+      {showActionsColumn && (
+        <div className="flex flex-wrap items-center gap-2 sm:gap-3 shrink-0 sm:ms-auto sm:justify-end">
+          {showCollaborationAccess ? (
+            <PageHeaderCollaborationAccess
+              people={collaborators ?? []}
+              limit={collaboratorDisplayLimit}
+              onOpenCollaborators={onCollaboratorsOpen}
+              addCollaboratorLabel={addCollaboratorLabel}
+            />
+          ) : null}
+          {showCollaboratorActionsSeparator ? (
+            <Separator
+              orientation="vertical"
+              decorative
+              className="h-8 shrink-0"
+            />
+          ) : null}
+          {actions}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/components/ui/payment-card-fields.tsx

@@ -49,14 +49,14 @@ export function PaymentCardFieldsGroup({ className }: { className?: string }) {
           <Input
             {...getExpiryDateProps()}
             id={`card-expiry-${id}`}
-            className="rounded-t-none rounded-r-none shadow-none"
+            className="rounded-t-none rounded-e-none shadow-none"
           />
         </div>
         <div className="-ms-px min-w-0 flex-1 focus-within:z-1">
           <Input
             {...getCVCProps()}
             id={`card-cvc-${id}`}
-            className="rounded-t-none rounded-l-none shadow-none"
+            className="rounded-t-none rounded-s-none shadow-none"
           />
         </div>
       </div>

package/src/components/ui/resizable.tsx

@@ -0,0 +1,68 @@
+"use client"
+
+import * as React from "react"
+import { GripVertical } from "lucide-react"
+import { Group, Panel, Separator } from "react-resizable-panels"
+import type { GroupProps, PanelProps, SeparatorProps } from "react-resizable-panels"
+
+import { cn } from "../../lib/utils"
+
+// ─── ResizablePanelGroup ──────────────────────────────────────────────────────
+
+export type ResizablePanelGroupProps = Omit<GroupProps, "orientation"> & {
+  direction?: "horizontal" | "vertical"
+}
+
+export function ResizablePanelGroup({
+  direction = "horizontal",
+  className,
+  ...props
+}: ResizablePanelGroupProps) {
+  return (
+    <Group
+      orientation={direction}
+      className={cn(
+        "flex h-full w-full",
+        direction === "vertical" && "flex-col",
+        className,
+      )}
+      {...props}
+    />
+  )
+}
+
+// ─── ResizablePanel ───────────────────────────────────────────────────────────
+
+export type ResizablePanelProps = PanelProps
+
+export const ResizablePanel = Panel
+
+// ─── ResizableHandle ──────────────────────────────────────────────────────────
+
+export type ResizableHandleProps = Omit<SeparatorProps, "children"> & {
+  /** Render a visible grip icon on the handle. */
+  withHandle?: boolean
+}
+
+export function ResizableHandle({ withHandle, className, ...props }: ResizableHandleProps) {
+  return (
+    <Separator
+      className={cn(
+        // Base — horizontal handle (between side-by-side panels)
+        "relative flex w-1 shrink-0 cursor-col-resize items-center justify-center bg-border/60",
+        "transition-colors hover:bg-border active:bg-primary/30",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1",
+        // Vertical handle (between stacked panels)
+        "data-[orientation=vertical]:h-1 data-[orientation=vertical]:w-full data-[orientation=vertical]:cursor-row-resize data-[orientation=vertical]:flex-row",
+        className,
+      )}
+      {...props}
+    >
+      {withHandle && (
+        <div className="z-10 flex h-5 w-3.5 items-center justify-center rounded-sm border border-border bg-background shadow-sm">
+          <GripVertical className="h-3 w-3 text-muted-foreground" />
+        </div>
+      )}
+    </Separator>
+  )
+}

package/src/components/ui/scroll-area.tsx

@@ -0,0 +1,72 @@
+"use client"
+
+/**
+ * ScrollArea — Radix-backed scroll container with always-visible-on-hover
+ * scrollbars that respect platform conventions.
+ *
+ * Use when you need an **explicitly bounded** scrolling region (lists in
+ * popovers, sidebar nav trees, long config panels) and the default
+ * browser scrollbar is too coarse or visually noisy.
+ *
+ * Accessibility:
+ *  - Radix manages keyboard scrolling parity with native overflow.
+ *  - The viewport is `role="region"`-compatible — give the wrapper an
+ *    `aria-label` when the content is a meaningful landmark.
+ */
+
+import * as React from "react"
+import { ScrollArea as ScrollAreaPrimitive } from "radix-ui"
+
+import { cn } from "../../lib/utils"
+
+function ScrollArea({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof ScrollAreaPrimitive.Root>) {
+  return (
+    <ScrollAreaPrimitive.Root
+      data-slot="scroll-area"
+      className={cn("relative", className)}
+      {...props}
+    >
+      <ScrollAreaPrimitive.Viewport
+        data-slot="scroll-area-viewport"
+        className="size-full rounded-[inherit] outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background"
+      >
+        {children}
+      </ScrollAreaPrimitive.Viewport>
+      <ScrollBar />
+      <ScrollAreaPrimitive.Corner />
+    </ScrollAreaPrimitive.Root>
+  )
+}
+
+function ScrollBar({
+  className,
+  orientation = "vertical",
+  ...props
+}: React.ComponentProps<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>) {
+  return (
+    <ScrollAreaPrimitive.ScrollAreaScrollbar
+      data-slot="scroll-area-scrollbar"
+      orientation={orientation}
+      className={cn(
+        "flex touch-none select-none p-px transition-colors",
+        orientation === "vertical" &&
+          "h-full w-2.5 border-s border-s-transparent",
+        orientation === "horizontal" &&
+          "h-2.5 w-full flex-col border-t border-t-transparent",
+        className,
+      )}
+      {...props}
+    >
+      <ScrollAreaPrimitive.ScrollAreaThumb
+        data-slot="scroll-area-thumb"
+        className="relative flex-1 rounded-full bg-border hover:bg-border/80"
+      />
+    </ScrollAreaPrimitive.ScrollAreaScrollbar>
+  )
+}
+
+export { ScrollArea, ScrollBar }

package/src/components/ui/selection-tile-grid.tsx

@@ -15,10 +15,17 @@ export interface SelectionTileOption<T extends string = string> {
   leading?: React.ReactNode
 }
 
-/** Shared surface classes for icon+label tiles (Properties view type, Export format, etc.). */
+/** Shared surface classes for icon+label tiles (Properties view type, Export format, etc.).
+ *
+ * `aspect-square` + horizontal padding keeps every tile a uniform square regardless of how
+ * many tiles are in the row — without it, the last row of a `grid-cols-N` grid (e.g. 3 tiles
+ * in a 4-col grid for the Properties view selector) renders the same width per cell but the
+ * eye reads them as inconsistent when the row's empty trailing cell shifts visual rhythm.
+ * Two-line labels (e.g. "List & details", "Tree & details") still fit because the icon
+ * column is only ~18px and the square grows with the cell. */
 export function selectionTileClassNames(selected: boolean) {
   return cn(
-    "flex flex-col items-center justify-center gap-1.5 rounded-lg border py-3 text-xs transition-colors",
+    "flex aspect-square flex-col items-center justify-center gap-1.5 rounded-lg border px-2 py-3 text-xs leading-tight transition-colors",
     "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
     selected
       ? "border-brand bg-brand/5 text-foreground font-medium shadow-sm"

package/src/components/ui/sidebar.tsx

@@ -16,7 +16,21 @@ import {
   TooltipTrigger,
 } from "./tooltip"
 
-const SIDEBAR_COOKIE_NAME = "sidebar_state"
+/**
+ * Cookie persisting the user's explicit expanded/collapsed preference.
+ *
+ * Versioned (`_v2`) on 2026-05-21 to drop stale values written by the
+ * pre-fix code where incidental layout collapses (secondary panel open,
+ * route auto-collapse) would clobber the user's preference on every
+ * navigation. Anyone on the old `sidebar_state` cookie falls back to
+ * the `defaultOpen` default (expanded), and the next explicit toggle
+ * starts persisting under the new name. The old cookie self-expires
+ * by `max-age` within a week; if you want immediate cleanup, the
+ * client clears it explicitly on first mount (see `useLayoutEffect`
+ * below).
+ */
+const SIDEBAR_COOKIE_NAME = "sidebar_state_v2"
+const SIDEBAR_COOKIE_LEGACY_NAME = "sidebar_state"
 const SIDEBAR_COOKIE_MAX_AGE = 60 * 60 * 24 * 7
 /** Matches `useIsMobile` / Tailwind `md:` — do not apply desktop cookie to mobile overlay. */
 const SIDEBAR_COOKIE_VIEWPORT_MQ = "(max-width: 767px)"
@@ -24,14 +38,37 @@ const SIDEBAR_WIDTH = "16rem"
 const SIDEBAR_WIDTH_ICON = "3rem"
 const SIDEBAR_KEYBOARD_SHORTCUT = "b"
 
+/**
+ * Options for {@link SidebarContextProps.setOpen}.
+ *
+ * `persist: false` updates the visual sidebar state **without** writing the
+ * `sidebar_state` cookie. Pass it from incidental layout effects — e.g. a
+ * secondary panel taking the rail space, a route-level auto-collapse — so
+ * the user's explicit preference (their ⌘B toggle / sidebar button) is the
+ * only thing that ever rewrites the cookie. Defaults to `true` for
+ * backward compatibility with the toggle button and existing callsites.
+ */
+type SetOpenOptions = { persist?: boolean }
+
 type SidebarContextProps = {
   state: "expanded" | "collapsed"
   open: boolean
-  setOpen: (open: boolean) => void
+  setOpen: (
+    open: boolean | ((value: boolean) => boolean),
+    opts?: SetOpenOptions,
+  ) => void
   openMobile: boolean
   setOpenMobile: (open: boolean) => void
   isMobile: boolean
   toggleSidebar: () => void
+  /**
+   * Snap the rail back to the user's saved preference — the value persisted in
+   * `sidebar_state_v2`, or `defaultOpen` if no cookie was ever written. Use
+   * this from incidental-collapse cleanups (secondary panel closing, route
+   * leaves) so the rail doesn't stay stuck in its incidental state once the
+   * thing that caused the collapse is gone. Always uses `persist: false`.
+   */
+  restoreSavedOpen: () => void
 }
 
 const SidebarContext = React.createContext<SidebarContextProps | null>(null)
@@ -73,19 +110,35 @@ function SidebarProvider({
   const [_open, _setOpen] = React.useState(defaultOpen)
   const open = openProp ?? _open
 
-  // `setOpen` already persists `sidebar_state` to a cookie on desktop; restore it on mount so
+  // `setOpen` already persists `sidebar_state_v2` to a cookie on desktop; restore it on mount so
   // full reloads and new tabs keep the rail expanded/collapsed. Skip when controlled or on mobile.
+  // Also actively drop the legacy `sidebar_state` cookie (pre-2026-05-21) so stale
+  // collapsed-by-default values written by the old incidental-collapse bug don't linger.
+  //
+  // MOUNT-ONLY: deps are `[]` so this runs once per `SidebarProvider` mount, NOT
+  // every time `open` flips. That matters because incidental collapses
+  // (`setOpen(false, { persist: false })` from a secondary panel opening or
+  // `SidebarAutoCollapse` route) must NOT trigger a re-reconcile that reads the
+  // saved cookie back as "expanded" and snaps the rail open again.
+  // The functional setter avoids closing over a stale `open` value.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
   React.useLayoutEffect(() => {
-    if (openProp !== undefined) return
     if (typeof window === "undefined") return
+    if (typeof document !== "undefined" && document.cookie.includes(`${SIDEBAR_COOKIE_LEGACY_NAME}=`)) {
+      document.cookie = `${SIDEBAR_COOKIE_LEGACY_NAME}=; path=/; max-age=0`
+    }
+    if (openProp !== undefined) return
     if (window.matchMedia(SIDEBAR_COOKIE_VIEWPORT_MQ).matches) return
     const fromCookie = readSidebarStateCookie()
-    if (fromCookie === undefined || fromCookie === open) return
-    _setOpen(fromCookie)
-  }, [openProp, open])
+    if (fromCookie === undefined) return
+    _setOpen((prev) => (prev === fromCookie ? prev : fromCookie))
+  }, [])
 
   const setOpen = React.useCallback(
-    (value: boolean | ((value: boolean) => boolean)) => {
+    (
+      value: boolean | ((value: boolean) => boolean),
+      opts?: SetOpenOptions,
+    ) => {
       const openState = typeof value === "function" ? value(open) : value
       if (setOpenProp) {
         setOpenProp(openState)
@@ -93,8 +146,12 @@ function SidebarProvider({
         _setOpen(openState)
       }
 
-      // Persist on desktop only — zooming in and closing shouldn't clobber the desktop state.
-      if (!isMobile) {
+      // Persist on desktop only — zooming in and closing shouldn't clobber the
+      // desktop state. Callers can also opt out explicitly (`persist: false`)
+      // for incidental layout collapses such as a secondary panel opening or
+      // an auto-collapse route; those visual side-effects must not overwrite
+      // the user's saved expanded/collapsed preference.
+      if (!isMobile && opts?.persist !== false) {
         document.cookie = `${SIDEBAR_COOKIE_NAME}=${openState}; path=/; max-age=${SIDEBAR_COOKIE_MAX_AGE}`
       }
     },
@@ -106,6 +163,20 @@ function SidebarProvider({
     setOpen((open) => !open)
   }, [setOpen])
 
+  /**
+   * Snap the rail back to the user's saved preference. Called when a secondary
+   * panel closes or an auto-collapse route is left — so an incidental collapse
+   * doesn't persist beyond the page that caused it. `persist: false` because
+   * this restore is itself incidental; the only writes to the cookie should
+   * still come from real user gestures (⌘B, sidebar button).
+   */
+  const restoreSavedOpen = React.useCallback(() => {
+    if (typeof window === "undefined") return
+    const fromCookie = readSidebarStateCookie()
+    const target = fromCookie ?? defaultOpen
+    setOpen(target, { persist: false })
+  }, [defaultOpen, setOpen])
+
   // Adds a keyboard shortcut to toggle the sidebar.
   React.useEffect(() => {
     const handleKeyDown = (event: KeyboardEvent) => {
@@ -138,8 +209,9 @@ function SidebarProvider({
       openMobile,
       setOpenMobile,
       toggleSidebar,
+      restoreSavedOpen,
     }),
-    [state, open, setOpen, isMobile, openMobile, setOpenMobile, toggleSidebar]
+    [state, open, setOpen, isMobile, openMobile, setOpenMobile, toggleSidebar, restoreSavedOpen]
   )
 
   return (
@@ -569,7 +641,7 @@ const SidebarMenuButton = React.forwardRef<
     return button
   }
 
-  let tooltipProps: React.ComponentProps<typeof TooltipContent> =
+  const tooltipProps: React.ComponentProps<typeof TooltipContent> =
     typeof tooltip === "string" ? { children: tooltip } : tooltip
 
   return (