@lo-tek/interfaces 0.42.0 → 0.43.0

package/src/components/frame/error-summary/lt-error-summary.ts

@@ -2,8 +2,12 @@ import {
   addClass,
   defineElement,
   HostElement,
+  hasName,
+  nameFromHeading,
+  ownership,
   setAttr,
   warnAboutMarkup,
+  watcher,
 } from "../../host-element.js"
 import {
   ERROR_SUMMARY_CLASS,
@@ -82,28 +86,18 @@ export class LtErrorSummary extends HostElement {
   private focusAttempted = false
   /** Where focus was when `hidden` last changed, until the deferred round has run. */
   private focusBefore: Element | null | undefined
-  private observer?: MutationObserver
   /**
-   * The `aria-labelledby` the component wrote on the box, or null. Another
-   * value there is the server's, and stays; the component's own follows the
-   * heading, so a patch that replaces the heading does not leave the name
-   * pointing at an id that is gone.
+   * The `aria-labelledby` the component wrote on the box, through
+   * `nameFromHeading()`.
    */
-  private labelledByWritten: string | null = null
-
-  connectedCallback(): void {
-    // 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.
-    // An id only matters on the heading, which the name points at, and a
-    // name only on the box. The same attributes on a link or a field inside
-    // the box are not ours to follow.
-    this.observer = new MutationObserver((records) => {
+  private readonly own = ownership()
+  /**
+   * An id only matters on the heading, which the name points at, and a name
+   * only on the box. The same attributes on a link or a field inside the box
+   * are not ours to follow.
+   */
+  private readonly watch = watcher(
+    (records) => {
       const relevant = records.some((r) => {
         if (r.attributeName === "id")
           return (r.target as Element).matches(LT_ERROR_SUMMARY_PARTS.title)
@@ -115,8 +109,8 @@ export class LtErrorSummary extends HostElement {
         return true
       })
       if (relevant) this.sync()
-    })
-    this.observer.observe(this, {
+    },
+    {
       childList: true,
       subtree: true,
       attributes: true,
@@ -128,7 +122,19 @@ export class LtErrorSummary extends HostElement {
         "aria-label",
         "id",
       ],
-    })
+    },
+  )
+
+  connectedCallback(): void {
+    // 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.watch.start(this)
     this.sync()
   }
 
@@ -164,8 +170,7 @@ export class LtErrorSummary extends HostElement {
   }
 
   disconnectedCallback(): void {
-    this.observer?.disconnect()
-    this.observer = undefined
+    this.watch.stop()
     this.removeEventListener("click", this.handleLinkClick)
   }
 
@@ -212,32 +217,14 @@ export class LtErrorSummary extends HostElement {
      * nothing, so it counts as missing.
      * `check-accessibility-tree.ts` checks the name a screen reader gets.
      */
-    const labelledBy = this.getAttribute("aria-labelledby")?.trim() || null
-    const label = this.getAttribute("aria-label")?.trim() || null
-    const ours = labelledBy !== null && labelledBy === this.labelledByWritten
-    if (labelledBy !== null && !ours) this.labelledByWritten = null
-    if (title?.id && label === null && (labelledBy === null || ours)) {
-      setAttr(this, "aria-labelledby", title.id)
-      this.labelledByWritten = title.id
-    } else if (ours) {
-      // The heading is gone or lost its id, or the server named the box
-      // with `aria-label`, which `aria-labelledby` would otherwise win over.
-      this.removeAttribute("aria-labelledby")
-      this.labelledByWritten = null
-    }
-    if (title && !title.id && label === null && labelledBy === null)
+    const name = nameFromHeading(this.own, this, this, () => title?.id || null)
+    if (name === "none" && title && !title.id)
       warnAboutMarkup(
         this,
         "has a heading without an id and no name, so it takes focus as an alert a screen reader cannot name. Give the heading an id and the box aria-labelledby pointing at it, as lt.errorSummary({ id }) does.",
         () => {
           const now = this.querySelector(LT_ERROR_SUMMARY_PARTS.title)
-          return (
-            this.isConnected &&
-            now !== null &&
-            !now.id &&
-            !this.getAttribute("aria-label")?.trim() &&
-            !this.getAttribute("aria-labelledby")?.trim()
-          )
+          return this.isConnected && now !== null && !now.id && !hasName(this)
         },
       )
   }

package/src/components/frame/field/lt-field.ts

@@ -4,14 +4,14 @@ import {
   addClass,
   defineElement,
   HostElement,
-  markWritten,
+  ownership,
   setAttr,
   setFlag,
-  stillMarked,
   uniqueId,
   WRITTEN,
   warnAboutCopiedMark,
   warnAboutMarkup,
+  watcher,
 } from "../../host-element.js"
 import { computeFieldAttributes } from "./field-core.js"
 
@@ -69,58 +69,6 @@ const DERIVED_ATTRIBUTES = [
   "style",
 ]
 
-/**
- * What the component last wrote on a control, and what the server last said.
- *
- * Three attributes are both read from the control and written back to it:
- * `aria-invalid`, `aria-describedby` and `disabled`. They are read because
- * the server may have written the field with `lt.field()`, and then the
- * answer is already there. But a naive read is the component's echo from the
- * previous round. For `aria-invalid` that meant `field.invalid = false`
- * removed the flag on the host while the red border stayed for good. For
- * `aria-describedby` the list never shrank: the error text's id stayed after
- * the error was gone. For `disabled` the field could not be enabled again
- * from the host.
- *
- * The fix is not to remember what the host said last. That was tried, and
- * made the component depend on its history: the same markup gave two
- * different answers depending on whether the host had had `invalid` at some
- * point.
- *
- * Instead the component notes the value it wrote, and on which control. If
- * something else is there next time, someone else has touched the
- * attribute, and that is the server's word. The read is therefore always
- * derived from a change that actually happened, and the same document always
- * gives the same answer.
- */
-type ControlMemory = {
-  written: ControlWord
-  server: ControlWord
-}
-
-/**
- * The same memory for the markers on the label. The component both reads and
- * writes `data-required` and `data-optional`, and without knowing what it
- * wrote itself, it read its own answer back: `optional` and the required
- * marker could not be turned off again.
- */
-type LabelWord = { required: string | null; optional: boolean }
-type LabelMemory = { written: LabelWord; server: LabelWord }
-
-type ControlWord = {
-  invalid: string | null
-  describedBy: string | null
-  disabled: boolean
-}
-
-function readControlWord(control: Element): ControlWord {
-  return {
-    invalid: control.getAttribute("aria-invalid"),
-    describedBy: control.getAttribute("aria-describedby"),
-    disabled: control.hasAttribute("disabled"),
-  }
-}
-
 /**
  * Connects label, control, help text and error text in plain DOM.
  *
@@ -153,7 +101,31 @@ function readControlWord(control: Element): ControlWord {
 export class LtField extends HostElement {
   static observedAttributes = ["disabled", "optional", "described-by"] as const
 
-  private observer?: MutationObserver
+  /**
+   * The children and the derived attributes, watched while connected.
+   * `style` is observed for `display: none` on the error text; a style write
+   * elsewhere in the field, such as a popover positioning its panel, does not
+   * concern the wiring.
+   */
+  private readonly watch = watcher(
+    (records) => {
+      const onlyForeignStyle = records.every(
+        (r) =>
+          r.type === "attributes" &&
+          r.attributeName === "style" &&
+          !(r.target as Element).matches?.(LT_FIELD_PARTS.error),
+      )
+      if (!onlyForeignStyle) this.sync()
+    },
+    {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: DERIVED_ATTRIBUTES,
+      // A morph can change the text of the error text without replacing the node.
+      characterData: true,
+    },
+  )
   /**
    * 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
@@ -165,20 +137,17 @@ export class LtField extends HostElement {
   private lastErrorId?: string
   private readonly managedIds = new Set<string>()
   /**
-   * 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.
+   * What the component wrote on the control and the label, and the server's
+   * word it wrote against, per node. 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
+   * 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. The component both reads and writes
+   * `data-required` and `data-optional` on the label too, and without the
+   * memory `optional` and the required marker could not be turned off.
    */
-  private readonly memory = new WeakMap<Element, ControlMemory>()
-  private readonly labelMemory = new WeakMap<Element, LabelMemory>()
-  /** The `for` the component itself wrote on the label. */
-  private readonly forByMe = new WeakMap<Element, string>()
+  private readonly own = ownership()
   /**
    * Labels where the server wrote a `for` pointing to a different id than
    * the control's. The component rewrites it, but without JavaScript the
@@ -202,8 +171,6 @@ export class LtField extends HostElement {
    * detached node alive until the next `sync()`, on purpose.
    */
   private lastControl?: HTMLElement
-  /** The controls where `data-state` was written by the component. */
-  private readonly stateByMe = new WeakSet<Element>()
 
   /**
    * The properties mirror the attributes.
@@ -253,32 +220,12 @@ export class LtField extends HostElement {
      * Every write in `sync()` compares first. Without that the observer
      * would trigger itself forever.
      */
-    this.observer = new MutationObserver((records) => {
-      // `style` is observed for `display: none` on the error text. A style
-      // write elsewhere in the field, such as a popover positioning its
-      // panel, does not concern the wiring.
-      const onlyForeignStyle = records.every(
-        (r) =>
-          r.type === "attributes" &&
-          r.attributeName === "style" &&
-          !(r.target as Element).matches?.(LT_FIELD_PARTS.error),
-      )
-      if (!onlyForeignStyle) this.sync()
-    })
-    this.observer.observe(this, {
-      childList: true,
-      subtree: true,
-      attributes: true,
-      attributeFilter: DERIVED_ATTRIBUTES,
-      // A morph can change the text of the error text without replacing the node.
-      characterData: true,
-    })
+    this.watch.start(this)
     this.sync()
   }
 
   disconnectedCallback(): void {
-    this.observer?.disconnect()
-    this.observer = undefined
+    this.watch.stop()
   }
 
   attributeChangedCallback(): void {
@@ -301,7 +248,7 @@ export class LtField extends HostElement {
   private noteFor(label: Element, id: string): void {
     const current = label.getAttribute("for")
     if (current === null || current === id) return
-    if (current !== this.forByMe.get(label)) this.wrongFor.add(label)
+    if (current !== this.own.written(label, "for")) this.wrongFor.add(label)
   }
 
   private resolveLabel(control: HTMLElement | null): HTMLLabelElement | null {
@@ -316,62 +263,6 @@ export class LtField extends HostElement {
     )
   }
 
-  /**
-   * 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(label: Element | null): LabelWord {
-    if (!label) return { required: null, optional: false }
-    const now: LabelWord = {
-      required: label.getAttribute("data-required"),
-      optional: label.hasAttribute("data-optional"),
-    }
-    const known = this.labelMemory.get(label)
-    if (!known) return now
-
-    const spoke = (name: string, changed: boolean) =>
-      changed || !stillMarked(label, name)
-    return {
-      required: spoke("data-required", now.required !== known.written.required)
-        ? now.required
-        : known.server.required,
-      optional: spoke("data-optional", now.optional !== known.written.optional)
-        ? now.optional
-        : known.server.optional,
-    }
-  }
-
-  private serverWord(control: Element, now: ControlWord): ControlWord {
-    const known = this.memory.get(control)
-    if (!known) {
-      warnAboutCopiedMark(this, control)
-      return now
-    }
-
-    // The server's when the value is another, or when a morph from the
-    // server has been there since the component wrote it (`WRITTEN`).
-    const spoke = (name: string, changed: boolean) =>
-      changed || !stillMarked(control, name)
-    return {
-      invalid: spoke("aria-invalid", now.invalid !== known.written.invalid)
-        ? now.invalid
-        : known.server.invalid,
-      describedBy: spoke(
-        "aria-describedby",
-        now.describedBy !== known.written.describedBy,
-      )
-        ? now.describedBy
-        : known.server.describedBy,
-      disabled: spoke("disabled", now.disabled !== known.written.disabled)
-        ? now.disabled
-        : known.server.disabled,
-    }
-  }
-
   /**
    * The parts that belong to this field, and not to a field further down.
    *
@@ -471,11 +362,8 @@ export class LtField extends HostElement {
         "found no control to connect. Add an <input>, <textarea> or " +
           "<select>, or the label, help text and error text have no field " +
           "to be connected to.",
-        // An empty element is a region the server has not filled yet, and
-        // that is not an error in the markup.
-        () =>
-          this.childElementCount > 0 &&
-          this.ownParts(CONTROL_SELECTOR).length === 0,
+        () => this.ownParts(CONTROL_SELECTOR).length === 0,
+        { silentWhenEmpty: true },
       )
       return
     }
@@ -604,16 +492,33 @@ export class LtField extends HostElement {
     // looked at its own attributes would remove them again. In React that
     // gave a hydration error: the server sent `data-required="symbol"`, the
     // component removed it, and then React decided the HTML did not match.
-    const serverLabel = this.serverLabelWord(label)
+    const serverLabel = {
+      required: label ? this.own.serverWord(label, "data-required") : null,
+      optional: label
+        ? this.own.serverWord(label, "data-optional", { presence: true }) !==
+          null
+        : false,
+    }
     const marker = readMarker(serverLabel.required)
 
     // The state is read from the markup, not just from an attribute on the
     // host. If the server wrote the field with `lt.field()`, the answer is
     // already on the control, and a component that computed its own would
-    // remove it again. The two halves of the API then fought each other. See
-    // `ControlMemory` for how the server's word is told apart from what the
-    // component wrote.
-    const server = this.serverWord(control, readControlWord(control))
+    // remove it again. The two halves of the API then fought each other.
+    // `ownership()` in host-element.ts tells the server's word apart from
+    // what the component wrote: by the value and the node it wrote it on,
+    // never by what the host said last, which gave two answers for the same
+    // markup depending on what the host had been through.
+    // A control the component has never written on holds only the server's
+    // word, and a mark found there was copied into the template.
+    if (!this.own.knows(control, "aria-invalid"))
+      warnAboutCopiedMark(this, control)
+    const server = {
+      invalid: this.own.serverWord(control, "aria-invalid"),
+      describedBy: this.own.serverWord(control, "aria-describedby"),
+      disabled:
+        this.own.serverWord(control, "disabled", { flag: true }) !== null,
+    }
 
     // `aria-invalid` has four valid values, and both `grammar` and
     // `spelling` mean invalid. Absence, `false` and the empty string mean
@@ -693,29 +598,24 @@ export class LtField extends HostElement {
       // the wiring is implicit.
       if (control.id && !label.contains(control)) {
         this.noteFor(label, control.id)
-        setAttr(label, "for", control.id)
-        this.forByMe.set(label, control.id)
-      }
-      setAttr(label, "data-required", computed.label["data-required"])
-      setAttr(label, "data-optional", computed.label["data-optional"])
-      const writtenLabel: LabelWord = {
-        required: computed.label["data-required"] ?? null,
-        optional: computed.label["data-optional"] !== undefined,
+        this.own.write(label, "for", control.id)
       }
-      markWritten(
+      this.own.write(
         label,
         "data-required",
-        writtenLabel.required !== serverLabel.required,
+        computed.label["data-required"] ?? null,
+        { server: serverLabel.required, mark: true },
       )
-      markWritten(
+      this.own.write(
         label,
         "data-optional",
-        writtenLabel.optional !== serverLabel.optional,
+        computed.label["data-optional"] ?? null,
+        {
+          server: serverLabel.optional ? "" : null,
+          mark: true,
+          presence: true,
+        },
       )
-      this.labelMemory.set(label, {
-        written: writtenLabel,
-        server: serverLabel,
-      })
       setAttr(label, "aria-disabled", computed.label["aria-disabled"])
     }
 
@@ -730,8 +630,16 @@ export class LtField extends HostElement {
         ? "true"
         : server.invalid
 
-    setAttr(control, "aria-describedby", computed.control["aria-describedby"])
-    setAttr(control, "aria-invalid", ariaInvalid)
+    this.own.write(
+      control,
+      "aria-describedby",
+      computed.control["aria-describedby"] ?? null,
+      { server: server.describedBy, mark: true },
+    )
+    this.own.write(control, "aria-invalid", ariaInvalid, {
+      server: server.invalid,
+      mark: true,
+    })
     // `setFlag` and not `setAttr`: a template may have written
     // `disabled="disabled"`, and it must stay as it is. `setAttr` would
     // normalise the value to the empty string, and since `disabled` is among
@@ -739,33 +647,18 @@ export class LtField extends HostElement {
     // would each write their own value on every patch. No `aria-disabled`
     // alongside it: a real `disabled` is already visible to assistive
     // technology, and `computeFieldAttributes` only writes it on the label.
-    setFlag(control, "disabled", disabled)
-    const written: ControlWord = {
-      invalid: ariaInvalid,
-      describedBy: computed.control["aria-describedby"] ?? null,
-      disabled,
-    }
-    markWritten(control, "aria-invalid", written.invalid !== server.invalid)
-    markWritten(
-      control,
-      "aria-describedby",
-      written.describedBy !== server.describedBy,
-    )
-    markWritten(control, "disabled", written.disabled !== server.disabled)
-
-    this.memory.set(control, {
-      written: {
-        invalid: written.invalid,
-        describedBy: written.describedBy,
-        disabled: written.disabled,
-      },
-      server,
+    this.own.write(control, "disabled", disabled ? "" : null, {
+      server: server.disabled ? "" : null,
+      mark: true,
+      flag: true,
     })
 
     // `data-state` is only set on the system's controls, and only when the
-    // consumer has not set it. It is only removed when the component set it
-    // and the field is no longer invalid. A `data-state` a template wrote by
-    // hand stays as the template wrote it.
+    // consumer has not set it. It is only removed when the component set it,
+    // the field is no longer invalid, and the server has not sent the same
+    // value since: written with the mark, so a morph that sent it removes
+    // the mark. A `data-state` a template wrote by hand stays as the
+    // template wrote it.
     const isSystemField =
       control.classList.contains("lt-input") ||
       control.classList.contains("lt-textarea") ||
@@ -773,15 +666,14 @@ export class LtField extends HostElement {
 
     const state = computed.control["data-state"]
     if (state && isSystemField && !control.hasAttribute("data-state")) {
-      setAttr(control, "data-state", state)
-      this.stateByMe.add(control)
+      this.own.write(control, "data-state", state, { server: null, mark: true })
     } else if (
       !state &&
-      this.stateByMe.has(control) &&
-      control.getAttribute("data-state") === "invalid"
+      this.own.written(control, "data-state") != null &&
+      control.getAttribute("data-state") === "invalid" &&
+      this.own.serverWord(control, "data-state") === null
     ) {
-      control.removeAttribute("data-state")
-      this.stateByMe.delete(control)
+      this.own.release(control, "data-state")
     }
   }
 }

package/src/components/frame/popover/lt-popover.ts

@@ -8,6 +8,7 @@ import {
   setAttr,
   setFlag,
   warnAboutMarkup,
+  watcher,
 } from "../../host-element.js"
 import {
   isPopoverPlacement,
@@ -80,7 +81,35 @@ export class LtPopover extends HostElement {
 
   private panel?: HTMLElement
   private triggerElement?: HTMLElement
-  private observer?: MutationObserver
+  private readonly watch = watcher(
+    (records) => {
+      // `type` concerns only the button. A password field in the panel that
+      // switches between `password` and `text` must not run all of `sync()`.
+      const onlyOtherTypes = records.every(
+        (record) =>
+          record.attributeName === "type" &&
+          record.target !== this.triggerElement,
+      )
+      if (!onlyOtherTypes) this.sync()
+    },
+    {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: [
+        "aria-expanded",
+        "style",
+        // The wiring the component fills in when the markup came without it.
+        "popover",
+        "id",
+        "aria-controls",
+        "class",
+        // A patch from a template without `type` removes it, and then the
+        // button submits the form again.
+        "type",
+      ],
+    },
+  )
   /**
    * What the component was last asked for, through the `open` property.
    *
@@ -133,33 +162,7 @@ export class LtPopover extends HostElement {
      * out, so if a patch removes them, they must come back. Every write in
      * `sync()` compares first, or the observer would trigger itself.
      */
-    this.observer = new MutationObserver((records) => {
-      // `type` concerns only the button. A password field in the panel that
-      // switches between `password` and `text` must not run all of `sync()`.
-      const onlyOtherTypes = records.every(
-        (record) =>
-          record.attributeName === "type" &&
-          record.target !== this.triggerElement,
-      )
-      if (!onlyOtherTypes) this.sync()
-    })
-    this.observer.observe(this, {
-      childList: true,
-      subtree: true,
-      attributes: true,
-      attributeFilter: [
-        "aria-expanded",
-        "style",
-        // The wiring the component fills in when the markup came without it.
-        "popover",
-        "id",
-        "aria-controls",
-        "class",
-        // A patch from a template without `type` removes it, and then the
-        // button submits the form again.
-        "type",
-      ],
-    })
+    this.watch.start(this)
     this.sync()
   }
 
@@ -168,8 +171,7 @@ export class LtPopover extends HostElement {
     window.removeEventListener("scroll", this.reposition, true)
     document.removeEventListener("click", this.handleOutsideClick, true)
     document.removeEventListener("keydown", this.handleKeydown)
-    this.observer?.disconnect()
-    this.observer = undefined
+    this.watch.stop()
     this.triggerElement?.removeEventListener("click", this.handleTriggerClick)
     this.panel?.removeEventListener("toggle", this.handlePanelToggle)
     // The reference must be reset, or `sync()` sees that the button is the
@@ -269,16 +271,15 @@ export class LtPopover extends HostElement {
       /*
        * Two different faults, and a message for each, so the developer looks in
        * the right place. An empty element is a region the server has not filled
-       * yet, and that is not a fault in the markup.
+       * yet, and that is not a fault in the markup: `silentWhenEmpty`.
        */
-      const isEmpty = () => this.childElementCount === 0
-
       if (!panel) {
         warnAboutMarkup(
           this,
           "found no panel: an element with popover or the class " +
             "lt-popover. Without one there is nothing to open or position.",
-          () => !isEmpty() && this.findPanel() === null,
+          () => this.findPanel() === null,
+          { silentWhenEmpty: true },
         )
       } else {
         warnAboutMarkup(
@@ -288,8 +289,9 @@ export class LtPopover extends HostElement {
             "component does not know what opens the popover.",
           () => {
             const found = this.findPanel()
-            return !isEmpty() && found !== null && !this.findTrigger(found)
+            return found !== null && !this.findTrigger(found)
           },
+          { silentWhenEmpty: true },
         )
       }