@flamingo-stack/openframe-frontend-core 0.0.402 → 0.0.404-snapshot.20260711053526

package/src/components/features/video.tsx

@@ -708,6 +708,15 @@ interface YouTubeFacadeInnerProps {
 
 const YT_NOCOOKIE_ORIGIN = 'https://www.youtube-nocookie.com';
 
+// Poster thumbnail tiers, best → always-present. YouTube serves each size at a
+// fixed path on i.ytimg.com. `maxresdefault` is 1280×720 (crisp) but is only
+// generated for uploads whose source was ≥720p, so it can 404; `mqdefault` is
+// 320×180 and ALWAYS exists. BOTH are 16:9 — unlike the letterboxed 4:3 `hq`/`sd`
+// sizes — so an `object-cover` frame never shows black bars regardless of tier.
+// The facade starts at `maxresdefault` and drops to `mqdefault` on load error,
+// so low-res-only videos render exactly as they did before this change.
+const YT_POSTER_TIERS = ['maxresdefault', 'mqdefault'] as const;
+
 // YouTube IFrame Player API state codes — documented integers.
 // https://developers.google.com/youtube/iframe_api_reference#Playback_status
 const YT_STATE_ENDED = 0;
@@ -757,7 +766,7 @@ function YouTubeFacadeInner({
   // SSR-safe: the URL is rebuilt client-side in the same useMemo on
   // hydration when `window` becomes available; the first SSR pass emits
   // the URL without `origin` (no jsapi traffic yet — no iframe mounted).
-  const { embedUrl, posterJpg, posterWebp } = useMemo(() => {
+  const embedUrl = useMemo(() => {
     const params = new URLSearchParams({
       autoplay: '1',
       rel: '0',
@@ -775,13 +784,23 @@ function YouTubeFacadeInner({
       params.set('cc_load_policy', '0');
       params.set('disablekb', '1');
     }
-    return {
-      embedUrl: `${YT_NOCOOKIE_ORIGIN}/embed/${videoId}?${params.toString()}`,
-      posterJpg: `https://i.ytimg.com/vi/${videoId}/mqdefault.jpg`,
-      posterWebp: `https://i.ytimg.com/vi_webp/${videoId}/mqdefault.webp`,
-    };
+    return `${YT_NOCOOKIE_ORIGIN}/embed/${videoId}?${params.toString()}`;
   }, [videoId, minimalControls]);
 
+  // Poster starts at the highest tier and steps down on load error (see
+  // `YT_POSTER_TIERS`). Reset to the top tier whenever the video changes so a
+  // new id gets a fresh shot at its `maxresdefault`.
+  const [posterTier, setPosterTier] = useState(0);
+  useEffect(() => {
+    setPosterTier(0);
+  }, [videoId]);
+  const posterQuality = YT_POSTER_TIERS[posterTier];
+  const posterJpg = `https://i.ytimg.com/vi/${videoId}/${posterQuality}.jpg`;
+  const posterWebp = `https://i.ytimg.com/vi_webp/${videoId}/${posterQuality}.webp`;
+  // On a 404 (e.g. no `maxresdefault`) drop one tier; clamp at the last so a
+  // genuinely missing thumbnail can't loop.
+  const handlePosterError = () => setPosterTier((tier) => Math.min(tier + 1, YT_POSTER_TIERS.length - 1));
+
   // ---------------------------------------------------------------------------
   // YouTube control-fade accelerator (user-locked target: ~1s).
   //
@@ -894,6 +913,7 @@ function YouTubeFacadeInner({
             src={posterJpg}
             alt={title}
             loading="lazy"
+            onError={handlePosterError}
             // React 18 wants lowercase (`fetchpriority` DOM attribute);
             // React 19 wants camelCase (`fetchPriority` prop). Detect at
             // module load and spread the right shape so both runtimes

package/src/components/ui/button/button.tsx

@@ -29,7 +29,7 @@ const buttonVariants = cva(
       size: {
         default: "py-[var(--spacing-system-sf)] px-[var(--spacing-system-m)] text-h3 md:h-12 h-10",
         small: "p-[var(--spacing-system-xs)] text-h5 h-6 md:h-8",
-        "small-legacy": "py-[var(--spacing-system-xs)] px-[var(--spacing-system-m)] h-10 text-[14px] font-bold", // Temporary alias for "small" to avoid breaking changes in AnnouncementBar's CTA button; will be removed in the future
+        "small-legacy": "py-[var(--spacing-system-xs)] px-[var(--spacing-system-m)] h-10 text-[14px] font-bold", // Temporary alias for "small" — deprecated; grep size="small-legacy" (lib + hub) and migrate the remaining consumers before removal
         icon: "p-[var(--spacing-system-sf)] h-11 w-11 md:h-12 md:w-12 [&_svg]:h-4 [&_svg]:w-4 md:[&_svg]:h-6 md:[&_svg]:w-6",
         // Quiet 32px icon target with a 16px glyph, fixed across breakpoints
         // (Carbon ghost sm / Primer medium / shadcn icon-sm all pin 32px;

package/src/hooks/.api-hooks.md

@@ -5,18 +5,16 @@ This file provides stub React hooks for API data fetching, offering consistent i
 
 - **`useCategories()`** - Hook for fetching and managing category data with loading/error states
 - **`useVendors()`** - Hook for fetching and managing vendor data with loading/error states  
-- **`useAnnouncements()`** - Hook for fetching announcement data with loading state
 - **`useSubcategoryCountByCategory()`** - Hook that returns empty subcategory count data
 
 ## Usage Example
 
 ```typescript
-import { useCategories, useVendors, useAnnouncements } from './api-hooks';
+import { useCategories, useVendors } from './api-hooks';
 
 function MyComponent() {
   const { categories, loading: categoriesLoading, error: categoriesError } = useCategories();
   const { vendors, loading: vendorsLoading, error: vendorsError } = useVendors();
-  const { announcements, loading: announcementsLoading } = useAnnouncements();
 
   if (categoriesLoading || vendorsLoading) {
     return <div>Loading...</div>;
@@ -30,7 +28,6 @@ function MyComponent() {
     <div>
       <h2>Categories: {categories.length}</h2>
       <h2>Vendors: {vendors.length}</h2>
-      <h2>Announcements: {announcements.length}</h2>
     </div>
   );
 }

package/src/hooks/api-hooks.ts

@@ -17,13 +17,6 @@ export function useVendors() {
   return { vendors, loading, error };
 }
 
-export function useAnnouncements() {
-  const [announcements, setAnnouncements] = useState([]);
-  const [loading, setLoading] = useState(false);
-
-  return { announcements, loading };
-}
-
 export function useSubcategoryCountByCategory() {
   return { data: {}, loading: false };
 }

package/src/hooks/use-self-fetch.ts

@@ -31,19 +31,30 @@ export interface UseSelfFetchResult<T> {
  *   - a `cancelled` guard ensures an in-flight response from a STALE `url`
  *     (e.g. a fast pagination / section toggle) can't overwrite a newer one.
  *   - `reload()` bumps an internal key to retry after an error.
+ *   - `revalidateOnVisibleAfterMs` (opt-in) → re-fetch when the tab becomes
+ *     visible AND the held data is older than the threshold. Event-driven
+ *     freshness with ZERO background requests — the replacement for
+ *     setInterval polling. Data age counts from the last completed fetch, or
+ *     from mount when `initialData` seeded it (an SSR seed is milliseconds
+ *     old — without that, the first refocus would always refire).
  *
  * Re-fetches whenever `url` changes, so callers fold all query params INTO the
  * url string (the url IS the cache key).
  */
 export function useSelfFetch<T>(
   url: string | null,
-  options?: { initialData?: T },
+  options?: { initialData?: T; revalidateOnVisibleAfterMs?: number },
 ): UseSelfFetchResult<T> {
   const initialData = options?.initialData
+  const revalidateOnVisibleAfterMs = options?.revalidateOnVisibleAfterMs
   const [data, setData] = useState<T | null>(initialData ?? null)
   const [isLoading, setIsLoading] = useState(initialData === undefined && url !== null)
   const [error, setError] = useState(false)
   const [reloadKey, setReloadKey] = useState(0)
+  // When the held data was obtained: seeded at mount for SSR-hydrated data,
+  // stamped after each completed fetch. Drives the visibility revalidation age
+  // check. 0 = nothing held yet (first visible event may fetch).
+  const dataAtRef = useRef<number>(initialData !== undefined ? Date.now() : 0)
   // The url whose data we currently hold — seeded from SSR `initialData`, then set after
   // each completed fetch. The effect skips the fetch when this equals `url` (so server-
   // rendered data isn't re-fetched on mount). A VALUE compare (not a one-shot flag) so the
@@ -78,6 +89,7 @@ export function useSelfFetch<T>(
         if (!cancelled) {
           setData(json)
           dataUrlRef.current = url // remember the url we now hold data for
+          dataAtRef.current = Date.now()
         }
       } catch (err) {
         // AbortError on cleanup (unmount / stale-url change / React StrictMode's dev
@@ -100,6 +112,22 @@ export function useSelfFetch<T>(
     // `url` folds in every query param; `reloadKey` drives retry.
   }, [url, reloadKey])
 
+  // Opt-in visibility-driven revalidation. Registered only when the option is
+  // set and fetching is enabled; SSR-safe (effects don't run on the server)
+  // and StrictMode-safe (idempotent listener, cleaned up per mount cycle).
+  useEffect(() => {
+    if (!revalidateOnVisibleAfterMs || url === null) return
+    const onVisible = () => {
+      if (document.visibilityState !== 'visible') return
+      if (Date.now() - dataAtRef.current < revalidateOnVisibleAfterMs) return
+      // Same mechanics as reload(): clear the held-url skip, bump the key.
+      dataUrlRef.current = null
+      setReloadKey((k) => k + 1)
+    }
+    document.addEventListener('visibilitychange', onVisible)
+    return () => document.removeEventListener('visibilitychange', onVisible)
+  }, [url, revalidateOnVisibleAfterMs])
+
   return {
     data,
     setData,

package/src/stories/AnnouncementBar.stories.tsx

@@ -1,36 +1,24 @@
 import type { Meta, StoryObj } from '@storybook/nextjs-vite'
 import type { Announcement } from '../types/announcement'
 import { AnnouncementBar } from '../components/announcement-bar'
+import { announcementDismissCookieName } from '../utils/announcement-storage'
+import { getAppType } from '../utils/app-config'
+import { EndpointsRuntimeContext, type EndpointsRuntime } from '../contexts/endpoints-runtime-context'
 
 /**
- * Mock fetch so the component receives announcement data without a real API.
- * Also seeds localStorage so the bar isn't marked as dismissed.
+ * Stories drive the bar through its real `initialAnnouncement` prop (the hub's
+ * SSR-seed path) — no fetch mock needed; with no EndpointsRuntime provider
+ * mounted the bar never fetches. The decorator clears any dismissal state left
+ * by a previous interaction so every story starts visible.
  */
-function mockAnnouncement(announcement: Announcement | null) {
-  // Clear any previous dismiss flags
-  if (announcement) {
-    Object.keys(localStorage).forEach((key) => {
-      if (key.includes(`announcement-${announcement.id}-dismissed`)) {
-        localStorage.removeItem(key)
-      }
-    })
-  }
-
-  const originalFetch = window.fetch
-  window.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
-    const url = typeof input === 'string' ? input : input.toString()
-    if (url.includes('/api/announcements/active')) {
-      return new Response(JSON.stringify({ announcement }), {
-        status: 200,
-        headers: { 'Content-Type': 'application/json' },
-      })
+function clearDismissals() {
+  const platform = getAppType()
+  document.cookie = `${announcementDismissCookieName(platform)}=; path=/; max-age=0`
+  Object.keys(localStorage).forEach((key) => {
+    if (key.includes('-announcement-') && key.endsWith('-dismissed')) {
+      localStorage.removeItem(key)
     }
-    return originalFetch(input, init)
-  }) as typeof window.fetch
-
-  return () => {
-    window.fetch = originalFetch
-  }
+  })
 }
 
 const now = new Date().toISOString()
@@ -41,7 +29,6 @@ const baseAnnouncement: Announcement = {
   description: 'Check out our latest updates and improvements to the platform.',
   background_color: '#FFD951',
   icon_name: 'rocket',
-  platform_id: 'openframe',
   is_active: true,
   created_at: now,
   updated_at: now,
@@ -55,10 +42,16 @@ const meta = {
     docs: {
       description: {
         component:
-          'A top-of-page announcement bar that fetches the active announcement from the API. Supports SVG/PNG icons, CTA buttons, dismiss functionality, and responsive mobile layout.',
+          'A top-of-page announcement bar. The host seeds it with `initialAnnouncement` (SSR path) or lets it self-fetch via the endpoints runtime. Supports SVG/PNG icons, CTA buttons, contrast-aware text, animated dismiss, and responsive mobile layout.',
       },
     },
   },
+  decorators: [
+    (Story) => {
+      clearDismissals()
+      return <Story />
+    },
+  ],
   tags: ['autodocs'],
 } satisfies Meta<typeof AnnouncementBar>
 
@@ -69,189 +62,232 @@ type Story = StoryObj<typeof meta>
  * Default announcement with an icon and description.
  */
 export const Default: Story = {
-  decorators: [
-    (Story) => {
-      const cleanup = mockAnnouncement(baseAnnouncement)
-      return (
-        <>
-          <Story />
-          {/* cleanup on unmount is handled by storybook re-renders */}
-        </>
-      )
-    },
-  ],
+  args: { initialAnnouncement: baseAnnouncement },
 }
 
 /**
  * Announcement with a CTA button.
  */
 export const WithCTA: Story = {
-  decorators: [
-    (Story) => {
-      mockAnnouncement({
-        ...baseAnnouncement,
-        id: 'story-cta',
-        title: 'OpenFrame v2.0 is here!',
-        description: 'Explore the new dashboard, improved device management, and more.',
-        background_color: '#FFD951',
-        icon_name: 'star',
-        cta_enabled: true,
-        cta_text: 'Learn More',
-        cta_url: 'https://example.com',
-        cta_target: '_blank',
-        cta_icon_name: 'rocket',
-        cta_show_icon: true,
-        cta_button_background_color: '#1A1A1A',
-        cta_button_text_color: '#FFFFFF',
-      })
-      return <Story />
+  args: {
+    initialAnnouncement: {
+      ...baseAnnouncement,
+      id: 'story-cta',
+      title: 'OpenFrame v2.0 is here!',
+      description: 'Explore the new dashboard, improved device management, and more.',
+      background_color: '#FFD951',
+      icon_name: 'star',
+      cta_enabled: true,
+      cta_text: 'Learn More',
+      cta_url: 'https://example.com',
+      cta_target: '_blank',
+      cta_icon_name: 'rocket',
+      cta_show_icon: true,
+      cta_button_background_color: '#1A1A1A',
+      cta_button_text_color: '#FFFFFF',
     },
-  ],
+  },
 }
 
 /**
  * Announcement with a CTA button that opens in the same tab.
  */
 export const WithCTASameTab: Story = {
-  decorators: [
-    (Story) => {
-      mockAnnouncement({
-        ...baseAnnouncement,
-        id: 'story-cta-same',
-        title: 'Scheduled Maintenance',
-        description: 'We will perform maintenance on Saturday from 2:00 AM to 4:00 AM UTC.',
-        background_color: '#FFE082',
-        icon_name: 'info',
-        cta_enabled: true,
-        cta_text: 'View Status',
-        cta_url: '/status',
-        cta_target: '_self',
-      })
-      return <Story />
+  args: {
+    initialAnnouncement: {
+      ...baseAnnouncement,
+      id: 'story-cta-same',
+      title: 'Scheduled Maintenance',
+      description: 'We will perform maintenance on Saturday from 2:00 AM to 4:00 AM UTC.',
+      background_color: '#FFE082',
+      icon_name: 'info',
+      cta_enabled: true,
+      cta_text: 'View Status',
+      cta_url: '/status',
+      cta_target: '_self',
     },
-  ],
+  },
+}
+
+/**
+ * Dark background — text flips to the light shade via pickReadableTextColor.
+ */
+export const DarkBackground: Story = {
+  args: {
+    initialAnnouncement: {
+      ...baseAnnouncement,
+      id: 'story-dark',
+      title: 'Contrast-aware text',
+      description: 'On a dark admin-chosen background the foreground goes light automatically.',
+      background_color: '#1F2937',
+      icon_name: 'megaphone',
+    },
+  },
 }
 
 /**
  * Announcement with a blue background.
  */
 export const BlueBackground: Story = {
-  decorators: [
-    (Story) => {
-      mockAnnouncement({
-        ...baseAnnouncement,
-        id: 'story-blue',
-        title: 'Join our Community',
-        description: 'Connect with other MSPs and share best practices.',
-        background_color: '#60A5FA',
-        icon_name: 'megaphone',
-      })
-      return <Story />
+  args: {
+    initialAnnouncement: {
+      ...baseAnnouncement,
+      id: 'story-blue',
+      title: 'Join our Community',
+      description: 'Connect with other MSPs and share best practices.',
+      background_color: '#60A5FA',
+      icon_name: 'megaphone',
     },
-  ],
+  },
 }
 
 /**
  * Announcement with a green background.
  */
 export const GreenBackground: Story = {
-  decorators: [
-    (Story) => {
-      mockAnnouncement({
-        ...baseAnnouncement,
-        id: 'story-green',
-        title: 'All Systems Operational',
-        description: 'Everything is running smoothly. No issues detected.',
-        background_color: '#86EFAC',
-        icon_name: 'bell',
-      })
-      return <Story />
+  args: {
+    initialAnnouncement: {
+      ...baseAnnouncement,
+      id: 'story-green',
+      title: 'All Systems Operational',
+      description: 'Everything is running smoothly. No issues detected.',
+      background_color: '#86EFAC',
+      icon_name: 'bell',
     },
-  ],
+  },
 }
 
 /**
  * Announcement with OpenFrame logo icon.
  */
 export const WithOpenFrameLogo: Story = {
-  decorators: [
-    (Story) => {
-      mockAnnouncement({
-        ...baseAnnouncement,
-        id: 'story-logo',
-        title: 'Welcome to OpenFrame',
-        description: 'Your open-source IT infrastructure management platform.',
-        background_color: '#FFD951',
-        icon_name: 'openframe-logo',
-        cta_enabled: true,
-        cta_text: 'Get Started',
-        cta_url: '/getting-started',
-        cta_target: '_self',
-        cta_button_background_color: '#000000',
-        cta_button_text_color: '#FFD951',
-      })
-      return <Story />
+  args: {
+    initialAnnouncement: {
+      ...baseAnnouncement,
+      id: 'story-logo',
+      title: 'Welcome to OpenFrame',
+      description: 'Your open-source IT infrastructure management platform.',
+      background_color: '#FFD951',
+      icon_name: 'openframe-logo',
+      cta_enabled: true,
+      cta_text: 'Get Started',
+      cta_url: '/getting-started',
+      cta_target: '_self',
+      cta_button_background_color: '#000000',
+      cta_button_text_color: '#FFD951',
     },
-  ],
+  },
 }
 
 /**
  * Announcement with a PNG icon.
  */
 export const WithPNGIcon: Story = {
-  decorators: [
-    (Story) => {
-      mockAnnouncement({
-        ...baseAnnouncement,
-        id: 'story-png',
-        title: 'Partner Program Launch',
-        description: 'Become an OpenFrame certified partner and grow your business.',
-        background_color: '#C4B5FD',
-        icon_url: 'https://placehold.co/32x32/1a1a1a/white?text=OF',
-      })
-      return <Story />
+  args: {
+    initialAnnouncement: {
+      ...baseAnnouncement,
+      id: 'story-png',
+      title: 'Partner Program Launch',
+      description: 'Become an OpenFrame certified partner and grow your business.',
+      background_color: '#C4B5FD',
+      icon_url: 'https://placehold.co/32x32/1a1a1a/white?text=OF',
     },
-  ],
+  },
 }
 
 /**
  * Long title and description to test truncation.
  */
 export const LongContent: Story = {
-  decorators: [
-    (Story) => {
-      mockAnnouncement({
-        ...baseAnnouncement,
-        id: 'story-long',
-        title: 'This is a very long announcement title that should be truncated on smaller screens to prevent layout issues',
-        description:
-          'This is an extremely long description that goes into great detail about the announcement. It should be truncated on the desktop view and hidden on mobile view to keep the bar compact and readable.',
-        background_color: '#FCA5A5',
-        icon_name: 'info',
-        cta_enabled: true,
-        cta_text: 'Read Full Announcement',
-        cta_url: '/announcements/long',
-        cta_target: '_self',
-      })
-      return <Story />
+  args: {
+    initialAnnouncement: {
+      ...baseAnnouncement,
+      id: 'story-long',
+      title: 'This is a very long announcement title that should be truncated on smaller screens to prevent layout issues',
+      description:
+        'This is an extremely long description that goes into great detail about the announcement. It should be truncated on the desktop view and hidden on mobile view to keep the bar compact and readable.',
+      background_color: '#FCA5A5',
+      icon_name: 'info',
+      cta_enabled: true,
+      cta_text: 'Read Full Announcement',
+      cta_url: '/announcements/long',
+      cta_target: '_self',
     },
-  ],
+  },
+}
+
+/**
+ * previewMode — the admin live-preview path: render-only, inert dismiss,
+ * no fetch and no storage side effects.
+ */
+export const PreviewMode: Story = {
+  args: {
+    initialAnnouncement: {
+      ...baseAnnouncement,
+      id: 'story-preview',
+      title: 'Admin preview',
+      description: 'Exactly the live bar, but inert: dismiss does nothing.',
+    },
+    previewMode: true,
+  },
 }
 
 /**
  * No active announcement — the bar renders nothing.
  */
 export const NoAnnouncement: Story = {
+  args: { initialAnnouncement: null },
+  decorators: [
+    (Story) => (
+      <div>
+        <Story />
+        <p className="p-4 text-sm text-gray-500">
+          No announcement is active — the bar renders nothing above this text.
+        </p>
+      </div>
+    ),
+  ],
+}
+
+/**
+ * Client-only mode (no SSR) — the react-embedding-example structure: the
+ * embedder mounts an EndpointsRuntime provider (announcementsUrl is a fixed
+ * suffix under its one content base) and drops in a PROP-LESS bar. No
+ * platform knob anywhere on the client: the proxied server resolves its own
+ * platform via currentPlatform(). The decorator mocks the fetch.
+ */
+const embedEndpoints: EndpointsRuntime = {
+  announcementsUrl: '/content/api/announcements/active',
+  accessCode: { validateUrl: '/content/api/validate-access-code', consumeUrl: '/content/api/consume-access-code' },
+  contactUrl: '/content/api/contact',
+}
+
+export const ClientOnlyEmbed: Story = {
+  args: {},
   decorators: [
     (Story) => {
-      mockAnnouncement(null)
+      const originalFetch = window.fetch
+      window.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+        const requestUrl = typeof input === 'string' ? input : input.toString()
+        if (requestUrl.includes('/content/api/announcements/active')) {
+          return new Response(
+            JSON.stringify({
+              announcement: {
+                ...baseAnnouncement,
+                id: 'story-embed',
+                title: 'Client-only embed',
+                description: 'Fetched on mount through the EndpointsRuntime provider, no SSR.',
+              },
+            }),
+            { status: 200, headers: { 'Content-Type': 'application/json' } },
+          )
+        }
+        return originalFetch(input, init)
+      }) as typeof window.fetch
       return (
-        <div>
+        <EndpointsRuntimeContext.Provider value={embedEndpoints}>
           <Story />
-          <p className="p-4 text-sm text-gray-500">
-            No announcement is active — the bar renders nothing above this text.
-          </p>
-        </div>
+        </EndpointsRuntimeContext.Provider>
       )
     },
   ],

package/src/types/.announcement.md

@@ -4,7 +4,7 @@ TypeScript type definitions for the announcement system, providing comprehensive
 ## Key Components
 
 ### Core Database Models
-- **`Announcement`** - Main announcement entity with title, description, platform targeting, and visual customization
+- **`Announcement`** - Main announcement entity; platform targeting via hydrated `announcement_platforms?: EntityPlatformAssoc[]` (no singular platform_id/platform)
 - **`AnnouncementAsset`** - File attachments linked to announcements (images, documents, etc.)
 
 ### API Types
@@ -30,7 +30,7 @@ const newAnnouncement: CreateAnnouncementData = {
   background_color: "#FFC008",
   icon_type: "svg",
   icon_svg_name: "rocket",
-  platform_id: "openframe-platform-id",
+  platforms: ["openframe-platform-id"],
   is_active: true,
   cta_enabled: true,
   cta_text: "Learn More",