feat(toast): add accessible toast system#82
Open
joshsadam wants to merge 15 commits into
Open
Conversation
joshsadam
force-pushed
the
feat/pathogen-toast-notifications
branch
from
19bce34 to
5fc9a48
Compare
Add reusable Toaster and Toast components with WCAG-focused live region behavior, including assertive error announcements and keyboard-friendly dismiss handling. This also adds Lookbook previews, locale strings, and controller/component tests. Preview scenarios now run in container-anchored mode to prevent stacking collisions and cross-scenario persistence in Lookbook.
Derive a stable id for the turbo-permanent toaster host so Turbo can preserve it across visits. Restore focus when dismissing via the close button, and route announcements through dedicated polite and assertive regions so errors are not double-announced and simultaneous messages are not dropped.
Custom 32x32 SVG paths rendered squashed in the flex layout, and the error X was off-centre. Use Heroicons 16px solid paths with a square size-4 container.
Remove the decorative accent bar, use control-scale type tokens, quiet info icons, Pathogen::Button dismiss, and opacity-only exit motion so toasts match Pathogen overlay and quiet-status patterns.
Document overlay surface, status colours, dismiss control, and motion rules so toast work stays aligned with Pathogen foundations.
Use the shared max-w-4xl section structure, framed demo panels, reference tables, and usage footers used by tabs and typography previews.
px-3 py-2 made horizontal inset 4px wider than vertical. Use p-3 on the content row and drop the icon nudge.
Shrink-wrap corner hosts with w-max so bottom-4 and right-4 apply evenly. Reserve w-full and horizontal padding for centered positions only.
joshsadam
force-pushed
the
feat/pathogen-toast-notifications
branch
from
9f1890d to
a6f4188
Compare
…proved dismissible button positioning
…mproved dismissible button positioning
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new Pathogen::Toast + Pathogen::Toaster system (Ruby ViewComponents + Stimulus controllers) designed for accessible, WCAG-aligned toast notifications, including Lookbook previews, localization strings, and automated tests.
Changes:
- Introduces
Toast/ToasterViewComponents with dedicated polite/assertive live regions and stacking behavior. - Adds Stimulus controllers to manage dismissal, focus restoration, announcements, and stack collapsing/expanding.
- Ships Lookbook previews, locale keys (en/fr), importmap pins, and component/controller tests.
Reviewed changes
Copilot reviewed 23 out of 23 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| test/javascript/controllers/toaster_controller.test.js | Adds Vitest coverage for stacking/overflow and live-region announcement batching. |
| test/javascript/controllers/toast_controller.test.js | Adds Vitest coverage for auto-dismiss, focus pause/resume, Escape dismiss, and announcement payloads. |
| test/components/previews/pathogen/toast_preview/turbo_stream_simulation.html.erb | Lookbook preview simulating Turbo Stream appends/updates into a toaster list. |
| test/components/previews/pathogen/toast_preview/stacking_and_accessibility.html.erb | Lookbook preview demonstrating stacking behavior and live-region rationale. |
| test/components/previews/pathogen/toast_preview/positions.html.erb | Lookbook preview for toaster anchor positions. |
| test/components/previews/pathogen/toast_preview/playground.html.erb | Param-driven Lookbook playground for type/timeout/dismissible/position. |
| test/components/previews/pathogen/toast_preview/overview.html.erb | Lookbook overview showing typical toast variants. |
| test/components/previews/pathogen/toast_preview.rb | Registers Lookbook preview actions and parameters. |
| test/components/pathogen/toaster_test.rb | ViewComponent tests for toaster structure, positioning, permanence, and axe checks. |
| test/components/pathogen/toast_test.rb | ViewComponent tests for toast rendering, normalization, i18n, styling, and axe checks. |
| lib/pathogen/view_helper.rb | Exposes toast/toaster helpers in PATHOGEN_COMPONENT_HELPERS. |
| docs/lookbook/design_system/01-design-contract.md.erb | Documents toast design/behavior expectations in the design contract. |
| config/locales/fr.yml | Adds French toast strings (labels + type names). |
| config/locales/en.yml | Adds English toast strings (labels + type names). |
| config/importmap.rb | Pins toast/toaster Stimulus controllers for importmap usage. |
| app/components/pathogen/toaster.rb | Implements toaster component API, positioning/strategy mappings, and system args. |
| app/components/pathogen/toaster.html.erb | Renders toast list plus polite/assertive SR-only live regions. |
| app/components/pathogen/toast.rb | Implements toast API (type normalization, timeout rules, icon label/color) and data attrs. |
| app/components/pathogen/toast.html.erb | Renders toast UI including SR-only type prefix and dismiss button. |
| app/assets/stylesheets/pathogen_view_components.css | Updates compiled Tailwind output to include toast/toaster utilities. |
| app/assets/javascripts/pathogen_view_components/toaster_controller.js | Implements stack collapsing/expanding and queued live-region announcements. |
| app/assets/javascripts/pathogen_view_components/toast_controller.js | Implements timer lifecycle, dismiss behavior, focus restoration, and announce events. |
| app/assets/javascripts/pathogen_view_components.js | Registers and exports the new Stimulus controllers. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Debounce rapid live-region writes and skip clearing on first announcement so NVDA no longer speaks "blank". Use Stimulus dispatch for toast events, keep persistent errors visible when the stack collapses, and let pointer-events pass through the toaster host.
Use Pathogen typography helpers and token-based Tailwind classes in Lookbook toast previews so examples match the design system surface and type scale.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What does this PR do and why?
ToastandToastercomponents with WCAG-focused live region behavior (assertive error announcements, keyboard-friendly dismiss).Screenshots or screen recordings
Accessible at 400% Zoom
NVDA Screen-reader Support
How to set up and validate locally
Pathogen::Toastpreviews to verify positions, stacking, and dismiss behavior.bin/rails test test/components/pathogen/toast_test.rb test/components/pathogen/toaster_test.rb.PR acceptance checklist
This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.