Skip to content

Add Conversation and its scrolling #99

Closed

Description

@pratikbuilds

Add Conversation, the scroll container the chat family composes under. The mechanism (anchors, item registry, glide, reduced motion) is built in; the policy (settle or stick) is a prop.

Part of #94.

Why

Scrolling is what makes a chat feel right or wrong. Conversation owns the mechanism once, and each product picks the policy: settle a sent message at the top of the view, or stick to the bottom. The history window (#100) and the conversation map (#101) build on its item registry and anchor calls, so the anchor algorithm is specified and written here, once.

What

  • src/ui/conversation.tsx:
    • Conversation (scrollPolicy: "settle" | "stick"), ConversationContent, ConversationItem (registers its element by id), ConversationScrollButton, ConversationEmptyState.
    • useConversation(): scrollToItem, scrollToEnd, atBottom, the item registry, captureAnchor() / restoreAnchor().
  • src/ui/conversation-divider.tsx: ConversationDivider (day or label) and ConversationNotice (a one-line system event).
  • src/lib/conversation-scroll.ts: the settle target, the reserved space below, and the anchor algorithm (capture candidates, restore offset, hand over when the anchor is trimmed), as pure functions over measured rectangles.
  • stories/chat/conversation.stories.tsx: short, long and streaming in each policy, empty, with dividers and notices. Rows are plain placeholders; Conversation never renders messages.
  • e2e/fixtures.tsx: conversation-settle and conversation-stick scenarios, with e2e/conversation.spec.ts.
  • Unit tests beside the lib module; exports in src/index.ts.

Requirements

  • R20: Conversation owns the scroll container and shares it through useConversation(); it never renders messages.
  • R21: scrollPolicy of settle or stick; layout shifts never scroll; only the reader's input breaks a follow; one smooth glide, instant under reduced motion; scroll button when the latest content is out of view.
  • R22: the anchor algorithm lives in src/lib/conversation-scroll.ts; the container sets overflow-anchor: none.
  • R23: scroll state at most once per frame; registry in refs with a subscription; stable context value.
  • R24: ConversationDivider and ConversationNotice.
  • R5–R12: the shared component rules.

Constraints

  • No dependency on the message components: items are whatever the host renders.
  • Performance: the context value's identity does not change on scroll, so streaming and scrolling re-render only what changed.
  • stick keeps following within a small threshold of the bottom (the old ChatThread uses 32px, which is reasonable).
  • Compare settle against established assistant chat interfaces and note any difference in the PR.
  • Smooth scrolling is off under reduced motion.
  • The shared rules in Replace the chat components with a stateless Conversation family #94 apply: no new dependency or peer, no optional-peer import, token-only styling, no change to existing modules, additions only to src/index.ts and e2e/fixtures.tsx.

Done when

  • Unit tests cover:
    • Geometry: the settle target puts the item's top at the container top; reserved space is the viewport minus the item, never negative.
    • Anchor: content inserted above restores the same offset; when the anchor item is gone the next candidate restores its own; with no candidate left nothing moves.
    • Context: scrolling 100 frames re-renders a memoised child zero times.
  • Browser spec covers:
    • Settle: after send, the sent item's top is at the viewport top (±1px); scrolling up while text streams leaves scrollTop unchanged.
    • Stick: at the bottom, streaming keeps the end in view; scrolled up, nothing moves.
    • A reduced-motion run jumps instantly.
  • No serious or critical axe violation in the new stories, in light or dark.
  • bun run check, bun run build, bun run test:e2e and bun run dep-guard pass.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions