@flamingo-stack/openframe-frontend-core 0.0.291 → 0.0.292-snapshot.20260619040151

package/src/utils/.source-icons.md

@@ -27,7 +27,7 @@ const iconName = getSourceIconName('github-commits')
 
 // Get display label for a chip strip
 const label = getSourceLabel('hubspot-tickets-anon')
-// → 'Known Issues'
+// → 'Tickets'
 
 // Map a documentType emitted by the LLM to its table ID
 const tableId = defaultTableIdForDocumentType('slack_message')

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

@@ -19,3 +19,17 @@ export const DEV_SECTION_PARAM_KEYS = {
   /** Delivery (bug-fix / enhancement) task-type filter. */
   deliveryTaskType: 'task_type',
 } as const
+
+/** Section keys that participate in `<section>-<id>` anchor IDs.
+ *  The URL composer (`appendSearchAndHash` in hub `dev-section-url.ts`)
+ *  and the row components (`DeliveryRow`, `RoadmapCard`, `HelpCenterCard`)
+ *  both call `devSectionAnchorId` so the DOM `id` and the URL hash stay
+ *  in lockstep — adding a new section means adding the literal here
+ *  ONCE, not at every render site. */
+export type DevSectionAnchorKind = 'roadmap' | 'delivery' | 'ticket'
+
+/** Compose the canonical `<section>-<id>` anchor id used by the dev-center
+ *  rows + URL composer. */
+export function devSectionAnchorId(section: DevSectionAnchorKind, id: string): string {
+  return `${section}-${id}`
+}

package/src/utils/index.ts

@@ -44,7 +44,11 @@ export * from './release-cover'
 // Dev-center URL param keys — the ONE source for the `?search=` / `?status=` / … keys the
 // chrome registry writes and the list views read; re-exported so embedders (and the hub's
 // dev-section-url helper) build deep-links with the same keys instead of a bare literal.
-export { DEV_SECTION_PARAM_KEYS } from './dev-sections/dev-section-param-keys'
+export {
+  DEV_SECTION_PARAM_KEYS,
+  devSectionAnchorId,
+  type DevSectionAnchorKind,
+} from './dev-sections/dev-section-param-keys'
 // Dynamic icon registry — single source of truth lives at
 // components/chat/utils/icon-registry. Re-exported here so existing
 // `@flamingo-stack/openframe-frontend-core/utils` callers (hub admin
@@ -246,6 +250,18 @@ export {
   scrollElementIntoView,
 } from './scroll-into-view'
 
+// Same-page hash navigation — owns pushState + synthetic hashchange +
+// anchoring-proof scroll. Pair of `scrollElementIntoView`. Used by the
+// hub's `useUnifiedNav` + chat-runtime `navigate`, AND by every
+// embeddable surface that drives state off the URL hash.
+export {
+  navigateSamePageHash,
+  normalizeHashFragment,
+  STICKY_HEADER_OFFSET_PX,
+  HUB_HEADER_OFFSET_PX,
+  type NavigateSamePageHashOptions,
+} from './same-page-hash-nav'
+
 // Shared list-API URL builder — the single source for the per-type chat
 // entity-card fetch shapes. The hub's 12 RAG mapper `listApi` closures
 // delegate here (byte-parity test guards the migration); embedders wire

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

@@ -0,0 +1,115 @@
+import { scrollElementIntoView } from './scroll-into-view'
+
+/** Pages with a section-nav STRIP on top of the global hub header
+ *  (dev-center roadmap/delivery/tickets, FAQ category-pill nav).
+ *  Anchor lands BELOW both layers. */
+export const STICKY_HEADER_OFFSET_PX = 96
+
+/** Pages with only the global hub header (docs, blog, vendor detail).
+ *  Anchor lands BELOW the header bar. */
+export const HUB_HEADER_OFFSET_PX = 80
+
+/**
+ * Take only the FIRST hash segment from a fragment that may contain extra
+ * `#` characters. `'' → ''`, `'#a' → '#a'`, `'#a#b' → '#a'`.
+ *
+ * No real DOM id contains `#`, so a multi-fragment hash is always a bug at
+ * the composer site; `navigateSamePageHash` + `useScrollToHash` both call
+ * this so URL bar and `getElementById` stay in sync.
+ */
+export function normalizeHashFragment(hash: string): string {
+  if (!hash) return ''
+  const second = hash.indexOf('#', 1)
+  return second < 0 ? hash : hash.slice(0, second)
+}
+
+export interface NavigateSamePageHashOptions {
+  /** Pixels to subtract for sticky chrome. */
+  headerOffset?: number
+  /** `'push'` (default) — new history entry; `'replace'` — overwrite
+   *  current entry (use for TOC-style in-page navigators). */
+  history?: 'push' | 'replace'
+}
+
+/**
+ * Same-page hash navigation primitive: pushState + synthetic `hashchange`
+ * + anchoring-proof smooth scroll. Replaces `router.push` for hash CTAs
+ * (Next.js suppresses smooth-scroll during navigation; `router.push` on
+ * an exact-URL match is a no-op). Returns `true` when the helper claimed
+ * the nav (same pathname + search); `false` for cross-page targets so
+ * callers fall through to `router.push`.
+ *
+ * `target` accepts an origin-stripped path (`/x#anchor`) or a bare hash
+ * (`#anchor`); bare-hash callers don't need to reconstruct `pathname +
+ * search` themselves.
+ */
+export function navigateSamePageHash(
+  target: string,
+  options: NavigateSamePageHashOptions = {},
+): boolean {
+  if (typeof window === 'undefined') return false
+  const { headerOffset = 0, history: historyMode = 'push' } = options
+  const normalizedTarget =
+    target.startsWith('#')
+      ? window.location.pathname + window.location.search + target
+      : target
+  // `new URL(absoluteUrl, base)` ignores `base` per RFC 3986; an absolute
+  // cross-origin target sharing pathname/search would otherwise pass the
+  // check below and trip pushState's same-origin enforcement. Parse with
+  // an explicit base so malformed inputs cleanly fall through.
+  let url: URL
+  try {
+    url = new URL(normalizedTarget, window.location.href)
+  } catch {
+    return false
+  }
+  if (
+    url.origin !== window.location.origin ||
+    url.pathname !== window.location.pathname ||
+    url.search !== window.location.search
+  ) {
+    return false
+  }
+  const current = window.location.pathname + window.location.search + window.location.hash
+  // Heal a malformed multi-fragment hash so the URL bar is clean and
+  // `getElementById` resolves. Dev-warn fingers the upstream composer.
+  const normalizedHash = normalizeHashFragment(url.hash)
+  if (process.env.NODE_ENV === 'development' && normalizedHash !== url.hash) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[navigateSamePageHash] malformed fragment "${url.hash}" → normalizing to "${normalizedHash}". Fix the upstream composer.`,
+    )
+  }
+  const next = url.pathname + url.search + normalizedHash
+  const id = normalizedHash && normalizedHash !== '#' ? normalizedHash.slice(1) : ''
+  // Hash-less targets are only ours on an EXACT URL re-click.
+  if (!id && next !== current) return false
+  if (next !== current) {
+    const oldURL = window.location.href
+    if (historyMode === 'replace') {
+      window.history.replaceState(null, '', next)
+    } else {
+      window.history.pushState(null, '', next)
+    }
+    // Synthetic `hashchange` — `pushState` doesn't fire it (HTML spec),
+    // so URL-hash-bound listeners (FAQ auto-expand, etc.) wouldn't react.
+    window.dispatchEvent(new HashChangeEvent('hashchange', {
+      oldURL,
+      newURL: window.location.href,
+    }))
+  }
+  const el = id ? document.getElementById(id) : null
+  if (id && !el && process.env.NODE_ENV === 'development') {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[navigateSamePageHash] anchor "#${id}" not found — scrolling to top.`,
+    )
+  }
+  // Missing anchor → tween to page top. `documentElement` is at 0 by
+  // definition, so one tween covers both branches.
+  scrollElementIntoView(el ?? document.documentElement, {
+    behavior: 'smooth',
+    headerOffset,
+  })
+  return true
+}

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

@@ -33,6 +33,18 @@
  *
  * Honors `prefers-reduced-motion` (jumps instantly) and cancels on genuine user
  * scroll intent (wheel / touch) so we never fight the user.
+ *
+ * WINDOW *OR* A SCROLLABLE ANCESTOR: the helper is not hard-wired to the window
+ * scroller. It walks up from the target to the nearest ancestor that is an
+ * actual scroll container (`overflow-y: auto | scroll | overlay` AND
+ * `scrollHeight > clientHeight`) and drives THAT element; only when none exists
+ * does it fall back to `window`. This is what makes it work inside app shells
+ * that put page content in a fixed-height `<main class="overflow-y-auto">`
+ * (e.g. OpenFrame's `AppLayout`) where the document/window never scrolls — the
+ * old window-only version was a silent no-op there. Note `overflow: clip` /
+ * `hidden` are deliberately NOT treated as scroll containers, so a list wrapper
+ * that uses `overflow-clip` only to round its corners still bubbles the scroll
+ * up to the real container (matches the `<HelpCenterCard>` list intent).
  */
 
 export interface ScrollElementIntoViewOptions {
@@ -70,6 +82,23 @@ function cancelActiveScroll(): void {
 
 const easeOutCubic = (t: number): number => 1 - Math.pow(1 - t, 3)
 
+/** Nearest ancestor that is a *real* scroll container, or `null` when the
+ *  window/document is the scroller. Only `auto | scroll | overlay` count —
+ *  `clip` / `hidden` are intentionally excluded (a wrapper using `overflow-clip`
+ *  purely to round corners must let the scroll bubble to the page). */
+function getScrollableAncestor(el: HTMLElement): HTMLElement | null {
+  for (let node = el.parentElement; node; node = node.parentElement) {
+    const overflowY = getComputedStyle(node).overflowY
+    if (
+      (overflowY === 'auto' || overflowY === 'scroll' || overflowY === 'overlay') &&
+      node.scrollHeight > node.clientHeight
+    ) {
+      return node
+    }
+  }
+  return null
+}
+
 /**
  * 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
@@ -82,16 +111,29 @@ export function scrollElementIntoView(
   if (typeof window === 'undefined' || !target) return
   const { headerOffset = 0, behavior = 'smooth', adjustTargetY, durationMs = 320 } = options
 
+  // Pick the scroller ONCE: a fixed-height `<main overflow-y-auto>` shell scrolls
+  // the element, a plain document scrolls the window. The choice can't change
+  // mid-tween, so resolve it up front and route every read/write through it.
+  const container = getScrollableAncestor(target)
+  const readCurrent = (): number => (container ? container.scrollTop : window.scrollY)
+  const writeTo = (y: number): void => {
+    if (container) container.scrollTop = y
+    else window.scrollTo(0, y)
+  }
+
   // Target is recomputed every frame: the row's absolute position can move as
   // 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 raw = target.getBoundingClientRect().top + window.scrollY - headerOffset
+    const raw = container
+      ? container.scrollTop +
+        (target.getBoundingClientRect().top - container.getBoundingClientRect().top) -
+        headerOffset
+      : target.getBoundingClientRect().top + window.scrollY - headerOffset
     const adjusted = adjustTargetY ? adjustTargetY(raw) : raw
-    const maxScroll = Math.max(
-      0,
-      document.documentElement.scrollHeight - window.innerHeight,
-    )
+    const maxScroll = container
+      ? Math.max(0, container.scrollHeight - container.clientHeight)
+      : Math.max(0, document.documentElement.scrollHeight - window.innerHeight)
     return Math.min(Math.max(0, adjusted), maxScroll)
   }
 
@@ -104,7 +146,7 @@ export function scrollElementIntoView(
 
   // Instant paths: a single synchronous write. No tween, no anchoring race.
   if (behavior === 'instant' || behavior === 'auto' || prefersReduced) {
-    window.scrollTo(0, computeTarget())
+    writeTo(computeTarget())
     return
   }
 
@@ -125,18 +167,18 @@ export function scrollElementIntoView(
 
   const step = (now: number) => {
     if (startY === null) {
-      startY = window.scrollY
+      startY = readCurrent()
       startTime = now
     }
     const targetY = computeTarget()
     const t = Math.min(1, (now - startTime) / durationMs)
     const y = startY + (targetY - startY) * easeOutCubic(t)
-    window.scrollTo(0, y)
+    writeTo(y)
     if (t < 1) {
       activeRaf = requestAnimationFrame(step)
     } else {
       // Final exact write in case easing left a sub-pixel gap, then teardown.
-      window.scrollTo(0, computeTarget())
+      writeTo(computeTarget())
       activeRaf = 0
       if (teardownActive) {
         teardownActive()

package/src/utils/source-icons.ts

@@ -128,7 +128,13 @@ export const SOURCE_LABELS_BY_TABLE: Record<string, string> = {
 
   // HubSpot
   'hubspot-tickets':             'HubSpot Tickets',
-  'hubspot-tickets-anon':        'Known Issues',
+  // Anon + self share the "Tickets" root so the chip vocabulary is
+  // uniform across logged-out (everyone's resolved support tickets,
+  // anonymized → "Tickets") and logged-in (user-scoped → "My Tickets")
+  // surfaces. The full-PII `hubspot-tickets` entry above is product-hub
+  // internal only (admin view), kept as "HubSpot Tickets" to flag the
+  // distinct scope.
+  'hubspot-tickets-anon':        'Tickets',
   'hubspot-tickets-self':        'My Tickets',
 
   // Communications