@webjsdev/ui 0.3.12 → 0.3.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/ui",
-  "version": "0.3.12",
+  "version": "0.3.14",
   "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/native-select.ts

@@ -9,14 +9,16 @@
  *   NativeSelect wrapper     → nativeSelectWrapperClass()
  *   NativeSelect chevron     → nativeSelectIconClass()
  *   NativeSelect option      → bare <option> (or nativeSelectOptionClass()
- *                              for explicit overrides; the installed
+ *                              for explicit overrides, since the theme
  *                              stylesheet sets Canvas / CanvasText on
  *                              every <option> automatically)
  *
- * Importing this module installs a stylesheet that forces Canvas /
- * CanvasText on every <option> inside the wrapper so the dropdown reads
- * in both light and dark themes regardless of OS preference; advanced
- * overrides use `nativeSelectOptionClass()` / `nativeSelectOptGroupClass()`.
+ * The theme stylesheet forces Canvas / CanvasText on every <option> so the
+ * dropdown reads in both light and dark themes regardless of OS preference.
+ * It arrives with the design tokens (`npx @webjsdev/ui init`, or `add`, which
+ * writes the block when it is missing), so it is in the first paint and works
+ * with JavaScript off. Advanced overrides use `nativeSelectOptionClass()` and
+ * `nativeSelectOptGroupClass()`.
  *
  * Design tokens used: --input, --background, --primary, --primary-foreground,
  * --muted-foreground, --ring, --destructive.
@@ -58,61 +60,17 @@ import { cn } from '../lib/utils.ts';
 
 export type NativeSelectSize = 'default' | 'sm';
 
-// Auto-apply Canvas/CanvasText to every <option> on the page. Without
-// this, an <option> with no explicit bg paints transparent on top of
-// the browser-popup background; in dark mode (when color-scheme: dark
-// is set on <html>) Chrome's popup is dark, the option's transparent
-// bg lets the popup colour through, and the inherited text colour
-// from the <select> matches that dark popup: the option disappears,
-// only the focused/selected one stays visible because the browser
-// overlays its own highlight on it.
+// The <option> / <optgroup> colour rule is NOT injected from here. It lives in
+// the theme stylesheet the kit installs, so it is in the first paint, works
+// with JavaScript off, and does not make this module client-effecting (a
+// module-scope call pins every page that imports it, #1320). See the
+// `select option, select optgroup` rule in the theme block.
 //
-// Original selector required the option to be inside a
-// `.group/native-select` wrapper, on the assumption every user would
-// follow the documented Usage block above. But it's easy to write a
-// bare <select class=${nativeSelectClass()}> without the wrapper
-// (legitimate when you don't need the chevron icon: the popover and
-// hover-card docs examples both do this), in which case the rule
-// never matched and the dropdown reverted to invisible-options.
-// Broadening to `select option, select optgroup` makes the fix work
-// everywhere the user has imported native-select, with no required
-// wrapper. The Canvas/CanvasText pair is a safe default: they ARE
-// the system colours the browser would have painted anyway when no
-// rule applied; we just stop relying on inheritance to pull through.
-// Selector specificity is 0,0,2 (two elements), so any user who
-// genuinely needs custom <option> colours can override with a single
-// class anywhere in their cascade (e.g. `.my-select option { ... }`
-// at 0,1,2 wins).
-//
-// `nativeSelectOptionClass()` and `nativeSelectOptGroupClass()` stay
-// exported for users who want to opt into the same colours via the
-// class helper instead of the global rule. They emit the same
-// `bg-[Canvas] text-[CanvasText]` Tailwind utilities: redundant if
-// this stylesheet is installed, but harmless and matches the broader
-// shadcn convention of "every part has a class helper".
-const STYLES = `
-select option,
-select optgroup {
-  background-color: Canvas;
-  color: CanvasText;
-}
-`;
-
-let installed = false;
-export function installNativeSelectStyles(): void {
-  if (installed || typeof document === 'undefined') return;
-  if (document.getElementById('ui-native-select-styles')) {
-    installed = true;
-    return;
-  }
-  const style = document.createElement('style');
-  style.id = 'ui-native-select-styles';
-  style.textContent = STYLES;
-  document.head.appendChild(style);
-  installed = true;
-}
-
-if (typeof document !== 'undefined') installNativeSelectStyles();
+// `nativeSelectOptionClass()` and `nativeSelectOptGroupClass()` stay exported
+// for users who want to opt into the same colours via a class helper. They
+// emit the same `bg-[Canvas] text-[CanvasText]` utilities: redundant when the
+// theme block is present, harmless, and they match the broader shadcn
+// convention that every part has a class helper.
 
 export const nativeSelectWrapperClass = (): string =>
   'group/native-select relative w-fit has-[select:disabled]:opacity-50';

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/packages/registry/lib/utils.ts

@@ -50,99 +50,106 @@ function walk(value: ClassValue, out: string[]): void {
 // IMPORTANT: text-size (text-sm, text-xs, text-base, text-lg, …) and
 // text-color (text-primary, text-foreground, …) are DIFFERENT properties
 // and must be in different groups. Same for bg-size vs bg-color etc.
-const GROUPS: Array<[RegExp, string]> = [
-  [/^p-/, 'p'], [/^px-/, 'px'], [/^py-/, 'py'], [/^pt-/, 'pt'], [/^pr-/, 'pr'], [/^pb-/, 'pb'], [/^pl-/, 'pl'],
-  [/^m-/, 'm'], [/^mx-/, 'mx'], [/^my-/, 'my'], [/^mt-/, 'mt'], [/^mr-/, 'mr'], [/^mb-/, 'mb'], [/^ml-/, 'ml'],
-  [/^w-/, 'w'], [/^h-/, 'h'], [/^size-/, 'size'],
-  // A `bg-[url(…)]` / `bg-[linear-gradient(…)]` background image is classified
-  // by its FUNCTION, since it carries no type hint to classify it by. The
-  // hinted forms are handled centrally, in `hintedGroup`.
-  [/^bg-\[(url\(|linear-gradient|radial-gradient|conic-gradient)/, 'bg-image'],
-  [/^bg-(linear|gradient|conic|radial|none)/, 'bg-image'],
-  [/^bg-(no-repeat|repeat|repeat-x|repeat-y|repeat-round|repeat-space)$/, 'bg-repeat'],
-  [/^bg-(fixed|local|scroll)$/, 'bg-attach'],
-  [/^bg-(auto|cover|contain)$/, 'bg-size'],
-  [/^bg-size-/, 'bg-size'],
-  // Two entries rather than one alternation: the first covers the live v4
-  // compounds (`bg-top-left`), the second the bare keywords plus the v4.1
-  // deprecated reversed compounds (`bg-left-top`), which tailwind-merge still
-  // carries. An unmatched `bg-*` token falls into the colour catch-all below and
-  // evicts a real colour, so admitting a dead spelling is the safe direction.
-  [/^bg-(top|bottom)(-(left|right))?$/, 'bg-position'],
-  [/^bg-(left|right|center)(-(top|bottom))?$/, 'bg-position'],
-  [/^bg-position-/, 'bg-position'],
-  // Clip, origin, and blend mode are three more properties under the same
-  // prefix. Each sat in `bg-color` before, so `bg-clip-text` evicted a real
-  // background colour (the gradient-text idiom lost its clip silently).
-  [/^bg-clip-(border|padding|content|text)$/, 'bg-clip'],
-  [/^bg-origin-(border|padding|content)$/, 'bg-origin'],
-  [/^bg-blend-(normal|multiply|screen|overlay|darken|lighten|color-dodge|color-burn|hard-light|soft-light|difference|exclusion|hue|saturation|color|luminosity)$/, 'bg-blend'],
-  [/^bg-/, 'bg-color'],
-  // text-shadow is its own property, and its size scale and its colour are two
-  // properties again. All three entries precede the text- patterns below, which
-  // is what keeps a `text-shadow-*` token out of `text-size` and `text-color`.
-  [/^text-shadow(-(2xs|xs|sm|md|lg|none))?(\/([\d.]+|\[[^\]]*\]))?$/, 'text-shadow'],
-  [/^text-shadow-(\[(inset|-|\.|\d|var\()|\(--)/, 'text-shadow'],
-  [/^text-shadow-/, 'text-shadow-color'],
-  // Font size: explicit list of Tailwind size scale.
-  [/^text-(xs|sm|base|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl|8xl|9xl)$/, 'text-size'],
-  // Alignment, wrapping, and overflow are three more properties under the same
-  // prefix. Each was previously excluded from text-color by a lookahead and then
-  // matched nothing at all, so two alignments never collapsed.
-  [/^text-(left|center|right|justify|start|end)$/, 'text-align'],
-  [/^text-(wrap|nowrap|balance|pretty)$/, 'text-wrap'],
-  [/^text-(ellipsis|clip)$/, 'text-overflow'],
-  // Text color: anything else under the prefix. The specific groups above are
-  // the whole carve-out, so no negative lookahead is needed here as well.
-  [/^text-/, 'text-color'],
-  // Border sub-properties that are neither a width nor a colour. These come
-  // FIRST so the width / colour classifier below never sees them.
-  [/^border-(collapse|separate)$/, 'border-collapse'],
-  [/^border-spacing(-[xy])?-/, 'border-spacing'],
-  [/^border-(solid|dashed|dotted|double|hidden|none)$/, 'border-style'],
-  ...borderGroups(),
-  [/^rounded(-[a-z]+)?$/, 'rounded'],
-  [/^rounded-/, 'rounded'],
-  [/^opacity-/, 'opacity'],
-  [/^font-(thin|light|normal|medium|semibold|bold|black|extralight|extrabold)$/, 'font-weight'],
-  // Box-shadow SIZE and box-shadow COLOUR are two properties (`box-shadow` and
-  // `--tw-shadow-color`), so they need two groups. `shadow-none` is a size,
-  // `shadow-inherit` / `shadow-initial` are colours, and Tailwind accepts an
-  // alpha modifier on a size as well as on a colour, so `shadow-lg/25` has to
-  // stay on the size side. An unhinted arbitrary value is a SIZE when it opens
-  // with `inset`, a sign, a dot, or a digit (a shadow offset list) and also
-  // when it is a bare `var()` or the `(--x)` variable shorthand: Tailwind
-  // itself resolves an ambiguous arbitrary shadow to `box-shadow` unless the
-  // value is provably a colour, and `shadow-[var(--shadow-glow)]` is the normal
-  // way to write a design-token shadow. This is the one place the
-  // `borderGroups()` convention inverts, because a bare `border-[var(--x)]` is
-  // far more often a colour while a bare `shadow-[var(--x)]` is far more often
-  // a shadow. The size entries must precede the colour catch-all, or every
-  // size lands in the colour group and the bug inverts rather than being fixed.
-  [/^shadow(-(2xs|xs|sm|md|lg|xl|2xl|inner|none))?(\/([\d.]+|\[[^\]]*\]))?$/, 'shadow'],
-  [/^shadow-(\[(inset|-|\.|\d|var\()|\(--)/, 'shadow'],
-  // A bare name the size scale does not list reads as a colour, because
-  // `shadow-primary` is overwhelmingly more common than a `@theme`-extended
-  // `--shadow-card`. A project that adds a custom shadow NAME is the residual
-  // gap, and the docs say so rather than claiming the split is total.
-  [/^shadow-/, 'shadow-color'],
-  [/^z-/, 'z'],
-  // A bare `flex` / `grid` is a DISPLAY value, not a member of the flex / grid
-  // sub-property groups below, so it must never dedupe against them: an element
-  // can be both a flex container and a flex child (`class="flex flex-1"`), and
-  // collapsing the two silently drops `display:flex`. It still belongs to a
-  // group of its own, alongside every other display keyword, so a repeated one
-  // collapses and `cn('hidden', open && 'flex')` resolves to one display.
-  [/^(inline-block|inline-flex|inline-grid|inline-table|inline|block|flex|grid|flow-root|contents|hidden|list-item|table-caption|table-cell|table-column-group|table-column|table-footer-group|table-header-group|table-row-group|table-row|table)$/, 'display'],
-  // Each sub-utility below gets the group of the real CSS property it sets, so
-  // none of them collapses against the display value or against each other.
-  [/^flex-(row|row-reverse|col|col-reverse)$/, 'flex-direction'],
-  [/^flex-(wrap|wrap-reverse|nowrap)$/, 'flex-wrap'],
-  [/^flex-(\d+|auto|initial|none|\[[^\]]*\])$/, 'flex'],
-  [/^grid-cols-/, 'grid-cols'],
-  [/^grid-rows-/, 'grid-rows'],
-  [/^grid-flow-/, 'grid-flow'],
-];
+// Built on FIRST USE, not at module load. A module-scope `...borderGroups()`
+// spread is a real top-level call, so the elision analyser reads this module as
+// client-effecting and every page that reaches `cn` on a component-free path
+// ships whole instead of being elided (#1320).
+let _groups: Array<[RegExp, string]> | undefined;
+function GROUPS(): Array<[RegExp, string]> {
+  return (_groups ??= [
+    [/^p-/, 'p'], [/^px-/, 'px'], [/^py-/, 'py'], [/^pt-/, 'pt'], [/^pr-/, 'pr'], [/^pb-/, 'pb'], [/^pl-/, 'pl'],
+    [/^m-/, 'm'], [/^mx-/, 'mx'], [/^my-/, 'my'], [/^mt-/, 'mt'], [/^mr-/, 'mr'], [/^mb-/, 'mb'], [/^ml-/, 'ml'],
+    [/^w-/, 'w'], [/^h-/, 'h'], [/^size-/, 'size'],
+    // A `bg-[url(…)]` / `bg-[linear-gradient(…)]` background image is classified
+    // by its FUNCTION, since it carries no type hint to classify it by. The
+    // hinted forms are handled centrally, in `hintedGroup`.
+    [/^bg-\[(url\(|linear-gradient|radial-gradient|conic-gradient)/, 'bg-image'],
+    [/^bg-(linear|gradient|conic|radial|none)/, 'bg-image'],
+    [/^bg-(no-repeat|repeat|repeat-x|repeat-y|repeat-round|repeat-space)$/, 'bg-repeat'],
+    [/^bg-(fixed|local|scroll)$/, 'bg-attach'],
+    [/^bg-(auto|cover|contain)$/, 'bg-size'],
+    [/^bg-size-/, 'bg-size'],
+    // Two entries rather than one alternation: the first covers the live v4
+    // compounds (`bg-top-left`), the second the bare keywords plus the v4.1
+    // deprecated reversed compounds (`bg-left-top`), which tailwind-merge still
+    // carries. An unmatched `bg-*` token falls into the colour catch-all below and
+    // evicts a real colour, so admitting a dead spelling is the safe direction.
+    [/^bg-(top|bottom)(-(left|right))?$/, 'bg-position'],
+    [/^bg-(left|right|center)(-(top|bottom))?$/, 'bg-position'],
+    [/^bg-position-/, 'bg-position'],
+    // Clip, origin, and blend mode are three more properties under the same
+    // prefix. Each sat in `bg-color` before, so `bg-clip-text` evicted a real
+    // background colour (the gradient-text idiom lost its clip silently).
+    [/^bg-clip-(border|padding|content|text)$/, 'bg-clip'],
+    [/^bg-origin-(border|padding|content)$/, 'bg-origin'],
+    [/^bg-blend-(normal|multiply|screen|overlay|darken|lighten|color-dodge|color-burn|hard-light|soft-light|difference|exclusion|hue|saturation|color|luminosity)$/, 'bg-blend'],
+    [/^bg-/, 'bg-color'],
+    // text-shadow is its own property, and its size scale and its colour are two
+    // properties again. All three entries precede the text- patterns below, which
+    // is what keeps a `text-shadow-*` token out of `text-size` and `text-color`.
+    [/^text-shadow(-(2xs|xs|sm|md|lg|none))?(\/([\d.]+|\[[^\]]*\]))?$/, 'text-shadow'],
+    [/^text-shadow-(\[(inset|-|\.|\d|var\()|\(--)/, 'text-shadow'],
+    [/^text-shadow-/, 'text-shadow-color'],
+    // Font size: explicit list of Tailwind size scale.
+    [/^text-(xs|sm|base|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl|8xl|9xl)$/, 'text-size'],
+    // Alignment, wrapping, and overflow are three more properties under the same
+    // prefix. Each was previously excluded from text-color by a lookahead and then
+    // matched nothing at all, so two alignments never collapsed.
+    [/^text-(left|center|right|justify|start|end)$/, 'text-align'],
+    [/^text-(wrap|nowrap|balance|pretty)$/, 'text-wrap'],
+    [/^text-(ellipsis|clip)$/, 'text-overflow'],
+    // Text color: anything else under the prefix. The specific groups above are
+    // the whole carve-out, so no negative lookahead is needed here as well.
+    [/^text-/, 'text-color'],
+    // Border sub-properties that are neither a width nor a colour. These come
+    // FIRST so the width / colour classifier below never sees them.
+    [/^border-(collapse|separate)$/, 'border-collapse'],
+    [/^border-spacing(-[xy])?-/, 'border-spacing'],
+    [/^border-(solid|dashed|dotted|double|hidden|none)$/, 'border-style'],
+    ...borderGroups(),
+    [/^rounded(-[a-z]+)?$/, 'rounded'],
+    [/^rounded-/, 'rounded'],
+    [/^opacity-/, 'opacity'],
+    [/^font-(thin|light|normal|medium|semibold|bold|black|extralight|extrabold)$/, 'font-weight'],
+    // Box-shadow SIZE and box-shadow COLOUR are two properties (`box-shadow` and
+    // `--tw-shadow-color`), so they need two groups. `shadow-none` is a size,
+    // `shadow-inherit` / `shadow-initial` are colours, and Tailwind accepts an
+    // alpha modifier on a size as well as on a colour, so `shadow-lg/25` has to
+    // stay on the size side. An unhinted arbitrary value is a SIZE when it opens
+    // with `inset`, a sign, a dot, or a digit (a shadow offset list) and also
+    // when it is a bare `var()` or the `(--x)` variable shorthand: Tailwind
+    // itself resolves an ambiguous arbitrary shadow to `box-shadow` unless the
+    // value is provably a colour, and `shadow-[var(--shadow-glow)]` is the normal
+    // way to write a design-token shadow. This is the one place the
+    // `borderGroups()` convention inverts, because a bare `border-[var(--x)]` is
+    // far more often a colour while a bare `shadow-[var(--x)]` is far more often
+    // a shadow. The size entries must precede the colour catch-all, or every
+    // size lands in the colour group and the bug inverts rather than being fixed.
+    [/^shadow(-(2xs|xs|sm|md|lg|xl|2xl|inner|none))?(\/([\d.]+|\[[^\]]*\]))?$/, 'shadow'],
+    [/^shadow-(\[(inset|-|\.|\d|var\()|\(--)/, 'shadow'],
+    // A bare name the size scale does not list reads as a colour, because
+    // `shadow-primary` is overwhelmingly more common than a `@theme`-extended
+    // `--shadow-card`. A project that adds a custom shadow NAME is the residual
+    // gap, and the docs say so rather than claiming the split is total.
+    [/^shadow-/, 'shadow-color'],
+    [/^z-/, 'z'],
+    // A bare `flex` / `grid` is a DISPLAY value, not a member of the flex / grid
+    // sub-property groups below, so it must never dedupe against them: an element
+    // can be both a flex container and a flex child (`class="flex flex-1"`), and
+    // collapsing the two silently drops `display:flex`. It still belongs to a
+    // group of its own, alongside every other display keyword, so a repeated one
+    // collapses and `cn('hidden', open && 'flex')` resolves to one display.
+    [/^(inline-block|inline-flex|inline-grid|inline-table|inline|block|flex|grid|flow-root|contents|hidden|list-item|table-caption|table-cell|table-column-group|table-column|table-footer-group|table-header-group|table-row-group|table-row|table)$/, 'display'],
+    // Each sub-utility below gets the group of the real CSS property it sets, so
+    // none of them collapses against the display value or against each other.
+    [/^flex-(row|row-reverse|col|col-reverse)$/, 'flex-direction'],
+    [/^flex-(wrap|wrap-reverse|nowrap)$/, 'flex-wrap'],
+    [/^flex-(\d+|auto|initial|none|\[[^\]]*\])$/, 'flex'],
+    [/^grid-cols-/, 'grid-cols'],
+    [/^grid-rows-/, 'grid-rows'],
+    [/^grid-flow-/, 'grid-flow'],
+  ]);
+}
 
 /**
  * Border WIDTH and border COLOUR share the `border-` prefix but are different
@@ -155,9 +162,11 @@ const GROUPS: Array<[RegExp, string]> = [
  * Classification, after an optional side / axis segment: a bare or numeric
  * value is a width (`border`, `border-2`, `border-t-4`), an arbitrary value
  * that opens with a digit, a dot, or `length:` is a width (`border-[3px]`,
- * `border-[length:var(--w)]`), and everything else is a colour
+ * `border-[length:var(--w)]`, and the v4 paren spelling
+ * `border-(length:--w)`), and everything else is a colour
  * (`border-primary`, `border-red-500/50`, `border-[#fff]`). An ambiguous
- * `border-[var(--x)]` falls to colour, which is the far more common intent.
+ * `border-[var(--x)]`, or its paren spelling `border-(--x)`, falls to colour,
+ * which is the far more common intent.
  *
  * Each side is its own group so a per-side utility only overrides its own side,
  * and the shorthand / axis subsumption is declared in CONFLICTS below, exactly
@@ -167,7 +176,7 @@ const GROUPS: Array<[RegExp, string]> = [
  * the writing direction, so an axis override there would be a guess.
  */
 function borderGroups(): Array<[RegExp, string]> {
-  const width = '(\\d+(\\.\\d+)?|\\[(length:|\\d|\\.)[^\\]]*\\])';
+  const width = '(\\d+(\\.\\d+)?|\\[(length:|\\d|\\.)[^\\]]*\\]|\\(length:[^)]*\\))';
   const out: Array<[RegExp, string]> = [];
   // Sides before the bare form: `border-t-primary` must match the `t` colour
   // group, not be swallowed by the side-less `^border-` colour pattern.
@@ -185,7 +194,8 @@ function borderGroups(): Array<[RegExp, string]> {
 
 /**
  * An arbitrary value may carry a Tailwind TYPE HINT: `bg-[image:var(--g)]`,
- * `text-[length:14px]`, `shadow-[color:red]`. The hint exists precisely because
+ * `text-[length:14px]`, `shadow-[color:red]`, and in the v4 paren shorthand
+ * `bg-(image:--g)`, `shadow-(color:--x)`. The hint exists precisely because
  * the utility prefix is ambiguous, so the PREFIX cannot decide the group and
  * the hint must. Letting a hinted value fall into the prefix's default group
  * evicts a class that sets an entirely different property (`shadow-[color:red]`
@@ -204,7 +214,13 @@ function borderGroups(): Array<[RegExp, string]> {
  * while `bg-` and `text-` were correct.
  *
  * These reach the matcher at all only because `variantPrefix` splits on the
- * last colon OUTSIDE brackets; see the comment there.
+ * last colon OUTSIDE brackets AND parentheses; see the comment there.
+ *
+ * Both spellings of one hint produce the identical `<prefix>:<hint>` key, so
+ * the map needs no paren-specific entries. The closing delimiter is
+ * deliberately not validated: the hint names the CSS property, and how the
+ * value terminates cannot change which property that is (the bracket branch
+ * has never validated its own close either).
  */
 const HINTED_GROUPS: Record<string, string> = {
   'bg:color': '',
@@ -227,7 +243,7 @@ const HINTED_GROUPS: Record<string, string> = {
  * should decide it, `undefined` when the token carries no hint at all.
  */
 function hintedGroup(bare: string): string | null | undefined {
-  const m = /^([a-z][a-z-]*)-\[([a-z][a-z-]*):/.exec(bare);
+  const m = /^([a-z][a-z-]*)-[\[(]([a-z][a-z-]*):/.exec(bare);
   if (!m) return undefined;
   const prefix = m[1];
   const hint = m[2];
@@ -283,7 +299,7 @@ function dedupeUtilities(input: string): string {
     const hinted = hintedGroup(bare);
     let gk: string | null = hinted ?? null;
     if (hinted === undefined || hinted === null) {
-      for (const [re, g] of GROUPS) {
+      for (const [re, g] of GROUPS()) {
         if (re.test(bare)) { gk = g; break; }
       }
     }
@@ -303,19 +319,32 @@ function dedupeUtilities(input: string): string {
 
 function variantPrefix(token: string): string {
   // Capture leading variants like `hover:`, `dark:`, `md:`: overrides only
-  // conflict within the same variant set. The split is the last colon OUTSIDE
-  // square brackets, because an arbitrary value can contain one of its own
-  // (`border-[length:2px]`, `bg-[url(https://x/y.png)]`, `text-[color:var(--c)]`).
+  // conflict within the same variant set. The split is the last colon at top
+  // level, meaning outside BOTH square brackets and parentheses, because an
+  // arbitrary value can contain a colon of its own in either delimiter
+  // (`border-[length:2px]`, `bg-[url(https://x/y.png)]`, `text-[color:var(--c)]`,
+  // and the v4 paren spelling `shadow-(color:--x)`, `bg-(image:--g)`).
   // Splitting on the last colon anywhere hands the group matcher a fragment
-  // like `2px]`, which matches nothing, so the utility silently stops
-  // deduping against its own property.
-  let depth = 0;
+  // like `2px]` or `--x)`, which matches nothing, so the utility silently
+  // stops deduping against its own property.
+  //
+  // TWO counters, both required to be zero, rather than one shared counter.
+  // Tailwind's own top-level splitter (`segment()`, in the upstream
+  // tailwindlabs/tailwindcss repo at packages/tailwindcss/src/utils/segment.ts,
+  // NOT a path in this repo) is a MATCHED-PAIR stack, so a
+  // stray closer never cancels a live opener of the other kind. A single
+  // shared counter would let `)` cancel `[` and read `x-[y)-z:w` as having a
+  // top-level colon, which is the fragment bug above wearing a different hat.
+  let bracketDepth = 0;
+  let parenDepth = 0;
   let i = -1;
   for (let n = 0; n < token.length; n += 1) {
     const c = token[n];
-    if (c === '[') depth += 1;
-    else if (c === ']') depth -= 1;
-    else if (c === ':' && depth === 0) i = n;
+    if (c === '[') bracketDepth += 1;
+    else if (c === ']') bracketDepth -= 1;
+    else if (c === '(') parenDepth += 1;
+    else if (c === ')') parenDepth -= 1;
+    else if (c === ':' && bracketDepth === 0 && parenDepth === 0) i = n;
   }
   return i === -1 ? '' : token.slice(0, i + 1);
 }

package/packages/registry/themes/index.css

@@ -149,4 +149,17 @@
     outline: 2px solid color-mix(in oklab, var(--color-ring) 50%, transparent);
     outline-offset: 2px;
   }
+  /* Native <select> options paint transparent over the browser popup when no
+     rule applies, so in dark mode Chrome's dark popup plus the inherited text
+     colour makes every unselected option disappear. Canvas / CanvasText are
+     the system colours the browser would have painted anyway, so this stops
+     relying on inheritance to pull them through. Two ELEMENT selectors
+     (specificity 0,0,2) and no wrapper requirement on purpose: a bare
+     <select class=${nativeSelectClass()}> with no wrapper is legitimate, and
+     any single class overrides this. */
+  select option,
+  select optgroup {
+    background-color: Canvas;
+    color: CanvasText;
+  }
 }