@fusion.dev/helix-headless 0.0.0-dev

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

@@ -0,0 +1,102 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+/**
+ * @summary One choice in a radio group.
+ *
+ * @description
+ * Renders a `<button role="radio">`, not an `<input type="radio">`, and the
+ * reason is the shadow boundary rather than preference: native radios group by
+ * sharing a `name` within a form, and a radio inside a shadow root cannot join
+ * a group on the other side of it. The group is the form control here, so the
+ * option only has to say what it is and announce when it is chosen.
+ *
+ * **It carries no label of its own.** A radio is named by the words beside it,
+ * which is its own content, and the label, hint and message of the *set* belong
+ * to the group. This is the one control in the family that takes nothing from
+ * `MixinField`, because a lone radio is not a control: it is an answer to one.
+ *
+ * Selection is announced rather than applied. The item dispatches, the group
+ * decides, and the group writes `selected` back. An item that set itself would
+ * be a second source of truth for which one is on.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category forms
+ * @aliases Option, Choice
+ * @documentation https://helix.fusion.dev/components/radio
+ *
+ * @slot - The words naming this choice.
+ * @slot icon - A mark shown beside them, or instead of them under
+ * `appearance="chip"`, where the words become the accessible name and the mark
+ * is what a reader picks between. Separate from the default slot because the
+ * chip has to hide one and show the other, and they are both in the same place
+ * otherwise.
+ *
+ * @event {HelixSelectEvent} helix-select - Fired when this choice is made. Cancelable: refusing it takes the decision and nothing moves.
+ *
+ * @csspart box - The circle.
+ * @csspart item - The button, which is the whole row.
+ * @csspart label - The words beside it.
+ * @csspart mark - The dot inside it.
+ */
+export declare class HelixHeadlessRadio extends HelixElement {
+    /**
+     * Whether this choice can be made.
+     */
+    disabled: boolean;
+    /**
+     * Whether the markup declared this one chosen, which is what a reset returns to.
+     *
+     * `<option selected>` reflects to `defaultSelected` and `option.selected` is
+     * live state that does not reflect, and those are two different facts. This
+     * element has one `selected` doing both jobs, so what is captured here is what
+     * the markup said at upgrade, before anything could overwrite it: read the
+     * attribute later and the listbox's own writes answer instead.
+     *
+     * **The deeper half is 302 and is not this.** State reflecting under the
+     * declaration's name is the fault `TreeItem` already avoids by mirroring to
+     * `data-selected`, and four families here still write `selected` back into a
+     * consumer's markup. Splitting them means moving what every stylesheet selects
+     * on, which is a change of its own rather than a property being added.
+     */
+    get defaultSelected(): boolean;
+    set defaultSelected(next: boolean);
+    /** What the markup said, read once at construction for the reason above. */
+    private seeded;
+    /**
+     * Whether this is the current choice.
+     *
+     * Written by the group.
+     */
+    selected: boolean;
+    /**
+     * Identifies this choice to the group, and is what the form submits.
+     */
+    value: string;
+    /** Moves focus to this choice, for the group's arrow keys. */
+    focusItem(): void;
+    /** Makes this choice and announces it. */
+    select(): void;
+    /**
+     * Mirrors the chosen state where a stylesheet can select on it.
+     *
+     * **A custom state and not the `selected` attribute it used to reflect.** The
+     * parent writes this: a listbox choosing a row, a tab strip moving the tab, a
+     * radio group answering for its set. Reflected, that put the element's own
+     * bookkeeping onto markup a consumer wrote and a consumer's server never sent,
+     * which React reconciles and reports as a mismatch, and which a serialized
+     * element pasted back declares as a choice nobody made. `ElementInternals`
+     * holds it instead, where it is not in the DOM at all.
+     *
+     * Reading `selected` is unaffected and so is writing it: the attribute still
+     * seeds the property, which is what `<helix-radio selected>` in a consumer's
+     * markup means. What stops is the write back. See 302 and 304.
+     */
+    protected willUpdate(changed: PropertyValues): void;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-radio': HelixHeadlessRadio;
+    }
+}

package/dist/radio/root/radio-root.js

@@ -0,0 +1,151 @@
+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 } from '@fusion.dev/helix-core';
+import { html } from 'lit';
+import { property } from 'lit/decorators.js';
+/**
+ * @summary One choice in a radio group.
+ *
+ * @description
+ * Renders a `<button role="radio">`, not an `<input type="radio">`, and the
+ * reason is the shadow boundary rather than preference: native radios group by
+ * sharing a `name` within a form, and a radio inside a shadow root cannot join
+ * a group on the other side of it. The group is the form control here, so the
+ * option only has to say what it is and announce when it is chosen.
+ *
+ * **It carries no label of its own.** A radio is named by the words beside it,
+ * which is its own content, and the label, hint and message of the *set* belong
+ * to the group. This is the one control in the family that takes nothing from
+ * `MixinField`, because a lone radio is not a control: it is an answer to one.
+ *
+ * Selection is announced rather than applied. The item dispatches, the group
+ * decides, and the group writes `selected` back. An item that set itself would
+ * be a second source of truth for which one is on.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category forms
+ * @aliases Option, Choice
+ * @documentation https://helix.fusion.dev/components/radio
+ *
+ * @slot - The words naming this choice.
+ * @slot icon - A mark shown beside them, or instead of them under
+ * `appearance="chip"`, where the words become the accessible name and the mark
+ * is what a reader picks between. Separate from the default slot because the
+ * chip has to hide one and show the other, and they are both in the same place
+ * otherwise.
+ *
+ * @event {HelixSelectEvent} helix-select - Fired when this choice is made. Cancelable: refusing it takes the decision and nothing moves.
+ *
+ * @csspart box - The circle.
+ * @csspart item - The button, which is the whole row.
+ * @csspart label - The words beside it.
+ * @csspart mark - The dot inside it.
+ */
+let HelixHeadlessRadio = class HelixHeadlessRadio extends HelixElement {
+    constructor() {
+        super(...arguments);
+        /**
+         * Whether this choice can be made.
+         */
+        this.disabled = false;
+        /** What the markup said, read once at construction for the reason above. */
+        this.seeded = this.hasAttribute('selected');
+        /**
+         * Whether this is the current choice.
+         *
+         * Written by the group.
+         */
+        this.selected = false;
+        /**
+         * Identifies this choice to the group, and is what the form submits.
+         */
+        this.value = '';
+    }
+    /**
+     * Whether the markup declared this one chosen, which is what a reset returns to.
+     *
+     * `<option selected>` reflects to `defaultSelected` and `option.selected` is
+     * live state that does not reflect, and those are two different facts. This
+     * element has one `selected` doing both jobs, so what is captured here is what
+     * the markup said at upgrade, before anything could overwrite it: read the
+     * attribute later and the listbox's own writes answer instead.
+     *
+     * **The deeper half is 302 and is not this.** State reflecting under the
+     * declaration's name is the fault `TreeItem` already avoids by mirroring to
+     * `data-selected`, and four families here still write `selected` back into a
+     * consumer's markup. Splitting them means moving what every stylesheet selects
+     * on, which is a change of its own rather than a property being added.
+     */
+    get defaultSelected() {
+        return this.seeded;
+    }
+    set defaultSelected(next) {
+        this.seeded = next;
+    }
+    /** Moves focus to this choice, for the group's arrow keys. */
+    focusItem() {
+        this.renderRoot.querySelector('[part="item"]')?.focus();
+    }
+    /** Makes this choice and announces it. */
+    select() {
+        if (this.disabled) {
+            return;
+        }
+        this.dispatchEvent(new HelixSelectEvent({ value: this.value }));
+    }
+    /**
+     * Mirrors the chosen state where a stylesheet can select on it.
+     *
+     * **A custom state and not the `selected` attribute it used to reflect.** The
+     * parent writes this: a listbox choosing a row, a tab strip moving the tab, a
+     * radio group answering for its set. Reflected, that put the element's own
+     * bookkeeping onto markup a consumer wrote and a consumer's server never sent,
+     * which React reconciles and reports as a mismatch, and which a serialized
+     * element pasted back declares as a choice nobody made. `ElementInternals`
+     * holds it instead, where it is not in the DOM at all.
+     *
+     * Reading `selected` is unaffected and so is writing it: the attribute still
+     * seeds the property, which is what `<helix-radio selected>` in a consumer's
+     * markup means. What stops is the write back. See 302 and 304.
+     */
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        this.toggleState('selected', this.selected);
+    }
+    render() {
+        /* Roving `tabindex`: one stop for the whole set, which is what a radio
+           group is in the tab order, and the arrow keys move within it. The group
+           owns the keys, because moving between items is a fact about the set. */
+        return html `<button
+      part="item"
+      type="button"
+      role="radio"
+      aria-checked=${this.selected ? 'true' : 'false'}
+      ?disabled=${this.disabled}
+      tabindex=${this.selected ? '0' : '-1'}
+      @click=${() => this.select()}
+    >
+      <span part="box"><span part="mark" aria-hidden="true"></span></span>
+      <slot name="icon"></slot>
+      <span part="label"><slot></slot></span>
+    </button>`;
+    }
+};
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessRadio.prototype, "disabled", void 0);
+__decorate([
+    property({ type: Boolean })
+], HelixHeadlessRadio.prototype, "selected", void 0);
+__decorate([
+    property()
+], HelixHeadlessRadio.prototype, "value", void 0);
+HelixHeadlessRadio = __decorate([
+    customElement('helix-headless-radio')
+], HelixHeadlessRadio);
+export { HelixHeadlessRadio };

package/dist/rating/index.d.ts

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

package/dist/rating/index.js

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

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

@@ -0,0 +1,242 @@
+import { HelixFormElement, KeyboardNavigationController } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+declare const HelixHeadlessRating_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
+/**
+ * @summary A score out of a few marks, given or shown.
+ *
+ * @description
+ * **Half marks decide the shape, so they are decided first.** Supporting them
+ * means the value is not an integer and the targets are not the marks: five
+ * stars at a half step is ten places to press, and a mark that is filled to the
+ * middle. Everything else follows from that, which is why `step` is here rather
+ * than added later, when the pointer handling would have to be rewritten around
+ * it.
+ *
+ * **A partial mark is the whole mark, clipped.** Not a second glyph filled to
+ * the middle: that needs a matching pair drawn for every mark anybody uses, and
+ * the moment a consumer wants a heart or a circle they need to draw one too. The
+ * fill is the same marks over the same marks, cut off partway, so any mark works
+ * and any fraction does.
+ *
+ * **Read-only is not this control greyed out, it is a different thing.** The
+ * commoner use is showing a score nobody is being asked for, a product's
+ * average, and that is not a control at all: it takes no focus, answers no keys,
+ * has no options to choose between, and reads as one thing rather than as five.
+ * So `readonly` is `role="img"` with the score in its name, where the control is
+ * a radio group. A disabled control is still a control and still says so; this
+ * is not one.
+ *
+ * **Moving is choosing here**, which is the radio group's reading and the
+ * opposite of `Menu`'s: arriving at four stars *is* rating it four, because
+ * nothing else follows and there is nothing to confirm. That is what
+ * `KeyboardNavigationController` takes `selects` for, and why this can use it
+ * where a menu cannot.
+ *
+ * **The mark is a stylesheet's, not a slot's.** A slot projects its content
+ * once, and there are two layers of marks here: slotting a star would put it in
+ * the track or the fill and leave the other empty. So the mark is a shape the
+ * styled tier masks with, which is also what lets a partial one be a clip of the
+ * whole rather than a second drawing of it.
+ *
+ * The properties below are written by this component and read by whoever draws
+ * it. A consumer sets none of them: they carry a number this element computed
+ * and CSS cannot, which is what lets a stylesheet on this tier draw the thing
+ * without measuring anything itself.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category forms
+ * @aliases Stars, Score, Review score
+ * @documentation https://helix.fusion.dev/components/rating
+ *
+ * @event {Event} change - Announced with it, the choice being the commit.
+ * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the score changes, and cancelable.
+ * @event {Event} input - Announced once the value has moved.
+ *
+ * @csspart feedback - What is wrong with it.
+ * @csspart fill - The filled marks, clipped to the score.
+ * @csspart hint - Help under the marks, while nothing is wrong.
+ * @csspart label - The question, over the marks.
+ * @csspart mark - One mark, in either layer.
+ * @csspart marks - The row of marks.
+ * @csspart option - One place a reader can press, which is one step.
+ * @csspart track - The unfilled marks.
+ * @csspart value - The score written out, under `show-value`.
+ *
+ * @cssproperty --rating-full - How many marks are wholly filled.
+ * @cssproperty --rating-part - How much of the next mark is filled, 0 to 1.
+ * @cssproperty --rating-step - The width of one step, as a fraction of a mark.
+ * @cssproperty --rating-steps - How many steps one mark is divided into.
+ */
+export declare class HelixHeadlessRating extends HelixHeadlessRating_base {
+    protected readonly announcesInput = false;
+    /**
+     * How many marks there are.
+     */
+    max: number;
+    /**
+     * The lowest score a reader can give, which is what clearing returns to.
+     *
+     * Zero rather than one, because "no rating" and "the worst rating" are
+     * different answers and a control that cannot express the first has to
+     * pretend the second. A survey that requires an answer says so with
+     * `required`, not by making one unreachable.
+     */
+    min: number;
+    /**
+     * The smallest part of a mark that can be chosen.
+     *
+     * `0.5` is the half star, and it is the reason the value is a number rather
+     * than an index: with halves, five marks are ten answers.
+     */
+    step: number;
+    /**
+     * Whether this shows a score rather than asks for one.
+     *
+     * A readout is not a control that has been switched off. It takes no focus,
+     * answers no keys, and reads as one thing: see the note on the class.
+     */
+    readOnly: boolean;
+    /**
+     * How the score is read out, where "3.5 out of 5" is not what it should say.
+     *
+     * A rating out of five is one of the few places a screen reader gets a worse
+     * answer from the value than from a sentence: "3.5" alone is a number without
+     * a subject. This names the readout, where a control is named by its `label`
+     * and each of its options by the score that option is.
+     */
+    valueText: string;
+    /**
+     * Whether the score is written out beside the marks.
+     *
+     * Marks say roughly, and a number says exactly. Four and a bit stars is not a
+     * reading anyone can repeat, which is why a product's average is nearly always
+     * printed next to them. `Meter` spells its reading the same way and under the
+     * same attribute.
+     *
+     * It follows the pointer, because it labels what the marks are showing rather
+     * than what the form holds: a label that disagreed with the marks under the
+     * reader's own cursor would be worse than no label.
+     */
+    showValue: boolean;
+    /**
+     * The shape a consumer slotted, if they slotted one.
+     *
+     * Read rather than projected. A `<slot>` shows its content once and a rating
+     * needs the shape as many times as there are marks, twice over because there
+     * are two layers, so the slot here is a way of being handed the shape rather
+     * than a place the shape is drawn. What is handed over gets cloned into every
+     * position.
+     *
+     * **One shape, not one per position.** A rating is a quantity of identical
+     * marks and the fill is a clip across all of them, so a row whose third mark
+     * is a different drawing from its first is not a rating: it is a set of
+     * choices, which is `Radio.Group` and already carries a value and a name on
+     * each of its own options. Anything past the first slotted element is
+     * ignored.
+     */
+    private markSource;
+    /**
+     * What the pointer is over, which is shown instead of the score while it is.
+     */
+    private previewing;
+    protected readonly keys: KeyboardNavigationController;
+    /** The score, as a number, clamped to what the marks can show. */
+    get score(): number;
+    /** Every score a reader can choose, which is `max / step` of them. */
+    private get steps();
+    /**
+     * The options, as the shared controller wants them.
+     *
+     * Adapters rather than elements, because these are buttons this element drew
+     * rather than a consumer's custom elements: the interface asks for five
+     * things and a `<button>` in a shadow root can answer all five without being
+     * dressed up as a component to do it.
+     */
+    private get options();
+    /** The pointer drawing a score, while one is. */
+    private dragging;
+    /**
+     * One clone per place a mark goes, kept so a render does not remake them.
+     *
+     * A drag renders on every pointer move, and handing Lit a fresh node each
+     * time would swap every mark in the row on every frame of a gesture whose
+     * whole point is that only the fill moves.
+     */
+    private readonly clones;
+    /** The shape for one place, or nothing when the stylesheet is drawing it. */
+    private markFor;
+    private readonly handleMarkSlot;
+    /**
+     * The step under a point on the row, or the nearest one to it.
+     *
+     * Asked of the boxes rather than worked out from `max` and `step`, because
+     * where a step sits is the stylesheet's arithmetic and this would be a second
+     * copy of it that could disagree. The browser has already laid the targets
+     * out; this reads them back.
+     *
+     * Nearest rather than only a hit, so a drag that runs off the end of the row
+     * pins to the last mark instead of stopping at whatever it last touched, and
+     * a pointer in the half-gap outside the first mark still answers.
+     */
+    private scoreAt;
+    /**
+     * Dragging across the marks draws a score, and letting go chooses it.
+     *
+     * One press and a slide is how a rating is given on a phone, and on a desktop
+     * it is how somebody who overshoots corrects without lifting. Pointer capture
+     * is what makes it one gesture: without it the events go to whichever target
+     * the pointer crossed into, and a drag that leaves the row stops reporting.
+     *
+     * Nothing is chosen until release, so a drag that ends back where it started,
+     * or off the element entirely, has asked for nothing.
+     */
+    private readonly handleDragStart;
+    private readonly handleDragMove;
+    private readonly handleDragEnd;
+    private readonly handleDragCancel;
+    /**
+     * Reports the value, and whether the form may go without one.
+     *
+     * **`required` was on the API page and did nothing.** The mixin brings it,
+     * so it printed on the reference page and read as supported, and nothing here
+     * ever called `setValidity`: a form holding an unrated required rating
+     * submitted, measured, with `:valid` true and the entry present but empty.
+     * This is the case `min` argues for in its own note, that "no rating" and
+     * "the worst rating" are different answers and a survey that requires one
+     * says so with `required`.
+     *
+     * **Empty is `value === ''` rather than a score of zero**, because zero is a
+     * rating a reader can deliberately give when `min` allows it, and refusing to
+     * submit it would be the control disagreeing with the property that permits
+     * it. What `required` asks is whether they answered at all.
+     *
+     * `Slider` is deliberately not given the same treatment: a native
+     * `<input type="range" required>` is always valid, because a range always
+     * holds a number, and matching the platform there is the point.
+     */
+    private sync;
+    private readonly handleOptionClick;
+    private readonly handleOptionEnter;
+    private readonly handleLeave;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected updated(changed: PropertyValues): void;
+    protected firstUpdated(changed: PropertyValues): void;
+    protected render(): TemplateResult;
+    /**
+     * The value as a number, or `NaN` while the control is empty.
+     *
+     * `NaN` and not zero, which is the trap the platform already avoids: `Number('')`
+     * is zero, so an empty control would report a number it does not hold and a
+     * form would submit it.
+     */
+    get valueAsNumber(): number;
+    set valueAsNumber(count: number);
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-rating': HelixHeadlessRating;
+    }
+}
+export {};