@webjsdev/ui 0.3.10 → 0.3.12

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

@@ -26,6 +26,28 @@
  *
  * Programmatic API on <ui-hover-card>: `.show()` · `.hide()`.
  *
+ * Keyboard:
+ *   Tab      from the trigger into the card, whose content stays open while it
+ *            holds focus, so links and buttons inside it are reachable
+ *   Escape   dismiss the card, returning focus to the trigger when the card
+ *            held it
+ *
+ * A11y (owned by the element, mostly nothing to supply):
+ *   The trigger opens on focus as well as hover and carries `aria-haspopup` /
+ *   `aria-expanded` / `aria-controls`. The panel is a `role="dialog"`, which
+ *   REQUIRES an accessible name, so the element always gives it one, from the
+ *   first of: an `aria-label` / `aria-labelledby` you put on
+ *   `<ui-hover-card-content>`, a `[data-slot="hover-card-title"]` or heading
+ *   inside the card, or the trigger itself (the card is about whatever the
+ *   trigger names). Escape dismisses it and hands focus back when the card had
+ *   it, and the content keeps itself open while focus is inside.
+ *   What you DO supply: a name for the trigger control if it is icon-only, and
+ *   ideally a title node in the card so its name describes the card rather
+ *   than falling back to the trigger's text.
+ *   Touch: the hover and focus linger paths are gated to pointer devices, so on
+ *   a no-hover device the card is tap-toggled and dismissed by an outside tap
+ *   (#745). Do not remove that gate to "fix" keyboard behaviour.
+ *
  * Design tokens used: --popover, --popover-foreground, --border.
  *
  * @example
@@ -38,8 +60,9 @@
  *     <div class="flex gap-3">
  *       <img class="size-10 rounded-full" src="/avatars/vivek.jpg" alt="Vivek Khandelwal">
  *       <div>
- *         <div class="text-sm font-semibold">Vivek Khandelwal</div>
+ *         <div class="text-sm font-semibold" data-slot="hover-card-title">Vivek Khandelwal</div>
  *         <p class="text-sm text-muted-foreground">Builds the platform, not against it.</p>
+ *         <a class="text-sm underline" href="/user/vivek/posts">Read the posts</a>
  *       </div>
  *     </div>
  *   </ui-hover-card-content>
@@ -72,6 +95,8 @@ export class UiHoverCard extends WebComponent({
   _showTimer: number | undefined;
   _hideTimer: number | undefined;
 
+  _keyHandler = (e: KeyboardEvent): void => this._onKeyDown(e);
+
   constructor() {
     super();
     this.open = false;
@@ -95,10 +120,49 @@ export class UiHoverCard extends WebComponent({
   }
 
   disconnectedCallback(): void {
+    this._unbindEscape();
     this._disposeBeforeCache?.();
     super.disconnectedCallback?.();
   }
 
+  // A hover card can hold interactive content and cover what is under it, so a
+  // keyboard user needs a way out that is not "tab through the whole card".
+  // Bound only WHILE OPEN so a closed card cannot swallow Escape.
+  _onKeyDown(e: KeyboardEvent): void {
+    if (e.key !== 'Escape' || !this.open) return;
+    e.preventDefault();
+    this._dismiss();
+  }
+
+  // Immediate, unlike hide()'s close-delay linger, since a dismissal is
+  // deliberate. Focus moves out BEFORE the panel hides: the content is
+  // popover="manual", so hiding it while a descendant holds focus drops focus
+  // to <body> and the user loses their place on the page.
+  _suppressReopen = false;
+
+  _dismiss(): void {
+    clearTimeout(this._showTimer);
+    clearTimeout(this._hideTimer);
+    this._closeReleasingFocus();
+  }
+
+  _focusIsInContent(): boolean {
+    if (typeof document === 'undefined') return false;
+    const content = this.querySelector('ui-hover-card-content');
+    const active = document.activeElement;
+    return !!content && !!active && content.contains(active);
+  }
+
+  _bindEscape(): void {
+    if (typeof document === 'undefined') return;
+    document.addEventListener('keydown', this._keyHandler);
+  }
+
+  _unbindEscape(): void {
+    if (typeof document === 'undefined') return;
+    document.removeEventListener('keydown', this._keyHandler);
+  }
+
   // 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.
@@ -117,20 +181,103 @@ export class UiHoverCard extends WebComponent({
     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'));
+    if (!content) return;
+    control.setAttribute('aria-controls', ensureId(content, 'ui-hovercard'));
+    this._nameContent(content, control);
+  }
+
+  // role="dialog" REQUIRES an accessible name. Without one a screen reader
+  // announces a bare "dialog" with no hint of what it holds, which is an ARIA
+  // defect rather than a missing nicety. Three sources, most specific first:
+  //   1. what the author put on <ui-hover-card-content>, which always wins
+  //   2. a title node inside the card (the dialog.ts idiom)
+  //   3. the trigger, since the card is ABOUT whatever the trigger names
+  //      ("@vivek" names that user's card). Same fallback the dropdown menu
+  //      already uses to label its panel back to its trigger.
+  // Source 3 is what makes the name unconditional: there is no shape of this
+  // component that can end up with an unnamed dialog role.
+  _nameContent(content: HTMLElement, control: HTMLElement): void {
+    const host = this.querySelector('ui-hover-card-content');
+    // aria-labelledby is checked FIRST because it beats aria-label per accname,
+    // matching dialog / alert-dialog / toggle. Checking aria-label first would
+    // name this panel by the attribute that loses everywhere else, so an author
+    // writing both would get a different name here than in a dialog.
+    const authoredLabelledBy = host?.getAttribute('aria-labelledby');
+    if (authoredLabelledBy) {
+      content.setAttribute('aria-labelledby', authoredLabelledBy);
+      return;
+    }
+    const authoredLabel = host?.getAttribute('aria-label');
+    if (authoredLabel) {
+      content.setAttribute('aria-label', authoredLabel);
+      // This method re-runs on every open change, and the fallback below writes
+      // aria-labelledby unconditionally. So a card named from its title on an
+      // earlier pass still carries that reference, and it would outrank the
+      // author's aria-label. Drop it, as dialog / alert-dialog do.
+      content.removeAttribute('aria-labelledby');
+      return;
+    }
+    // Already named by an earlier pass (this runs again on every open change).
+    if (content.hasAttribute('aria-label') || content.hasAttribute('aria-labelledby')) return;
+    const title = content.querySelector<HTMLElement>(
+      '[data-slot="hover-card-title"], h1, h2, h3, h4, h5, h6',
+    );
+    content.setAttribute(
+      'aria-labelledby',
+      title
+        ? ensureId(title, 'ui-hovercard-title')
+        : ensureId(control, 'ui-hovercard-trigger'),
+    );
   }
 
   // Back-compat getter.
   get isOpen(): boolean { return this.open; }
 
   show(): void {
+    // A keyboard dismissal has to stick: _dismiss() moves focus to the trigger,
+    // and that focusin lands right back here, which would reopen the card and
+    // make Escape look broken. The guard is released once the transfer flushes.
+    if (this._suppressReopen) return;
     clearTimeout(this._hideTimer);
     this._showTimer = window.setTimeout(() => { this.open = true; }, this.openDelay);
   }
 
   hide(): void {
     clearTimeout(this._showTimer);
-    this._hideTimer = window.setTimeout(() => { this.open = false; }, this.closeDelay);
+    // 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 the card after a later show() thought it had cancelled the close.
+    // Reachable whenever two leave paths fire without a show() between them,
+    // and the focus linger below doubles how many of those paths exist.
+    clearTimeout(this._hideTimer);
+    this._hideTimer = window.setTimeout(() => {
+      // The card KEEPS ITSELF OPEN while focus is inside it. That is what makes
+      // in-card content Tab-reachable and what both doc surfaces promise, and a
+      // mouseleave can schedule this close while a keyboard user still holds
+      // focus on an in-card link. Closing then would pull the card out from
+      // under them, so leave it open: the content's own focusout schedules the
+      // close once focus has actually left, and that pass takes this branch.
+      if (this._focusIsInContent()) return;
+      this.open = false;
+    }, this.closeDelay);
+  }
+
+  // Every close of this popover="manual" panel owes the same focus care, not
+  // just Escape. The focus linger added here makes in-card content Tab-
+  // reachable, so a user CAN be holding focus on a link inside the card when a
+  // mouseleave-scheduled close fires; hiding the panel then drops focus to
+  // <body>. Guarded, so a close while focus is elsewhere leaves it alone.
+  //
+  // The reopen suppression is what makes this terminate. Moving focus to the
+  // trigger fires the trigger's own focusin, which calls show() and would
+  // reopen the card the close just closed. It is released on the next
+  // macrotask, once that synchronous focus transfer has been refused, so a
+  // genuinely new hover or a fresh Tab back in still opens the card.
+  _closeReleasingFocus(): void {
+    this._suppressReopen = true;
+    if (this._focusIsInContent()) this._control()?.focus();
+    this.open = false;
+    setTimeout(() => { this._suppressReopen = false; }, 0);
   }
 
   // Touch open: there is no hover delay and no mouseleave to close it, so open
@@ -145,7 +292,8 @@ export class UiHoverCard extends WebComponent({
       // 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;
+        // Same focus care as every other close path: the card may hold focus.
+        this._closeReleasingFocus();
         document.removeEventListener('pointerdown', onOutside, true);
       }
     };
@@ -162,6 +310,10 @@ export class UiHoverCard extends WebComponent({
   updated(changedProperties: Map<string, unknown>): void {
     if (!changedProperties.has('open')) return;
     if (changedProperties.get('open') === undefined) return;
+    // Bind synchronously rather than in the microtask below, which bails on
+    // engines with no Popover API: Escape has to work regardless of that.
+    if (this.open) this._bindEscape();
+    else this._unbindEscape();
     // Wait one microtask for <ui-hover-card-content>'s inner [popover]
     // element to commit; we drive its showPopover() / hidePopover() and
     // refresh the trigger's aria-expanded.
@@ -260,6 +412,10 @@ UiHoverCardTrigger.register('ui-hover-card-trigger');
 // The mouseenter/mouseleave handlers keep the card open while the cursor
 // is over the content itself (so it does not close during a brief
 // mouseleave on the trigger if the user is moving toward the card).
+// focusin/focusout mirror that linger for the KEYBOARD: the trigger closes
+// the card on its own focusout, so without these, Tabbing from the trigger
+// toward the card scheduled the close before focus could land inside, and
+// the interactive content the JSDoc example shows was unreachable.
 // --------------------------------------------------------------------------
 
 export class UiHoverCardContent extends WebComponent {
@@ -271,6 +427,8 @@ export class UiHoverCardContent extends WebComponent {
       class=${hoverCardContentClass()}
       @mouseenter=${this._onEnter}
       @mouseleave=${this._onLeave}
+      @focusin=${this._onEnter}
+      @focusout=${this._onLeave}
     ><slot></slot></div>`;
   }
 

package/packages/registry/components/input.ts

@@ -15,10 +15,42 @@
  * Design tokens used: --input, --background, --primary, --primary-foreground,
  * --muted-foreground, --foreground, --ring, --destructive.
  *
+ * A11y (required for accessible output):
+ *   LABEL IT. A `<label class=${labelClass()} for="<the input's id">` is the
+ *   whole requirement, and the `for` / `id` pair is what links them. Without it
+ *   the input has no accessible name and a screen reader announces only "edit
+ *   text". A `placeholder` is NOT a label: it disappears the moment the user
+ *   types, and some engines never expose it as a name at all.
+ *   Every `aria-describedby` must point at an element that EXISTS on the page.
+ *   A dangling id silently contributes nothing, so the hint or error text is
+ *   never announced; the example below therefore renders the `#email-hint` node
+ *   it references rather than assuming it.
+ *   On a validation failure set `aria-invalid="true"` (the class styles the
+ *   error ring off it) and point `aria-describedby` at the error text, so the
+ *   reason is announced along with the field rather than only shown in red.
+ *   Set the right `type` and `autocomplete`. Both are accessibility features:
+ *   `type` picks the mobile keyboard and the native validation, and
+ *   `autocomplete` is what lets a password manager or an autofill user avoid
+ *   retyping. `type="search"` / `type="email"` also announce as such.
+ *   A required field wants the native `required` attribute, not just an
+ *   asterisk in the label, so the state reaches assistive tech.
+ *
  * @example
  * ```html
- * <input class=${inputClass()} type="email" name="email" id="email" required
- *        aria-describedby="email-hint">
+ * <div class=${fieldClass()}>
+ *   <label class=${labelClass()} for="email">Email</label>
+ *   <input class=${inputClass()} type="email" name="email" id="email" required
+ *          autocomplete="email" aria-describedby="email-hint">
+ *   <p class=${hintClass()} id="email-hint">We never share it.</p>
+ * </div>
+ *
+ * <!-- Failed validation: invalid state plus the reason, both announced. -->
+ * <div class=${fieldClass()}>
+ *   <label class=${labelClass()} for="email-2">Email</label>
+ *   <input class=${inputClass()} type="email" name="email" id="email-2"
+ *          aria-invalid="true" aria-describedby="email-2-error" value="nope">
+ *   <p class=${errorClass()} id="email-2-error">Enter a valid email address.</p>
+ * </div>
  * ```
  */
 import { cn } from '../lib/utils.ts';

package/packages/registry/components/kbd.ts

@@ -8,12 +8,45 @@
  *
  * Design tokens used: --muted, --muted-foreground, --background.
  *
+ * A11y (required for accessible output):
+ *   SYMBOL-ONLY KEYS NEED A SPOKEN NAME. A screen reader reads a bare glyph
+ *   however its speech engine happens to handle that codepoint, so a key shown
+ *   as a symbol can be announced as a meaningless character name or skipped
+ *   entirely. Spell the name the way a person says it: `⌘` is "Command", `⇧`
+ *   "Shift", `⌥` "Option", `⌃` "Control", `⏎` "Enter", `⌫` "Backspace", `␣`
+ *   "Space", `⎋` "Escape", and the arrows are "Up arrow" and friends. A key
+ *   already spelled in words ("Shift", "K") reads correctly and needs nothing.
+ *   DO NOT put `aria-label` on the `<kbd>` itself. `<kbd>` maps to
+ *   `role=generic`, where a name is prohibited and browsers ignore it, so it
+ *   would silently do nothing. Supply the name as TEXT instead: hide the glyph
+ *   with `aria-hidden="true"` and put the spoken form in a visually-hidden
+ *   sibling (`sr-only`), which every screen reader reads.
+ *   NAME THE CHORD, not just the keys, since three `<kbd>` elements are
+ *   otherwise announced as three separate things with no hint they are pressed
+ *   together. Wrap the group in an element with `role="img"` and an
+ *   `aria-label` of the whole chord: `role="img"` both SUPPORTS a name (unlike
+ *   generic) and makes its children presentational, so the chord is announced
+ *   once as one thing. Do not use `role="group"` + `aria-hidden` children for
+ *   this: that leaves the group with nothing to announce.
+ *   Keep the native `<kbd>` element. The class is styling only; `<kbd>` is what
+ *   carries the "this is keyboard input" semantic.
+ *   `<kbd>` DOCUMENTS a shortcut, it does not create one. If the shortcut is
+ *   real, it also needs a keyboard handler, must not clash with an assistive-tech
+ *   or browser binding, and per WCAG 2.1.4 a single-character shortcut has to be
+ *   remappable or disableable.
+ *
  * @example
  * ```html
- * <kbd class=${kbdClass()}>⌘</kbd>
+ * <!-- A symbol key: hide the glyph, supply the spoken form as text. An
+ *      aria-label on the <kbd> itself would be ignored (role=generic). -->
+ * <kbd class=${kbdClass()} aria-hidden="true">⌘</kbd><span class="sr-only">Command</span>
+ *
+ * <!-- A spelled-out key needs nothing. -->
  * <kbd class=${kbdClass()}>K</kbd>
  *
- * <div class=${kbdGroupClass()}>
+ * <!-- A chord, announced once as one thing. role="img" supports a name AND
+ *      makes its children presentational, so the glyphs are not read twice. -->
+ * <div class=${kbdGroupClass()} role="img" aria-label="Command Shift P">
  *   <kbd class=${kbdClass()}>⌘</kbd>
  *   <kbd class=${kbdClass()}>Shift</kbd>
  *   <kbd class=${kbdClass()}>P</kbd>

package/packages/registry/components/label.ts

@@ -12,10 +12,31 @@
  *
  * Design tokens used: none (typography only).
  *
+ * A11y (required for accessible output):
+ *   Put this on a REAL `<label>`, and link it to its control, either with `for`
+ *   pointing at the control's `id` (below) or by nesting the control inside the
+ *   `<label>`. That link is the entire point of the element: it supplies the
+ *   control's accessible name and makes clicking the text focus the control.
+ *   The same classes on a `<span>` or `<div>` look identical and name nothing.
+ *   One label, one control. `for` takes a single id, so a label cannot name a
+ *   group; use `<fieldset>` + `<legend>`, or a heading referenced by
+ *   `aria-labelledby`, for that.
+ *   Do not use a label as a heading for a non-control region. A label with no
+ *   control is inert; if it is really a section title, use a heading element.
+ *   The dimmed disabled look is presentational only (it keys on a parent's
+ *   `data-disabled` or a `peer-disabled:` sibling). Actually disable the
+ *   CONTROL: styling the label alone leaves a control that still takes input.
+ *
  * @example
  * ```html
  * <label class=${labelClass()} for="email">Email</label>
  * <input class=${inputClass()} id="email" name="email" type="email">
+ *
+ * <!-- Nesting works too, and needs no id / for pair. -->
+ * <label class=${labelClass()}>
+ *   <input type="checkbox" data-slot="checkbox" class=${checkboxClass()}>
+ *   Email me a receipt
+ * </label>
  * ```
  */
 

package/packages/registry/components/native-select.ts

@@ -21,15 +21,36 @@
  * Design tokens used: --input, --background, --primary, --primary-foreground,
  * --muted-foreground, --ring, --destructive.
  *
+ * A11y (required for accessible output):
+ *   LABEL IT. A `<label class=${labelClass()} for="<the select's id">` linked by
+ *   the `for` / `id` pair is the whole requirement. A `<select>` with no label
+ *   announces only its current value, so the user hears "Basic" with no idea it
+ *   is the billing plan.
+ *   The chevron is DECORATIVE and must stay `aria-hidden="true"`. It duplicates
+ *   information the select's own role already conveys, and it sits outside the
+ *   control, so without the attribute it is announced as a stray graphic.
+ *   There is no placeholder option in a `<select>`. If you need one, use a
+ *   `<option value="" disabled selected>` prompt, and keep `required` on the
+ *   select so an empty submit is caught natively.
+ *   Group long option lists with `<optgroup label="...">`; the label is
+ *   announced, so it is real structure rather than only a visual break.
+ *   Being native is the accessibility win here: the platform picker, the
+ *   keyboard behaviour, and the mobile UX come for free. Do not rebuild it as a
+ *   div-based listbox to gain styling.
+ *
  * @example
  * ```html
- * <div class=${nativeSelectWrapperClass()}>
- *   <select class=${nativeSelectClass()} name="plan">
- *     <option>Basic</option>
- *     <option>Pro</option>
- *   </select>
- *   <!-- chevron icon, decorative -->
- *   <svg class="${nativeSelectIconClass()}" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="m6 9 6 6 6-6" /></svg>
+ * <div class=${fieldClass()}>
+ *   <label class=${labelClass()} for="plan">Billing plan</label>
+ *   <div class=${nativeSelectWrapperClass()}>
+ *     <select class=${nativeSelectClass()} name="plan" id="plan" required>
+ *       <option value="" disabled selected>Choose a plan</option>
+ *       <option value="basic">Basic</option>
+ *       <option value="pro">Pro</option>
+ *     </select>
+ *     <!-- chevron icon, decorative -->
+ *     <svg class="${nativeSelectIconClass()}" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="m6 9 6 6 6-6" /></svg>
+ *   </div>
  * </div>
  * ```
  */

package/packages/registry/components/popover.ts

@@ -25,25 +25,61 @@
  *
  * Design tokens used: --popover, --popover-foreground, --border.
  *
+ * A11y (required for accessible output):
+ *   This is the Tier-1 component with the most for you to supply, because
+ *   `popoverContentClass()` returns only classes: the panel it styles is a bare
+ *   `<div popover>` with NO role and NO accessible name unless you add them.
+ *   GIVE THE PANEL `role="dialog"`, then NAME it with `aria-labelledby`
+ *   pointing at the `popoverTitleClass()` heading's `id`. Both halves matter: a
+ *   role with no name announces as a bare "dialog", and a name with no role is
+ *   never announced as a grouped thing at all. This is what shadcn's
+ *   `PopoverContent` does for you in React, and here it is yours.
+ *   Point `aria-describedby` at the `popoverDescriptionClass()` paragraph when
+ *   there is one, so the supporting line is announced with the panel.
+ *   TELL THE TRIGGER what it does: `aria-expanded` tracking the open state, and
+ *   `aria-haspopup="dialog"`. The browser does not derive either from
+ *   `popovertarget`, so without them the button announces as a plain button that
+ *   gives no hint a panel will appear. Keep `aria-expanded` in sync from the
+ *   panel's `toggle` event, which is the native signal for this.
+ *   Use `popover` (auto), not `popover="manual"`, unless you have a reason.
+ *   The auto mode is where the platform gives you light-dismiss, Escape-to-close,
+ *   and FOCUS RESTORATION back to the invoker; manual mode gives up all three
+ *   and makes them your problem.
+ *   Make the title a REAL heading element (`<h2>` / `<h3>`) at the right level
+ *   for its place in the page, not a styled `<div>`, so it appears in the
+ *   heading outline a screen reader user navigates by.
+ *
  * @example
  * ```html
  * <!-- Single invoker, implicit anchor, zero inline style. -->
- * <button popovertarget="filter" class=${buttonClass({ variant: 'outline' })}>Filter</button>
- * <div id="filter" popover
+ * <button popovertarget="filter" aria-expanded="false" aria-haspopup="dialog"
+ *         class=${buttonClass({ variant: 'outline' })}>Filter</button>
+ * <div id="filter" popover role="dialog" aria-labelledby="filter-title"
+ *      aria-describedby="filter-desc"
  *      class=${popoverContentClass({ side: 'bottom', align: 'start', sideOffset: 4 })}>
  *   <div class=${popoverHeaderClass()}>
- *     <h3 class=${popoverTitleClass()}>Filter posts</h3>
- *     <p class=${popoverDescriptionClass()}>By tag and status.</p>
+ *     <h3 class=${popoverTitleClass()} id="filter-title">Filter posts</h3>
+ *     <p class=${popoverDescriptionClass()} id="filter-desc">By tag and status.</p>
  *   </div>
  * </div>
  *
+ * <!-- Keep the trigger's aria-expanded in sync from the native toggle event. -->
+ * <script type="module">
+ *   const panel = document.getElementById('filter');
+ *   const trigger = document.querySelector('[popovertarget="filter"]');
+ *   panel.addEventListener('toggle', (e) => {
+ *     trigger.setAttribute('aria-expanded', String(e.newState === 'open'));
+ *   });
+ * </script>
+ *
  * <!-- Explicit anchor, for multiple invokers or anchoring to a different element. -->
  * <span style="anchor-name: --picker">@vivek</span>
- * <button popovertarget="profile">Show</button>
- * <div id="profile" popover style="position-anchor: --picker"
+ * <button popovertarget="profile" aria-expanded="false" aria-haspopup="dialog">Show</button>
+ * <div id="profile" popover role="dialog" aria-labelledby="profile-title"
+ *      style="position-anchor: --picker"
  *      class=${popoverContentClass({ side: 'bottom' })}>
  *   <div class=${popoverHeaderClass()}>
- *     <h3 class=${popoverTitleClass()}>Vivek Khandelwal</h3>
+ *     <h3 class=${popoverTitleClass()} id="profile-title">Vivek Khandelwal</h3>
  *     <p class=${popoverDescriptionClass()}>@vivek</p>
  *   </div>
  * </div>

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

@@ -11,16 +11,37 @@
  *
  * Design tokens used: --input, --primary, --ring, --destructive.
  *
+ * A11y (required for accessible output):
+ *   `data-slot="radio"` is REQUIRED, not decoration. The injected stylesheet
+ *   keys the indicator dot on it, and `radioClass()` carries no checked
+ *   background fill, so without the attribute a SELECTED radio differs from an
+ *   unselected one by border colour alone. That is both easy to miss and a
+ *   WCAG 1.4.1 problem (state by colour only). Every example here carries it.
+ *   NAME THE GROUP. A bare `<div role="radiogroup">` has no accessible name, so
+ *   a screen reader announces "radio group" with no idea what is being chosen.
+ *   Point `aria-labelledby` at the visible group label, as below, or use a
+ *   `<fieldset>` + `<legend>` instead of the `role="radiogroup"` div.
+ *   Give every input the SAME `name`, which is what makes the browser treat
+ *   them as one set: it supplies single-selection, Arrow-key navigation, and a
+ *   single tab stop for free. Different names produce N independent radios that
+ *   can all be selected at once.
+ *   Label each input with `<label for>` pointing at its `id`, and mark the
+ *   group `aria-invalid="true"` plus an `aria-describedby` error element when
+ *   the selection fails validation.
+ *
  * @example
  * ```html
- * <div role="radiogroup" class=${radioGroupClass()}>
- *   <div class="flex items-center gap-2">
- *     <input type="radio" name="plan" value="basic" id="plan-basic" class=${radioClass()}>
- *     <label class=${labelClass()} for="plan-basic">Basic</label>
- *   </div>
- *   <div class="flex items-center gap-2">
- *     <input type="radio" name="plan" value="pro" id="plan-pro" class=${radioClass()}>
- *     <label class=${labelClass()} for="plan-pro">Pro</label>
+ * <div class=${fieldClass()}>
+ *   <span class=${fieldLabelClass()} id="plan-label">Billing plan</span>
+ *   <div role="radiogroup" aria-labelledby="plan-label" class=${radioGroupClass()}>
+ *     <div class="flex items-center gap-2">
+ *       <input type="radio" data-slot="radio" name="plan" value="basic" id="plan-basic" class=${radioClass()}>
+ *       <label class=${labelClass()} for="plan-basic">Basic</label>
+ *     </div>
+ *     <div class="flex items-center gap-2">
+ *       <input type="radio" data-slot="radio" name="plan" value="pro" id="plan-pro" class=${radioClass()}>
+ *       <label class=${labelClass()} for="plan-pro">Pro</label>
+ *     </div>
  *   </div>
  * </div>
  * ```
@@ -109,7 +130,14 @@ export function radioGroupClass(opts: { orientation?: RadioGroupOrientation } =
     : 'grid gap-3';
 }
 
-/** Tailwind classes for a styled `<input type="radio">`. Add `data-slot="radio"` for the indicator dot. */
+/**
+ * Tailwind classes for a styled `<input type="radio">`.
+ *
+ * PAIR THIS WITH `data-slot="radio"` ON THE SAME INPUT. The injected stylesheet
+ * keys the indicator dot on that attribute, and this class deliberately carries
+ * no checked background fill, so the class alone leaves a selected radio
+ * differing from an unselected one by border colour and nothing else.
+ */
 export function radioClass(): string {
   return cn(RADIO_CLASS);
 }