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

package/src/types/doc-source.ts

@@ -0,0 +1,88 @@
+/**
+ * Single home for doc-source tree + content types.
+ *
+ * Consumed by every doc-viewer consumer (knowledge base, data room, future
+ * sources). Replaces the per-source `OpenFrameDocNode` / `OpenFrameDocContent`
+ * / `DataRoomDocNode` / `DocNavNode` types that previously lived in the hub.
+ */
+
+/**
+ * A single node in a doc-source tree. The `documentType` discriminator
+ * defaults to `'markdown'` when undefined; rich-content viewers handle
+ * `'pdf' | 'google_sheet' | 'figma' | 'file'`.
+ */
+export interface DocNode {
+  id: string
+  name: string
+  slug: string
+  path: string
+  type: 'file' | 'folder'
+  hasReadme?: boolean
+  /** Per-row sort key — populated by data-room rows, undefined elsewhere. */
+  sortOrder?: number
+  /** Discriminator for the rich renderer. `undefined` is treated as `'markdown'`. */
+  documentType?: 'markdown' | 'pdf' | 'google_sheet' | 'figma' | 'file'
+  children?: DocNode[]
+}
+
+/**
+ * Content payload returned by a doc-source DAL's `getContent` call. Carries
+ * everything any consumer's renderer might need; markdown-only fields and
+ * rich-only fields are both optional.
+ */
+export interface DocContent {
+  content: string
+  sections: Array<{ id: string; title: string; level: number }>
+  path: string
+  /** Defaults to `'markdown'` when undefined. */
+  documentType?: DocNode['documentType']
+  // Markdown-only
+  brokenLinks?: string[]
+  // Rich-content (data-room) — optional
+  fileUrl?: string
+  externalUrl?: string
+  mimeType?: string
+  fileName?: string
+  fileSize?: number
+  /** ISO timestamps for SEO `datePublished` / `dateModified` — DAL populates
+   *  from the underlying row's sync/update timestamp. Undefined when unknown. */
+  publishedAt?: string
+  updatedAt?: string
+}
+
+/**
+ * Doc-source data-access contract. Each doc source's hub-side DAL conforms
+ * to this. Generic over the Supabase-client type so the lib doesn't pull in
+ * `@supabase/supabase-js`; hub callers tighten `Client` to `SupabaseClient`.
+ */
+export interface DocSourceDal<Client = unknown> {
+  getStructure(client: Client): Promise<DocNode[]>
+  getContent(client: Client, path: string): Promise<DocContent | null>
+}
+
+/**
+ * Doc-source registry id. The lib's `<DocViewer>` is generic over this union
+ * — the hub's `DOC_SOURCES` registry defines the actual ids. Listed here as a
+ * type-only union so the lib can flow the id into `DocRenderHandlers.sourceId`
+ * without callers having to cast `string` → `'openframe-docs' | 'data-room-docs'`.
+ *
+ * Adding a new source = add the id here AND register it in the hub. The lib
+ * never reaches into the registry — this is purely a type-narrowing handle.
+ */
+export type DocSourceId = 'openframe-docs' | 'data-room-docs'
+
+/**
+ * Handlers the viewer passes to a consumer's `renderContent` callback.
+ * The page shell wires `renderContent` directly — no `DocContentRenderer`
+ * interface layer between the viewer and the consumer's render logic.
+ */
+export interface DocRenderHandlers {
+  onInternalLinkClick: (
+    path: string,
+    options?: { expandFolder?: boolean; fromInternalLink?: boolean },
+  ) => void
+  currentPath: string
+  /** Registry source id (e.g. `'openframe-docs'`, `'data-room-docs'`) — used by
+   *  the consumer's `/api/resolve-link` POST to disambiguate the doc source. */
+  sourceId: DocSourceId
+}

package/src/types/index.ts

@@ -3,6 +3,10 @@
 
 // Core platform types
 export * from './announcement'
+// Doc-source viewer types — DocNode / DocContent / DocSourceDal /
+// DocRenderHandlers. Consumed by knowledge-base, data-room, and future
+// doc-source viewers.
+export * from './doc-source'
 export type { Category, CategoryCardProps, RealCategoryCardProps } from './categories'
 export * from './category'
 export * from './media'

package/src/utils/doc-path-utils.ts

@@ -0,0 +1,47 @@
+/**
+ * Shared document path utilities.
+ * Single source of truth for path/slug operations used by all doc-source viewers
+ * (knowledge base, data room, future).
+ */
+
+import { DEFAULT_FOLDER_INDEX_FILE } from './doc-tree-nav'
+
+/**
+ * Convert a document name to a URL-safe path slug.
+ * Used when creating, moving, or renaming documents.
+ * e.g., "Investor Thesis" → "investor-thesis"
+ */
+export function toDocSlug(name: string): string {
+  return name.trim().toLowerCase().replace(/\s+/g, '-')
+}
+
+/**
+ * Convert a full document path to a DOM-safe node ID.
+ * Used for tree node IDs and sidebar expand/collapse state.
+ * e.g., "legal/cap-table/safe.md" → "legal-cap-table-safe.md"
+ */
+export function pathToNodeId(path: string): string {
+  return path.replace(/[\/\s]/g, '-').toLowerCase()
+}
+
+/**
+ * Normalize a raw URL path from a route handler.
+ * Strips folder-index suffixes (default README.md) and lowercases segments.
+ * Used by both data-room and knowledge-base [...path] route handlers.
+ */
+export function normalizeDocPath(
+  segments: string[],
+  folderIndexFile: string = DEFAULT_FOLDER_INDEX_FILE,
+): string {
+  // Lowercase BOTH sides BEFORE comparison so paths from URL segments
+  // (`readme.md`) and the canonical folder-index constant (`README.md`)
+  // strip uniformly. Lowercasing only at the end (the previous shape) left
+  // lowercase URL inputs unstripped → bogus content lookups.
+  const lowerPath = (segments?.join('/') || '').toLowerCase()
+  const lowerIndex = folderIndexFile.toLowerCase()
+
+  const suffix = `/${lowerIndex}`
+  if (lowerPath.endsWith(suffix)) return lowerPath.slice(0, -suffix.length)
+  if (lowerPath === lowerIndex) return ''
+  return lowerPath
+}

package/src/utils/doc-tree-nav.ts

@@ -0,0 +1,111 @@
+/**
+ * Pure helpers for doc-source tree navigation — shared by client hook and RSC SSR.
+ * README convention (folder-index file) is configurable but defaults to 'README.md'.
+ */
+
+import type { DocNode } from '../types/doc-source'
+
+/**
+ * Canonical folder-index filename. Single SSOT consumed by `doc-tree-nav`
+ * pure helpers, `useDocumentTree` (default config), `DocSeoContent` (fallback
+ * fetch path), and `multi-level-navigation`'s visual-selection logic. Stays
+ * in canonical case here; consumers that do case-insensitive comparison
+ * (the navigation) lowercase locally.
+ */
+export const DEFAULT_FOLDER_INDEX_FILE = 'README.md'
+
+/** @deprecated Re-exported under the new name; remove after consumers migrate. */
+const DEFAULT_FOLDER_INDEX = DEFAULT_FOLDER_INDEX_FILE
+
+/**
+ * Strip the folder-index filename from a path, returning the folder path.
+ * For default 'README.md': 'folder/README.md' → 'folder', 'README.md' → '', 'folder/file.md' → 'folder/file.md'
+ */
+export function stripFolderIndexFromPath(
+  path: string,
+  folderIndexFile: string = DEFAULT_FOLDER_INDEX,
+): string {
+  const suffix = `/${folderIndexFile}`
+  if (path.endsWith(suffix)) return path.slice(0, -suffix.length)
+  if (path === folderIndexFile) return ''
+  return path
+}
+
+export function findDocNodeByPath(path: string, nodes: DocNode[]): DocNode | null {
+  for (const node of nodes) {
+    if (node.path === path) return node
+    if (node.children) {
+      const found = findDocNodeByPath(path, node.children)
+      if (found) return found
+    }
+  }
+  return null
+}
+
+/**
+ * Given a node path like "folder1/subfolder2", return DOM-style node IDs for each segment
+ * (accordion sidebar — matches use-document-tree).
+ */
+export function getDocAncestorNodeIds(nodePath: string): string[] {
+  const parts = nodePath.split('/')
+  const ids: string[] = []
+  let current = ''
+  for (const part of parts) {
+    current = current ? `${current}-${part}` : part
+    ids.push(current.toLowerCase())
+  }
+  return ids
+}
+
+/**
+ * Resolve which storage path to load (matches use-document-tree content effect).
+ */
+export function resolveContentFetchPath(
+  selectedPath: string,
+  structure: DocNode[],
+  folderIndexFile: string = DEFAULT_FOLDER_INDEX,
+): string | null {
+  if (selectedPath === '') {
+    return folderIndexFile
+  }
+  const node = findDocNodeByPath(selectedPath, structure)
+  if (node && node.type === 'folder' && !node.hasReadme) {
+    return null
+  }
+  let pathToFetch = selectedPath
+  if (node && node.type === 'folder' && node.hasReadme) {
+    pathToFetch = `${selectedPath}/${folderIndexFile}`
+  }
+  return pathToFetch
+}
+
+export function getInitialExpandedNodeIds(cleanInitialPath: string): string[] {
+  if (!cleanInitialPath) return []
+  const pathForExpansion = cleanInitialPath.includes('.')
+    ? cleanInitialPath.substring(0, cleanInitialPath.lastIndexOf('/'))
+    : cleanInitialPath
+  if (!pathForExpansion) return []
+  return getDocAncestorNodeIds(pathForExpansion)
+}
+
+/**
+ * When a doc source's root has no top-level folder-index file, navigate to the first
+ * folder that does. Matches the historical knowledge-base default.
+ */
+export function getDocSourceDefaultPath(
+  structure: DocNode[],
+  folderIndexFile: string = DEFAULT_FOLDER_INDEX,
+): string | null {
+  if (!structure.length) return null
+  const hasRootIndex = structure.some(
+    (node) => node.type === 'file' && node.path === folderIndexFile
+  )
+  if (hasRootIndex) return null
+  // Scan ALL root nodes for the first folder with a README — not just
+  // structure[0]. Otherwise a leading non-folder root (file / folder without
+  // README) silently returns null even when a later root folder has one.
+  const firstFolderWithReadme = structure.find(
+    (node) => node.type === 'folder' && node.hasReadme && !!node.path,
+  )
+  return firstFolderWithReadme?.path ?? null
+}

package/src/utils/embed-url-converters.ts

@@ -0,0 +1,77 @@
+/**
+ * Shared utilities for converting external service URLs to embeddable formats.
+ * Used by lib's embed components and the hub's admin document editor.
+ */
+
+export function toGoogleSheetsEmbedUrl(url: string): string {
+  if (url.includes('/htmlembed')) return url
+
+  const match = url.match(/\/spreadsheets\/d\/([a-zA-Z0-9-_]+)/)
+  if (!match) return url
+
+  const gidMatch = url.match(/[#?&]gid=(\d+)/)
+  const gid = gidMatch ? gidMatch[1] : '0'
+
+  return `https://docs.google.com/spreadsheets/d/${match[1]}/htmlembed?widget=true&chrome=false&headers=false&gid=${gid}`
+}
+
+export function toGoogleSheetsOriginalUrl(url: string): string {
+  const match = url.match(/\/spreadsheets\/d\/([a-zA-Z0-9-_]+)/)
+  if (!match) return url
+
+  const gidMatch = url.match(/[#?&]gid=(\d+)/)
+  const gid = gidMatch ? gidMatch[1] : '0'
+
+  return `https://docs.google.com/spreadsheets/d/${match[1]}/edit#gid=${gid}`
+}
+
+/**
+ * Convert a Figma URL to an embeddable URL.
+ * Slides/deck URLs map to `deck` (present) by default; `slidesView: 'browse'` switches to `slides` (browse).
+ */
+export function toFigmaEmbedUrl(
+  url: string,
+  opts?: { slidesView?: 'present' | 'browse' }
+): string {
+  if (url.includes('embed.figma.com')) return url
+  if (url.includes('figma.com/embed')) return url
+
+  const match = url.match(
+    /figma\.com\/(design|file|proto|board|slides|deck)\/([a-zA-Z0-9]+)(?:\/([^?]*))?(\?.*)?$/
+  )
+
+  if (match) {
+    const [, urlType, fileKey, titleSlug, queryString] = match
+    const isSlides = urlType === 'slides' || urlType === 'deck'
+    const embedType =
+      urlType === 'proto' ? 'proto'
+      : isSlides ? (opts?.slidesView === 'browse' ? 'slides' : 'deck')
+      : 'design'
+    const pathSuffix = titleSlug ? `/${titleSlug}` : ''
+
+    const params = new URLSearchParams(queryString?.replace(/^\?/, '') || '')
+    if (!params.has('embed-host')) {
+      params.set('embed-host', 'flamingo')
+    }
+    const clientId = process.env.NEXT_PUBLIC_FIGMA_CLIENT_ID
+    if (clientId && !params.has('client-id')) {
+      params.set('client-id', clientId)
+    }
+
+    return `https://embed.figma.com/${embedType}/${fileKey}${pathSuffix}?${params.toString()}`
+  }
+
+  return `https://www.figma.com/embed?embed-host=flamingo&url=${encodeURIComponent(url)}`
+}
+
+export function isFigmaSlidesUrl(url: string): boolean {
+  if (!url) return false
+  return /(?:www\.|embed\.)?figma\.com\/(?:slides|deck)\/[a-zA-Z0-9]+/.test(url)
+}
+
+export function toFigmaOriginalUrl(url: string): string {
+  if (url.includes('embed.figma.com')) {
+    return url.replace('embed.figma.com', 'www.figma.com').replace(/\?.*$/, '')
+  }
+  return url.replace(/\?.*$/, '')
+}

package/src/utils/format.ts

@@ -81,6 +81,22 @@ export function formatBytesShort(bytes: number): string {
   return `${parseFloat((bytes / Math.pow(k, i)).toFixed(2))} ${sizes[i]}`
 }
 
+/**
+ * File-size formatter (1 decimal place, `'B'` unit, caps at `GB`).
+ * Hub historical semantics — distinct from `formatBytesShort` (2dp) and
+ * `formatBytes` (2dp / `'Bytes'`). Lifted from the hub during the doc-viewer
+ * unification so all upload UIs, publication cards, and data-room file-size
+ * displays render the same way.
+ * @example formatFileSize(0) → "0 B"; formatFileSize(1500) → "1.5 KB"
+ */
+export 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]}`
+}
+
 /**
  * Format large numbers to abbreviated form (K, M, B) with no decimal points
  * @param num - The number to format

package/src/utils/index.ts

@@ -102,6 +102,7 @@ export {
   formatWholeDollars,
   formatLegalDate,
   formatBytesShort,
+  formatFileSize,
   formatDateTimeAt,
   formatDurationFromMs,
   type MetricFormat,
@@ -283,3 +284,13 @@ export {
 // decision fn the lib forms feed. Also exported via the granular subpath
 // `./utils/humanity-signals` for server-only consumers.
 export * from './humanity-signals'
+
+// Doc-source viewer utilities (path parsing, tree building, section extraction,
+// embed-URL conversion) — single home for all doc-viewer pure helpers across
+// hub + lib consumers (knowledge-base, data-room, and future sources).
+export * from './doc-path-utils'
+export * from './doc-tree-nav'
+export * from './tree-builder'
+export * from './markdown-section-extractor'
+export * from './markdown-to-plain'
+export * from './embed-url-converters'

package/src/utils/markdown-section-extractor.ts

@@ -0,0 +1,106 @@
+/**
+ * Shared markdown section extractor
+ * Extracts heading sections from markdown content for navigation.
+ */
+
+import { stripInlineMarkdown } from './markdown-to-plain'
+
+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
+}
+
+const DEFAULT_OPTIONS: Required<ExtractSectionsOptions> = {
+  maxLevel: 2,
+  removeEmojis: true,
+  handleDuplicateIds: true,
+  stripFormattingMarkers: true,
+  skipCodeAndYamlBlocks: true,
+}
+
+export function extractSections(
+  markdown: string,
+  options: ExtractSectionsOptions = {},
+): MarkdownSection[] {
+  const opts = { ...DEFAULT_OPTIONS, ...options }
+  const sections: MarkdownSection[] = []
+  const lines = markdown.split('\n')
+  const idCounts: Record<string, number> = {}
+
+  let inCodeBlock = false
+  let inYamlBlock = false
+
+  for (const line of lines) {
+    if (opts.skipCodeAndYamlBlocks) {
+      if (line.startsWith('```')) {
+        inCodeBlock = !inCodeBlock
+        continue
+      }
+      if (line === '---') {
+        inYamlBlock = !inYamlBlock
+        continue
+      }
+      if (inCodeBlock || inYamlBlock) continue
+    }
+
+    const pattern = new RegExp(`^(#{1,${opts.maxLevel}})\\s+(.+)`)
+    const match = line.match(pattern)
+    if (!match) continue
+
+    const level = match[1].length
+    if (level > opts.maxLevel) continue
+
+    let title = match[2].trim()
+
+    if (opts.stripFormattingMarkers) {
+      title = stripInlineMarkdown(title).trim()
+    }
+
+    let baseId = title
+
+    if (opts.removeEmojis) {
+      baseId = baseId
+        .replace(
+          /[\u{1F300}-\u{1F9FF}]|[\u{2600}-\u{26FF}]|[\u{2700}-\u{27BF}]/gu,
+          '',
+        )
+        .trim()
+    }
+
+    baseId = baseId
+      .toLowerCase()
+      .replace(/[^\w\s-]/g, '')
+      .replace(/\s+/g, '-')
+      .replace(/^-+|-+$/g, '')
+
+    const cleanId = baseId || `section-${sections.length + 1}`
+
+    let id = cleanId
+    if (opts.handleDuplicateIds) {
+      if (idCounts[cleanId]) {
+        idCounts[cleanId]++
+        id = `${cleanId}-${idCounts[cleanId]}`
+      } else {
+        idCounts[cleanId] = 1
+      }
+    }
+
+    sections.push({ id, title, level })
+  }
+
+  return sections
+}

package/src/utils/markdown-to-plain.ts

@@ -0,0 +1,69 @@
+/**
+ * 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 function stripInlineMarkdown(s: string): string {
+  return s
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')   // [text](url) → text
+    .replace(/\*\*([^*]+)\*\*/g, '$1')         // **bold** → bold
+    .replace(/\*([^*]+)\*/g, '$1')             // *italic* → italic
+    .replace(/`([^`]+)`/g, '$1')               // `inline code` → inline code
+}
+
+export function markdownToPlainText(
+  markdown: string,
+  options: MarkdownToPlainOptions = {},
+): string {
+  const { mode = 'article', maxChars } = options
+
+  let out = markdown
+    // Fenced code blocks — must run BEFORE inline strippers (otherwise the
+    // backtick-grave strip below grazes them).
+    .replace(/```[\s\S]*?```/g, '')
+    // Images — `![alt](src)` → empty (we drop them entirely in plain text).
+    .replace(/!\[[^\]]*\]\([^)]+\)/g, '')
+
+  out = stripInlineMarkdown(out)
+    // Heading markers (any depth).
+    .replace(/^#+\s*/gm, '')
+    // List bullets at start-of-line.
+    .replace(/^\s*[-*+]\s+/gm, '')
+
+  if (mode === 'preview') {
+    out = out.replace(/\s+/g, ' ').trim()
+  } else {
+    out = out.replace(/\n{3,}/g, '\n\n').trim()
+  }
+
+  if (maxChars != null && out.length > maxChars) {
+    out = out.slice(0, maxChars)
+  }
+  return out
+}

package/src/utils/tree-builder.ts

@@ -0,0 +1,114 @@
+// =============================================================================
+// Shared Document Tree Builder
+// =============================================================================
+// Generic 3-pass algorithm for building hierarchical trees from flat records.
+// Used by all doc-source DALs (openframe-docs, data-room-docs, future).
+
+/**
+ * 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 function formatDocName(name: string): string {
+  let displayName = name
+  if (displayName.endsWith('.md')) {
+    displayName = displayName.slice(0, -3)
+  }
+  if (displayName.toLowerCase() === 'readme') {
+    return 'README'
+  }
+  return displayName.charAt(0).toUpperCase() + displayName.slice(1).replace(/-/g, ' ')
+}
+
+/**
+ * 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 function sortTreeChildren<TNode extends TreeNodeBase>(nodes: TNode[]): TNode[] {
+  nodes.sort((a, b) => {
+    const aIsReadme = a.name.toLowerCase() === 'readme' || a.name.toLowerCase() === 'readme.md'
+    const bIsReadme = b.name.toLowerCase() === 'readme' || b.name.toLowerCase() === 'readme.md'
+    if (aIsReadme && !bIsReadme) return -1
+    if (!aIsReadme && bIsReadme) return 1
+
+    if (a.type === 'folder' && b.type !== 'folder') return -1
+    if (a.type !== 'folder' && b.type === 'folder') return 1
+
+    const aOrder = a.sortOrder ?? Infinity
+    const bOrder = b.sortOrder ?? Infinity
+    if (aOrder !== bOrder) return aOrder - bOrder
+
+    return a.name.localeCompare(b.name, undefined, { sensitivity: 'base' })
+  })
+
+  for (const node of nodes) {
+    if (node.type === 'folder' && node.children) {
+      node.children = sortTreeChildren(node.children as TNode[])
+    }
+  }
+
+  return nodes
+}
+
+/**
+ * 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 function buildDocumentTree<TNode extends TreeNodeBase, TDoc>(
+  docs: TDoc[],
+  mapFn: (doc: TDoc) => TNode,
+  getParentPath: (doc: TDoc) => string | null,
+  getPath: (doc: TDoc) => string
+): TNode[] {
+  const nodeMap = new Map<string, TNode>()
+  const rootNodes: TNode[] = []
+
+  for (const doc of docs) {
+    const node = mapFn(doc)
+    nodeMap.set(getPath(doc), node)
+  }
+
+  for (const doc of docs) {
+    const node = nodeMap.get(getPath(doc))!
+    let resolvedParentPath = getParentPath(doc)
+
+    if (!resolvedParentPath) {
+      const nodePath = getPath(doc)
+      const lastSlash = nodePath.lastIndexOf('/')
+      if (lastSlash > 0) {
+        resolvedParentPath = nodePath.substring(0, lastSlash)
+      }
+    }
+
+    if (resolvedParentPath) {
+      const parent = nodeMap.get(resolvedParentPath)
+      if (parent) {
+        // Lazily initialize `children` so callers whose `mapFn` doesn't
+        // pre-seed it still get a proper tree (previously a missing
+        // `parent.children` silently flattened the child to the root).
+        if (!parent.children) parent.children = []
+        ;(parent.children as TNode[]).push(node)
+      } else {
+        rootNodes.push(node)
+      }
+    } else {
+      rootNodes.push(node)
+    }
+  }
+
+  return sortTreeChildren(rootNodes)
+}