@fusion.dev/helix-core 0.0.0-dev

package/dist/mixins/mixin-dismissible/mixin-dismissible.js

@@ -0,0 +1,79 @@
+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 { property } from 'lit/decorators.js';
+import { HelixDismissEvent } from '../../events/events.js';
+/**
+ * Grafts `dismissible`, its label, and the event that says so.
+ *
+ * Three surfaces had written this: `Announcement`, `Tag` and `Toast.Item`, each
+ * with the same two properties, the same event, and the same expression for the
+ * label. They had not diverged, which is the argument for extracting rather than
+ * against it, because the fourth would have.
+ *
+ * **The label reads the default slot, not the whole element**, and that is a bug
+ * fix rather than a move. Every copy said `this.textContent`, which is every
+ * light-DOM descendant including the ones assigned elsewhere. On `Announcement`
+ * and `Tag` that is the same thing, because they have one slot. On `Toast.Item`
+ * it swept in the actions: a message reading "Could not reach the server" with a
+ * `Retry` button announced itself as "Could not reach the server Retry", and the
+ * consumer removing it from their list got that string to match on.
+ *
+ * **`dismissEvent()` is separate from `dismiss()` for the one that needs it.**
+ * `Announcement` and `Tag` dispatch and are done: they own no state, so a
+ * refusal is the whole of the consumer's answer. `Toast.Item` holds an `open`
+ * it may or may not own, so its event has to go through the controlled-change
+ * path with an `apply` beside it. Giving it the event rather than the method
+ * lets it keep the contract and skip the default.
+ */
+export const MixinDismissible = (Base) => {
+    class Dismissible extends Base {
+        constructor() {
+            super(...arguments);
+            /**
+             * Whether it offers a control to take it away.
+             */
+            this.dismissible = false;
+            /**
+             * Accessible name for that control.
+             *
+             * `attribute` is spelled out because Lit lowercases a property name to
+             * derive one rather than dash-casing it, so this would otherwise be
+             * reachable only as `dismisslabel`, which nobody would guess and no linter
+             * would catch.
+             */
+            this.dismissLabel = 'Dismiss';
+        }
+        /**
+         * The event, built and not dispatched.
+         *
+         * Reading text is safe here: nothing calls this on a server, because the
+         * only things that do are a press and a timer.
+         */
+        dismissEvent() {
+            /* Default slot only. A node assigned to a named slot belongs to another
+               region and is not what this surface is called. */
+            const own = [...this.childNodes]
+                .filter((node) => !(node instanceof Element) || !node.slot)
+                .map((node) => node.textContent ?? '')
+                .join('');
+            return new HelixDismissEvent({ label: own.trim() });
+        }
+        /** Announces that it should go, and reports whether the request stood. */
+        dismiss() {
+            const event = this.dismissEvent();
+            this.dispatchEvent(event);
+            return !event.defaultPrevented;
+        }
+    }
+    __decorate([
+        property({ reflect: true, type: Boolean })
+    ], Dismissible.prototype, "dismissible", void 0);
+    __decorate([
+        property({ attribute: 'dismiss-label' })
+    ], Dismissible.prototype, "dismissLabel", void 0);
+    return Dismissible;
+};

package/dist/mixins/mixin-field/mixin-field.d.ts

@@ -0,0 +1,145 @@
+import { nothing, type TemplateResult } from 'lit';
+import type { HelixElement } from '../../helix-element/helix-element.js';
+type Constructor<T> = new (...args: any[]) => T;
+/**
+ * The public surface `MixinField` adds.
+ *
+ * Declared separately because TypeScript cannot emit declarations for an
+ * anonymous class that has private members (TS4094). Casting the mixin's return
+ * to this interface keeps the internals private and the build working.
+ */
+export declare class MixinFieldInterface {
+    /**
+     * Help under the control, shown while there is nothing wrong.
+     *
+     * Fallback content for the `hint` slot, so anything richer replaces it.
+     */
+    hint: string;
+    /**
+     * Ids of the description nodes, for `aria-describedby` on the control.
+     *
+     * `undefined` when there is nothing to point at, so the attribute is absent
+     * rather than pointing at an id that renders nothing.
+     */
+    readonly describedBy: string | undefined;
+    /**
+     * What is wrong, in the reader's words rather than the browser's.
+     *
+     * Overrides the platform's message. Left empty, the platform's own is shown
+     * once the reader has had a go at the field, never before. Either way it
+     * takes the hint's place rather than appearing under it.
+     */
+    feedback: string;
+    /**
+     * The accessible name, and the fallback for the `label` slot.
+     *
+     * Content rather than configuration, so it is the slot's fallback and never a
+     * second thing rendered beside it.
+     */
+    label: string;
+    /**
+     * Points the host at its own label and description nodes, for a group.
+     *
+     * Client only, and an enhancement rather than the whole story: a group's name
+     * is also set as a plain string so the server can serve one, and this
+     * overrides it where a consumer slotted something richer than a string.
+     */
+    protected linkHost(): void;
+    /** Help under the control, unless something has gone wrong. */
+    protected renderHint(): TemplateResult | typeof nothing;
+    /** The validation message, in the hint's place. */
+    protected renderFeedback(): TemplateResult | typeof nothing;
+    /** A label over a set, for a group, which has nothing to point `for` at. */
+    protected renderGroupLabel(): TemplateResult | typeof nothing;
+    /** A label above the control, pointing at it with a real `for`. */
+    protected renderLabel(): TemplateResult | typeof nothing;
+    /** Whether the form refuses to submit without it. */
+    required: boolean;
+    /**
+     * Re-reads the platform's verdict, for a control that has just reported one.
+     *
+     * Call it straight after `setValidity`. Nothing else can: validity changes
+     * through `ElementInternals` rather than through a property, so no update is
+     * scheduled for it and the message on screen would be the one from before.
+     */
+    protected refreshFeedback(): void;
+    /**
+     * Reports "required and empty" against a rendered part, or clears it.
+     *
+     * `empty` is the control's own answer to whether it holds nothing, `message`
+     * is what to say about it, and `anchor` names the part the browser should
+     * point its bubble at. Seven families wrote this out by hand.
+     */
+    protected reportRequired(empty: boolean, message: string, anchor: string): void;
+    /** The message actually shown: the consumer's, or the platform's, or none. */
+    readonly resolvedFeedback: string;
+}
+/**
+ * Grafts a label, help text, and a validation message onto a control.
+ *
+ * **Over `HelixElement` rather than `HelixFormElement`, because not every
+ * control that wants a label is form-associated.** A checkbox group is the
+ * case: each box in it submits itself already, so the group deliberately
+ * reports no value of its own, and every form-related member of
+ * `ElementInternals` throws `NotSupportedError` on an element that is not
+ * form-associated. Measured, and the ARIA members are fine on the same
+ * element, which is why the naming and describing work there and only the
+ * validity has to ask first.
+ *
+ * Every form control wants the same three things around it and wants them in a
+ * different arrangement: a label above an input, beside a checkbox, and over a
+ * group. So this owns the properties, the parts, and the wiring, and each
+ * control places the nodes where its own geometry needs them. Same part names
+ * either way, so one stylesheet in the styled tier dresses all of them.
+ *
+ * **Not a wrapping `Field` component, and that is not a style preference.** A
+ * wrapper cannot name what it wraps. Its label would live in its own shadow
+ * root and the control in another, and measured in Chrome 148: an
+ * `aria-labelledby` IDREF cannot see across, and
+ * `control.ariaLabelledByElements = [labelInTheWrapper]` reads back as zero
+ * elements, the reference dropped. The same assignment with a label in the
+ * control's own tree is kept. That pattern works in React libraries because
+ * they have no shadow boundary; bringing it here brings the ergonomics and none
+ * of the conditions that made it work.
+ *
+ * **A control whose label is its content renders its own.** A checkbox is named
+ * by the words beside it, inside the `<label>` that forwards the press, so it
+ * uses its default slot and nesting `renderLabel`'s `<label>` in there would be
+ * invalid markup. `label` is that slot's fallback either way.
+ *
+ * Worth knowing, because it costs a label and gives no warning: **a
+ * whitespace-only text node is assigned to the default slot and defeats its
+ * fallback.** Measured in Chrome 148, and a newline between the tags is enough,
+ * so `<helix-checkbox label="Accept">` closed on the next line renders no label
+ * at all. A named slot does not have this problem, because `slot="label"` is an
+ * attribute and a text node has none. It is the platform's behavior rather
+ * than ours, and the same is already true of every slot fallback here.
+ *
+ * **The ids are fixed rather than generated.** IDREFs resolve within the tree
+ * that holds them, so two controls on a page each carrying `helix-hint` in
+ * their own shadow root do not collide. That also removes the usual hydration
+ * hazard, since there is no generated value for a server and a client to
+ * disagree about.
+ *
+ * **A group has to say it differently.** A control's `<input>` and its hint
+ * are both in the shadow root, so a plain `aria-describedby` resolves. A
+ * group's host is in the light DOM and its hint is not, so the IDREF cannot
+ * reach and `element.ariaDescribedByElements` drops the reference. Only
+ * `internals.ariaDescribedByElements` keeps it, which is what `describeHost`
+ * uses. Measured the same way, and the failure is silent either way: the
+ * description simply never reaches the accessibility tree.
+ *
+ *
+ * **The label, the hint and the feedback are documented on each component that
+ * applies this, rather than here.** Eight of the eighteen did and ten did not,
+ * which is what `check:parts` now refuses in both directions. Declaring them
+ * once on this mixin is the obvious fix and does not work: the analyzer reads
+ * `@csspart` off a custom element class, so a class-level tag here reaches the
+ * manifest as nothing at all, on this JSDoc and on the inner class alike.
+ * Measured both ways, and the inner-class version is the dangerous one, since
+ * it satisfies `check:parts` while every API page stays exactly as wrong as
+ * before. Members are different and do inherit, which is what the note about
+ * the inner class in the area rules is about.
+ */
+export declare const MixinField: <T extends Constructor<HelixElement>>(Base: T) => Constructor<MixinFieldInterface> & T;
+export {};

package/dist/mixins/mixin-field/mixin-field.js

@@ -0,0 +1,423 @@
+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 { html, nothing } from 'lit';
+import { property, state } from 'lit/decorators.js';
+import { hostAria } from '../../utils/host-aria/host-aria.js';
+/** Fixed ids, scoped to the shadow root that holds them. See the mixin's note. */
+const HINT_ID = 'helix-hint';
+const FEEDBACK_ID = 'helix-feedback';
+/**
+ * Grafts a label, help text, and a validation message onto a control.
+ *
+ * **Over `HelixElement` rather than `HelixFormElement`, because not every
+ * control that wants a label is form-associated.** A checkbox group is the
+ * case: each box in it submits itself already, so the group deliberately
+ * reports no value of its own, and every form-related member of
+ * `ElementInternals` throws `NotSupportedError` on an element that is not
+ * form-associated. Measured, and the ARIA members are fine on the same
+ * element, which is why the naming and describing work there and only the
+ * validity has to ask first.
+ *
+ * Every form control wants the same three things around it and wants them in a
+ * different arrangement: a label above an input, beside a checkbox, and over a
+ * group. So this owns the properties, the parts, and the wiring, and each
+ * control places the nodes where its own geometry needs them. Same part names
+ * either way, so one stylesheet in the styled tier dresses all of them.
+ *
+ * **Not a wrapping `Field` component, and that is not a style preference.** A
+ * wrapper cannot name what it wraps. Its label would live in its own shadow
+ * root and the control in another, and measured in Chrome 148: an
+ * `aria-labelledby` IDREF cannot see across, and
+ * `control.ariaLabelledByElements = [labelInTheWrapper]` reads back as zero
+ * elements, the reference dropped. The same assignment with a label in the
+ * control's own tree is kept. That pattern works in React libraries because
+ * they have no shadow boundary; bringing it here brings the ergonomics and none
+ * of the conditions that made it work.
+ *
+ * **A control whose label is its content renders its own.** A checkbox is named
+ * by the words beside it, inside the `<label>` that forwards the press, so it
+ * uses its default slot and nesting `renderLabel`'s `<label>` in there would be
+ * invalid markup. `label` is that slot's fallback either way.
+ *
+ * Worth knowing, because it costs a label and gives no warning: **a
+ * whitespace-only text node is assigned to the default slot and defeats its
+ * fallback.** Measured in Chrome 148, and a newline between the tags is enough,
+ * so `<helix-checkbox label="Accept">` closed on the next line renders no label
+ * at all. A named slot does not have this problem, because `slot="label"` is an
+ * attribute and a text node has none. It is the platform's behavior rather
+ * than ours, and the same is already true of every slot fallback here.
+ *
+ * **The ids are fixed rather than generated.** IDREFs resolve within the tree
+ * that holds them, so two controls on a page each carrying `helix-hint` in
+ * their own shadow root do not collide. That also removes the usual hydration
+ * hazard, since there is no generated value for a server and a client to
+ * disagree about.
+ *
+ * **A group has to say it differently.** A control's `<input>` and its hint
+ * are both in the shadow root, so a plain `aria-describedby` resolves. A
+ * group's host is in the light DOM and its hint is not, so the IDREF cannot
+ * reach and `element.ariaDescribedByElements` drops the reference. Only
+ * `internals.ariaDescribedByElements` keeps it, which is what `describeHost`
+ * uses. Measured the same way, and the failure is silent either way: the
+ * description simply never reaches the accessibility tree.
+ *
+ *
+ * **The label, the hint and the feedback are documented on each component that
+ * applies this, rather than here.** Eight of the eighteen did and ten did not,
+ * which is what `check:parts` now refuses in both directions. Declaring them
+ * once on this mixin is the obvious fix and does not work: the analyzer reads
+ * `@csspart` off a custom element class, so a class-level tag here reaches the
+ * manifest as nothing at all, on this JSDoc and on the inner class alike.
+ * Measured both ways, and the inner-class version is the dangerous one, since
+ * it satisfies `check:parts` while every API page stays exactly as wrong as
+ * before. Members are different and do inherit, which is what the note about
+ * the inner class in the area rules is about.
+ */
+export const MixinField = (Base) => {
+    // JSDoc is duplicated from MixinFieldInterface deliberately. The interface is
+    // what TypeScript consumers see; this class is what the manifest analyzer
+    // reads when resolving inherited members into dependent packages.
+    class FieldElement extends Base {
+        constructor() {
+            super(...arguments);
+            /**
+             * Help under the control, shown while there is nothing wrong.
+             */
+            this.hint = '';
+            /**
+             * What is wrong, in the reader's words rather than the browser's.
+             */
+            this.feedback = '';
+            /**
+             * The accessible name, and the fallback for the `label` slot.
+             */
+            this.label = '';
+            /**
+             * Whether the form refuses to submit without it.
+             */
+            this.required = false;
+            /**
+             * Whether the reader has had a go at the field yet.
+             *
+             * This was `:user-invalid`, which is the platform's own answer to "is this
+             * field wrong *yet*" and is the right idea. It does not work here, and the
+             * reason is structural rather than a browser bug: `:user-invalid` tracks
+             * interaction with the element it is on, and nobody interacts with this
+             * element. The reader types into an `<input>` inside its shadow root, so
+             * the host's interaction flag is never set and the selector never matches.
+             * Measured after submitting an invalid required field and again after
+             * editing one and leaving it: false both times, while `:invalid` matched
+             * both times.
+             *
+             * So the moments are listened for instead, and both of them demonstrably
+             * reach the host: `invalid` when a form is submitted with this control
+             * failing, and `change` when the reader has edited and committed. Focus
+             * alone is deliberately not one of them. Tabbing past an empty required
+             * field should not be answered with an error.
+             *
+             * **A composite control has to construct its own `change`, and this mixin
+             * deliberately does not do it for them.** A native `change` is
+             * `composed: false`, so a control built from several inner inputs never
+             * relays one to its host: `Input` gets this free from its one control, and
+             * `PinInput` had four boxes, none of whose `change` means the code is
+             * entered, so a half-entered code was never `touched` and could never say
+             * what was wrong with it. See 311.
+             *
+             * **The obvious shared fix is for `touched` to take a `focusout`, and it is
+             * the wrong one**, because it is the paragraph above undone: a `focusout`
+             * fires on the reader who tabbed past and typed nothing, which is exactly
+             * the case this refuses to call an error. What a composite needs is not a
+             * focus moment, it is the native meaning of `change`, "edited, then left",
+             * and the editing half is the part a mixin up here cannot see.
+             *
+             * **Nor is there one shape to extract yet.** The two composites in the
+             * library solve it differently and both are right: `PinInput` is
+             * focus-driven, taking a baseline when focus arrives from outside the row
+             * and announcing on the way out if it moved, and `DateInput` is
+             * value-driven, stopping its inner `change` and announcing once the date
+             * itself moves. Generalizing from those two would be generalizing from one,
+             * since only one of them has a leaving moment at all. The trigger for
+             * lifting it is a third control that needs the focus-driven shape, at which
+             * point what moves up is the baseline-and-commit pair rather than `touched`.
+             */
+            this.touched = false;
+            /** What the last render put on screen, so a change can be noticed. */
+            this.shownFeedback = '';
+        }
+        /**
+         * Whether this element may be asked about its own validity at all.
+         *
+         * Reading the static the platform itself reads to decide, rather than
+         * probing: `validity` and `validationMessage` throw `NotSupportedError` on
+         * an element that is not form-associated, and a group whose members each
+         * submit themselves is not. Such a control still shows a message, it just
+         * has to be given one.
+         */
+        get validates() {
+            return this.constructor.formAssociated === true;
+        }
+        /**
+         * @internal The message actually shown: the consumer's, or the platform's,
+         * or none. Wiring a field does to itself, read by its own template. A
+         * consumer sets `feedback` and reads validity from the platform.
+         */
+        get resolvedFeedback() {
+            if (this.feedback !== '') {
+                return this.feedback;
+            }
+            if (!this.validates || !this.touched || this.internals.validity.valid) {
+                return '';
+            }
+            return this.internals.validationMessage;
+        }
+        /**
+         * @internal Id of the description node, for `aria-describedby` on the
+         * control. Written by the field's own template into its own shadow root.
+         *
+         * One at a time, because only one of the two is ever rendered. Naming both
+         * would point a screen reader at an id that resolves to nothing, which it
+         * reads as a description it cannot find.
+         */
+        get describedBy() {
+            if (this.resolvedFeedback !== '') {
+                return FEEDBACK_ID;
+            }
+            return this.hint === '' ? undefined : HINT_ID;
+        }
+        /**
+         * A label over a set rather than beside a control.
+         *
+         * A plain element and not a `<label for>`, because a group is not a single
+         * control and there is nothing for `for` to point at. What names the group
+         * is `linkHost`, pointing the host's internals at this element.
+         */
+        renderGroupLabel() {
+            /* A set names itself through `hostAria`, so an `aria-label` here already
+               reaches the group. The label is still rendered and clipped, because
+               `renderGroupLabel` is what the styled tier lays out and a group that
+               drew nothing would collapse its own first row. */
+            const hidden = this.label === '' ? this.getAttribute('aria-label') : null;
+            if (this.label === '' && !hidden) {
+                return nothing;
+            }
+            return html `<span part="label" ?data-hidden=${hidden !== null}
+        ><slot name="label">${this.label || hidden}</slot></span
+      >`;
+        }
+        /**
+         * A label above the control, pointing at it.
+         *
+         * A real `<label for>`, so pressing the words focuses the field and the
+         * browser does the forwarding. It resolves because `for` looks within the
+         * same tree, and the control it names is in this shadow root.
+         *
+         * **Nothing at all when there is no label**, which is the same rule the
+         * hint and the feedback follow: none of the three is always used, and an
+         * element rendered empty is not free. It still generates a box, so it still
+         * takes a row of the grid and a gap on either side of it, which is a field
+         * that has moved down the page for a label nobody wrote. `nothing` leaves
+         * comment markers rather than a node, so the gap has nothing to sit between.
+         *
+         * **`aria-label` names without showing**, and it is forwarded rather than
+         * left where the consumer put it. A custom element has no way to delegate a
+         * label to the control inside it, so an `aria-label` on the host reaches
+         * nothing: measured, the inner input came back with no label and no name of
+         * its own while the attribute sat on the wrapper. What happens instead is
+         * that the label is rendered and clipped, so the name arrives through the
+         * same `<label for>` a visible one does.
+         *
+         * This replaced `hide-label`, which was a second attribute to say what the
+         * absence of the first should have said. The rule is now `label` means a
+         * label, `aria-label` means a name, and neither means an unnamed field a
+         * screen reader announces as "edit text"
+         */
+        renderLabel() {
+            const hidden = this.label === '' ? this.getAttribute('aria-label') : null;
+            if (this.label === '' && !hidden) {
+                return nothing;
+            }
+            return html `<label part="label" for="control" ?data-hidden=${hidden !== null}
+        ><slot name="label">${this.label || hidden}</slot></label
+      >`;
+        }
+        /**
+         * Help under the control, unless something has gone wrong.
+         *
+         * The two share a place rather than stacking, so a field is one line of
+         * small text either way and nothing below it moves when the message
+         * changes. What the reader needs at that moment is what is wrong, and a
+         * hint that survives the error it describes is a second line to read before
+         * getting to the one that matters.
+         */
+        renderHint() {
+            if (this.hint === '' || this.resolvedFeedback !== '') {
+                return nothing;
+            }
+            return html `<p part="hint" id=${HINT_ID}><slot name="hint">${this.hint}</slot></p>`;
+        }
+        /**
+         * The validation message, in the hint's place.
+         *
+         * `role="alert"` rather than a live region on the whole field, so what is
+         * announced is the message and not the label and help along with it.
+         */
+        renderFeedback() {
+            const message = this.resolvedFeedback;
+            if (message === '') {
+                return nothing;
+            }
+            return html `<p part="feedback" id=${FEEDBACK_ID} role="alert">
+        <slot name="feedback">${message}</slot>
+      </p>`;
+        }
+        /**
+         * Points the host at its own label and description nodes, for a group.
+         *
+         * A control's `<input>` and its hint are both in the shadow root, so a
+         * plain `aria-describedby` resolves between them. A group's host is in the
+         * light DOM and its hint is not, so the IDREF cannot reach and
+         * `element.ariaDescribedByElements` drops the reference outright. Only the
+         * `ElementInternals` form keeps it, measured in Chrome 148: two of two
+         * kept through internals, zero of one through the element.
+         *
+         * Client only, and deliberately, because element references need the nodes
+         * to exist and on the server they do not. The name is therefore also set as
+         * a plain string by the component, which a server can write, and the
+         * reference here overrides it wherever a consumer slotted something richer
+         * than a string. A group with only a property for a label reads the same
+         * either way.
+         */
+        linkHost() {
+            const label = this.renderRoot.querySelector('[part="label"]');
+            hostAria(this.internals, {
+                describedBy: [HINT_ID, FEEDBACK_ID]
+                    .map((id) => this.renderRoot.querySelector(`#${id}`))
+                    .filter((node) => node !== null),
+                labelledBy: label ? [label] : [],
+            });
+        }
+        /**
+         * Re-reads the platform's verdict, for a control that has just reported one.
+         *
+         * Validity changes through `ElementInternals` rather than through a
+         * property, so nothing schedules an update for it. Worse, the order is
+         * against us: this mixin sits above the control in the prototype chain, so
+         * its `updated` runs before the control's own, which is where `setValidity`
+         * is called. Reading the verdict here would always read the previous one,
+         * which is what left a corrected field still showing the error it had
+         * before. So the control says when it has reported, and this schedules the
+         * one further update that needs. It converges because the second pass finds
+         * nothing changed.
+         */
+        refreshFeedback() {
+            const next = this.resolvedFeedback;
+            if (next !== this.shownFeedback) {
+                this.shownFeedback = next;
+                this.requestUpdate();
+            }
+        }
+        /**
+         * Reports "required and empty" and refreshes the message, or clears both.
+         *
+         * Seven families had this written out: the same `valueMissing`, the same
+         * anchor lookup, the same `refreshFeedback` under the same comment about
+         * validity moving without a property moving. Seven copies of a five-line
+         * shape is the threshold at which this mixin itself was extracted, and two
+         * of them had already drifted, `checkbox-group` having no validity at all
+         * until yesterday.
+         *
+         * What differs between them is exactly two things, so those are the
+         * arguments: whether the control is empty, which only it can say, and the
+         * sentence to say about it, which is different for a box, a switch and a
+         * set. The anchor is looked up here because every one of them anchored on a
+         * rendered part and the browser needs somewhere to point the bubble.
+         *
+         * The message is not derived from the control's kind, deliberately. "Tick
+         * this box" and "Choose one" are not the same instruction and a lookup
+         * table would be one more thing to keep in step with the components.
+         */
+        reportRequired(empty, message, anchor) {
+            if (this.required && empty) {
+                this.internals.setValidity({ valueMissing: true }, message, this.renderRoot?.querySelector(`[part="${anchor}"]`) ?? undefined);
+            }
+            else {
+                this.internals.setValidity({});
+            }
+            // Straight after, because validity moved without any property moving.
+            this.refreshFeedback();
+        }
+        /**
+         * Records "wrong, and the reader knows it" as the custom state `invalid`.
+         *
+         * The styled tier selects on this rather than on `:host(:user-invalid)`,
+         * which cannot match for the reason above, so the invalid border never
+         * arrived either. One state, and the message and the border agree by
+         * construction.
+         *
+         * **A state and not `data-invalid`, since 27 Aug 2026.** A field served
+         * with a `feedback` message already failing was written invalid on its
+         * first update, which is an attribute the consumer's server never sent.
+         * `HelixElement.toggleState` carries the argument.
+         *
+         * In `willUpdate`, which is where the resolved message is first known.
+         */
+        willUpdate(changed) {
+            super.willUpdate(changed);
+            this.shownFeedback = this.resolvedFeedback;
+            this.toggleState('invalid', this.shownFeedback !== '');
+            /* And say it to the accessibility tree, which nothing did.
+             *
+             * A field carrying a `feedback` message painted red, and was described by
+             * that message through `aria-describedby`, and was never announced as
+             * being *wrong*: a reader heard the message as though it were help text.
+             * `aria-invalid` is the one word for it, and this is the one place that
+             * knows, so every field in the library gets it from here. */
+            this.internals.ariaInvalid = this.shownFeedback === '' ? null : 'true';
+        }
+        /**
+         * The two moments a field becomes wrong, neither of which is a property
+         * change, so nothing else would schedule an update for them.
+         *
+         * In `firstUpdated` rather than `connectedCallback`, which SSR never calls.
+         */
+        firstUpdated(changed) {
+            super.firstUpdated(changed);
+            const touch = () => {
+                this.touched = true;
+            };
+            this.addEventListener('invalid', touch);
+            this.addEventListener('change', touch);
+        }
+    }
+    __decorate([
+        property()
+    ], FieldElement.prototype, "hint", void 0);
+    __decorate([
+        property()
+    ], FieldElement.prototype, "feedback", void 0);
+    __decorate([
+        property()
+    ], FieldElement.prototype, "label", void 0);
+    __decorate([
+        property({ reflect: true, type: Boolean })
+    ], FieldElement.prototype, "required", void 0);
+    __decorate([
+        state()
+    ], FieldElement.prototype, "touched", void 0);
+    /* Through `unknown`, which the protected members make necessary: TypeScript
+       treats two protected members as compatible only when they come from the
+       same declaration, and these come from two, the class here and the declared
+       interface above. Making them public would type-check without a word and put
+       five render helpers on the public API page of every form control, which is
+       what the interface exists to prevent.
+  
+       The contract is enforced by use rather than by the cast. Every helper is
+       called from `Input` or `Checkbox`, so an interface that drifts from the
+       class fails their builds, which is exactly how the missing declarations
+       were found. */
+    return FieldElement;
+};

package/dist/utils/anchor-element/anchor-element.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The element a floating surface should open against, given the slot it wraps.
+ *
+ * **A wrapper with no box is not an anchor.** `display: contents` puts an
+ * element's children into the layout and leaves the element itself without a
+ * box, so its `getBoundingClientRect()` is `0 0 0 0`. Measured: a tooltip host
+ * reports exactly that while the button inside it reports 32 by 32. Anchoring
+ * to it opens the surface against the top left of the window, and focusing it
+ * on close puts focus nowhere.
+ *
+ * That is not an edge case, because wrapping is how a tooltip attaches to the
+ * thing it describes. Without this, an icon button used as a trigger is the one
+ * button on a toolbar that cannot have a tooltip.
+ *
+ * So this descends past anything that draws nothing, and the first child with a
+ * box is the anchor. The wrapper is transparent by construction, so the thing
+ * with the box is the thing the reader is pointing at.
+ *
+ * Bounded rather than a walk to the leaves: a chain of box-less wrappers is
+ * already unusual, and descending without a limit through a tree this library
+ * does not own is worse than stopping and anchoring to something imperfect.
+ */
+export declare const anchorElement: (slot: HTMLSlotElement | null | undefined, fallback: HTMLElement) => HTMLElement;