@flamingo-stack/openframe-frontend-core 0.0.764 → 0.0.766

package/src/components/navigation/multi-level-navigation.tsx

@@ -3,7 +3,8 @@
 import { ChevronDown, ChevronUp, FileText, Folder, FolderOpen } from 'lucide-react';
 import { cn } from '../../utils/cn';
 import { DEFAULT_FOLDER_INDEX_FILE as CANONICAL_FOLDER_INDEX_FILE } from '../../utils/doc-tree-nav';
-import { UnifiedSkeleton } from '../loading/unified-skeleton';
+import { MediaSkeleton, TextLineSkeleton } from '../loading/unified-skeleton';
+import { useLoadingScope } from '../ui/loading-scope';
 
 export interface NavigationNode {
   id: string;
@@ -40,6 +41,128 @@ interface MultiLevelNavigationProps {
 // drifting from the SSOT.
 const DEFAULT_FOLDER_INDEX_FILE = CANONICAL_FOLDER_INDEX_FILE;
 
+/**
+ * The tree's list, item and row frame, read by the tree and by its skeleton, so the skeleton is its size. The tree's
+ * entries are a read list (`data-loading-item`; an open folder holds its children's items).
+ */
+const NAV_LIST_CLASS = 'space-y-2';
+const NAV_ITEM_CLASS = 'space-y-1';
+const NAV_ROW_FRAME_CLASS = 'relative w-full rounded-lg border transition-all duration-150';
+const NAV_ROW_CONTENT_CLASS = 'flex w-full items-center rounded-lg px-2 text-h6';
+/** Each entry's side padding, around its row frame. */
+const NAV_ROW_PAD_CLASS = 'px-2';
+/**
+ * A row's height (the desktop tree's, the dropdown's), with the folder toggle's square box at the row's end and the
+ * room the name leaves for it: read by the loaded rows and by their skeleton.
+ */
+const NAV_ROW_HEIGHT = {
+  desktop: { row: 'h-12', toggle: 'h-12 w-12', toggleRoom: 'pr-12' },
+  mobile: { row: 'h-11', toggle: 'h-11 w-11', toggleRoom: 'pr-11' },
+} as const;
+/**
+ * How many rows each skeleton draws (the desktop tree, the mobile dropdown): a layout fold, the rows one screen holds.
+ * A row is 48px (44px in the dropdown) with its border and the list's gap, about 54px (50px): a first screen of 900px
+ * (844px on a phone) holds 17. The tree opens on the reader's repository, so the skeleton draws that shape: one root
+ * entry open, the rest of the fold its entries (indented as the tree indents them). It is drawn open FIRST: the root
+ * order is the source's path sort, and which repositories sort before the reader's needs the read, so a page in a
+ * later repository differs by one collapsed root row above the open one. A repository holding fewer entries ends
+ * past the first screen anyway, and the tree's other root entries are list growth below it.
+ */
+export const MULTI_LEVEL_NAVIGATION_SKELETON_ROWS = 17;
+export const MOBILE_NAVIGATION_SKELETON_ROWS = 17;
+const NAV_SKELETON_LABEL_WIDTHS = ['w-3/5', 'w-2/5', 'w-1/2', 'w-1/3'] as const;
+/** An open folder's entries: the list under its row, and each entry's indent (the desktop tree's, the dropdown's). */
+const NAV_CHILDREN_CLASS = 'space-y-1';
+const NAV_INDENT_CLASS = { desktop: 'ml-4', mobile: 'ml-3' } as const;
+
+/** One row's frame while it loads: an icon box and a bar of its name. */
+function NavigationRowSkeleton({
+  index,
+  rowHeightClass,
+  indentClass,
+}: {
+  index: number;
+  rowHeightClass: string;
+  indentClass?: string;
+}) {
+  return (
+    <div className={cn(NAV_ROW_PAD_CLASS, indentClass)}>
+      <div className={cn(NAV_ROW_FRAME_CLASS, 'border-ods-border bg-ods-card')}>
+        <div className={cn(NAV_ROW_CONTENT_CLASS, rowHeightClass)}>
+          <MediaSkeleton.Icon size="sm" className="mr-2 flex-shrink-0" />
+          <TextLineSkeleton type="h6" className={NAV_SKELETON_LABEL_WIDTHS[index % NAV_SKELETON_LABEL_WIDTHS.length]} />
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function NavigationTreeSkeleton({
+  rows,
+  rowHeightClass,
+  indentClass,
+  className,
+}: {
+  rows: number;
+  rowHeightClass: string;
+  indentClass: string;
+  className?: string;
+}) {
+  return (
+    <div className={cn(NAV_LIST_CLASS, className)} aria-hidden>
+      {/* The open root entry: its row, then its entries, each an item of the tree's read list. */}
+      <div className={NAV_ITEM_CLASS} data-loading-item>
+        <NavigationRowSkeleton index={0} rowHeightClass={rowHeightClass} />
+        {rows > 1 && (
+          <div className={NAV_CHILDREN_CLASS}>
+            {Array.from({ length: rows - 1 }, (_, i) => (
+              <div key={i} className={NAV_ITEM_CLASS} data-loading-item>
+                <NavigationRowSkeleton index={i + 1} rowHeightClass={rowHeightClass} indentClass={indentClass} />
+              </div>
+            ))}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+/** The documentation tree while it is read: its rows' frames, each with an icon box and a bar of its name. */
+export function MultiLevelNavigationSkeleton({
+  rows = MULTI_LEVEL_NAVIGATION_SKELETON_ROWS,
+  className,
+}: {
+  rows?: number;
+  className?: string;
+}) {
+  return (
+    <NavigationTreeSkeleton
+      rows={rows}
+      rowHeightClass={NAV_ROW_HEIGHT.desktop.row}
+      indentClass={NAV_INDENT_CLASS.desktop}
+      className={className}
+    />
+  );
+}
+
+/** The mobile documentation dropdown while it is read: the same rows at the dropdown's height. */
+export function MobileNavigationDropdownSkeleton({
+  rows = MOBILE_NAVIGATION_SKELETON_ROWS,
+  className,
+}: {
+  rows?: number;
+  className?: string;
+}) {
+  return (
+    <NavigationTreeSkeleton
+      rows={rows}
+      rowHeightClass={NAV_ROW_HEIGHT.mobile.row}
+      indentClass={NAV_INDENT_CLASS.mobile}
+      className={className}
+    />
+  );
+}
+
 /**
  * Compute the visual "selected" state for a navigation node.
  *
@@ -90,18 +213,10 @@ export function MultiLevelNavigation({
   className,
   folderIndexFile = DEFAULT_FOLDER_INDEX_FILE,
 }: MultiLevelNavigationProps) {
-  if (isLoading) {
-    return (
-      <div className={cn('space-y-2', className)}>
-        {[1, 2, 3, 4].map(i => (
-          <UnifiedSkeleton key={i} className="h-12 rounded-lg p-3" />
-        ))}
-      </div>
-    );
-  }
+  if (useLoadingScope() || isLoading) return <MultiLevelNavigationSkeleton className={className} />;
 
   return (
-    <div className={cn('space-y-2', className)} role="list" aria-label="Navigation list">
+    <div className={cn(NAV_LIST_CLASS, className)} role="list" aria-label="Navigation list">
       {nodes.map(node => (
         <NavigationItem
           key={node.id}
@@ -145,20 +260,22 @@ function NavigationItem({
   const hasChildren = children.length > 0;
 
   return (
-    <div className="space-y-1" role="listitem">
-      <div className={cn('px-2', level > 0 && 'ml-4')}>
+    <div className={NAV_ITEM_CLASS} role="listitem" data-loading-item>
+      <div className={cn(NAV_ROW_PAD_CLASS, level > 0 && NAV_INDENT_CLASS.desktop)}>
         <div
           className={cn(
-            'relative w-full rounded-lg border transition-all duration-150',
+            NAV_ROW_FRAME_CLASS,
             isSelected ? 'border-ods-border bg-ods-border' : 'border-ods-border bg-ods-card',
           )}
         >
           <div className="relative flex items-center">
             <button
               className={cn(
-                'flex h-12 w-full items-center rounded-lg px-2 text-ods-text-primary transition-all duration-150 text-h6',
+                NAV_ROW_CONTENT_CLASS,
+                NAV_ROW_HEIGHT.desktop.row,
+                'text-ods-text-primary transition-all duration-150',
                 !isSelected && 'hover:bg-ods-bg-hover',
-                hasChildren && 'pr-12',
+                hasChildren && NAV_ROW_HEIGHT.desktop.toggleRoom,
               )}
               onClick={() => onNodeClick(node)}
               aria-label={`${isSelected ? 'Selected' : 'Select'} ${node.name}`}
@@ -186,7 +303,10 @@ function NavigationItem({
 
             {hasChildren && (
               <button
-                className="absolute right-0 top-0 flex h-12 w-12 items-center justify-center text-ods-text-secondary transition-colors duration-150 hover:text-ods-text-primary"
+                className={cn(
+                  'absolute right-0 top-0 flex items-center justify-center text-ods-text-secondary transition-colors duration-150 hover:text-ods-text-primary',
+                  NAV_ROW_HEIGHT.desktop.toggle,
+                )}
                 onClick={e => {
                   e.stopPropagation();
                   if (onToggleExpand) {
@@ -209,7 +329,7 @@ function NavigationItem({
       </div>
 
       {hasChildren && isExpanded && (
-        <div className="space-y-1">
+        <div className={NAV_CHILDREN_CLASS}>
           {children.map(child => (
             <NavigationItem
               key={child.id}
@@ -238,18 +358,10 @@ export function MobileNavigationDropdown({
   className,
   folderIndexFile = DEFAULT_FOLDER_INDEX_FILE,
 }: MultiLevelNavigationProps) {
-  if (isLoading) {
-    return (
-      <div className={cn('space-y-2', className)}>
-        {[1, 2, 3].map(i => (
-          <UnifiedSkeleton key={i} className="h-10 rounded-lg p-3" />
-        ))}
-      </div>
-    );
-  }
+  if (useLoadingScope() || isLoading) return <MobileNavigationDropdownSkeleton className={className} />;
 
   return (
-    <div className={cn('space-y-2', className)}>
+    <div className={cn(NAV_LIST_CLASS, className)}>
       {nodes.map(node => (
         <MobileNavigationItem
           key={node.id}
@@ -282,20 +394,22 @@ function MobileNavigationItem({
   const hasChildren = children.length > 0;
 
   return (
-    <div className="space-y-1">
-      <div className={cn('px-2', level > 0 && 'ml-3')}>
+    <div className={NAV_ITEM_CLASS} data-loading-item>
+      <div className={cn(NAV_ROW_PAD_CLASS, level > 0 && NAV_INDENT_CLASS.mobile)}>
         <div
           className={cn(
-            'relative w-full rounded-lg border transition-all duration-150',
+            NAV_ROW_FRAME_CLASS,
             isSelected ? 'border-ods-border bg-ods-border' : 'border-ods-border bg-ods-card',
           )}
         >
           <div className="relative flex items-center">
             <button
               className={cn(
-                'flex h-11 w-full items-center rounded-lg px-2 text-ods-text-primary transition-all duration-150 text-h6',
+                NAV_ROW_CONTENT_CLASS,
+                NAV_ROW_HEIGHT.mobile.row,
+                'text-ods-text-primary transition-all duration-150',
                 !isSelected && 'hover:bg-ods-bg-hover',
-                hasChildren && 'pr-11',
+                hasChildren && NAV_ROW_HEIGHT.mobile.toggleRoom,
               )}
               onClick={() => onNodeClick(node)}
             >
@@ -322,7 +436,10 @@ function MobileNavigationItem({
 
             {hasChildren && (
               <button
-                className="absolute right-0 top-0 flex h-11 w-11 items-center justify-center text-ods-text-secondary transition-colors duration-150 hover:text-ods-text-primary"
+                className={cn(
+                  'absolute right-0 top-0 flex items-center justify-center text-ods-text-secondary transition-colors duration-150 hover:text-ods-text-primary',
+                  NAV_ROW_HEIGHT.mobile.toggle,
+                )}
                 onClick={e => {
                   e.stopPropagation();
                   if (onToggleExpand) {
@@ -345,7 +462,7 @@ function MobileNavigationItem({
       </div>
 
       {hasChildren && isExpanded && (
-        <div className="space-y-1">
+        <div className={NAV_CHILDREN_CLASS}>
           {children.map(child => (
             <MobileNavigationItem
               key={child.id}

package/src/components/navigation/page-section-bar.tsx

@@ -0,0 +1,132 @@
+'use client';
+
+/**
+ * THE bar that follows the reader down a long page: its sections as tabs, the
+ * one being read marked. A full-width band stuck directly under the site header
+ * (`useHeaderHeight` with `stuckOnly`: the header alone, never the announcement
+ * bar, which scrolls away), its content on the page's gutters. `StickySectionNav`
+ * owns its look; `useScrollSpy` says which section is being read and keeps the
+ * URL's hash on it (`syncHash`), so a reload stays where the reader was, and
+ * above the first section (the hero) nothing is active and the URL has no hash.
+ *
+ * A tab is shown only for a section that RENDERED: a section that leaves itself
+ * out (its anchor element empty, e.g. a list with no rows) loses its tab, also
+ * when that happens after a client read (`useRenderedSections`). A page puts
+ * `PAGE_ANCHOR_SCOPE_CLASS` on its `<main>` so every anchor clears the header and
+ * the bar when a link lands on it.
+ */
+import { type ReactNode, useEffect, useState } from 'react';
+import { useHeaderHeight } from '../../hooks/ui/use-header-height';
+import { cn } from '../../utils/cn';
+import { NavLinkAnchorViaRuntime } from '../chat/nav-link-anchor-via-runtime';
+import { useScrollSpy } from '../docs/use-scroll-spy';
+import { PageContainer } from '../layout/page-container';
+import { useLoadingScope } from '../ui/loading-scope';
+import { STICKY_SECTION_NAV_HEIGHT_PX, StickySectionNav, type StickyNavSection } from './sticky-section-nav';
+
+/** The bar's own height: what a section's anchor must clear besides the header. */
+export const SECTION_BAR_HEIGHT_PX = STICKY_SECTION_NAV_HEIGHT_PX;
+/**
+ * What a section clears when a link lands on it: the site header (72px), this
+ * bar (56px) and the gap (16px), 144px = `scroll-mt-36`. The CSS twin of the
+ * offset the bar's tabs scroll by. Written out twice below (a class built at
+ * runtime emits no CSS); the test pins both to the px sum.
+ */
+export const PAGE_ANCHOR_SCROLL_MARGIN_CLASS = 'scroll-mt-36';
+/** The same margin for every anchored element under a page's `<main>` (sections, cards, tabs). */
+export const PAGE_ANCHOR_SCOPE_CLASS = '[&_[id]]:scroll-mt-36';
+/** The breath between the bars and the heading a link lands on. */
+export const PAGE_ANCHOR_GAP_PX = 16;
+/** The bar's side insets: the page sections' own (the width is `PageContainer`'s). */
+const SECTION_BAR_INSET_CLASS = 'px-[var(--spacing-system-lf)] md:px-20';
+
+/**
+ * The sections whose anchor element holds something. Every section counts until
+ * the page has mounted (the server's HTML and the first render agree); then a
+ * section whose element is missing or empty is left out, and each element is
+ * watched, so a section that removes itself after a client read loses its tab.
+ */
+function useRenderedSections(sections: StickyNavSection[]): StickyNavSection[] {
+  const [empty, setEmpty] = useState<ReadonlySet<string>>(() => new Set());
+  useEffect(() => {
+    const measure = () =>
+      setEmpty(prev => {
+        const next = new Set(
+          sections.filter(section => !document.getElementById(section.id)?.hasChildNodes()).map(s => s.id),
+        );
+        return next.size === prev.size && [...next].every(id => prev.has(id)) ? prev : next;
+      });
+    measure();
+    const observer = new MutationObserver(measure);
+    for (const section of sections) {
+      const element = document.getElementById(section.id);
+      if (element) observer.observe(element, { childList: true });
+    }
+    return () => observer.disconnect();
+  }, [sections]);
+  return empty.size === 0 ? sections : sections.filter(section => !empty.has(section.id));
+}
+
+export interface PageSectionBarProps {
+  /** The sections on the page, in page order. A stable array while the set is (the spy re-binds on a new one). */
+  sections: StickyNavSection[];
+  /** The bar's accessible name. */
+  label?: string;
+  /** Before the tabs (a product's mark and name). */
+  brand?: ReactNode;
+  /**
+   * A link after the tabs (a product page's "pricing"): the site's one link (the
+   * unified nav rule); a same-page `#id` scrolls the way the tabs do (the bar's
+   * own scroll, with the header's live offset).
+   */
+  action?: { label: ReactNode; href: string; className?: string };
+}
+
+export function PageSectionBar({ sections: listed, label, brand, action }: PageSectionBarProps) {
+  const sections = useRenderedSections(listed);
+  // In a loading scope a page whose sections are not known yet passes none: the bar still stands, and
+  // `StickySectionNav` draws its own skeleton.
+  const inScope = useLoadingScope();
+  // What stays stuck over the bar: the site header alone, and nothing while it has slid away.
+  const headerBottom = useHeaderHeight(undefined, { stuckOnly: true });
+  const { activeSection, handleSectionClick } = useScrollSpy(sections, {
+    syncHash: true,
+    aboveFirst: 'none',
+    headerOffset: headerBottom + SECTION_BAR_HEIGHT_PX + PAGE_ANCHOR_GAP_PX,
+  });
+  if (sections.length === 0 && !inScope) return null;
+
+  return (
+    <PageContainer
+      as="div"
+      backgroundClassName="sticky z-30 border-b border-ods-border bg-ods-bg transition-[top] duration-300 ease-in-out motion-reduce:transition-none"
+      backgroundStyle={{ top: headerBottom }}
+      contentPadding={SECTION_BAR_INSET_CLASS}
+    >
+      <StickySectionNav
+        orientation="horizontal"
+        label={label}
+        sections={sections}
+        activeSection={activeSection}
+        onSectionClick={handleSectionClick}
+        brand={brand}
+        action={
+          action && (
+            <NavLinkAnchorViaRuntime
+              href={action.href}
+              // A same-page `#id` lands like a tab does: the bar's own scroll, with the header's live offset.
+              onClick={event => {
+                if (!action.href.startsWith('#')) return;
+                event.preventDefault();
+                handleSectionClick(action.href.slice(1));
+              }}
+              className={cn('whitespace-nowrap text-h6 hover:underline', action.className)}
+            >
+              {action.label}
+            </NavLinkAnchorViaRuntime>
+          )
+        }
+      />
+    </PageContainer>
+  );
+}

package/src/components/navigation/sticky-section-nav.tsx

@@ -5,8 +5,35 @@ import { useEffect, useState, useCallback, useRef } from 'react';
 import Link from '../../embed-shims/next-link';
 import { cn } from '../../utils';
 import { scrollElementIntoView } from '../../utils/scroll-into-view';
+import { TextLineSkeleton } from '../loading/unified-skeleton';
+import { useLoadingScope } from '../ui/loading-scope';
 import { ScrollShadow } from '../ui/scroll-fade';
 
+/** The bar's height, as a class and in px (the offset a page's anchors clear besides the header). */
+export const STICKY_SECTION_NAV_HEIGHT_CLASS = 'h-14';
+export const STICKY_SECTION_NAV_HEIGHT_PX = 56;
+
+/** How many sections the skeleton draws when the sections are read with the page. */
+export const STICKY_SECTION_NAV_SKELETON_COUNT = 5;
+
+/** The bars' and rows' classes, read by the navigation and by its skeleton, so the skeleton is its size. */
+const HORIZONTAL_NAV_CLASS = 'flex items-stretch gap-6 bg-ods-bg';
+const HORIZONTAL_BRAND_CLASS =
+  'hidden shrink-0 items-center gap-2.5 border-r border-ods-border pr-6 text-ods-text-primary text-h4 content-lg:flex';
+const HORIZONTAL_ROW_CLASS = 'flex h-full items-center gap-1 [scrollbar-width:none] content-lg:items-stretch';
+const HORIZONTAL_ACTION_CLASS = 'hidden shrink-0 items-center content-lg:flex';
+/**
+ * A section's pill on a narrow area; from the content `lg` step a tab the height of the bar. Its shape, read by the
+ * pill and by its skeleton (the label a bar inside it), so the skeleton is the pill's size at every step.
+ */
+const PILL_CLASS = cn(
+  'flex shrink-0 items-center whitespace-nowrap rounded-full border px-3 py-1.5 text-h6',
+  'content-lg:rounded-none content-lg:border-x-0 content-lg:border-b-2 content-lg:border-t-0 content-lg:py-0',
+);
+const VERTICAL_NAV_CLASS = 'relative bg-ods-bg';
+const VERTICAL_ROW_CLASS = 'relative flex h-10 w-full items-stretch transition-all duration-200';
+const VERTICAL_BUTTON_CLASS = 'relative flex flex-1 cursor-pointer items-center gap-2 px-3 py-2';
+
 export interface StickyNavSection {
   id: string;
   label: string;
@@ -57,18 +84,14 @@ function HorizontalSectionNav({
   }, [activeSection]);
 
   return (
-    <nav ref={navRef} aria-label={label} className={cn('flex h-14 items-stretch gap-6 bg-ods-bg', className)}>
-      {brand && (
-        <div className="hidden shrink-0 items-center gap-2.5 border-r border-ods-border pr-6 text-ods-text-primary text-h4 content-lg:flex">
-          {brand}
-        </div>
-      )}
+    <nav
+      ref={navRef}
+      aria-label={label}
+      className={cn(HORIZONTAL_NAV_CLASS, STICKY_SECTION_NAV_HEIGHT_CLASS, className)}
+    >
+      {brand && <div className={HORIZONTAL_BRAND_CLASS}>{brand}</div>}
       {/* The scrolling row and its edge fades are the lib's one pattern (`ScrollShadow`), not a second one. */}
-      <ScrollShadow
-        axis="horizontal"
-        className="min-w-0 flex-1"
-        scrollClassName="flex h-full items-center gap-1 [scrollbar-width:none] content-lg:items-stretch"
-      >
+      <ScrollShadow axis="horizontal" className="min-w-0 flex-1" scrollClassName={HORIZONTAL_ROW_CLASS}>
         {sections.map(section => {
           const active = activeSection === section.id;
           return (
@@ -82,9 +105,8 @@ function HorizontalSectionNav({
                 onSectionClick(section.id);
               }}
               className={cn(
-                // A pill on a narrow area; from the content `lg` step a tab the height of the bar.
-                'flex shrink-0 items-center whitespace-nowrap rounded-full border px-3 py-1.5 transition-colors text-h6 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ods-accent',
-                'content-lg:rounded-none content-lg:border-x-0 content-lg:border-b-2 content-lg:border-t-0 content-lg:py-0',
+                PILL_CLASS,
+                'transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ods-accent',
                 active
                   ? 'border-ods-border bg-ods-card text-ods-text-primary content-lg:border-ods-accent content-lg:bg-transparent content-lg:bg-gradient-to-b content-lg:from-transparent content-lg:to-ods-accent/10'
                   : 'border-transparent text-ods-text-secondary hover:text-ods-text-primary content-lg:hover:bg-ods-bg-hover',
@@ -95,7 +117,7 @@ function HorizontalSectionNav({
           );
         })}
       </ScrollShadow>
-      {action && <div className="hidden shrink-0 items-center content-lg:flex">{action}</div>}
+      {action && <div className={HORIZONTAL_ACTION_CLASS}>{action}</div>}
     </nav>
   );
 }
@@ -116,6 +138,19 @@ export function StickySectionNav({
   action,
   label,
 }: StickySectionNavProps) {
+  // Sections that are read arrive empty in a page's loading state: the navigation is its skeleton. Sections a page
+  // states itself are its own words and draw as they are.
+  if (useLoadingScope() && sections.length === 0) {
+    return (
+      <StickySectionNavSkeleton
+        orientation={orientation}
+        brand={brand}
+        action={action}
+        ribbonPosition={ribbonPosition}
+        className={className}
+      />
+    );
+  }
   if (orientation === 'horizontal') {
     return (
       <HorizontalSectionNav
@@ -132,7 +167,7 @@ export function StickySectionNav({
   const navHeight = sections.length * 40; // 40px per item (h-10)
 
   return (
-    <nav aria-label={label} className={cn('relative bg-ods-bg', className)}>
+    <nav aria-label={label} className={cn(VERTICAL_NAV_CLASS, className)}>
       {/* Background gray vertical line for all nav items */}
       <div
         className="absolute bg-ods-border"
@@ -145,7 +180,7 @@ export function StickySectionNav({
       />
 
       {sections.map(section => (
-        <div key={section.id} className="relative flex h-10 w-full items-stretch transition-all duration-200">
+        <div key={section.id} className={VERTICAL_ROW_CLASS}>
           {/* Yellow ribbon for active state */}
           {activeSection === section.id && (
             <div
@@ -167,7 +202,7 @@ export function StickySectionNav({
             // The ribbon is the visual; this is the same state for assistive
             // tech (a table of contents marks the reader's current location).
             aria-current={activeSection === section.id ? 'location' : undefined}
-            className="relative flex flex-1 cursor-pointer items-center gap-2 px-3 py-2"
+            className={VERTICAL_BUTTON_CLASS}
           >
             <span
               className={cn(
@@ -186,6 +221,62 @@ export function StickySectionNav({
   );
 }
 
+/** Bar widths for the skeleton's sections, fixed so the skeleton does not change between renders. */
+const SKELETON_LABEL_WIDTHS = ['w-24', 'w-32', 'w-20', 'w-28', 'w-24'] as const;
+
+/**
+ * The section navigation while its sections are read: the same bar (horizontal: its brand and action as given,
+ * the sections as pill boxes) or list (vertical: its rail, each row a bar of its label).
+ */
+export function StickySectionNavSkeleton({
+  orientation = 'vertical',
+  count = STICKY_SECTION_NAV_SKELETON_COUNT,
+  brand,
+  action,
+  ribbonPosition = 'left',
+  className,
+}: Pick<StickySectionNavProps, 'orientation' | 'brand' | 'action' | 'ribbonPosition' | 'className'> & {
+  count?: number;
+}) {
+  const widths = Array.from({ length: count }, (_, i) => SKELETON_LABEL_WIDTHS[i % SKELETON_LABEL_WIDTHS.length]);
+  if (orientation === 'horizontal') {
+    return (
+      <div className={cn(HORIZONTAL_NAV_CLASS, STICKY_SECTION_NAV_HEIGHT_CLASS, className)} aria-hidden inert>
+        {brand && <div className={HORIZONTAL_BRAND_CLASS}>{brand}</div>}
+        <div className={cn('min-w-0 flex-1 overflow-hidden', HORIZONTAL_ROW_CLASS, 'content-lg:items-center')}>
+          {widths.map((width, i) => (
+            // The pill's own box (a tab from the content `lg` step), its label a bar.
+            <div key={i} className={cn(PILL_CLASS, 'border-transparent')}>
+              <TextLineSkeleton type="h6" className={width} />
+            </div>
+          ))}
+        </div>
+        {action && <div className={HORIZONTAL_ACTION_CLASS}>{action}</div>}
+      </div>
+    );
+  }
+  return (
+    <div className={cn(VERTICAL_NAV_CLASS, className)} aria-hidden>
+      <div
+        className="absolute bg-ods-border"
+        style={{
+          width: '1px',
+          height: `${count * 40}px`,
+          [ribbonPosition === 'left' ? 'left' : 'right']: '-2px',
+          top: '0px',
+        }}
+      />
+      {widths.map((width, i) => (
+        <div key={i} className={VERTICAL_ROW_CLASS}>
+          <div className={VERTICAL_BUTTON_CLASS}>
+            <TextLineSkeleton type="h6" className={width} />
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
+
 /**
  * SIMPLEST POSSIBLE IMPLEMENTATION - Just make it work
  */

package/src/components/navigation/ticket-alerts-button.tsx

@@ -29,9 +29,9 @@
  */
 
 import { cn } from '../../utils/cn';
+import { buildTicketOpenHref } from '../../utils/dev-sections/dev-section-param-keys';
 import { LifeBuoyIcon } from '../icons-v2-generated/interface/life-buoy-icon';
 import { useOptionalTicketLive } from '../tickets/ticket-live-provider';
-import { buildTicketOpenHref } from '../tickets/types';
 import { HeaderButton } from './header-button';
 import { UnreadCountBadge } from './unread-dot';
 

package/src/components/onboarding-guides/hooks/use-onboarding-guides.ts

@@ -21,6 +21,7 @@ import type {
   OnboardingGuideListResponse,
   OnboardingGuideSectionSummary,
 } from '../../chat/types/entities/onboarding-guide';
+import { useLoadingScope } from '../../ui/loading-scope';
 
 /**
  * Cache key builder for the `['onboarding-guides']` namespace.
@@ -47,7 +48,10 @@ export const onboardingGuideKeys = {
 };
 
 export function useOnboardingGuides(filters?: OnboardingGuideFilters) {
+  // In a loading scope nothing is fetched (the view draws its loading state).
+  const held = useLoadingScope();
   return useQuery({
+    enabled: !held,
     queryKey: onboardingGuideKeys.list(filters || {}),
     queryFn: async (): Promise<OnboardingGuideListResponse> => {
       const params = new URLSearchParams();
@@ -68,6 +72,7 @@ export function useOnboardingGuides(filters?: OnboardingGuideFilters) {
 }
 
 export function useOnboardingGuide(slug: string | undefined) {
+  const held = useLoadingScope();
   return useQuery({
     queryKey: onboardingGuideKeys.detail(slug || ''),
     queryFn: async (): Promise<OnboardingGuide> => {
@@ -75,12 +80,14 @@ export function useOnboardingGuide(slug: string | undefined) {
       if (!res.ok) throw new Error('Failed to fetch onboarding guide');
       return (await res.json()) as OnboardingGuide;
     },
-    enabled: !!slug,
+    enabled: !!slug && !held,
   });
 }
 
 export function useOnboardingGuideSections() {
+  const held = useLoadingScope();
   return useQuery({
+    enabled: !held,
     queryKey: onboardingGuideKeys.sections(),
     queryFn: async (): Promise<OnboardingGuideSectionSummary[]> => {
       const res = await fetch('/api/onboarding-guides/sections');

package/src/components/onboarding-guides/index.ts

@@ -20,8 +20,11 @@
  */
 
 export { OnboardingGuidesCatalogView, type OnboardingGuidesCatalogViewProps } from './onboarding-guides-catalog-view';
-export { OnboardingGuideDetailView, type OnboardingGuideDetailViewProps } from './onboarding-guide-detail-view';
-export { OnboardingGuidesCatalogSkeleton } from './onboarding-guides-catalog-skeleton';
+export {
+  OnboardingGuideDetailView,
+  ONBOARDING_GUIDE_RELATED_SKELETON_COUNT,
+  type OnboardingGuideDetailViewProps,
+} from './onboarding-guide-detail-view';
 
 export {
   useOnboardingGuides,