@fusion.dev/helix-headless 0.0.0-dev

package/dist/steps/step/step.js

@@ -0,0 +1,215 @@
+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, HelixSelectEvent, hostAria } from '@fusion.dev/helix-core';
+import { check, circle, record } from '@fusion.dev/helix-icons';
+import { property } from 'lit/decorators.js';
+import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
+import { html } from 'lit/static-html.js';
+/* Side-effect import, because this renders a button and a custom element
+   registers on import. The path is relative, so this registers the base button
+   and the styled file's identical import registers the styled one; `tier` picks
+   which name the template asks for. `check:composed` enforces both. */
+import '../../button/index.js';
+/**
+ * @summary One stage in a sequence.
+ *
+ * @description
+ * **The name is a button, and only the name.** A stepper is something a reader
+ * goes back through, and the thing they reach for is the name of the stage. The
+ * marker is `aria-hidden` decoration, so wrapping it in the button would add
+ * hit area and no meaning: the accessible name would be the text either way,
+ * and what is pressable would stop being the same shape as what is readable.
+ *
+ * It is `helix-button`, not a `<button>` this element resets and dresses. The
+ * hover wash, the focus ring, the disabled treatment and the way the label sits
+ * against an icon are all decisions the button already carries, and a second
+ * copy of them here is a second copy to keep in step. `ghost` is the quiet
+ * shape: transparent until it is pointed at.
+ *
+ * It says nothing about where a reader may go. Every step is pressable and
+ * announces itself with `helix-select`; refusing the ones ahead is `disabled`,
+ * which the consumer sets because only the consumer knows whether a form can be
+ * skipped. A component that guessed would be wrong on the first wizard that
+ * lets you jump to the end.
+ *
+ * **The marker is a slot whose fallback is the state.** A finished stage shows
+ * a check, the current one a target, and one not yet reached an empty ring:
+ * three marks that say what a reader wants to know without a legend. A consumer
+ * who wants their own fills the slot instead.
+ *
+ * The step renders exactly one of the three, chosen from its own two booleans.
+ * Rendering all three and hiding two in CSS would work and is worse: the
+ * accessibility tree would carry marks that are not there, and the markup would
+ * say three things about a stage that is one.
+ *
+ * Numbering is a separate question and belongs to the tier above. `numeric`
+ * hides the mark and shows a CSS counter, which the browser resolves at layout,
+ * so the digit costs no script and is right in the server's markup however the
+ * steps are ordered. Nothing here knows which appearance is in use, and does
+ * not need to.
+ *
+ * **`complete` and `current` are separate, and both can be false.** A stage
+ * that is neither is one the reader has not reached, which is the majority of
+ * any sequence and therefore the state that needs no attribute. They can also
+ * both be true: a reader who steps back into a finished stage is in it and has
+ * finished it, and a stepper that forgets the second is one that loses its
+ * checks the moment somebody reviews their answers.
+ *
+ * **The `content` slot opens on the current step, and only down a column.** A
+ * row has no room under a step to put a form in, and stretching one to fit
+ * would set every step's height by the tallest. `current` is what opens it, so
+ * the state that says where the reader is is also the state that shows them the
+ * stage: one attribute, no second flag to keep in step with it, and it renders
+ * open on the server rather than after hydration.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @aliases Stage
+ * @documentation https://helix.fusion.dev/components/steps
+ *
+ * @slot - The step's name.
+ * @slot content - What the stage holds, shown while it is the current one.
+ * @slot description - A line under the name, for what the stage is for.
+ * @slot marker - Replaces the number, or the check a complete step shows.
+ *
+ * @event {HelixSelectEvent} helix-select - Fired when the step is pressed. Cancelable: refusing it takes the decision and nothing moves.
+ *
+ * @csspart body - The name and its description.
+ * @csspart content - What the stage holds, while it is open.
+ * @csspart description - The line under it.
+ * @csspart label - The step's name, which is a `helix-button`.
+ * @csspart label-button - The inner control.
+ * @csspart lead - The half line arriving from the step before.
+ * @csspart mark - The glyph inside the marker: a tick, a dot, or an empty ring.
+ * @csspart marker - The shape carrying the number or the check.
+ * @csspart trail - The half line running on to the next.
+ */
+let HelixHeadlessStep = class HelixHeadlessStep extends HelixElement {
+    constructor() {
+        super(...arguments);
+        /**
+         * Whether the reader has finished this stage.
+         */
+        this.complete = false;
+        /**
+         * Whether this is the stage the reader is in.
+         */
+        this.current = false;
+        /**
+         * Whether the reader may go to this stage.
+         */
+        this.disabled = false;
+        /**
+         * What this stage is called when it announces itself.
+         */
+        this.value = '';
+    }
+    /** Announces the step, unless it is refusing. */
+    select() {
+        if (this.disabled) {
+            return;
+        }
+        this.dispatchEvent(new HelixSelectEvent({ value: this.value }));
+    }
+    /**
+     * The mark this stage's state calls for.
+     *
+     * `complete` first, so a stage a reader has stepped back into keeps its check
+     * rather than losing it to the target: they did finish it, and the name and
+     * the rule below still say which one is open.
+     *
+     * **Three shapes, and the reader can tell them apart with the color off.**
+     * An outline circle for a stage nobody has reached, the same circle with a
+     * center for the one they are standing on, a bare check for one that is done.
+     * The first two are one shape filling in, which is the progression, and the
+     * check is the only mark that leaves the family because finishing is the only
+     * state that is not a position in the sequence.
+     *
+     * What went was the coin around the check: a filled disc carrying a check
+     * beside a filled disc carrying a ring put two of the three inside the same
+     * container, and left hue doing most of the work of telling them apart.
+     *
+     * The bare check is `Timeline`'s, deliberately: the two components report the
+     * same kind of thing, a sequence with marks down it, and a check floating on
+     * a hairline in one beside a check inside a green coin in the other was two
+     * answers to one question. Timeline's rings came off the same day.
+     */
+    renderMarker() {
+        const icon = this.complete ? check : this.current ? record : circle;
+        return html `<slot name="marker"
+      ><svg part="mark" fill="currentColor" viewBox=${icon.viewBox}
+        >${unsafeSVG(icon.content)}</svg
+      ></slot
+    >`;
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        hostAria(this.internals, { role: 'listitem' });
+        this.internals.ariaCurrent = this.current ? 'step' : null;
+    }
+    /**
+     * The step's own label, which is a control because a step can be gone to, behind a seam the styled tier can move.
+     *
+     * A method rather than a fragment inline, so a tier above can render its own,
+     * wrap this one, pass it a property the base does not know about, or leave it
+     * out, without reimplementing the whole template to do any of them. The tag is
+     * interpolated rather than written, so `tier` resolves it: this renders the
+     * headless element, and a styled subclass that sets `tier` renders the styled one
+     * from the same template.
+     */
+    renderLabel() {
+        return html `<${this.tag('button')}
+      part="label"
+      exportparts="button: label-button"
+      appearance="ghost"
+      ?disabled=${this.disabled}
+      @click=${this.select}
+    >
+      <slot></slot>
+    </${this.tag('button')}>`;
+    }
+    render() {
+        /* Two half lines, one either side of the mark, rather than one line running
+           the whole way to the next step.
+           A single line was tried twice. Drawn to the next marker it has to know
+           how far away that is, which is the next step's size, and a step knows
+           only its own. Drawn across the gap alone it is a stub. Two halves need
+           neither: each reaches from the mark to its own step's edge and half the
+           gap beyond, so it meets the one coming the other way in the middle of the
+           gap and the rule reads as continuous however wide the steps are or how
+           differently they are filled.
+           The first has nothing on its leading side and the last nothing on its
+           trailing one, which `:host(:first-child)` and `:host(:last-child)` say
+           with no index and no parent counting its children. */
+        return html `<span part="lead" aria-hidden="true"></span>
+      <span part="trail" aria-hidden="true"></span>
+      <span part="marker" aria-hidden="true">
+        ${this.renderMarker()}
+      </span>
+      <span part="body">
+        ${this.renderLabel()}
+        <span part="description"><slot name="description"></slot></span>
+      </span>
+      <div part="content"><slot name="content"></slot></div>`;
+    }
+};
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessStep.prototype, "complete", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessStep.prototype, "current", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessStep.prototype, "disabled", void 0);
+__decorate([
+    property()
+], HelixHeadlessStep.prototype, "value", void 0);
+HelixHeadlessStep = __decorate([
+    customElement('helix-headless-step')
+], HelixHeadlessStep);
+export { HelixHeadlessStep };

package/dist/switch/index.d.ts

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

package/dist/switch/index.js

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

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

@@ -0,0 +1,74 @@
+import { AriaForwardController, HelixFormElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+declare const HelixHeadlessSwitch_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerCheckedInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
+/**
+ * @summary A control that turns something on or off.
+ *
+ * @description
+ * **A switch is not a checkbox with a different shape.** A checkbox is an
+ * answer to a question the form asks when it is submitted; a switch is a thing
+ * happening now. That is why `role="switch"` exists and why a switch belongs
+ * outside a form as often as in one: it says "on" and "off" rather than
+ * "ticked" and "unticked", and a reader expects the effect immediately rather
+ * than on Save.
+ *
+ * Rendered as a real `<input type="checkbox">` carrying `role="switch"`, which
+ * is the pairing ARIA describes: the input is what a form submits and what a
+ * label forwards a press to, and the role is what a screen reader announces.
+ * Neither half can be got from the other.
+ *
+ * The label sits beside it, inside the `<label>` that forwards the press, the
+ * way a checkbox's does. The hint and the message go under the row, because
+ * there is no above: the switch and the words naming it are one line.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category forms
+ * @aliases Toggle switch, On/off
+ * @documentation https://helix.fusion.dev/components/switch
+ *
+ * @slot - The words naming what this turns on.
+ *
+ * @event {Event} change - Relayed from the input once the state has changed.
+ * @event {HelixBeforeToggleEvent} helix-before-toggle - Fired before the state changes, and cancelable.
+ * @event {Event} input - Announced once the state has moved.
+ *
+ * @csspart control - The input.
+ * @csspart feedback - What is wrong with it.
+ * @csspart field - The row: the track and its label.
+ * @csspart hint - Help under the control, while nothing is wrong.
+ * @csspart label - The words beside it.
+ * @csspart thumb - The part that moves.
+ * @csspart track - The groove the thumb travels in.
+ */
+export declare class HelixHeadlessSwitch extends HelixHeadlessSwitch_base {
+    protected readonly aria: AriaForwardController;
+    /**
+     * Value submitted when the switch is on.
+     */
+    value: string;
+    private readonly handleChange;
+    /** Reports what the form would submit, and the verdict on it. */
+    private sync;
+    /** Returns the switch to the state its markup declared. */
+    formResetCallback(): void;
+    protected updated(changed: PropertyValues): void;
+    /**
+     * Says on the `label` region whether anything is in it.
+     *
+     * An empty region is not free: it is still a flex item, so it still takes the
+     * container's gap. There is no selector that can ask, `slot:empty` being
+     * about a slot's fallback rather than its assigned nodes, so the component
+     * asks and says so, on the region inside this shadow root rather than on the
+     * host: an attribute written onto the host is a change to markup the consumer
+     * rendered, which React reports on hydration and does not patch up.
+     */
+    private markEmpty;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-switch': HelixHeadlessSwitch;
+    }
+}
+export {};

package/dist/switch/root/switch-root.js

@@ -0,0 +1,153 @@
+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 { AriaForwardController, customElement, HelixFormElement, MixinControllerChecked, MixinField, slotFilled, } from '@fusion.dev/helix-core';
+import { html, nothing } from 'lit';
+import { property } from 'lit/decorators.js';
+/**
+ * @summary A control that turns something on or off.
+ *
+ * @description
+ * **A switch is not a checkbox with a different shape.** A checkbox is an
+ * answer to a question the form asks when it is submitted; a switch is a thing
+ * happening now. That is why `role="switch"` exists and why a switch belongs
+ * outside a form as often as in one: it says "on" and "off" rather than
+ * "ticked" and "unticked", and a reader expects the effect immediately rather
+ * than on Save.
+ *
+ * Rendered as a real `<input type="checkbox">` carrying `role="switch"`, which
+ * is the pairing ARIA describes: the input is what a form submits and what a
+ * label forwards a press to, and the role is what a screen reader announces.
+ * Neither half can be got from the other.
+ *
+ * The label sits beside it, inside the `<label>` that forwards the press, the
+ * way a checkbox's does. The hint and the message go under the row, because
+ * there is no above: the switch and the words naming it are one line.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category forms
+ * @aliases Toggle switch, On/off
+ * @documentation https://helix.fusion.dev/components/switch
+ *
+ * @slot - The words naming what this turns on.
+ *
+ * @event {Event} change - Relayed from the input once the state has changed.
+ * @event {HelixBeforeToggleEvent} helix-before-toggle - Fired before the state changes, and cancelable.
+ * @event {Event} input - Announced once the state has moved.
+ *
+ * @csspart control - The input.
+ * @csspart feedback - What is wrong with it.
+ * @csspart field - The row: the track and its label.
+ * @csspart hint - Help under the control, while nothing is wrong.
+ * @csspart label - The words beside it.
+ * @csspart thumb - The part that moves.
+ * @csspart track - The groove the thumb travels in.
+ */
+let HelixHeadlessSwitch = class HelixHeadlessSwitch extends MixinControllerChecked(MixinField(HelixFormElement)) {
+    constructor() {
+        super(...arguments);
+        /* A consumer's `aria-describedby` names ids in their own tree and the control
+           is in this shadow root, so the reference has to be carried down as an
+           element rather than copied as an id. See `AriaForwardController`: measured
+           in Chrome's own tree, the host held the description and the control the
+           reader is actually on was exposed without it. */
+        this.aria = new AriaForwardController(this, {
+            target: () => this.renderRoot?.querySelector('[part="control"]') ?? null,
+        });
+        /**
+         * Value submitted when the switch is on.
+         */
+        this.value = 'on';
+        this.handleChange = (event) => {
+            event.stopPropagation();
+            const control = event.target;
+            const taken = this.requestChecked(control.checked);
+            /* The input follows the element, always, not only where the change was
+               refused.
+             *
+             * A controlled switch takes the request and applies nothing: it has
+               announced where it would go and is waiting to be told. The input had
+               already flipped itself, so until the consumer answered, the switch showed
+               one state and held the other, and a consumer who never answers showed the
+               wrong one for good. Putting it back costs nothing where the change was
+               taken, since `this.checked` is then the new value anyway. */
+            control.checked = this.checked;
+            if (!taken) {
+                return;
+            }
+            this.dispatchEvent(new Event('change', { bubbles: true, composed: false }));
+        };
+    }
+    /** Reports what the form would submit, and the verdict on it. */
+    sync() {
+        // `null` rather than the value when it is off, which is how a checkbox
+        // behaves: an unticked box submits nothing rather than a blank.
+        this.internals.setFormValue(this.checked ? this.value : null);
+        this.reportRequired(!this.checked, 'Turn this on to continue.', 'control');
+    }
+    /** Returns the switch to the state its markup declared. */
+    formResetCallback() {
+        // `resetChecked` drops both halves now, the consumer's and the element's,
+        // so there is nothing to clear before it.
+        this.resetChecked();
+    }
+    updated(changed) {
+        super.updated(changed);
+        this.markEmpty();
+        this.sync();
+    }
+    /**
+     * Says on the `label` region whether anything is in it.
+     *
+     * An empty region is not free: it is still a flex item, so it still takes the
+     * container's gap. There is no selector that can ask, `slot:empty` being
+     * about a slot's fallback rather than its assigned nodes, so the component
+     * asks and says so, on the region inside this shadow root rather than on the
+     * host: an attribute written onto the host is a change to markup the consumer
+     * rendered, which React reports on hydration and does not patch up.
+     */
+    markEmpty() {
+        const region = this.renderRoot?.querySelector('[part="label"]');
+        const empty = !slotFilled(this.renderRoot?.querySelector('[part="label"] slot'));
+        region?.toggleAttribute('data-empty', empty);
+        /* `hidden` beside the mirror, because `data-empty` is a hook the styled
+           sheet reads and this tier has no sheet: an empty region left in the box
+           tree is a gap a consumer cannot close without knowing to look for it. The
+           styled rule stays, because that sheet sets `display` on this part and so
+           outranks the UA one. */
+        region?.toggleAttribute('hidden', empty);
+    }
+    render() {
+        /* A real `<label>` around both, so pressing the words works with no click
+           handler: the browser does the forwarding. */
+        return html `<label part="field">
+      <span part="track">
+        <input
+          part="control"
+          type="checkbox"
+          role="switch"
+          .checked=${this.checked}
+          ?disabled=${this.isDisabled}
+          ?required=${this.required}
+          aria-describedby=${this.describedBy ?? nothing}
+          @change=${this.handleChange}
+          @input=${this.stopInner}
+        />
+        <span part="thumb" aria-hidden="true"></span>
+      </span>
+      <span part="label"><slot>${this.label}</slot></span>
+    </label>
+    ${this.renderHint()}${this.renderFeedback()}`;
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessSwitch.prototype, "value", void 0);
+HelixHeadlessSwitch = __decorate([
+    customElement('helix-headless-switch')
+], HelixHeadlessSwitch);
+export { HelixHeadlessSwitch };

package/dist/table/cell/table-cell.d.ts

@@ -0,0 +1,34 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+/**
+ * @summary One cell of a table.
+ *
+ * @description
+ * Carries its own role, because a grid of divs is not a table to anything
+ * reading it. `header` makes the cell a `columnheader`, which is what lets a
+ * screen reader announce "Attribute, appearance" rather than just the value.
+ *
+ * The role goes on the host rather than inside the shadow root, because the
+ * cell has to be a child of its row in the flat tree for the table's structure
+ * to hold together.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @aliases Cell, TableCell
+ * @documentation https://helix.fusion.dev/components/table
+ *
+ * @slot - The cell's content.
+ */
+export declare class HelixHeadlessTableCell extends HelixElement {
+    /**
+     * Whether the cell heads its column.
+     */
+    header: boolean;
+    protected willUpdate(changed: PropertyValues): void;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-table-cell': HelixHeadlessTableCell;
+    }
+}

package/dist/table/cell/table-cell.js

@@ -0,0 +1,52 @@
+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 One cell of a table.
+ *
+ * @description
+ * Carries its own role, because a grid of divs is not a table to anything
+ * reading it. `header` makes the cell a `columnheader`, which is what lets a
+ * screen reader announce "Attribute, appearance" rather than just the value.
+ *
+ * The role goes on the host rather than inside the shadow root, because the
+ * cell has to be a child of its row in the flat tree for the table's structure
+ * to hold together.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @aliases Cell, TableCell
+ * @documentation https://helix.fusion.dev/components/table
+ *
+ * @slot - The cell's content.
+ */
+let HelixHeadlessTableCell = class HelixHeadlessTableCell extends HelixElement {
+    constructor() {
+        super(...arguments);
+        /**
+         * Whether the cell heads its column.
+         */
+        this.header = false;
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        // In `willUpdate`, which the server does call, unlike `connectedCallback`.
+        hostAria(this.internals, { role: this.header ? 'columnheader' : 'cell' });
+    }
+    render() {
+        return html `<slot></slot>`;
+    }
+};
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessTableCell.prototype, "header", void 0);
+HelixHeadlessTableCell = __decorate([
+    customElement('helix-headless-table-cell')
+], HelixHeadlessTableCell);
+export { HelixHeadlessTableCell };