@lo-tek/interfaces 0.37.0 → 0.39.0

package/manifest/manifest.json

@@ -1,7 +1,8 @@
 {
   "$schema": "./manifest.schema.json",
   "schemaVersion": 1,
-  "version": "0.37.0",
+  "version": "0.39.0",
+  "textLanguage": "en",
   "elements": {
     "lt-field": {
       "link": "https://lo-tek.sobernetics.no/components/field/",
@@ -31,7 +32,10 @@
           "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",
@@ -76,7 +80,8 @@
           "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])",
@@ -88,7 +93,10 @@
           "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": {
@@ -128,6 +136,10 @@
           "content": "text",
           "multiple": true
         }
+      },
+      "name": {
+        "after": "title",
+        "id": true
       }
     },
     "lt-popover": {
@@ -221,13 +233,19 @@
           "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])",
@@ -253,6 +271,34 @@
           "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": {
@@ -282,7 +328,10 @@
           "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",
@@ -325,6 +374,21 @@
         }
       },
       "parts": {},
+      "texts": {
+        "toastRegion": {
+          "text": "Notifications",
+          "replacedBy": [
+            "label",
+            "aria-label"
+          ]
+        },
+        "toastClose": {
+          "text": "Close message",
+          "replacedBy": [
+            "close-label"
+          ]
+        }
+      },
       "events": {
         "toast-dismiss": {}
       }
@@ -351,7 +415,10 @@
           "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",
@@ -405,6 +472,20 @@
         }
       },
       "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": {}
@@ -731,6 +812,7 @@
           "optional": true
         }
       },
+      "name": {},
       "attributes": {
         "data-state": {
           "values": [
@@ -749,6 +831,22 @@
       "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": [
@@ -879,6 +977,22 @@
       "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": [
@@ -1325,6 +1439,7 @@
           "multiple": true
         }
       },
+      "name": {},
       "attributes": {}
     },
     "lt-toggle-group__option": {
@@ -1798,6 +1913,9 @@
             }
           }
         }
+      },
+      "classes": {
+        "content": "lt-accordion__content"
       }
     },
     {
@@ -1846,6 +1964,9 @@
             }
           }
         }
+      },
+      "classes": {
+        "title": "lt-alert__title"
       }
     },
     {
@@ -1908,6 +2029,9 @@
             }
           }
         }
+      },
+      "classes": {
+        "stack": "lt-avatar-stack"
       }
     },
     {
@@ -2074,6 +2198,9 @@
             }
           }
         }
+      },
+      "classes": {
+        "title": "lt-card__title"
       }
     },
     {
@@ -2118,6 +2245,9 @@
             }
           }
         }
+      },
+      "classes": {
+        "row": "lt-checkbox-row"
       }
     },
     {
@@ -2148,6 +2278,8 @@
         "table": {
           "base": {
             "class": "lt-connection-status",
+            "role": "status",
+            "aria-live": "polite",
             "data-ignore-morph": ""
           },
           "options": {
@@ -2476,6 +2608,14 @@
             "kind": "text"
           },
           "description": "The id of the box, so the form can move focus here after submission."
+        },
+        {
+          "name": "titleId",
+          "required": false,
+          "type": {
+            "kind": "text"
+          },
+          "description": "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."
         }
       ],
       "returns": {
@@ -2775,6 +2915,9 @@
             }
           }
         }
+      },
+      "classes": {
+        "list": "lt-file-upload-list"
       }
     },
     {
@@ -3184,6 +3327,9 @@
           },
           "options": {}
         }
+      },
+      "classes": {
+        "gap": "lt-pagination__gap"
       }
     },
     {
@@ -3526,6 +3672,9 @@
             }
           }
         }
+      },
+      "classes": {
+        "row": "lt-radio-row"
       }
     },
     {
@@ -3570,6 +3719,9 @@
             }
           }
         }
+      },
+      "classes": {
+        "row": "lt-search-row"
       }
     },
     {
@@ -4229,6 +4381,9 @@
             }
           }
         }
+      },
+      "classes": {
+        "row": "lt-switch-row"
       }
     },
     {
@@ -4283,6 +4438,9 @@
             }
           }
         }
+      },
+      "classes": {
+        "scroll": "lt-table-scroll"
       }
     },
     {
@@ -4617,6 +4775,9 @@
           },
           "options": {}
         }
+      },
+      "classes": {
+        "option": "lt-toggle-group__option"
       }
     },
     {
@@ -4633,6 +4794,9 @@
           },
           "options": {}
         }
+      },
+      "classes": {
+        "bubble": "lt-tooltip__bubble"
       }
     }
   ],

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.",
@@ -192,6 +239,13 @@
           "returns": {
             "$ref": "#/$defs/returns"
           },
+          "classes": {
+            "type": "object",
+            "description": "The classes the builder function carries for the parts the template writes itself, as lt.card.title in TypeScript: the name on the function and the class. Only the parts no set of the function's own answer writes.",
+            "additionalProperties": {
+              "type": "string"
+            }
+          },
           "table": {
             "description": "When the options act independently: the base set and what each option adds, derived from the results and checked against every builder case. Another language can build the builder function from it alone.",
             "oneOf": [
@@ -505,6 +559,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.39.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 }),
+  }
+}