FRD: Inbox Preview Panel

Document Summary

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

---

Introduction

Overview

Inbox Preview Panel is a messaging widget that renders a compact list of inbox threads showing sender, subject snippet, timestamp, and unread count. It builds on the existing InboxThreadList pattern component, elevating it into a self-contained panel widget with header, unread badge, and integration-ready callbacks. The widget is designed for SaaS sidebar panels, notification centers, and messaging overviews.

Goals

• Deliver an <InboxPreviewPanel> component that wraps InboxThreadList with a panel header, unread count badge, and thread-selection callback.
• Display sender name/avatar, subject or snippet, timestamp, and unread indicator per thread.
• Support loading, empty, and error states.
• Ship Storybook stories with realistic inbox data.

Non-Goals

• Full email client functionality (compose, forward, archive, search).
• Message body rendering (this is a preview list, not a reader pane).
• Real-time sync or push notification integration.
• Pagination or infinite scroll (deferred to future enhancement).

---

Scope

In Scope

Area	Description
Component	<InboxPreviewPanel> wrapping InboxThreadList with panel chrome
Panel Header	Title, total unread count badge, optional action button (e.g., “Mark all read”)
Thread Items	Sender avatar, sender name, snippet, timestamp, unread dot
Selection	onThreadSelect callback when a thread is clicked
States	Loading skeleton, empty inbox, error state
Stories	Storybook stories for populated inbox, empty inbox, loading, error, and themed variants

Out of Scope

Area	Reason
Message body / reader pane	Separate component; this is a preview list only
Compose / reply	Handled by Compose Panel widget (#53)
Thread actions (archive, delete, star)	Future enhancement; initial version is read + select
Search / filter	Future enhancement
Pagination / infinite scroll	Future enhancement

---

Users and Pain Points

User Groups

User	Description	Needs
Developers	Engineers building SaaS messaging features	A ready-made inbox preview using DS components
Designers	Design-system consumers	Consistent inbox UX aligned with DS tokens
End Users	SaaS application users	Quick scan of recent messages with clear unread indicators

Pain Points

User	Pain Point	Impact
Developers	Building inbox previews requires assembling avatar, text truncation, timestamp formatting, and unread indicators from scratch	Slow development, inconsistent results
End Users	Inconsistent inbox UIs across SaaS apps make it hard to quickly identify unread messages	Missed messages, poor UX

---

Definitions

Term	Definition
Inbox Thread	A conversation thread in the inbox, represented by its most recent message
Snippet	A truncated preview of the most recent message text
Unread Count	The total number of threads with unread messages
Preview Panel	A compact panel showing a list of thread summaries

---

Current State

Existing Behavior

InboxThreadList in src/components/patterns/inbox-thread-list.tsx renders a list of inbox threads. It exists as a pattern component with stories but is not wrapped in a panel with header, unread count, or standardized callbacks.

Current Limitations

• InboxThreadList is a raw list without panel chrome (header, badge, actions).
• No standardized empty, loading, or error state handling at the panel level.
• No unread count badge aggregation.

Existing Workarounds

• Developers wrap InboxThreadList in custom panel containers and add their own headers and badges.

---

Proposed Solution

Summary

Introduce <InboxPreviewPanel> that wraps InboxThreadList with a panel header containing a title, unread count badge, and optional action slot. The component accepts a threads array, renders them via the existing list pattern, and calls onThreadSelect when a thread is clicked.

Key Capabilities

• Panel header with title and unread count badge.
• Optional header action (e.g., “Mark all read” button).
• Thread list rendering via InboxThreadList composition.
• Thread selection callback.
• Empty inbox state with configurable message.
• Loading skeleton matching thread item shapes.
• Error state with retry.

User Experience

Users see a panel with a header showing “Inbox” and an unread count badge (e.g., “3”). Below is a scrollable list of thread previews. Each thread shows a sender avatar, name, message snippet (truncated), and relative timestamp. Unread threads have a dot indicator and bolder text. Clicking a thread fires the selection callback.

Developer Experience

<InboxPreviewPanel
  title="Inbox"
  threads={threads}
  onThreadSelect={(threadId) => openThread(threadId)}
  onMarkAllRead={() => markAllRead()}
/>

---

Requirements

ID	Requirement	Priority	Notes
FR-001	InboxPreviewPanel renders a panel header with title and unread badge	Must	-
FR-002	Thread list renders sender, snippet, timestamp, and unread indicator	Must	Delegates to InboxThreadList
FR-003	onThreadSelect fires when a thread item is clicked	Must	-
FR-004	Optional “Mark all read” action in header	Should	-
FR-005	Loading, empty, and error states are handled	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	threads prop accepts InboxThread[] with id, senderName, senderAvatar, snippet, timestamp, and isUnread fields	Typed thread data structure	Must
FUNC-002	Unread count badge in header auto-calculates from threads.filter(t => t.isUnread).length	No manual count management	Must
FUNC-003	Thread items show sender avatar (via Avatar), sender name, truncated snippet, and relative timestamp	Familiar inbox layout	Must
FUNC-004	Unread threads display a dot indicator and bolder sender name	Quick visual identification	Must
FUNC-005	Clicking a thread fires onThreadSelect(threadId)	Navigation to thread detail	Must
FUNC-006	Header action slot accepts a button (e.g., “Mark all read”) with onClick	Batch actions	Should
FUNC-007	Empty state shows configurable message when threads is empty and not loading	Clear feedback	Must
FUNC-008	Loading skeleton renders 3-5 placeholder thread items	Smooth loading transition	Must

---

Non-Functional Requirements

ID	Requirement	Category	Priority
NFR-001	Renders in under 30ms for up to 50 threads	Performance	Must
NFR-002	Thread items are keyboard-navigable with arrow keys	Accessibility	Must
NFR-003	Works in light and dark themes	Theming	Must
NFR-004	No new runtime dependencies	Maintainability	Must

---

API / Interface Requirements

Public API

Name	Type	Description	Required
title	string	Panel header title	No (default: “Inbox”)
threads	InboxPreviewThread[]	Array of thread summaries	Yes
onThreadSelect	(threadId: string) => void	Thread click callback	Yes
onMarkAllRead	() => void	Mark-all-read action callback	No
isLoading	boolean	Show loading skeleton	No
error	string	Error message	No
onRetry	() => void	Retry callback	No
emptyMessage	string	Text for empty state	No
className	string	Additional CSS classes	No

InboxPreviewThread Type

interface InboxPreviewThread {
  id: string;
  senderName: string;
  senderAvatar?: string;
  snippet: string;
  timestamp: string;
  isUnread: boolean;
}

Example Usage

import { InboxPreviewPanel } from "@/components/ui/inbox-preview-panel";

<InboxPreviewPanel
  threads={[
    { id: "1", senderName: "Alice Chen", snippet: "Hey, can we sync on the Q3 roadmap?", timestamp: "2m ago", isUnread: true },
    { id: "2", senderName: "Bob Smith", snippet: "Updated the design spec with your feedback", timestamp: "1h ago", isUnread: false },
  ]}
  onThreadSelect={(id) => navigate(`/inbox/${id}`)}
  onMarkAllRead={() => api.markAllRead()}
/>

API Notes

• Reuses concepts from existing InboxThreadList but with a simplified, widget-focused API.
• Snippet truncation happens internally (max ~80 characters with ellipsis).
• Timestamp is a pre-formatted string; the consumer handles relative time formatting.

---

Accessibility Requirements

ID	Requirement	Notes
A11Y-001	Thread list has role="listbox" with aria-label describing the inbox	-
A11Y-002	Each thread item is role="option" and focusable	Arrow key navigation
A11Y-003	Unread status is conveyed to screen readers	aria-label includes “unread” for unread threads
A11Y-004	Unread count badge has aria-label (e.g., “3 unread messages”)	Not just visual number
A11Y-005	Mark-all-read button has descriptive label	-

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 populated inbox, empty inbox, loading, and error states	Storybook	Must
DOC-004	Story demonstrating keyboard navigation	Storybook	Should

---

Dependencies

Dependency	Type	Owner	Status	Notes
InboxThreadList	Engineering	Design System	Ready	Existing pattern component
Avatar	Engineering	Design System	Ready	Sender avatars
Badge	Engineering	Design System	Ready	Unread count badge
Button	Engineering	Design System	Ready	Header action
Design tokens	Design	Design System	Ready	-

---

Risks and Tradeoffs

Risk / Tradeoff	Impact	Mitigation
No pagination may not scale for users with large inboxes	Performance and usability	Document as a limitation; pagination is a planned follow-up
Simplified API compared to InboxThreadList may not cover all use cases	Power users may need the raw component	Export both; InboxPreviewPanel is the opinionated widget, InboxThreadList remains available
Pre-formatted timestamp string puts formatting burden on consumer	Inconsistent time display	Document recommended time formatting utility

---

Open Questions

ID	Question	Owner	Status	Resolution
Q-001	Should the panel support thread grouping (Today, Yesterday, Older)?	David Holmes	Open	—
Q-002	Should swipe-to-archive be supported on touch devices?	David Holmes	Open	—
Q-003	Should the panel support a compact mode with less padding?	David Holmes	Open	—

---

Acceptance Criteria

ID	Criteria	Related Requirement
AC-001	Panel header shows title and unread count badge	FR-001, FUNC-002
AC-002	Thread items display sender avatar, name, snippet, timestamp, and unread dot	FR-002, FUNC-003, FUNC-004
AC-003	Clicking a thread fires onThreadSelect with the thread ID	FR-003, FUNC-005
AC-004	Mark-all-read button renders and fires callback when provided	FR-004, FUNC-006
AC-005	Empty state displays when threads is empty and not loading	FUNC-007
AC-006	Loading skeleton displays placeholder thread items	FUNC-008
AC-007	All Storybook stories render without errors	DOC-003
AC-008	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 InboxThreadList (or its internal patterns) for the thread list rendering.
• Use Avatar for sender avatars, Badge for unread count, Button for actions.
• Auto-calculate unread count from the threads array.
• Place stories under the SaaS Widgets Storybook section.

LLM Should Not

• Build a full email client.
• Add pagination or infinite scroll.
• Add search or filter functionality.
• Modify existing InboxThreadList component.

---

Decision Log

Date	Decision	Reason	Owner
2026-05-26	Wrap InboxThreadList rather than rebuild from scratch	Reuses existing pattern; avoids duplication	David Holmes
2026-05-26	Consumer provides pre-formatted timestamp strings	Avoids opinionated date-formatting dependency	David Holmes

---

Document History

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