@flamingo-stack/openframe-frontend-core 0.0.285 → 0.0.286-snapshot.20260618154650

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

@@ -0,0 +1,358 @@
+"use client"
+
+import { ChevronRight, ChevronDown, ChevronUp, FileText, Folder, FolderOpen } from 'lucide-react'
+import { cn } from '../../utils/cn'
+import { DEFAULT_FOLDER_INDEX_FILE as CANONICAL_FOLDER_INDEX_FILE } from '../../utils/doc-tree-nav'
+
+export interface NavigationNode {
+  id: string
+  name: string
+  path: string
+  type: 'file' | 'folder'
+  hasReadme?: boolean
+  children?: NavigationNode[]
+  slug?: string
+  // Mirror DocNode's extra optional fields so a DocNode tree is structurally
+  // assignable to NavigationNode[] without an `as` cast. NavigationNode
+  // intentionally never reads these — they're carried for type-compat only.
+  documentType?: 'markdown' | 'pdf' | 'google_sheet' | 'figma' | 'file'
+  sortOrder?: number
+}
+
+interface MultiLevelNavigationProps {
+  nodes: NavigationNode[]
+  selectedPath: string
+  expandedNodes: Set<string>
+  onNodeClick: (node: NavigationNode) => void
+  onToggleExpand?: (nodeId: string) => void
+  isLoading?: boolean
+  className?: string
+  /** Folder-index filename (default `'README.md'`, case-insensitive). When the
+   *  selectedPath is a folder with this file, the visual ribbon moves to the
+   *  child file. */
+  folderIndexFile?: string
+}
+
+// SSOT lives in `doc-tree-nav` (canonical case `'README.md'`). The visual
+// comparator below lowercases both sides, so re-exporting the canonical
+// constant under the same local name preserves call-site syntax without
+// drifting from the SSOT.
+const DEFAULT_FOLDER_INDEX_FILE = CANONICAL_FOLDER_INDEX_FILE
+
+/**
+ * Compute the visual "selected" state for a navigation node.
+ *
+ * Folder-with-README convention: when `selectedPath` is a folder that has a
+ * README, the FOLDER doesn't get the ribbon — its README child does. The folder
+ * is just a container; the README is the actual document being viewed.
+ *
+ * Mirror case: a README file whose parent folder is the `selectedPath` gets the
+ * visual selection ribbon (implicit). This handles both the auto-select-first-
+ * folder landing path AND the user-clicks-folder case.
+ */
+function isNodeVisuallySelected(
+  node: NavigationNode,
+  selectedPath: string,
+  folderIndexFile: string = DEFAULT_FOLDER_INDEX_FILE,
+): boolean {
+  const FOLDER_INDEX_FILE = folderIndexFile.toLowerCase()
+  // Path comparisons keyed on `node.path` (raw, includes `.md`). Do NOT use
+  // `node.name` — the tree-builder runs it through `formatDocName` which strips
+  // the `.md` extension, so `node.name.toLowerCase() === 'readme.md'` is always
+  // false.
+  if (selectedPath === node.path) {
+    // Explicit match — but folder-with-README defers to its README child.
+    return !(node.type === 'folder' && node.hasReadme)
+  }
+  if (node.type !== 'file') return false
+  const pathLower = node.path.toLowerCase()
+  // Implicit: README child whose parent folder is the selectedPath.
+  if (
+    selectedPath !== '' &&
+    pathLower === `${selectedPath.toLowerCase()}/${FOLDER_INDEX_FILE}`
+  ) {
+    return true
+  }
+  // Implicit: ROOT README on the landing page (selectedPath === '' means
+  // "no explicit doc selected" — the viewer falls back to the root folder-
+  // index file, so that file IS the active document).
+  if (selectedPath === '' && pathLower === FOLDER_INDEX_FILE) {
+    return true
+  }
+  return false
+}
+
+export function MultiLevelNavigation({
+  nodes,
+  selectedPath,
+  expandedNodes,
+  onNodeClick,
+  onToggleExpand,
+  isLoading,
+  className,
+  folderIndexFile = DEFAULT_FOLDER_INDEX_FILE,
+}: MultiLevelNavigationProps) {
+  if (isLoading) {
+    return (
+      <div className={cn("space-y-2", className)}>
+        {[1, 2, 3, 4].map((i) => (
+          <div key={i} className="p-3 bg-ods-skeleton rounded-lg animate-pulse h-12" />
+        ))}
+      </div>
+    )
+  }
+
+  return (
+    <div className={cn("space-y-2", className)} role="list" aria-label="Navigation list">
+      {nodes.map(node => (
+        <NavigationItem
+          key={node.id}
+          node={node}
+          selectedPath={selectedPath}
+          expandedNodes={expandedNodes}
+          onNodeClick={onNodeClick}
+          onToggleExpand={onToggleExpand}
+          level={0}
+          folderIndexFile={folderIndexFile}
+        />
+      ))}
+    </div>
+  )
+}
+
+interface NavigationItemProps {
+  node: NavigationNode
+  selectedPath: string
+  expandedNodes: Set<string>
+  onNodeClick: (node: NavigationNode) => void
+  onToggleExpand?: (nodeId: string) => void
+  level: number
+  folderIndexFile: string
+}
+
+function NavigationItem({
+  node,
+  selectedPath,
+  expandedNodes,
+  onNodeClick,
+  onToggleExpand,
+  level,
+  folderIndexFile,
+}: NavigationItemProps) {
+  const isExpanded = expandedNodes.has(node.id)
+  const isSelected = isNodeVisuallySelected(node, selectedPath, folderIndexFile)
+  const hasChildren = node.children && node.children.length > 0
+
+  return (
+    <div className="space-y-1" role="listitem">
+      <div className={cn("px-2", level > 0 && "ml-4")}>
+        <div
+          className={cn(
+            "w-full rounded-lg transition-all duration-150 border relative",
+            isSelected
+              ? "bg-ods-border border-ods-border"
+              : "bg-ods-card border-ods-border"
+          )}
+        >
+          <div className="flex items-center relative">
+            <button
+              className={cn(
+                "w-full flex items-center h-12 px-2 rounded-lg text-[16px] font-medium font-['DM_Sans'] transition-all duration-150 leading-[1.33em] text-ods-text-primary",
+                !isSelected && "hover:bg-ods-bg-secondary",
+                hasChildren && "pr-12"
+              )}
+              onClick={() => onNodeClick(node)}
+              aria-label={`${isSelected ? 'Selected' : 'Select'} ${node.name}`}
+            >
+              <span className="flex-shrink-0 mr-2">
+                {node.type === 'folder' ? (
+                  isExpanded ? <FolderOpen className="h-4 w-4" /> : <Folder className="h-4 w-4" />
+                ) : (
+                  <FileText className="h-4 w-4" />
+                )}
+              </span>
+              <span className="text-left truncate flex-1 min-w-0">
+                {node.name.endsWith('.md') ? node.name.replace('.md', '') : node.name}
+              </span>
+              {node.type === 'folder' && node.hasReadme && (
+                <span className="text-[10px] bg-ods-bg-secondary text-ods-text-tertiary px-1.5 py-0.5 rounded mr-2">
+                  README
+                </span>
+              )}
+            </button>
+
+            {hasChildren && (
+              <button
+                className="absolute right-0 top-0 flex items-center justify-center w-12 h-12 text-ods-text-secondary hover:text-ods-text-primary transition-colors duration-150"
+                onClick={(e) => {
+                  e.stopPropagation()
+                  if (onToggleExpand) {
+                    onToggleExpand(node.id)
+                  } else {
+                    onNodeClick(node)
+                  }
+                }}
+                aria-label={`${isExpanded ? 'Collapse' : 'Expand'} ${node.name}`}
+              >
+                {isExpanded ? <ChevronUp className="h-4 w-4" /> : <ChevronDown className="h-4 w-4" />}
+              </button>
+            )}
+          </div>
+
+          {isSelected && (
+            <div className="absolute right-0 top-1/2 -translate-y-1/2 w-1 h-[calc(100%-8px)] bg-ods-accent rounded-l" />
+          )}
+        </div>
+      </div>
+
+      {hasChildren && isExpanded && (
+        <div className="space-y-1">
+          {node.children!.map(child => (
+            <NavigationItem
+              key={child.id}
+              node={child}
+              selectedPath={selectedPath}
+              expandedNodes={expandedNodes}
+              onNodeClick={onNodeClick}
+              onToggleExpand={onToggleExpand}
+              level={level + 1}
+              folderIndexFile={folderIndexFile}
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}
+
+export function MobileNavigationDropdown({
+  nodes,
+  selectedPath,
+  expandedNodes,
+  onNodeClick,
+  onToggleExpand,
+  isLoading,
+  className,
+  folderIndexFile = DEFAULT_FOLDER_INDEX_FILE,
+}: MultiLevelNavigationProps) {
+  if (isLoading) {
+    return (
+      <div className={cn("space-y-2", className)}>
+        {[1, 2, 3].map((i) => (
+          <div key={i} className="p-3 bg-ods-skeleton rounded-lg animate-pulse h-10" />
+        ))}
+      </div>
+    )
+  }
+
+  return (
+    <div className={cn("space-y-2", className)}>
+      {nodes.map(node => (
+        <MobileNavigationItem
+          key={node.id}
+          node={node}
+          selectedPath={selectedPath}
+          expandedNodes={expandedNodes}
+          onNodeClick={onNodeClick}
+          onToggleExpand={onToggleExpand}
+          level={0}
+          folderIndexFile={folderIndexFile}
+        />
+      ))}
+    </div>
+  )
+}
+
+function MobileNavigationItem({
+  node,
+  selectedPath,
+  expandedNodes,
+  onNodeClick,
+  onToggleExpand,
+  level,
+  folderIndexFile,
+}: NavigationItemProps) {
+  const isExpanded = expandedNodes.has(node.id)
+  const isSelected = isNodeVisuallySelected(node, selectedPath, folderIndexFile)
+  const hasChildren = node.children && node.children.length > 0
+
+  return (
+    <div className="space-y-1">
+      <div className={cn("px-2", level > 0 && "ml-3")}>
+        <div
+          className={cn(
+            "w-full rounded-lg transition-all duration-150 border relative",
+            isSelected
+              ? "bg-ods-border border-ods-border"
+              : "bg-ods-card border-ods-border"
+          )}
+        >
+          <div className="flex items-center relative">
+            <button
+              className={cn(
+                "w-full flex items-center h-11 px-2 rounded-lg text-[15px] font-medium font-['DM_Sans'] transition-all duration-150 leading-[1.33em] text-ods-text-primary",
+                !isSelected && "hover:bg-ods-bg-secondary",
+                hasChildren && "pr-11"
+              )}
+              onClick={() => onNodeClick(node)}
+            >
+              <span className="flex-shrink-0 mr-2">
+                {node.type === 'folder' ? (
+                  isExpanded ? <FolderOpen className="h-4 w-4" /> : <Folder className="h-4 w-4" />
+                ) : (
+                  <FileText className="h-4 w-4" />
+                )}
+              </span>
+              <span className="text-left truncate flex-1 min-w-0 text-sm">
+                {node.name.endsWith('.md') ? node.name.replace('.md', '') : node.name}
+              </span>
+              {node.type === 'folder' && node.hasReadme && (
+                <span className="text-[10px] bg-ods-bg-secondary text-ods-text-tertiary px-1.5 py-0.5 rounded mr-2">
+                  README
+                </span>
+              )}
+            </button>
+
+            {hasChildren && (
+              <button
+                className="absolute right-0 top-0 flex items-center justify-center w-11 h-11 text-ods-text-secondary hover:text-ods-text-primary transition-colors duration-150"
+                onClick={(e) => {
+                  e.stopPropagation()
+                  if (onToggleExpand) {
+                    onToggleExpand(node.id)
+                  } else {
+                    onNodeClick(node)
+                  }
+                }}
+                aria-label={`${isExpanded ? 'Collapse' : 'Expand'} ${node.name}`}
+              >
+                {isExpanded ? <ChevronUp className="h-3.5 w-3.5" /> : <ChevronDown className="h-3.5 w-3.5" />}
+              </button>
+            )}
+          </div>
+
+          {isSelected && (
+            <div className="absolute right-0 top-1/2 -translate-y-1/2 w-1 h-[calc(100%-8px)] bg-ods-accent rounded-l" />
+          )}
+        </div>
+      </div>
+
+      {hasChildren && isExpanded && (
+        <div className="space-y-1">
+          {node.children!.map(child => (
+            <MobileNavigationItem
+              key={child.id}
+              node={child}
+              selectedPath={selectedPath}
+              expandedNodes={expandedNodes}
+              onNodeClick={onNodeClick}
+              onToggleExpand={onToggleExpand}
+              level={level + 1}
+              folderIndexFile={folderIndexFile}
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}

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/types/marketing.ts

@@ -347,6 +347,7 @@ export type ContentSourceType =
   | 'investor_update'     // Investor updates
   | 'onboarding_guide'    // Onboarding guides (lives on openframe platform)
   | 'what_i_shipped'      // What I Shipped employee check-ins (lives on people-hub)
+  | 'faq'                 // FAQ Q&A pair (single-page /faqs index; deep-link by category anchor)
   | 'from_scratch';
 
 export type URLInjectionPreference = 'none' | 'in_post' | 'as_comment';

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
+}