@lo-tek/interfaces 0.37.0 → 0.38.0

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>
 }
 

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.38.0",
   "description-markup": "markdown",
   "contributions": {
     "html": {