@flamingo-stack/openframe-frontend-core 0.0.387 → 0.0.388-snapshot.20260709030118

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.387",
+  "version": "0.0.388-snapshot.20260709030118",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",
@@ -120,6 +120,12 @@
       "require": "./dist/components/features/mux-origins.cjs",
       "default": "./dist/components/features/mux-origins.js"
     },
+    "./components/features/video-bites-shared": {
+      "types": "./dist/components/features/video-bites-shared.d.ts",
+      "import": "./dist/components/features/video-bites-shared.js",
+      "require": "./dist/components/features/video-bites-shared.cjs",
+      "default": "./dist/components/features/video-bites-shared.js"
+    },
     "./components/toast": {
       "types": "./dist/components/toast/index.d.ts",
       "import": "./dist/components/toast/index.js",

package/src/components/features/entity-video-section.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { ComponentType } from 'react';
+import React, { ComponentType } from 'react';
 import {
   Tabs,
   TabsList,
@@ -9,7 +9,8 @@ import {
 } from '../ui/tabs';
 import type { VideoTeaser } from '../../types/video-processing';
 import { Video } from './video';
-import { VideoBitesDisplay } from './video-bites-display';
+import { VideoBitesStrip, type VideoBiteStripItem } from './video-bites-strip';
+import { DEFAULT_VIDEO_BITES_TITLE, type VideoBiteStripProfile } from './video-bites-shared';
 import { SECTION_HEADING_CLASS } from '../layout/page-heading';
 
 /**
@@ -47,10 +48,20 @@ export interface EntityVideoSectionProps {
   videoSummary?: string | null;
   /** Video bites/teasers array. */
   videoBites?: VideoTeaser[];
-  /** Title for the video bites section. */
+  /** Title for the video bites section. Default: 'Key Moments' (unified). */
   bitesTitle?: string;
   /** Whether to filter bites to published only. */
   filterPublishedBites?: boolean;
+  /** Section-level profile shown in the strip's hover overlay. */
+  bitesProfile?: VideoBiteStripProfile | null;
+  /** Navigation target for the strip's overlay footer (the origin entity). */
+  bitesHref?: string;
+  /** Custom node between the bites heading and the strip (description slot). */
+  bitesHeaderSlot?: React.ReactNode;
+  /** Navigation fallback for bites without their own href/onNavigate. */
+  onBiteNavigate?: (bite: VideoBiteStripItem, index: number) => void;
+  /** Marquee auto-scroll for the bites strip. Default true. */
+  bitesAutoScroll?: boolean;
   /** Markdown renderer component injected by the host app. */
   MarkdownRenderer?: ComponentType<MarkdownRendererProps>;
   /**
@@ -73,8 +84,13 @@ export function EntityVideoSection({
   title = 'Video',
   videoSummary,
   videoBites,
-  bitesTitle = 'Video Highlights',
+  bitesTitle = DEFAULT_VIDEO_BITES_TITLE,
   filterPublishedBites = true,
+  bitesProfile = null,
+  bitesHref,
+  bitesHeaderSlot,
+  onBiteNavigate,
+  bitesAutoScroll = true,
   MarkdownRenderer,
   srtContent,
   captionsUrl,
@@ -165,10 +181,15 @@ export function EntityVideoSection({
       )}
 
       {videoBites && videoBites.length > 0 && (
-        <VideoBitesDisplay
+        <VideoBitesStrip
           bites={videoBites}
           title={bitesTitle}
           filterPublished={filterPublishedBites}
+          profile={bitesProfile}
+          href={bitesHref}
+          headerSlot={bitesHeaderSlot}
+          onBiteNavigate={onBiteNavigate}
+          autoScroll={bitesAutoScroll}
         />
       )}
     </>

package/src/components/features/index.ts

@@ -52,11 +52,14 @@ export * from './tags-selector'
 export * from './warning-block'
 // Unified video primitives — single source of truth across all platforms.
 // `<Video>` replaces the deleted `<VideoPlayer>` + `<YouTubeEmbed>` pair;
-// `<EntityVideoSection>` + `<VideoBitesDisplay>` are the public detail-page
-// wrappers; `video-ratio-tabs` exports the aspect-ratio grouping primitives
-// shared by the public bites grid and the admin editors.
+// `<EntityVideoSection>` + `<VideoBitesStrip>` are the public detail-page
+// wrappers (`<VideoBitesDisplay>` is a deprecated shim over the strip);
+// `video-ratio-tabs` keeps the aspect-ratio primitives (tabs/grid = admin-only);
+// `video-bites-shared` is the SERVER-SAFE leaf (also its own published subpath).
 export * from './video'
 export * from './video-ratio-tabs'
+export * from './video-bites-shared'
+export * from './video-bites-strip'
 export * from './video-bites-display'
 export * from './entity-video-section'
 export * from './use-video-warmup'

package/src/components/features/video-bites-display.tsx

@@ -1,77 +1,22 @@
 "use client";
 
-import React, { useMemo } from 'react';
-import { Card } from '../ui/card';
-import { useNearViewport } from '../../hooks/use-near-viewport';
+import React from 'react';
 import type { VideoTeaser } from '../../types/video-processing';
-import { Video } from './video';
-import { SECTION_HEADING_CLASS } from '../layout/page-heading';
-import {
-  RatioTabs,
-  groupByAspectRatio,
-  detectAspectRatio,
-  ratioToCategory,
-  RATIO_DISPLAY_GRID_CLASS,
-  type VideoTeaserWithRatio,
-  type RatioCategory,
-} from './video-ratio-tabs';
+import { VideoBitesStrip } from './video-bites-strip';
+import { DEFAULT_VIDEO_BITES_TITLE } from './video-bites-shared';
 
 /**
- * <VideoBitesDisplay> — public grid of short video bites grouped by
- * aspect ratio.
+ * @deprecated Transitional shim — use `<VideoBitesStrip>` directly.
  *
- * Goes through `<Video>` for every clip — bites are no longer carved
- * out to raw `<VideoPlayer>`. The previous carve-out existed because
- * react-player's hls.js bundle was ~80KB and short clips didn't need
- * adaptive bitrate. With MuxPlayer, the player loads its HLS engine
- * lazily — for a plain MP4 source it's a thin shell around `<video>`,
- * so the carve-out costs more in complexity than it saves in bytes.
+ * The old aspect-ratio GRID rendered here was replaced by the unified
+ * strip (`video-bites-strip.tsx`, Figma node 4033-90364). This wrapper
+ * keeps the historical 4-prop signature compiling for hub call sites
+ * between the lib version bump and the hub-side migration.
  *
- * `LazyBite` defers mount until the wrapper enters the IO `500px`
- * margin so off-screen bites don't even render their player. Same
- * `useNearViewport` singleton used everywhere else in the lib.
+ * Scheduled deletion: next lib minor after the hub migration's grep gate
+ * confirms zero consumers. Do NOT add features here.
  */
 
-// =============================================================================
-// LazyBite — viewport-gated wrapper for video bite cards
-// =============================================================================
-
-/** Aspect-ratio-aware placeholder prevents CLS across the grid. */
-const RATIO_TO_CSS_ASPECT: Record<RatioCategory, string> = {
-  portrait: '9 / 16',
-  square: '1 / 1',
-  landscape: '16 / 9',
-};
-
-interface LazyBiteProps {
-  /** Aspect ratio of the wrapped bite — placeholder keeps layout stable. */
-  ratio: RatioCategory;
-  /** Card rendered once the wrapper enters (within `500px` of) the viewport. */
-  children: React.ReactNode;
-}
-
-/**
- * Defers mounting an off-screen video bite until it scrolls within
- * ~500px of the viewport. Renders an aspect-ratio-matched placeholder
- * beforehand so layout stays stable.
- *
- * Placeholder bg matches the wrapped `<Card>` background (`bg-ods-card`)
- * so the swap-in is visually seamless and avoids a flash on hydration.
- */
-function LazyBite({ ratio, children }: LazyBiteProps) {
-  const { ref, isNear } = useNearViewport<HTMLDivElement>('500px');
-
-  return (
-    <div ref={ref} style={{ aspectRatio: RATIO_TO_CSS_ASPECT[ratio] }}>
-      {isNear ? children : <div className="w-full h-full bg-ods-card rounded-md" />}
-    </div>
-  );
-}
-
-// =============================================================================
-// Public component
-// =============================================================================
-
 export interface VideoBitesDisplayProps {
   /** Array of video bites/teasers to display. */
   bites: VideoTeaser[];
@@ -83,135 +28,18 @@ export interface VideoBitesDisplayProps {
   showTitle?: boolean;
 }
 
-/**
- * Unified video-bites grid.
- *
- * Groups by aspect ratio when multiple ratios are present, otherwise
- * renders a flat grid. Each bite mounts lazily via `LazyBite` so
- * off-screen players don't cost the page.
- */
 export function VideoBitesDisplay({
   bites,
-  title = 'Video Highlights',
+  title = DEFAULT_VIDEO_BITES_TITLE,
   filterPublished = true,
   showTitle = true,
 }: VideoBitesDisplayProps) {
-  const grouped = useMemo(() => {
-    const filtered = filterPublished ? bites.filter(b => b.published) : bites;
-
-    const sorted = [...filtered].sort((a, b) => {
-      if (!a.created_at && !b.created_at) return 0;
-      if (!a.created_at) return 1;
-      if (!b.created_at) return -1;
-      return new Date(b.created_at).getTime() - new Date(a.created_at).getTime();
-    });
-
-    return groupByAspectRatio(sorted, b =>
-      detectAspectRatio((b as VideoTeaserWithRatio).aspect_ratio),
-    );
-  }, [bites, filterPublished]);
-
-  const totalCount = grouped.portrait.length + grouped.square.length + grouped.landscape.length;
-  if (totalCount === 0) return null;
-
-  return (
-    <div className="flex flex-col gap-6 w-full min-w-0">
-      {showTitle && (
-        <h2 className={`${SECTION_HEADING_CLASS} break-words`}>
-          {title}
-        </h2>
-      )}
-
-      {grouped.hasMultiple ? (
-        <RatioTabs
-          groups={{
-            portrait: {
-              count: grouped.portrait.length,
-              render: () => <BiteGrid bites={grouped.portrait} ratio="portrait" />,
-            },
-            square: {
-              count: grouped.square.length,
-              render: () => <BiteGrid bites={grouped.square} ratio="square" />,
-            },
-            landscape: {
-              count: grouped.landscape.length,
-              render: () => <BiteGrid bites={grouped.landscape} ratio="landscape" />,
-            },
-          }}
-        />
-      ) : (
-        <BiteGrid
-          bites={
-            grouped.portrait.length > 0
-              ? grouped.portrait
-              : grouped.square.length > 0
-                ? grouped.square
-                : grouped.landscape
-          }
-          ratio={
-            grouped.portrait.length > 0
-              ? 'portrait'
-              : grouped.square.length > 0
-                ? 'square'
-                : 'landscape'
-          }
-        />
-      )}
-    </div>
-  );
-}
-
-// =============================================================================
-// Internals
-// =============================================================================
-
-/**
- * Renders a grid of bite cards with ratio-appropriate column layout.
- * Each card is wrapped in `LazyBite` so off-screen bites don't mount
- * their player until they scroll near the viewport.
- */
-function BiteGrid({ bites, ratio }: { bites: VideoTeaser[]; ratio: RatioCategory }) {
   return (
-    <div className={RATIO_DISPLAY_GRID_CLASS[ratio]}>
-      {bites.map((bite, index) => (
-        <LazyBite key={bite.url || index} ratio={ratio}>
-          <VideoBiteCard url={bite.url} title={bite.title} thumbnailUrl={bite.thumbnail_url} />
-        </LazyBite>
-      ))}
-    </div>
+    <VideoBitesStrip
+      bites={bites}
+      title={title}
+      filterPublished={filterPublished}
+      showTitle={showTitle}
+    />
   );
 }
-
-interface VideoBiteCardProps {
-  url: string;
-  title?: string | null;
-  thumbnailUrl?: string | null;
-}
-
-/**
- * Individual bite card — routes through `<Video>` so the SSoT player
- * is the only video primitive in the lib.
- *
- * Layout: `LazyBite` sets the OUTER `aspectRatio` (portrait/square/landscape),
- * but `<Card>` between LazyBite and `<Video>` has no intrinsic height, so
- * we wrap `<Video>` in `layout="fill"` + an explicit `relative` parent so
- * the player fills the bite's aspect box from first paint. Otherwise
- * MuxPlayer renders at its intrinsic default size and grows once metadata
- * loads — the same CLS that hits the centered layout.
- */
-function VideoBiteCard({ url, title, thumbnailUrl }: VideoBiteCardProps) {
-  return (
-    <Card className="overflow-hidden border border-ods-border bg-ods-card hover:border-ods-accent transition-colors flex flex-col h-full">
-      <div className="relative flex-1 min-h-0">
-        <Video url={url} poster={thumbnailUrl || undefined} layout="fill" />
-      </div>
-      {title && (
-        <div className="p-4">
-          <p className="text-h4 text-ods-text-primary line-clamp-2" title={title}>{title}</p>
-        </div>
-      )}
-    </Card>
-  );
-}
-
-export { VideoBiteCard };

package/src/components/features/video-bites-shared.ts

@@ -0,0 +1,62 @@
+/**
+ * video-bites-shared — SERVER-SAFE leaf for the video-bites surface.
+ *
+ * No React imports, no 'use client'. Published as its own subpath
+ * (`@flamingo-stack/openframe-frontend-core/components/features/video-bites-shared`)
+ * so server-side consumers (the hub's featured-video-bites DAL) can import the
+ * title constant, profile adapter, and sort comparator WITHOUT pulling the
+ * 'use client' strip/MuxPlayer module graph into a server bundle — same
+ * pattern (and reason) as `mux-origins.ts`.
+ *
+ * Client components (`<VideoBitesStrip>`, the features barrel) re-export from
+ * here; there must never be a second definition of any of these.
+ */
+
+import type { VideoTeaser } from '../../types/video-processing'
+
+/** Single exported home for the unified public bites-section title. */
+export const DEFAULT_VIDEO_BITES_TITLE = 'Key Moments'
+
+/**
+ * Profile rendered in the strip's hover overlay. Structurally identical to
+ * `UserDisplayProps` — the overlay renders it via `<UserDisplay>` 1:1.
+ */
+export interface VideoBiteStripProfile {
+  name: string
+  avatarUrl?: string | null
+  subtitle?: string | null
+}
+
+/**
+ * Adapter SSoT: builds a strip profile from the repo-wide author/user shape
+ * (`profiles` rows and hydrated authors all expose full_name / avatar_url /
+ * job_title). ALL strip call sites and the featured DAL's mapProfile route
+ * through this — never hand-roll the mapping.
+ *
+ * Returns NULL (never `{name: ''}`) when `full_name` is null/empty: callers
+ * rely on `profile ?? fallback` chains, and some producers (e.g. the release
+ * kit) pass null-field author stubs.
+ */
+export function toStripProfile(
+  p?: { full_name?: string | null; avatar_url?: string | null; job_title?: string | null } | null,
+  fallbackSubtitle?: string | null,
+): VideoBiteStripProfile | null {
+  if (!p?.full_name) return null
+  return {
+    name: p.full_name,
+    avatarUrl: p.avatar_url ?? null,
+    subtitle: p.job_title ?? fallbackSubtitle ?? null,
+  }
+}
+
+/**
+ * Null-safe created_at-desc COMPARATOR (missing dates sort last).
+ * Call as `[...arr].sort(sortBitesByCreatedAtDesc)` — shared by the strip,
+ * the hub admin editor, and the hub featured DAL.
+ */
+export function sortBitesByCreatedAtDesc(a: VideoTeaser, b: VideoTeaser): number {
+  if (!a.created_at && !b.created_at) return 0
+  if (!a.created_at) return 1
+  if (!b.created_at) return -1
+  return new Date(b.created_at).getTime() - new Date(a.created_at).getTime()
+}