@lo-tek/interfaces 0.39.0 → 0.41.0

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 the fixer's address with an @</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

@@ -3,6 +3,7 @@ import {
   defineElement,
   HostElement,
   isServerControlled,
+  place,
   SERVER_CONTROLLED,
   setAttr,
   setFlag,
@@ -40,9 +41,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.
@@ -507,7 +508,6 @@ export class LtPopover extends HostElement {
 
     const anchor = this.triggerElement.getBoundingClientRect()
     const panel = this.panel.getBoundingClientRect()
-    const space = 4
 
     const below = this.placement.startsWith("bottom")
     // `start` and `end` follow the reading direction: in a right-to-left
@@ -520,30 +520,10 @@ export class LtPopover extends HostElement {
     const rtl = this.panel.matches(":dir(rtl)")
     const alignRight = this.placement.endsWith("end") !== rtl
 
-    let top = below ? anchor.bottom + space : anchor.top - panel.height - space
-    let left = alignRight ? anchor.right - panel.width : anchor.left
-
-    // The panel must not end up off screen. If it goes out at the side, it is
-    // moved in. If there is no room on the side of the button the placement asks
-    // for, it goes on the other side, and is then clamped into the viewport
-    // either way. `top-*` lacked the last part, and a panel at the top of the
-    // page lay entirely off screen, with no way to scroll it into view.
-    left = Math.max(
-      space,
-      Math.min(left, window.innerWidth - panel.width - space),
-    )
-    if (below && top + panel.height > window.innerHeight) {
-      top = anchor.top - panel.height - space
-    } else if (!below && top < space) {
-      top = anchor.bottom + space
-    }
-    top = Math.max(
-      space,
-      Math.min(top, window.innerHeight - panel.height - space),
-    )
+    const { top, left } = place(anchor, panel, below, alignRight)
 
-    this.panel.style.setProperty("--lt-popover-top", `${Math.round(top)}px`)
-    this.panel.style.setProperty("--lt-popover-left", `${Math.round(left)}px`)
+    this.panel.style.setProperty("--lt-popover-top", `${top}px`)
+    this.panel.style.setProperty("--lt-popover-left", `${left}px`)
   }
 
   private emit(open: boolean): void {

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>

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 => {