@flamingo-stack/openframe-frontend-core 0.0.215 → 0.0.216

package/src/components/features/notifications/notification-popups.tsx

@@ -0,0 +1,105 @@
+'use client'
+
+import type { KeyboardEvent, MouseEvent } from 'react'
+import { cn } from '../../../utils/cn'
+import { useOptionalNotifications } from './notifications-context'
+import { NotificationTile } from './notification-tile'
+import type { Notification } from './types'
+
+export type NotificationPopupsPosition =
+  | 'top-right'
+  | 'top-left'
+  | 'bottom-right'
+  | 'bottom-left'
+
+export interface NotificationPopupsProps {
+  className?: string
+  liveDurationMs?: number
+  maxVisible?: number
+  position?: NotificationPopupsPosition
+  hideWhenDrawerOpen?: boolean
+}
+
+const positionClasses: Record<NotificationPopupsPosition, string> = {
+  'top-right': 'top-4 right-4',
+  'top-left': 'top-4 left-4',
+  'bottom-right': 'bottom-4 right-4 flex-col-reverse',
+  'bottom-left': 'bottom-4 left-4 flex-col-reverse',
+}
+
+export function NotificationPopups({
+  className,
+  liveDurationMs = 4000,
+  maxVisible = 4,
+  position = 'top-right',
+  hideWhenDrawerOpen = true,
+}: NotificationPopupsProps) {
+  const ctx = useOptionalNotifications()
+  if (!ctx) return null
+
+  const { notifications, showPopups, isOpen, open, markRead, markSettled } = ctx
+
+  if (!showPopups) return null
+  if (hideWhenDrawerOpen && isOpen) return null
+
+  const now = Date.now()
+  const live = notifications
+    .filter((n) => !n.read && !n.settled && now - n.createdAt < liveDurationMs)
+    .slice(0, maxVisible)
+
+  if (live.length === 0) return null
+
+  const activate = (notification: Notification) => {
+    if (notification.onClick) {
+      notification.onClick()
+      markRead(notification.id)
+      markSettled(notification.id)
+      return
+    }
+    open()
+    markSettled(notification.id)
+  }
+
+  const handleBodyClick = (notification: Notification) => (event: MouseEvent<HTMLDivElement>) => {
+    // Nested interactive controls (X, check button) handle their own actions.
+    if ((event.target as HTMLElement).closest('button')) return
+    activate(notification)
+  }
+
+  const handleBodyKeyDown = (notification: Notification) => (event: KeyboardEvent<HTMLDivElement>) => {
+    if ((event.target as HTMLElement).closest('button')) return
+    if (event.key !== 'Enter' && event.key !== ' ') return
+    event.preventDefault()
+    activate(notification)
+  }
+
+  return (
+    <div
+      aria-live="polite"
+      className={cn(
+        'pointer-events-none fixed z-[9999] flex w-[26rem] max-w-[calc(100vw-2rem)] flex-col gap-[var(--spacing-system-xs)]',
+        positionClasses[position],
+        className,
+      )}
+    >
+      {live.map((n) => (
+        // biome-ignore lint/a11y/useSemanticElements: nested interactive elements forbid <button>
+        <div
+          key={n.id}
+          role="button"
+          tabIndex={0}
+          onClick={handleBodyClick(n)}
+          onKeyDown={handleBodyKeyDown(n)}
+          className="pointer-events-auto cursor-pointer rounded-md focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ods-accent"
+        >
+          <NotificationTile
+            notification={n}
+            liveDurationMs={liveDurationMs}
+            onComplete={markRead}
+            onSettle={markSettled}
+          />
+        </div>
+      ))}
+    </div>
+  )
+}

package/src/components/features/notifications/notifications-context.tsx

@@ -21,6 +21,9 @@ interface NotificationsContextValue {
   toggle: () => void
   setShowPopups: (value: boolean) => void
   onHistoryClick?: () => void
+  hasMore: boolean
+  isLoadingMore: boolean
+  loadMore?: () => void
 }
 
 const NotificationsContext = React.createContext<NotificationsContextValue | null>(null)
@@ -44,6 +47,10 @@ export interface NotificationsProviderProps {
   onShowPopupsChange?: (value: boolean) => void
   onHistoryClick?: () => void
   actions?: NotificationsActions
+  /** Pagination — when omitted, the drawer hides its load-more sentinel. */
+  hasMore?: boolean
+  isLoadingMore?: boolean
+  onLoadMore?: () => void
 }
 
 type Action =
@@ -130,6 +137,9 @@ export function NotificationsProvider({
   onShowPopupsChange,
   onHistoryClick,
   actions,
+  hasMore = false,
+  isLoadingMore = false,
+  onLoadMore,
 }: NotificationsProviderProps) {
   const [notifications, dispatch] = React.useReducer(reducer, initialNotifications)
   const [isOpen, setIsOpen] = React.useState(false)
@@ -231,6 +241,9 @@ export function NotificationsProvider({
       toggle,
       setShowPopups,
       onHistoryClick,
+      hasMore,
+      isLoadingMore,
+      loadMore: onLoadMore,
     }),
     [
       notifications,
@@ -250,6 +263,9 @@ export function NotificationsProvider({
       toggle,
       setShowPopups,
       onHistoryClick,
+      hasMore,
+      isLoadingMore,
+      onLoadMore,
     ],
   )
 

package/src/components/features/notifications/types.ts

@@ -15,6 +15,7 @@ export interface Notification {
   severity?: NotificationSeverity
   category?: string
   meta?: Record<string, unknown>
+  onClick?: () => void
 }
 
 export type AddNotificationInput =

package/src/components/features/use-video-warmup.ts

@@ -0,0 +1,176 @@
+'use client'
+
+/**
+ * `useVideoWarmup` — single-source-of-truth hook for warming the
+ * network path to a public entity's main video so click→first-frame
+ * lands in sub-second on Fast 4G.
+ *
+ * Behavior:
+ *
+ *   1. **Preconnect on every render** (`ReactDOM.preconnect`) — buys
+ *      the TCP / TLS handshakes to the video-bearing origins. React
+ *      19 de-dupes identical preconnects, so this is safe to call
+ *      on every render.
+ *
+ *   2. **Preload the video bytes** (`<link rel="preload" as="video">`)
+ *      ONLY when:
+ *        - the consumer's container scrolls within `nearMargin` of
+ *          the viewport (gated via the lib's IO singleton hook), AND
+ *        - `navigator.connection?.saveData !== true`, AND
+ *        - the URL is on the Supabase storage origin (Mux HLS warms
+ *          via its own manifest fetch when MuxPlayer mounts; YouTube
+ *          has its own origin pool, no preload benefit).
+ *
+ * Origin configuration:
+ *   - Mux origins (`stream.mux.com` / `image.mux.com`) are public
+ *     Mux CDN hostnames and stable across the Mux API contract —
+ *     hardcoded here.
+ *   - Supabase storage origin varies per-deployment (different
+ *     project per env). Threaded via the `supabaseStorageOrigin`
+ *     argument so the lib stays env-agnostic; hub callers pass
+ *     `getSupabaseStorageOrigin()` from their env config, or read
+ *     it from `ChatRuntime.endpoints.supabaseStorageOrigin`.
+ *
+ * Lifted from hub `hooks/use-video-warmup.ts`. The Mux constants
+ * and the IO-gated preload semantics are byte-equivalent.
+ */
+
+import { useEffect } from 'react'
+import ReactDOM from 'react-dom'
+import { useNearViewport } from '../../hooks/use-near-viewport'
+import { useChatRuntime } from '../../contexts/chat-runtime-context'
+// Re-export from the server-safe `mux-origins.ts` module so the
+// constants are NOT bound to this `'use client'` file. See the
+// JSDoc in `mux-origins.ts` for the bug history. Backward-compat:
+// existing imports that read `MUX_STREAM_ORIGIN` from
+// `@flamingo-stack/openframe-frontend-core/components/features`
+// continue to resolve through this re-export.
+export { MUX_STREAM_ORIGIN, MUX_IMAGE_ORIGIN } from './mux-origins'
+import { MUX_STREAM_ORIGIN, MUX_IMAGE_ORIGIN } from './mux-origins'
+
+/**
+ * Preconnect-only variant — fires the three video-bearing origin
+ * preconnects (Supabase Storage + Mux stream + Mux image) without
+ * setting up the IntersectionObserver subscription or the preload
+ * `<link>` injection.
+ *
+ * Use this when the consumer can't attach a `ref` to the video
+ * container (e.g. release detail page, which delegates the player
+ * render to a sibling component). Calling the full `useVideoWarmup`
+ * from there would subscribe to a never-mounted ref and ship dead
+ * preload machinery in the bundle.
+ *
+ * For consumers that own the video container, use `useVideoWarmup`
+ * (which composes this hook + the IO-gated preload step).
+ *
+ * Reads `supabaseStorageOrigin` from `ChatRuntime.endpoints` by
+ * default — callers in hosts that mount `HubRuntimeProvider` (or
+ * any equivalent provider that wires the field) get the origin
+ * automatically. The explicit `supabaseStorageOrigin` argument
+ * overrides the runtime value when set.
+ */
+export function useVideoOriginPreconnect({
+  supabaseStorageOrigin,
+}: { supabaseStorageOrigin?: string } = {}): void {
+  const runtime = useChatRuntime()
+  const resolvedOrigin =
+    supabaseStorageOrigin ?? runtime?.endpoints.supabaseStorageOrigin
+  try {
+    ReactDOM.preconnect(MUX_STREAM_ORIGIN, { crossOrigin: 'anonymous' })
+    ReactDOM.preconnect(MUX_IMAGE_ORIGIN, { crossOrigin: 'anonymous' })
+    if (resolvedOrigin) {
+      ReactDOM.preconnect(resolvedOrigin, { crossOrigin: 'anonymous' })
+    }
+  } catch (err) {
+    if (process.env.NODE_ENV !== 'production') {
+      // eslint-disable-next-line no-console
+      console.warn('[useVideoOriginPreconnect] preconnect failed:', err)
+    }
+  }
+}
+
+interface UseVideoWarmupOptions {
+  /**
+   * Effective video URL the page renders. Pass null/undefined when
+   * there's no video yet (the hook still preconnects). Only URLs on
+   * `supabaseStorageOrigin` are preloaded — Mux HLS and YouTube are
+   * no-ops on the preload side.
+   */
+  videoUrl?: string | null
+  /**
+   * Supabase storage origin (e.g. `https://xyz.supabase.co`). When
+   * omitted, falls back to `ChatRuntime.endpoints.supabaseStorageOrigin`
+   * — hosts that mount `HubRuntimeProvider` (or any equivalent
+   * provider) get the origin automatically. When neither is set, the
+   * preload step is skipped (preconnect to Mux still fires).
+   */
+  supabaseStorageOrigin?: string
+  /**
+   * IO root margin gate for the preload step. Default `'1000px'` —
+   * about one viewport's worth of lookahead on desktop.
+   */
+  nearMargin?: string
+}
+
+export interface UseVideoWarmupResult<T extends Element = HTMLDivElement> {
+  ref: (node: T | null) => void
+  isNear: boolean
+}
+
+export function useVideoWarmup<T extends Element = HTMLDivElement>({
+  videoUrl,
+  supabaseStorageOrigin,
+  nearMargin = '1000px',
+}: UseVideoWarmupOptions = {}): UseVideoWarmupResult<T> {
+  // Resolve origin once — runtime fallback so callers in hosts that
+  // mount `HubRuntimeProvider` don't need to thread it themselves.
+  const runtime = useChatRuntime()
+  const resolvedOrigin =
+    supabaseStorageOrigin ?? runtime?.endpoints.supabaseStorageOrigin
+
+  // Preconnect on every render — React 19 dedupes. Delegates to the
+  // shared preconnect-only variant so the origin list is a single
+  // source of truth.
+  useVideoOriginPreconnect({ supabaseStorageOrigin: resolvedOrigin })
+
+  const { ref, isNear } = useNearViewport<T>(nearMargin)
+
+  useEffect(() => {
+    if (!isNear || !videoUrl || !resolvedOrigin) return
+
+    // Save-Data gate — metered connections skip preload.
+    type Connection = { saveData?: boolean }
+    const conn = (navigator as Navigator & { connection?: Connection }).connection
+    if (conn?.saveData === true) return
+
+    // Origin gate: only preload Supabase-hosted MP4s. Mux HLS warms
+    // via the manifest fetch when MuxPlayer mounts; YouTube has no
+    // preload benefit.
+    let videoOrigin: string
+    try {
+      videoOrigin = new URL(videoUrl, 'http://placeholder.local').origin
+    } catch {
+      return
+    }
+    if (videoOrigin !== resolvedOrigin) return
+
+    const link = document.createElement('link')
+    link.rel = 'preload'
+    link.as = 'video'
+    link.href = videoUrl
+    link.crossOrigin = 'anonymous'
+    // `fetchPriority='low'` matches the plan — the hint should not
+    // steal network from the LCP image; the click→first-frame win is
+    // in milliseconds, not the first paint.
+    if ('fetchPriority' in link) {
+      ;(link as HTMLLinkElement & { fetchPriority?: string }).fetchPriority = 'low'
+    }
+    document.head.appendChild(link)
+
+    return () => {
+      link.remove()
+    }
+  }, [isNear, videoUrl, resolvedOrigin])
+
+  return { ref, isNear }
+}

package/src/components/index.ts

@@ -62,6 +62,11 @@ export * from './chat'
 // Onboarding components
 export * from './shared/onboarding'
 
+// Doc-search bar — unified RAG-search dropdown used by the data-room
+// sidebar AND the onboarding-guide catalog. Pure presentation; hosts
+// own the `useDocSearch` hook and pass results in as props.
+export * from './shared/doc-search'
+
 // Product Release components
 export * from './shared/product-release'
 

package/src/components/onboarding-guides/build-default-href.ts

@@ -0,0 +1,16 @@
+/**
+ * Lib-internal helper — default href shape for onboarding-guide cards
+ * when `runtime.composeContentUrl` is not wired (single-platform
+ * embedders without cross-platform topology).
+ *
+ * Shared between `OnboardingGuidesCatalogView` (per-card href) and
+ * `OnboardingGuideDetailView` (per-related-card href) so both views
+ * compose hrefs from the same `basePath`-derived shape — no parallel
+ * 4-line helper to drift apart.
+ */
+export function buildDefaultHref(
+  basePath: string,
+  slug: string,
+): { href: string; targetPlatform: string | null } {
+  return { href: `${basePath}/${slug}`, targetPlatform: null }
+}

package/src/components/onboarding-guides/hooks/use-onboarding-guides.ts

@@ -0,0 +1,90 @@
+'use client'
+
+/**
+ * React Query hooks for Onboarding Guides — PUBLIC reads only.
+ *
+ * Admin mutations (create/update/delete/publish/stats/save-highlight)
+ * stay HUB-side in `hooks/use-onboarding-guides.ts` and import the
+ * `onboardingGuideKeys.admin` sub-namespace from this module so the
+ * cache namespace `['onboarding-guides']` has a single source of truth.
+ *
+ * Endpoints (`/api/onboarding-guides*`) are host-supplied — non-Next.js
+ * embedders must reverse-proxy the same routes. Same precedent as the
+ * tickets list hook.
+ */
+
+import { useQuery } from '@tanstack/react-query'
+
+import type {
+  OnboardingGuide,
+  OnboardingGuideFilters,
+  OnboardingGuideListResponse,
+  OnboardingGuideSectionSummary,
+} from '../../chat/types/entities/onboarding-guide'
+
+/**
+ * Cache key builder for the `['onboarding-guides']` namespace.
+ *
+ * Includes BOTH public-read sub-keys (`lists`, `list`, `details`,
+ * `detail`, `sections`) AND the `admin` sub-namespace. Admin mutations
+ * live hub-side but invalidate against this same builder so a single
+ * `qc.invalidateQueries({ queryKey: onboardingGuideKeys.all })` from
+ * an admin hook also clears the public read cache.
+ */
+export const onboardingGuideKeys = {
+  all: ['onboarding-guides'] as const,
+  lists: () => [...onboardingGuideKeys.all, 'list'] as const,
+  list: (filters: OnboardingGuideFilters) =>
+    [...onboardingGuideKeys.lists(), filters] as const,
+  details: () => [...onboardingGuideKeys.all, 'detail'] as const,
+  detail: (slug: string) => [...onboardingGuideKeys.details(), slug] as const,
+  sections: () => [...onboardingGuideKeys.all, 'sections'] as const,
+  admin: {
+    all: ['admin', 'onboarding-guides'] as const,
+    lists: () => ['admin', 'onboarding-guides', 'list'] as const,
+    detail: (slug: string) =>
+      ['admin', 'onboarding-guide', slug] as const,
+    stats: () => ['admin', 'onboarding-guides', 'stats'] as const,
+  },
+}
+
+export function useOnboardingGuides(filters?: OnboardingGuideFilters) {
+  return useQuery({
+    queryKey: onboardingGuideKeys.list(filters || {}),
+    queryFn: async (): Promise<OnboardingGuideListResponse> => {
+      const params = new URLSearchParams()
+      if (filters?.search) params.set('search', filters.search)
+      if (filters?.section) params.set('section', filters.section)
+      if (filters?.limit) params.set('limit', filters.limit.toString())
+      if (filters?.offset) params.set('offset', filters.offset.toString())
+      const res = await fetch(`/api/onboarding-guides?${params}`)
+      if (!res.ok) throw new Error('Failed to fetch onboarding guides')
+      return res.json()
+    },
+  })
+}
+
+export function useOnboardingGuide(slug: string | undefined) {
+  return useQuery({
+    queryKey: onboardingGuideKeys.detail(slug || ''),
+    queryFn: async (): Promise<OnboardingGuide> => {
+      const res = await fetch(`/api/onboarding-guides/${slug}`)
+      if (!res.ok) throw new Error('Failed to fetch onboarding guide')
+      return res.json()
+    },
+    enabled: !!slug,
+  })
+}
+
+export function useOnboardingGuideSections() {
+  return useQuery({
+    queryKey: onboardingGuideKeys.sections(),
+    queryFn: async (): Promise<OnboardingGuideSectionSummary[]> => {
+      const res = await fetch('/api/onboarding-guides/sections')
+      if (!res.ok)
+        throw new Error('Failed to fetch onboarding-guide sections')
+      return res.json()
+    },
+    staleTime: 0,
+  })
+}

package/src/components/onboarding-guides/index.ts

@@ -0,0 +1,39 @@
+/**
+ * Onboarding Guides surface barrel.
+ *
+ * Mirrors `components/tickets/` — top-level openframe-route-specific
+ * product surface (NOT under `shared/`, which is reserved for
+ * cross-platform marketing).
+ *
+ * IMPORTANT: this barrel MUST NOT re-export `OnboardingGuide`,
+ * `OnboardingGuideFilters`, `OnboardingGuideListResponse`, or
+ * `OnboardingGuideSectionSummary`. Those types already flow via
+ * `components/chat/types/entities/onboarding-guide.ts` (re-exported
+ * from `components/chat` through `./types/*`). A duplicate path
+ * triggers TypeScript's TS2308 ambiguous re-export at the top-level
+ * `components/index.ts` barrel — same gotcha documented for
+ * `RoadmapItem` at `shared/roadmap/index.ts:1-14`.
+ *
+ * Consumers needing the row type:
+ *   import type { OnboardingGuide } from
+ *     '@flamingo-stack/openframe-frontend-core/components/chat'
+ */
+
+export {
+  OnboardingGuidesCatalogView,
+  type OnboardingGuidesCatalogViewProps,
+} from './onboarding-guides-catalog-view'
+export {
+  OnboardingGuideDetailView,
+  type OnboardingGuideDetailViewProps,
+} from './onboarding-guide-detail-view'
+export {
+  OnboardingGuidesCatalogSkeleton,
+} from './onboarding-guides-catalog-skeleton'
+
+export {
+  useOnboardingGuides,
+  useOnboardingGuide,
+  useOnboardingGuideSections,
+  onboardingGuideKeys,
+} from './hooks/use-onboarding-guides'