@lo-tek/interfaces 0.41.0 → 0.43.0

package/src/components/host-element.ts

@@ -265,6 +265,295 @@ export function stillMarked(element: Element, name: string): boolean {
   return (element.getAttribute(WRITTEN) ?? "").split(/\s+/).includes(name)
 }
 
+/**
+ * What a web component wrote on a node, and what the server had said there.
+ *
+ * Some attributes are both the server's and the component's, and the
+ * component must read the server's word back without taking its own echo
+ * for it. The question was answered in seven ways across the components,
+ * and the model tests found bugs in five classes there. This is the rule
+ * for them to share, and field uses it: per node and attribute, the value
+ * the component wrote and the server's word it wrote it against. A
+ * `WeakMap`, so the memory survives the host being moved, and a node that is
+ * gone for good takes its memory with it.
+ */
+export interface Ownership {
+  /** Whether the component has written `name` on `element` before. */
+  knows(element: Element, name: string): boolean
+  /**
+   * The server's word for `name` on `element`: what stands there when the
+   * component has never written it, or when it differs from what the
+   * component wrote, or when a morph has removed the mark since; otherwise
+   * the server's word the component wrote against. With `presence` the
+   * attribute is compared by whether it is there, so `data-optional="true"`
+   * and `data-optional` are the same; a `flag` is compared so too.
+   */
+  serverWord(
+    element: Element,
+    name: string,
+    options?: { flag?: boolean; presence?: boolean },
+  ): string | null
+  /**
+   * Writes `value` for `name` on `element`, through `setAttr` or, for a
+   * `flag`, `setFlag`, and notes it against the server's word, compared by
+   * presence for a `flag` or with `presence`. With `mark`,
+   * the attribute is marked as the component's when the value differs from
+   * the server's, so a morph that removes the mark is seen as the server
+   * speaking.
+   */
+  write(
+    element: Element,
+    name: string,
+    value: string | null,
+    options?: {
+      /**
+       * The server's word the value was written against. Left out for an
+       * attribute the component never reads back as the server's, such as
+       * `for` written from the control's id: then nothing is remembered as
+       * the server's, and a later read sees what stands there.
+       */
+      server?: string | null
+      mark?: boolean
+      flag?: boolean
+      presence?: boolean
+    },
+  ): void
+  /** What the component last wrote for `name` on `element`, or `undefined`. */
+  written(element: Element, name: string): string | null | undefined
+  /**
+   * Forgets what the component wrote for `name` on `element`: the server has
+   * taken the attribute over, and the same value later is the server's. The
+   * mark goes too, so the markup does not say a value the server owns is
+   * the component's.
+   */
+  forget(element: Element, name: string): void
+  /**
+   * Removes `name` from `element` and forgets it in the same step, for an
+   * attribute the component wrote and no longer wants. Removing without
+   * forgetting left the component believing the attribute was its own, and
+   * it could later remove one the server had written.
+   */
+  release(element: Element, name: string, options?: { flag?: boolean }): void
+  /**
+   * Whether a morph from the server has been there since the component
+   * wrote `name` on `element`: it marked a value that differed from the
+   * server's word, and the mark is gone. A value that did not differ had no
+   * mark to lose, and its absence says nothing.
+   */
+  lost(element: Element, name: string): boolean
+}
+
+export function ownership(): Ownership {
+  const memory = new WeakMap<
+    Element,
+    Map<
+      string,
+      {
+        written: string | null
+        /** `undefined` when the write gave no server's word. */
+        server: string | null | undefined
+        marked: boolean
+        /** Compared by whether it is there, as the write said. */
+        presence: boolean
+      }
+    >
+  >()
+  // By presence, a value is "" when the attribute is there and null when not.
+  const byPresence = (value: string | null) => (value === null ? null : "")
+  const read = (element: Element, name: string, presence: boolean) =>
+    presence
+      ? byPresence(element.getAttribute(name))
+      : element.getAttribute(name)
+  return {
+    knows: (element, name) => Boolean(memory.get(element)?.has(name)),
+    serverWord(element, name, { flag, presence } = {}) {
+      const known = memory.get(element)?.get(name)
+      // The comparison the write used, so a read that forgets the option
+      // still knows the component's own echo.
+      const now = read(
+        element,
+        name,
+        known?.presence ?? Boolean(flag || presence),
+      )
+      if (!known || known.server === undefined) return now
+      // The server's when the value is another, or, for an attribute written
+      // with the mark, when a morph from the server has been there since
+      // (`WRITTEN`). Without the mark, only a value that differs from the
+      // component's own says the server spoke.
+      return now !== known.written ||
+        (known.marked && !stillMarked(element, name))
+        ? now
+        : known.server
+    },
+    write(element, name, value, { server, mark, flag, presence } = {}) {
+      if (flag) setFlag(element, name, value !== null)
+      else setAttr(element, name, value)
+      const compared = Boolean(flag || presence)
+      // Both sides in the same form, so `disabled="disabled"` from the
+      // server and the component's `disabled` are the same word.
+      const written = compared ? byPresence(value) : value
+      const said =
+        server === undefined
+          ? undefined
+          : compared
+            ? byPresence(server)
+            : server
+      // The mark says the value differs from the server's word, so without
+      // one there is nothing to mark against.
+      if (mark && said !== undefined)
+        markWritten(element, name, written !== said)
+      let attributes = memory.get(element)
+      if (!attributes) {
+        attributes = new Map()
+        memory.set(element, attributes)
+      }
+      attributes.set(name, {
+        written,
+        server: said,
+        marked: Boolean(mark),
+        presence: compared,
+      })
+    },
+    written: (element, name) => memory.get(element)?.get(name)?.written,
+    forget(element, name) {
+      if (memory.get(element)?.get(name)?.marked)
+        markWritten(element, name, false)
+      memory.get(element)?.delete(name)
+    },
+    release(element, name, { flag } = {}) {
+      if (flag) setFlag(element, name, false)
+      else setAttr(element, name, null)
+      if (memory.get(element)?.get(name)?.marked)
+        markWritten(element, name, false)
+      memory.get(element)?.delete(name)
+    },
+    lost(element, name) {
+      const known = memory.get(element)?.get(name)
+      return Boolean(
+        known?.marked &&
+          known.server !== undefined &&
+          known.written !== known.server &&
+          !stillMarked(element, name),
+      )
+    },
+  }
+}
+
+/**
+ * Whether `element` has a name from `aria-labelledby` or `aria-label`. A
+ * blank one names nothing. The rule `nameFromHeading()` reads by, for the
+ * warnings about an element without a name.
+ */
+export function hasName(element: Element): boolean {
+  return Boolean(
+    element.getAttribute("aria-labelledby")?.trim() ||
+      element.getAttribute("aria-label")?.trim(),
+  )
+}
+
+/**
+ * Names `element` from a heading with `aria-labelledby`, unless the server
+ * named it, and says how it is named.
+ *
+ * - `"server"`: an `aria-labelledby` the component did not write, or wrote
+ *   and the server has sent since. It stays, and the component forgets its
+ *   own.
+ * - `"label"`: the server gave an `aria-label`, which `aria-labelledby` would
+ *   otherwise win over. The component lets go of its own.
+ * - `"heading"`: `heading()` gave an id, and `aria-labelledby` points at it,
+ *   written with the mark, so a morph that sends the same id makes it the
+ *   server's. It follows a heading a patch replaced.
+ * - `"none"`: no name and no heading. The component lets go of its own, and
+ *   the caller says so with `warnAboutMarkup`.
+ *
+ * A blank `aria-labelledby` or `aria-label` names nothing, so it counts as
+ * missing. `heading()` is only called when the server has not named the
+ * element, so a caller that gives the heading an id does so only then.
+ * dialog, session-timeout and error-summary name themselves through it,
+ * and `host` is the web component that says so when the markup came with
+ * the mark copied in.
+ */
+export function nameFromHeading(
+  own: Ownership,
+  host: Element,
+  element: Element,
+  heading: () => string | null,
+): "server" | "label" | "heading" | "none" {
+  const NAME = "aria-labelledby"
+  if (!own.knows(element, NAME)) warnAboutCopiedMark(host, element)
+  const labelledBy = element.getAttribute(NAME)?.trim() || null
+  const label = element.getAttribute("aria-label")?.trim() || null
+  const ours =
+    labelledBy !== null &&
+    own.knows(element, NAME) &&
+    own.serverWord(element, NAME) === null
+  if (labelledBy !== null && !ours) {
+    own.forget(element, NAME)
+    return "server"
+  }
+  if (label !== null) {
+    if (ours) own.release(element, NAME)
+    return "label"
+  }
+  const id = heading()
+  if (!id) {
+    if (ours) own.release(element, NAME)
+    return "none"
+  }
+  own.write(element, NAME, id, { server: null, mark: true })
+  return "heading"
+}
+
+/**
+ * A `MutationObserver` a web component starts on a node and stops again.
+ *
+ * Started again on another node, it stops watching the old one first, so a
+ * node the server has replaced does not go on calling the component. field
+ * watches through it.
+ */
+export function watcher(
+  callback: (records: MutationRecord[]) => void,
+  init: MutationObserverInit,
+): {
+  start(target: Node): void
+  stop(): void
+  /** Whether it was started and not stopped since. */
+  readonly watching: boolean
+} {
+  let observer: MutationObserver | undefined
+  return {
+    get watching() {
+      return observer !== undefined
+    },
+    start(target) {
+      observer?.disconnect()
+      observer = new MutationObserver(callback)
+      observer.observe(target, init)
+    },
+    stop() {
+      observer?.disconnect()
+      observer = undefined
+    },
+  }
+}
+
+/**
+ * Puts `open` back on a `<dialog>` that is still in the top layer, when a
+ * morph took the attribute the server never sent, and says whether it did.
+ *
+ * The condition is `:modal` and not `open`: a dialog the user has closed
+ * leaves the top layer, and one a morph took `open` from stays there,
+ * invisible, with the rest of the page inert, and `close()` does nothing on
+ * it until the attribute is back.
+ */
+export function restoreModalOpen(
+  dialog: HTMLDialogElement | null | undefined,
+): boolean {
+  if (!dialog?.matches(":modal") || dialog.open) return false
+  setAttr(dialog, "open", "")
+  return true
+}
+
 /**
  * Turns a boolean attribute on or off, without writing when it is already so.
  *
@@ -382,14 +671,16 @@ export function derivedParts<T extends Element>(
   host: Element,
   selector: string,
   role: string,
-  roledByHost: WeakSet<Element>,
+  /** The `ownership()` the component wrote the roles through. */
+  roledByHost: Pick<Ownership, "written">,
 ): T[] {
+  const mine = (part: Element) => roledByHost.written(part, "role") === role
   const own = [...host.querySelectorAll<T>(selector)].filter(
     (part) => part.closest(host.localName) === host,
   )
   const bare = own
     .filter((part) => part.getAttribute("role") === role)
-    .every((part) => roledByHost.has(part))
+    .every(mine)
   return bare ? own : own.filter((part) => part.getAttribute("role") === role)
 }
 
@@ -456,6 +747,16 @@ export function warnAboutMarkup(
   element: Element,
   message: string,
   stillBroken: () => boolean,
+  {
+    silentWhenEmpty = false,
+  }: {
+    /**
+     * An element with no children is a region the server has not filled
+     * yet, which is not an error in the markup. field uses it, in place of
+     * `childElementCount > 0` in its `stillBroken`.
+     */
+    silentWhenEmpty?: boolean
+  } = {},
 ): void {
   if (typeof console === "undefined") return
   if (reported.get(element)?.has(message)) return
@@ -470,7 +771,9 @@ export function warnAboutMarkup(
 
   whenSettled(() => {
     pending.delete(message)
-    if (!element.isConnected || !stillBroken()) return
+    if (!element.isConnected) return
+    if (silentWhenEmpty && element.childElementCount === 0) return
+    if (!stillBroken()) return
 
     let said = reported.get(element)
     if (!said) {