feat(react-ui-base): add scrollable-message-container compound component

[lachieh]

Summary

Adds scrollable-message-container compound component base primitives and styled wrapper.

Base: Root, Viewport, ScrollToBottom
Styled: Composes base components with Tailwind styling

Fixes TAM-1061

Test Plan

• Verify component renders in showcase
• Run npm run lint && npm run check-types && npm test

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
cloud	Error		Feb 9, 2026 10:18pm
showcase	Error		Feb 9, 2026 10:18pm
tambo-docs	Error		Feb 9, 2026 10:18pm

[charliecreates]

The biggest issue is architectural: ScrollableMessageContainerRoot lives in react-ui-base but directly depends on @tambo-ai/react thread state, making the “base primitive” not actually generic and likely to throw if used outside a Tambo provider. There are also performance/UX concerns around always using behavior: "smooth" for auto-scrolling (especially during streaming). Lastly, the context ref typing is inconsistent with how it’s mutated, and the styled wrapper’s props/asChild forwarding is redundant/surprising.

Additional notes (1)

• Readability | ...nents/scrollable-message-container/scrollable-message-container.tsx:11-11
  The wrapper component’s props type intersects ScrollableMessageContainerViewportProps with React.HTMLAttributes<HTMLDivElement>. Since ScrollableMessageContainerViewportProps is already BaseProps<React.HTMLAttributes<HTMLDivElement>>, this intersection is redundant and can confuse consumers (and can lead to harder-to-read generated docs).

Also, in the wrapper, {...props} is spread onto Viewport while Root is rendered as asChild with no props passed—so any asChild passed to the wrapper will be forwarded to Viewport, not Root. If the wrapper is meant to preserve the original single-element API, it’s fine to not expose asChild at all, but currently it’s implicitly exposed and does something surprising.

Summary of changes

Added ScrollableMessageContainer compound component (react-ui-base)

• Exported a new package entrypoint ./scrollable-message-container in packages/react-ui-base/package.json to publish ESM/CJS builds (dist/esm/..., dist/cjs/...).
• Re-exported ScrollableMessageContainer and its related types from packages/react-ui-base/src/index.ts.
• Introduced a new compound component under packages/react-ui-base/src/scrollable-message-container/:
  • Root primitive that manages scroll state, auto-scroll behavior, and provides context.
  • Viewport primitive that binds the scrollable element to the root’s viewportRef.
  • ScrollToBottom primitive that exposes render props (isAtBottom, scrollToBottom).

Updated ui-registry to consume the base primitives

• Updated packages/ui-registry/src/components/scrollable-message-container/config.json to depend on @tambo-ai/react-ui-base@next and to include the base registry files.
• Refactored the styled ScrollableMessageContainer wrapper to compose ScrollableMessageContainerBase.Root + Viewport, preserving the previous single-component API surface while moving behavior into the base package.

[charliecreates]

ScrollableMessageContainerRoot is part of react-ui-base, but it directly imports and depends on @tambo-ai/react (useTambo, GenerationStage). That makes this “base primitive” tightly coupled to the Tambo thread model and effectively not reusable outside that context.

This is a design/correctness issue for a base component library: consumers who want a generic scrollable container will be forced to install and run Tambo thread logic, and the component becomes harder to test in isolation. It also creates an implicit contract that the Root must be used inside a TamboProvider, otherwise useTambo() will likely throw at runtime.

If the intent is truly “message container for Tambo threads”, consider moving it to a Tambo-specific package (or to ui-registry only). If you want it in react-ui-base, the Root should accept the relevant signals as props (e.g., contentKey, isStreaming, onReachBottom, etc.) rather than reaching into Tambo state itself.

Suggestion

Decouple react-ui-base from @tambo-ai/react by lifting “what changed” and “streaming vs not” into props, and remove the useTambo() dependency.

For example:

export type ScrollableMessageContainerRootProps = BaseProps<
  React.HTMLAttributes<HTMLDivElement> & {
    /** Changes when content changes; used to trigger autoscroll */
    contentKey?: unknown;
    /** Whether content is currently streaming (affects scroll scheduling) */
    isStreaming?: boolean;
  }
>;

Then use contentKey in the autoscroll effect deps instead of messagesContent, and use isStreaming instead of GenerationStage.

Reply with "@CharlieHelps yes please" if you'd like me to add a commit implementing this refactor (including updating the ui-registry wrapper to pass the appropriate values from useTambo()).

[charliecreates]

scrollToBottom() always uses behavior: "smooth". When called during streaming updates and/or in the auto-scroll effect, this can cause jank (repeated smooth scroll animations) and can also fight user intent if they briefly scroll.

You already differentiate streaming vs non-streaming for scheduling; the same distinction should usually apply to scroll behavior (instant during streaming, smooth for user-initiated button clicks).

Suggestion

Add an option/parameter to scrollToBottom (or a separate scrollToBottomInstant) and use instant scrolling for auto-scroll while keeping smooth scrolling for explicit user actions.

Example:

const scrollToBottom = React.useCallback((opts?: { behavior?: ScrollBehavior }) => {
  const el = viewportRef.current;
  if (!el) return;
  el.scrollTo({ top: el.scrollHeight, behavior: opts?.behavior ?? "auto" });
}, []);

• In the auto-scroll effect: scrollToBottom({ behavior: "auto" })
• In ScrollToBottom button: scrollToBottom({ behavior: "smooth" })

Reply with "@CharlieHelps yes please" if you'd like me to add a commit with this change.

[charliecreates]

handleViewportScroll toggles shouldAutoscroll based on scroll direction using lastScrollTopRef. This can disable autoscroll even when the user scrolls only slightly (e.g., trackpad jitter) and doesn’t consider programmatic smooth scrolling (triggered by scrollToBottom) which also fires scroll events and can flip state unexpectedly.

It’s safer to drive autoscroll primarily from atBottom (with tolerance), and only suspend on explicit user intent (wheel/touch/scrollbar drag) or when atBottom becomes false.

Suggestion

Simplify the state machine:

• Compute atBottom and always set isAtBottom.
• Set shouldAutoscroll to atBottom (or only resume when atBottom is true), and suspend only when atBottom becomes false and the event was user-initiated.

A pragmatic improvement without complex pointer heuristics:

const atBottom = ...;
setIsAtBottom(atBottom);
setShouldAutoscroll(atBottom);

If you need “suspend even when near-bottom but user scrolls up a bit”, add onWheel/onTouchMove handlers on the viewport to call suspendAutoscroll().

Reply with "@CharlieHelps yes please" if you'd like me to add a commit that adjusts the autoscroll logic and reduces unexpected toggling.

[charliecreates]

In Viewport, the context ref is typed as RefObject<HTMLDivElement | null> but you’re mutating it by casting to MutableRefObject. This works because it’s actually created via useRef in the root, but the current context typing communicates “read-only” while the viewport relies on mutability.

This mismatch makes the API brittle: if the ref implementation ever changes, this becomes a footgun. It also encourages unsafe casts in downstream primitives.

Suggestion

Change the context type to accurately reflect intended usage by storing a React.MutableRefObject<HTMLDivElement | null>.

export interface ScrollableMessageContainerRootContextValue {
  // ...
  viewportRef: React.MutableRefObject<HTMLDivElement | null>;
}

Then remove the cast in Viewport and assign directly.

Reply with "@CharlieHelps yes please" if you'd like me to add a commit updating the context typing + viewport assignment.

[charliecreates]

The Viewport assigns the context ref by casting viewportRef to MutableRefObject and manually merges forwarded refs. This is brittle and easy to get wrong (especially if viewportRef type changes), and it’s a pattern that tends to get duplicated.

Prefer a small composeRefs/mergeRefs utility or useCallback ref that sets both without type assertions.

Suggestion

Replace the cast + manual branching with a composeRefs helper.

Example:

function composeRefs<T>(...refs: Array<React.Ref<T> | undefined>) {
  return (node: T) => {
    for (const ref of refs) {
      if (!ref) continue;
      if (typeof ref === "function") ref(node);
      else (ref as React.MutableRefObject<T>).current = node;
    }
  };
}

Then:

ref={composeRefs(ref, viewportRef)}

This removes the unsafe assertion and simplifies the component.

Reply with "@CharlieHelps yes please" if you'd like me to add a commit with this ref composition change.

[charliecreates]

ScrollableMessageContainerScrollToBottom always renders a wrapping div/Slot even when there is no children and no render function output. The docstring says it can return null, but the implementation doesn’t.

Rendering an empty element can affect layout, focus order, and CSS selectors (e.g. spacing utilities).

Suggestion

Return null when there’s nothing to render.

After useRender, do:

if (content == null) return null;

(Use whatever “empty” semantics your useRender contract defines.)

Reply with "@CharlieHelps yes please" if you'd like me to add a commit updating this component to truly return null when there’s no content.