@webjsdev/ui 0.3.4 → 0.3.6

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 } 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,37 @@ export class UiHoverCard extends WebComponent {
     this.closeDelay = 300;
   }
 
+  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());
+    }
+  }
+
+  // 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; }
 
@@ -98,8 +125,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 {

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,7 @@
  *
  * 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';
 
 type ToastType = 'default' | 'success' | 'error' | 'info' | 'warning' | 'loading';
 
@@ -134,11 +134,9 @@ 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[]>([]);
 
   constructor() {
@@ -190,8 +188,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.
  */
 

package/packages/registry/components/tabs.ts

@@ -43,8 +43,11 @@
  * Design tokens used: --muted, --muted-foreground, --foreground, --background,
  * --input, --ring.
  */
-import { WebComponent, html } from '@webjsdev/core';
-import { cn } from '../lib/utils.ts';
+import { WebComponent, html, prop } from '@webjsdev/core';
+import { cn, ensureId } from '../lib/utils.ts';
+
+// A tab `value` becomes part of an id, so reduce it to id-safe characters.
+const idSafe = (s: string): string => s.replace(/[^A-Za-z0-9_-]/g, '-');
 
 // --------------------------------------------------------------------------
 // Class helpers
@@ -92,20 +95,29 @@ const TABS_CONTENT_CLASS = 'flex-1 outline-none';
 // requestUpdate() to re-render against the new parent value.
 // --------------------------------------------------------------------------
 
-export class UiTabs extends WebComponent {
-  static properties = {
-    value: { type: String, reflect: true },
-    orientation: { type: String, reflect: true },
-  };
-  declare value: string;
-  declare orientation: 'horizontal' | 'vertical';
-
+export class UiTabs extends WebComponent({
+  value: prop(String, { reflect: true }),
+  orientation: prop<'horizontal' | 'vertical'>(String, { reflect: true }),
+}) {
   constructor() {
     super();
     this.value = '';
     this.orientation = 'horizontal';
   }
 
+  // Stable per-instance scope so a trigger and its panel agree on the
+  // shared id stem (`<scope>-trigger-<value>` / `<scope>-panel-<value>`)
+  // even when several tab sets reuse the same `value` names on one page.
+  get scopeId(): string {
+    return ensureId(this, 'ui-tabs');
+  }
+
+  // Builds the trigger / panel id pair a child derives from its `value`.
+  idsFor(value: string): { trigger: string; panel: string } {
+    const v = idSafe(value);
+    return { trigger: `${this.scopeId}-trigger-${v}`, panel: `${this.scopeId}-panel-${v}` };
+  }
+
   render() {
     return html`<div
       data-slot="tabs"
@@ -130,7 +142,7 @@ export class UiTabs extends WebComponent {
 
   _broadcast(): void {
     this.querySelectorAll<WebComponent>(
-      'ui-tabs-trigger, ui-tabs-content',
+      'ui-tabs-list, ui-tabs-trigger, ui-tabs-content',
     ).forEach((el) => el.requestUpdate?.());
   }
 }
@@ -140,21 +152,25 @@ UiTabs.register('ui-tabs');
 // <ui-tabs-list>
 // --------------------------------------------------------------------------
 
-export class UiTabsList extends WebComponent {
-  static properties = {
-    variant: { type: String, reflect: true },
-  };
-  declare variant: TabsListVariant;
-
+export class UiTabsList extends WebComponent({
+  variant: prop<TabsListVariant>(String, { reflect: true }),
+}) {
   constructor() {
     super();
     this.variant = 'default';
   }
 
+  get _tabs(): UiTabs | null {
+    if (typeof this.closest !== 'function') return null;
+    return this.closest('ui-tabs') as UiTabs | null;
+  }
+
   render() {
+    const orientation = this._tabs?.orientation ?? 'horizontal';
     return html`<div
       data-slot="tabs-list"
       role="tablist"
+      aria-orientation=${orientation}
       data-variant=${this.variant}
       class=${tabsListClass({ variant: this.variant })}
     ><slot></slot></div>`;
@@ -166,20 +182,17 @@ UiTabsList.register('ui-tabs-list');
 // <ui-tabs-trigger value="...">
 // --------------------------------------------------------------------------
 
-export class UiTabsTrigger extends WebComponent {
-  static properties = {
-    value: { type: String, reflect: true },
-  };
-  declare value: string;
-
+export class UiTabsTrigger extends WebComponent({
+  value: prop(String, { reflect: true }),
+}) {
   constructor() {
     super();
     this.value = '';
   }
 
-  // render() runs server-side too; linkedom doesn't implement closest()
-  // on custom elements. Return null during SSR; the client re-renders
-  // with the parent reference after hydration.
+  // render() runs server-side too. webjs resolves closest() at SSR against
+  // the enclosing-element ancestor chain, so the active tab is marked in the
+  // first paint (no hydration flash). The typeof guard stays defensive.
   get _tabs(): UiTabs | null {
     if (typeof this.closest !== 'function') return null;
     return this.closest('ui-tabs') as UiTabs | null;
@@ -188,10 +201,13 @@ export class UiTabsTrigger extends WebComponent {
   render() {
     const tabs = this._tabs;
     const active = !!tabs && tabs.value === this.value && this.value !== '';
+    const ids = tabs && this.value ? tabs.idsFor(this.value) : null;
     return html`<button
       type="button"
       role="tab"
       data-slot="tabs-trigger"
+      id=${ids ? ids.trigger : ''}
+      aria-controls=${ids ? ids.panel : ''}
       data-state=${active ? 'active' : 'inactive'}
       aria-selected=${String(active)}
       tabindex=${active ? '0' : '-1'}
@@ -235,12 +251,9 @@ UiTabsTrigger.register('ui-tabs-trigger');
 // <ui-tabs-content value="...">
 // --------------------------------------------------------------------------
 
-export class UiTabsContent extends WebComponent {
-  static properties = {
-    value: { type: String, reflect: true },
-  };
-  declare value: string;
-
+export class UiTabsContent extends WebComponent({
+  value: prop(String, { reflect: true }),
+}) {
   constructor() {
     super();
     this.value = '';
@@ -254,14 +267,20 @@ export class UiTabsContent extends WebComponent {
   render() {
     const tabs = this._tabs;
     const active = !!tabs && tabs.value === this.value && this.value !== '';
+    const ids = tabs && this.value ? tabs.idsFor(this.value) : null;
     // The host needs to be hidden when inactive so its rendered <section>
     // is removed from layout (light DOM has no :host CSS to scope this).
     // Use the native `hidden` IDL property rather than imperative
-    // setAttribute, so it reads as a property assignment.
+    // setAttribute, so it reads as a property assignment. `inert` on the
+    // host additionally pulls an inactive panel (and anything focusable
+    // inside it) out of the tab order and the accessibility tree.
     this.hidden = !active;
+    this.inert = !active;
     return html`<section
       data-slot="tabs-content"
       role="tabpanel"
+      id=${ids ? ids.panel : ''}
+      aria-labelledby=${ids ? ids.trigger : ''}
       tabindex="0"
       data-state=${active ? 'active' : 'inactive'}
       class=${TABS_CONTENT_CLASS}

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

@@ -41,12 +41,14 @@
  * Events:
  *   `ui-value-change` on <ui-toggle-group>: `{ detail: { value } }` after selection changes.
  *
- * Keyboard: Enter / Space toggles the focused item (native button activation).
+ * 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.
  *
  * Design tokens used: inherited from toggleClass (--muted, --accent, --ring,
  * --input, --destructive).
  */
-import { WebComponent, html } from '@webjsdev/core';
+import { WebComponent, html, prop } from '@webjsdev/core';
 import { cn } from '../lib/utils.ts';
 import { toggleClass, type ToggleVariant, type ToggleSize } from './toggle.ts';
 
@@ -66,22 +68,14 @@ const ITEM_EXTRA =
 // their own renders before we read / write their state.
 // --------------------------------------------------------------------------
 
-export class UiToggleGroup extends WebComponent {
-  static properties = {
-    value: { type: String, reflect: true },
-    type: { type: String, reflect: true },
-    variant: { type: String, reflect: true },
-    size: { type: String, reflect: true },
-    spacing: { type: String, reflect: true },
-    orientation: { type: String, reflect: true },
-  };
-  declare value: string;
-  declare type: 'single' | 'multiple';
-  declare variant: ToggleVariant;
-  declare size: ToggleSize;
-  declare spacing: string;
-  declare orientation: 'horizontal' | 'vertical';
-
+export class UiToggleGroup extends WebComponent({
+  value: prop(String, { reflect: true }),
+  type: prop<'single' | 'multiple'>(String, { reflect: true }),
+  variant: prop<ToggleVariant>(String, { reflect: true }),
+  size: prop<ToggleSize>(String, { reflect: true }),
+  spacing: prop(String, { reflect: true }),
+  orientation: prop<'horizontal' | 'vertical'>(String, { reflect: true }),
+}) {
   constructor() {
     super();
     this.value = '';
@@ -117,9 +111,15 @@ export class UiToggleGroup extends WebComponent {
     queueMicrotask(() => this._reflectItems());
   }
 
+  _items(): UiToggleGroupItem[] {
+    return Array.from(this.querySelectorAll<UiToggleGroupItem>('ui-toggle-group-item'));
+  }
+
   _reflectItems(): void {
     const values = this._values;
-    this.querySelectorAll<UiToggleGroupItem>('ui-toggle-group-item').forEach((item) => {
+    const items = this._items();
+    const current = items.find((el) => el.tabIndex === 0);
+    items.forEach((item) => {
       const on = !!item.value && values.has(item.value);
       // Reflect both on the host (for CSS sibling selectors like
       // data-[spacing=0]:first:rounded-l-md that need to target the host
@@ -127,6 +127,31 @@ export class UiToggleGroup extends WebComponent {
       // item's render() refreshes its inner styling.
       item.pressed = on;
     });
+    this._roving(items, current);
+  }
+
+  // Roving tabindex (APG): exactly one item is in the tab order. Prefer the
+  // currently-focused item, then whichever was tabbable, then the first
+  // selected item, then the first item. Arrow keys move focus and shift the
+  // single tabbable slot via `focusItem`.
+  _roving(items: UiToggleGroupItem[], current?: UiToggleGroupItem): void {
+    if (!items.length) 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];
+    items.forEach((item) => {
+      item.tabIndex = item === tabbable ? 0 : -1;
+    });
+  }
+
+  focusItem(item: UiToggleGroupItem): void {
+    this._items().forEach((el) => {
+      el.tabIndex = el === item ? 0 : -1;
+    });
+    item.focus();
   }
 
   _onItemClick = (e: Event): void => {
@@ -159,23 +184,19 @@ UiToggleGroup.register('ui-toggle-group');
 // Tailwind variant selectors on the joined-spacing rounded corners).
 // --------------------------------------------------------------------------
 
-export class UiToggleGroupItem extends WebComponent {
-  static properties = {
-    value: { type: String, reflect: true },
-    pressed: { type: Boolean, reflect: true },
-  };
-  declare value: string;
-  declare pressed: boolean;
-
+export class UiToggleGroupItem extends WebComponent({
+  value: prop(String, { reflect: true }),
+  pressed: prop(Boolean, { reflect: true }),
+}) {
   constructor() {
     super();
     this.value = '';
     this.pressed = false;
   }
 
-  // render() runs server-side too. linkedom doesn't implement closest()
-  // on custom elements, so guard it; the client re-renders with the
-  // real parent reference after hydration.
+  // render() runs server-side too. webjs resolves closest() at SSR against
+  // the enclosing-element ancestor chain, so the pressed item is marked in
+  // the first paint (no hydration flash). The typeof guard stays defensive.
   get _group(): UiToggleGroup | null {
     if (typeof this.closest !== 'function') return null;
     return this.closest('ui-toggle-group') as UiToggleGroup | null;
@@ -193,7 +214,10 @@ export class UiToggleGroupItem extends WebComponent {
   connectedCallback(): void {
     this.dataset.slot = 'toggle-group-item';
     this.role = 'button';
-    this.tabIndex = 0;
+    // Roving tabindex: start outside the tab order. The group promotes
+    // exactly one item to tabindex 0 in _reflectItems (runs after first
+    // render); Arrow keys move focus and the tabbable slot from there.
+    this.tabIndex = -1;
     this.addEventListener('click', this._onClick);
     this.addEventListener('keydown', this._onKeyDown);
     super.connectedCallback?.();
@@ -230,6 +254,24 @@ export class UiToggleGroupItem extends WebComponent {
     if (e.key === ' ' || e.key === 'Enter') {
       e.preventDefault();
       this._onClick();
+      return;
+    }
+    const group = this._group;
+    if (!group) return;
+    const horizontal = group.orientation !== 'vertical';
+    const nextKey = horizontal ? 'ArrowRight' : 'ArrowDown';
+    const prevKey = horizontal ? 'ArrowLeft' : 'ArrowUp';
+    const items = group._items();
+    const idx = items.indexOf(this);
+    if (idx === -1) return;
+    let target: UiToggleGroupItem | null = null;
+    if (e.key === nextKey) target = items[(idx + 1) % items.length] ?? null;
+    else if (e.key === prevKey) target = items[(idx - 1 + items.length) % items.length] ?? null;
+    else if (e.key === 'Home') target = items[0] ?? null;
+    else if (e.key === 'End') target = items[items.length - 1] ?? null;
+    if (target) {
+      e.preventDefault();
+      group.focusItem(target);
     }
   };
 }

package/packages/registry/components/toggle.ts

@@ -38,7 +38,7 @@
  * Design tokens used: --muted, --muted-foreground, --accent, --accent-foreground,
  * --input, --background, --ring, --destructive.
  */
-import { WebComponent, html } from '@webjsdev/core';
+import { WebComponent, html, prop } from '@webjsdev/core';
 import { cn } from '../lib/utils.ts';
 
 // cursor-pointer + select-none on BASE for both call sites: the
@@ -76,18 +76,12 @@ export function toggleClass(opts: { variant?: ToggleVariant; size?: ToggleSize }
 // project through the default slot inside the inner button.
 // --------------------------------------------------------------------------
 
-export class UiToggle extends WebComponent {
-  static properties = {
-    pressed: { type: Boolean, reflect: true },
-    variant: { type: String, reflect: true },
-    size: { type: String, reflect: true },
-    disabled: { type: Boolean, reflect: true },
-  };
-  declare pressed: boolean;
-  declare variant: ToggleVariant;
-  declare size: ToggleSize;
-  declare disabled: boolean;
-
+export class UiToggle extends WebComponent({
+  pressed: prop(Boolean, { reflect: true }),
+  variant: prop<ToggleVariant>(String, { reflect: true }),
+  size: prop<ToggleSize>(String, { reflect: true }),
+  disabled: prop(Boolean, { reflect: true }),
+}) {
   constructor() {
     super();
     this.pressed = false;

package/packages/registry/components/tooltip.ts

@@ -40,7 +40,8 @@
  *
  * Design tokens used: --foreground, --background.
  */
-import { WebComponent, html } from '@webjsdev/core';
+import { WebComponent, html, prop } from '@webjsdev/core';
+import { ensureId } from '../lib/utils.ts';
 import { positionFloating, type PopoverSide, type PopoverAlign } from './popover.ts';
 
 // UA `[popover]` defaults paint a bordered, padded panel centered with
@@ -61,18 +62,13 @@ let lastTooltipHideAt = 0;
 // <ui-tooltip>
 // --------------------------------------------------------------------------
 
-export class UiTooltip extends WebComponent {
-  static properties = {
-    open: { type: Boolean, reflect: true },
-    delayDuration: { type: Number },
-    skipDelayDuration: { type: Number },
-  };
-  declare open: boolean;
+export class UiTooltip extends WebComponent({
+  open: prop(Boolean, { reflect: true }),
   // `delayDuration` / `skipDelayDuration` ride the `delay-duration` /
   // `skip-delay-duration` attributes (shadcn parity), read as typed props.
-  declare delayDuration: number;
-  declare skipDelayDuration: number;
-
+  delayDuration: Number,
+  skipDelayDuration: Number,
+}) {
   _showTimer: number | undefined;
   _hideTimer: number | undefined;
 
@@ -83,6 +79,36 @@ export class UiTooltip extends WebComponent {
     this.skipDelayDuration = 300;
   }
 
+  connectedCallback(): void {
+    super.connectedCallback?.();
+    // webjs projects slotted light-DOM children in a pass after the first
+    // render, so the trigger's focusable control is not in place yet at
+    // connect / firstUpdated. Defer to the next frame, by which point the
+    // projection has run and both the control and the tip content exist.
+    if (typeof requestAnimationFrame === 'function') {
+      requestAnimationFrame(() => this._wireAria());
+    }
+  }
+
+  // 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,
+  // so doing this at runtime is correct.
+  _wireAria(): void {
+    const triggerHost = this.querySelector('ui-tooltip-trigger');
+    const content = this.querySelector<HTMLElement>('ui-tooltip-content [role="tooltip"]');
+    if (!triggerHost || !content) return;
+    const control =
+      triggerHost.querySelector<HTMLElement>('button, a[href], [tabindex], [role="button"]') ??
+      (triggerHost as HTMLElement);
+    const id = ensureId(content, 'ui-tooltip');
+    const existing = control.getAttribute('aria-describedby');
+    if (!existing) control.setAttribute('aria-describedby', id);
+    else if (!existing.split(/\s+/).includes(id)) {
+      control.setAttribute('aria-describedby', `${existing} ${id}`);
+    }
+  }
+
   // Back-compat getter for tests + external code that read `el.isOpen`
   // alongside the reactive `open` prop.
   get isOpen(): boolean { return this.open; }