fix(toast): respect queue strategy overflow

[egdev6]

Summary

• Fixes Toast queueStrategy overflow semantics so FIFO keeps current visible toasts and queues newer overflow toasts.
• Preserves LIFO latest-first overflow behavior while keeping promotion order strategy-aware.
• Updates regression coverage and Storybook/type docs for FIFO/LIFO behavior.

Closes #274

Review scope

• Primary files/areas:
  • src/components/organisms/toast/toastStore.ts
  • src/components/organisms/toast/Toast.test.tsx
  • src/components/organisms/toast/Toast.stories.tsx
  • src/components/organisms/toast/types.ts
• Out of scope: broader Toast API changes, visual redesign, accessibility semantics.
• Review workload: small (~110 insertions / 35 deletions).

Type of change

• New component
• Existing component update/refactor
• Bug fix
• Accessibility
• Design tokens
• Storybook/docs
• Infrastructure/tooling
• NPM/dependencies

Workflow gates

• Linked issue is present with Closes #NNN or maintainer approved an exception.
• Linked issue has label status:approved before implementation starts.
• Linked issue assignee was checked before work started; if it was assigned to someone else, explicit reassignment permission is documented.
• Work was started through the Project flow: assignee set, Project status In progress, branch/worktree recorded.
• PR title follows Conventional Commit format: <type>(<optional scope>): <description>.
• Commits follow the same commitlint-enforced format.
• Diff is focused; unrelated work is called out in Review scope.
• MCP/runtime artifacts are absent: .playwright-mcp, page-*.png, page-*.jpeg, *.md.playwright-output.

Component evidence (required for component changes)

• Validated component spec is linked or quoted in the issue.
• Accessibility contract from the spec was implemented or deviations are explained below.
• Follows the 6-file pattern: types.ts, use*.ts, Component.tsx, Component.test.tsx, Component.stories.tsx, index.ts.
• CVA variants live in types.ts; JSX component has no state, CVA calls, or business logic.
• Public props with runtime defaults have matching @default JSDoc in types.ts (node scripts/verify-prop-default-docs.mjs).
• Uses design tokens from theme.css; no hardcoded colors or arbitrary color utilities.
• Storybook covers default, variants, documented states, edge cases, and dark mode when visually different.
• Component audit result is PASS or accepted PASS WITH WARNINGS.
• Visual review result is included when visuals changed.

Accessibility evidence

• Role/name semantics verified with Testing Library queries or equivalent.
• Keyboard-only behavior verified: Tab / Shift+Tab, Enter / Space, Arrow keys, Escape, Home / End / typeahead where applicable.
• Focus lifecycle verified: initial focus, roving/active descendant, focus restore, trap/portal behavior where applicable.
• Disabled, required, invalid/error, loading, and empty states expose the expected semantics where applicable.
• Reduced motion behavior is respected where motion changed.
• Screen reader or axe/manual evidence is included below when applicable.

Validation evidence

• TypeScript: pnpm exec tsc --noEmit ✅
• Unit tests:
  • pnpm vitest run src/components/organisms/toast/Toast.test.tsx ✅ — 48 tests passed
  • pre-push pnpm run test ✅ — 35 files / 741 tests passed
• Build/package: not run; package exports were not changed.
• Storybook or visual check: pnpm run storybook-build ✅
• Accessibility check: behavior verified with Testing Library role/name queries; no semantic/a11y behavior changed.
• Security/dependency check: N/A — no dependency changes.
• Additional checks:
  • node scripts/verify-prop-default-docs.mjs ✅
  • pnpm exec biome check src/components/organisms/toast/toastStore.ts src/components/organisms/toast/Toast.test.tsx src/components/organisms/toast/Toast.stories.tsx src/components/organisms/toast/types.ts ✅
  • git diff --check ✅
  • Fresh pre-PR review ✅ — no blockers.

Screenshots or recordings

N/A — this is queue-order behavior plus docs/test coverage; Storybook build passed.

Notes for reviewer

FIFO now queues new overflow toasts and keeps current visible slots stable. LIFO keeps the previous latest-first behavior by demoting the oldest visible toast before showing the new one. Promotion after close remains strategy-aware through the existing queue promotion path.

[Copilot]

Pull request overview

Fixes Toast overflow behavior so queueStrategy consistently governs what happens when maxVisible is exceeded (not just which queued toast is promoted later), aligning runtime behavior with the intended FIFO/LIFO contract for consumers of the design system.

Changes:

• Updates enqueueToast() overflow handling: FIFO now queues new overflow toasts instead of demoting a visible toast; LIFO keeps demotion/latest-visible behavior.
• Adds/updates regression tests to cover FIFO overflow visibility, FIFO promotion order, queued-toast removal stability, and LIFO overflow/promotion scenarios.
• Updates Storybook queue-strategy demo copy and TypeScript docs to reflect the clarified semantics.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
src/components/organisms/toast/types.ts	Documents the FIFO/LIFO overflow + promotion semantics for ToastQueueStrategy and provider props.
src/components/organisms/toast/toastStore.ts	Applies queueStrategy during overflow so FIFO queues and LIFO demotes/shows newest.
src/components/organisms/toast/Toast.test.tsx	Expands regression coverage for FIFO/LIFO overflow visibility and promotion ordering.
src/components/organisms/toast/Toast.stories.tsx	Updates the QueueStrategy story text to accurately teach the new behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.