@webjsdev/ui 0.3.5 → 0.3.7

package/README.md

@@ -30,14 +30,32 @@ is configured, the components render correctly. Variant names, sizes, and
 data-attribute conventions mirror shadcn's so an AI agent's existing
 knowledge of shadcn maps directly.
 
-Tier-2 elements extend `WebComponent` from `@webjsdev/core`, a tiny
-Lit-shaped base class with `static properties` for reactive attributes,
+Tier-2 elements extend the `WebComponent({ ... })` factory from
+`@webjsdev/core`, a tiny Lit-shaped base class whose factory shape declares
+reactive attributes,
 `render()` returning an `` html`...` `` template, and declarative
 bindings (`@click`, `?attr`, `attr=`). Light DOM throughout, so Tailwind
 utility classes on authored children apply directly. The `webjsui add`
 CLI installs `@webjsdev/core` automatically when you add a Tier-2
 component.
 
+## Accessibility
+
+Tier-2 elements are accessible out of the box: they wire their own WAI-ARIA
+pattern, so you do not hand-add ARIA. Tabs cross-links triggers and panels and
+reports orientation, toggle-group uses roving tabindex with Arrow / Home / End,
+dropdown-menu declares orientation and reflects `aria-disabled`, dialog and
+alert-dialog name themselves from their title and description, tooltip wires
+`aria-describedby`, hover-card exposes `aria-haspopup` / `aria-expanded`, and
+sonner is a live region.
+
+Tier-1 class helpers return only classes, so the semantic element and ARIA are
+yours to supply. Each one's JSDoc carries an `A11y (required for accessible
+output)` block stating exactly what to add: a name on an icon-only button, a
+role on an alert, `scope` on table headers, `alt` on an avatar image, a
+labelled `<nav>` with `aria-current="page"` on pagination and breadcrumb, and
+so on. Follow that block and the markup is fully accessible.
+
 ## Install
 
 ### Option A : Webjs users (already have `@webjsdev/cli`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/ui",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "type": "module",
   "description": "An AI-first component library - class-helper functions for visuals, custom elements only where state matters. Source-copied into your repo, you own it. Works with any Tailwind v4 project.",
   "bin": {
@@ -19,7 +19,8 @@
     "README.md"
   ],
   "scripts": {
-    "test": "node --test test/*.test.js"
+    "test": "node --test test/*.test.js",
+    "test:e2e:touch": "node test/e2e/touch.e2e.mjs"
   },
   "dependencies": {
     "commander": "^14.0.0",

package/packages/registry/components/alert-dialog.ts

@@ -32,8 +32,8 @@
  *     </ui-alert-dialog-trigger>
  *     <ui-alert-dialog-content>
  *       <div class=${alertDialogHeaderClass()}>
- *         <h2 class=${alertDialogTitleClass()}>Delete account?</h2>
- *         <p class=${alertDialogDescriptionClass()}>This cannot be undone.</p>
+ *         <h2 data-slot="alert-dialog-title" class=${alertDialogTitleClass()}>Delete account?</h2>
+ *         <p data-slot="alert-dialog-description" class=${alertDialogDescriptionClass()}>This cannot be undone.</p>
  *       </div>
  *       <div class=${alertDialogFooterClass()}>
  *         <ui-alert-dialog-cancel>Cancel</ui-alert-dialog-cancel>
@@ -63,8 +63,9 @@
  *
  * Design tokens used: --background, --border, --muted-foreground.
  */
-import { WebComponent, html } from '@webjsdev/core';
+import { WebComponent, html, prop } from '@webjsdev/core';
 import { ref, createRef } from '@webjsdev/core/directives';
+import { ensureId, onBeforeCache } from '../lib/utils.ts';
 import { buttonClass, type ButtonVariant, type ButtonSize } from './button.ts';
 
 export const alertDialogContentClass = (): string =>
@@ -86,7 +87,10 @@ ui-alert-dialog:not([open]) ui-alert-dialog-content { display: none !important;
 ui-alert-dialog-content { display: grid; }
 `;
 
-const NATIVE_DIALOG_CLASS = 'border-0 bg-transparent p-0 m-0 w-0 h-0 max-w-none max-h-none overflow-visible text-inherit backdrop:bg-black/50';
+// Fills the viewport (fixed inset-0), NOT 0x0 (#730): WebKit makes a
+// top-layer <dialog> the containing block for its position:fixed descendants,
+// so a 0x0 host collapsed the fixed content panel to 0x0 (invisible on iOS).
+const NATIVE_DIALOG_CLASS = 'fixed inset-0 border-0 bg-transparent p-0 m-0 max-w-none max-h-none overflow-visible text-inherit backdrop:bg-black/50';
 
 function installStyles(): void {
   if (typeof document === 'undefined') return;
@@ -131,27 +135,30 @@ function unlockScroll(): void {
 // content child via prop transitions.
 // --------------------------------------------------------------------------
 
-export class UiAlertDialog extends WebComponent {
-  static properties = {
-    open: { type: Boolean, reflect: true },
-  };
-  declare open: boolean;
-
+export class UiAlertDialog extends WebComponent({
+  open: prop(Boolean, { reflect: true }),
+}) {
   constructor() {
     super();
     this.open = false;
   }
 
+  _disposeBeforeCache?: () => void;
+
   connectedCallback(): void {
     installStyles();
     // Legacy <ui-alert-dialog-overlay> isn't supported anymore; the native
     // ::backdrop pseudo replaces it. Strip it if a stale doc uses it.
     this.querySelector<HTMLElement>(':scope > ui-alert-dialog-overlay')?.remove();
     super.connectedCallback?.();
+    // Close before a back/forward snapshot: a modal restored half-open (the
+    // `open` attr without the native showModal top-layer state) is broken (#766).
+    this._disposeBeforeCache = onBeforeCache(() => { this.open = false; });
   }
 
   disconnectedCallback(): void {
     if (this.open) this._teardown();
+    this._disposeBeforeCache?.();
     super.disconnectedCallback?.();
   }
 
@@ -223,12 +230,9 @@ UiAlertDialogTrigger.register('ui-alert-dialog-trigger');
 // explicit choice via Cancel / Action).
 // --------------------------------------------------------------------------
 
-export class UiAlertDialogContent extends WebComponent {
-  static properties = {
-    size: { type: String, reflect: true },
-  };
-  declare size: 'default' | 'sm';
-
+export class UiAlertDialogContent extends WebComponent({
+  size: prop<'default' | 'sm'>(String, { reflect: true }),
+}) {
   // ref to the own-rendered native <dialog>. render() creates it, so a
   // ref() binding is the lit-idiomatic handle (no querySelector against
   // a string selector into the component's own output).
@@ -239,13 +243,44 @@ export class UiAlertDialogContent extends WebComponent {
     this.size = 'default';
   }
 
+  // Query the native <dialog> rather than the #dialog ref: the ref's `.value`
+  // came back null on iOS WebKit (the binding did not populate through SSR
+  // hydration), so showModal() never ran (#730). querySelector is robust on
+  // every engine.
+  _native(): HTMLDialogElement | null {
+    return this.querySelector<HTMLDialogElement>('dialog[data-slot="alert-dialog-native"]');
+  }
+
   showModal(): void {
-    const native = this.#dialog.value;
+    this._wireLabels();
+    const native = this._native();
     if (native && !native.open) native.showModal();
   }
 
+  // Wire the alertdialog's accessible name + description to its title /
+  // description nodes at open time (an alert dialog only ever appears via
+  // showModal(), so there is no SSR id-stability concern). The title is
+  // data-slot="alert-dialog-title" (falling back to the first heading); the
+  // description is data-slot="alert-dialog-description" (falling back to the
+  // first paragraph). Author-set ARIA always wins. Inlined rather than shared
+  // with dialog.ts so `webjs ui add alert-dialog` stays self-contained.
+  _wireLabels(): void {
+    const panel = this.querySelector('[data-slot="alert-dialog-content"]');
+    if (!panel) return;
+    const title =
+      this.querySelector('[data-slot="alert-dialog-title"]') ?? this.querySelector('h1, h2, h3');
+    const desc =
+      this.querySelector('[data-slot="alert-dialog-description"]') ?? this.querySelector('p');
+    if (title && !panel.hasAttribute('aria-labelledby')) {
+      panel.setAttribute('aria-labelledby', ensureId(title as HTMLElement, 'ui-alert-title'));
+    }
+    if (desc && !panel.hasAttribute('aria-describedby')) {
+      panel.setAttribute('aria-describedby', ensureId(desc as HTMLElement, 'ui-alert-desc'));
+    }
+  }
+
   close(): void {
-    const native = this.#dialog.value;
+    const native = this._native();
     if (native?.open) native.close();
   }
 
@@ -311,14 +346,10 @@ UiAlertDialogContent.register('ui-alert-dialog-content');
 
 const ALERT_DIALOG_ACTION_GRID_STRETCH = 'group-data-[size=sm]/alert-dialog-content:w-full';
 
-export class UiAlertDialogCancel extends WebComponent {
-  static properties = {
-    variant: { type: String, reflect: true },
-    size: { type: String, reflect: true },
-  };
-  declare variant: ButtonVariant;
-  declare size: ButtonSize;
-
+export class UiAlertDialogCancel extends WebComponent({
+  variant: prop<ButtonVariant>(String, { reflect: true }),
+  size: prop<ButtonSize>(String, { reflect: true }),
+}) {
   constructor() {
     super();
     this.variant = 'outline';
@@ -338,14 +369,10 @@ export class UiAlertDialogCancel extends WebComponent {
 }
 UiAlertDialogCancel.register('ui-alert-dialog-cancel');
 
-export class UiAlertDialogAction extends WebComponent {
-  static properties = {
-    variant: { type: String, reflect: true },
-    size: { type: String, reflect: true },
-  };
-  declare variant: ButtonVariant;
-  declare size: ButtonSize;
-
+export class UiAlertDialogAction extends WebComponent({
+  variant: prop<ButtonVariant>(String, { reflect: true }),
+  size: prop<ButtonSize>(String, { reflect: true }),
+}) {
   constructor() {
     super();
     this.variant = 'default';

package/packages/registry/components/alert.ts

@@ -25,6 +25,11 @@
  *     </div>
  *   </div>
  *
+ * A11y (required for accessible output): put role="alert" on the container
+ * for an urgent, interrupting message, or role="status" for a polite,
+ * non-urgent update. The class helper sets no role, so without one the
+ * banner is silent to assistive tech.
+ *
  * Design tokens used: --card, --card-foreground, --destructive, --muted-foreground.
  */
 import { cn } from '../lib/utils.ts';

package/packages/registry/components/avatar.ts

@@ -23,6 +23,11 @@
  *     <div class=${avatarGroupCountClass()}>+3</div>
  *   </div>
  *
+ * A11y (required for accessible output): the <img> MUST have an alt that
+ * names the person (alt="Vivek Khandelwal"), or alt="" when a visible text
+ * fallback already names them. Always provide the fallback <span> so the
+ * avatar is still named if the image fails to load.
+ *
  * Design tokens used: --muted, --muted-foreground, --primary, --background.
  */
 import { cn } from '../lib/utils.ts';

package/packages/registry/components/badge.ts

@@ -14,6 +14,10 @@
  * The `[a&]:hover:...` hover styles only apply when the element is an `<a>`,
  * so a static `<span>` doesn't pick up an unwanted hover.
  *
+ * A11y (required for accessible output): render a static badge as a plain
+ * <span> (not focusable, no tabindex). Only an interactive badge (an <a>
+ * or <button>) is focusable, and an icon-only one needs an aria-label.
+ *
  * Design tokens used: --primary, --secondary, --destructive, --foreground,
  * --accent, --border, --ring.
  */

package/packages/registry/components/breadcrumb.ts

@@ -26,6 +26,11 @@
  *     </ol>
  *   </nav>
  *
+ * A11y (required for accessible output): wrap the list in <nav
+ * aria-label="breadcrumb">, set aria-current="page" on the current-page
+ * element, and mark each separator role="presentation" aria-hidden="true".
+ * The class helpers emit none of these.
+ *
  * Design tokens used: --muted-foreground, --foreground.
  */
 

package/packages/registry/components/button.ts

@@ -17,6 +17,12 @@
  * shadcn React's `asChild` (Slot) prop has no equivalent here: just call
  * `buttonClass(...)` and spread the classes onto whatever element you want.
  *
+ * A11y (required for accessible output): an icon-only button (the `icon`,
+ * `icon-xs`, `icon-sm`, `icon-lg` sizes) has no visible text, so it MUST
+ * carry an accessible name via aria-label (or aria-labelledby). A button
+ * that opens an overlay should also set aria-haspopup and aria-expanded.
+ * Native <button> focus and keyboard activation are already correct.
+ *
  * Design tokens used: --primary, --primary-foreground, --destructive,
  * --secondary, --secondary-foreground, --accent, --accent-foreground,
  * --background, --input, --ring.

package/packages/registry/components/dialog.ts

@@ -29,8 +29,8 @@
  *     </ui-dialog-trigger>
  *     <ui-dialog-content>
  *       <div class=${dialogHeaderClass()}>
- *         <h2 class=${dialogTitleClass()}>Edit profile</h2>
- *         <p class=${dialogDescriptionClass()}>Make changes and click save.</p>
+ *         <h2 data-slot="dialog-title" class=${dialogTitleClass()}>Edit profile</h2>
+ *         <p data-slot="dialog-description" class=${dialogDescriptionClass()}>Make changes and click save.</p>
  *       </div>
  *       <div class="grid gap-3">
  *         <label class=${labelClass()} for="dlg-name">Name</label>
@@ -63,10 +63,33 @@
  *
  * Design tokens used: --background, --border, --muted-foreground.
  */
-import { WebComponent, html, unsafeHTML } from '@webjsdev/core';
+import { WebComponent, html, unsafeHTML, prop } from '@webjsdev/core';
 import { ref, createRef } from '@webjsdev/core/directives';
+import { ensureId, onBeforeCache } from '../lib/utils.ts';
 import { buttonClass } from './button.ts';
 
+// Wires a dialog panel's accessible name + description to its title /
+// description nodes. A dialog only ever appears via showModal() (JS), so
+// resolving the relationship at open time is correct and avoids any
+// SSR id-stability concern. The title is the element marked
+// data-slot="dialog-title" (falling back to the first heading); the
+// description is data-slot="dialog-description" (falling back to the first
+// paragraph). Author-set aria-labelledby / aria-describedby always win.
+export function wireDialogLabels(host: Element, panelSelector: string): void {
+  const panel = host.querySelector(panelSelector);
+  if (!panel) return;
+  const title =
+    host.querySelector('[data-slot="dialog-title"]') ?? host.querySelector('h1, h2, h3');
+  const desc =
+    host.querySelector('[data-slot="dialog-description"]') ?? host.querySelector('p');
+  if (title && !panel.hasAttribute('aria-labelledby')) {
+    panel.setAttribute('aria-labelledby', ensureId(title as HTMLElement, 'ui-dialog-title'));
+  }
+  if (desc && !panel.hasAttribute('aria-describedby')) {
+    panel.setAttribute('aria-describedby', ensureId(desc as HTMLElement, 'ui-dialog-desc'));
+  }
+}
+
 // --------------------------------------------------------------------------
 // Class helpers for subparts.
 // --------------------------------------------------------------------------
@@ -110,7 +133,16 @@ ui-dialog-content { display: grid; }
 // Clears the UA defaults on <dialog> so it becomes an invisible top-layer
 // host. The visible box is rendered by <ui-dialog-content>. The
 // backdrop: variant styles the ::backdrop pseudo-element.
-const NATIVE_DIALOG_CLASS = 'border-0 bg-transparent p-0 m-0 w-0 h-0 max-w-none max-h-none overflow-visible text-inherit backdrop:bg-black/50';
+//
+// The host FILLS THE VIEWPORT (fixed inset-0) rather than collapsing to
+// 0x0 (#730): WebKit makes a top-layer <dialog> the containing block for
+// its position:fixed descendants, so a 0x0 host collapsed the fixed content
+// panel (w-full) to 0x0 and the dialog was invisible on iOS (Blink resolves
+// the same fixed panel against the viewport, so it worked on Android). A
+// viewport-sized transparent host gives the panel a correct containing block
+// on both engines; the panel still centers itself and the ::backdrop covers
+// the screen.
+const NATIVE_DIALOG_CLASS = 'fixed inset-0 border-0 bg-transparent p-0 m-0 max-w-none max-h-none overflow-visible text-inherit backdrop:bg-black/50';
 
 function installStyles(): void {
   if (typeof document === 'undefined') return;
@@ -157,27 +189,30 @@ function unlockScroll(): void {
 // to showModal() / close() its inner <dialog>.
 // --------------------------------------------------------------------------
 
-export class UiDialog extends WebComponent {
-  static properties = {
-    open: { type: Boolean, reflect: true },
-  };
-  declare open: boolean;
-
+export class UiDialog extends WebComponent({
+  open: prop(Boolean, { reflect: true }),
+}) {
   constructor() {
     super();
     this.open = false;
   }
 
+  _disposeBeforeCache?: () => void;
+
   connectedCallback(): void {
     installStyles();
     // Legacy <ui-dialog-overlay> isn't supported anymore; the native
     // ::backdrop pseudo replaces it. Strip it if a stale doc uses it.
     this.querySelector<HTMLElement>(':scope > ui-dialog-overlay')?.remove();
     super.connectedCallback?.();
+    // Close before a back/forward snapshot: a modal restored half-open (the
+    // `open` attr without the native showModal top-layer state) is broken (#766).
+    this._disposeBeforeCache = onBeforeCache(() => { this.open = false; });
   }
 
   disconnectedCallback(): void {
     if (this.open) this._teardown();
+    this._disposeBeforeCache?.();
     super.disconnectedCallback?.();
   }
 
@@ -257,12 +292,9 @@ UiDialogTrigger.register('ui-dialog-trigger');
 // close button. Exposes showModal() / close() so the parent <ui-dialog>
 // can drive the open state imperatively without a named slot.
 
-export class UiDialogContent extends WebComponent {
-  static properties = {
-    showCloseButton: { type: String, reflect: true, attribute: 'show-close-button' },
-  };
-  declare showCloseButton: string;
-
+export class UiDialogContent extends WebComponent({
+  showCloseButton: prop(String, { reflect: true, attribute: 'show-close-button' }),
+}) {
   // ref to the own-rendered native <dialog>. render() creates it, so a
   // ref() binding is the lit-idiomatic handle (no querySelector against
   // a string selector into the component's own output).
@@ -273,13 +305,23 @@ export class UiDialogContent extends WebComponent {
     this.showCloseButton = 'true';
   }
 
+  // Resolve the native <dialog> by query, NOT the #dialog ref: on iOS WebKit
+  // the ref's `.value` came back null (the ref binding did not populate through
+  // SSR hydration), so showModal() was never called and the dialog never opened
+  // (#730). A direct querySelector is robust on every engine, and matches what
+  // the tooltip / popover components already do.
+  _native(): HTMLDialogElement | null {
+    return this.querySelector<HTMLDialogElement>('dialog[data-slot="dialog-native"]');
+  }
+
   showModal(): void {
-    const native = this.#dialog.value;
+    wireDialogLabels(this, '[data-slot="dialog-content"]');
+    const native = this._native();
     if (native && !native.open) native.showModal();
   }
 
   close(): void {
-    const native = this.#dialog.value;
+    const native = this._native();
     if (native?.open) native.close();
   }
 
@@ -359,12 +401,9 @@ UiDialogClose.register('ui-dialog-close');
 // <ui-dialog-footer>
 // --------------------------------------------------------------------------
 
-export class UiDialogFooter extends WebComponent {
-  static properties = {
-    showCloseButton: { type: String, attribute: 'show-close-button' },
-  };
-  declare showCloseButton: string | null;
-
+export class UiDialogFooter extends WebComponent({
+  showCloseButton: prop<string | null>(String, { attribute: 'show-close-button' }),
+}) {
   constructor() {
     super();
     this.showCloseButton = null;