@flamingo-stack/openframe-frontend-core 0.0.481 → 0.0.482

package/src/utils/dev-sections/.openframe-dev-sections.md

@@ -1,49 +1,61 @@
-<!-- source-hash: 54e69314db343a8160db105f0636d9c5 -->
-Canonical metadata registry for all OpenFrame dev-center surface sections (Roadmap, Bug-fixes & Enhancements, Releases, Onboarding Guides, Help Center). Centralizes per-section icon, navigator card copy, hero copy, search config, and filter config into a single source of truth consumed by both the homepage navigator grid and destination page heroes.
+<!-- source-hash: 5b2aafd9e6be550c74161d5e68607913 -->
+Canonical metadata registry for the five OpenFrame dev-center surfaces (Roadmap, Bug-fixes & Enhancements, Releases, Onboarding Guides, Help Center), co-locating all per-section values consumed by both the homepage navigator cards and destination page heroes.
 
 ## Key Components
 
-### Exported Constants
+### Filter Option Constants
 
-| Export | Purpose |
-|--------|---------|
-| `ROADMAP_STATUS_OPTIONS` | Filter options for roadmap status (`all`, `completed`, `in_progress`) |
-| `DELIVERY_TASK_TYPE_OPTIONS` | Filter options for delivery task type (`all`, `Bug`, `Request`) |
-| `TICKET_STATUS_OPTIONS` | Filter options for help center ticket status (`all`, `open`, `closed`) |
-| `OPENFRAME_DEV_SECTIONS` | Primary registry — keyed object of all 5 dev-center sections |
+| Constant | Description |
+|---|---|
+| `ROADMAP_STATUS_OPTIONS` | `all` / `completed` / `in_progress` — roadmap status pills |
+| `DELIVERY_TASK_TYPE_OPTIONS` | `all` / `Bug` / `Request` — maps to ClickUp `custom_item_id` labels |
+| `TICKET_STATUS_OPTIONS` | `all` / `open` / `closed` — wire values accepted by `/api/chat/agent/find-ticket` |
 
-### Types
+### `OpenframeDevSection` Interface
 
-- **`OpenframeDevSection`** — Shape contract for each registry entry, including `href`, `icon`, `navigator`, `hero`, `search`, and `filter` fields
-- **`OpenframeDevSectionKey`** — Union type of valid section keys: `"roadmap" | "delivery" | "releases" | "onboarding" | "tickets"`
+Defines the shape of each registry entry:
 
-### Sections in the Registry
+| Field | Type | Purpose |
+|---|---|---|
+| `href` | `string` | Route path for nav cards and cross-links |
+| `icon` | `LucideIcon` | Icon component reference (not rendered at module load) |
+| `navigator` | `{ title, description }` | ~50-char teaser for homepage navigator cards |
+| `hero` | `{ title, description }` | ~120–150-char copy for destination page heroes |
+| `search` | `{ placeholder, paramKey } \| null` | Inline search bar config; `null` for onboarding |
+| `filter` | `{ label, paramKey, defaultValue, options } \| null` | Filter pill row config; `null` for onboarding |
 
-| Key | Route | Notes |
-|-----|-------|-------|
-| `roadmap` | `/roadmap` | Status filter |
-| `delivery` | `/bug-fixes-and-enhancements` | Task type filter |
-| `releases` | `/releases` | Release status filter |
-| `onboarding` | `/onboarding-guides` | Navigator card only — `hero`/`search`/`filter` are inert |
-| `tickets` | `/tickets` | Ticket status filter |
+### `OPENFRAME_DEV_SECTIONS`
+
+The central registry — a `const` object satisfying `Record<string, OpenframeDevSection>` with five keys: `roadmap`, `delivery`, `releases`, `onboarding`, `tickets`.
+
+> **Important:** The `onboarding` entry has `search: null` and `filter: null`. Its route (`/onboarding-guides`) is owned by `OnboardingGuidesCatalogView`, not the shared `DevSectionView`. Embedders iterating the registry that don't host this route should filter it out.
+
+### `OpenframeDevSectionKey`
+
+Derived type: `keyof typeof OPENFRAME_DEV_SECTIONS` — `"roadmap" | "delivery" | "releases" | "onboarding" | "tickets"`.
 
 ## Usage Example
 
 ```typescript
-import { OPENFRAME_DEV_SECTIONS, type OpenframeDevSectionKey } from './openframe-dev-sections'
+import {
+  OPENFRAME_DEV_SECTIONS,
+  type OpenframeDevSectionKey,
+} from './openframe-dev-sections'
 
-// Render all navigator cards (skip onboarding if route is not hosted)
+// Render all homepage navigator cards (skip inert onboarding if route not hosted)
 const navSections = Object.values(OPENFRAME_DEV_SECTIONS).filter(
   (s) => s.href !== '/onboarding-guides'
 )
 
-// Access a specific section's hero copy
-const { title, description } = OPENFRAME_DEV_SECTIONS.roadmap.hero
+// Access a specific section by key
+const roadmap = OPENFRAME_DEV_SECTIONS['roadmap']
+console.log(roadmap.hero.description)
+// "See what's in flight, what's planned, and what's up for community vote..."
 
-// Type-safe section key lookup
-function getSectionConfig(key: OpenframeDevSectionKey) {
-  return OPENFRAME_DEV_SECTIONS[key]
+// Type-safe key usage
+function getSectionHref(key: OpenframeDevSectionKey): string {
+  return OPENFRAME_DEV_SECTIONS[key].href
 }
 ```
 
-> **⚠️ Embedder Note — `onboarding` entry:** The `onboarding` section drives the homepage navigator card only. Its `hero`, `search`, and `filter` fields are intentionally empty/null. Embedders that don't host `/onboarding-guides` should filter it out before iterating the registry.
+**Source:** [`src/utils/openframe-dev-sections.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/utils/openframe-dev-sections.ts)

package/src/utils/dismiss-cookie.ts

@@ -0,0 +1,55 @@
+/**
+ * Dismissal-cookie primitives — THE one implementation of "this surface was
+ * dismissed", shared by every dismissible surface (announcement bar, floating
+ * walkthrough video, and anything added later).
+ *
+ * The dismissal rule is an ID MATCH, never mere cookie presence: the cookie
+ * stores the id of the LAST dismissed item, so publishing a NEW item re-shows
+ * the surface while the old dismissal still suppresses the old item.
+ *
+ * No `"use client"` on purpose — `isDismissedCookieValue` is pure and is used by
+ * server code (the hub's root layout reads the cookie during SSR to avoid a
+ * flash); the DOM-touching helpers guard on `typeof document`.
+ */
+
+/** One year, the standard dismissal horizon for these surfaces. */
+const DISMISS_COOKIE_MAX_AGE_SECONDS = 31_536_000;
+
+/** THE dismissal match rule. `undefined` id (nothing active) → not dismissed. */
+export function isDismissedCookieValue(
+  cookieValue: string | undefined,
+  id: string | undefined,
+): boolean {
+  return !!id && cookieValue === id;
+}
+
+/**
+ * Read a dismissal cookie. Returns `undefined` when absent OR malformed:
+ * `decodeURIComponent` throws `URIError` on bad percent-encoding, and callers
+ * run this inside reveal paths where an uncaught throw would hide the surface
+ * permanently. Failing open (treated as not-dismissed) is always the safe side.
+ */
+export function readDismissCookie(name: string): string | undefined {
+  if (typeof document === 'undefined') return undefined;
+  const match = document.cookie
+    .split('; ')
+    .find((row) => row.startsWith(`${name}=`));
+  if (!match) return undefined;
+  try {
+    return decodeURIComponent(match.slice(name.length + 1));
+  } catch {
+    return undefined;
+  }
+}
+
+/** Persist a dismissal (cookie only, 1 year). */
+export function writeDismissCookie(name: string, id: string): void {
+  if (typeof document === 'undefined') return;
+  document.cookie = `${name}=${encodeURIComponent(id)}; path=/; max-age=${DISMISS_COOKIE_MAX_AGE_SECONDS}; SameSite=Lax`;
+}
+
+/** Clear a dismissal (test/story helper). */
+export function clearDismissCookie(name: string): void {
+  if (typeof document === 'undefined') return;
+  document.cookie = `${name}=; path=/; max-age=0`;
+}

package/src/utils/dismissal-storage.ts

@@ -0,0 +1,38 @@
+/**
+ * Walkthrough-video dismissal — a thin key-naming layer over the shared
+ * dismissal-cookie primitives (`utils/dismiss-cookie.ts`). Same id-match
+ * semantics as the announcement bar, from the same implementation.
+ */
+
+import {
+  isDismissedCookieValue,
+  readDismissCookie,
+  writeDismissCookie,
+  clearDismissCookie,
+} from './dismiss-cookie';
+
+/** Cookie-name stem. */
+export const WALKTHROUGH_VIDEO_DISMISS_KEY = 'walkthrough-video-dismissed';
+
+/** THE per-platform cookie name — the ONE home for the encoding, mirroring
+ *  `announcementDismissCookieName`. Hosts must not rebuild it inline, or an SSR
+ *  reader added later will restate the separator. */
+export function walkthroughDismissCookieName(platform: string): string {
+  return `${WALKTHROUGH_VIDEO_DISMISS_KEY}:${platform}`;
+}
+
+/** Client-side dismissal check (id-match). Reads a cookie, so call it from an
+ *  effect, never during render. */
+export function isWalkthroughDismissed(key: string, id: string | undefined): boolean {
+  return isDismissedCookieValue(readDismissCookie(key), id);
+}
+
+/** Persist a dismissal for this video id. */
+export function dismissWalkthrough(key: string, id: string): void {
+  writeDismissCookie(key, id);
+}
+
+/** Clear a platform key's dismissal (test/story helper). */
+export function clearWalkthroughDismissal(key: string): void {
+  clearDismissCookie(key);
+}

package/src/utils/index.ts

@@ -91,6 +91,9 @@ export * from './color-analysis'
 
 // Announcement dismissal store (cookie SSOT; server-safe name/match helpers)
 export * from './announcement-storage'
+// cookie id-match dismissal store (walkthrough video widget)
+export * from './dismiss-cookie'
+export * from './dismissal-storage'
 
 // Image-proxy URL builder (pure, runtime-configurable)
 export {