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

package/src/components/docs/use-document-tree.ts

@@ -0,0 +1,427 @@
+"use client"
+
+import { useState, useEffect, useCallback, useRef } from 'react'
+import type { DocNode, DocContent } from '../../types/doc-source'
+import {
+  stripFolderIndexFromPath,
+  findDocNodeByPath,
+  getDocAncestorNodeIds,
+  DEFAULT_FOLDER_INDEX_FILE,
+} from '../../utils/doc-tree-nav'
+import { useDocNavigation } from './doc-navigation-context'
+import { scrollElementIntoView } from '../../utils/scroll-into-view'
+
+function scrollToContent() {
+  const article = document.querySelector('article') as HTMLElement | null
+  if (article) {
+    scrollElementIntoView(article, { headerOffset: 80 })
+  } else {
+    window.scrollTo({ top: 0, behavior: 'smooth' })
+  }
+}
+
+export interface UseDocumentTreeConfig {
+  /** API endpoint for fetching the document tree structure */
+  structureEndpoint: string
+  /** API endpoint for fetching document content */
+  contentEndpoint: string
+  /** Base route path for URL navigation (e.g., '/knowledge-base', '/data-room') */
+  baseRoute: string
+  /** Folder-index filename (defaults to 'README.md'). */
+  folderIndexFile?: string
+}
+
+/**
+ * Generic hook for document tree navigation and content fetching.
+ * Drives DocViewer across all doc-source consumers.
+ *
+ * Client-only: structure + content fetches run in parallel on first mount.
+ * No SSR pre-population — the previous SSR path required a Supabase admin
+ * client (service role key) and silently fell back to client fetches on
+ * envs where the key wasn't set; the parallel client fetches keep behavior
+ * uniform across local + prod (latency ~= max(structure, content), not sum).
+ */
+export function useDocumentTree(
+  config: UseDocumentTreeConfig,
+  initialPath?: string,
+) {
+  const { structureEndpoint, contentEndpoint, baseRoute } = config
+  const folderIndexFile = config.folderIndexFile ?? DEFAULT_FOLDER_INDEX_FILE
+
+  const cleanInitialPath = stripFolderIndexFromPath(
+    initialPath?.replace(/\/$/, '') || '',
+    folderIndexFile,
+  )
+
+  const [structure, setStructure] = useState<DocNode[]>([])
+  const [selectedPath, setSelectedPath] = useState<string>(cleanInitialPath)
+  const [content, setContent] = useState<DocContent | null>(null)
+  const [isLoadingStructure, setIsLoadingStructure] = useState(true)
+  const [isLoadingContent, setIsLoadingContent] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [expandedNodes, setExpandedNodes] = useState<Set<string>>(new Set())
+  const [isInitialized, setIsInitialized] = useState(false)
+  const lastFetchedPath = useRef<string | null>(null)
+
+  const normalizedBaseRoute = baseRoute.replace(/\/$/, '')
+
+  const selectedPathRef = useRef(selectedPath)
+  selectedPathRef.current = selectedPath
+
+  const docNavigation = useDocNavigation()
+
+  useEffect(() => {
+    const handlePopState = () => {
+      const pathname = window.location.pathname
+      let pathFromUrl = ''
+
+      if (pathname === normalizedBaseRoute || pathname === `${normalizedBaseRoute}/`) {
+        pathFromUrl = ''
+      } else if (pathname.startsWith(`${normalizedBaseRoute}/`)) {
+        pathFromUrl = pathname.substring(`${normalizedBaseRoute}/`.length)
+      }
+
+      pathFromUrl = stripFolderIndexFromPath(pathFromUrl, folderIndexFile)
+
+      if (pathFromUrl !== selectedPathRef.current) {
+        setSelectedPath(pathFromUrl)
+        if (pathFromUrl) {
+          const parentPath = pathFromUrl.includes('/')
+            ? pathFromUrl.substring(0, pathFromUrl.lastIndexOf('/'))
+            : pathFromUrl
+          setExpandedNodes(new Set(getDocAncestorNodeIds(parentPath)))
+        }
+        setTimeout(() => {
+          scrollToContent()
+        }, 150)
+      }
+    }
+
+    window.addEventListener('popstate', handlePopState)
+    return () => window.removeEventListener('popstate', handlePopState)
+  }, [normalizedBaseRoute, folderIndexFile])
+
+  useEffect(() => {
+    if (!isInitialized) {
+      // Kick off the speculative content fetch IN PARALLEL with the structure
+      // fetch — the two endpoints are independent and most landing pages have
+      // a root README (the default folder-index). If the structure ends up
+      // pointing at a different path (e.g. knowledge-base falls back to the
+      // first-folder README because there's no root README), the content
+      // useEffect issues the correct fetch after structure arrives — the
+      // speculative result silently no-ops (the content state update gets
+      // overwritten by the targeted fetch).
+      const speculativeContentPath = cleanInitialPath || folderIndexFile
+      lastFetchedPath.current = speculativeContentPath
+      fetchContent(speculativeContentPath)
+      fetchStructure()
+      setIsInitialized(true)
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [isInitialized])
+
+  useEffect(() => {
+    if (selectedPath === null || selectedPath === undefined) return
+    if (!structure || structure.length === 0) return
+
+    let pathToFetch: string | null = null
+
+    if (selectedPath === '') {
+      pathToFetch = folderIndexFile
+    } else {
+      const node = findDocNodeByPath(selectedPath, structure)
+
+      if (node && node.type === 'folder' && !node.hasReadme) {
+        return
+      }
+
+      pathToFetch = selectedPath
+      if (node && node.type === 'folder' && node.hasReadme) {
+        pathToFetch = `${selectedPath}/${folderIndexFile}`
+      }
+    }
+
+    if (pathToFetch === lastFetchedPath.current) {
+      return
+    }
+
+    if (pathToFetch) {
+      lastFetchedPath.current = pathToFetch
+      fetchContent(pathToFetch)
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [selectedPath, structure, folderIndexFile])
+
+  const fetchStructure = async () => {
+    try {
+      setIsLoadingStructure(true)
+      setError(null)
+
+      const response = await fetch(structureEndpoint)
+
+      if (!response.ok) {
+        throw new Error('Failed to load documentation structure')
+      }
+
+      const result = await response.json()
+
+      if (result.success && result.data) {
+        setStructure(result.data)
+
+        if (cleanInitialPath) {
+          const pathForExpansion = cleanInitialPath.includes('.')
+            ? cleanInitialPath.substring(0, cleanInitialPath.lastIndexOf('/'))
+            : cleanInitialPath
+          if (pathForExpansion) {
+            setExpandedNodes(new Set(getDocAncestorNodeIds(pathForExpansion)))
+          }
+        } else if (result.data.length > 0) {
+          const hasRootReadme = result.data.some(
+            (node: DocNode) => node.type === 'file' && node.path === folderIndexFile
+          )
+
+          if (!hasRootReadme) {
+            const firstNode = result.data[0]
+            if (firstNode.type === 'folder') {
+              setExpandedNodes(new Set([firstNode.id]))
+              if (firstNode.hasReadme) {
+                setSelectedPath(firstNode.path)
+                window.history.replaceState({}, '', `${normalizedBaseRoute}/${firstNode.path}`)
+              }
+            }
+          }
+        }
+      } else {
+        setError('Failed to load documentation structure')
+      }
+    } catch (err) {
+      console.error('Error fetching documentation structure:', err)
+      setError(err instanceof Error ? err.message : 'Failed to load documentation')
+    } finally {
+      setIsLoadingStructure(false)
+    }
+  }
+
+  const fetchContent = async (path: string) => {
+    try {
+      setIsLoadingContent(true)
+      // Don't clear `error` here — if a previous fetch set an error and this
+      // is a stale/speculative call that gets superseded, the guard below
+      // returns early without writing to state. Clearing error here would
+      // briefly flicker the user-visible error message.
+
+      const response = await fetch(`${contentEndpoint}?path=${encodeURIComponent(path)}`)
+
+      // Request-id guard: between awaits, `lastFetchedPath.current` may have
+      // been bumped by a newer fetch (the structure-arrives auto-select issues
+      // a more-targeted fetch while the speculative one is in flight). Bail
+      // BEFORE writing to state — otherwise the late 404 of the speculative
+      // fetch overwrites the targeted fetch's good content with null.
+      if (path !== lastFetchedPath.current) return
+
+      if (!response.ok) {
+        if (response.status === 404) {
+          const result = await response.json().catch(() => ({}))
+          if (path !== lastFetchedPath.current) return
+          // Landing-page silent fallback: when the user lands on the source's
+          // root URL and there's no root `README.md` (knowledge-base case),
+          // the speculative fetch 404s — surface an empty state instead of
+          // an error banner. The structure-arrives auto-select will fire
+          // a targeted fetch for the first-folder README on the next render.
+          if (path === folderIndexFile && selectedPath === '') {
+            setError(null)
+            setContent(null)
+            return
+          }
+          setError(result.error || 'Documentation file not found')
+          setContent(null)
+          return
+        }
+        throw new Error('Failed to load documentation content')
+      }
+
+      const result = await response.json()
+      if (path !== lastFetchedPath.current) return
+      setError(null)
+
+      if (result.success && result.data) {
+        if (result.redirect && result.correctPath !== undefined) {
+          const correctedPath = result.correctPath
+          setSelectedPath(correctedPath)
+          window.history.replaceState({}, '', `${normalizedBaseRoute}/${correctedPath}`)
+          setContent(result.data)
+        } else {
+          setContent(result.data)
+        }
+      } else {
+        setError(result.error || 'Failed to load content')
+        setContent(null)
+      }
+    } catch (err) {
+      if (path !== lastFetchedPath.current) return
+      console.error('Error fetching documentation content:', err)
+      setError(err instanceof Error ? err.message : 'Failed to load content')
+      setContent(null)
+    } finally {
+      // Only clear loading state if THIS fetch is still the active one — a
+      // superseded speculative shouldn't flip the spinner off while the
+      // targeted fetch is still in flight.
+      if (path === lastFetchedPath.current) setIsLoadingContent(false)
+    }
+  }
+
+  const toggleNode = useCallback((nodeId: string) => {
+    setExpandedNodes(prev => {
+      const next = new Set(prev)
+      if (next.has(nodeId)) {
+        next.delete(nodeId)
+      } else {
+        next.add(nodeId)
+      }
+      return next
+    })
+  }, [])
+
+  // Structural minimum the body uses — `id`, `path`, `type`, `hasReadme`.
+  // Widening from `DocNode` lets the navigation components (which carry the
+  // narrower `NavigationNode` row shape) pass their own node back without the
+  // cross-type `as` cast. Both DocNode and NavigationNode satisfy this.
+  const selectNode = useCallback((node: Pick<DocNode, 'id' | 'path' | 'type' | 'hasReadme'>) => {
+    if (node.type === 'folder') {
+      setExpandedNodes(prev => {
+        if (prev.has(node.id)) {
+          const ancestorIds = getDocAncestorNodeIds(node.path)
+          ancestorIds.pop()
+          return new Set(ancestorIds)
+        } else {
+          return new Set(getDocAncestorNodeIds(node.path))
+        }
+      })
+
+      if (node.hasReadme) {
+        lastFetchedPath.current = null
+        setSelectedPath(node.path)
+        window.history.pushState({}, '', `${normalizedBaseRoute}/${node.path}`)
+        setTimeout(() => {
+          scrollToContent()
+        }, 150)
+      } else {
+        setSelectedPath(node.path)
+      }
+    } else {
+      const lastSlash = node.path.lastIndexOf('/')
+      if (lastSlash > 0) {
+        const parentPath = node.path.substring(0, lastSlash)
+        setExpandedNodes(new Set(getDocAncestorNodeIds(parentPath)))
+      }
+
+      lastFetchedPath.current = null
+      setSelectedPath(node.path)
+      window.history.pushState({}, '', `${normalizedBaseRoute}/${node.path}`)
+      setTimeout(() => {
+        scrollToContent()
+      }, 150)
+    }
+  }, [normalizedBaseRoute])
+
+  const navigateToDoc = useCallback((path: string, options?: { expandFolder?: boolean; fromInternalLink?: boolean }) => {
+    const hashIndex = path.indexOf('#')
+    const anchor = hashIndex !== -1 ? path.substring(hashIndex) : ''
+    const cleanPath = path.replace(/\/$/, '').split('#')[0]
+
+    const scrollAfterNav = () => {
+      if (anchor) {
+        setTimeout(() => {
+          const el = document.getElementById(anchor.substring(1))
+          if (el) {
+            scrollElementIntoView(el, { headerOffset: 80 })
+          } else {
+            scrollToContent()
+          }
+        }, 300)
+      } else {
+        setTimeout(() => {
+          scrollToContent()
+        }, 150)
+      }
+    }
+
+    if (options?.expandFolder) {
+      lastFetchedPath.current = null
+      setSelectedPath(cleanPath)
+      window.history.pushState({}, '', `${normalizedBaseRoute}/${cleanPath}${anchor}`)
+
+      const pathParts = cleanPath.split('/')
+      const nodeIdsToExpand: string[] = []
+      let currentPath = ''
+
+      for (const part of pathParts) {
+        currentPath = currentPath ? `${currentPath}-${part}` : part
+        nodeIdsToExpand.push(currentPath.toLowerCase())
+      }
+
+      setExpandedNodes(new Set(nodeIdsToExpand))
+
+      if (options?.fromInternalLink) {
+        scrollAfterNav()
+      }
+
+      setError(null)
+      return
+    }
+
+    const pathForSelection = stripFolderIndexFromPath(cleanPath, folderIndexFile)
+    const urlPath = pathForSelection
+
+    lastFetchedPath.current = null
+    setSelectedPath(pathForSelection)
+    window.history.pushState({}, '', `${normalizedBaseRoute}/${urlPath}${anchor}`)
+
+    if (options?.fromInternalLink) {
+      scrollAfterNav()
+    }
+
+    const pathParts = cleanPath.split('/')
+    const parentIds: string[] = []
+    let currentPath = ''
+    const partsToProcess = cleanPath.includes('.') ? pathParts.slice(0, -1) : pathParts
+
+    for (const part of partsToProcess) {
+      currentPath = currentPath ? `${currentPath}-${part}` : part
+      parentIds.push(currentPath.toLowerCase())
+    }
+
+    if (parentIds.length > 0) {
+      setExpandedNodes(new Set(parentIds))
+    }
+  }, [structure, normalizedBaseRoute, folderIndexFile])
+
+  useEffect(() => {
+    return docNavigation.register({
+      baseRoute: normalizedBaseRoute,
+      findNodeByPath: (path) => {
+        const clean = stripFolderIndexFromPath(path.replace(/\/$/, '').split('#')[0], folderIndexFile)
+        return findDocNodeByPath(clean, structure) ?? null
+      },
+      selectNode,
+    })
+  }, [docNavigation, normalizedBaseRoute, structure, selectNode, folderIndexFile])
+
+  return {
+    structure,
+    selectedPath,
+    setSelectedPath,
+    content,
+    isLoadingStructure,
+    isLoadingContent,
+    error,
+    expandedNodes,
+    toggleNode,
+    selectNode,
+    navigateToDoc,
+    refetch: fetchStructure,
+    setExpandedNodes,
+  }
+}
+
+export type { DocNode, DocContent }

package/src/components/docs/use-scroll-spy.ts

@@ -0,0 +1,93 @@
+"use client"
+
+import { useState, useRef, useCallback, useEffect, useMemo } from "react"
+import { scrollElementIntoView } from "../../utils/scroll-into-view"
+
+// Single source for the sticky-chrome height. Used for BOTH the scroll target
+// offset (where a clicked section lands) AND the active-section detection
+// threshold (where the scroll listener flips highlight). They must match —
+// previously 100 vs 150 caused a 50px window where the indicator jumped to
+// the next section even though that section's top was still below the
+// clicked one's resting offset.
+const SCROLL_OFFSET = 100
+
+interface ScrollSpySection {
+  id: string
+  title?: string
+  level?: number
+}
+
+interface UseScrollSpyReturn {
+  activeSection: string
+  handleSectionClick: (sectionId: string) => void
+}
+
+/**
+ * Shared scroll spy hook for tracking active section based on scroll position.
+ * Used by DocViewer for sticky section navigation.
+ */
+export function useScrollSpy(sections: ScrollSpySection[] | undefined): UseScrollSpyReturn {
+  const [activeSection, setActiveSection] = useState("")
+  const isScrollingFromClick = useRef(false)
+
+  const sectionIds = useMemo(
+    () => sections?.map(s => s.id).join(',') ?? '',
+    [sections]
+  )
+  const stableSections = useRef(sections)
+  if (sectionIds !== (stableSections.current?.map(s => s.id).join(',') ?? '')) {
+    stableSections.current = sections
+  }
+
+  const handleSectionClick = useCallback((sectionId: string) => {
+    const targetElement = document.getElementById(sectionId)
+    if (!targetElement) return
+
+    isScrollingFromClick.current = true
+    setActiveSection(sectionId)
+
+    scrollElementIntoView(targetElement, { headerOffset: SCROLL_OFFSET })
+
+    setTimeout(() => {
+      isScrollingFromClick.current = false
+    }, 800)
+  }, [])
+
+  useEffect(() => {
+    const currentSections = stableSections.current
+    if (!currentSections || currentSections.length === 0) return
+
+    const handleScroll = () => {
+      if (isScrollingFromClick.current) return
+
+      const scrollPosition = window.scrollY + SCROLL_OFFSET
+      let currentSection = currentSections[0]?.id || ""
+
+      for (let i = currentSections.length - 1; i >= 0; i--) {
+        const element = document.getElementById(currentSections[i].id)
+        if (element && scrollPosition >= element.offsetTop) {
+          currentSection = currentSections[i].id
+          break
+        }
+      }
+
+      setActiveSection((prev) => (prev !== currentSection ? currentSection : prev))
+    }
+
+    let scrollTimer: ReturnType<typeof setTimeout>
+    const throttledScroll = () => {
+      clearTimeout(scrollTimer)
+      scrollTimer = setTimeout(handleScroll, 100)
+    }
+
+    window.addEventListener("scroll", throttledScroll)
+    handleScroll()
+
+    return () => {
+      window.removeEventListener("scroll", throttledScroll)
+      clearTimeout(scrollTimer)
+    }
+  }, [sectionIds])
+
+  return { activeSection, handleSectionClick }
+}

package/src/components/embeds/embed-iframe.tsx

@@ -0,0 +1,103 @@
+"use client"
+
+import React, { useState, useCallback, useRef, useEffect } from 'react'
+
+/** Loading skeleton for iframe embeds — matches project skeleton pattern */
+function EmbedLoadingSkeleton({ height }: { height?: string }) {
+  return (
+    <div
+      className="w-full rounded-lg border border-ods-border overflow-hidden bg-ods-skeleton animate-pulse"
+      style={{ height: height || 'calc(100vh - 250px)' }}
+    >
+      <div className="flex flex-col items-center justify-center h-full gap-4">
+        <div className="w-12 h-12 rounded-lg bg-ods-card" />
+        <div className="h-4 w-48 rounded bg-ods-card" />
+        <div className="h-3 w-32 rounded bg-ods-card" />
+      </div>
+    </div>
+  )
+}
+
+export interface EmbedIframeProps {
+  /** The URL to embed */
+  src: string
+  /** Accessible title for the iframe */
+  title: string
+  /** Additional class names for the outer container */
+  className?: string
+  /** Container height (CSS value). Defaults to `calc(100vh - 250px)` */
+  height?: string
+  /** iframe `allow` attribute */
+  allow?: string
+  /** iframe `referrerPolicy` attribute */
+  referrerPolicy?: React.IframeHTMLAttributes<HTMLIFrameElement>['referrerPolicy']
+  /** iframe `loading` attribute */
+  loading?: 'eager' | 'lazy'
+  /** iframe `allowFullScreen` attribute */
+  allowFullScreen?: boolean
+}
+
+/**
+ * Base iframe wrapper with loading skeleton and proper memory cleanup.
+ *
+ * Prevents memory leaks by:
+ * - Using `key={src}` to force full unmount/remount when src changes
+ * - Setting iframe src to about:blank on unmount to release the embedded document
+ * - Resetting loaded state when src changes
+ */
+export function EmbedIframe({
+  src,
+  title,
+  className,
+  height,
+  allow,
+  referrerPolicy,
+  loading,
+  allowFullScreen,
+}: EmbedIframeProps) {
+  const [isLoaded, setIsLoaded] = useState(false)
+  const iframeRef = useRef<HTMLIFrameElement>(null)
+  const handleLoad = useCallback(() => setIsLoaded(true), [])
+
+  useEffect(() => {
+    setIsLoaded(false)
+  }, [src])
+
+  useEffect(() => {
+    const iframe = iframeRef.current
+    return () => {
+      if (iframe) {
+        try {
+          iframe.src = 'about:blank'
+        } catch {
+          // Cross-origin iframes may throw — safe to ignore
+        }
+      }
+    }
+  }, [src])
+
+  const resolvedHeight = height || 'calc(100vh - 250px)'
+
+  return (
+    <>
+      {!isLoaded && <EmbedLoadingSkeleton height={resolvedHeight} />}
+      <div
+        className={`w-full rounded-lg border border-ods-border overflow-hidden ${!isLoaded ? 'h-0 overflow-hidden' : ''} ${className || ''}`}
+        style={isLoaded ? { height: resolvedHeight } : undefined}
+      >
+        <iframe
+          key={src}
+          ref={iframeRef}
+          src={src}
+          className="w-full h-full border-0"
+          title={title}
+          onLoad={handleLoad}
+          allow={allow}
+          referrerPolicy={referrerPolicy}
+          loading={loading}
+          allowFullScreen={allow?.includes('fullscreen') ? undefined : allowFullScreen}
+        />
+      </div>
+    </>
+  )
+}