@lo-tek/interfaces 0.0.0 → 0.37.0

package/src/components/css/pagination/pagination.css

@@ -0,0 +1,95 @@
+@layer lotek {
+  .lt-pagination {
+    box-sizing: border-box;
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--lt-pagination-gap, var(--lt-spacing-1));
+    margin: 0;
+    padding: 0;
+    list-style: none;
+    font-family: inherit;
+    font-size: var(--lt-font-size-m);
+  }
+
+  /* `span[aria-disabled]` is "Next" on the last page: not a link, but it
+     must have the same box, or the row jumps when it is swapped in. */
+  .lt-pagination a,
+  .lt-pagination button,
+  .lt-pagination span[aria-disabled="true"] {
+    box-sizing: border-box;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    /* 40 pixels in both directions. WCAG 2.2 requires 24, and a number in a
+       long row is easy to miss with a finger. */
+    min-inline-size: var(--lt-pagination-size, var(--lt-spacing-10));
+    min-block-size: var(--lt-pagination-size, var(--lt-spacing-10));
+    padding-inline: var(--lt-spacing-2);
+    font-family: inherit;
+    font-size: inherit;
+    line-height: 1;
+    color: var(--lt-color-accent-text);
+    background: transparent;
+    border: 1px solid transparent;
+    border-radius: var(--lt-pagination-radius, var(--lt-spacing-1));
+    text-decoration: none;
+    cursor: pointer;
+  }
+
+  /* The current page is excluded, and has its own hover below. Without
+     `:not()` this rule won on specificity, and the page number the user is
+     on stayed `accent-content` on `accent-surface`, that is 1.09:1. */
+  .lt-pagination a:not([aria-current="page"]):hover,
+  .lt-pagination button:hover:not(:disabled):not([aria-current="page"]) {
+    background: var(--lt-color-accent-surface);
+  }
+
+  .lt-pagination a:focus-visible,
+  .lt-pagination button:focus-visible {
+    outline: var(--lt-focus-ring);
+    outline-offset: 2px;
+  }
+
+  .lt-pagination [aria-current="page"] {
+    color: var(--lt-color-accent-content);
+    background: var(--lt-color-accent-fill);
+    border-color: var(--lt-color-accent-fill);
+    font-weight: var(--lt-font-weight-semibold);
+  }
+
+  /* Like the button: away from `content`, so darker in the light theme and
+     lighter in the dark one, and the text on top stays readable. */
+  .lt-pagination [aria-current="page"]:hover {
+    background: var(--lt-color-accent-text);
+    border-color: var(--lt-color-accent-text);
+  }
+
+  .lt-pagination button:disabled,
+  .lt-pagination [aria-disabled="true"],
+  .lt-pagination span[aria-disabled="true"] {
+    color: var(--lt-color-disabled-text);
+    cursor: not-allowed;
+  }
+
+  /* The gap in the row of numbers, as in "1 2 ... 9 10". */
+  .lt-pagination__gap {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    min-inline-size: var(--lt-pagination-size, var(--lt-spacing-10));
+    color: var(--lt-color-neutral-text-subtle);
+  }
+
+  /* High contrast: the current page differs only by colour. */
+  @media (forced-colors: active) {
+    /* `:hover` included, or the hover rule beat this one on specificity, and
+       the background was forced to `Canvas` under `HighlightText`: white on
+       white, or black on black. */
+    .lt-pagination [aria-current="page"],
+    .lt-pagination [aria-current="page"]:hover {
+      background-color: Highlight;
+      color: HighlightText;
+    }
+  }
+}

package/src/components/css/pagination/pagination.ts

@@ -0,0 +1,33 @@
+import { attributes } from "../shared.js"
+
+export const PAGINATION_CLASS = "lt-pagination" as const
+/** The gap in the row of numbers, as in "1 2 … 9 10". */
+export const PAGINATION_GAP_CLASS = "lt-pagination__gap" as const
+
+export type PaginationAttributes = {
+  class: typeof PAGINATION_CLASS
+}
+
+/**
+ * The attributes for pagination.
+ *
+ * The class goes on a `<ul>` inside a `<nav aria-label="Pagination">`. Each
+ * page is a link with its own address, not a button: the user can then open
+ * page three in a new tab, and come back with the back button.
+ *
+ * The current page is marked with `aria-current="page"`, which both gives
+ * the colour and is what the screen reader announces.
+ *
+ * ```ts
+ * <nav aria-label="Pagination">
+ *   <ul {...pagination()}>…</ul>
+ * </nav>
+ * ```
+ */
+export const pagination = Object.assign(
+  (): PaginationAttributes => attributes({ class: PAGINATION_CLASS }),
+  {
+    /** The class on the gap in the row of numbers. */
+    gap: PAGINATION_GAP_CLASS,
+  },
+)

package/src/components/css/paragraph/paragraph.css

@@ -0,0 +1,31 @@
+@layer lotek {
+  .lt-paragraph {
+    margin: 0;
+    font-family: inherit;
+    font-size: var(--lt-font-size-m);
+    line-height: var(--lt-paragraph-line-height, var(--lt-line-height-article));
+    color: var(--lt-color-neutral-text-strong);
+    /* Under 75 characters per line. Longer lines make it hard to find the
+       start of the next one. */
+    max-inline-size: var(--lt-paragraph-width, 70ch);
+  }
+
+  .lt-paragraph + .lt-paragraph {
+    margin-block-start: var(--lt-paragraph-gap, var(--lt-spacing-3));
+  }
+
+  .lt-paragraph[data-size="small"] {
+    font-size: var(--lt-font-size-s);
+  }
+
+  .lt-paragraph[data-size="large"] {
+    font-size: var(--lt-font-size-l);
+    line-height: 1.55;
+  }
+
+  .lt-paragraph[data-variant="lead"] {
+    font-size: var(--lt-font-size-l);
+    line-height: 1.55;
+    color: var(--lt-color-neutral-text-subtle);
+  }
+}

package/src/components/css/paragraph/paragraph.ts

@@ -0,0 +1,53 @@
+import { attributes, createGuard } from "../shared.js"
+
+export const PARAGRAPH_CLASS = "lt-paragraph" as const
+
+export const paragraphSizes = ["small", "medium", "large"] as const
+export const paragraphVariants = ["default", "lead"] as const
+
+export type ParagraphSize = (typeof paragraphSizes)[number]
+export type ParagraphVariant = (typeof paragraphVariants)[number]
+export type NonDefaultParagraphSize = Exclude<ParagraphSize, "medium">
+export type NonDefaultParagraphVariant = Exclude<ParagraphVariant, "default">
+
+export type ParagraphOptions = {
+  /** Text size. Default: `medium`. */
+  size?: ParagraphSize
+  /** `lead` is the introduction right below the heading. Default: `default`. */
+  variant?: ParagraphVariant
+}
+
+export type ParagraphAttributes = {
+  class: typeof PARAGRAPH_CLASS
+  "data-size"?: NonDefaultParagraphSize
+  "data-variant"?: NonDefaultParagraphVariant
+}
+
+/**
+ * The attributes for a paragraph.
+ *
+ * The width is limited to 70 characters. Longer lines make it hard to find
+ * the start of the next one, and that is the most common reason a text is
+ * hard to read even when the type is large enough.
+ *
+ * ```ts
+ * <p {...paragraph({ variant: "lead" })}>A short summary of what the page is about.</p>
+ * ```
+ */
+export const paragraph = Object.assign(
+  ({
+    size = "medium",
+    variant = "default",
+  }: ParagraphOptions = {}): ParagraphAttributes =>
+    attributes({
+      class: PARAGRAPH_CLASS,
+      "data-size": size === "medium" ? undefined : size,
+      "data-variant": variant === "default" ? undefined : variant,
+    }),
+  {
+    sizes: paragraphSizes,
+    isSize: createGuard(paragraphSizes),
+    variants: paragraphVariants,
+    isVariant: createGuard(paragraphVariants),
+  },
+)

package/src/components/css/progress/progress.css

@@ -0,0 +1,161 @@
+@layer lotek {
+  /*
+   * The fill colour is carried by `color` on the host, and the filled part
+   * reads `currentColor`.
+   *
+   * The reason is that the filled part has two names,
+   * `::-webkit-progress-value` in Chromium and WebKit and
+   * `::-moz-progress-bar` in Gecko, and they cannot be in the same selector
+   * list: a pseudo-element the engine does not know makes the whole rule
+   * invalid. The colour must therefore be decided in one place and
+   * inherited, and `currentColor` is the built-in way to do that.
+   *
+   * `<progress>` has no text, so `color` is free for the job.
+   * `data-color` changes `--lt-progress-fill`, which `color` reads.
+   */
+  .lt-progress {
+    box-sizing: border-box;
+    appearance: none;
+    display: block;
+    inline-size: 100%;
+    block-size: var(--lt-progress-height, var(--lt-spacing-2));
+    border: 0;
+    /* The track alone is 1.12:1 against the page, and without an edge nobody
+       could see how far the bar goes. `neutral-border` holds 3:1. An inward
+       `outline` and not a `border`: with `border-box` the border took 2
+       pixels of the height, and a 2 pixel bar lost its fill entirely. */
+    /* The longhands, since this is not a focus ring: the shorthand with
+       `solid` is reserved for `--lt-focus-ring`, and
+       `package-css.browser.test.ts` rejects it. */
+    outline-width: 1px;
+    outline-style: solid;
+    outline-color: var(--lt-progress-border, var(--lt-color-neutral-border));
+    outline-offset: -1px;
+    border-radius: var(--lt-progress-radius, var(--lt-spacing-1));
+    overflow: hidden;
+    background: var(--lt-progress-track, var(--lt-color-neutral-surface));
+    color: var(--lt-progress-fill, var(--lt-color-accent-fill));
+  }
+
+  .lt-progress[data-color="success"] {
+    --lt-progress-fill: var(--lt-color-success-fill);
+  }
+
+  .lt-progress[data-color="warning"] {
+    --lt-progress-fill: var(--lt-color-warning-fill);
+  }
+
+  .lt-progress[data-color="danger"] {
+    --lt-progress-fill: var(--lt-color-danger-fill);
+  }
+
+  /* The track behind, in Chromium and WebKit. */
+  .lt-progress::-webkit-progress-bar {
+    background: var(--lt-progress-track, var(--lt-color-neutral-surface));
+  }
+
+  /* The filled part. One rule per engine, for the reason at the top. */
+  .lt-progress::-webkit-progress-value {
+    background: currentColor;
+    transition: inline-size 200ms ease-out;
+  }
+
+  .lt-progress::-moz-progress-bar {
+    background: currentColor;
+    transition: inline-size 200ms ease-out;
+  }
+
+  /*
+   * Indeterminate: a bar without `value`. We then do not know how far it has
+   * come, and a stripe sweeping across it says "in progress" without
+   * promising a number.
+   */
+  .lt-progress:indeterminate {
+    background:
+      linear-gradient(90deg, transparent 0%, currentColor 50%, transparent 100%)
+      no-repeat,
+      var(--lt-progress-track, var(--lt-color-neutral-surface));
+    background-size: 40% 100%;
+    animation: lt-progress-slide 1400ms ease-in-out infinite;
+  }
+
+  /* Without this Chromium and WebKit draw their own track on top of the gradient. */
+  .lt-progress:indeterminate::-webkit-progress-bar {
+    background: transparent;
+  }
+
+  .lt-progress:indeterminate::-moz-progress-bar {
+    background: transparent;
+  }
+
+  @keyframes lt-progress-slide {
+    from {
+      background-position: -40% 0;
+    }
+    to {
+      background-position: 140% 0;
+    }
+  }
+
+  /* As in the spinner: slower rather than still. An indicator that stands
+     still no longer says that something is going on. */
+  @media (prefers-reduced-motion: reduce) {
+    .lt-progress:indeterminate {
+      animation-duration: 4200ms;
+    }
+
+    .lt-progress::-webkit-progress-value {
+      transition: none;
+    }
+
+    .lt-progress::-moz-progress-bar {
+      transition: none;
+    }
+  }
+
+  /*
+   * High contrast: custom colours are overridden, so the filled part must
+   * take its colour from the system colours. `Highlight` is the same as
+   * selection elsewhere in the system, and the edge brings back the shape
+   * when the background becomes `Canvas`.
+   */
+  @media (forced-colors: active) {
+    .lt-progress,
+    .lt-progress[data-color] {
+      --lt-progress-fill: Highlight;
+
+      /* The same inward edge as otherwise, in the system text colour. A
+         `border` would have taken 2 pixels of the height, see above. */
+      outline-color: CanvasText;
+    }
+
+    /*
+     * The variable above is not enough for the filled part. It reads
+     * `currentColor`, and the mode forces the background back to `Canvas`
+     * when the value is not a system colour, so the bar looked empty
+     * whatever the `value`. The system colour must be on the pseudo-element
+     * itself.
+     */
+    .lt-progress::-webkit-progress-value {
+      background: Highlight;
+    }
+
+    .lt-progress::-moz-progress-bar {
+      background: Highlight;
+    }
+
+    /*
+     * The stripe in an indeterminate bar is a gradient, and the mode removes
+     * gradients. Without the exception an empty frame was left, and nothing
+     * said that something was going on. The colours are the system's, so
+     * the user's choice still applies.
+     */
+    .lt-progress:indeterminate {
+      forced-color-adjust: none;
+      background:
+        linear-gradient(90deg, Canvas 0%, Highlight 50%, Canvas 100%) no-repeat,
+        Canvas;
+      background-size: 40% 100%;
+    }
+  }
+}

package/src/components/css/progress/progress.ts

@@ -0,0 +1,78 @@
+import { attributes, createGuard } from "../shared.js"
+
+export const PROGRESS_CLASS = "lt-progress" as const
+
+export const progressColors = ["success", "warning", "danger"] as const
+
+export type ProgressColor = (typeof progressColors)[number]
+
+export type ProgressOptions = {
+  /** How far it has come. Leave it out, and the bar is indeterminate. */
+  value?: number
+  /** What counts as full. Default: `100`. */
+  max?: number
+  /** What the number means. The default is the accent colour, meaning "this is in progress". */
+  color?: ProgressColor
+  /** What is in progress. Becomes `aria-label`, so the bar has a name. */
+  label?: string
+  /**
+   * How far it has come, in words. Becomes `aria-valuetext`, which the
+   * screen reader reads instead of the percentage: "Step 3 of 7" says more
+   * than "43 percent", and `max` is rarely announced.
+   */
+  valueText?: string
+}
+
+export type ProgressAttributes = {
+  class: typeof PROGRESS_CLASS
+  value?: string
+  max: string
+  "data-color"?: ProgressColor
+  "aria-label"?: string
+  "aria-valuetext"?: string
+}
+
+/**
+ * The attributes for a progress bar on a `<progress>`.
+ *
+ * The element has the semantics built in: the browser exposes it as
+ * `role="progressbar"` and announces how far it has come. You need neither a
+ * role, `aria-valuenow` nor `aria-valuemax`.
+ *
+ * Leave out `value`, and the bar becomes indeterminate: "something is going
+ * on, we do not know for how long". That is the same as `lt.spinner()` says,
+ * so choose one of them.
+ *
+ * ```ts
+ * <progress {...progress({ value: 3, max: 7, label: "Step 3 of 7" })} />
+ * ```
+ *
+ * `max` defaults to 100 and is always written out, against the rule that a
+ * default gives no attribute. The reason is that the rule is about
+ * appearance, where the CSS already has the answer. `max` is semantics, and
+ * HTML's own default is `1`: a `<progress value="40">` without `max` shows a
+ * full bar, without anything saying so.
+ */
+export const progress = Object.assign(
+  ({
+    value,
+    max = 100,
+    color,
+    label,
+    valueText,
+  }: ProgressOptions = {}): ProgressAttributes =>
+    attributes({
+      class: PROGRESS_CLASS,
+      // The numbers are sent out as strings, like the rest of the return
+      // values: that is the HTML form, and it is what `setAttributes` accepts.
+      value: value === undefined ? undefined : String(value),
+      max: String(max),
+      "data-color": color,
+      "aria-label": label,
+      "aria-valuetext": valueText,
+    }),
+  {
+    colors: progressColors,
+    isColor: createGuard(progressColors),
+  },
+)

package/src/components/css/radio/radio.css

@@ -0,0 +1,94 @@
+@layer lotek {
+  .lt-radio {
+    box-sizing: border-box;
+    appearance: none;
+    flex: none;
+    display: inline-block;
+    inline-size: var(--lt-radio-size, var(--lt-spacing-5));
+    block-size: var(--lt-radio-size, var(--lt-spacing-5));
+    margin: 0;
+    background-color: var(--lt-color-neutral-canvas);
+    border: 1px solid var(--lt-color-neutral-border);
+    border-radius: 50%;
+    cursor: pointer;
+  }
+
+  /* Without `:not(:disabled)`. It raised the specificity above the states
+     below, so the mouse removed both the error border and the border of a
+     selected button. The rules for selected, disabled and invalid come
+     after this one and win on order. */
+  .lt-radio:hover {
+    border-color: var(--lt-color-neutral-border-strong);
+  }
+
+  .lt-radio:focus-visible {
+    outline: var(--lt-focus-ring);
+    outline-offset: 2px;
+  }
+
+  /* The dot is a gradient and not an image, so it takes its colour from the
+     token directly and needs no separate variant for the dark theme. */
+  .lt-radio:checked {
+    background-color: var(--lt-color-accent-fill);
+    border-color: var(--lt-color-accent-fill);
+    background-image: radial-gradient(
+      circle at center,
+      var(--lt-color-accent-content) 0 32%,
+      transparent 34%
+    );
+  }
+
+  .lt-radio:disabled {
+    background-color: var(--lt-color-disabled-surface);
+    border-color: var(--lt-color-disabled-surface);
+    cursor: not-allowed;
+  }
+
+  .lt-radio:disabled:checked {
+    background-color: var(--lt-color-disabled-text);
+    border-color: var(--lt-color-disabled-text);
+  }
+
+  .lt-radio[data-state="invalid"] {
+    border-color: var(--lt-color-danger-text);
+  }
+
+  .lt-radio[data-state="invalid"]:focus-visible {
+    outline-color: var(--lt-color-danger-text);
+  }
+
+  .lt-radio[data-state="success"] {
+    border-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-radio:disabled[data-state] {
+    background-color: var(--lt-color-disabled-surface);
+    border-color: var(--lt-color-disabled-surface);
+  }
+
+  .lt-radio:disabled:checked[data-state] {
+    background-color: var(--lt-color-disabled-text);
+    border-color: var(--lt-color-disabled-text);
+  }
+
+  .lt-radio-row {
+    display: flex;
+    align-items: flex-start;
+    gap: var(--lt-spacing-2);
+    line-height: var(--lt-line-height-default);
+  }
+
+  /* High contrast: the dot is a gradient, and gradients are removed in the
+     mode. The browser's own radio button is drawn correctly in every
+     theme. */
+  @media (forced-colors: active) {
+    .lt-radio,
+    .lt-radio:checked {
+      appearance: auto;
+      background-image: none;
+    }
+  }
+}

package/src/components/css/radio/radio.ts

@@ -0,0 +1,50 @@
+import {
+  attributes,
+  type FieldState,
+  fieldStates,
+  isFieldState,
+  type NonDefaultFieldState,
+} from "../shared.js"
+
+export const RADIO_CLASS = "lt-radio" as const
+/** The row that holds the button and the text next to each other. */
+export const RADIO_ROW_CLASS = "lt-radio-row" as const
+
+export type RadioOptions = {
+  /** Validation state. Default: `default`. */
+  state?: FieldState
+}
+
+export type RadioAttributes = {
+  class: typeof RADIO_CLASS
+  type: "radio"
+  "data-state"?: NonDefaultFieldState
+  "aria-invalid"?: "true"
+}
+
+/**
+ * The attributes for a radio button.
+ *
+ * All the buttons in a group must have the same `name`. That connection is
+ * what lets only one be selected, and lets the arrow keys move between them.
+ * You set `name` yourself, since only you know what the group is called.
+ *
+ * ```ts
+ * <input {...radio()} name="delivery" value="post" />
+ * ```
+ */
+export const radio = Object.assign(
+  ({ state = "default" }: RadioOptions = {}): RadioAttributes =>
+    attributes({
+      class: RADIO_CLASS,
+      type: "radio" as const,
+      "data-state": state === "default" ? undefined : state,
+      "aria-invalid": state === "invalid" ? ("true" as const) : undefined,
+    }),
+  {
+    /** The class on the row around the button and the text. */
+    row: RADIO_ROW_CLASS,
+    states: fieldStates,
+    isState: isFieldState,
+  },
+)

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

@@ -0,0 +1,50 @@
+@import "../input/input.css";
+
+@layer lotek {
+  /*
+   * Both classes in the selector, not just .lt-search.
+   *
+   * .lt-input sets padding with the shorthand, and .lt-search only
+   * padding-inline-start. With equal specificity the order the stylesheets
+   * load in decides, and if the consumer imports input.css last, the room
+   * for the icon disappears. With both classes the rule wins in any order.
+   */
+  .lt-input.lt-search {
+    padding-inline-start: var(--lt-search-icon-space, var(--lt-spacing-10));
+    background-image: var(--lt-icon-search);
+    background-repeat: no-repeat;
+    background-position: left var(--lt-spacing-3) center;
+    background-size: var(--lt-search-icon-size, var(--lt-spacing-5));
+  }
+
+  .lt-search:dir(rtl) {
+    background-position: right var(--lt-spacing-3) center;
+  }
+
+  /* The browser's own cross in a type="search" field. Safari and Chrome draw
+     it differently, and Firefox not at all. */
+  .lt-search::-webkit-search-cancel-button {
+    cursor: pointer;
+  }
+
+  .lt-search-row {
+    display: flex;
+    align-items: stretch;
+    gap: var(--lt-spacing-2);
+  }
+
+  .lt-search-row .lt-search {
+    flex: 1 1 auto;
+    min-inline-size: 0;
+  }
+
+  /* High contrast: the magnifying glass is painted into the image with a
+     fixed colour, and can become invisible. It is better to remove it and
+     give the room back. */
+  @media (forced-colors: active) {
+    .lt-input.lt-search {
+      background-image: none;
+      padding-inline-start: var(--lt-spacing-3);
+    }
+  }
+}