[Feature] Add Message Scroller component

[djalmaaraujo]

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 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.

^{Written for commit 7e4e3ed. Summary will update on new commits.}

[cubic-dev-ai]

5 issues found across 21 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cirdes]

@djalmaaraujo, please take a look on cubic-dev comments and ask for review again

[djalmaaraujo]

Addressed all 5 cubic findings in 205355d8 (registry rebuilt):

• P1 — anchor scroll yank: anchored-turn scrolling is now gated behind autoScroll && following, same as end scrolling. A new turn no longer pulls a reader who scrolled up to older content; the jump button surfaces it instead.
• P2 — button ignores direction: renamed the action jumpToEnd → jump and it branches on data-direction, so a direction: :start button jumps to the start.
• P2 — last-anchor throws without content: guarded with hasContentTarget (the Stimulus target getter throws rather than returning undefined, so optional chaining didn't help).
• P2 — prepend under-compensates by gap: prepend preservation now adds the computed flex row-gap per inserted row, so the visible row stays put.
• P2 — subtree prepend false positive: only direct children of the content element count as transcript rows; markup mutated inside a message is treated as streaming, not history.

@cirdes ready for another look.

[cubic-dev-ai]

2 issues found across 5 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[djalmaaraujo]

Added the faithful shadcn-style chat window as the hero example, addressing the gap raised in review:

• Empty state — uses the new Empty component (split into its own PR [Feature] Add Empty component #448). The window shows it until the first message.
• Full chat window — Card (header + content + footer) with an input + send button, matching the shadcn demo layout.
• Interactive — a docs-only Stimulus harness (message-scroller-chat) clones server-rendered user/assistant <template> rows on send, so autoscroll + turn-anchoring are demonstrated live (standing in for an ActionCable/streaming source, which is the intended real-world driver).

This PR now stacks on #448 (Empty) — base retargeted to feat/empty-component. Merge order: #448 → #447.

The earlier "empty state / full chat window out of scope" note no longer applies — both are now included.

[djalmaaraujo]

Fixed in 7e4e3edf: updateButton() is now direction-aware and iterates all button targets. An end button activates when away from the bottom; a start button activates when away from the top (isAtStart()), instead of both keying off !isAtEnd(). Registry rebuilt.