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

package/src/components/onboarding-guides/onboarding-guide-detail-view.tsx

@@ -0,0 +1,215 @@
+'use client'
+
+/**
+ * Public-facing detail view for `/onboarding-guides/<slug>` on
+ * openframe.
+ *
+ * Self-contained: every concern that used to require a hub-side
+ * wrapper now flows through lib primitives + the ChatRuntime context.
+ *
+ *   - Markdown: lib `<SimpleMarkdownRenderer>` (already lib-resident).
+ *   - Video warmup: lib `useVideoWarmup` (reads Supabase storage
+ *     origin from `runtime.endpoints.supabaseStorageOrigin`; Mux
+ *     origins are hardcoded public CDN hosts).
+ *   - Captions URL: lib `getCaptionsUrl` (pure URL builder).
+ *   - Video poster: inline priority chain
+ *     (`main_video_thumbnail || featured_image || og_image_url`) —
+ *     same fallbacks the card uses.
+ *   - Related card hrefs: `runtime.composeContentUrl?.(
+ *     'onboarding_guide', slug, platforms)` — falls back to same-
+ *     origin relative path when no composer is wired.
+ *
+ * No hub-side wrapper file required. Optional `MarkdownRenderer`
+ * prop lets hosts swap in a renderer with extra plugins (Reddit /
+ * Twitter / X embeds) when needed.
+ */
+
+import { type ComponentType, type ReactNode } from 'react'
+import { ArrowLeft } from 'lucide-react'
+
+import { Link } from '../../embed-shims'
+import { ArticleDetailLayout } from '../layout/article-detail-layout'
+import { EntityVideoSection } from '../features/entity-video-section'
+import { VideoBitesDisplay } from '../features/video-bites-display'
+import { useVideoWarmup } from '../features/use-video-warmup'
+import { getCaptionsUrl } from '../features/captions-url'
+import { SimpleMarkdownRenderer } from '../ui/simple-markdown-renderer'
+import { EntityAuthorCard } from '../chat/entity-cards/entity-author-card'
+import { OnboardingGuideCard } from '../chat/entity-cards/onboarding-guide-card'
+import { useChatRuntime } from '../../contexts/chat-runtime-context'
+import type { OnboardingGuide } from '../chat/types/entities/onboarding-guide'
+import type { VideoTeaser } from '../../types/video-processing'
+import { buildDefaultHref } from './build-default-href'
+
+export interface OnboardingGuideDetailViewProps {
+  initialData: OnboardingGuide
+  related?: OnboardingGuide[]
+  /** Optional markdown renderer override. Defaults to lib
+   *  `<SimpleMarkdownRenderer>`. Hosts override when they need extra
+   *  plugins (Reddit / Twitter / X / code-block enhancements). */
+  MarkdownRenderer?: ComponentType<{ content: string }>
+  /** Optional per-row related-card renderer override. When omitted,
+   *  lib renders `<OnboardingGuideCard>` with runtime-composed href. */
+  renderRelatedCard?: (guide: OnboardingGuide) => ReactNode
+  /** Back-link target. Defaults to `basePath` so the link returns to
+   *  the catalog the embedder is hosting (no drift when `basePath`
+   *  is overridden). The admin preview explicitly overrides to
+   *  `/admin/onboarding-guides`. */
+  backHref?: string
+  /** Back-link label. Defaults to "Back to Getting Started". */
+  backLabel?: string
+  /** Base path the related-card hrefs default to when
+   *  `runtime.composeContentUrl` is not wired. Embedders mounting at
+   *  `/docs/onboarding/` instead of `/onboarding-guides/` should
+   *  override. Default `/onboarding-guides`. */
+  basePath?: string
+}
+
+export function OnboardingGuideDetailView({
+  initialData: guide,
+  related = [],
+  MarkdownRenderer = SimpleMarkdownRenderer,
+  renderRelatedCard,
+  backHref,
+  backLabel = 'Back to Getting Started',
+  basePath = '/onboarding-guides',
+}: OnboardingGuideDetailViewProps) {
+  // Resolve `backHref` from `basePath` when not explicitly set — so
+  // an embedder overriding `basePath="/docs/onboarding"` automatically
+  // gets the right back link without remembering to thread `backHref`
+  // too. Admin preview still wins via its explicit `backHref` override.
+  const resolvedBackHref = backHref ?? basePath
+  const runtime = useChatRuntime()
+
+  // Video warmup — preconnect always fires; preload only when the
+  // container scrolls within ~1 viewport AND the URL is on the
+  // configured Supabase storage origin. No origin in runtime ⇒
+  // preconnect-only path (Mux/YouTube unaffected).
+  const { ref: videoWarmupRef } = useVideoWarmup<HTMLDivElement>({
+    videoUrl: guide.main_video_url,
+    supabaseStorageOrigin: runtime?.endpoints.supabaseStorageOrigin,
+  })
+
+  const captionsUrl = getCaptionsUrl(
+    'onboarding_guide',
+    guide.id,
+    guide.srt_content,
+  )
+
+  // Video poster — fallback chain:
+  //   1. Entity-owned thumbnails (main_video_thumbnail / featured_image / og_image_url)
+  //   2. Branded OG placeholder from `runtime.resolvePlaceholderUrl(title)`
+  //      — restores the hub's prior behavior where a video without a
+  //      thumbnail still showed a branded poster instead of a black
+  //      frame.
+  //   3. `undefined` (player picks its own default poster — usually
+  //      first-frame extraction).
+  const videoPoster =
+    guide.main_video_thumbnail ||
+    guide.featured_image ||
+    guide.og_image_url ||
+    runtime?.resolvePlaceholderUrl?.(guide.title, { aspect: 'wide' }) ||
+    undefined
+
+  // Default related-card renderer — runtime-composed cross-platform href.
+  const defaultRenderRelatedCard = (g: OnboardingGuide) => {
+    const cta = runtime?.composeContentUrl
+      ? runtime.composeContentUrl(
+          'onboarding_guide',
+          g.slug,
+          g.onboarding_guide_platforms,
+        )
+      : buildDefaultHref(basePath, g.slug)
+    return (
+      <OnboardingGuideCard
+        guide={g}
+        href={cta.href}
+        targetPlatform={cta.targetPlatform}
+      />
+    )
+  }
+  const renderRelatedCardFn = renderRelatedCard ?? defaultRenderRelatedCard
+
+  return (
+    <ArticleDetailLayout>
+      <div className="space-y-6 md:space-y-8">
+        {/* Back link */}
+        <Link
+          href={resolvedBackHref}
+          className="inline-flex items-center gap-2 text-ods-text-secondary hover:text-ods-accent transition-colors"
+        >
+          <ArrowLeft className="h-4 w-4" />
+          <span className="text-h5">{backLabel}</span>
+        </Link>
+
+        <h1 className="text-h1 tracking-[-1.12px] text-ods-text-primary">
+          {guide.title}
+        </h1>
+
+        {/* Metadata grid — Section · Step | Published | Author. */}
+        <EntityAuthorCard
+          author={guide.author}
+          publishedAt={guide.published_at}
+          extraCells={[
+            {
+              value: `${guide.section} · Step ${guide.step_order}`,
+              label: 'Section',
+              uppercase: false,
+            },
+          ]}
+        />
+
+        {/* Video. `main_video_url` (Mux/MP4) and `youtube_url` are
+            independent columns — either one populated should render
+            the player. `EntityVideoSection` routes accordingly. */}
+        {(guide.main_video_url || guide.youtube_url) && (
+          <div ref={videoWarmupRef}>
+            <EntityVideoSection
+              mainVideoUrl={guide.main_video_url}
+              youtubeUrl={guide.youtube_url || undefined}
+              highlightVideoUrl={guide.highlight_video_url}
+              mainVideoPoster={videoPoster}
+              highlightVideoThumbnail={guide.highlight_video_thumbnail || undefined}
+              videoSummary={undefined}
+              videoBites={undefined}
+              title={guide.title}
+              srtContent={guide.srt_content}
+              captionsUrl={captionsUrl}
+              MarkdownRenderer={MarkdownRenderer}
+            />
+          </div>
+        )}
+
+        {/* Markdown body */}
+        {guide.content && (
+          <div className="space-y-4">
+            <MarkdownRenderer content={guide.content} />
+          </div>
+        )}
+
+        {/* Video Bites */}
+        {guide.video_bites && guide.video_bites.length > 0 && (
+          <VideoBitesDisplay
+            bites={guide.video_bites as VideoTeaser[]}
+            filterPublished={true}
+            showTitle={false}
+          />
+        )}
+
+        {/* Related — same-section, ordered by step. */}
+        {related.length > 0 && (
+          <div className="space-y-4 pt-8 border-t border-ods-border">
+            <h2 className="text-h3 tracking-[-0.36px] text-ods-text-primary">
+              More in {guide.section}
+            </h2>
+            <ul className="flex flex-col gap-3">
+              {related.map((r) => (
+                <li key={r.id}>{renderRelatedCardFn(r)}</li>
+              ))}
+            </ul>
+          </div>
+        )}
+      </div>
+    </ArticleDetailLayout>
+  )
+}

package/src/components/onboarding-guides/onboarding-guides-catalog-skeleton.tsx

@@ -0,0 +1,62 @@
+'use client'
+
+import { DevSectionPage } from '../shared/dev-section'
+import { OnboardingGuideCardSkeleton } from '../chat/entity-cards/onboarding-guide-card'
+
+/**
+ * Page-level Suspense fallback for `/onboarding-guides`.
+ *
+ * Mirrors the loaded `<OnboardingGuidesCatalogView>` shape — both
+ * mount the same `<DevSectionPage sectionKey="onboarding">` so the
+ * hero, back button, and overall page scaffold render identically.
+ *
+ * The `preControls` slot reserves space for the search bar (h-12)
+ * plus the section pill row (~74px including padding) so the
+ * Suspense → loaded transition doesn't shift vertically.
+ *
+ * Card distribution `4 + 3 + 3 = 10` matches the typical openframe
+ * onboarding dataset; per-card height (288 px) is byte-identical to
+ * the loaded card so per-card shifts on resolve are zero.
+ */
+export function OnboardingGuidesCatalogSkeleton() {
+  return (
+    <DevSectionPage
+      sectionKey="onboarding"
+      preControls={
+        <div className="space-y-4 animate-pulse">
+          {/* Search input placeholder — matches `<SearchInput>` h-12. */}
+          <div className="h-12 w-full bg-ods-card border border-ods-border rounded-md" />
+          {/* Section pill row placeholder — same wrapper class set the
+              hub-side `<FilterSection>` uses (~74 px). */}
+          <div className="flex flex-wrap items-center gap-3 p-4 bg-ods-card border border-ods-border rounded-lg">
+            <div className="h-4 w-14 bg-ods-border/60 rounded" />
+            {[0, 1, 2, 3].map((i) => (
+              <div
+                key={i}
+                className="h-10 w-24 bg-ods-card border border-ods-border rounded-md"
+              />
+            ))}
+          </div>
+        </div>
+      }
+    >
+      <div className="space-y-10 animate-pulse">
+        {[4, 3, 3].map((cardCount, sectionIdx) => (
+          <section key={sectionIdx} className="space-y-4">
+            <h2 className="text-h3 tracking-[-0.36px] text-ods-text-primary flex items-center gap-2">
+              <span className="h-6 w-40 bg-ods-border/70 rounded" />
+              <span className="h-5 w-8 bg-ods-text-secondary/20 rounded-full" />
+            </h2>
+            <ul className="flex flex-col gap-4">
+              {Array.from({ length: cardCount }).map((_, cardIdx) => (
+                <li key={cardIdx}>
+                  <OnboardingGuideCardSkeleton size="catalog" />
+                </li>
+              ))}
+            </ul>
+          </section>
+        ))}
+      </div>
+    </DevSectionPage>
+  )
+}

package/src/components/onboarding-guides/onboarding-guides-catalog-view.tsx

@@ -0,0 +1,230 @@
+'use client'
+
+/**
+ * Public-facing catalog view for `/onboarding-guides` on openframe.
+ *
+ * Self-contained: every concern that used to require a hub-side
+ * wrapper now flows through lib primitives + the ChatRuntime context.
+ *
+ *   - Chrome: `<DevSectionPage sectionKey="onboarding">` (same lib
+ *     primitive every other dev-center surface uses).
+ *   - Search bar: lib `<DocSearchBar>` + `useDocSearch` directly,
+ *     pre-scoped to `tableIds: ['onboarding-guides']`. The chat
+ *     runtime's `source` discriminates the RAG namespace.
+ *   - Section filter: lib `<FilterSection>` + URL push via embed-shim
+ *     `useRouter`/`useSearchParams`.
+ *   - Cards: lib `<OnboardingGuideCard>` with hrefs composed via
+ *     `runtime.composeContentUrl?.('onboarding_guide', slug, platforms)`.
+ *     Falls back to a same-origin relative path when no composer is
+ *     wired (single-platform embedders).
+ *
+ * No hub-side wrapper file required.
+ */
+
+import { useMemo, useTransition, type ReactNode } from 'react'
+import { GraduationCap } from 'lucide-react'
+
+import { useRouter, useSearchParams } from '../../embed-shims'
+import { DevSectionPage } from '../shared/dev-section'
+import { DocSearchBar, useDocSearch } from '../shared/doc-search'
+import { FilterPillRow } from '../ui/filter-pill-row'
+import { OnboardingGuideCard } from '../chat/entity-cards/onboarding-guide-card'
+import { useChatRuntime } from '../../contexts/chat-runtime-context'
+import type { OnboardingGuide } from '../chat/types/entities/onboarding-guide'
+import { buildDefaultHref } from './build-default-href'
+
+export interface OnboardingGuidesCatalogViewProps {
+  initialGuides: OnboardingGuide[]
+  initialSections: Array<{
+    section: string
+    section_order: number
+    count: number
+  }>
+  initialSection?: string
+  /** Optional per-row card renderer override. When omitted, lib
+   *  renders `<OnboardingGuideCard>` with runtime-composed href.
+   *  Embedders only override to swap the card shape entirely. */
+  renderCard?: (guide: OnboardingGuide) => ReactNode
+  /** Base path the catalog is mounted under. Used as the fallback
+   *  `href` prefix for card hrefs when `runtime.composeContentUrl` is
+   *  not wired. Embedders mounting at `/docs/onboarding/` instead of
+   *  `/onboarding-guides/` should override. Also used by `setSection`
+   *  for the `?section=` URL push. Default `/onboarding-guides`. */
+  basePath?: string
+}
+
+export function OnboardingGuidesCatalogView({
+  initialGuides,
+  initialSections,
+  initialSection = '',
+  renderCard,
+  basePath = '/onboarding-guides',
+}: OnboardingGuidesCatalogViewProps) {
+  const router = useRouter()
+  const searchParams = useSearchParams()
+  const [isPending, startTransition] = useTransition()
+  const runtime = useChatRuntime()
+  const activeSection = initialSection || 'all'
+
+  // Section grouping. Data arrives already filtered server-side via
+  // `?section=`; this just buckets the visible rows for the section-
+  // header layout — no client-side `.filter()`.
+  const grouped = useMemo(() => {
+    const map = new Map<
+      string,
+      { section_order: number; guides: OnboardingGuide[] }
+    >()
+    for (const g of initialGuides) {
+      const existing = map.get(g.section)
+      if (existing) {
+        if (g.section_order < existing.section_order)
+          existing.section_order = g.section_order
+        existing.guides.push(g)
+      } else {
+        map.set(g.section, { section_order: g.section_order, guides: [g] })
+      }
+    }
+    for (const entry of map.values()) {
+      entry.guides.sort(
+        (a, b) =>
+          a.step_order - b.step_order || a.title.localeCompare(b.title),
+      )
+    }
+    return Array.from(map.entries())
+      .map(([section, info]) => ({ section, ...info }))
+      .sort(
+        (a, b) =>
+          a.section_order - b.section_order ||
+          a.section.localeCompare(b.section),
+      )
+  }, [initialGuides])
+
+  // Section-filter options for the lib `<FilterSection>` row.
+  const sectionFilterOptions = useMemo(
+    () => [
+      { value: 'all', label: `All (${initialGuides.length})` },
+      ...initialSections.map((s) => ({
+        value: s.section,
+        label: `${s.section} (${s.count})`,
+      })),
+    ],
+    [initialGuides.length, initialSections],
+  )
+
+  // Section pill change → push `?section=X` so the host RSC re-
+  // fetches against the DAL. Wrapped in `useTransition` so the
+  // results grid dims while the new payload is in flight.
+  const setSection = (value: string) => {
+    const params = new URLSearchParams(searchParams.toString())
+    if (value === 'all') {
+      params.delete('section')
+    } else {
+      params.set('section', value)
+    }
+    const qs = params.toString()
+    startTransition(() => {
+      router.push(qs ? `${basePath}?${qs}` : basePath)
+    })
+  }
+
+  // Search bar — scoped to onboarding-guides only via the RAG-search
+  // `tableIds` parameter. The hook calls `/api/docs/search` directly;
+  // hub or embedder must expose that endpoint (reverse-proxy on
+  // non-Next.js hosts).
+  const source = runtime?.source ?? 'openframe'
+  const docSearch = useDocSearch({
+    source,
+    baseRoute: basePath,
+    onNavigate: (path) => router.push(path),
+    tableIds: ['onboarding-guides'],
+  })
+
+  // Per-row card renderer — uses runtime-composed href for cross-
+  // platform navigation. Falls back to a same-origin relative URL
+  // when no composer is wired.
+  const defaultRenderCard = (guide: OnboardingGuide) => {
+    const cta = runtime?.composeContentUrl
+      ? runtime.composeContentUrl(
+          'onboarding_guide',
+          guide.slug,
+          guide.onboarding_guide_platforms,
+        )
+      : buildDefaultHref(basePath, guide.slug)
+    return (
+      <OnboardingGuideCard
+        guide={guide}
+        href={cta.href}
+        targetPlatform={cta.targetPlatform}
+        size="catalog"
+      />
+    )
+  }
+  const renderCardFn = renderCard ?? defaultRenderCard
+
+  const preControls = (
+    <div className="space-y-4">
+      <DocSearchBar
+        placeholder="Search onboarding guides, releases, case studies…"
+        query={docSearch.query}
+        onQueryChange={docSearch.setQuery}
+        results={docSearch.results}
+        isLoading={docSearch.isLoading}
+        onResultSelect={docSearch.handleResultSelect}
+        showDropdown={docSearch.keepDropdownOpen}
+      />
+      {initialSections.length > 0 && (
+        <FilterPillRow
+          label="Section"
+          selectedValue={activeSection}
+          onValueChange={setSection}
+          options={sectionFilterOptions}
+        />
+      )}
+    </div>
+  )
+
+  return (
+    <DevSectionPage sectionKey="onboarding" preControls={preControls}>
+      {initialGuides.length === 0 ? (
+        <div className="text-center py-16">
+          <GraduationCap className="h-12 w-12 text-ods-text-secondary mx-auto mb-4" />
+          <h2 className="text-ods-text-primary font-['DM_Sans'] text-[20px] font-semibold mb-2">
+            No onboarding guides found
+          </h2>
+          <p className="text-ods-text-secondary font-['DM_Sans'] text-[14px]">
+            {activeSection !== 'all'
+              ? 'No guides in this section yet.'
+              : "We're working on the onboarding library. Check back soon."}
+          </p>
+        </div>
+      ) : (
+        <div
+          className={
+            isPending
+              ? 'opacity-60 transition-opacity space-y-10'
+              : 'space-y-10'
+          }
+        >
+          {grouped.map((sec) => (
+            <section key={sec.section} className="space-y-4">
+              <h2 className="text-h3 tracking-[-0.36px] text-ods-text-primary flex items-center gap-2">
+                {sec.section}
+                <span className="inline-flex items-center justify-center rounded-full bg-ods-text-secondary/20 text-ods-text-secondary text-xs font-medium px-2 py-0.5">
+                  {sec.guides.length}
+                </span>
+              </h2>
+              {/* HORIZONTAL catalog list — single column so consecutive
+                  steps read top-to-bottom (Step 1 above Step 2 above
+                  Step 3); a grid would visually reorder them. */}
+              <ul className="flex flex-col gap-4">
+                {sec.guides.map((guide) => (
+                  <li key={guide.id}>{renderCardFn(guide)}</li>
+                ))}
+              </ul>
+            </section>
+          ))}
+        </div>
+      )}
+    </DevSectionPage>
+  )
+}

package/src/components/shared/doc-search/doc-search-bar.tsx

@@ -0,0 +1,100 @@
+'use client'
+
+/**
+ * `<DocSearchBar>` — the canonical RAG-search dropdown surface.
+ *
+ * Mounted by every doc-search consumer (data-room sidebar, onboarding-
+ * guide catalog, and any future surface that needs typeahead against
+ * `/api/docs/search`). Wraps `<SearchInput>` with the lib's standard
+ * `<DocSearchResultRow>` so the dropdown looks identical everywhere.
+ *
+ * ## Why a presentation component, not a "search bar that owns its
+ *    own hook"
+ *
+ * The data-fetching hook (`useDocSearch`) lives hub-side because it
+ * depends on hub-only context (`useDocNavigation`, the rag-table-
+ * config registry, the hub's `decideNewTab` helper). Moving the hook
+ * would cascade ~5 more file migrations into the lib.
+ *
+ * Instead, the hook stays hub-side and callers pass its result into
+ * this component as plain props. Both consumers shrink to ~5 lines.
+ */
+
+import type { ReactNode } from 'react'
+import { SearchInput, type SearchResult } from '../../ui/search-input'
+import { DocSearchResultRow } from './doc-search-result-row'
+
+export interface DocSearchBarProps {
+  placeholder: string
+  query: string
+  onQueryChange: (value: string) => void
+  /** Hook-fetched results. Reuses the lib's `<SearchInput>` `SearchResult`
+   *  shape directly so callers don't translate. */
+  results: SearchResult[]
+  isLoading: boolean
+  /** Result selection handler. Mirrors `<SearchInput>` — the second
+   *  `modifiers` argument is preserved so cmd-click / shift-click on
+   *  a result row still forces new-tab behavior. Hub `useDocSearch`
+   *  reads these to short-circuit to `window.open()`. */
+  onResultSelect: (
+    result: SearchResult,
+    modifiers?: {
+      metaKey?: boolean
+      ctrlKey?: boolean
+      shiftKey?: boolean
+      altKey?: boolean
+      button?: number
+    },
+  ) => void
+  /** Lets the caller's hook force the dropdown open after a recent
+   *  internal action (e.g. result navigation). `undefined` falls back
+   *  to `<SearchInput>`'s built-in focus/hover heuristics. */
+  showDropdown?: boolean
+  /** Defaults to 2 — matches the existing data-room and onboarding-
+   *  guide consumers. Override only if a surface needs different
+   *  typeahead semantics. */
+  minQueryLength?: number
+  /** Defaults to 0 — both existing consumers debounce inside the
+   *  hook, not the input. */
+  debounceMs?: number
+  className?: string
+  /** Optional row-renderer override. Defaults to the lib's standard
+   *  `<DocSearchResultRow>` (source icon + title + path breadcrumb).
+   *  Override only when a surface needs custom row chrome. */
+  renderResult?: (result: SearchResult, isHighlighted: boolean) => ReactNode
+}
+
+export function DocSearchBar({
+  placeholder,
+  query,
+  onQueryChange,
+  results,
+  isLoading,
+  onResultSelect,
+  showDropdown,
+  minQueryLength = 2,
+  debounceMs = 0,
+  className = 'w-full',
+  renderResult,
+}: DocSearchBarProps) {
+  return (
+    <SearchInput
+      placeholder={placeholder}
+      value={query}
+      onChange={onQueryChange}
+      results={results}
+      isLoading={isLoading}
+      onResultSelect={onResultSelect}
+      showDropdown={showDropdown || undefined}
+      debounceMs={debounceMs}
+      minQueryLength={minQueryLength}
+      className={className}
+      renderResult={
+        renderResult ??
+        ((result, isHighlighted) => (
+          <DocSearchResultRow result={result} isHighlighted={isHighlighted} />
+        ))
+      }
+    />
+  )
+}

package/src/components/shared/doc-search/doc-search-result-row.tsx

@@ -0,0 +1,73 @@
+'use client'
+
+/**
+ * Single row in the `<SearchInput>` dropdown — the standard layout
+ * used by every doc-search-backed surface (company-hub data-room
+ * search bar, onboarding-guide catalog search, …). Single source of
+ * truth for the row appearance so search dropdowns are visually
+ * identical everywhere.
+ *
+ * Resolves the source icon via the same `resolveSourceIcon()`
+ * registry the inline chat-card refs use, so a row pointing at e.g.
+ * an onboarding-guide surfaces the SAME `<GraduationCap>` glyph the
+ * chat card surfaces — no cross-surface drift.
+ */
+
+import { resolveSourceIcon } from '../../chat/utils/source-row-cta'
+import { formatRelativePath } from './format-relative-path'
+
+/**
+ * Minimal result shape this row renders. Compatible with any
+ * doc-search hook whose result type exposes `{ title?, path?,
+ * metadata? }`. The two hub consumers (onboarding-guide catalog,
+ * data-room sidebar) both satisfy this shape via their
+ * `useDocSearch` hook result.
+ */
+export interface DocSearchResultRowEntry {
+  title?: string
+  path?: string
+  metadata?: Record<string, unknown>
+}
+
+export interface DocSearchResultRowProps {
+  result: DocSearchResultRowEntry
+  isHighlighted: boolean
+}
+
+export function DocSearchResultRow({
+  result,
+  isHighlighted,
+}: DocSearchResultRowProps) {
+  const docType = (result.metadata?.documentType as string) || undefined
+  const sourceRepo = (result.metadata?.sourceRepo as string) || undefined
+  const { Icon: SourceIcon, label: iconLabel } = resolveSourceIcon({
+    sourceRepo,
+    documentType: docType,
+  })
+  const isGroup = result.metadata?.isGroup as boolean | undefined
+
+  return (
+    <div className="flex items-center gap-3 w-full min-w-0">
+      <span
+        className="flex-shrink-0 text-ods-text-secondary"
+        title={iconLabel}
+      >
+        <SourceIcon className="size-4" />
+      </span>
+      <div className="min-w-0 flex-1">
+        <div
+          className={`text-sm font-medium leading-5 truncate ${
+            isHighlighted ? 'text-ods-accent' : 'text-ods-text-primary'
+          }`}
+        >
+          {result.title || result.path}
+        </div>
+        {!isGroup && result.path?.includes('/') && (
+          <div className="text-xs leading-4 text-ods-text-secondary truncate mt-0.5">
+            {formatRelativePath(result.path)}
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}