aria-live="polite"
aria-atomic="true">
```
### Screen Reader Behavior
1. **Toast Appears**: Screen reader announces title + message
2. **Toast Updates**: New content announced automatically
3. **Toast Dismisses**: Silent (user already informed)
### Keyboard Navigation
- **Close Button**: Focusable with `Tab`
- **Enter/Space**: Activate close button
- **ESC**: Closes parent modal (which may trigger toast)
### Reduced Motion
Users with motion sensitivity get simplified animations:
```css
@media (prefers-reduced-motion: reduce) {
.success-toast,
.error-toast,
.toast {
animation: none;
opacity: 1;
}
.toast-progress-bar {
animation: none;
}
}
```
**Effect:** Toast appears/disappears instantly without sliding/fading.
---
## Testing
### Automated Test
**File:** `tests/mjs/29-pdf-toast-notifications.test.mjs`
**Coverage:**
- ✅ Toast elements exist in DOM
- ✅ Toast initially hidden
- ✅ JavaScript functions available
- ✅ Manual toast trigger works
- ✅ Toast auto-hides after duration
- ✅ PDF modal integration (Scenario A: Stay in modal)
- ✅ PDF modal integration (Scenario B: Close modal early)
- ✅ CSS animations defined
- ✅ Icon/title/message updates
- ✅ Progress bar animation
**Run Test:**
```bash
bun tests/mjs/29-pdf-toast-notifications.test.mjs
```
### Manual Testing Checklist
**Scenario 1: Modal Overlay Only**
- [ ] Open PDF modal
- [ ] Select Default CV
- [ ] Click Download PDF
- [ ] Wait in modal without closing
- [ ] Verify overlay shows with spinner
- [ ] Verify modal closes after ~4 seconds
- [ ] Verify NO toast appears
**Scenario 2: Toast After Modal Close**
- [ ] Open PDF modal
- [ ] Select Extended CV (9 pages)
- [ ] Click Download PDF
- [ ] Immediately press ESC to close modal
- [ ] Verify toast appears bottom-right
- [ ] Verify icon is 📥
- [ ] Verify title says "Preparing PDF..."
- [ ] Verify message includes format name and time
- [ ] Verify progress bar animates (shrinks)
- [ ] Wait ~8 seconds
- [ ] Verify toast updates to ✅
- [ ] Verify title says "PDF Ready!"
- [ ] Verify toast auto-dismisses after ~3 seconds
**Scenario 3: Close Button**
- [ ] Trigger toast manually (browser console): `showPDFToast({icon: '🧪', title: 'Test', message: 'Test message'})`
- [ ] Click × close button
- [ ] Verify toast disappears immediately
**Scenario 4: Mobile Responsive**
- [ ] Resize browser to < 540px width
- [ ] Trigger toast
- [ ] Verify toast is full-width at bottom
- [ ] Verify content is readable
- [ ] Verify close button accessible
---
## Customization Guide
### Adding a New Toast Variant
**1. Define CSS Class** (`static/css/04-interactive/_toasts.css`):
```css
.custom-toast {
background: linear-gradient(135deg,
rgba(156, 39, 176, 0.95) 0%,
rgba(123, 31, 162, 0.95) 100%);
color: white;
border-left: 4px solid #fff;
}
```
**2. Create HTML Template** (`templates/partials/widgets/custom-toast.html`):
```html
{{define "custom-toast"}}
{{end}}
```
**3. Add JavaScript Function** (`static/js/main.js`):
```javascript
window.showCustomToast = function(options = {}) {
const toast = document.getElementById('custom-toast');
const icon = document.getElementById('custom-toast-icon');
const title = document.getElementById('custom-toast-title');
const message = document.getElementById('custom-toast-message');
if (options.icon) icon.textContent = options.icon;
if (options.title) title.textContent = options.title;
if (options.message) message.textContent = options.message;
toast.classList.remove('show');
void toast.offsetWidth;
toast.classList.add('show');
if (options.autoHide !== false) {
const duration = options.duration || 5000;
setTimeout(() => toast.classList.remove('show'), duration);
}
};
```
**4. Include in Index** (`templates/index.html`):
```html
{{template "custom-toast" .}}
```
### Changing Animation Duration
**CSS** (`_toasts.css`):
```css
/* Change lifecycle duration (default: 5s) */
.toast.show {
animation: toastLifecycle 8s ease forwards; /* Now 8 seconds */
}
/* Change progress bar duration */
.toast-progress-bar {
animation: progressShrink 8s linear forwards; /* Match lifecycle */
}
```
**JavaScript** (when calling function):
```javascript
window.showPDFToast({
icon: '📥',
title: 'Preparing...',
message: 'This will take longer',
duration: 10000 // 10 seconds
});
```
---
## Troubleshooting
### Toast Not Appearing
**Symptom:** Calling `showPDFToast()` has no effect.
**Checks:**
1. Verify toast element exists: `document.getElementById('pdf-toast')`
2. Check console for JavaScript errors
3. Verify CSS is loaded: Inspect element and check for `.success-toast` styles
4. Confirm `toasts.css` imported in `main.css`
5. Check `index.html` includes `{{template "pdf-toast" .}}`
**Solution:**
```bash
# Verify CSS import
grep "toasts.css" static/css/main.css
# Verify template inclusion
grep "pdf-toast" templates/index.html
# Check browser console
# Should see no errors when calling showPDFToast()
```
---
### Toast Not Auto-Dismissing
**Symptom:** Toast appears but never disappears.
**Checks:**
1. Verify `autoHide` is not set to `false`
2. Check CSS animation: `toastLifecycle` should be defined
3. Inspect element: `animation` property should be set
4. Check for `prefers-reduced-motion` (disables animations)
**Solution:**
```javascript
// Explicitly set autoHide
window.showPDFToast({
icon: '✅',
title: 'Test',
message: 'Should auto-hide',
duration: 3000,
autoHide: true // Explicitly enable
});
// Or manually hide
setTimeout(() => window.hidePDFToast(), 3000);
```
---
### Progress Bar Not Animating
**Symptom:** Progress bar appears but doesn't shrink.
**Checks:**
1. Verify `progressShrink` animation is defined in CSS
2. Check animation is applied: Inspect `#pdf-toast-progress`
3. Confirm `prefers-reduced-motion` is not active
4. Check `duration` parameter matches animation duration
**Solution:**
```javascript
// Ensure progress bar animation resets
const progressBar = document.getElementById('pdf-toast-progress');
if (progressBar) {
progressBar.style.animation = 'none';
void progressBar.offsetWidth; // Trigger reflow
progressBar.style.animation = 'progressShrink 5000ms linear forwards';
}
```
---
### Toast Overlaps Content on Mobile
**Symptom:** Toast covers important content on small screens.
**Checks:**
1. Verify responsive CSS is loaded
2. Check viewport width: `< 540px` should trigger mobile styles
3. Inspect `z-index` conflicts
**Solution:**
```css
/* Adjust mobile positioning */
@media (max-width: 540px) {
.toast {
bottom: 1rem; /* Lower if needed */
right: 1rem;
left: 1rem;
z-index: 10000; /* Ensure on top */
}
}
```
---
### Multiple Toasts Stacking
**Symptom:** Calling `showPDFToast()` multiple times creates overlapping toasts.
**Root Cause:** Current system uses single toast element, so multiple calls update the same toast.
**Expected Behavior:** Later calls replace earlier toast content.
**If You Need Multiple Toasts:**
1. Clone toast element before showing:
```javascript
function showMultipleToasts(options) {
const original = document.getElementById('pdf-toast');
const clone = original.cloneNode(true);
clone.id = `toast-${Date.now()}`;
document.body.appendChild(clone);
// Update clone content and show
// ... similar logic to showPDFToast ...
}
```
2. Or use a toast queue system (advanced).
---
## Related Documentation
- [2. Modern Web Techniques](2-MODERN-WEB-TECHNIQUES.md) - HTMX patterns and hypermedia architecture
- [12. CSS Architecture](12-CSS-ARCHITECTURE.md) - Modular CSS structure and ITCSS organization
- [3. API Reference](3-API.md) - Backend API endpoints including PDF export
- [11. PDF Export](11-PDF-EXPORT.md) - PDF generation with chromedp
---
**Last Updated**: 2025-11-20
**Version**: 1.0
**Status**: Production Ready
**Test Coverage**: 29-pdf-toast-notifications.test.mjs (22 assertions)