FRD: Chat Thread Widget

Document Summary

Field	Details
Feature Name	Chat Thread Widget
Status	Draft
Owner	David Holmes
Contributors	Design, Engineering
Target Release	v2.0.0 (P2)
Related Links	Roadmap item #51
Last Updated	2026-05-26

---

Introduction

Overview

Chat Thread Widget is a self-contained messaging component that composes ChatBubble, Avatar, TextArea, and Button into a complete conversation thread with send, reply, and reaction UX. It provides a ready-to-use messaging surface for SaaS applications that need in-app chat, support threads, or comment-style conversations. The existing chat-bubble.tsx handles individual message rendering; this widget adds the thread container, input area, message list, and interaction layer.

Goals

• Deliver a <ChatThread> component that renders a scrollable message list with a compose input area.
• Compose existing ChatBubble, Avatar, TextArea, and Button primitives.
• Support send, reply, and emoji reaction interactions.
• Handle empty, loading, and error states with appropriate UX.
• Ship Storybook stories covering typical chat flows and edge cases.

Non-Goals

• Real-time message delivery (WebSocket, SSE, or polling integration).
• File or image attachment uploads.
• Message search or filtering.
• Typing indicators or read receipts beyond ChatBubble’s existing status prop.
• End-to-end encryption or message persistence.

---

Scope

In Scope

Area	Description
Component	<ChatThread> composing message list + input area
Message List	Scrollable container rendering ChatBubble instances with avatars
Compose Input	TextArea + Button for sending new messages
Reply	Reply-to-message UX showing quoted original message above compose input
Reactions	Emoji reaction picker on individual messages
States	Empty thread, loading messages, error loading, send failure
Stories	Storybook stories for conversations, replies, reactions, and all states

Out of Scope

Area	Reason
Real-time sync	Application-layer concern; widget calls onSend callback
File attachments	Separate feature; compose area handles text only
Message threading (nested replies)	Flat thread only; nested threading is a separate pattern
User presence / online indicators	Application-layer concern

---

Users and Pain Points

User Groups

User	Description	Needs
Developers	Engineers building SaaS apps with in-app messaging	A composable chat widget using DS primitives
Designers	Design-system consumers	Consistent chat UI that matches DS visual language
End Users	SaaS application users	Familiar, responsive messaging experience

Pain Points

User	Pain Point	Impact
Developers	Assembling chat UIs from primitives (bubble, input, scroll, reactions) is complex	High development cost, inconsistent chat experiences
End Users	Ad-hoc chat UIs often lack keyboard navigation, screen reader support, and proper focus management	Poor accessibility and usability

---

Definitions

Term	Definition
Chat Thread	A chronological, flat list of messages between participants
Compose Input	The text input area at the bottom of the thread for writing new messages
Reply	A message that quotes and references a previous message in the thread
Reaction	An emoji response attached to a specific message

---

Current State

Existing Behavior

ChatBubble in chat-bubble.tsx renders individual sent/received messages with avatar, timestamp, and delivery status. There is no thread container, compose input, reply UX, or reaction system.

Current Limitations

• No thread-level component; consumers must build scroll containers and input areas manually.
• No reply-to-message pattern.
• No emoji reaction support.
• No empty/loading/error states for the thread as a whole.

Existing Workarounds

• Developers wrap ChatBubble instances in a custom scrollable div and add their own textarea.
• Reply and reaction UX are built from scratch in each application.

---

Proposed Solution

Summary

Introduce <ChatThread> that accepts a messages array and renders them as ChatBubble components in a scrollable container, with a compose input area at the bottom. The component supports onSend for new messages, onReply for reply-to interactions, and onReact for emoji reactions. State management (adding messages to the array) is the consumer’s responsibility.

Key Capabilities

• Scrollable message list with auto-scroll to newest message.
• Compose input with send button (Enter to send, Shift+Enter for newline).
• Reply mode: clicking reply on a message shows the quoted message above the compose input.
• Emoji reaction: clicking a reaction button on a message opens a picker; selected emoji is added to the message.
• Empty thread: shows a placeholder message encouraging the first message.
• Loading state: skeleton bubbles while messages load.
• Error state: error banner with retry action.

User Experience

Users see a scrolling list of messages with sent messages on the right and received on the left. Each message has a subtle reaction button and reply button on hover. The compose area at the bottom has a textarea and send button. When replying, a quoted preview of the original message appears above the textarea.

Developer Experience

<ChatThread
  messages={messages}
  currentUserId="user-1"
  onSend={(text) => sendMessage(text)}
  onReply={(text, replyToId) => sendReply(text, replyToId)}
  onReact={(messageId, emoji) => addReaction(messageId, emoji)}
/>

---

Requirements

ID	Requirement	Priority	Notes
FR-001	ChatThread renders a scrollable list of ChatBubble messages	Must	-
FR-002	Compose input at the bottom sends messages via onSend	Must	-
FR-003	Reply-to interaction shows quoted message and sends via onReply	Should	-
FR-004	Emoji reaction on messages fires onReact	Should	-
FR-005	Empty, loading, and error states are handled	Must	-
FR-006	Auto-scroll to newest message on new message arrival	Must	-

Priority Definitions

Priority	Meaning
Must	Required for this feature to ship.
Should	Important, but can be deferred if needed.
Could	Nice to have. Not required for initial release.

---

Functional Requirements

ID	Requirement	User Benefit	Priority
FUNC-001	messages prop accepts ChatMessage[] with id, text, senderId, timestamp, reactions, and replyTo fields	Comprehensive message model	Must
FUNC-002	Messages from currentUserId render as “sent” (right-aligned); others as “received” (left-aligned)	Familiar chat layout	Must
FUNC-003	Enter key sends the current message; Shift+Enter inserts a newline	Standard chat keyboard behavior	Must
FUNC-004	Send button is disabled when textarea is empty or whitespace-only	Prevents empty sends	Must
FUNC-005	Clicking reply on a message enters reply mode with quoted preview	Threaded conversation context	Should
FUNC-006	Escape key exits reply mode	Quick escape from reply	Should
FUNC-007	Reaction button on each message opens an emoji picker	Express reactions without typing	Should
FUNC-008	Existing reactions on a message display as small badges below the bubble	Visible social signals	Should
FUNC-009	Auto-scroll to bottom when a new message is added to messages	Users see latest messages	Must
FUNC-010	Error state shows a banner with optional retry button	Recoverable error handling	Must

---

Non-Functional Requirements

ID	Requirement	Category	Priority
NFR-001	Renders in under 100ms for threads with up to 200 messages	Performance	Must
NFR-002	All interactive elements are keyboard-navigable	Accessibility	Must
NFR-003	Works in light and dark themes	Theming	Must
NFR-004	No new runtime dependencies beyond existing DS components	Maintainability	Must
NFR-005	Compose input maintains focus after sending a message	Usability	Must

---

API / Interface Requirements

Public API

Name	Type	Description	Required
messages	ChatMessage[]	Array of messages to display	Yes
currentUserId	string	ID of the current user (determines sent vs. received)	Yes
onSend	(text: string) => void	Callback when a new message is sent	Yes
onReply	(text: string, replyToId: string) => void	Callback when replying to a message	No
onReact	(messageId: string, emoji: string) => void	Callback when adding a reaction	No
isLoading	boolean	Show loading skeleton	No
error	string	Error message to display	No
onRetry	() => void	Retry callback for error state	No
placeholder	string	Compose textarea placeholder text	No
emptyMessage	string	Text shown when thread has no messages	No
className	string	Additional CSS classes	No

ChatMessage Type

interface ChatMessageReaction {
  emoji: string;
  count: number;
  userReacted: boolean;
}

interface ChatMessage {
  id: string;
  text: string;
  senderId: string;
  senderName: string;
  senderAvatar?: string;
  timestamp: string;
  status?: "sending" | "sent" | "delivered" | "read" | "failed";
  reactions?: ChatMessageReaction[];
  replyTo?: { id: string; text: string; senderName: string };
}

Example Usage

import { ChatThread } from "@/components/ui/chat-thread";

<ChatThread
  messages={[
    { id: "1", text: "Hey, how's the project going?", senderId: "user-2", senderName: "Alice", timestamp: "10:30 AM" },
    { id: "2", text: "Going well! Just finishing the design review.", senderId: "user-1", senderName: "Bob", timestamp: "10:32 AM", status: "read" },
  ]}
  currentUserId="user-1"
  onSend={(text) => console.log("Send:", text)}
/>

API Notes

• messages should be sorted chronologically by the consumer.
• ChatBubble is used internally; its props are derived from ChatMessage.
• Reaction emoji picker uses a small predefined set (thumbs up, heart, laugh, surprised, sad, fire) rather than a full emoji keyboard.

---

Accessibility Requirements

ID	Requirement	Notes
A11Y-001	Message list has role="log" with aria-live="polite" for new messages	New messages announced without interrupting current task
A11Y-002	Each message is a focusable region with aria-label including sender and timestamp	Keyboard navigation through messages
A11Y-003	Compose textarea has a descriptive aria-label	”Type a message” or custom placeholder
A11Y-004	Reply and reaction buttons have descriptive aria-label including message context	e.g., “Reply to Alice’s message”
A11Y-005	Reply preview is announced to screen readers when entering reply mode	Focus moves to textarea with context
A11Y-006	Emoji reaction picker is keyboard-navigable	Arrow keys to select, Enter to confirm, Escape to close

Checklist

• Keyboard support is defined.
• Focus behavior is defined.
• Screen reader behavior is defined.
• Color contrast requirements are met.
• Reduced motion behavior is considered.
• Semantic HTML expectations are documented.
• ARIA usage is defined only where needed.

---

Content and Documentation Requirements

ID	Requirement	Location	Priority
DOC-001	Storybook docs page with overview and props table	Storybook	Must
DOC-002	”When to use / When not to use” guidance	Storybook docs	Must
DOC-003	Stories for basic conversation, reply flow, reactions, and all states	Storybook	Must
DOC-004	Story demonstrating keyboard navigation through thread	Storybook	Should

---

Dependencies

Dependency	Type	Owner	Status	Notes
ChatBubble	Engineering	Design System	Ready	Individual message rendering
Avatar	Engineering	Design System	Ready	Sender avatars
TextArea	Engineering	Design System	Ready	Compose input
Button	Engineering	Design System	Ready	Send, reply, reaction buttons
Badge	Engineering	Design System	Ready	Reaction display badges
Design tokens	Design	Design System	Ready	-

---

Risks and Tradeoffs

Risk / Tradeoff	Impact	Mitigation
Flat thread only; no nested replies	Users expecting Discord/Slack-style threading will not find it here	Document as intentional; nested threading is a separate widget
Predefined emoji set rather than full emoji keyboard	Limited reaction expression	Keep the set small and useful; full keyboard can be a future enhancement
No file attachments in compose	Limited for support-chat use cases	Document text-only scope; file attachments are a separate feature
Large threads (200+ messages) may scroll slowly	Performance concern	Implement virtual scrolling if performance testing shows degradation

---

Open Questions

ID	Question	Owner	Status	Resolution
Q-001	Should message grouping (consecutive messages from same sender) collapse avatars?	David Holmes	Open	—
Q-002	Should the compose area support markdown formatting?	David Holmes	Open	—
Q-003	Should the emoji reaction set be configurable?	David Holmes	Open	—
Q-004	Should virtual scrolling be included in v1 for large threads?	David Holmes	Open	—

---

Acceptance Criteria

ID	Criteria	Related Requirement
AC-001	Messages render as ChatBubbles with correct sent/received alignment	FR-001, FUNC-002
AC-002	Typing text and pressing Enter sends via onSend	FR-002, FUNC-003
AC-003	Shift+Enter inserts a newline without sending	FUNC-003
AC-004	Reply mode shows quoted message and sends via onReply	FR-003, FUNC-005
AC-005	Emoji reaction picker opens and fires onReact	FR-004, FUNC-007
AC-006	Empty thread shows placeholder message	FR-005
AC-007	Loading state shows skeleton bubbles	FR-005
AC-008	Error state shows error banner with retry	FUNC-010
AC-009	Thread auto-scrolls to bottom on new message	FR-006
AC-010	All Storybook stories render without errors	DOC-003
AC-011	Component passes axe accessibility audit	NFR-002

---

LLM Handoff Instructions

Expected LLM Behavior

• Follow the requirements and acceptance criteria in this document.
• Do not expand scope beyond the In Scope section.
• Respect the Out of Scope section.
• Compose ChatBubble for each message; do not reimplement bubble rendering.
• Use Avatar for sender avatars, TextArea for compose input, Button for send/reply/reaction triggers.
• Use Badge for reaction display.
• Implement a small predefined emoji set (6 emojis) for the reaction picker.
• Use role="log" with aria-live="polite" on the message list.
• Place stories under the SaaS Widgets Storybook section.

LLM Should Not

• Implement WebSocket or real-time sync.
• Add file upload or attachment support.
• Build nested threading.
• Add a full emoji keyboard.
• Modify existing ChatBubble or Avatar components.

---

Decision Log

Date	Decision	Reason	Owner
2026-05-26	Flat thread only, no nested replies	Keeps complexity manageable; nested threading is architecturally different	David Holmes
2026-05-26	Predefined 6-emoji reaction set	Avoids full emoji keyboard dependency; covers common reactions	David Holmes
2026-05-26	Consumer manages message array state	Widget is a controlled component; no internal state management for messages	David Holmes

---

Document History

Date	Author	Change
2026-05-26	David Holmes	Initial draft