fix(FR-2770): polish docs sider version selector and mobile topbar layout (#7143)

yomybaby · yomybaby · commit 87e108b23e66 · 2026-04-28T21:42:41.000Z
Resolves #7142 ([FR-2770](https://lablup.atlassian.net/browse/FR-2770)) ## Summary Tightens visual polish on the docs static site after the FR-2733 / FR-2758 phases. Touches `packages/backend.ai-docs-toolkit/src/styles-web.ts` and `packages/backend.ai-docs-toolkit/src/website-builder.ts`. ### Sider version selector - Switched the sider to a flex column with `overflow: hidden`, and moved scrolling to a new `.doc-sidebar__scroll` wrapper (intro + nav groups) so the version block sits **outside** the scroll area. The version selector is now structurally pinned to the top of the sider — no `position: sticky` / z-index tricks needed, no opaque-background hack required for the bottom border. - Version block now renders horizontally: uppercase label on the left, `<select>` on the right via `justify-content: space-between`, with an **edge-to-edge** soft bottom rule. Padding is `14px 24px 10px` so the label aligns with the indentation of the nav category headers below (which combine `.doc-sidebar__scroll` 8px + `.doc-sidebar-group` 6px margin + summary 10px padding = 24px from the sider edge). - Added `min-width: 132px` on the native `<select>` so the control no longer auto-shrinks when the only option is short (e.g., `next`). ### Mobile drawer scroll chaining - iOS/Android touch handling was routing the gesture to `<body>` once the sider hit a scroll boundary, causing "menu sometimes scrolls, sometimes the article behind scrolls instead." Fixed by: - Locking the underlying page (`body.bai-drawer-open { overflow: hidden; touch-action: none; }`). - Containing the drawer's overscroll (`.doc-sidebar { overscroll-behavior: contain; touch-action: pan-y; }` in drawer mode). - Defense-in-depth: same `overscroll-behavior: contain` on the desktop `.doc-sidebar__scroll` so wheel/trackpad scrolling in the nav doesn't bleed into the article. ### Mobile topbar layout - Hamburger SVG paths changed from `M4 6h16` to `M3 6h18` so the bars span the full 18-unit icon box edge-to-edge (matching the GitHub icon's content distribution). The previous 4..20 span left ~3px of dead space inside the SVG, making the menu glyph visually **inset** versus the right-edge buttons even though the button paddings were symmetric. - On `≤ 880px`, set `.bai-topbar { gap: 6px }` so the search-icon-button → first-action-button distance matches the action-button → action-button distance (which is also 6px). The previous 14px top-level gap clashed with the 6px cluster gap, making the search button look detached from the rest of the icon row. ## Test plan - [ ] `bash scripts/verify.sh` reports `=== ALL PASS ===`. - [ ] `pnpm --filter backend.ai-docs-toolkit test` (162 tests) passes. - [ ] `pnpm --filter backend.ai-webui-docs run build:web:en` regenerates pages without errors. - [ ] On the served site (desktop): the version block sits flush at the top of the sider, label aligns with the nav category labels below, and the bottom border spans the full sider width. Scrolling the nav (wheel) doesn't scroll the article. - [ ] On a real phone (or DevTools mobile emulation ≤ 880px): opening the drawer locks the article behind it; the menu always scrolls regardless of where the touch lands or whether you've already hit the top/bottom of the nav. The hamburger and the rightmost icon button sit at the same visual inset from their respective screen edges; the search icon is grouped with the lang/theme/github cluster at a uniform 6px rhythm. - [ ] Switch language (en/ko/ja/th) — the localized "Version" label still fits horizontally next to the switcher without wrapping. [FR-2770]: https://lablup.atlassian.net/browse/FR-2770?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ
diff --git a/packages/backend.ai-docs-toolkit/src/styles-web.ts b/packages/backend.ai-docs-toolkit/src/styles-web.ts
@@ -730,8 +730,38 @@ body.bai-drawer-open .bai-scrim {
     border-right: 1px solid var(--bai-border);
     box-shadow: var(--bai-shadow-lg);
     overflow-y: auto;
+    /* FR-2768: contain touch scroll inside the drawer so reaching the
+       top/bottom of the nav doesn't bubble up and scroll the page
+       behind. Without this, mobile Safari/Chrome route the gesture to
+       the body whenever the sider hits a boundary — the user sees the
+       menu freeze and the article scroll instead. Pairs with the
+       body-lock rule below for defense in depth. */
+    overscroll-behavior: contain;
+    -webkit-overflow-scrolling: touch;
+    touch-action: pan-y;
     animation: bai-drawer-in 200ms ease-out;
   }
+
+  /* In drawer mode, .doc-sidebar is forced back to display:block
+     above, so the inner .doc-sidebar__scroll wrapper no longer has the
+     flex-sizing that gives it a constrained height — its content
+     determines its size, and there is nothing for overflow-y:auto to
+     scroll. Make that explicit by switching it to overflow:visible so
+     there is exactly one scrollport (the sider itself) and the
+     touch-action / overscroll-behavior rules above unambiguously
+     target the element that actually scrolls. */
+  body.bai-drawer-open .doc-sidebar__scroll {
+    overflow: visible;
+  }
+
+  /* Lock the underlying page scroll while the drawer is open. The
+     scrim already blocks taps, but on touch devices the gesture
+     hand-off (when the sider has no more room to scroll) still reaches
+     the body unless its overflow is clipped. */
+  body.bai-drawer-open {
+    overflow: hidden;
+    touch-action: none;
+  }
 }
 
 @keyframes bai-drawer-in {
@@ -782,16 +812,39 @@ body.bai-drawer-open .bai-scrim {
      .doc-toc below. */
   top: calc(var(--bai-topbar-h) + var(--bai-banner-h, 0px));
   height: calc(100vh - var(--bai-topbar-h) - var(--bai-banner-h, 0px));
-  overflow-y: auto;
+  /* FR-2768: switch from a single scrollable aside to a flex column
+     with an internal scrollport. The version block becomes the first
+     row (no flex), the .doc-sidebar__scroll wrapper takes flex: 1 and
+     owns the overflow. This pins the version selector to the top of
+     the sider while the nav list scrolls beneath, matching the design
+     handoff (and avoiding the position:sticky / z-index dance). */
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
   border-right: 1px solid var(--bai-border);
   background: var(--bai-bg-sider);
+}
+
+/* The internal scrollport. Holds the synthetic Introduction entry +
+   the nav groups; everything that should scroll lives inside this
+   wrapper. Padding moves here from .doc-sidebar so the version block
+   above can render edge-to-edge with its own padding. */
+.doc-sidebar__scroll {
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow-y: auto;
+  /* Prevent scroll chaining: if the user scrolls the nav past its
+     top/bottom, the gesture stays inside this container instead of
+     bubbling out and scrolling the article. Same defense applied to
+     the mobile drawer override below. */
+  overscroll-behavior: contain;
   padding: 10px 8px 24px;
 }
 
-.doc-sidebar::-webkit-scrollbar {
+.doc-sidebar__scroll::-webkit-scrollbar {
   width: 8px;
 }
-.doc-sidebar::-webkit-scrollbar-thumb {
+.doc-sidebar__scroll::-webkit-scrollbar-thumb {
   background: var(--bai-border);
   border-radius: 4px;
 }
@@ -895,20 +948,43 @@ body.bai-drawer-open .bai-scrim {
    image, BAI primary focus outline) so the two site-level controls feel
    like a coordinated pair. */
 .doc-sidebar-version {
+  /* FR-2768: horizontal layout matching the design handoff —
+     uppercase label on the left, switcher pill on the right, soft
+     bottom rule separating it from the scrolling nav below. The
+     wrapper is a fixed-height row outside the scrollport so it stays
+     visible while the nav scrolls.
+
+     Horizontal padding is 24px (vs. the design's 18px) to align with
+     the indentation of nav items below: the .doc-sidebar__scroll
+     wrapper adds 8px padding and .doc-sidebar-group adds 6px margin
+     plus the summary's 10px inner padding (FR-2758 introduced this
+     extra margin). 8 + 6 + 10 = 24px from the sider edge to the
+     category label — the version label needs to sit at the same
+     x-coordinate so the grid aligns. */
   display: flex;
-  flex-direction: column;
-  gap: 6px;
-  padding: 14px 18px 12px;
-  border-bottom: 1px solid var(--bai-border);
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+  flex: 0 0 auto;
+  padding: 14px 24px 10px;
+  border-bottom: 1px solid var(--bai-border-soft, var(--bai-border));
 }
 .doc-sidebar-version__label {
   font-size: 10.5px;
   font-weight: 500;
   letter-spacing: 0.06em;
   text-transform: uppercase;
   color: var(--bai-text-2);
+  flex: 0 0 auto;
 }
 .doc-sidebar-version .version-switcher {
+  flex: 0 0 auto;
+  /* FR-2768: native <select> auto-sizes to its longest option, which
+     for short version labels (e.g., "next") renders much narrower
+     than the prototype's pill button. Anchor the width so the
+     control reads as a deliberate UI element rather than a tiny
+     dropdown. */
+  min-width: 132px;
   appearance: none;
   -webkit-appearance: none;
   -moz-appearance: none;
@@ -2758,6 +2834,14 @@ details > :last-child {
   .bai-topbar__actions {
     margin-left: 0;
   }
+  /* FR-2768: match the topbar's child-to-child gap to .bai-topbar__actions'
+     internal gap so the search-icon-button → first-action-button distance
+     reads the same as action-button → action-button. Without this the
+     14px top-level gap clashed with the 6px cluster gap, making the
+     search button look detached from the rest of the icon row on mobile. */
+  .bai-topbar {
+    gap: 6px;
+  }
 }
 
 @media (max-width: 880px) {
diff --git a/packages/backend.ai-docs-toolkit/src/website-builder.ts b/packages/backend.ai-docs-toolkit/src/website-builder.ts
@@ -386,11 +386,21 @@ function buildWebsiteSidebar(
   </a>
 `;
 
+  // Wrap intro + nav groups in a scroll container so the version block
+  // stays pinned at the top while the nav list scrolls beneath it. The
+  // sider itself is overflow:hidden + flex column (see styles-web.ts);
+  // .doc-sidebar__scroll is flex: 1 + overflow-y: auto. Mirrors the
+  // pattern from the FR-2768 design handoff (`.sider__nav` in the
+  // prototype). Tests still see .doc-sidebar-version inside <aside>
+  // before .doc-sidebar-groups — the wrapper sits between them but
+  // doesn't change ordering.
   return `
 <aside class="doc-sidebar">
-${versionBlockHtml}${introHtml}  <nav class="doc-sidebar-groups" aria-label="Documentation navigation">
-    ${groupsHtml}
-  </nav>
+${versionBlockHtml}  <div class="doc-sidebar__scroll">
+${introHtml}    <nav class="doc-sidebar-groups" aria-label="Documentation navigation">
+      ${groupsHtml}
+    </nav>
+  </div>
 </aside>`;
 }
 
@@ -1453,7 +1463,13 @@ function buildBaiTopbar(
 
   // Mobile menu icon (Phase 2 emits the surface; Phase 4 wires the
   // drawer toggle).
-  const menuIconSvg = `<svg width="18" height="18" viewBox="0 0 24 24" aria-hidden="true"><path d="M4 6h16M4 12h16M4 18h16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round"/></svg>`;
+  // Path data spans x=3..21 (18 units wide) so the bars fill the icon's
+  // 18×18 box edge-to-edge, matching the visual weight of the GitHub /
+  // theme icons on the right side. The original 4..20 left ~3px of dead
+  // space inside the SVG, which made the menu glyph appear inset
+  // compared to the right-edge buttons even though the button paddings
+  // were symmetric.
+  const menuIconSvg = `<svg width="18" height="18" viewBox="0 0 24 24" aria-hidden="true"><path d="M3 6h18M3 12h18M3 18h18" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round"/></svg>`;
 
   return `<header class="bai-topbar" role="banner">
   <button class="bai-iconbtn bai-topbar__menu" type="button" aria-label="Toggle navigation">${menuIconSvg}</button>
