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

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`.

package/src/utils/announcement-storage.ts

@@ -1,36 +1,82 @@
-// Stub for announcement storage
-export interface AnnouncementStorageOptions {
-  key: string;
-  defaultValue?: any;
+/**
+ * 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 bar (no flash for
+ * dismissed users), and the client reads it via `isAnnouncementDismissed`.
+ * One cookie per platform holding the LAST dismissed announcement id —
+ * dismissal is an id-match, never mere cookie presence, so a new announcement
+ * always shows after an old one was dismissed, and re-activating an old
+ * announcement intentionally re-shows it.
+ *
+ * The legacy per-id localStorage key (`<platform>-announcement-<id>-dismissed`)
+ * is READ-ONLY legacy: consulted only when no cookie exists for the platform,
+ * purely as the migration trigger (the bar's mount effect backfills the
+ * cookie). New dismissals write the cookie only, so the second store dies out.
+ *
+ * No `"use client"` directive on purpose — `announcementDismissCookieName` and
+ * `isDismissedCookieValue` are pure/isomorphic and imported by the hub's
+ * server layout; the DOM-touching helpers guard on `typeof document`.
+ */
+
+/** Cookie name for a platform's dismissed-announcement id — the ONE home for
+ *  the encoding, shared by the client writer and the hub's SSR reader. */
+export function announcementDismissCookieName(platform: string): string {
+  return `${platform}-announcement-dismissed`
 }
 
-export function getStoredAnnouncement(key: string): any {
-  if (typeof window !== 'undefined') {
-    try {
-      return JSON.parse(localStorage.getItem(key) || 'null');
-    } catch {
-      return null;
-    }
-  }
-  return null;
+/** THE dismissal match rule (id-match, not presence), shared across the
+ *  server/client boundary. `undefined` id (no active announcement) → false. */
+export function isDismissedCookieValue(
+  cookieValue: string | undefined,
+  id: string | undefined,
+): boolean {
+  return !!id && cookieValue === id
+}
+
+function readCookie(name: string): string | undefined {
+  if (typeof document === 'undefined') return undefined
+  const match = document.cookie
+    .split('; ')
+    .find((row) => row.startsWith(`${name}=`))
+  return match ? decodeURIComponent(match.slice(name.length + 1)) : undefined
 }
 
-export function setStoredAnnouncement(key: string, value: any): void {
-  if (typeof window !== 'undefined') {
-    try {
-      localStorage.setItem(key, JSON.stringify(value));
-    } catch {
-      // Ignore storage errors
-    }
+const legacyDismissKey = (platform: string, id: string) =>
+  `${platform}-announcement-${id}-dismissed`
+
+/** Persist a dismissal: cookie only (1 year). The SSR layout sees it on the
+ *  next request; localStorage is intentionally NOT written (read-only legacy). */
+export function dismissAnnouncement(platform: string, id: string): void {
+  if (typeof document === 'undefined') return
+  const name = announcementDismissCookieName(platform)
+  document.cookie = `${name}=${encodeURIComponent(id)}; path=/; max-age=31536000; SameSite=Lax`
+}
+
+/**
+ * Client-side dismissal check — cookie-first: the legacy localStorage key is
+ * consulted ONLY when no cookie exists for the platform. Reads browser
+ * storage, so callers must invoke it from effects, never during render
+ * (a render-time read would desync hydration from the SSR HTML).
+ */
+export function isAnnouncementDismissed(platform: string, id: string): boolean {
+  if (typeof document === 'undefined') return false
+  const cookieValue = readCookie(announcementDismissCookieName(platform))
+  if (cookieValue !== undefined) return isDismissedCookieValue(cookieValue, id)
+  try {
+    return localStorage.getItem(legacyDismissKey(platform, id)) !== null
+  } catch {
+    return false
   }
 }
 
-export function clearStoredAnnouncement(key: string = 'announcement'): void {
-  if (typeof window !== 'undefined') {
-    try {
-      localStorage.removeItem(key);
-    } catch {
-      // Ignore storage errors
-    }
+/** One-time cleanup of pre-refactor storage: the orphaned announcement cache
+ *  (the old "instant paint" blob) — called from the bar's mount effect. */
+export function clearLegacyAnnouncementCache(platform: string): void {
+  if (typeof window === 'undefined') return
+  try {
+    localStorage.removeItem(`${platform}-announcement-cache`)
+  } catch {
+    // ignore storage errors
   }
-}
+}

package/src/utils/app-config.ts

@@ -16,5 +16,14 @@ export function getAppConfig() {
 }
 
 export function getAppType() {
-  return process.env.NEXT_PUBLIC_APP_TYPE || 'openmsp';
+  // The exact `process.env.NEXT_PUBLIC_APP_TYPE` member expression is kept so
+  // Next/webpack can statically inline it. The try/catch makes the call safe
+  // in non-Next React hosts (Vite/CRA embeds) where `process` does not exist
+  // at runtime — those hosts fall back to 'openmsp' or pass an explicit
+  // platform where it matters (e.g. AnnouncementBar's `platform` prop).
+  try {
+    return process.env.NEXT_PUBLIC_APP_TYPE || 'openmsp';
+  } catch {
+    return 'openmsp';
+  }
 }

package/src/utils/color-analysis.ts

@@ -26,7 +26,7 @@ export function hexToRgb(hex: string): [number, number, number] {
 /**
  * Calculate relative luminance for contrast calculations
  */
-function getLuminance(rgb: [number, number, number]): number {
+export function getLuminance(rgb: [number, number, number]): number {
   const [r, g, b] = rgb.map(c => {
     c = c / 255;
     return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
@@ -45,6 +45,21 @@ export function getContrastRatio(color1: [number, number, number], color2: [numb
   return (brightest + 0.05) / (darkest + 0.05);
 }
 
+/**
+ * Pick the readable foreground shade for an arbitrary background hex — 'dark'
+ * when dark text has the better WCAG contrast on it, 'light' otherwise.
+ * Callers map the result to an ODS THEME, not to color literals (e.g. the
+ * announcement bar scopes its content with .theme-light when the background
+ * needs dark-on-light, .theme-dark otherwise — every color then resolves
+ * from the active theme's own tokens).
+ */
+export function pickReadableTextColor(bgHex: string): 'dark' | 'light' {
+  const bg = hexToRgb(bgHex);
+  const darkContrast = getContrastRatio(bg, [26, 26, 26]);
+  const lightContrast = getContrastRatio(bg, [250, 250, 250]);
+  return darkContrast >= lightContrast ? 'dark' : 'light';
+}
+
 /**
  * Extract dominant color from image canvas
  */

package/src/utils/index.ts

@@ -85,6 +85,9 @@ export * from './generic-domain-utils'
 // Color analysis (canvas-based image color extraction)
 export * from './color-analysis'
 
+// Announcement dismissal store (cookie SSOT; server-safe name/match helpers)
+export * from './announcement-storage'
+
 // Image-proxy URL builder (pure, runtime-configurable)
 export {
   type GetProxiedImageUrlOptions,