@flamingo-stack/openframe-frontend-core 0.0.711 → 0.0.712

package/src/hooks/ui/use-header-height.ts

@@ -2,11 +2,20 @@
 
 import { useEffect, useState } from 'react';
 
+/** The site header's own element (`SiteHeader`'s hook point). */
+const SITE_HEADER_SELECTOR = '[data-site-header]';
+
 /**
  * Returns the combined height (px) of the sticky page header and announcement
  * bar (if present), updated live via ResizeObserver / MutationObserver.
  * Useful for offsetting fixed/absolute-positioned panels so they don't
  * overlap the header.
+ *
+ * With `stuckOnly` it answers a different question: where the header's bottom
+ * edge sits once the page has scrolled, the `top` of anything that sticks
+ * directly under it. That is the site header ALONE (the announcement bar
+ * scrolls away with the page, so adding it leaves a gap the content shows
+ * through), and 0 while the header has slid itself out of view.
  */
 export function useHeaderHeight(
   // First-paint fallback = the unified top-navigation `big` bar (72px), the
@@ -21,14 +30,54 @@ export function useHeaderHeight(
      * @default true
      */
     enabled?: boolean;
+    /**
+     * Measure only what stays stuck to the top of a scrolled page: the site
+     * header, without the announcement bar, and 0 while the header is hidden.
+     * @default false
+     */
+    stuckOnly?: boolean;
   } = {},
 ): number {
-  const { enabled = true } = options;
+  const { enabled = true, stuckOnly = false } = options;
   const [height, setHeight] = useState(defaultHeight);
 
   useEffect(() => {
     if (!enabled) return undefined;
 
+    if (stuckOnly) {
+      let stop: (() => void) | undefined;
+      const watch = (header: HTMLElement) => {
+        // The header hides by translating itself up by its own height.
+        const measureStuck = () => setHeight(header.style.transform.includes('-100%') ? 0 : header.offsetHeight);
+        measureStuck();
+        const resize = new ResizeObserver(measureStuck);
+        resize.observe(header);
+        const mutation = new MutationObserver(measureStuck);
+        mutation.observe(header, { attributes: true, attributeFilter: ['style'] });
+        stop = () => {
+          resize.disconnect();
+          mutation.disconnect();
+        };
+      };
+      const present = document.querySelector<HTMLElement>(SITE_HEADER_SELECTOR);
+      if (present) {
+        watch(present);
+        return () => stop?.();
+      }
+      // A header that mounts after this hook: wait for it, then watch it.
+      const arrival = new MutationObserver(() => {
+        const header = document.querySelector<HTMLElement>(SITE_HEADER_SELECTOR);
+        if (!header) return;
+        arrival.disconnect();
+        watch(header);
+      });
+      arrival.observe(document.body, { childList: true, subtree: true });
+      return () => {
+        arrival.disconnect();
+        stop?.();
+      };
+    }
+
     const measure = () => {
       let total = 0;
       const header = document.querySelector('header');
@@ -66,7 +115,7 @@ export function useHeaderHeight(
       resizeObserver.disconnect();
       mutationObserver.disconnect();
     };
-  }, [defaultHeight, enabled]);
+  }, [defaultHeight, enabled, stuckOnly]);
 
   return height;
 }

package/src/hooks/ui/use-sticky-toolbar.ts

@@ -0,0 +1,60 @@
+'use client';
+
+import { type CSSProperties, useCallback, useEffect, useState } from 'react';
+
+interface StickyToolbar {
+  /** Attach to the sticky toolbar element whose height drives the table-header offset. */
+  toolbarRef: (node: HTMLDivElement | null) => void;
+  /** Apply to the element wrapping both the toolbar and the table; publishes the measured height. */
+  containerStyle: CSSProperties;
+  /** Pass to DataTable.Header's `stickyHeaderOffset` so it pins right below the toolbar. */
+  stickyHeaderOffset: string;
+}
+
+/**
+ * Keeps a sticky filter toolbar pinned above a sticky table header. (The page's
+ * OWN header and announcement bar are `useHeaderHeight`'s: that one reads the
+ * document's chrome; this one measures the toolbar element it is handed.)
+ *
+ * How: The toolbar
+ * height is measured (it changes as the single-row tag list appears or collapses)
+ * and published as `--sticky-toolbar-h` on the container, which the table header
+ * reads via `top-[var(--sticky-toolbar-h)]`, so the header always pins flush
+ * below the toolbar without a hard-coded offset.
+ *
+ * A CALLBACK ref, not a ref object: a toolbar can be conditionally rendered (a
+ * list with nothing in it hides its search box), and a plain `useRef` + mount
+ * effect would neither measure a toolbar that appears later nor zero the offset
+ * for one that goes away, the header would then pin below a strip that is no
+ * longer there.
+ */
+export function useStickyToolbar(): StickyToolbar {
+  const [node, setNode] = useState<HTMLDivElement | null>(null);
+  const [height, setHeight] = useState(0);
+
+  const toolbarRef = useCallback((el: HTMLDivElement | null) => setNode(el), []);
+
+  // No toolbar mounted → no offset. Derived during render rather than in the
+  // effect: the effect's job is the ResizeObserver, and zeroing here means the
+  // header never pins below a strip that has already gone.
+  const [lastNode, setLastNode] = useState(node);
+  if (node !== lastNode) {
+    setLastNode(node);
+    if (!node) setHeight(0);
+  }
+
+  useEffect(() => {
+    if (!node) return undefined;
+    const update = () => setHeight(node.offsetHeight);
+    update();
+    const observer = new ResizeObserver(update);
+    observer.observe(node);
+    return () => observer.disconnect();
+  }, [node]);
+
+  return {
+    toolbarRef,
+    containerStyle: { '--sticky-toolbar-h': `${height}px` } as CSSProperties,
+    stickyHeaderOffset: 'top-[var(--sticky-toolbar-h)]',
+  };
+}

package/src/hooks/use-location-hash.ts

@@ -1,10 +1,14 @@
 'use client';
 
 import { useSyncExternalStore } from 'react';
-import { normalizeHashFragment } from '../utils/same-page-hash-nav';
+import { LOCATION_HASH_SYNC_EVENT, normalizeHashFragment } from '../utils/same-page-hash-nav';
 
-/** `navigateSamePageHash` dispatches `hashchange` itself; `popstate` covers back and forward. */
-const HASH_EVENTS = ['hashchange', 'popstate'] as const;
+/**
+ * `navigateSamePageHash` dispatches `hashchange` itself; `popstate` covers back
+ * and forward; `replaceLocationHash` (a scroll spy, a tab naming itself)
+ * announces its silent writes with its own event.
+ */
+const HASH_EVENTS = ['hashchange', 'popstate', LOCATION_HASH_SYNC_EVENT] as const;
 
 function subscribe(onChange: () => void): () => void {
   for (const event of HASH_EVENTS) window.addEventListener(event, onChange);
@@ -24,8 +28,8 @@ function readHash(): string {
 
 /**
  * The URL's hash without its `#`, or `''`: the READ side of same-page anchor
- * navigation (`navigateSamePageHash` writes it, `useScrollToHash` scrolls to
- * it). For a component whose state follows the anchor: a tab group that opens
+ * navigation (`navigateSamePageHash` and `replaceLocationHash` write it,
+ * `useScrollToHash` scrolls to it when it was a navigation). For a component whose state follows the anchor: a tab group that opens
  * the tab a link names. Empty on the server and during hydration (the server
  * never sees a hash), then the real one.
  */

package/src/hooks/use-scroll-to-hash.ts

@@ -1,7 +1,7 @@
 'use client';
 
 import { useEffect } from 'react';
-import { getHashTargetElement, normalizeHashFragment } from '../utils/same-page-hash-nav';
+import { getHashTargetElement, isScrollSyncedHash, normalizeHashFragment } from '../utils/same-page-hash-nav';
 import { scrollElementIntoView } from '../utils/scroll-into-view';
 
 /** ~1s at 60fps — long enough to outlast Radix accordion expand + SWR
@@ -20,6 +20,13 @@ export interface UseScrollToHashOptions {
  * reference change AND on `hashchange` (browser back/forward + the
  * synthetic event `navigateSamePageHash` dispatches).
  *
+ * A hash the reader's own scrolling left in the URL (`replaceLocationHash`,
+ * written by a scroll spy with `syncHash`) is not a navigation: on a reload,
+ * and on back or forward to such an entry, the browser restores the exact
+ * scroll position, which that hash only mirrors, so it is left alone
+ * (`isScrollSyncedHash`). On a load the spy checks the restored position
+ * against the hash and scrolls only when they disagree.
+ *
  * Skipped when `readyDep == null || readyDep === false`. Default
  * `true` makes the hook run on mount for pages whose target is in the
  * initial SSR render.
@@ -37,6 +44,7 @@ export function useScrollToHash(readyDep: unknown = true, options?: UseScrollToH
       }
     };
     const tryScrollToHash = () => {
+      if (isScrollSyncedHash()) return;
       // `normalizeHashFragment` heals a malformed multi-fragment hash
       // so `getElementById` resolves on deep-link entries that bypass
       // `navigateSamePageHash`'s own normalize.

package/src/types/case-study.ts

@@ -9,6 +9,15 @@ import type { MSP } from './stack';
 import type { UserProfile } from './user';
 import type { EntityQuote } from './video-processing';
 
+/**
+ * One headline number of a story ("50%" / "of routine tasks automated"). A
+ * story carries at most three; a card shows the first, the story's page all.
+ */
+export interface CaseStudyMetric {
+  value: string;
+  label: string;
+}
+
 export interface CaseStudy {
   id: number;
   title: string;
@@ -24,6 +33,8 @@ export interface CaseStudy {
   challenge: string | null;
   solution: string | null;
   results: string | null;
+  /** Headline metrics (jsonb, at most three). Null or empty: the story has none. */
+  metrics?: CaseStudyMetric[] | null;
 
   // Testimonial video (text testimonials come from MSP profile)
   testimonial_video_url: string | null; // YouTube URL (preferred when both exist)
@@ -91,7 +102,12 @@ export type CaseStudyCardData = Pick<CaseStudy, 'id' | 'title' | 'summary' | 'fe
   Partial<
     Pick<
       CaseStudy,
-      'main_video_url' | 'main_video_thumbnail' | 'highlight_video_url' | 'highlight_video_thumbnail' | 'video_bites'
+      | 'main_video_url'
+      | 'main_video_thumbnail'
+      | 'highlight_video_url'
+      | 'highlight_video_thumbnail'
+      | 'video_bites'
+      | 'metrics'
     >
   > & {
     user?: Pick<UserProfile, 'full_name' | 'job_title'> & Partial<Pick<UserProfile, 'avatar_url'>>;
@@ -107,6 +123,8 @@ export interface CreateCaseStudyData {
   challenge?: string;
   solution?: string;
   results?: string;
+  /** Headline metrics, at most three. Null or an empty list clears them. */
+  metrics?: CaseStudyMetric[] | null;
   testimonial_video_url?: string; // YouTube URL
   main_video_url?: string; // Uploaded video file URL
   main_video_thumbnail?: string | null; // Manual poster image URL for testimonial video (standardized name across all video-bearing entities). Nullable so admin form can explicitly clear a stale poster from the DB when the testimonial video is removed or the source is switched to YouTube.
@@ -149,6 +167,8 @@ export interface CaseStudyFilters {
   company_size?: string; // Filtered from MSP profile data
   search?: string;
   featured?: boolean;
+  /** Only stories that carry at least one headline metric. */
+  withMetrics?: boolean;
   status?: string;
   limit?: number;
   offset?: number;

package/src/utils/date-utils.ts

@@ -56,7 +56,14 @@ export function formatTicketFullTimestamp(iso: string): string {
  * formatRelativeTime(new Date()) // 'Just now'
  */
 export function formatRelativeTime(timestamp: string | Date): string {
-  const now = new Date();
+  return formatRelativeTimeFrom(timestamp, new Date());
+}
+
+/**
+ * {@link formatRelativeTime} against a given "now": for a view that renders
+ * with a fixed clock (a product screen fed by a fixture, a test).
+ */
+export function formatRelativeTimeFrom(timestamp: string | Date, now: Date): string {
   const targetTime = typeof timestamp === 'string' ? new Date(timestamp) : timestamp;
 
   // Validate the date

package/src/utils/index.ts

@@ -331,6 +331,7 @@ export * from './dev-sections';
 // pre-computed pixel value avoids the mid-animation jitter that
 // `element.scrollIntoView()` produces when layout shifts during the
 // scroll).
+export { openInNewTab } from './open-in-new-tab';
 export { type ScrollElementIntoViewOptions, scrollElementIntoView } from './scroll-into-view';
 
 // Same-page hash navigation — owns pushState + synthetic hashchange +
@@ -338,8 +339,12 @@ export { type ScrollElementIntoViewOptions, scrollElementIntoView } from './scro
 // hub's `useUnifiedNav` + chat-runtime `navigate`, AND by every
 // embeddable surface that drives state off the URL hash.
 export {
+  ACTIVE_ANCHOR_ATTRIBUTE,
+  isScrollSyncedHash,
+  LOCATION_HASH_SYNC_EVENT,
   navigateSamePageHash,
   normalizeHashFragment,
+  replaceLocationHash,
   STICKY_HEADER_OFFSET_PX,
   HUB_HEADER_OFFSET_PX,
   type NavigateSamePageHashOptions,

package/src/utils/open-in-new-tab.ts

@@ -0,0 +1,12 @@
+import type { MouseEvent } from 'react';
+
+/**
+ * A click handler that opens `href` in a new tab and does nothing else: the
+ * "open in new tab" cell of a table whose rows are links themselves.
+ */
+export function openInNewTab(href: string) {
+  return (event: MouseEvent) => {
+    event.preventDefault();
+    window.open(href, '_blank', 'noopener,noreferrer');
+  };
+}

package/src/utils/same-page-hash-nav.ts

@@ -63,6 +63,63 @@ export function getHashTargetElement(id: string): HTMLElement | null {
   return findAnchorElementByNormalizedId(decoded, document);
 }
 
+/**
+ * Fired on `window` after {@link replaceLocationHash} changed the hash. NOT
+ * `hashchange`: a listener of this event follows the hash as STATE (which tab
+ * is open, `useLocationHash`); a listener of `hashchange` treats it as a
+ * NAVIGATION and scrolls (`useScrollToHash`). A scroll spy that keeps the URL
+ * on the section being read must reach the first and never the second.
+ */
+export const LOCATION_HASH_SYNC_EVENT = 'locationhashsync';
+
+/** Marks, on an element inside a section, the child anchor a scroll spy writes for that section (see `useScrollSpy`). */
+export const ACTIVE_ANCHOR_ATTRIBUTE = 'data-active-anchor';
+
+/** The key, in the history entry's state, of the hash {@link replaceLocationHash} last gave that entry. */
+const HASH_SYNC_STATE_KEY = '__hashSync';
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null;
+
+/**
+ * Point the URL's hash at `id` (or clear it) to say where the reader IS, as
+ * opposed to sending them somewhere: no history entry (`replaceState`), no
+ * `hashchange`, no scroll. THE writer for a scroll spy's hash and for a tab
+ * that names itself in the URL. State followers hear
+ * {@link LOCATION_HASH_SYNC_EVENT}.
+ *
+ * The hash is also noted in the history ENTRY's state (beside whatever the
+ * host router keeps there), which survives a reload and comes back on back
+ * and forward: {@link isScrollSyncedHash}. For such an entry the hash only
+ * mirrors a scroll position the browser restores by itself, so
+ * `useScrollToHash` does not scroll to it again. Any navigation writes its own
+ * state and drops the note.
+ */
+export function replaceLocationHash(id: string | null): void {
+  if (typeof window === 'undefined') return;
+  const { pathname, search, hash } = window.location;
+  const next = id ? `#${id}` : '';
+  const state: unknown = window.history.state;
+  const noted = isRecord(state) ? state[HASH_SYNC_STATE_KEY] : undefined;
+  if (hash === next && (noted === next || !next)) return;
+  window.history.replaceState(
+    { ...(isRecord(state) ? state : {}), [HASH_SYNC_STATE_KEY]: next },
+    '',
+    `${pathname}${search}${next}`,
+  );
+  if (hash !== next) window.dispatchEvent(new Event(LOCATION_HASH_SYNC_EVENT));
+}
+
+/**
+ * Whether the hash in the URL was put there by {@link replaceLocationHash}
+ * (the reader scrolled or opened a tab) rather than by a navigation. False
+ * with no hash, on a fresh visit, and once any navigation rewrote the entry.
+ */
+export function isScrollSyncedHash(): boolean {
+  if (typeof window === 'undefined' || !window.location.hash) return false;
+  const state: unknown = window.history.state;
+  return isRecord(state) && state[HASH_SYNC_STATE_KEY] === window.location.hash;
+}
+
 export interface NavigateSamePageHashOptions {
   /** Pixels to subtract for sticky chrome. */
   headerOffset?: number;

package/src/utils/scroll-into-view.ts

@@ -49,7 +49,9 @@
 
 export interface ScrollElementIntoViewOptions {
   /** Pixels to subtract from the target element's `top` so it lands BELOW
-   *  sticky chrome. Defaults to 0. Pass `96` for the standard hub header. */
+   *  sticky chrome. Defaults to 0. Pass `96` for the standard hub header.
+   *  A target that declares a larger `scroll-margin-top` in CSS wins: see
+   *  {@link declaredScrollMarginTop}. */
   headerOffset?: number;
   /** `'smooth'` (default) runs the self-driven tween; `'instant'` / `'auto'`
    *  jump in one synchronous write (deep-link land, programmatic focus moves). */
@@ -104,6 +106,21 @@ export function getScrollableAncestor(el: HTMLElement): HTMLElement | null {
   return null;
 }
 
+/**
+ * The offset the target ITSELF declares in CSS (`scroll-margin-top`), in px.
+ *
+ * A page with more sticky chrome than the standard header (a second bar under
+ * it) says so on its anchors with `scroll-margin-top`, which is what a native
+ * anchor jump (a URL that loads with the hash, the router's own hash scroll)
+ * honours. The tween honours the same declaration, so a link clicked on the
+ * page and a link that loads the page land on the same pixel: the caller's
+ * `headerOffset` is the floor, the anchor's own margin wins when it is larger.
+ */
+export function declaredScrollMarginTop(target: HTMLElement): number {
+  const margin = Number.parseFloat(getComputedStyle(target).scrollMarginTop);
+  return Number.isFinite(margin) ? margin : 0;
+}
+
 /**
  * Scroll the page so `target` lands at the top of the viewport (below sticky
  * chrome via `headerOffset`). SSR-safe; `null`/`undefined` target is a no-op so
@@ -130,11 +147,10 @@ export function scrollElementIntoView(
   // the page reflows (a sibling drawer collapsing) and the reachable max grows
   // as the just-opened drawer expands. Clamp to the LIVE max each frame.
   const computeTarget = (): number => {
+    const offset = Math.max(headerOffset, declaredScrollMarginTop(target));
     const raw = container
-      ? container.scrollTop +
-        (target.getBoundingClientRect().top - container.getBoundingClientRect().top) -
-        headerOffset
-      : target.getBoundingClientRect().top + window.scrollY - headerOffset;
+      ? container.scrollTop + (target.getBoundingClientRect().top - container.getBoundingClientRect().top) - offset
+      : target.getBoundingClientRect().top + window.scrollY - offset;
     const adjusted = adjustTargetY ? adjustTargetY(raw) : raw;
     const maxScroll = container
       ? Math.max(0, container.scrollHeight - container.clientHeight)