@fusion.dev/helix-headless 0.0.0-dev

package/dist/input/root/input-root.js

@@ -0,0 +1,472 @@
+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, drawIcon, HelixFormElement, holdCaret, MixinControllerValue, MixinField, restoreValue, } from '@fusion.dev/helix-core';
+import { eye, eyeSlash, x } from '@fusion.dev/helix-icons';
+import { html, nothing } from 'lit';
+import { property, state } from 'lit/decorators.js';
+/**
+ * @summary A single line of text a reader types into.
+ *
+ * @description
+ * Renders a real `<input>`, so the caret, selection, autofill, spellcheck, the
+ * password manager, and the on-screen keyboard a phone chooses all come from the
+ * platform. `delegatesFocus` puts focus on it, and it serializes into the
+ * server's markup, so the field is usable before any script loads.
+ *
+ * **The input inside a shadow root submits nothing**, because the form is on the
+ * other side of the boundary. The host is form-associated instead and reports
+ * its own value through `ElementInternals`, which is also what carries validity
+ * and what answers a form reset.
+ *
+ * `value` and `defaultValue` are separate for the reason `checked` and
+ * `defaultChecked` are: `value` is what is in the field now and
+ * `defaultValue` is what the markup asked for, which is where a reset returns
+ * to and is gone the moment anyone types.
+ *
+ * **Validity is the platform's.** The `type` and `required` are set on the real
+ * input and its `validity` is copied onto the host, so an email field rejects
+ * what the browser says is not an email rather than what a regular expression
+ * here guesses. What this adds is the anchor, so `reportValidity` points the
+ * bubble at the input rather than at the host.
+ *
+ * `pattern`, `minlength` and `maxlength` are forwarded with them. They were
+ * promised by this paragraph and did not exist, so a consumer following the
+ * sentence wrote an attribute on the host that reached no input and constrained
+ * nothing: the field looked as though it were checked and was not.
+ *
+ * **`clearable` and `reveal` are the field's, not the consumer's.** The `end`
+ * slot used to be the answer to both, which meant every consumer of
+ * `type="search"` built the same button and every consumer of
+ * `type="password"` either built the same toggle or shipped a field a reader
+ * cannot check what they typed into. Neither is a slot's worth of variation:
+ * one empties the value, the other flips the type, and both want the same
+ * position, the same size and the same disabled behavior. The slot stays for
+ * what actually varies, a unit or a prefix.
+ *
+ * Both opt in rather than following from `type`, and are booleans that default
+ * to false. A Lit boolean property that defaults to *true* cannot be turned off
+ * from HTML at all, only from script, which is the wrong way round for
+ * revealing a password: a consumer should have to ask for it. Drawer's `modal`
+ * defaults true for the opposite reason, that losing a focus trap by forgetting
+ * a word is worse than having to say so.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category forms
+ * @aliases TextField, Field, TextInput
+ * @documentation https://helix.fusion.dev/components/input
+ *
+ * @slot end - After the text, for an icon or a unit.
+ * @slot start - Before the text, for an icon or a prefix.
+ *
+ * @event {Event} change - Relayed from the input once the reader has finished.
+ * @event {HelixBeforeChangeEvent} helix-before-change - Fired as the text changes, and cancelable.
+ * @event {Event} input - Announced once the value has moved.
+ *
+ * @csspart clear - The button that empties the field.
+ * @csspart control - The input itself.
+ * @csspart feedback - What is wrong with it.
+ * @csspart field - The box holding everything.
+ * @csspart hint - Help under the field, while nothing is wrong.
+ * @csspart icon - A glyph this component draws.
+ * @csspart label - The question, over the field.
+ * @csspart reveal - The button that shows and hides a password.
+ */
+let HelixHeadlessInput = class HelixHeadlessInput extends MixinControllerValue(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,
+        });
+        /** Typed or dragged, so every edit is announced. See `announcesInput`. */
+        this.announcesInput = true;
+        /**
+         * What the browser may autofill here, as one of the platform's own tokens.
+         *
+         * Empty leaves the attribute off, which is the browser's default. Set it to
+         * a token like `email` or `bday` to ask for autofill, or to `off` to refuse.
+         */
+        this.autocomplete = '';
+        /**
+         * Shown while the field is empty.
+         *
+         * Not a label: it goes when typing starts.
+         */
+        this.placeholder = '';
+        /**
+         * Whether the field refuses input while still submitting its value.
+         *
+         * **`readonly`, which is the platform's spelling, and it was `read-only`
+         * until 28 Aug 2026.** A camelCase property needs an explicit `attribute`
+         * and the library had been answering that question two ways: thirteen
+         * attributes kept the name HTML uses (`crossorigin`, `maxlength`,
+         * `formnovalidate`, `dirname` and the rest) and five dash-cased a word the
+         * platform writes as one. `readonly` was the only one on both lists, this
+         * spelling on `Rating` and `read-only` on the eight other fields, so one
+         * library shipped both and each was inert on the other's families.
+         *
+         * The cost of the dash-cased form is the one this repository keeps writing
+         * down about attributes: nothing warns. `<helix-input readonly>` is what
+         * anybody who has written HTML types, it parsed to no property at all, and
+         * the field stayed editable with no error anywhere. Measured before the
+         * rename: `readOnly` came back `false`.
+         *
+         * Taken now for the reason [#213](../../../../../docs/19-queue.md) gives
+         * about the part it renamed for the same kind of reason: there is no
+         * `helix-v` tag, so no consumer is holding the old spelling, and this is free
+         * today and a deprecation after the first release.
+         * `check:attribute-names` holds it from here.
+         */
+        this.readOnly = false;
+        /**
+         * What the field accepts, which decides the keyboard and the validation.
+         *
+         * **Not reflected**, and it was. Reflection exists so a selector can reach a
+         * value, and no stylesheet in this repository selects on `type`: what it did
+         * instead was write `type="text"` onto every `<helix-input>` ever rendered,
+         * an attribute no consumer's markup had. That is precisely the fault `Button`
+         * had with `href`, `target` and `rel`, written up in the area rules as the
+         * reason the rule exists, and this was the last property in the library still
+         * doing it. Audited: ten reflected attributes have no selector anywhere, and
+         * this is the only one of them with a value that puts itself on the host.
+         *
+         * Nothing reads it from the attribute either. The real `<input>` inside takes
+         * it as a property binding, which is what makes the keyboard and the
+         * validation follow.
+         */
+        this.type = 'text';
+        /**
+         * Whether the field offers a button that empties it.
+         *
+         * Shown only while there is something to clear, because a control that does
+         * nothing is worse than no control: a reader who presses it and sees no
+         * change has to work out whether the field was already empty or the button
+         * is broken.
+         */
+        this.clearable = false;
+        /**
+         * What the clear button is called, since an icon has no name of its own.
+         */
+        this.clearLabel = 'Clear';
+        /**
+         * Whether a password field offers a toggle that shows what was typed.
+         *
+         * Ignored on every other type. A reveal on an email field would be a button
+         * that does nothing visible, and guarding it here rather than asking the
+         * consumer not to means the property can be set once on a component that
+         * changes type.
+         */
+        this.reveal = false;
+        /**
+         * What the reveal toggle is called.
+         *
+         * The state is `aria-pressed`, not this.
+         */
+        this.revealLabel = 'Show password';
+        /**
+         * Whether the password is currently showing.
+         *
+         * State rather than a property: it is a reader's momentary choice about what
+         * is on their own screen, it must not survive anything, and a consumer that
+         * could set it could reveal a password without the reader asking.
+         */
+        this.revealed = false;
+        /**
+         * Every keystroke, cancelable, and put back where it is refused.
+         *
+         * The input has already taken the character by the time this runs, so a
+         * consumer that refuses the change has to see the field returned to what the
+         * element still holds. Otherwise the text on screen and the value the form
+         * would submit disagree, which is the one thing a controlled field must never
+         * do.
+         */
+        this.handleInput = (event) => {
+            /* **Stopped, because the control inside this one is not a control a consumer
+               has.** `input` is composed by specification, so the native event from the
+               `<input>` in this shadow root crosses the boundary and reaches the host
+               beside the one the mixin announces: measured in Chrome 148, one keystroke
+               produced `helix-before-change`, this element's own `input`, and the inner
+               control's, so `onInput` ran twice and one of the two carried the value
+               from before the change. `handleChange` two methods down has always done
+               this; the pair was half applied. */
+            event.stopPropagation();
+            const control = event.target;
+            const next = control.value;
+            /* Through the mixin, which announces and then applies only if the value is
+               the element's to move. The native control has already changed either way,
+               so wherever the answer does not follow it has to be put back: that is a
+               refusal, and it is equally a consumer who owns the value and has not
+               given a new one yet. Both are "what is on screen is not the answer". */
+            this.requestValue(next);
+            restoreValue(control, this.value);
+        };
+        /**
+         * Empties the field and gives the caret back.
+         *
+         * Focus returns to the input rather than staying on the button, which is
+         * about to disappear: a reader who cleared a field is going to type in it,
+         * and focus resting on a control that is being removed lands on the body.
+         *
+         * Through `requestValue` like every other change, so a consumer who owns the
+         * value hears about it and decides, and a canceled clear leaves the text
+         * where it was.
+         */
+        this.handleClear = () => {
+            this.requestValue('');
+            const control = this.control;
+            if (control) {
+                restoreValue(control, this.value);
+                control.focus();
+            }
+        };
+        /** Relayed, because `change` does not cross a shadow boundary on its own. */
+        this.handleChange = (event) => {
+            event.stopPropagation();
+            this.dispatchEvent(new Event('change', { bubbles: true, composed: false }));
+        };
+        /**
+         * A regular expression the value has to match, as the platform reads it.
+         *
+         * The class documentation promised `pattern` and `minlength` "and the rest"
+         * were set on the real input, and no such properties existed: a consumer
+         * following that sentence wrote an attribute on the host, it reached no input,
+         * and the field constrained nothing while looking as though it did.
+         *
+         * Forwarded rather than checked here, which is the whole reason validity is
+         * the platform's: the browser knows what a `pattern` means, anchors it at both
+         * ends, and produces the message in the reader's own language.
+         */
+        this.pattern = '';
+    }
+    /**
+     * The type the real input is given, which is not always the type asked for.
+     *
+     * A revealed password is a text field for exactly as long as the reader is
+     * looking at it. Reading through a getter rather than mutating `type` keeps
+     * the property the consumer's: what they set is what they get back, whatever
+     * the button is doing.
+     */
+    get effectiveType() {
+        return this.revealed && this.type === 'password' ? 'text' : this.type;
+    }
+    /** Whether there is a clear button on screen right now. */
+    get showsClear() {
+        return this.clearable && this.value !== '' && !this.isDisabled && !this.readOnly;
+    }
+    /** Focus is delegated to the input, so the host is never the focus target. */
+    static { this.shadowRootOptions = {
+        ...HelixFormElement.shadowRootOptions,
+        delegatesFocus: true,
+    }; }
+    /**
+     * The caret and the selection, under the platform's own names.
+     *
+     * The `<input>` is inside this shadow root, so a consumer had no way to ask
+     * where the selection is, let alone move it: `querySelector` does not cross
+     * the boundary. An insert-at-cursor toolbar, a format button, a mask that
+     * repositions the caret after rewriting the value, all of them need this and
+     * none of them could be written. Textarea gained the same surface for the same
+     * reason. See 295.
+     *
+     * Zero before there is a control, which is where an empty field's caret would
+     * be anyway.
+     */
+    get selectionDirection() {
+        return this.control?.selectionDirection ?? 'none';
+    }
+    set selectionDirection(direction) {
+        const control = this.control;
+        if (control) {
+            control.selectionDirection = direction;
+        }
+    }
+    /** Where the selection ends, as an offset into the value. */
+    get selectionEnd() {
+        return this.control?.selectionEnd ?? 0;
+    }
+    set selectionEnd(at) {
+        const control = this.control;
+        if (control) {
+            control.selectionEnd = at;
+        }
+    }
+    /** Where the selection starts, as an offset into the value. */
+    get selectionStart() {
+        return this.control?.selectionStart ?? 0;
+    }
+    set selectionStart(at) {
+        const control = this.control;
+        if (control) {
+            control.selectionStart = at;
+        }
+    }
+    /**
+     * Selects a range, which is the one operation the three accessors above
+     * cannot express between them.
+     *
+     * Setting `selectionStart` past the current `selectionEnd` drags the end
+     * along, so the two writes a consumer would make in sequence do not compose
+     * into the range they asked for. The platform has this method for that reason
+     * and so does this.
+     */
+    setSelectionRange(start, end, direction) {
+        this.control?.setSelectionRange(start, end, direction);
+    }
+    get control() {
+        return this.renderRoot.querySelector('[part="control"]');
+    }
+    /** Reports the value and the validity the host stands behind. */
+    sync() {
+        this.internals.setFormValue(this.value);
+        const control = this.control;
+        if (!control) {
+            return;
+        }
+        /* The input's own verdict, copied over rather than recomputed. It knows
+           what an email is and what `pattern` means, and it knows it the same way
+           the browser will when the form is submitted. The anchor is what this adds:
+           without it the validity bubble points at the host, which is a box with no
+           text in it. */
+        this.internals.setValidity(control.validity, control.validationMessage, control);
+        // Straight after, because validity moved without any property moving.
+        this.refreshFeedback();
+    }
+    /** Puts the caret in the field, the way a label pointing at one would. */
+    focus(options) {
+        this.control?.focus(options);
+    }
+    /** Selects everything in the field. */
+    select() {
+        this.control?.select();
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        /* Never before the first update, which is the one the server does: there is
+           no render root to query there, and `querySelector` is not merely empty on
+           Lit's element shim, it is undefined. There is also no caret to keep before
+           anything has rendered. */
+        if (!this.hasUpdated) {
+            return;
+        }
+        const control = this.control;
+        if (changed.has('value') && control && this.shadowRoot?.activeElement === control) {
+            this.releaseCaret = holdCaret(control);
+        }
+    }
+    updated(changed) {
+        super.updated(changed);
+        this.releaseCaret?.();
+        this.releaseCaret = undefined;
+        this.sync();
+    }
+    render() {
+        /* Label, field, and one line under it.
+           The hint and the feedback share that line rather than stacking, so a
+           field is the same height either way and nothing below it moves when the
+           message changes. */
+        return html `${this.renderLabel()}
+    <div part="field">
+      <slot name="start"></slot>
+      <input
+        part="control"
+        id="control"
+        .value=${this.value}
+        type=${this.effectiveType}
+        name=${this.name || nothing}
+        placeholder=${this.placeholder || nothing}
+        autocomplete=${this.autocomplete || nothing}
+        pattern=${this.pattern || nothing}
+        minlength=${this.minLength ?? nothing}
+        maxlength=${this.maxLength ?? nothing}
+        aria-describedby=${this.describedBy ?? nothing}
+        ?disabled=${this.isDisabled}
+        ?readonly=${this.readOnly}
+        ?required=${this.required}
+        @input=${this.handleInput}
+        @change=${this.handleChange}
+      />
+      <slot name="end"></slot>
+      <!-- In the tab order, unlike the browser's own search clear, which is not
+           reachable by keyboard at all. That is defensible for a native control
+           a reader can empty with select-all and Delete, and less so for one
+           whose only affordance is an icon: a control that exists on screen and
+           cannot be reached is one a keyboard reader is told about and cannot
+           use. It only exists while there is a value, so the extra stop appears
+           exactly when there is something to do with it. -->
+      ${this.showsClear
+            ? html `<button
+              part="clear"
+              type="button"
+              aria-label=${this.clearLabel}
+              @click=${this.handleClear}
+            >
+              ${drawIcon(x)}
+            </button>`
+            : nothing}
+      ${this.reveal && this.type === 'password'
+            ? html `<button
+              part="reveal"
+              type="button"
+              aria-label=${this.revealLabel}
+              aria-pressed=${this.revealed ? 'true' : 'false'}
+              ?disabled=${this.isDisabled}
+              @click=${() => {
+                this.revealed = !this.revealed;
+            }}
+            >
+              ${drawIcon(this.revealed ? eyeSlash : eye)}
+            </button>`
+            : nothing}
+    </div>
+    ${this.renderHint()}${this.renderFeedback()}`;
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessInput.prototype, "autocomplete", void 0);
+__decorate([
+    property()
+], HelixHeadlessInput.prototype, "placeholder", void 0);
+__decorate([
+    property({ attribute: 'readonly', reflect: true, type: Boolean })
+], HelixHeadlessInput.prototype, "readOnly", void 0);
+__decorate([
+    property()
+], HelixHeadlessInput.prototype, "type", void 0);
+__decorate([
+    property({ type: Boolean })
+], HelixHeadlessInput.prototype, "clearable", void 0);
+__decorate([
+    property({ attribute: 'clear-label' })
+], HelixHeadlessInput.prototype, "clearLabel", void 0);
+__decorate([
+    property({ type: Boolean })
+], HelixHeadlessInput.prototype, "reveal", void 0);
+__decorate([
+    property({ attribute: 'reveal-label' })
+], HelixHeadlessInput.prototype, "revealLabel", void 0);
+__decorate([
+    state()
+], HelixHeadlessInput.prototype, "revealed", void 0);
+__decorate([
+    property()
+], HelixHeadlessInput.prototype, "pattern", void 0);
+__decorate([
+    property({ attribute: 'minlength', type: Number })
+], HelixHeadlessInput.prototype, "minLength", void 0);
+__decorate([
+    property({ attribute: 'maxlength', type: Number })
+], HelixHeadlessInput.prototype, "maxLength", void 0);
+HelixHeadlessInput = __decorate([
+    customElement('helix-headless-input')
+], HelixHeadlessInput);
+export { HelixHeadlessInput };

package/dist/kbd/index.d.ts

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

package/dist/kbd/index.js

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

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

@@ -0,0 +1,98 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type TemplateResult } from 'lit';
+/**
+ * @summary A keyboard key or chord, set inline with text.
+ *
+ * @description
+ * Renders a real `<kbd>`, so the passage still means "press this" to anything
+ * reading the markup rather than only to a reader looking at it.
+ *
+ * **One key per element, with `keys` as the stated exception.** A *sequence* is
+ * several of these with the separator written between them as ordinary text,
+ * because that separator is prose: it is "then" in a sequence and "plus" in a
+ * simultaneous press, and a component that inserted one would have to guess
+ * which. `keys` cannot be guessing, since a chord written `mod+k` has said
+ * which it is.
+ *
+ * **`keys` exists because the glyphs were being typed by hand and were wrong.**
+ * A literal `⌘K` in a template tells a reader on Windows to press a key their
+ * keyboard does not have, and nothing catches it, a string being a string.
+ * Given `mod` this renders `⌘K` on Apple and `Ctrl+K` everywhere else.
+ *
+ * **`within` is what binds it, and it is absent by default.** Without it this
+ * draws a key and listens for nothing, which is what every existing use of this
+ * component wants. The two values are the two honest lifetimes:
+ *
+ * - `control` listens within the element's own parent, which is the case this
+ *   is mostly for: a hint sitting inside the control it belongs to, where the
+ *   shortcut should work while that control has focus and stop existing when
+ *   the control does.
+ * - `document` listens on the document, for a chord that works from anywhere.
+ *
+ * *Corrected 25 Aug 2026: this said `scope`, `self` and `global` until then,
+ * naming a property that has never existed under that name. The rename is
+ * explained on the property itself, twenty lines below, and this paragraph
+ * above it went on teaching the old one. A reader who trusted the class doc
+ * wrote an attribute that binds nothing, which is also what an unset `within`
+ * does, so nothing about the mistake looked like one.*
+ *
+ * **A hidden `kbd` is a dead shortcut, and that is the point rather than a
+ * trap.** Binding here ties the key to its own advertisement, so a hint that is
+ * not rendered is a shortcut that is not offered. A chord that must outlive its
+ * label is a chord whose owner is not a label: give it to whatever owns the
+ * action and let this element only describe it.
+ *
+ * Nothing binds until this upgrades, so a shortcut is not available in the
+ * moments before hydration.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category typography
+ * @aliases Key, Shortcut, Hotkey
+ * @documentation https://helix.fusion.dev/components/kbd
+ *
+ * @slot - The key's label, where `keys` is not set.
+ *
+ * @event {HelixShortcutEvent} helix-shortcut - Fired when the chord is pressed, and cancelable.
+ *
+ * @csspart kbd - The key.
+ */
+export declare class HelixHeadlessKbd extends HelixElement {
+    /**
+     * The chord, written plainly: `mod+k`, `shift+?`, `/`.
+     *
+     * `mod` is the platform's own command modifier, which is the reason to write
+     * a chord here rather than a glyph: it is the one token whose right answer
+     * differs per reader.
+     */
+    keys: string;
+    /**
+     * Where the chord is listened for, and whether it is listened for at all.
+     *
+     * Unset draws a key and binds nothing.
+     *
+     * **Named `within` because `scope` is taken.** `scope` is a real HTML
+     * attribute belonging to `<th>`, so putting one on anything else is both a
+     * lint failure and a word in the DOM that already means something narrower.
+     * `within` says the same thing and says it about this element.
+     */
+    within?: 'control' | 'document';
+    /** The element the listener is on, kept so it can be taken off the same one. */
+    private listening;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected updated(changed: Map<string, unknown>): void;
+    /** The chord as this reader's keyboard labels it. */
+    private get label();
+    private listen;
+    private deafen;
+    private readonly handleKeydown;
+    /** Whether a press is this chord, modifiers and all. */
+    private matches_;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-kbd': HelixHeadlessKbd;
+    }
+}