@fusion.dev/helix-headless 0.0.0-dev

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

@@ -0,0 +1,95 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { nothing, type PropertyValues, type TemplateResult } from 'lit';
+/**
+ * @summary One row of a list.
+ *
+ * @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.
+ *
+ * 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
+ * destination, and it all works before any JavaScript runs.
+ *
+ * What it costs is client-side routing, and that is the consumer's to restore.
+ * A router renders its own anchor and cannot render one inside this shadow
+ * root, so a framework wanting a soft navigation intercepts the click on the
+ * way out: the anchor is in `composedPath()`, and taking only a plain primary
+ * press leaves every native gesture alone.
+ *
+ * **`data-list-item` is still the answer for a row that is not a destination.**
+ * A list row is often a container of controls rather than a place to go, and a
+ * row with `href` unset behaves exactly as it always did.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @aliases Row, Entry
+ * @documentation https://helix.fusion.dev/components/list
+ *
+ * @slot - The label.
+ * @slot end - Trailing content.
+ * @slot start - Leading content, usually an icon or an avatar.
+ * @slot supporting - Secondary text under the label.
+ *
+ * @csspart row - The layout, held off the host so the host can carry a marker.
+ */
+export declare class HelixHeadlessListItem extends HelixElement {
+    /**
+     * Where the row goes, and nothing when it goes nowhere.
+     *
+     * Empty rather than optional, and unset by default: a list is not always a
+     * list of links, and an empty `href` written onto every row would be a link
+     * 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;
+    protected willUpdate(changed: PropertyValues): void;
+    /**
+     * The cell before the row's content, which this tier leaves empty.
+     *
+     * A railed list puts its number at the block's own start edge, in a track of
+     * its own ahead of the words, and the native `::marker` cannot reach there:
+     * `outside` hangs the marker just clear of the row's content box, which is
+     * beside the words rather than at the edge of the block. A number that has to
+     * 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.
+     *
+     * 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
+     * reason: *that* a list is numbered is a fact about the content and *where the
+     * numbers are drawn* is not. A headless consumer wanting a rail writes the
+     * cell they were going to style anyway.
+     *
+     * `protected` rather than `private`, so the tier above can reach it.
+     */
+    protected renderRail(): TemplateResult | typeof nothing;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-list-item': HelixHeadlessListItem;
+    }
+}

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

@@ -0,0 +1,148 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { customElement, HelixElement, hostAria } from '@fusion.dev/helix-core';
+import { html, nothing } from 'lit';
+import { property } from 'lit/decorators.js';
+/**
+ * @summary One row of a list.
+ *
+ * @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.
+ *
+ * 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
+ * destination, and it all works before any JavaScript runs.
+ *
+ * What it costs is client-side routing, and that is the consumer's to restore.
+ * A router renders its own anchor and cannot render one inside this shadow
+ * root, so a framework wanting a soft navigation intercepts the click on the
+ * way out: the anchor is in `composedPath()`, and taking only a plain primary
+ * press leaves every native gesture alone.
+ *
+ * **`data-list-item` is still the answer for a row that is not a destination.**
+ * A list row is often a container of controls rather than a place to go, and a
+ * row with `href` unset behaves exactly as it always did.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @aliases Row, Entry
+ * @documentation https://helix.fusion.dev/components/list
+ *
+ * @slot - The label.
+ * @slot end - Trailing content.
+ * @slot start - Leading content, usually an icon or an avatar.
+ * @slot supporting - Secondary text under the label.
+ *
+ * @csspart row - The layout, held off the host so the host can carry a marker.
+ */
+let HelixHeadlessListItem = class HelixHeadlessListItem extends HelixElement {
+    constructor() {
+        super(...arguments);
+        /**
+         * Where the row goes, and nothing when it goes nowhere.
+         *
+         * Empty rather than optional, and unset by default: a list is not always a
+         * list of links, and an empty `href` written onto every row would be a link
+         * 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 = '';
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        hostAria(this.internals, { role: 'listitem' });
+    }
+    /**
+     * The cell before the row's content, which this tier leaves empty.
+     *
+     * A railed list puts its number at the block's own start edge, in a track of
+     * its own ahead of the words, and the native `::marker` cannot reach there:
+     * `outside` hangs the marker just clear of the row's content box, which is
+     * beside the words rather than at the edge of the block. A number that has to
+     * 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.
+     *
+     * 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
+     * reason: *that* a list is numbered is a fact about the content and *where the
+     * numbers are drawn* is not. A headless consumer wanting a rail writes the
+     * cell they were going to style anyway.
+     *
+     * `protected` rather than `private`, so the tier above can reach it.
+     */
+    renderRail() {
+        return nothing;
+    }
+    render() {
+        /* One wrapper, and it earns its place rather than breaking the bare-slot
+           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
+           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
+           grid lost it the moment the list asked for a marker. Measured before this
+           wrapper: a row with a leading icon put the icon 32px in instead of 16 and
+           its supporting text beside the label instead of under it. */
+        const content = html `${this.renderRail()}<slot name="start"></slot>
+      <slot></slot>
+      <slot name="supporting"></slot>
+      <slot name="end"></slot>`;
+        /* An anchor where there is somewhere to go, and the same box either way.
+           The host keeps `role="listitem"`, so the row inside it is the link and
+           not the item: an `<a>` carrying `listitem` would be a link that claims to
+           be a list entry, and the list would have one fewer entry than it has. */
+        return this.href === ''
+            ? html `<div part="row">${content}</div>`
+            : html `<a
+          part="row"
+          href=${this.href}
+          target=${this.target || nothing}
+          rel=${this.rel || nothing}
+          >${content}</a
+        >`;
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessListItem.prototype, "href", void 0);
+__decorate([
+    property()
+], HelixHeadlessListItem.prototype, "target", void 0);
+__decorate([
+    property()
+], HelixHeadlessListItem.prototype, "rel", void 0);
+HelixHeadlessListItem = __decorate([
+    customElement('helix-headless-list-item')
+], HelixHeadlessListItem);
+export { HelixHeadlessListItem };

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

@@ -0,0 +1,72 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+/**
+ * @summary A set of rows, read as a set.
+ *
+ * @description
+ * `role="list"` on the host, so the rows are counted and announced as "1 of 7"
+ * rather than as seven unrelated passages. That count is the whole reason to
+ * use a list rather than a stack of divs.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category data
+ * @aliases Rows, Stack, Menu
+ * @documentation https://helix.fusion.dev/components/list
+ *
+ * @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.
+     *
+     * On the headless tier because it is meaning rather than decoration, the same
+     * argument `severity` makes on `Callout`. A numbered list is numbered because
+     * the order carries information; a bulleted one is bulleted because the items
+     * are a set and the order does not. That distinction is the reader's, and it
+     * has to survive with the stylesheet turned off.
+     *
+     * - `default` is a run of rows and takes no marker. It is what a list of
+     *   settings or files is: neither ordered nor a set to be counted.
+     * - `ordered` numbers them, for steps.
+     * - `unordered` bullets them, for a set.
+     * - `description` pairs each row's label with its supporting text as a term
+     *   and what the term means.
+     *
+     * **`description` reuses the row's existing slots rather than inventing a
+     *   second kind of row.** A term and its description is exactly the label and
+     *   the supporting text `List.Item` already has, so the kind changes how the
+     *   pair is drawn and nothing about what a consumer writes. A separate
+     *   `List.Term` element would be a second row shape for one attribute's sake.
+     */
+    kind?: 'default' | 'description' | 'ordered' | 'unordered';
+    /**
+     * Which markers an ordered list draws, in `<ol type>`'s own five values.
+     *
+     * Reflected, because this is one of the things a stylesheet selects on and
+     * the styled tier maps each to a `list-style-type`. The platform's spellings
+     * rather than the CSS ones, so `<helix-list kind="ordered" type="i">` is what
+     * a consumer would have written on an `<ol>`.
+     *
+     * **`start` and `reversed` are both absent and neither can be done here.**
+     * This renders no `<ol>`: the rows are slotted and numbered by the CSS
+     * `list-item` counter, and that counter is not author-resettable. Measured in
+     * Chrome 148, `counter-reset: list-item 4` moves nothing on a `<div>`, on a
+     * `<ul>`, or even on a real `<ol>`, while `<ol start="5">` does and a *named*
+     * counter with explicit `::before` content does. So the markers would have to
+     * be rebuilt out of generated content to gain a start, which is a different
+     * component. `type` is only `list-style-type` and works.
+     */
+    type?: '1' | 'a' | 'A' | 'i' | 'I';
+    protected willUpdate(changed: PropertyValues): void;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-list': HelixHeadlessList;
+    }
+}

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

@@ -0,0 +1,61 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { customElement, HelixElement, hostAria } from '@fusion.dev/helix-core';
+import { html } from 'lit';
+import { property } from 'lit/decorators.js';
+/**
+ * @summary A set of rows, read as a set.
+ *
+ * @description
+ * `role="list"` on the host, so the rows are counted and announced as "1 of 7"
+ * rather than as seven unrelated passages. That count is the whole reason to
+ * use a list rather than a stack of divs.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category data
+ * @aliases Rows, Stack, Menu
+ * @documentation https://helix.fusion.dev/components/list
+ *
+ * @slot - The rows.
+ */
+let HelixHeadlessList = class HelixHeadlessList extends HelixElement {
+    constructor() {
+        super(...arguments);
+        /**
+         * Accessible name for the set.
+         */
+        this.label = '';
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        hostAria(this.internals, { label: this.label, role: 'list' });
+        /* `role="list"` at every kind, including `description`. A description list
+           has its own native role, but this renders divs rather than `<dl>`, and
+           claiming `term`/`definition` without the owning `list` those roles
+           require is worse than a plain list: an invented role that resolves to
+           nothing tells a reader less than an honest generic one. The pairing is
+           carried by the markup being a label and its supporting text, which is
+           what it already was. */
+    }
+    render() {
+        return html `<slot></slot>`;
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessList.prototype, "label", void 0);
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessList.prototype, "kind", void 0);
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessList.prototype, "type", void 0);
+HelixHeadlessList = __decorate([
+    customElement('helix-headless-list')
+], HelixHeadlessList);
+export { HelixHeadlessList };

package/dist/listbox/index.d.ts

@@ -0,0 +1 @@
+export * from './root/listbox-root.js';

package/dist/listbox/index.js

@@ -0,0 +1 @@
+export * from './root/listbox-root.js';