@lo-tek/interfaces 0.0.0 → 0.38.0

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

@@ -0,0 +1,268 @@
+import { defineElement, HostElement, whenUpgraded } from "../../host-element.js"
+import {
+  CONNECTION_STATUS_BAR_CLASS,
+  CONNECTION_STATUS_CLASS,
+} from "./connection-status.js"
+
+export const LT_CONNECTION_STATUS_TAG = "lt-connection-status" as const
+
+import { DEFAULT_TEXTS } from "../../default-texts.js"
+
+const DEFAULT_OFFLINE = DEFAULT_TEXTS.connectionOffline
+const DEFAULT_ONLINE = DEFAULT_TEXTS.connectionOnline
+
+/** How long "back online" stays visible. */
+const RECEIPT_MS = 4000
+
+/**
+ * Tells the user when the connection to the server is lost.
+ *
+ * By definition the server cannot tell you this. When it is unreachable,
+ * nothing comes from it. So this is a standalone component that creates all
+ * of its content itself.
+ *
+ * It is not decoration in an app that fetches content from the server as it
+ * goes. A page that loses its stream looks perfectly normal but is frozen,
+ * and a user filling in a form over a dead connection loses everything.
+ *
+ * `navigator.onLine` only says whether the machine has a network, not whether
+ * the server answers. That is why `reportFailure()` and `reportSuccess()`
+ * exist: the app calls them when a request fails or succeeds.
+ *
+ * ```ts
+ * const status = document.querySelector("lt-connection-status")
+ * try {
+ *   const response = await fetch("/api/save", { method: "POST", body })
+ *   if (!response.ok) throw new Error(response.statusText)
+ *   status.reportSuccess()
+ * } catch {
+ *   status.reportFailure()
+ * }
+ * ```
+ */
+export class LtConnectionStatus extends HostElement {
+  static observedAttributes = ["offline-text", "online-text"] as const
+
+  private bar?: HTMLElement
+  private timer?: number
+  /** True when the app has reported a failed request, regardless of navigator. */
+  private failing = false
+
+  get offlineText(): string {
+    return this.getAttribute("offline-text") ?? DEFAULT_OFFLINE
+  }
+
+  set offlineText(value: string) {
+    this.setAttribute("offline-text", value)
+  }
+
+  get onlineText(): string {
+    return this.getAttribute("online-text") ?? DEFAULT_ONLINE
+  }
+
+  set onlineText(value: string) {
+    this.setAttribute("online-text", value)
+  }
+
+  attributeChangedCallback(): void {
+    // If the text changes while the bar is showing, as when the language
+    // changes, the bar says the new one. `textContent` is only written when
+    // the text differs.
+    const bar = this.bar
+    if (!bar || bar.textContent === "") return
+    const text =
+      bar.dataset.state === "offline" ? this.offlineText : this.onlineText
+    if (bar.textContent !== text) bar.textContent = text
+  }
+
+  connectedCallback(): void {
+    this.classList.add(CONNECTION_STATUS_CLASS)
+    /*
+     * The host is the live region, from the moment it is connected, so the
+     * region exists long before the bar and its text arrive. Only what is
+     * missing: a role or politeness the server wrote stays. When the bar was
+     * the region, it was inserted together with its text, and Firefox sent
+     * no live-region text through AT-SPI at all, so "No connection" was
+     * never announced. `check-accessibility-tree.ts` checks it.
+     */
+    this.markRegion()
+    // A morph without `data-ignore-morph` takes both off, and then the next
+    // outage is never announced. Writing only what is missing keeps the
+    // observer from triggering itself.
+    this.regionObserver = new MutationObserver(() => this.markRegion())
+    this.regionObserver.observe(this, {
+      attributes: true,
+      attributeFilter: ["role", "aria-live"],
+    })
+    window.addEventListener("offline", this.handleOffline)
+    window.addEventListener("online", this.handleOnline)
+    if (!navigator.onLine) {
+      this.showOffline()
+      return
+    }
+    /*
+     * The element may have been out of the document, and then both the
+     * events and the timer are lost. If the receipt was showing, it stayed
+     * for good, and if the bar said "offline" while the network came back,
+     * it kept saying so until the next time the network dropped. `failing`
+     * is the app's word and not the network's, so it stays.
+     */
+    if (this.bar?.dataset.state === "online") this.scheduleRemoval(this.bar)
+    else if (this.bar?.dataset.state === "offline" && !this.failing) {
+      this.showOnline()
+    }
+  }
+
+  private regionObserver?: MutationObserver
+
+  /**
+   * The region, as a pair and only when both are missing. A role the server
+   * wrote carries its own politeness (`alert` is assertive), and an
+   * `aria-live` added next to it would override that.
+   */
+  private markRegion(): void {
+    if (this.hasAttribute("role") || this.hasAttribute("aria-live")) return
+    this.setAttribute("role", "status")
+    this.setAttribute("aria-live", "polite")
+  }
+
+  disconnectedCallback(): void {
+    this.regionObserver?.disconnect()
+    this.regionObserver = undefined
+    window.removeEventListener("offline", this.handleOffline)
+    window.removeEventListener("online", this.handleOnline)
+    if (this.timer) window.clearTimeout(this.timer)
+    this.timer = undefined
+  }
+
+  /**
+   * The bar, created empty first and filled afterwards.
+   *
+   * A live region must exist before its content arrives, or assistive
+   * technology does not announce the first change. The region is the host
+   * (see `connectedCallback`), so the bar is content inside a region that is
+   * already there; the text is still set in the next frame when the bar is
+   * new, so the bar and its text arrive as two changes.
+   *
+   * The bar is created only when it is needed, not on connection: when it
+   * was in the DOM before React hydrated, React found an element it had not
+   * rendered.
+   */
+  private ensureBar(): { bar: HTMLElement; fresh: boolean } {
+    if (this.bar) return { bar: this.bar, fresh: false }
+
+    const bar = document.createElement("div")
+    bar.className = CONNECTION_STATUS_BAR_CLASS
+    this.append(bar)
+    this.bar = bar
+    return { bar, fresh: true }
+  }
+
+  private write(
+    bar: HTMLElement,
+    fresh: boolean,
+    state: "offline" | "online",
+  ): void {
+    // The text is read when it is written, not when it is scheduled. If
+    // `offline-text` changed in the frame between, the bar wrote the old one.
+    const text = () =>
+      state === "offline" ? this.offlineText : this.onlineText
+    if (!fresh || typeof requestAnimationFrame === "undefined") {
+      bar.textContent = text()
+      return
+    }
+    requestAnimationFrame(() => {
+      // The guard is the state, not the bar: if `reportSuccess()` came in
+      // the same frame, the bar already says "online", and the offline text
+      // must not be written over the receipt.
+      if (this.bar === bar && bar.dataset.state === state) {
+        bar.textContent = text()
+      }
+    })
+  }
+
+  private showOffline(): void {
+    // Browsers often fire several `offline` events in a row, and the app
+    // can report a failure on top of a network that is already gone. If the
+    // bar already says "offline", there is nothing new to write or report:
+    // each write was announced again, and each report gave the app a new
+    // `connection-lost`.
+    if (this.bar?.dataset.state === "offline") return
+
+    if (this.timer) window.clearTimeout(this.timer)
+    const { bar, fresh } = this.ensureBar()
+    bar.dataset.state = "offline"
+    this.write(bar, fresh, "offline")
+    this.emit("connection-lost")
+  }
+
+  private showOnline(): void {
+    if (!this.bar || this.bar.dataset.state === "online") return
+    const bar = this.bar
+    bar.dataset.state = "online"
+    this.write(bar, false, "online")
+    this.emit("connection-restored")
+
+    this.scheduleRemoval(bar)
+  }
+
+  private scheduleRemoval(bar: HTMLElement): void {
+    if (this.timer) window.clearTimeout(this.timer)
+    this.timer = window.setTimeout(() => {
+      bar.remove()
+      this.bar = undefined
+      this.timer = undefined
+    }, RECEIPT_MS)
+  }
+
+  private handleOffline = (): void => {
+    this.showOffline()
+  }
+
+  private handleOnline = (): void => {
+    if (this.failing) return
+    this.showOnline()
+  }
+
+  private emit(name: string): void {
+    this.dispatchEvent(new CustomEvent(name, { bubbles: true, composed: true }))
+  }
+
+  /** Reports that a request to the server failed. */
+  reportFailure(): void {
+    if (this.failing) return
+    this.failing = true
+    this.showOffline()
+  }
+
+  /** Reports that a request to the server succeeded again. */
+  reportSuccess(): void {
+    if (!this.failing) return
+    this.failing = false
+    this.showOnline()
+  }
+}
+
+export function defineLtConnectionStatus(
+  tagName: string = LT_CONNECTION_STATUS_TAG,
+): void {
+  defineElement(tagName, LtConnectionStatus)
+}
+
+/**
+ * `element.reportFailure()`, but waits for the registration first.
+ *
+ * This is where the gap showed up in production: the first message from the
+ * event stream came before `defineLtConnectionStatus()`, and the app got
+ * "reportSuccess is not a function". See `whenUpgraded`.
+ */
+export async function reportFailure(element: Element): Promise<void> {
+  const status = await whenUpgraded<LtConnectionStatus>(element)
+  status.reportFailure()
+}
+
+/** `element.reportSuccess()`, but waits for the registration first. */
+export async function reportSuccess(element: Element): Promise<void> {
+  const status = await whenUpgraded<LtConnectionStatus>(element)
+  status.reportSuccess()
+}

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

@@ -0,0 +1,300 @@
+import { DEFAULT_TEXTS } from "../../default-texts.js"
+import { defineElement, HostElement, whenUpgraded } from "../../host-element.js"
+import { TOAST_CLASS, TOAST_CLOSE_CLASS, TOAST_MESSAGE_CLASS } from "./toast.js"
+
+export const LT_TOAST_TAG = "lt-toast" as const
+
+export const toastColors = ["neutral", "success", "warning", "danger"] as const
+export type ToastColor = (typeof toastColors)[number]
+
+export function isToastColor(value: unknown): value is ToastColor {
+  return (toastColors as readonly unknown[]).includes(value)
+}
+
+const DEFAULT_DURATION = 6000
+const DEFAULT_LABEL = DEFAULT_TEXTS.toastRegion
+const DEFAULT_CLOSE_LABEL = DEFAULT_TEXTS.toastClose
+
+export type ShowOptions = {
+  /** What the message means. Default: `neutral`. */
+  color?: ToastColor
+  /** Milliseconds before the message disappears. `0` keeps it. */
+  duration?: number
+  /**
+   * The screen reader name of the close button. Default: `close-label` on
+   * the host, and otherwise "Close message".
+   */
+  closeLabel?: string
+}
+
+/**
+ * The queue of short messages in the corner of the screen.
+ *
+ * This is one of the standalone components, and part of the package you call
+ * instead of writing markup. The element is the container, not the message:
+ * you put it in the app once and call `show()` when there is something to
+ * report. The messages do not exist until an event on the client creates
+ * them, so there is nothing for the server to render.
+ *
+ * The server writes the container with `lt.toast()`, which sets
+ * `data-ignore-morph`. Without it the Datastar morph tears the messages away
+ * at the next patch, because the server's version of the region is empty.
+ *
+ * The container is a `role="status"` region, not `role="alert"`. A message
+ * that appears in the corner should not interrupt what the screen reader is
+ * doing; if the message is important enough to interrupt, it belongs in an
+ * [Alert](../../css/alert/alert.js) in the page itself. The region has
+ * `aria-atomic="false"`: `status` is atomic by default, and then the whole
+ * stack was announced again for every new message.
+ *
+ * Messages that disappear by themselves are an accessibility trap: someone
+ * who reads slowly or uses magnification does not have time to read them. So
+ * the close button is always there, and the timer stops while the mouse or
+ * focus is in the message.
+ *
+ * ```ts
+ * document.querySelector("lt-toast").show("Application sent", {
+ *   color: "success",
+ * })
+ * ```
+ */
+export class LtToast extends HostElement {
+  static observedAttributes = ["duration", "label", "close-label"] as const
+
+  /**
+   * The screen reader name of the close button in each message shown.
+   * `closeLabel` in `show()` overrides it for one message.
+   */
+  get closeLabel(): string {
+    return this.getAttribute("close-label") || DEFAULT_CLOSE_LABEL
+  }
+
+  set closeLabel(value: string) {
+    this.setAttribute("close-label", value)
+  }
+
+  /** Default lifetime in milliseconds. `0` keeps the messages. */
+  get duration(): number {
+    // `0` is a valid value and means the messages stay. Without the check
+    // against null here they still disappeared after six seconds, and only
+    // `show(..., { duration: 0 })` worked. An empty attribute is not null:
+    // `Number("")` is 0, and `<lt-toast duration>` kept the messages.
+    const raw = this.getAttribute("duration")
+    if (raw === null || raw.trim() === "") return DEFAULT_DURATION
+    const value = Number(raw)
+    return Number.isFinite(value) && value >= 0 ? value : DEFAULT_DURATION
+  }
+
+  set duration(value: number) {
+    this.setAttribute("duration", String(value))
+  }
+
+  /**
+   * Whether the component wrote `aria-label`. Before, `label` overwrote an
+   * `aria-label` the author had set, and when `label` was removed, the old
+   * one stayed.
+   */
+  private ownsLabel = false
+  /**
+   * The element focus came from before it entered a message. If the last
+   * message is removed while it has focus, focus goes back there. Before, it
+   * fell to `body`, and the next Tab started at the top of the page. If
+   * focus came from a screen reader or F6, the origin is not known, and focus
+   * still falls.
+   */
+  private focusOrigin: HTMLElement | null = null
+
+  private rememberOrigin = (event: FocusEvent): void => {
+    const from = event.relatedTarget
+    if (from instanceof HTMLElement && !this.contains(from)) {
+      this.focusOrigin = from
+    }
+  }
+
+  /**
+   * Focus left the region for somewhere else. Then the origin is stale:
+   * without this, focus later came back to an element the user left long
+   * ago, and the page scrolled there. Not when `relatedTarget` is `null`,
+   * because that is also what happens when the message with focus is
+   * removed.
+   */
+  private forgetOrigin = (event: FocusEvent): void => {
+    const to = event.relatedTarget
+    if (to instanceof Node && !this.contains(to)) this.focusOrigin = null
+  }
+
+  /**
+   * Whether focus is in the element. Read from the component's root node,
+   * not from `document`: when the region is in a shadow root, as in every
+   * preview in the documentation, `document.activeElement` points to the
+   * shadow host. Then it looked as if no message had focus, and focus fell
+   * to `body` instead of to the neighbouring message or where it came from.
+   */
+  private holdsFocus(element: Element): boolean {
+    const root = this.getRootNode() as Document | ShadowRoot
+    return element.contains(root.activeElement)
+  }
+
+  private restoreFocus(): void {
+    const origin = this.focusOrigin
+    this.focusOrigin = null
+    // A restore, not a navigation: the page must not scroll.
+    if (origin?.isConnected) origin.focus({ preventScroll: true })
+  }
+
+  disconnectedCallback(): void {
+    this.removeEventListener("focusin", this.rememberOrigin)
+    this.removeEventListener("focusout", this.forgetOrigin)
+    this.focusOrigin = null
+  }
+
+  connectedCallback(): void {
+    this.addEventListener("focusin", this.rememberOrigin)
+    this.addEventListener("focusout", this.forgetOrigin)
+    // If the server wrote the region with lt.toast(), all of this is
+    // already there. Here it is only set when missing, so a plain HTML page
+    // without a builder function also gets a region the screen reader
+    // understands.
+    // The class carries the position. It is set here too, so a region
+    // without a builder function, or registered under another name, ends up
+    // in the corner.
+    this.classList.add(TOAST_CLASS)
+    if (!this.hasAttribute("role")) this.setAttribute("role", "status")
+    if (!this.hasAttribute("aria-live")) {
+      this.setAttribute("aria-live", "polite")
+    }
+    if (!this.hasAttribute("aria-atomic")) {
+      this.setAttribute("aria-atomic", "false")
+    }
+    if (!this.hasAttribute("aria-label")) {
+      this.ownsLabel = true
+      this.setAttribute(
+        "aria-label",
+        this.getAttribute("label") ?? DEFAULT_LABEL,
+      )
+    }
+  }
+
+  attributeChangedCallback(name: string, _old: string, value: string): void {
+    // `label` can be set after the element is in the DOM, for example by a
+    // framework that fills in the attributes in a later step.
+    if (name !== "label" || !this.ownsLabel) return
+    this.setAttribute("aria-label", value || DEFAULT_LABEL)
+  }
+
+  /** Shows a message, and returns the element it was put in. */
+  show(message: string, options: ShowOptions = {}): HTMLElement {
+    const {
+      color = "neutral",
+      duration = this.duration,
+      closeLabel = this.closeLabel,
+    } = options
+
+    const toast = document.createElement("div")
+    toast.className = TOAST_MESSAGE_CLASS
+    // An unknown colour gives no border, instead of a `data-color` without a rule.
+    if (isToastColor(color) && color !== "neutral") toast.dataset.color = color
+
+    const text = document.createElement("span")
+    text.textContent = message
+    toast.append(text)
+
+    const close = document.createElement("button")
+    close.type = "button"
+    close.className = TOAST_CLOSE_CLASS
+    close.setAttribute("aria-label", closeLabel)
+    close.textContent = "×"
+    close.addEventListener("click", () => this.dismiss(toast))
+    toast.append(close)
+
+    this.prepend(toast)
+
+    if (duration > 0) {
+      let timer = window.setTimeout(() => this.dismiss(toast), duration)
+
+      /*
+       * The timer stops while the user reads or is on the way to the close
+       * button, and only runs when neither the mouse nor focus is in the
+       * message. The pause used to be two independent pairs, and the mouse
+       * leaving restarted the clock while focus was in the message: it
+       * disappeared from under the user's fingers.
+       */
+      const holds = new Set<"pointer" | "focus">()
+      const pause = (reason: "pointer" | "focus") => {
+        holds.add(reason)
+        window.clearTimeout(timer)
+      }
+      const resume = (reason: "pointer" | "focus") => {
+        holds.delete(reason)
+        if (holds.size > 0) return
+        window.clearTimeout(timer)
+        timer = window.setTimeout(() => this.dismiss(toast), duration)
+      }
+
+      toast.addEventListener("mouseenter", () => pause("pointer"))
+      toast.addEventListener("mouseleave", () => resume("pointer"))
+      toast.addEventListener("focusin", () => pause("focus"))
+      toast.addEventListener("focusout", (event) => {
+        // Within the message, from the text to the button: still paused.
+        const next = event.relatedTarget
+        if (next instanceof Node && toast.contains(next)) return
+        resume("focus")
+      })
+    }
+
+    return toast
+  }
+
+  /** Removes a message. */
+  dismiss(toast: HTMLElement): void {
+    if (!this.contains(toast)) return
+
+    /*
+     * If focus was in the message, as on the close button after Enter, it
+     * would otherwise fall to `body`, and the next Tab starts at the top of
+     * the page. The neighbouring message is the nearest place to continue
+     * from: the one below, otherwise the one above.
+     */
+    const hadFocus = this.holdsFocus(toast)
+    const neighbour = toast.nextElementSibling ?? toast.previousElementSibling
+    toast.remove()
+    if (hadFocus) {
+      const next = neighbour?.querySelector<HTMLElement>(
+        `.${TOAST_CLOSE_CLASS}`,
+      )
+      if (next) next.focus()
+      else this.restoreFocus()
+    }
+
+    this.dispatchEvent(
+      new CustomEvent("toast-dismiss", { bubbles: true, composed: true }),
+    )
+  }
+
+  /** Removes all the messages. */
+  clear(): void {
+    if (this.holdsFocus(this)) this.restoreFocus()
+    for (const toast of this.querySelectorAll(`.${TOAST_MESSAGE_CLASS}`)) {
+      toast.remove()
+    }
+  }
+}
+
+export function defineLtToast(tagName: string = LT_TOAST_TAG): void {
+  defineElement(tagName, LtToast)
+}
+
+/**
+ * `element.show()`, but waits for `defineLtToast()` to have run first.
+ *
+ * See `whenUpgraded` for why: a call before the registration hit a plain
+ * `HTMLElement` without `show`.
+ */
+export async function showToast(
+  element: Element,
+  message: string,
+  options: ShowOptions = {},
+): Promise<HTMLElement> {
+  const toast = await whenUpgraded<LtToast>(element)
+  return toast.show(message, options)
+}

package/src/components/standalone/toast/toast.css

@@ -0,0 +1,78 @@
+@layer lotek {
+  /* The element name and the class. The name keeps the position when a
+     morph or a `className` from React tears the class away, and the class
+     carries it when the component is registered under another name. */
+  lt-toast,
+  .lt-toast {
+    /* The container is fixed in the corner and lets clicks through, so it
+       does not block buttons beneath it when it is empty. */
+    position: fixed;
+    inset-block-end: var(--lt-toast-space, var(--lt-spacing-4));
+    inset-inline-end: var(--lt-toast-space, var(--lt-spacing-4));
+    z-index: var(--lt-toast-layer, 60);
+    display: flex;
+    flex-direction: column;
+    gap: var(--lt-spacing-2);
+    inline-size: var(
+      --lt-toast-width,
+      min(24rem, calc(100vw - var(--lt-spacing-8)))
+    );
+    pointer-events: none;
+  }
+
+  .lt-toast__message {
+    box-sizing: border-box;
+    display: flex;
+    align-items: flex-start;
+    justify-content: space-between;
+    gap: var(--lt-spacing-3);
+    padding: var(--lt-toast-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-canvas);
+    border: 1px solid var(--lt-color-neutral-border-subtle);
+    border-inline-start: var(--lt-spacing-1) solid var(--lt-color-neutral-text);
+    border-radius: var(--lt-toast-radius, var(--lt-spacing-1));
+    box-shadow: var(--lt-shadow-overlay);
+    pointer-events: auto;
+  }
+
+  .lt-toast__message[data-color="success"] {
+    border-inline-start-color: var(--lt-color-success-text);
+  }
+
+  .lt-toast__message[data-color="warning"] {
+    border-inline-start-color: var(--lt-color-warning-text);
+  }
+
+  .lt-toast__message[data-color="danger"] {
+    border-inline-start-color: var(--lt-color-danger-text);
+  }
+
+  .lt-toast__close {
+    flex: none;
+    min-inline-size: var(--lt-spacing-6);
+    min-block-size: var(--lt-spacing-6);
+    padding: 0;
+    font-family: inherit;
+    font-size: var(--lt-font-size-l);
+    line-height: 1;
+    color: var(--lt-color-neutral-text-subtle);
+    background: transparent;
+    border: 0;
+    border-radius: var(--lt-spacing-1);
+    cursor: pointer;
+  }
+
+  .lt-toast__close:hover {
+    color: var(--lt-color-neutral-text-strong);
+    background: var(--lt-color-neutral-surface);
+  }
+
+  .lt-toast__close:focus-visible {
+    outline: var(--lt-focus-ring);
+    outline-offset: 2px;
+  }
+}