@flamingo-stack/openframe-frontend-core 0.0.284 → 0.0.285-snapshot.20260618135145

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