@lo-tek/interfaces 0.0.0 → 0.37.0

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,EAKZ,MAAM,uBAAuB,CAAA;AAG9B,eAAO,MAAM,YAAY,EAAG,UAAmB,CAAA;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,cAAc;;;;;CAKjB,CAAA;AA0FV;;;;;;;;;;;;;;;;;;;;;;;;;;;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;IAoBlB;;;;;;;;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;CA+Sb;AAED,wBAAgB,aAAa,CAAC,OAAO,GAAE,MAAqB,GAAG,IAAI,CAElE"}