@flamingo-stack/openframe-frontend-core 0.0.510 → 0.0.511-snapshot.20260804140004

package/src/components/ui/markdown/base-components.tsx

@@ -21,6 +21,11 @@ import {
   useHeadingId,
 } from './heading-ids';
 import { slugifyHeadingText } from '../../../utils/markdown-heading-id';
+import {
+  getHashTargetElement,
+  navigateSamePageHash,
+  HUB_HEADER_OFFSET_PX,
+} from '../../../utils/same-page-hash-nav';
 
 /**
  * True when an image `src` is worth rendering. Shared by the base `img` and
@@ -284,12 +289,33 @@ export function buildBaseComponents({
         );
       }
 
+      // In-page anchor. Doc TOCs are authored against GitHub's slugger
+      // (`## 📚 Table of Contents` → `#-table-of-contents`) while our heading
+      // ids trim the emoji's leftover hyphen, so the raw href resolves to
+      // nothing and the browser silently ignores the click. Resolve through
+      // `getHashTargetElement` — the same resolver deep links use — then hand
+      // the real id to the canonical hash-nav helper, which also lands the
+      // heading BELOW the sticky header instead of under it, matching how the
+      // "On this page" rail scrolls.
+      const isInPageAnchor = typeof href === 'string' && href.startsWith('#') && href.length > 1;
+      const handleAnchorClick = (e: React.MouseEvent<HTMLAnchorElement>) => {
+        // Let modifier / non-primary clicks keep their native behavior.
+        if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || e.button !== 0) return;
+        const target = getHashTargetElement(href.slice(1));
+        // Nothing matched anywhere in the document → leave the browser's
+        // default alone rather than swallowing a click that isn't ours.
+        if (!target?.id) return;
+        e.preventDefault();
+        navigateSamePageHash(`#${target.id}`, { headerOffset: HUB_HEADER_OFFSET_PX });
+      };
+
       return (
         <a
           href={href}
           className={`text-ods-accent no-underline relative transition-colors duration-200 hover:after:w-full after:content-[''] after:absolute after:w-0 after:h-0.5 after:-bottom-0.5 after:left-0 after:bg-ods-accent after:transition-all after:duration-300 ${linkClassName || ''}`}
           target={href?.startsWith('http') ? '_blank' : undefined}
           rel={href?.startsWith('http') ? 'noopener noreferrer' : undefined}
+          onClick={isInPageAnchor ? handleAnchorClick : undefined}
         >
           {children}
         </a>

package/src/components/ui/overlay-open-registry.tsx

@@ -0,0 +1,99 @@
+'use client'
+
+/**
+ * A surface-scoped count of overlays (⋯ menus, popovers) currently open INSIDE
+ * that surface, so the surface can suspend behaviour that would move the ground
+ * under them.
+ *
+ * ## Why
+ *
+ * An open menu stays anchored to its trigger. In a chat thread the ground moves
+ * on its own: a streaming reply grows the transcript and the auto-scroll follows
+ * the bottom, carrying the trigger — and its menu — upward until the menu is
+ * pinned to an off-screen anchor at the panel edge, visually detached from the
+ * card it belongs to.
+ *
+ * The honest fix is not to dismiss the menu on every scroll event (that breaks
+ * touch, where momentum scrolling fires constantly) but to stop pulling the
+ * ground: while an overlay is open the thread stops chasing the bottom, exactly
+ * how ChatGPT/Claude stop chasing once you interact with the transcript. When
+ * the overlay closes, the thread catches up if it was at the bottom before.
+ *
+ * ## Wiring
+ *
+ * Surface: wrap the region in `<OverlayOpenRegistryProvider onOpenChange={…}>`.
+ * Overlay: call `useReportOverlayOpen(open)`. No provider → the hook is inert,
+ * so overlays outside such a surface behave exactly as before.
+ */
+
+import * as React from 'react'
+
+export interface OverlayOpenRegistry {
+  /** Register one open overlay; call the returned fn to release it. */
+  acquire: () => () => void
+}
+
+export const OverlayOpenRegistryContext =
+  React.createContext<OverlayOpenRegistry | null>(null)
+
+/** Read the surrounding registry (or `null` when there is no provider). */
+export function useOverlayOpenRegistry(): OverlayOpenRegistry | null {
+  return React.useContext(OverlayOpenRegistryContext)
+}
+
+/**
+ * Report this overlay's open state to the surrounding surface. Safe to call
+ * unconditionally — with no provider it does nothing.
+ */
+export function useReportOverlayOpen(open: boolean): void {
+  const registry = useOverlayOpenRegistry()
+  React.useEffect(() => {
+    if (!open || !registry) return
+    return registry.acquire()
+  }, [open, registry])
+}
+
+export interface OverlayOpenRegistryProviderProps {
+  /** Fires on 0 → 1 and 1 → 0 transitions only, not on every acquire. */
+  onOpenChange?: (hasOpenOverlay: boolean) => void
+  children: React.ReactNode
+}
+
+/**
+ * Owns the count for one surface. The context value is referentially stable, so
+ * mounting this provider does not re-render overlays when the count changes —
+ * only the surface's own `onOpenChange` callback fires.
+ */
+export function OverlayOpenRegistryProvider({
+  onOpenChange,
+  children,
+}: OverlayOpenRegistryProviderProps) {
+  const countRef = React.useRef(0)
+  const onOpenChangeRef = React.useRef(onOpenChange)
+  onOpenChangeRef.current = onOpenChange
+
+  const registry = React.useMemo<OverlayOpenRegistry>(
+    () => ({
+      acquire: () => {
+        countRef.current += 1
+        if (countRef.current === 1) onOpenChangeRef.current?.(true)
+        let released = false
+        return () => {
+          // Guard against a double release (StrictMode double-invokes effect
+          // cleanups in development) driving the count negative.
+          if (released) return
+          released = true
+          countRef.current -= 1
+          if (countRef.current === 0) onOpenChangeRef.current?.(false)
+        }
+      },
+    }),
+    [],
+  )
+
+  return (
+    <OverlayOpenRegistryContext.Provider value={registry}>
+      {children}
+    </OverlayOpenRegistryContext.Provider>
+  )
+}

package/src/components/ui/portal-container.tsx

@@ -26,3 +26,34 @@ export const PortalContainerContext = React.createContext<HTMLElement | null>(
 export function usePortalContainer(): HTMLElement | null {
   return React.useContext(PortalContainerContext)
 }
+
+/**
+ * The element Radix overlays should treat as their COLLISION boundary — the
+ * surface they must stay inside of.
+ *
+ * Separate from {@link PortalContainerContext} on purpose: the portal target is
+ * a `display: contents` node (no box, so it can't be measured), while a
+ * collision boundary must be a real, laid-out element.
+ *
+ * Why it matters: Radix positions overlays `position: fixed` and, by default,
+ * flips/shifts them against the VIEWPORT. A menu opened near the top of a
+ * panel therefore happily grows upward past the panel's edge and lands on top
+ * of the app header — visually detached from the surface it belongs to. Handing
+ * Radix the panel element instead keeps flip/shift (and the
+ * `--radix-popper-available-height` a menu sizes itself by) inside that panel.
+ *
+ * Default `null` → viewport, i.e. Radix's own default, unchanged everywhere a
+ * provider isn't present.
+ */
+export const CollisionBoundaryContext = React.createContext<HTMLElement | null>(
+  null,
+)
+
+/** Read the active collision boundary (or `null` for the viewport). */
+export function useCollisionBoundary(): HTMLElement | null {
+  return React.useContext(CollisionBoundaryContext)
+}
+
+/** Padding (px) kept between an overlay and its boundary edge. Matches the
+ *  panel's own gutter so a shifted menu never sits flush against the edge. */
+export const COLLISION_PADDING_PX = 8

package/src/utils/__tests__/anchor-id.test.ts

@@ -0,0 +1,139 @@
+// @vitest-environment jsdom
+import { beforeEach, describe, expect, it } from 'vitest'
+import { extractSections } from '../markdown-section-extractor'
+import { findAnchorElementByNormalizedId, normalizeAnchorId } from '../anchor-id'
+import { getHashTargetElement } from '../same-page-hash-nav'
+
+describe('normalizeAnchorId', () => {
+  it('drops the hyphen GitHub leaves behind a stripped emoji', () => {
+    expect(normalizeAnchorId('-getting-started')).toBe('getting-started')
+    expect(normalizeAnchorId('-architecture-diagrams')).toBe('architecture-diagrams')
+  })
+
+  it('collapses the hyphen run GitHub emits around a dropped "&"', () => {
+    expect(normalizeAnchorId('-community--support')).toBe('community-support')
+  })
+
+  it('is a no-op for an already-clean id', () => {
+    expect(normalizeAnchorId('table-of-contents')).toBe('table-of-contents')
+  })
+
+  it('normalizes raw heading text too', () => {
+    expect(normalizeAnchorId('🚀 Getting Started')).toBe('getting-started')
+  })
+})
+
+describe('findAnchorElementByNormalizedId', () => {
+  beforeEach(() => {
+    document.body.innerHTML = `
+      <h1 id="openframe-cli-documentation">OpenFrame CLI — Documentation</h1>
+      <h2 id="table-of-contents">📚 Table of Contents</h2>
+      <h2 id="getting-started">🚀 Getting Started</h2>
+      <h2 id="community-support">💬 Community &amp; Support</h2>
+      <h3 id="a---b">A - B</h3>
+    `
+  })
+
+  it('resolves a GitHub-style anchor onto our heading id', () => {
+    expect(findAnchorElementByNormalizedId('-getting-started', document)?.id).toBe('getting-started')
+    expect(findAnchorElementByNormalizedId('-table-of-contents', document)?.id).toBe(
+      'table-of-contents',
+    )
+  })
+
+  it('resolves the double-hyphen "&" form', () => {
+    expect(findAnchorElementByNormalizedId('-community--support', document)?.id).toBe(
+      'community-support',
+    )
+  })
+
+  it('matches an id whose own raw form normalizes differently', () => {
+    // `a---b` is not reachable by normalized lookup — only the heading scan finds it.
+    expect(findAnchorElementByNormalizedId('a-b', document)?.id).toBe('a---b')
+  })
+
+  it('returns null for an anchor with no heading behind it', () => {
+    expect(findAnchorElementByNormalizedId('nope', document)).toBeNull()
+    expect(findAnchorElementByNormalizedId('', document)).toBeNull()
+  })
+})
+
+describe('duplicate headings — GitHub numbers from -1, our deduper from -2', () => {
+  beforeEach(() => {
+    document.body.innerHTML = `
+      <h2 id="setup">Setup</h2>
+      <h2 id="setup-2">Setup</h2>
+      <h2 id="setup-3">Setup</h2>
+      <h2 id="step-2">Step 2</h2>
+    `
+  })
+
+  it('shifts a GitHub duplicate fragment onto our id', () => {
+    expect(getHashTargetElement('setup-1')?.id).toBe('setup-2')
+    expect(getHashTargetElement('setup-2')?.id).toBe('setup-2')
+  })
+
+  it('an id that genuinely ends in a number is matched exactly, never shifted', () => {
+    // `step-2` exists, so the exact lookup wins and `step-3` is never consulted.
+    expect(getHashTargetElement('step-2')?.id).toBe('step-2')
+  })
+
+  it('does not invent a match when the shifted id is absent too', () => {
+    expect(getHashTargetElement('missing-1')).toBeNull()
+  })
+})
+
+describe('getHashTargetElement — the fuzzy pass is wired into THE resolver', () => {
+  beforeEach(() => {
+    document.body.innerHTML = `
+      <h2 id="getting-started">🚀 Getting Started</h2>
+      <div id="ticket-a/b">encoded-id row</div>
+    `
+  })
+
+  it('exact ids still win, unchanged', () => {
+    expect(getHashTargetElement('getting-started')?.id).toBe('getting-started')
+  })
+
+  it('percent-decoding still runs before the fuzzy pass', () => {
+    expect(getHashTargetElement('ticket-a%2Fb')?.id).toBe('ticket-a/b')
+  })
+
+  it('falls back to a normalized match — the TOC bug, through the public entry point', () => {
+    expect(getHashTargetElement('-getting-started')?.id).toBe('getting-started')
+  })
+
+  it('still returns null when nothing matches', () => {
+    expect(getHashTargetElement('nope')).toBeNull()
+    expect(getHashTargetElement('')).toBeNull()
+  })
+})
+
+describe('the openframe-cli doc that reported the bug', () => {
+  // Verbatim shapes from
+  // GET /api/docs/sources/openframe-docs/content?path=openframe-cli
+  const headings = [
+    '# OpenFrame CLI — Documentation',
+    '## 📚 Table of Contents',
+    '## 🚀 Getting Started',
+    '## 🛠️ Development',
+    '## 💬 Community & Support',
+  ].join('\n\n')
+  const tocHrefs = ['#-getting-started', '#-development', '#-community--support']
+
+  it('every TOC href resolves to the id the section extractor emits', () => {
+    const sections = extractSections(headings)
+    document.body.innerHTML = sections
+      .map((s) => `<h2 id="${s.id}">${s.title}</h2>`)
+      .join('')
+
+    const resolved = tocHrefs.map((href) => getHashTargetElement(href.slice(1))?.id ?? null)
+    expect(resolved).toEqual(['getting-started', 'development', 'community-support'])
+    // …and none of them resolved before this helper existed:
+    expect(tocHrefs.map((href) => document.getElementById(href.slice(1)))).toEqual([
+      null,
+      null,
+      null,
+    ])
+  })
+})

package/src/utils/__tests__/content-href.test.ts

@@ -32,6 +32,80 @@ describe('makeComposeContentUrl (unified single-object seam)', () => {
     })
   })
 
+  it('canonicalizes rail-vocab aliases before matching suffixes', () => {
+    // `blog_post_existing` is the legacy ContentRef spelling `buildListUrl`
+    // accepts. Without canonicalization here it missed `suffixes` entirely and
+    // emitted `<hub>/blog_post_existing/<slug>` — the same post reachable at
+    // two different urls depending on which call site produced the link.
+    expect(compose({ type: 'blog_post_existing', identifier: 'hello' })).toEqual(
+      compose({ type: 'blog_post', identifier: 'hello' }),
+    )
+    expect(compose({ type: 'blog_post_existing', identifier: 'hello' })).toEqual({
+      href: `${HUB}/blog/hello`,
+      targetPlatform: null,
+    })
+  })
+
+  it('non-hosted row resolves to the OWNING platform, not to contentOrigin', () => {
+    // The reported bug: an OpenMSP-owned blog post linked to flamingo.run.
+    expect(
+      compose({ type: 'blog_post', identifier: 'why-mdr', platforms: [{ name: 'openmsp' }] }),
+    ).toEqual({ href: 'https://www.openmsp.ai/blog/why-mdr', targetPlatform: 'openmsp' })
+  })
+
+  it('reads all three junction shapes the DALs produce', () => {
+    const shapes = [
+      [{ name: 'openmsp' }],
+      [{ platform_name: 'openmsp' } as unknown as { name?: string }],
+      [{ platforms: { name: 'openmsp' } } as unknown as { name?: string }],
+    ]
+    for (const platforms of shapes) {
+      expect(compose({ type: 'blog_post', identifier: 'x', platforms }).href).toBe(
+        'https://www.openmsp.ai/blog/x',
+      )
+    }
+  })
+
+  it('explicit targetPlatform wins over the junction', () => {
+    expect(
+      compose({
+        type: 'blog_post',
+        identifier: 'x',
+        targetPlatform: 'tmcg',
+        platforms: [{ name: 'openmsp' }],
+      }),
+    ).toEqual({ href: 'https://www.tmcg.miami/blog/x', targetPlatform: 'tmcg' })
+  })
+
+  it('falls back to contentOrigin for an unknown or absent platform', () => {
+    expect(compose({ type: 'blog_post', identifier: 'x' })).toEqual({
+      href: `${HUB}/blog/x`,
+      targetPlatform: null,
+    })
+    // An unresolvable owner reports `null`, NOT its own name: the href came
+    // from `contentOrigin`, and `decideNewTab` prefers `targetPlatform` over
+    // its origin check — so claiming a platform here forced a same-host link
+    // into a new tab.
+    expect(
+      compose({ type: 'blog_post', identifier: 'x', platforms: [{ name: 'not-a-platform' }] }),
+    ).toEqual({ href: `${HUB}/blog/x`, targetPlatform: null })
+    expect(
+      compose({ type: 'blog_post', identifier: 'x', targetPlatform: 'not-a-platform' }),
+    ).toEqual({ href: `${HUB}/blog/x`, targetPlatform: null })
+  })
+
+  it('externalUrl still wins — the RAG url is authoritative', () => {
+    expect(
+      compose({
+        type: 'blog_post',
+        identifier: 'x',
+        externalUrl: 'https://www.openmsp.ai/blog/x',
+        targetPlatform: 'openmsp',
+        platforms: [{ name: 'flamingo' }],
+      }),
+    ).toEqual({ href: 'https://www.openmsp.ai/blog/x', targetPlatform: 'openmsp' })
+  })
+
   it('always returns a tuple (never null) — even for an unknown type', () => {
     expect(compose({ type: 'totally_unknown', identifier: 'x' })).toEqual({
       href: `${HUB}/totally_unknown/x`,

package/src/utils/__tests__/list-url.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { buildListUrl } from '../list-url'
+import { buildListUrl, canonicalContentRefType } from '../list-url'
 
 /**
  * Byte-parity gate for the shared `buildListUrl`.
@@ -33,6 +33,16 @@ describe('buildListUrl — byte parity with the hub mappers', () => {
     expect(buildListUrl(type, ['a', 'b'])).toBe(expected)
   })
 
+  it('canonicalContentRefType: aliases resolve, prototype keys do not', () => {
+    expect(canonicalContentRefType('blog_post_existing')).toBe('blog_post')
+    expect(canonicalContentRefType('roadmap_item')).toBe('roadmap_item')
+    // A bare `ALIASES[key]` read returned `Object` here, which downstream
+    // interpolated into a URL path.
+    expect(canonicalContentRefType('constructor')).toBe('constructor')
+    expect(canonicalContentRefType('__proto__')).toBe('__proto__')
+    expect(canonicalContentRefType('toString')).toBe('toString')
+  })
+
   it('un-aliases blog_post_existing → blog_post (mirrors hub LEGACY_TYPE_ALIASES)', () => {
     expect(buildListUrl('blog_post_existing', ['a', 'b'])).toBe(BASELINE.blog_post)
   })

package/src/utils/anchor-id.ts

@@ -0,0 +1,106 @@
+/**
+ * GitHub-compatible anchor resolution for in-page `#hash` links.
+ *
+ * ## The mismatch this exists to bridge
+ *
+ * Doc authors write their table of contents against GitHub's slugger, which
+ * keeps the separator left behind by a stripped emoji:
+ *
+ *   `## 📚 Table of Contents`  →  GitHub anchor `#-table-of-contents`
+ *
+ * Our heading ids come from the shared slug SSOT (`markdown-heading-id`),
+ * whose `slugifyHeadingBase` trims leading and trailing hyphens — so the same
+ * heading renders as `id="table-of-contents"`. The "On this page" rail
+ * navigates by those ids and works; the in-body TOC link points at an id that
+ * does not exist and the browser silently does nothing.
+ *
+ * Rather than change the id shape (it is already baked into shared URLs and
+ * the rail), resolution is made tolerant: compare a *normalized* form of both
+ * sides. This module owns ONLY that tolerance — the slug chain itself is
+ * imported, never re-implemented, so a change to the id shape lands in one
+ * place and both sides move together.
+ *
+ * Callers do not reach for this directly: `getHashTargetElement`
+ * (`utils/same-page-hash-nav`) is the ONE resolver every hash consumer goes
+ * through, and it applies this as its last pass.
+ */
+import { slugifyHeadingText } from './markdown-heading-id'
+
+/**
+ * Reduce an anchor id (ours or GitHub's) to a comparable form.
+ *
+ * Everything but the final hyphen-run collapse is the shared heading-slug
+ * chain: emoji strip → lowercase → drop non-word chars → spaces to hyphens →
+ * trim edge hyphens. The collapse is this module's own addition, covering
+ * GitHub's *interior* divergence — `## 💬 Community & Support` slugs to
+ * `#-community--support` (a double hyphen around the dropped `&`) against our
+ * `community-support`.
+ *
+ *   `'-getting-started'`     → `'getting-started'`
+ *   `'-community--support'`  → `'community-support'`
+ *   `'Getting Started'`      → `'getting-started'`
+ */
+export function normalizeAnchorId(raw: string): string {
+  return slugifyHeadingText(raw).replace(/-+/g, '-').replace(/^-+|-+$/g, '')
+}
+
+/** Heading elements carrying an id — the candidate set for the fuzzy pass. */
+const HEADING_SELECTOR = 'h1[id], h2[id], h3[id], h4[id], h5[id], h6[id]'
+
+/** A `base-N` id, split into its base and ordinal. */
+const DUPLICATE_SUFFIX_RE = /^(.+)-(\d+)$/
+
+/**
+ * The two sides also disagree on where duplicate-heading numbering STARTS.
+ * For a document with two `## Setup` headings GitHub emits `setup` and
+ * `setup-1`, while `createHeadingIdDeduper` emits `setup` and `setup-2` (its
+ * suffix is the occurrence COUNT, not the offset). So a GitHub `#setup-1`
+ * needs our `setup-2` — every duplicate is off by exactly one.
+ *
+ * Runs LAST, after the exact lookup and the heading scan have both missed: a
+ * heading that genuinely slugs to `step-2` is resolved long before this, and
+ * the shift is the one pass that can match an id it was not asked for.
+ */
+function findDuplicateShifted(normalized: string, doc: Document): HTMLElement | null {
+  const parts = DUPLICATE_SUFFIX_RE.exec(normalized)
+  if (!parts) return null
+  const ordinal = Number(parts[2])
+  if (!Number.isSafeInteger(ordinal)) return null
+  return doc.getElementById(`${parts[1]}-${ordinal + 1}`)
+}
+
+/**
+ * Resolve a `#hash` id that no exact lookup matched, by comparing normalized
+ * forms. Returns `null` when nothing in the document matches, so the caller
+ * can leave the browser's default behavior alone rather than hijacking a
+ * click that was never ours to handle.
+ *
+ * Three passes, in order of how much they assume:
+ *   1. a single `getElementById` on the normalized id — catches the whole
+ *      emoji-hyphen family without walking the DOM;
+ *   2. a heading scan — catches ids whose own raw form normalizes differently
+ *      (e.g. `a---b`, from a title containing a literal ` - `);
+ *   3. the duplicate-heading shift (see `findDuplicateShifted`) — last,
+ *      because it is the only pass that resolves to an id the fragment did
+ *      not name.
+ */
+export function findAnchorElementByNormalizedId(
+  rawId: string,
+  doc: Document,
+): HTMLElement | null {
+  const normalized = normalizeAnchorId(rawId)
+  if (!normalized) return null
+
+  if (normalized !== rawId) {
+    const direct = doc.getElementById(normalized)
+    if (direct) return direct
+  }
+
+  for (const heading of Array.from(doc.querySelectorAll<HTMLElement>(HEADING_SELECTOR))) {
+    if (normalizeAnchorId(heading.id) === normalized) return heading
+  }
+
+  // Last: the shift would happily match an unrelated `x-3` for a `x-2` that
+  // has no heading at all, so it runs only once the scan has come up empty.
+  return findDuplicateShifted(normalized, doc)
+}