@lo-tek/interfaces 0.37.0 → 0.39.0

package/src/components/host-element.ts

@@ -12,12 +12,108 @@
  * without `customElements` nothing is registered, and without registration
  * the browser never creates an instance. It only exists so the module can
  * load.
+ *
+ * In the browser the base does one thing: it adopts the properties a script
+ * set before the registration, see `adoptPropertiesSetBeforeUpgrade()`.
  */
 
 export const HostElement =
   typeof HTMLElement === "undefined"
     ? (class {} as unknown as typeof HTMLElement)
-    : HTMLElement
+    : (class extends HTMLElement {
+        constructor() {
+          super()
+          // Here the own properties are exactly what a script set before the
+          // upgrade: the component's own fields are assigned after `super()`
+          // returns. An element created after the registration has none, and
+          // costs nothing.
+          const names = Object.getOwnPropertyNames(this)
+          if (names.length === 0) return
+          const pending = holdPropertiesSetBeforeUpgrade(this, names)
+          if (pending.size === 0) return
+          // Written in a microtask, not here: the field initialisers run
+          // after `super()`, and a setter that notes something on the
+          // instance, as `<lt-popover>` does with `open`, would have been
+          // overwritten by them. By the microtask the whole constructor and
+          // the upgrade's `connectedCallback` are done.
+          queueMicrotask(() => {
+            for (const [name, value] of pending) {
+              Reflect.deleteProperty(this, name)
+              ;(this as unknown as Record<string, unknown>)[name] = value
+            }
+          })
+        }
+      } as unknown as typeof HTMLElement)
+
+/**
+ * Takes the properties a script set on the element before it was upgraded out
+ * of the way, so they can be written through the component's setters.
+ *
+ * `dialog.open = true` from a script that runs before `defineLt()` lands on a
+ * plain `HTMLElement`, and becomes an own data property. When the element is
+ * upgraded, that property shadows the accessor on the prototype: the
+ * attribute is never set, and every later write, `dialog.open = false`
+ * included, goes to the shadow and never reaches the setter. Tested against
+ * `dist` on 2026-11-01: the setters were dead for the rest of the element's
+ * life.
+ *
+ * Each such property is replaced by a stand-in for the time until the
+ * microtask that writes the value. A read goes to the getter, so the
+ * component's first `sync()` sees the attribute and not the script's value:
+ * when it saw the value, it opened a dialog the script closed again right
+ * after the registration, and the write of `false` then removed an attribute
+ * that was never there, so nothing closed the dialog (found by GitHub's
+ * review). A write goes to the setter and cancels the adoption, so the last
+ * write wins. The values returned are what the microtask writes.
+ *
+ * Only a property with a setter somewhere on the prototype chain is taken;
+ * anything else a script put on the element stays as it is. A property set
+ * after the upgrade is never an own property, so there is nothing to do for
+ * an element created once the registration is there. A property someone made
+ * non-configurable cannot be moved out of the way, and is left shadowing the
+ * setter, as before. (Documented: the "lazy properties" pattern in Google's
+ * custom elements best practices.)
+ */
+function holdPropertiesSetBeforeUpgrade(
+  element: HTMLElement,
+  names: readonly string[],
+): Map<string, unknown> {
+  const pending = new Map<string, unknown>()
+  for (const name of names) {
+    const own = Object.getOwnPropertyDescriptor(element, name)
+    if (!own || !("value" in own) || !own.configurable) continue
+    const accessor = accessorOnPrototype(element, name)
+    if (!accessor?.set) continue
+    const { get, set } = accessor
+    pending.set(name, own.value)
+    Object.defineProperty(element, name, {
+      configurable: true,
+      enumerable: true,
+      get: () => get?.call(element),
+      set: (value: unknown) => {
+        pending.delete(name)
+        Reflect.deleteProperty(element, name)
+        set.call(element, value)
+      },
+    })
+  }
+  return pending
+}
+
+function accessorOnPrototype(
+  element: object,
+  name: string,
+): PropertyDescriptor | undefined {
+  for (
+    let proto = Object.getPrototypeOf(element);
+    proto !== null;
+    proto = Object.getPrototypeOf(proto)
+  ) {
+    const descriptor = Object.getOwnPropertyDescriptor(proto, name)
+    if (descriptor) return descriptor
+  }
+  return undefined
+}
 
 /*
  * The types of the events, such as `dialog-toggle` with `detail.open`. Every
@@ -96,6 +192,79 @@ export function setAttr(
   }
 }
 
+/**
+ * The attribute a component marks what it wrote with: the names of the
+ * attributes on the element whose value is the component's, separated by
+ * spaces.
+ *
+ * Some attributes are both the server's and the component's: `aria-invalid`
+ * on a field, `aria-selected` on a tab. To tell the server's word from its
+ * own echo, a component remembered the value it wrote, and read anything
+ * else as the server's. A server that sent the same value was never seen: a
+ * morph does not touch an attribute whose value is already right, and the
+ * component took the server's `aria-invalid="true"` for its own and removed
+ * it. The mark is what a morph does touch. The server never sends it, so a
+ * morph from the server removes it, and an attribute without the mark is the
+ * server's, whatever its value. A script that changes the element without a
+ * morph leaves the mark, and is seen as before, by the value.
+ *
+ * Only what differs from the server's word is marked. A value that is the
+ * server's has nothing to tell apart, and markup that is already right, as
+ * React renders `lt.tabs()` with the state, must not be touched: hydration
+ * reports every attribute it did not render.
+ */
+export const WRITTEN = "data-lt-written"
+
+/**
+ * Marks `name` on `element` as the component's when `mine`, that is, when
+ * what the component wrote differs from the server's word, and removes the
+ * mark otherwise.
+ */
+export function markWritten(
+  element: Element,
+  name: string,
+  mine: boolean,
+): void {
+  const marked = new Set(
+    (element.getAttribute(WRITTEN) ?? "").split(/\s+/).filter(Boolean),
+  )
+  if (mine) marked.add(name)
+  else marked.delete(name)
+  setAttr(
+    element,
+    WRITTEN,
+    marked.size > 0 ? [...marked].sort().join(" ") : null,
+  )
+}
+
+/**
+ * Warns when `element` carries the mark before the component has written on
+ * it: the mark is in the markup it was given, copied into a template from
+ * the browser's developer tools. A morph then never removes it, and the
+ * component takes the server's word for its own echo again. Called where the
+ * component meets the element for the first time; the check cannot wait, so
+ * the warning is not checked again when the page has settled.
+ */
+export function warnAboutCopiedMark(host: Element, element: Element): void {
+  if (!element.hasAttribute(WRITTEN)) return
+  warnAboutMarkup(
+    host,
+    `found ${WRITTEN} in the markup it was given. The browser writes the ` +
+      "attribute to tell the component's own values from the server's; " +
+      "copied into a template, it makes the component take what the " +
+      "server sends for its own. Remove it from the template.",
+    () => true,
+  )
+}
+
+/**
+ * Whether the component's mark for `name` is still on `element`: no morph
+ * from the server has been there since the component wrote it.
+ */
+export function stillMarked(element: Element, name: string): boolean {
+  return (element.getAttribute(WRITTEN) ?? "").split(/\s+/).includes(name)
+}
+
 /**
  * Turns a boolean attribute on or off, without writing when it is already so.
  *
@@ -175,6 +344,26 @@ export function uniqueId(prefix: string): string {
   return `${prefix}-${Math.random().toString(36).slice(2, 9)}`
 }
 
+/**
+ * The id an element should have: the one it has, otherwise the one the
+ * component created for that node before. A morph keeps the node and tears
+ * the id off, and it gets the same one back, so a screen reader does not
+ * follow a reference that changes under it.
+ */
+export function rememberedId(
+  memory: WeakMap<Element, string>,
+  element: Element,
+  prefix: string,
+): string {
+  if (element.id) return element.id
+  let id = memory.get(element)
+  if (!id) {
+    id = uniqueId(prefix)
+    memory.set(element, id)
+  }
+  return id
+}
+
 /**
  * The parts with a role, and those without only when the component set the
  * roles itself.

package/src/components/standalone/connection-status/connection-status.ts

@@ -12,6 +12,8 @@ export type ConnectionStatusOptions = {
 
 export type ConnectionStatusAttributes = {
   class: typeof CONNECTION_STATUS_CLASS
+  role: "status"
+  "aria-live": "polite"
   "offline-text"?: string
   "online-text"?: string
   "data-ignore-morph": ""
@@ -23,7 +25,9 @@ export type ConnectionStatusAttributes = {
  * By definition the server cannot tell you it is unreachable. When it is
  * down, nothing comes from it to render. So the component creates all the
  * content itself, and `data-ignore-morph` stops a later patch from tearing
- * it away the moment the connection is back.
+ * it away the moment the connection is back. The host is the live region,
+ * `role="status"` with `aria-live="polite"`, so the region exists before the
+ * bar and its text arrive.
  *
  * ```ts
  * <lt-connection-status {...lt.connectionStatus()} />
@@ -35,6 +39,8 @@ export const connectionStatus = ({
 }: ConnectionStatusOptions = {}): ConnectionStatusAttributes =>
   attributes({
     class: CONNECTION_STATUS_CLASS,
+    role: "status" as const,
+    "aria-live": "polite" as const,
     "offline-text": offlineText,
     "online-text": onlineText,
     "data-ignore-morph": "" as const,

package/src/components/standalone/connection-status/lt-connection-status.ts

@@ -77,6 +77,23 @@ export class LtConnectionStatus extends HostElement {
 
   connectedCallback(): void {
     this.classList.add(CONNECTION_STATUS_CLASS)
+    /*
+     * The host is the live region, from the moment it is connected, so the
+     * region exists long before the bar and its text arrive. Only what is
+     * missing: a role or politeness the server wrote stays. When the bar was
+     * the region, it was inserted together with its text, and Firefox sent
+     * no live-region text through AT-SPI at all, so "No connection" was
+     * never announced. `check-accessibility-tree.ts` checks it.
+     */
+    this.markRegion()
+    // A morph without `data-ignore-morph` takes both off, and then the next
+    // outage is never announced. Writing only what is missing keeps the
+    // observer from triggering itself.
+    this.regionObserver = new MutationObserver(() => this.markRegion())
+    this.regionObserver.observe(this, {
+      attributes: true,
+      attributeFilter: ["role", "aria-live"],
+    })
     window.addEventListener("offline", this.handleOffline)
     window.addEventListener("online", this.handleOnline)
     if (!navigator.onLine) {
@@ -96,7 +113,22 @@ export class LtConnectionStatus extends HostElement {
     }
   }
 
+  private regionObserver?: MutationObserver
+
+  /**
+   * The region, as a pair and only when both are missing. A role the server
+   * wrote carries its own politeness (`alert` is assertive), and an
+   * `aria-live` added next to it would override that.
+   */
+  private markRegion(): void {
+    if (this.hasAttribute("role") || this.hasAttribute("aria-live")) return
+    this.setAttribute("role", "status")
+    this.setAttribute("aria-live", "polite")
+  }
+
   disconnectedCallback(): void {
+    this.regionObserver?.disconnect()
+    this.regionObserver = undefined
     window.removeEventListener("offline", this.handleOffline)
     window.removeEventListener("online", this.handleOnline)
     if (this.timer) window.clearTimeout(this.timer)
@@ -107,12 +139,10 @@ export class LtConnectionStatus extends HostElement {
    * The bar, created empty first and filled afterwards.
    *
    * A live region must exist before its content arrives, or assistive
-   * technology does not announce the first change. When the bar was already
-   * filled as it was inserted, the region appeared complete to the screen
-   * reader, and "No connection", the most important message, could be lost.
-   * So the text is set in the next frame when the bar is new. This cannot be
-   * checked without a screen reader; the rule is known from NVDA, JAWS and
-   * VoiceOver.
+   * technology does not announce the first change. The region is the host
+   * (see `connectedCallback`), so the bar is content inside a region that is
+   * already there; the text is still set in the next frame when the bar is
+   * new, so the bar and its text arrive as two changes.
    *
    * The bar is created only when it is needed, not on connection: when it
    * was in the DOM before React hydrated, React found an element it had not
@@ -123,10 +153,6 @@ export class LtConnectionStatus extends HostElement {
 
     const bar = document.createElement("div")
     bar.className = CONNECTION_STATUS_BAR_CLASS
-    // polite and not assertive: the message matters, but should not
-    // interrupt mid-word. It stays until the connection is back.
-    bar.setAttribute("role", "status")
-    bar.setAttribute("aria-live", "polite")
     this.append(bar)
     this.bar = bar
     return { bar, fresh: true }

package/src/diagnostics/core.ts

@@ -148,12 +148,23 @@ type Exports = {
   inspect_theme_raw(pointer: number, length: number): number
   inspect_styles_raw(pointer: number, length: number): void
   diagnose_styled_raw(pointer: number, length: number): number
+  accessibility_tree_raw(pointer: number, length: number): number
+  accessibility_facts_raw(): void
+  accessibility_roles_raw(): void
+  accessibility_states_raw(): void
   result_ptr(): number
   result_len(): number
 }
 
-/** Loads the core from the module's bytes or an already compiled module. */
-export function loadCore(source: BufferSource | WebAssembly.Module): Core {
+/**
+ * @internal Not part of the package's API.
+ *
+ * An instance of the core and the helpers every call goes through: the text
+ * written into the module's memory, and the answer read back. Not part of
+ * the package: `index.ts` exports `loadCore`. The tests reach the core's
+ * other functions, such as the accessibility tree, through this.
+ */
+export function instantiate(source: BufferSource | WebAssembly.Module) {
   const module =
     source instanceof WebAssembly.Module
       ? source
@@ -181,6 +192,12 @@ export function loadCore(source: BufferSource | WebAssembly.Module): Core {
     if (status !== 0) throw new Error(read<{ error: string }>().error)
     return read<T>()
   }
+  return { e, write, read, answer }
+}
+
+/** Loads the core from the module's bytes or an already compiled module. */
+export function loadCore(source: BufferSource | WebAssembly.Module): Core {
+  const { e, write, read, answer } = instantiate(source)
 
   return {
     diagnoseMarkup: (html) => answer(e.diagnose_markup_raw(...write(html))),

package/src/vocabulary/classes.ts

@@ -311,6 +311,7 @@ export const classes: Classes = {
         "optional": true
       }
     },
+    "name": {},
     "attributes": {
       "data-state": {
         "values": [
@@ -328,6 +329,22 @@ export const classes: Classes = {
     "link": "https://lo-tek.sobernetics.no/components/fieldset/",
     "content": "text",
     "partOf": "lt-fieldset",
+    "texts": [
+      {
+        "variable": "--lt-label-required-text",
+        "text": " (required)",
+        "attribute": "data-required",
+        "value": "text"
+      },
+      {
+        "variable": "--lt-label-optional-text",
+        "text": " (optional)",
+        "attribute": "data-optional",
+        "unless": [
+          "data-required"
+        ]
+      }
+    ],
     "attributes": {
       "data-required": {
         "values": [
@@ -453,6 +470,22 @@ export const classes: Classes = {
     "description": "A label for form fields, with marking of required and optional. A CSS component.",
     "link": "https://lo-tek.sobernetics.no/components/label/",
     "content": "text",
+    "texts": [
+      {
+        "variable": "--lt-label-required-text",
+        "text": " (required)",
+        "attribute": "data-required",
+        "value": "text"
+      },
+      {
+        "variable": "--lt-label-optional-text",
+        "text": " (optional)",
+        "attribute": "data-optional",
+        "unless": [
+          "data-required"
+        ]
+      }
+    ],
     "attributes": {
       "data-required": {
         "values": [
@@ -885,6 +918,7 @@ export const classes: Classes = {
         "multiple": true
       }
     },
+    "name": {},
     "attributes": {}
   },
   "lt-toggle-group__option": {

package/src/vocabulary/elements.ts

@@ -30,7 +30,10 @@ export const elements: Elements = {
         "description": "The control the field wires: an `<input>`, `<textarea>` or `<select>` with its `<option>`s. `type=\"hidden\"` does not count, and only the first one is wired. The template writes `for` on the label and `id` on the control, or wraps the control in the label.",
         "content": "none",
         "unique": true,
-        "stableId": true
+        "stableId": true,
+        "name": {
+          "after": "label"
+        }
       },
       "help": {
         "selector": ".lt-help-text",
@@ -75,7 +78,8 @@ export const elements: Elements = {
         "selector": "[role='tablist'], .lt-tabs__list",
         "description": "The tab list, a `<ul>` where each `<li>` gets `role=\"presentation\"`. It needs a name, such as `aria-label`. When the server has written `role=\"tab\"` on the links, the list can also hold other links.",
         "content": "free",
-        "unique": true
+        "unique": true,
+        "name": {}
       },
       "tab": {
         "selector": "a[role='tab'][href^='#'], .lt-tabs__list a[href^='#']:not([role])",
@@ -87,7 +91,10 @@ export const elements: Elements = {
         "selector": "[role='tabpanel'], .lt-tabs__panel:not([role])",
         "description": "The content of one tab, with the id the link points to. The panel has the same name as the tab: the heading at the top of the panel is the name when it says the same as the tab.",
         "content": "free",
-        "multiple": true
+        "multiple": true,
+        "name": {
+          "component": true
+        }
       }
     },
     "events": {
@@ -127,6 +134,10 @@ export const elements: Elements = {
         "content": "text",
         "multiple": true
       }
+    },
+    "name": {
+      "after": "title",
+      "id": true
     }
   },
   "lt-popover": {
@@ -220,13 +231,19 @@ export const elements: Elements = {
         "description": "The field the user types in: `role=\"combobox\"`, otherwise the first `<input>`. The template writes `for` on the label and `id` on the field, or wraps the field in the label.",
         "content": "none",
         "unique": true,
-        "stableId": true
+        "stableId": true,
+        "name": {
+          "after": "label"
+        }
       },
       "list": {
         "selector": "[role='listbox'], .lt-suggestion__list",
         "description": "The list of suggestions. It sits in the top layer when it is open, `popover=\"manual\"`, and has the label as its name.",
         "content": "parts",
-        "unique": true
+        "unique": true,
+        "name": {
+          "component": true
+        }
       },
       "option": {
         "selector": "[role='option'], .lt-suggestion__list > li:not([role])",
@@ -252,6 +269,34 @@ export const elements: Elements = {
         "content": "none",
         "unique": true,
         "optional": true
+      },
+      "label": {
+        "selector": "label",
+        "description": "The label. The component writes `for` on it from the field's id when it does not wrap the field, and names the list after it.",
+        "content": "text",
+        "optional": true
+      }
+    },
+    "texts": {
+      "suggestionNone": {
+        "text": "No matches",
+        "replacedBy": [
+          "count-none",
+          "count-other"
+        ]
+      },
+      "suggestionOne": {
+        "text": "One match",
+        "replacedBy": [
+          "count-one",
+          "count-other"
+        ]
+      },
+      "suggestionOther": {
+        "text": "{n} matches",
+        "replacedBy": [
+          "count-other"
+        ]
       }
     },
     "events": {
@@ -281,7 +326,10 @@ export const elements: Elements = {
         "selector": ":scope > dialog",
         "description": "The `<dialog>` element, as a direct child of the host.",
         "content": "free",
-        "unique": true
+        "unique": true,
+        "name": {
+          "after": "title"
+        }
       },
       "title": {
         "selector": "h1, h2, h3, h4, h5, h6",
@@ -324,6 +372,21 @@ export const elements: Elements = {
       }
     },
     "parts": {},
+    "texts": {
+      "toastRegion": {
+        "text": "Notifications",
+        "replacedBy": [
+          "label",
+          "aria-label"
+        ]
+      },
+      "toastClose": {
+        "text": "Close message",
+        "replacedBy": [
+          "close-label"
+        ]
+      }
+    },
     "events": {
       "toast-dismiss": {}
     }
@@ -350,7 +413,10 @@ export const elements: Elements = {
         "selector": "dialog",
         "description": "The `<dialog>` element with the warning.",
         "content": "free",
-        "unique": true
+        "unique": true,
+        "name": {
+          "after": "title"
+        }
       },
       "title": {
         "selector": "h1, h2, h3, h4, h5, h6",
@@ -404,6 +470,20 @@ export const elements: Elements = {
       }
     },
     "parts": {},
+    "texts": {
+      "connectionOffline": {
+        "text": "No connection. What you type is not being saved.",
+        "replacedBy": [
+          "offline-text"
+        ]
+      },
+      "connectionOnline": {
+        "text": "Connection restored.",
+        "replacedBy": [
+          "online-text"
+        ]
+      }
+    },
     "events": {
       "connection-lost": {},
       "connection-restored": {}

package/src/vocabulary/types.ts

@@ -34,8 +34,29 @@ export type Part = {
   optional?: true
   /** The part must have an id from the server; the component never writes one. */
   stableId?: true
+  /** LO-TEK demands a name for the part. */
+  name?: Name
 }
 
+/**
+ * A name LO-TEK demands where WAI-ARIA does not, or one the component gives
+ * itself. WAI-ARIA's own demands, by role, are in the core, and `lotek check`
+ * reports an element the markup gives no name (`without-name`).
+ *
+ * `after` is the part the component points `aria-labelledby` at when the
+ * markup has neither `aria-label` nor `aria-labelledby`, such as the heading
+ * of a dialog; then that part's name is enough. With `id` the part must have
+ * an id from the template, since the component does not write one. With
+ * `component` the component names it itself, after what the other rules
+ * check, such as the list in a suggestion field after the label, and no
+ * rule judges its name in the markup.
+ *
+ * Each of them is held to the component by a contract in
+ * `interfaces/scripts/accessibility/contracts.ts`: a mutation that takes the name away
+ * must fail in the browsers, and `lotek check` must report it.
+ */
+export type Name = { after?: string; id?: true; component?: true }
+
 /**
  * An event an element dispatches, such as `dialog-toggle`. `detail` is the
  * fields in `event.detail` with their types, and is absent when the event
@@ -52,10 +73,35 @@ export type Element = {
   /** Empty for the elements that create all of their content themselves. */
   parts?: Record<string, Part>
   events?: Record<string, ElementEvent>
+  /** LO-TEK demands a name for the element itself. */
+  name?: Name
+  /** The texts the element writes itself, by their name in `DEFAULT_TEXTS`. */
+  texts?: Record<string, DefaultText>
   /** Attributes that have been removed, with what applies instead. */
   removed?: Record<string, string>
 }
 
+/**
+ * A text the element writes itself when nobody has given it another, from
+ * `DEFAULT_TEXTS`. `replacedBy` is the attributes that replace it; any one
+ * of them is enough, and `lotek check` warns when none is there on a page in
+ * another language than the text's.
+ */
+export type DefaultText = { text: string; replacedBy: readonly string[] }
+
+/**
+ * A text the stylesheet shows in `::after` on an element with the class and
+ * `attribute`, with `value` when the selector requires one, and none of the
+ * attributes in `unless`. `variable` is the CSS variable that replaces it.
+ */
+export type CssText = {
+  variable: string
+  text: string
+  attribute: string
+  value?: string
+  unless?: readonly string[]
+}
+
 /** The content of `elements.ts`: tag to element. */
 export type Elements = Record<string, Element>
 
@@ -88,6 +134,10 @@ export type ClassInfo = {
   partOf?: string
   /** The parts the markup consists of, for the classes with a fixed structure. */
   parts?: Record<string, Part>
+  /** LO-TEK demands a name for the element with the class. */
+  name?: Name
+  /** The texts the stylesheet shows on it. */
+  texts?: readonly CssText[]
   attributes: Record<string, ClassAttribute>
 }
 
@@ -147,6 +197,12 @@ export type Builder = {
     description?: string
   }[]
   returns: BuilderReturns
+  /**
+   * The classes for the parts the template writes itself, as `lt.card.title`:
+   * the name on the function and the class. Only on the builder functions
+   * that have one.
+   */
+  classes?: Record<string, string>
 }
 
 /**

package/web-types.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/JetBrains/web-types/master/schema/web-types.json",
   "name": "@lo-tek/interfaces",
-  "version": "0.37.0",
+  "version": "0.39.0",
   "description-markup": "markdown",
   "contributions": {
     "html": {