[Feature] Add Message Scroller component

Merged
DJ
5mo ago
+1879-2

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:

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 via MutationObserver (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 animates scrollTop itself; honors prefers-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-chat controller; route/nav/tests/registry updated; generator dependencies.yml lists Message and Bubble.
    • 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 Message and Bubble.