@lo-tek/interfaces 0.0.0 → 0.37.0

package/src/components/css/search/search.ts

@@ -0,0 +1,56 @@
+import { INPUT_CLASS, input } from "../input/input.js"
+import {
+  attributes,
+  type FieldState,
+  fieldStates,
+  isFieldState,
+} from "../shared.js"
+
+export const SEARCH_CLASS = "lt-search" as const
+/** The row with the search field and the button next to it. */
+export const SEARCH_ROW_CLASS = "lt-search-row" as const
+
+export type SearchOptions = {
+  /** Validation state. Default: `default`. */
+  state?: FieldState
+}
+
+export type SearchAttributes = {
+  class: `${typeof INPUT_CLASS} ${typeof SEARCH_CLASS}`
+  type: "search"
+  "data-state"?: "invalid" | "success"
+  "aria-invalid"?: "true"
+}
+
+/**
+ * The attributes for a search field.
+ *
+ * The field is an `lt-input` with room for the magnifying glass, so both
+ * classes are set. `type="search"` gives the browser's own cross for
+ * clearing the field, and on mobile a keyboard with "Search" instead of
+ * "Enter".
+ *
+ * ```ts
+ * <input {...search()} name="q" />
+ * ```
+ */
+export const search = Object.assign(
+  ({ state = "default" }: SearchOptions = {}): SearchAttributes => {
+    const base = input({ type: "search", state })
+    return attributes(
+      {
+        ...base,
+        class: `${INPUT_CLASS} ${SEARCH_CLASS}` as const,
+        type: "search" as const,
+        "data-variant": undefined,
+      },
+      base,
+    ) as SearchAttributes
+  },
+  {
+    /** The class on the row with the field and the button. */
+    row: SEARCH_ROW_CLASS,
+    states: fieldStates,
+    isState: isFieldState,
+  },
+)

package/src/components/css/select/select.css

@@ -0,0 +1,321 @@
+@layer lotek {
+  .lt-select {
+    /* 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: var(--lt-select-width, 100%);
+    padding: var(--lt-select-padding, var(--lt-spacing-2) var(--lt-spacing-3));
+    /* The end side is the room for the arrow, and it is fixed: the arrow is
+       drawn a fixed distance from the edge, so less room would put the text
+       on top of it. So `--lt-select-padding` applies to everything except
+       this side here. With `data-picker="styled"` the arrow takes real
+       room, and there the variable applies to all four sides. */
+    padding-inline-end: calc(var(--lt-spacing-4) + var(--lt-spacing-2));
+    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-color: var(--lt-color-neutral-canvas);
+    border: 1px solid var(--lt-color-neutral-border);
+    border-radius: var(--lt-select-radius, var(--lt-spacing-1));
+    appearance: none;
+    background-image:
+      linear-gradient(
+        45deg,
+        transparent 50%,
+        var(--lt-color-neutral-text-subtle) 50%
+      ),
+      linear-gradient(
+        135deg,
+        var(--lt-color-neutral-text-subtle) 50%,
+        transparent 50%
+      );
+    background-position:
+      calc(100% - 1rem) calc(50% - 0.1rem),
+      calc(100% - 0.75rem) calc(50% - 0.1rem);
+    background-size:
+      0.35rem 0.35rem,
+      0.35rem 0.35rem;
+    background-repeat: no-repeat;
+  }
+
+  /* The arrow is two gradients, and `background-position` has no logical
+     variant. The mirrored version is the same two pieces, moved to the left
+     edge and swapped: the one that was outermost is now innermost. From the
+     left the position is given to the piece's left edge, from the right with
+     `calc(100% - ...)` to the same point on the other side, so the distances
+     are the same numbers. With 0.35rem subtracted the arrow sat 6 pixels
+     from the edge instead of 12. */
+  .lt-select:dir(rtl) {
+    background-position:
+      0.75rem calc(50% - 0.1rem),
+      1rem calc(50% - 0.1rem);
+  }
+
+  .lt-select:hover {
+    border-color: var(--lt-color-neutral-border-strong);
+  }
+
+  .lt-select:focus-visible {
+    outline: var(--lt-focus-ring);
+    outline-offset: 2px;
+    border-color: var(--lt-color-accent-border);
+  }
+
+  .lt-select:disabled,
+  .lt-select[aria-disabled="true"] {
+    background-color: 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-select[aria-disabled="true"] {
+    pointer-events: none;
+  }
+
+  .lt-select[data-state="invalid"] {
+    border-color: var(--lt-color-danger-text);
+    background-color: var(--lt-color-danger-surface);
+  }
+
+  .lt-select[data-state="invalid"]:focus-visible {
+    outline-color: var(--lt-color-danger-text);
+  }
+
+  .lt-select[data-state="success"] {
+    border-color: var(--lt-color-success-text);
+    background-color: var(--lt-color-success-surface);
+  }
+
+  .lt-select[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-select:is(:disabled, [aria-disabled="true"])[data-state] {
+    background-color: var(--lt-color-disabled-surface);
+    color: var(--lt-color-disabled-text);
+    border-color: var(--lt-color-disabled-surface);
+  }
+
+  /*
+   * The dropdown list is a window from the operating system, and no CSS
+   * reaches into it. `appearance: base-select` asks the browser to draw it
+   * inside the page instead: `::picker(select)` becomes a normal element,
+   * and each `<option>` can get the design system's colours and spacing.
+   *
+   * It is optional, and turned on with `data-picker="styled"`. Firefox 150
+   * does not have it, and there the field keeps the browser's own list. It
+   * is the same component with two looks, not something that breaks.
+   */
+  @supports (appearance: base-select) {
+    .lt-select[data-picker="styled"],
+    .lt-select[data-picker="styled"]::picker(select) {
+      appearance: base-select;
+    }
+
+    /* The button now draws its own arrow with `::picker-icon`, so the
+       gradients must go. The arrow takes real room in the layout, and the
+       room we kept for the drawn arrow would then be there twice. */
+    .lt-select[data-picker="styled"] {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: var(--lt-spacing-2);
+      background-image: none;
+      padding: var(
+        --lt-select-padding,
+        var(--lt-spacing-2) var(--lt-spacing-3)
+      );
+    }
+
+    /* The text in the button is the current choice. Long choices should be
+       clipped, not push the arrow out of the field. Without
+       `min-inline-size: 0` it does not shrink, because flex gives it the
+       minimum width of its content.
+
+       The browser does not create <selectedcontent> by itself. It only
+       exists when the author writes
+       `<button><selectedcontent></selectedcontent></button>` first in the
+       select. Without it the choice is drawn in the browser's own shadow
+       DOM, which no rule reaches, and a long choice wraps over several
+       lines. `white-space: nowrap` on the select does not help: the text
+       does not shrink there, and the arrow is pushed out of the field. */
+    /* biome-ignore lint/correctness/noUnknownTypeSelector: <selectedcontent> is
+       the element that shows the selected option in a customisable
+       dropdown list. Biome does not know it yet. */
+    .lt-select[data-picker="styled"] selectedcontent {
+      min-inline-size: 0;
+      overflow: hidden;
+      white-space: nowrap;
+      text-overflow: ellipsis;
+    }
+
+    .lt-select[data-picker="styled"]::picker-icon {
+      color: var(--lt-color-neutral-text-subtle);
+      transition: rotate 120ms ease;
+    }
+
+    .lt-select[data-picker="styled"]:open::picker-icon {
+      rotate: 180deg;
+    }
+
+    .lt-select[data-picker="styled"]::picker(select) {
+      box-sizing: border-box;
+      min-inline-size: anchor-size(self-inline);
+      /* The list should fill the room that is actually left down to the
+         edge of the window, not stretch beyond it. `stretch` is exactly
+         that room, and the margin is subtracted. */
+      max-block-size: stretch;
+      margin-block: var(--lt-select-viewport-margin, var(--lt-spacing-2));
+      padding: 0;
+      overflow-y: auto;
+      background: var(--lt-color-neutral-canvas);
+      border: 1px solid var(--lt-color-neutral-border);
+      border-radius: var(--lt-select-radius, var(--lt-spacing-1));
+      box-shadow: var(--lt-shadow-overlay);
+      /* If there is no room below the field, the list goes above it. */
+      position-try-fallbacks: flip-block;
+      opacity: 0;
+      transition:
+        opacity 120ms ease,
+        overlay 120ms allow-discrete,
+        display 120ms allow-discrete;
+    }
+
+    .lt-select[data-picker="styled"]:open::picker(select) {
+      opacity: 1;
+    }
+
+    @starting-style {
+      .lt-select[data-picker="styled"]:open::picker(select) {
+        opacity: 0;
+      }
+    }
+
+    /* The height can only be animated where `calc-size` exists, since `auto`
+       is otherwise not a value that can be transitioned to. Without support
+       the height stays `auto`, and only the opacity fades. */
+    @supports (block-size: calc-size(auto, size)) {
+      .lt-select[data-picker="styled"]::picker(select) {
+        block-size: 0;
+        transition:
+          opacity 120ms ease,
+          block-size 120ms ease,
+          overlay 120ms allow-discrete,
+          display 120ms allow-discrete;
+      }
+
+      .lt-select[data-picker="styled"]:open::picker(select) {
+        block-size: calc-size(auto, size);
+      }
+
+      @starting-style {
+        .lt-select[data-picker="styled"]:open::picker(select) {
+          block-size: 0;
+        }
+      }
+    }
+
+    /* The group heading is not an element we can target when it comes from
+       `label=`, only from `<legend>`. So it is set on the group, and
+       inherited down: the size and colour set it apart from the options,
+       and `text-indent` gives it the same left edge as the text in an
+       option. The options set those three back to their own values. */
+    .lt-select[data-picker="styled"] optgroup {
+      padding-block: var(--lt-spacing-2) var(--lt-spacing-1);
+      font-size: var(--lt-font-size-s);
+      color: var(--lt-color-neutral-text-subtle);
+      text-indent: var(--lt-spacing-3);
+    }
+
+    .lt-select[data-picker="styled"] option {
+      text-indent: 0;
+      display: flex;
+      align-items: center;
+      gap: var(--lt-spacing-2);
+      padding: var(
+        --lt-select-option-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);
+      cursor: pointer;
+    }
+
+    /* The tick comes after the text, not before it, so all the options get
+       the text in the same place. */
+    .lt-select[data-picker="styled"] option::checkmark {
+      order: 1;
+      margin-inline-start: auto;
+    }
+
+    .lt-select[data-picker="styled"] option:hover {
+      background: var(--lt-color-accent-surface);
+    }
+
+    .lt-select[data-picker="styled"] option:checked {
+      background: var(--lt-color-accent-fill);
+      color: var(--lt-color-accent-content);
+    }
+
+    /* Focus is shown with a border, not with a surface. The arrow keys move
+       focus between the options, and the selected one already has its own
+       surface. A different background colour would therefore disappear
+       exactly where the user is. */
+    .lt-select[data-picker="styled"] option:focus {
+      outline: var(--lt-focus-ring);
+      outline-offset: -2px;
+    }
+
+    .lt-select[data-picker="styled"] option:checked:focus {
+      outline-color: var(--lt-color-accent-content);
+    }
+
+    .lt-select[data-picker="styled"] option:disabled {
+      color: var(--lt-color-disabled-text);
+      background: var(--lt-color-disabled-surface);
+      cursor: not-allowed;
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+      .lt-select[data-picker="styled"]::picker(select),
+      .lt-select[data-picker="styled"]::picker-icon {
+        transition: none;
+      }
+    }
+  }
+
+  /* High contrast: the arrow is two gradients, and they are removed in the
+     mode. The browser's own arrow is then better than none. The list drawn
+     in the page falls back for the same reason: the browser's own list uses
+     the system colours, and they are the only ones guaranteed to be
+     readable in the mode. */
+  @media (forced-colors: active) {
+    .lt-select,
+    .lt-select[data-picker="styled"] {
+      display: block;
+      appearance: auto;
+      background-image: none;
+      padding: var(
+        --lt-select-padding,
+        var(--lt-spacing-2) var(--lt-spacing-3)
+      );
+    }
+  }
+}

package/src/components/css/select/select.ts

@@ -0,0 +1,63 @@
+import {
+  attributes,
+  createGuard,
+  type FieldState,
+  fieldStates,
+  isFieldState,
+  type NonDefaultFieldState,
+} from "../shared.js"
+
+export const SELECT_CLASS = "lt-select" as const
+
+/**
+ * Who draws the dropdown list.
+ *
+ * `auto` is the browser's own list, a window from the operating system that
+ * cannot be styled. `styled` asks the browser to draw it inside the page
+ * instead, so it gets the design system's colours, spacing and shadow.
+ */
+export const selectPickers = ["auto", "styled"] as const
+export type SelectPicker = (typeof selectPickers)[number]
+export type NonDefaultSelectPicker = Exclude<SelectPicker, "auto">
+export const isSelectPicker = createGuard(selectPickers)
+
+export type SelectOptions = {
+  /** Validation state. Default: `default`. */
+  state?: FieldState
+  /** Who draws the dropdown list. Default: `auto`. */
+  picker?: SelectPicker
+}
+
+export type SelectAttributes = {
+  class: typeof SELECT_CLASS
+  "data-state"?: NonDefaultFieldState
+  "data-picker"?: NonDefaultSelectPicker
+  "aria-invalid"?: "true"
+}
+
+/**
+ * The attributes for a dropdown list.
+ *
+ * ```ts
+ * <select {...select({ state: "invalid" })} />
+ * <select {...select({ picker: "styled" })} />
+ * ```
+ */
+export const select = Object.assign(
+  ({
+    state = "default",
+    picker = "auto",
+  }: SelectOptions = {}): SelectAttributes =>
+    attributes({
+      class: SELECT_CLASS,
+      "data-state": state === "default" ? undefined : state,
+      "data-picker": picker === "auto" ? undefined : picker,
+      "aria-invalid": state === "invalid" ? ("true" as const) : undefined,
+    }),
+  {
+    states: fieldStates,
+    isState: isFieldState,
+    pickers: selectPickers,
+    isPicker: isSelectPicker,
+  },
+)

package/src/components/css/shared.ts

@@ -0,0 +1,199 @@
+/**
+ * Shared building blocks for the component API.
+ *
+ * Each component exports one function that takes an object of options and
+ * returns the attributes you spread onto the element. The shape is the same
+ * for all of them, so you only need to learn it once.
+ */
+
+/**
+ * The attributes each set manages, including those that are off right now.
+ *
+ * `attributes()` drops the keys without a value, and with them the record of
+ * which attributes the builder function has a say in. `setAttributes` needs
+ * exactly that: `lt.switch()` manages `disabled` and must be able to remove
+ * it, while `lt.button()` has never written it and must leave it alone. The
+ * list is kept in a map beside the object, not on it, so spreading, JSON and
+ * React see the same as before.
+ */
+const managed = new WeakMap<object, readonly string[]>()
+
+/** The names the set manages, or `undefined` for a set we did not create. */
+export function managedNames(set: object): readonly string[] | undefined {
+  return managed.get(set)
+}
+
+/**
+ * Gives a set rewritten from another the same managed names.
+ *
+ * `/react` renames `class` to `className` in a new object, and the new object
+ * was not in the map. `lt.setAttributes` from there then only cleaned up
+ * `data-*`, and `aria-invalid` stayed after the field was corrected. The
+ * names are given as they are spelled in the new set.
+ *
+ * For `/react` and other entry points that rewrite the sets, not for apps: a
+ * set from `lt.*` is already managed.
+ */
+export function rememberManaged(set: object, names: readonly string[]): void {
+  managed.set(set, names)
+}
+
+/**
+ * Removes attributes without a value, so `{...spread}` does not set empty
+ * fields.
+ *
+ * When the set builds on another, as `lt.search()` does on `lt.input()`, the
+ * other is passed in as `based`. The spread has already lost the keys that
+ * were off, and without this the search field only managed `data-state` when
+ * it happened to be set: it could be set, but not removed.
+ */
+export function attributes<T extends Record<string, unknown>>(
+  values: T,
+  ...based: object[]
+): T {
+  const result = {} as T
+  for (const [name, value] of Object.entries(values)) {
+    if (value !== undefined) {
+      ;(result as Record<string, unknown>)[name] = value
+    }
+  }
+  const names = new Set(Object.keys(values))
+  for (const set of based) {
+    for (const name of managed.get(set) ?? []) names.add(name)
+  }
+  managed.set(result, [...names])
+  return result
+}
+
+/** Creates a type guard for a list of allowed strings. */
+export function createGuard<T extends string>(allowed: readonly T[]) {
+  return (value: string): value is T =>
+    (allowed as readonly string[]).includes(value)
+}
+
+/**
+ * Validation state for form controls.
+ *
+ * Input, textarea and select each had an identical type of their own. Now
+ * there is one, so a value can pass between them without conversion.
+ */
+export const fieldStates = ["default", "invalid", "success"] as const
+export type FieldState = (typeof fieldStates)[number]
+export type NonDefaultFieldState = Exclude<FieldState, "default">
+export const isFieldState = createGuard(fieldStates)
+
+/** How a required field is marked in its label. */
+export const requiredMarkers = ["symbol", "text"] as const
+export type RequiredMarker = (typeof requiredMarkers)[number]
+export const isRequiredMarker = createGuard(requiredMarkers)
+
+/**
+ * Warns once per message, in the console.
+ *
+ * The builder functions are pure functions without an element to attach the
+ * message to, so they cannot use `warnAboutMarkup`. The deduplication is
+ * needed all the same: an app that renders a list of fields would otherwise
+ * say the same thing per field and per render.
+ */
+const said = new Set<string>()
+
+export function warnOnce(message: string): void {
+  if (typeof console === "undefined" || said.has(message)) return
+  said.add(message)
+  console.warn(message)
+}
+
+let idCounter = 0
+
+/**
+ * Creates an id that is unique within the document.
+ *
+ * Safe only when the markup is rendered once. When the same field is rendered
+ * both on a server and in the browser, the two runs give two different ids,
+ * and the wiring is broken until the framework has corrected it.
+ */
+export function createFieldId(): string {
+  idCounter += 1
+  return `lt-field-${idCounter}-${Math.random().toString(36).slice(2, 8)}`
+}
+
+/**
+ * The keys a builder function creates ids from, checked.
+ *
+ * A key is the same as `key` in React: a fixed value from the data, such as
+ * a record id. The id is the same on every render, and a server update
+ * recognises the element. An index is not a key: if the server inserts a row
+ * first, the same index points to something else.
+ *
+ * Throws, instead of warning and creating a fallback as `idOrFallback` does:
+ * an empty key, one with whitespace or two identical ones give ids that are
+ * empty, invalid or identical, and there is no fallback that is right.
+ * Whitespace is what JavaScript counts as whitespace (`\s`), which the
+ * Kotlin version spells out.
+ */
+export function checkedKeys(builder: string, keys: unknown): string[] {
+  if (!Array.isArray(keys)) {
+    throw new Error(
+      `${builder}: keys is missing. Pass a list with one key per element, taken from the data, such as a record id.`,
+    )
+  }
+  const seen = new Set<string>()
+  for (const key of keys) {
+    if (typeof key !== "string") {
+      throw new Error(
+        `${builder}: a key in keys is not a string but ${typeof key}. The keys become ids; turn numbers into strings, as in String(recordId).`,
+      )
+    }
+    if (key === "") {
+      throw new Error(
+        `${builder}: a key in keys is empty. The keys become ids, and each must be a fixed value from the data.`,
+      )
+    }
+    if (/\s/.test(key)) {
+      throw new Error(
+        `${builder}: the key "${key}" contains whitespace. The keys become ids, and an id cannot contain whitespace.`,
+      )
+    }
+    if (seen.has(key)) {
+      throw new Error(
+        `${builder}: the key "${key}" appears twice in keys. The keys become ids, and two equal ids point to the same element.`,
+      )
+    }
+    seen.add(key)
+  }
+  return keys
+}
+
+/**
+ * The id the builder function received, or a fallback with a warning.
+ *
+ * Every builder function that takes an id requires it in the type. That is
+ * not enough on its own: a consumer without TypeScript sees no type, and
+ * plain HTML with `<script type="module">` is a first-class way to use
+ * LO-TEK. Without the fallback the ids became strings like `undefined-list`,
+ * `aria-controls` pointed there, and the wiring was broken in a way that
+ * looked valid.
+ *
+ * The empty string counts as no id. `lt.field({ id: "" })` gave `for=""` and
+ * `help.id="-help"`, the same problem without anything saying so.
+ *
+ * The name of the builder function is in the message. Without it the
+ * suggestion field said "lt.field()" and sent the developer to the wrong
+ * place.
+ */
+export function idOrFallback(
+  builder: string,
+  id: string | undefined,
+  option = "id",
+): string {
+  if (typeof id === "string" && id.trim() !== "") return id
+
+  warnOnce(
+    `${builder}: no ${option} given, so a random one is created, and two runs ` +
+      "create two different ones. Rendered on a server and in the browser, the " +
+      "wiring points to something that does not exist, and a server that sends " +
+      "the region again with a new id makes the morph replace the elements and " +
+      `lose what the user did in them. Pass ${option}, in React from useId().`,
+  )
+  return createFieldId()
+}

package/src/components/css/skeleton/skeleton.css

@@ -0,0 +1,62 @@
+@layer lotek {
+  .lt-skeleton {
+    box-sizing: border-box;
+    display: block;
+    inline-size: 100%;
+    block-size: var(--lt-skeleton-height, var(--lt-spacing-4));
+    border-radius: var(--lt-skeleton-radius, var(--lt-spacing-1));
+    background: var(--lt-color-neutral-surface);
+    /* The shimmer is a gradient moving across the surface, not an opacity
+       that pulses. The contrast against the page surface then stays the
+       same all the way. */
+    background-image: linear-gradient(
+      90deg,
+      transparent 0%,
+      var(--lt-color-neutral-canvas) 50%,
+      transparent 100%
+    );
+    background-size: 200% 100%;
+    background-repeat: no-repeat;
+    animation: lt-skeleton-shimmer 1600ms ease-in-out infinite;
+  }
+
+  /* The text lines are low, so the default radius is smaller. The variable
+     applies here too. */
+  .lt-skeleton[data-variant="text"] {
+    block-size: var(--lt-font-size-m);
+    border-radius: var(--lt-skeleton-radius, var(--lt-spacing-0-5));
+  }
+
+  .lt-skeleton[data-variant="circle"] {
+    inline-size: var(--lt-skeleton-height, var(--lt-spacing-10));
+    block-size: var(--lt-skeleton-height, var(--lt-spacing-10));
+    border-radius: 50%;
+  }
+
+  @keyframes lt-skeleton-shimmer {
+    from {
+      background-position: 150% 0;
+    }
+    to {
+      background-position: -50% 0;
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .lt-skeleton {
+      animation: none;
+      background-image: none;
+    }
+  }
+
+  /* High contrast: the surface and the shimmer are backgrounds, and both are
+     forced to the page surface colour. Without a border the placeholder was
+     invisible. */
+  @media (forced-colors: active) {
+    .lt-skeleton {
+      border: 1px solid GrayText;
+      animation: none;
+      background-image: none;
+    }
+  }
+}