@flamingo-stack/openframe-frontend-core 0.0.178 → 0.0.179-snapshot.20260514181702

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

@@ -0,0 +1,175 @@
+"use client";
+
+import { ComponentType } from 'react';
+import {
+  Tabs,
+  TabsList,
+  TabsTrigger,
+  TabsContent,
+} from '../ui/tabs';
+import type { VideoTeaser } from '../../types/video-processing';
+import { Video } from './video';
+import { VideoBitesDisplay } from './video-bites-display';
+
+/**
+ * <EntityVideoSection> — public detail-page video block.
+ *
+ * Tabbed Full Video / Highlights when both exist, plus optional
+ * markdown summary + video bites grid. The actual video rendering
+ * (YouTube facade, Mux HLS, MP4 fallback) is delegated to `<Video>` —
+ * the single source of truth.
+ *
+ * YouTube takes precedence over the uploaded video when both
+ * `youtubeUrl` and `mainVideoUrl` are present. That precedence is
+ * resolved here (in the section wrapper) rather than inside `<Video>`,
+ * so the underlying primitive stays single-source-per-render.
+ */
+
+interface MarkdownRendererProps {
+  content: string;
+}
+
+export interface EntityVideoSectionProps {
+  /** Main uploaded video URL. */
+  mainVideoUrl?: string | null;
+  /** YouTube URL (takes priority over `mainVideoUrl` for display). */
+  youtubeUrl?: string | null;
+  /** AI-generated highlight video URL. */
+  highlightVideoUrl?: string | null;
+  /** Thumbnail for highlight video. */
+  highlightVideoThumbnail?: string | null;
+  /** Poster/thumbnail for main video. */
+  mainVideoPoster?: string | null;
+  /** Title for YouTube embed. */
+  title?: string;
+  /** AI-generated video summary (markdown). */
+  videoSummary?: string | null;
+  /** Video bites/teasers array. */
+  videoBites?: VideoTeaser[];
+  /** Title for the video bites section. */
+  bitesTitle?: string;
+  /** Whether to filter bites to published only. */
+  filterPublishedBites?: boolean;
+  /** Markdown renderer component injected by the host app. */
+  MarkdownRenderer?: ComponentType<MarkdownRendererProps>;
+  /**
+   * Raw SRT content. Deprecated — pass `captionsUrl` instead.
+   * Forwarded to `<Video>` for the dev-only warning.
+   */
+  srtContent?: string | null;
+  /** HTTPS URL to a VTT captions file (rendered as native `<track>`). */
+  captionsUrl?: string | null;
+  /** LCP hint — when true, the full-video tab's poster eager-loads. */
+  priority?: boolean;
+}
+
+export function EntityVideoSection({
+  mainVideoUrl,
+  youtubeUrl,
+  highlightVideoUrl,
+  highlightVideoThumbnail,
+  mainVideoPoster,
+  title = 'Video',
+  videoSummary,
+  videoBites,
+  bitesTitle = 'Video Highlights',
+  filterPublishedBites = true,
+  MarkdownRenderer,
+  srtContent,
+  captionsUrl,
+  priority = false,
+}: EntityVideoSectionProps) {
+  const hasFullVideo = !!(youtubeUrl || mainVideoUrl);
+  const hasHighlight = !!highlightVideoUrl;
+  const hasVideo = hasFullVideo || hasHighlight;
+
+  if (!hasVideo && !videoSummary && (!videoBites || videoBites.length === 0)) {
+    return null;
+  }
+
+  // YouTube wins when both URLs are present.
+  const fullVideoUrl = youtubeUrl || mainVideoUrl || null;
+  const fullVideoKind: 'youtube' | 'auto' = youtubeUrl ? 'youtube' : 'auto';
+
+  return (
+    <>
+      {hasVideo &&
+        (hasFullVideo && hasHighlight ? (
+          <Tabs defaultValue="full-video" className="w-full">
+            <TabsList className="inline-flex justify-start rounded-none bg-transparent h-auto p-0 gap-0">
+              <TabsTrigger
+                value="full-video"
+                className="rounded-none border-b-2 border-transparent data-[state=active]:border-ods-accent data-[state=active]:bg-transparent data-[state=active]:shadow-none px-4 md:px-6 py-3 text-ods-text-secondary data-[state=active]:text-ods-text-primary"
+              >
+                Full Video
+              </TabsTrigger>
+              <TabsTrigger
+                value="highlights"
+                className="rounded-none border-b-2 border-transparent data-[state=active]:border-ods-accent data-[state=active]:bg-transparent data-[state=active]:shadow-none px-4 md:px-6 py-3 text-ods-text-secondary data-[state=active]:text-ods-text-primary"
+              >
+                Highlights
+              </TabsTrigger>
+            </TabsList>
+
+            <TabsContent value="full-video" className="mt-4">
+              <Video
+                kind={fullVideoKind}
+                url={fullVideoUrl!}
+                poster={mainVideoPoster}
+                title={title}
+                srtContent={srtContent}
+                captionsUrl={captionsUrl}
+                layout="centered"
+                priority={priority}
+              />
+            </TabsContent>
+
+            <TabsContent value="highlights" className="mt-4">
+              <Video
+                url={highlightVideoUrl!}
+                poster={highlightVideoThumbnail}
+                layout="centered"
+              />
+            </TabsContent>
+          </Tabs>
+        ) : hasFullVideo ? (
+          <Video
+            kind={fullVideoKind}
+            url={fullVideoUrl!}
+            poster={mainVideoPoster}
+            title={title}
+            srtContent={srtContent}
+            captionsUrl={captionsUrl}
+            layout="centered"
+            priority={priority}
+          />
+        ) : (
+          <Video
+            url={highlightVideoUrl!}
+            poster={highlightVideoThumbnail}
+            layout="centered"
+            priority={priority}
+          />
+        ))}
+
+      {videoSummary && MarkdownRenderer && (
+        <div className="flex flex-col gap-6 w-full min-w-0">
+          <h2 className="text-h1 tracking-[-1.12px] text-ods-text-primary break-words">
+            Summary
+          </h2>
+          <div className="text-h4 text-ods-text-primary break-words overflow-hidden">
+            <MarkdownRenderer content={videoSummary} />
+          </div>
+        </div>
+      )}
+
+      {videoBites && videoBites.length > 0 && (
+        <VideoBitesDisplay
+          bites={videoBites}
+          title={bitesTitle}
+          filterPublished={filterPublishedBites}
+        />
+      )}
+    </>
+  );
+}

package/src/components/features/index.ts

@@ -33,7 +33,15 @@ export * from './social-links-manager'
 export * from './start-with-openframe-button'
 export * from './status-filter-component'
 export * from './tags-selector'
-export * from './video-player'
+// 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.
+export * from './video'
+export * from './video-ratio-tabs'
+export * from './video-bites-display'
+export * from './entity-video-section'
 export * from './video-source-selector'
 export * from './transcript-summary-editor'
 export * from './highlight-video-section'
@@ -46,7 +54,6 @@ export * from './highlight-video-preview'
 export * from './transcribe-and-summarize-combined-section'
 export * from './highlight-video-combined-section'
 export * from './view-toggle'
-export * from './youtube-embed'
 // AI Enrich components
 export * from './ai-enrich'
 export * from './policy-configuration-panel'

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

@@ -0,0 +1,216 @@
+"use client";
+
+import React, { useMemo } from 'react';
+import { Card } from '../ui/card';
+import { useNearViewport } from '../../hooks/use-near-viewport';
+import type { VideoTeaser } from '../../types/video-processing';
+import { Video } from './video';
+import {
+  RatioTabs,
+  groupByAspectRatio,
+  detectAspectRatio,
+  ratioToCategory,
+  RATIO_DISPLAY_GRID_CLASS,
+  type VideoTeaserWithRatio,
+  type RatioCategory,
+} from './video-ratio-tabs';
+
+/**
+ * <VideoBitesDisplay> — public grid of short video bites grouped by
+ * aspect ratio.
+ *
+ * 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.
+ *
+ * `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.
+ */
+
+// =============================================================================
+// 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[];
+  /** Title for the section. */
+  title?: string;
+  /** Whether to filter to only show published bites. Default `true`. */
+  filterPublished?: boolean;
+  /** Whether to show the title section heading. Default `true`. */
+  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',
+  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="text-h1 tracking-[-1.12px] text-ods-text-primary 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>
+  );
+}
+
+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}</p>
+        </div>
+      )}
+    </Card>
+  );
+}
+
+export { VideoBiteCard };

package/src/components/features/video-ratio-tabs.tsx

@@ -0,0 +1,174 @@
+"use client";
+
+/**
+ * Aspect-ratio tab + grouping primitives for video grids.
+ *
+ * Used by `<VideoBitesDisplay>` and by app-level admin editors
+ * (VideoBitesEditor, VideoLibraryGrid) so portrait / square / landscape
+ * clips render in cohesive groups.
+ *
+ * Why these live here in the lib (not the hub): `<VideoBitesDisplay>`
+ * was moved into the lib for SSoT, and it depends on these primitives.
+ * The hub's admin editors re-export from here.
+ */
+
+import {
+  Tabs,
+  TabsList,
+  TabsTrigger,
+  TabsContent,
+} from '../ui/tabs';
+import type { VideoTeaser } from '../../types/video-processing';
+
+/**
+ * Vizard clip extraction aspect ratios. Mirrors `lib/types/aspect-ratio.ts`
+ * in the hub — narrow on purpose. If the hub's `VizardAspectRatio` adds a
+ * value, mirror it here.
+ */
+export type VizardAspectRatio = '9:16' | '16:9' | '1:1';
+
+/**
+ * Extended VideoTeaser with aspect_ratio metadata from Vizard.
+ * The lib `VideoTeaser` is the canonical type but doesn't include
+ * `aspect_ratio` (stored in JSONB, preserved through spreads).
+ * Import this when you need the ratio at compile time.
+ */
+export interface VideoTeaserWithRatio extends VideoTeaser {
+  aspect_ratio?: VizardAspectRatio;
+  confidence?: number;
+  viral_reason?: string;
+  start_time_ms?: number;
+  end_time_ms?: number;
+}
+
+/** Ratio category used for grid layout and tab grouping. */
+export type RatioCategory = 'portrait' | 'square' | 'landscape';
+
+// Shared tab trigger class — matches `<EntityVideoSection>`'s pattern.
+const TAB_TRIGGER_CLASS =
+  'rounded-none border-b-2 border-transparent data-[state=active]:border-ods-accent data-[state=active]:bg-transparent data-[state=active]:shadow-none px-4 py-2 text-sm text-ods-text-secondary data-[state=active]:text-ods-text-primary';
+
+/** Grid class for each aspect ratio (admin editors — narrower columns). */
+export const RATIO_GRID_CLASS: Record<RatioCategory, string> = {
+  portrait: 'grid grid-cols-2 md:grid-cols-3 gap-4',
+  square: 'grid grid-cols-2 md:grid-cols-3 gap-4',
+  landscape: 'grid grid-cols-1 md:grid-cols-2 gap-4',
+};
+
+/** Grid class for public display (wider grids on detail pages). */
+export const RATIO_DISPLAY_GRID_CLASS: Record<RatioCategory, string> = {
+  portrait: 'grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-4',
+  square: 'grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-4',
+  landscape: 'grid grid-cols-1 md:grid-cols-2 gap-6',
+};
+
+const RATIO_TAB_CONFIG: { key: RatioCategory; label: string }[] = [
+  { key: 'portrait', label: 'Portrait 9:16' },
+  { key: 'square', label: 'Square 1:1' },
+  { key: 'landscape', label: 'Landscape 16:9' },
+];
+
+interface RatioTabsProps {
+  groups: Record<RatioCategory, { count: number; render: () => React.ReactNode }>;
+  defaultTab?: RatioCategory;
+  className?: string;
+}
+
+/**
+ * RatioTabs — shared aspect-ratio tab wrapper.
+ *
+ * Only renders tabs that have content. `forceMount` + `data-[state=inactive]:hidden`
+ * keeps inactive tabs in the DOM so switching back doesn't scroll-jump.
+ */
+export function RatioTabs({
+  groups,
+  defaultTab,
+  className = '',
+}: RatioTabsProps) {
+  const activeTabs = RATIO_TAB_CONFIG.filter(t => groups[t.key].count > 0);
+
+  // If only one tab has content, don't show tabs.
+  if (activeTabs.length <= 1) {
+    const active = activeTabs[0];
+    return active ? <>{groups[active.key].render()}</> : null;
+  }
+
+  const firstTab =
+    defaultTab && groups[defaultTab].count > 0 ? defaultTab : activeTabs[0].key;
+
+  return (
+    <Tabs defaultValue={firstTab} className={`w-full ${className}`}>
+      <TabsList className="inline-flex justify-start rounded-none bg-transparent h-auto p-0 gap-0 mb-2">
+        {activeTabs.map(t => (
+          <TabsTrigger key={t.key} value={t.key} className={TAB_TRIGGER_CLASS}>
+            {t.label} ({groups[t.key].count})
+          </TabsTrigger>
+        ))}
+      </TabsList>
+      {activeTabs.map(t => (
+        <TabsContent
+          key={t.key}
+          value={t.key}
+          forceMount
+          className="data-[state=inactive]:hidden"
+        >
+          {groups[t.key].render()}
+        </TabsContent>
+      ))}
+    </Tabs>
+  );
+}
+
+/**
+ * Detect aspect ratio from a Vizard ratio string, falling back to
+ * inferring from width/height if the string is missing or unknown.
+ * Default: portrait (`'9:16'`).
+ */
+export function detectAspectRatio(
+  ratioString?: string,
+  width?: number,
+  height?: number,
+): VizardAspectRatio {
+  if (ratioString === '16:9') return '16:9';
+  if (ratioString === '1:1') return '1:1';
+  if (ratioString === '9:16') return '9:16';
+  if (width && height) {
+    if (Math.abs(width - height) < Math.min(width, height) * 0.1) return '1:1';
+    if (width > height) return '16:9';
+  }
+  return '9:16';
+}
+
+/** Map a `VizardAspectRatio` to its `RatioCategory` for grouping. */
+export function ratioToCategory(ratio: VizardAspectRatio): RatioCategory {
+  if (ratio === '16:9') return 'landscape';
+  if (ratio === '1:1') return 'square';
+  return 'portrait';
+}
+
+/**
+ * Group items by aspect ratio into portrait / square / landscape buckets.
+ * `hasMultiple` is true when 2+ buckets are non-empty (drives tab vs. flat
+ * grid rendering downstream).
+ */
+export function groupByAspectRatio<T>(
+  items: T[],
+  getAspectRatio: (item: T) => VizardAspectRatio,
+): {
+  portrait: T[];
+  square: T[];
+  landscape: T[];
+  hasMultiple: boolean;
+} {
+  const portrait: T[] = [];
+  const square: T[] = [];
+  const landscape: T[] = [];
+  for (const item of items) {
+    const cat = ratioToCategory(getAspectRatio(item));
+    if (cat === 'landscape') landscape.push(item);
+    else if (cat === 'square') square.push(item);
+    else portrait.push(item);
+  }
+  const filled = [portrait, square, landscape].filter(a => a.length > 0).length;
+  return { portrait, square, landscape, hasMultiple: filled > 1 };
+}