@boostdev/design-system-components 2.8.0 → 2.11.0

package/src/components/interaction/Drawer/Drawer.tsx

@@ -4,11 +4,12 @@ import { installInvokerCommandsPolyfill } from '../../../polyfill-invoker-comman
 // Install once at module load — no-op if native support is present.
 installInvokerCommandsPolyfill();
 
+const FOCUSABLE_SELECTOR = 'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])';
 import css from './Drawer.module.css';
 import { cn } from '@boostdev/design-system-foundation';
 import type { WithClassName } from '../../../types';
 
-interface DrawerProps extends WithClassName, Omit<HTMLAttributes<HTMLDialogElement>, 'title'> {
+export interface DrawerProps extends WithClassName, Omit<HTMLAttributes<HTMLDialogElement>, 'title'> {
   isOpen: boolean;
   onOpen?: () => void;
   onClose: () => void;
@@ -29,6 +30,8 @@ export function Drawer({
 }: Readonly<DrawerProps>) {
   const generatedId = useId();
   const id = idProp ?? generatedId;
+  const titleId = useId();
+  const hasCustomLabel = 'aria-label' in rest || 'aria-labelledby' in rest;
 
   const dialogRef = useRef<HTMLDialogElement>(null);
   const triggerRef = useRef<Element | null>(null);
@@ -70,15 +73,12 @@ export function Drawer({
     return () => dialog.removeEventListener('command', handleCommand);
   }, [onOpen, onClose]);
 
-  // Close on backdrop click
-  const handleClick = (e: React.MouseEvent<HTMLDialogElement>) => {
-    const dialog = dialogRef.current;
-    if (!dialog) return;
-    const rect = dialog.getBoundingClientRect();
-    const outside =
-      e.clientX < rect.left || e.clientX > rect.right ||
-      e.clientY < rect.top  || e.clientY > rect.bottom;
-    if (outside) onClose();
+  // Close on backdrop click. The dialog element's own box is only the visible
+  // panel — clicking the ::backdrop dispatches with e.target === the dialog
+  // itself, so this correctly ignores clicks (including keyboard-activated
+  // synthetic clicks at 0,0) on controls inside the panel.
+  const handleBackdropClick = (e: React.MouseEvent<HTMLDialogElement>) => {
+    if (e.target === dialogRef.current) onClose();
   };
 
   // Close on Escape (dialog handles it natively, but we sync state)
@@ -87,6 +87,22 @@ export function Drawer({
     onClose();
   };
 
+  // Trap Tab focus inside the drawer while open, matching Dialog's behaviour.
+  const handleKeyDown = (e: React.KeyboardEvent<HTMLDialogElement>) => {
+    if (e.key !== 'Tab') return;
+    const dialog = dialogRef.current;
+    if (!dialog) return;
+    const focusable = Array.from(dialog.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR));
+    if (focusable.length === 0) return;
+    const first = focusable[0];
+    const last = focusable[focusable.length - 1];
+    if (e.shiftKey) {
+      if (document.activeElement === first) { e.preventDefault(); last.focus(); }
+    } else {
+      if (document.activeElement === last) { e.preventDefault(); first.focus(); }
+    }
+  };
+
   return (
     <dialog
       {...rest}
@@ -94,11 +110,13 @@ export function Drawer({
       id={id}
       className={cn(css.drawer, css[`--side_${side}`], className)}
       aria-modal="true"
-      onClick={handleClick}
+      aria-labelledby={hasCustomLabel ? rest['aria-labelledby'] : (title ? titleId : undefined)}
+      onClick={handleBackdropClick}
       onCancel={handleCancel}
+      onKeyDown={handleKeyDown}
     >
       <div className={css.header}>
-        {!!title && title}
+        {!!title && <div id={titleId}>{title}</div>}
         <button
           type="button"
           className={css.closeButton}

package/src/components/interaction/Drawer/index.ts

@@ -1 +1,2 @@
 export { Drawer } from './Drawer';
+export type { DrawerProps } from './Drawer';

package/src/components/interaction/DropdownMenu/DropdownMenu.mdx

@@ -57,3 +57,5 @@ Floating menu with a list of selectable actions, triggered by a button. Supports
 - Implements ARIA menu pattern: `role="menu"`, `role="menuitem"`
 - Arrow keys navigate items; `Enter`/`Space` activate; `Escape` closes
 - Disabled items have `aria-disabled="true"` and are skipped during keyboard navigation
+- Opening the menu focuses the first enabled item (disabled items are skipped as the initial target)
+- Closing the menu via `Escape` or item activation returns focus to the trigger; closing via `Tab` lets focus move naturally to the next element

package/src/components/interaction/DropdownMenu/DropdownMenu.spec.tsx

@@ -71,4 +71,38 @@ describe('DropdownMenu', () => {
     await user.keyboard('{ArrowDown}');
     expect(screen.getByRole('menuitem', { name: 'Duplicate' })).toHaveFocus();
   });
+
+  it('restores focus to the trigger when Escape is pressed', async () => {
+    const user = userEvent.setup();
+    render(<DropdownMenu trigger={<button type="button">Actions</button>} items={items} />);
+    await user.click(screen.getByRole('button', { name: 'Actions' }));
+    await user.keyboard('{Escape}');
+    expect(screen.getByRole('button', { name: 'Actions' })).toHaveFocus();
+  });
+
+  it('restores focus to the trigger when a menu item is activated', async () => {
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu
+        trigger={<button type="button">Actions</button>}
+        items={[{ id: 'edit', label: 'Edit', onClick: vi.fn() }]}
+      />
+    );
+    await user.click(screen.getByRole('button', { name: 'Actions' }));
+    await user.click(screen.getByRole('menuitem', { name: 'Edit' }));
+    expect(screen.getByRole('button', { name: 'Actions' })).toHaveFocus();
+  });
+
+  it('focuses the first enabled item when the first item is disabled', async () => {
+    const user = userEvent.setup();
+    const itemsWithDisabledFirst = [
+      { id: 'delete', label: 'Delete', onClick: vi.fn(), disabled: true },
+      { id: 'edit', label: 'Edit', onClick: vi.fn() },
+    ];
+    render(
+      <DropdownMenu trigger={<button type="button">Actions</button>} items={itemsWithDisabledFirst} />
+    );
+    await user.click(screen.getByRole('button', { name: 'Actions' }));
+    expect(screen.getByRole('menuitem', { name: 'Edit' })).toHaveFocus();
+  });
 });

package/src/components/interaction/DropdownMenu/DropdownMenu.tsx

@@ -22,7 +22,7 @@ export interface DropdownMenuItem {
   separator?: boolean;
 }
 
-interface DropdownMenuProps extends WithClassName, HTMLAttributes<HTMLDivElement> {
+export interface DropdownMenuProps extends WithClassName, HTMLAttributes<HTMLDivElement> {
   trigger: ReactElement;
   items: DropdownMenuItem[];
   placement?: 'bottom-start' | 'bottom-end';
@@ -39,15 +39,25 @@ export function DropdownMenu({
   const containerRef = useRef<HTMLDivElement>(null);
   const menuId = useId();
   const itemRefs = useRef<(HTMLButtonElement | null)[]>([]);
+  const triggerRef = useRef<Element | null>(null);
   const open = () => {
+    triggerRef.current = document.activeElement;
     setIsOpen(true);
   };
 
-  const close = () => setIsOpen(false);
+  const close = (restoreFocus = false) => {
+    setIsOpen(false);
+    if (restoreFocus) {
+      (triggerRef.current as HTMLElement | null)?.focus();
+    }
+  };
 
   useEffect(() => {
     if (isOpen) {
-      itemRefs.current[0]?.focus();
+      const firstEnabledIndex = items.findIndex(item => !item.disabled);
+      if (firstEnabledIndex !== -1) {
+        itemRefs.current[firstEnabledIndex]?.focus();
+      }
     }
   }, [isOpen]);
 
@@ -58,7 +68,7 @@ export function DropdownMenu({
       if (!containerRef.current?.contains(e.target as Node)) close();
     };
     const handleKeyDown = (e: globalThis.KeyboardEvent) => {
-      if (e.key === 'Escape') close();
+      if (e.key === 'Escape') close(true);
     };
 
     document.addEventListener('pointerdown', handlePointerDown);
@@ -124,7 +134,7 @@ export function DropdownMenu({
                 role="menuitem"
                 disabled={item.disabled}
                 className={css.item}
-                onClick={() => { item.onClick?.(); close(); }}
+                onClick={() => { item.onClick?.(); close(true); }}
                 onKeyDown={e => handleItemKeyDown(e, index)}
               >
                 {item.icon && <span className={css.icon} aria-hidden="true">{item.icon}</span>}

package/src/components/interaction/DropdownMenu/index.ts

@@ -1,2 +1,3 @@
 export { DropdownMenu } from './DropdownMenu';
 export type { DropdownMenuItem } from './DropdownMenu';
+export type { DropdownMenuProps } from './DropdownMenu';

package/src/components/interaction/Popover/Popover.mdx

@@ -40,12 +40,16 @@ Floating panel anchored to a trigger element. Unlike `Tooltip`, popovers can con
 <tr><td>`--popover_shadow`</td><td>`var(--bds-shadow_m)`</td><td>Panel box shadow</td></tr>
 <tr><td>`--popover_border`</td><td>`none`</td><td>Panel border</td></tr>
 <tr><td>`--popover_radius`</td><td>`var(--bdc-outline_radius)`</td><td>Panel corner radius</td></tr>
+<tr><td>`--popover_z-index`</td><td>`var(--bds-z-index_dropdown)`</td><td>Panel stacking order</td></tr>
+<tr><td>`--popover_max-width`</td><td>`20rem`</td><td>Panel maximum inline size</td></tr>
+<tr><td>`--popover_max-height`</td><td>`80dvh`</td><td>Panel maximum block size</td></tr>
 </tbody>
 </table>
 
 
 ## Accessibility
 
-- Trigger element gets `aria-haspopup="true"` and `aria-expanded` toggled on open/close
-- Popover panel is linked via `aria-controls`
+- Trigger element gets `aria-expanded` toggled on open/close (no `aria-haspopup` — the panel is a disclosure region, not a menu)
+- Popover panel is linked to the trigger via `aria-controls`
 - Focus moves into the panel on open; `Escape` closes and returns focus to trigger
+- The trigger must render a native `<button>` for the built-in open/close behaviour (invoker commands are spec-limited to `<button>`). Non-`<button>` triggers still work — an `onClick` fallback calls `togglePopover()` directly — but should render an accessible, keyboard-operable control themselves.

package/src/components/interaction/Popover/Popover.module.css

@@ -16,7 +16,7 @@
     inset: unset;
     margin: 0;
     overflow-block: auto;
-    z-index: var(--popover_z-index, 100);
+    z-index: var(--popover_z-index, var(--bds-z-index_dropdown));
     min-inline-size: 12rem;
     max-inline-size: var(--popover_max-width, 20rem);
     max-block-size: var(--popover_max-height, 80dvh);
@@ -36,31 +36,40 @@
      anchor() resolves relative to the element tagged with the matching anchor-name.
      @position-try fallbacks are tried in order when the primary placement overflows. */
 
+  /* Physical top/left/right/bottom (not logical inset-*) are intentional here:
+     `placement` is a physical direction chosen by the consumer ('top' |
+     'bottom' | 'left' | 'right'), not a text-direction-relative one. Anchor
+     positioning's logical inset-inline-start/end flip meaning under
+     [dir='rtl'], which would silently reinterpret e.g. placement="right" as
+     "left" in RTL documents — changing consumer-visible behaviour, not just
+     CSS convention. Kept physical, consistent with the @position-try blocks
+     below (already an accepted logical-properties exception). */
+
   .panel[data-placement='bottom'] {
     top: anchor(bottom);
     left: anchor(left);
-    margin-block-start: var(--bds-space_xs, 8px);
+    margin-block-start: var(--bds-space_xs);
     position-try-fallbacks: --popover-top, --popover-right, --popover-left;
   }
 
   .panel[data-placement='top'] {
     bottom: anchor(top);
     left: anchor(left);
-    margin-block-end: var(--bds-space_xs, 8px);
+    margin-block-end: var(--bds-space_xs);
     position-try-fallbacks: --popover-bottom, --popover-right, --popover-left;
   }
 
   .panel[data-placement='right'] {
     top: anchor(top);
     left: anchor(right);
-    margin-inline-start: var(--bds-space_xs, 8px);
+    margin-inline-start: var(--bds-space_xs);
     position-try-fallbacks: --popover-left, --popover-bottom, --popover-top;
   }
 
   .panel[data-placement='left'] {
     top: anchor(top);
     right: anchor(left);
-    margin-inline-end: var(--bds-space_xs, 8px);
+    margin-inline-end: var(--bds-space_xs);
     position-try-fallbacks: --popover-right, --popover-bottom, --popover-top;
   }
 
@@ -74,7 +83,7 @@
     bottom: unset;
     left: anchor(left);
     margin: 0;
-    margin-block-start: var(--bds-space_xs, 8px);
+    margin-block-start: var(--bds-space_xs);
   }
 
   @position-try --popover-top {
@@ -83,7 +92,7 @@
     bottom: anchor(top);
     left: anchor(left);
     margin: 0;
-    margin-block-end: var(--bds-space_xs, 8px);
+    margin-block-end: var(--bds-space_xs);
   }
 
   @position-try --popover-right {
@@ -92,7 +101,7 @@
     bottom: unset;
     left: anchor(right);
     margin: 0;
-    margin-inline-start: var(--bds-space_xs, 8px);
+    margin-inline-start: var(--bds-space_xs);
   }
 
   @position-try --popover-left {
@@ -101,7 +110,7 @@
     bottom: unset;
     left: unset;
     margin: 0;
-    margin-inline-end: var(--bds-space_xs, 8px);
+    margin-inline-end: var(--bds-space_xs);
   }
 
   /* Full-width fallback blocks for narrow screens.
@@ -111,20 +120,20 @@
 
   @position-try --popover-bottom-fullwidth {
     top: anchor(bottom);
-    right: var(--bds-space_xs, 8px);
+    right: var(--bds-space_xs);
     bottom: unset;
-    left: var(--bds-space_xs, 8px);
+    left: var(--bds-space_xs);
     margin: 0;
-    margin-block-start: var(--bds-space_xs, 8px);
+    margin-block-start: var(--bds-space_xs);
   }
 
   @position-try --popover-top-fullwidth {
     top: unset;
-    right: var(--bds-space_xs, 8px);
+    right: var(--bds-space_xs);
     bottom: anchor(top);
-    left: var(--bds-space_xs, 8px);
+    left: var(--bds-space_xs);
     margin: 0;
-    margin-block-end: var(--bds-space_xs, 8px);
+    margin-block-end: var(--bds-space_xs);
   }
 
   /* Narrow screens (≤420px): span full viewport width and only flip vertically.
@@ -136,10 +145,9 @@
     .panel[data-placement='top'],
     .panel[data-placement='left'],
     .panel[data-placement='right'] {
-      left: var(--bds-space_xs, 8px);
-      right: var(--bds-space_xs, 8px);
+      inset-inline: var(--bds-space_xs);
       inline-size: 100%;
-      max-inline-size: calc(100svw - 2 * var(--bds-space_xs, 8px));
+      max-inline-size: calc(100svw - 2 * var(--bds-space_xs));
       position-try-fallbacks: --popover-top-fullwidth, --popover-bottom-fullwidth;
     }
   }

package/src/components/interaction/Popover/Popover.spec.tsx

@@ -189,4 +189,42 @@ describe('Popover', () => {
     );
     expect(getPanel()).not.toHaveAttribute('role');
   });
+
+  it('does not set aria-haspopup on the trigger', () => {
+    render(
+      <Popover content={<p>Panel content</p>}>
+        <button type="button">Open</button>
+      </Popover>
+    );
+    expect(screen.getByRole('button', { name: 'Open' })).not.toHaveAttribute('aria-haspopup');
+  });
+
+  it('falls back to togglePopover on click when the trigger does not render a <button>', async () => {
+    const user = userEvent.setup();
+    render(
+      <Popover content={<p>Panel content</p>}>
+        <span role="button" tabIndex={0}>
+          Open
+        </span>
+      </Popover>
+    );
+    const trigger = screen.getByRole('button', { name: 'Open' });
+    await user.click(trigger);
+    expect(HTMLElement.prototype.togglePopover).toHaveBeenCalled();
+    expect(trigger).toHaveAttribute('aria-expanded', 'true');
+  });
+
+  it('still calls the consumer onClick handler for a non-<button> trigger', async () => {
+    const user = userEvent.setup();
+    const onClick = vi.fn();
+    render(
+      <Popover content={<p>Panel content</p>}>
+        <span role="button" tabIndex={0} onClick={onClick}>
+          Open
+        </span>
+      </Popover>
+    );
+    await user.click(screen.getByRole('button', { name: 'Open' }));
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
 });

package/src/components/interaction/Popover/Popover.tsx

@@ -1,5 +1,6 @@
 import {
   HTMLAttributes,
+  MouseEvent as ReactMouseEvent,
   ReactElement,
   ReactNode,
   cloneElement,
@@ -26,7 +27,7 @@ if (
   import('@oddbird/css-anchor-positioning').catch(() => {});
 }
 
-interface PopoverProps extends WithClassName, Omit<HTMLAttributes<HTMLSpanElement>, 'content'> {
+export interface PopoverProps extends WithClassName, Omit<HTMLAttributes<HTMLSpanElement>, 'content'> {
   children: ReactElement;
   content: ReactNode;
   placement?: 'top' | 'bottom' | 'left' | 'right';
@@ -88,7 +89,6 @@ export function Popover({
     ? cloneElement(children as ReactElement<Record<string, unknown>>, {
         'aria-expanded': isOpen,
         'aria-controls': panelId,
-        'aria-haspopup': true,
         commandfor: panelId,
         command: 'toggle-popover',
         style: {
@@ -96,9 +96,23 @@ export function Popover({
           anchorName,
         },
         // Forward any existing onClick on the child (for custom side-effects).
-        // Do NOT add our own toggle here — commandfor/command handles it to
-        // avoid a double-toggle when both onClick and invoker fire.
-        onClick: (children.props as Record<string, unknown>).onClick as (() => void) | undefined,
+        // commandfor/command handles the toggle when the trigger renders a
+        // native <button> — don't also toggle there (avoids a double-toggle).
+        // Invoker commands are spec-limited to <button>, so when the actual
+        // rendered element isn't one (e.g. a plain <a> or a custom non-button
+        // Link), fall back to an explicit togglePopover() call instead of
+        // silently going dead. Checked on the DOM node (event.currentTarget),
+        // not the React element type, so wrapper components that forward
+        // props onto an inner <button> (e.g. this library's Button) still
+        // take the native path.
+        onClick: (event: ReactMouseEvent<HTMLElement>) => {
+          ((children.props as Record<string, unknown>).onClick as
+            | ((e: ReactMouseEvent<HTMLElement>) => void)
+            | undefined)?.(event);
+          if (!(event.currentTarget instanceof HTMLButtonElement)) {
+            panelRef.current?.togglePopover();
+          }
+        },
       })
     : children;
 

package/src/components/interaction/Popover/index.ts

@@ -1 +1,2 @@
 export { Popover } from './Popover';
+export type { PopoverProps } from './Popover';

package/src/components/interaction/Rating/Rating.mdx

@@ -48,5 +48,5 @@ Read-only star rating display. Use to show an existing score; for user input, co
 
 ## Accessibility
 
-- Renders as a `<span>` with `role="img"` and `aria-label="X out of Y stars"`
+- Renders as a `<div>` with `role="img"` and `aria-label="X out of Y stars"`
 - Stars are `aria-hidden` — the label carries the full meaning

package/src/components/interaction/Rating/Rating.module.css

@@ -6,8 +6,8 @@
   }
 
   .star {
-    width: 1.5em;
-    height: 1.5em;
+    inline-size: 1.5em;
+    block-size: 1.5em;
   }
 
   .--filled {

package/src/components/interaction/Rating/Rating.tsx

@@ -3,7 +3,7 @@ import css from './Rating.module.css';
 import { cn } from '@boostdev/design-system-foundation';
 import type { WithClassName } from '../../../types';
 
-interface RatingProps extends WithClassName, HTMLAttributes<HTMLDivElement> {
+export interface RatingProps extends WithClassName, HTMLAttributes<HTMLDivElement> {
   value: number;
   max?: number;
 }

package/src/components/interaction/Rating/index.ts

@@ -1 +1,2 @@
 export { Rating } from './Rating';
+export type { RatingProps } from './Rating';

package/src/components/interaction/Toast/Toast.mdx

@@ -43,6 +43,7 @@ const { showToast } = useToast();
 showToast('Changes saved', 'success');
 showToast('Something went wrong', 'error');
 showToast('New message received', 'info');
+showToast('Double-check this before continuing', 'warning');
 ```
 
 > **Next.js RSC note:** The root entry (`@boostdev/design-system-components`) is safe to import in Server Components for server-safe components like `Typography` or `Badge`. Toast itself is client-only and must be used inside a `'use client'` boundary.
@@ -78,6 +79,8 @@ The override surface is **layered**. Setting a public token on the toast (or any
 <tbody>
 <tr><td>`--toast_color`</td><td>per variant</td><td>Toast background. Set to theme every variant at once.</td></tr>
 <tr><td>`--toast_on-color`</td><td>per variant</td><td>Toast text colour.</td></tr>
+<tr><td>`--toast_radius`</td><td>`var(--bds-border_radius--s)`</td><td>Toast corner radius.</td></tr>
+<tr><td>`--toast_shadow`</td><td>`var(--bds-shadow_s)`</td><td>Toast elevation shadow.</td></tr>
 </tbody>
 </table>
 

package/src/components/interaction/Toast/Toast.module.css

@@ -21,15 +21,26 @@
        over per-variant defaults. Variants write to the inner --toast_*--variant slot. */
     background-color: var(--toast_color, var(--toast_color--variant, var(--bds-color_bg)));
     color:            var(--toast_on-color, var(--toast_on-color--variant, var(--bds-color_on-bg)));
-    border-radius: var(--bds-border_radius--s);
-    box-shadow: var(--bds-shadow_s);
+    border-radius: var(--toast_radius, var(--bds-border_radius--s));
+    box-shadow: var(--toast_shadow, var(--bds-shadow_s));
     display: flex;
     align-items: center;
     gap: var(--bds-space_m);
-    min-inline-size: 300px;
+    min-inline-size: min(300px, calc(100svw - 2 * var(--bds-space_xl)));
     animation: slideIn var(--bds-animation_duration--fast) var(--bds-animation_easing);
   }
 
+  /*
+   * translateX() is a physical transform (documented exception — see AGENTS.md).
+   * The container is anchored on the logical inline-end edge (inset-inline-end),
+   * which is the physical *left* edge in RTL, so the off-screen slide-in offset
+   * must flip too or the toast slides in from the wrong side. --toast_slide-offset
+   * is an internal implementation slot, not part of the public token surface.
+   */
+  .toast:dir(rtl) {
+    --toast_slide-offset: -100%;
+  }
+
   .toast.--variant_success {
     --toast_color--variant:    var(--toast_color--success, var(--bds-color_success));
     --toast_on-color--variant: var(--toast_on-color--success, var(--bds-color_on-success));
@@ -55,6 +66,7 @@
   }
 
   .closeButton {
+    position: relative;
     display: flex;
     align-items: center;
     justify-content: center;
@@ -65,7 +77,19 @@
     background: none;
     border: none;
     cursor: pointer;
-    color: var(--toast_on-color);
+    color: currentcolor;
+  }
+
+  /* Expands the hit area to >=44px (WCAG 2.5.5) without growing the visible icon. */
+  .closeButton::after {
+    content: '';
+    position: absolute;
+    inset: -0.75rem;
+  }
+
+  .closeButton:focus-visible {
+    outline: var(--bds-outline_default);
+    outline-offset: var(--bds-outline_offset);
   }
 
   .closeButton svg {
@@ -76,7 +100,7 @@
 
 @keyframes slideIn {
   from {
-    transform: translateX(100%);
+    transform: translateX(var(--toast_slide-offset, 100%));
     opacity: 0;
   }
 
@@ -85,3 +109,9 @@
     opacity: 1;
   }
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .toast {
+    animation: none;
+  }
+}

package/src/components/interaction/Toast/Toast.spec.tsx

@@ -2,7 +2,13 @@ import { render, screen, act, fireEvent } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { ToastProvider, useToast } from './Toast';
 
-const ToastTrigger = ({ message = 'Test toast', variant = 'info' as const }) => {
+const ToastTrigger = ({
+  message = 'Test toast',
+  variant = 'info' as const,
+}: {
+  message?: string;
+  variant?: 'success' | 'error' | 'info' | 'warning';
+}) => {
   const { showToast } = useToast();
   return <button onClick={() => showToast(message, variant)}>Show Toast</button>;
 };
@@ -32,6 +38,68 @@ describe('Toast', () => {
     vi.useRealTimers();
   });
 
+  it('auto-dismisses each toast on its own 5s schedule even when another toast arrives mid-stream', () => {
+    vi.useFakeTimers();
+    const TwoTriggers = () => {
+      const { showToast } = useToast();
+      return (
+        <>
+          <button onClick={() => showToast('First toast', 'info')}>First</button>
+          <button onClick={() => showToast('Second toast', 'info')}>Second</button>
+        </>
+      );
+    };
+    render(
+      <ToastProvider>
+        <TwoTriggers />
+      </ToastProvider>,
+    );
+
+    act(() => { fireEvent.click(screen.getByText('First')); });
+    act(() => { vi.advanceTimersByTime(3000); });
+    // Second toast arrives before the first's timer fires — under the prior bug
+    // this reset every in-flight toast's timer instead of just starting its own.
+    act(() => { fireEvent.click(screen.getByText('Second')); });
+    act(() => { vi.advanceTimersByTime(2100); }); // t=5100 since "First" mounted
+    expect(screen.queryByText('First toast')).not.toBeInTheDocument();
+    expect(screen.getByText('Second toast')).toBeInTheDocument();
+    vi.useRealTimers();
+  });
+
+  it('does not crash when another toast is queued while the popover is already open', async () => {
+    // jsdom has no Popover API — mock a spec-accurate showPopover/hidePopover that
+    // throws InvalidStateError when called in a redundant state, matching real browsers.
+    HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+      if (this.hasAttribute('data-popover-open')) {
+        throw new DOMException('Invalid state', 'InvalidStateError');
+      }
+      this.setAttribute('data-popover-open', 'true');
+    });
+    HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
+      if (!this.hasAttribute('data-popover-open')) {
+        throw new DOMException('Invalid state', 'InvalidStateError');
+      }
+      this.removeAttribute('data-popover-open');
+    });
+
+    const user = userEvent.setup();
+    setup({ message: 'Queued toast' });
+    const button = screen.getByRole('button');
+    await user.click(button);
+    await user.click(button);
+    await user.click(button);
+
+    expect(screen.getAllByText('Queued toast')).toHaveLength(3);
+  });
+
+  it('accepts the warning variant', async () => {
+    const user = userEvent.setup();
+    setup({ message: 'Careful now', variant: 'warning' });
+    await user.click(screen.getByRole('button'));
+    const toastEl = screen.getByText('Careful now').closest('[role="status"]');
+    expect(toastEl?.className).toMatch(/--variant_warning/);
+  });
+
   it('renders the toast container as a manual popover', () => {
     render(
       <ToastProvider>