@helixui/library 3.3.1 → 3.4.0-next.121

package/dist/css/helix-forms.css

@@ -72,6 +72,23 @@
 
   /* ─── Focus Ring ─── */
 
+  /*
+   * Host-focus path: on the modern (IDL element-references) render branch the
+   * host is the tabbable surface (tabindex=0) and the inner input is demoted
+   * to tabindex=-1. Drive the focus ring from ':host(:focus-visible)' so
+   * keyboard users still get a visible affordance. Codex round-11 P1.
+   */
+  :host(:focus-visible) .checkbox__box {
+    outline: var(--hx-checkbox-focus-ring-width, var(--hx-focus-ring-width, 2px)) solid
+      var(--hx-checkbox-focus-ring-color, var(--hx-focus-ring-color, #0f7078));
+    outline-offset: var(--hx-checkbox-focus-ring-offset, var(--hx-focus-ring-offset, 2px));
+  }
+
+  /*
+   * Fallback (no-IDL-ref) path: the host carries tabindex=-1 and the inner
+   * input is the tab target. The native :focus-visible on the input drives
+   * the same visual ring, scoped via the inner-state class.
+   */
   .checkbox__input:focus-visible ~ .checkbox__box {
     outline: var(--hx-checkbox-focus-ring-width, var(--hx-focus-ring-width, 2px)) solid
       var(--hx-checkbox-focus-ring-color, var(--hx-focus-ring-color, #0f7078));
@@ -226,6 +243,7 @@
       border: 2px solid ButtonText;
     }
 
+    :host(:focus-visible) .checkbox__box,
     .checkbox__input:focus-visible ~ .checkbox__box {
       outline: 3px solid Highlight;
       outline-offset: 2px;
@@ -402,6 +420,31 @@
     pointer-events: none;
     opacity: var(--hx-opacity-disabled, 0.5);
   }
+  /* Slotted label / help / error blocks for cross-shadow naming. */
+  .hx-color-picker__label {
+    display: block;
+    margin-bottom: var(--hx-space-1, 0.25rem);
+    font-weight: var(--hx-font-weight-semibold, 600);
+    color: var(--hx-color-neutral-900, #1a1a1a);
+  }
+  .hx-color-picker__label:empty {
+    display: none;
+  }
+  .hx-color-picker__help {
+    display: block;
+    margin-top: var(--hx-space-1, 0.25rem);
+    font-size: var(--hx-font-size-xs, 0.75rem);
+    color: var(--hx-color-neutral-600, #525252);
+  }
+  .hx-color-picker__error {
+    display: block;
+    margin-top: var(--hx-space-1, 0.25rem);
+    font-size: var(--hx-font-size-xs, 0.75rem);
+    color: var(--hx-color-danger-700, #c43e3e);
+  }
+  [hidden] {
+    display: none !important;
+  }
   .trigger {
     display: inline-flex;
     align-items: center;
@@ -1398,7 +1441,8 @@
      Live region (screen reader announcements)
      ============================================================ */
 
-  .calendar__live-region {
+  .calendar__live-region,
+  .field__sr-only {
     position: absolute;
     width: 1px;
     height: 1px;
@@ -2615,6 +2659,11 @@
 /* ─── 3-tier token cascade: component → semantic → hardcoded fallback ─── */
   :host {
     display: block;
+    /* Round-3 finding 1: host is the canonical combobox surface, so it owns
+       keyboard focus. Suppress the UA default outline; the custom focus ring
+       is painted on the inner trigger via :host(:focus-visible)
+       .field__trigger so visual feedback follows the host's focus state. */
+    outline: none;
 
     /* Background & foreground */
     --_bg: var(--hx-select-bg, var(--hx-color-surface-default, #ffffff));
@@ -2691,6 +2740,12 @@
   }
 
   .field__trigger {
+    /* Round-3 finding 1 / CodeRabbit F1: trigger is a <button type="button">
+       (labelable) so native <label for> click activation works for mouse
+       users. Reset native button chrome before applying field styles. */
+    appearance: none;
+    -webkit-appearance: none;
+    margin: 0;
     display: flex;
     align-items: center;
     justify-content: space-between;
@@ -2701,6 +2756,7 @@
     border-radius: var(--_border-radius);
     background-color: var(--_bg);
     color: var(--_color);
+    font: inherit;
     font-family: inherit;
     font-size: var(--hx-font-size-md, 1rem);
     line-height: var(--hx-line-height-normal, 1.5);
@@ -2713,6 +2769,11 @@
     outline: none;
   }
 
+  /* Round-3 finding 1: host is the canonical focusable surface. Both the
+     :host(:focus-visible) descendant selector AND the legacy
+     .field__trigger:focus-visible (kept for forced-colors regression test
+     parity) paint the focus ring on the visual trigger. */
+  :host(:focus-visible) .field__trigger,
   .field__trigger:focus-visible {
     border-color: var(--_focus-ring-color);
     box-shadow: 0 0 0 var(--hx-focus-ring-width, 2px)
@@ -2781,6 +2842,7 @@
     border-color: var(--_error-color);
   }
 
+  :host(:focus-visible) .field--error .field__trigger,
   .field--error .field__trigger:focus-visible {
     border-color: var(--_error-color);
     box-shadow: 0 0 0 var(--hx-focus-ring-width, 2px)
@@ -2914,6 +2976,7 @@
       border: 2px solid ButtonText;
     }
 
+    :host(:focus-visible) .field__trigger,
     .field__trigger:focus-visible {
       outline: 3px solid Highlight;
       outline-offset: 2px;
@@ -3328,6 +3391,22 @@
     appearance: none;
   }
 
+  /*
+   * Host-focus path: on the modern (IDL element-references) render branch the
+   * host is the tabbable surface (tabindex=0) and the inner track button is
+   * demoted to tabindex=-1. Drive the focus ring from ':host(:focus-visible)'
+   * so keyboard users still see a visible affordance. Codex round-11 P1.
+   */
+  :host(:focus-visible) .switch__track {
+    outline: var(--hx-focus-ring-width, 2px) solid
+      var(--hx-switch-focus-ring-color, var(--hx-focus-ring-color, #0f7078));
+    outline-offset: var(--hx-focus-ring-offset, 2px);
+  }
+
+  /*
+   * Fallback (no-IDL-ref) path: the host carries tabindex=-1 and the inner
+   * track button is the tab target. Native :focus-visible drives the ring.
+   */
   .switch__track:focus-visible {
     outline: var(--hx-focus-ring-width, 2px) solid
       var(--hx-switch-focus-ring-color, var(--hx-focus-ring-color, #0f7078));
@@ -3465,6 +3544,7 @@
       border: 2px solid ButtonText;
     }
 
+    :host(:focus-visible) .switch__track,
     .switch__track:focus-visible {
       outline: 3px solid Highlight;
       outline-offset: 2px;
@@ -4323,6 +4403,17 @@
   .field__error {
     color: var(--hx-time-picker-error-color, var(--hx-color-error-text, #c92a2a));
   }
+  .field__sr-only {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+  }
   @media (forced-colors: active) {
     .field__combobox {
       border-color: ButtonText;
@@ -4400,6 +4491,22 @@
     -webkit-user-select: none;
   }
 
+  /*
+   * Host-focus path: on the modern (IDL element-references) render branch the
+   * host is the tabbable surface (tabindex=0) and the inner <button> is
+   * demoted to tabindex=-1. Drive the focus ring from ':host(:focus-visible)'
+   * so keyboard users still see a visible affordance. Codex round-11 P1.
+   */
+  :host(:focus-visible) .button {
+    outline: var(--hx-focus-ring-width, 2px) solid
+      var(--hx-toggle-button-focus-ring-color, var(--hx-focus-ring-color, #0f7078));
+    outline-offset: var(--hx-focus-ring-offset, 2px);
+  }
+
+  /*
+   * Fallback (no-IDL-ref) path: the host carries tabindex=-1 and the inner
+   * <button> is the tab target. Native :focus-visible drives the ring.
+   */
   .button:focus-visible {
     outline: var(--hx-focus-ring-width, 2px) solid
       var(--hx-toggle-button-focus-ring-color, var(--hx-focus-ring-color, #0f7078));
@@ -4598,6 +4705,7 @@
       border: 2px solid ButtonText;
     }
 
+    :host(:focus-visible) .button,
     .button:focus-visible {
       outline: 3px solid Highlight;
       outline-offset: 2px;

package/dist/css/helix-overlay.css

@@ -456,6 +456,23 @@
     margin: 0;
   }
 
+  /* ─── Synthesized consumer-description span ─── */
+  /* Visually hidden mirror of consumer-resolved aria-describedby text used by */
+  /* the host-canonical ARIA pipeline. Always present in the shadow tree so AT */
+  /* can resolve the same-root id even when the description is currently empty. */
+
+  .drawer-sr-only {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+  }
+
   /* ─── Body ─── */
 
   .drawer-body {

package/dist/css/hx-alert.css

@@ -107,6 +107,15 @@
     min-width: 0;
   }
 
+  /* (group-6 5.1) Wrapper around the default slot. Carries aria-hidden=true
+     so the visible message text is not double-announced alongside the
+     sr-only announcer. display:contents keeps the wrapper visually
+     transparent so children participate in the parent flex layout as if
+     the wrapper were not there. */
+  .alert__default-slot {
+    display: contents;
+  }
+
   /* ─── Actions ─── */
   /* Hidden by default; shown via JS slotchange detection to avoid invisible  */
   /* margin-top spacing when no actions are slotted.                          */

package/dist/css/hx-badge.css

@@ -201,6 +201,9 @@
   @media (forced-colors: active) {
     .badge {
       border: 1px solid CanvasText;
+      forced-color-adjust: none;
+      background-color: Canvas;
+      color: CanvasText;
     }
 
     .badge--pulse {
@@ -210,4 +213,29 @@
     .badge__remove-button {
       color: ButtonText;
     }
+
+    /* Per-semantic-variant forced-colors fallbacks. The visually-hidden
+       semantic variant label (.badge__variant-label) keeps AT users
+       informed; these blocks restore visual semantic distinction for
+       sighted users in HCM where bg/color collapse to system defaults.
+       Pattern: distinct border-style per variant. */
+    .badge--success {
+      border-style: solid;
+      border-width: 2px;
+    }
+
+    .badge--warning {
+      border-style: dashed;
+      border-width: 2px;
+    }
+
+    .badge--error {
+      border-style: double;
+      border-width: 3px;
+    }
+
+    .badge--info {
+      border-style: dotted;
+      border-width: 2px;
+    }
   }

package/dist/css/hx-checkbox.css

@@ -70,6 +70,23 @@
 
   /* ─── Focus Ring ─── */
 
+  /*
+   * Host-focus path: on the modern (IDL element-references) render branch the
+   * host is the tabbable surface (tabindex=0) and the inner input is demoted
+   * to tabindex=-1. Drive the focus ring from ':host(:focus-visible)' so
+   * keyboard users still get a visible affordance. Codex round-11 P1.
+   */
+  :host(:focus-visible) .checkbox__box {
+    outline: var(--hx-checkbox-focus-ring-width, var(--hx-focus-ring-width, 2px)) solid
+      var(--hx-checkbox-focus-ring-color, var(--hx-focus-ring-color, #0f7078));
+    outline-offset: var(--hx-checkbox-focus-ring-offset, var(--hx-focus-ring-offset, 2px));
+  }
+
+  /*
+   * Fallback (no-IDL-ref) path: the host carries tabindex=-1 and the inner
+   * input is the tab target. The native :focus-visible on the input drives
+   * the same visual ring, scoped via the inner-state class.
+   */
   .checkbox__input:focus-visible ~ .checkbox__box {
     outline: var(--hx-checkbox-focus-ring-width, var(--hx-focus-ring-width, 2px)) solid
       var(--hx-checkbox-focus-ring-color, var(--hx-focus-ring-color, #0f7078));
@@ -224,6 +241,7 @@
       border: 2px solid ButtonText;
     }
 
+    :host(:focus-visible) .checkbox__box,
     .checkbox__input:focus-visible ~ .checkbox__box {
       outline: 3px solid Highlight;
       outline-offset: 2px;

package/dist/css/hx-color-picker.css

@@ -9,6 +9,31 @@
     pointer-events: none;
     opacity: var(--hx-opacity-disabled, 0.5);
   }
+  /* Slotted label / help / error blocks for cross-shadow naming. */
+  .hx-color-picker__label {
+    display: block;
+    margin-bottom: var(--hx-space-1, 0.25rem);
+    font-weight: var(--hx-font-weight-semibold, 600);
+    color: var(--hx-color-neutral-900, #1a1a1a);
+  }
+  .hx-color-picker__label:empty {
+    display: none;
+  }
+  .hx-color-picker__help {
+    display: block;
+    margin-top: var(--hx-space-1, 0.25rem);
+    font-size: var(--hx-font-size-xs, 0.75rem);
+    color: var(--hx-color-neutral-600, #525252);
+  }
+  .hx-color-picker__error {
+    display: block;
+    margin-top: var(--hx-space-1, 0.25rem);
+    font-size: var(--hx-font-size-xs, 0.75rem);
+    color: var(--hx-color-danger-700, #c43e3e);
+  }
+  [hidden] {
+    display: none !important;
+  }
   .trigger {
     display: inline-flex;
     align-items: center;

package/dist/css/hx-date-picker.css

@@ -335,7 +335,8 @@
      Live region (screen reader announcements)
      ============================================================ */
 
-  .calendar__live-region {
+  .calendar__live-region,
+  .field__sr-only {
     position: absolute;
     width: 1px;
     height: 1px;

package/dist/css/hx-drawer.css

@@ -239,6 +239,23 @@
     margin: 0;
   }
 
+  /* ─── Synthesized consumer-description span ─── */
+  /* Visually hidden mirror of consumer-resolved aria-describedby text used by */
+  /* the host-canonical ARIA pipeline. Always present in the shadow tree so AT */
+  /* can resolve the same-root id even when the description is currently empty. */
+
+  .drawer-sr-only {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+  }
+
   /* ─── Body ─── */
 
   .drawer-body {

package/dist/css/hx-icon-button.css

@@ -151,12 +151,37 @@
        multiplicative stacking (0.5 * 0.5 = 0.25). Do not add opacity here. */
   }
 
+  /* ─── Loading State ─── */
+
+  .button--loading {
+    position: relative;
+    cursor: wait;
+  }
+
+  .button__spinner {
+    width: 1em;
+    height: 1em;
+    flex-shrink: 0;
+    animation: hx-icon-button-spin var(--hx-duration-spinner, 750ms) linear infinite;
+  }
+
+  @keyframes hx-icon-button-spin {
+    to {
+      transform: rotate(360deg);
+    }
+  }
+
   /* ─── Reduced Motion ─── */
 
   @media (prefers-reduced-motion: reduce) {
     .button {
       transition: none;
     }
+
+    .button__spinner {
+      animation: none;
+      opacity: var(--hx-opacity-muted, 0.6);
+    }
   }
 
   /* ─── High Contrast Mode (forced-colors) ─── */
@@ -184,4 +209,9 @@
     :host([disabled]) {
       opacity: 1;
     }
+
+    .button--loading .button__spinner {
+      stroke: ButtonText;
+      forced-color-adjust: none;
+    }
   }

package/dist/css/hx-meter.css

@@ -116,6 +116,11 @@
   /* ─── Forced Colors (Windows High Contrast) ─── */
 
   @media (forced-colors: active) {
+    .meter:focus-visible {
+      outline: 2px solid Highlight;
+      outline-offset: var(--hx-focus-ring-offset, 2px);
+    }
+
     .meter__track {
       border: 1px solid CanvasText;
     }

package/dist/css/hx-select.css

@@ -2,6 +2,11 @@
 /* ─── 3-tier token cascade: component → semantic → hardcoded fallback ─── */
   :host {
     display: block;
+    /* Round-3 finding 1: host is the canonical combobox surface, so it owns
+       keyboard focus. Suppress the UA default outline; the custom focus ring
+       is painted on the inner trigger via :host(:focus-visible)
+       .field__trigger so visual feedback follows the host's focus state. */
+    outline: none;
 
     /* Background & foreground */
     --_bg: var(--hx-select-bg, var(--hx-color-surface-default, #ffffff));
@@ -78,6 +83,12 @@
   }
 
   .field__trigger {
+    /* Round-3 finding 1 / CodeRabbit F1: trigger is a <button type="button">
+       (labelable) so native <label for> click activation works for mouse
+       users. Reset native button chrome before applying field styles. */
+    appearance: none;
+    -webkit-appearance: none;
+    margin: 0;
     display: flex;
     align-items: center;
     justify-content: space-between;
@@ -88,6 +99,7 @@
     border-radius: var(--_border-radius);
     background-color: var(--_bg);
     color: var(--_color);
+    font: inherit;
     font-family: inherit;
     font-size: var(--hx-font-size-md, 1rem);
     line-height: var(--hx-line-height-normal, 1.5);
@@ -100,6 +112,11 @@
     outline: none;
   }
 
+  /* Round-3 finding 1: host is the canonical focusable surface. Both the
+     :host(:focus-visible) descendant selector AND the legacy
+     .field__trigger:focus-visible (kept for forced-colors regression test
+     parity) paint the focus ring on the visual trigger. */
+  :host(:focus-visible) .field__trigger,
   .field__trigger:focus-visible {
     border-color: var(--_focus-ring-color);
     box-shadow: 0 0 0 var(--hx-focus-ring-width, 2px)
@@ -168,6 +185,7 @@
     border-color: var(--_error-color);
   }
 
+  :host(:focus-visible) .field--error .field__trigger,
   .field--error .field__trigger:focus-visible {
     border-color: var(--_error-color);
     box-shadow: 0 0 0 var(--hx-focus-ring-width, 2px)
@@ -301,6 +319,7 @@
       border: 2px solid ButtonText;
     }
 
+    :host(:focus-visible) .field__trigger,
     .field__trigger:focus-visible {
       outline: 3px solid Highlight;
       outline-offset: 2px;

package/dist/css/hx-switch.css

@@ -49,6 +49,22 @@
     appearance: none;
   }
 
+  /*
+   * Host-focus path: on the modern (IDL element-references) render branch the
+   * host is the tabbable surface (tabindex=0) and the inner track button is
+   * demoted to tabindex=-1. Drive the focus ring from ':host(:focus-visible)'
+   * so keyboard users still see a visible affordance. Codex round-11 P1.
+   */
+  :host(:focus-visible) .switch__track {
+    outline: var(--hx-focus-ring-width, 2px) solid
+      var(--hx-switch-focus-ring-color, var(--hx-focus-ring-color, #0f7078));
+    outline-offset: var(--hx-focus-ring-offset, 2px);
+  }
+
+  /*
+   * Fallback (no-IDL-ref) path: the host carries tabindex=-1 and the inner
+   * track button is the tab target. Native :focus-visible drives the ring.
+   */
   .switch__track:focus-visible {
     outline: var(--hx-focus-ring-width, 2px) solid
       var(--hx-switch-focus-ring-color, var(--hx-focus-ring-color, #0f7078));
@@ -186,6 +202,7 @@
       border: 2px solid ButtonText;
     }
 
+    :host(:focus-visible) .switch__track,
     .switch__track:focus-visible {
       outline: 3px solid Highlight;
       outline-offset: 2px;

package/dist/css/hx-tag.css

@@ -150,9 +150,32 @@
   @media (forced-colors: active) {
     .tag {
       border-color: CanvasText;
+      forced-color-adjust: none;
+      background-color: Canvas;
+      color: CanvasText;
     }
 
     .tag__remove-button {
       color: ButtonText;
     }
+
+    /* Per-semantic-variant forced-colors fallbacks. The visually-hidden
+       semantic variant label (.tag__variant-label) keeps AT users
+       informed; these blocks restore visual semantic distinction for
+       sighted users in HCM where bg/color collapse to system defaults.
+       Pattern: distinct border-style per variant (matches hx-badge). */
+    .tag--success {
+      border-style: solid;
+      border-width: 2px;
+    }
+
+    .tag--warning {
+      border-style: dashed;
+      border-width: 2px;
+    }
+
+    .tag--danger {
+      border-style: double;
+      border-width: 3px;
+    }
   }

package/dist/css/hx-time-picker.css

@@ -188,6 +188,17 @@
   .field__error {
     color: var(--hx-time-picker-error-color, var(--hx-color-error-text, #c92a2a));
   }
+  .field__sr-only {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+  }
   @media (forced-colors: active) {
     .field__combobox {
       border-color: ButtonText;

package/dist/css/hx-toggle-button.css

@@ -34,6 +34,22 @@
     -webkit-user-select: none;
   }
 
+  /*
+   * Host-focus path: on the modern (IDL element-references) render branch the
+   * host is the tabbable surface (tabindex=0) and the inner <button> is
+   * demoted to tabindex=-1. Drive the focus ring from ':host(:focus-visible)'
+   * so keyboard users still see a visible affordance. Codex round-11 P1.
+   */
+  :host(:focus-visible) .button {
+    outline: var(--hx-focus-ring-width, 2px) solid
+      var(--hx-toggle-button-focus-ring-color, var(--hx-focus-ring-color, #0f7078));
+    outline-offset: var(--hx-focus-ring-offset, 2px);
+  }
+
+  /*
+   * Fallback (no-IDL-ref) path: the host carries tabindex=-1 and the inner
+   * <button> is the tab target. Native :focus-visible drives the ring.
+   */
   .button:focus-visible {
     outline: var(--hx-focus-ring-width, 2px) solid
       var(--hx-toggle-button-focus-ring-color, var(--hx-focus-ring-color, #0f7078));
@@ -232,6 +248,7 @@
       border: 2px solid ButtonText;
     }
 
+    :host(:focus-visible) .button,
     .button:focus-visible {
       outline: 3px solid Highlight;
       outline-offset: 2px;

package/dist/css/index.css

@@ -1,4 +1,4 @@
-/* index.css — generated 2026-05-03T13:57:26.583Z */
+/* index.css — generated 2026-05-06T11:20:36.952Z */
 /* Imports all per-component CSS files for Drupal asset pipeline */
 
 @import './hx-accordion.css';

package/dist/css/manifest.json

@@ -1,5 +1,5 @@
 {
-  "generated": "2026-05-03T13:57:26.582Z",
+  "generated": "2026-05-06T11:20:36.951Z",
   "components": [
     {
       "name": "hx-accordion",
@@ -595,6 +595,7 @@
         "--hx-border-radius-md",
         "--hx-border-radius-sm",
         "--hx-border-width-thin",
+        "--hx-color-danger-700",
         "--hx-color-neutral-0",
         "--hx-color-neutral-100",
         "--hx-color-neutral-200",
@@ -1178,6 +1179,7 @@
         "--hx-color-text-on-error",
         "--hx-color-text-on-primary",
         "--hx-color-text-strong",
+        "--hx-duration-spinner",
         "--hx-filter-brightness-active",
         "--hx-focus-ring-color",
         "--hx-focus-ring-offset",
@@ -1192,6 +1194,7 @@
         "--hx-icon-button-focus-ring-color",
         "--hx-icon-button-size",
         "--hx-opacity-disabled",
+        "--hx-opacity-muted",
         "--hx-size-10",
         "--hx-size-12",
         "--hx-size-8",