@flamingo-stack/openframe-frontend-core 0.0.239 → 0.0.241

package/dist/utils/list-url.d.ts

@@ -27,6 +27,12 @@
  * Pure + server-safe (no React, no browser APIs) so the hub's server-side
  * mappers can import it from `@flamingo-stack/openframe-frontend-core/utils`.
  */
+/** Resolve a ContentRef rail-vocab type to its canonical `documentType`
+ *  (registry vocabulary) — `blog_post_existing` → `blog_post`, everything
+ *  else passes through. Exported so consumers comparing rail group keys to
+ *  registry entityTypes (e.g. the related-content rail's same-type-first
+ *  ordering) share THIS alias map instead of re-declaring it. */
+export declare function canonicalContentRefType(contentRefType: string): string;
 /**
  * Build a list-API URL that returns full rows for the given ids, or `null`
  * when the type has no list endpoint (the caller skips fetching rather than

package/dist/utils/list-url.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"list-url.d.ts","sourceRoot":"","sources":["../../src/utils/list-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAqCH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,IAAI,SAAK,GAAG,MAAM,GAAG,IAAI,CAa5F"}
+{"version":3,"file":"list-url.d.ts","sourceRoot":"","sources":["../../src/utils/list-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAWH;;;;iEAIiE;AACjE,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAEtE;AA4BD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,IAAI,SAAK,GAAG,MAAM,GAAG,IAAI,CAa5F"}

package/dist/utils/suggestion-url.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared fetch-URL composer for the two suggestion sections (FaqSection +
+ * RelatedContentSection) — ONE owner of the entityType/entityId/count query
+ * shape so the sections can never drift. Pure + server-safe.
+ *
+ * Byte-parity contract with the original `buildFaqsUrl`: when only
+ * entityType/entityId are set, the param order is `entityType`, `entityId`;
+ * with nothing set, the bare `path` is returned (no `?`).
+ */
+export interface SuggestionUrlOptions {
+    /** Fetch-URL prefix for third-party embeds / reverse proxies
+     *  ('' = same-origin relative). */
+    apiBaseUrl?: string;
+    /** Both required together for entity scope; partial → bare path. */
+    entityType?: string;
+    entityId?: number | string;
+    /** Maps to the server's `count` param. Undefined → param not sent
+     *  (server default applies). */
+    count?: number;
+    /** Extra query params appended after the shared trio (e.g. the
+     *  related-content `excludeTypes` deny-list). Empty/undefined values
+     *  are skipped. */
+    extraParams?: Record<string, string | undefined>;
+}
+export declare function buildSuggestionUrl(path: string, opts?: SuggestionUrlOptions): string;
+//# sourceMappingURL=suggestion-url.d.ts.map

package/dist/utils/suggestion-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggestion-url.d.ts","sourceRoot":"","sources":["../../src/utils/suggestion-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,WAAW,oBAAoB;IACnC;uCACmC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IAC1B;oCACgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;uBAEmB;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;CACjD;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,oBAAyB,GAAG,MAAM,CAaxF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.239",
+  "version": "0.0.241",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",
@@ -60,6 +60,12 @@
       "require": "./dist/components/faq/index.cjs",
       "default": "./dist/components/faq/index.js"
     },
+    "./components/related-content": {
+      "types": "./dist/components/related-content/index.d.ts",
+      "import": "./dist/components/related-content/index.js",
+      "require": "./dist/components/related-content/index.cjs",
+      "default": "./dist/components/related-content/index.js"
+    },
     "./components/faq/json-ld": {
       "types": "./dist/components/faq/json-ld.d.ts",
       "import": "./dist/components/faq/json-ld.js",

package/src/components/chat/hooks/use-chat-card-item.ts

@@ -22,6 +22,7 @@
 import { useQuery } from '@tanstack/react-query'
 import { useRequiredChatRuntime } from '../../../contexts/chat-runtime-context'
 import { embedAuthedFetch } from '../../../utils/embed-authed-fetch'
+import { extractItems, extractItemId } from '../../../utils/extract-items'
 
 export interface UseChatCardItemResult<T = unknown> {
   item: T | undefined
@@ -29,44 +30,8 @@ export interface UseChatCardItemResult<T = unknown> {
   isError: boolean
 }
 
-/** Extract the items array from each endpoint's response shape (some
- *  return `{ items }`, others `{ posts }`, etc.). Single normalization
- *  point — callers always read `Item[]`. */
-function extractItems(data: unknown): unknown[] {
-  if (!data || typeof data !== 'object') return []
-  const obj = data as Record<string, unknown>
-  if (Array.isArray(obj.items)) return obj.items
-  if (Array.isArray(obj.posts)) return obj.posts
-  if (Array.isArray(obj.campaigns)) return obj.campaigns
-  if (Array.isArray(obj.completed) || Array.isArray(obj.inProgress)) {
-    // Delivery endpoint splits into completed/inProgress arrays — flatten.
-    const completed = Array.isArray(obj.completed) ? obj.completed : []
-    const inProgress = Array.isArray(obj.inProgress) ? obj.inProgress : []
-    return [...completed, ...inProgress]
-  }
-  if (Array.isArray(obj.data)) return obj.data
-  if (Array.isArray(data)) return data
-  return []
-}
-
-/** Extract a stable id from a fetched item — different shapes use
- *  `id` vs `external_id`. Used by the chat loader to match the fetched
- *  array element back to the marker's id. */
-function extractItemId(type: string, item: unknown): string | null {
-  if (!item || typeof item !== 'object') return null
-  const obj = item as Record<string, unknown>
-  if (type === 'roadmap_item' || type === 'delivery_item' || type === 'internal_task') {
-    const ext = obj.external_id
-    if (typeof ext === 'string') return ext
-  }
-  // RoadmapItem-shaped responses use `id` to carry the external_id; the
-  // mapper renames external_id→id at the API boundary. Treat both id and
-  // external_id as primary-key candidates for these clickup-backed types.
-  const id = obj.id
-  if (typeof id === 'string') return id
-  if (typeof id === 'number') return String(id)
-  return null
-}
+// `extractItems` / `extractItemId` hoisted to `src/utils/extract-items.ts`
+// (shared with the related-content rail — react-query-free home).
 
 export function useChatCardItem<T = unknown>(
   type: string,

package/src/components/chat/types/entities/content-ref.ts

@@ -1,23 +1,7 @@
 /**
- * ContentRef — the unified link/embed shape stored in JSONB columns
- * across investor updates, performance baselines, and any other entity
- * that surfaces "related content" rails.
- *
- * Lifted from `lib/data/investor-update-utils-shared.ts` in the hub
- * (the server-side data utils in the same file stay hub-side; only the
- * TYPE moves here).
+ * RELOCATED — the canonical `ContentRef` now lives at `src/types/content-ref.ts`
+ * (server-safe home, shared by the related-content rail + chat entities).
+ * This stub keeps the chat entities barrel + `entities/investor-update.ts`
+ * compiling unchanged. One definition package-wide.
  */
-
-export interface ContentRef {
-  type: string;
-  id: string;
-  slug: string;
-  url: string;
-  targetPlatform?: string | null;
-  title: string;
-  summary?: string;
-  image_url?: string;
-  image_bg_color?: string;
-  visibility: 'public' | 'internal';
-  display_order: number;
-}
+export type { ContentRef, ContentRefWithReason } from '../../../../types/content-ref';

package/src/components/chevron-button.tsx

@@ -10,6 +10,8 @@ interface ChevronButtonProps {
   backgroundColor?: string;
   borderColor?: string;
   onClick?: (e: React.MouseEvent) => void;
+  /** Forwarded to the inner <button> for assistive tech. */
+  'aria-label'?: string;
 }
 
 export function ChevronButton({
@@ -18,7 +20,8 @@ export function ChevronButton({
   size = 'icon',
   backgroundColor = 'transparent',
   borderColor = 'transparent',
-  onClick
+  onClick,
+  'aria-label': ariaLabel,
 }: ChevronButtonProps) {
   const [isHovered, setIsHovered] = React.useState(false);
 
@@ -37,6 +40,7 @@ export function ChevronButton({
       variant="transparent"
       size="icon"
       onClick={onClick}
+      aria-label={ariaLabel}
       onMouseEnter={() => setIsHovered(true)}
       onMouseLeave={() => setIsHovered(false)}
       className={cn(

package/src/components/faq/faq-section.tsx

@@ -1,10 +1,11 @@
 "use client"
 
-import React from 'react'
+import React, { useMemo } from 'react'
 import type { Faq } from '../../types/faq'
 import { FaqAccordion, type FaqItem } from '../faq-accordion'
 import { useSelfFetch } from '../../hooks/use-self-fetch'
-import { buildFaqJsonLdFromFaqs, type FaqSchemaOptions } from './faq-json-ld'
+import { buildSuggestionUrl } from '../../utils/suggestion-url'
+import { buildFaqJsonLdFromFaqs, type FaqSchemaOptions } from './json-ld'
 
 export interface FaqSectionProps {
   /**
@@ -28,16 +29,26 @@ export interface FaqSectionProps {
   /** Overrides for the JSON-LD's name/description/url. */
   jsonLd?: FaqSchemaOptions
   className?: string
+  /** Maps to /api/faqs `?count=` (the 5-tier fill target). Absent → param
+   *  not sent (server default applies). */
+  minResults?: number
+  /** Fetch-URL prefix for third-party embeds / reverse proxies
+   *  ('' = same-origin relative). */
+  apiBaseUrl?: string
 }
 
 const DEFAULT_HEADING_TEXT = 'Frequently Asked Questions'
 
-function buildFaqsUrl(entityType?: string, entityId?: number | string): string {
-  if (!entityType || entityId === undefined || entityId === null || entityId === '') {
-    return '/api/faqs'
-  }
-  const qs = new URLSearchParams({ entityType, entityId: String(entityId) })
-  return `/api/faqs?${qs.toString()}`
+/** URL composition shared with RelatedContentSection (`buildSuggestionUrl`)
+ *  — byte-identical to the historical `buildFaqsUrl` output when
+ *  `minResults`/`apiBaseUrl` are absent. */
+function buildFaqsUrl(
+  entityType?: string,
+  entityId?: number | string,
+  minResults?: number,
+  apiBaseUrl = '',
+): string {
+  return buildSuggestionUrl('/api/faqs', { apiBaseUrl, entityType, entityId, count: minResults })
 }
 
 function groupBySection(faqs: Faq[]): Array<{ section: string | null; items: FaqItem[] }> {
@@ -60,7 +71,7 @@ function groupBySection(faqs: Faq[]): Array<{ section: string | null; items: Faq
 function FaqSkeleton() {
   return (
     <div className="space-y-8 animate-pulse">
-      <div className="h-[48px] md:h-[56px] w-2/3 rounded bg-ods-border" />
+      <div className="h-12 md:h-14 w-2/3 rounded bg-ods-border" />
       <div className="rounded-3xl border border-ods-border overflow-hidden bg-ods-card divide-y divide-ods-border w-full">
         {Array.from({ length: 8 }).map((_, idx) => (
           <div key={idx} className="flex items-center justify-between px-6 md:px-8 py-6">
@@ -97,9 +108,16 @@ export function FaqSection({
   emitJsonLd = false,
   jsonLd,
   className,
+  minResults,
+  apiBaseUrl = '',
 }: FaqSectionProps) {
-  const url = buildFaqsUrl(entityType, entityId)
-  const initialData = initialFaqs ? { faqs: initialFaqs } : undefined
+  const url = buildFaqsUrl(entityType, entityId, minResults, apiBaseUrl)
+  // Memoized — useSelfFetch re-syncs on [initialData]; a fresh per-render
+  // wrapper object would setState-loop under re-rendering parents.
+  const initialData = useMemo<FaqsResponse | undefined>(
+    () => (initialFaqs ? { faqs: initialFaqs } : undefined),
+    [initialFaqs],
+  )
   const { data, isLoading, error } = useSelfFetch<FaqsResponse>(url, { initialData })
 
   const faqs = data?.faqs ?? []
@@ -116,7 +134,24 @@ export function FaqSection({
     return null
   }
 
+  // Embedded mode, zero FAQs after load: render nothing — an embedded host
+  // page (blog/case-study detail) must not show an empty section shell.
+  // The standalone /faqs page (heading set) keeps its existing behavior.
+  if (!isLoading && !error && faqs.length === 0 && !showHeading) {
+    return null
+  }
+
   if (isLoading && faqs.length === 0) {
+    // Embedded mode renders skeletons WITHOUT the standalone page shell —
+    // a host detail page already provides <main> + gutters; nesting them
+    // here would emit invalid markup and double padding.
+    if (!showHeading) {
+      return (
+        <div className={className}>
+          <FaqSkeleton />
+        </div>
+      )
+    }
     return (
       <main className={className ?? 'bg-ods-bg'}>
         <div className="max-w-[1920px] px-6 md:px-20 py-6 md:py-10 mx-auto">
@@ -136,23 +171,33 @@ export function FaqSection({
 
   const schema = emitJsonLd ? buildFaqJsonLdFromFaqs(faqs, jsonLd) : null
 
+  const groupNodes = groups.map(({ section, items }) => (
+    <div key={section || 'default'} className="space-y-4">
+      {section && (
+        <h2 className="text-h2 tracking-[-0.04em] text-ods-text-primary mb-3 md:mb-4">
+          {section}
+        </h2>
+      )}
+      <FaqAccordion items={items} />
+    </div>
+  ))
+
+  // Embedded mode (heading === null): no <main> page shell, no page gutters —
+  // the host page owns layout. Standalone mode keeps the historical markup.
+  const body = showHeading ? (
+    <main className={className ?? 'bg-ods-bg'}>
+      <div className="max-w-[1920px] px-6 md:px-20 py-6 md:py-10 mx-auto space-y-10">
+        {headingNode}
+        {groupNodes}
+      </div>
+    </main>
+  ) : (
+    <section className={className ?? 'space-y-10'}>{groupNodes}</section>
+  )
+
   return (
     <>
-      <main className={className ?? 'bg-ods-bg'}>
-        <div className="max-w-[1920px] px-6 md:px-20 py-6 md:py-10 mx-auto space-y-10">
-          {showHeading && headingNode}
-          {groups.map(({ section, items }) => (
-            <div key={section || 'default'} className="space-y-4">
-              {section && (
-                <h2 className="text-h2 tracking-[-0.04em] text-ods-text-primary mb-3 md:mb-4">
-                  {section}
-                </h2>
-              )}
-              <FaqAccordion items={items} />
-            </div>
-          ))}
-        </div>
-      </main>
+      {body}
       {schema && (
         <script
           type="application/ld+json"

package/src/components/faq-accordion.tsx

@@ -79,8 +79,9 @@ export function FaqAccordion({ items, defaultOpenIds = [] }: FaqAccordionProps)
               <h3>
                 {item.question}
               </h3>
-              <div className="flex-shrink-0" aria-label={isOpen ? 'Collapse question' : 'Expand question'}>
+              <div className="flex-shrink-0">
                 <ChevronButton
+                  aria-label={isOpen ? 'Collapse question' : 'Expand question'}
                   size="md"
                   isExpanded={isOpen}
                   backgroundColor="transparent"

package/src/components/index.ts

@@ -26,6 +26,7 @@ export * from './faq-accordion'
 // dedicated server-safe subpath "./components/faq/json-ld" (built without the
 // client banner under the server/universal block of tsup.config.ts).
 export * from './faq'
+export * from './related-content'
 export * from './filter-chip'
 export * from './footer'
 export * from './unified-filter-logic'

package/src/components/related-content/index.ts

@@ -0,0 +1,9 @@
+// CLIENT subpath barrel — `@flamingo-stack/openframe-frontend-core/components/related-content`
+export {
+  RelatedContentSection,
+  type RelatedContentSectionProps,
+  type CardLinkProvider,
+  type CardLinkProviderProps,
+  type CardLinkAnchorProps,
+  type AdminCampaignCardSlot,
+} from './related-content-section'