@webjsdev/ui 0.3.13 → 0.3.15

package/README.md

@@ -127,6 +127,7 @@ always compares against the live upstream.
 | `webjsui diff [name]` | Show diff between your local copy and the live registry |
 | `webjsui info` | Print project diagnostics |
 | `webjsui build` | (For registry authors) Compile a custom registry |
+| `webjsui lint` | Opt-in design-system linter. Reports raw palette colors, arbitrary values and classes composed over a kit helper, at the line, with a message built from your own theme tokens and helper variants. Configured by a `lint` block in `components.json`; with no block it reports nothing and exits 0. `--json` for an agent loop, `--max-warnings <n>` to pin a count. |
 
 ## Tag convention
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/ui",
-  "version": "0.3.13",
+  "version": "0.3.15",
   "type": "module",
   "description": "The AI-first component library for WebJs, a full-stack JavaScript framework built on web components with server-side rendering and no build step. Class-helper functions for visuals, custom elements only where state matters, source-copied into your repo so you own it.",
   "bin": {
@@ -21,7 +21,8 @@
   ],
   "scripts": {
     "test": "node --test test/*.test.js",
-    "test:e2e:touch": "node test/e2e/touch.e2e.mjs"
+    "test:e2e:touch": "node test/e2e/touch.e2e.mjs",
+    "test:e2e:a11y-tree": "node test/e2e/a11y-tree.e2e.mjs"
   },
   "dependencies": {
     "commander": "^14.0.0",

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

@@ -55,6 +55,11 @@
  *   Treat that as a bug in your markup rather than a feature: this dialog
  *   interrupts the user to demand an explicit choice and blocks Escape, so
  *   naming it "Alert dialog" tells them nothing about what they are deciding.
+ *   `role="alertdialog"` and the name both sit on the NATIVE `<dialog>`, a
+ *   valid ARIA-in-HTML override of that element's implicit `dialog` role, so
+ *   exactly one dialog-family node is exposed rather than an `alertdialog`
+ *   nested inside a `dialog`. There is no `aria-modal`: the platform already
+ *   exposes a `showModal()`-opened dialog as modal.
  *
  * Design tokens used: --background, --border, --muted-foreground.
  *
@@ -417,18 +422,23 @@ export class UiAlertDialogContent extends WebComponent({
       panel.setAttribute('aria-describedby', authored);
       return;
     }
+    // Clear the previous open's value before resolving again. The panel keeps
+    // its attributes between opens, so a guard that skips when the attribute is
+    // already present can never re-resolve, and a removed description node
+    // leaves a stale aria-describedby pointing at a dead IDREF.
+    panel.removeAttribute('aria-describedby');
     const desc =
       this.querySelector('[data-slot="alert-dialog-description"]') ?? this.querySelector('p');
-    if (desc && !panel.hasAttribute('aria-describedby')) {
+    if (desc) {
       panel.setAttribute('aria-describedby', ensureId(desc as HTMLElement, 'ui-alert-desc'));
     }
   }
 
   _wireLabels(): void {
-    const panel = this.querySelector('[data-slot="alert-dialog-content"]');
+    const panel = this.querySelector('dialog[data-slot="alert-dialog-native"]');
     if (!panel) return;
     // A name the author put on <ui-alert-dialog-content> is where they
-    // naturally write it, but role="alertdialog" lives on the inner panel.
+    // naturally write it, but role="alertdialog" lives on the native <dialog>.
     //
     // Each authored-name branch RETURNS rather than falling through to the
     // title wiring. Falling through would set aria-labelledby from the title
@@ -449,9 +459,13 @@ export class UiAlertDialogContent extends WebComponent({
       this._wireDescription(panel);
       return;
     }
+    // Same re-resolve rule: clear what a previous open wrote, or a removed
+    // title node leaves a stale aria-labelledby that points at a dead IDREF AND
+    // suppresses the floor below, which exists to prevent exactly that state.
+    panel.removeAttribute('aria-labelledby');
     const title =
       this.querySelector('[data-slot="alert-dialog-title"]') ?? this.querySelector('h1, h2, h3');
-    if (title && !panel.hasAttribute('aria-labelledby')) {
+    if (title) {
       panel.setAttribute('aria-labelledby', ensureId(title as HTMLElement, 'ui-alert-title'));
     }
     this._wireDescription(panel);
@@ -472,15 +486,13 @@ export class UiAlertDialogContent extends WebComponent({
     const parentOpen = !!this._parent()?.open;
     return html`<dialog
       data-slot="alert-dialog-native"
+      role="alertdialog"
       class=${NATIVE_DIALOG_CLASS}
       ${ref(this.#dialog)}
       @cancel=${this._onNativeCancel}
       @close=${this._onNativeClose}
     ><div
       data-slot="alert-dialog-content"
-      role="alertdialog"
-      aria-modal="true"
-      tabindex="-1"
       data-size=${this.size}
       data-state=${parentOpen ? 'open' : 'closed'}
       class=${alertDialogContentClass()}

package/packages/registry/components/dialog.ts

@@ -47,6 +47,10 @@
  *   floor to make an unnamed modal impossible, NOT a substitute: give the
  *   dialog a real title, since "Dialog" tells a screen reader user nothing
  *   about what they have been interrupted with.
+ *   `role="dialog"` and the name both sit on the NATIVE `<dialog>`, not on the
+ *   inner content div, so exactly one dialog-family node is exposed in the
+ *   accessibility tree. There is no `aria-modal`: a `showModal()`-opened
+ *   native dialog is already exposed as modal by the platform.
  *
  * Design tokens used: --background, --border, --muted-foreground.
  *
@@ -111,9 +115,14 @@ function wireDialogDescription(host: Element, panel: Element): void {
     panel.setAttribute('aria-describedby', authored);
     return;
   }
+  // Clear the previous open's value before resolving again. The panel keeps its
+  // attributes between opens, so a guard that skips when the attribute is
+  // already present can never re-resolve: remove the description node and
+  // re-open, and the stale aria-describedby survives pointing at a dead IDREF.
+  panel.removeAttribute('aria-describedby');
   const desc =
     host.querySelector('[data-slot="dialog-description"]') ?? host.querySelector('p');
-  if (desc && !panel.hasAttribute('aria-describedby')) {
+  if (desc) {
     panel.setAttribute('aria-describedby', ensureId(desc as HTMLElement, 'ui-dialog-desc'));
   }
 }
@@ -122,7 +131,7 @@ export function wireDialogLabels(host: Element, panelSelector: string): void {
   const panel = host.querySelector(panelSelector);
   if (!panel) return;
   // A name the author put on <ui-dialog-content> is where they naturally write
-  // it, but role="dialog" lives on the inner panel, so forward it there.
+  // it, but role="dialog" lives on the native <dialog>, so forward it there.
   //
   // This RETURNS once an authored name is forwarded, rather than falling
   // through to the title wiring below. Falling through would set
@@ -144,9 +153,13 @@ export function wireDialogLabels(host: Element, panelSelector: string): void {
     wireDialogDescription(host, panel);
     return;
   }
+  // Same re-resolve rule: clear what a previous open wrote, or a removed title
+  // node leaves a stale aria-labelledby that points at a dead IDREF AND
+  // suppresses the floor below, which exists to prevent exactly that state.
+  panel.removeAttribute('aria-labelledby');
   const title =
     host.querySelector('[data-slot="dialog-title"]') ?? host.querySelector('h1, h2, h3');
-  if (title && !panel.hasAttribute('aria-labelledby')) {
+  if (title) {
     panel.setAttribute('aria-labelledby', ensureId(title as HTMLElement, 'ui-dialog-title'));
   }
   wireDialogDescription(host, panel);
@@ -505,7 +518,7 @@ export class UiDialogContent extends WebComponent({
   }
 
   showModal(): void {
-    wireDialogLabels(this, '[data-slot="dialog-content"]');
+    wireDialogLabels(this, 'dialog[data-slot="dialog-native"]');
     const native = this._native();
     if (native && !native.open) native.showModal();
   }
@@ -520,15 +533,13 @@ export class UiDialogContent extends WebComponent({
     const parentOpen = !!this._parent()?.open;
     return html`<dialog
       data-slot="dialog-native"
+      role="dialog"
       class=${NATIVE_DIALOG_CLASS}
       ${ref(this.#dialog)}
       @close=${this._onNativeClose}
       @click=${this._onNativeBackdropClick}
     ><div
       data-slot="dialog-content"
-      role="dialog"
-      aria-modal="true"
-      tabindex="-1"
       data-state=${parentOpen ? 'open' : 'closed'}
       class=${dialogContentClass()}
     >

package/packages/registry/components/sonner.ts

@@ -32,14 +32,21 @@
  *
  * 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
+ *   "Notifications", so a toast is announced as it is inserted, and it is the
+ *   ONLY live root an ordinary toast resolves under: a non-error toast carries
+ *   no role of its own, because `role="status"` is itself a live region and
+ *   nesting one inside the polite viewport bought nothing while making some
+ *   readers announce the toast twice. An `error` toast does carry
+ *   `role="alert"` so it is announced assertively, which is the only way to
+ *   make one item assertive inside a polite viewport, and its second live
+ *   root is the accepted cost of that urgency. 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.
+ *   aria-hidden; the meaning is in the text, and urgency in the viewport's
+ *   politeness plus `role="alert"` on an error toast.
  *
  * Design tokens used: --popover, --popover-foreground, --border, --radius.
  *
@@ -247,9 +254,16 @@ export class UiSonner extends WebComponent({
     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.
+    // each toast as it is inserted. It is polite, and it is the ONLY live
+    // root an ordinary toast resolves under.
+    //
+    // A non-error toast therefore carries no role of its own. It used to carry
+    // role="status", which is itself a live region, so the toast resolved under
+    // TWO nested live roots (measured over CDP, #1245) and some readers
+    // double-announce that. The inner role bought nothing, because the viewport
+    // is already polite. An `error` toast keeps role="alert", which is
+    // load-bearing: it is the only way to make ONE item assertive inside a
+    // polite viewport, and its second live root is the accepted cost.
     return html`<div
       data-slot="sonner"
       role="region"
@@ -262,12 +276,33 @@ export class UiSonner extends WebComponent({
       ${repeat(
         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'}
-        >
+        // The role is BRANCHED rather than written as a nullish hole. A hole
+        // that evaluates to null serves role="" from the server renderer while
+        // the client renderer removes the attribute, which is the divergence
+        // test/ssr-aria.test.js exists to catch, and an empty role is worse
+        // than no role: it is not a role, so the toast falls back to `generic`
+        // in a way no attribute assertion would notice.
+        (item) => (item.type === 'error'
+          ? html`<div
+              data-slot="sonner-toast"
+              class=${TOAST_ITEM_BASE}
+              data-type=${item.type}
+              role="alert"
+            >${this._toastBody(item)}</div>`
+          : html`<div
+              data-slot="sonner-toast"
+              class=${TOAST_ITEM_BASE}
+              data-type=${item.type}
+            >${this._toastBody(item)}</div>`),
+      )}
+    </div>`;
+  }
+
+  // The toast's contents, shared by both arms of the role branch above.
+  // A METHOD, not a module-scope value: a registry module does no work at
+  // module scope.
+  _toastBody(item: ToastItem) {
+    return html`
           <div class=${`${TYPE_ICON_COLOR[item.type]} pt-0.5`}>${unsafeHTML(ICONS[item.type])}</div>
           <div class="flex-1">
             <div class="font-medium">${item.message}</div>
@@ -304,9 +339,7 @@ export class UiSonner extends WebComponent({
             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>`;
+        `;
   }
 }
 UiSonner.register('ui-sonner');
@@ -316,8 +349,9 @@ UiSonner.register('ui-sonner');
 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.
+// Type glyphs, all decorative: the toast's text carries the meaning, and
+// urgency is conveyed by role="alert" on an error toast, not by the picture.
+// An ordinary toast carries no role and is announced by the polite viewport.
 const ICONS: Record<ToastType, string> = {
   default: '',
   success:

package/src/commands/lint.js

@@ -0,0 +1,93 @@
+import { Command } from 'commander';
+import { getConfig } from '../utils/get-config.js';
+import { lintApp } from '../lint/index.js';
+import { logger } from '../utils/logger.js';
+
+/**
+ * Run the linter and shape its report, with no printing and no exit, so the
+ * command test calls this directly. `code` is 0 or 1 only, matching `webjs
+ * check`'s posture that an agent gates on non-zero: 1 when any error-level
+ * violation exists, when the warning count exceeds `maxWarnings` (-1 is no
+ * cap), or when the command cannot run at all (no `components.json`, or a
+ * config that fails the schema).
+ *
+ * @param {{ cwd?: string, json?: boolean, maxWarnings?: number|string }} [opts]
+ * @returns {{ lines: string[], code: number, report: null | { violations: any[], summary: any, warnings: string[] } }}
+ */
+export function runLint(opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const maxWarnings = Number(opts.maxWarnings ?? -1);
+  /** @type {string[]} */
+  const lines = [];
+  // A run that cannot start still answers in the requested shape, so an agent
+  // loop parsing stdout under --json receives an error document, never text.
+  const refuse = (error) => {
+    if (opts.json) {
+      lines.push(JSON.stringify({ error, violations: [], summary: { count: 0, errors: 0, warnings: 0, byRule: {} }, warnings: [], configured: false }, null, 2));
+    } else {
+      lines.push(`webjsui lint: ${error}`);
+    }
+    return { lines, code: 1, report: null };
+  };
+  if (!Number.isInteger(maxWarnings) || maxWarnings < -1) {
+    return refuse(`--max-warnings expects an integer (-1 for no cap), got ${JSON.stringify(String(opts.maxWarnings))}`);
+  }
+  let config;
+  try {
+    config = getConfig(cwd);
+  } catch (e) {
+    return refuse(`components.json is invalid: ${firstIssue(e)}`);
+  }
+  if (!config) return refuse('components.json not found (run `npx @webjsdev/ui init`)');
+
+  const { violations, warnings, configured } = lintApp(cwd, config);
+  const errors = violations.filter((v) => v.severity === 'error').length;
+  const warns = violations.length - errors;
+  /** @type {Record<string, number>} */
+  const byRule = {};
+  for (const v of violations) byRule[v.rule] = (byRule[v.rule] ?? 0) + 1;
+  const report = {
+    violations,
+    summary: { count: violations.length, errors, warnings: warns, byRule },
+    warnings,
+    configured,
+  };
+
+  if (opts.json) {
+    lines.push(JSON.stringify(report, null, 2));
+  } else if (!configured) {
+    lines.push('webjsui lint: no rules configured (add a "lint" block to components.json)');
+  } else {
+    for (const w of warnings) lines.push(`⚠ ${w}`);
+    if (violations.length === 0) {
+      lines.push('webjsui lint: all checks pass ✓');
+    } else {
+      lines.push(`webjsui lint: ${violations.length} problem(s) found (${errors} error${errors === 1 ? '' : 's'}, ${warns} warning${warns === 1 ? '' : 's'})`);
+      for (const v of violations) {
+        lines.push('');
+        lines.push(`  ${v.severity === 'error' ? '✗' : '⚠'} [${v.rule}] ${v.file}:${v.line}:${v.column}`);
+        lines.push(`    ${v.message}`);
+      }
+    }
+  }
+  const code = errors > 0 || (maxWarnings >= 0 && warns > maxWarnings) ? 1 : 0;
+  return { lines, code, report };
+}
+
+function firstIssue(e) {
+  const issue = e?.issues?.[0];
+  if (issue) return `${issue.path?.join('.') || '(root)'}: ${issue.message}`;
+  return String(e?.message ?? e);
+}
+
+export const lint = new Command()
+  .name('lint')
+  .description('Check the app against its design system (opt-in, configured in components.json)')
+  .option('-c, --cwd <cwd>', 'the working directory', process.cwd())
+  .option('--json', 'emit structured violations for an agent loop')
+  .option('--max-warnings <n>', 'fail when warnings exceed this count', '-1')
+  .action((opts) => {
+    const { lines, code } = runLint(opts);
+    for (const l of lines) logger.info(l);
+    if (code !== 0) process.exitCode = code;
+  });

package/src/index.js

@@ -9,6 +9,7 @@ import { view } from './commands/view.js';
 import { diff } from './commands/diff.js';
 import { info } from './commands/info.js';
 import { build } from './commands/build.js';
+import { lint } from './commands/lint.js';
 
 const pkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8'));
 
@@ -27,6 +28,7 @@ program
   .addCommand(view)
   .addCommand(diff)
   .addCommand(info)
-  .addCommand(build);
+  .addCommand(build)
+  .addCommand(lint);
 
 program.parse();