@fusion.dev/helix-headless 0.0.0-dev

package/dist/breadcrumbs/breadcrumb/breadcrumb.d.ts

@@ -0,0 +1,104 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+/**
+ * @summary One step in a breadcrumb trail.
+ *
+ * @description
+ * Contributes the separator, the list-item role, and the link itself where one
+ * is wanted.
+ *
+ * **`href` makes the crumb the link.** *Added 19 Aug 2026, reversing the note
+ * that said an anchor could not be rendered here.* That note was right that a
+ * router cannot reach an anchor inside a shadow root, and wrong that this
+ * settles it: the consumer restores the soft navigation by intercepting the
+ * click on the way out, which is what `Tree.Item` and `List.Item` both do.
+ * What the anchor buys is the whole crumb as a target, Enter, middle click, the
+ * status bar, and a trail that works before any JavaScript runs.
+ *
+ * **And the parent needs it.** A trail that collapses has to rebuild its hidden
+ * crumbs somewhere else, which means reading each one's destination. From a
+ * property that is a read; from a consumer's slotted markup it is a hunt for an
+ * anchor and a guess about which element is the link.
+ *
+ * A crumb with no `href` is unchanged: the consumer slots whatever they like,
+ * including their own anchor, and this renders a plain `<span>` around it.
+ *
+ * Each item renders its own separator and hides it with `:host(:first-child)`,
+ * so the trail needs no index and no coordination from the parent. `:host()`
+ * takes a structural pseudo-class, unlike `:has()`, which it rejects.
+ *
+ * The current page is text, not a link. Linking a page to itself is a known
+ * screen-reader annoyance, and `aria-current="page"` on the host is what
+ * conveys position.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @aliases Crumb
+ * @documentation https://helix.fusion.dev/components/breadcrumbs
+ *
+ * @slot - The step's label. Without an `href` this may be the consumer's own
+ * anchor, styled with `data-link="quiet"`, since a slotted anchor belongs to the
+ * outer tree and cannot be reached from this component's styles.
+ * @slot end - After it, for a count or a mark.
+ * @slot separator - Replaces the chevron shown before this item.
+ * @slot start - Before the label, for an icon.
+ *
+ * @csspart link - The crumb itself, which is an `<a>` where `href` is set.
+ * @csspart separator - The separator preceding the item.
+ * @csspart separator-mark - The glyph between this crumb and the next, where none is slotted.
+ */
+export declare class HelixHeadlessBreadcrumb extends HelixElement {
+    /**
+     * Whether this item is the page the reader is on.
+     */
+    current: boolean;
+    /**
+     * Where the crumb goes, and nothing where it is the current page.
+     *
+     * **Optional and reflected, because a stylesheet does select on it.**
+     * `breadcrumb.css` writes `:host(:not([href])) [part="link"]` to take the
+     * block padding off a crumb that is not a link, so the attribute is what
+     * decides how tall a crumb is. Unreflected, an `href` set from script reached
+     * the property, rendered the anchor, and left the host looking unlinked: the
+     * crumb drew at 20px where a markup twin drew at 28.
+     *
+     * *This said the opposite until 27 Aug 2026*, and named the reason as
+     * "nothing selects on it", which was not true when it was written. The
+     * paragraph is worth keeping because the rest of it is right and is what makes
+     * this optional rather than defaulted: an `href` written onto every host would
+     * be a link to the current page on every crumb nobody asked to be one. That is
+     * the general rule as well, that a reflected property takes no default, so the
+     * two agree.
+     *
+     * Found by the picture comparison rather than by reading: React assigns a
+     * matching property instead of an attribute, so every crumb in the React twin
+     * of `breadcrumbs/links` lost its padding at once.
+     */
+    href?: string;
+    /**
+     * Where the link opens, for the rare crumb that leaves the site.
+     */
+    target: string;
+    /**
+     * What the link declares about where it goes.
+     *
+     * The consumer's decision.
+     */
+    rel: string;
+    protected willUpdate(changed: PropertyValues): void;
+    /**
+     * The mark between one crumb and the next.
+     *
+     * The chevron is the slot's own fallback, so replacing it is a matter of
+     * filling the slot and costs the consumer no way to opt out of the default.
+     * The seam answers the other half: a tier drawing its own separator gets it
+     * without reimplementing the crumb, its link and its current-page branch.
+     */
+    protected renderSeparator(): TemplateResult;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-breadcrumb': HelixHeadlessBreadcrumb;
+    }
+}

package/dist/breadcrumbs/breadcrumb/breadcrumb.js

@@ -0,0 +1,137 @@
+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 { caretRight } from '@fusion.dev/helix-icons';
+import { html, nothing } from 'lit';
+import { property } from 'lit/decorators.js';
+import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
+/**
+ * @summary One step in a breadcrumb trail.
+ *
+ * @description
+ * Contributes the separator, the list-item role, and the link itself where one
+ * is wanted.
+ *
+ * **`href` makes the crumb the link.** *Added 19 Aug 2026, reversing the note
+ * that said an anchor could not be rendered here.* That note was right that a
+ * router cannot reach an anchor inside a shadow root, and wrong that this
+ * settles it: the consumer restores the soft navigation by intercepting the
+ * click on the way out, which is what `Tree.Item` and `List.Item` both do.
+ * What the anchor buys is the whole crumb as a target, Enter, middle click, the
+ * status bar, and a trail that works before any JavaScript runs.
+ *
+ * **And the parent needs it.** A trail that collapses has to rebuild its hidden
+ * crumbs somewhere else, which means reading each one's destination. From a
+ * property that is a read; from a consumer's slotted markup it is a hunt for an
+ * anchor and a guess about which element is the link.
+ *
+ * A crumb with no `href` is unchanged: the consumer slots whatever they like,
+ * including their own anchor, and this renders a plain `<span>` around it.
+ *
+ * Each item renders its own separator and hides it with `:host(:first-child)`,
+ * so the trail needs no index and no coordination from the parent. `:host()`
+ * takes a structural pseudo-class, unlike `:has()`, which it rejects.
+ *
+ * The current page is text, not a link. Linking a page to itself is a known
+ * screen-reader annoyance, and `aria-current="page"` on the host is what
+ * conveys position.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @aliases Crumb
+ * @documentation https://helix.fusion.dev/components/breadcrumbs
+ *
+ * @slot - The step's label. Without an `href` this may be the consumer's own
+ * anchor, styled with `data-link="quiet"`, since a slotted anchor belongs to the
+ * outer tree and cannot be reached from this component's styles.
+ * @slot end - After it, for a count or a mark.
+ * @slot separator - Replaces the chevron shown before this item.
+ * @slot start - Before the label, for an icon.
+ *
+ * @csspart link - The crumb itself, which is an `<a>` where `href` is set.
+ * @csspart separator - The separator preceding the item.
+ * @csspart separator-mark - The glyph between this crumb and the next, where none is slotted.
+ */
+let HelixHeadlessBreadcrumb = class HelixHeadlessBreadcrumb extends HelixElement {
+    constructor() {
+        super(...arguments);
+        /**
+         * Whether this item is the page the reader is on.
+         */
+        this.current = false;
+        /**
+         * Where the link opens, for the rare crumb that leaves the site.
+         */
+        this.target = '';
+        /**
+         * What the link declares about where it goes.
+         *
+         * The consumer's decision.
+         */
+        this.rel = '';
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        // On the host, because the item is an `<ol>` child in the flat tree and the
+        // role has to be there for the list to have items. In `willUpdate` rather
+        // than `connectedCallback`, which the server never calls.
+        hostAria(this.internals, { role: 'listitem' });
+        this.internals.ariaCurrent = this.current ? 'page' : null;
+    }
+    /**
+     * The mark between one crumb and the next.
+     *
+     * The chevron is the slot's own fallback, so replacing it is a matter of
+     * filling the slot and costs the consumer no way to opt out of the default.
+     * The seam answers the other half: a tier drawing its own separator gets it
+     * without reimplementing the crumb, its link and its current-page branch.
+     */
+    renderSeparator() {
+        return html `<slot name="separator"
+      ><svg part="separator-mark" fill="currentColor" viewBox=${caretRight.viewBox}>
+        ${unsafeSVG(caretRight.content)}
+      </svg></slot
+    >`;
+    }
+    render() {
+        /* The label and whatever flanks it, which is the same content whether or
+           not it is a link. Built once so the two branches below cannot drift. */
+        const label = html `<slot name="start"></slot><slot></slot><slot name="end"></slot>`;
+        /* The current page is text, not a link, whatever it was given: linking a
+           page to itself is a known screen-reader annoyance and `aria-current` is
+           what conveys position. So `current` wins over `href` rather than the two
+           contradicting each other in the markup. */
+        const linked = (this.href ?? '') !== '' && !this.current;
+        return html `<span part="separator" aria-hidden="true"
+        >${this.renderSeparator()}</span
+      >${linked
+            ? html `<a
+              part="link"
+              href=${this.href ?? ''}
+              target=${this.target || nothing}
+              rel=${this.rel || nothing}
+              >${label}</a
+            >`
+            : html `<span part="link">${label}</span>`}`;
+    }
+};
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessBreadcrumb.prototype, "current", void 0);
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessBreadcrumb.prototype, "href", void 0);
+__decorate([
+    property()
+], HelixHeadlessBreadcrumb.prototype, "target", void 0);
+__decorate([
+    property()
+], HelixHeadlessBreadcrumb.prototype, "rel", void 0);
+HelixHeadlessBreadcrumb = __decorate([
+    customElement('helix-headless-breadcrumb')
+], HelixHeadlessBreadcrumb);
+export { HelixHeadlessBreadcrumb };

package/dist/breadcrumbs/index.d.ts

@@ -0,0 +1,2 @@
+export * from './breadcrumb/breadcrumb.js';
+export * from './root/breadcrumbs-root.js';

package/dist/breadcrumbs/index.js

@@ -0,0 +1,2 @@
+export * from './breadcrumb/breadcrumb.js';
+export * from './root/breadcrumbs-root.js';

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

@@ -0,0 +1,77 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+/**
+ * @summary Shows the path to the current page.
+ *
+ * @description
+ * The host is the landmark, so `aria-label` on it names the trail directly and
+ * there is no property mirroring one. A page may hold more than one navigation,
+ * and landmarks are how a screen-reader user chooses between them.
+ *
+ * `role="list"` is set explicitly on the `<ol>` even though it is already a
+ * list: removing the markers with `list-style: none` strips list semantics in
+ * Safari, and a breadcrumb trail always removes its markers.
+ *
+ * Items are slotted rather than wrapped, so they are `<ol>` children in the flat
+ * tree and each carries `role="listitem"` itself.
+ *
+ * **The trail does not measure itself, and the overflow is markup.** It held a
+ * `collapse` property, a `ResizeObserver` through `CollapseController`, an
+ * `overflowed` getter and a `helix-change` event, all to answer one question:
+ * how many crumbs fit. Removed 20 Aug 2026, because the question is the wrong
+ * one and answering it cost more than it returned.
+ *
+ * - **It can never reach the server.** There is no width without a DOM, so the
+ *   server shipped every crumb and the client removed some after hydrating. A
+ *   trail that collapses therefore painted wrong on every single load, and the
+ *   SSR spec asserting "hides no crumb, whatever collapse says" was recording
+ *   that as correct behavior rather than as the cost it is.
+ * - **The consumer already wrote the crumbs.** The measurement hid some, then
+ *   announced which, so that the consumer could read them back off the element
+ *   and clone them into menu items. The overflow example spent 32 lines of
+ *   JavaScript making a round trip out of data that started in its own markup.
+ * - **Nobody specifies a breadcrumb in units of fit.** Designs say "keep the
+ *   root and the current page, fold the middle", which is a fact about depth,
+ *   or "fold below this width", which is a fact CSS knows. The arithmetic was
+ *   the only thing that needed a width, and it was wrong three times in one day:
+ *   the observer watched a container that did not exist yet, the gap between
+ *   items went uncounted, and the result was still wrong at 34rem.
+ *
+ * So the trail lays out crumbs and separators, and the consumer writes what
+ * folds: a `helix-menu` of `helix-menu-item`s in a crumb, where the gap
+ * belongs. Server rendered, no observer, no stylesheet, and correct before the
+ * first script runs. A trail that should fold only at some widths is a
+ * container query in the consumer's own sheet, which is theirs to write and
+ * theirs to leave out.
+ *
+ * **And the crumbs carry no marker for any of it.** There was an `overflow`
+ * property on the crumb, which existed so the controller could tell a control
+ * from a step and so the trail could size it. With the controller gone the
+ * first use went with it, and the second is better answered by the crumb
+ * sizing whatever is slotted into it, which is true of every crumb rather than
+ * of one a consumer remembered to mark. What is left is a fact CSS can already
+ * see: the crumb with the menu in it is `:has(helix-menu)`, and the middle is
+ * `:not(:first-child, [current])`. A marker would be the design rule written
+ * twice, once in the HTML and once in the sheet, with nothing keeping the two
+ * honest.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category navigation
+ * @aliases Breadcrumb, Crumbs
+ * @documentation https://helix.fusion.dev/components/breadcrumbs
+ *
+ * @slot - The trail's items, in order from root to current page, with the
+ * crumb holding the fold wherever the gap should appear.
+ *
+ * @csspart list - The ordered list.
+ */
+export declare class HelixHeadlessBreadcrumbs extends HelixElement {
+    protected willUpdate(changed: PropertyValues): void;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-breadcrumbs': HelixHeadlessBreadcrumbs;
+    }
+}

package/dist/breadcrumbs/root/breadcrumbs-root.js

@@ -0,0 +1,94 @@
+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';
+/**
+ * @summary Shows the path to the current page.
+ *
+ * @description
+ * The host is the landmark, so `aria-label` on it names the trail directly and
+ * there is no property mirroring one. A page may hold more than one navigation,
+ * and landmarks are how a screen-reader user chooses between them.
+ *
+ * `role="list"` is set explicitly on the `<ol>` even though it is already a
+ * list: removing the markers with `list-style: none` strips list semantics in
+ * Safari, and a breadcrumb trail always removes its markers.
+ *
+ * Items are slotted rather than wrapped, so they are `<ol>` children in the flat
+ * tree and each carries `role="listitem"` itself.
+ *
+ * **The trail does not measure itself, and the overflow is markup.** It held a
+ * `collapse` property, a `ResizeObserver` through `CollapseController`, an
+ * `overflowed` getter and a `helix-change` event, all to answer one question:
+ * how many crumbs fit. Removed 20 Aug 2026, because the question is the wrong
+ * one and answering it cost more than it returned.
+ *
+ * - **It can never reach the server.** There is no width without a DOM, so the
+ *   server shipped every crumb and the client removed some after hydrating. A
+ *   trail that collapses therefore painted wrong on every single load, and the
+ *   SSR spec asserting "hides no crumb, whatever collapse says" was recording
+ *   that as correct behavior rather than as the cost it is.
+ * - **The consumer already wrote the crumbs.** The measurement hid some, then
+ *   announced which, so that the consumer could read them back off the element
+ *   and clone them into menu items. The overflow example spent 32 lines of
+ *   JavaScript making a round trip out of data that started in its own markup.
+ * - **Nobody specifies a breadcrumb in units of fit.** Designs say "keep the
+ *   root and the current page, fold the middle", which is a fact about depth,
+ *   or "fold below this width", which is a fact CSS knows. The arithmetic was
+ *   the only thing that needed a width, and it was wrong three times in one day:
+ *   the observer watched a container that did not exist yet, the gap between
+ *   items went uncounted, and the result was still wrong at 34rem.
+ *
+ * So the trail lays out crumbs and separators, and the consumer writes what
+ * folds: a `helix-menu` of `helix-menu-item`s in a crumb, where the gap
+ * belongs. Server rendered, no observer, no stylesheet, and correct before the
+ * first script runs. A trail that should fold only at some widths is a
+ * container query in the consumer's own sheet, which is theirs to write and
+ * theirs to leave out.
+ *
+ * **And the crumbs carry no marker for any of it.** There was an `overflow`
+ * property on the crumb, which existed so the controller could tell a control
+ * from a step and so the trail could size it. With the controller gone the
+ * first use went with it, and the second is better answered by the crumb
+ * sizing whatever is slotted into it, which is true of every crumb rather than
+ * of one a consumer remembered to mark. What is left is a fact CSS can already
+ * see: the crumb with the menu in it is `:has(helix-menu)`, and the middle is
+ * `:not(:first-child, [current])`. A marker would be the design rule written
+ * twice, once in the HTML and once in the sheet, with nothing keeping the two
+ * honest.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category navigation
+ * @aliases Breadcrumb, Crumbs
+ * @documentation https://helix.fusion.dev/components/breadcrumbs
+ *
+ * @slot - The trail's items, in order from root to current page, with the
+ * crumb holding the fold wherever the gap should appear.
+ *
+ * @csspart list - The ordered list.
+ */
+let HelixHeadlessBreadcrumbs = class HelixHeadlessBreadcrumbs extends HelixElement {
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        // On the host through internals, so the landmark is the element itself and
+        // an author's `aria-label` names it without anything being copied inward.
+        hostAria(this.internals, { role: 'navigation' });
+    }
+    render() {
+        /* One slot. The crumb holding the fold is one the consumer placed in
+           source order, so there is nothing here to position it: the list renders
+           what it was given, in the order it was given. */
+        return html `<ol part="list" role="list">
+      <slot></slot>
+    </ol>`;
+    }
+};
+HelixHeadlessBreadcrumbs = __decorate([
+    customElement('helix-headless-breadcrumbs')
+], HelixHeadlessBreadcrumbs);
+export { HelixHeadlessBreadcrumbs };

package/dist/button/index.d.ts

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

package/dist/button/index.js

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