@webjsdev/ui 0.3.5 → 0.3.7

package/packages/registry/components/dropdown-menu.ts

@@ -55,6 +55,9 @@
  *   `type`:    omit (default) | "checkbox" | "radio".
  *   `checked`: boolean. Applies to checkbox / radio items.
  *   `value`:   string. Identifier for radio items.
+ *   `data-disabled`: boolean. Skips keyboard focus and activation, dims the
+ *                    item, and sets aria-disabled. Same attribute on a
+ *                    <ui-dropdown-menu-sub-trigger> disables the submenu.
  *
  * Events:
  *   `ui-open-change` on <ui-dropdown-menu>: `{ detail: { open } }` after a transition.
@@ -74,7 +77,8 @@
  * Design tokens used: --popover, --popover-foreground, --accent,
  * --accent-foreground, --destructive, --muted-foreground, --border.
  */
-import { WebComponent, html, unsafeHTML, signal } from '@webjsdev/core';
+import { WebComponent, html, unsafeHTML, signal, prop } from '@webjsdev/core';
+import { ensureId, onBeforeCache } from '../lib/utils.ts';
 import { positionFloating, type PopoverSide, type PopoverAlign } from './popover.ts';
 
 // --------------------------------------------------------------------------
@@ -116,12 +120,9 @@ const SUB_CLOSE_DELAY = 200;
 // <ui-dropdown-menu>
 // --------------------------------------------------------------------------
 
-export class UiDropdownMenu extends WebComponent {
-  static properties = {
-    open: { type: Boolean, reflect: true },
-  };
-  declare open: boolean;
-
+export class UiDropdownMenu extends WebComponent({
+  open: prop(Boolean, { reflect: true }),
+}) {
   _typeBuffer = '';
   _typeBufferTimer: number | undefined;
 
@@ -134,8 +135,11 @@ export class UiDropdownMenu extends WebComponent {
     this.open = false;
   }
 
+  _disposeBeforeCache?: () => void;
+
   disconnectedCallback(): void {
     if (this.open) this._teardown();
+    this._disposeBeforeCache?.();
     super.disconnectedCallback?.();
   }
 
@@ -156,15 +160,61 @@ export class UiDropdownMenu extends WebComponent {
     queueMicrotask(() => this._afterRender());
   }
 
+  connectedCallback(): void {
+    super.connectedCallback?.();
+    // webjs projects slotted light-DOM children in a pass after the first
+    // render, so the trigger button and the menu are not in place at
+    // connect. Defer to the next frame, when the projection has run.
+    if (typeof requestAnimationFrame === 'function') {
+      requestAnimationFrame(() => this._wireAria());
+    }
+    // Close (and tear down) before a back/forward snapshot so the menu does not
+    // restore open (#766). Closing the root also hides any open submenu.
+    this._disposeBeforeCache = onBeforeCache(() => { this.open = false; });
+  }
+
   _afterRender(): void {
     const content = this._content();
     if (content) {
       this._syncContentPopover(content);
     }
+    this._wireAria();
     if (this.open) this._setup();
     else this._teardown();
   }
 
+  // The trigger wraps an author-supplied control (usually a <button>). Expose
+  // the menu relationship on that focusable control: aria-haspopup announces
+  // it opens a menu, aria-expanded tracks open state, aria-controls points at
+  // the menu, and the menu is labelled back by the trigger. Done at runtime
+  // because the menu is JS-driven (never shown without script).
+  _triggerControl(): HTMLElement | null {
+    const trigger = this.querySelector('ui-dropdown-menu-trigger');
+    if (!trigger) return null;
+    return (
+      trigger.querySelector<HTMLElement>('button, [role="button"], a[href], [tabindex]') ??
+      (trigger as HTMLElement)
+    );
+  }
+
+  _menuEl(): HTMLElement | null {
+    return this.querySelector('ui-dropdown-menu-content [role="menu"]');
+  }
+
+  _wireAria(): void {
+    const control = this._triggerControl();
+    if (!control) return;
+    control.setAttribute('aria-haspopup', 'menu');
+    control.setAttribute('aria-expanded', String(this.open));
+    const menu = this._menuEl();
+    if (!menu) return;
+    const menuId = ensureId(menu, 'ui-menu');
+    control.setAttribute('aria-controls', menuId);
+    if (!menu.hasAttribute('aria-label') && !menu.hasAttribute('aria-labelledby')) {
+      menu.setAttribute('aria-labelledby', ensureId(control, 'ui-menu-trigger'));
+    }
+  }
+
   _content(): HTMLElement | null {
     return this.querySelector('ui-dropdown-menu-content [popover]');
   }
@@ -329,6 +379,7 @@ export class UiDropdownMenuContent extends WebComponent {
     return html`<div
       data-slot="dropdown-menu-content"
       role="menu"
+      aria-orientation="vertical"
       popover="manual"
       class=${dropdownMenuContentClass()}
     ><slot></slot></div>`;
@@ -340,14 +391,10 @@ UiDropdownMenuContent.register('ui-dropdown-menu-content');
 // <ui-dropdown-menu-item>
 // --------------------------------------------------------------------------
 
-export class UiDropdownMenuItem extends WebComponent {
-  static properties = {
-    variant: { type: String, reflect: true },
-    inset: { type: Boolean },
-  };
-  declare variant: 'default' | 'destructive';
-  declare inset: boolean;
-
+export class UiDropdownMenuItem extends WebComponent({
+  variant: prop<'default' | 'destructive'>(String, { reflect: true }),
+  inset: Boolean,
+}) {
   // Keyboard / pointer highlight state for the own-rendered menuitem. A
   // local signal bound with ?data-highlighted keeps the highlight in the
   // declarative template instead of an imperative setAttribute on
@@ -361,12 +408,19 @@ export class UiDropdownMenuItem extends WebComponent {
   }
 
   render() {
+    // `data-disabled` on the host is the historical disabled marker (focus
+    // skips it, the click / pointer handlers bail on it). Mirror it onto the
+    // inner menuitem as both data-disabled (CSS) and aria-disabled, so the
+    // state also reaches assistive tech.
+    const disabled = typeof this.hasAttribute === 'function' && this.hasAttribute('data-disabled');
     return html`<div
       data-slot="dropdown-menu-item"
       role="menuitem"
       tabindex="-1"
       data-variant=${this.variant}
       ?data-inset=${this.inset}
+      ?data-disabled=${disabled}
+      aria-disabled=${disabled ? 'true' : 'false'}
       ?data-highlighted=${this.#highlighted.get()}
       class=${dropdownMenuItemClass()}
       @click=${this._onClick}
@@ -402,10 +456,7 @@ UiDropdownMenuItem.register('ui-dropdown-menu-item');
 // <ui-dropdown-menu-label>
 // --------------------------------------------------------------------------
 
-export class UiDropdownMenuLabel extends WebComponent {
-  static properties = { inset: { type: Boolean } };
-  declare inset: boolean;
-
+export class UiDropdownMenuLabel extends WebComponent({ inset: Boolean }) {
   constructor() {
     super();
     this.inset = false;
@@ -468,12 +519,9 @@ UiDropdownMenuGroup.register('ui-dropdown-menu-group');
 // Submenu: Sub / SubTrigger / SubContent
 // --------------------------------------------------------------------------
 
-export class UiDropdownMenuSub extends WebComponent {
-  static properties = {
-    open: { type: Boolean, reflect: true },
-  };
-  declare open: boolean;
-
+export class UiDropdownMenuSub extends WebComponent({
+  open: prop(Boolean, { reflect: true }),
+}) {
   _closeTimer: number | undefined;
 
   constructor() {
@@ -522,7 +570,13 @@ export class UiDropdownMenuSub extends WebComponent {
   }
 
   _cancelCloseHandler = (): void => this._cancelClose();
-  _scheduleCloseHandler = (): void => this._scheduleClose();
+  // Hover-close is a mouse affordance. On touch, lifting the finger fires
+  // pointerleave; without this guard a tap-opened submenu would close itself
+  // ~200ms after the tap. On touch the submenu stays open until tapped again.
+  _scheduleCloseHandler = (e: Event): void => {
+    if ((e as PointerEvent).pointerType === 'touch') return;
+    this._scheduleClose();
+  };
 
   _scheduleClose(): void {
     this._cancelClose();
@@ -555,10 +609,7 @@ export class UiDropdownMenuSub extends WebComponent {
 }
 UiDropdownMenuSub.register('ui-dropdown-menu-sub');
 
-export class UiDropdownMenuSubTrigger extends WebComponent {
-  static properties = { inset: { type: Boolean } };
-  declare inset: boolean;
-
+export class UiDropdownMenuSubTrigger extends WebComponent({ inset: Boolean }) {
   constructor() {
     super();
     this.inset = false;
@@ -572,14 +623,17 @@ export class UiDropdownMenuSubTrigger extends WebComponent {
 
   render() {
     const open = !!this._sub()?.open;
+    const disabled = typeof this.hasAttribute === 'function' && this.hasAttribute('data-disabled');
     return html`<div
       data-slot="dropdown-menu-sub-trigger"
       role="menuitem"
       tabindex="-1"
       aria-haspopup="menu"
       aria-expanded=${String(open)}
+      aria-disabled=${disabled ? 'true' : 'false'}
       data-state=${open ? 'open' : 'closed'}
       ?data-inset=${this.inset}
+      ?data-disabled=${disabled}
       class=${dropdownMenuSubTriggerClass()}
       @click=${this._onClick}
       @pointerenter=${this._onPointerEnter}
@@ -593,6 +647,10 @@ export class UiDropdownMenuSubTrigger extends WebComponent {
   };
 
   _onPointerEnter = (e: Event): void => {
+    // Hover-open is a mouse affordance. On touch there is no hover: a tap
+    // fires pointerenter on finger-down, which would open the submenu only for
+    // the following click to toggle it shut. On touch, @click is the opener.
+    if ((e as PointerEvent).pointerType === 'touch') return;
     const el = e.currentTarget as HTMLElement;
     if (el.hasAttribute('data-disabled')) return;
     el.focus();
@@ -606,6 +664,7 @@ export class UiDropdownMenuSubContent extends WebComponent {
     return html`<div
       data-slot="dropdown-menu-sub-content"
       role="menu"
+      aria-orientation="vertical"
       popover="manual"
       class=${dropdownMenuSubContentClass()}
     ><slot></slot></div>`;

package/packages/registry/components/hover-card.ts

@@ -38,7 +38,8 @@
  *
  * Design tokens used: --popover, --popover-foreground, --border.
  */
-import { WebComponent, html } from '@webjsdev/core';
+import { WebComponent, html, prop } from '@webjsdev/core';
+import { ensureId, onBeforeCache } from '../lib/utils.ts';
 import { positionFloating, type PopoverSide, type PopoverAlign } from './popover.ts';
 
 // `fixed m-0` opts out of the UA `[popover]` auto-centering margin so
@@ -52,18 +53,13 @@ export const hoverCardContentClass = (): string =>
 // <ui-hover-card>
 // --------------------------------------------------------------------------
 
-export class UiHoverCard extends WebComponent {
-  static properties = {
-    open: { type: Boolean, reflect: true },
-    openDelay: { type: Number },
-    closeDelay: { type: Number },
-  };
-  declare open: boolean;
+export class UiHoverCard extends WebComponent({
+  open: prop(Boolean, { reflect: true }),
   // `openDelay` / `closeDelay` ride the `open-delay` / `close-delay`
   // attributes (shadcn parity), read as typed props.
-  declare openDelay: number;
-  declare closeDelay: number;
-
+  openDelay: Number,
+  closeDelay: Number,
+}) {
   _showTimer: number | undefined;
   _hideTimer: number | undefined;
 
@@ -74,6 +70,47 @@ export class UiHoverCard extends WebComponent {
     this.closeDelay = 300;
   }
 
+  _disposeBeforeCache?: () => void;
+
+  connectedCallback(): void {
+    super.connectedCallback?.();
+    // webjs projects slotted light-DOM children after the first render, so
+    // the trigger control is not in place at connect. Defer to the next
+    // frame, when the projection has run.
+    if (typeof requestAnimationFrame === 'function') {
+      requestAnimationFrame(() => this._wireAria());
+    }
+    // Close before the page is cached for back/forward so a restored snapshot
+    // does not come back frozen open (#766).
+    this._disposeBeforeCache = onBeforeCache(() => { this.open = false; });
+  }
+
+  disconnectedCallback(): void {
+    this._disposeBeforeCache?.();
+    super.disconnectedCallback?.();
+  }
+
+  // The trigger also opens on focus (see the @focusin handler), so it is
+  // keyboard-reachable: expose the popup relationship on the focusable
+  // control. aria-expanded is refreshed on every open transition.
+  _control(): HTMLElement | null {
+    const t = this.querySelector('ui-hover-card-trigger');
+    if (!t) return null;
+    return (
+      t.querySelector<HTMLElement>('a[href], button, [tabindex], [role="button"]') ??
+      (t as HTMLElement)
+    );
+  }
+
+  _wireAria(): void {
+    const control = this._control();
+    if (!control) return;
+    control.setAttribute('aria-haspopup', 'dialog');
+    control.setAttribute('aria-expanded', String(this.open));
+    const content = this.querySelector<HTMLElement>('ui-hover-card-content [role="dialog"]');
+    if (content) control.setAttribute('aria-controls', ensureId(content, 'ui-hovercard'));
+  }
+
   // Back-compat getter.
   get isOpen(): boolean { return this.open; }
 
@@ -87,6 +124,25 @@ export class UiHoverCard extends WebComponent {
     this._hideTimer = window.setTimeout(() => { this.open = false; }, this.closeDelay);
   }
 
+  // Touch open: there is no hover delay and no mouseleave to close it, so open
+  // immediately and arm a one-shot outside-tap dismiss (a tap anywhere outside
+  // this card closes it). Deferred a tick so the opening tap itself does not
+  // immediately dismiss it.
+  openByTouch(): void {
+    clearTimeout(this._showTimer);
+    clearTimeout(this._hideTimer);
+    this.open = true;
+    const onOutside = (ev: Event): void => {
+      // Close on an outside tap; also self-remove if the card was already
+      // closed by other means (a re-tap toggle), so the listener never lingers.
+      if (!this.open || !this.contains(ev.target as Node)) {
+        this.open = false;
+        document.removeEventListener('pointerdown', onOutside, true);
+      }
+    };
+    setTimeout(() => document.addEventListener('pointerdown', onOutside, true), 0);
+  }
+
   render() {
     return html`<div
       data-slot="hover-card"
@@ -98,8 +154,12 @@ export class UiHoverCard extends WebComponent {
     if (!changedProperties.has('open')) return;
     if (changedProperties.get('open') === undefined) return;
     // Wait one microtask for <ui-hover-card-content>'s inner [popover]
-    // element to commit; we drive its showPopover() / hidePopover().
-    queueMicrotask(() => this._syncContent());
+    // element to commit; we drive its showPopover() / hidePopover() and
+    // refresh the trigger's aria-expanded.
+    queueMicrotask(() => {
+      this._wireAria();
+      this._syncContent();
+    });
   }
 
   _syncContent(): void {
@@ -148,11 +208,41 @@ export class UiHoverCardTrigger extends WebComponent {
       @mouseleave=${this._onLeave}
       @focusin=${this._onEnter}
       @focusout=${this._onLeave}
+      @click=${this._onClick}
     ><slot></slot></div>`;
   }
 
-  _onEnter = (): void => (this.closest('ui-hover-card') as UiHoverCard | null)?.show();
-  _onLeave = (): void => (this.closest('ui-hover-card') as UiHoverCard | null)?.hide();
+  // Hover/focus open + close are MOUSE affordances. On a no-hover (touch)
+  // device, iOS Safari still fires SYNTHETIC mouseenter/mouseleave (and
+  // focusin/focusout from the inner link) around a tap, which would otherwise
+  // immediately re-close a tap-opened card. Gate the hover handlers to pointer
+  // devices so on touch the card is driven only by the tap path (#745).
+  _noHover = (): boolean => !!window.matchMedia?.('(hover: none)').matches;
+  _onEnter = (): void => {
+    if (this._noHover()) return;
+    (this.closest('ui-hover-card') as UiHoverCard | null)?.show();
+  };
+  _onLeave = (): void => {
+    if (this._noHover()) return;
+    (this.closest('ui-hover-card') as UiHoverCard | null)?.hide();
+  };
+
+  // Touch path. A touch device has no `mouseenter`, so a tap would fall through
+  // to the inner `<a href>` and navigate. On a no-hover device the trigger tap
+  // TOGGLES the card and NEVER navigates (the real link is reachable inside the
+  // opened card). It must ALWAYS preventDefault, including while open: the
+  // client router pushState()s on any bubble-phase `<a>` click that is not
+  // defaultPrevented, so a re-tap that fell through would push a history entry
+  // every time and Back would need N presses (#745).
+  _onClick = (e: Event): void => {
+    if (!window.matchMedia?.('(hover: none)').matches) return;
+    const card = this.closest('ui-hover-card') as UiHoverCard | null;
+    if (!card) return;
+    e.preventDefault();
+    e.stopPropagation();
+    if (card.open) card.open = false;
+    else card.openByTouch();
+  };
 }
 UiHoverCardTrigger.register('ui-hover-card-trigger');
 
@@ -175,7 +265,19 @@ export class UiHoverCardContent extends WebComponent {
     ><slot></slot></div>`;
   }
 
-  _onEnter = (): void => (this.closest('ui-hover-card') as UiHoverCard | null)?.show();
-  _onLeave = (): void => (this.closest('ui-hover-card') as UiHoverCard | null)?.hide();
+  // Hover/focus open + close are MOUSE affordances. On a no-hover (touch)
+  // device, iOS Safari still fires SYNTHETIC mouseenter/mouseleave (and
+  // focusin/focusout from the inner link) around a tap, which would otherwise
+  // immediately re-close a tap-opened card. Gate the hover handlers to pointer
+  // devices so on touch the card is driven only by the tap path (#745).
+  _noHover = (): boolean => !!window.matchMedia?.('(hover: none)').matches;
+  _onEnter = (): void => {
+    if (this._noHover()) return;
+    (this.closest('ui-hover-card') as UiHoverCard | null)?.show();
+  };
+  _onLeave = (): void => {
+    if (this._noHover()) return;
+    (this.closest('ui-hover-card') as UiHoverCard | null)?.hide();
+  };
 }
 UiHoverCardContent.register('ui-hover-card-content');

package/packages/registry/components/pagination.ts

@@ -23,6 +23,11 @@
  *     </ul>
  *   </nav>
  *
+ * A11y (required for accessible output): wrap the list in <nav
+ * aria-label="pagination">, set aria-current="page" on the active page
+ * link, give an icon-only Previous / Next control an aria-label, and mark
+ * the ellipsis aria-hidden="true". The class helpers emit none of these.
+ *
  * Design tokens used: inherited from buttonClass.
  */
 import { cn } from '../lib/utils.ts';

package/packages/registry/components/progress.ts

@@ -16,6 +16,11 @@
  *   <!-- Indeterminate (no `value` attribute): -->
  *   <progress class=${progressClass()}></progress>
  *
+ * A11y (required for accessible output): give the <progress> an accessible
+ * name with aria-label (or a <label for>), e.g. aria-label="Upload
+ * progress". The native element supplies the role and value; only the name
+ * is the author's responsibility.
+ *
  * Design tokens used: --primary.
  */
 

package/packages/registry/components/separator.ts

@@ -13,6 +13,11 @@
  *        class=${separatorClass({ orientation: 'vertical' })}
  *        data-orientation="vertical"></div>
  *
+ * A11y (required for accessible output): a meaningful divider needs
+ * role="separator" plus aria-orientation. A purely decorative one needs
+ * role="none" (or aria-hidden="true") so assistive tech does not announce
+ * an empty separator.
+ *
  * Design tokens used: --border.
  */
 import { cn } from '../lib/utils.ts';

package/packages/registry/components/skeleton.ts

@@ -10,6 +10,11 @@
  *   <div class=${cn(skeletonClass(), 'h-4 w-32')}></div>
  *   <div class=${cn(skeletonClass(), 'h-12 w-12 rounded-full')}></div>
  *
+ * A11y (required for accessible output): a skeleton is a decorative
+ * placeholder, so hide it from assistive tech with aria-hidden="true" (or
+ * mark the loading region aria-busy="true"). Announce the real content
+ * once it replaces the skeleton.
+ *
  * Design tokens used: --accent.
  */
 

package/packages/registry/components/sonner.ts

@@ -43,7 +43,8 @@
  *
  * Design tokens used: --popover, --popover-foreground, --border, --radius.
  */
-import { WebComponent, html, repeat, unsafeHTML, signal } from '@webjsdev/core';
+import { WebComponent, html, repeat, unsafeHTML, signal, prop } from '@webjsdev/core';
+import { onBeforeCache } from '../lib/utils.ts';
 
 type ToastType = 'default' | 'success' | 'error' | 'info' | 'warning' | 'loading';
 
@@ -61,13 +62,28 @@ interface ToastItem extends ToastOptions {
 }
 
 let nextId = 1;
-const toaster: { add(t: ToastItem): void; remove(id: string | number): void } = {
-  add() {},
-  remove() {},
-};
+
+interface ToastBus {
+  add(t: ToastItem): void;
+  remove(id: string | number): void;
+}
+
+// The toast bus lives on `globalThis`, NOT in module scope, so the global
+// `toast()` still reaches a mounted <ui-sonner> when the module is loaded
+// under two different URLs. The app registers the element from the
+// version-hashed `sonner.ts?v=<hash>` (asset-hash, #243), while a caller may
+// do a bare `import('/components/ui/sonner.ts')`: those are distinct module
+// instances with distinct module-scope state, but they share one `window`.
+// Last-mounted viewport wins (it overwrites `bus().add`), matching the prior
+// singleton semantics. Without this, toasts published from a different module
+// instance silently went to a no-op bus (#745).
+function bus(): ToastBus {
+  const g = globalThis as unknown as { __webjsSonnerBus?: ToastBus };
+  return (g.__webjsSonnerBus ??= { add() {}, remove() {} });
+}
 
 function publish(item: ToastItem): string | number {
-  toaster.add(item);
+  bus().add(item);
   return item.id;
 }
 
@@ -92,7 +108,7 @@ toast.warning = (msg: string, o?: ToastOptions) => makeToast(msg, o, 'warning');
 toast.loading = (msg: string, o?: ToastOptions) => makeToast(msg, o, 'loading');
 toast.dismiss = (id?: string | number) => {
   if (id == null) return;
-  toaster.remove(id);
+  bus().remove(id);
 };
 toast.promise = <T,>(p: Promise<T>, opts: { loading: string; success: string; error: string }) => {
   const id = toast.loading(opts.loading);
@@ -134,31 +150,45 @@ const TYPE_ICON_COLOR: Record<ToastType, string> = {
   loading: 'text-muted-foreground',
 };
 
-export class UiSonner extends WebComponent {
-  static properties = {
-    position: { type: String, reflect: true },
-  };
-  declare position: SonnerPosition;
+export class UiSonner extends WebComponent({
+  position: prop<SonnerPosition>(String, { reflect: true }),
+}) {
   items = signal<ToastItem[]>([]);
 
+  _disposeBeforeCache?: () => void;
+
   constructor() {
     super();
     this.position = 'bottom-right';
   }
 
+  connectedCallback(): void {
+    super.connectedCallback?.();
+    // Clear pending toasts before a back/forward snapshot so a restored page
+    // does not show stale toasts that should have auto-dismissed (#766).
+    this._disposeBeforeCache = onBeforeCache(() => this.items.set([]));
+  }
+
+  disconnectedCallback(): void {
+    this._disposeBeforeCache?.();
+    super.disconnectedCallback?.();
+  }
+
   // Routing the global toast() function to this viewport. Runs in
   // firstUpdated rather than the constructor because tests can mount
   // multiple <ui-sonner> instances and the most recently mounted wins
-  // (matches the existing semantics).
+  // (matches the existing semantics). The bus lives on globalThis so this
+  // routing is visible to a toast() called from another module instance.
   firstUpdated(): void {
-    toaster.add = (t) => this._add(t);
-    toaster.remove = (id) => this._remove(id);
+    const b = bus();
+    b.add = (t) => this._add(t);
+    b.remove = (id) => this._remove(id);
   }
 
   /**
    * Publish a toast directly to THIS viewport. Use when you have a
-   * specific <ui-sonner> reference and want to bypass the singleton
-   * `toaster.add` routing (which always points to the last-mounted
+   * specific <ui-sonner> reference and want to bypass the global
+   * `bus().add` routing (which always points to the last-mounted
    * viewport). Primary use case: docs demos that mount one viewport
    * per position and want each demo button to fire into its own
    * viewport. App code should normally call the global `toast()` /
@@ -190,8 +220,18 @@ export class UiSonner extends WebComponent {
 
   render() {
     const pos = POSITIONS[this.position] ?? POSITIONS['bottom-right'];
+    // The container is a persistent live region: it is in the DOM from the
+    // first render (even with zero toasts), so a screen reader announces
+    // each toast as it is inserted. It defaults to polite; an `error` toast
+    // carries its own role="alert" (assertive) and that innermost live
+    // region wins for that item.
     return html`<div
       data-slot="sonner"
+      role="region"
+      aria-label="Notifications"
+      aria-live="polite"
+      aria-relevant="additions text"
+      aria-atomic="false"
       class=${`pointer-events-none fixed z-[100] flex flex-col gap-2 ${pos}`}
     >
       ${repeat(

package/packages/registry/components/table.ts

@@ -18,8 +18,8 @@
  *     <table class=${tableClass()}>
  *       <thead class=${tableHeaderClass()}>
  *         <tr class=${tableRowClass()}>
- *           <th class=${tableHeadClass()}>Name</th>
- *           <th class=${tableHeadClass()}>Status</th>
+ *           <th scope="col" class=${tableHeadClass()}>Name</th>
+ *           <th scope="col" class=${tableHeadClass()}>Status</th>
  *         </tr>
  *       </thead>
  *       <tbody class=${tableBodyClass()}>
@@ -32,6 +32,11 @@
  *     </table>
  *   </div>
  *
+ * A11y (required for accessible output): every header cell needs a scope
+ * (scope="col" on a column header, scope="row" on a row header) so screen
+ * readers map cells to their headers. Add a <caption> naming the table's
+ * purpose (it can be visually hidden if a heading already names it).
+ *
  * Design tokens used: --muted, --muted-foreground, --foreground.
  */