@lo-tek/interfaces 0.39.0 → 0.41.0

package/src/components/frame/term/term.css

@@ -0,0 +1,177 @@
+@layer lotek {
+  /* The word. It is a link, but reads as part of the sentence: the colour
+     is the text's, and the dotted line says it has an explanation. */
+  .lt-term {
+    color: inherit;
+    text-decoration-line: underline;
+    text-decoration-style: dotted;
+    text-decoration-color: var(
+      --lt-term-underline-color,
+      var(--lt-color-accent-fill)
+    );
+    text-decoration-thickness: 0.1em;
+    text-underline-offset: 0.2em;
+  }
+
+  /* Only where there is a pointer that hovers. iOS keeps `:hover` on a
+     link after a tap, and the line stayed solid until the next tap
+     somewhere else. */
+  @media (hover: hover) {
+    .lt-term:hover {
+      text-decoration-style: solid;
+    }
+  }
+
+  /* The word whose card is open, so the reader sees what the card belongs
+     to. It matters most on a narrow screen, where the card is a sheet at
+     the edge of the window and not next to the word. */
+  .lt-term[aria-expanded="true"] {
+    text-decoration-style: solid;
+    background: var(--lt-color-accent-surface);
+    border-radius: var(--lt-spacing-0-5);
+  }
+
+  .lt-term:focus-visible {
+    outline: var(--lt-focus-ring);
+    outline-offset: 2px;
+    border-radius: var(--lt-spacing-0-5);
+  }
+
+  /* The card is the glossary entry itself, in the top layer while
+     `<lt-term>` has it open. Every rule stands on `:popover-open`, so the
+     entry looks as the page made it everywhere else. */
+  .lt-term__entry:popover-open {
+    /* The position is relative to the viewport. The values are set by the
+       web component, which works them out against the word. */
+    position: fixed;
+    inset: auto;
+    inset-block-start: var(--lt-term-top, 0);
+    inset-inline-start: var(--lt-term-left, 0);
+    margin: 0;
+    /* The space between the word and the card. The web component reads it
+       from here, where the browser has turned it into pixels, and places the
+       card with it. The card is never scrolled to, so the property does
+       nothing else. */
+    scroll-margin-block-start: var(--lt-term-gap, var(--lt-spacing-2));
+    box-sizing: border-box;
+    inline-size: max-content;
+    max-inline-size: var(
+      --lt-term-width,
+      min(22rem, calc(100vw - var(--lt-spacing-8)))
+    );
+    padding: var(--lt-term-padding, var(--lt-spacing-3) var(--lt-spacing-4));
+    font-family: inherit;
+    font-size: var(--lt-font-size-m);
+    line-height: var(--lt-line-height-default);
+    color: var(--lt-color-neutral-text-strong);
+    background: var(--lt-color-neutral-surface);
+    border: 1px solid var(--lt-color-neutral-border-strong);
+    border-inline-start: var(--lt-spacing-1) solid
+      var(--lt-term-accent-color, var(--lt-color-accent-fill));
+    border-radius: var(--lt-term-radius, var(--lt-spacing-1));
+    box-shadow: var(--lt-shadow-overlay);
+    /* An explanation taller than the window scrolls in the card rather
+       than running off the screen. */
+    max-block-size: calc(100dvh - var(--lt-spacing-4));
+    overflow-y: auto;
+    /* Scrolling to the end of the explanation stops there. Otherwise it
+       went on to the page behind, the word left the view, and the card
+       closed while the reader was still in it. */
+    overscroll-behavior: contain;
+  }
+
+  /* `--lt-term-left` is the distance from the left edge of the viewport.
+     `inset-inline-start` is the right edge in a right-to-left document, so
+     there it is flipped, as on the popover. */
+  .lt-term__entry:popover-open:dir(rtl) {
+    inset-inline-start: auto;
+    inset-inline-end: var(--lt-term-left, 0);
+  }
+
+  /* On a narrow screen the card is a sheet across the window, at the
+     bottom, or at the top when the word is down where the sheet would
+     cover it. A card by the word covered the lines the reader was about to
+     read, and closing it meant reaching for the middle of the screen.
+     `--lt-term-sheet` tells the web component which form the card has; the
+     stylesheet is the one place that decides. The width is `sm` in the
+     breakpoints in `tokens.ts`: a media query cannot read a variable. */
+  @media (width < 640px) {
+    .lt-term__entry:popover-open {
+      --lt-term-sheet: 1;
+      inset-inline: 0;
+      inline-size: auto;
+      max-inline-size: none;
+      max-block-size: var(--lt-term-sheet-height, 60dvh);
+      padding-block-end: calc(
+        var(--lt-spacing-3) +
+        env(safe-area-inset-bottom, 0px)
+      );
+      border-radius: 0;
+      border-inline-end: none;
+    }
+
+    /* The direction does not matter across the whole width. Without this
+       the rule above for right to left won, and the sheet hung from the
+       word. */
+    .lt-term__entry:popover-open:dir(rtl) {
+      inset-inline: 0;
+    }
+  }
+
+  /* The label over the term. CSS cannot import a text, so it is read from a
+     variable with the English text as the fallback. */
+  .lt-term__entry:popover-open::before {
+    content: var(--lt-term-label-text, "Glossary");
+    display: block;
+    margin-block-end: var(--lt-spacing-1);
+    font-family: var(--lt-term-label-font, inherit);
+    font-size: var(--lt-font-size-xs);
+    line-height: var(--lt-line-height-compact);
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    color: var(--lt-color-accent-text);
+  }
+
+  .lt-term__entry:popover-open > dt {
+    margin: 0;
+    font-weight: var(--lt-font-weight-semibold);
+  }
+
+  .lt-term__entry:popover-open > dd {
+    margin: 0;
+  }
+
+  @starting-style {
+    .lt-term__entry:popover-open {
+      opacity: 0;
+    }
+  }
+
+  @media (prefers-reduced-motion: no-preference) {
+    .lt-term__entry:popover-open {
+      transition: opacity 120ms ease;
+    }
+  }
+
+  /* More contrast: the line under the word is solid and in the text's own
+     colour, and the card's edge is as strong as the text. */
+  @media (prefers-contrast: more) {
+    .lt-term {
+      text-decoration-style: solid;
+      text-decoration-color: currentColor;
+    }
+
+    .lt-term__entry:popover-open {
+      border-block-color: var(--lt-color-neutral-text-strong);
+      border-inline-end-color: var(--lt-color-neutral-text-strong);
+    }
+  }
+
+  /* High contrast: the shadow is removed and the surface is the page's, so
+     the edge is what holds the card apart from the text under it. */
+  @media (forced-colors: active) {
+    .lt-term__entry:popover-open {
+      border-color: CanvasText;
+    }
+  }
+}

package/src/components/frame/term/term.ts

@@ -0,0 +1,87 @@
+import { attributes } from "../../css/shared.js"
+
+export const TERM_CLASS = "lt-term" as const
+export const TERM_ENTRY_CLASS = "lt-term__entry" as const
+
+export type TermOptions = {
+  /**
+   * Id of the entry in the glossary: the `<div>` around the `<dt>` and
+   * `<dd>`. The word links to it, and the web component shows the entry
+   * itself as the card. Make it from the term, such as `term-signal`, so it
+   * is the same on every render.
+   */
+  id: string
+}
+
+export type TermAttributes = {
+  word: {
+    class: typeof TERM_CLASS
+    href: string
+    "aria-details": string
+  }
+  entry: {
+    class: typeof TERM_ENTRY_CLASS
+    id: string
+  }
+}
+
+/**
+ * The attributes for a word in the text that is explained in a glossary on
+ * the same page.
+ *
+ * Only what holds without JavaScript: the word is a link to the entry, and
+ * `aria-details` says the entry explains it. `<lt-term>` around the link
+ * opens the entry as a card by the word, and writes `aria-expanded`.
+ *
+ * ```ts
+ * const signal = lt.term({ id: "term-signal" })
+ * ```
+ * ```html
+ * <p>Datastar keeps <lt-term><a {...signal.word}>signals</a></lt-term> in the browser.</p>
+ * <dl>
+ *   <div {...signal.entry}><dt>Signal</dt><dd>A value Datastar keeps in the browser.</dd></div>
+ * </dl>
+ * ```
+ */
+export function term({ id }: TermOptions): TermAttributes {
+  // A made-up id would point at nothing: the entry is in the glossary, and
+  // only the template knows its id.
+  if (typeof id !== "string" || id.trim() === "") {
+    throw new Error(
+      "lt.term(): id is required. It is the id of the entry in the glossary, " +
+        'such as "term-signal".',
+    )
+  }
+  return {
+    word: attributes({
+      class: TERM_CLASS,
+      href: `#${id}`,
+      "aria-details": id,
+    }),
+    entry: attributes({
+      class: TERM_ENTRY_CLASS,
+      id,
+    }),
+  }
+}
+
+/**
+ * `lt.term()` with the state `<lt-term>` writes, for `/react`.
+ *
+ * React reports a mismatch for every attribute a web component writes on an
+ * element React has rendered. `aria-expanded="false"` is there from the
+ * start, so the web component has nothing to write before React hydrates.
+ */
+export function termWithState(options: TermOptions): {
+  word: TermAttributes["word"] & { "aria-expanded": "false" }
+  entry: TermAttributes["entry"]
+} {
+  const built = term(options)
+  return {
+    word: attributes(
+      { ...built.word, "aria-expanded": "false" as const },
+      built.word,
+    ),
+    entry: built.entry,
+  }
+}

package/src/components/host-element.ts

@@ -587,3 +587,49 @@ export async function whenUpgraded<T extends HTMLElement>(
   customElements.upgrade(element)
   return element as T
 }
+
+/** The space between a panel and the window's edge. */
+const PLACE_EDGE = 4
+
+/**
+ * Where a panel in the top layer goes next to the element that opened it,
+ * as distances from the window's top and left edge.
+ *
+ * `below` asks for the panel under the anchor, otherwise over it, and
+ * `alignRight` lines the panel's right edge up with the anchor's. `gap` is
+ * the space between the anchor and the panel. 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 anchor that was asked for, it goes on the other side, and
+ * is then clamped into the viewport either way.
+ *
+ * `<lt-popover>` and `<lt-term>` place their panels with it, and write the
+ * answer as two variables the stylesheet reads. It lives here so a copy from
+ * `lotek takeover` finds it through `@lo-tek/interfaces/host-element`.
+ */
+export function place(
+  anchor: DOMRect,
+  panel: DOMRect,
+  below: boolean,
+  alignRight: boolean,
+  gap = 4,
+): { top: number; left: number } {
+  // The viewport a fixed box lives in, without a classic scrollbar:
+  // `innerWidth` counts it, and a panel pushed in from the right edge sat
+  // under the scrollbar on Windows and Linux.
+  const width = document.documentElement.clientWidth || window.innerWidth
+  const height = document.documentElement.clientHeight || window.innerHeight
+  let top = below ? anchor.bottom + gap : anchor.top - panel.height - gap
+  let left = alignRight ? anchor.right - panel.width : anchor.left
+
+  // `top-*` lacked the vertical clamp once, and a panel at the top of the
+  // page lay entirely off screen, with no way to scroll it into view.
+  left = Math.max(PLACE_EDGE, Math.min(left, width - panel.width - PLACE_EDGE))
+  if (below && top + panel.height > height) {
+    top = anchor.top - panel.height - gap
+  } else if (!below && top < PLACE_EDGE) {
+    top = anchor.bottom + gap
+  }
+  top = Math.max(PLACE_EDGE, Math.min(top, height - panel.height - PLACE_EDGE))
+
+  return { top: Math.round(top), left: Math.round(left) }
+}

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/index.ts

@@ -155,6 +155,8 @@ export type {
 export { spinner } from "./components/css/spinner/spinner.js"
 export type { SrOnlyAttributes } from "./components/css/sr-only/sr-only.js"
 export { srOnly } from "./components/css/sr-only/sr-only.js"
+export type { StepsAttributes } from "./components/css/steps/steps.js"
+export { steps } from "./components/css/steps/steps.js"
 export type {
   SwitchAttributes,
   SwitchOptions,
@@ -207,6 +209,8 @@ export * from "./components/frame/suggestion/lt-suggestion.js"
 export * from "./components/frame/suggestion/suggestion.js"
 export * from "./components/frame/tabs/lt-tabs.js"
 export * from "./components/frame/tabs/tabs.js"
+export * from "./components/frame/term/lt-term.js"
+export * from "./components/frame/term/term.js"
 export * from "./components/standalone/connection-status/connection-status.js"
 export * from "./components/standalone/connection-status/lt-connection-status.js"
 export * from "./components/standalone/toast/lt-toast.js"

package/src/jsx/react.ts

@@ -158,6 +158,8 @@ type LtPopoverAttributes = Host &
     placement?: "bottom-start" | "bottom-end" | "top-start" | "top-end"
   }
 
+type LtTermAttributes = Host
+
 type LtSessionTimeoutAttributes = Host & {
   /** Seconds without activity before the warning appears. */
   "warn-at"?: number | string
@@ -192,6 +194,7 @@ declare module "react" {
       "lt-popover": LtPopoverAttributes
       "lt-suggestion": LtSuggestionAttributes
       "lt-tabs": LtTabsAttributes
+      "lt-term": LtTermAttributes
       "lt-session-timeout": LtSessionTimeoutAttributes
       "lt-connection-status": LtConnectionStatusAttributes
       "lt-toast": LtToastAttributes
@@ -208,5 +211,6 @@ export type {
   LtSessionTimeoutAttributes,
   LtSuggestionAttributes,
   LtTabsAttributes,
+  LtTermAttributes,
   LtToastAttributes,
 }

package/src/lt.ts

@@ -33,6 +33,7 @@ import { skeleton } from "./components/css/skeleton/skeleton.js"
 import { skipLink } from "./components/css/skip-link/skip-link.js"
 import { spinner } from "./components/css/spinner/spinner.js"
 import { srOnly } from "./components/css/sr-only/sr-only.js"
+import { steps } from "./components/css/steps/steps.js"
 import { switchControl } from "./components/css/switch/switch.js"
 import { table, tableSort } from "./components/css/table/table.js"
 import { tag } from "./components/css/tag/tag.js"
@@ -46,6 +47,7 @@ import { popover } from "./components/frame/popover/popover.js"
 import { sessionTimeout } from "./components/frame/session-timeout/session-timeout.js"
 import { suggestion } from "./components/frame/suggestion/suggestion.js"
 import { tabs } from "./components/frame/tabs/tabs.js"
+import { term } from "./components/frame/term/term.js"
 import { connectionStatus } from "./components/standalone/connection-status/connection-status.js"
 import { toast } from "./components/standalone/toast/toast.js"
 import { setAttributes } from "./dom.js"
@@ -98,16 +100,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.errorText()} {...field.error}>Enter a valid address.</p>
+   * <p {...lt.helpText()} {...field.help}>The board writes to the fixer, never to the crew.</p>
+   * <p {...lt.errorText()} {...field.error}>Enter the fixer's address, for example fixer@relay.example.</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`. */
@@ -143,6 +145,7 @@ export const lt = {
   spinner,
   /** Text only screen readers get. Requires `sr-only.css`. */
   srOnly,
+  steps,
   /**
    * The field and the suggestion list. `<lt-suggestion>` handles the
    * keyboard and the filtering, the server writes the markup.
@@ -169,6 +172,11 @@ export const lt = {
    */
   tableSort,
   tag,
+  /**
+   * A word in the text, linked to its entry in a glossary on the same page.
+   * `<lt-term>` around the link shows the entry as a card by the word.
+   */
+  term,
   textarea,
 
   /**

package/src/react.ts

@@ -35,6 +35,7 @@ import { skeleton } from "./components/css/skeleton/skeleton.js"
 import { skipLink } from "./components/css/skip-link/skip-link.js"
 import { spinner } from "./components/css/spinner/spinner.js"
 import { srOnly } from "./components/css/sr-only/sr-only.js"
+import { steps } from "./components/css/steps/steps.js"
 import { switchControl } from "./components/css/switch/switch.js"
 import { table, tableSort } from "./components/css/table/table.js"
 import { tag } from "./components/css/tag/tag.js"
@@ -55,6 +56,7 @@ import {
   type TabsWithStateOptions,
   tabsWithState,
 } from "./components/frame/tabs/tabs.js"
+import { termWithState } from "./components/frame/term/term.js"
 import { connectionStatus } from "./components/standalone/connection-status/connection-status.js"
 import { toast } from "./components/standalone/toast/toast.js"
 import { type Attributes, setAttributes as setHtmlAttributes } from "./dom.js"
@@ -261,6 +263,7 @@ export const lt = {
   progress: forReact(progress),
   spinner: forReact(spinner),
   srOnly: forReact(srOnly),
+  steps: forReact(steps),
   switch: forReact(switchControl),
   toggleGroup: forReact(toggleGroup),
   tooltip: forReact(tooltip),
@@ -354,6 +357,18 @@ export const lt = {
     }
   },
 
+  /**
+   * With `aria-expanded`, which `<lt-term>` writes: React reports a mismatch
+   * for an attribute it did not render. See `termWithState`.
+   */
+  term: (options: Parameters<typeof termWithState>[0]) => {
+    const built = termWithState(options)
+    return {
+      word: toReactAttributes(built.word),
+      entry: toReactAttributes(built.entry),
+    }
+  },
+
   suggestion: (options: Parameters<typeof suggestion>[0]) => {
     const built = suggestion(options)
     return {

package/src/register.ts

@@ -20,6 +20,7 @@ import { defineLtPopover } from "./components/frame/popover/lt-popover.js"
 import { defineLtSessionTimeout } from "./components/frame/session-timeout/lt-session-timeout.js"
 import { defineLtSuggestion } from "./components/frame/suggestion/lt-suggestion.js"
 import { defineLtTabs } from "./components/frame/tabs/lt-tabs.js"
+import { defineLtTerm } from "./components/frame/term/lt-term.js"
 import { defineLtConnectionStatus } from "./components/standalone/connection-status/lt-connection-status.js"
 import { defineLtToast } from "./components/standalone/toast/lt-toast.js"
 
@@ -40,4 +41,5 @@ export function defineLt(): void {
   defineLtToast()
   defineLtSessionTimeout()
   defineLtConnectionStatus()
+  defineLtTerm()
 }

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/tokens/tokens.css

@@ -527,6 +527,7 @@
     .lt-skip-link,
     .lt-spinner,
     .lt-sr-only,
+    .lt-steps,
     .lt-suggestion__empty,
     .lt-suggestion__list,
     .lt-suggestion__option,
@@ -539,6 +540,8 @@
     .lt-tabs__list,
     .lt-tabs__panel,
     .lt-tag,
+    .lt-term,
+    .lt-term__entry,
     .lt-textarea,
     .lt-toast,
     .lt-toast__close,
@@ -551,6 +554,7 @@
     lt-tabs,
     lt-error-summary,
     lt-popover,
+    lt-term,
     lt-suggestion,
     lt-dialog,
     lt-toast,