@lo-tek/interfaces 0.0.0 → 0.37.0

package/dist/components/frame/error-summary/lt-error-summary.d.ts

@@ -0,0 +1,82 @@
+import { HostElement } from "../../host-element.js";
+export declare const LT_ERROR_SUMMARY_TAG: "lt-error-summary";
+/**
+ * The parts the error summary looks for, as selectors relative to the
+ * element. The component finds its parts with these, and the manifest
+ * describes them for whoever assembles the markup by hand, so the two cannot
+ * say different things.
+ */
+export declare const LT_ERROR_SUMMARY_PARTS: {
+    readonly title: "h1, h2, h3, h4, h5, h6";
+    readonly link: "li a[href^='#']";
+};
+export declare class LtErrorSummary extends HostElement {
+    static observedAttributes: readonly ["data-autofocus", "hidden"];
+    private hasFocused;
+    /**
+     * Whether the component has tried to move focus since the box last became
+     * visible.
+     *
+     * The first attempt happens wherever focus is: a new submission has
+     * failed, and that is the message. If it did not land, because the box was
+     * in a hidden panel, the component tries again on the next change to the
+     * list, but only when nobody is in a field. Without that distinction the
+     * retry pulled focus out of the field the user was correcting, as soon as
+     * live validation patched the list.
+     */
+    private focusAttempted;
+    private observer?;
+    connectedCallback(): void;
+    attributeChangedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * Whether the box takes focus when it becomes visible. Default: yes.
+     *
+     * The attribute is called `data-autofocus` and not `autofocus`, even
+     * though the latter reads better. `autofocus` is a boolean property on
+     * `HTMLElement`, and React 19 sets properties rather than attributes on web
+     * components. `autofocus="false"` then became `el.autofocus = "false"`,
+     * which is true, while the attribute never reached the markup, and the
+     * opt-out did not work. `data-*` is passed on as an attribute in every
+     * React version.
+     */
+    private get shouldFocus();
+    /**
+     * Fills in what a template without JavaScript did not write. Only what is
+     * missing: a role the server chose stays, and so does a `tabindex`.
+     */
+    private wire;
+    private sync;
+    /**
+     * Takes focus back once, if it went back to where it was.
+     *
+     * React gives focus back to the element that had it before a commit, right
+     * after the DOM has changed. The box moves focus as `hidden` is removed or
+     * as it is connected, that is inside the same commit, so focus ended up on
+     * the submit button again in Chromium and Firefox, and on the field in all
+     * three engines when the form was submitted with Enter. A microtask runs
+     * after the commit. If focus is then on the same element as before, the
+     * framework took it, and the box takes it again. If a script has moved
+     * focus somewhere else, it stays.
+     *
+     * Only when the box is directly in the document. React does not enter a
+     * shadow root when it restores focus, and there `document.activeElement`
+     * is the shadow host both before and after, so the comparison would take
+     * focus from a field in the same root. The condition is deliberately
+     * coarse: a box portalled into a shadow root from a React app in plain DOM
+     * does not take focus back.
+     */
+    private reclaimFocusFrom;
+    /**
+     * The element a link points to.
+     *
+     * The lookup goes to the root the component is in, not to `document`. If
+     * the form is in a shadow root, as in a preview or inside another
+     * component, `document.getElementById` finds nothing, and the link becomes
+     * a plain anchor link without moving focus.
+     */
+    private resolveTarget;
+    private handleLinkClick;
+}
+export declare function defineLtErrorSummary(tagName?: string): void;
+//# sourceMappingURL=lt-error-summary.d.ts.map

package/dist/components/frame/error-summary/lt-error-summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lt-error-summary.d.ts","sourceRoot":"","sources":["../../../../src/components/frame/error-summary/lt-error-summary.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,WAAW,EAGZ,MAAM,uBAAuB,CAAA;AAK9B,eAAO,MAAM,oBAAoB,EAAG,kBAA2B,CAAA;AAE/D;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;;;CAGzB,CAAA;AA0CV,qBAAa,cAAe,SAAQ,WAAW;IAC7C,MAAM,CAAC,kBAAkB,wCAAwC;IAEjE,OAAO,CAAC,UAAU,CAAQ;IAC1B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,cAAc,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,CAAkB;IAEnC,iBAAiB,IAAI,IAAI;IAmBzB,wBAAwB,IAAI,IAAI;IAOhC,oBAAoB,IAAI,IAAI;IAM5B;;;;;;;;;;OAUG;IACH,OAAO,KAAK,WAAW,GAEtB;IAED;;;OAGG;IACH,OAAO,CAAC,IAAI;IAWZ,OAAO,CAAC,IAAI;IA2FZ;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,gBAAgB;IAWxB;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;IAarB,OAAO,CAAC,eAAe,CAwCtB;CACF;AAYD,wBAAgB,oBAAoB,CAClC,OAAO,GAAE,MAA6B,GACrC,IAAI,CAEN"}

package/dist/components/frame/error-summary/lt-error-summary.js

@@ -0,0 +1,302 @@
+import { addClass, defineElement, HostElement, setAttr, warnAboutMarkup, } from "../../host-element.js";
+import { ERROR_SUMMARY_CLASS, ERROR_SUMMARY_TITLE_CLASS, } from "./error-summary.js";
+export const LT_ERROR_SUMMARY_TAG = "lt-error-summary";
+/**
+ * The parts the error summary looks for, as selectors relative to the
+ * element. The component finds its parts with these, and the manifest
+ * describes them for whoever assembles the markup by hand, so the two cannot
+ * say different things.
+ */
+export const LT_ERROR_SUMMARY_PARTS = {
+    title: "h1, h2, h3, h4, h5, h6",
+    link: "li a[href^='#']",
+};
+/**
+ * Takes the user from an error in the summary to the field that failed.
+ *
+ * The server writes the content: the heading and the list of links. When the
+ * markup is written with JavaScript, `lt.errorSummary()` also writes the
+ * class, `role="alert"` and `tabindex="-1"` on the box, and the component
+ * leaves them alone. When the markup comes from a template without
+ * JavaScript, the component fills in those three and the class on the
+ * heading, and sets them back when a patch removes them. The component
+ * creates no nodes: it used to, and then the heading disappeared on the
+ * first morph in Datastar and never came back.
+ *
+ * What is left are two things the browser does not do by itself:
+ *
+ * 1. Focus moves to the box when it becomes visible, so someone listening to
+ *    the page learns that the submission stopped.
+ * 2. Focus goes to the control itself when a link is followed. A plain anchor
+ *    link only gives focus to a target that can take it; if it points to a
+ *    label or a heading, `document.activeElement` becomes `<body>`, and the
+ *    screen reader is not told where the user is. Tab continues from the
+ *    target either way.
+ *
+ * ```html
+ * <lt-error-summary>
+ *   <h2>The form has two errors</h2>
+ *   <ul class="lt-list">
+ *     <li><a href="#email">Enter a valid email address</a></li>
+ *   </ul>
+ * </lt-error-summary>
+ * ```
+ */
+/** Decodes a fragment, and returns it untouched if it is not valid. */
+function decodeFragment(fragment) {
+    try {
+        return decodeURIComponent(fragment);
+    }
+    catch {
+        return fragment;
+    }
+}
+export class LtErrorSummary extends HostElement {
+    constructor() {
+        super(...arguments);
+        this.hasFocused = false;
+        /**
+         * Whether the component has tried to move focus since the box last became
+         * visible.
+         *
+         * The first attempt happens wherever focus is: a new submission has
+         * failed, and that is the message. If it did not land, because the box was
+         * in a hidden panel, the component tries again on the next change to the
+         * list, but only when nobody is in a field. Without that distinction the
+         * retry pulled focus out of the field the user was correcting, as soon as
+         * live validation patched the list.
+         */
+        this.focusAttempted = false;
+        this.handleLinkClick = (event) => {
+            const link = event.target?.closest?.(LT_ERROR_SUMMARY_PARTS.link);
+            if (!link || !this.contains(link))
+                return;
+            const id = link.getAttribute("href")?.slice(1);
+            if (!id)
+                return;
+            // The guard stays for the race: the target may have disappeared in a
+            // patch between the sync and the click. `sync()` has already reported a
+            // link that never had a target.
+            const target = this.resolveTarget(id);
+            if (!target)
+                return;
+            event.preventDefault();
+            // If the link is to a label, focus goes to what the label belongs to,
+            // whether it points with `for` or wraps the control. `control` covers
+            // both for real controls; if `for` points to something else, such as a
+            // group, the id is followed there.
+            const focusable = target instanceof HTMLLabelElement
+                ? (target.control ??
+                    (target.htmlFor ? this.resolveTarget(target.htmlFor) : null) ??
+                    target)
+                : target;
+            // A target that cannot take focus, such as a heading, gets a `tabindex`
+            // for this one jump. It is a write on markup that comes from the server,
+            // and a patch may remove it again; by then the jump has happened.
+            if (!focusable.hasAttribute("tabindex") && !isFocusable(focusable)) {
+                setAttr(focusable, "tabindex", "-1");
+            }
+            focusable.focus();
+            // Without `behavior`: the page's own `scroll-behavior` decides. The
+            // browser does not turn off `smooth` by itself under
+            // `prefers-reduced-motion`, so that is up to the page, and "Accessibility"
+            // in the documentation says so.
+            focusable.scrollIntoView({ block: "center" });
+        };
+    }
+    connectedCallback() {
+        // One listener on the host, not one per link. The set of links was only
+        // emptied on disconnect, so every link a patch replaced stayed in
+        // memory.
+        this.addEventListener("click", this.handleLinkClick);
+        // The errors come and go while the user corrects them, and `slotchange`
+        // does not fire in plain DOM. The attributes are the ones the component
+        // fills in itself, so a patch that removes them gets them back. Every
+        // write compares first, or the observer would trigger itself.
+        this.observer = new MutationObserver(() => this.sync());
+        this.observer.observe(this, {
+            childList: true,
+            subtree: true,
+            attributes: true,
+            attributeFilter: ["class", "role", "tabindex"],
+        });
+        this.sync();
+    }
+    attributeChangedCallback() {
+        // The server can send the box hidden and later only remove `hidden` on
+        // the same node. Without this, a summary that just became visible never
+        // gets focus, and that is the whole reason the component exists.
+        if (this.isConnected)
+            this.sync();
+    }
+    disconnectedCallback() {
+        this.observer?.disconnect();
+        this.observer = undefined;
+        this.removeEventListener("click", this.handleLinkClick);
+    }
+    /**
+     * Whether the box takes focus when it becomes visible. Default: yes.
+     *
+     * The attribute is called `data-autofocus` and not `autofocus`, even
+     * though the latter reads better. `autofocus` is a boolean property on
+     * `HTMLElement`, and React 19 sets properties rather than attributes on web
+     * components. `autofocus="false"` then became `el.autofocus = "false"`,
+     * which is true, while the attribute never reached the markup, and the
+     * opt-out did not work. `data-*` is passed on as an attribute in every
+     * React version.
+     */
+    get shouldFocus() {
+        return this.dataset.autofocus !== "false";
+    }
+    /**
+     * Fills in what a template without JavaScript did not write. Only what is
+     * missing: a role the server chose stays, and so does a `tabindex`.
+     */
+    wire() {
+        addClass(this, ERROR_SUMMARY_CLASS);
+        if (!this.hasAttribute("role"))
+            setAttr(this, "role", "alert");
+        // Without `tabindex`, `focus()` does nothing, and the whole reason for
+        // the component silently disappears.
+        if (!this.hasAttribute("tabindex"))
+            setAttr(this, "tabindex", "-1");
+        const title = this.querySelector(LT_ERROR_SUMMARY_PARTS.title);
+        if (title)
+            addClass(title, ERROR_SUMMARY_TITLE_CLASS);
+    }
+    sync() {
+        this.wire();
+        const links = [
+            ...this.querySelectorAll(LT_ERROR_SUMMARY_PARTS.link),
+        ];
+        // If the server hides the box again, that submission is over. Without
+        // this reset the box only took focus the first time: the pattern in a
+        // Datastar app is that the list keeps the same links throughout and only
+        // `hidden` is toggled, so "have I moved focus here before" does not
+        // answer whether this is a new submission. It comes before the return
+        // for an empty list: React removes the items before it sets `hidden` on
+        // the host, so the list is already empty in the round where the box is
+        // hidden.
+        if (this.hidden) {
+            this.hasFocused = false;
+            this.focusAttempted = false;
+        }
+        if (links.length === 0) {
+            // The flags are not reset by an empty list, only by `hidden` above. A
+            // visible list that is emptied and filled while the user corrects
+            // would otherwise pull focus out of the field they were in.
+            warnAboutMarkup(this, "found no links to the fields. Each item needs an <a " +
+                'href="#id"> pointing to the control or its label, or the user ' +
+                "cannot get from the error to the field.", 
+            // An empty box is not an error: the pattern is that the server leaves
+            // it with `hidden` and fills it when the submission fails. A box with
+            // items but no links to the fields is something else.
+            () => this.querySelector("li") !== null &&
+                this.querySelector(LT_ERROR_SUMMARY_PARTS.link) === null);
+            return;
+        }
+        for (const link of links) {
+            /*
+             * A link that leads nowhere, reported here and not only on a click.
+             *
+             * The check used to be only in the click handler, and then a box with a
+             * link to a field that does not exist was completely silent until
+             * someone actually followed it. An error summary is read by someone who
+             * just failed with a form, and a link that does not work is exactly
+             * what makes the box worthless. The id is in the message, and each link
+             * has its own, so a box with two broken links reports both.
+             */
+            const id = link.getAttribute("href")?.slice(1);
+            if (id) {
+                warnAboutMarkup(this, `the link points to #${id}, but no element has that id. The link scrolls nowhere, and focus stays where it is.`, () => this.resolveTarget(id) === null);
+            }
+        }
+        if (this.hidden)
+            return;
+        // If the box is visible now and we have not moved focus here yet, it is
+        // this submission that failed. The flag is only set when focus actually
+        // landed: if the box is in a hidden panel or a closed dialog, `focus()`
+        // does nothing, and the next attempt is then allowed, as long as nobody
+        // is in a field.
+        if (this.shouldFocus && !this.hasFocused) {
+            // `document.activeElement` and not the root's: if the box is in a
+            // shadow root and the field in plain DOM, the root's `activeElement` is
+            // null, and the user would have counted as "nobody". The document's
+            // points to the shadow host when focus is in a shadow tree, and is
+            // never null for a field on the page.
+            const active = document.activeElement;
+            const nobodyTyping = !active || active === document.body;
+            if (this.focusAttempted && !nobodyTyping)
+                return;
+            const root = this.getRootNode();
+            this.focusAttempted = true;
+            this.focus();
+            this.hasFocused = root.activeElement === this;
+            if (this.hasFocused &&
+                root === document &&
+                active &&
+                active !== document.body)
+                this.reclaimFocusFrom(active);
+        }
+    }
+    /**
+     * Takes focus back once, if it went back to where it was.
+     *
+     * React gives focus back to the element that had it before a commit, right
+     * after the DOM has changed. The box moves focus as `hidden` is removed or
+     * as it is connected, that is inside the same commit, so focus ended up on
+     * the submit button again in Chromium and Firefox, and on the field in all
+     * three engines when the form was submitted with Enter. A microtask runs
+     * after the commit. If focus is then on the same element as before, the
+     * framework took it, and the box takes it again. If a script has moved
+     * focus somewhere else, it stays.
+     *
+     * Only when the box is directly in the document. React does not enter a
+     * shadow root when it restores focus, and there `document.activeElement`
+     * is the shadow host both before and after, so the comparison would take
+     * focus from a field in the same root. The condition is deliberately
+     * coarse: a box portalled into a shadow root from a React app in plain DOM
+     * does not take focus back.
+     */
+    reclaimFocusFrom(previous) {
+        queueMicrotask(() => {
+            if (this.isConnected &&
+                !this.hidden &&
+                document.activeElement === previous)
+                this.focus();
+        });
+    }
+    /**
+     * The element a link points to.
+     *
+     * The lookup goes to the root the component is in, not to `document`. If
+     * the form is in a shadow root, as in a preview or inside another
+     * component, `document.getElementById` finds nothing, and the link becomes
+     * a plain anchor link without moving focus.
+     */
+    resolveTarget(raw) {
+        const root = this.getRootNode();
+        // A link to a field with non-ASCII characters in its id is often
+        // percent-encoded, `#f%C3%B8dselsdato`. The browser decodes it when the
+        // link is followed, so the lookup must do the same, or a working link is
+        // reported.
+        for (const id of new Set([raw, decodeFragment(raw)])) {
+            const target = root.getElementById?.(id) ?? document.getElementById(id);
+            if (target)
+                return target;
+        }
+        return null;
+    }
+}
+LtErrorSummary.observedAttributes = ["data-autofocus", "hidden"];
+function isFocusable(element) {
+    return (element instanceof HTMLInputElement ||
+        element instanceof HTMLSelectElement ||
+        element instanceof HTMLTextAreaElement ||
+        element instanceof HTMLButtonElement ||
+        element instanceof HTMLAnchorElement);
+}
+export function defineLtErrorSummary(tagName = LT_ERROR_SUMMARY_TAG) {
+    defineElement(tagName, LtErrorSummary);
+}
+//# sourceMappingURL=lt-error-summary.js.map

package/dist/components/frame/error-summary/lt-error-summary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lt-error-summary.js","sourceRoot":"","sources":["../../../../src/components/frame/error-summary/lt-error-summary.ts"],"names":[],"mappings":"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"}

package/dist/components/frame/field/field-core.d.ts

@@ -0,0 +1,92 @@
+import type { FieldState, RequiredMarker } from "../../css/shared.js";
+import { createFieldId } from "../../css/shared.js";
+export { createFieldId };
+/**
+ * Computes the wiring between label, field, help text and error text.
+ *
+ * This is the one implementation of the accessibility contract in the system.
+ * `<lt-field>` applies it to elements already in the DOM, and `lt.field()`
+ * returns the same result as data, for whoever writes the markup with
+ * JavaScript. Without sharing it, the contract would exist in two places and
+ * could drift apart.
+ */
+export type FieldOptions = {
+    /**
+     * The id of the control. Required.
+     *
+     * In React it comes from `useId()`. Otherwise the field's name is usually
+     * the obvious choice. If you know for certain that the markup is rendered
+     * once, call `createFieldId()` yourself.
+     *
+     * It used to be optional, and the function created one when it was
+     * missing. That id is random, so two runs give two different ones, and if
+     * the same field is rendered on a server and then in the browser, `for`
+     * and `aria-describedby` point to something other than what is there.
+     * React reports a mismatch on hydration, and the warning itself says the
+     * mismatch is not repaired.
+     *
+     * The type requires it, and that is not enough on its own: a consumer
+     * without TypeScript sees no type. If the id is left out anyway, the
+     * function creates one and says so in the console. The field then works,
+     * and the developer learns why the id should be given anyway. Without the
+     * fallback they got `for=""`, `aria-describedby="undefined-help"` and no
+     * wiring at all, which is worse than the unstable id the requirement was
+     * meant to remove.
+     */
+    id: string;
+    /** The field has a help text to connect with `aria-describedby`. */
+    help?: boolean;
+    /** The field has an error text. It is hidden until the field is invalid. */
+    error?: boolean;
+    /** A separate id for the help text. Derived from `id` if left out. */
+    helpId?: string;
+    /** A separate id for the error text. Derived from `id` if left out. */
+    errorId?: string;
+    /** Marks the label as required. */
+    required?: RequiredMarker;
+    /** Marks the label as optional. */
+    optional?: boolean;
+    /** The field is invalid: shows the error text and sets `aria-invalid`. */
+    invalid?: boolean;
+    /** The control is disabled. */
+    disabled?: boolean;
+    /** Extra ids to include in `aria-describedby`. */
+    describedBy?: string[];
+};
+export type FieldAttributes = {
+    label: {
+        class: "lt-label";
+        for: string;
+        "data-required"?: RequiredMarker;
+        "data-optional"?: "";
+        "aria-disabled"?: "true";
+    };
+    control: {
+        id: string;
+        "aria-describedby"?: string;
+        "aria-invalid"?: "true";
+        "data-state"?: "invalid";
+        disabled?: true;
+    };
+    help: {
+        id: string;
+    };
+    error: {
+        id: string;
+        hidden?: true;
+    };
+    /** The state the control should have, for `input()`, `textarea()` and `select()`. */
+    state: FieldState;
+};
+/**
+ * Joins `aria-describedby` from the help text, the error text and whatever
+ * the caller added.
+ *
+ * The error text is only included when the field is actually invalid.
+ * Otherwise `aria-describedby` would point to a hidden element, and screen
+ * readers then announce either nothing or something that is not on the
+ * screen.
+ */
+export declare function joinDescribedBy(ids: Array<string | undefined | false>): string | undefined;
+export declare function computeFieldAttributes(options: FieldOptions): FieldAttributes;
+//# sourceMappingURL=field-core.d.ts.map

package/dist/components/frame/field/field-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-core.d.ts","sourceRoot":"","sources":["../../../../src/components/frame/field/field-core.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACrE,OAAO,EAAc,aAAa,EAAgB,MAAM,qBAAqB,CAAA;AAI7E,OAAO,EAAE,aAAa,EAAE,CAAA;AAExB;;;;;;;;GAQG;AAEH,MAAM,MAAM,YAAY,GAAG;IACzB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,EAAE,EAAE,MAAM,CAAA;IACV,oEAAoE;IACpE,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,4EAA4E;IAC5E,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,mCAAmC;IACnC,QAAQ,CAAC,EAAE,cAAc,CAAA;IACzB,mCAAmC;IACnC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;CACvB,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,EAAE;QACL,KAAK,EAAE,UAAU,CAAA;QACjB,GAAG,EAAE,MAAM,CAAA;QACX,eAAe,CAAC,EAAE,cAAc,CAAA;QAChC,eAAe,CAAC,EAAE,EAAE,CAAA;QACpB,eAAe,CAAC,EAAE,MAAM,CAAA;KACzB,CAAA;IACD,OAAO,EAAE;QACP,EAAE,EAAE,MAAM,CAAA;QACV,kBAAkB,CAAC,EAAE,MAAM,CAAA;QAC3B,cAAc,CAAC,EAAE,MAAM,CAAA;QACvB,YAAY,CAAC,EAAE,SAAS,CAAA;QACxB,QAAQ,CAAC,EAAE,IAAI,CAAA;KAChB,CAAA;IACD,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAA;IACpB,KAAK,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,IAAI,CAAA;KAAE,CAAA;IACpC,qFAAqF;IACrF,KAAK,EAAE,UAAU,CAAA;CAClB,CAAA;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,KAAK,CAAC,MAAM,GAAG,SAAS,GAAG,KAAK,CAAC,GACrC,MAAM,GAAG,SAAS,CASpB;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,YAAY,GAAG,eAAe,CA+C7E"}

package/dist/components/frame/field/field-core.js

@@ -0,0 +1,63 @@
+import { attributes, createFieldId, idOrFallback } from "../../css/shared.js";
+// Re-exported here, where it used to live, so consumers that import from
+// `./field-core` do not notice the move.
+export { createFieldId };
+/**
+ * Joins `aria-describedby` from the help text, the error text and whatever
+ * the caller added.
+ *
+ * The error text is only included when the field is actually invalid.
+ * Otherwise `aria-describedby` would point to a hidden element, and screen
+ * readers then announce either nothing or something that is not on the
+ * screen.
+ */
+export function joinDescribedBy(ids) {
+    const unique = new Set();
+    for (const id of ids) {
+        if (!id)
+            continue;
+        for (const part of id.split(/\s+/)) {
+            if (part)
+                unique.add(part);
+        }
+    }
+    return unique.size > 0 ? [...unique].join(" ") : undefined;
+}
+export function computeFieldAttributes(options) {
+    const { id: givenId, help = false, error = false, required, optional, invalid = false, disabled = false, describedBy = [], } = options;
+    // The fallback is only for callers without a type check. See `idOrFallback`.
+    const id = idOrFallback("lt.field()", givenId);
+    const helpId = options.helpId ?? `${id}-help`;
+    const errorId = options.errorId ?? `${id}-error`;
+    return {
+        label: attributes({
+            class: "lt-label",
+            for: id,
+            "data-required": required,
+            "data-optional": optional && !required ? "" : undefined,
+            "aria-disabled": disabled ? "true" : undefined,
+        }),
+        control: attributes({
+            id,
+            "aria-describedby": joinDescribedBy([
+                help && helpId,
+                invalid && error && errorId,
+                ...describedBy,
+            ]),
+            "aria-invalid": invalid ? "true" : undefined,
+            // The colour comes from here, not from input()/textarea()/select().
+            // Otherwise both would set aria-invalid, and in templates that write
+            // the attributes out literally, such as Astro and plain HTML, it
+            // appeared twice.
+            "data-state": invalid ? "invalid" : undefined,
+            disabled: disabled ? true : undefined,
+        }),
+        help: attributes({ id: helpId }),
+        error: attributes({
+            id: errorId,
+            hidden: invalid ? undefined : true,
+        }),
+        state: invalid ? "invalid" : "default",
+    };
+}
+//# sourceMappingURL=field-core.js.map

package/dist/components/frame/field/field-core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-core.js","sourceRoot":"","sources":["../../../../src/components/frame/field/field-core.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAE7E,yEAAyE;AACzE,yCAAyC;AACzC,OAAO,EAAE,aAAa,EAAE,CAAA;AA6ExB;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAC7B,GAAsC;IAEtC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAA;IAChC,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;QACrB,IAAI,CAAC,EAAE;YAAE,SAAQ;QACjB,KAAK,MAAM,IAAI,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;YACnC,IAAI,IAAI;gBAAE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QAC5B,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;AAC5D,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,OAAqB;IAC1D,MAAM,EACJ,EAAE,EAAE,OAAO,EACX,IAAI,GAAG,KAAK,EACZ,KAAK,GAAG,KAAK,EACb,QAAQ,EACR,QAAQ,EACR,OAAO,GAAG,KAAK,EACf,QAAQ,GAAG,KAAK,EAChB,WAAW,GAAG,EAAE,GACjB,GAAG,OAAO,CAAA;IAEX,6EAA6E;IAC7E,MAAM,EAAE,GAAG,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAA;IAC9C,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,GAAG,EAAE,OAAO,CAAA;IAC7C,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,GAAG,EAAE,QAAQ,CAAA;IAEhD,OAAO;QACL,KAAK,EAAE,UAAU,CAAC;YAChB,KAAK,EAAE,UAAmB;YAC1B,GAAG,EAAE,EAAE;YACP,eAAe,EAAE,QAAQ;YACzB,eAAe,EAAE,QAAQ,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAE,EAAY,CAAC,CAAC,CAAC,SAAS;YAClE,eAAe,EAAE,QAAQ,CAAC,CAAC,CAAE,MAAgB,CAAC,CAAC,CAAC,SAAS;SAC1D,CAAC;QACF,OAAO,EAAE,UAAU,CAAC;YAClB,EAAE;YACF,kBAAkB,EAAE,eAAe,CAAC;gBAClC,IAAI,IAAI,MAAM;gBACd,OAAO,IAAI,KAAK,IAAI,OAAO;gBAC3B,GAAG,WAAW;aACf,CAAC;YACF,cAAc,EAAE,OAAO,CAAC,CAAC,CAAE,MAAgB,CAAC,CAAC,CAAC,SAAS;YACvD,oEAAoE;YACpE,qEAAqE;YACrE,iEAAiE;YACjE,kBAAkB;YAClB,YAAY,EAAE,OAAO,CAAC,CAAC,CAAE,SAAmB,CAAC,CAAC,CAAC,SAAS;YACxD,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAE,IAAc,CAAC,CAAC,CAAC,SAAS;SACjD,CAAC;QACF,IAAI,EAAE,UAAU,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC;QAChC,KAAK,EAAE,UAAU,CAAC;YAChB,EAAE,EAAE,OAAO;YACX,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAE,IAAc;SAC9C,CAAC;QACF,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS;KACvC,CAAA;AACH,CAAC"}