@fusion.dev/helix-headless 0.0.0-dev → 0.0.3

package/dist/list/item/list-item.d.ts

@@ -6,13 +6,10 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
  * @description
  * Layout and semantics, and deliberately not a target.
  *
- * **`href` makes the row itself the link.** *Corrected 19 Aug 2026.* This said a
- * row could not become one, on the grounds that "a whole-row target needs the
- * anchor to wrap the layout, and the layout is what this component is." That is
- * true of the *consumer's* anchor, which cannot wrap slots it does not own, and
- * it is not true of the component's: an `<a part="row">` wraps this component's
- * own layout perfectly well. `Tree.Item` does exactly that, and the two were
- * refusing and accepting `href` on the same argument.
+ * **`href` makes the row itself the link.** A whole-row target needs the anchor
+ * to wrap the layout, which a *consumer's* anchor cannot do for slots it does not
+ * own. The component's can: an `<a part="row">` wraps this component's own layout
+ * perfectly well, which is what `Tree.Item` does.
  *
  * What the anchor buys is what the row could not fake: the whole row is a
  * target, Enter follows it, middle click opens a tab, the status bar shows the
@@ -49,15 +46,15 @@ export declare class HelixHeadlessListItem extends HelixElement {
      * to the current page on every row a consumer never asked to be one.
      */
     href: string;
-    /**
-     * Where the link opens, for the rare row that leaves the site.
-     */
-    target: string;
     /**
      * What the link declares about where it goes. The consumer's decision rather
      * than one derived from `target`, for the reason `Tree.Item` gives.
      */
     rel: string;
+    /**
+     * Where the link opens, for the rare row that leaves the site.
+     */
+    target: string;
     protected willUpdate(changed: PropertyValues): void;
     /**
      * The cell before the row's content, which this tier leaves empty.
@@ -69,13 +66,12 @@ export declare class HelixHeadlessListItem extends HelixElement {
      * sit in a track has to be a box in that track.
      *
      * **The box belongs to the styled tier, which is why this returns `nothing`.**
-     * It was rendered here, on the argument that the template lives here, and that
-     * put an unstyled empty box in front of every headless row. A row styled with
-     * `display: flex` and a `gap` draws that gap beside the empty child: measured
-     * on this tier's own example, which is exactly such a row, 1384 pixels moved
-     * and every label sat half a rem further in. It is the fault the styled row's
-     * own comment already records about a column gap beside a zero-width column,
-     * and the one the toast had before it.
+     * Rendering it here puts an unstyled empty box in front of every headless row,
+     * and a row styled with `display: flex` and a `gap` draws that gap beside the
+     * empty child: measured on this tier's own example, which is exactly such a
+     * row, 1384 pixels moved and every label sat half a rem further in. The styled
+     * row's own comment records the same fault about a column gap beside a
+     * zero-width column.
      *
      * A tier that ships no CSS cannot make a box it renders cost nothing, so it
      * does not render one. `marker="rail"` is a styled-tier attribute for the same

package/dist/list/item/list-item.js

@@ -13,13 +13,10 @@ import { property } from 'lit/decorators.js';
  * @description
  * Layout and semantics, and deliberately not a target.
  *
- * **`href` makes the row itself the link.** *Corrected 19 Aug 2026.* This said a
- * row could not become one, on the grounds that "a whole-row target needs the
- * anchor to wrap the layout, and the layout is what this component is." That is
- * true of the *consumer's* anchor, which cannot wrap slots it does not own, and
- * it is not true of the component's: an `<a part="row">` wraps this component's
- * own layout perfectly well. `Tree.Item` does exactly that, and the two were
- * refusing and accepting `href` on the same argument.
+ * **`href` makes the row itself the link.** A whole-row target needs the anchor
+ * to wrap the layout, which a *consumer's* anchor cannot do for slots it does not
+ * own. The component's can: an `<a part="row">` wraps this component's own layout
+ * perfectly well, which is what `Tree.Item` does.
  *
  * What the anchor buys is what the row could not fake: the whole row is a
  * target, Enter follows it, middle click opens a tab, the status bar shows the
@@ -58,15 +55,15 @@ let HelixHeadlessListItem = class HelixHeadlessListItem extends HelixElement {
          * to the current page on every row a consumer never asked to be one.
          */
         this.href = '';
-        /**
-         * Where the link opens, for the rare row that leaves the site.
-         */
-        this.target = '';
         /**
          * What the link declares about where it goes. The consumer's decision rather
          * than one derived from `target`, for the reason `Tree.Item` gives.
          */
         this.rel = '';
+        /**
+         * Where the link opens, for the rare row that leaves the site.
+         */
+        this.target = '';
     }
     willUpdate(changed) {
         super.willUpdate(changed);
@@ -82,13 +79,12 @@ let HelixHeadlessListItem = class HelixHeadlessListItem extends HelixElement {
      * sit in a track has to be a box in that track.
      *
      * **The box belongs to the styled tier, which is why this returns `nothing`.**
-     * It was rendered here, on the argument that the template lives here, and that
-     * put an unstyled empty box in front of every headless row. A row styled with
-     * `display: flex` and a `gap` draws that gap beside the empty child: measured
-     * on this tier's own example, which is exactly such a row, 1384 pixels moved
-     * and every label sat half a rem further in. It is the fault the styled row's
-     * own comment already records about a column gap beside a zero-width column,
-     * and the one the toast had before it.
+     * Rendering it here puts an unstyled empty box in front of every headless row,
+     * and a row styled with `display: flex` and a `gap` draws that gap beside the
+     * empty child: measured on this tier's own example, which is exactly such a
+     * row, 1384 pixels moved and every label sat half a rem further in. The styled
+     * row's own comment records the same fault about a column gap beside a
+     * zero-width column.
      *
      * A tier that ships no CSS cannot make a box it renders cost nothing, so it
      * does not render one. `marker="rail"` is a styled-tier attribute for the same
@@ -106,8 +102,8 @@ let HelixHeadlessListItem = class HelixHeadlessListItem extends HelixElement {
            rule. That rule is about optional *regions*, which generate an empty box
            when nothing fills them; this is a single always-present container whose
            job is to hold the layout somewhere other than the host.
-         *
-         * The host has to be free for `display: list-item`, which is how an ordered
+    
+           The host has to be free for `display: list-item`, which is how an ordered
            or unordered list gets its marker: native numbering, native counters,
            native RTL, and nothing written by script or counted on the server. But
            `list-item` cannot combine with `grid`, so a row whose host carried the
@@ -138,10 +134,10 @@ __decorate([
 ], HelixHeadlessListItem.prototype, "href", void 0);
 __decorate([
     property()
-], HelixHeadlessListItem.prototype, "target", void 0);
+], HelixHeadlessListItem.prototype, "rel", void 0);
 __decorate([
     property()
-], HelixHeadlessListItem.prototype, "rel", void 0);
+], HelixHeadlessListItem.prototype, "target", void 0);
 HelixHeadlessListItem = __decorate([
     customElement('helix-headless-list-item')
 ], HelixHeadlessListItem);

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

@@ -17,10 +17,6 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @slot - The rows.
  */
 export declare class HelixHeadlessList extends HelixElement {
-    /**
-     * Accessible name for the set.
-     */
-    label: string;
     /**
      * What kind of list this is, which is a fact about the content.
      *
@@ -44,6 +40,10 @@ export declare class HelixHeadlessList extends HelixElement {
      *   `List.Term` element would be a second row shape for one attribute's sake.
      */
     kind?: 'default' | 'description' | 'ordered' | 'unordered';
+    /**
+     * Accessible name for the set.
+     */
+    label: string;
     /**
      * Which markers an ordered list draws, in `<ol type>`'s own five values.
      *

package/dist/list/root/list-root.js

@@ -46,12 +46,12 @@ let HelixHeadlessList = class HelixHeadlessList extends HelixElement {
         return html `<slot></slot>`;
     }
 };
-__decorate([
-    property()
-], HelixHeadlessList.prototype, "label", void 0);
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessList.prototype, "kind", void 0);
+__decorate([
+    property()
+], HelixHeadlessList.prototype, "label", void 0);
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessList.prototype, "type", void 0);

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

@@ -25,25 +25,14 @@ declare const HelixHeadlessListbox_base: (new (...args: any[]) => import("@fusio
  * chooses, because a reader passing over four options on the way to the fifth
  * did not mean to pick all five.
  *
- * **This does not use `KeyboardNavigationController`, and the reason given here
- * was the wrong one.** It said the controller moves and chooses in one act by
- * design, so half of this component needed that and half the opposite. The
- * controller does not work that way: it takes `origin: 'focus' | 'selection'`,
- * and `focus` exists precisely so a reader can arrow without choosing, which is
- * what `Tabs` uses in `manual` mode. `focusItem()` and `select()` are separate
- * members of `NavigableItem`. The incompatibility named above is one the
- * controller had already solved.
- *
- * The real one is where focus lives. `NavigableItem.focusItem()` moves DOM
- * focus to the item, because the controller's model is a roving tab stop. A
- * filterable list cannot do that: focus has to stay in the field or typing
- * stops, so what moves is a virtual cursor and `aria-activedescendant` is what
- * says where it is. Those two disagree about the one thing neither can
- * abstract, and no flag reconciles them.
- *
- * Worth keeping the distinction sharp, because the old wording invites the
- * wrong fix: someone reading it would add `origin` to the controller, find it
- * already there, and conclude this component could adopt it.
+ * **This does not use `KeyboardNavigationController`, and the reason is where
+ * focus lives rather than whether moving chooses.** The controller already
+ * separates those, taking `origin: 'focus' | 'selection'`. What it cannot do is
+ * leave focus alone: `NavigableItem.focusItem()` moves DOM focus to the item,
+ * its model being a roving tab stop. A filterable list cannot have that, focus
+ * having to stay in the field or typing stops, so what moves is a virtual
+ * cursor and `aria-activedescendant` is what says where it is. No flag
+ * reconciles the two.
  *
  * **Filtering hides rather than removes.** An option the filter has hidden is
  * still the consumer's element in the consumer's order, so a filter that clears
@@ -96,8 +85,6 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
      * the list is still the consumer's own elements in their own order. Reading
      * gives what is being filtered on; writing declares it theirs, and
      * `default-filter` seeds one the list owns.
-     *
-     *
      */
     get filter(): string;
     set filter(next: string);
@@ -107,15 +94,22 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
     defaultFilter: string;
     /** What the list is narrowed to, whoever set it. */
     private filterState;
+    /**
+     * What is shown when a filter has hidden every option.
+     *
+     * From `MixinCollection`, which every collection in the library now shares,
+     * and re-declared here only to keep this list's own wording: "No matches" is
+     * about a filter, and the mixin's "Nothing to show" is about a list that was
+     * never given anything.
+     */
+    emptyText: string;
     /**
      * Whether the list renders a field for narrowing itself.
      *
      * The field lives here rather than in whatever frames the list, because the
      * filtering already does: `filter`, the empty state and the keyboard are all
-     * this component's. A select that drew its own search box above a listbox
-     * would be writing the same field again, and so would a combobox, and so
-     * would a command palette, which is the fault the three-family split exists
-     * to prevent.
+     * this component's. A select, a combobox and a command palette drawing their
+     * own search boxes would be three copies of one field.
      */
     filterable: boolean;
     /**
@@ -126,15 +120,6 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
      * Whether more than one option can be the answer.
      */
     multiple: boolean;
-    /**
-     * What is shown when a filter has hidden every option.
-     *
-     * From `MixinCollection`, which every collection in the library now shares,
-     * and re-declared here only to keep this list's own wording: "No matches" is
-     * about a filter, and the mixin's "Nothing to show" is about a list that was
-     * never given anything.
-     */
-    emptyText: string;
     /**
      * Which option the keyboard is on, which is not what is chosen.
      */
@@ -153,10 +138,9 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
      *
      * Counting during render reads the hiding from the *previous* pass, because
      * hiding happens in `updated` against options that are the consumer's
-     * elements rather than this component's markup. So a filter matching nothing
-     * rendered the full list, hid every option, and left an empty box with no
-     * message in it: the count was right one pass too late. Written to state
-     * instead, which schedules the one further render that shows it.
+     * elements rather than this component's markup, so a filter matching nothing
+     * leaves an empty box with no message in it. Written to state instead, which
+     * schedules the one further render that shows it.
      */
     private hasMatches;
     /**
@@ -202,17 +186,11 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
     /**
      * Walks the tree, and walks *through* a slot when it meets one.
      *
-     * Descendants rather than children, because a group puts a level between the
-     * list and its options and the keyboard has to move through a grouped list
-     * exactly as it moves through a flat one.
-     *
      * Through a slot because that is how this gets composed. `Select` renders a
      * listbox in its own shadow root with a slot inside it, so the options are
      * the *select's* light DOM and the listbox's only child is the slot: a plain
      * `querySelectorAll` finds the slot and no options at all, and the whole
-     * component comes up empty. Found the first time the two were put together,
-     * which is the argument for building the pieces separately rather than
-     * discovering it inside a finished Select.
+     * component comes up empty.
      */
     private collect;
     /** The groups, found the same way and for the same reason. */
@@ -242,9 +220,8 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
      *
      * A combobox keeps focus in its text field, because that is the whole of what
      * a combobox is, and still has to move this list with the arrows. Without
-     * this it would have to reimplement the moving, the wrapping, the skipping of
-     * disabled options and the seeding from the current value, and the second
-     * copy would drift from this one the first time either changed.
+     * this it would reimplement the moving, the wrapping, the skipping of
+     * disabled options and the seeding from the current value.
      *
      * Public and taking the event rather than a direction, so a caller forwards
      * what it received and this decides what the key means. `preventDefault` is
@@ -265,8 +242,8 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
      * A method rather than something this does on its own, because a listbox
      * opening on its answer usually wants it merely *visible* and the browser
      * already manages that: centering is what a caller wants when the list is being
-     * read as a dial rather than scanned as a list, which is what Time Picker's wheels
-     * does with three of these.
+     * read as a dial rather than scanned as a list, which is what Time Picker's
+     * wheels do with three of these.
      *
      * A delta from the two boxes rather than `offsetTop`. An option is a slotted
      * light DOM child, so its `offsetParent` is whatever is positioned above it,
@@ -290,12 +267,9 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
      * Seeding from the value means the first press moves from what the reader can
      * see is selected.
      *
-     * **The keyboard knew this and the announcement did not.** `linkActive` asked
-     * for `activeValue` alone, so a list that had been given a value and not yet
-     * arrowed through pointed `aria-activedescendant` at nothing: a screen reader
-     * was told the list and its selection, and nothing about where the cursor
-     * was, until a key moved it. Both read this now, so the thing announced and
-     * the thing the arrows move from cannot disagree.
+     * Read by `linkActive` as well as by the keys, so the option announced and
+     * the option the arrows move from cannot disagree: asking for `activeValue`
+     * alone points `aria-activedescendant` at nothing until a key has moved it.
      */
     private get currentValue();
     private linkActive;
@@ -305,8 +279,7 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
      *
      * `helix-filter` and not `helix-change`, because nothing about the value
      * changes: the options are hidden rather than removed, and telling a consumer
-     * their answer moved when it did not is worse than telling them nothing. It
-     * told them nothing before this.
+     * their answer moved when it did not is worse than telling them nothing.
      */
     private readonly handleFilter;
     /** Requests a narrowing, and reports whether the request stood. */