@flamingo-stack/openframe-frontend-core 0.0.243 → 0.0.244

package/dist/utils/list-url.d.ts

@@ -27,12 +27,6 @@
  * Pure + server-safe (no React, no browser APIs) so the hub's server-side
  * mappers can import it from `@flamingo-stack/openframe-frontend-core/utils`.
  */
-/** Resolve a ContentRef rail-vocab type to its canonical `documentType`
- *  (registry vocabulary) — `blog_post_existing` → `blog_post`, everything
- *  else passes through. Exported so consumers comparing rail group keys to
- *  registry entityTypes (e.g. the related-content rail's same-type-first
- *  ordering) share THIS alias map instead of re-declaring it. */
-export declare function canonicalContentRefType(contentRefType: string): string;
 /**
  * Build a list-API URL that returns full rows for the given ids, or `null`
  * when the type has no list endpoint (the caller skips fetching rather than

package/dist/utils/list-url.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"list-url.d.ts","sourceRoot":"","sources":["../../src/utils/list-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAWH;;;;iEAIiE;AACjE,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAEtE;AA4BD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,IAAI,SAAK,GAAG,MAAM,GAAG,IAAI,CAa5F"}
+{"version":3,"file":"list-url.d.ts","sourceRoot":"","sources":["../../src/utils/list-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAqCH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,IAAI,SAAK,GAAG,MAAM,GAAG,IAAI,CAa5F"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.243",
+  "version": "0.0.244",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",
@@ -60,12 +60,6 @@
       "require": "./dist/components/faq/index.cjs",
       "default": "./dist/components/faq/index.js"
     },
-    "./components/related-content": {
-      "types": "./dist/components/related-content/index.d.ts",
-      "import": "./dist/components/related-content/index.js",
-      "require": "./dist/components/related-content/index.cjs",
-      "default": "./dist/components/related-content/index.js"
-    },
     "./components/faq/json-ld": {
       "types": "./dist/components/faq/json-ld.d.ts",
       "import": "./dist/components/faq/json-ld.js",

package/src/components/chat/__tests__/chat-message-list.test.tsx

@@ -0,0 +1,92 @@
+import { render } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { Message } from '../types/message.types'
+
+const scrollToBottom = vi.fn()
+const stopScroll = vi.fn()
+
+function makeRef() {
+  const fn = ((el: HTMLElement | null) => {
+    ;(fn as { current: HTMLElement | null }).current = el
+  }) as ((el: HTMLElement | null) => void) & { current: HTMLElement | null }
+  fn.current = null
+  return fn
+}
+const scrollRefMock = makeRef()
+const contentRefMock = makeRef()
+
+vi.mock('use-stick-to-bottom', () => ({
+  useStickToBottom: () => ({
+    scrollRef: scrollRefMock,
+    contentRef: contentRefMock,
+    scrollToBottom,
+    stopScroll,
+  }),
+}))
+
+// Keep the row renderer trivial — these tests exercise ChatMessageList's
+// scroll orchestration, not markdown rendering.
+vi.mock('../chat-message-enhanced', () => ({
+  ChatMessageEnhanced: ({ content }: { content: string }) => <div>{content}</div>,
+}))
+
+import { ChatMessageList } from '../chat-message-list'
+
+// jsdom ships neither observer; the component instantiates both
+// (load-more sentinel + top-anchor settle watcher).
+class ObserverStub {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+vi.stubGlobal('IntersectionObserver', ObserverStub)
+vi.stubGlobal('ResizeObserver', ObserverStub)
+
+const msg = (id: string, role: Message['role']): Message => ({
+  id,
+  role,
+  content: `body of ${id}`,
+  timestamp: new Date(),
+})
+
+describe('ChatMessageList force-scroll decisions', () => {
+  beforeEach(() => {
+    scrollToBottom.mockClear()
+  })
+
+  it('snaps to bottom when the dialog changes', () => {
+    const { rerender } = render(<ChatMessageList dialogId="d1" messages={[msg('m1', 'user')]} />)
+    scrollToBottom.mockClear()
+    rerender(<ChatMessageList dialogId="d2" messages={[msg('x1', 'user')]} />)
+    expect(scrollToBottom).toHaveBeenCalled()
+  })
+
+  it('snaps to bottom when a new user message is appended', () => {
+    const initial = [msg('m1', 'user'), msg('m2', 'assistant')]
+    const { rerender } = render(<ChatMessageList dialogId="d1" messages={initial} />)
+    scrollToBottom.mockClear()
+    rerender(<ChatMessageList dialogId="d1" messages={[...initial, msg('m3', 'user')]} />)
+    expect(scrollToBottom).toHaveBeenCalled()
+  })
+
+  it('does NOT scroll when an older page is prepended (load-more)', () => {
+    const initial = [msg('m3', 'user'), msg('m4', 'assistant')]
+    const { rerender } = render(
+      <ChatMessageList dialogId="d1" messages={initial} hasNextPage onLoadMore={() => {}} />,
+    )
+    scrollToBottom.mockClear()
+    const olderPage = [msg('m1', 'user'), msg('m2', 'assistant')]
+    rerender(
+      <ChatMessageList dialogId="d1" messages={[...olderPage, ...initial]} hasNextPage onLoadMore={() => {}} />,
+    )
+    expect(scrollToBottom).not.toHaveBeenCalled()
+  })
+
+  it('does NOT scroll on assistant-only appends (library owns streaming follow)', () => {
+    const initial = [msg('m1', 'user'), msg('m2', 'assistant')]
+    const { rerender } = render(<ChatMessageList dialogId="d1" messages={initial} />)
+    scrollToBottom.mockClear()
+    rerender(<ChatMessageList dialogId="d1" messages={[...initial, msg('m3', 'assistant')]} />)
+    expect(scrollToBottom).not.toHaveBeenCalled()
+  })
+})

package/src/components/chat/chat-message-list.tsx

@@ -130,6 +130,11 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
     onLoadMoreRef.current = onLoadMore
     const isFetchingRef = useRef(isFetchingNextPage)
     isFetchingRef.current = isFetchingNextPage
+    // Fresh dialogId for the IntersectionObserver callback (its effect must
+    // not depend on `dialogId` or it would re-create on every dialog switch
+    // mid-stream; the ref keeps the snapshot's dialog tag current).
+    const dialogIdRef = useRef(dialogId)
+    dialogIdRef.current = dialogId
 
     // Tracks previous render state for explicit "force-stick" decisions
     // (dialog change, first message, new user message). The library
@@ -140,15 +145,19 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
       lastMessageId: string | undefined
     }>({ dialogId: undefined, messageCount: 0, lastMessageId: undefined })
 
-    // Snapshot of the first message id + scrollHeight observed BEFORE
-    // a load-older prepend, so we can preserve the user's viewport
-    // position when older messages stream in above their current
-    // reading position.
-    const prependRef = useRef<{
-      firstMessageId: string | undefined
-      firstMessageContent: unknown
+    // Geometry snapshot captured the instant the top sentinel triggers
+    // onLoadMore (BEFORE the older page lands), applied once when the taller
+    // content commits. Keyed on the LOAD LIFECYCLE, not `messages[0].id`: the
+    // history processor groups consecutive assistant turns into one bubble
+    // keyed by the group's LAST id, so an older page that is all continuation
+    // of the first bubble grows that bubble in place WITHOUT changing its id.
+    // An id-based anchor misses that growth and leaves the reader pinned at
+    // the top (and the still-visible sentinel never re-fires).
+    const loadOlderAnchorRef = useRef<{
+      dialogId: string | undefined
       scrollHeight: number
-    }>({ firstMessageId: undefined, firstMessageContent: undefined, scrollHeight: 0 })
+      scrollTop: number
+    } | null>(null)
 
     // ---- Force-stick: dialog change / first-load / new user message --
     useEffect(() => {
@@ -156,6 +165,7 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
 
       const dialogChanged = dialogId !== prevRenderRef.current.dialogId
       const prevCount = prevRenderRef.current.messageCount
+      const prevLastId = prevRenderRef.current.lastMessageId
       const newCount = messages.length
       const currentLastId = messages[messages.length - 1]?.id
       prevRenderRef.current = { dialogId, messageCount: newCount, lastMessageId: currentLastId }
@@ -177,7 +187,18 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
         // user message DID arrive). When the user just sent a
         // message, they expect their bubble pinned to the bottom,
         // regardless of where they were scrolled.
-        const newSlice = messages.slice(prevCount)
+        //
+        // The tail must be located via the previous LAST message id,
+        // not `slice(prevCount)`: when load-older PREPENDS a page,
+        // count grows but the new messages are at the HEAD —
+        // `slice(prevCount)` would return already-rendered tail
+        // messages (which contain user bubbles) and force-scroll the
+        // reader away from the older page they just loaded. With the
+        // id-based slice a pure prepend yields an empty tail → no
+        // scroll, and the prepend-anchoring effect below keeps their
+        // viewport position.
+        const prevLastIdx = prevLastId ? messages.findIndex((m) => m.id === prevLastId) : -1
+        const newSlice = prevLastIdx >= 0 ? messages.slice(prevLastIdx + 1) : messages.slice(prevCount)
         const hasNewUser = newSlice.some((m) => m.role === 'user')
         if (hasNewUser) {
           void scrollToBottom({ animation: 'instant', ignoreEscapes: true })
@@ -230,49 +251,35 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
     }, [autoScroll, messages, dialogId, scrollToBottom, contentRef])
 
     // ---- Prepend anchoring (load-older) ------------------------------
-    // The library doesn't preserve user position when content prepends
-    // ABOVE the viewport. We do it ourselves: snapshot scrollHeight
-    // BEFORE the new render, then add the delta after to keep the
-    // user on the same message they were reading. `useLayoutEffect`
-    // so the scrollTop write lands before paint (no visible jump).
+    // The library doesn't preserve user position when content grows ABOVE
+    // the viewport. We do: from the pre-load geometry snapshot (taken in the
+    // sentinel callback), add the height the list gained and re-pin scrollTop
+    // so the message the user was reading stays put. `useLayoutEffect` so the
+    // write lands before paint (no visible jump). Covers both a pure prepend
+    // (new ids on top) and a boundary-merge (first bubble grows in place) —
+    // it measures total height delta, not message identity.
     useLayoutEffect(() => {
       const el = scrollRef.current
-      if (!el) {
-        prependRef.current = { firstMessageId: undefined, firstMessageContent: undefined, scrollHeight: 0 }
-        return
-      }
-
-      const currentFirstId = messages[0]?.id
-      const currentFirstContent = messages[0]?.content
-      const prevFirstId = prependRef.current.firstMessageId
-      const prevHeight = prependRef.current.scrollHeight
-
-      if (currentFirstId !== prevFirstId) {
-        // First-id changed → older messages prepended (verified by
-        // confirming the previous-first is still in the array at
-        // idx > 0; otherwise this is some other mutation).
-        if (prevFirstId && prevHeight > 0) {
-          const prevIdx = messages.findIndex((m) => m.id === prevFirstId)
-          if (prevIdx > 0) {
-            const addedHeight = el.scrollHeight - prevHeight
-            if (addedHeight > 0) el.scrollTop += addedHeight
-          }
-        }
-        prependRef.current = {
-          firstMessageId: currentFirstId,
-          firstMessageContent: currentFirstContent,
-          scrollHeight: el.scrollHeight,
-        }
+      const anchor = loadOlderAnchorRef.current
+      if (!el || !anchor) return
+      // Dialog switched out from under a pending load — abandon; the
+      // force-stick effect owns the new dialog's position.
+      if (anchor.dialogId !== dialogId) {
+        loadOlderAnchorRef.current = null
         return
       }
-      // Always keep `scrollHeight` snapshot fresh so the next prepend
-      // computes the right delta. The id/content updates only when
-      // those actually change to avoid churn.
-      prependRef.current.scrollHeight = el.scrollHeight
-      if (currentFirstContent !== prependRef.current.firstMessageContent) {
-        prependRef.current.firstMessageContent = currentFirstContent
-      }
-    }, [messages, scrollRef])
+      // Hold the anchor across the intermediate renders between firing
+      // onLoadMore and the older page committing (the isFetchingNextPage
+      // flip, and in some hosts a two-stage store update) — those don't grow
+      // the list. Apply on the first render where it actually grew taller,
+      // which is the prepend (new ids on top) or a boundary-merge (first
+      // bubble grew in place). Same-id boundary-merge is why this can't key
+      // on message count.
+      const addedHeight = el.scrollHeight - anchor.scrollHeight
+      if (addedHeight <= 0) return
+      loadOlderAnchorRef.current = null
+      el.scrollTop = anchor.scrollTop + addedHeight
+    }, [messages, dialogId, scrollRef])
 
     // ---- Per-message scrollAnchor (server-driven) --------------------
     // Server emits `scrollAnchor: 'top'` on the metadata leading frame
@@ -382,6 +389,14 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
     // ---- Load-more (infinite-scroll UP) ------------------------------
     // Distinct from stick-to-bottom; uses its own IntersectionObserver
     // on the top sentinel.
+    //
+    // `isFetchingNextPage` is in the deps so the observer is RE-CREATED when a
+    // fetch completes: IntersectionObserver fires no new callback while an
+    // element stays continuously intersecting, so after an older page lands
+    // with the sentinel still in view (small prepend, or rootMargin overlap)
+    // nothing would re-trigger until the user scrolled it out and back in.
+    // Re-observing re-evaluates the current intersection and fires again if
+    // the sentinel is still visible — load continues until it's pushed out.
     useEffect(() => {
       const scrollContainer = scrollRef.current
       const sentinelElement = sentinelRef.current
@@ -392,6 +407,16 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
           const entry = entries[0]
           if (!entry) return
           if (entry.isIntersecting && !isFetchingRef.current) {
+            // Snapshot pre-load geometry so the prepend-anchoring layout
+            // effect can re-pin scrollTop once the taller content commits.
+            const el = scrollRef.current
+            if (el) {
+              loadOlderAnchorRef.current = {
+                dialogId: dialogIdRef.current,
+                scrollHeight: el.scrollHeight,
+                scrollTop: el.scrollTop,
+              }
+            }
             onLoadMoreRef.current?.()
           }
         },
@@ -399,7 +424,7 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
       )
       observer.observe(sentinelElement)
       return () => observer.disconnect()
-    }, [hasNextPage, scrollRef])
+    }, [hasNextPage, isFetchingNextPage, scrollRef])
 
     // Expose the scroll container ref to parents that need it (rare,
     // but the existing public contract). Library's `scrollRef` is a

package/src/components/chat/hooks/use-chat-card-item.ts

@@ -22,7 +22,6 @@
 import { useQuery } from '@tanstack/react-query'
 import { useRequiredChatRuntime } from '../../../contexts/chat-runtime-context'
 import { embedAuthedFetch } from '../../../utils/embed-authed-fetch'
-import { extractItems, extractItemId } from '../../../utils/extract-items'
 
 export interface UseChatCardItemResult<T = unknown> {
   item: T | undefined
@@ -30,8 +29,44 @@ export interface UseChatCardItemResult<T = unknown> {
   isError: boolean
 }
 
-// `extractItems` / `extractItemId` hoisted to `src/utils/extract-items.ts`
-// (shared with the related-content rail — react-query-free home).
+/** Extract the items array from each endpoint's response shape (some
+ *  return `{ items }`, others `{ posts }`, etc.). Single normalization
+ *  point — callers always read `Item[]`. */
+function extractItems(data: unknown): unknown[] {
+  if (!data || typeof data !== 'object') return []
+  const obj = data as Record<string, unknown>
+  if (Array.isArray(obj.items)) return obj.items
+  if (Array.isArray(obj.posts)) return obj.posts
+  if (Array.isArray(obj.campaigns)) return obj.campaigns
+  if (Array.isArray(obj.completed) || Array.isArray(obj.inProgress)) {
+    // Delivery endpoint splits into completed/inProgress arrays — flatten.
+    const completed = Array.isArray(obj.completed) ? obj.completed : []
+    const inProgress = Array.isArray(obj.inProgress) ? obj.inProgress : []
+    return [...completed, ...inProgress]
+  }
+  if (Array.isArray(obj.data)) return obj.data
+  if (Array.isArray(data)) return data
+  return []
+}
+
+/** Extract a stable id from a fetched item — different shapes use
+ *  `id` vs `external_id`. Used by the chat loader to match the fetched
+ *  array element back to the marker's id. */
+function extractItemId(type: string, item: unknown): string | null {
+  if (!item || typeof item !== 'object') return null
+  const obj = item as Record<string, unknown>
+  if (type === 'roadmap_item' || type === 'delivery_item' || type === 'internal_task') {
+    const ext = obj.external_id
+    if (typeof ext === 'string') return ext
+  }
+  // RoadmapItem-shaped responses use `id` to carry the external_id; the
+  // mapper renames external_id→id at the API boundary. Treat both id and
+  // external_id as primary-key candidates for these clickup-backed types.
+  const id = obj.id
+  if (typeof id === 'string') return id
+  if (typeof id === 'number') return String(id)
+  return null
+}
 
 export function useChatCardItem<T = unknown>(
   type: string,

package/src/components/chat/types/entities/content-ref.ts

@@ -1,7 +1,23 @@
 /**
- * RELOCATED — the canonical `ContentRef` now lives at `src/types/content-ref.ts`
- * (server-safe home, shared by the related-content rail + chat entities).
- * This stub keeps the chat entities barrel + `entities/investor-update.ts`
- * compiling unchanged. One definition package-wide.
+ * ContentRef — the unified link/embed shape stored in JSONB columns
+ * across investor updates, performance baselines, and any other entity
+ * that surfaces "related content" rails.
+ *
+ * Lifted from `lib/data/investor-update-utils-shared.ts` in the hub
+ * (the server-side data utils in the same file stay hub-side; only the
+ * TYPE moves here).
  */
-export type { ContentRef, ContentRefWithReason } from '../../../../types/content-ref';
+
+export interface ContentRef {
+  type: string;
+  id: string;
+  slug: string;
+  url: string;
+  targetPlatform?: string | null;
+  title: string;
+  summary?: string;
+  image_url?: string;
+  image_bg_color?: string;
+  visibility: 'public' | 'internal';
+  display_order: number;
+}