@lo-tek/interfaces 0.37.0 → 0.38.0

package/manifest/manifest.schema.json

@@ -24,6 +24,10 @@
       "type": "string",
       "description": "The version of @lo-tek/interfaces the manifest was written from."
     },
+    "textLanguage": {
+      "type": "string",
+      "description": "The language of the texts the components and stylesheets write themselves. lotek check warns about one of them on a page in another language."
+    },
     "elements": {
       "type": "object",
       "description": "Every <lt-…> element, with the attributes the component reads.",
@@ -51,6 +55,26 @@
               "$ref": "#/$defs/part"
             }
           },
+          "name": {
+            "$ref": "#/$defs/name"
+          },
+          "texts": {
+            "type": "object",
+            "description": "The texts the element writes itself, by their name in DEFAULT_TEXTS.",
+            "additionalProperties": {
+              "type": "object",
+              "required": ["text", "replacedBy"],
+              "properties": {
+                "text": { "type": "string" },
+                "replacedBy": {
+                  "type": "array",
+                  "description": "The attributes that replace the text. Any one of them is enough.",
+                  "items": { "type": "string" }
+                }
+              },
+              "additionalProperties": false
+            }
+          },
           "events": {
             "type": "object",
             "description": "The events the element dispatches. All of them bubble and cross shadow boundaries. Absent when the element dispatches nothing.",
@@ -104,6 +128,29 @@
             "type": "string",
             "description": "The class this one is part of, when it is only a part of another component's markup, like lt-card__title in lt-card. The parent has a part that matches it."
           },
+          "name": {
+            "$ref": "#/$defs/name"
+          },
+          "texts": {
+            "type": "array",
+            "description": "The texts the stylesheet shows on the element with the class and the attribute, and the CSS variable that replaces each.",
+            "items": {
+              "type": "object",
+              "required": ["variable", "text", "attribute"],
+              "properties": {
+                "variable": { "type": "string" },
+                "text": { "type": "string" },
+                "attribute": { "type": "string" },
+                "value": { "type": "string" },
+                "unless": {
+                  "type": "array",
+                  "description": "Attributes that keep the text from showing.",
+                  "items": { "type": "string" }
+                }
+              },
+              "additionalProperties": false
+            }
+          },
           "parts": {
             "type": "object",
             "description": "The parts the markup consists of, for the classes with a fixed structure, with the selector relative to the element with the class. Absent for the classes without one.",
@@ -505,6 +552,32 @@
         "optional": {
           "const": true,
           "description": "The element works without the part."
+        },
+        "stableId": {
+          "const": true,
+          "description": "The part needs an id from the server: the component never writes one."
+        },
+        "name": {
+          "$ref": "#/$defs/name"
+        }
+      },
+      "additionalProperties": false
+    },
+    "name": {
+      "type": "object",
+      "description": "A name LO-TEK demands where WAI-ARIA does not, or one the component gives itself. lotek check reports an element the markup gives no name.",
+      "properties": {
+        "after": {
+          "type": "string",
+          "description": "The part the component points aria-labelledby at when the markup has neither aria-label nor aria-labelledby."
+        },
+        "id": {
+          "const": true,
+          "description": "That part must have an id from the template: the component does not write one."
+        },
+        "component": {
+          "const": true,
+          "description": "The component names it itself, and no rule judges its name in the markup."
         }
       },
       "additionalProperties": false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lo-tek/interfaces",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "description": "Framework-agnostic design system: tokens, CSS components and web components.",
   "license": "MIT",
   "author": "August Søberg-Klyver",
@@ -367,6 +367,7 @@
     "typecheck": "tsc --noEmit",
     "typecheck:tests": "tsc --noEmit -p tsconfig.tests.json",
     "test:browser": "vitest --config vitest.config.ts --run",
+    "test:model": "vitest --config vitest.model.config.ts --run",
     "check:exports": "bun scripts/check-exports.ts",
     "check:server": "bun scripts/check-server-import.ts",
     "check:types": "bun scripts/check-types.ts",

package/src/components/default-texts.ts

@@ -16,6 +16,13 @@
  * read from an `--lt-` variable with the text as the fallback, and
  * `check-texts.ts` requires that.
  */
+/**
+ * The language the texts are in. `lotek check` warns about a component that
+ * shows one of them on a page in another language, without the attribute or
+ * CSS variable that replaces it.
+ */
+export const DEFAULT_LANGUAGE = "en"
+
 export const DEFAULT_TEXTS = {
   /** `aria-label` on the `<lt-toast>` region. Replaced with `label`. */
   toastRegion: "Notifications",

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

@@ -159,7 +159,9 @@ export class LtDialog extends HostElement {
       childList: true,
       subtree: true,
       attributes: true,
-      attributeFilter: ["class", "id", "aria-labelledby"],
+      // `aria-label` too: removed, the dialog is named after its title
+      // again, and without it here the dialog was left without a name.
+      attributeFilter: ["class", "id", "aria-labelledby", "aria-label"],
     })
     this.sync()
   }
@@ -284,7 +286,8 @@ export class LtDialog extends HostElement {
   }
 
   private notify(open: boolean, returnValue = ""): void {
-    if (open === this.lastNotified) return
+    // A dialog starts closed: one that never opened reported a close.
+    if (open === (this.lastNotified ?? false)) return
     this.lastNotified = open
     this.dispatchEvent(
       new CustomEvent("dialog-toggle", {

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

@@ -8,6 +8,13 @@ export type ErrorSummaryOptions = {
   count?: number
   /** The id of the box, so the form can move focus here after submission. */
   id?: string
+  /**
+   * The id of the heading. The box takes its name from it with
+   * `aria-labelledby`. Default: the box's `id` with `-title`, so the markup
+   * carries the wiring whenever the box has an id. An empty one counts as
+   * none; one with whitespace throws.
+   */
+  titleId?: string
 }
 
 export type ErrorSummaryAttributes = {
@@ -17,9 +24,11 @@ export type ErrorSummaryAttributes = {
     tabindex: "-1"
     id?: string
     hidden?: true
+    "aria-labelledby"?: string
   }
   title: {
     class: typeof ERROR_SUMMARY_TITLE_CLASS
+    id?: string
   }
 }
 
@@ -32,7 +41,11 @@ export type ErrorSummaryAttributes = {
  * every morph in Datastar.
  *
  * ```ts
- * const summary = lt.errorSummary({ count: errors.length, id: "errors" })
+ * const summary = lt.errorSummary({
+ *   count: errors.length,
+ *   id: "errors",
+ *   titleId: "errors-title",
+ * })
  * ```
  * ```html
  * <lt-error-summary {...summary.host}>
@@ -44,13 +57,34 @@ export type ErrorSummaryAttributes = {
 export const errorSummary = ({
   count = 0,
   id,
-}: ErrorSummaryOptions = {}): ErrorSummaryAttributes => ({
-  host: attributes({
-    class: ERROR_SUMMARY_CLASS,
-    role: "alert" as const,
-    tabindex: "-1" as const,
-    id,
-    hidden: count === 0 ? (true as const) : undefined,
-  }),
-  title: attributes({ class: ERROR_SUMMARY_TITLE_CLASS }),
-})
+  titleId: givenTitleId,
+}: ErrorSummaryOptions = {}): ErrorSummaryAttributes => {
+  /*
+   * The heading's id is written here, by whoever renders, never by the web
+   * component: Datastar and idiomorph replace an element whose id the server
+   * did not send, so an id from the component gave the heading a new one on
+   * every patch. An empty one names nothing.
+   */
+  const titleId = givenTitleId?.trim()
+    ? givenTitleId
+    : id?.trim()
+      ? `${id}-title`
+      : undefined
+  // `aria-labelledby` splits on whitespace, so the box would point at two
+  // ids, neither of them the heading's.
+  if (titleId !== undefined && /\s/.test(titleId))
+    throw new Error(
+      `lt.errorSummary(): the titleId "${titleId}" contains whitespace. aria-labelledby splits on whitespace, so the box would point at ids that are not the heading's.`,
+    )
+  return {
+    host: attributes({
+      class: ERROR_SUMMARY_CLASS,
+      role: "alert" as const,
+      tabindex: "-1" as const,
+      id,
+      hidden: count === 0 ? (true as const) : undefined,
+      "aria-labelledby": titleId,
+    }),
+    title: attributes({ class: ERROR_SUMMARY_TITLE_CLASS, id: titleId }),
+  }
+}

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

@@ -30,7 +30,8 @@ export const LT_ERROR_SUMMARY_PARTS = {
  * 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
+ * heading, and sets them back when a patch removes them. Either way, a box
+ * without a name gets `aria-labelledby` pointing at its heading. The component
  * creates no nodes: it used to, and then the heading disappeared on the
  * first morph in Datastar and never came back.
  *
@@ -53,6 +54,7 @@ export const LT_ERROR_SUMMARY_PARTS = {
  * </lt-error-summary>
  * ```
  */
+
 /** Decodes a fragment, and returns it untouched if it is not valid. */
 function decodeFragment(fragment: string): string {
   try {
@@ -78,7 +80,16 @@ export class LtErrorSummary extends HostElement {
    * live validation patched the list.
    */
   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.
+   */
+  private labelledByWritten: string | null = null
 
   connectedCallback(): void {
     // One listener on the host, not one per link. The set of links was only
@@ -89,21 +100,67 @@ export class LtErrorSummary extends HostElement {
     // 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())
+    // 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) => {
+      const relevant = records.some((r) => {
+        if (r.attributeName === "id")
+          return (r.target as Element).matches(LT_ERROR_SUMMARY_PARTS.title)
+        if (
+          r.attributeName === "aria-label" ||
+          r.attributeName === "aria-labelledby"
+        )
+          return r.target === this
+        return true
+      })
+      if (relevant) this.sync()
+    })
     this.observer.observe(this, {
       childList: true,
       subtree: true,
       attributes: true,
-      attributeFilter: ["class", "role", "tabindex"],
+      attributeFilter: [
+        "class",
+        "role",
+        "tabindex",
+        "aria-labelledby",
+        "aria-label",
+        "id",
+      ],
     })
     this.sync()
   }
 
   attributeChangedCallback(): void {
-    // 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()
+    /*
+     * 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.
+     *
+     * A microtask later, not now. A morph sets `hidden` in its attribute
+     * pass, before it updates the children; focus moved then made the box
+     * the focused element, and idiomorph with `ignoreActiveValue` leaves the
+     * children of the focused element as they were, so the new errors never
+     * arrived. Found by the code review of PR 240.
+     */
+    // Where focus was when the box was shown. React gives it back there
+    // after the commit, and the box takes it anyway; a script that moves it
+    // somewhere else in the same turn has decided, and the box leaves it.
+    this.focusBefore ??= document.activeElement
+    // Hidden: let go of focus now, in the morph's attribute pass, so the
+    // morph still updates the content (see `sync()`).
+    if (this.hidden) this.blurInside()
+    queueMicrotask(() => {
+      if (this.isConnected) this.sync()
+      this.focusBefore = undefined
+    })
+  }
+
+  /** Takes focus off the box, or off a link in it. */
+  private blurInside(): void {
+    const focused = (this.getRootNode() as Document | ShadowRoot).activeElement
+    if (focused instanceof HTMLElement && this.contains(focused)) focused.blur()
   }
 
   disconnectedCallback(): void {
@@ -140,6 +197,49 @@ export class LtErrorSummary extends HostElement {
 
     const title = this.querySelector(LT_ERROR_SUMMARY_PARTS.title)
     if (title) addClass(title, ERROR_SUMMARY_TITLE_CLASS)
+
+    /*
+     * The box takes focus, so it needs a name: without one a screen reader
+     * says only "alert" when the focus lands, and the heading is what says
+     * how many errors there are. The template writes the heading's id and
+     * the box's `aria-labelledby`, as it writes `for` and `id` on a field;
+     * `lt.errorSummary({ id })` writes both. The component never writes an
+     * id: Datastar and idiomorph replace an element whose id the server did
+     * not send, so an id from the component gave the heading a new one on
+     * every patch. When the heading has an id and the box no name, the
+     * component points `aria-labelledby` at it, and follows a heading a
+     * patch has replaced. A blank `aria-label` or `aria-labelledby` names
+     * 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)
+      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()
+          )
+        },
+      )
   }
 
   private sync(): void {
@@ -160,6 +260,15 @@ export class LtErrorSummary extends HostElement {
     if (this.hidden) {
       this.hasFocused = false
       this.focusAttempted = false
+      /*
+       * A hidden box gives up focus. HTML's focus fixup rule moves focus
+       * off an element that is no longer rendered; Chromium does it at
+       * once, Firefox and WebKit left it on the hidden box. idiomorph leaves
+       * the content of the focused element as it was, so the next errors
+       * the server sent never reached the box, which then showed an empty
+       * heading and list. Found by the model test.
+       */
+      this.blurInside()
     }
 
     if (links.length === 0) {
@@ -218,6 +327,11 @@ export class LtErrorSummary extends HostElement {
       const active = document.activeElement
       const nobodyTyping = !active || active === document.body
       if (this.focusAttempted && !nobodyTyping) return
+      const movedByScript =
+        this.focusBefore !== undefined &&
+        active !== this.focusBefore &&
+        !nobodyTyping
+      if (movedByScript) return
       const root = this.getRootNode() as Document | ShadowRoot
 
       this.focusAttempted = true

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

@@ -4,9 +4,13 @@ import {
   addClass,
   defineElement,
   HostElement,
+  markWritten,
   setAttr,
   setFlag,
+  stillMarked,
   uniqueId,
+  WRITTEN,
+  warnAboutCopiedMark,
   warnAboutMarkup,
 } from "../../host-element.js"
 import { computeFieldAttributes } from "./field-core.js"
@@ -47,6 +51,9 @@ function readMarker(value: string | null | undefined): Marker | undefined {
  * back.
  */
 const DERIVED_ATTRIBUTES = [
+  // A morph from the server removes the mark, and the component puts it
+  // back: the same markup must give the same page.
+  WRITTEN,
   "class",
   "for",
   "id",
@@ -325,35 +332,42 @@ export class LtField extends HostElement {
     const known = this.labelMemory.get(label)
     if (!known) return now
 
+    const spoke = (name: string, changed: boolean) =>
+      changed || !stillMarked(label, name)
     return {
-      required:
-        now.required !== known.written.required
-          ? now.required
-          : known.server.required,
-      optional:
-        now.optional !== known.written.optional
-          ? now.optional
-          : known.server.optional,
+      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) return now
+    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:
-        now.invalid !== known.written.invalid
-          ? now.invalid
-          : known.server.invalid,
-      describedBy:
-        now.describedBy !== known.written.describedBy
-          ? now.describedBy
-          : known.server.describedBy,
-      disabled:
-        now.disabled !== known.written.disabled
-          ? now.disabled
-          : known.server.disabled,
+      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,
     }
   }
 
@@ -683,11 +697,22 @@ export class LtField extends HostElement {
       }
       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,
+      }
+      markWritten(
+        label,
+        "data-required",
+        writtenLabel.required !== serverLabel.required,
+      )
+      markWritten(
+        label,
+        "data-optional",
+        writtenLabel.optional !== serverLabel.optional,
+      )
       this.labelMemory.set(label, {
-        written: {
-          required: computed.label["data-required"] ?? null,
-          optional: computed.label["data-optional"] !== undefined,
-        },
+        written: writtenLabel,
         server: serverLabel,
       })
       setAttr(label, "aria-disabled", computed.label["aria-disabled"])
@@ -714,12 +739,24 @@ export class LtField extends HostElement {
     // 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: ariaInvalid,
-        describedBy: computed.control["aria-describedby"] ?? null,
-        disabled,
+        invalid: written.invalid,
+        describedBy: written.describedBy,
+        disabled: written.disabled,
       },
       server,
     })

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

@@ -196,7 +196,8 @@ export class LtPopover extends HostElement {
      * user or the server has said so. If it is gone while the user opened it, the
      * morph took it, and then it comes back.
      */
-    if (this.wantsOpen && !this.open && !isServerControlled(this)) {
+    const repairing = this.wantsOpen && !this.open && !isServerControlled(this)
+    if (repairing) {
       /*
        * Wait until the whole patch has landed before opening the popover again.
        *
@@ -206,10 +207,16 @@ export class LtPopover extends HostElement {
        * was taking over the state, and the popover stayed open afterwards.
        * `queueMicrotask` runs after the whole patch is done, and the condition is
        * checked again there.
+       *
+       * Until then the panel stays as it is: closing it while the repair waits
+       * took the focus from a button in it to the trigger on every patch.
+       * When the repair is called off, `sync()` closes the panel for real.
        */
       queueMicrotask(() => {
-        if (!this.isConnected || isServerControlled(this)) return
-        if (this.wantsOpen && !this.open) setFlag(this, "open", true)
+        if (!this.isConnected) return
+        if (!isServerControlled(this) && this.wantsOpen && !this.open)
+          setFlag(this, "open", true)
+        else this.sync()
       })
     }
 
@@ -322,16 +329,30 @@ export class LtPopover extends HostElement {
       this.panel = panel
     }
 
+    // Shown while a repair waits, so the button says the same as the panel.
+    const shown = this.open || repairing
+
     // Written by the component, and set again if a patch took it.
-    setAttr(trigger, "aria-expanded", String(this.open))
+    setAttr(trigger, "aria-expanded", String(shown))
 
-    if (this.open) {
+    if (shown) {
       if (!panel.matches(":popover-open")) panel.showPopover()
       this.reposition()
       document.addEventListener("click", this.handleOutsideClick, true)
       document.addEventListener("keydown", this.handleKeydown)
     } else {
-      if (panel.matches(":popover-open")) panel.hidePopover()
+      if (panel.matches(":popover-open")) {
+        /*
+         * Focus in the panel goes back to the button, whatever closed it:
+         * `hide()`, `toggle()`, the server taking `open`. Otherwise it stays
+         * on a button that is no longer shown, and the next key press starts
+         * at the top of the page. Escape did this alone before. Focus
+         * elsewhere, such as a field the user clicked outside, stays.
+         */
+        const inside = panel.contains(document.activeElement)
+        panel.hidePopover()
+        if (inside) trigger.focus()
+      }
       document.removeEventListener("click", this.handleOutsideClick, true)
       document.removeEventListener("keydown", this.handleKeydown)
     }
@@ -397,7 +418,13 @@ export class LtPopover extends HostElement {
   }
 
   private handleTriggerClick = (): void => {
+    const closing = this.open
     this.toggle()
+    // Safari gives a clicked button no focus: focus in the panel went to
+    // `<body>` with the click, before the panel closed, and `sync()` did not
+    // see it there. The other browsers have given the button focus already.
+    if (closing && document.activeElement === document.body)
+      this.triggerElement?.focus()
   }
 
   private handlePanelToggle = (event: Event): void => {
@@ -529,18 +556,22 @@ export class LtPopover extends HostElement {
     )
   }
 
-  /** Opens the panel. */
+  /**
+   * Opens the panel. Through the setter also when it is open already, as
+   * when the server sent `open`: the call is the app's message, and without
+   * it the next patch without `open` closed the panel.
+   */
   show(): void {
-    if (this.open) return
+    const was = this.open
     this.open = true
-    this.emit(true)
+    if (!was) this.emit(true)
   }
 
-  /** Closes the panel. */
+  /** Closes the panel. Through the setter also when it is closed, as `show()`. */
   hide(): void {
-    if (!this.open) return
+    const was = this.open
     this.open = false
-    this.emit(false)
+    if (was) this.emit(false)
   }
 
   /** Opens or closes. */