@lo-tek/interfaces 0.0.0 → 0.37.0

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

@@ -0,0 +1,43 @@
+import { attributes, createGuard } from "../shared.js"
+
+export const SKELETON_CLASS = "lt-skeleton" as const
+
+export const skeletonVariants = ["block", "text", "circle"] as const
+
+export type SkeletonVariant = (typeof skeletonVariants)[number]
+export type NonDefaultSkeletonVariant = Exclude<SkeletonVariant, "block">
+
+export type SkeletonOptions = {
+  /** Shape. Default: `block`. */
+  variant?: SkeletonVariant
+}
+
+export type SkeletonAttributes = {
+  class: typeof SKELETON_CLASS
+  "data-variant"?: NonDefaultSkeletonVariant
+  "aria-hidden": "true"
+}
+
+/**
+ * The attributes for a placeholder while the content loads.
+ *
+ * The shapes are always hidden from screen readers. They say nothing about
+ * what is coming, and a row of empty boxes being announced is worse than
+ * silence. Announce the wait in one place instead, with `role="status"`.
+ *
+ * ```ts
+ * <div {...skeleton({ variant: "text" })} />
+ * ```
+ */
+export const skeleton = Object.assign(
+  ({ variant = "block" }: SkeletonOptions = {}): SkeletonAttributes =>
+    attributes({
+      class: SKELETON_CLASS,
+      "data-variant": variant === "block" ? undefined : variant,
+      "aria-hidden": "true" as const,
+    }),
+  {
+    variants: skeletonVariants,
+    isVariant: createGuard(skeletonVariants),
+  },
+)

package/src/components/css/skip-link/skip-link.css

@@ -0,0 +1,41 @@
+@layer lotek {
+  /* The link sits off screen until it gets focus. It cannot be hidden with
+     display or visibility, because then the keyboard cannot reach it either,
+     and the whole point is lost. */
+  .lt-skip-link {
+    position: absolute;
+    inset-inline-start: var(--lt-spacing-2);
+    inset-block-start: var(--lt-spacing-2);
+    z-index: 100;
+    transform: translateY(calc(-100% - var(--lt-spacing-4)));
+    display: inline-block;
+    padding: var(
+      --lt-skip-link-padding,
+      var(--lt-spacing-2) 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-content);
+    background: var(--lt-color-accent-fill);
+    border-radius: var(--lt-skip-link-radius, var(--lt-spacing-1));
+    text-decoration: underline;
+  }
+
+  /* `:focus` and not `:focus-visible`. Focus set from code after a mouse
+     click does not count as "visible focus", and the link would then stay
+     hidden for someone a script sends there. After a key press it counts as
+     visible, but it is the mouse click that decides. */
+  .lt-skip-link:focus {
+    transform: translateY(0);
+    outline: var(--lt-focus-ring);
+    outline-color: var(--lt-color-neutral-text-strong);
+    outline-offset: 2px;
+  }
+
+  @media (prefers-reduced-motion: no-preference) {
+    .lt-skip-link {
+      transition: transform 120ms ease;
+    }
+  }
+}

package/src/components/css/skip-link/skip-link.ts

@@ -0,0 +1,22 @@
+import { attributes } from "../shared.js"
+
+export const SKIP_LINK_CLASS = "lt-skip-link" as const
+
+export type SkipLinkAttributes = {
+  class: typeof SKIP_LINK_CLASS
+}
+
+/**
+ * The attributes for a skip-to-content link.
+ *
+ * The link must be the first element in `<body>`, and point to the id of the
+ * main content. It sits off screen until it gets focus, and therefore cannot
+ * be hidden with `display: none`: the keyboard could not reach it either,
+ * and the whole point is lost.
+ *
+ * ```ts
+ * <a {...skipLink()} href="#main-content">Skip to main content</a>
+ * ```
+ */
+export const skipLink = (): SkipLinkAttributes =>
+  attributes({ class: SKIP_LINK_CLASS })

package/src/components/css/spinner/spinner.css

@@ -0,0 +1,48 @@
+@layer lotek {
+  .lt-spinner {
+    box-sizing: border-box;
+    display: inline-block;
+    inline-size: var(--lt-spinner-size, var(--lt-spacing-6));
+    block-size: var(--lt-spinner-size, var(--lt-spacing-6));
+    border: var(--lt-spinner-thickness, 2px) solid
+      var(--lt-color-neutral-surface);
+    border-block-start-color: var(--lt-color-accent-border);
+    border-radius: 50%;
+    animation: lt-spinner-rotate 800ms linear infinite;
+  }
+
+  .lt-spinner[data-size="small"] {
+    inline-size: var(--lt-spacing-4);
+    block-size: var(--lt-spacing-4);
+  }
+
+  .lt-spinner[data-size="large"] {
+    inline-size: var(--lt-spacing-10);
+    block-size: var(--lt-spacing-10);
+    border-width: 3px;
+  }
+
+  @keyframes lt-spinner-rotate {
+    to {
+      transform: rotate(360deg);
+    }
+  }
+
+  /* The user has asked for less motion. It then spins more slowly rather
+     than standing still: an indicator that does not move no longer says that
+     something is going on. */
+  @media (prefers-reduced-motion: reduce) {
+    .lt-spinner {
+      animation-duration: 2400ms;
+    }
+  }
+
+  /* High contrast: all four borders are forced to the same colour, and the
+     ring becomes an even circle. It still spins, but `Highlight` brings back
+     the mark that shows something is happening. */
+  @media (forced-colors: active) {
+    .lt-spinner {
+      border-block-start-color: Highlight;
+    }
+  }
+}

package/src/components/css/spinner/spinner.ts

@@ -0,0 +1,48 @@
+import { attributes, createGuard } from "../shared.js"
+
+export const SPINNER_CLASS = "lt-spinner" as const
+
+export const spinnerSizes = ["small", "medium", "large"] as const
+
+export type SpinnerSize = (typeof spinnerSizes)[number]
+export type NonDefaultSpinnerSize = Exclude<SpinnerSize, "medium">
+
+export type SpinnerOptions = {
+  /** Size. Default: `medium`. */
+  size?: SpinnerSize
+  /** What is loading. Becomes `aria-label`, so the ring has a name for screen readers. */
+  label?: string
+}
+
+export type SpinnerAttributes = {
+  class: typeof SPINNER_CLASS
+  "data-size"?: NonDefaultSpinnerSize
+  role?: "status"
+  "aria-label"?: string
+}
+
+/**
+ * The attributes for a loading indicator.
+ *
+ * Without `label` the ring is only a shape, and screen readers announce
+ * nothing. With `label` it becomes a `role="status"` that says what is going
+ * on. If you already have a visible text next to it, let that carry the
+ * message and drop `label`, so the same thing is not announced twice.
+ *
+ * ```ts
+ * <span {...spinner({ label: "Loading applications" })} />
+ * ```
+ */
+export const spinner = Object.assign(
+  ({ size = "medium", label }: SpinnerOptions = {}): SpinnerAttributes =>
+    attributes({
+      class: SPINNER_CLASS,
+      "data-size": size === "medium" ? undefined : size,
+      role: label ? ("status" as const) : undefined,
+      "aria-label": label,
+    }),
+  {
+    sizes: spinnerSizes,
+    isSize: createGuard(spinnerSizes),
+  },
+)

package/src/components/css/sr-only/sr-only.css

@@ -0,0 +1,16 @@
+@layer lotek {
+  /* Text that only screen readers should get. `display: none` and
+     `visibility: hidden` remove the element for them too, so the content must
+     stay in the document and be shrunk away visually instead. */
+  .lt-sr-only {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+    border-width: 0;
+  }
+}

package/src/components/css/sr-only/sr-only.ts

@@ -0,0 +1,21 @@
+import { attributes } from "../shared.js"
+
+export const SR_ONLY_CLASS = "lt-sr-only" as const
+
+export type SrOnlyAttributes = {
+  class: typeof SR_ONLY_CLASS
+}
+
+/**
+ * The attributes for text that only screen readers should get.
+ *
+ * ```ts
+ * <span {...srOnly()}>Opens in a new tab</span>
+ * ```
+ *
+ * Use it when a label or explanation is needed by someone listening to the
+ * page, but would be noise to someone looking at it. If the content should
+ * be gone for everyone, use `hidden` instead.
+ */
+export const srOnly = (): SrOnlyAttributes =>
+  attributes({ class: SR_ONLY_CLASS })

package/src/components/css/switch/switch.css

@@ -0,0 +1,105 @@
+@layer lotek {
+  .lt-switch {
+    box-sizing: border-box;
+    appearance: none;
+    flex: none;
+    display: inline-block;
+    inline-size: var(--lt-switch-width, var(--lt-spacing-10));
+    block-size: var(--lt-switch-height, var(--lt-spacing-6));
+    margin: 0;
+    border: 1px solid var(--lt-color-neutral-border);
+    border-radius: var(--lt-spacing-4);
+    background-color: var(--lt-color-neutral-surface);
+    /* The knob is a gradient, not a pseudo-element: Firefox does not render
+       ::before and ::after on an <input>. */
+    background-image: radial-gradient(
+      circle at center,
+      var(--lt-color-neutral-text-strong) 0 34%,
+      transparent 36%
+    );
+    background-repeat: no-repeat;
+    background-size: var(--lt-switch-height, var(--lt-spacing-6)) 100%;
+    /* background-position has no logical variant, so both directions are
+       written by hand. Off is at the start, on is at the end. */
+    background-position: left center;
+    cursor: pointer;
+    transition:
+      background-color 120ms ease,
+      background-position 120ms ease;
+  }
+
+  /* Without `:not(:disabled)`. It raised the specificity above the states
+     below, so the mouse removed the border of a switch that was on. The
+     rules for checked and disabled come after this one and win on order. */
+  .lt-switch:hover {
+    border-color: var(--lt-color-neutral-border-strong);
+  }
+
+  .lt-switch:focus-visible {
+    outline: var(--lt-focus-ring);
+    outline-offset: 2px;
+  }
+
+  .lt-switch:dir(rtl) {
+    background-position: right center;
+  }
+
+  .lt-switch:checked {
+    background-color: var(--lt-color-accent-fill);
+    border-color: var(--lt-color-accent-fill);
+    background-position: right center;
+    background-image: radial-gradient(
+      circle at center,
+      var(--lt-color-accent-content) 0 34%,
+      transparent 36%
+    );
+  }
+
+  .lt-switch:checked:dir(rtl) {
+    background-position: left center;
+  }
+
+  .lt-switch:disabled {
+    background-color: var(--lt-color-disabled-surface);
+    border-color: var(--lt-color-disabled-surface);
+    background-image: radial-gradient(
+      circle at center,
+      var(--lt-color-disabled-text) 0 34%,
+      transparent 36%
+    );
+    cursor: not-allowed;
+  }
+
+  /* The user has asked for less motion. The switch should still change
+     state, it just should not slide. */
+  @media (prefers-reduced-motion: reduce) {
+    .lt-switch {
+      transition: none;
+    }
+  }
+
+  .lt-switch-row {
+    display: flex;
+    align-items: center;
+    gap: var(--lt-spacing-2);
+    line-height: var(--lt-line-height-default);
+  }
+
+  /*
+   * High contrast: the knob is a gradient, and disappears in the mode.
+   * Without it on and off look exactly alike. Here we fall back to a plain
+   * checkbox. The switch loses its shape, but `role="switch"` is still
+   * there, so it is announced as on and off, and the state is visible
+   * again.
+   */
+  @media (forced-colors: active) {
+    .lt-switch,
+    .lt-switch:checked {
+      appearance: auto;
+      inline-size: auto;
+      block-size: auto;
+      background-image: none;
+      border: 0;
+    }
+  }
+}

package/src/components/css/switch/switch.ts

@@ -0,0 +1,50 @@
+import { attributes } from "../shared.js"
+
+export const SWITCH_CLASS = "lt-switch" as const
+/** The row that holds the switch and the text next to each other. */
+export const SWITCH_ROW_CLASS = "lt-switch-row" as const
+
+export type SwitchOptions = {
+  /**
+   * The control is disabled. Do not use it to lock the switch while a save
+   * is in progress: `disabled` takes focus away from it, and focus does not
+   * come back.
+   */
+  disabled?: boolean
+}
+
+export type SwitchAttributes = {
+  class: typeof SWITCH_CLASS
+  type: "checkbox"
+  role: "switch"
+  disabled?: true
+}
+
+/**
+ * The attributes for an on/off switch.
+ *
+ * The switch is a checkbox with `role="switch"`. Screen readers then
+ * announce it as "on" and "off" rather than "checked", while the keyboard
+ * and `FormData` work as for a plain checkbox.
+ *
+ * The switch has no validation state. A choice that is on or off cannot be
+ * invalid in itself; if turning it on is required, the requirement belongs
+ * in a checkbox with `required`.
+ *
+ * ```ts
+ * <input {...switchControl()} />
+ * ```
+ */
+export const switchControl = Object.assign(
+  ({ disabled }: SwitchOptions = {}): SwitchAttributes =>
+    attributes({
+      class: SWITCH_CLASS,
+      type: "checkbox" as const,
+      role: "switch" as const,
+      disabled: disabled ? (true as const) : undefined,
+    }),
+  {
+    /** The class on the row around the switch and the text. */
+    row: SWITCH_ROW_CLASS,
+  },
+)

package/src/components/css/table/table.css

@@ -0,0 +1,159 @@
+@layer lotek {
+  .lt-table {
+    box-sizing: border-box;
+    inline-size: 100%;
+    border-collapse: collapse;
+    font-family: inherit;
+    font-size: var(--lt-font-size-m);
+    line-height: var(--lt-line-height-default);
+    color: var(--lt-color-neutral-text-strong);
+    /* Numbers stacked under each other must have the same width per digit,
+       or the column cannot be read downwards. */
+    font-variant-numeric: tabular-nums;
+  }
+
+  .lt-table caption {
+    text-align: start;
+    font-weight: var(--lt-font-weight-semibold);
+    padding-block-end: var(--lt-spacing-2);
+  }
+
+  .lt-table th,
+  .lt-table td {
+    padding: var(
+      --lt-table-cell-padding,
+      var(--lt-spacing-2) var(--lt-spacing-3)
+    );
+    text-align: start;
+    vertical-align: top;
+    border-block-end: 1px solid var(--lt-color-neutral-border-subtle);
+  }
+
+  .lt-table thead th {
+    font-weight: var(--lt-font-weight-semibold);
+    border-block-end: 2px solid var(--lt-color-neutral-border-strong);
+  }
+
+  .lt-table tbody tr:last-child th,
+  .lt-table tbody tr:last-child td {
+    border-block-end: 0;
+  }
+
+  .lt-table[data-variant="striped"] tbody tr:nth-child(even) {
+    background: var(--lt-color-neutral-surface);
+  }
+
+  .lt-table[data-hoverable] tbody tr:hover {
+    background: var(--lt-color-accent-surface);
+  }
+
+  .lt-table td[data-align="end"],
+  .lt-table th[data-align="end"] {
+    text-align: end;
+  }
+
+  /*
+   * A sortable column has a button in the header, and the button fills the
+   * cell. The cell gives up its padding and the button takes it over, so
+   * the text sits where it would without a button and the whole cell can be
+   * pressed. Without that the header got padding from both the cell and the
+   * button, and became taller and shifted against the cells below.
+   */
+  .lt-table th:has(> .lt-table__sort) {
+    padding: 0;
+  }
+
+  .lt-table__sort {
+    box-sizing: border-box;
+    display: flex;
+    align-items: center;
+    gap: var(--lt-spacing-2);
+    inline-size: 100%;
+    margin: 0;
+    padding: var(
+      --lt-table-cell-padding,
+      var(--lt-spacing-2) var(--lt-spacing-3)
+    );
+    font: inherit;
+    color: inherit;
+    text-align: inherit;
+    background: none;
+    border: 0;
+    border-radius: 0;
+    /* Can also be a link, when the server sorts without JavaScript. */
+    text-decoration: none;
+    cursor: pointer;
+  }
+
+  .lt-table th[data-align="end"] > .lt-table__sort {
+    justify-content: flex-end;
+  }
+
+  .lt-table__sort:hover {
+    background: var(--lt-color-neutral-surface);
+  }
+
+  .lt-table__sort:focus-visible {
+    outline: var(--lt-focus-ring);
+    outline-offset: -2px;
+  }
+
+  /*
+   * The arrow is read from `aria-sort` on the cell, not from a class. It is
+   * the same attribute the screen reader reads, so what is shown and what is
+   * said cannot drift apart. Without the attribute the button shows both
+   * arrows, muted, so it is visible that the column can be sorted.
+   *
+   * The arrow is a mask and not an image, so it takes the text colour and
+   * flips with the theme. An empty `content` means it never becomes part of
+   * the button's name.
+   */
+  .lt-table__sort::after {
+    content: "";
+    flex: none;
+    inline-size: var(--lt-spacing-3);
+    block-size: var(--lt-spacing-3);
+    background-color: var(--lt-color-neutral-text-subtle);
+    mask:
+      url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath d='M8 1 13 6.5H3zM8 15 3 9.5H13z'/%3E%3C/svg%3E")
+      center / contain no-repeat;
+  }
+
+  .lt-table th[aria-sort="ascending"] > .lt-table__sort::after {
+    background-color: currentColor;
+    mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath d='M8 3 14 11H2z'/%3E%3C/svg%3E");
+  }
+
+  .lt-table th[aria-sort="descending"] > .lt-table__sort::after {
+    background-color: currentColor;
+    mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath d='M8 13 2 5H14z'/%3E%3C/svg%3E");
+  }
+
+  /* High contrast: the mode forces the background colour to the surface
+     colour, and the arrow would then have become invisible. A system colour
+     is left alone, so it is drawn in the system text colour. */
+  @media (forced-colors: active) {
+    .lt-table__sort::after,
+    .lt-table th[aria-sort] > .lt-table__sort::after {
+      background-color: CanvasText;
+    }
+  }
+
+  /* The arrow comes before the text in a right-aligned column, so the text
+     ends where the numbers below end. */
+  .lt-table th[data-align="end"] > .lt-table__sort::after {
+    order: -1;
+  }
+
+  /* A table wider than the screen must be scrollable, and that area must be
+     reachable with the keyboard. Hence tabindex="0" on the container. */
+  .lt-table-scroll {
+    overflow-x: auto;
+    max-inline-size: 100%;
+  }
+
+  .lt-table-scroll:focus-visible {
+    outline: var(--lt-focus-ring);
+    outline-offset: 2px;
+  }
+}

package/src/components/css/table/table.ts

@@ -0,0 +1,107 @@
+import { attributes, createGuard } from "../shared.js"
+
+export const TABLE_CLASS = "lt-table" as const
+/** The container that lets a wide table scroll sideways. */
+export const TABLE_SCROLL_CLASS = "lt-table-scroll" as const
+
+export const tableVariants = ["default", "striped"] as const
+
+export type TableVariant = (typeof tableVariants)[number]
+export type NonDefaultTableVariant = Exclude<TableVariant, "default">
+
+export type TableOptions = {
+  /** Every other row on a muted surface. Default: `default`. */
+  variant?: TableVariant
+  /** Highlights the row under the mouse. Use only when rows can be pressed. */
+  hoverable?: boolean
+}
+
+export type TableAttributes = {
+  class: typeof TABLE_CLASS
+  "data-variant"?: NonDefaultTableVariant
+  "data-hoverable"?: ""
+}
+
+/**
+ * The attributes for a table.
+ *
+ * The class goes on a real `<table>` with `<thead>` and `<th>`. The header
+ * cells are what let screen readers say "Amount, 1,240 kroner" when the user
+ * is in a cell. Build the table from `<div>` elements, and that connection
+ * does not exist.
+ *
+ * ```ts
+ * <table {...table({ variant: "striped" })}>…</table>
+ * ```
+ */
+export const table = Object.assign(
+  ({ variant = "default", hoverable }: TableOptions = {}): TableAttributes =>
+    attributes({
+      class: TABLE_CLASS,
+      "data-variant": variant === "default" ? undefined : variant,
+      "data-hoverable": hoverable ? ("" as const) : undefined,
+    }),
+  {
+    /** The class on the container around a wide table. */
+    scroll: TABLE_SCROLL_CLASS,
+    variants: tableVariants,
+    isVariant: createGuard(tableVariants),
+  },
+)
+
+/** The class on the button in a sortable column header. */
+export const TABLE_SORT_CLASS = "lt-table__sort" as const
+
+export const tableSortDirections = ["ascending", "descending"] as const
+
+export type TableSortDirection = (typeof tableSortDirections)[number]
+
+export type TableSortOptions = {
+  /**
+   * The direction the column is sorted in. Left out, it means the table is
+   * not sorted by this column, and the header gets no `aria-sort`.
+   */
+  direction?: TableSortDirection
+}
+
+export type TableSortAttributes = {
+  header: {
+    "aria-sort"?: TableSortDirection
+  }
+  button: {
+    class: typeof TABLE_SORT_CLASS
+    type: "button"
+  }
+}
+
+/**
+ * The attributes for a sortable column header.
+ *
+ * `aria-sort` is on the `<th>`, not on the button, because the cell is what
+ * describes the column. Only the sorted column has the attribute. The arrow
+ * is drawn from the same attribute, so what the screen reader says and what
+ * is shown cannot drift apart. The sorting itself is the app's job.
+ *
+ * ```ts
+ * const date = lt.tableSort({ direction: "descending" })
+ * ```
+ * ```html
+ * <th scope="col" {...date.header}>
+ *   <button {...date.button}>Date</button>
+ * </th>
+ * ```
+ */
+export const tableSort = Object.assign(
+  ({ direction }: TableSortOptions = {}): TableSortAttributes => ({
+    header: attributes({ "aria-sort": direction }),
+    button: attributes({ class: TABLE_SORT_CLASS, type: "button" as const }),
+  }),
+  {
+    // The list sits next to it, as `tableSortDirections`, and not on the
+    // function. The guard for the lists requires the attribute and the class
+    // to be on the same element, and here `aria-sort` is on the cell and the
+    // class on the button. The table test requires each direction to give its
+    // own arrow.
+    isDirection: createGuard(tableSortDirections),
+  },
+)