@lo-tek/interfaces 0.0.0 → 0.37.0

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

@@ -0,0 +1,58 @@
+@layer lotek {
+  .lt-tag {
+    box-sizing: border-box;
+    display: inline-flex;
+    align-items: center;
+    gap: var(--lt-spacing-1);
+    padding: var(--lt-tag-padding, var(--lt-spacing-0-5) var(--lt-spacing-2));
+    font-family: inherit;
+    font-size: var(--lt-font-size-s);
+    line-height: var(--lt-line-height-compact);
+    color: var(--lt-color-neutral-text-strong);
+    background: transparent;
+    border: 1px solid var(--lt-color-neutral-border-subtle);
+    border-radius: var(--lt-tag-radius, var(--lt-spacing-1));
+  }
+
+  .lt-tag[data-variant="filled"] {
+    background: var(--lt-color-neutral-surface);
+    border-color: transparent;
+  }
+
+  /* The tag can be toggled on and off, and is then a real button. */
+  .lt-tag[data-selectable] {
+    cursor: pointer;
+  }
+
+  .lt-tag[data-selectable]:hover {
+    border-color: var(--lt-color-accent-border);
+  }
+
+  .lt-tag[data-selectable]:focus-visible {
+    outline: var(--lt-focus-ring);
+    outline-offset: 2px;
+  }
+
+  .lt-tag[aria-pressed="true"] {
+    background: var(--lt-color-accent-fill);
+    border-color: var(--lt-color-accent-fill);
+    color: var(--lt-color-accent-content);
+  }
+
+  .lt-tag:disabled,
+  .lt-tag[aria-disabled="true"] {
+    background: var(--lt-color-disabled-surface);
+    border-color: var(--lt-color-disabled-surface);
+    color: var(--lt-color-disabled-text);
+    cursor: not-allowed;
+  }
+
+  /* High contrast: the selected tag differs only by colour. System colours
+     get through where ours do not. */
+  @media (forced-colors: active) {
+    .lt-tag[aria-pressed="true"] {
+      background-color: Highlight;
+      color: HighlightText;
+    }
+  }
+}

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

@@ -0,0 +1,49 @@
+import { attributes, createGuard } from "../shared.js"
+
+export const TAG_CLASS = "lt-tag" as const
+
+export const tagVariants = ["outline", "filled"] as const
+
+export type TagVariant = (typeof tagVariants)[number]
+export type NonDefaultTagVariant = Exclude<TagVariant, "outline">
+
+export type TagOptions = {
+  /** Outline or muted surface. Default: `outline`. */
+  variant?: TagVariant
+  /** The tag can be toggled on and off. Use only on a `<button>`. */
+  selectable?: boolean
+}
+
+export type TagAttributes = {
+  class: typeof TAG_CLASS
+  "data-variant"?: NonDefaultTagVariant
+  "data-selectable"?: ""
+}
+
+/**
+ * The attributes for a tag.
+ *
+ * A tag labels content: keywords on an article, selected filters above a
+ * list. If it says what state something is in, [Badge](../badge/badge.js)
+ * is right instead.
+ *
+ * `selectable` gives hover and a focus ring, but makes nothing pressable.
+ * The element must be a `<button>`, and you set `aria-pressed` yourself,
+ * since only you know whether the tag is selected.
+ *
+ * ```ts
+ * <button {...tag({ selectable: true })} aria-pressed="true">Housing benefit</button>
+ * ```
+ */
+export const tag = Object.assign(
+  ({ variant = "outline", selectable }: TagOptions = {}): TagAttributes =>
+    attributes({
+      class: TAG_CLASS,
+      "data-variant": variant === "outline" ? undefined : variant,
+      "data-selectable": selectable ? ("" as const) : undefined,
+    }),
+  {
+    variants: tagVariants,
+    isVariant: createGuard(tagVariants),
+  },
+)

package/src/components/css/textarea/textarea.css

@@ -0,0 +1,83 @@
+@layer lotek {
+  .lt-textarea {
+    /* The design system cannot assume the consumer has a CSS reset. Without
+       border-box, padding and border are added outside the width, and the
+       field becomes wider than the box it sits in. */
+    box-sizing: border-box;
+
+    display: block;
+    width: 100%;
+    min-height: var(--lt-textarea-min-height, calc(var(--lt-spacing-4) * 5));
+    padding: var(
+      --lt-textarea-padding,
+      var(--lt-spacing-2) var(--lt-spacing-3)
+    );
+    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);
+    border-radius: var(--lt-textarea-radius, var(--lt-spacing-1));
+    resize: vertical;
+  }
+
+  .lt-textarea::placeholder {
+    color: var(--lt-color-neutral-text-subtle);
+  }
+
+  .lt-textarea:hover {
+    border-color: var(--lt-color-neutral-border-strong);
+  }
+
+  .lt-textarea:focus-visible {
+    outline: var(--lt-focus-ring);
+    outline-offset: 2px;
+    border-color: var(--lt-color-accent-border);
+  }
+
+  .lt-textarea:disabled,
+  .lt-textarea[aria-disabled="true"] {
+    background: var(--lt-color-disabled-surface);
+    color: var(--lt-color-disabled-text);
+    border-color: var(--lt-color-disabled-surface);
+    /* No pointer-events: none here. The browser already blocks a disabled
+       field, and pointer-events would only stop the cursor from showing. The
+       element is then not hit by the mouse at all. */
+    cursor: not-allowed;
+  }
+
+  /* aria-disabled is only information for screen readers; the element still
+     works. Here pointer-events stops the mouse, at the cost of the cursor.
+     If the field should really be off, use `disabled` or `readonly`. */
+  .lt-textarea[aria-disabled="true"] {
+    pointer-events: none;
+  }
+
+  .lt-textarea[data-state="invalid"] {
+    border-color: var(--lt-color-danger-text);
+    background: var(--lt-color-danger-surface);
+  }
+
+  .lt-textarea[data-state="invalid"]:focus-visible {
+    outline-color: var(--lt-color-danger-text);
+  }
+
+  .lt-textarea[data-state="success"] {
+    border-color: var(--lt-color-success-text);
+    background: var(--lt-color-success-surface);
+  }
+
+  .lt-textarea[data-state="success"]:focus-visible {
+    outline-color: var(--lt-color-success-text);
+  }
+
+  /* Disabled wins over a state. `[data-state]` used to come after
+     `:disabled` with the same specificity, and an invalid field in a form
+     that was disabled during submission looked red, not disabled. */
+  .lt-textarea:is(:disabled, [aria-disabled="true"])[data-state] {
+    background: var(--lt-color-disabled-surface);
+    color: var(--lt-color-disabled-text);
+    border-color: var(--lt-color-disabled-surface);
+  }
+}

package/src/components/css/textarea/textarea.ts

@@ -0,0 +1,40 @@
+import {
+  attributes,
+  type FieldState,
+  fieldStates,
+  isFieldState,
+  type NonDefaultFieldState,
+} from "../shared.js"
+
+export const TEXTAREA_CLASS = "lt-textarea" as const
+
+export type TextareaOptions = {
+  /** Validation state. Default: `default`. */
+  state?: FieldState
+}
+
+export type TextareaAttributes = {
+  class: typeof TEXTAREA_CLASS
+  "data-state"?: NonDefaultFieldState
+  "aria-invalid"?: "true"
+}
+
+/**
+ * The attributes for a multi-line text field.
+ *
+ * ```ts
+ * <textarea {...textarea({ state: "invalid" })} />
+ * ```
+ */
+export const textarea = Object.assign(
+  ({ state = "default" }: TextareaOptions = {}): TextareaAttributes =>
+    attributes({
+      class: TEXTAREA_CLASS,
+      "data-state": state === "default" ? undefined : state,
+      "aria-invalid": state === "invalid" ? ("true" as const) : undefined,
+    }),
+  {
+    states: fieldStates,
+    isState: isFieldState,
+  },
+)

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

@@ -0,0 +1,92 @@
+@layer lotek {
+  .lt-toggle-group {
+    box-sizing: border-box;
+    display: inline-flex;
+    flex-wrap: wrap;
+    gap: 0;
+    margin: 0;
+    padding: 0;
+    border: 1px solid var(--lt-color-neutral-border);
+    border-radius: var(--lt-toggle-group-radius, var(--lt-spacing-1));
+    overflow: hidden;
+    min-inline-size: 0;
+  }
+
+  .lt-toggle-group__option {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    /* 40 pixels high, like the buttons, so a row of them lines up. */
+    min-block-size: var(--lt-toggle-group-height, var(--lt-spacing-10));
+    padding: var(--lt-toggle-group-padding, 0 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-accent-text);
+    background: var(--lt-color-neutral-canvas);
+    cursor: pointer;
+  }
+
+  .lt-toggle-group__option + .lt-toggle-group__option {
+    border-inline-start: 1px solid var(--lt-color-neutral-border);
+  }
+
+  /* The radio button sits inside the label and is shrunk away visually. It
+     stays in the keyboard order, so the arrow keys and the screen reader
+     work as in a plain radio group. */
+  .lt-toggle-group__option input {
+    position: absolute;
+    inline-size: 1px;
+    block-size: 1px;
+    margin: -1px;
+    padding: 0;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+    border-width: 0;
+  }
+
+  .lt-toggle-group__option:hover {
+    background: var(--lt-color-accent-surface);
+  }
+
+  .lt-toggle-group__option:has(input:focus-visible) {
+    outline: var(--lt-focus-ring);
+    outline-offset: -2px;
+  }
+
+  .lt-toggle-group__option:has(input:checked) {
+    color: var(--lt-color-accent-content);
+    background: var(--lt-color-accent-fill);
+    font-weight: var(--lt-font-weight-semibold);
+  }
+
+  /* The ring is inside, on top of the selected surface, and
+     `accent-border-strong` against `accent-fill` was 1.23:1. The selected
+     option is always the one that gets focus in a radio group, so nobody
+     could see where focus was. `content` against `fill` is a promise in the
+     colour contract. The ring cannot be moved outside: the group has
+     `overflow: hidden`, and it was clipped away. */
+  .lt-toggle-group__option:has(input:checked:focus-visible) {
+    outline-color: var(--lt-color-accent-content);
+  }
+
+  .lt-toggle-group__option:has(input:disabled) {
+    color: var(--lt-color-disabled-text);
+    background: var(--lt-color-disabled-surface);
+    cursor: not-allowed;
+  }
+
+  /*
+   * High contrast: the selected option differs only by background colour,
+   * and custom colours are overridden in the mode. System colours get
+   * through, and `Highlight` with `HighlightText` is exactly the pair the
+   * operating system uses to show that something is selected.
+   */
+  @media (forced-colors: active) {
+    .lt-toggle-group__option:has(input:checked) {
+      background-color: Highlight;
+      color: HighlightText;
+    }
+  }
+}

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

@@ -0,0 +1,37 @@
+import { attributes } from "../shared.js"
+
+export const TOGGLE_GROUP_CLASS = "lt-toggle-group" as const
+/** The label around each option. */
+export const TOGGLE_GROUP_OPTION_CLASS = "lt-toggle-group__option" as const
+
+export type ToggleGroupAttributes = {
+  class: typeof TOGGLE_GROUP_CLASS
+}
+
+/**
+ * The attributes for a group where one option is selected at a time.
+ *
+ * The group is radio buttons in disguise. Each option is a `<label>` with an
+ * `<input type="radio">` inside, visually shrunk away. You then keep the
+ * arrow keys, `FormData` and the screen reader saying "2 of 3" without
+ * writing any of it again.
+ *
+ * If the choices are actions rather than a setting, such as "bold, italic,
+ * underline", buttons with `aria-pressed` belong there instead.
+ *
+ * ```ts
+ * <fieldset {...toggleGroup()}>
+ *   <legend class="lt-sr-only">View</legend>
+ *   <label class={toggleGroup.option}>
+ *     <input type="radio" name="view" value="list" checked /> List
+ *   </label>
+ * </fieldset>
+ * ```
+ */
+export const toggleGroup = Object.assign(
+  (): ToggleGroupAttributes => attributes({ class: TOGGLE_GROUP_CLASS }),
+  {
+    /** The class on the label around each option. */
+    option: TOGGLE_GROUP_OPTION_CLASS,
+  },
+)

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

@@ -0,0 +1,89 @@
+@layer lotek {
+  .lt-tooltip {
+    position: relative;
+    display: inline-flex;
+  }
+
+  .lt-tooltip__bubble {
+    /* The width in `--lt-tooltip-width` is the whole bubble, also on a page
+       without a CSS reset that sets border-box. */
+    box-sizing: border-box;
+    position: absolute;
+    inset-block-end: calc(100% + var(--lt-spacing-2));
+    inset-inline-start: 50%;
+    transform: translateX(-50%);
+    z-index: 40;
+    inline-size: max-content;
+    max-inline-size: var(--lt-tooltip-width, 16rem);
+    padding: var(--lt-tooltip-padding, var(--lt-spacing-1) var(--lt-spacing-2));
+    font-size: var(--lt-font-size-s);
+    line-height: var(--lt-line-height-compact);
+    color: var(--lt-color-neutral-canvas);
+    background: var(--lt-color-neutral-text-strong);
+    border-radius: var(--lt-tooltip-radius, var(--lt-spacing-1));
+    /* The bubble is hidden until the trigger gets focus or the mouse.
+       `display: none` and not just `visibility`: a hidden bubble still took
+       up room, and at the right edge it caused sideways scrolling on a
+       narrow screen. `aria-describedby` reads the text it points to also
+       while the bubble is hidden. */
+    display: none;
+    opacity: 0;
+    /* While it fades out, the bubble briefly has `display` on. Without this
+       it and the bridge took clicks meant for what was underneath. */
+    pointer-events: none;
+  }
+
+  /* `inset-inline-start` flips with the direction, `translateX` does not.
+     Without this the bubble sat a whole bubble width to the left of the
+     button. */
+  .lt-tooltip__bubble:dir(rtl) {
+    transform: translateX(50%);
+  }
+
+  .lt-tooltip:hover .lt-tooltip__bubble,
+  .lt-tooltip:focus-within .lt-tooltip__bubble {
+    display: block;
+    opacity: 1;
+    pointer-events: auto;
+  }
+
+  /* An invisible bridge over the gap between the button and the bubble, as
+     wide as the button. Without it `:hover` let go on the way up, and the
+     bubble disappeared before the mouse reached it. It is only there while
+     the bubble shows, and no wider than the button, so it does not take
+     clicks from the content next to it. */
+  .lt-tooltip:is(:hover, :focus-within)::before {
+    content: "";
+    position: absolute;
+    inset-inline: 0;
+    inset-block-end: 100%;
+    block-size: var(--lt-spacing-2);
+  }
+
+  /* The fade-in starts from invisible also when the bubble comes from
+     `display: none`. Without support for this it just appears without
+     fading. */
+  @starting-style {
+    .lt-tooltip:hover .lt-tooltip__bubble,
+    .lt-tooltip:focus-within .lt-tooltip__bubble {
+      opacity: 0;
+    }
+  }
+
+  @media (prefers-reduced-motion: no-preference) {
+    .lt-tooltip__bubble {
+      transition:
+        opacity 120ms ease,
+        display 120ms allow-discrete;
+    }
+  }
+
+  /* High contrast: the bubble has no border, and the surfaces are forced to
+     the same colour as the page. Without an edge the text floats right on
+     top of the content below. */
+  @media (forced-colors: active) {
+    .lt-tooltip__bubble {
+      border: 1px solid CanvasText;
+    }
+  }
+}

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

@@ -0,0 +1,37 @@
+import { attributes } from "../shared.js"
+
+export const TOOLTIP_CLASS = "lt-tooltip" as const
+/** The bubble with the text. */
+export const TOOLTIP_BUBBLE_CLASS = "lt-tooltip__bubble" as const
+
+export type TooltipAttributes = {
+  class: typeof TOOLTIP_CLASS
+}
+
+/**
+ * The attributes for the wrapper around a trigger and a tooltip bubble.
+ *
+ * The bubble shows on hover and on focus. The focus part is not optional: a
+ * bubble that only comes with the mouse does not exist for keyboard users.
+ *
+ * The text in the bubble must be connected to the trigger with
+ * `aria-describedby`. Without it the bubble is just something that appears
+ * on screen, and is never announced.
+ *
+ * Use it for something extra, never for something the user must have. On a
+ * touch screen there is neither hover nor focus before something is tapped.
+ *
+ * ```ts
+ * <span {...tooltip()}>
+ *   <button aria-describedby="hint">Archive</button>
+ *   <span class={tooltip.bubble} role="tooltip" id="hint">Moves it to the archive</span>
+ * </span>
+ * ```
+ */
+export const tooltip = Object.assign(
+  (): TooltipAttributes => attributes({ class: TOOLTIP_CLASS }),
+  {
+    /** The class on the bubble with the text. */
+    bubble: TOOLTIP_BUBBLE_CLASS,
+  },
+)

package/src/components/default-texts.ts

@@ -0,0 +1,34 @@
+/**
+ * Every text the package itself writes into the page when nobody has given
+ * it another one.
+ *
+ * LO-TEK has almost no text: the renderer writes the text, in its own
+ * language. What is left here are the defaults for text a component creates
+ * itself, and each of them can be replaced. How is noted next to each one,
+ * and the same is in the table on the documentation page about translation.
+ *
+ * The texts live here and not in the components, so there is one place to
+ * read them. `scripts/check-texts.ts` fails the build on a user-facing text
+ * that is in a component and not here, and requires each of them to be in
+ * the table on the translation page.
+ *
+ * The texts in CSS, such as " (required)", cannot import anything. They are
+ * read from an `--lt-` variable with the text as the fallback, and
+ * `check-texts.ts` requires that.
+ */
+export const DEFAULT_TEXTS = {
+  /** `aria-label` on the `<lt-toast>` region. Replaced with `label`. */
+  toastRegion: "Notifications",
+  /** The close button in each message. Replaced with `close-label`. */
+  toastClose: "Close message",
+  /** `<lt-connection-status>` when the connection is lost. Replaced with `offline-text`. */
+  connectionOffline: "No connection. What you type is not being saved.",
+  /** `<lt-connection-status>` when it comes back. Replaced with `online-text`. */
+  connectionOnline: "Connection restored.",
+  /** The match count in `<lt-suggestion>` with no matches. Replaced with `count-none`. */
+  suggestionNone: "No matches",
+  /** The match count with one match. Replaced with `count-one`. */
+  suggestionOne: "One match",
+  /** The match count otherwise. `{n}` is the number. Replaced with `count-other`. */
+  suggestionOther: "{n} matches",
+} as const

package/src/components/events.ts

@@ -0,0 +1,68 @@
+// Generated by interfaces/scripts/generate-vocabulary.ts from metadata.ts. Do not edit.
+
+import type { LtDialog } from "./frame/dialog/lt-dialog.js"
+import type { LtErrorSummary } from "./frame/error-summary/lt-error-summary.js"
+import type { LtField } from "./frame/field/lt-field.js"
+import type { LtPopover } from "./frame/popover/lt-popover.js"
+import type { LtSessionTimeout } from "./frame/session-timeout/lt-session-timeout.js"
+import type { LtSuggestion } from "./frame/suggestion/lt-suggestion.js"
+import type { LtTabs } from "./frame/tabs/lt-tabs.js"
+import type { LtConnectionStatus } from "./standalone/connection-status/lt-connection-status.js"
+import type { LtToast } from "./standalone/toast/lt-toast.js"
+
+/**
+ * The events the web components dispatch, with `detail` as the component
+ * sends it. All of them bubble, and come out of a shadow root.
+ * `HTMLElementEventMap` and `DocumentEventMap` are extended with them, so
+ * `addEventListener("dialog-toggle", …)` gives `event.detail.open` as
+ * `boolean` on any element and on `document`.
+ *
+ * `HTMLElementTagNameMap` is extended with the elements, so
+ * `querySelector("lt-dialog")` gives `LtDialog | null`. The map is here,
+ * and not in each component, because every entry to the web components
+ * brings this file along: from `/register` alone,
+ * `querySelector("lt-dialog")` was otherwise an `Element`, and the listener
+ * on it got `Event` without `detail`.
+ */
+export interface LtEventMap {
+  /** `<lt-tabs>`: The user selected a tab. `index` counts from 0. */
+  "tab-select": CustomEvent<{ index: number }>
+  /** `<lt-popover>`: The user opened or closed the panel, or `show()`, `hide()` or `toggle()` was called. Setting `open` as a property or attribute dispatches no event. */
+  "popover-toggle": CustomEvent<{ open: boolean }>
+  /** `<lt-suggestion>`: The user chose a suggestion. `label` is the text, `value` the code from `data-value`, or the text when the option has none. The field also gets `input` and `change`, as if the user had typed it. */
+  "suggestion-select": CustomEvent<{ value: string; label: string }>
+  /** `<lt-dialog>`: The dialog opened or closed. `returnValue` is the value of the button that closed it, or an empty string. */
+  "dialog-toggle": CustomEvent<{ open: boolean; returnValue: string }>
+  /** `<lt-toast>`: A message was closed, by the user, because its time ran out, or with `dismiss()`. `clear()` dispatches none. */
+  "toast-dismiss": CustomEvent<null>
+  /** `<lt-session-timeout>`: The warning opened. */
+  "session-warn": CustomEvent<null>
+  /** `<lt-session-timeout>`: The session continues: the user closed the warning with a button other than log out or with Escape, or the app called `extend()`. */
+  "session-extend": CustomEvent<null>
+  /** `<lt-session-timeout>`: The user chose to log out. */
+  "session-logout": CustomEvent<null>
+  /** `<lt-session-timeout>`: Time is up. */
+  "session-expired": CustomEvent<null>
+  /** `<lt-session-timeout>`: The user is active. Dispatched at most once per `activity-interval`, so the app can keep the server session alive. */
+  "session-activity": CustomEvent<null>
+  /** `<lt-connection-status>`: The connection is lost. */
+  "connection-lost": CustomEvent<null>
+  /** `<lt-connection-status>`: The connection is back. */
+  "connection-restored": CustomEvent<null>
+}
+
+declare global {
+  interface HTMLElementEventMap extends LtEventMap {}
+  interface DocumentEventMap extends LtEventMap {}
+  interface HTMLElementTagNameMap {
+    "lt-connection-status": LtConnectionStatus
+    "lt-dialog": LtDialog
+    "lt-error-summary": LtErrorSummary
+    "lt-field": LtField
+    "lt-popover": LtPopover
+    "lt-session-timeout": LtSessionTimeout
+    "lt-suggestion": LtSuggestion
+    "lt-tabs": LtTabs
+    "lt-toast": LtToast
+  }
+}