facebook / facebook/astryx

Define compact Toast queue and persistent-head policy

Open
#5,376 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
13.1k
Forks
1.1k
Avg merge
1d 14h
Merged PRs (30d)
669

Description

## Problem

A stack of up to five Toasts can cover too much content on a narrow viewport, which motivated automatically showing one Toast at a time below 640px. Review exposed a more serious lifecycle problem: if the visible Toast is persistent, it can hold the head of a FIFO queue indefinitely and prevent later feedback from being seen or announced.

Changing the compact default also changes behavior for every existing consumer, so it should not ship as an incidental responsive-layout fix.

## Why this is separate

#5353 now keeps the existing five-visible default and only demonstrates `maxVisible={1}` as an explicit consumer choice. Queueing affects ordering, timing, announcements, focus, deduplication, and persistent Toast behavior together; those decisions need an explicit contract before implementation.

## Decisions required

1. **Default policy:** Should Core ever change `maxVisible` automatically based on available width, or should products always opt in?
2. **Persistent head:** If the visible Toast does not auto-hide, should later Toasts wait, replace it, bypass it, or be summarized elsewhere?
3. **Ordering:** If queueing is supported, is FIFO always correct, or do errors/actions need priority?
4. **Timer start:** Should auto-hide begin at dispatch or only when a queued Toast becomes visible?
5. **Announcement timing:** Should assistive technology hear a Toast when dispatched or when it becomes visually visible? A hidden queued Toast must not create misleading visual/auditory ordering.
6. **Deduplication:** How should `uniqueID` overwrite/ignore behave for visible versus queued Toasts?
7. **Focus:** What receives focus after a focused Toast dismisses if the next item is queued?
8. **Bounded growth:** What happens when producers create Toasts faster than users can dismiss a persistent visible Toast?

## Constraints

- Preserve the existing `maxVisible` API and five-visible default until this policy is decided.
- Do not infer persistence from `endContent`; callers must set `isAutoHide: false` explicitly.
- Keep viewport width, pointer precision, hover, and touch capability independent. A narrow fine-pointer window is not automatically a touch device.
- Avoid announcing hidden queued content out of visual order.
- Retain visible close, F6 keyboard access, Escape/layer behavior, and imperative dismissal.
- Evaluate against WCAG 2.2 Level AA, especially timing behavior under SC 2.2.1.

## Evidence needed before implementation

- scenarios covering five rapid transient Toasts, a persistent Toast followed by transient Toasts, error/action priority, uniqueID overwrite/ignore, and focused dismissal;
- compact and wide viewport tests with explicit expected ordering;
- screen-reader announcement ordering evidence;
- a bounded policy proving the queue cannot grow or remain blocked indefinitely;
- Storybook examples that distinguish the default stack from any explicit queue mode.

## Related work

- #5353 — responsive layout, safe areas, wrapping, spacing, motion, and live-region cleanup without lifecycle changes
- #5375 — swipe dismissal with native page-scroll handoff
- Review context: Cindy’s review on #5353 identified the persistent-head starvation case and asked for each runtime behavior change to state the problem it solves.

Contributor guide

Open the contributing guide

Research direction

Review #5353 and #5375 first to understand the existing maxVisible behavior and related Toast lifecycle constraints. Define the policy decisions listed here, then document scenarios and expected ordering for rapid transient Toasts, persistent heads, deduplication, focus, announcements, and bounded growth; done includes compact/wide viewport tests and Storybook examples.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
accessibility, design, frontend, testing
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.