@fusion.dev/helix-core 0.182.1 → 0.183.0

package/dist/helix-form-element/helix-form-element-base.d.ts

@@ -0,0 +1,264 @@
+import type { PropertyValues } from 'lit';
+import { HelixElement } from '../helix-element/helix-element.js';
+/**
+ * @summary Base for a form element that reports no validity of its own, as a native button does.
+ *
+ * @description
+ * `HelixFormElementBase` carries form ownership, `disabled` and the fieldset
+ * that disables it, `name`, focus, and the validity API with a custom message
+ * as its only verdict. `HelixFormElement` extends it with what a control that
+ * judges its own value needs: the wrapped `setValidity`, `feedback` from a
+ * field, and the `input` and `change` announcements.
+ *
+ * **Two classes, because a button pays for the half it never calls.** Button
+ * reports nothing through `setValidity` and holds no value, so a message from
+ * `setCustomValidity` is the whole of its verdict, the same as on a native
+ * `<button>`. Measured on the styled Button bundled alone, October 7, 2026:
+ * the validating half was 347 of its 12,973 bytes brotli.
+ *
+ * A family extends this one only where it never calls
+ * `internals.setValidity` and takes no `MixinField`. Every other control
+ * extends `HelixFormElement`.
+ *
+ * @since 0.176.0
+ * @status experimental
+ * @documentation https://fusion.dev/helix/docs/tiers
+ */
+export declare class HelixFormElementBase extends HelixElement {
+    /** Opts the element into form ownership, labels, and submission. */
+    static readonly formAssociated = true;
+    /**
+     * Whether the control is disabled and cannot be used.
+     *
+     * Reflected, because the styled tier selects on it, and mirrored to
+     * `aria-disabled` rather than removing the element from the accessibility
+     * tree, so a screen reader can still announce that the control exists.
+     *
+     * The mirror itself is in `willUpdate` below, here rather than in each
+     * control, because here is where `disabled` is.
+     */
+    disabled: boolean;
+    /**
+     * Whether an ancestor `<fieldset disabled>` has switched this control off.
+     *
+     * The platform tells a form-associated element through `formDisabledCallback`
+     * and nothing else does, so without this a control inside a disabled fieldset
+     * stays fully typeable and announces itself as enabled.
+     *
+     * The submission half is already the platform's: measured, the fieldset's
+     * controls are absent from the form's entry list and the host matches
+     * `:disabled`, so the value never goes anywhere. What is missing without this
+     * is everything a reader can see or touch.
+     *
+     * State rather than the `disabled` property. Writing that would reflect an
+     * attribute the consumer's server markup does not have, which React reports
+     * on hydration and does not patch up, and it would also silently overwrite
+     * what the consumer set.
+     */
+    protected formDisabled: boolean;
+    /**
+     * Whether the control is off, by its own attribute or by an ancestor.
+     *
+     * What a component should bind to rather than `disabled`, which is only the
+     * half of it the consumer wrote.
+     *
+     * @internal Read by the component itself and by nothing outside it: every
+     * call in the library is `this.isDisabled`. Public, it prints a row on
+     * twenty-four families in both tiers, forty-eight in all, on every form
+     * control's reference page.
+     *
+     * **A consumer loses nothing, which was measured rather than assumed.**
+     * `element.matches(':disabled')` answers the same question, is the platform's
+     * own, and works on a native control too. Checked in a browser across the
+     * three cases: a control disabled by its own attribute, one inside a
+     * `<fieldset>` before and after that fieldset is disabled, and one that is
+     * neither. `:disabled` agreed with `isDisabled` in every one, including the
+     * inheritance case that is the only reason this getter exists.
+     *
+     * Documented away rather than made `protected`, because a subclass in
+     * `helix/styled` binds to it and that is exactly what it is for.
+     */
+    get isDisabled(): boolean;
+    /**
+     * Called by the browser when an ancestor fieldset is disabled or enabled.
+     *
+     * **The argument is the effective state, and taking it whole is what latched
+     * every control in the library.** The platform calls this for the element's
+     * own `disabled` as well as for a fieldset, and our own arrives here at the
+     * worst possible moment: reflecting `disabled` to the attribute happens
+     * inside Lit's `update()`, the UA fires this synchronously from that write,
+     * and a reactive write during an update is a change-in-update Lit does not
+     * re-render for. So `formDisabled` ran exactly one update behind forever.
+     *
+     * Measured on Slider, logging what `render` saw:
+     *
+     * ```
+     * set true    disabled true   formDisabled false  isDisabled true
+     * set false   disabled false  formDisabled true   isDisabled true   <- stale
+     * (no third render)
+     * ```
+     *
+     * The host came out right every time, `disabled` false, `:disabled` not
+     * matching, and the inner control kept the attribute, so a control disabled
+     * once could never be re-enabled. It only shows when something re-enables,
+     * which is the same shape of bug `inheritDisabled` was written for.
+     *
+     * Our own half is already in `this.disabled` and `isDisabled` is an or, so
+     * this records only what the fieldset adds. That also removes the write
+     * entirely on the own-disabled path rather than moving it.
+     *
+     * The one case this cannot see is a control that is disabled itself *and*
+     * inside a disabled fieldset, whose own `disabled` is then removed: the
+     * effective state does not change, so the platform does not call again, and
+     * the fieldset's hold is not recorded. There is no callback to learn it from
+     * and reading `:disabled` here would answer about the attribute we are in the
+     * middle of removing.
+     */
+    formDisabledCallback(disabled: boolean): void;
+    /**
+     * Whether an ancestor `<fieldset disabled>` holds the control, outside its
+     * first `<legend>`, read from the tree.
+     *
+     * For the one case the callback cannot report: a control disabled itself and
+     * by a fieldset, whose own `disabled` is then removed. The effective state does
+     * not change, so the platform does not call, and the fieldset's hold has to
+     * be read.
+     */
+    private get heldByFieldset();
+    /**
+     * Called by the browser when the form is reset. It does nothing here, and
+     * every override calls it.
+     *
+     * **A chain rather than a leaf**, because more than one layer owes a reset
+     * something: the value mixin its default, and the field mixin beneath it the
+     * forgetting of a reader's past attempt, whose message otherwise showed over
+     * the emptied control the moment the form was reset.
+     */
+    formResetCallback(): void;
+    protected willUpdate(changed: PropertyValues): void;
+    /**
+     * The name the control's value is submitted under.
+     *
+     * **Reflected, and it is the exception to "reflect only what CSS selects
+     * on".** The platform builds a form's entry list from the `name` *content
+     * attribute*, not from the property, so a control named through the property
+     * submitted under no name at all and was silently dropped. Measured: two
+     * inputs in one form, one named by attribute and one by property, and the
+     * form carried a single entry.
+     *
+     * Safe for a React consumer, which is what the rule is protecting: React
+     * renders a custom element's props as attributes on the server, so the name
+     * is already in the markup being hydrated and reflecting it writes what is
+     * there. It is only a change to the markup when a consumer assigns it
+     * imperatively later, and nothing is hydrating by then.
+     *
+     * Here rather than on each control.
+     */
+    name: string;
+    /** The message `setCustomValidity` was given. */
+    protected customValidity: string;
+    /**
+     * Hands the platform the control's verdict, anchored where focus can go.
+     *
+     * Here the verdict is the custom message alone. `HelixFormElement` lays the
+     * message over what the control itself reported.
+     */
+    protected applyValidity(): void;
+    /**
+     * Whether the control meets its constraints, and why not.
+     *
+     * @reference https://developer.mozilla.org/docs/Web/API/ElementInternals/validity ElementInternals.validity
+     */
+    get validity(): ValidityState;
+    /** The message the browser would show for the control, or an empty string. */
+    get validationMessage(): string;
+    /** Whether an update is running, so `runPendingUpdate` never starts one inside another. */
+    private updateRunning;
+    protected performUpdate(): void;
+    /**
+     * Runs an update that is on its way, so the verdict read next is the one
+     * for what the control holds now.
+     *
+     * **A control reports its verdict as it updates, and an update waits for a
+     * microtask**, so a script that wrote `value` and asked at once was answered
+     * about the value before: measured on Time Input, `value = '18:00'` past a
+     * `max` of 17:00 and `checkValidity()` returned true until `updateComplete`.
+     * A native control answers about the value it was just given, so the
+     * questions a script can ask run the pending update first. Lit's
+     * `performUpdate` is the documented way to run one synchronously.
+     *
+     * Protected for a control that submits on its own, which has to hand the
+     * form the verdict for what it holds now: Pin Input's `autosubmit`.
+     */
+    protected runPendingUpdate(): void;
+    /** Whether the control is checked when its form is submitted. */
+    get willValidate(): boolean;
+    /**
+     * Returns whether the control is valid, and fires `invalid` on it when it is
+     * not. The control shows no message for it: `reportValidity()` does that.
+     */
+    checkValidity(): boolean;
+    /**
+     * Returns whether the control is valid, and when it is not, fires `invalid`
+     * and shows the browser's message at the control.
+     */
+    reportValidity(): boolean;
+    /**
+     * Marks the control invalid with `message`, or clears that with an empty
+     * string, as on a native control. The form does not submit while it is set.
+     */
+    setCustomValidity(message: string): void;
+    /**
+     * The element focus goes to: the control's first tab stop, or `null` where
+     * there is none.
+     *
+     * Read through shadow roots and slots, so a group lands on the member that
+     * holds its tab stop, which is the chosen radio in a radio group.
+     */
+    protected get focusTarget(): HTMLElement | null;
+    /** Moves focus to the control, as focusing a native control does. */
+    focus(options?: FocusOptions): void;
+    /**
+     * Focuses the control when its `<label>` is pressed.
+     *
+     * The label sends the host a click of the browser's own after trying to
+     * focus it, and a host that is not focusable takes nothing from that try.
+     * Only a click that starts at the host and that the browser sent: one from
+     * inside has landed where it meant to, and `click()` from a script does not
+     * focus a native control either.
+     */
+    private readonly focusFromLabel;
+    /**
+     * Re-anchors the verdict as the form checks it, because the control's
+     * members may have rendered since it last reported, and the anchor read then
+     * was the best there was.
+     */
+    private readonly refreshAnchor;
+    /** Stops listening for the labels in this control's tree. */
+    private unwatchLabels;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * @internal Whether this control is a field that counts against implicit
+     * submission: a single line of text, as `<input type="text">` is. Read by
+     * `submitImplicitly` in `utils/implicit-submit`, which only the controls
+     * that submit on Enter import.
+     */
+    protected get blocksImplicitSubmission(): boolean;
+    /** @internal Whether this control submits its form, for finding the form's default button. */
+    protected get submitsForm(): boolean;
+    /** @internal Activates the control as its form's default button. */
+    protected activate(): void;
+    /**
+     * The form the control belongs to, or `null`.
+     *
+     * @reference https://html.spec.whatwg.org/multipage/custom-elements.html#form-associated-custom-elements form-associated custom elements
+     */
+    get form(): HTMLFormElement | null;
+    /**
+     * The labels associated with the control.
+     *
+     * @reference https://html.spec.whatwg.org/multipage/custom-elements.html#form-associated-custom-elements form-associated custom elements
+     */
+    get labels(): NodeList;
+}

package/dist/helix-form-element/helix-form-element-base.js

@@ -0,0 +1,173 @@
+import { __decorate } from "tslib";
+import { property, state } from 'lit/decorators.js';
+import { HelixElement } from '../helix-element/helix-element.js';
+import { watchLabels } from '../utils/watch-labels/watch-labels.js';
+const isTabStop = (element) => element instanceof HTMLElement &&
+    element.tabIndex >= 0 &&
+    !element.disabled &&
+    !element.hidden &&
+    !element.inert &&
+    (typeof element.checkVisibility !== 'function' || element.checkVisibility());
+const firstTabStop = (node) => {
+    const children = node instanceof HTMLSlotElement ? node.assignedElements({ flatten: true }) : [...node.children];
+    for (const child of children) {
+        if (isTabStop(child)) {
+            return child;
+        }
+        const found = (child.shadowRoot ? firstTabStop(child.shadowRoot) : null) ?? firstTabStop(child);
+        if (found) {
+            return found;
+        }
+    }
+    return null;
+};
+export class HelixFormElementBase extends HelixElement {
+    constructor() {
+        super(...arguments);
+        this.disabled = false;
+        this.formDisabled = false;
+        this.name = '';
+        this.customValidity = '';
+        this.updateRunning = false;
+        this.focusFromLabel = (event) => {
+            if (!event.isTrusted || event.composedPath()[0] !== this || this.isDisabled) {
+                return;
+            }
+            if (!this.matches(':focus-within')) {
+                this.focus();
+            }
+        };
+        this.refreshAnchor = () => {
+            if (!this.internals.validity.valid) {
+                this.applyValidity();
+            }
+        };
+    }
+    static { this.formAssociated = true; }
+    get isDisabled() {
+        return this.disabled || this.formDisabled;
+    }
+    formDisabledCallback(disabled) {
+        this.formDisabled = disabled && !this.disabled;
+    }
+    get heldByFieldset() {
+        let fieldset = this.parentElement?.closest('fieldset[disabled]') ?? null;
+        while (fieldset) {
+            const legend = fieldset.querySelector(':scope > legend');
+            if (!legend?.contains(this)) {
+                return true;
+            }
+            fieldset = fieldset.parentElement?.closest('fieldset[disabled]') ?? null;
+        }
+        return false;
+    }
+    formResetCallback() { }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        if (changed.get('disabled') === true && !this.disabled && this.isConnected) {
+            this.formDisabled = this.heldByFieldset;
+        }
+        this.internals.ariaDisabled = this.isDisabled ? 'true' : null;
+    }
+    applyValidity() {
+        if (this.customValidity === '') {
+            this.internals.setValidity({});
+            return;
+        }
+        this.internals.setValidity({ customError: true }, this.customValidity, this.focusTarget ?? undefined);
+    }
+    get validity() {
+        this.runPendingUpdate();
+        return this.internals.validity;
+    }
+    get validationMessage() {
+        this.runPendingUpdate();
+        return this.internals.validationMessage;
+    }
+    performUpdate() {
+        this.updateRunning = true;
+        try {
+            super.performUpdate();
+        }
+        finally {
+            this.updateRunning = false;
+        }
+    }
+    runPendingUpdate() {
+        if (this.hasUpdated && this.isUpdatePending && !this.updateRunning) {
+            this.performUpdate();
+        }
+    }
+    get willValidate() {
+        return this.internals.willValidate;
+    }
+    checkValidity() {
+        this.runPendingUpdate();
+        return this.internals.checkValidity();
+    }
+    reportValidity() {
+        this.runPendingUpdate();
+        this.applyValidity();
+        return this.internals.reportValidity();
+    }
+    setCustomValidity(message) {
+        this.customValidity = message;
+        this.applyValidity();
+        this.requestUpdate();
+    }
+    get focusTarget() {
+        const root = this.shadowRoot;
+        return root ? firstTabStop(root) : null;
+    }
+    focus(options) {
+        const target = this.focusTarget;
+        if (target) {
+            target.focus(options);
+            return;
+        }
+        super.focus(options);
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        this.addEventListener('click', this.focusFromLabel);
+        this.addEventListener('invalid', this.refreshAnchor);
+        this.unwatchLabels = watchLabels(this, () => this.requestUpdate());
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.removeEventListener('click', this.focusFromLabel);
+        this.removeEventListener('invalid', this.refreshAnchor);
+        this.unwatchLabels?.();
+        this.unwatchLabels = undefined;
+    }
+    get blocksImplicitSubmission() {
+        return false;
+    }
+    get submitsForm() {
+        return false;
+    }
+    activate() {
+        this.click();
+    }
+    get form() {
+        return this.internals.form;
+    }
+    get labels() {
+        return this.internals.labels;
+    }
+}
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixFormElementBase.prototype, "disabled", void 0);
+__decorate([
+    state()
+], HelixFormElementBase.prototype, "formDisabled", void 0);
+__decorate([
+    property({
+        converter: {
+            fromAttribute: (value) => value ?? '',
+            toAttribute: (value) => (value === '' ? null : value),
+        },
+        reflect: true,
+    })
+], HelixFormElementBase.prototype, "name", void 0);