@flamingo-stack/openframe-frontend-core 0.0.396 → 0.0.397-snapshot.20260710044003

package/src/components/chat/entity-cards/entity-portrait-card.tsx

@@ -0,0 +1,201 @@
+'use client'
+
+/**
+ * <EntityPortraitCard> — THE portrait (rail/strip) card anatomy, shared by
+ * EVERY entity card's `size="portrait"` density (case study, blog post,
+ * customer interview, program, investor update, onboarding guide, …).
+ *
+ * One rail = one anatomy (2026 card-UI practice): identical zone boxes across
+ * all content types —
+ *   media  : aspect-[1200/630] slot + content-type chip overlay
+ *   title  : fixed 72px zone, 3-line clamp (typography per entity via
+ *            `titleClassName` — e.g. Azeret Mono for programs)
+ *   footer : fixed 60px person zone (author avatar + name + subtitle, with
+ *            the optional bottom-right icon overlay — the case-study MSP
+ *            pattern)
+ * Card surface, padding (p-6/gap-6) and the hover treatment (accent border +
+ * accent shadow) are encoded HERE exactly once, so no per-card drift is
+ * possible. Entity cards only MAP their row onto these props.
+ *
+ * Media rule ("our common way"): the REAL cover always wins. Wide covers
+ * (OG-style 1200×630) fill the slot `object-cover`; a non-wide cover (square
+ * podcast artwork) renders contained on an `useImageEdgeColor` background —
+ * the SAME edge-sampled fill the media/news cards use (OGLinkPreview) — never
+ * a flat filler and never the generic placeholder while a real image exists.
+ * The cover → placeholder → hide resolution is the shared
+ * `useCoverImageFallback` chain (one fallback logic for all entity cards).
+ *
+ * The content-type chip is the common <StatusBadge> and lives ABOVE the title
+ * (an eyebrow inside the title zone), never overlaid on the artwork — branded
+ * covers carry their own marks (Flamingo logo top-left) that an overlay would
+ * collide with.
+ */
+
+import React, { useEffect, useState } from 'react'
+import Image from '../../../embed-shims/next-image'
+import { Card } from '../../ui/card'
+import { StatusBadge } from '../../ui/status-badge'
+import { useImageEdgeColor } from '../../../hooks/ui/use-image-edge-color'
+import { useCoverImageFallback } from './use-cover-image-fallback'
+import { cn } from '../../../utils/cn'
+
+/** Sources narrower than this are "not wide" → contained on the edge-color
+ *  fill. Wide covers are 1200/630 ≈ 1.9; squares are 1.0; 1.3 splits safely. */
+const MIN_WIDE_RATIO = 1.3
+
+export interface EntityPortraitPerson {
+  name: string
+  avatarUrl?: string | null
+  subtitle?: string | null
+  /** Small round overlay on the avatar's bottom-right corner (e.g. MSP icon). */
+  iconOverlayUrl?: string | null
+}
+
+export interface EntityPortraitCardProps {
+  href: string
+  target?: '_blank'
+  rel?: string
+  /** Content-type chip ('Case Study', 'Podcast', …). OMIT to hide the chip —
+   *  single-type rails don't need per-card type identification; only mixed
+   *  rails pass it. */
+  typeLabel?: string
+  imageUrl?: string | null
+  /** Branded wide OG fallback — used when `imageUrl` is missing, errors, or
+   *  isn't wide. */
+  placeholderUrl?: string | null
+  imageAlt: string
+  title: string
+  /** Typography override for the title (entity identity), zone box unchanged. */
+  titleClassName?: string
+  person?: EntityPortraitPerson | null
+  className?: string
+}
+
+export function EntityPortraitCard({
+  href,
+  target,
+  rel,
+  typeLabel,
+  imageUrl,
+  placeholderUrl,
+  imageAlt,
+  title,
+  titleClassName,
+  person,
+  className,
+}: EntityPortraitCardProps) {
+  const { src, onError: onMediaError } = useCoverImageFallback(imageUrl, placeholderUrl)
+  // null = unknown (assume wide until the image reports its natural size).
+  const [isWide, setIsWide] = useState<boolean | null>(null)
+  useEffect(() => {
+    // Re-detect whenever the resolved source changes (prop change OR the
+    // fallback chain advancing to the placeholder).
+    setIsWide(null)
+  }, [src])
+
+  const onMediaLoad = (e: React.SyntheticEvent<HTMLImageElement>) => {
+    const img = e.currentTarget
+    if (img.naturalWidth > 0 && img.naturalHeight > 0) {
+      setIsWide(img.naturalWidth / img.naturalHeight >= MIN_WIDE_RATIO)
+    }
+  }
+
+  // Edge-sampled slot fill for non-wide covers — the SAME hook/fallback the
+  // media/news cards use (og-link-preview.tsx).
+  const edgeColor = useImageEdgeColor(isWide === false ? src : null, 'var(--ods-bg-secondary)')
+
+  return (
+    <a href={href} target={target} rel={rel} className={cn('block h-full', className)} aria-label={`Open ${title}`}>
+      <Card className="bg-ods-card border border-ods-border hover:border-ods-accent hover:shadow-lg hover:shadow-ods-accent/[0.08] transition-all duration-200 p-6 flex flex-col gap-6 overflow-hidden h-full">
+        {/* Media zone — the real cover always wins: wide → cover-fill;
+            non-wide → contained on the edge-color fill (news-card treatment). */}
+        <div
+          className="relative w-full aspect-[1200/630] rounded-sm overflow-hidden bg-ods-bg shrink-0 flex items-center justify-center transition-colors duration-300"
+          style={isWide === false ? { backgroundColor: edgeColor } : undefined}
+        >
+          {src && (
+            <Image
+              src={src}
+              alt={imageAlt}
+              className={cn('w-full h-full', isWide === false ? 'object-contain' : 'object-cover')}
+              sizes="(min-width: 800px) 400px, 100vw"
+              fill
+              unoptimized
+              onLoad={onMediaLoad}
+              onError={onMediaError}
+            />
+          )}
+        </div>
+
+        {/* Title zone — fixed box. Mixed rails: common StatusBadge eyebrow +
+            2-line title (chip lives here, never on the artwork). Single-type
+            rails (no typeLabel): centered 3-line title. */}
+        <div className="h-[72px] flex flex-col justify-center gap-1.5 shrink-0">
+          {typeLabel && (
+            <StatusBadge
+              variant="button"
+              colorScheme="accentBorder"
+              singleLine
+              text={typeLabel}
+              className="self-start"
+            />
+          )}
+          <h3
+            className={cn(
+              'text-h4 leading-6 text-ods-text-primary break-words',
+              typeLabel ? 'line-clamp-2' : 'line-clamp-3',
+              titleClassName,
+            )}
+          >
+            {title}
+          </h3>
+        </div>
+
+        {/* Person/footer zone — fixed box (kept even when empty so every card
+            in a rail shares baselines). */}
+        <div className="h-[60px] flex items-center shrink-0">
+          {person && (
+            <div className="flex items-center gap-3 min-w-0 w-full">
+              <div className="relative shrink-0 w-12 h-12">
+                {person.avatarUrl ? (
+                  <Image
+                    src={person.avatarUrl}
+                    alt={person.name}
+                    className="w-12 h-12 rounded-full object-cover bg-ods-bg border border-ods-border"
+                    width={48}
+                    height={48}
+                    unoptimized
+                  />
+                ) : (
+                  <div className="w-12 h-12 rounded-full bg-ods-bg border border-ods-border flex items-center justify-center">
+                    <span className="text-ods-text-secondary font-medium text-xl">
+                      {person.name.charAt(0).toUpperCase()}
+                    </span>
+                  </div>
+                )}
+                {person.iconOverlayUrl && (
+                  <div className="absolute -bottom-1 -right-1 w-6 h-6 rounded-full bg-ods-text-primary ring-1 ring-ods-bg overflow-hidden flex items-center justify-center">
+                    <Image
+                      src={person.iconOverlayUrl}
+                      alt=""
+                      className="w-full h-full object-cover"
+                      width={24}
+                      height={24}
+                      unoptimized
+                    />
+                  </div>
+                )}
+              </div>
+              <div className="flex flex-col min-w-0">
+                <span className="font-['DM_Sans'] font-bold text-ods-text-primary truncate">{person.name}</span>
+                {person.subtitle && (
+                  <span className="font-['DM_Sans'] text-sm text-ods-text-secondary truncate">{person.subtitle}</span>
+                )}
+              </div>
+            </div>
+          )}
+        </div>
+      </Card>
+    </a>
+  )
+}

package/src/components/chat/entity-cards/index.ts

@@ -16,6 +16,16 @@ export {
   type EntityAuthorCardProps,
 } from './entity-author-card'
 export { BlogImagePlaceholder } from './blog-image-placeholder'
+export {
+  EntityPortraitCard,
+  type EntityPortraitCardProps,
+  type EntityPortraitPerson,
+} from './entity-portrait-card'
+export {
+  useCoverImageFallback,
+  hideOnError,
+  type CoverImageFallback,
+} from './use-cover-image-fallback'
 export { AdminContentCard } from './admin-content-card'
 export { WhatIShippedCard, WhatIShippedCardSkeleton } from './what-i-shipped-card'
 export type { WhatIShippedCardData, WhatIShippedCardProps } from './what-i-shipped-card'
@@ -133,3 +143,11 @@ export {
   type ChatCardRenderOptions,
   type ChatCardDispatchExtras,
 } from './dispatch'
+
+// Program author-ref + video-bites profile adapter — re-exported through the
+// PACKAGE-EXPORTED chat barrel so the hub can value-import them (deep paths
+// into chat/types/* are not in the package exports map and 404 at runtime).
+export {
+  programItemToStripProfile,
+  type ProgramAuthorRef,
+} from '../types/entities/program-types'

package/src/components/chat/entity-cards/investor-update-card.tsx

@@ -11,6 +11,7 @@
 import React from 'react'
 import { Calendar } from 'lucide-react'
 import { AdminContentCard } from './admin-content-card'
+import { EntityPortraitCard } from './entity-portrait-card'
 import { formatInvestorUpdatePeriod, type InvestorUpdate } from '../types/entities/investor-update'
 import { useEntityCardLink } from './use-entity-card-link'
 import { useEntityCardPlaceholder } from './use-entity-card-placeholder'
@@ -38,11 +39,14 @@ export interface InvestorUpdateCardProps {
   targetPlatform?: string | null
   /** OG placeholder URL used when `update.featured_image` is missing. */
   placeholderUrl?: string | null
-  size?: 'default' | 'sm'
+  size?: 'default' | 'sm' | 'portrait'
+  /** Portrait density: render the content-type chip. Mixed rails only; single-type rails pass false. Default true. */
+  showTypeBadge?: boolean
   className?: string
 }
 
-export function InvestorUpdateCardSkeleton({ size = 'default' }: { size?: 'default' | 'sm' }) {
+/** `portrait` shares the default skeleton shape (same zone boxes). */
+export function InvestorUpdateCardSkeleton({ size = 'default' }: { size?: 'default' | 'sm' | 'portrait' }) {
   if (size === 'sm') {
     return (
       <span className={COMPACT_CARD_SKELETON_OUTER}>
@@ -83,6 +87,7 @@ export function InvestorUpdateCard({
   targetPlatform,
   placeholderUrl: placeholderUrlProp,
   size = 'default',
+  showTypeBadge = true,
   className,
 }: InvestorUpdateCardProps) {
   const { target, rel } = useEntityCardLink({
@@ -144,6 +149,27 @@ export function InvestorUpdateCard({
     )
   }
 
+  if (size === 'portrait') {
+    // Rail/strip density — shared <EntityPortraitCard> shell. The reporting
+    // period is the meaningful footer line (no fabricated author — no avatar
+    // renders an initial circle).
+    const periodText = formatInvestorUpdatePeriod(update.period_start, update.period_end)
+    return (
+      <EntityPortraitCard
+        href={href}
+        target={target}
+        rel={rel}
+        typeLabel={showTypeBadge ? 'Investor Update' : undefined}
+        imageUrl={update.featured_image}
+        placeholderUrl={placeholderUrl}
+        imageAlt={update.title ?? 'Investor update'}
+        title={update.title || `Update #${update.update_number ?? '?'}`}
+        person={periodText ? { name: periodText } : null}
+        className={className}
+      />
+    )
+  }
+
   return (
     <a href={href} target={target} rel={rel} className={`block h-full ${className ?? ''}`}>
       <AdminContentCard

package/src/components/chat/entity-cards/onboarding-guide-card.tsx

@@ -24,6 +24,7 @@ import { Clock, ExternalLink, GraduationCap, Play } from 'lucide-react'
 import { cn } from '../../../utils/cn'
 import { BlogImagePlaceholder } from './blog-image-placeholder'
 import { EntityAuthorCard } from './entity-author-card'
+import { EntityPortraitCard } from './entity-portrait-card'
 import { formatDurationMMSS } from '../../../utils/format'
 import type { OnboardingGuide } from '../types/entities/onboarding-guide'
 import { useEntityCardLink } from './use-entity-card-link'
@@ -52,7 +53,10 @@ export interface OnboardingGuideCardProps {
   targetPlatform?: string | null
   /** OG placeholder URL used by the catalog + sm variants when no cover. */
   placeholderUrl?: string | null
-  size?: 'catalog' | 'default' | 'sm'
+  size?: 'catalog' | 'default' | 'sm' | 'portrait'
+  /** Portrait density: render the content-type chip. Mixed rails only; single-type rails pass false. Default true. */
+  showTypeBadge?: boolean
+| 'default' | 'sm' | 'portrait'
   className?: string
 }
 
@@ -169,6 +173,7 @@ export function OnboardingGuideCard({
   targetPlatform,
   placeholderUrl: placeholderUrlProp,
   size = 'default',
+  showTypeBadge = true,
   className,
 }: OnboardingGuideCardProps) {
   const { target, rel } = useEntityCardLink({
@@ -183,6 +188,30 @@ export function OnboardingGuideCard({
     aspect: size === 'sm' ? 'square' : 'wide',
   })
 
+  if (size === 'portrait') {
+    // Rail/strip density — shared <EntityPortraitCard> shell. Same cover
+    // chain as the catalog variant.
+    const coverImage =
+      guide.featured_image ||
+      guide.main_video_thumbnail ||
+      guide.og_image_url ||
+      null
+    return (
+      <EntityPortraitCard
+        href={href}
+        target={target}
+        rel={rel}
+        typeLabel={showTypeBadge ? 'Guide' : undefined}
+        imageUrl={coverImage}
+        placeholderUrl={placeholderUrl}
+        imageAlt={guide.title}
+        title={guide.title}
+        person={guide.section ? { name: guide.section } : null}
+        className={className}
+      />
+    )
+  }
+
   if (size === 'catalog') {
     const coverImage =
       guide.featured_image ||

package/src/components/chat/entity-cards/program-card.tsx

@@ -2,8 +2,18 @@
 
 /**
  * ProgramCard (pure presentation). Generic card for podcasts / webinars /
- * events. Two densities — `default` (vertical detail) and `sm` (compact
- * horizontal for chat-inline).
+ * events. Three densities — `default` (wide horizontal detail, archive
+ * pages), `sm` (compact horizontal for chat-inline), and `portrait`
+ * (vertical rail/strip card).
+ *
+ * `portrait` exists because mixed-content rails MUST share ONE card anatomy
+ * (2026 card-UI practice: a rail mixes content types, never card layouts —
+ * mixing orientations/aspects in one scroller is the anti-pattern). It
+ * renders the SAME three zones as the other portrait entity cards
+ * (CaseStudyCard et al.): wide media slot → fixed 72px title zone → fixed
+ * 60px person/meta footer, p-6 / gap-6. The program's identity lives in the
+ * Azeret Mono title and the date · duration meta line — not in a different
+ * layout.
  *
  * The card writes NO click logic — callers wrap with their own anchor
  * and pass the resolved detail URL via `href`.
@@ -34,16 +44,19 @@ import {
   COMPACT_CARD_TITLE,
   COMPACT_CARD_TITLE_ROW,
 } from '../utils/compact-card-classes'
-import type {
-  BaseProgramItem,
-  ProgramConfig,
-  ProgramMedia,
-  ProgramHost,
+import {
+  programItemToStripProfile,
+  type BaseProgramItem,
+  type ProgramAuthorRef,
+  type ProgramConfig,
+  type ProgramMedia,
+  type ProgramHost,
 } from '../types/entities/program-types'
+import { EntityPortraitCard } from './entity-portrait-card'
 import { useEntityCardLink } from './use-entity-card-link'
 import { useEntityCardPlaceholder } from './use-entity-card-placeholder'
 
-type CardSize = 'default' | 'sm'
+type CardSize = 'default' | 'sm' | 'portrait'
 
 /**
  * Format a Date with date-fns pinned to UTC. `date-fns` `format()` reads the
@@ -115,6 +128,8 @@ export interface ProgramCardProps<T extends BaseProgramItem> {
   media?: ProgramMedia[]
   renderMeta?: (item: T) => React.ReactNode
   size?: CardSize
+  /** Portrait density: render the content-type chip. Mixed rails only; single-type rails pass false. Default true. */
+  showTypeBadge?: boolean
   /** Detail URL resolved by the caller. */
   href: string
   /** When `_blank`, opens in a new tab. Set by chat dispatch via
@@ -212,6 +227,7 @@ export function ProgramCard<T extends BaseProgramItem>({
   media = [],
   renderMeta,
   size = 'default',
+  showTypeBadge = true,
   href,
   target: targetProp,
   rel: relProp,
@@ -237,24 +253,60 @@ export function ProgramCard<T extends BaseProgramItem>({
   const accentColor = 'var(--color-accent-primary)'
   const isScheduled = 'status' in item && (item as any).status === 'scheduled'
 
-  if (size === 'sm') {
-    const itemDate = (() => {
-      try { return formatUtc(new Date(item.date), 'MMM d, yyyy') } catch { return '' }
-    })()
-    const compactCover = coverImage || placeholderUrl || null
-    let typeMeta: string | null = null
+  // Compact per-type meta (duration / location / start time) — shared by the
+  // `sm` and `portrait` densities.
+  const compactTypeMeta = (): string | null => {
     if (config.type === 'podcast' && 'duration_seconds' in item && !isScheduled) {
       const dur = (item as any).duration_seconds
-      if (typeof dur === 'number' && dur > 0) typeMeta = formatDurationCompact(dur)
+      if (typeof dur === 'number' && dur > 0) return formatDurationCompact(dur)
     } else if (config.type === 'event' && 'location_name' in item) {
       const loc = (item as any).location_name
-      if (typeof loc === 'string' && loc.trim().length > 0) typeMeta = loc
+      if (typeof loc === 'string' && loc.trim().length > 0) return loc
     } else if (config.type === 'webinar' && 'start_at' in item) {
       const w = item as any
       const time = formatTimeWithTimezone(w.start_at, w.timezone ?? null)
       const dur = formatDurationFromRange(w.start_at, w.end_at)
-      typeMeta = dur ? `${time} · ${dur}` : time
+      return dur ? `${time} · ${dur}` : time
     }
+    return null
+  }
+  const compactDate = (() => {
+    try { return formatUtc(new Date(item.date), 'MMM d, yyyy') } catch { return '' }
+  })()
+
+  if (size === 'portrait') {
+    // Rail/strip density — mapped onto the shared <EntityPortraitCard> shell
+    // (media aspect-[1200/630] → h-[72px] title → h-[60px] footer, p-6/gap-6).
+    // Person = author-first via programItemToStripProfile (author → primary
+    // host); the date · duration meta line fills the subtitle when the
+    // profile has no job title.
+    const profile = programItemToStripProfile(item as { author?: ProgramAuthorRef | null; hosts?: ProgramHost[] | null })
+    const dateMeta = [compactDate, compactTypeMeta()].filter(Boolean).join(' · ')
+    return (
+      <EntityPortraitCard
+        href={href}
+        target={target}
+        rel={rel}
+        typeLabel={showTypeBadge ? config.labels.singular : undefined}
+        imageUrl={coverImage}
+        placeholderUrl={placeholderUrl}
+        imageAlt={item.title}
+        title={item.title}
+        titleClassName="font-['Azeret_Mono'] font-semibold text-lg leading-6"
+        person={
+          profile
+            ? { name: profile.name, avatarUrl: profile.avatarUrl, subtitle: profile.subtitle || dateMeta }
+            : { name: config.labels.singular, subtitle: dateMeta }
+        }
+        className={className}
+      />
+    )
+  }
+
+  if (size === 'sm') {
+    const itemDate = compactDate
+    const compactCover = coverImage || placeholderUrl || null
+    const typeMeta = compactTypeMeta()
     const subtitleParts = [itemDate, typeMeta, config.labels?.singular].filter(
       (s): s is string => typeof s === 'string' && s.length > 0,
     )

package/src/components/chat/entity-cards/use-cover-image-fallback.ts

@@ -0,0 +1,50 @@
+'use client'
+
+/**
+ * THE common cover-image fallback chain for entity cards:
+ *   real cover → branded placeholder → nothing (hide the media element).
+ *
+ * One hook so no card hand-rolls its own `imageError` state / `displayImage`
+ * ternary (they drift: the pre-hook BlogCard chain couldn't recover from a
+ * FAILING placeholder, EntityPortraitCard duplicated the same logic with
+ * different state). Cards wire `src` + `onError` and render their own
+ * empty-state when `src` is null.
+ *
+ * Implementation note: state is the SET of candidate URLs that failed, and
+ * `src` is derived — so a prop change (new cover URL) re-resolves instantly
+ * with no reset effect, and a URL that failed once isn't retried in a loop.
+ */
+
+import { useCallback, useState, type SyntheticEvent } from 'react'
+
+export interface CoverImageFallback {
+  /** Resolved source: first non-failed of [imageUrl, placeholderUrl], else null. */
+  src: string | null
+  /** Wire to the media element's `onError`. */
+  onError: () => void
+}
+
+export function useCoverImageFallback(
+  imageUrl?: string | null,
+  placeholderUrl?: string | null,
+): CoverImageFallback {
+  const [failed, setFailed] = useState<ReadonlySet<string>>(() => new Set())
+
+  const src =
+    imageUrl && !failed.has(imageUrl) ? imageUrl
+    : placeholderUrl && !failed.has(placeholderUrl) ? placeholderUrl
+    : null
+
+  const onError = useCallback(() => {
+    if (!src) return
+    setFailed(prev => new Set(prev).add(src))
+  }, [src])
+
+  return { src, onError }
+}
+
+/** Fallback for cards with NO placeholder chain (compact/sm image slots):
+ *  a broken cover simply disappears, leaving the slot's background. */
+export const hideOnError = (e: SyntheticEvent<HTMLImageElement>) => {
+  ;(e.currentTarget as HTMLImageElement).style.display = 'none'
+}

package/src/components/chat/types/entities/program-types.ts

@@ -17,6 +17,10 @@
  */
 
 import type { ReactNode } from 'react';
+import {
+  toStripProfile,
+  type VideoBiteStripProfile,
+} from '../../../features/video-bites-shared';
 
 // ============================================================================
 // HOST TYPES
@@ -34,6 +38,36 @@ export interface ProgramHost {
   role?: string; // e.g., "Host", "Speaker", "Guest"
 }
 
+/**
+ * Client-safe author subset hydrated onto program items from the entity's
+ * `author_id → profiles` FK join (podcast episodes / webinars). Deliberately
+ * excludes `email` — this shape is serialized into public payloads.
+ */
+export interface ProgramAuthorRef {
+  id?: string | null;
+  full_name?: string | null;
+  avatar_url?: string | null;
+  job_title?: string | null;
+}
+
+/**
+ * Video-bites overlay profile for a program item: internal author first
+ * (`author_id → profiles`), then the provider-synced primary host (Livestorm
+ * speakers / Podbean hosts). Host `role` is a raw provider enum (e.g.
+ * `team_member`) — never display copy, so it is not used as the subtitle.
+ * Routes through `toStripProfile` (the SSoT — null on missing names).
+ */
+export function programItemToStripProfile(item: {
+  author?: ProgramAuthorRef | null;
+  hosts?: ProgramHost[] | null;
+}): VideoBiteStripProfile | null {
+  const fromAuthor = toStripProfile(item.author);
+  if (fromAuthor) return fromAuthor;
+  const host = Array.isArray(item.hosts) ? item.hosts[0] : null;
+  if (!host?.name) return null;
+  return toStripProfile({ full_name: host.name, avatar_url: host.avatar_url ?? null });
+}
+
 // ============================================================================
 // DATABASE ROW TYPES
 // ============================================================================