@lo-tek/interfaces 0.38.0 → 0.40.0

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

@@ -64,9 +64,10 @@ const OPTION_SELECTOR = LT_SUGGESTION_PARTS.option
 /**
  * The keyboard and the filtering in a field with a suggestion list.
  *
- * The server writes the field and the list. When the markup is made with
- * JavaScript, `lt.suggestion()` writes the roles, the ids and the wiring.
- * When it comes from a template without JavaScript, the template writes
+ * The server writes the field and the list. When the code that renders the
+ * markup can call a builder function, `lt.suggestion()` or `Lt.suggestion()`
+ * writes the roles, the ids and the wiring. When it comes from a template that
+ * cannot, the template writes
  * `for` on the label and `id` on the field, or wraps the field in the label,
  * which HTML requires for the field to have a name without JavaScript. The
  * rest is enough: a `.lt-suggestion__list` with `<li>` and a
@@ -99,15 +100,15 @@ const OPTION_SELECTOR = LT_SUGGESTION_PARTS.option
  *
  * ```html
  * <lt-suggestion>
- *   <label class="lt-label" for="city">City</label>
- *   <input class="lt-input" id="city" role="combobox" aria-controls="city-list"
+ *   <label class="lt-label" for="breaker">Breaker</label>
+ *   <input class="lt-input" id="breaker" role="combobox" aria-controls="breaker-list"
  *          aria-expanded="false" aria-autocomplete="list" autocomplete="off"
- *          aria-describedby="city-status">
- *   <ul class="lt-suggestion__list" id="city-list" role="listbox" hidden>
- *     <li class="lt-suggestion__option" id="city-option-0" role="option">Bergen</li>
+ *          aria-describedby="breaker-status">
+ *   <ul class="lt-suggestion__list" id="breaker-list" role="listbox" hidden>
+ *     <li class="lt-suggestion__option" id="breaker-option-0" role="option">Crowbar</li>
  *   </ul>
  *   <p class="lt-suggestion__empty">No matches</p>
- *   <span class="lt-sr-only" id="city-status" role="status"></span>
+ *   <span class="lt-sr-only" id="breaker-status" role="status"></span>
  * </lt-suggestion>
  * ```
  */
@@ -136,8 +137,8 @@ export class LtSuggestion extends HostElement {
    *
    * The pair is what the code in the value field applies to. If the user
    * changes the text, the code no longer applies, and the value field is
-   * emptied; otherwise the form would submit the code for Bergen with the
-   * text "Bodø" in the field. If the text is still there after an update, the
+   * emptied; otherwise the form would submit the code for Crowbar with the
+   * text "Needle" in the field. If the text is still there after an update, the
    * code is set back: the value field's `value` is an attribute, and a morph
    * writes the server's over what the web component set.
    */
@@ -1196,7 +1197,7 @@ export class LtSuggestion extends HostElement {
     }
     // The field shows the text. The code goes to the value field, when the
     // server has written one, and in the event. `data-value` used to end up in
-    // the field, and the user who chose Bergen saw "4601".
+    // the field, and the user who chose Crowbar saw "LDG-117".
     if (setter) setter.call(this.control, label)
     else this.control.value = label
 

package/src/components/frame/suggestion/suggestion.css

@@ -50,7 +50,7 @@
     display: none;
   }
 
-  /* Markup written without JavaScript arrives without `hidden` on the list,
+  /* Markup written without a builder function arrives without `hidden` on the list,
      and the web component only closes it once it is registered. Until then
      it is hidden, so it does not stand open below a field nobody has
      touched. */

package/src/components/frame/suggestion/suggestion.ts

@@ -14,7 +14,9 @@ export const SUGGESTION_STATUS_CLASS = "lt-sr-only" as const
 export type SuggestionOptions = Omit<FieldOptions, "id"> & {
   /**
    * Shared id stem. The control becomes `${id}`, the list `${id}-list`, and
-   * the options `${id}-option-${key}`.
+   * the options `${id}-option-${key}`. Make it from a key in the data, never
+   * from the loop index or a counter, so it is unique on the page and the
+   * same on every render.
    */
   id: string
   /**

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

@@ -192,11 +192,11 @@ function markGone(element: Element, name: string, word: Word): boolean {
  *
  * ```html
  * <lt-tabs>
- *   <ul class="lt-tabs__list" aria-label="Parts of the case">
- *     <li><a href="#application">Application</a></li>
+ *   <ul class="lt-tabs__list" aria-label="Parts of the claim">
+ *     <li><a href="#claim">Claim</a></li>
  *     <li><a href="#attachments">Attachments</a></li>
  *   </ul>
- *   <section class="lt-tabs__panel" id="application"><h2>Application</h2>…</section>
+ *   <section class="lt-tabs__panel" id="claim"><h2>Claim</h2>…</section>
  *   <section class="lt-tabs__panel" id="attachments"><h2>Attachments</h2>…</section>
  * </lt-tabs>
  * ```
@@ -759,7 +759,7 @@ export class LtTabs extends HostElement {
     // the user asked for. Waiting for every tab to have a panel was not
     // enough: with one link pointing to nothing, the tab list never loaded.
     // If the address points to something that never comes, such as
-    // `#/case/1`, there is nothing to select either. The server's word is read
+    // `#/claim/1`, there is nothing to select either. The server's word is read
     // through the memory, so a new connection does not take the web
     // component's writes for the server's.
     const tabs = this.tabs
@@ -1066,7 +1066,7 @@ export class LtTabs extends HostElement {
     warnAboutMarkup(
       this,
       "has a tab list without a name. Write aria-label on " +
-        '.lt-tabs__list, such as aria-label="Parts of the case", or ' +
+        '.lt-tabs__list, such as aria-label="Parts of the claim", or ' +
         "aria-labelledby pointing to a heading; without a name a screen " +
         'reader only says "tab list".',
       () => {

package/src/components/frame/tabs/tabs.css

@@ -58,7 +58,7 @@
       cursor: not-allowed;
     }
 
-    /* Markup written without JavaScript comes without `hidden` on the panels,
+    /* Markup written without a builder function comes without `hidden` on the panels,
        and the web component sets it only once it is registered. Until then
        only one panel is shown, the one the web component is going to select,
        so the content does not jump when the rest are hidden:

package/src/components/frame/tabs/tabs.ts

@@ -6,11 +6,13 @@ export const TABS_PANEL_CLASS = "lt-tabs__panel" as const
 export type TabsOptions = {
   /**
    * The shared id stem. The panels become `${id}-${key}`, and the headings in
-   * them `${id}-${key}-heading`.
+   * them `${id}-${key}-heading`. Make it from a key in the data, never from
+   * the loop index or a counter, so it is unique on the page and the same on
+   * every render.
    */
   id: string
   /**
-   * One key per tab, from the data, such as `["application", "attachments"]`.
+   * One key per tab, from the data, such as `["claim", "attachments"]`.
    * The key gives the panel its id, and the link points to it. An index is
    * not a key: if the server inserts a tab first, the same index points to
    * another panel. An empty key, whitespace and two identical keys throw.
@@ -70,14 +72,14 @@ function prepare(
  * behave like one, and hidden the panels.
  *
  * The first tab is selected when the page loads. Another one comes from the
- * address, such as `#case-attachments`, or from `selected` and `select()` on
+ * address, such as `#file-attachments`, or from `selected` and `select()` on
  * `<lt-tabs>`.
  *
- * A React app uses `lt.tabs()` from `@lo-tek/interfaces/react`, which gives
- * the whole state, so React hydrates without mismatches.
+ * In React, use `lt.tabs()` from `@lo-tek/interfaces/react`, which gives the
+ * whole state, so React hydrates without mismatches.
  *
  * ```ts
- * const tabs = lt.tabs({ id: "case", keys: ["application", "attachments"], label: "Parts of the case" })
+ * const tabs = lt.tabs({ id: "file", keys: ["claim", "attachments"], label: "Parts of the claim" })
  * ```
  */
 export const tabs = (options: TabsOptions): TabsAttributes => {

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

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

@@ -32,7 +32,7 @@ const RECEIPT_MS = 4000
  * ```ts
  * const status = document.querySelector("lt-connection-status")
  * try {
- *   const response = await fetch("/api/save", { method: "POST", body })
+ *   const response = await fetch("/api/routes", { method: "POST", body })
  *   if (!response.ok) throw new Error(response.statusText)
  *   status.reportSuccess()
  * } catch {

package/src/components/standalone/toast/lt-toast.ts

@@ -53,7 +53,7 @@ export type ShowOptions = {
  * focus is in the message.
  *
  * ```ts
- * document.querySelector("lt-toast").show("Application sent", {
+ * document.querySelector("lt-toast").show("Relay 14 is back", {
  *   color: "success",
  * })
  * ```

package/src/diagnostics/index.ts

@@ -3,8 +3,8 @@
  *
  * `diagnoseMarkup(html)` is the same check the editor extensions run while
  * you type, and that `lotek check` runs on the command line. It is here
- * because markup produced without JavaScript, in a Go template, a Kotlin
- * string or a Razor view, has no compiler looking at the attributes. A test
+ * because markup from a template, in Go, a Kotlin string or a Razor view, has
+ * no compiler looking at the attributes. A test
  * in the app can then run it over the HTML the server actually sends:
  *
  * ```ts

package/src/dom.ts

@@ -72,7 +72,8 @@ export type Attributes = Record<string, string | boolean | undefined>
  * Call it again to change state. What the builder function manages and is
  * not in the new set is removed, and the `lt-` classes are replaced. A
  * builder function manages the attributes it has an option for:
- * `lt.spinner()` has `label`, and so manages `role` and `aria-label`. What it
+ * `lt.spinner()` has `label`, and so manages `role`, `aria-label` and
+ * `aria-hidden`. What it
  * has no option for stays as it is: `lt.button()` has never written
  * `disabled`, so a disabled button is still disabled afterwards. `id` and
  * `for` are never removed.

package/src/lt.ts

@@ -98,16 +98,16 @@ export const lt = {
    * Connects the label, field, help text and error text.
    *
    * ```ts
-   * const field = lt.field({ id: "email", required: "text", help: true, error: true, invalid })
+   * const field = lt.field({ id: "fixer", required: "text", help: true, error: true, invalid })
    *
-   * <label {...field.label}>Email address</label>
+   * <label {...field.label}>Fixer's address</label>
    * <input {...lt.input({ type: "email", state: field.state })} {...field.control} />
-   * <p {...lt.helpText()} {...field.help}>We send the receipt here.</p>
+   * <p {...lt.helpText()} {...field.help}>The board writes to the fixer, never to the crew.</p>
    * <p {...lt.errorText()} {...field.error}>Enter a valid address.</p>
    * ```
    *
-   * The same calculation `<lt-field>` does, but as data, for markup created
-   * with JavaScript. Then no web component is needed.
+   * The same calculation `<lt-field>` does in the browser, but as data, for
+   * the code that renders the markup. Then no web component is needed.
    */
   field: computeFieldAttributes,
   /** A group of controls that belong together. Its label is `lt.legend`. */

package/src/tokens/boundary.css

@@ -91,6 +91,10 @@
   all: revert-layer;
 }
 
+[data-lt-boundary][data-lt-boundary] *::-webkit-date-and-time-value {
+  all: revert-layer;
+}
+
 [data-lt-boundary][data-lt-boundary] *::-webkit-progress-bar {
   all: revert-layer;
 }

package/src/vocabulary/elements.ts

@@ -4,7 +4,7 @@ import type { Elements } from "./types.js"
 export const elements: Elements = {
   "lt-field": {
     "link": "https://lo-tek.sobernetics.no/components/field/",
-    "description": "Wires label, field, help text and error text together: sets `aria-describedby` and `aria-invalid` on the control and an id on the help text and the error text. Never writes an id on the control: the template writes `for` and `id`, or wraps the field in the label. The field is invalid when the error text is there without `hidden`. Exists for markup produced without JavaScript. When the markup is produced with JavaScript, use `lt.field()` instead.",
+    "description": "Wires label, field, help text and error text together: sets `aria-describedby` and `aria-invalid` on the control and an id on the help text and the error text. Never writes an id on the control: the template writes `for` and `id`, or wraps the field in the label. The field is invalid when the error text is there without `hidden`. Exists for markup from code that cannot call a builder function. When it can, in TypeScript, Kotlin or Java, use `lt.field()` or `Lt.field()` instead.",
     "attributes": {
       "disabled": {
         "type": "flag",

package/src/vocabulary/types.ts

@@ -190,13 +190,36 @@ export type BuilderReturns = { optional?: boolean } & (
  */
 export type Builder = {
   name: string
+  /**
+   * The comment on the function, without the code examples. Missing in a
+   * manifest from before 0.40, where the schema version was already 1.
+   */
+  description?: string
+  /** The code examples in the comment, in TypeScript. */
+  example?: string
+  /** The page the function is documented on. */
+  docs?: string
+  /**
+   * Which part of a frame component each set in the result fills, as
+   * `field.control` fills the control of `<lt-field>`. A set that fills no
+   * part is left out.
+   */
+  parts?: Record<string, { element: string; part: string }>
   options: {
     name: string
     required: boolean
     type: BuilderOptionType
     description?: string
+    /** The value that gives the same answer as leaving the option out. */
+    default?: 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,14 +1,14 @@
 {
   "$schema": "https://raw.githubusercontent.com/JetBrains/web-types/master/schema/web-types.json",
   "name": "@lo-tek/interfaces",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "description-markup": "markdown",
   "contributions": {
     "html": {
       "elements": [
         {
           "name": "lt-field",
-          "description": "Wires label, field, help text and error text together: sets `aria-describedby` and `aria-invalid` on the control and an id on the help text and the error text. Never writes an id on the control: the template writes `for` and `id`, or wraps the field in the label. The field is invalid when the error text is there without `hidden`. Exists for markup produced without JavaScript. When the markup is produced with JavaScript, use `lt.field()` instead.",
+          "description": "Wires label, field, help text and error text together: sets `aria-describedby` and `aria-invalid` on the control and an id on the help text and the error text. Never writes an id on the control: the template writes `for` and `id`, or wraps the field in the label. The field is invalid when the error text is there without `hidden`. Exists for markup from code that cannot call a builder function. When it can, in TypeScript, Kotlin or Java, use `lt.field()` or `Lt.field()` instead.",
           "doc-url": "https://lo-tek.sobernetics.no/components/field/",
           "attributes": [
             {