feat(react-ui-base): add MessageThreadPanel base primitive

[lachieh]

Summary

• Adds unstyled MessageThreadPanel compound component to @tambo-ai/react-ui-base
• Provides Root, Resizable, Content, and Sidebar sub-components for building resizable panel UIs
• Includes drag-to-resize functionality with CSS custom properties for width management

Test plan

• npm run check-types -w packages/react-ui-base passes
• npm run lint -w packages/react-ui-base passes
• Verify exports are accessible via @tambo-ai/react-ui-base/message-thread-panel

Fixes TAM-1060

🤖 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 1:02am
showcase	Error		Feb 9, 2026 1:02am
tambo-docs	Error		Feb 9, 2026 1:02am

[charliecreates]

Several base primitives currently include behavior that makes composition brittle: global side effects (ThreadHistoryRoot mutating documentElement), non-composed event handlers that can be overwritten by consumer props, and shortcut/key handling that may be inconsistent across platforms. There’s also a concrete config issue: duplicated moduleNameMapper entries in ui-registry Jest config. Addressing these will improve correctness, reusability, and alignment with the project’s headless primitive patterns.

Additional notes (1)

• Maintainability | packages/ui-registry/jest.config.ts:22-35
packages/ui-registry/jest.config.ts now includes two identical moduleNameMapper entries for ^@tambo-ai/react-ui-base/(.*)$. This duplication is confusing and risks one of them being edited later while the other remains, causing brittle behavior.

Only one mapping should exist.

Summary of changes

What changed

New base primitives in @tambo-ai/react-ui-base

• Added new compound-component primitives for:
  • scrollable-message-container: Viewport and ScrollToBottom primitives.
  • thread-content: Root, MessageList, and Message primitives, plus getMessageKey.
  • thread-dropdown: Root, Trigger, Menu, NewThreadItem, and ThreadItem primitives.
  • thread-history: Root and supporting primitives (Header, CollapseToggle, NewThreadButton, SearchInput, List, Item).

Render-prop API standardization

• Updated PropsWithChildrenOrRenderFunction to prefer children as function and mark render as deprecated.
• Updated useRender() to prefer children-as-function over deprecated render prop.

ui-registry refactors to compose base primitives

• Refactored multiple styled components in packages/ui-registry/src/components/* to compose the new base primitives rather than duplicating context/state logic (e.g. CanvasSpace, EditWithTamboButton, ElicitationUI, Form, Graph, InputFields, Map, MessageInput, MessageSuggestions, ScrollableMessageContainer, ThreadContent, ThreadDropdown, ThreadHistory).

Tooling/test config updates

• Updated packages/ui-registry/jest.config.ts to map @tambo-ai/react-ui-base/* subpath imports to source.

Docs / planning

• Added plans/compound-component-refactor.md documenting phases and patterns.

[charliecreates]

viewportRef is being assigned via a forced cast to MutableRefObject and a bespoke inline ref-forwarding implementation. This is brittle and easy to get subtly wrong (especially if viewportRef is already a callback ref or not guaranteed to be mutable), and it duplicates a common pattern used elsewhere.

This also makes it harder to maintain and audit for correct ref behavior with asChild (Slot) usage.

Suggestion

Consider using Radix's composeRefs (@radix-ui/react-compose-refs) or a small internal mergeRefs helper to merge viewportRef and the forwarded ref without as casting.

Example:

import { composeRefs } from "@radix-ui/react-compose-refs";

...
const composedRef = React.useMemo(
  () => composeRefs(viewportRef, ref),
  [viewportRef, ref],
);

return (
  <Comp
    ref={composedRef}
    data-slot="scrollable-message-container-viewport"
    {...props}
  >
    {children}
  </Comp>
);

This removes the unsafe cast and centralizes correct ref semantics. Reply with "@CharlieHelps yes please" if you'd like me to add a commit with this suggestion.

[charliecreates]

The keyboard shortcut handler uses event.key === "n". On some keyboards/layouts and with Shift held, event.key can be uppercase ("N") or vary; additionally, the code is hard-coded to Alt+Shift+N even though the UI advertises a platform-specific modifier.

This can lead to shortcuts that work inconsistently depending on layout and OS, and it also ignores the isMac/modKey intention (currently modKey is a symbol on Mac but the listener still checks altKey).

Suggestion

Normalize the key and align the actual shortcut logic with the label you present:

• Use event.key.toLowerCase() === "n".
• Decide whether Mac should be alt+shift+n or meta+shift+n (and ensure both label + handler match).

Example:

const isTrigger = isMac
  ? event.metaKey && event.shiftKey && event.key.toLowerCase() === "n"
  : event.altKey && event.shiftKey && event.key.toLowerCase() === "n";

Or keep Alt everywhere but make labels match (modKey should then be "Alt"/"⌥"). Reply with "@CharlieHelps yes please" if you'd like me to add a commit with this suggestion.

[charliecreates]

ThreadDropdownRoot registers a global document.addEventListener("keydown", ...) for Alt+Shift+N. When multiple dropdown roots are mounted (common in component libraries, storybooks, or multi-panel UIs), this will create duplicated handlers and multiple thread creations per keypress.

Also, this listener fires even when focus is inside text inputs/textarea, which is likely undesirable.

Suggestion

Guard the shortcut and avoid global duplication. Options:

1. Only enable the listener when the dropdown is open / focused, or when a prop enables shortcuts.
2. Ignore key presses originating from editable elements.
3. Use an AbortController to ensure cleanup and simplify effect logic.

Example guard:

const isEditableTarget = (t: EventTarget | null) => {
  const el = t as HTMLElement | null;
  return !!el && (
    el.tagName === "INPUT" ||
    el.tagName === "TEXTAREA" ||
    el.isContentEditable
  );
};

React.useEffect(() => {
  const onKeyDown = (event: KeyboardEvent) => {
    if (isEditableTarget(event.target)) return;
    if (event.altKey && event.shiftKey && event.key.toLowerCase() === "n") {
      event.preventDefault();
      void handleNewThread();
    }
  };
  document.addEventListener("keydown", onKeyDown);
  return () => document.removeEventListener("keydown", onKeyDown);
}, [handleNewThread]);

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

[charliecreates]

This component mutates a global CSS variable on document.documentElement inside the base primitive. That’s a significant side effect for a headless primitive:

• It creates cross-instance coupling (multiple sidebars would race each other).
• It leaks styling decisions into base logic, reducing reusability.
• It can cause surprising global layout changes when this component mounts.

This is especially problematic since the repo’s own patterns emphasize unstyled/base primitives with styling controlled at the wrapper layer via data-* attributes.

Suggestion

Move the CSS variable mutation out of the base primitive and into the styled wrapper (or expose state via data-collapsed and let CSS handle width without JS). If you must support CSS-variable-based layouts, consider:

• Accepting a callback prop like onSidebarWidthChange(width: string) in the base root, or
• Applying the CSS variable on the root element only (not documentElement), e.g. style={{ "--sidebar-width": ... } as React.CSSProperties }.

This keeps the primitive composable and avoids global side effects. Reply with "@CharlieHelps yes please" if you'd like me to add a commit with this suggestion.

[charliecreates]

setTimeout(..., 300) is used to focus the search input after expanding. This is timing-coupled to the CSS animation duration and can break if durations change, user prefers reduced motion, or the browser throttles timers.

Since this is a base primitive, it’s better to make focusing deterministic and not depend on magic numbers.

Suggestion

Prefer a deterministic focus strategy:

• Use requestAnimationFrame (possibly twice) after setIsCollapsed(false), or
• Focus on next layout effect when isCollapsed becomes false and a shouldFocus flag is set.

Example:

const [shouldFocus, setShouldFocus] = React.useState(false);

const expandOnSearch = React.useCallback(() => {
  if (isCollapsed) {
    setShouldFocus(true);
    setIsCollapsed(false);
  }
}, [isCollapsed, setIsCollapsed]);

React.useLayoutEffect(() => {
  if (!isCollapsed && shouldFocus) {
    searchInputRef.current?.focus();
    setShouldFocus(false);
  }
}, [isCollapsed, shouldFocus]);

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

[charliecreates]

ThreadHistoryCollapseToggle always sets onClick={handleToggle} and then spreads {...props} afterwards. If a consumer passes their own onClick, it will override the internal toggle behavior and the component will silently stop working.

For primitives, the internal behavior should be preserved and consumer handlers should be composed (called in addition).

Suggestion

Compose the click handler instead of letting it be overwritten:

const { onClick, ...rest } = props;

<Comp
  ...
  onClick={(e) => {
    onClick?.(e);
    if (!e.defaultPrevented) handleToggle();
  }}
  {...rest}
/>

This preserves the toggle while still allowing consumers to hook into the event. Reply with "@CharlieHelps yes please" if you'd like me to add a commit with this suggestion.

[charliecreates]

Similar to the collapse toggle: ThreadHistoryItem sets onClick={handleClick} and then spreads {...props} after it, allowing consumer onClick to override the internal switch-thread behavior.

This is a correctness issue: the component may render but no longer switches threads when clicked.

Suggestion

Compose onClick like:

const { onClick, ...rest } = props;

<Comp
  ...
  onClick={(e) => {
    onClick?.(e);
    if (!e.defaultPrevented) void handleClick();
  }}
  {...rest}
/>

Also consider using a <button> by default for accessibility if this is intended to be interactive (or require role="button" + keyboard handlers). Reply with "@CharlieHelps yes please" if you'd like me to add a commit with this suggestion.

[charliecreates]

ThreadDropdownTrigger forces type="button" unconditionally. When asChild is used, consumers may provide a non-<button> element (e.g. <a>), and type will be passed to it.

While React will generally ignore unknown attributes for many elements, this makes asChild composition leaky. The common Radix/Slot pattern is to only set type when rendering an actual <button>.

Suggestion

Only set type="button" when Comp is a real button:

<Comp
  ref={ref}
  {...(!asChild ? { type: "button" } : {})}
  data-slot="thread-dropdown-trigger"
  {...props}
>

This keeps asChild usage cleaner. Reply with "@CharlieHelps yes please" if you'd like me to add a commit with this suggestion.

[charliecreates]

useRender() now prefers children-as-function, which is good. However, PropsWithChildrenOrRenderFunction is defined as Omit<ComponentProps, "children"> & { children?: ...; render?: ... }.

That means if a component's ComponentProps legitimately includes a children prop with a stricter type (e.g., children: (x) => ... only), you lose that type information. It’s a subtle but real DX regression for base primitives where children types matter.

Given the plan doc explicitly says render prop is deprecated and new code should use children-as-function, it’d be better if the helper preserved/parameterized the children type rather than erasing it.

Suggestion

Consider making PropsWithChildrenOrRenderFunction accept a Children generic (defaulting to React.ReactNode | ((props) => React.ReactNode)) rather than always omitting/overriding children.

Sketch:

export type PropsWithChildrenOrRenderFunction<
  ComponentProps,
  RenderPropProps = never,
  Children = React.ReactNode | ((props: RenderPropProps) => React.ReactNode)
> = Omit<ComponentProps, "children"> & {
  children?: Children;
  /** @deprecated Use children as a function instead. */
  render?: ComponentRenderFn<RenderPropProps>;
};

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