@lo-tek/interfaces 0.39.0 → 0.40.0

package/manifest/manifest.schema.json

@@ -65,11 +65,15 @@
               "type": "object",
               "required": ["text", "replacedBy"],
               "properties": {
-                "text": { "type": "string" },
+                "text": {
+                  "type": "string"
+                },
                 "replacedBy": {
                   "type": "array",
                   "description": "The attributes that replace the text. Any one of them is enough.",
-                  "items": { "type": "string" }
+                  "items": {
+                    "type": "string"
+                  }
                 }
               },
               "additionalProperties": false
@@ -138,14 +142,24 @@
               "type": "object",
               "required": ["variable", "text", "attribute"],
               "properties": {
-                "variable": { "type": "string" },
-                "text": { "type": "string" },
-                "attribute": { "type": "string" },
-                "value": { "type": "string" },
+                "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" }
+                  "items": {
+                    "type": "string"
+                  }
                 }
               },
               "additionalProperties": false
@@ -214,6 +228,35 @@
           "name": {
             "type": "string"
           },
+          "description": {
+            "type": "string",
+            "description": "The comment on the builder function, without the code examples and without advice for React: what it is for and what the template has to know. Paragraphs are separated by an empty line. Added after schemaVersion 1 was set, so an older manifest does not have it."
+          },
+          "example": {
+            "type": "string",
+            "description": "The code examples in the comment, in TypeScript."
+          },
+          "docs": {
+            "type": "string",
+            "format": "uri",
+            "description": "The page the builder function is documented on."
+          },
+          "parts": {
+            "type": "object",
+            "description": "Which part of a frame component each set in the result fills, as field.control fills the control of lt-field. The part's selector in elements is what the set may go on. A set that fills no part is left out.",
+            "additionalProperties": {
+              "type": "object",
+              "required": ["element", "part"],
+              "properties": {
+                "element": {
+                  "type": "string"
+                },
+                "part": {
+                  "type": "string"
+                }
+              }
+            }
+          },
           "options": {
             "type": "array",
             "items": {
@@ -232,6 +275,10 @@
                 "description": {
                   "type": "string",
                   "description": "What the option does, taken from the comment on the option in the type."
+                },
+                "default": {
+                  "type": "string",
+                  "description": "For an option with a closed list: the value that gives the same answer as leaving the option out, read from the answers. The description says the same."
                 }
               }
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lo-tek/interfaces",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "description": "Framework-agnostic design system: tokens, CSS components and web components.",
   "license": "MIT",
   "author": "August Søberg-Klyver",
@@ -335,6 +335,7 @@
     "dist",
     "web-types.json",
     "live-templates.xml",
+    "live-templates-kotlin.xml",
     "manifest/manifest.json",
     "manifest/files.json",
     "core/lotek-core.wasm",

package/src/components/css/accordion/accordion.ts

@@ -30,7 +30,7 @@ export type AccordionAttributes = {
  *
  * ```ts
  * <details {...accordion()}>
- *   <summary>Who can apply?</summary>
+ *   <summary>Who can take out a policy?</summary>
  *   <div class={accordion.content}>…</div>
  * </details>
  * ```

package/src/components/css/alert/alert.ts

@@ -29,7 +29,7 @@ export type AlertAttributes = {
  *
  * ```ts
  * <div {...alert({ color: "warning" })}>
- *   <p class={alert.title}>The application has not been sent</p>
+ *   <p class={alert.title}>Your routes have not been saved</p>
  * </div>
  * ```
  */

package/src/components/css/avatar/avatar.ts

@@ -33,7 +33,7 @@ export type AvatarAttributes = {
  * picture stands alone, it must have a text that says who it is.
  *
  * ```ts
- * <span {...avatar({ size: "small" })} aria-hidden="true">ON</span>
+ * <span {...avatar({ size: "small" })} aria-hidden="true">DP</span>
  * ```
  */
 export const avatar = Object.assign(

package/src/components/css/badge/badge.ts

@@ -27,7 +27,7 @@ export type BadgeAttributes = {
  * The attributes for a status badge.
  *
  * ```ts
- * <span {...badge({ color: "success" })}>Approved</span>
+ * <span {...badge({ color: "success" })}>Paid</span>
  * ```
  */
 export const badge = Object.assign(

package/src/components/css/breadcrumbs/breadcrumbs.ts

@@ -21,7 +21,7 @@ export type BreadcrumbsAttributes = {
  * <nav aria-label="You are here">
  *   <ol {...breadcrumbs()}>
  *     <li><a href="/">Home</a></li>
- *     <li><a href="/cases" aria-current="page">My cases</a></li>
+ *     <li><a href="/claims" aria-current="page">My claims</a></li>
  *   </ol>
  * </nav>
  * ```

package/src/components/css/card/card.ts

@@ -31,7 +31,7 @@ export type CardAttributes = {
  * reached with the keyboard nor be announced as something to press.
  *
  * ```ts
- * <a {...card({ interactive: true })} href="/case/481">…</a>
+ * <a {...card({ interactive: true })} href="/claims/AV-2079-0481">…</a>
  * ```
  */
 export const card = Object.assign(

package/src/components/css/file-upload/file-upload.ts

@@ -39,7 +39,7 @@ export type FileUploadAttributes = {
  * "all files", so the type must be checked on the server anyway.
  *
  * ```ts
- * <input {...fileUpload({ multiple: true, accept: ".pdf" })} />
+ * <input {...fileUpload({ multiple: true, accept: ".bin" })} />
  * ```
  */
 export const fileUpload = Object.assign(

package/src/components/css/icon/icon.ts

@@ -30,7 +30,7 @@ export type IconAttributes = {
  * reports a button that lacks one.
  *
  * ```ts
- * <button {...button()} aria-label="Delete the application">
+ * <button {...button()} aria-label="Delete ticket #0331">
  *   <svg {...icon()} viewBox="0 0 24 24">…</svg>
  * </button>
  * ```

package/src/components/css/input/input.css

@@ -126,6 +126,27 @@
     cursor: pointer;
   }
 
+  /* iOS Safari: with the native appearance, a date or time field stood wider
+     than its container. Without it, the field fits.
+     Undocumented: on 2026-11-01, CSS.supports("-webkit-touch-callout", "none")
+     was false in Playwright's Chromium, Firefox and WebKit on macOS, also with
+     iPhone emulation, and this rule applied in Safari on an iPhone. A WebKit
+     build with touch events elsewhere may match it too. */
+  @supports (-webkit-touch-callout: none) {
+    .lt-input[data-variant="date"],
+    .lt-input[data-variant="time"],
+    .lt-input[data-variant="datetime-local"] {
+      -webkit-appearance: none;
+      appearance: none;
+    }
+
+    .lt-input[data-variant="date"]::-webkit-date-and-time-value,
+    .lt-input[data-variant="time"]::-webkit-date-and-time-value,
+    .lt-input[data-variant="datetime-local"]::-webkit-date-and-time-value {
+      text-align: start;
+    }
+  }
+
   /* High contrast: the icon is painted into the image with a fixed colour,
      and can become invisible in a dark theme. The browser's own button is
      hidden behind our icon, and is brought back here. */

package/src/components/css/label/label.ts

@@ -33,7 +33,7 @@ export type LabelAttributes = {
  * or the screen reader is not told that it must be filled in.
  *
  * ```ts
- * <label {...label({ required: "symbol" })} htmlFor="email">Email address</label>
+ * <label {...label({ required: "symbol" })} htmlFor="fixer">Fixer's address</label>
  * ```
  */
 export const label = Object.assign(

package/src/components/css/link/link.ts

@@ -22,7 +22,7 @@ export type LinkAttributes = {
  * The attributes for a link.
  *
  * ```ts
- * <a {...link()} href="/receipt">See receipt</a>
+ * <a {...link()} href="/small-print">Read the small print</a>
  * <a {...link({ disabled: true })}>See annual statement</a>
  * ```
  *

package/src/components/css/spinner/spinner.ts

@@ -19,18 +19,20 @@ export type SpinnerAttributes = {
   "data-size"?: NonDefaultSpinnerSize
   role?: "status"
   "aria-label"?: string
+  "aria-hidden"?: "true"
 }
 
 /**
  * The attributes for a loading indicator.
  *
- * Without `label` the ring is only a shape, and screen readers announce
- * nothing. With `label` it becomes a `role="status"` that says what is going
- * on. If you already have a visible text next to it, let that carry the
- * message and drop `label`, so the same thing is not announced twice.
+ * Without `label` the ring is only a shape, and is hidden from screen readers
+ * with `aria-hidden`, as an icon without a label is. With `label` it becomes a
+ * `role="status"` that says what is going on. If you already have a visible
+ * text next to it, let that carry the message and drop `label`, so the same
+ * thing is not announced twice.
  *
  * ```ts
- * <span {...spinner({ label: "Loading applications" })} />
+ * <span {...spinner({ label: "Loading sectors" })} />
  * ```
  */
 export const spinner = Object.assign(
@@ -40,6 +42,7 @@ export const spinner = Object.assign(
       "data-size": size === "medium" ? undefined : size,
       role: label ? ("status" as const) : undefined,
       "aria-label": label,
+      "aria-hidden": label ? undefined : ("true" as const),
     }),
   {
     sizes: spinnerSizes,

package/src/components/css/tag/tag.ts

@@ -32,7 +32,7 @@ export type TagAttributes = {
  * since only you know whether the tag is selected.
  *
  * ```ts
- * <button {...tag({ selectable: true })} aria-pressed="true">Housing benefit</button>
+ * <button {...tag({ selectable: true })} aria-pressed="true">Cutter</button>
  * ```
  */
 export const tag = Object.assign(

package/src/components/css/toggle-group/toggle-group.ts

@@ -23,7 +23,7 @@ export type ToggleGroupAttributes = {
  * <fieldset {...toggleGroup()}>
  *   <legend class="lt-sr-only">View</legend>
  *   <label class={toggleGroup.option}>
- *     <input type="radio" name="view" value="list" checked /> List
+ *     <input type="radio" name="view" value="dry" checked /> Dry
  *   </label>
  * </fieldset>
  * ```

package/src/components/css/tooltip/tooltip.ts

@@ -23,8 +23,8 @@ export type TooltipAttributes = {
  *
  * ```ts
  * <span {...tooltip()}>
- *   <button aria-describedby="hint">Archive</button>
- *   <span class={tooltip.bubble} role="tooltip" id="hint">Moves it to the archive</span>
+ *   <button aria-describedby="hint">Appraise</button>
+ *   <span class={tooltip.bubble} role="tooltip" id="hint">At street value</span>
  * </span>
  * ```
  */

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

@@ -25,7 +25,12 @@ export const dialogColors = [
 export type DialogColor = (typeof dialogColors)[number]
 
 export type DialogOptions = {
-  /** Id of the heading. The dialog takes its name from it with `aria-labelledby`. */
+  /**
+   * Id of the heading. The dialog takes its name from it with
+   * `aria-labelledby`. 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.
+   */
   titleId: string
   /**
    * The dialog is open. Default: closed.
@@ -36,7 +41,7 @@ export type DialogOptions = {
    */
   open?: boolean
   /**
-   * Colour of the header. Default: none.
+   * Colour of the header. Default: `neutral`, which gives none.
    *
    * The colour applies to `header`, so the header must be in the markup for
    * it to show: `<div {...box.header}>` around the heading. Without a header
@@ -94,15 +99,15 @@ export type DialogAttributes = {
  *   turns it into a modal.
  *
  * ```ts
- * const box = lt.dialog({ titleId: "delete-title", open: true })
+ * const box = lt.dialog({ titleId: "cancel-title", open: true })
  * ```
  * ```html
  * <lt-dialog {...box.host}>
  *   <dialog {...box.dialog}>
- *     <h2 {...box.title}>Delete the application?</h2>
- *     <div {...box.body}>The application and its attachments will be gone.</div>
+ *     <h2 {...box.title}>Cancel job 222-0481?</h2>
+ *     <div {...box.body}>The crew keeps the advance. This cannot be undone.</div>
  *     <form method="dialog" {...box.footer}>
- *       <button class="lt-button" value="cancel">Cancel</button>
+ *       <button class="lt-button" value="keep">Keep the job</button>
  *     </form>
  *   </dialog>
  * </lt-dialog>

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

@@ -65,8 +65,8 @@ export const LT_DIALOG_PARTS = {
  * ```html
  * <lt-dialog open>
  *   <dialog class="lt-dialog" aria-labelledby="title" open>
- *     <h2 class="lt-dialog__title" id="title">The decision is registered</h2>
- *     <div class="lt-dialog__body">The case has been processed.</div>
+ *     <h2 class="lt-dialog__title" id="title">The order is placed</h2>
+ *     <div class="lt-dialog__body">Job 222-0481 is open to crews.</div>
  *     <form method="dialog" class="lt-dialog__footer">
  *       <button class="lt-button" value="close">Close</button>
  *     </form>
@@ -237,7 +237,7 @@ export class LtDialog extends HostElement {
   }
 
   /**
-   * Fills in what a template without JavaScript did not write: the class on
+   * Fills in what a template without a builder function did not write: the class on
    * the dialog, and the title. The title is what `aria-labelledby` points to
    * when the server wrote it, otherwise the first heading outside the body,
    * and only when the dialog does not already have a name from `aria-label`.
@@ -449,7 +449,7 @@ export class LtDialog extends HostElement {
      * run. When something wrote `open` on the host in the meantime, such as a
      * framework setting the same value again, the component opened the dialog
      * again and cleared `returnValue`, and a listener on `close` read an empty
-     * value instead of "delete". `returnValue` is cleared every time the
+     * value instead of "cancel". `returnValue` is cleared every time the
      * dialog opens, so a value here comes from a button in this round.
      */
     if (
@@ -478,9 +478,9 @@ export class LtDialog extends HostElement {
       /*
        * Escape and `close()` without an argument leave the previous
        * `returnValue` in place. A dialog the server opened again then
-       * reported "delete" from last time when it was closed from the server,
-       * and the app that tells "Cancel" from "Delete" by the value deleted
-       * something the user never asked for.
+       * reported "cancel" from last time when it was closed from the server,
+       * and the app that tells "Keep the job" from "Cancel the job" by the
+       * value cancelled something the user never asked for.
        */
       dialog.returnValue = ""
       dialog.showModal()

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

@@ -6,7 +6,11 @@ export const ERROR_SUMMARY_TITLE_CLASS = "lt-error-summary__title" as const
 export type ErrorSummaryOptions = {
   /** The number of errors the server found. When it is zero, the box is hidden. */
   count?: number
-  /** The id of the box, so the form can move focus here after submission. */
+  /**
+   * The id of the box, so the form can move focus here after submission.
+   * 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
   /**
    * The id of the heading. The box takes its name from it with
@@ -50,7 +54,7 @@ export type ErrorSummaryAttributes = {
  * ```html
  * <lt-error-summary {...summary.host}>
  *   <h2 {...summary.title}>You need to fix 2 errors</h2>
- *   <ul><li><a href="#email">The email address is missing an @</a></li></ul>
+ *   <ul><li><a href="#fixer">The fixer's address is missing an @</a></li></ul>
  * </lt-error-summary>
  * ```
  */

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

@@ -26,10 +26,10 @@ export const LT_ERROR_SUMMARY_PARTS = {
  * Takes the user from an error in the summary to the field that failed.
  *
  * The server writes the content: the heading and the list of links. When the
- * markup is written with JavaScript, `lt.errorSummary()` also writes the
- * 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
+ * markup is written with a builder function, `lt.errorSummary()` also writes
+ * the class, `role="alert"` and `tabindex="-1"` on the box, and the component
+ * leaves them alone. When the markup comes from a template without one, the
+ * component fills in those three and the class on the
  * 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
@@ -49,7 +49,7 @@ export const LT_ERROR_SUMMARY_PARTS = {
  * <lt-error-summary>
  *   <h2>The form has two errors</h2>
  *   <ul class="lt-list">
- *     <li><a href="#email">Enter a valid email address</a></li>
+ *     <li><a href="#fixer">Enter a valid address</a></li>
  *   </ul>
  * </lt-error-summary>
  * ```
@@ -185,7 +185,7 @@ export class LtErrorSummary extends HostElement {
   }
 
   /**
-   * Fills in what a template without JavaScript did not write. Only what is
+   * Fills in what a template without a builder function did not write. Only what is
    * missing: a role the server chose stays, and so does a `tabindex`.
    */
   private wire(): void {

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

@@ -17,10 +17,12 @@ export { createFieldId }
 
 export type FieldOptions = {
   /**
-   * The id of the control. Required.
+   * The id of the control. Required. 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.
    *
    * In React it comes from `useId()`. Otherwise the field's name is usually
-   * the obvious choice. If you know for certain that the markup is rendered
+   * the obvious choice, and in a loop the name with the row's key. If you know for certain that the markup is rendered
    * once, call `createFieldId()` yourself.
    *
    * It used to be optional, and the function created one when it was

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

@@ -124,10 +124,11 @@ function readControlWord(control: Element): ControlWord {
 /**
  * Connects label, control, help text and error text in plain DOM.
  *
- * The component is for markup produced without JavaScript: a Go template, a
- * PHP file, a Razor view or handwritten HTML. When the markup is written with
- * JavaScript, wherever the code runs, `lt.field()` should write the
- * attributes instead, and this element is not needed.
+ * The component is for markup from code that cannot call a builder function:
+ * a Go template, a PHP file, a Razor view or handwritten HTML. When the code
+ * can, in TypeScript wherever it runs, or in Kotlin or Java, `lt.field()` or
+ * `Lt.field()` should write the attributes instead, and this element is not
+ * needed.
  *
  * The component renders nothing. It used to insert a `<slot>` element into
  * plain DOM, and since the server did not know about it, Datastar's morph

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

@@ -40,9 +40,9 @@ export const LT_POPOVER_PARTS = {
  * What the top layer does not do is place the panel. `position-anchor` is not
  * yet in every browser, so the position is worked out here.
  *
- * When the markup is made with JavaScript, `lt.popover()` writes the wiring:
- * `aria-controls` on the button, and the class, the id and `popover` on the
- * panel. When the markup comes from a template without JavaScript, the
+ * When the markup is made with a builder function, `lt.popover()` writes the
+ * wiring: `aria-controls` on the button, and the class, the id and `popover`
+ * on the panel. When the markup comes from a template without one, the
  * template writes a button and a panel with the class `lt-popover` and an id:
  * the component sets `popover="manual"` and writes `aria-controls` on the
  * button from the id. Only what is missing, so what the server wrote stays.

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

@@ -16,7 +16,11 @@ export function isPopoverPlacement(value: unknown): value is PopoverPlacement {
 }
 
 export type PopoverOptions = {
-  /** Id of the panel. Connects the button to the panel with `aria-controls`. */
+  /**
+   * Id of the panel. Connects the button to the panel with `aria-controls`.
+   * 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
   /** The panel is open. Default: closed. */
   open?: boolean
@@ -52,8 +56,8 @@ export type PopoverAttributes = {
  * ```
  * ```html
  * <lt-popover>
- *   <button {...box.trigger}>What does this mean?</button>
- *   <div {...box.panel}>We use the date of birth to find the right rate.</div>
+ *   <button {...box.trigger}>What is the late fee?</button>
+ *   <div {...box.panel}>EB 100 a night past the return date. No exceptions.</div>
  * </lt-popover>
  * ```
  */

package/src/components/frame/session-timeout/lt-session-timeout.ts

@@ -141,9 +141,9 @@ function deepActiveElement(): HTMLElement | null {
  * Warns before a signed-in session expires.
  *
  * This is the thing every large organisation builds itself and gets wrong.
- * Either no warning comes, and the user loses a half-filled application
- * form, or the dialog steals focus in the middle of a sentence, or the
- * screen reader reads the countdown every second.
+ * Either no warning comes, and the user loses a half-filled form, or the
+ * dialog steals focus in the middle of a sentence, or the screen reader
+ * reads the countdown every second.
  *
  * The renderer writes the dialog and the text, so the warning is in the
  * language the app uses, with the translation tool the app already has. The
@@ -163,14 +163,14 @@ function deepActiveElement(): HTMLElement | null {
  * ```html
  * <lt-session-timeout warn-at="1500" expires-at="1800" data-ignore-morph>
  *   <dialog class="lt-session-timeout__dialog" role="alertdialog" aria-labelledby="session">
- *     <h2 class="lt-session-timeout__title" id="session">You will soon be signed out</h2>
+ *     <h2 class="lt-session-timeout__title" id="session">Your session is ending</h2>
  *     <p class="lt-session-timeout__text">
- *       We will sign you out in <span class="lt-session-timeout__count" aria-hidden="true"></span>.
+ *       Your session on the Lattice ends in <span class="lt-session-timeout__count" aria-hidden="true"></span>. Unsaved routes will be lost.
  *     </p>
  *     <span class="lt-sr-only" role="status"></span>
  *     <form method="dialog" class="lt-session-timeout__actions">
- *       <button class="lt-button" value="extend">Stay signed in</button>
- *       <button class="lt-button" data-variant="secondary" value="logout">Sign out now</button>
+ *       <button class="lt-button" value="extend">Stay connected</button>
+ *       <button class="lt-button" data-variant="secondary" value="logout">Log out</button>
  *     </form>
  *   </dialog>
  * </lt-session-timeout>
@@ -224,7 +224,7 @@ export class LtSessionTimeout extends HostElement {
    * `close` arrives in a later task than the click that closed the dialog.
    * When the clock ticked in between, `tick()` opened the dialog again and
    * cleared `returnValue`, and the queued event then read `""` and extended
-   * the session: the user pressed "Sign out now", and the app got
+   * the session: the user pressed "Log out", and the app got
    * `session-extend`.
    */
   private shownDialog?: HTMLDialogElement

package/src/components/frame/session-timeout/session-timeout.ts

@@ -15,7 +15,12 @@ export const SESSION_EXTEND = "extend" as const
 export const SESSION_LOGOUT = "logout" as const
 
 export type SessionTimeoutOptions = {
-  /** Id of the heading. The dialog takes its name from it with `aria-labelledby`. */
+  /**
+   * Id of the heading. The dialog takes its name from it with
+   * `aria-labelledby`. 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.
+   */
   titleId: string
   /** Seconds without activity before the warning appears. Default: 25 minutes. */
   warnAt?: number
@@ -76,14 +81,14 @@ export type SessionTimeoutAttributes = {
  * ```html
  * <lt-session-timeout {...session.host}>
  *   <dialog {...session.dialog}>
- *     <h2 {...session.title}>You will soon be signed out</h2>
+ *     <h2 {...session.title}>Your session is ending</h2>
  *     <p {...session.text}>
- *       We will sign you out in <span {...session.count}></span>.
+ *       Your session on the Lattice ends in <span {...session.count}></span>. Unsaved routes will be lost.
  *     </p>
  *     <span {...session.live}></span>
  *     <form {...session.actions}>
- *       <button {...session.extend}>Stay signed in</button>
- *       <button {...session.logout}>Sign out now</button>
+ *       <button {...session.extend}>Stay connected</button>
+ *       <button {...session.logout}>Log out</button>
  *     </form>
  *   </dialog>
  * </lt-session-timeout>