@webjsdev/ui 0.3.10 → 0.3.12

package/packages/registry/components/sonner.ts

@@ -22,6 +22,7 @@
  *   `duration`:    ms, default 4000 (loading toasts default to 0, no auto-dismiss).
  *   `action`:      { label, onClick } | undefined. Renders an action button.
  *   `cancel`:      { label, onClick } | undefined. Renders a cancel button.
+ *                  Both buttons dismiss the toast after running their onClick.
  *
  * Events: none dispatched (consumers act on the id returned by `toast()`).
  *
@@ -29,6 +30,17 @@
  * per-instance dispatch (bypasses the singleton router that `toast()`
  * uses); typically only needed when mounting multiple viewports.
  *
+ * A11y (owned by the element, nothing to supply):
+ *   The viewport is a persistent `aria-live="polite"` region labelled
+ *   "Notifications", so a toast is announced as it is inserted; an `error`
+ *   toast carries `role="alert"` so it is announced assertively. Every toast
+ *   also ships a labelled close button, so a toast can always be dismissed by
+ *   hand rather than only by its timer or a programmatic `toast.dismiss(id)`.
+ *   That matters most for a toast that never auto-dismisses, which
+ *   `toast.loading()` is by default (`duration: 0`) and which was otherwise
+ *   impossible to get rid of from the UI. Each toast's icon is decorative and
+ *   aria-hidden; the meaning is in the text and the role.
+ *
  * Design tokens used: --popover, --popover-foreground, --border, --radius.
  *
  * @example
@@ -44,6 +56,12 @@
  *   toast.error('Failed to save', { description: 'Try again' });
  *   toast.promise(savePost(), { loading: 'Saving', success: 'Saved', error: 'Failed' });
  *   toast.dismiss(id);
+ *
+ *   // action and cancel buttons; each dismisses the toast after its onClick.
+ *   toast('Post deleted', {
+ *     action: { label: 'Undo', onClick: () => restorePost() },
+ *     cancel: { label: 'Dismiss', onClick: () => {} },
+ *   });
  * </script>
  * ```
  */
@@ -57,6 +75,7 @@ interface ToastOptions {
   description?: string;
   duration?: number;
   action?: { label: string; onClick: () => void };
+  cancel?: { label: string; onClick: () => void };
 }
 
 interface ToastItem extends ToastOptions {
@@ -99,6 +118,7 @@ function makeToast(message: string, opts: ToastOptions = {}, type: ToastType = '
     description: opts.description,
     duration: opts.duration ?? (type === 'loading' ? 0 : 4000),
     action: opts.action,
+    cancel: opts.cancel,
   });
 }
 
@@ -207,6 +227,7 @@ export class UiSonner extends WebComponent({
       description: opts.description,
       duration: opts.duration ?? (type === 'loading' ? 0 : 4000),
       action: opts.action,
+      cancel: opts.cancel,
     });
     return id;
   }
@@ -242,6 +263,7 @@ export class UiSonner extends WebComponent({
         this.items.get(),
         (item) => item.id,
         (item) => html`<div
+          data-slot="sonner-toast"
           class=${TOAST_ITEM_BASE}
           data-type=${item.type}
           role=${item.type === 'error' ? 'alert' : 'status'}
@@ -253,9 +275,21 @@ export class UiSonner extends WebComponent({
               ? html`<div class="mt-1 text-xs text-muted-foreground">${item.description}</div>`
               : ''}
           </div>
+          ${item.cancel
+            ? html`<button
+                type="button"
+                data-slot="sonner-cancel"
+                class="rounded-md px-2 py-1 text-xs font-medium text-muted-foreground hover:bg-accent"
+                @click=${() => {
+                  item.cancel!.onClick();
+                  this._remove(item.id);
+                }}
+              >${item.cancel.label}</button>`
+            : ''}
           ${item.action
             ? html`<button
                 type="button"
+                data-slot="sonner-action"
                 class="rounded-md px-2 py-1 text-xs font-medium hover:bg-accent"
                 @click=${() => {
                   item.action!.onClick();
@@ -263,6 +297,13 @@ export class UiSonner extends WebComponent({
                 }}
               >${item.action.label}</button>`
             : ''}
+          <button
+            type="button"
+            data-slot="sonner-close"
+            aria-label="Close notification"
+            class="shrink-0 rounded-md p-1 text-muted-foreground hover:bg-accent hover:text-foreground"
+            @click=${() => this._remove(item.id)}
+          >${unsafeHTML(CLOSE_SVG)}</button>
         </div>`,
       )}
     </div>`;
@@ -270,15 +311,22 @@ export class UiSonner extends WebComponent({
 }
 UiSonner.register('ui-sonner');
 
+// The close affordance's own glyph. Decorative: the button's accessible name
+// comes from its aria-label, so the icon must not be walked for a name.
+const CLOSE_SVG =
+  '<svg viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>';
+
+// Type glyphs, all decorative: the toast's text carries the meaning, and the
+// type is conveyed by role="alert" vs role="status", not by the picture.
 const ICONS: Record<ToastType, string> = {
   default: '',
   success:
-    '<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2"><polyline points="20 6 9 17 4 12"/></svg>',
+    '<svg aria-hidden="true" viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2"><polyline points="20 6 9 17 4 12"/></svg>',
   error:
-    '<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>',
-  info: '<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="10"/><line x1="12" y1="16" x2="12" y2="12"/><line x1="12" y1="8" x2="12.01" y2="8"/></svg>',
+    '<svg aria-hidden="true" viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>',
+  info: '<svg aria-hidden="true" viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="10"/><line x1="12" y1="16" x2="12" y2="12"/><line x1="12" y1="8" x2="12.01" y2="8"/></svg>',
   warning:
-    '<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2"><path d="M10.29 3.86 1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0z"/><line x1="12" y1="9" x2="12" y2="13"/><line x1="12" y1="17" x2="12.01" y2="17"/></svg>',
+    '<svg aria-hidden="true" viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2"><path d="M10.29 3.86 1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0z"/><line x1="12" y1="9" x2="12" y2="13"/><line x1="12" y1="17" x2="12.01" y2="17"/></svg>',
   loading:
-    '<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" class="animate-spin"><line x1="12" y1="2" x2="12" y2="6"/><line x1="12" y1="18" x2="12" y2="22"/><line x1="4.93" y1="4.93" x2="7.76" y2="7.76"/><line x1="16.24" y1="16.24" x2="19.07" y2="19.07"/><line x1="2" y1="12" x2="6" y2="12"/><line x1="18" y1="12" x2="22" y2="12"/></svg>',
+    '<svg aria-hidden="true" viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" class="animate-spin"><line x1="12" y1="2" x2="12" y2="6"/><line x1="12" y1="18" x2="12" y2="22"/><line x1="4.93" y1="4.93" x2="7.76" y2="7.76"/><line x1="16.24" y1="16.24" x2="19.07" y2="19.07"/><line x1="2" y1="12" x2="6" y2="12"/><line x1="18" y1="12" x2="22" y2="12"/></svg>',
 };

package/packages/registry/components/switch.ts

@@ -11,6 +11,22 @@
  * Design tokens used: --primary, --input, --background, --foreground, --ring,
  * --primary-foreground.
  *
+ * A11y (required for accessible output):
+ *   Keep `role="switch"` on the native checkbox. That is what makes a screen
+ *   reader announce "on / off" rather than "checked / unchecked", and the
+ *   browser maps the input's checked state to it for free.
+ *   NAME IT. The visible track is a `<span>` and the real control is `sr-only`,
+ *   so there is no text on the input at all. Wrapping the whole thing in a
+ *   `<label>` (the first example) is the simplest way, since the label's text
+ *   then names the input. A STANDALONE switch, one with no wrapping `<label>`
+ *   and no `<label for>` pointing at it, has NO accessible name and needs an
+ *   explicit `aria-label`, as the second example shows.
+ *   The visual track and thumb are presentation only. They carry no text and no
+ *   role, so nothing about the state reaches assistive tech through them: it all
+ *   comes from the input. Do not move the name onto the track.
+ *   Use `disabled` on the input, not on the track: the track styles itself from
+ *   the `peer-disabled:` variant, and only the real control can refuse input.
+ *
  * @example
  * ```html
  * <label class="inline-flex items-center gap-2">
@@ -19,8 +35,14 @@
  *   <span class=${labelClass()}>Notifications</span>
  * </label>
  *
+ * <!-- Standalone (no wrapping label), so the name has to be explicit. -->
+ * <input type="checkbox" role="switch" name="wifi" aria-label="Wi-Fi"
+ *        class=${switchInputClass()}>
+ * <span class=${switchTrackClass()}></span>
+ *
  * <!-- Small size. -->
- * <input type="checkbox" role="switch" name="x" class=${cn(switchInputClass(), 'peer/sm')}>
+ * <input type="checkbox" role="switch" name="x" aria-label="Compact mode"
+ *        class=${cn(switchInputClass(), 'peer/sm')}>
  * <span class=${switchTrackClass({ size: 'sm' })}></span>
  * ```
  */

package/packages/registry/components/tabs.ts

@@ -30,6 +30,21 @@
  *   Home / End               first / last
  *   Enter / Space            activate (native button activation)
  *
+ * A11y (owned by the element, nothing to supply beyond trigger names):
+ *   The element wires the whole APG Tabs pattern: the list is a
+ *   `role="tablist"` reporting `aria-orientation`, each trigger is a
+ *   `role="tab"` cross-linked to its panel with `aria-controls` while the panel
+ *   points back with `aria-labelledby`, ids stay unique across groups on one
+ *   page, and an inactive panel is both `hidden` and `inert`. Arrow / Home / End
+ *   move focus AND selection (APG automatic activation) via a roving tabindex,
+ *   so the tablist is a single Tab stop and nav stays inside its own group when
+ *   tabs are nested. Do not hand-add any of these; the element already has.
+ *   What you DO supply: a name for each trigger. A trigger's name comes from its
+ *   own content, so an icon-only tab needs an `aria-label` on the
+ *   `<ui-tabs-trigger>` and an `aria-hidden="true"` icon inside it.
+ *   Keep the panel's content after the tablist in the DOM, which the example
+ *   shape already does, so reading order follows the tab that was activated.
+ *
  * Design tokens used: --muted, --muted-foreground, --foreground, --background,
  * --input, --ring.
  *

package/packages/registry/components/textarea.ts

@@ -12,10 +12,29 @@
  * Design tokens used: --input, --background, --muted-foreground, --ring,
  * --destructive.
  *
+ * A11y (required for accessible output):
+ *   LABEL IT. A `<label class=${labelClass()} for="<the textarea's id">` linked
+ *   by the `for` / `id` pair is the whole requirement. The `placeholder` in the
+ *   old example was doing that job and cannot: it vanishes as soon as the user
+ *   types, and it is not reliably exposed as a name.
+ *   Point `aria-describedby` at a hint or a character counter that EXISTS on the
+ *   page, and on a validation failure set `aria-invalid="true"` plus an
+ *   `aria-describedby` error element so the reason is announced with the field.
+ *   If you show a live character count, put it in an `aria-live="polite"`
+ *   region, otherwise the number updates silently for a screen reader user.
+ *   Leave the textarea RESIZABLE. The class autosizes via `field-sizing:
+ *   content`, which is fine, but do not add `resize-none` on top: a user who
+ *   needs more room to read their own text has no other way to get it (WCAG
+ *   1.4.4-adjacent).
+ *
  * @example
  * ```html
- * <textarea class=${textareaClass()} name="message" rows="4" placeholder="Your message">
- * </textarea>
+ * <div class=${fieldClass()}>
+ *   <label class=${labelClass()} for="message">Message</label>
+ *   <textarea class=${textareaClass()} name="message" id="message" rows="4"
+ *             aria-describedby="message-hint"></textarea>
+ *   <p class=${hintClass()} id="message-hint">Markdown is supported.</p>
+ * </div>
  * ```
  */
 import { cn } from '../lib/utils.ts';

package/packages/registry/components/toggle-group.ts

@@ -22,15 +22,30 @@
  *   `orientation`: "horizontal" (default) | "vertical".
  *
  * Attributes on <ui-toggle-group-item>:
- *   `value`:   string. Identifier this item contributes when selected.
- *   `pressed`: boolean (reflected). Mirrors the group's selection for this item.
+ *   `value`:    string. Identifier this item contributes when selected.
+ *   `pressed`:  boolean (reflected). Mirrors the group's selection for this item.
+ *   `disabled`: boolean (reflected). Refuses click + Enter / Space, is skipped by
+ *               Arrow / Home / End, and never holds the group's tab stop.
  *
  * Events:
  *   `ui-value-change` on <ui-toggle-group>: `{ detail: { value } }` after selection changes.
  *
  * Keyboard: Arrow keys move focus between items (roving tabindex, so the
  * group is a single Tab stop), Home / End jump to the first / last item, and
- * Enter / Space toggles the focused item.
+ * Enter / Space toggles the focused item. A `disabled` item is skipped by all
+ * of these.
+ *
+ * A11y (owned by the element, nothing to supply beyond item names):
+ *   The group is a `role="group"` whose items carry `aria-pressed`, navigated by
+ *   a roving tabindex so the whole group is one Tab stop. A `disabled` item
+ *   reports `aria-disabled` and is skipped by navigation: since the group is a
+ *   single tab stop, focus landing on a disabled item could not be tabbed past,
+ *   so skipping it is what keeps the group usable rather than a nicety.
+ *   Note `disabled` on the item is deliberately exposed as `aria-disabled`, not
+ *   a `disabled` attribute. The item's host IS the button and it is a custom
+ *   element, so a `disabled` attribute there is inert: no `:disabled` CSS, no
+ *   click suppression, no removal from the tab order.
+ *   What you DO supply: an `aria-label` on any icon-only item, as below.
  *
  * Design tokens used: inherited from toggleClass (--muted, --accent, --ring,
  * --input, --destructive).
@@ -48,6 +63,13 @@
  *   <ui-toggle-group-item value="bold">B</ui-toggle-group-item>
  *   <ui-toggle-group-item value="italic">I</ui-toggle-group-item>
  * </ui-toggle-group>
+ *
+ * <!-- A disabled item: unclickable, and skipped by Arrow / Home / End. -->
+ * <ui-toggle-group type="single" value="left">
+ *   <ui-toggle-group-item value="left" aria-label="Align left">L</ui-toggle-group-item>
+ *   <ui-toggle-group-item value="justify" aria-label="Justify" disabled>J</ui-toggle-group-item>
+ *   <ui-toggle-group-item value="right" aria-label="Align right">R</ui-toggle-group-item>
+ * </ui-toggle-group>
  * ```
  */
 import { WebComponent, html, prop } from '@webjsdev/core';
@@ -57,8 +79,13 @@ import { toggleClass, type ToggleVariant, type ToggleSize } from './toggle.ts';
 const ROOT_BASE =
   'group/toggle-group flex w-fit items-center rounded-md data-[spacing=default]:data-[variant=outline]:shadow-xs data-[orientation=vertical]:flex-col data-[orientation=vertical]:items-stretch';
 
+// The `disabled:` variants inside toggleClass() key on the :disabled pseudo,
+// which only ever matches a real form control. An item's host IS the button
+// here (a custom element), so `disabled` on it is inert as far as CSS and the
+// browser are concerned, and the disabled look has to come from the
+// aria-disabled variant instead.
 const ITEM_EXTRA =
-  'w-auto min-w-0 shrink-0 px-3 focus:z-10 focus-visible:z-10 data-[spacing=0]:rounded-none data-[spacing=0]:shadow-none data-[spacing=0]:first:rounded-l-md data-[spacing=0]:last:rounded-r-md data-[spacing=0]:data-[variant=outline]:border-l-0 data-[spacing=0]:data-[variant=outline]:first:border-l';
+  'w-auto min-w-0 shrink-0 px-3 focus:z-10 focus-visible:z-10 aria-disabled:pointer-events-none aria-disabled:opacity-50 data-[spacing=0]:rounded-none data-[spacing=0]:shadow-none data-[spacing=0]:first:rounded-l-md data-[spacing=0]:last:rounded-r-md data-[spacing=0]:data-[variant=outline]:border-l-0 data-[spacing=0]:data-[variant=outline]:first:border-l';
 
 // --------------------------------------------------------------------------
 // <ui-toggle-group>
@@ -117,6 +144,14 @@ export class UiToggleGroup extends WebComponent({
     return Array.from(this.querySelectorAll<UiToggleGroupItem>('ui-toggle-group-item'));
   }
 
+  // Arrow / Home / End navigate among ENABLED items only. Landing focus on a
+  // disabled item would strand the user on a control that refuses every
+  // interaction, and since this group is a single tab stop they cannot simply
+  // Tab past it.
+  _enabledItems(): UiToggleGroupItem[] {
+    return this._items().filter((i) => !i.disabled);
+  }
+
   _reflectItems(): void {
     const values = this._values;
     const items = this._items();
@@ -138,18 +173,29 @@ export class UiToggleGroup extends WebComponent({
   // single tabbable slot via `focusItem`.
   _roving(items: UiToggleGroupItem[], current?: UiToggleGroupItem): void {
     if (!items.length) return;
+    // The tab stop must land on an ENABLED item: promoting a disabled one makes
+    // the group's single Tab stop a dead end.
+    const enabled = items.filter((i) => !i.disabled);
+    if (!enabled.length) {
+      items.forEach((item) => {
+        item.tabIndex = -1;
+      });
+      return;
+    }
     const values = this._values;
     const active =
       typeof document !== 'undefined' ? (document.activeElement as Element | null) : null;
-    const focused = active ? items.find((i) => i === active) : undefined;
-    const selected = items.find((i) => !!i.value && values.has(i.value));
-    const tabbable = focused ?? current ?? selected ?? items[0];
+    const focused = active ? enabled.find((i) => i === active) : undefined;
+    const selected = enabled.find((i) => !!i.value && values.has(i.value));
+    const held = current && !current.disabled ? current : undefined;
+    const tabbable = focused ?? held ?? selected ?? enabled[0];
     items.forEach((item) => {
       item.tabIndex = item === tabbable ? 0 : -1;
     });
   }
 
   focusItem(item: UiToggleGroupItem): void {
+    if (item.disabled) return;
     this._items().forEach((el) => {
       el.tabIndex = el === item ? 0 : -1;
     });
@@ -189,11 +235,13 @@ UiToggleGroup.register('ui-toggle-group');
 export class UiToggleGroupItem extends WebComponent({
   value: prop(String, { reflect: true }),
   pressed: prop(Boolean, { reflect: true }),
+  disabled: prop(Boolean, { reflect: true }),
 }) {
   constructor() {
     super();
     this.value = '';
     this.pressed = false;
+    this.disabled = false;
   }
 
   // render() runs server-side too. webjs resolves closest() at SSR against
@@ -240,12 +288,36 @@ export class UiToggleGroupItem extends WebComponent({
     this.dataset.size = size;
     this.dataset.spacing = spacing;
     this.dataset.state = this.pressed ? 'on' : 'off';
+    // role and data-slot are set HERE as well as in connectedCallback, because
+    // SSR runs render() but NOT connectedCallback. Without this the served item
+    // carried aria-pressed / aria-disabled with no role at all, and neither is a
+    // global ARIA attribute, so the first paint shipped attributes that are not
+    // allowed on a generic-role element. (`this.role` is shimmed server-side too,
+    // like the ariaPressed / dataset / className writes around it; setAttribute
+    // is simply the more explicit spelling.)
+    this.setAttribute('role', 'button');
+    this.setAttribute('data-slot', 'toggle-group-item');
     this.ariaPressed = String(this.pressed);
+    // aria-disabled rather than a `disabled` attribute: the host is a custom
+    // element, so `disabled` would be inert (no CSS pseudo, no click blocking,
+    // no removal from the tab order). aria-disabled is what actually reaches
+    // assistive tech, and the group skips these in its roving tabindex.
+    this.ariaDisabled = String(this.disabled);
     this.className = cn(toggleClass({ variant, size }), ITEM_EXTRA);
     return html`<slot></slot>`;
   }
 
+  // Disabling the item that happens to hold the group's only tab stop would
+  // leave the group unreachable by keyboard, and the group cannot see an item's
+  // prop change on its own, so ask it to recompute which item is tabbable.
+  updated(changedProperties: Map<string, unknown>): void {
+    if (!changedProperties.has('disabled')) return;
+    if (changedProperties.get('disabled') === undefined) return;
+    queueMicrotask(() => this._group?._reflectItems());
+  }
+
   _onClick = (): void => {
+    if (this.disabled) return;
     if (!this.value) return;
     this.dispatchEvent(
       new CustomEvent('ui-toggle-item-click', { detail: { value: this.value }, bubbles: true }),
@@ -253,6 +325,7 @@ export class UiToggleGroupItem extends WebComponent({
   };
 
   _onKeyDown = (e: KeyboardEvent): void => {
+    if (this.disabled) return;
     if (e.key === ' ' || e.key === 'Enter') {
       e.preventDefault();
       this._onClick();
@@ -263,7 +336,7 @@ export class UiToggleGroupItem extends WebComponent({
     const horizontal = group.orientation !== 'vertical';
     const nextKey = horizontal ? 'ArrowRight' : 'ArrowDown';
     const prevKey = horizontal ? 'ArrowLeft' : 'ArrowUp';
-    const items = group._items();
+    const items = group._enabledItems();
     const idx = items.indexOf(this);
     if (idx === -1) return;
     let target: UiToggleGroupItem | null = null;

package/packages/registry/components/toggle.ts

@@ -21,6 +21,32 @@
  *
  * Keyboard: native button. Enter / Space activates (via the inner <button>).
  *
+ * A11y (required for accessible output):
+ *   `<ui-toggle>` renders a native `<button>` inside itself, and that button is
+ *   the focusable control whose accessible name a screen reader announces. An
+ *   `aria-label` on the host would not reach it (a name on a generic-role
+ *   element does not contribute to a descendant's name), so the element
+ *   FORWARDS the host's `aria-label` / `aria-labelledby` onto the inner button.
+ *   Put the name on the host, as the icon-only example below does, and the
+ *   element wires the rest. An icon-only toggle needs one; a text toggle takes
+ *   its name from the slotted text and needs nothing.
+ *   Set the name as an ATTRIBUTE on the host in your markup
+ *   (`aria-label="Toggle bold"`), not as a property.
+ *   LIMITATION, and it is a real one: `aria-label` / `aria-labelledby` are not
+ *   reactive properties of this element, so they are not observed attributes.
+ *   The name is read during render(), which means markup present at first paint
+ *   works, but a LATER `el.setAttribute('aria-label', ...)` does not re-render
+ *   and so does not reach the inner button until something else happens to
+ *   trigger a render. If your name is computed after mount, set it on the inner
+ *   button yourself (`el.querySelector('button').setAttribute('aria-label',
+ *   name)`). Do NOT reach for "flip a reactive prop to force a re-render":
+ *   adding or removing the name switches which of the three templates below is
+ *   used, and a template swap REBUILDS the button, so doing it on a click would
+ *   destroy the control the user is focused on and drop focus to <body>.
+ *   Using the Tier-1 `toggleClass()` helper on your own `<button>` instead? Then
+ *   the name is entirely yours: give an icon-only button an `aria-label`, and
+ *   carry the pressed state on `aria-pressed` + `data-state` as the example does.
+ *
  * Design tokens used: --muted, --muted-foreground, --accent, --accent-foreground,
  * --input, --background, --ring, --destructive.
  *
@@ -93,13 +119,66 @@ export class UiToggle extends WebComponent({
     this.disabled = false;
   }
 
+  // Read a host attribute defensively. render() runs server-side too, where
+  // webjs shims the attribute methods; the typeof guard stays for any other
+  // renderer that does not.
+  _hostAttr(name: string): string | null {
+    if (typeof this.getAttribute !== 'function') return null;
+    return this.getAttribute(name);
+  }
+
   render() {
+    // The focusable control is the inner <button>, so its accessible name is
+    // what a screen reader announces. `aria-label` on the host cannot supply
+    // that (the host has a generic role, and a name there does not contribute
+    // to a descendant's name), and the documented icon-only shape slots an
+    // aria-hidden SVG, which contributes nothing either. Forward the host's
+    // name source onto the button so the documented shape ships named.
+    //
+    // The name is BRANCHED into three templates rather than carried in one
+    // hole, because a null hole does NOT omit an attribute on the server: the
+    // server renderer stringifies the value, so `aria-label=${null}` ships
+    // `aria-label=""` while the client renderer removes it. On an unlabelled
+    // toggle that would put an empty name on the very control whose name is
+    // supposed to come from its slotted text, and disagree with the hydrated
+    // DOM on the exact attribute this forwarding exists to get right.
+    const labelledBy = this._hostAttr('aria-labelledby');
+    const label = this._hostAttr('aria-label');
+    const cls = toggleClass({ variant: this.variant, size: this.size });
+    const pressed = String(this.pressed);
+    const state = this.pressed ? 'on' : 'off';
+    // aria-labelledby beats aria-label per accname, so it is checked first and
+    // only ONE of the two is ever emitted.
+    if (labelledBy) {
+      return html`<button
+        type="button"
+        data-slot="toggle"
+        class=${cls}
+        aria-pressed=${pressed}
+        aria-labelledby=${labelledBy}
+        data-state=${state}
+        ?disabled=${this.disabled}
+        @click=${this._onClick}
+      ><slot></slot></button>`;
+    }
+    if (label) {
+      return html`<button
+        type="button"
+        data-slot="toggle"
+        class=${cls}
+        aria-pressed=${pressed}
+        aria-label=${label}
+        data-state=${state}
+        ?disabled=${this.disabled}
+        @click=${this._onClick}
+      ><slot></slot></button>`;
+    }
     return html`<button
       type="button"
       data-slot="toggle"
-      class=${toggleClass({ variant: this.variant, size: this.size })}
-      aria-pressed=${String(this.pressed)}
-      data-state=${this.pressed ? 'on' : 'off'}
+      class=${cls}
+      aria-pressed=${pressed}
+      data-state=${state}
       ?disabled=${this.disabled}
       @click=${this._onClick}
     ><slot></slot></button>`;

package/packages/registry/components/tooltip.ts

@@ -30,6 +30,20 @@
  *
  * Programmatic API on <ui-tooltip>: `.show()` · `.hide()`.
  *
+ * Keyboard:
+ *   Escape   dismiss a showing tip, leaving focus on the trigger
+ *
+ * A11y (owned by the element, nothing to supply):
+ *   The focusable trigger references the tip via `aria-describedby`, so a
+ *   screen reader appends the tip to the trigger's own name, and the tip opens
+ *   on focus as well as hover. Escape dismisses a showing tip without moving
+ *   focus (APG requires the escape hatch, since a tip can cover the content
+ *   underneath it). A CLOSED tooltip never consumes Escape, so it cannot
+ *   swallow the key from a dialog it happens to sit inside.
+ *   What you DO supply: an accessible name on the trigger control itself. The
+ *   tip is a DESCRIPTION, not a name, so an icon-only trigger still needs its
+ *   own `aria-label` as the example below shows.
+ *
  * Design tokens used: --foreground, --background.
  *
  * @example
@@ -75,6 +89,8 @@ export class UiTooltip extends WebComponent({
   _showTimer: number | undefined;
   _hideTimer: number | undefined;
 
+  _keyHandler = (e: KeyboardEvent): void => this._onKeyDown(e);
+
   constructor() {
     super();
     this.open = false;
@@ -98,10 +114,43 @@ export class UiTooltip extends WebComponent({
   }
 
   disconnectedCallback(): void {
+    this._unbindEscape();
     this._disposeBeforeCache?.();
     super.disconnectedCallback?.();
   }
 
+  // APG Tooltip requires an Escape escape-hatch: a tip can cover the content
+  // underneath it, and a keyboard user who cannot dismiss it is stuck. Focus
+  // is deliberately untouched, since the tip is not focusable and the trigger
+  // should keep focus (moving it would lose the user's place).
+  //
+  // The listener is bound only WHILE OPEN, which is how a closed tooltip is
+  // kept from consuming Escape that a dialog (or anything else) wants.
+  _onKeyDown(e: KeyboardEvent): void {
+    if (e.key !== 'Escape' || !this.open) return;
+    e.preventDefault();
+    this._dismiss();
+  }
+
+  // Immediate, unlike hide()'s 100ms hover-out grace: a dismissal is a
+  // deliberate act, so it should not sit around waiting to be cancelled.
+  _dismiss(): void {
+    clearTimeout(this._showTimer);
+    clearTimeout(this._hideTimer);
+    this.open = false;
+    lastTooltipHideAt = Date.now();
+  }
+
+  _bindEscape(): void {
+    if (typeof document === 'undefined') return;
+    document.addEventListener('keydown', this._keyHandler);
+  }
+
+  _unbindEscape(): void {
+    if (typeof document === 'undefined') return;
+    document.removeEventListener('keydown', this._keyHandler);
+  }
+
   // APG tooltip wiring: the focusable trigger references the tip via
   // aria-describedby, so a screen reader appends the tip text to the
   // trigger's own name ("Help, button, Helpful tip"). The tip is JS-driven,
@@ -140,6 +189,10 @@ export class UiTooltip extends WebComponent({
 
   hide(): void {
     clearTimeout(this._showTimer);
+    // Clear the PENDING hide before scheduling the next one: overwriting the
+    // handle alone orphans the old timer, which then fires on its own and
+    // closes a tip a later show() had already reopened.
+    clearTimeout(this._hideTimer);
     this._hideTimer = window.setTimeout(() => {
       this.open = false;
       lastTooltipHideAt = Date.now();
@@ -157,6 +210,10 @@ export class UiTooltip extends WebComponent({
     if (!changedProperties.has('open')) return;
     // Skip the constructor's initial open=false set.
     if (changedProperties.get('open') === undefined) return;
+    // Bind synchronously rather than inside _syncContent, which bails early on
+    // engines with no Popover API: Escape has to work regardless of that.
+    if (this.open) this._bindEscape();
+    else this._unbindEscape();
     // Defer one microtask so the content child's [popover] inner element
     // has committed; we drive its showPopover() / hidePopover() from here.
     queueMicrotask(() => this._syncContent());