@flamingo-stack/openframe-frontend-core 0.0.481 → 0.0.482-snapshot.20260726003127

package/src/utils/announcement-storage.ts

@@ -19,6 +19,8 @@
  * server layout; the DOM-touching helpers guard on `typeof document`.
  */
 
+import { isDismissedCookieValue, readDismissCookie, writeDismissCookie, clearDismissCookie } from './dismiss-cookie'
+
 /** 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 {
@@ -27,20 +29,10 @@ export function announcementDismissCookieName(platform: string): string {
 
 /** 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
-}
+// The match rule + cookie IO live in `utils/dismiss-cookie.ts` — shared with
+// every other dismissible surface. Re-exported so existing importers (incl. the
+// hub's SSR layout) keep their import path.
+export { isDismissedCookieValue } from './dismiss-cookie'
 
 const legacyDismissKey = (platform: string, id: string) =>
   `${platform}-announcement-${id}-dismissed`
@@ -49,8 +41,7 @@ const legacyDismissKey = (platform: string, id: string) =>
  *  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`
+  writeDismissCookie(announcementDismissCookieName(platform), id)
 }
 
 /**
@@ -61,7 +52,7 @@ export function dismissAnnouncement(platform: string, id: string): void {
  */
 export function isAnnouncementDismissed(platform: string, id: string): boolean {
   if (typeof document === 'undefined') return false
-  const cookieValue = readCookie(announcementDismissCookieName(platform))
+  const cookieValue = readDismissCookie(announcementDismissCookieName(platform))
   if (cookieValue !== undefined) return isDismissedCookieValue(cookieValue, id)
   try {
     return localStorage.getItem(legacyDismissKey(platform, id)) !== null
@@ -74,7 +65,7 @@ export function isAnnouncementDismissed(platform: string, id: string): boolean {
  *  keys) — test/story helper so callers never restate the key encoding. */
 export function clearAnnouncementDismissals(platform: string): void {
   if (typeof document === 'undefined') return
-  document.cookie = `${announcementDismissCookieName(platform)}=; path=/; max-age=0`
+  clearDismissCookie(announcementDismissCookieName(platform))
   try {
     const prefix = `${platform}-announcement-`
     Object.keys(localStorage).forEach((key) => {

package/src/utils/dev-sections/.dev-section-param-keys.md

@@ -0,0 +1,51 @@
+<!-- source-hash: 4c86af12e778cd64fe713a8cdb304259 -->
+Defines shared URL parameter keys and anchor ID utilities for the OpenFrame dev-center, serving as the single source of truth between the chrome registry (which writes query params) and list views (which read them).
+
+## Key Components
+
+### `DEV_SECTION_PARAM_KEYS`
+A `const` object mapping logical filter names to their canonical URL query parameter strings.
+
+| Key | URL Param | Purpose |
+|---|---|---|
+| `search` | `search` | Free-text search, shared by all dev-center sections |
+| `status` | `status` | Roadmap / Help Center ticket status filter |
+| `releaseStatus` | `release_status` | Product-releases stability-tier filter |
+| `deliveryTaskType` | `task_type` | Delivery task-type filter (bug-fix / enhancement) |
+
+### `DevSectionAnchorKind`
+Union type constraining valid section identifiers used in DOM anchor IDs: `'roadmap' | 'delivery' | 'ticket'`.
+
+### `devSectionAnchorId(section, id)`
+Composes the canonical `<section>-<id>` anchor string used consistently by row components (`DeliveryRow`, `RoadmapCard`, `HelpCenterCard`) and the URL composer (`appendSearchAndHash`).
+
+## Usage Example
+
+```typescript
+import {
+  DEV_SECTION_PARAM_KEYS,
+  DevSectionAnchorKind,
+  devSectionAnchorId,
+} from './dev-section-param-keys'
+
+// Reading a filter from the URL (list view side)
+const url = new URL(window.location.href)
+const status = url.searchParams.get(DEV_SECTION_PARAM_KEYS.status)
+const taskType = url.searchParams.get(DEV_SECTION_PARAM_KEYS.deliveryTaskType)
+
+// Writing a filter to the URL (chrome registry side)
+url.searchParams.set(DEV_SECTION_PARAM_KEYS.releaseStatus, 'stable')
+
+// Generating a consistent anchor ID for a roadmap item
+const anchorId = devSectionAnchorId('roadmap', 'item-42')
+// → "roadmap-item-42"
+
+// Used in a row component
+<div id={devSectionAnchorId('delivery' as DevSectionAnchorKind, task.id)} />
+```
+
+## Why This Exists
+
+Without this module, the chrome and view layers could each hard-code different string literals (e.g., `"task_type"` vs `"taskType"`), causing silent filtering failures. Since this file has **no React or heavy dependencies**, it is safely importable from both server-bundled utilities and client-side views.
+
+**Source:** [`dev-section-param-keys.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/dev-section-param-keys.ts)

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,44 @@
+/**
+ * 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. Shaped exactly
+ *  like `announcementDismissCookieName` (`<platform>-<name>-dismissed`): `:` is
+ *  not a `token` character under RFC 6265, so the old `…-dismissed:<platform>`
+ *  form was only working on browser leniency. Hosts must not rebuild this
+ *  inline, or an SSR reader added later will restate the separator.
+ *
+ *  Renaming orphans existing cookies, so anyone who had dismissed the card sees
+ *  it once more. Deliberate and one-time: the alternative is reading both names
+ *  forever to save a single re-dismissal. */
+export function walkthroughDismissCookieName(platform: string): string {
+  return `${platform}-${WALKTHROUGH_VIDEO_DISMISS_KEY}`;
+}
+
+/** 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 {