@lo-tek/interfaces 0.0.0-stage → 0.37.0

package/src/components/css/checkbox/checkbox.css

@@ -0,0 +1,114 @@
+@layer lotek {
+  .lt-checkbox {
+    /* The design system cannot assume the consumer has a CSS reset. */
+    box-sizing: border-box;
+
+    appearance: none;
+    flex: none;
+    display: inline-block;
+    inline-size: var(--lt-checkbox-size, var(--lt-spacing-5));
+    block-size: var(--lt-checkbox-size, var(--lt-spacing-5));
+    margin: 0;
+    background-color: var(--lt-color-neutral-canvas);
+    background-position: center;
+    background-repeat: no-repeat;
+    background-size: 80%;
+    border: 1px solid var(--lt-color-neutral-border);
+    border-radius: var(--lt-checkbox-radius, var(--lt-spacing-1));
+    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
+     checked box. The rules for checked, disabled and invalid come after
+     this one and win on order. */
+  .lt-checkbox:hover {
+    border-color: var(--lt-color-neutral-border-strong);
+  }
+
+  .lt-checkbox:focus-visible {
+    outline: var(--lt-focus-ring);
+    outline-offset: 2px;
+  }
+
+  .lt-checkbox:checked,
+  .lt-checkbox:indeterminate {
+    background-color: var(--lt-color-accent-fill);
+    border-color: var(--lt-color-accent-fill);
+  }
+
+  /* The tick is a token and not an image in this file, because a data URL
+     cannot read a CSS variable. The stroke is painted into the image, and
+     must therefore flip with the theme where the other colours flip. */
+  .lt-checkbox:checked {
+    background-image: var(--lt-icon-check);
+  }
+
+  .lt-checkbox:indeterminate {
+    background-image: var(--lt-icon-dash);
+  }
+
+  .lt-checkbox:disabled {
+    background-color: var(--lt-color-disabled-surface);
+    border-color: var(--lt-color-disabled-surface);
+    cursor: not-allowed;
+  }
+
+  .lt-checkbox:disabled:checked,
+  .lt-checkbox:disabled:indeterminate {
+    background-color: var(--lt-color-disabled-text);
+    border-color: var(--lt-color-disabled-text);
+  }
+
+  .lt-checkbox[data-state="invalid"] {
+    border-color: var(--lt-color-danger-text);
+  }
+
+  .lt-checkbox[data-state="invalid"]:focus-visible {
+    outline-color: var(--lt-color-danger-text);
+  }
+
+  .lt-checkbox[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-checkbox:disabled[data-state] {
+    background-color: var(--lt-color-disabled-surface);
+    border-color: var(--lt-color-disabled-surface);
+  }
+
+  .lt-checkbox:disabled:is(:checked, :indeterminate)[data-state] {
+    background-color: var(--lt-color-disabled-text);
+    border-color: var(--lt-color-disabled-text);
+  }
+
+  /* The box and the text on one line, with the text in place over several lines. */
+  .lt-checkbox-row {
+    display: flex;
+    align-items: flex-start;
+    gap: var(--lt-spacing-2);
+    line-height: var(--lt-line-height-default);
+  }
+
+  /*
+   * High contrast: let the browser draw the box itself.
+   *
+   * Tested in the mode: gradients and box-shadow are removed, custom colours
+   * are overridden, and only system colours, borders, masks and data URL
+   * images survive. Our tick is white and painted into the image, so it
+   * would have become invisible against the forced surface. The browser's
+   * own checkbox is correct in every theme the user can choose, and costs
+   * us nothing to fall back on.
+   */
+  @media (forced-colors: active) {
+    .lt-checkbox,
+    .lt-checkbox:checked,
+    .lt-checkbox:indeterminate {
+      appearance: auto;
+      background-image: none;
+    }
+  }
+}

package/src/components/css/checkbox/checkbox.ts

@@ -0,0 +1,50 @@
+import {
+  attributes,
+  type FieldState,
+  fieldStates,
+  isFieldState,
+  type NonDefaultFieldState,
+} from "../shared.js"
+
+export const CHECKBOX_CLASS = "lt-checkbox" as const
+/** The row that holds the box and the text next to each other. */
+export const CHECKBOX_ROW_CLASS = "lt-checkbox-row" as const
+
+export type CheckboxOptions = {
+  /** Validation state. Default: `default`. */
+  state?: FieldState
+}
+
+export type CheckboxAttributes = {
+  class: typeof CHECKBOX_CLASS
+  type: "checkbox"
+  "data-state"?: NonDefaultFieldState
+  "aria-invalid"?: "true"
+}
+
+/**
+ * The attributes for a checkbox.
+ *
+ * `type` is set here, so the box cannot become a text field with a box's
+ * styling. The indeterminate state is set with `element.indeterminate = true`
+ * in JavaScript, not as an attribute, because HTML has no such attribute.
+ *
+ * ```ts
+ * <input {...checkbox({ state: "invalid" })} />
+ * ```
+ */
+export const checkbox = Object.assign(
+  ({ state = "default" }: CheckboxOptions = {}): CheckboxAttributes =>
+    attributes({
+      class: CHECKBOX_CLASS,
+      type: "checkbox" as const,
+      "data-state": state === "default" ? undefined : state,
+      "aria-invalid": state === "invalid" ? ("true" as const) : undefined,
+    }),
+  {
+    /** The class on the row around the box and the text. */
+    row: CHECKBOX_ROW_CLASS,
+    states: fieldStates,
+    isState: isFieldState,
+  },
+)

package/src/components/css/divider/divider.css

@@ -0,0 +1,38 @@
+@layer lotek {
+  .lt-divider {
+    /* <hr> has both a border and a height from the browser. Both must go
+       before the colour below is the only thing shown. */
+    border: 0;
+    block-size: 1px;
+    /* The browser also gives <hr> auto margins at the sides. In a flex
+       column they win over stretch, and the line shrinks to its content,
+       which is nothing. It was 0 pixels wide and invisible. It also
+       stretches when the parent centres its children or aligns them to the
+       start. */
+    margin-block: var(--lt-divider-space, var(--lt-spacing-4));
+    margin-inline: 0;
+    align-self: stretch;
+    justify-self: stretch;
+    background: var(--lt-color-neutral-border-subtle);
+  }
+
+  .lt-divider[data-variant="strong"] {
+    background: var(--lt-color-neutral-border-strong);
+  }
+
+  /* The surface colour alone was so close to the canvas that the line almost
+     disappeared. raised sits between it and border-subtle in both themes. */
+  .lt-divider[data-variant="subtle"] {
+    background: var(--lt-color-neutral-raised);
+  }
+
+  /* High contrast: backgrounds are forced to the page surface colour, and the
+     line was only a background. It became invisible. A system colour
+     survives. */
+  @media (forced-colors: active) {
+    .lt-divider,
+    .lt-divider[data-variant] {
+      background: CanvasText;
+    }
+  }
+}

package/src/components/css/divider/divider.ts

@@ -0,0 +1,42 @@
+import { attributes, createGuard } from "../shared.js"
+
+export const DIVIDER_CLASS = "lt-divider" as const
+
+export const dividerVariants = ["default", "subtle", "strong"] as const
+
+export type DividerVariant = (typeof dividerVariants)[number]
+export type NonDefaultDividerVariant = Exclude<DividerVariant, "default">
+
+export type DividerOptions = {
+  /** How visible the line is. Default: `default`. */
+  variant?: DividerVariant
+}
+
+export type DividerAttributes = {
+  class: typeof DIVIDER_CLASS
+  "data-variant"?: NonDefaultDividerVariant
+}
+
+/**
+ * The attributes for a divider.
+ *
+ * The class goes on an `<hr>`. If the line separates two parts of the
+ * content, it is information screen readers should get. If it is only
+ * decoration between two boxes that are already apart, set
+ * `aria-hidden="true"` on it.
+ *
+ * ```ts
+ * <hr {...divider({ variant: "subtle" })} />
+ * ```
+ */
+export const divider = Object.assign(
+  ({ variant = "default" }: DividerOptions = {}): DividerAttributes =>
+    attributes({
+      class: DIVIDER_CLASS,
+      "data-variant": variant === "default" ? undefined : variant,
+    }),
+  {
+    variants: dividerVariants,
+    isVariant: createGuard(dividerVariants),
+  },
+)

package/src/components/css/error-text/error-text.css

@@ -0,0 +1,21 @@
+@layer lotek {
+  .lt-error-text {
+    display: block;
+    /* The whole margin is set, not just the top: without it a <p> inherits
+       the browser's 1em at the bottom for consumers without a reset. */
+    margin: var(--lt-spacing-1) 0 0;
+    font-family: inherit;
+    font-size: var(--lt-font-size-xs);
+    font-weight: var(--lt-font-weight-medium);
+    line-height: var(--lt-line-height-compact);
+    color: var(--lt-color-danger-text);
+  }
+
+  .lt-error-text[hidden] {
+    display: none;
+  }
+
+  .lt-error-text[data-variant="warning"] {
+    color: var(--lt-color-warning-text);
+  }
+}

package/src/components/css/error-text/error-text.ts

@@ -0,0 +1,37 @@
+import { attributes, createGuard } from "../shared.js"
+
+export const ERROR_TEXT_CLASS = "lt-error-text" as const
+
+export const errorTextVariants = ["error", "warning"] as const
+
+export type ErrorTextVariant = (typeof errorTextVariants)[number]
+export type NonDefaultErrorTextVariant = Exclude<ErrorTextVariant, "error">
+
+export type ErrorTextOptions = {
+  /** Whether the error stops submission or only warns. Default: `error`. */
+  variant?: ErrorTextVariant
+}
+
+export type ErrorTextAttributes = {
+  class: typeof ERROR_TEXT_CLASS
+  "data-variant"?: NonDefaultErrorTextVariant
+}
+
+/**
+ * The attributes for an error text below a field.
+ *
+ * ```ts
+ * <p {...errorText({ variant: "warning" })}>…</p>
+ * ```
+ */
+export const errorText = Object.assign(
+  ({ variant = "error" }: ErrorTextOptions = {}): ErrorTextAttributes =>
+    attributes({
+      class: ERROR_TEXT_CLASS,
+      "data-variant": variant === "error" ? undefined : variant,
+    }),
+  {
+    variants: errorTextVariants,
+    isVariant: createGuard(errorTextVariants),
+  },
+)

package/src/components/css/fieldset/fieldset.css

@@ -0,0 +1,72 @@
+@import "../label/label.css";
+
+@layer lotek {
+  .lt-fieldset {
+    box-sizing: border-box;
+    display: flex;
+    flex-direction: column;
+    gap: var(--lt-fieldset-gap, var(--lt-spacing-2));
+    margin: 0;
+    padding: 0;
+    /* The browser's own border and indentation on <fieldset> belong to a look
+       from 1996, and cannot be turned off unless both are reset here. */
+    border: 0;
+    min-inline-size: 0;
+  }
+
+  .lt-legend {
+    padding: 0;
+    margin-block-end: var(--lt-spacing-1);
+    font-family: inherit;
+    font-size: var(--lt-font-size-m);
+    font-weight: var(--lt-font-weight-semibold);
+    line-height: var(--lt-line-height-default);
+    color: var(--lt-color-neutral-text-strong);
+  }
+
+  /* The same marker as on a label. The rules are here and not in label.css,
+     because <legend> is a different element with its own defaults. */
+  .lt-legend[data-required]::after {
+    content: var(--lt-label-required-symbol, " *");
+    color: var(--lt-color-danger-text);
+    font-weight: var(--lt-font-weight-bold);
+  }
+
+  .lt-legend[data-required="text"]::after {
+    /* Keep the fallback ASCII. A stylesheet without `@charset` inherits the
+       page's encoding, and a non-ASCII fallback came out garbled when the
+       page lacked `<meta charset>` and the server sent no charset. Write any
+       other character as an escape, such as `\e5`. */
+    content: var(--lt-label-required-text, " (required)");
+    color: var(--lt-color-danger-text);
+    font-weight: var(--lt-font-weight-regular);
+    font-size: var(--lt-font-size-xs);
+  }
+
+  /* Not when the field is also marked required: the builder function picks
+     required, and hand-written markup with both must give the same result.
+     The colour is not `disabled-text`: the text is not disabled, and that
+     colour gave 4.37:1. */
+  .lt-legend[data-optional]:not([data-required])::after {
+    content: var(--lt-label-optional-text, " (optional)");
+    color: var(--lt-color-neutral-text-subtle);
+    font-weight: var(--lt-font-weight-regular);
+    font-size: var(--lt-font-size-xs);
+  }
+
+  .lt-fieldset[data-state="invalid"] .lt-legend {
+    color: var(--lt-color-danger-text);
+  }
+
+  /* The fieldset has the same states as the controls it contains, and
+     `lt.fieldset.states` has always listed both. Without this rule the
+     builder function wrote out an attribute that did nothing. */
+  .lt-fieldset[data-state="success"] .lt-legend {
+    color: var(--lt-color-success-text);
+  }
+
+  .lt-fieldset:disabled .lt-legend,
+  .lt-legend[aria-disabled="true"] {
+    color: var(--lt-color-neutral-text-subtle);
+  }
+}

package/src/components/css/fieldset/fieldset.ts

@@ -0,0 +1,87 @@
+import {
+  attributes,
+  createGuard,
+  type FieldState,
+  fieldStates,
+  isFieldState,
+  type NonDefaultFieldState,
+  type RequiredMarker,
+  requiredMarkers,
+} from "../shared.js"
+
+export const FIELDSET_CLASS = "lt-fieldset" as const
+export const LEGEND_CLASS = "lt-legend" as const
+
+export type FieldsetOptions = {
+  /** Validation state for the whole group. Default: `default`. */
+  state?: FieldState
+  /** Disables all the controls in the group. */
+  disabled?: boolean
+}
+
+export type FieldsetAttributes = {
+  class: typeof FIELDSET_CLASS
+  "data-state"?: NonDefaultFieldState
+  disabled?: true
+}
+
+export type LegendOptions = {
+  /** Marks the group as required, with an asterisk or with the word "(required)". */
+  required?: RequiredMarker
+  /** Marks the group as optional. Choose one of `required` and `optional`. */
+  optional?: boolean
+  /** Mutes the text when the group is disabled. */
+  disabled?: boolean
+}
+
+export type LegendAttributes = {
+  class: typeof LEGEND_CLASS
+  "data-required"?: RequiredMarker
+  "data-optional"?: ""
+  "aria-disabled"?: "true"
+}
+
+/**
+ * The attributes for a group of controls that belong together.
+ *
+ * `<fieldset>` with `<legend>` is the one way to give a set of radio buttons
+ * or checkboxes a shared label that screen readers actually announce before
+ * each choice.
+ *
+ * ```ts
+ * <fieldset {...fieldset({ state: "invalid" })}>
+ *   <legend {...legend({ required: "symbol" })}>Delivery method</legend>
+ * </fieldset>
+ * ```
+ */
+export const fieldset = Object.assign(
+  ({ state = "default", disabled }: FieldsetOptions = {}): FieldsetAttributes =>
+    attributes({
+      class: FIELDSET_CLASS,
+      "data-state": state === "default" ? undefined : state,
+      disabled: disabled ? (true as const) : undefined,
+    }),
+  {
+    states: fieldStates,
+    isState: isFieldState,
+  },
+)
+
+/**
+ * The attributes for the label of a group.
+ *
+ * The same marker as `label()`, but on a `<legend>`.
+ */
+export const legend = Object.assign(
+  ({ required, optional, disabled }: LegendOptions = {}): LegendAttributes =>
+    attributes({
+      class: LEGEND_CLASS,
+      "data-required": required,
+      "data-optional": optional && !required ? ("" as const) : undefined,
+      "aria-disabled": disabled ? ("true" as const) : undefined,
+    }),
+  {
+    markers: requiredMarkers,
+    isMarker: createGuard(requiredMarkers),
+  },
+)

package/src/components/css/file-upload/file-upload.css

@@ -0,0 +1,102 @@
+@layer lotek {
+  .lt-file-upload {
+    box-sizing: border-box;
+    display: block;
+    inline-size: 100%;
+    padding: var(--lt-file-upload-padding, 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: var(--lt-color-neutral-canvas);
+    border: 1px dashed var(--lt-color-neutral-border);
+    border-radius: var(--lt-file-upload-radius, var(--lt-spacing-1));
+    cursor: pointer;
+  }
+
+  /* The button inside the field is the browser's own, and can only be styled
+     through this pseudo-element. Its text comes from the browser and the
+     operating system's language, so it cannot be translated from here. */
+  .lt-file-upload::file-selector-button {
+    margin-inline-end: var(--lt-spacing-3);
+    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-text);
+    background: transparent;
+    border: 1px solid var(--lt-color-accent-border);
+    border-radius: var(--lt-file-upload-radius, var(--lt-spacing-1));
+    cursor: pointer;
+  }
+
+  .lt-file-upload::file-selector-button:hover {
+    background: var(--lt-color-accent-surface);
+  }
+
+  .lt-file-upload:hover {
+    border-color: var(--lt-color-neutral-border-strong);
+  }
+
+  .lt-file-upload:focus-visible {
+    outline: var(--lt-focus-ring);
+    outline-offset: 2px;
+  }
+
+  .lt-file-upload:disabled {
+    background: var(--lt-color-disabled-surface);
+    color: var(--lt-color-disabled-text);
+    border-color: var(--lt-color-disabled-surface);
+    cursor: not-allowed;
+  }
+
+  .lt-file-upload[data-state="invalid"] {
+    border-color: var(--lt-color-danger-text);
+    background: var(--lt-color-danger-surface);
+  }
+
+  .lt-file-upload[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-file-upload:disabled[data-state] {
+    background: var(--lt-color-disabled-surface);
+    color: var(--lt-color-disabled-text);
+    border-color: var(--lt-color-disabled-surface);
+  }
+
+  /* The list of the selected files. You write it yourself, since only you
+     know what should happen when a file is removed. */
+  .lt-file-upload-list {
+    display: flex;
+    flex-direction: column;
+    gap: var(--lt-spacing-2);
+    margin: var(--lt-spacing-2) 0 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  .lt-file-upload-list li {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--lt-spacing-2);
+    padding: var(--lt-spacing-2) var(--lt-spacing-3);
+    background: var(--lt-color-neutral-surface);
+    border-radius: var(--lt-file-upload-radius, var(--lt-spacing-1));
+    /* File names rarely have spaces to break at, and the button text repeats
+       the name. Without this the row pushes wider than the screen on
+       mobile. */
+    overflow-wrap: anywhere;
+  }
+
+  /* A flex item cannot by default become narrower than its content. Without
+     this the file name does not break, whatever we say above. */
+  .lt-file-upload-list li > * {
+    min-inline-size: 0;
+  }
+}

package/src/components/css/file-upload/file-upload.ts

@@ -0,0 +1,65 @@
+import {
+  attributes,
+  type FieldState,
+  fieldStates,
+  isFieldState,
+  type NonDefaultFieldState,
+} from "../shared.js"
+
+export const FILE_UPLOAD_CLASS = "lt-file-upload" as const
+/** The list of the selected files. */
+export const FILE_UPLOAD_LIST_CLASS = "lt-file-upload-list" as const
+
+export type FileUploadOptions = {
+  /** Validation state. Default: `default`. */
+  state?: FieldState
+  /** Allow several files. */
+  multiple?: boolean
+  /** The file types the field accepts, such as `.pdf,image/*`. */
+  accept?: string
+}
+
+export type FileUploadAttributes = {
+  class: typeof FILE_UPLOAD_CLASS
+  type: "file"
+  multiple?: true
+  accept?: string
+  "data-state"?: NonDefaultFieldState
+  "aria-invalid"?: "true"
+}
+
+/**
+ * The attributes for a file upload field.
+ *
+ * The field is a plain `<input type="file">`. The button inside is the
+ * browser's own, and its text comes from the operating system's language. It
+ * cannot be translated, so the label above the field must say what to upload.
+ *
+ * `accept` is a help in the file picker, not a barrier. The user can choose
+ * "all files", so the type must be checked on the server anyway.
+ *
+ * ```ts
+ * <input {...fileUpload({ multiple: true, accept: ".pdf" })} />
+ * ```
+ */
+export const fileUpload = Object.assign(
+  ({
+    state = "default",
+    multiple,
+    accept,
+  }: FileUploadOptions = {}): FileUploadAttributes =>
+    attributes({
+      class: FILE_UPLOAD_CLASS,
+      type: "file" as const,
+      multiple: multiple ? (true as const) : undefined,
+      accept,
+      "data-state": state === "default" ? undefined : state,
+      "aria-invalid": state === "invalid" ? ("true" as const) : undefined,
+    }),
+  {
+    /** The class on the list of selected files. */
+    list: FILE_UPLOAD_LIST_CLASS,
+    states: fieldStates,
+    isState: isFieldState,
+  },
+)

package/src/components/css/heading/heading.css

@@ -0,0 +1,33 @@
+@layer lotek {
+  .lt-heading {
+    margin: 0;
+    font-family: inherit;
+    font-weight: var(--lt-heading-font-weight, var(--lt-font-weight-bold));
+    line-height: var(--lt-heading-line-height, var(--lt-line-height-heading));
+    color: var(--lt-color-neutral-text-strong);
+    text-wrap: balance;
+    font-size: var(--lt-font-size-xl);
+  }
+
+  .lt-heading[data-size="mega"] {
+    font-size: var(--lt-font-size-mega);
+  }
+
+  .lt-heading[data-size="xl"] {
+    font-size: var(--lt-font-size-xxl);
+  }
+
+  .lt-heading[data-size="m"] {
+    font-size: var(--lt-font-size-l);
+  }
+
+  .lt-heading[data-size="s"] {
+    font-size: var(--lt-font-size-m);
+  }
+
+  .lt-heading[data-size="xs"] {
+    font-size: var(--lt-font-size-s);
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+  }
+}