@flamingo-stack/openframe-frontend-core 0.0.240 → 0.0.242

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.240",
+  "version": "0.0.242",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/related-content/related-content-section.tsx

@@ -52,7 +52,7 @@ import {
 import type { ContentRef, ContentRefWithReason } from '../../types/content-ref';
 import { useSelfFetch } from '../../hooks/use-self-fetch';
 import { extractItems } from '../../utils/extract-items';
-import { buildListUrl as libBuildListUrl } from '../../utils/list-url';
+import { buildListUrl as libBuildListUrl, canonicalContentRefType } from '../../utils/list-url';
 import { buildSuggestionUrl } from '../../utils/suggestion-url';
 import { decideNewTab } from '../chat/utils/decide-new-tab';
 // DEEP card imports — NOT the `../chat` barrel (the barrel statically reaches
@@ -158,7 +158,10 @@ function renderSkeletonForType(
     case 'investor_update':
       return <InvestorUpdateCardSkeleton size={legacySize} />;
     case 'onboarding_guide':
-      return <OnboardingGuideCardSkeleton size={legacySize} />;
+      // The rich catalog variant (hero + author grid, clamped description) —
+      // the step-numbered 'default' variant is for the guide detail page's
+      // "More in section" rail, not this full-width row.
+      return <OnboardingGuideCardSkeleton size={size === 'sm' ? 'sm' : 'catalog'} />;
     case 'marketing_campaign':
       return adminCampaignCard ? <adminCampaignCard.Skeleton size={legacySize} /> : null;
     case 'roadmap_item':
@@ -267,7 +270,9 @@ function CardForType({
     case 'investor_update':
       return <InvestorUpdateCard update={item} size={legacySize} href={href} targetPlatform={targetPlatform} placeholderUrl={placeholderUrl} {...anchorAttrs} />;
     case 'onboarding_guide':
-      return <OnboardingGuideCard guide={item} size={legacySize} href={href} targetPlatform={targetPlatform} placeholderUrl={placeholderUrl} {...anchorAttrs} />;
+      // Catalog variant (see skeleton note) — full-width rich card with a
+      // line-clamped description instead of the step-numbered rail card.
+      return <OnboardingGuideCard guide={item} size={size === 'sm' ? 'sm' : 'catalog'} href={href} targetPlatform={targetPlatform} placeholderUrl={placeholderUrl} {...anchorAttrs} />;
     case 'marketing_campaign':
       return adminCampaignCard ? <adminCampaignCard.Card campaign={item} /> : null;
     case 'roadmap_item':
@@ -441,9 +446,15 @@ export interface RelatedContentSectionProps {
    *  `contentRefs` is provided. */
   entityType?: string;
   entityId?: number | string;
-  /** Maps to the suggestion API's `count` param. Absent → param not sent
+  /** Maps to the suggestion API's `count` param — the PER-TYPE fill target
+   *  for every candidate type EXCEPT the host's own. Absent → param not sent
    *  (server default applies). */
   minResults?: number;
+  /** Maps to the suggestion API's `sameTypeCount` param — the budget for the
+   *  candidate type MATCHING the host's own `entityType` (same-type boost:
+   *  a blog post's rail leads with more blog posts). Absent → param not
+   *  sent (host's type uses the server's `count`). */
+  sameTypeMinResults?: number;
   /** SSR hydrate for suggestion mode — the server page ran the engine and
    *  drills the refs here; the first client fetch is skipped (useSelfFetch
    *  initialData contract). */
@@ -493,6 +504,7 @@ export function RelatedContentSection({
   entityType,
   entityId,
   minResults,
+  sameTypeMinResults,
   initialItems,
   title = 'Related Content',
   columns = 2,
@@ -517,6 +529,7 @@ export function RelatedContentSection({
           entityId,
           count: minResults,
           extraParams: {
+            sameTypeCount: sameTypeMinResults !== undefined ? String(sameTypeMinResults) : undefined,
             excludeTypes: excludeTypes && excludeTypes.length > 0 ? excludeTypes.join(',') : undefined,
           },
         })
@@ -558,7 +571,17 @@ export function RelatedContentSection({
   // Registered types in CONTENT_REF_GROUPS order, then any unregistered
   // types appended (same shape the investor-email builder uses — both
   // consume `orderContentRefTypes` so cross-surface ordering matches).
-  const orderedTypes = orderContentRefTypes(Object.keys(grouped));
+  // SAME-TYPE FIRST: when a host entityType is known (suggestion / SSR
+  // modes), its own content-type group is hoisted to the top — a blog
+  // post's rail leads with blog posts. Rail group keys are compared via
+  // the shared alias canonicalizer (blog_post_existing ↔ blog_post).
+  let orderedTypes = orderContentRefTypes(Object.keys(grouped));
+  if (entityType) {
+    const sameType = orderedTypes.filter((t) => canonicalContentRefType(t) === entityType);
+    if (sameType.length > 0) {
+      orderedTypes = [...sameType, ...orderedTypes.filter((t) => canonicalContentRefType(t) !== entityType)];
+    }
+  }
 
   return (
     <div className="space-y-8">

package/src/utils/content-ref-groups.ts

@@ -52,7 +52,7 @@ export const CONTENT_REF_GROUPS: Record<string, ContentRefGroupConfig> = {
   event:               { label: 'Events',              order: 6, layout: 'list', gridSize: 'default' },
   blog_post_existing:  { label: 'Blog Posts',          order: 7, layout: 'grid', gridSize: 'default' },
   customer_interview:  { label: 'Customer Interviews', order: 8, layout: 'grid', gridSize: 'default' },
-  onboarding_guide:    { label: 'Onboarding Guides',   order: 9, layout: 'grid', gridSize: 'default' },
+  onboarding_guide:    { label: 'Onboarding Guides',   order: 9, layout: 'list', gridSize: 'default' },
 }
 
 /** Human-readable label for a content_ref `type`. Returns null when the type

package/src/utils/index.ts

@@ -235,7 +235,7 @@ export {
 // delegate here (byte-parity test guards the migration); embedders wire
 // `endpoints.buildListUrl = (t, ids) => buildListUrl(t, ids, '/content')`.
 // Pure + server-safe (the hub imports it server-side from this barrel).
-export { buildListUrl } from './list-url'
+export { buildListUrl, canonicalContentRefType } from './list-url'
 
 // Content-ref group registry (labels/order/layout per rail type) + list-API
 // response normalizers + the shared suggestion-fetch URL composer — all

package/src/utils/list-url.ts

@@ -37,6 +37,15 @@
  */
 const ALIASES: Record<string, string> = { blog_post_existing: 'blog_post' }
 
+/** 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 function canonicalContentRefType(contentRefType: string): string {
+  return ALIASES[contentRefType] ?? contentRefType
+}
+
 /**
  * One builder per fetch-mode `contentRefType`, keyed by the canonical
  * `documentType`. Each body is copied VERBATIM from the matching hub