@flamingo-stack/openframe-frontend-core 0.0.404 → 0.0.405-snapshot.20260711081601

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",

package/src/types/announcement.ts

@@ -1,7 +1,7 @@
 // Announcement system TypeScript types
-import type { LegacyPlatform, PlatformFilter, PlatformRecord } from './platform';
+import type { LegacyPlatform, PlatformFilter } from './platform';
+import type { EntityPlatformAssoc } from './entity-platform';
 
-// For backward compatibility, maintain the old Platform type temporarily
 // Database Models
 export interface Announcement {
   id: string;
@@ -12,8 +12,9 @@ export interface Announcement {
   icon_url?: string;
   /** Extra props for the main bar/icon */
   icon_props?: Record<string, any>;
-  platform_id: string;  // Foreign key to platforms table
-  platform?: PlatformRecord;  // Joined platform data
+  /** Hydrated entity_platforms associations (featured-first) — what the hub
+   *  DAL's attachPlatformsToRow(s) emits. No singular platform/platform_id. */
+  announcement_platforms?: EntityPlatformAssoc[];
   is_active: boolean;
   // CTA (Call-To-Action) fields
   cta_enabled?: boolean;
@@ -109,10 +110,25 @@ export interface AnnouncementListResponse {
   };
 }
 
+/**
+ * Wire shape of GET /api/announcements/active — the single typed home for the
+ * `{ announcement }` envelope (hub route return + AnnouncementBar's
+ * useSelfFetch generic). `null` when no active announcement exists.
+ */
 export interface AnnouncementResponse {
-  announcement: Announcement;
+  announcement: Announcement | null;
 }
 
+/**
+ * Default CTA button colors — one home for the pair the DAL create/update
+ * defaults and the admin form both reference. Announcement colors are
+ * admin-chosen data (not ODS-token surfaces) by design.
+ */
+export const ANNOUNCEMENT_CTA_DEFAULTS = {
+  background: '#1A1A1A',
+  text: '#FAFAFA',
+} as const;
+
 // Form Data Types
 export interface AnnouncementFormData {
   title: string;
@@ -214,8 +230,22 @@ export interface AnnouncementStats {
 
 // Component Props Types
 export interface AnnouncementBarProps {
-  announcement?: Announcement;
-  onDismiss?: (announcementId: string) => void;
+  /**
+   * SSR mode seed. `null` = the server resolved "nothing to show" (no active
+   * announcement, or dismissed via cookie) — seeds the fetch hook and skips
+   * the mount fetch. Absent (`undefined`) = client-only mode: the bar
+   * self-fetches on mount from the EndpointsRuntime provider's
+   * `announcementsUrl` (see react-embedding-example — no per-component URL
+   * or platform knobs; the server resolves its own platform via
+   * currentPlatform()).
+   */
+  initialAnnouncement?: Announcement | null;
+  /**
+   * Render-only mode for the admin live preview: no fetch/revalidation, inert
+   * dismiss button, and no storage side effects (never writes dismissal
+   * cookies or touches localStorage).
+   */
+  previewMode?: boolean;
   className?: string;
 }
 

package/src/utils/.announcement-storage.md

@@ -1,36 +1,31 @@
-<!-- source-hash: eb9e1e114c43007debee28971d977a02 -->
-A utility module for managing announcement data persistence in browser localStorage with safe server-side rendering support.
+<!-- source-hash: pending-regeneration -->
+Announcement dismissal store. The dismissal COOKIE is the single source of truth — the hub's root layout reads it server-side to decide whether to SSR-seed the AnnouncementBar (no flash for dismissed users); the legacy per-id localStorage key is read-only legacy consulted only when no cookie exists (migration trigger).
 
 ## Key Components
 
-- **`AnnouncementStorageOptions`** - Interface defining storage configuration with key and optional default value
-- **`getStoredAnnouncement(key)`** - Retrieves and parses announcement data from localStorage
-- **`setStoredAnnouncement(key, value)`** - Stores announcement data as JSON in localStorage
-- **`clearStoredAnnouncement(key?)`** - Removes announcement data from localStorage (defaults to 'announcement' key)
+- **`announcementDismissCookieName(platform)`** - The ONE home for the cookie-name encoding (`<platform>-announcement-dismissed`), shared by the client writer and the hub's SSR reader
+- **`isDismissedCookieValue(cookieValue, id)`** - THE dismissal match rule (id-match, never mere cookie presence), pure and isomorphic — shared across the server/client boundary
+- **`dismissAnnouncement(platform, id)`** - Persists a dismissal (cookie only, 1 year, SameSite=Lax); localStorage is intentionally not written
+- **`isAnnouncementDismissed(platform, id)`** - Client-side check, cookie-first with legacy-localStorage fallback; reads browser storage so it must be called from effects, never during render
+- **`clearLegacyAnnouncementCache(platform)`** - One-time cleanup of the pre-refactor localStorage "instant paint" cache blob
 
 ## Usage Example
 
 ```typescript
-import { 
-  getStoredAnnouncement, 
-  setStoredAnnouncement, 
-  clearStoredAnnouncement 
+import {
+  dismissAnnouncement,
+  isAnnouncementDismissed,
+  announcementDismissCookieName,
+  isDismissedCookieValue,
 } from './announcement-storage';
 
-// Store announcement dismissal state
-setStoredAnnouncement('banner-dismissed', { 
-  dismissed: true, 
-  timestamp: Date.now() 
-});
+// Client (in an effect):
+if (isAnnouncementDismissed('openframe', announcement.id)) { /* collapse */ }
+dismissAnnouncement('openframe', announcement.id);
 
-// Check if announcement was dismissed
-const dismissalState = getStoredAnnouncement('banner-dismissed');
-if (dismissalState?.dismissed) {
-  console.log('Banner was dismissed');
-}
-
-// Clear announcement data
-clearStoredAnnouncement('banner-dismissed');
+// Server (hub root layout):
+const cookieValue = (await cookies()).get(announcementDismissCookieName(platform))?.value;
+const dismissed = isDismissedCookieValue(cookieValue, announcement?.id);
 ```
 
-All functions include browser environment checks and error handling to prevent issues during server-side rendering or when localStorage is unavailable.
+No `"use client"` directive on purpose — the name/match helpers are imported by the hub's server layout; DOM-touching helpers guard on `typeof document`.