[Feature] Add Message Scroller component
Description
Ports the shadcn Message Scroller to RubyUI — a chat transcript scroller that follows the live edge, anchors new turns near the top, preserves position when older messages load, and jumps to the latest message.
Stacked on #446 (Message) which stacks on #445 (Bubble). Base is feat/message-component; this PR shows only the scroller diff. Retarget down the stack as the lower PRs merge.
Reference:
- Docs: https://ui.shadcn.com/docs/components/radix/message-scroller
- Source:
apps/v4/registry/bases/radix/ui/message-scroller.tsx
Our own code — no external lib
shadcn delegates the behavior to a closed React primitive (@shadcn/react/message-scroller). This is a from-scratch Stimulus controller (ruby-ui--message-scroller) — the first JS component in this stack — replicating the documented behaviors in vanilla JS:
- autoScroll follow-edge — pins to the bottom while the reader is at the live edge; releases on wheel / touch / keyboard / scrollbar away; re-engages on jump.
- scrollAnchor — settles an appended turn near the top, keeping a peek of the previous item (
previous_item_peek, default 64). - defaultPosition — open at
end/start/last-anchor. - preserveOnPrepend — hold the visible row when history loads in above.
- Public API (built for future streaming / ActionCable):
scrollToEnd,scrollToStart,scrollToMessage. New rows are picked up automatically viaMutationObserver(childList + characterData), so streamed tokens keep the view pinned. - rAF-based smooth scrolling — native
scrollTo({ behavior: "smooth" })is unreliable on a contained viewport, so the controller animatesscrollTopitself; honorsprefers-reduced-motion. - Accessibility — content is
role="log"+aria-relevant; the button has an sr-only label and is removed from the tab order while inert.
Parts
MessageScrollerProvider (owns scroll state) · MessageScroller (frame) · MessageScrollerViewport · MessageScrollerContent · MessageScrollerItem (scroll_anchor:, message_id:) · MessageScrollerButton (direction:).
Reuses Message + Bubble; dependencies.yml declares both.
Out of scope (vs shadcn)
The full primitive also does row-virtualization and exposes visibility/animation hooks. This port keeps the documented scroll behaviors and drops content-visibility virtualization, which made scrollHeight unstable and fought reliable programmatic scroll-to-end. The demo is a self-contained thread (no ai-sdk); it's wired so a future ActionCable/streaming source can drive it through the public API.
Testing
cd gem && bundle exec rake→ tests + StandardRB green.- Verified in-browser at
/docs/message_scroller: opens at the live edge, scroll up reveals the jump-to-latest button, clicking it smooth-scrolls back to the bottom and hides the button. Scroll-command buttons drive the viewport from outside the frame.
Screenshots
Add before/after of /docs/message_scroller.
Summary by cubic
Adds a Message Scroller and an Empty state. The scroller follows the live edge, anchors new turns, preserves position when history loads, and provides a jump-to-latest button. Implemented with a Stimulus controller, no external libraries.
-
New Features
- Components: MessageScrollerProvider, MessageScroller, MessageScrollerViewport, MessageScrollerContent, MessageScrollerItem, MessageScrollerButton; Empty, EmptyHeader, EmptyMedia, EmptyTitle, EmptyDescription, EmptyContent.
- Behaviors: auto-follow with release on user scroll; turn anchoring with previous_item_peek; default positions (end/start/last-anchor); preserveOnPrepend.
- API: scrollToEnd, scrollToStart, scrollToMessage; streaming picked up via
MutationObserver. - UX: rAF smooth scrolling; honors reduced motion; live-region and focus-safe button.
- Docs: new /docs/message_scroller page with an interactive chat window demo using Empty and a docs-only
message-scroller-chatcontroller; route/nav/tests/registry updated; generatordependencies.ymllistsMessageandBubble. - Fixes: gate anchoring behind auto-follow; button action renamed to
jump; direction-aware button visibility (start vs end) with multiple targets; guard last-anchor when content is missing; include row gap in prepend preservation; treat only direct content children as rows (subtree mutations count as streaming).
-
Migration
- Wrap your message list in MessageScrollerProvider and use Viewport > Content > Item.
- Mark the first row of a turn with scroll_anchor; use MessageScrollerButton to jump to the latest.
- No external dependencies; relies on
MessageandBubble.