@flamingo-stack/openframe-frontend-core 0.0.285 → 0.0.286

package/dist/utils/markdown-section-extractor.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared markdown section extractor
+ * Extracts heading sections from markdown content for navigation.
+ */
+export interface MarkdownSection {
+    id: string;
+    title: string;
+    level: number;
+}
+export interface ExtractSectionsOptions {
+    /** Maximum heading level to include (default: 2 = H1-H2) */
+    maxLevel?: number;
+    /** Remove emoji characters from IDs (default: true) */
+    removeEmojis?: boolean;
+    /** Handle duplicate IDs by appending a counter suffix (default: true) */
+    handleDuplicateIds?: boolean;
+    /** Strip bold, italic, and inline code markers from titles (default: true) */
+    stripFormattingMarkers?: boolean;
+    /** Skip code blocks and YAML frontmatter (default: true) */
+    skipCodeAndYamlBlocks?: boolean;
+}
+export declare function extractSections(markdown: string, options?: ExtractSectionsOptions): MarkdownSection[];
+//# sourceMappingURL=markdown-section-extractor.d.ts.map

package/dist/utils/markdown-section-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-section-extractor.d.ts","sourceRoot":"","sources":["../../src/utils/markdown-section-extractor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,sBAAsB;IACrC,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,uDAAuD;IACvD,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,yEAAyE;IACzE,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B,8EAA8E;IAC9E,sBAAsB,CAAC,EAAE,OAAO,CAAA;IAChC,4DAA4D;IAC5D,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAChC;AAUD,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,sBAA2B,GACnC,eAAe,EAAE,CAoEnB"}

package/dist/utils/markdown-to-plain.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Convert markdown source to plain text. Used by both the SEO server component
+ * (article-body echo in JSON-LD) and chat entity-card preview (clamped previews
+ * inside chat cards).
+ *
+ * The two consumers differ only in pre/post processing — `mode: 'article'`
+ * strips code blocks + images + headings + list bullets and preserves paragraph
+ * breaks; `mode: 'preview'` collapses everything to a single line. Both share
+ * the same inline-marker strip (link / bold / italic / inline-code).
+ *
+ * All regex patterns are linear (negated character classes, non-greedy with
+ * bounded targets) — no nested quantifiers, no catastrophic backtracking on
+ * pathological input.
+ */
+export interface MarkdownToPlainOptions {
+    /**
+     * - `'article'` (default): preserve paragraph structure (`\n\n` as separator),
+     *   strip code blocks + images + headings + list bullets. Used for the
+     *   article-body echo on SEO surfaces.
+     * - `'preview'`: collapse all whitespace to single spaces; result is a single
+     *   line. Used for chat-card previews / OG-card snippets where line breaks
+     *   would wrap awkwardly.
+     */
+    mode?: 'article' | 'preview';
+    /** Optional max-character cap. Truncates with no ellipsis (caller-decided). */
+    maxChars?: number;
+}
+/** Strip inline markdown markers (bold, italic, inline-code, links). Shared
+ *  by `extractSections`'s `stripFormattingMarkers` and `markdownToPlainText`. */
+export declare function stripInlineMarkdown(s: string): string;
+export declare function markdownToPlainText(markdown: string, options?: MarkdownToPlainOptions): string;
+//# sourceMappingURL=markdown-to-plain.d.ts.map

package/dist/utils/markdown-to-plain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-to-plain.d.ts","sourceRoot":"","sources":["../../src/utils/markdown-to-plain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,sBAAsB;IACrC;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,SAAS,GAAG,SAAS,CAAA;IAC5B,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;iFACiF;AACjF,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAMrD;AAED,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,sBAA2B,GACnC,MAAM,CA0BR"}

package/dist/utils/tree-builder.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Base interface for tree nodes. Consumers extend this with additional fields.
+ */
+export interface TreeNodeBase {
+    id: string;
+    name: string;
+    path: string;
+    type: 'file' | 'folder';
+    sortOrder?: number;
+    children?: TreeNodeBase[];
+}
+/**
+ * Format a document name for display: remove .md extension and capitalize.
+ */
+export declare function formatDocName(name: string): string;
+/**
+ * Sort children: README first, then folders, then files — each group by sort_order then alphabetical.
+ * Recurses into folder children to ensure consistent ordering at all levels.
+ */
+export declare function sortTreeChildren<TNode extends TreeNodeBase>(nodes: TNode[]): TNode[];
+/**
+ * Build a hierarchical document tree from a flat list of records.
+ *
+ * 3-pass algorithm:
+ *   1. Create node map from flat records using the provided `mapFn`
+ *   2. Build parent-child hierarchy using `getParentPath`
+ *   3. Sort children (folders first, README, then others)
+ */
+export declare function buildDocumentTree<TNode extends TreeNodeBase, TDoc>(docs: TDoc[], mapFn: (doc: TDoc) => TNode, getParentPath: (doc: TDoc) => string | null, getPath: (doc: TDoc) => string): TNode[];
+//# sourceMappingURL=tree-builder.d.ts.map

package/dist/utils/tree-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-builder.d.ts","sourceRoot":"","sources":["../../src/utils/tree-builder.ts"],"names":[],"mappings":"AAMA;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAA;IACvB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,YAAY,EAAE,CAAA;CAC1B;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CASlD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,SAAS,YAAY,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE,CAwBpF;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,SAAS,YAAY,EAAE,IAAI,EAChE,IAAI,EAAE,IAAI,EAAE,EACZ,KAAK,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,KAAK,EAC3B,aAAa,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,MAAM,GAAG,IAAI,EAC3C,OAAO,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,MAAM,GAC7B,KAAK,EAAE,CAsCT"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.285",
+  "version": "0.0.286",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",
@@ -126,6 +126,24 @@
       "require": "./dist/components/navigation/index.cjs",
       "default": "./dist/components/navigation/index.js"
     },
+    "./components/docs": {
+      "types": "./dist/components/docs/index.d.ts",
+      "import": "./dist/components/docs/index.js",
+      "require": "./dist/components/docs/index.cjs",
+      "default": "./dist/components/docs/index.js"
+    },
+    "./components/embeds": {
+      "types": "./dist/components/embeds/index.d.ts",
+      "import": "./dist/components/embeds/index.js",
+      "require": "./dist/components/embeds/index.cjs",
+      "default": "./dist/components/embeds/index.js"
+    },
+    "./types/doc-source": {
+      "types": "./dist/types/doc-source.d.ts",
+      "import": "./dist/types/doc-source.js",
+      "require": "./dist/types/doc-source.cjs",
+      "default": "./dist/types/doc-source.js"
+    },
     "./hooks": {
       "types": "./dist/hooks/index.d.ts",
       "import": "./dist/hooks/index.js",

package/src/components/chat/chat-attachment-bar.tsx

@@ -1,6 +1,8 @@
 'use client'
 // compact-size support added for the ticket-drawer reply composer.
 
+import { formatFileSize } from '../../utils/format'
+
 /**
  * Chat-attachment UI primitives.
  *
@@ -321,19 +323,12 @@ function AttachmentChip({ attachment, onRemove, disabled, size = 'default' }: At
 }
 
 // ---------------------------------------------------------------------------
-// Helpers — inlined from hub upload-utils.ts to keep this file standalone
+// Helpers
 // ---------------------------------------------------------------------------
 
-/** Same byte-rounding shape as the hub `formatFileSize` in
- *  `lib/utils/upload-utils.ts`. Inlined so the lib doesn't pull in the
- *  hub upload service. */
-function formatFileSize(bytes: number): string {
-  if (bytes === 0) return '0 B'
-  const k = 1024
-  const sizes = ['B', 'KB', 'MB', 'GB']
-  const i = Math.floor(Math.log(bytes) / Math.log(k))
-  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(1))} ${sizes[i]}`
-}
+// formatFileSize was previously inlined here as a copy of the hub's helper. It
+// now lives in `../../utils/format.ts` (lifted during the doc-viewer unification).
+// Imported at the top of this file.
 
 function extLabel(fileName: string): string {
   const dot = fileName.lastIndexOf('.')

package/src/components/docs/doc-navigation-context.tsx

@@ -0,0 +1,123 @@
+"use client"
+
+import React, { createContext, useCallback, useContext, useRef, type ReactNode } from 'react'
+import type { DocNode } from '../../types/doc-source'
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface DocNavigator {
+  /** Base route this navigator owns (e.g., '/knowledge-base', '/data-room'). */
+  baseRoute: string
+  /** Look up a node in the tree by its storage path (e.g., 'openframe-cli/README.md'). */
+  findNodeByPath: (path: string) => DocNode | null
+  /** Navigate to a node using the same flow as a sidebar menu click. */
+  selectNode: (node: DocNode) => void
+}
+
+interface DocNavigationContextValue {
+  /**
+   * Register a navigator for a `baseRoute`. Returns a cleanup function that
+   * removes the navigator from the map IF the slot still owns it (StrictMode-safe).
+   * Duplicate registration for the same baseRoute logs a console.warn and replaces.
+   */
+  register: (nav: DocNavigator) => () => void
+  /**
+   * Navigate to a path inside whichever registered navigator owns its baseRoute prefix.
+   * Returns true if handled, false otherwise (caller falls back to opening in a new tab).
+   */
+  navigate: (path: string) => boolean
+  /** Whether ANY navigator is currently mounted. */
+  isAvailable: () => boolean
+}
+
+// =============================================================================
+// Context
+// =============================================================================
+
+const DocNavigationContext = createContext<DocNavigationContextValue | null>(null)
+
+/**
+ * Bridges `useDocumentTree` instances (deep in the page tree) to `GlobalAskAI`
+ * (high up near the root) without global events or URL parsing.
+ *
+ * Multi-navigator design: a `Map<baseRoute, DocNavigator>` lets multiple
+ * viewers coexist (nested viewers, dual-pane scenarios). Today only one
+ * viewer mounts at a time, so behavior is unchanged.
+ */
+export function DocNavigationProvider({ children }: { children: ReactNode }) {
+  const navMap = useRef<Map<string, DocNavigator>>(new Map())
+
+  const register = useCallback((nav: DocNavigator) => {
+    const existing = navMap.current.get(nav.baseRoute)
+    if (existing && existing !== nav) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[DocNavigationContext] duplicate registration for ${nav.baseRoute}; replacing`,
+      )
+    }
+    navMap.current.set(nav.baseRoute, nav)
+    return () => {
+      // StrictMode-safe identity check: only delete if THIS nav still owns the slot.
+      if (navMap.current.get(nav.baseRoute) === nav) {
+        navMap.current.delete(nav.baseRoute)
+      }
+    }
+  }, [])
+
+  const findOwningNavigator = useCallback((path: string): DocNavigator | null => {
+    // First try: a navigator whose baseRoute is a prefix of `path`. Walks the
+    // longest match first so nested routes win over a parent.
+    const baseRoutes = Array.from(navMap.current.keys()).sort((a, b) => b.length - a.length)
+    for (const baseRoute of baseRoutes) {
+      if (path === baseRoute || path.startsWith(`${baseRoute}/`)) {
+        return navMap.current.get(baseRoute) ?? null
+      }
+    }
+    // Fallback: a single navigator handles any path (existing behavior — chat
+    // chips emit storage paths, not absolute URLs, so prefix matching misses).
+    if (navMap.current.size === 1) {
+      return navMap.current.values().next().value ?? null
+    }
+    return null
+  }, [])
+
+  const navigate = useCallback(
+    (path: string): boolean => {
+      const nav = findOwningNavigator(path)
+      if (!nav) return false
+      const node = nav.findNodeByPath(path)
+      if (!node) return false
+      nav.selectNode(node)
+      return true
+    },
+    [findOwningNavigator],
+  )
+
+  const isAvailable = useCallback(() => navMap.current.size > 0, [])
+
+  const value = React.useMemo(
+    () => ({ register, navigate, isAvailable }),
+    [register, navigate, isAvailable],
+  )
+
+  return <DocNavigationContext.Provider value={value}>{children}</DocNavigationContext.Provider>
+}
+
+// =============================================================================
+// Hooks
+// =============================================================================
+
+export function useDocNavigation(): DocNavigationContextValue {
+  const ctx = useContext(DocNavigationContext)
+  if (!ctx) {
+    // Safe no-op fallback when used outside the provider.
+    return {
+      register: () => () => {},
+      navigate: () => false,
+      isAvailable: () => false,
+    }
+  }
+  return ctx
+}

package/src/components/docs/doc-viewer.tsx

@@ -0,0 +1,345 @@
+"use client"
+
+import React, { useMemo } from "react"
+import { MultiLevelNavigation, MobileNavigationDropdown } from "../navigation/multi-level-navigation"
+import { PageHeading } from "../layout/page-heading"
+import { PersistentSidebar, PersistentMobileDropdown } from "../persistent-filter-controls"
+import { CategorySidebarSkeleton } from "../loading/page-layout-skeleton"
+import { DocSearchBar, useDocSearch } from "../shared/doc-search"
+import { StickySectionNav } from "../navigation/sticky-section-nav"
+import { useDocumentTree } from "./use-document-tree"
+import { useScrollSpy } from "./use-scroll-spy"
+import { useDocNavigation } from "./doc-navigation-context"
+import { findDocNodeByPath } from "../../utils/doc-tree-nav"
+import type { DocContent, DocNode, DocRenderHandlers, DocSourceId } from "../../types/doc-source"
+
+/** Color tokens for the doc-viewer chrome. Hub-side `DocViewer` callers share
+ *  this constant; no need to override per source — the palette is intentionally
+ *  uniform across knowledge-base + data-room (both use ODS dark tokens). */
+export const DEFAULT_DOC_VIEWER_PALETTE = {
+  background: "bg-ods-bg",
+  containerBackground: "transparent",
+  headerText: "text-ods-text-primary",
+  primaryText: "text-ods-text-primary",
+  secondaryText: "text-ods-text-secondary",
+  accent: "var(--ods-accent)",
+  border: "border-ods-border",
+  cardBackground: "bg-ods-card",
+} as const
+
+export interface DocViewerProps {
+  /**
+   * Registry source id (`'openframe-docs'`, `'data-room-docs'`, …). Flowed through
+   * `renderContent`'s handlers for `/api/resolve-link` POSTs.
+   */
+  sourceId: DocSourceId
+
+  /**
+   * Render the content body. The page shell owns this — it picks the markdown
+   * renderer, dispatches PDF/Figma/Sheets/file branches, etc. No renderer
+   * interface in between.
+   */
+  renderContent: (content: DocContent, handlers: DocRenderHandlers) => React.ReactNode
+
+  /**
+   * Render the loading skeleton. Receives the selected node's `documentType`
+   * (undefined while structure is still loading) so the caller can return a
+   * markdown-shaped skeleton vs an embed-shaped skeleton.
+   */
+  renderSkeleton: (documentType: DocNode['documentType']) => React.ReactNode
+
+  /**
+   * Chat-source identifier — passed in by the page shell from server-side
+   * `currentPlatform()`. Lib has no platform context; the page shell is the
+   * trusted boundary that wires this. NEVER pass user input here.
+   */
+  chatSource: string
+
+  title: string | React.ReactNode
+  /** Override the default ODS palette. Optional — most callers should omit. */
+  colorPalette?: typeof DEFAULT_DOC_VIEWER_PALETTE
+  className?: string
+
+  /** Initial doc path (URL `[...path]`). */
+  docPath?: string
+
+  /** Sidebar header copy (`'DOCUMENTATION'`, `'DATA ROOM'`). */
+  sidebarLabel?: string
+
+  /**
+   * API endpoint for fetching the document tree structure. Defaults to the
+   * dispatcher path `/api/docs/sources/${sourceId}/structure`. Override only
+   * if hosting the viewer behind a different route.
+   */
+  structureEndpoint?: string
+  /** Same shape as `structureEndpoint`. Defaults to `/api/docs/sources/${sourceId}/content`. */
+  contentEndpoint?: string
+  /** Base route path for URL navigation. */
+  baseRoute: string
+
+  /** Empty state copy when no doc is selected. */
+  emptyStateText?: string
+
+  /** Whether to render the doc-search bar (bound to chat). */
+  showAIChat?: boolean
+
+  /** Folder-index filename (default `'README.md'`). */
+  folderIndexFile?: string
+}
+
+export function DocViewer(props: DocViewerProps) {
+  return <DocViewerContent {...props} />
+}
+
+function DocViewerContent({
+  sourceId,
+  renderContent,
+  renderSkeleton,
+  chatSource,
+  title,
+  colorPalette = DEFAULT_DOC_VIEWER_PALETTE,
+  className = "",
+  docPath,
+  sidebarLabel = "DOCUMENTATION",
+  structureEndpoint,
+  contentEndpoint,
+  baseRoute,
+  emptyStateText,
+  showAIChat = false,
+  folderIndexFile,
+}: DocViewerProps) {
+  // Default endpoints derived from sourceId. Hub callers omit the props in 99%
+  // of cases; the override is for embed contexts where the doc-viewer sits
+  // behind a non-standard route.
+  const resolvedStructureEndpoint =
+    structureEndpoint ?? `/api/docs/sources/${sourceId}/structure`
+  const resolvedContentEndpoint =
+    contentEndpoint ?? `/api/docs/sources/${sourceId}/content`
+  const {
+    structure,
+    selectedPath,
+    content,
+    isLoadingStructure,
+    isLoadingContent,
+    error,
+    expandedNodes,
+    selectNode,
+    toggleNode,
+    navigateToDoc,
+  } = useDocumentTree(
+    {
+      structureEndpoint: resolvedStructureEndpoint,
+      contentEndpoint: resolvedContentEndpoint,
+      baseRoute,
+      folderIndexFile,
+    },
+    docPath,
+  )
+
+  const { activeSection, handleSectionClick } = useScrollSpy(content?.sections)
+
+  const docNav = useDocNavigation()
+  const docSearch = useDocSearch({
+    source: chatSource,
+    baseRoute,
+    onNavigate: (path) => navigateToDoc(path, { fromInternalLink: true }),
+    onInPageSwap: (path) => docNav.navigate(path),
+  })
+
+  const renderedContent = useMemo(() => {
+    if (!content) return null
+    return renderContent(content, {
+      onInternalLinkClick: navigateToDoc,
+      currentPath: selectedPath,
+      sourceId,
+    })
+  }, [content, selectedPath, renderContent, navigateToDoc, sourceId])
+
+  // Selected node's documentType drives:
+  //   - which skeleton the caller renders during fetch (markdown vs embed)
+  //   - the article max-width + sticky-nav visibility (markdown only)
+  // `undefined` documentType is treated as `'markdown'` (per the DocNode
+  // discriminator's documented default).
+  const selectedNodeDocType =
+    selectedPath && structure.length > 0
+      ? findDocNodeByPath(selectedPath, structure)?.documentType
+      : undefined
+  // During loading, the in-flight content's type isn't known yet — fall back
+  // to the selected node's type (or markdown if neither is set).
+  const activeDocType = content?.documentType ?? selectedNodeDocType
+  const isMarkdownContent = !activeDocType || activeDocType === 'markdown'
+  const showStickyNav = isMarkdownContent
+
+  const stickyNavSections =
+    content?.sections?.map((s) => ({ id: s.id, label: s.title })) ?? []
+
+  const isColorValue =
+    colorPalette.background.startsWith('#') ||
+    colorPalette.background.startsWith('rgb') ||
+    colorPalette.background.startsWith('var(')
+
+  const bgStyle = isColorValue ? { backgroundColor: colorPalette.background } : {}
+  const bgClass = !isColorValue ? colorPalette.background : ''
+  const containerBgStyle =
+    colorPalette.containerBackground !== 'transparent'
+      ? { backgroundColor: colorPalette.containerBackground }
+      : {}
+
+  const defaultEmptyText =
+    structure.length > 0
+      ? 'Select a document from the sidebar to view'
+      : 'No documents yet. Add content from the admin panel.'
+  const resolvedEmptyText = emptyStateText || defaultEmptyText
+
+  return (
+    <section className={`${bgClass} ${className}`} style={bgStyle}>
+      <div
+        className="max-w-[1920px] px-6 md:px-20 py-6 md:py-10 mx-auto"
+        style={containerBgStyle}
+      >
+        <div className="flex flex-col gap-6">
+          <div className="flex flex-col gap-4">
+            {typeof title === 'string' ? <PageHeading>{title}</PageHeading> : title}
+          </div>
+
+          {showAIChat && (
+            <DocSearchBar
+              placeholder={`Search ${sidebarLabel?.toLowerCase() || 'documents'}...`}
+              query={docSearch.query}
+              onQueryChange={docSearch.setQuery}
+              results={docSearch.results}
+              isLoading={docSearch.isLoading}
+              onResultSelect={docSearch.handleResultSelect}
+              showDropdown={docSearch.keepDropdownOpen}
+            />
+          )}
+
+          {error && (
+            <div className="flex justify-center">
+              <div className="rounded-lg border bg-ods-card p-8 text-center max-w-md border-ods-border">
+                <h2 className="text-xl font-semibold text-ods-text-primary">
+                  Error Loading Documents
+                </h2>
+                <p className="mt-2 text-ods-text-secondary">{error}. Please try again later.</p>
+              </div>
+            </div>
+          )}
+
+          {!error && (
+            <div className="flex flex-col lg:flex-row gap-6 lg:gap-10 items-start flex-1">
+              <div className="w-full lg:w-[320px] lg:shrink-0">
+                <div className="lg:sticky lg:top-20">
+                  {isLoadingStructure ? (
+                    <CategorySidebarSkeleton />
+                  ) : (
+                    <>
+                      <PersistentMobileDropdown isLoading={false}>
+                        <MobileNavigationDropdown
+                          nodes={structure}
+                          selectedPath={selectedPath}
+                          expandedNodes={expandedNodes}
+                          onNodeClick={selectNode}
+                          onToggleExpand={toggleNode}
+                          isLoading={false}
+                          folderIndexFile={folderIndexFile}
+                        />
+                      </PersistentMobileDropdown>
+
+                      <PersistentSidebar isLoading={false}>
+                        <div className="hidden lg:block">
+                          <div className="space-y-4">
+                            <h3 className="text-[14px] font-['Azeret_Mono'] font-semibold uppercase text-ods-text-secondary tracking-[-0.02em] leading-[1.43em]">
+                              {sidebarLabel}
+                            </h3>
+                            <MultiLevelNavigation
+                              nodes={structure}
+                              selectedPath={selectedPath}
+                              expandedNodes={expandedNodes}
+                              onNodeClick={selectNode}
+                              onToggleExpand={toggleNode}
+                              isLoading={false}
+                              folderIndexFile={folderIndexFile}
+                            />
+                          </div>
+                        </div>
+                      </PersistentSidebar>
+                    </>
+                  )}
+                </div>
+              </div>
+
+              <div className="flex-1 min-w-0 w-full">
+                <div
+                  className={`grid grid-cols-1 ${
+                    (showStickyNav && stickyNavSections.length > 0) ||
+                    isLoadingContent ||
+                    isLoadingStructure
+                      ? 'lg:grid-cols-[1fr_280px]'
+                      : ''
+                  } gap-8`}
+                >
+                  <div className={`w-full ${isMarkdownContent ? 'max-w-4xl mx-auto' : ''}`}>
+                    <article className="space-y-2">
+                      {(isLoadingContent || isLoadingStructure) ? (
+                        renderSkeleton(selectedNodeDocType)
+                      ) : !content ? (
+                        <div className="text-center py-16">
+                          <p className="text-xl text-ods-text-secondary">{resolvedEmptyText}</p>
+                        </div>
+                      ) : (
+                        renderedContent
+                      )}
+                    </article>
+                  </div>
+
+                  {(isLoadingContent || isLoadingStructure) && (
+                    <div className="hidden lg:block">
+                      <div className="sticky top-24">
+                        <div className="h-[14px] w-28 bg-ods-border rounded animate-pulse mb-5" />
+                        <div className="space-y-0">
+                          {[130, 170, 190, 220, 110, 200, 80, 100, 120, 140, 90].map((w, i) => (
+                            <div
+                              key={i}
+                              className={`py-[13px] pl-3 border-l-2 ${
+                                i === 0 ? 'border-ods-accent' : 'border-transparent'
+                              }`}
+                            >
+                              <div
+                                className="h-[13px] bg-ods-border rounded animate-pulse"
+                                style={{ width: w }}
+                              />
+                            </div>
+                          ))}
+                        </div>
+                      </div>
+                    </div>
+                  )}
+
+                  {showStickyNav &&
+                    content &&
+                    stickyNavSections.length > 0 &&
+                    !isLoadingContent && (
+                      <div className="hidden lg:block">
+                        <div className="sticky top-24">
+                          <h3 className="text-[14px] font-['Azeret_Mono'] font-semibold uppercase text-ods-text-secondary tracking-[-0.02em] leading-[1.43em] mb-4">
+                            ON THIS PAGE
+                          </h3>
+                          <StickySectionNav
+                            sections={stickyNavSections}
+                            activeSection={activeSection}
+                            onSectionClick={handleSectionClick}
+                            ribbonPosition="left"
+                            ribbonColor="var(--ods-accent)"
+                          />
+                        </div>
+                      </div>
+                    )}
+                </div>
+              </div>
+            </div>
+          )}
+        </div>
+      </div>
+    </section>
+  )
+}

package/src/components/docs/index.ts

@@ -0,0 +1,12 @@
+"use client"
+
+export { DocViewer } from './doc-viewer'
+export type { DocViewerProps } from './doc-viewer'
+
+export { useDocumentTree } from './use-document-tree'
+export type { UseDocumentTreeConfig } from './use-document-tree'
+
+export { useScrollSpy } from './use-scroll-spy'
+
+export { DocNavigationProvider, useDocNavigation } from './doc-navigation-context'
+export type { DocNavigator } from './doc-navigation-context'