@flamingo-stack/openframe-frontend-core 0.0.481 → 0.0.482

package/src/components/navigation/.mobile-burger-menu.md

@@ -1,26 +1,29 @@
-<!-- source-hash: 5b93029e90f2707d4d17ae7b8abe09dc -->
-A mobile slide-down navigation menu component that renders a full-screen overlay panel with user profile card, primary/secondary navigation items in a responsive grid layout, and optional action buttons (logout, edit profile, search user).
+<!-- source-hash: 239259ec2e61e6f79f54306c82df0784 -->
+Accessible mobile navigation drawer that slides down from the app header, rendering primary nav items in a 2-column grid, secondary items full-width, a user profile card, and an optional logout button.
 
 ## Key Components
 
-**`MobileBurgerMenu`** — Memoized React component (`React.memo`) with the following behavior:
-- Locks body scroll and traps `Escape` key while open
-- Renders a blur backdrop and animated slide-down panel below the fixed header (`48px` offset)
-- Splits `config.items` into **primary** (2-column grid) and **secondary** (full-width list) sections
-- Supports a `disabled` prop that freezes all interactive items while keeping close/backdrop functional
+### `MobileBurgerMenu`
 
-**`MobileBurgerMenuProps`** — Exported interface defining all props:
+A memoized React component that manages the full mobile menu overlay. Key behaviors:
+
+- **Scroll lock** — uses `usePreventScroll` (react-aria) to block body scroll on iOS and Android while open
+- **Focus trap** — `useFocusTrap` contains Tab focus within the panel, supports Escape-to-close, and restores focus on dismiss
+- **Animation** — slide-down + fade via Tailwind transition classes; `inert` attribute removes closed items from the tab order without unmounting
+- **Layout anchoring** — backdrop and panel use `absolute` (not `fixed`) so they position relative to the app row below any top banner, with `top: 48px` clearing the header
+
+### `MobileBurgerMenuProps`
 
 | Prop | Type | Description |
-|------|------|-------------|
-| `isOpen` | `boolean` | Controls visibility and animation |
-| `onClose` | `() => void` | Close handler (backdrop click, Escape key) |
-| `config` | `NavigationSidebarConfig` | Nav items and `onNavigate` callback |
-| `user` | `object` | Optional user card data (name, email, avatar, role) |
-| `onSearchUser` | `() => void` | Optional search user action button |
-| `onEditProfile` | `() => void` | Optional edit profile action button |
-| `onLogout` | `() => void` | Optional logout button at bottom |
-| `disabled` | `boolean` | Disables all interactive items |
+|---|---|---|
+| `isOpen` | `boolean` | Controls open/closed state |
+| `onClose` | `() => void` | Called on backdrop click or Escape |
+| `config` | `NavigationSidebarConfig` | Nav items and `onNavigate` handler |
+| `user` | `object` | Avatar, name, email, role for the header card |
+| `onSearchUser` | `() => void` | Optional search-user action button |
+| `onEditProfile` | `() => void` | Optional edit-profile action button |
+| `onLogout` | `() => void` | Renders logout row when provided |
+| `disabled` | `boolean` | Disables all interactive items; backdrop/close still work |
 
 ## Usage Example
 
@@ -32,19 +35,16 @@ const [menuOpen, setMenuOpen] = useState(false)
 <MobileBurgerMenu
   isOpen={menuOpen}
   onClose={() => setMenuOpen(false)}
-  config={{
-    items: [
-      { id: 'dashboard', label: 'Dashboard', path: '/dashboard', isActive: true },
-      { id: 'settings', label: 'Settings', section: 'secondary', path: '/settings' },
-    ],
-    onNavigate: (path) => router.push(path),
-  }}
+  config={sidebarConfig}
   user={{
-    userName: 'Jane Smith',
-    userEmail: 'jane@example.com',
-    userRole: 'Admin',
+    userName: 'Alice Smith',
+    userEmail: 'alice@example.com',
+    userAvatarUrl: '/avatars/alice.png',
+    userRole: 'admin',
   }}
-  onLogout={() => signOut()}
   onEditProfile={() => router.push('/profile')}
+  onLogout={handleLogout}
 />
-```
+```
+
+**Source:** [`mobile-burger-menu.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/mobile-burger-menu.tsx)

package/src/components/navigation/.mobile-nav-panel.md

@@ -1,64 +1,56 @@
-<!-- source-hash: 22dc571f86ff6412c173e898a5bebb85 -->
-A client-side React component that renders a full-featured mobile navigation panel with backdrop overlay, keyboard support, and scroll locking.
+<!-- source-hash: f440873b10ff8a3b76d3a4ca0faf8299 -->
+Accessible mobile navigation panel component that renders a floating dialog with scroll lock, focus trapping, and backdrop dismissal for responsive navigation menus.
 
 ## Key Components
 
-### `MobileNavPanel`
-The primary export — a modal-style slide-in navigation panel controlled by `isOpen`.
+### Exports
 
-**Props (`MobileNavPanelProps`):**
+| Export | Type | Description |
+|--------|------|-------------|
+| `MOBILE_NAV_PANEL_ID` | `string` | DOM id (`'mobile-nav-panel'`) referenced by the header hamburger's `aria-controls` attribute |
+| `MobileNavPanelProps` | `interface` | Props shape: `isOpen: boolean`, `config: MobileNavConfig` |
+| `MobileNavPanel` | Component | Main panel component |
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `isOpen` | `boolean` | Controls panel visibility |
-| `config` | `MobileNavConfig` | Navigation structure and callbacks |
+### Accessibility & Behavior Hooks
 
-**Behaviors:**
-- Locks `document.body` scroll while open
-- Closes on `Escape` key press (via `config.onClose`)
-- Closes on backdrop click; prevents propagation inside panel
-- Renders `null` when closed (no DOM presence)
+| Hook | Purpose |
+|------|---------|
+| `usePreventScroll` | iOS-aware, ref-counted body scroll lock (shared counter with modals/chat overlays) |
+| `useFocusTrap` | Initial focus, Tab containment, Escape-to-close, and guarded focus restore |
+| `useHeaderHeight` | Measures live header height so the panel anchors correctly below it |
 
-**Layout structure:**
-- **Backdrop** — full-screen overlay (`z-[9998]`) that closes the panel on click
-- **Panel** — floating card (`z-[9999]`), full-width on mobile / `400px` on `md+`, anchored top-right with scroll-locked content area
-- **Header** — fixed close (`X`) button
-- **Body** — scrollable section list with optional section titles and nav items
-- **Footer** — optional sticky footer from `config.footer`
+### Internal: `renderNavigationItem`
 
-### `renderNavigationItem` (internal)
-Handles three `NavigationItem` render modes:
-1. **Custom element** — renders `item.element` directly
-2. **Link** — `<Button href=...>` with icon, badge, and active state
-3. **Action** — `<Button onClick=...>` with inline badge support
+Renders each `NavigationItem` in one of three modes:
+- **Custom element** — renders `item.element` directly
+- **Link item** — renders a `Button` with `href`, `leftIcon`, and `rightIcon` (badge)
+- **Button item** — renders a `Button` with `onClick`, with badge appended via `ml-auto` span
 
 ## Usage Example
 
 ```typescript
 import { MobileNavPanel } from './mobile-nav-panel'
-import { useState } from 'react'
-import { Home, Settings } from 'lucide-react'
 
-export function AppShell() {
-  const [menuOpen, setMenuOpen] = useState(false)
-
-  return (
-    <MobileNavPanel
-      isOpen={menuOpen}
-      config={{
-        onClose: () => setMenuOpen(false),
-        sections: [
-          {
-            title: 'Main',
-            items: [
-              { id: 'home', label: 'Home', href: '/', icon: <Home />, isActive: true },
-              { id: 'settings', label: 'Settings', href: '/settings', icon: <Settings /> },
-            ],
-          },
-        ],
-        footer: <button onClick={() => setMenuOpen(false)}>Sign Out</button>,
-      }}
-    />
-  )
+const navConfig: MobileNavConfig = {
+  onClose: () => setOpen(false),
+  sections: [
+    {
+      title: 'Main',
+      items: [
+        { id: 'home', label: 'Home', href: '/', isActive: true },
+        { id: 'settings', label: 'Settings', onClick: openSettings },
+      ],
+    },
+  ],
+  footer: <UserAccountWidget />,
 }
-```
+
+<MobileNavPanel isOpen={isNavOpen} config={navConfig} />
+```
+
+## Notes
+
+- The panel is **layout-mounted on every page** but returns `null` when closed; observers activate only while open.
+- Positioning uses a CSS custom property `--mobile-nav-top` derived from the measured header height, avoiding overflow under mobile browser chrome.
+- The footer respects iOS safe-area insets via `env(safe-area-inset-bottom)`.
+- Source: [`src/components/navigation/mobile-nav-panel.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/components/navigation/mobile-nav-panel.tsx)

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

@@ -0,0 +1,76 @@
+<!-- source-hash: eda7ac7f37238cf41917334033d772b6 -->
+Renders a recursive, multi-level document tree navigation UI with support for both desktop sidebar and mobile dropdown layouts, handling folder/file selection state with a folder-index (README) convention.
+
+## Key Components
+
+### Exports
+
+| Name | Type | Description |
+|------|------|-------------|
+| `NavigationNode` | Interface | Tree node shape (file or folder) compatible with `DocNode` for type-safe assignment |
+| `MultiLevelNavigation` | Component | Desktop sidebar navigation with recursive expand/collapse and visual selection ribbon |
+| `MobileNavigationDropdown` | Component | Compact mobile variant of the navigation tree |
+
+### Internal
+
+| Name | Description |
+|------|-------------|
+| `isNodeVisuallySelected` | Pure function implementing the folder-with-README selection convention — the folder node is never visually selected; its README child is |
+| `NavigationItem` | Recursive desktop tree node (file icon, folder icon, expand chevron, selection ribbon) |
+| `MobileNavigationItem` | Recursive mobile tree node (slightly smaller hit targets) |
+
+### Props (`MultiLevelNavigationProps`)
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `nodes` | `NavigationNode[]` | Root-level tree nodes |
+| `selectedPath` | `string` | Currently active document path |
+| `expandedNodes` | `Set<string>` | Set of expanded folder node IDs |
+| `onNodeClick` | `(node) => void` | Called on node selection |
+| `onToggleExpand` | `(nodeId) => void` | Optional separate expand handler |
+| `folderIndexFile` | `string` | Folder-index filename, defaults to `'README.md'` |
+
+## Usage Example
+
+```typescript
+import { MultiLevelNavigation, MobileNavigationDropdown } from './multi-level-navigation'
+import type { NavigationNode } from './multi-level-navigation'
+import { useState } from 'react'
+
+const tree: NavigationNode[] = [
+  {
+    id: 'docs',
+    name: 'Docs',
+    path: 'docs',
+    type: 'folder',
+    hasReadme: true,
+    children: [
+      { id: 'docs/README.md', name: 'README', path: 'docs/README.md', type: 'file' },
+      { id: 'docs/setup.md', name: 'Setup', path: 'docs/setup.md', type: 'file' },
+    ],
+  },
+]
+
+export function Sidebar() {
+  const [selectedPath, setSelectedPath] = useState('')
+  const [expandedNodes, setExpandedNodes] = useState<Set<string>>(new Set(['docs']))
+
+  return (
+    <MultiLevelNavigation
+      nodes={tree}
+      selectedPath={selectedPath}
+      expandedNodes={expandedNodes}
+      onNodeClick={(node) => setSelectedPath(node.path)}
+      onToggleExpand={(id) =>
+        setExpandedNodes(prev => {
+          const next = new Set(prev)
+          next.has(id) ? next.delete(id) : next.add(id)
+          return next
+        })
+      }
+    />
+  )
+}
+```
+
+> **Folder-index convention:** When `selectedPath` points to a folder that has a README, the visual selection ribbon renders on the README child, not the folder row itself.

package/src/components/navigation/.navigation-sidebar-item.md

@@ -1,25 +1,25 @@
-<!-- source-hash: c8f7676bd726a51b4cf502a4fd6cee17 -->
-Renders an individual navigation sidebar button with support for active state, disabled state, icon rendering, collapsible label visibility, and optional badge display.
+<!-- source-hash: 6877367e58f856ff5bd01b0038abbc1d -->
+Renders an accessible, stateful sidebar navigation button that supports active, disabled, and unread notification states with animated label visibility.
 
 ## Key Components
 
 ### `NavigationSidebarItemButtonProps`
 | Prop | Type | Description |
 |------|------|-------------|
-| `item` | `NavigationSidebarItem` | Navigation item data (label, icon, badge, isActive) |
-| `showLabel` | `boolean` | Controls label and badge visibility (collapsed/expanded sidebar) |
-| `disabled` | `boolean` | Disables interaction and applies reduced-opacity styling |
+| `item` | `NavigationSidebarItem` | Navigation item data (label, icon, active state, unread count) |
+| `showLabel` | `boolean` | Toggles label/unread badge visibility (collapsed vs. expanded sidebar) |
+| `disabled` | `boolean` | Disables interaction and applies muted styling |
 | `onClick` | `(item, event?) => void` | Click handler receiving the item and optional mouse event |
 
 ### `NavigationSidebarItemButton`
-The primary exported component. Applies four distinct visual states via `cn()`:
+The primary export. Renders a `<button>` with four visual states driven by `isActive` and `disabled` combinations:
 
-| State | Appearance |
-|-------|-----------|
-| Default | Primary text, secondary icon fill |
-| Hover (not active) | `ods-bg-hover` background |
-| Active | Yellow-light background, accent text/icon, left accent border |
-| Disabled | 50% opacity, `not-allowed` cursor |
+- **Default** — hover background, secondary text/icon colors
+- **Active** — yellow-light background, accent left border, accent text/icon
+- **Disabled** — reduced opacity, `cursor-not-allowed`, secondary colors
+- **Active + Disabled** — secondary colors, no accent styling
+
+Unread count renders as a small dot badge on the icon when collapsed, or a numbered pill (capped at `99+`) beside the label when expanded.
 
 ## Usage Example
 
@@ -31,7 +31,7 @@ const item = {
   label: 'Dashboard',
   icon: <HomeIcon />,
   isActive: true,
-  badge: '3',
+  unreadCount: 5,
 }
 
 <NavigationSidebarItemButton
@@ -42,4 +42,4 @@ const item = {
 />
 ```
 
-> **Note:** The icon is rendered via `cloneElement` to inject the appropriate `color` prop based on active/disabled state. Ensure icons accept an `IconProps`-compatible interface (`color`, `className`).
+> **Note:** Icon color is injected via `cloneElement`, so icons must accept a `color` prop to respond to active/disabled state changes.

package/src/components/navigation/.navigation-sidebar.md

@@ -1,30 +1,22 @@
-<!-- source-hash: 6f802a22aab4156f34b7564f49df9553 -->
-Responsive navigation sidebar component that renders a collapsible, accessible side navigation panel with distinct behavior for tablet (overlay/floating) and desktop (push layout) viewports.
+<!-- source-hash: c0bb51dff21ce2a1f2d328b688a856a9 -->
+A responsive, collapsible navigation sidebar component that adapts between desktop (persistent, width-animating) and tablet (overlay/drawer) layouts, persisting the desktop minimize state to `localStorage`.
 
 ## Key Components
 
 | Export | Type | Description |
 |--------|------|-------------|
-| `NavigationSidebar` | Component | Main sidebar component with responsive layout logic |
+| `NavigationSidebar` | Component | Main sidebar component with responsive behavior |
 | `NavigationSidebarProps` | Interface | Props: `config: NavigationSidebarConfig`, `disabled?: boolean` |
-| `MINIMIZED_WIDTH` | Constant | Collapsed width: `56px` |
-| `EXPANDED_WIDTH` | Constant | Expanded width: `224px` |
-| `STORAGE_KEY` | Constant | localStorage key for desktop minimized state |
+| `MINIMIZED_WIDTH` | Constant | Collapsed width — `56px` |
+| `EXPANDED_WIDTH` | Constant | Expanded width — `224px` |
+| `STORAGE_KEY` | Constant | `localStorage` key: `of.navigationSidebar.minimized` |
 
-### Behavior by Breakpoint
+**Internal behavior:**
 
-| Viewport | Behavior | State Persistence |
-|----------|----------|-------------------|
-| `< md` | Hidden | — |
-| `md` (tablet) | Floating overlay, starts minimized | In-memory only |
-| `≥ lg` (desktop) | Push layout | localStorage |
-
-### Key Internal Logic
-
-- **`minimized`** — resolves to `tabletMinimized` or `desktopMinimized` based on viewport
-- **`transitionsEnabled`** — deferred via `requestAnimationFrame` to prevent flash of wrong width on hydration
-- **`isOverlayOpen`** — drives backdrop scrim visibility and `Escape` key dismissal
-- **`primaryItems` / `secondaryItems`** — items split by `section !== 'secondary'` filter
+- **Desktop (`lg+`)** — sidebar pushes content; minimize state persists via `localStorage`
+- **Tablet (`md` only)** — sidebar floats as an overlay; always starts minimized (in-memory state only); backdrop scrim + `Escape` key close it
+- **Transitions** — enabled after first hydrated paint via `useLayoutEffect` + `requestAnimationFrame` to prevent flash on load
+- Items split into `primaryItems` and `secondaryItems` (filtered by `item.section === 'secondary'`)
 
 ## Usage Example
 
@@ -34,13 +26,28 @@ import { NavigationSidebarConfig } from '../../types/navigation'
 
 const config: NavigationSidebarConfig = {
   minimized: false,
+  onNavigate: (path) => router.push(path),
+  onToggleMinimized: () => console.log('toggled'),
   items: [
     { id: 'dashboard', label: 'Dashboard', path: '/dashboard', icon: HomeIcon },
     { id: 'settings', label: 'Settings', path: '/settings', icon: SettingsIcon, section: 'secondary' },
   ],
-  onNavigate: (path) => router.push(path),
-  onToggleMinimized: () => console.log('toggled'),
 }
 
-<NavigationSidebar config={config} disabled={false} />
-```
+export default function AppLayout() {
+  return (
+    <div className="relative flex h-screen">
+      <NavigationSidebar config={config} disabled={false} />
+      <main className="flex-1 overflow-auto">
+        {/* page content */}
+      </main>
+    </div>
+  )
+}
+```
+
+## Notes
+
+- The parent layout container must be `position: relative` for the tablet overlay anchor to work correctly.
+- The `disabled` prop dims all nav items but leaves the collapse toggle interactive.
+- Source: [`navigation-sidebar.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/navigation-sidebar.tsx)

package/src/components/navigation/.sliding-sidebar.md

@@ -1,43 +1,48 @@
-<!-- source-hash: 84f0966556e789258670b58482f3bc27 -->
-A client-side animated sidebar component that slides in from either edge of the screen, supporting nested navigation items, dynamic header offset calculation, and animated expand/collapse for sub-menus.
+<!-- source-hash: 9eba798cffb073c1e0f63ba366c6bd59 -->
+Accessible animated sidebar component that slides in from the left or right edge of the viewport, with focus management, scroll locking, and nested navigation support.
 
 ## Key Components
 
+### `SlidingSidebar`
+
+The primary export. Accepts a `SlidingSidebarConfig` object to control open state, position, navigation items, and lifecycle callbacks.
+
 ### `SlidingSidebarProps`
-| Prop | Type | Description |
-|------|------|-------------|
-| `config` | `SlidingSidebarConfig` | Full sidebar configuration including `isOpen`, `position`, `items`, `onClose`, `footer`, and `className` |
 
-### Internal State
-| State | Purpose |
-|-------|---------|
-| `expandedItems` | Tracks which nav items have their children visible |
-| `mounted` | Guards against SSR hydration mismatches |
-| `headerHeight` | Dynamic offset calculated from `<header>` and `[data-announcement-bar]` elements |
+```typescript
+interface SlidingSidebarProps {
+  config: SlidingSidebarConfig // position, isOpen, onClose, items, footer, className
+}
+```
+
+### Internal Helpers
+
+- **`renderMenuItem`** — Recursively renders `NavigationItem` nodes as expandable groups (with animated `AnimatePresence` children) or leaf buttons/links. Supports custom `element` overrides, badges, icons, and active state styling.
+- **`toggleExpanded`** — Manages a `Set<string>` of expanded parent item IDs.
 
-### `renderMenuItem(item, level)`
-Recursive renderer that handles three item variants:
-- **Custom element** — renders `item.element` directly
-- **Parent node** — renders a toggle button with animated `AnimatePresence` child list
-- **Leaf node** — renders a `Button` that calls `item.onClick?.()` then `config.onClose()`
+### Accessibility & UX Hooks
 
-### Header Height Detection
-Uses `ResizeObserver` + `MutationObserver` to dynamically track the combined height of `<header>` and `[data-announcement-bar]`, keeping the sidebar content correctly offset as layout changes.
+| Hook | Purpose |
+|---|---|
+| `usePreventScroll` | Locks body scroll while the sidebar is open |
+| `useFocusTrap` | Traps/restores focus; fires `onClose` on Escape. Non-modal (`contain: false`) so the z-50 header stays reachable |
+| `useReducedMotion` | Collapses spring animation to instant when the OS prefers reduced motion |
+| `useHeaderHeight` | Inserts a dynamic spacer so the panel clears the app header |
 
 ## Usage Example
 
 ```typescript
-import { SlidingSidebar } from './sliding-sidebar'
+import { SlidingSidebar } from '@openframe/ui'
 import { useState } from 'react'
 
-function AppShell() {
-  const [isOpen, setIsOpen] = useState(false)
+export function AppShell() {
+  const [open, setOpen] = useState(false)
 
   return (
     <SlidingSidebar
       config={{
-        isOpen,
-        onClose: () => setIsOpen(false),
+        isOpen: open,
+        onClose: () => setOpen(false),
         position: 'left',
         items: [
           {
@@ -55,11 +60,11 @@ function AppShell() {
             ],
           },
         ],
-        footer: <div>v1.0.0</div>,
+        footer: <p className="text-sm text-ods-text-secondary">v1.0.0</p>,
       }}
     />
   )
 }
 ```
 
-> **Note:** The sidebar is client-only (`"use client"`). It returns `null` until after mount to prevent SSR/hydration mismatches. Nest it inside a layout that also renders the `<header>` element so the offset calculation works correctly.
+> **Z-index note:** The overlay sits at `z-[45]` and the panel at `z-[46]`, keeping both above the footer (`z-[44]`) but below the app header (`z-[50]`) and any modals (`z-50+`). See `ODS_TOKEN_RULES.md` for the full z-index hierarchy.

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

@@ -1,42 +1,43 @@
-<!-- source-hash: fab223205d06a85cbd1f071b97356037 -->
-Sticky section navigation component and scroll-spy hook for section-based page navigation, used across vendor detail pages, knowledge base, and documentation surfaces.
+<!-- source-hash: 06a508edb80b9bce20fd7344ee3e0962 -->
+Reusable sticky navigation component and scroll-spy hook for section-based page navigation, commonly used in vendor detail pages, knowledge base articles, and documentation layouts.
 
 ## Key Components
 
 ### `StickySectionNav`
-A `<nav>` component that renders a vertical list of section buttons with an animated yellow ribbon indicator for the active section.
+A controlled `<nav>` component that renders a vertical list of section links with an animated active-state ribbon indicator.
 
 **Props:**
 
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
+|---|---|---|---|
 | `sections` | `StickyNavSection[]` | — | Array of `{ id, label }` nav items |
 | `activeSection` | `string` | — | ID of the currently active section |
 | `onSectionClick` | `(id: string) => void` | — | Click handler for nav items |
 | `ribbonPosition` | `'left' \| 'right'` | `'left'` | Side the active ribbon renders on |
-| `ribbonColor` | `string` | `'#FFC008'` | Active ribbon color |
-| `className` | `string` | — | Optional extra class names |
+| `ribbonColor` | `string` | `var(--color-accent-primary)` | CSS color for the active ribbon |
+| `className` | `string` | — | Optional class override |
 
 ### `useSectionNavigation`
-A hook that wires up scroll-spy and programmatic scrolling for a set of section refs.
+A React hook that wires up scroll-spy detection and smooth scrolling for a set of section refs. Uses `scrollElementIntoView` internally and suppresses scroll-spy during programmatic scrolls.
 
-**Returns:** `{ activeSection, handleSectionClick }`
+**Parameters:**
 
-**Options:**
+| Param | Type | Description |
+|---|---|---|
+| `sections` | `{ id: string; ref: RefObject<HTMLElement> }[]` | Sections to track |
+| `options.offset` | `number` | Scroll offset for sticky chrome (default: `100`) |
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `offset` | `number` | `100` | Header offset in px passed to `scrollElementIntoView` |
+**Returns:** `{ activeSection: string, handleSectionClick: (id: string) => void }`
 
 ## Usage Example
 
 ```typescript
-const heroRef = useRef<HTMLElement>(null)
-const detailsRef = useRef<HTMLElement>(null)
+const overviewRef = useRef<HTMLElement>(null)
+const detailsRef  = useRef<HTMLElement>(null)
 
 const sections = [
-  { id: 'hero', ref: heroRef },
-  { id: 'details', ref: detailsRef },
+  { id: 'overview', ref: overviewRef },
+  { id: 'details',  ref: detailsRef },
 ]
 
 const { activeSection, handleSectionClick } = useSectionNavigation(sections, {
@@ -47,17 +48,18 @@ return (
   <>
     <StickySectionNav
       sections={[
-        { id: 'hero', label: 'Overview' },
-        { id: 'details', label: 'Details' },
+        { id: 'overview', label: 'Overview' },
+        { id: 'details',  label: 'Details' },
       ]}
       activeSection={activeSection}
       onSectionClick={handleSectionClick}
       ribbonPosition="left"
     />
-    <section id="hero" ref={heroRef}>...</section>
-    <section id="details" ref={detailsRef}>...</section>
+
+    <section id="overview" ref={overviewRef}>...</section>
+    <section id="details"  ref={detailsRef}>...</section>
   </>
 )
 ```
 
-> **Scroll-spy behavior:** Scroll events are throttled at 100ms. A `isScrollingFromClick` guard suppresses the spy for 500ms after a nav click to prevent active-state flicker during programmatic scrolling.
+**Source:** [`sticky-section-nav.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/sticky-section-nav.tsx)

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

@@ -0,0 +1,40 @@
+<!-- source-hash: 32d8ecb25777faace2a4b5a46e28428a -->
+Barrel export file for the **Onboarding Guides** product surface, scoped to the `openframe` route. Aggregates view components, skeleton loaders, and query hooks for consuming applications.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `OnboardingGuidesCatalogView` | Component | Full catalog/list view for onboarding guides |
+| `OnboardingGuidesCatalogViewProps` | Type | Props interface for the catalog view |
+| `OnboardingGuideDetailView` | Component | Detail/single-guide view |
+| `OnboardingGuideDetailViewProps` | Type | Props interface for the detail view |
+| `OnboardingGuidesCatalogSkeleton` | Component | Loading skeleton for the catalog view |
+| `useOnboardingGuides` | Hook | Fetches a paginated list of onboarding guides |
+| `useOnboardingGuide` | Hook | Fetches a single onboarding guide by ID |
+| `useOnboardingGuideSections` | Hook | Fetches sections for a given guide |
+| `onboardingGuideKeys` | Object | TanStack Query key factory for cache management |
+
+## Usage Example
+
+```typescript
+import {
+  OnboardingGuidesCatalogView,
+  OnboardingGuideDetailView,
+  OnboardingGuidesCatalogSkeleton,
+  useOnboardingGuides,
+} from '@flamingo-stack/openframe-oss-lib/components/onboarding-guides'
+
+// If you need the OnboardingGuide row type, import from the chat surface:
+import type { OnboardingGuide } from
+  '@flamingo-stack/openframe-frontend-core/components/chat'
+
+function GuidesPage() {
+  const { data, isLoading } = useOnboardingGuides()
+
+  if (isLoading) return <OnboardingGuidesCatalogSkeleton />
+  return <OnboardingGuidesCatalogView guides={data} />
+}
+```
+
+> **⚠️ Ambiguous re-export warning:** Do **not** re-export `OnboardingGuide`, `OnboardingGuideFilters`, `OnboardingGuideListResponse`, or `OnboardingGuideSectionSummary` from this barrel. These types are already exported via `components/chat` — duplicating them causes **TS2308** at the top-level `components/index.ts` barrel. See [`shared/roadmap/index.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/shared/roadmap/index.ts) for the same pattern applied to `RoadmapItem`.