@flamingo-stack/openframe-frontend-core 0.0.215 → 0.0.216

package/src/components/shared/doc-search/format-relative-path.ts

@@ -0,0 +1,17 @@
+/**
+ * Format a full document path as a breadcrumb trail.
+ * Shows parent folders only (excludes the last segment / filename).
+ *
+ * @example
+ *   formatRelativePath('openframe-oss-tenant/architecture/api-controllers.md')
+ *   // → 'Openframe oss tenant / Architecture'
+ */
+export function formatRelativePath(fullPath: string): string {
+  if (!fullPath) return ''
+  const segments = fullPath.replace(/\.md$/, '').split('/')
+  // Show only parent path (exclude the filename itself since the title already shows it)
+  const parentSegments = segments.length > 1 ? segments.slice(0, -1) : segments
+  return parentSegments
+    .map((seg) => seg.charAt(0).toUpperCase() + seg.slice(1).replace(/-/g, ' '))
+    .join(' / ')
+}

package/src/components/shared/doc-search/index.ts

@@ -0,0 +1,24 @@
+export {
+  DocSearchBar,
+  type DocSearchBarProps,
+} from './doc-search-bar'
+export {
+  DocSearchResultRow,
+  type DocSearchResultRowProps,
+  type DocSearchResultRowEntry,
+} from './doc-search-result-row'
+export { formatRelativePath } from './format-relative-path'
+
+// Hook + supporting helpers — moved from hub `hooks/use-docs.ts` so
+// embedders can mount the search bar directly without re-implementing
+// the debounced fetch + result navigation logic.
+export {
+  useDocSearch,
+  type UseDocSearchConfig,
+} from './use-doc-search'
+export {
+  resolveSearchResultAction,
+  type SearchResultAction,
+} from './resolve-search-result-action'
+export { mapDocSearchResults } from './map-doc-search-results'
+export type { DocSearchResult } from './types'

package/src/components/shared/doc-search/map-doc-search-results.ts

@@ -0,0 +1,113 @@
+/**
+ * Map RAG `/api/docs/search` wire results into the `<DocSearchBar>`
+ * dropdown's row shape, collapsing entity-table rows into grouped
+ * results so the dropdown lists ONE "Cap Table (12 records)" row
+ * instead of 12 individual rows.
+ *
+ * Pure transform — no telemetry, no navigation, no React deps. Lifted
+ * from the hub's `hooks/use-docs.ts:mapDocSearchResults` (the hub's
+ * `traceCompose` call was hub-only telemetry and is intentionally
+ * dropped — callers that want logging can wrap this helper).
+ */
+
+import type { SearchResult } from '../../ui/search-input'
+import type { DocSearchResult } from './types'
+
+/** Source repos that should be collapsed into grouped results in the search bar.
+ *  Only financial tables (all rows link to the same admin page).
+ *  Content tables (blog, webinar, podcast, etc.) stay individual since each has a unique URL. */
+const SEARCH_GROUP_REPOS = new Set([
+  'financial-cap-table',
+  'financial-kpis',
+  'financial-pnl',
+  'financial-balance-sheet',
+  'financial-cash-flow',
+])
+
+const ENTITY_LABELS: Record<string, string> = {
+  'financial-cap-table': 'Cap Table',
+  'financial-kpis': 'Financial KPIs',
+  'financial-pnl': 'Profit & Loss',
+  'financial-balance-sheet': 'Balance Sheets',
+  'financial-cash-flow': 'Cash Flow',
+  'blog-posts': 'Blog Posts',
+  'product-releases': 'Product Releases',
+  'case-studies': 'Case Studies',
+  webinars: 'Webinars',
+  events: 'Events',
+  podcasts: 'Podcasts',
+}
+
+export function mapDocSearchResults(docs: DocSearchResult[]): SearchResult[] {
+  const entityGroups = new Map<string, DocSearchResult[]>()
+  // Track insertion order — groups appear where the FIRST row of that
+  // repo appeared in the response.
+  const order: Array<
+    { type: 'entity'; repo: string } | { type: 'doc'; doc: DocSearchResult }
+  > = []
+  const seenRepos = new Set<string>()
+
+  for (const doc of docs) {
+    if (doc.sourceRepo && SEARCH_GROUP_REPOS.has(doc.sourceRepo)) {
+      const group = entityGroups.get(doc.sourceRepo) || []
+      group.push(doc)
+      entityGroups.set(doc.sourceRepo, group)
+      if (!seenRepos.has(doc.sourceRepo)) {
+        seenRepos.add(doc.sourceRepo)
+        order.push({ type: 'entity', repo: doc.sourceRepo })
+      }
+    } else {
+      order.push({ type: 'doc', doc })
+    }
+  }
+
+  const results: SearchResult[] = []
+  for (const entry of order) {
+    if (entry.type === 'entity') {
+      const rows = entityGroups.get(entry.repo)!
+      const label = ENTITY_LABELS[entry.repo] || entry.repo
+      results.push({
+        id: `group-${entry.repo}`,
+        title: `${label} (${rows.length} ${rows.length === 1 ? 'record' : 'records'})`,
+        path: rows[0].path,
+        type: 'file',
+        metadata: {
+          documentType: rows[0].documentType,
+          externalUrl: rows[0].externalUrl,
+          sourceRepo: entry.repo,
+          id: rows[0].entityId,
+          isGroup: true,
+          items: rows.map((r) => ({
+            name: r.name,
+            externalUrl: r.externalUrl,
+            id: r.entityId,
+            sourceRepo: r.sourceRepo,
+            documentType: r.documentType,
+          })),
+        },
+      })
+    } else {
+      const doc = entry.doc
+      const isNonMarkdown = doc.documentType && doc.documentType !== 'markdown'
+      results.push({
+        id: doc.path,
+        title: doc.name,
+        description: isNonMarkdown ? doc.name : doc.snippet,
+        path: doc.path,
+        type: doc.type,
+        metadata: {
+          matchType: doc.matchType,
+          ...(doc.documentType ? { documentType: doc.documentType } : {}),
+          ...(doc.externalUrl ? { externalUrl: doc.externalUrl } : {}),
+          ...(doc.targetPlatform != null
+            ? { targetPlatform: doc.targetPlatform }
+            : {}),
+          ...(doc.sourceRepo ? { sourceRepo: doc.sourceRepo } : {}),
+          ...(doc.entityId ? { id: doc.entityId } : {}),
+        },
+      })
+    }
+  }
+
+  return results
+}

package/src/components/shared/doc-search/resolve-search-result-action.ts

@@ -0,0 +1,68 @@
+/**
+ * Resolve what should happen when the user picks a search result.
+ * Returns one of five typed actions so the caller is a single switch.
+ *
+ * Resolution order:
+ *  1. `externalUrl` present → use `decideNewTab` to choose same-tab vs
+ *     new-tab against the row's `targetPlatform`.
+ *  2. Row has `id` + `sourceRepo` + `documentType` → synth an Ask-AI
+ *     action (entity drill-in via primary key, no URL).
+ *  3. Row has only `path` → legacy navigation fallback.
+ *  4. Nothing actionable → noop.
+ *
+ * Lifted from the hub's `hooks/use-docs.ts:resolveSearchResultAction`.
+ * Pure — no React, no telemetry.
+ */
+
+import type { SearchResult } from '../../ui/search-input'
+import type { ChatRef } from '../../chat/chat-ref.types'
+import { decideNewTab } from '../../chat/utils/decide-new-tab'
+
+export type SearchResultAction =
+  | { kind: 'navigate-same-tab'; href: string }
+  | { kind: 'navigate-new-tab'; href: string }
+  | { kind: 'ask-ai'; detail: { source: string; ref: ChatRef } }
+  | { kind: 'route'; path: string }
+  | { kind: 'noop' }
+
+export function resolveSearchResultAction(
+  result: SearchResult,
+  source: string,
+  runtimeMode?: 'host' | 'embed',
+): SearchResultAction {
+  const meta = result.metadata ?? {}
+  const externalUrl = meta.externalUrl as string | undefined
+  if (externalUrl) {
+    // Same pure helper `useNavLink` and `useUnifiedNav` call — single
+    // decision rule across cards, chips, and autocomplete rows. Thread
+    // the caller's `source` as `currentSource` so the platform-vs-
+    // platform comparison matches the hub's pre-migration behavior.
+    const targetPlatform = meta.targetPlatform as string | null | undefined
+    const isNewTab = decideNewTab({
+      href: externalUrl,
+      targetPlatform,
+      surface: 'useUnifiedNav',
+      runtimeMode,
+      currentSource: source,
+    })
+    return isNewTab
+      ? { kind: 'navigate-new-tab', href: externalUrl }
+      : { kind: 'navigate-same-tab', href: externalUrl }
+  }
+  const rowId = meta.id as string | undefined
+  const sourceRepo = meta.sourceRepo as string | undefined
+  const documentType = meta.documentType as string | undefined
+  if (rowId && sourceRepo && documentType) {
+    return {
+      kind: 'ask-ai',
+      detail: {
+        source,
+        ref: { type: documentType, id: rowId, title: result.title, url: null },
+      },
+    }
+  }
+  if (result.path) {
+    return { kind: 'route', path: result.path }
+  }
+  return { kind: 'noop' }
+}

package/src/components/shared/doc-search/types.ts

@@ -0,0 +1,28 @@
+/**
+ * Wire shape returned by `/api/docs/search` (one row per result).
+ * The hub's server-side RAG layer composes this; the lib hook
+ * consumes it. Keep field-for-field identical with the hub's
+ * `lib/data/doc-search-utils.ts:DocSearchResult` interface.
+ */
+export interface DocSearchResult {
+  path: string
+  name: string
+  type: 'file' | 'folder'
+  snippet: string
+  matchType: 'title' | 'content'
+  documentType?: string
+  externalUrl?: string
+  /** Platform that owns `externalUrl`. Threaded from the rag-config's
+   *  `resolveUrl` so the search-bar click handler can hand it straight
+   *  to the lib's `decideNewTab` for the same-tab-vs-new-tab decision.
+   *  `null` when external/unknown. */
+  targetPlatform?: string | null
+  sourceRepo?: string
+  /** Row's `RagTableConfig.primaryKey` value when known. Surfaced so the
+   *  search bar consumer can synthesize a `ChatRef` for entity rows
+   *  that have no public viewer (cap_table, financial-kpis, etc.) — the
+   *  click handler opens the chat panel pre-filled with a row drill-in
+   *  via `entityIdFilter` instead of synthesizing a 404 URL from
+   *  `result.path`. */
+  entityId?: string
+}

package/src/components/shared/doc-search/use-doc-search.ts

@@ -0,0 +1,263 @@
+'use client'
+
+/**
+ * `useDocSearch` — debounced RAG-search hook against `/api/docs/search`.
+ *
+ * Pure fetch + navigation glue. Embedders can mount this directly
+ * (any host with a reverse-proxy that exposes `/api/docs/search` will
+ * work). Hub callers wire it into the lib `<DocSearchBar>` for the
+ * canonical typeahead dropdown.
+ *
+ * ## What moved from hub to lib
+ *
+ * Lifted from `multi-platform-hub/hooks/use-docs.ts:useDocSearch`. Two
+ * hub-only concerns are now optional injection points instead of
+ * direct imports:
+ *
+ *   - `useDocNavigation()` (hub's in-page doc-tree swap) → optional
+ *     `onInPageSwap?: (path: string) => boolean` config callback. When
+ *     present and returns true, the hook treats a same-origin result
+ *     click as "handled in-page"; when absent or returns false, the
+ *     hook falls back to `onNavigate(path)` (`router.push` on hub,
+ *     `window.location.assign` on bare embedders).
+ *   - `traceCompose` (hub-only telemetry) → dropped. The lib has no
+ *     equivalent runtime-context yet; bring it back when there is one.
+ *
+ * Everything else (debounce, `useChatRuntime` for embed-mode short-
+ * circuit, embed-shim router, the action-resolver + result-mapper) is
+ * now lib-resident.
+ */
+
+import { useState, useEffect, useCallback } from 'react'
+import { useRouter } from '../../../embed-shims'
+import { useDebounce } from '../../../hooks/ui/use-debounce'
+import { useChatRuntime } from '../../../contexts/chat-runtime-context'
+import type { SearchResult } from '../../ui/search-input'
+import {
+  resolveExternalNavigation,
+  stripSameOriginToPath,
+  NEW_TAB_FEATURES,
+} from '../../chat/utils/chat-nav-resolution'
+import type { DocSearchResult } from './types'
+import { mapDocSearchResults } from './map-doc-search-results'
+import { resolveSearchResultAction } from './resolve-search-result-action'
+
+export interface UseDocSearchConfig {
+  /** Discriminator passed to `/api/docs/search?source=` (e.g.
+   *  `'openframe'`). Embedders set it to whatever discriminator their
+   *  reverse-proxy expects. */
+  source: string
+  /** Base route prefix this search lives under (e.g. `'/onboarding-guides'`).
+   *  When a result's href starts with `${baseRoute}/`, the hook
+   *  attempts the optional in-page swap path before falling through
+   *  to a full nav. */
+  baseRoute: string
+  /** Imperative navigation fallback. Called when no override
+   *  (in-page swap, new-tab) applies. Hub callers pass
+   *  `(path) => router.push(path)`; embedders pass an equivalent. */
+  onNavigate: (path: string) => void
+  /** Optional `RagTableConfig.id` list to narrow the search to specific
+   *  tables (e.g. `['onboarding-guides']`). Forwarded to
+   *  `/api/docs/search?tableIds=…` which intersects with the source's
+   *  standing set. */
+  tableIds?: string[]
+  /** Optional in-page swap callback. When the result's href is under
+   *  `baseRoute` AND this callback returns true, the hook treats the
+   *  click as handled in-page (no router push). Hub's
+   *  `<DocumentationSection>` wires this to
+   *  `useDocNavigation().navigate(path)`. */
+  onInPageSwap?: (path: string) => boolean
+  /** Optional endpoint override. Defaults to `'/api/docs/search'`
+   *  (the hub's reverse-proxy route). Embedders with a different
+   *  path can override. */
+  searchEndpoint?: string
+}
+
+export function useDocSearch(config: UseDocSearchConfig) {
+  const {
+    source,
+    baseRoute,
+    onNavigate,
+    tableIds,
+    onInPageSwap,
+    searchEndpoint = '/api/docs/search',
+  } = config
+  const tableIdsKey = tableIds && tableIds.length > 0 ? tableIds.join(',') : ''
+
+  const router = useRouter()
+  // Optional chat-runtime read — when present and mode='embed' the
+  // search-result row click short-circuits to a new-tab open against
+  // the absolutized URL. Null/host preserves today's behavior.
+  const runtime = useChatRuntime()
+
+  const [query, setQuery] = useState('')
+  const [results, setResults] = useState<SearchResult[]>([])
+  const [isFetching, setIsFetching] = useState(false)
+  const debouncedQuery = useDebounce(query, 300)
+
+  useEffect(() => {
+    if (!debouncedQuery || debouncedQuery.trim().length < 2) {
+      setResults([])
+      setIsFetching(false)
+      return
+    }
+
+    let cancelled = false
+
+    async function fetchResults() {
+      setIsFetching(true)
+      try {
+        const params = new URLSearchParams({
+          q: debouncedQuery,
+          source,
+          limit: '10',
+        })
+        if (tableIdsKey) params.set('tableIds', tableIdsKey)
+
+        const response = await fetch(`${searchEndpoint}?${params.toString()}`)
+        if (!response.ok) {
+          throw new Error(`Search request failed: ${response.status}`)
+        }
+
+        const json = await response.json()
+
+        if (!cancelled && json.success && Array.isArray(json.data)) {
+          const mapped = mapDocSearchResults(json.data as DocSearchResult[])
+          setResults(mapped)
+        }
+      } catch (error) {
+        console.error('Doc search error:', error)
+        if (!cancelled) {
+          setResults([])
+        }
+      } finally {
+        if (!cancelled) {
+          setIsFetching(false)
+        }
+      }
+    }
+
+    fetchResults()
+
+    return () => {
+      cancelled = true
+    }
+  }, [debouncedQuery, source, tableIdsKey, searchEndpoint])
+
+  // Derived loading state — single source of truth for "should the
+  // dropdown show 'Loading...' instead of 'No results found'":
+  const isLoading =
+    query.trim().length >= 2 && (query !== debouncedQuery || isFetching)
+
+  // Track whether dropdown should stay open (external link opened in new tab).
+  const [keepOpen, setKeepOpen] = useState(false)
+
+  const handleResultSelect = useCallback(
+    (
+      result: SearchResult,
+      modifiers?: {
+        metaKey?: boolean
+        ctrlKey?: boolean
+        shiftKey?: boolean
+        altKey?: boolean
+        button?: number
+      },
+    ) => {
+      const action = resolveSearchResultAction(
+        result,
+        source,
+        runtime?.navigation.mode,
+      )
+      // Modifier / non-primary mouse click → force new tab regardless of
+      // same-tab/new-tab decision. The dropdown row is a `<div>`, not an
+      // `<a target="_blank">`, so the browser doesn't background-tab
+      // natively on cmd-click. Honor it explicitly here for parity with
+      // the anchor-based surfaces (cards, chips, related-content). Plain
+      // Enter from the keyboard passes `modifiers === undefined`.
+      const wantsNewTab =
+        modifiers &&
+        (modifiers.metaKey ||
+          modifiers.ctrlKey ||
+          modifiers.shiftKey ||
+          modifiers.altKey ||
+          (typeof modifiers.button === 'number' && modifiers.button !== 0))
+      switch (action.kind) {
+        case 'navigate-same-tab': {
+          // Embed-mode short-circuit — autocomplete row clicked while
+          // the chat panel is hosted inside an embedding app.
+          if (runtime?.navigation.mode === 'embed') {
+            setKeepOpen(true)
+            const targetPlatform =
+              (result.metadata?.targetPlatform as string | null | undefined) ?? null
+            resolveExternalNavigation({
+              href: action.href,
+              targetPlatform,
+              runtime,
+            }).open()
+            return
+          }
+          if (wantsNewTab) {
+            setKeepOpen(true)
+            window.open(action.href, '_blank', NEW_TAB_FEATURES)
+            return
+          }
+          // Same-origin click:
+          //   1. If the href is under the current doc-tree's baseRoute AND
+          //      an `onInPageSwap` callback is wired AND returns true →
+          //      consider in-page swap handled.
+          //   2. Otherwise → embed-shim `router.push()` (soft RSC nav on
+          //      Next.js hosts, window.location.assign on bare hosts).
+          setKeepOpen(false)
+          const path =
+            baseRoute && action.href.startsWith(`${baseRoute}/`)
+              ? action.href.slice(baseRoute.length + 1)
+              : null
+          if (path && onInPageSwap?.(path)) return
+          router.push(stripSameOriginToPath(action.href))
+          return
+        }
+        case 'navigate-new-tab':
+          // Cross-origin (e.g. clicking a flamingo.run release from
+          // product-hub) — open in a new tab. Keep dropdown open so the
+          // user can pick another result without re-searching.
+          setKeepOpen(true)
+          window.open(action.href, '_blank', NEW_TAB_FEATURES)
+          return
+        case 'ask-ai':
+          // Row is searchable-but-not-openable (cap_table positions,
+          // financial-kpi snapshots, anything backed by
+          // `resolveUrl: () => null`). Dispatch a CustomEvent that
+          // GlobalAskAI listens for — opens chat + drills via
+          // `entityIdFilter` (primary-key only, same as inline-card Ask).
+          setKeepOpen(false)
+          window.dispatchEvent(
+            new CustomEvent('ask-ai:open-with-ref', { detail: action.detail }),
+          )
+          return
+        case 'route':
+          // Final fallback: legacy navigation by path. Hits when a row
+          // has neither URL nor pk metadata — a mapper/API regression.
+          setKeepOpen(false)
+          onNavigate(action.path)
+          return
+        case 'noop':
+          return
+      }
+    },
+    [onNavigate, source, baseRoute, router, onInPageSwap, runtime],
+  )
+
+  // Reset keepOpen when query changes.
+  useEffect(() => {
+    setKeepOpen(false)
+  }, [query])
+
+  return {
+    query,
+    setQuery,
+    results,
+    isLoading,
+    handleResultSelect,
+    keepDropdownOpen: keepOpen,
+  }
+}

package/src/components/tickets/help-center-card.tsx

@@ -55,6 +55,10 @@ export interface HelpCenterCardProps {
   onClose: TicketDetailDrawerProps['onClose']
   onReopen: TicketDetailDrawerProps['onReopen']
   onActionCollapsed: () => void
+  /** Persisted reply-failure banner — forwarded to the drawer. Parent
+   *  (`HelpCenterList`) reads via `actions.replyErrorFor(external_id)`. */
+  replyError?: TicketDetailDrawerProps['replyError']
+  onClearReplyError?: TicketDetailDrawerProps['onClearReplyError']
 }
 
 export function HelpCenterCard({
@@ -67,6 +71,8 @@ export function HelpCenterCard({
   onClose,
   onReopen,
   onActionCollapsed,
+  replyError,
+  onClearReplyError,
 }: HelpCenterCardProps) {
   const optimistic = isOptimistic(ticket)
   const rawStatus = (ticket.status ?? 'OPEN').toUpperCase()
@@ -177,6 +183,8 @@ export function HelpCenterCard({
             onClose={onClose}
             onReopen={onReopen}
             onActionCollapsed={onActionCollapsed}
+            replyError={replyError}
+            onClearReplyError={onClearReplyError}
           />
         </div>
       )}

package/src/components/tickets/help-center-list.tsx

@@ -40,7 +40,7 @@ import { useTicketsList } from './hooks/use-tickets-list'
 import { useTicketActions } from './hooks/use-ticket-actions'
 import { HelpCenterCard } from './help-center-card'
 import { HelpCenterCreateForm, HelpCenterCreateFormSkeleton } from './help-center-create-form'
-import type { AnyTicket, OptimisticTicket, TicketData } from './types'
+import type { AnyTicket, OptimisticTicket, TicketsCacheSlot } from './types'
 import { isOptimistic } from './types'
 
 export interface HelpCenterListProps {
@@ -175,9 +175,21 @@ function HelpCenterListAuthed({
       // Every cache slot under the ['tickets'] prefix — the queryKey
       // includes search + status + page + pageSize segments so a bare
       // write would miss most slots.
-      queryClient.setQueriesData<TicketData[] | undefined>(
+      //
+      // Cache slot is `TicketsCacheSlot` (`{ tickets, count, … }`), NOT
+      // a bare `TicketData[]`. The previous version called `.filter()`
+      // directly on the object — silently crashing only on the rare
+      // TICKET_NOT_FOUND path; the prod regression that landed
+      // 2026-05-29 surfaced the same shape mismatch in the
+      // close/reopen optimistic-update path. Project, filter, reassemble.
+      queryClient.setQueriesData<TicketsCacheSlot | undefined>(
         { queryKey: ['tickets'] },
-        (prev) => (prev ?? []).filter((t) => t.id !== ticketId),
+        (prev) => {
+          if (!prev || !Array.isArray(prev.tickets)) return prev
+          const nextTickets = prev.tickets.filter((t) => t.id !== ticketId)
+          if (nextTickets.length === prev.tickets.length) return prev
+          return { ...prev, tickets: nextTickets }
+        },
       )
       setExpandedTicketId((prev) => (prev === ticketId ? null : prev))
     },
@@ -285,6 +297,8 @@ function HelpCenterListAuthed({
                   onClose={actions.closeTicket}
                   onReopen={actions.reopenTicket}
                   onActionCollapsed={() => setExpandedTicketId(null)}
+                  replyError={actions.replyErrorFor(ticket.external_id)}
+                  onClearReplyError={() => actions.clearReplyError(ticket.external_id)}
                 />
               ))}
             </div>