@boostdev/design-system-components 1.0.3 → 1.1.1

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

@@ -1,13 +1,25 @@
 @layer component {
   .wrapper {
-    position: relative;
     display: inline-flex;
+
+    /* No position: relative — the panel is position: fixed so it doesn't need
+       the wrapper as a containing block. */
   }
 
   .panel {
-    position: absolute;
-    z-index: var(--bds-z-index_popover);
-    min-width: 12rem;
+    /* Fixed positioning: containing block is the viewport.
+       - CSS anchor() values resolve in viewport space → polyfill applies them correctly.
+       - Ancestor overflow / stacking contexts cannot clip the panel. */
+    position: fixed;
+
+    /* Reset UA [popover] defaults (inset: 0, margin: auto, border, padding). */
+    inset: unset;
+    margin: 0;
+    overflow-block: auto;
+    z-index: var(--popover_z-index, 100);
+    min-inline-size: 12rem;
+    max-inline-size: var(--popover_max-width, 20rem);
+    max-block-size: var(--popover_max-height, 80dvh);
     padding: var(--bds-space_m);
     border: var(--popover_border, none);
     --bdc_color: currentcolor;
@@ -22,23 +34,127 @@
     font-size: var(--bds-font_size--body);
   }
 
-  .--placement_bottom {
-    top: calc(100% + var(--bds-space_xs));
-    left: 0;
+  /* Primary placements via CSS anchor positioning.
+     anchor() resolves relative to the element tagged with the matching anchor-name.
+     @position-try fallbacks are tried in order when the primary placement overflows. */
+
+  .panel[data-placement='bottom'] {
+    top: anchor(bottom);
+    left: anchor(left);
+    margin-block-start: var(--bds-space_xs, 8px);
+    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);
+    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);
+    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);
+    position-try-fallbacks: --popover-right, --popover-bottom, --popover-top;
+  }
+
+  /* Fallback placements — used by the browser (or polyfill) when the primary
+     placement would overflow the viewport. Each block resets all inset/margin
+     properties so nothing bleeds in from the primary placement. */
+
+  @position-try --popover-bottom {
+    top: anchor(bottom);
+    right: unset;
+    bottom: unset;
+    left: anchor(left);
+    margin: 0;
+    margin-block-start: var(--bds-space_xs, 8px);
+  }
+
+  @position-try --popover-top {
+    top: unset;
+    right: unset;
+    bottom: anchor(top);
+    left: anchor(left);
+    margin: 0;
+    margin-block-end: var(--bds-space_xs, 8px);
   }
 
-  .--placement_top {
-    bottom: calc(100% + var(--bds-space_xs));
-    left: 0;
+  @position-try --popover-right {
+    top: anchor(top);
+    right: unset;
+    bottom: unset;
+    left: anchor(right);
+    margin: 0;
+    margin-inline-start: var(--bds-space_xs, 8px);
   }
 
-  .--placement_right {
-    left: calc(100% + var(--bds-space_xs));
-    top: 0;
+  @position-try --popover-left {
+    top: anchor(top);
+    right: anchor(left);
+    bottom: unset;
+    left: unset;
+    margin: 0;
+    margin-inline-end: var(--bds-space_xs, 8px);
+  }
+
+  /* Full-width fallback blocks for narrow screens.
+     Defined at layer level (not inside @media) because @position-try cannot
+     be nested inside @media. These preserve left:8px/right:8px so the
+     panel stays edge-to-edge even when a @position-try fallback fires. */
+
+  @position-try --popover-bottom-fullwidth {
+    top: anchor(bottom);
+    right: var(--bds-space_xs, 8px);
+    bottom: unset;
+    left: var(--bds-space_xs, 8px);
+    margin: 0;
+    margin-block-start: var(--bds-space_xs, 8px);
   }
 
-  .--placement_left {
-    right: calc(100% + var(--bds-space_xs));
-    top: 0;
+  @position-try --popover-top-fullwidth {
+    top: unset;
+    right: var(--bds-space_xs, 8px);
+    bottom: anchor(top);
+    left: var(--bds-space_xs, 8px);
+    margin: 0;
+    margin-block-end: var(--bds-space_xs, 8px);
+  }
+
+  /* Narrow screens (≤420px): span full viewport width and only flip vertically.
+     max-width: none overrides the base 20rem cap; left/right edge constraints
+     handle the width instead. The panel still touches the anchor on the
+     vertical axis (top/bottom via anchor() is not overridden here). */
+  @media (width <= 420px) {
+    .panel[data-placement='bottom'],
+    .panel[data-placement='top'],
+    .panel[data-placement='left'],
+    .panel[data-placement='right'] {
+      left: var(--bds-space_xs, 8px);
+      right: var(--bds-space_xs, 8px);
+      inline-size: 100%;
+      max-inline-size: calc(100svw - 2 * var(--bds-space_xs, 8px));
+      position-try-fallbacks: --popover-top-fullwidth, --popover-bottom-fullwidth;
+    }
+  }
+
+  /* Wide + short screens (e.g. landscape mobile, split-screen): when the
+     viewport has more horizontal room than vertical, prefer side placements. */
+  @media (aspect-ratio >= 2/1) {
+    .panel[data-placement='bottom'] {
+      position-try-fallbacks: --popover-top, --popover-right, --popover-left;
+    }
+
+    .panel[data-placement='top'] {
+      position-try-fallbacks: --popover-bottom, --popover-right, --popover-left;
+    }
   }
 }

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

@@ -2,6 +2,47 @@ import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { Popover } from './Popover';
 
+// jsdom doesn't implement CSS.supports — stub so the anchor polyfill guard doesn't throw.
+beforeAll(() => {
+  Object.defineProperty(globalThis, 'CSS', {
+    value: { supports: () => true },
+    configurable: true,
+  });
+});
+
+// jsdom doesn't implement the Popover API — mock showPopover/hidePopover/togglePopover
+// and dispatch the `toggle` event so our state-sync listener fires.
+beforeEach(() => {
+  HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+    const event = new Event('toggle');
+    Object.defineProperty(event, 'newState', { value: 'open', configurable: true });
+    this.dispatchEvent(event);
+  });
+  HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
+    const event = new Event('toggle');
+    Object.defineProperty(event, 'newState', { value: 'closed', configurable: true });
+    this.dispatchEvent(event);
+  });
+  HTMLElement.prototype.togglePopover = vi.fn(function (this: HTMLElement) {
+    const isCurrentlyOpen = this.getAttribute('data-popover-open') === 'true';
+    if (isCurrentlyOpen) {
+      this.setAttribute('data-popover-open', 'false');
+      const event = new Event('toggle');
+      Object.defineProperty(event, 'newState', { value: 'closed', configurable: true });
+      this.dispatchEvent(event);
+    } else {
+      this.setAttribute('data-popover-open', 'true');
+      const event = new Event('toggle');
+      Object.defineProperty(event, 'newState', { value: 'open', configurable: true });
+      this.dispatchEvent(event);
+    }
+  });
+});
+
+function getPanel() {
+  return document.querySelector<HTMLElement>('[popover]')!;
+}
+
 describe('Popover', () => {
   it('renders the trigger', () => {
     render(
@@ -12,13 +53,23 @@ describe('Popover', () => {
     expect(screen.getByRole('button', { name: 'Open' })).toBeInTheDocument();
   });
 
-  it('does not show the panel by default', () => {
+  it('renders the panel as a [popover] element', () => {
     render(
       <Popover content={<p>Panel content</p>}>
         <button type="button">Open</button>
       </Popover>
     );
-    expect(screen.queryByText('Panel content')).not.toBeInTheDocument();
+    expect(getPanel()).toBeInTheDocument();
+    expect(getPanel()).toHaveAttribute('popover', 'auto');
+  });
+
+  it('panel is not open by default', () => {
+    render(
+      <Popover content={<p>Panel content</p>}>
+        <button type="button">Open</button>
+      </Popover>
+    );
+    expect(screen.getByRole('button').getAttribute('aria-expanded')).toBe('false');
   });
 
   it('shows the panel when trigger is clicked', async () => {
@@ -29,7 +80,20 @@ describe('Popover', () => {
       </Popover>
     );
     await user.click(screen.getByRole('button', { name: 'Open' }));
-    expect(screen.getByText('Panel content')).toBeInTheDocument();
+    expect(HTMLElement.prototype.togglePopover).toHaveBeenCalled();
+  });
+
+  it('sets aria-expanded true after opening', async () => {
+    const user = userEvent.setup();
+    render(
+      <Popover content={<p>Panel</p>}>
+        <button type="button">Open</button>
+      </Popover>
+    );
+    const trigger = screen.getByRole('button');
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    await user.click(trigger);
+    expect(trigger).toHaveAttribute('aria-expanded', 'true');
   });
 
   it('closes the panel when trigger is clicked again', async () => {
@@ -41,32 +105,68 @@ describe('Popover', () => {
     );
     await user.click(screen.getByRole('button', { name: 'Toggle' }));
     await user.click(screen.getByRole('button', { name: 'Toggle' }));
-    expect(screen.queryByText('Panel content')).not.toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Toggle' })).toHaveAttribute('aria-expanded', 'false');
   });
 
-  it('closes the panel when Escape is pressed', async () => {
-    const user = userEvent.setup();
+  it('trigger uses commandfor/command="toggle-popover"', () => {
     render(
-      <Popover content={<p>Panel content</p>}>
+      <Popover content={<p>Panel</p>}>
         <button type="button">Open</button>
       </Popover>
     );
-    await user.click(screen.getByRole('button', { name: 'Open' }));
-    await user.keyboard('{Escape}');
-    expect(screen.queryByText('Panel content')).not.toBeInTheDocument();
+    const trigger = screen.getByRole('button');
+    expect(trigger).toHaveAttribute('commandfor');
+    expect(trigger).toHaveAttribute('command', 'toggle-popover');
+    expect(trigger.getAttribute('commandfor')).toBe(getPanel().id);
   });
 
-  it('sets aria-expanded on the trigger when open', async () => {
-    const user = userEvent.setup();
+  it('sets anchor-name on the trigger and position-anchor on the panel', () => {
     render(
       <Popover content={<p>Panel</p>}>
         <button type="button">Open</button>
       </Popover>
     );
     const trigger = screen.getByRole('button');
-    expect(trigger).toHaveAttribute('aria-expanded', 'false');
-    await user.click(trigger);
-    expect(trigger).toHaveAttribute('aria-expanded', 'true');
+    const panel = getPanel();
+    const anchorName = trigger.style.getPropertyValue('anchor-name');
+    const positionAnchor = panel.style.getPropertyValue('position-anchor');
+    expect(anchorName).toMatch(/^--popover-/);
+    expect(positionAnchor).toBe(anchorName);
+  });
+
+  it('each instance gets a unique anchor-name', () => {
+    render(
+      <>
+        <Popover content={<p>A</p>}>
+          <button type="button">A</button>
+        </Popover>
+        <Popover content={<p>B</p>}>
+          <button type="button">B</button>
+        </Popover>
+      </>
+    );
+    const [btnA, btnB] = screen.getAllByRole('button');
+    expect(btnA.style.getPropertyValue('anchor-name')).not.toBe(
+      btnB.style.getPropertyValue('anchor-name')
+    );
+  });
+
+  it('sets data-placement from the placement prop', () => {
+    render(
+      <Popover content={<p>Panel</p>} placement="top">
+        <button type="button">Open</button>
+      </Popover>
+    );
+    expect(getPanel()).toHaveAttribute('data-placement', 'top');
+  });
+
+  it('defaults data-placement to "bottom"', () => {
+    render(
+      <Popover content={<p>Panel</p>}>
+        <button type="button">Open</button>
+      </Popover>
+    );
+    expect(getPanel()).toHaveAttribute('data-placement', 'bottom');
   });
 
   it('renders role="region" with aria-label when aria-label prop is provided', async () => {
@@ -77,17 +177,16 @@ describe('Popover', () => {
       </Popover>
     );
     await user.click(screen.getByRole('button', { name: 'Open' }));
-    expect(screen.getByRole('region', { name: 'Filter options' })).toBeInTheDocument();
+    expect(getPanel()).toHaveAttribute('role', 'region');
+    expect(getPanel()).toHaveAttribute('aria-label', 'Filter options');
   });
 
-  it('does not render role="region" when no aria-label is provided', async () => {
-    const user = userEvent.setup();
+  it('does not render role="region" when no aria-label is provided', () => {
     render(
       <Popover content={<p>Panel</p>}>
         <button type="button">Open</button>
       </Popover>
     );
-    await user.click(screen.getByRole('button', { name: 'Open' }));
-    expect(screen.queryByRole('region')).not.toBeInTheDocument();
+    expect(getPanel()).not.toHaveAttribute('role');
   });
 });

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

@@ -3,7 +3,7 @@ import { Popover } from './Popover';
 import { Button } from '../Button/Button';
 
 const meta = {
-  title: 'Interaction/Popover',
+  title: 'React/Interaction/Popover',
   component: Popover,
   argTypes: {
     placement: { control: 'radio', options: ['top', 'bottom', 'left', 'right'] },

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

@@ -8,14 +8,27 @@ import {
   useRef,
   useState,
 } from 'react';
+import { installInvokerCommandsPolyfill } from '../../../polyfill-invoker-commands';
+
+// Install once at module load — no-op if native support is present.
+installInvokerCommandsPolyfill();
+
 import css from './Popover.module.css';
 import { cn } from '@boostdev/design-system-foundation';
+import type { WithClassName } from '../../../types';
 
-interface PopoverProps {
+// Load the CSS Anchor Positioning polyfill once, only in browsers that need it.
+if (
+  typeof window !== 'undefined' &&
+  !(typeof CSS !== 'undefined' && typeof CSS.supports === 'function' && CSS.supports('anchor-name: --a'))
+) {
+  import('@oddbird/css-anchor-positioning').catch(() => {});
+}
+
+interface PopoverProps extends WithClassName {
   children: ReactElement;
   content: ReactNode;
   placement?: 'top' | 'bottom' | 'left' | 'right';
-  className?: string;
   'aria-label'?: string;
 }
 
@@ -28,54 +41,81 @@ export function Popover({
 }: Readonly<PopoverProps>) {
   const [isOpen, setIsOpen] = useState(false);
   const containerRef = useRef<HTMLSpanElement>(null);
-  const panelId = useId();
+  const panelRef = useRef<HTMLDivElement>(null);
+  const rawId = useId();
+  // CSS anchor-name must be a valid custom-ident: strip non-word characters.
+  const anchorName = `--popover-${rawId.replace(/\W/g, '') || 'a'}`;
+  const panelId = rawId;
 
+  // Sync isOpen state via the popover toggle event (fires on both native and
+  // polyfilled open/close, including light-dismiss and Escape).
   useEffect(() => {
-    if (!isOpen) return;
+    const panel = panelRef.current;
+    if (!panel) return;
+    const handleToggle = (e: Event) => {
+      setIsOpen((e as ToggleEvent).newState === 'open');
+    };
+    panel.addEventListener('toggle', handleToggle);
+    return () => panel.removeEventListener('toggle', handleToggle);
+  }, []);
 
-    const handlePointerDown = (e: PointerEvent) => {
-      if (!containerRef.current?.contains(e.target as Node)) {
-        setIsOpen(false);
+  // Close the popover when the anchor scrolls out of the viewport.
+  // Light-dismiss (outside click) and Escape are handled natively by popover="auto".
+  useEffect(() => {
+    if (!isOpen) return;
+    const handleScroll = () => {
+      const rect = containerRef.current?.getBoundingClientRect();
+      if (!rect) return;
+      const { innerWidth: vw, innerHeight: vh } = window;
+      if (rect.bottom < 0 || rect.top > vh || rect.right < 0 || rect.left > vw) {
+        panelRef.current?.hidePopover();
       }
     };
-    const handleKeyDown = (e: KeyboardEvent) => {
-      if (e.key === 'Escape') setIsOpen(false);
-    };
-
-    document.addEventListener('pointerdown', handlePointerDown);
-    document.addEventListener('keydown', handleKeyDown);
+    window.addEventListener('scroll', handleScroll, { capture: true, passive: true });
+    window.addEventListener('resize', handleScroll, { passive: true });
     return () => {
-      document.removeEventListener('pointerdown', handlePointerDown);
-      document.removeEventListener('keydown', handleKeyDown);
+      window.removeEventListener('scroll', handleScroll, { capture: true });
+      window.removeEventListener('resize', handleScroll);
     };
   }, [isOpen]);
 
+  // Inject invoker command attrs and accessibility props onto the trigger.
+  // commandfor/command="toggle-popover" replaces the onClick toggle handler —
+  // the browser (or polyfill) calls togglePopover() on the panel, which fires
+  // the toggle event above to sync state.
   const trigger = isValidElement(children)
     ? cloneElement(children as ReactElement<Record<string, unknown>>, {
         'aria-expanded': isOpen,
         'aria-controls': panelId,
         'aria-haspopup': true,
-        onClick: (e: MouseEvent) => {
-          setIsOpen(prev => !prev);
-          const existingOnClick = (children.props as Record<string, unknown>).onClick;
-          if (typeof existingOnClick === 'function') existingOnClick(e);
+        commandfor: panelId,
+        command: 'toggle-popover',
+        style: {
+          ...((children.props as Record<string, unknown>).style as object | undefined),
+          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,
       })
     : children;
 
   return (
     <span ref={containerRef} className={cn(css.wrapper, className)}>
       {trigger}
-      {isOpen && (
-        <div
-          id={panelId}
-          role={ariaLabel ? 'region' : undefined}
-          aria-label={ariaLabel}
-          className={cn(css.panel, css[`--placement_${placement}`])}
-        >
-          {content}
-        </div>
-      )}
+      <div
+        ref={panelRef}
+        id={panelId}
+        popover="auto"
+        data-placement={placement}
+        role={ariaLabel ? 'region' : undefined}
+        aria-label={ariaLabel}
+        className={css.panel}
+        style={{ positionAnchor: anchorName }}
+      >
+        {content}
+      </div>
     </span>
   );
 }

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

@@ -2,7 +2,7 @@ import type { Meta, StoryObj } from '@storybook/react';
 import { Rating } from './Rating';
 
 const meta = {
-  title: 'Interaction/Rating',
+  title: 'React/Interaction/Rating',
   component: Rating,
   argTypes: {
     value: { control: { type: 'range', min: 0, max: 5, step: 1 } },

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

@@ -1,10 +1,10 @@
 import css from './Rating.module.css';
 import { cn } from '@boostdev/design-system-foundation';
+import type { WithClassName } from '../../../types';
 
-interface RatingProps {
+interface RatingProps extends WithClassName {
   value: number;
   max?: number;
-  className?: string;
 }
 
 export function Rating({ value, max = 5, className }: RatingProps) {

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

@@ -1,12 +1,17 @@
 @layer component {
   .toastContainer {
     position: fixed;
-    bottom: var(--bds-space_xl);
-    right: var(--bds-space_xl);
+    inset: unset; /* override UA popover default (inset: 0) */
+    inset-block-end: var(--bds-space_xl);
+    inset-inline-end: var(--bds-space_xl);
     display: flex;
     flex-direction: column;
     gap: var(--bds-space_m);
-    z-index: var(--bds-z-index_toast);
+
+    /* z-index removed — top layer renders above all fixed/sticky elements */
+    border: none; /* override UA popover default */
+    padding: 0; /* override UA popover default */
+    background: transparent; /* override UA popover default */
   }
 
   .toast {
@@ -18,7 +23,7 @@
     display: flex;
     align-items: center;
     gap: var(--bds-space_m);
-    min-width: 300px;
+    min-inline-size: 300px;
     animation: slideIn var(--bds-animation_duration--fast) var(--bds-animation_easing);
   }
 
@@ -51,8 +56,8 @@
     align-items: center;
     justify-content: center;
     flex-shrink: 0;
-    width: 1.25rem;
-    height: 1.25rem;
+    inline-size: 1.25rem;
+    block-size: 1.25rem;
     padding: 0;
     background: none;
     border: none;
@@ -61,8 +66,8 @@
   }
 
   .closeButton svg {
-    width: 1rem;
-    height: 1rem;
+    inline-size: 1rem;
+    block-size: 1rem;
   }
 }
 

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

@@ -32,6 +32,27 @@ describe('Toast', () => {
     vi.useRealTimers();
   });
 
+  it('renders the toast container as a manual popover', () => {
+    render(
+      <ToastProvider>
+        <div />
+      </ToastProvider>
+    );
+    const container = document.querySelector('[popover]');
+    expect(container).toHaveAttribute('popover', 'manual');
+  });
+
+  it('renders the toast container as a labelled notifications region', () => {
+    render(
+      <ToastProvider>
+        <div />
+      </ToastProvider>
+    );
+    const container = document.querySelector('[popover="manual"]');
+    expect(container).toHaveAttribute('role', 'region');
+    expect(container).toHaveAttribute('aria-label', 'Notifications');
+  });
+
   it('throws when useToast is used outside ToastProvider', () => {
     const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
     const Bad = () => { useToast(); return null; };

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

@@ -3,7 +3,7 @@ import { ToastProvider, useToast } from './Toast';
 import { Button } from '../Button/Button';
 
 const meta = {
-  title: 'Interaction/Toast',
+  title: 'React/Interaction/Toast',
   component: ToastProvider,
 } satisfies Meta<typeof ToastProvider>;