@flamingo-stack/openframe-frontend-core 0.0.295 → 0.0.296-snapshot.20260621021605

package/src/components/layout/page-with-header.tsx

@@ -0,0 +1,110 @@
+'use client'
+
+import React from 'react'
+import { useRouter } from '../../embed-shims/next-navigation'
+import { PageShell } from './article-detail-layout'
+import { PageLayout } from './page-layout'
+import { PageHeader, type PageHeaderProps } from './page-header'
+
+/**
+ * `<PageWithHeader>` — the canonical 4-layer unified-chrome wrapper that
+ * every public lib/hub page now uses (Knowledge Hub, Roadmap, FAQs,
+ * Authors, Blog, Vendors, Case Studies, Interviews, Investor Updates,
+ * /webinars-/podcasts-/events, hub admin-but-public pages, …).
+ *
+ * Renders the same JSX tree every consumer was hand-rolling individually
+ * before this helper landed:
+ *
+ *   PageShell                         ← bg-ods-bg, min-h-screen, max-w-[1920px],
+ *                                       page-shell-px/pt/pb gutters
+ *     PageLayout backButton           ← TitleBlock → PageHeader #1 (back-btn row
+ *                                       only, pt-l + mb-l)
+ *       div.w-full.flex-col.gap-10    ← matches DevSectionView's hero container
+ *         PageHeader title/subtitle   ← PageHeader #2 (noTopPadding +
+ *           titleIcon accentDot         noBottomMargin so PageLayout's gap-l owns
+ *           noTopPadding                the spacing between #1 and #2)
+ *           noBottomMargin
+ *         children                    ← page-specific body (search, lists, forms)
+ *
+ * Why this exists: 15+ pages copy-pasted the EXACT same nesting + the
+ * EXACT same `noTopPadding + noBottomMargin + accentDot` triplet on the
+ * inner `<PageHeader>`. Forgetting one of those flags collapsed the gap
+ * to ~8px (the FAQs-vs-Onboarding-Guides bug). Centralizing the chain
+ * here makes the spacing invariant compiler-enforced — consumers can't
+ * pick the wrong combination.
+ *
+ * **Back button is config-driven by default.** Consumers don't have to
+ * thread `useRouter()` + `() => router.push('/')` themselves anymore —
+ * the helper supplies a sane default (`{ label: 'Back to home', href: '/' }`).
+ * Hosts whose `/` lives elsewhere should pass their own `href`. Pass
+ * `backButton={false}` to suppress entirely (the lib's own
+ * `<DocsHubPage>` does this on the platform-home docs landing).
+ */
+export interface PageWithHeaderProps {
+  /** Title — passed straight to inner `<PageHeader>`. */
+  title?: string
+  /** Inline icon rendered before the title (lucide / SVG node). Wrap with
+   *  `SECTION_HERO_ICON_CLASS` at the call site, or use the lib's
+   *  `<PageHeader>`'s `titleIcon` ReactNode signature directly. */
+  titleIcon?: PageHeaderProps['titleIcon']
+  /** Subtitle (1-2 lines, auto-clamped to 2 + min-h-[56px]). */
+  subtitle?: string
+  /** Render yellow accent dot after the title (default true — matches every
+   *  unified surface). Pass `false` to opt out. */
+  accentDot?: boolean
+  /** Back-button config. Defaults to `{ label: 'Back to home', href: '/' }`.
+   *  Pass `false` to hide entirely (platform-home docs landings). */
+  backButton?: { label?: string; href?: string } | false
+  /** Optional image (entity-image-style — onboarding guides etc.). */
+  image?: PageHeaderProps['image']
+  /** Optional actions slot (right side of header). */
+  actions?: React.ReactNode
+  /** Page body — search bars, lists, forms, sections. Rendered INSIDE the
+   *  gap-10 flex column so it shares gutters + vertical rhythm with the
+   *  header. */
+  children: React.ReactNode
+  /** Extra class applied to the gap-10 content wrapper. */
+  contentClassName?: string
+}
+
+export function PageWithHeader({
+  title,
+  titleIcon,
+  subtitle,
+  accentDot = true,
+  backButton,
+  image,
+  actions,
+  children,
+  contentClassName,
+}: PageWithHeaderProps) {
+  const router = useRouter()
+
+  const backCfg =
+    backButton === false
+      ? undefined
+      : {
+          label: backButton?.label ?? 'Back to home',
+          onClick: () => router.push(backButton?.href ?? '/'),
+        }
+
+  return (
+    <PageShell>
+      <PageLayout backButton={backCfg}>
+        <div className={`w-full flex flex-col gap-10${contentClassName ? ` ${contentClassName}` : ''}`}>
+          <PageHeader
+            title={title}
+            titleIcon={titleIcon}
+            subtitle={subtitle}
+            accentDot={accentDot}
+            image={image}
+            actions={actions}
+            noTopPadding
+            noBottomMargin
+          />
+          {children}
+        </div>
+      </PageLayout>
+    </PageShell>
+  )
+}

package/src/components/layout/title-block.tsx

@@ -1,15 +1,29 @@
 'use client'
 
 import React from 'react'
-import { cn } from '../../utils/cn'
 import type { ActionsMenuGroup } from '../ui/actions-menu'
-import { EntityImage } from '../ui/entity-image'
 import { PageActions, type PageActionButton } from '../ui/page-actions'
-import { BackButton } from './back-button'
+import { PageHeader } from './page-header'
 
+/**
+ * `<TitleBlock>` — thin adapter over `<PageHeader>` that turns the
+ * `actions: PageActionButton[]` / `menuActions` / `selector` API into
+ * a `ReactNode` slot that PageHeader can render. Kept as a separate
+ * component for backwards compatibility (`PageLayout` consumes it,
+ * external callers may too) — all the DOM/CSS lives in PageHeader.
+ *
+ * If a new consumer doesn't need the `PageActions` wiring, prefer
+ * `<PageHeader>` directly.
+ */
 export interface TitleBlockProps {
   title?: string
   subtitle?: string
+  /** Inline icon rendered before the title text (e.g. HelpCircle on /faqs,
+   *  BookOpen on /knowledge-base, Map on /roadmap). Forwarded verbatim to
+   *  `<PageHeader>`. */
+  titleIcon?: React.ReactNode
+  /** Yellow accent dot after the title — same flag as PageHeader. */
+  accentDot?: boolean
   image?: { src: string; alt?: string }
   backButton?: { label?: string; onClick: () => void }
   actions?: PageActionButton[]
@@ -29,6 +43,8 @@ export interface TitleBlockProps {
 export function TitleBlock({
   title,
   subtitle,
+  titleIcon,
+  accentDot,
   image,
   backButton,
   actions,
@@ -40,67 +56,29 @@ export function TitleBlock({
 }: TitleBlockProps) {
   const hasActions = actions && actions.length > 0
   const hasMenuActions = !!menuActions && menuActions.some(g => g.items.length > 0)
+  const hasActionsSlot = hasActions || hasMenuActions || !!selector
 
-  return (
-    <div
-      className={cn(
-        'flex items-end justify-between gap-[var(--spacing-system-m)]',
-        'md:flex-col md:items-start md:justify-start lg:flex-row lg:items-end lg:justify-between',
-        'pt-[var(--spacing-system-l)]',
-        variant === 'card'
-          ? cn(
-              'bg-ods-card border-b border-ods-border',
-              'px-[var(--spacing-system-l)] pb-[var(--spacing-system-l)]',
-              'md:bg-transparent md:border-b-0',
-              'md:px-0 md:pb-0',
-              'md:mb-[var(--spacing-system-l)]',
-            )
-          : 'mb-[var(--spacing-system-l)]',
-        className,
-      )}
-    >
-      <div className="flex flex-col gap-[var(--spacing-system-xs)] flex-1 min-w-0">
-        {backButton && (
-          <BackButton
-            onClick={backButton.onClick}
-            label={backButton.label}
-            className="hidden md:inline-flex"
-          />
-        )}
-        {(image || subtitle) ? (
-          <div className="flex items-center gap-[var(--spacing-system-m)] min-w-0 w-full">
-            {image && (
-              <EntityImage
-                src={image.src}
-                alt={image.alt}
-                fallbackText={image.alt || title}
-              />
-            )}
-            <div className="flex flex-col justify-center min-w-0 flex-1">
-              {title && (
-                <h1 className="text-h2 text-ods-text-primary truncate" title={title}>{title}</h1>
-              )}
-              {subtitle && (
-                <p className="text-h6 text-ods-text-secondary truncate" title={subtitle}>{subtitle}</p>
-              )}
-            </div>
-          </div>
-        ) : (
-          title && <h1 className="text-h2 text-ods-text-primary">{title}</h1>
-        )}
-      </div>
+  const actionsNode = hasActionsSlot ? (
+    <PageActions
+      variant={actionsVariant}
+      actions={actions ?? []}
+      menuActions={menuActions}
+      selector={selector}
+    />
+  ) : undefined
 
-      {(hasActions || hasMenuActions || selector) && (
-        <div className="flex gap-2 items-center shrink-0">
-          <PageActions
-            variant={actionsVariant}
-            actions={actions ?? []}
-            menuActions={menuActions}
-            selector={selector}
-          />
-        </div>
-      )}
-    </div>
+  return (
+    <PageHeader
+      title={title}
+      titleIcon={titleIcon}
+      subtitle={subtitle}
+      accentDot={accentDot}
+      image={image}
+      backButton={backButton}
+      actions={actionsNode}
+      variant={variant}
+      className={className}
+    />
   )
 }
 

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

@@ -29,7 +29,7 @@ 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 { RichMarkdownRenderer } from '../ui/rich-markdown-renderer'
 import { EntityTagBadges } from '../features/entity-tag-badges'
 import { LoadError } from '../ui/error-state'
 import { ArticleAuthorByline } from '../shared/article-author-byline'
@@ -62,7 +62,7 @@ export interface OnboardingGuideDetailViewProps {
    *  byline renders nothing below the name when the bio is empty. */
   fallbackBio?: string | null
   /** Optional markdown renderer override. Defaults to lib
-   *  `<SimpleMarkdownRenderer>`. */
+   *  `<RichMarkdownRenderer>`. */
   MarkdownRenderer?: ComponentType<{ content: string }>
   /** Optional per-row related-card renderer override. */
   renderRelatedCard?: (guide: OnboardingGuide) => ReactNode
@@ -83,7 +83,7 @@ export function OnboardingGuideDetailView({
   slug,
   guideEndpoint,
   related = [],
-  MarkdownRenderer = SimpleMarkdownRenderer,
+  MarkdownRenderer = RichMarkdownRenderer,
   renderRelatedCard,
   backHref,
   backLabel = 'Back to Getting Started',

package/src/components/shared/dev-section/dev-section-page.tsx

@@ -25,7 +25,15 @@ import {
   type OpenframeDevSectionKey,
 } from '../../../utils/dev-sections/openframe-dev-sections';
 
-const SECTION_HERO_ICON_CLASS = 'h-10 w-10 text-ods-accent';
+/** Re-export the constant so existing dev-section call sites keep their
+ *  old import path. The canonical home is `src/utils/page-header-constants.ts`
+ *  (NOT a `'use client'` module) so server modules can import it without
+ *  Next.js turning it into a client reference proxy — that proxy is what
+ *  blew up lucide's `mergeClasses().trim()` when used as
+ *  `<Icon className={SECTION_HERO_ICON_CLASS} />` inside a hub
+ *  server-component preset. */
+import { SECTION_HERO_ICON_CLASS } from '../../../utils/page-header-constants';
+export { SECTION_HERO_ICON_CLASS };
 
 export interface DevSectionPageProps {
   sectionKey: OpenframeDevSectionKey;

package/src/components/shared/dev-section/dev-section-view.tsx

@@ -19,6 +19,7 @@ import { useState, useEffect } from 'react';
 import { useRouter, useSearchParams, usePathname } from '../../../embed-shims';
 import { SearchInput } from '../../ui';
 import { StatusFilterComponent } from '../../features';
+import { PageHeader } from '../../layout/page-header';
 import {
   OPENFRAME_DEV_SECTIONS,
   type OpenframeDevSectionKey,
@@ -95,15 +96,19 @@ export function DevSectionView({ sectionKey, hero, preControls, children }: DevS
   return (
     <div className="w-full flex flex-col gap-10">
       {hero ? (
-        <div className="space-y-4">
-          <h1 className="text-h1 tracking-[-1.12px] text-ods-text-primary flex items-center gap-3">
-            {hero.icon}
-            {hero.title ?? section.hero.title}
-          </h1>
-          <p className="font-['DM_Sans'] font-medium text-[18px] leading-[28px] text-ods-text-secondary max-w-3xl">
-            {hero.description}
-          </p>
-        </div>
+        // Render through the shared `<PageHeader>` primitive so the dev-
+        // section hero (Releases, Roadmap, Onboarding catalog) and the
+        // docs-hub hero (Knowledge Hub, Data Room) are LITERALLY the same
+        // component rendering the same DOM/CSS. `noBottomMargin` because
+        // the parent `gap-10` already supplies the spacing to the next
+        // sibling (preControls / search / filter).
+        <PageHeader
+          title={hero.title ?? section.hero.title}
+          titleIcon={hero.icon}
+          subtitle={hero.description}
+          noBottomMargin
+          noTopPadding
+        />
       ) : (
         <div className="flex items-center justify-between w-full">
           <h2 className="font-['Azeret_Mono'] font-semibold text-[32px] md:text-[40px] lg:text-[48px] leading-[40px] md:leading-[48px] lg:leading-[56px] text-ods-text-primary tracking-[-0.64px] md:tracking-[-0.8px] lg:tracking-[-0.96px]">

package/src/components/shared/dev-section/index.ts

@@ -1,5 +1,5 @@
 export { DevSectionView, type DevSectionViewProps } from './dev-section-view';
-export { DevSectionPage, type DevSectionPageProps } from './dev-section-page';
+export { DevSectionPage, type DevSectionPageProps, SECTION_HERO_ICON_CLASS } from './dev-section-page';
 export {
   DevCardRowContent,
   DevCardRowSkeleton,

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

@@ -80,7 +80,7 @@ export function useDocSearch(config: UseDocSearchConfig) {
     onNavigate,
     tableIds,
     onInPageSwap,
-    searchEndpoint = '/api/docs/search',
+    searchEndpoint,
   } = config
   const tableIdsKey = tableIds && tableIds.length > 0 ? tableIds.join(',') : ''
 
@@ -88,7 +88,11 @@ export function useDocSearch(config: UseDocSearchConfig) {
   // 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.
+  // Also used as the proxy-prefix fallback for `searchEndpoint`, matching
+  // how tickets resolves `findTicketUrl`.
   const runtime = useChatRuntime()
+  const resolvedSearchEndpoint =
+    searchEndpoint ?? runtime?.endpoints.docsSearchUrl ?? '/api/docs/search'
 
   const [query, setQuery] = useState('')
   const [results, setResults] = useState<SearchResult[]>([])
@@ -114,7 +118,7 @@ export function useDocSearch(config: UseDocSearchConfig) {
         })
         if (tableIdsKey) params.set('tableIds', tableIdsKey)
 
-        const response = await fetch(`${searchEndpoint}?${params.toString()}`)
+        const response = await fetch(`${resolvedSearchEndpoint}?${params.toString()}`)
         if (!response.ok) {
           throw new Error(`Search request failed: ${response.status}`)
         }
@@ -142,7 +146,7 @@ export function useDocSearch(config: UseDocSearchConfig) {
     return () => {
       cancelled = true
     }
-  }, [debouncedQuery, source, tableIdsKey, searchEndpoint])
+  }, [debouncedQuery, source, tableIdsKey, resolvedSearchEndpoint])
 
   // Derived loading state — single source of truth for "should the
   // dropdown show 'Loading...' instead of 'No results found'":

package/src/components/shared/legal-document/legal-document-page.tsx

@@ -19,7 +19,7 @@
 
 import type { ComponentType } from 'react';
 import { PageShell, PageLayout, PageHeading } from '../../ui';
-import { SimpleMarkdownRenderer } from '../../ui/simple-markdown-renderer';
+import { RichMarkdownRenderer } from '../../ui/rich-markdown-renderer';
 import { useRouter } from '../../../embed-shims/next-navigation';
 import { useLegalDocs, type LegalDocument } from './use-legal-docs';
 import { formatLegalDate } from '../../../utils/format';
@@ -76,7 +76,7 @@ export function LegalDocumentPage({
   initialData = null,
   initialLastUpdatedLabel = null,
   apiEndpoint,
-  MarkdownRenderer = SimpleMarkdownRenderer,
+  MarkdownRenderer = RichMarkdownRenderer,
   backButton,
 }: LegalDocumentPageProps) {
   const router = useRouter();

package/src/components/shared/product-release/release-detail-page.tsx

@@ -10,6 +10,7 @@ import { Card, CardContent } from '../../ui/card';
 import { PageShell } from '../../layout/article-detail-layout';
 import { PageLayout } from '../../layout/page-layout';
 import { ReleaseChangelogSection } from '../../ui/release-changelog-section';
+import { RichMarkdownRenderer } from '../../ui/rich-markdown-renderer';
 import { EntityTagBadges } from '../../features/entity-tag-badges';
 import { EntityMetadataAuthorCell } from '../../chat/entity-cards/entity-author-card';
 import type { EntityAuthor } from '../../../types/entity-author';
@@ -109,10 +110,11 @@ export interface ReleaseDetailPageProps {
   authorHref?: string;
 }
 
-// Default simple markdown renderer (just renders as text)
-function DefaultMarkdownRenderer({ content }: MarkdownRendererProps) {
-  return <div className="whitespace-pre-wrap">{content}</div>;
-}
+// Default renderer = the lib's `RichMarkdownRenderer` so out-of-the-box
+// release pages get full rich-link previews, embedded media, social cards,
+// etc. Hosts that want a different rendering (or a Supabase-aware preset)
+// override via the `MarkdownRenderer` prop.
+const DefaultMarkdownRenderer = RichMarkdownRenderer;
 
 export function ReleaseDetailPage({
   authorHref,

package/src/components/ui/button/split-button.tsx

@@ -106,13 +106,15 @@ interface HalfOptions {
   prefetch?: boolean
   onClick?: React.MouseEventHandler<HTMLButtonElement | HTMLAnchorElement>
   disabled?: boolean
+  /** Stretch this half to fill the group's free space (the icon half stays fixed-width). */
+  grow?: boolean
   type?: "button" | "submit" | "reset"
   ariaLabel?: string
   children: React.ReactNode
 }
 
-function Half({ variant, size, side, href, openInNewTab, prefetch, onClick, disabled, type = "button", ariaLabel, children }: HalfOptions) {
-  const classes = splitHalfVariants({ variant, size, side })
+function Half({ variant, size, side, href, openInNewTab, prefetch, onClick, disabled, grow, type = "button", ariaLabel, children }: HalfOptions) {
+  const classes = cn(splitHalfVariants({ variant, size, side }), grow && "flex-1")
 
   if (href) {
     return (
@@ -183,6 +185,7 @@ const SplitButton = React.forwardRef<HTMLDivElement, SplitButtonProps>(function
         prefetch={prefetch}
         onClick={onClick}
         disabled={disabled || mainDisabled}
+        grow={fullWidth}
         type={type}
         ariaLabel={ariaLabel}
       >

package/src/components/ui/index.ts

@@ -61,6 +61,7 @@ export * from './hover-dropdown'
 export * from '../chat'
 export * from '../layout/list-page-layout'
 export * from '../layout/page-container'
+export * from '../layout/page-header'
 export * from '../layout/page-heading'
 export * from '../layout/page-layout'
 export * from '../layout/article-detail-layout'
@@ -160,5 +161,6 @@ export * from './ticket-attachments-list'
 export * from './ticket-note-card'
 export * from './ticket-notes-section'
 export * from './simple-markdown-renderer'
+export { RichMarkdownRenderer, type RichMarkdownRendererProps } from './rich-markdown-renderer'
 export * from './filter-pill-row'
 

package/src/components/ui/release-changelog-section.tsx

@@ -3,6 +3,7 @@
 import React, { useState, useRef, useEffect } from 'react';
 import { Badge } from './badge';
 import { ChevronDown } from 'lucide-react';
+import { RichMarkdownRenderer } from './rich-markdown-renderer';
 import type { ChangelogEntry } from '../../types/product-release';
 
 interface ReleaseChangelogSectionProps {
@@ -31,7 +32,11 @@ interface ReleaseChangelogSectionProps {
    *  visual taxonomy across catalog and detail. Inherits the title's color
    *  (secondary for normal sections, red for breaking). */
   icon?: React.ReactNode;
-  SimpleMarkdownRenderer: React.ComponentType<{ content: string }>;
+  /** Markdown renderer for each entry's description. Optional — defaults to
+   *  the lib's `RichMarkdownRenderer` so changelog rich-link previews
+   *  (YouTube, OG cards, etc.) work out of the box. Hosts that already
+   *  wrap with a Supabase-aware preset can keep passing their own. */
+  SimpleMarkdownRenderer?: React.ComponentType<{ content: string }>;
 }
 
 // Collapsed height for the preview-first mode. ~120px shows the first
@@ -47,7 +52,7 @@ export function ReleaseChangelogSection({
   defaultCollapsed = true,
   previewFirst = false,
   icon,
-  SimpleMarkdownRenderer
+  SimpleMarkdownRenderer = RichMarkdownRenderer,
 }: ReleaseChangelogSectionProps) {
   const [collapsed, setCollapsed] = useState(collapsible ? defaultCollapsed : false);
   const [previewExpanded, setPreviewExpanded] = useState(false);