@veluai/velu 0.1.0

package/runtime/velu-ui/components/docs-layout.css

@@ -0,0 +1,775 @@
+/* DocsLayout — the chrome of a Velu docs page (header, fixed left
+   sidebar, center column, fixed right TOC, footer). The interesting
+   bit lives in the @container rule at the bottom: at narrow widths
+   the right TOC is hidden and the center column expands, with no
+   media queries. Container query → reacts to the layout wrapper's
+   inline-size, not the viewport, so the same component works in any
+   surrounding shell (modal, split view, etc).
+
+   All values are tokens; light/dark via [data-theme]. */
+
+.velu-docs-layout {
+  /* `inline-size` containment lets @container queries below react to
+     this element's width. `docs` is the named container so component
+     CSS elsewhere can target it specifically. */
+  container-type: inline-size;
+  container-name: docs;
+
+  /* Rail width — exposed as a custom property so the actual rail
+     element AND the centre-column margin that tracks it can reference
+     a single source of truth. Set OUTSIDE the @container block so the
+     value is unconditionally inherited by descendants (defining it
+     inside the container query was leaving it un-set for descendants
+     in some cascade edge cases, so the rail collapsed to 0 width). */
+  --velu-rail-width: 3.5rem; /* 56px */
+  /* Left sidebar column width — single source of truth so the aside
+     and the centre-column margin that reserves space for it stay in
+     sync. Wide enough that nav labels don't wrap given the left inset
+     gutter on the aside. */
+  --velu-sidebar-width: 18rem; /* 288px */
+  /* Right column reserve — the TOC aside width AND the centre's right
+     margin. Constant whether the TOC or the chatbot is shown, so the
+     article never shifts when the chatbot opens. The chatbot is wider
+     than this and simply slides OVER the right edge as a floating
+     panel (its own --vchat-width), rather than reflowing the article. */
+  --velu-aside-right-width: 17.5rem; /* 280px */
+
+  display: flex;
+  flex-direction: column;
+  min-height: 100vh;
+  background: var(--page-bg);
+}
+
+/* ── Asides (fixed left sidebar + right TOC) ───────────────────────── */
+.velu-docs-layout__aside {
+  position: fixed;
+  /* Span full viewport height so the aside extends behind the
+     translucent header (its top shows through the header's frost on
+     scroll). Inner padding-top pushes the nav content down below the
+     header band; scroll-padding-top keeps auto-scroll out of it. */
+  inset-block-start: 0;
+  inset-block-end: 0;
+  overflow-y: auto;
+  /* Horizontal clip: the left aside animates its `inline-size` down
+     to a thin rail when collapsed, and its child nav (which keeps
+     its full intrinsic width) MUST be visually cropped to the new
+     box. `overflow-y: auto` + `overflow-x: clip` is allowed (clip
+     is the spec partner that works with a scrollable y-axis) and
+     gives reliable visual clipping that pure `overflow: hidden`
+     can interact badly with on a `position: fixed` element. */
+  overflow-x: clip;
+  overscroll-behavior: contain;
+  padding-block-start: calc(var(--velu-header-height) + var(--s3));
+  scroll-padding-block-start: var(--velu-header-height);
+  z-index: 10;
+  /* `inline-size` is animated for the narrow-width collapse
+     (240px ↔ rail). `transform` is animated for the mobile drawer
+     (translateX(-100%) ↔ 0). Both timings live on the same property
+     list so each animation runs only when its property actually
+     changes at the active breakpoint. */
+  transition: inline-size 0.2s ease, transform 0.25s ease;
+}
+
+.velu-docs-layout__aside--left {
+  inset-inline-start: 0;
+  inline-size: var(--velu-sidebar-width);
+  /* Left gutter so the nav sits inset from the viewport edge rather
+     than hugging it. (At mobile the @container block resets this to 0
+     — the drawer manages its own padding.) */
+  padding-inline-start: var(--s5);
+  padding-inline-end: 0;
+  /* The aside itself does NOT scroll — it's a flex column whose context
+     zone (anchors/switchers) stays pinned and whose nav region
+     (.velu-docs-nav-scroll) scrolls on its own. Overrides the base
+     aside's `overflow-y: auto`. */
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  /* Bottom boundary: end the column a fixed gap above the viewport
+     bottom (mirrors the pinned top), so the nav scrolls within a
+     contained panel rather than running to the screen edge. The value
+     is driven by --velu-aside-bottom (set inline in App.jsx) so the
+     edge lifts to stay above the footer as it scrolls in; falls back
+     to a static gap. The mobile drawer resets this to 0. */
+  inset-block-end: var(--velu-aside-bottom, var(--s4));
+}
+/* Stack wrapper fills the aside so the inner nav region can flex-grow
+   and own the scroll. */
+.velu-docs-aside-stack {
+  flex: 1 1 auto;
+  min-block-size: 0;
+}
+/* Region wrapping the scroll area + the overlay arrows. Fills the
+   remaining aside height; relative so the arrows position to its
+   top/bottom edges. */
+.velu-docs-nav-region {
+  position: relative;
+  flex: 1 1 auto;
+  min-block-size: 0;
+  display: flex;
+  flex-direction: column;
+}
+.velu-docs-nav-scroll {
+  flex: 1 1 auto;
+  min-block-size: 0;
+  overflow-y: auto;
+}
+
+/* Up / down scroll arrows — circular buttons centered on the top and
+   bottom edges of the scroll region. Hidden by default; revealed (via
+   the sibling combinator off the scroll div's data-fade-* attrs) only
+   when there's content beyond that edge. Clicking smooth-scrolls the
+   nav fully to that end (handlers in App.jsx). */
+.velu-docs-nav-arrow {
+  position: absolute;
+  inset-inline-start: 50%;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  inline-size: 2rem;
+  block-size: 2rem;
+  padding: 0;
+  border: var(--border-width) solid var(--border-color);
+  border-radius: 999px;
+  background: var(--page-bg);
+  color: var(--muted-color);
+  cursor: pointer;
+  z-index: 3;
+  opacity: 0;
+  pointer-events: none;
+  transform: translateX(-50%) scale(0.9);
+  transition: opacity 0.15s ease, transform 0.15s ease, color 0.12s ease,
+    border-color 0.12s ease;
+  box-shadow: 0 var(--s-4) var(--s-1) color-mix(in srgb, #000 10%, transparent);
+}
+.velu-docs-nav-arrow:hover {
+  color: var(--accent-color);
+  border-color: var(--accent-color);
+}
+.velu-docs-nav-arrow svg {
+  inline-size: 1.1em;
+  block-size: 1.1em;
+}
+.velu-docs-nav-arrow--up {
+  inset-block-start: var(--s-3);
+}
+.velu-docs-nav-arrow--down {
+  inset-block-end: var(--s-3);
+}
+/* Reveal only while hovering the sidebar AND there's content beyond
+   that edge. */
+.velu-docs-layout__aside--left:hover
+  .velu-docs-nav-scroll[data-fade-top='true']
+  ~ .velu-docs-nav-arrow--up,
+.velu-docs-layout__aside--left:hover
+  .velu-docs-nav-scroll[data-fade-bottom='true']
+  ~ .velu-docs-nav-arrow--down {
+  opacity: 1;
+  pointer-events: auto;
+  transform: translateX(-50%) scale(1);
+}
+
+/* Edge fade: the scroll regions (left nav + right TOC) fade to
+   transparent at whichever edge has more content beyond it. The
+   --vf-top / --vf-bottom lengths default to 0 (no fade) and are
+   switched on by the data-fade-* attrs that App.jsx sets from scroll
+   position — so the top only fades once you've scrolled down, and the
+   bottom fade vanishes when you reach the end. */
+.velu-docs-nav-scroll,
+.velu-docs-layout__aside--right {
+  --vf-top: 0px;
+  --vf-bottom: 0px;
+  -webkit-mask-image: linear-gradient(
+    to bottom,
+    transparent,
+    #000 var(--vf-top),
+    #000 calc(100% - var(--vf-bottom)),
+    transparent
+  );
+  mask-image: linear-gradient(
+    to bottom,
+    transparent,
+    #000 var(--vf-top),
+    #000 calc(100% - var(--vf-bottom)),
+    transparent
+  );
+}
+/* Top fade only on the right TOC — the left nav uses sticky section
+   headers as its top treatment, so a top fade would just blur the
+   pinned heading. */
+.velu-docs-layout__aside--right[data-fade-top='true'] {
+  --vf-top: var(--s2);
+}
+/* The left nav's under-heading fade (the ::after below each sticky
+   section heading) is shown only while the nav is scrolled up, so a
+   section's first item isn't dimmed at rest. */
+.velu-docs-nav-scroll[data-fade-top='true'] .velu-sidebar__section::after {
+  opacity: 1;
+}
+.velu-docs-nav-scroll[data-fade-bottom='true'],
+.velu-docs-layout__aside--right[data-fade-bottom='true'] {
+  --vf-bottom: var(--s2);
+}
+
+.velu-docs-layout__aside--right {
+  inset-inline-end: 0;
+  inline-size: var(--velu-aside-right-width);
+  padding-inline: var(--s1);
+}
+
+/* Scrollbars hide at rest and reveal only while the cursor is over the
+   column. Applies to the right TOC aside (scrolls directly) and the
+   left nav's inner scroll region (.velu-docs-nav-scroll). The gutter
+   stays reserved (scrollbar-width: thin from .velu-hide-scrollbar) —
+   only the thumb's color toggles — so revealing it never shifts
+   content. Overrides .velu-hide-scrollbar's always-on thumb. */
+.velu-docs-layout__aside--right,
+.velu-docs-nav-scroll {
+  scrollbar-color: transparent transparent;
+}
+.velu-docs-layout__aside--right:hover,
+.velu-docs-layout__aside--left:hover .velu-docs-nav-scroll {
+  scrollbar-color: var(--border-color) transparent;
+}
+.velu-docs-layout__aside--right::-webkit-scrollbar-thumb,
+.velu-docs-nav-scroll::-webkit-scrollbar-thumb {
+  background: transparent;
+}
+.velu-docs-layout__aside--right:hover::-webkit-scrollbar-thumb,
+.velu-docs-layout__aside--left:hover .velu-docs-nav-scroll::-webkit-scrollbar-thumb {
+  background: var(--border-color);
+}
+.velu-docs-layout__aside--right:hover::-webkit-scrollbar-thumb:hover,
+.velu-docs-layout__aside--left:hover .velu-docs-nav-scroll::-webkit-scrollbar-thumb:hover {
+  background: var(--muted-color);
+}
+
+/* ── Center column ─────────────────────────────────────────────────── */
+/* Reserves the aside widths via margin so the article never slides
+   under them. The end margin collapses to 0 while the chatbot is
+   open (the right TOC is hidden then, the chatbot uses that slot).
+   Both can be overridden by the container query below. */
+.velu-docs-layout__center {
+  position: relative;
+  min-inline-size: 0;
+  margin-inline-start: var(--velu-sidebar-width);
+  /* Right reserve stays constant whether the right TOC or the chatbot
+     occupies it — so opening the chatbot does NOT shift the article.
+     The chatbot's desktop width matches this reserve (chatbot.css) so
+     it never overlaps the content. */
+  margin-inline-end: var(--velu-aside-right-width);
+  /* Tracks the sidebar's `inline-size` animation at narrow widths so
+     the article slides in sync with the collapse, no snap. Same 0.2s
+     timing as the aside's own `inline-size` transition. */
+  transition: margin-inline-start 0.2s ease;
+}
+
+/* <main> inside the centre column owns the article-area padding —
+   defined here (not inline) so the narrow + sidebar-closed @container
+   rule below can override just the inline-start side. */
+.velu-docs-layout__main {
+  padding-block-start: var(--s3);
+  padding-inline: var(--s4);
+}
+
+/* Article wrapper inside <main> — caps the prose at 46rem and centres
+   it by default. Container query below switches it to left-aligned
+   when the sidebar is closed at narrow widths, so the article hugs
+   the freed space rather than centring inside it (which would leave
+   the perceived "ghost sidebar" on the left). */
+.velu-docs-layout__article {
+  max-inline-size: 46rem;
+  margin-inline: auto;
+}
+
+/* Inner sidebar content (the <Sidebar> nav root, direct child of the
+   left aside) cross-fades during the collapse animation. Hidden when
+   the layout's `data-sidebar-open='false'` flag is set — see the
+   @container block below for the actual opacity:0 toggle, which is
+   scoped to narrow widths only (sidebar can't collapse at wide). */
+.velu-docs-layout__aside--left > * {
+  transition: opacity 0.15s ease;
+}
+
+/* ── Scrim (mobile-only) ───────────────────────────────────────────── */
+/* Backdrop layer behind the mobile drawer — dims + blurs the article
+   underneath and absorbs pointer events so nothing beneath is
+   clickable while the drawer is open. Always in the DOM so the
+   opacity + visibility transition runs in both directions; toggled
+   visible via [data-sidebar-open='true'] in the @container block
+   at the bottom. */
+.velu-docs-layout__scrim {
+  /* Hidden until the mobile @container block flips display on. */
+  display: none;
+  position: fixed;
+  inset: 0;
+  z-index: 34;
+  background: color-mix(in srgb, #000 28%, transparent);
+  backdrop-filter: blur(4px);
+  -webkit-backdrop-filter: blur(4px);
+  /* Closed state — invisible + non-interactive. The
+     [data-sidebar-open='true'] rule below flips both back on. */
+  opacity: 0;
+  pointer-events: none;
+  visibility: hidden;
+  transition:
+    opacity 0.25s ease,
+    visibility 0s linear 0.25s;
+  cursor: pointer;
+}
+
+/* ── Drawer chrome (mobile-only) ───────────────────────────────────── */
+/* Drawer-only elements (brand bar + docs-set selector) — hidden at
+   wide / narrow widths; the @container block at the bottom flips them
+   on at mobile. Defined here (above the @container blocks) so source
+   order works in the cascade's favor. */
+.velu-docs-layout__drawer-head,
+.velu-docs-layout__drawer-docselect {
+  display: none;
+}
+.velu-docs-layout__drawer-brand {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--s-3);
+  color: inherit;
+  text-decoration: none;
+}
+.velu-docs-layout__drawer-brand .velu-header__mark {
+  inline-size: 2em;
+  block-size: 1.5em;
+  color: var(--accent-color);
+}
+.velu-docs-layout__drawer-close {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  inline-size: 1.5rem;
+  block-size: 1.5rem;
+  padding: 0;
+  background: transparent;
+  border: 0;
+  color: var(--text-color);
+  cursor: pointer;
+}
+.velu-docs-layout__drawer-close svg {
+  inline-size: 1.5rem;
+  block-size: 1.5rem;
+  stroke-width: 1;
+}
+.velu-docs-layout__drawer-docselect {
+  position: relative;
+}
+.velu-docs-layout__drawer-docselect-btn {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  inline-size: 100%;
+  /* 8px top/bottom — matches the modular-scale step --s-3 (~0.5rem). */
+  padding-block: var(--s-3);
+  padding-inline: var(--s0);
+  background: var(--page-bg);
+  border: var(--border-width) solid var(--border-color);
+  border-radius: var(--radius-sm);
+  font: inherit;
+  font-size: var(--f-h5);
+  color: var(--text-color);
+  text-align: start;
+  cursor: pointer;
+  transition: border-color 0.12s ease;
+}
+.velu-docs-layout__drawer-docselect-btn:hover {
+  border-color: var(--accent-color);
+}
+.velu-docs-layout__drawer-docselect-label {
+  flex: 1;
+  min-inline-size: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.velu-docs-layout__drawer-docselect-chev {
+  inline-size: 1em;
+  block-size: 1em;
+  stroke-width: 1;
+  /* Match the label color (not the muted variant the kebab/search
+     icons use) — the chevron reads as part of the trigger text, not
+     a secondary indicator. */
+  color: var(--text-color);
+  stroke: currentColor;
+  flex: none;
+  transition: transform 0.18s ease;
+}
+.velu-docs-layout__drawer-docselect[data-open='true']
+  .velu-docs-layout__drawer-docselect-chev {
+  transform: rotate(180deg);
+}
+
+/* Menu — anchored below the trigger, full width of the wrapper.
+   Always in the DOM so the open/close transition can run in both
+   directions; visibility delayed so the closed menu isn't focusable
+   or click-able. */
+.velu-docs-layout__drawer-docselect-menu {
+  position: absolute;
+  inset-block-start: calc(100% + var(--s-3));
+  inset-inline-start: 0;
+  inset-inline-end: 0;
+  margin: 0;
+  padding-block: var(--s-2);
+  padding-inline: 0;
+  list-style: none;
+  background: var(--page-bg);
+  border: var(--border-width) solid var(--border-color);
+  border-radius: var(--radius-sm);
+  box-shadow: 0 var(--s-2) var(--s1)
+    color-mix(in srgb, #000 12%, transparent);
+  opacity: 0;
+  visibility: hidden;
+  transform: translateY(-0.25rem);
+  pointer-events: none;
+  transition:
+    opacity 0.15s ease,
+    transform 0.15s ease,
+    visibility 0s linear 0.15s;
+  z-index: 1;
+}
+.velu-docs-layout__drawer-docselect[data-open='true']
+  .velu-docs-layout__drawer-docselect-menu {
+  opacity: 1;
+  visibility: visible;
+  transform: translateY(0);
+  pointer-events: auto;
+  transition:
+    opacity 0.15s ease,
+    transform 0.15s ease,
+    visibility 0s;
+}
+.velu-docs-layout__drawer-docselect-item {
+  display: block;
+  padding-block: var(--s-2);
+  padding-inline: var(--s0);
+  font-size: var(--f-h5);
+  color: var(--text-color);
+  text-decoration: none;
+  cursor: pointer;
+  transition: background 0.12s ease, color 0.12s ease;
+}
+.velu-docs-layout__drawer-docselect-item:hover {
+  background: var(--surface-color);
+  color: var(--accent-color);
+}
+
+/* ── Sidebar toggle (narrow-width only) ────────────────────────────── */
+/* Small chevron button straddling the sidebar/article boundary.
+   `position: fixed` (not absolute) so it stays pinned to the
+   viewport while the article scrolls — the chevron is always
+   reachable, never buried below the fold. It sits one button-radius
+   below the header and is centred on the boundary between the
+   sidebar/rail and the article column. That boundary is exposed
+   via the `--velu-sidebar-boundary` custom property (defaults to
+   240px when the sidebar is open; collapses to the rail width
+   when closed — see @container rules below).
+
+   Hidden by default; revealed only at narrow widths. */
+.velu-docs-layout__sidebar-toggle {
+  display: none;
+  position: fixed;
+  /* Toggle sits well below the TocBar so it doesn't crowd the
+     bar's bottom border. --s5 (~49px) clears the TocBar height
+     itself; adding --s2 (~25px) gives a clear breathing gap. */
+  inset-block-start: calc(var(--velu-header-height) + var(--s5) + var(--s2));
+  /* Sidebar's right edge minus half the toggle's own width — centres
+     the 2rem button on the divider. Tracks the actual sidebar width. */
+  inset-inline-start: calc(var(--velu-sidebar-boundary, var(--velu-sidebar-width)) - 1rem);
+  inline-size: 2rem;
+  block-size: 2rem;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  border: var(--border-width) solid var(--border-color);
+  border-radius: 999px;
+  background: var(--page-bg);
+  color: var(--muted-color);
+  cursor: pointer;
+  transition: border-color 0.12s ease, color 0.12s ease,
+    inset-inline-start 0.2s ease;
+  z-index: 11;
+}
+.velu-docs-layout__sidebar-toggle:hover {
+  border-color: var(--accent-color);
+  color: var(--accent-color);
+}
+
+/* ── Narrow-width layout ───────────────────────────────────────────── */
+/* Container query (not media query) so the layout reacts to the
+   wrapper's inline-size — works the same inside a modal, split pane,
+   or shrunken window. At < 1024px the right TOC drops out and the
+   centre column expands to fill its slot; the left sidebar becomes
+   toggleable via the sidebar-toggle button (default open, per
+   design). Closing pushes the centre column over rather than overlaying. */
+@container docs (max-width: 1024px) {
+  .velu-docs-layout__aside--right {
+    display: none;
+  }
+  .velu-docs-layout__center {
+    margin-inline-end: 0;
+  }
+  .velu-docs-layout__sidebar-toggle {
+    display: inline-flex;
+  }
+  /* Hairline divider on the left sidebar — only at narrow widths,
+     where the sidebar visually separates from the article column.
+     Same --surface-color recipe as the header/footer rails. The big
+     desktop left-inset is dialed back here (tablet); mobile resets it
+     to 0 via the drawer block below. */
+  .velu-docs-layout__aside--left {
+    border-inline-end: var(--border-width) solid var(--surface-color);
+    padding-inline-start: var(--s2);
+  }
+  /* Sidebar closed → shrink the aside's `inline-size` from 240px to
+     the rail width. The aside stays in the DOM and keeps its own
+     border-inline-end — that border IS the rail's right edge when
+     collapsed, no separate rail element needed. `overflow-x: clip`
+     on the aside (set above) crops the still-rendered Sidebar nav
+     to the narrowed box; the opacity rule below fades the nav out
+     so the collapsed state reads as a clean stub.
+     The aside's `transition: inline-size 0.2s ease` (set above) is
+     what makes the collapse animate; the centre column tracks via
+     its own `margin-inline-start` transition. */
+  .velu-docs-layout[data-sidebar-open='false']
+    .velu-docs-layout__aside--left {
+    inline-size: var(--velu-rail-width);
+    /* Collapsed state is a thin stub — the (faded) nav is irrelevant,
+       so suppress the y-scrollbar that would otherwise appear over
+       the rail. `overflow-y: auto` is restored implicitly at wide
+       widths / open state by the base `.velu-docs-layout__aside`
+       rule above. */
+    overflow-y: hidden;
+  }
+  /* Fade out the Sidebar nav while the aside shrinks — opacity
+     transitions in parallel with `inline-size`, so the user sees a
+     single coherent collapse (shrink + fade) rather than a snap. */
+  .velu-docs-layout[data-sidebar-open='false']
+    .velu-docs-layout__aside--left > * {
+    opacity: 0;
+    pointer-events: none;
+  }
+  .velu-docs-layout[data-sidebar-open='false']
+    .velu-docs-layout__center {
+    margin-inline-start: var(--velu-rail-width);
+  }
+  /* Toggle position tracks the active boundary directly — when the
+     sidebar is closed the boundary moves from 240px (sidebar's right
+     edge) to var(--velu-rail-width) (rail's right edge), so the
+     toggle slides with it. Overriding the property here (instead of
+     going through a custom-prop indirection) keeps the transition
+     reliable across engines. */
+  .velu-docs-layout[data-sidebar-open='false']
+    .velu-docs-layout__sidebar-toggle {
+    inset-inline-start: calc(var(--velu-rail-width) - 1rem);
+  }
+  /* At narrow widths the article drops its 46rem cap and fills the
+     available main width. Cap survives at wide widths so the 46rem
+     prose column lives between the two asides. */
+  .velu-docs-layout__article {
+    max-inline-size: none;
+    margin-inline: 0;
+  }
+}
+
+/* ── Mobile-width layout (< 640px) ─────────────────────────────────── */
+/* At mobile widths the centre column reclaims full width regardless
+   of sidebar state. The sidebar becomes a RIGHT-edge drawer (anchored
+   to the trailing edge, slides in from the right) — opened by the
+   header's burger OR by tapping the breadcrumb strip, both of which
+   call `onMenuClick` → toggles the layout's `data-drawer-open` flag.
+   Note: mobile uses its OWN `data-drawer-open` attribute, separate
+   from `data-sidebar-open` (which drives the narrow-width rail
+   collapse). Two independent states avoid the SSR/hydration default
+   collision that would force the drawer to render open on refresh.
+   The floating chevron toggle is removed; it was a wide-layout
+   affordance and is redundant at mobile. */
+@container docs (max-width: 640px) {
+  .velu-docs-layout__sidebar-toggle {
+    display: none;
+  }
+  .velu-docs-layout__center,
+  .velu-docs-layout[data-sidebar-open='false'] .velu-docs-layout__center {
+    margin-inline-start: 0;
+  }
+  .velu-docs-layout__aside--left {
+    /* Anchor to the right edge instead of the left — override the
+       base `inset-inline-start: 0` from .velu-docs-layout__aside--left
+       so the drawer slides in from the trailing edge. Full viewport
+       height comes from the base `inset-block: 0 0` on the aside.
+       Drop the header-clearance top padding — the drawer has its own
+       brand bar. Inline padding stays at 0 — the Sidebar items have
+       their own `padding-inline: var(--s0)` (16px), and the drawer
+       chrome below gets matching `padding-inline` directly, so the
+       inner content lines up 16px from the drawer edge without
+       double-padding. */
+    inset-inline-start: auto;
+    inset-inline-end: 0;
+    /* Full-height drawer — no bottom boundary gap (overrides the
+       desktop panel inset). */
+    inset-block-end: 0;
+    inline-size: min(20rem, 85vw);
+    padding-block-start: var(--s0);
+    padding-inline: 0;
+    /* Closed default — fully off the trailing edge. The
+       data-sidebar-open='true' rule below brings it back in. */
+    transform: translateX(100%);
+    /* Above the sticky header (z-index 30 in page-header.css) so the
+       drawer covers the header bar too, but below the search palette
+       (z-index 60) and chatbot (z-index 50). The aside already spans
+       the full viewport via the base `inset-block: 0 0`. */
+    z-index: 35;
+    /* Solid body background — the aside has no background by default
+       (it inherits the layout's page-bg by virtue of being a child),
+       but at mobile it's a `position: fixed` drawer that overlays the
+       article + header, so transparency would let everything beneath
+       bleed through. Explicit --page-bg makes the drawer opaque. */
+    background: var(--page-bg);
+  }
+  /* Shadow only when the drawer is OPEN — when closed the drawer
+     sits off-screen right via `translateX(100%)`, and a left-edge
+     shadow would bleed leftward into the visible viewport (a ghost
+     band along the right edge). Gating to the open state keeps the
+     depth cue while the drawer is visible and hides it the rest of
+     the time. */
+  .velu-docs-layout[data-drawer-open='true']
+    .velu-docs-layout__aside--left {
+    transform: translateX(0);
+    box-shadow:
+      calc(-1 * var(--s0)) 0 var(--s2)
+        color-mix(in srgb, #000 18%, transparent);
+  }
+  /* Drop the narrow-width opacity fade / overflow-hidden on the
+     drawer's inner content — at mobile the narrow-width rules above
+     (data-sidebar-open='false') still apply because sidebarOpen
+     defaults to true and may flip via the chevron at narrow widths,
+     but at mobile we want the inner nav fully visible and the
+     drawer scrollable regardless of those narrow rules. */
+  .velu-docs-layout__aside--left > * {
+    opacity: 1;
+    pointer-events: auto;
+  }
+  /* The aside stays a non-scrolling flex column on mobile too; the
+     nav region (.velu-docs-nav-scroll) owns the scroll, with the
+     context zone pinned above it. */
+  .velu-docs-layout__aside--left {
+    overflow: hidden;
+  }
+  /* Drawer chrome — brand bar + docs-set selector — visible only at
+     mobile (default-hidden above). Both elements get `padding-inline:
+     var(--s0)` so their content lines up at the same 16px-from-edge
+     position the Sidebar items below them use (which inherit
+     `padding-inline: var(--s0)` from sidebar.css). */
+  .velu-docs-layout__drawer-head {
+    display: flex;
+    align-items: center;
+    gap: var(--s-1);
+    padding-inline: var(--s0);
+  }
+  .velu-docs-layout__drawer-head .velu-theme-toggle {
+    margin-inline-start: auto;
+  }
+  .velu-docs-layout__drawer-docselect {
+    display: block;
+    margin-inline: var(--s0);
+    /* Inset 16px from each drawer edge; Stack (column flex with
+       align-items: stretch) stretches it across the remaining width.
+       `align-self: stretch` explicit for engines that don't honor
+       the parent's default stretch. */
+    align-self: stretch;
+  }
+  /* Scrim — present at mobile; toggled on by the mobile nav drawer
+     here. The chatbot's bottom-sheet variant exists at the wider
+     `< 1024px` threshold, so the chatbot-driven scrim is enabled in
+     a SECOND @container block below (at the same wider threshold) —
+     keeping the drawer-only scrim scoped to mobile and the
+     chatbot-driven scrim available to both narrow and mobile. */
+  .velu-docs-layout__scrim {
+    display: block;
+  }
+  .velu-docs-layout[data-drawer-open='true'] .velu-docs-layout__scrim {
+    opacity: 1;
+    pointer-events: auto;
+    visibility: visible;
+    transition:
+      opacity 0.25s ease,
+      visibility 0s;
+  }
+}
+
+/* ── Chatbot scrim (narrow + mobile, < 1024px) ─────────────────────── */
+/* The chatbot becomes a bottom sheet at < 1024px (see chatbot.css);
+   the scrim follows the same threshold so the dim+blur layer appears
+   over the article whenever the sheet is up. The mobile-only
+   `data-drawer-open` trigger lives in the < 640px block above —
+   separate because the drawer itself doesn't exist at narrow widths. */
+@container docs (max-width: 1024px) {
+  .velu-docs-layout__scrim {
+    display: block;
+  }
+  .velu-docs-layout[data-chat-open='true'] .velu-docs-layout__scrim {
+    opacity: 1;
+    pointer-events: auto;
+    visibility: visible;
+    transition:
+      opacity 0.25s ease,
+      visibility 0s;
+  }
+}
+
+/* ── Sidebar context zone + responsive switcher helpers ────────────── */
+/* Product / version / language switchers + anchors above the group
+   nav. Inset matches the Sidebar items (which carry padding-inline:
+   var(--s0) from sidebar.css). */
+.velu-docs-context {
+  flex: none;
+  padding-inline: var(--s0);
+}
+.velu-docs-anchors {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: var(--s-3);
+}
+.velu-docs-anchors__link {
+  display: flex;
+  align-items: center;
+  gap: var(--s-3);
+  color: var(--text-color);
+  text-decoration: none;
+  font-size: var(--f-h6);
+  transition: color 0.12s ease;
+}
+.velu-docs-anchors__link:hover {
+  color: var(--accent-color);
+}
+.velu-docs-anchors__icon {
+  display: inline-flex;
+  flex: none;
+  color: var(--muted-color);
+}
+.velu-docs-anchors__link:hover .velu-docs-anchors__icon {
+  color: var(--accent-color);
+}
+
+/* Show/hide helpers, scoped to the docs container's mobile breakpoint.
+   Version + language switchers live in the header at desktop/tablet
+   (hide-on-mobile) and re-appear in the drawer context zone on mobile
+   (show-on-mobile). */
+.velu-show-on-mobile {
+  display: none;
+}
+@container docs (max-width: 640px) {
+  .velu-hide-on-mobile {
+    display: none !important;
+  }
+  .velu-show-on-mobile {
+    display: block;
+  }
+}