@lo-tek/interfaces 0.0.0 → 0.38.0

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"}

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

@@ -0,0 +1,173 @@
+import { HostElement } from "../../host-element.js";
+export declare const LT_FIELD_TAG: "lt-field";
+/**
+ * The parts the field 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_FIELD_PARTS: {
+    readonly label: "label";
+    readonly control: "input:not([type='hidden']), textarea, select";
+    readonly help: ".lt-help-text";
+    readonly error: ".lt-error-text";
+};
+/**
+ * Connects label, control, help text and error text in plain DOM.
+ *
+ * The component is for markup produced without JavaScript: a Go template, a
+ * PHP file, a Razor view or handwritten HTML. When the markup is written with
+ * JavaScript, wherever the code runs, `lt.field()` should write the
+ * attributes instead, and this element is not needed.
+ *
+ * The component renders nothing. It used to insert a `<slot>` element into
+ * plain DOM, and since the server did not know about it, Datastar's morph
+ * removed it on every patch.
+ *
+ * The template writes what HTML requires for the field to work without
+ * JavaScript: `for` on the label and `id` on the control, or the label
+ * wrapping the control. The component writes the rest: the ids of the help
+ * text and the error text, `aria-describedby`, `aria-invalid` and the
+ * classes. If a morph removes them, the component sees it and sets them back.
+ *
+ * The component never writes an id on the control. Datastar and idiomorph
+ * recognise a node by its id, and a control with an id the server did not
+ * send is replaced on the next update, along with focus and what the user
+ * has typed.
+ *
+ * The field is invalid when the error text is visible, that is when it has
+ * no `hidden`, or when the server has written `aria-invalid` on the control.
+ * There is no separate state on the host: a template renders the error text
+ * when the field is invalid, and client code toggles `hidden`.
+ */
+export declare class LtField extends HostElement {
+    static observedAttributes: readonly ["disabled", "optional", "described-by"];
+    private observer?;
+    /**
+     * The ids the help text and the error text last had, whether they came
+     * from the markup or from here, so a patch that removes them gets the same
+     * one back and not a new one. `managedIds` is every id the component has
+     * ever managed. Together with whether the id still points to an element,
+     * that tells them apart from the ids the server put in `aria-describedby`.
+     */
+    private lastHelpId?;
+    private lastErrorId?;
+    private readonly managedIds;
+    /**
+     * What the component wrote on each control, keyed on the control itself.
+     *
+     * A `WeakMap` and not a "previous control" property. The memory has to
+     * survive the host being disconnected and connected again, as when React
+     * moves a field, and the control disappearing and coming back in a patch.
+     * A property that was reset in `disconnectedCallback` made the component
+     * read its own `aria-invalid="true"` as the server's word after a move, and
+     * the field could never become valid again. A `WeakMap` also keeps no
+     * detached node alive: when the control is gone for good, so is the memory.
+     */
+    private readonly memory;
+    private readonly labelMemory;
+    /** The `for` the component itself wrote on the label. */
+    private readonly forByMe;
+    /**
+     * Labels where the server wrote a `for` pointing to a different id than
+     * the control's. The component rewrites it, but without JavaScript the
+     * field had no label, so it must be reported, once. The memory is not
+     * reset: after the rewrite the right value is there, and it cannot be told
+     * apart from a server that corrected itself.
+     */
+    private readonly wrongFor;
+    /**
+     * The control last time.
+     *
+     * Enough to see that a server update replaced it because the id changed:
+     * Datastar and idiomorph recognise a node by its id, and a new id from the
+     * server is a new node to them. That happens when the template builds the
+     * id from something that changes between renders, such as a random number
+     * or a counter.
+     *
+     * A reference, not just an entry in `memory`: the replacement is detected
+     * by comparing it with the control that is there now, and what the old one
+     * contained must be readable after it has left the tree. It keeps one
+     * detached node alive until the next `sync()`, on purpose.
+     */
+    private lastControl?;
+    /** The controls where `data-state` was written by the component. */
+    private readonly stateByMe;
+    /**
+     * The properties mirror the attributes.
+     *
+     * The state lives in the attribute and not in a field on the class, so what
+     * the server sent and what the component thinks are always the same.
+     */
+    get disabled(): boolean;
+    set disabled(value: boolean);
+    get optional(): boolean;
+    set optional(value: boolean);
+    get describedBy(): string | undefined;
+    set describedBy(value: string | undefined);
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(): void;
+    /**
+     * The label the field belongs with.
+     *
+     * Usually it is inside the element. If it is outside, with `for` pointing
+     * to the control, the field is just as well named, and the component
+     * connects it the same way. One difference is worth knowing: a label
+     * outside is not in what the component observes, so if a patch removes its
+     * class, the class does not come back by itself.
+     */
+    /**
+     * Remembers whether the server wrote a `for` that was not the control's
+     * id. What the component itself wrote last does not count.
+     */
+    private noteFor;
+    private resolveLabel;
+    /**
+     * The server's word about the control, derived from what is there now
+     * compared with what the component itself wrote last.
+     *
+     * A control the component has never written on holds only the server's
+     * word. Otherwise each attribute is the server's if it differs from what
+     * the component wrote, and unchanged if it is the same.
+     */
+    private serverLabelWord;
+    private serverWord;
+    /**
+     * The parts that belong to this field, and not to a field further down.
+     *
+     * A field can be inside another: a search field in a popover inside the
+     * field, or an `<lt-field>` in an `<lt-field>`. `querySelector` over the
+     * whole subtree then found the innermost field's control first, and the
+     * outer field wrote its wiring on it. The scoping is the same as the one
+     * `derivedParts()` in `host-element.ts` uses for the other components.
+     */
+    private ownParts;
+    private ownPart;
+    /**
+     * Reports when an update replaced the control because the id from the
+     * server changed.
+     *
+     * The message only comes when the user had something to lose: the old
+     * control has left the tree, both had an id from the server, the ids
+     * differ, and the old one contained something other than the new one. A
+     * server that sends a different field on purpose usually also has a
+     * different label or a different `name`; then it stays silent. The
+     * comparison is with the new control, not with the old one's
+     * `defaultValue`: a `<select>` always has a selected option without any
+     * being `defaultSelected`, and a server that sends back the text the user
+     * typed has lost nothing.
+     */
+    private warnAboutReplacedControl;
+    /**
+     * Did the old control contain something other than the new one?
+     *
+     * A checkbox and a radio button have the same `value` either way, so there
+     * the checked state is what counts. A `<select>` is compared on the
+     * selected options, since `value` is only the first of them.
+     */
+    private differs;
+    private sync;
+}
+export declare function defineLtField(tagName?: string): void;
+//# sourceMappingURL=lt-field.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lt-field.d.ts","sourceRoot":"","sources":["../../../../src/components/frame/field/lt-field.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,WAAW,EASZ,MAAM,uBAAuB,CAAA;AAG9B,eAAO,MAAM,YAAY,EAAG,UAAmB,CAAA;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,cAAc;;;;;CAKjB,CAAA;AA6FV;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,OAAQ,SAAQ,WAAW;IACtC,MAAM,CAAC,kBAAkB,oDAAoD;IAE7E,OAAO,CAAC,QAAQ,CAAC,CAAkB;IACnC;;;;;;OAMG;IACH,OAAO,CAAC,UAAU,CAAC,CAAQ;IAC3B,OAAO,CAAC,WAAW,CAAC,CAAQ;IAC5B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;IAC/C;;;;;;;;;;OAUG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwC;IAC/D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsC;IAClE,yDAAyD;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IACzD;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;IAClD;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,WAAW,CAAC,CAAa;IACjC,oEAAoE;IACpE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;IAEnD;;;;;OAKG;IACH,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,IAAI,QAAQ,CAAC,KAAK,EAAE,OAAO,EAE1B;IAED,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,IAAI,QAAQ,CAAC,KAAK,EAAE,OAAO,EAE1B;IAED,IAAI,WAAW,IAAI,MAAM,GAAG,SAAS,CAEpC;IAED,IAAI,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAExC;IAED,iBAAiB,IAAI,IAAI;IAyCzB,oBAAoB,IAAI,IAAI;IAK5B,wBAAwB,IAAI,IAAI;IAIhC;;;;;;;;OAQG;IACH;;;OAGG;IACH,OAAO,CAAC,OAAO;IAMf,OAAO,CAAC,YAAY;IAYpB;;;;;;;OAOG;IACH,OAAO,CAAC,eAAe;IAqBvB,OAAO,CAAC,UAAU;IA2BlB;;;;;;;;OAQG;IACH,OAAO,CAAC,QAAQ;IAMhB,OAAO,CAAC,OAAO;IAIf;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,wBAAwB;IAyBhC;;;;;;OAMG;IACH,OAAO,CAAC,OAAO;IAqBf,OAAO,CAAC,IAAI;CAsUb;AAED,wBAAgB,aAAa,CAAC,OAAO,GAAE,MAAqB,GAAG,IAAI,CAElE"}