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

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/faq-anchor.ts

@@ -0,0 +1,70 @@
+/**
+ * FAQ anchor SSOTs — TWO complementary deep-link kinds on the `/faqs` page,
+ * both rendered straight onto the DOM and recognised by ONE parser. Keeping
+ * the format helpers + parser in one file means the page, the chat RAG
+ * mapper, and any future consumer can't drift on what a hash means.
+ *
+ *   `/faqs#faq-pricing`     → category section header (jump-nav pills,
+ *                             scroll-spy)
+ *   `/faqs#faq-item-42`     → individual question (chat citation chips —
+ *                             auto-expands the row + scrolls to it)
+ *
+ * Reserved namespaces — `faq-item-<digits>` is the item shape; everything
+ * else starting with `faq-` is a section slug. `faqSectionSlug` lowercases
+ * + dash-collapses + dash-trims, so a section name would only collide with
+ * the item shape if it slugified to `faq-item-<digits-only>` (e.g. a
+ * category called "Item 42") — none of the 21 production sections do, and
+ * `parseFaqHash`'s regex is digits-only so future word-suffixed names like
+ * "Item Whatever" (slugifies to `faq-item-whatever`) are also safe.
+ */
+
+/** Stable, URL-safe anchor id for a category. Prefixed with `faq-` so it
+ *  can't collide with other in-page ids, and so a bare numeric/blank
+ *  section still yields a valid id. The helper assumes the caller has
+ *  already verified the section is a non-blank string (matches
+ *  `faq-section.tsx`'s `groupFaqsBySection` precondition). */
+export function faqSectionSlug(section: string): string {
+  return (
+    'faq-' +
+    section
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '')
+  )
+}
+
+/** Stable anchor for an individual FAQ row. Rendered as the row container's
+ *  `id` attribute by `FaqAccordion`; consumed by `FaqSection` (auto-open +
+ *  auto-scroll on mount) AND by the hub's RAG mapper so chat citations
+ *  deep-link to the specific question, not just its category. The id is
+ *  stringified verbatim — the FAQ schema uses integer PKs so `parseFaqHash`'s
+ *  digits-only regex always matches a real row. */
+export function faqItemAnchor(id: number | string): string {
+  return `faq-item-${id}`
+}
+
+/** Discriminated parse of a `/faqs#…` hash. Returns null for an empty,
+ *  missing, or unrecognised hash so callers can early-out without
+ *  scattering string parsing across the file.
+ *
+ *   parseFaqHash('#faq-item-42')   → { kind: 'item',    rawId: '42' }
+ *   parseFaqHash('#faq-pricing')   → { kind: 'section', slug: 'faq-pricing' }
+ *   parseFaqHash('#anything-else') → null
+ *
+ * `rawId` is the matched digit run as a string — the caller compares it
+ * to `String(item.id)` so coercion stays at the comparison site. */
+export type FaqHashTarget =
+  | { kind: 'item';    rawId: string }
+  | { kind: 'section'; slug:  string }
+
+const FAQ_ITEM_HASH_RE = /^faq-item-(\d+)$/
+
+export function parseFaqHash(hash: string | null | undefined): FaqHashTarget | null {
+  if (!hash) return null
+  const trimmed = hash.replace(/^#/, '')
+  if (!trimmed) return null
+  const itemMatch = FAQ_ITEM_HASH_RE.exec(trimmed)
+  if (itemMatch) return { kind: 'item', rawId: itemMatch[1] }
+  if (trimmed.startsWith('faq-')) return { kind: 'section', slug: trimmed }
+  return null
+}

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,
@@ -252,6 +253,13 @@ export {
 // Pure + server-safe (the hub imports it server-side from this barrel).
 export { buildListUrl, canonicalContentRefType } from './list-url'
 
+// FAQ anchor SSOTs — section (`faq-<slug>`) AND item (`faq-item-<id>`)
+// formats plus the parser, all rendered by `FaqSection`/`FaqAccordion`
+// and recognised by the hub's RAG mapper. One algo per kind, one parser,
+// zero drift across page + chat + future consumers.
+export { faqSectionSlug, faqItemAnchor, parseFaqHash } from './faq-anchor'
+export type { FaqHashTarget } from './faq-anchor'
+
 // Content-ref group registry (labels/order/layout per rail type) + list-API
 // response normalizers + the shared suggestion-fetch URL composer — all
 // pure + server-safe; the hub re-exports these from its config/util shims.
@@ -283,3 +291,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/list-url.ts

@@ -70,6 +70,7 @@ const BUILDERS: Record<string, (ids: string[], base: string) => string> = {
   product_release: (ids, b) => `${b}/api/releases?ids=${ids.join(',')}&limit=${ids.length}`,
   customer_interview: (ids, b) => `${b}/api/customer-interviews?ids=${ids.join(',')}&limit=${ids.length}`,
   investor_update: (ids, b) => `${b}/api/investor-updates?ids=${ids.join(',')}&limit=${ids.length}`,
+  faq: (ids, b) => `${b}/api/faqs?ids=${ids.join(',')}&limit=${ids.length}`,
 }
 
 /**

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