@fusion.dev/helix-headless 0.44.0 → 0.45.0

package/custom-elements.json

@@ -38128,7 +38128,7 @@
           "helix": {
             "category": "forms",
             "since": "0.23.0",
-            "status": "experimental",
+            "status": "stable",
             "documentation": "https://fusion.dev/helix/components/filter-input",
             "aliases": [
               "FilterToken",
@@ -38596,7 +38596,7 @@
           "helix": {
             "category": "forms",
             "since": "0.23.0",
-            "status": "experimental",
+            "status": "stable",
             "documentation": "https://fusion.dev/helix/components/filter-input",
             "aliases": [
               "Facet",
@@ -39325,7 +39325,7 @@
           "helix": {
             "category": "forms",
             "since": "0.25.0",
-            "status": "experimental",
+            "status": "stable",
             "documentation": "https://fusion.dev/helix/components/filter-input",
             "aliases": [
               "FacetPicker",
@@ -39789,7 +39789,7 @@
           "helix": {
             "category": "forms",
             "since": "0.23.0",
-            "status": "experimental",
+            "status": "stable",
             "documentation": "https://fusion.dev/helix/components/filter-input",
             "aliases": [
               "Comparator",
@@ -41812,7 +41812,7 @@
           "helix": {
             "category": "forms",
             "since": "0.1.0",
-            "status": "experimental",
+            "status": "stable",
             "documentation": "https://fusion.dev/helix/components/filter-input",
             "aliases": [
               "SearchField",
@@ -62513,6 +62513,17 @@
               "description": "The heading over the run.",
               "attribute": "label"
             },
+            {
+              "kind": "method",
+              "name": "nameFromHeading",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Names the run after the heading it drew, whatever the heading is made of.\n\n**The string alone was not the name of the heading, it was the name of one\nway of writing it.** `label` reached `ariaLabel` and the slot reached the\nscreen, so a consumer who took the documented `label` slot for a heading\nricher than a string got a `role=\"group\"` with no accessible name at all,\nand the words they wrote were the one thing a reader could not hear: the\nheading carries `aria-hidden`, because the name was supposed to be on the\nhost already. Set both and they disagreed, the host saying the string and\nthe panel showing the slot.\n\nSo the host points at the heading, which is the one thing that is always\nwhat a reader sees. `ElementInternals` and not an IDREF, because the host\nis in the light DOM and the heading is in this shadow root, which is the\nboundary `aria-labelledby` cannot cross. `MixinField.linkHost` does the\nsame for a field's label and records the measurement.\n\nClient only. Element references need the nodes to exist, and the server has\nthe string."
+            },
             {
               "kind": "field",
               "name": "tier",
@@ -62856,7 +62867,7 @@
           "summary": "A named run of options inside a listbox.",
           "helix": {
             "since": "0.1.0",
-            "status": "experimental",
+            "status": "stable",
             "documentation": "https://fusion.dev/helix/components/option",
             "aliases": [
               "OptGroup",
@@ -63532,7 +63543,7 @@
           "helix": {
             "category": "forms",
             "since": "0.1.0",
-            "status": "experimental",
+            "status": "stable",
             "documentation": "https://fusion.dev/helix/components/option",
             "aliases": [
               "Item",
@@ -71390,7 +71401,7 @@
           "summary": "A set of choices where exactly one is the answer.",
           "helix": {
             "since": "0.1.0",
-            "status": "experimental",
+            "status": "stable",
             "documentation": "https://fusion.dev/helix/components/radio",
             "aliases": [
               "RadioButtons",
@@ -71504,6 +71515,15 @@
               },
               "description": "Whether the markup declared this one chosen, which is what a reset returns to.\n\n`<option selected>` reflects to `defaultSelected` and `option.selected` is\nlive state that does not reflect, and those are two different facts. This\nelement has one `selected` doing both jobs, so the declaration is the\nattribute and the state is the property.\n\n**The attribute, read when it is asked for, and never a snapshot taken in\nthe constructor.** A field initializer runs there, and an element the HTML\nparser created has none of its attributes yet at that moment: measured on\nthis element, on `Option` and on `Toggle`, `<helix-radio value=\"a\"\nselected>` reported `defaultSelected` as `false` both from parsed markup\nand from `createElement` followed by `setAttribute`, which is every way a\nconsumer writes one. The snapshot could only ever be true for an element\nalready in the document when `customElements.define` ran.\n\nNothing overwrites it either, which is what makes reading it late correct\nrather than merely later: `selected` does not reflect, for the reason\n`willUpdate` records, so the group's writes never reach the attribute and\nwhat it says is what the markup said.\n\n**The deeper half is not this.** State reflecting under the declaration's\nname is the fault `TreeItem` avoids by mirroring to `data-selected`.\nSplitting them means moving what every stylesheet selects on, which is a\nchange of its own rather than a property being added."
             },
+            {
+              "kind": "field",
+              "name": "focusable",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether this choice holds the group's tab stop while nothing is chosen.\n\nThe stop rides on the selection, and an unanswered group has no selection,\nso without this every choice is `tabindex=\"-1\"` and the keyboard cannot\nenter the set at all.\n\n**Written by the group, with no attribute, and it reaches the control\nrather than the host.** A `tabindex` on the host is two faults at once: it\nis markup a consumer rendered and their server never sent, which React\nreports as a mismatch and does not patch up, and it puts the tab stop on\nthe element rather than on the `<button role=\"radio\">` inside it, so a\nscreen reader meets an unnamed box where a native group would have given\nthem an unchecked radio. `Toggle.Root` carries the same property for the\nsame reason."
+            },
             {
               "kind": "field",
               "name": "selected",
@@ -71936,7 +71956,7 @@
           "helix": {
             "category": "forms",
             "since": "0.1.0",
-            "status": "experimental",
+            "status": "stable",
             "documentation": "https://fusion.dev/helix/components/radio",
             "aliases": [
               "Option",
@@ -77274,7 +77294,7 @@
           "helix": {
             "category": "navigation",
             "since": "0.1.0",
-            "status": "experimental",
+            "status": "stable",
             "documentation": "https://fusion.dev/helix/components/skip-link",
             "aliases": [
               "Skip navigation",

package/dist/filter-input/chip/filter-chip.d.ts

@@ -37,7 +37,7 @@ declare const HelixHeadlessFilterChip_base: (new (...args: any[]) => import("@fu
  * gives: what the words mean is the domain's.
  *
  * @since 0.23.0
- * @status experimental
+ * @status stable
  * @category forms
  * @aliases FilterToken, FacetChip
  * @documentation https://fusion.dev/helix/components/filter-input

package/dist/filter-input/field/filter-field.d.ts

@@ -43,7 +43,7 @@ import type { HelixHeadlessFilterOperator } from '../operator/filter-operator.js
  * what fills a chip then is whatever the consumer types.
  *
  * @since 0.23.0
- * @status experimental
+ * @status stable
  * @category forms
  * @aliases Facet, Dimension
  * @documentation https://fusion.dev/helix/components/filter-input

package/dist/filter-input/menu/filter-menu.d.ts

@@ -50,7 +50,7 @@ import '../../menu/index.js';
  * rather than inventing one. Refusing `helix-facet` refuses the change.
  *
  * @since 0.25.0
- * @status experimental
+ * @status stable
  * @category forms
  * @aliases FacetPicker, FilterBuilder
  * @documentation https://fusion.dev/helix/components/filter-input

package/dist/filter-input/operator/filter-operator.d.ts

@@ -23,7 +23,7 @@ import { nothing, type PropertyValues } from 'lit';
  * consumer bug and the field reports it rather than guessing.
  *
  * @since 0.23.0
- * @status experimental
+ * @status stable
  * @category forms
  * @aliases Comparator, Predicate
  * @documentation https://fusion.dev/helix/components/filter-input

package/dist/filter-input/root/filter-input-root.d.ts

@@ -83,7 +83,7 @@ declare const HelixHeadlessFilterInput_base: (new (...args: any[]) => import("@f
  * and the chip goes because the filter went.
  *
  * @since 0.1.0
- * @status experimental
+ * @status stable
  * @category forms
  * @aliases SearchField, FacetInput, TokenInput
  * @documentation https://fusion.dev/helix/components/filter-input

package/dist/option/group/option-group.d.ts

@@ -13,7 +13,7 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * an option is in without the heading becoming something to land on.
  *
  * @since 0.1.0
- * @status experimental
+ * @status stable
  * @aliases OptGroup, Section
  * @documentation https://fusion.dev/helix/components/option
  *
@@ -29,6 +29,29 @@ export declare class HelixHeadlessOptionGroup extends HelixElement {
      */
     label: string;
     protected willUpdate(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    /**
+     * Names the run after the heading it drew, whatever the heading is made of.
+     *
+     * **The string alone was not the name of the heading, it was the name of one
+     * way of writing it.** `label` reached `ariaLabel` and the slot reached the
+     * screen, so a consumer who took the documented `label` slot for a heading
+     * richer than a string got a `role="group"` with no accessible name at all,
+     * and the words they wrote were the one thing a reader could not hear: the
+     * heading carries `aria-hidden`, because the name was supposed to be on the
+     * host already. Set both and they disagreed, the host saying the string and
+     * the panel showing the slot.
+     *
+     * So the host points at the heading, which is the one thing that is always
+     * what a reader sees. `ElementInternals` and not an IDREF, because the host
+     * is in the light DOM and the heading is in this shadow root, which is the
+     * boundary `aria-labelledby` cannot cross. `MixinField.linkHost` does the
+     * same for a field's label and records the measurement.
+     *
+     * Client only. Element references need the nodes to exist, and the server has
+     * the string.
+     */
+    private nameFromHeading;
     protected render(): TemplateResult;
 }
 declare global {

package/dist/option/group/option-group.js

@@ -16,6 +16,14 @@ let HelixHeadlessOptionGroup = class HelixHeadlessOptionGroup extends HelixEleme
         super.willUpdate(changed);
         hostAria(this.internals, { label: this.label, role: 'group' });
     }
+    updated(changed) {
+        super.updated(changed);
+        this.nameFromHeading();
+    }
+    nameFromHeading() {
+        const heading = this.partNamed('label');
+        hostAria(this.internals, { labelledBy: heading ? [heading] : [] });
+    }
     render() {
         return html `<span part="label" aria-hidden="true">
         <slot name="label">${this.label}</slot>

package/dist/option/root/option-root.d.ts

@@ -41,7 +41,7 @@ export declare const optionsAmong: (elements: readonly Element[]) => HelixHeadle
  * question and differs between a select and a command palette.
  *
  * @since 0.1.0
- * @status experimental
+ * @status stable
  * @category forms
  * @aliases Item, Choice
  * @documentation https://fusion.dev/helix/components/option

package/dist/radio/group/radio-group.d.ts

@@ -26,7 +26,7 @@ declare const HelixHeadlessRadioGroup_base: (new (...args: any[]) => import("@fu
  * anything is chosen.
  *
  * @since 0.1.0
- * @status experimental
+ * @status stable
  * @aliases RadioButtons, Choice group
  * @documentation https://fusion.dev/helix/components/radio
  *

package/dist/radio/group/radio-group.js

@@ -29,17 +29,13 @@ let HelixHeadlessRadioGroup = class HelixHeadlessRadioGroup extends MixinControl
     }
     place() {
         const items = this.items;
+        const answer = items.find((item) => item.value === this.value);
         for (const item of items) {
-            item.selected = item.value === this.value;
+            item.selected = item === answer;
         }
-        const entered = this.value === '' && items.length > 0 ? items[0] : undefined;
+        const entry = answer ? undefined : items.find((item) => !item.disabled);
         for (const item of items) {
-            if (item === entered) {
-                item.setAttribute('tabindex', '0');
-            }
-            else {
-                item.removeAttribute('tabindex');
-            }
+            item.focusable = item === entry;
         }
     }
     sync() {

package/dist/radio/root/radio-root.d.ts

@@ -20,7 +20,7 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * be a second source of truth for which one is on.
  *
  * @since 0.1.0
- * @status experimental
+ * @status stable
  * @category forms
  * @aliases Option, Choice
  * @documentation https://fusion.dev/helix/components/radio
@@ -75,6 +75,23 @@ export declare class HelixHeadlessRadio extends HelixElement {
      */
     get defaultSelected(): boolean;
     set defaultSelected(next: boolean);
+    /**
+     * Whether this choice holds the group's tab stop while nothing is chosen.
+     *
+     * The stop rides on the selection, and an unanswered group has no selection,
+     * so without this every choice is `tabindex="-1"` and the keyboard cannot
+     * enter the set at all.
+     *
+     * **Written by the group, with no attribute, and it reaches the control
+     * rather than the host.** A `tabindex` on the host is two faults at once: it
+     * is markup a consumer rendered and their server never sent, which React
+     * reports as a mismatch and does not patch up, and it puts the tab stop on
+     * the element rather than on the `<button role="radio">` inside it, so a
+     * screen reader meets an unnamed box where a native group would have given
+     * them an unchecked radio. `Toggle.Root` carries the same property for the
+     * same reason.
+     */
+    focusable: boolean;
     /**
      * Whether this is the current choice.
      *

package/dist/radio/root/radio-root.js

@@ -11,6 +11,7 @@ let HelixHeadlessRadio = class HelixHeadlessRadio extends HelixElement {
     constructor() {
         super(...arguments);
         this.disabled = false;
+        this.focusable = false;
         this.selected = false;
         this.value = '';
     }
@@ -40,7 +41,7 @@ let HelixHeadlessRadio = class HelixHeadlessRadio extends HelixElement {
       role="radio"
       aria-checked=${this.selected ? 'true' : 'false'}
       ?disabled=${this.disabled}
-      tabindex=${this.selected ? '0' : '-1'}
+      tabindex=${this.selected || this.focusable ? '0' : '-1'}
       @click=${() => this.select()}
     >
       <span part="box"><span part="mark" aria-hidden="true"></span></span>
@@ -52,6 +53,9 @@ let HelixHeadlessRadio = class HelixHeadlessRadio extends HelixElement {
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessRadio.prototype, "disabled", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessRadio.prototype, "focusable", void 0);
 __decorate([
     property({ type: Boolean })
 ], HelixHeadlessRadio.prototype, "selected", void 0);

package/dist/skip-link/root/skip-link-root.d.ts

@@ -32,7 +32,7 @@ import { type TemplateResult } from 'lit';
  * broken.
  *
  * @since 0.1.0
- * @status experimental
+ * @status stable
  * @category navigation
  * @aliases Skip navigation, Skip to content
  * @documentation https://fusion.dev/helix/components/skip-link

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-headless",
   "description": "Headless component tier. Structure, accessibility, state, and form participation. No styling.",
-  "version": "0.44.0",
+  "version": "0.45.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -46,14 +46,14 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-core": "0.44.0",
-    "@fusion.dev/helix-icons": "0.44.0",
+    "@fusion.dev/helix-core": "0.45.0",
+    "@fusion.dev/helix-icons": "0.45.0",
     "uqr": "^0.1.3"
   },
   "devDependencies": {
     "@custom-elements-manifest/analyzer": "^0.11.0",
-    "@fusion.dev/helix-cem": "0.44.0",
-    "@fusion.dev/helix-testing": "0.44.0",
+    "@fusion.dev/helix-cem": "0.45.0",
+    "@fusion.dev/helix-testing": "0.45.0",
     "@fusion.dev/scripts": "0.0.0-dev",
     "@happy-dom/global-registrator": "^20.0.0",
     "@lit-labs/ssr": "^4.1.0",

package/types/jsx.d.ts

@@ -11715,6 +11715,21 @@ name is the fault `TreeItem` avoids by mirroring to `data-selected`.
 Splitting them means moving what every stylesheet selects on, which is a
 change of its own rather than a property being added. */
   defaultSelected?: (HelixHeadlessRadio["defaultSelected"]) | undefined;
+  /** Whether this choice holds the group's tab stop while nothing is chosen.
+
+The stop rides on the selection, and an unanswered group has no selection,
+so without this every choice is `tabindex="-1"` and the keyboard cannot
+enter the set at all.
+
+**Written by the group, with no attribute, and it reaches the control
+rather than the host.** A `tabindex` on the host is two faults at once: it
+is markup a consumer rendered and their server never sent, which React
+reports as a mismatch and does not patch up, and it puts the tab stop on
+the element rather than on the `<button role="radio">` inside it, so a
+screen reader meets an unnamed box where a native group would have given
+them an unchecked radio. `Toggle.Root` carries the same property for the
+same reason. */
+  focusable?: (HelixHeadlessRadio["focusable"]) | undefined;
 
   /** Fired when this choice is made. Cancelable: refusing it takes the decision and nothing moves. */
   "onhelix-select"?: ((e: HelixHeadlessRadioHelixSelectElementEvent) => void) | undefined;
@@ -11755,6 +11770,21 @@ name is the fault `TreeItem` avoids by mirroring to `data-selected`.
 Splitting them means moving what every stylesheet selects on, which is a
 change of its own rather than a property being added. */
   "prop:defaultSelected"?: (HelixHeadlessRadio["defaultSelected"]) | undefined;
+  /** Whether this choice holds the group's tab stop while nothing is chosen.
+
+The stop rides on the selection, and an unanswered group has no selection,
+so without this every choice is `tabindex="-1"` and the keyboard cannot
+enter the set at all.
+
+**Written by the group, with no attribute, and it reaches the control
+rather than the host.** A `tabindex` on the host is two faults at once: it
+is markup a consumer rendered and their server never sent, which React
+reports as a mismatch and does not patch up, and it puts the tab stop on
+the element rather than on the `<button role="radio">` inside it, so a
+screen reader meets an unnamed box where a native group would have given
+them an unchecked radio. `Toggle.Root` carries the same property for the
+same reason. */
+  "prop:focusable"?: (HelixHeadlessRadio["focusable"]) | undefined;
   /** Fired when this choice is made. Cancelable: refusing it takes the decision and nothing moves. */
   "on:helix-select"?: ((e: HelixHeadlessRadioHelixSelectElementEvent) => void) | undefined;
 
@@ -29054,6 +29084,20 @@ export type CustomElements = {
    * name is the fault `TreeItem` avoids by mirroring to `data-selected`.
    * Splitting them means moving what every stylesheet selects on, which is a
    * change of its own rather than a property being added. (property only)
+   * - `focusable`: Whether this choice holds the group's tab stop while nothing is chosen.
+   *
+   * The stop rides on the selection, and an unanswered group has no selection,
+   * so without this every choice is `tabindex="-1"` and the keyboard cannot
+   * enter the set at all.
+   *
+   * **Written by the group, with no attribute, and it reaches the control
+   * rather than the host.** A `tabindex` on the host is two faults at once: it
+   * is markup a consumer rendered and their server never sent, which React
+   * reports as a mismatch and does not patch up, and it puts the tab stop on
+   * the element rather than on the `<button role="radio">` inside it, so a
+   * screen reader meets an unnamed box where a native group would have given
+   * them an unchecked radio. `Toggle.Root` carries the same property for the
+   * same reason. (property only)
    * - `whenSettled`: Resolves a frame after the first update, when transitions are switched on.
    *
    * **Named `whenSettled` because `settled` is taken four times over**, by
@@ -46914,6 +46958,20 @@ export type CustomElementsSolidJs = {
    * name is the fault `TreeItem` avoids by mirroring to `data-selected`.
    * Splitting them means moving what every stylesheet selects on, which is a
    * change of its own rather than a property being added. (property only)
+   * - `focusable`: Whether this choice holds the group's tab stop while nothing is chosen.
+   *
+   * The stop rides on the selection, and an unanswered group has no selection,
+   * so without this every choice is `tabindex="-1"` and the keyboard cannot
+   * enter the set at all.
+   *
+   * **Written by the group, with no attribute, and it reaches the control
+   * rather than the host.** A `tabindex` on the host is two faults at once: it
+   * is markup a consumer rendered and their server never sent, which React
+   * reports as a mismatch and does not patch up, and it puts the tab stop on
+   * the element rather than on the `<button role="radio">` inside it, so a
+   * screen reader meets an unnamed box where a native group would have given
+   * them an unchecked radio. `Toggle.Root` carries the same property for the
+   * same reason. (property only)
    * - `whenSettled`: Resolves a frame after the first update, when transitions are switched on.
    *
    * **Named `whenSettled` because `settled` is taken four times over**, by

package/types/vue.d.ts

@@ -6021,6 +6021,21 @@ name is the fault `TreeItem` avoids by mirroring to `data-selected`.
 Splitting them means moving what every stylesheet selects on, which is a
 change of its own rather than a property being added. */
   defaultSelected?: (HelixHeadlessRadio["defaultSelected"]) | undefined;
+  /** Whether this choice holds the group's tab stop while nothing is chosen.
+
+The stop rides on the selection, and an unanswered group has no selection,
+so without this every choice is `tabindex="-1"` and the keyboard cannot
+enter the set at all.
+
+**Written by the group, with no attribute, and it reaches the control
+rather than the host.** A `tabindex` on the host is two faults at once: it
+is markup a consumer rendered and their server never sent, which React
+reports as a mismatch and does not patch up, and it puts the tab stop on
+the element rather than on the `<button role="radio">` inside it, so a
+screen reader meets an unnamed box where a native group would have given
+them an unchecked radio. `Toggle.Root` carries the same property for the
+same reason. */
+  focusable?: (HelixHeadlessRadio["focusable"]) | undefined;
 };
 
 export type HelixHeadlessRadioVueEvents = {