feat(ui): store-backed Toast with a real queue

docs/06 §4 specifies a Toast (queue, auto-dismiss 4s, ARIA status) and §3.4
needs one for the Settings auto-save. All that existed was an inline
<p role="status"> in #export that never dismissed -- and that assigned error
strings to the same variable its CSS painted var(--success), so a failed
export reported itself in success-green. That is fixed here.

The store owns the timers rather than the component, because <Toast> mounts
once at the App root while the route chain below it unmounts on every
navigation. Component-owned timers would leak by construction.

Two queue rules exist for specific races, and both are pinned by tests:
timeouts are keyed by item id and re-check the head before shifting, so a user
dismiss racing a timer cannot double-shift and flash the next toast for a
frame; and a repeat of the visible message restarts its timer instead of
queueing a twin, because one debounced save resolves one promise that may have
several subscribers.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5 committed 2026-07-26 12:43:33 +07:00
1 parent 85f134c6e8
commit 93cf6b87fe
5 files changed
+264 -12

No files matched your search

+5
View File
@@ -4,6 +4,7 @@
import ExportTab from '@/lib/components/ExportTab.svelte';
import ImportTab from '@/lib/components/ImportTab.svelte';
import TabBar from '@/lib/components/TabBar.svelte';
import Toast from '@/lib/components/Toast.svelte';
import { t } from '@/lib/i18n/index.svelte';
import { isWriting } from '@/lib/stores/import-session.svelte';
import { getRoute, navigate, startRouting } from '@/lib/stores/route.svelte';
@@ -56,6 +57,10 @@
</nav>
</footer>
<!-- Mounted once, outside <main>, so the route chain below cannot unmount it
mid-dismiss and strand a timer (docs/06 §4). -->
<Toast />
<style>
header,
footer {
+5 -12
View File
@@ -8,6 +8,7 @@
import { countSelected, FORMAT_META, runExport } from '../export/run-export';
import { num, t } from '../i18n/index.svelte';
import { getSettings } from '../stores/settings.svelte';
import { pushToast } from '../stores/toast.svelte';
import Button from './Button.svelte';
import Callout from './Callout.svelte';
import FolderPickTree from './FolderPickTree.svelte';
@@ -17,7 +18,6 @@
let selection = $state<ReadonlySet<string> | undefined>(undefined);
let format = $state<ExportFormat>('netscape-html');
let loadError = $state<string | undefined>();
let toast = $state<string | undefined>();
let csvDelimiter = $state<CsvDelimiter>(',');
let markdownStyle = $state<MarkdownStyle>('nested');
@@ -55,9 +55,11 @@
markdownStyle,
now: new Date(),
});
toast = t('export.saved', { name: result.filename });
pushToast(t('export.saved', { name: result.filename }), 'success');
} catch (err) {
toast = err instanceof BmBrowserError ? err.detail : t('errors.UNKNOWN');
// Tone matters: this used to share a variable with the success message
// and rendered failures in success-green.
pushToast(err instanceof BmBrowserError ? err.detail : t('errors.UNKNOWN'), 'danger');
}
})();
}
@@ -112,9 +114,6 @@
{t('export.start', { n: num(bookmarkCount) })}
</Button>
{#if toast !== undefined}
<p class="toast" role="status">{toast}</p>
{/if}
</section>
</div>
{/if}
@@ -155,10 +154,4 @@
background: var(--bg);
color: var(--fg);
}
.toast {
margin: 0;
font-size: var(--fs-1);
color: var(--success);
}
</style>
+57
View File
@@ -0,0 +1,57 @@
<script lang="ts">
import { t } from '../i18n/index.svelte';
import { dismissToast, getVisibleToast } from '../stores/toast.svelte';
const toast = $derived(getVisibleToast());
</script>
{#if toast !== undefined}
<!-- role follows Callout's convention: an error interrupts, a status waits. -->
<div class="toast {toast.tone}" role={toast.tone === 'danger' ? 'alert' : 'status'}>
<span>{toast.message}</span>
<button aria-label={t('common.cancel')} onclick={() => dismissToast(toast.id)}>✕</button>
</div>
{/if}
<style>
.toast {
position: fixed;
right: var(--sp-4);
bottom: var(--sp-4);
z-index: 10;
display: flex;
align-items: center;
gap: var(--sp-3);
max-width: 44ch;
padding: var(--sp-2) var(--sp-3);
border: 1px solid var(--border);
border-left: 3px solid var(--fg-muted);
border-radius: var(--radius-sm);
background: var(--bg-raised);
color: var(--fg);
font-size: var(--fs-1);
box-shadow: 0 4px 16px rgb(0 0 0 / 0.18);
}
.success {
border-left-color: var(--success);
}
.danger {
border-left-color: var(--danger);
}
button {
font: inherit;
flex-shrink: 0;
padding: 0;
border: none;
background: none;
color: var(--fg-muted);
cursor: pointer;
}
button:hover {
color: var(--fg);
}
</style>
+91
View File
@@ -0,0 +1,91 @@
/**
* Transient status messages — docs/06 §4 (queue, auto-dismiss 4 s, ARIA status).
*
* Purpose: one place that owns toast state AND its timers.
* Inputs: `pushToast` calls from anywhere in the Manager.
* Guarantees: exactly one toast is visible at a time; a timer can only ever
* dismiss the item that started it; nothing here touches the DOM, so a fired
* timer is harmless even when no `<Toast>` is rendered.
*
* The store owns the timers rather than the component because `<Toast>` mounts
* once at the App root while the route chain below it unmounts on every
* navigation. Component-owned timers would leak by construction; this way there
* is nothing to clean up.
*/
export type ToastTone = 'success' | 'danger' | 'info';
export interface ToastItem {
id: string;
message: string;
tone: ToastTone;
}
const AUTO_DISMISS_MS = 4000;
/** Overflow drops the oldest *pending* item — never the one on screen. */
const MAX_QUEUED = 3;
let queue = $state<ToastItem[]>([]);
let timer: ReturnType<typeof setTimeout> | undefined;
let nextId = 0;
export function getVisibleToast(): ToastItem | undefined {
return queue[0];
}
export function pushToast(message: string, tone: ToastTone = 'info'): void {
const visible = queue[0];
// A repeat of what is already on screen restarts its timer instead of
// queueing a twin. One debounced settings save resolves one promise that may
// have several subscribers, and without this the user gets three identical
// "Settings saved" toasts in a row.
if (visible !== undefined && visible.message === message && visible.tone === tone) {
startTimer(visible.id);
return;
}
nextId += 1;
const item: ToastItem = { id: `toast-${nextId}`, message, tone };
if (queue.length >= MAX_QUEUED) queue = [...queue.slice(0, 1), ...queue.slice(2), item];
else queue = [...queue, item];
if (queue.length === 1) startTimer(item.id);
}
export function dismissToast(id: string): void {
if (queue[0]?.id !== id) return;
shift();
}
/** Test teardown — module state outlives a single `it()`. */
export function clearToasts(): void {
clearTimer();
queue = [];
nextId = 0;
}
function shift(): void {
clearTimer();
queue = queue.slice(1);
const next = queue[0];
if (next !== undefined) startTimer(next.id);
}
function startTimer(id: string): void {
clearTimer();
timer = setTimeout(() => {
timer = undefined;
// The identity check is what stops a user dismiss racing this timeout from
// shifting twice and flashing the next toast for a single frame.
if (queue[0]?.id !== id) return;
shift();
}, AUTO_DISMISS_MS);
}
function clearTimer(): void {
if (timer === undefined) return;
clearTimeout(timer);
timer = undefined;
}
+106
View File
@@ -0,0 +1,106 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { clearToasts, dismissToast, getVisibleToast, pushToast } from '@/lib/stores/toast.svelte';
beforeEach(() => {
clearToasts();
vi.useFakeTimers();
});
afterEach(() => {
vi.useRealTimers();
clearToasts();
});
describe('toast queue', () => {
it('shows a pushed message and dismisses it after 4 s', () => {
pushToast('Saved', 'success');
expect(getVisibleToast()?.message).toBe('Saved');
vi.advanceTimersByTime(3999);
expect(getVisibleToast()).toBeDefined();
vi.advanceTimersByTime(1);
expect(getVisibleToast()).toBeUndefined();
});
it('is a queue, not a stack — the second waits for the first', () => {
pushToast('first');
pushToast('second');
expect(getVisibleToast()?.message).toBe('first');
vi.advanceTimersByTime(4000);
expect(getVisibleToast()?.message).toBe('second');
vi.advanceTimersByTime(4000);
expect(getVisibleToast()).toBeUndefined();
});
it('restarts the timer for a repeat of the visible message instead of queueing a twin', () => {
// One debounced settings save resolves one promise with several
// subscribers; without this the user gets three identical "Saved" toasts.
pushToast('Settings saved', 'success');
vi.advanceTimersByTime(3000);
pushToast('Settings saved', 'success');
vi.advanceTimersByTime(3000);
expect(getVisibleToast()?.message).toBe('Settings saved');
vi.advanceTimersByTime(1000);
expect(getVisibleToast()).toBeUndefined();
});
it('treats the same text with a different tone as a distinct toast', () => {
pushToast('Done', 'success');
pushToast('Done', 'danger');
vi.advanceTimersByTime(4000);
expect(getVisibleToast()?.tone).toBe('danger');
});
it('does not let a stale timer shift the next item early after a manual dismiss', () => {
pushToast('first');
const first = getVisibleToast();
pushToast('second');
vi.advanceTimersByTime(1000);
dismissToast(first?.id ?? '');
expect(getVisibleToast()?.message).toBe('second');
// The first item's original 4 s deadline passes here. Without the id check
// in the timeout it would shift again and flash "second" away instantly.
vi.advanceTimersByTime(3000);
expect(getVisibleToast()?.message).toBe('second');
vi.advanceTimersByTime(1000);
expect(getVisibleToast()).toBeUndefined();
});
it('ignores a dismiss for an item that is not on screen', () => {
pushToast('first');
pushToast('second');
const queuedId = 'toast-2';
dismissToast(queuedId);
expect(getVisibleToast()?.message).toBe('first');
});
it('caps the queue by dropping the oldest pending item, never the visible one', () => {
pushToast('visible');
pushToast('pending-a');
pushToast('pending-b');
pushToast('pending-c');
expect(getVisibleToast()?.message).toBe('visible');
vi.advanceTimersByTime(4000);
// 'pending-a' was the oldest queued item when the cap was hit.
expect(getVisibleToast()?.message).toBe('pending-b');
vi.advanceTimersByTime(4000);
expect(getVisibleToast()?.message).toBe('pending-c');
vi.advanceTimersByTime(4000);
expect(getVisibleToast()).toBeUndefined();
});
it('defaults to the info tone', () => {
pushToast('plain');
expect(getVisibleToast()?.tone).toBe('info');
});
});