@flamingo-stack/openframe-frontend-core 0.0.582-1967.5390.1 → 0.0.582

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.582-1967.5390.1",
+  "version": "0.0.582",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/features/.push-button-selector.md

@@ -1,4 +1,4 @@
-<!-- source-hash: 1b470f4e084b6cb0c7cd286c460838ca -->
+<!-- source-hash: 0ccfb311d1bb254bbfb9ffdb994a9af1 -->
 A client-side React component that renders a list of toggleable push-button options with support for single/multi-select, section grouping, disabled states with tooltips, loading skeletons, and error handling.
 
 ## Key Components

package/src/components/features/push-button-selector.tsx

@@ -2,7 +2,9 @@
 
 import { Check } from 'lucide-react';
 import type React from 'react';
-import { Badge } from '../ui';
+import { useEffect, useRef } from 'react';
+import { UnifiedSkeleton } from '../loading';
+import { Badge, Input } from '../ui';
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '../ui/tooltip';
 
 export interface SelectableOption {
@@ -27,6 +29,28 @@ export interface SectionDefinition {
   description?: string; // Optional description shown under section label
 }
 
+/** SERVER-SIDE search: the selector renders the input; the PARENT owns the
+ *  query state and re-fetches `options` (never a client-side .filter of a
+ *  pre-fetched list). While `isLoading`, the input stays mounted (typing
+ *  must not lose focus to a skeleton swap). */
+export interface PushButtonSelectorSearch {
+  value: string;
+  onChange: (value: string) => void;
+  placeholder?: string;
+  ariaLabel?: string;
+}
+
+/** Lazy paging: the option list becomes a FIXED-HEIGHT scroll viewport with
+ *  an IntersectionObserver sentinel near the bottom — the selector calls
+ *  `onLoadMore` as the user scrolls; the parent appends to `options`. */
+export interface PushButtonSelectorLazyLoad {
+  hasMore: boolean;
+  isFetchingMore: boolean;
+  onLoadMore: () => void;
+  /** CSS height of the scroll viewport (default '336px' ≈ 6 rows). */
+  maxHeight?: string;
+}
+
 interface PushButtonSelectorProps {
   options: SelectableOption[];
   selectedIds: string[];
@@ -41,25 +65,37 @@ interface PushButtonSelectorProps {
   error?: string | null;
   skeletonCount?: number;
   sections?: SectionDefinition[]; // Optional sections for grouping options
+  /** Built-in server-side search input (see PushButtonSelectorSearch). */
+  search?: PushButtonSelectorSearch;
+  /** Built-in fixed-height scroll + infinite paging (see PushButtonSelectorLazyLoad). */
+  lazyLoad?: PushButtonSelectorLazyLoad;
+  /** Rendered inside the list when `options` is empty and not loading. */
+  emptyMessage?: React.ReactNode;
+  /** Rendered under the list (result counts, hints). */
+  footer?: React.ReactNode;
 }
 
-// Skeleton component matching external pattern from announcement-form.tsx
+// Composed from the app-wide UnifiedSkeleton system (components/loading) —
+// the same base every other loading surface uses (bg-ods-skeleton pulse,
+// prefers-reduced-motion support, role="status" a11y). Each skeleton row
+// mirrors a LOADED option row exactly (bg-ods-bg card, p-4, icon + two
+// 20px-tall text lines + selection box) so the list never jumps on load.
 function PushButtonSelectorSkeleton({ count = 3, hasTitle }: { count?: number; hasTitle?: boolean }) {
   return (
-    <div className="space-y-3">
-      {hasTitle && <div className="h-5 w-20 animate-pulse rounded bg-ods-skeleton" />}
+    <div className="space-y-3" role="status" aria-label="Loading options">
+      {hasTitle && <UnifiedSkeleton className="h-5 w-20" aria-label="Loading title" />}
       <div className="space-y-3">
         {Array.from({ length: count }, (_, i) => (
-          <div key={i} className="animate-pulse rounded-lg border border-ods-border bg-ods-skeleton p-4">
-            <div className="flex items-center justify-between">
+          <div key={i} className="rounded-lg border border-ods-border bg-ods-bg p-4">
+            <div className="flex items-center justify-between gap-4">
               <div className="flex items-center gap-3">
-                <div className="h-8 w-8 rounded bg-ods-skeleton" />
+                <UnifiedSkeleton className="h-8 w-8" aria-label="Loading icon" />
                 <div>
-                  <div className="mb-1 h-4 w-20 rounded bg-ods-skeleton" />
-                  <div className="h-3 w-32 rounded bg-ods-skeleton" />
+                  <UnifiedSkeleton variant="text" className="mb-2 h-4 w-24" aria-label="Loading name" />
+                  <UnifiedSkeleton variant="text" className="h-4 w-36" aria-label="Loading description" />
                 </div>
               </div>
-              <div className="h-6 w-6 rounded border-2 border-ods-border bg-ods-skeleton" />
+              <UnifiedSkeleton className="h-6 w-6" aria-label="Loading selection state" />
             </div>
           </div>
         ))}
@@ -94,18 +130,68 @@ export function PushButtonSelector({
   error = null,
   skeletonCount = 3,
   sections,
+  search,
+  lazyLoad,
+  emptyMessage,
+  footer,
 }: PushButtonSelectorProps) {
-  // LOADING STATE
-  if (isLoading) {
+  // Lazy-load sentinel: observe within the scroll viewport so onLoadMore
+  // fires as the user approaches the bottom. Hooks run unconditionally
+  // (before the early returns) per the rules of hooks. Pass a STABLE
+  // onLoadMore (react-query's fetchNextPage is) — an inline arrow re-arms
+  // the observer each render (harmless, just wasteful).
+  const scrollRef = useRef<HTMLDivElement | null>(null);
+  const sentinelRef = useRef<HTMLDivElement | null>(null);
+  const lazyHasMore = lazyLoad?.hasMore ?? false;
+  const lazyFetching = lazyLoad?.isFetchingMore ?? false;
+  const onLoadMore = lazyLoad?.onLoadMore;
+  const optionCount = options.length;
+  useEffect(() => {
+    const sentinel = sentinelRef.current;
+    const root = scrollRef.current;
+    if (!sentinel || !root || !onLoadMore || !lazyHasMore) return undefined;
+    const observer = new IntersectionObserver(
+      entries => {
+        if (entries.some(e => e.isIntersecting) && !lazyFetching) {
+          onLoadMore();
+        }
+      },
+      { root, rootMargin: '80px' },
+    );
+    observer.observe(sentinel);
+    return () => {
+      observer.disconnect();
+    };
+    // optionCount: re-arm when the list grows (the sentinel moves).
+  }, [lazyHasMore, lazyFetching, onLoadMore, optionCount]);
+
+  const searchInput = search ? (
+    <Input
+      value={search.value}
+      onChange={e => search.onChange(e.target.value)}
+      placeholder={search.placeholder}
+      aria-label={search.ariaLabel ?? search.placeholder ?? 'Search'}
+    />
+  ) : null;
+
+  // Framed mode (search and/or lazyLoad): loading and error are NOT early
+  // returns — the frame (title, search input, fixed-height viewport, footer)
+  // must stay pixel-identical across loading/loaded/empty/error, with only
+  // the viewport CONTENT swapping. An early-return skeleton dropped the
+  // bordered viewport + footer and rendered shorter rows, so the whole
+  // section collapsed and jumped on every debounced search.
+  const framed = !!search || !!lazyLoad;
+
+  // LOADING / ERROR STATES — legacy (unframed) consumers keep the historical
+  // whole-component swap, byte-identical.
+  if (isLoading && !framed) {
     return (
       <div className={className}>
         <PushButtonSelectorSkeleton count={skeletonCount} hasTitle={!!title} />
       </div>
     );
   }
-
-  // ERROR STATE
-  if (error) {
+  if (error && !framed) {
     return (
       <div className={className}>
         <PushButtonSelectorError message={error} title={title} />
@@ -252,15 +338,54 @@ export function PushButtonSelector({
     );
   };
 
+  // ~82px per row: enough skeleton rows to fill the fixed viewport, so the
+  // loading state occupies the SAME height as the loaded list.
+  const framedSkeletonCount = lazyLoad ? Math.max(skeletonCount, 4) : skeletonCount;
+  const listContent = isLoading ? (
+    <PushButtonSelectorSkeleton count={framedSkeletonCount} />
+  ) : error ? (
+    <PushButtonSelectorError message={error} />
+  ) : (
+    <>
+      {options.length === 0 && emptyMessage !== undefined ? (
+        <div className="text-ods-text-secondary text-h6">{emptyMessage}</div>
+      ) : (
+        renderOptionsContent()
+      )}
+      {lazyLoad ? (
+        <>
+          <div ref={sentinelRef} />
+          {lazyLoad.isFetchingMore ? (
+            <div className="py-2 text-center text-ods-text-secondary text-h6">Loading more…</div>
+          ) : null}
+        </>
+      ) : null}
+    </>
+  );
+
   return (
     <TooltipProvider delayDuration={150}>
       <div className={`space-y-4 ${className}`}>
         {title && <h3 className="text-ods-text-primary text-h5">{title}</h3>}
 
-        {renderOptionsContent()}
+        {searchInput}
+
+        {lazyLoad ? (
+          <div
+            ref={scrollRef}
+            className="space-y-4 overflow-y-auto rounded-lg border border-ods-border p-2"
+            style={{ height: lazyLoad.maxHeight ?? '336px' }}
+          >
+            {listContent}
+          </div>
+        ) : (
+          listContent
+        )}
+
+        {footer}
 
         {/* Selection Summary */}
-        {selectionSummary && validSelectedIds.length > 0 && (
+        {!isLoading && !error && selectionSummary && validSelectedIds.length > 0 && (
           <div className="rounded-lg border border-ods-success bg-ods-success-secondary p-4">
             <div className="mb-2 flex items-center gap-2">
               <div className="h-2 w-2 rounded-full bg-ods-success"></div>

package/src/utils/announcement-storage.ts

@@ -1,24 +1,18 @@
 /**
  * Announcement dismissal store.
  *
- * The dismissal COOKIE is the source of truth wherever cookies work: 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.
- *
- * On a cookie-averse document (see `utils/dismiss-cookie.ts`) the primitive
- * writes `<platform>-announcement-dismissed` to localStorage instead. Do not
- * mistake it for the legacy key below and delete the write: it is the ONLY
- * thing making a dismissal persist in a shell. `clearAnnouncementDismissals`' prefix sweep does match it, which
- * is right — a full reset should take both.
+ * 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). Nothing writes it any more, so that store dies out.
+ * 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
@@ -42,21 +36,18 @@ export { isDismissedCookieValue } from './dismiss-cookie';
 
 const legacyDismissKey = (platform: string, id: string) => `${platform}-announcement-${id}-dismissed`;
 
-/** Persist a dismissal (1 year). The SSR layout sees it on the next request —
- *  except in a native shell, where the primitive falls back to localStorage and
- *  there is no SSR layout to see it anyway. The LEGACY per-id key is still never
- *  written. */
+/** 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;
   writeDismissCookie(announcementDismissCookieName(platform), id);
 }
 
 /**
- * Client-side dismissal check — primary store first, with the legacy
- * localStorage key consulted ONLY when that comes back empty. Reads browser
- * storage, so callers must invoke it
- * from effects, never during render (a render-time read would desync hydration
- * from the SSR HTML).
+ * 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;
@@ -69,8 +60,8 @@ export function isAnnouncementDismissed(platform: string, id: string): boolean {
   }
 }
 
-/** Remove ALL dismissal state for a platform — test/story helper so callers
- *  never restate the key encoding. The header owns the tier inventory. */
+/** Remove ALL dismissal state for a platform (cookie + legacy localStorage
+ *  keys) — test/story helper so callers never restate the key encoding. */
 export function clearAnnouncementDismissals(platform: string): void {
   if (typeof document === 'undefined') return;
   clearDismissCookie(announcementDismissCookieName(platform));

package/src/utils/dismiss-cookie.ts

@@ -3,92 +3,31 @@
  * 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 store
- * holds the id of the LAST dismissed item, so publishing a NEW item re-shows
+ * 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.
  *
- * TWO TIERS. The cookie is primary wherever cookies work; on a cookie-averse
- * document `localStorage` takes over under the same key. See `canUseCookies`
- * for when that is, and `fallbackStore` for why it is a fallback and not a
- * mirror.
- *
  * 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`.
  */
 
-import { createLocalStorageAdapter } from './local-storage-adapter';
-
-/** One year — the COOKIE tier's horizon. The fallback tier has no expiry, so a
- *  dismissal in a native shell is permanent; adding an expiry envelope there
- *  would be inventing a second encoding to answer a question nobody has asked. */
+/** One year, the standard dismissal horizon for these surfaces. */
 const DISMISS_COOKIE_MAX_AGE_SECONDS = 31_536_000;
 
-/**
- * Whether `document.cookie` actually stores anything here.
- *
- * A Document whose URL scheme is not http(s) is COOKIE-AVERSE — the HTML spec's
- * term for one where the `document.cookie` setter is a silent no-op and the
- * getter returns ''. That is where the custom-scheme shells run: Tauri serves
- * the bundle from `tauri://localhost` on macOS/Linux, Capacitor from
- * `capacitor://localhost` on iOS. Every dismissal there was dropped on write
- * and unreadable on the next mount, so the surface came back in every new
- * window and on every launch. Tauri on Windows and Capacitor on Android serve
- * http(s), were never affected, and stay on the cookie tier.
- *
- * The scheme is read directly rather than probed with a throwaway write: a lib
- * whose consumers are consent-regulated marketing sites should not set a
- * cookie, however briefly, to answer a question the URL already answers.
- * Deliberately NOT covered: cookies blocked by user or enterprise policy on an
- * http(s) origin — the surface reappears there exactly as it always has, which
- * is what someone who blocked cookies asked for.
- *
- * Read off `document.URL`, not `window.location`: averseness is a property of
- * the DOCUMENT's URL, and this file must stay usable wherever `document` is the
- * only thing the other helpers here already require. `about:blank` and
- * `about:srcdoc` are the one miss: they carry their creator's origin and are
- * served its cookies, yet land on the fallback tier here. Accepted — nothing
- * hosts this lib in one, and the cost is a re-show, not a broken surface.
- */
-function canUseCookies(): boolean {
-  if (typeof document === 'undefined') return false;
-  return document.URL.startsWith('http:') || document.URL.startsWith('https:');
-}
-
-/**
- * The fallback tier for cookie-averse documents, keyed identically to the
- * cookie so a host needs no second key.
- *
- * A FALLBACK, never a mirror: cookies stay primary wherever they work, because
- * they are the only tier a server can read — which is what lets the hub
- * suppress a dismissed surface during SSR instead of flashing it — and writing
- * both would mean clearing cookies no longer clears a dismissal.
- */
-function fallbackStore(name: string) {
-  return createLocalStorageAdapter<string>({
-    key: name,
-    logTag: '[dismiss-cookie]',
-    validate: (parsed): parsed is string => typeof parsed === 'string',
-  });
-}
-
 /** 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. Returns `undefined` when absent OR unreadable — one
- * guarantee with two causes: a cookie with bad percent-encoding, where
- * `decodeURIComponent` throws `URIError`, and a fallback value that is not the
- * JSON string it should be, where the adapter swallows the parse failure.
- * Callers run this inside reveal paths where an uncaught throw would hide the
- * surface permanently, so failing open — treated as not-dismissed — is always
- * the safe side.
+ * 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;
-  if (!canUseCookies()) return fallbackStore(name).load() ?? undefined;
   const match = document.cookie.split('; ').find(row => row.startsWith(`${name}=`));
   if (!match) return undefined;
   try {
@@ -98,30 +37,14 @@ export function readDismissCookie(name: string): string | undefined {
   }
 }
 
-/** Persist a dismissal. */
+/** Persist a dismissal (cookie only, 1 year). */
 export function writeDismissCookie(name: string, id: string): void {
   if (typeof document === 'undefined') return;
-  if (!canUseCookies()) {
-    fallbackStore(name).save(id);
-    return;
-  }
   document.cookie = `${name}=${encodeURIComponent(id)}; path=/; max-age=${DISMISS_COOKIE_MAX_AGE_SECONDS}; SameSite=Lax`;
 }
 
-/**
- * Clear a dismissal (test/story helper).
- *
- * BOTH tiers, unconditionally — the tier check governs writes, not removal.
- * Clearing writes nothing and cannot resurrect a dismissal, so it carries none
- * of the reasons the write path commits to one tier, and a clear that leaves
- * the other tier holding a value is a lie.
- *
- * NOT for a shell that changes the scheme it serves under: that is an origin
- * change, so the old tier moves to a storage bucket no code in the new origin
- * can reach — `clear` included.
- */
+/** Clear a dismissal (test/story helper). */
 export function clearDismissCookie(name: string): void {
   if (typeof document === 'undefined') return;
-  fallbackStore(name).clear();
   document.cookie = `${name}=; path=/; max-age=0`;
 }

package/src/utils/dismissal-storage.ts

@@ -22,8 +22,8 @@ export function walkthroughDismissCookieName(platform: string): string {
   return `${platform}-${WALKTHROUGH_VIDEO_DISMISS_KEY}`;
 }
 
-/** Client-side dismissal check (id-match). Reads browser storage, so call it
- *  from an effect, never during render. */
+/** 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);
 }