@fusion.dev/helix-headless 0.0.0-dev

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

@@ -0,0 +1,30 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+/**
+ * @summary A row of related measurements.
+ *
+ * @description
+ * A group rather than a list, because the figures are read together and their
+ * order carries no meaning: a list would announce "1 of 4" for a set where the
+ * position is not information.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @aliases Metrics, KPIs, Figures
+ * @documentation https://helix.fusion.dev/components/stat
+ *
+ * @slot - The stats.
+ */
+export declare class HelixHeadlessStatGroup extends HelixElement {
+    /**
+     * Accessible name for the set.
+     */
+    label: string;
+    protected willUpdate(changed: PropertyValues): void;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-stat-group': HelixHeadlessStatGroup;
+    }
+}

package/dist/stat/group/stat-group.js

@@ -0,0 +1,47 @@
+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 row of related measurements.
+ *
+ * @description
+ * A group rather than a list, because the figures are read together and their
+ * order carries no meaning: a list would announce "1 of 4" for a set where the
+ * position is not information.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @aliases Metrics, KPIs, Figures
+ * @documentation https://helix.fusion.dev/components/stat
+ *
+ * @slot - The stats.
+ */
+let HelixHeadlessStatGroup = class HelixHeadlessStatGroup extends HelixElement {
+    constructor() {
+        super(...arguments);
+        /**
+         * Accessible name for the set.
+         */
+        this.label = '';
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        hostAria(this.internals, { label: this.label, role: 'group' });
+    }
+    render() {
+        return html `<slot></slot>`;
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessStatGroup.prototype, "label", void 0);
+HelixHeadlessStatGroup = __decorate([
+    customElement('helix-headless-stat-group')
+], HelixHeadlessStatGroup);
+export { HelixHeadlessStatGroup };

package/dist/stat/index.d.ts

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

package/dist/stat/index.js

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

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

@@ -0,0 +1,62 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type TemplateResult } from 'lit';
+/**
+ * @summary One measurement, with the word for what it measures.
+ *
+ * @description
+ * Label first in the markup and the value after it, which is the reading order
+ * a screen reader takes and the order a caption sits above a figure. The eye
+ * lands on the number either way, because the number is the loud thing; a
+ * reader hearing it needs to know what it counts before hearing how many.
+ *
+ * This paragraph said the opposite, value first and label after, on a render
+ * that has always emitted the label slot first: the description was published
+ * to two tiers and shipped into the generated types, and the component was
+ * right and the sentence was wrong.
+ *
+ * Both are bare slots. An element whose only job is to assign itself a slot on
+ * connect gives its own host an attribute after upgrade, which a React
+ * consumer's server markup never had.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category data
+ * @aliases Metric, KPI, Figure
+ * @documentation https://helix.fusion.dev/components/stat
+ *
+ * @slot - The value.
+ * @slot label - What the value measures.
+ * @slot unit - The unit, set beside the value.
+ */
+export declare class HelixHeadlessStat extends HelixElement {
+    /**
+     * Which way the label and the value are arranged.
+     *
+     * Absent is a column, the label over the number, which is how a figure is read
+     * on a dashboard: the words say what is coming and the number answers.
+     * `column-reverse` puts the number first, which is right where the number is
+     * the headline and the label is a caption under it.
+     *
+     * The row directions set them side by side, for a figure in a line of text or
+     * a narrow strip where a stacked pair would be two lines of almost nothing.
+     *
+     * A property rather than a `helix-flex` around it, because the unit has to
+     * stay on the value's baseline whichever way the pair goes, and only this
+     * element knows which of its children the unit belongs to.
+     *
+     * **Optional rather than defaulted to `column`, which is not a style
+     * preference.** A reflecting property with a default writes its attribute onto
+     * the host the moment the element upgrades, and the host is markup the
+     * consumer rendered: React compares what it rendered against what is there and
+     * reports a hydration mismatch. The absent attribute is the column, which the
+     * stylesheet reads as the base case. The existing server spec caught this,
+     * being the one that asserts the host carries nothing nobody wrote.
+     */
+    direction?: 'column-reverse' | 'row' | 'row-reverse';
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-stat': HelixHeadlessStat;
+    }
+}

package/dist/stat/root/stat-root.js

@@ -0,0 +1,51 @@
+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 } from '@fusion.dev/helix-core';
+import { html } from 'lit';
+import { property } from 'lit/decorators.js';
+/**
+ * @summary One measurement, with the word for what it measures.
+ *
+ * @description
+ * Label first in the markup and the value after it, which is the reading order
+ * a screen reader takes and the order a caption sits above a figure. The eye
+ * lands on the number either way, because the number is the loud thing; a
+ * reader hearing it needs to know what it counts before hearing how many.
+ *
+ * This paragraph said the opposite, value first and label after, on a render
+ * that has always emitted the label slot first: the description was published
+ * to two tiers and shipped into the generated types, and the component was
+ * right and the sentence was wrong.
+ *
+ * Both are bare slots. An element whose only job is to assign itself a slot on
+ * connect gives its own host an attribute after upgrade, which a React
+ * consumer's server markup never had.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category data
+ * @aliases Metric, KPI, Figure
+ * @documentation https://helix.fusion.dev/components/stat
+ *
+ * @slot - The value.
+ * @slot label - What the value measures.
+ * @slot unit - The unit, set beside the value.
+ */
+let HelixHeadlessStat = class HelixHeadlessStat extends HelixElement {
+    render() {
+        return html `<slot name="label"></slot>
+      <slot></slot>
+      <slot name="unit"></slot>`;
+    }
+};
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessStat.prototype, "direction", void 0);
+HelixHeadlessStat = __decorate([
+    customElement('helix-headless-stat')
+], HelixHeadlessStat);
+export { HelixHeadlessStat };

package/dist/steps/index.d.ts

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

package/dist/steps/index.js

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

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

@@ -0,0 +1,110 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+declare const HelixHeadlessSteps_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerActiveInterface) & typeof HelixElement;
+/**
+ * @summary A sequence of stages, and where the reader is in it.
+ *
+ * @description
+ * **`active` names where the reader is. `complete` stays on each step.** They
+ * are two different facts and only one of them is positional. Deriving both
+ * from a position is the obvious design and it is wrong the first time anybody
+ * steps back: return to stage one of three and stages one and two are still
+ * finished, while "everything before the active one" says only the first is.
+ * So this element drives `current` and never touches `complete`.
+ *
+ * **`active` is optional, and a sequence without it still renders.** Left
+ * unset, each step's own `current` stands and nothing here overwrites it, which
+ * is what lets the whole sequence be right in the server's markup: this element
+ * would have to count its slotted children to know which one is third, and the
+ * server has no children to count. Set it, and it wins, because it is a
+ * statement about the sequence where the attribute on a step is a statement
+ * about one step.
+ *
+ * That is also why the numbering is not JavaScript. It is a CSS counter in the
+ * tier above, which the browser resolves at layout with no script at all, so
+ * the third step reads "3" in the server's own markup.
+ *
+ * **The connector belongs to the step, not to the list.** Each one draws the
+ * line that arrives at it and hides it when it is first, the same arrangement
+ * Breadcrumbs uses for its separator and for the same reason: a line drawn
+ * between items needs either an index or a parent that counts, and drawing it
+ * on the item needs neither.
+ *
+ * `role="list"` on the host rather than an `<ol>` in the shadow root. The steps
+ * are the consumer's elements in the light DOM, so an `<ol>` here would be a
+ * list whose items are somewhere else.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category navigation
+ * @aliases Stepper, Wizard, Progress steps
+ * @documentation https://helix.fusion.dev/components/steps
+ *
+ * @slot - The steps, which are `helix-step` elements.
+ *
+ * @event {HelixActivateEvent} helix-activate - Fired once the current one has moved, so the element already holds it.
+ * @event {HelixBeforeActivateEvent} helix-before-activate - Fired before the active step changes. Cancelable: refusing it takes the decision and nothing moves.
+ */
+export declare class HelixHeadlessSteps extends HelixHeadlessSteps_base {
+    /**
+     * Accessible name for the sequence.
+     *
+     * A list of stages is a landmark a reader arrives at out of order, so it
+     * needs a name of its own rather than borrowing the heading above it.
+     */
+    label: string;
+    /**
+     * Which way the steps run.
+     *
+     * Absent is a row, which is what a form header wants, with each name under
+     * its mark: beside them there is a word in the rule's path and the line would
+     * be struck through it. `vertical` stacks them, names beside their marks,
+     * which is the shape with room under a step for what the stage holds.
+     *
+     * Each axis has one arrangement rather than a second property offering both
+     * in both. Of those four combinations three are ones nobody should pick, and
+     * a property whose job is mostly to be left alone is a property that mostly
+     * catches people out.
+     */
+    orientation?: 'vertical';
+    /**
+     * What each step is marked with.
+     *
+     * Absent is the state itself: a check where a stage is done, a target where
+     * the reader is, an empty ring ahead of them. Three marks that need no
+     * legend, which a number does: "3" says where a stage sits in the order and
+     * nothing about whether it is finished.
+     *
+     * `numeric` is the older convention and is still the right one where the
+     * order is the point, a form that says "step 3 of 5" beside it, or a sequence
+     * a reader is told to come back to by number.
+     */
+    variant?: 'numeric';
+    /** The steps, in the order the consumer wrote them. */
+    private get steps();
+    /**
+     * Puts `active` on whichever step owns it.
+     *
+     * Returns without touching anything where nothing has set `active`, which is
+     * the case a server renders: the steps' own `current` is the state then, and
+     * overwriting it on hydration is exactly the flash this design exists to
+     * avoid.
+     *
+     * `current` only. `complete` is the consumer's on each step, because a reader
+     * who steps back has finished more stages than they are standing in front of.
+     */
+    private sync;
+    private readonly handleSelection;
+    private readonly handleSlotChange;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected willUpdate(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-steps': HelixHeadlessSteps;
+    }
+}
+export {};

package/dist/steps/root/steps-root.js

@@ -0,0 +1,130 @@
+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, MixinControllerActive, } from '@fusion.dev/helix-core';
+import { html } from 'lit';
+import { property } from 'lit/decorators.js';
+/**
+ * @summary A sequence of stages, and where the reader is in it.
+ *
+ * @description
+ * **`active` names where the reader is. `complete` stays on each step.** They
+ * are two different facts and only one of them is positional. Deriving both
+ * from a position is the obvious design and it is wrong the first time anybody
+ * steps back: return to stage one of three and stages one and two are still
+ * finished, while "everything before the active one" says only the first is.
+ * So this element drives `current` and never touches `complete`.
+ *
+ * **`active` is optional, and a sequence without it still renders.** Left
+ * unset, each step's own `current` stands and nothing here overwrites it, which
+ * is what lets the whole sequence be right in the server's markup: this element
+ * would have to count its slotted children to know which one is third, and the
+ * server has no children to count. Set it, and it wins, because it is a
+ * statement about the sequence where the attribute on a step is a statement
+ * about one step.
+ *
+ * That is also why the numbering is not JavaScript. It is a CSS counter in the
+ * tier above, which the browser resolves at layout with no script at all, so
+ * the third step reads "3" in the server's own markup.
+ *
+ * **The connector belongs to the step, not to the list.** Each one draws the
+ * line that arrives at it and hides it when it is first, the same arrangement
+ * Breadcrumbs uses for its separator and for the same reason: a line drawn
+ * between items needs either an index or a parent that counts, and drawing it
+ * on the item needs neither.
+ *
+ * `role="list"` on the host rather than an `<ol>` in the shadow root. The steps
+ * are the consumer's elements in the light DOM, so an `<ol>` here would be a
+ * list whose items are somewhere else.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category navigation
+ * @aliases Stepper, Wizard, Progress steps
+ * @documentation https://helix.fusion.dev/components/steps
+ *
+ * @slot - The steps, which are `helix-step` elements.
+ *
+ * @event {HelixActivateEvent} helix-activate - Fired once the current one has moved, so the element already holds it.
+ * @event {HelixBeforeActivateEvent} helix-before-activate - Fired before the active step changes. Cancelable: refusing it takes the decision and nothing moves.
+ */
+let HelixHeadlessSteps = class HelixHeadlessSteps extends MixinControllerActive(HelixElement) {
+    constructor() {
+        super(...arguments);
+        /**
+         * Accessible name for the sequence.
+         *
+         * A list of stages is a landmark a reader arrives at out of order, so it
+         * needs a name of its own rather than borrowing the heading above it.
+         */
+        this.label = 'Steps';
+        this.handleSelection = (event) => {
+            this.requestActive(event.detail.value);
+        };
+        this.handleSlotChange = () => {
+            this.sync();
+        };
+    }
+    /** The steps, in the order the consumer wrote them. */
+    get steps() {
+        return [...this.querySelectorAll(':scope > *')].filter((one) => 'current' in one);
+    }
+    /**
+     * Puts `active` on whichever step owns it.
+     *
+     * Returns without touching anything where nothing has set `active`, which is
+     * the case a server renders: the steps' own `current` is the state then, and
+     * overwriting it on hydration is exactly the flash this design exists to
+     * avoid.
+     *
+     * `current` only. `complete` is the consumer's on each step, because a reader
+     * who steps back has finished more stages than they are standing in front of.
+     */
+    sync() {
+        if (this.active === '') {
+            return;
+        }
+        const steps = this.steps;
+        const value = this.resolveActive(steps)?.value ?? '';
+        for (const step of steps) {
+            step.current = step.value === value;
+        }
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        this.addEventListener('helix-select', this.handleSelection);
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.removeEventListener('helix-select', this.handleSelection);
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        hostAria(this.internals, { label: this.label, role: 'list' });
+    }
+    updated(changed) {
+        super.updated(changed);
+        if (changed.has('active')) {
+            this.sync();
+        }
+    }
+    render() {
+        return html `<slot @slotchange=${this.handleSlotChange}></slot>`;
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessSteps.prototype, "label", void 0);
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessSteps.prototype, "orientation", void 0);
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessSteps.prototype, "variant", void 0);
+HelixHeadlessSteps = __decorate([
+    customElement('helix-headless-steps')
+], HelixHeadlessSteps);
+export { HelixHeadlessSteps };

package/dist/steps/step/step.d.ts

@@ -0,0 +1,139 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import type { PropertyValues, TemplateResult } from 'lit';
+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.
+ */
+export declare class HelixHeadlessStep extends HelixElement {
+    /**
+     * Whether the reader has finished this stage.
+     */
+    complete: boolean;
+    /**
+     * Whether this is the stage the reader is in.
+     */
+    current: boolean;
+    /**
+     * Whether the reader may go to this stage.
+     */
+    disabled: boolean;
+    /**
+     * What this stage is called when it announces itself.
+     */
+    value: string;
+    /** Announces the step, unless it is refusing. */
+    select(): void;
+    /**
+     * 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.
+     */
+    protected renderMarker(): TemplateResult;
+    protected willUpdate(changed: PropertyValues): void;
+    /**
+     * 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.
+     */
+    protected renderLabel(): TemplateResult;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-step': HelixHeadlessStep;
+    }
+}