@lo-tek/interfaces 0.0.0 → 0.38.0

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

@@ -0,0 +1,42 @@
+import { attributes, createGuard } from "../shared.js"
+
+export const HEADING_CLASS = "lt-heading" as const
+
+export const headingSizes = ["xs", "s", "m", "l", "xl", "mega"] as const
+
+export type HeadingSize = (typeof headingSizes)[number]
+export type NonDefaultHeadingSize = Exclude<HeadingSize, "l">
+
+export type HeadingOptions = {
+  /** Visual size. Default: `l`. */
+  size?: HeadingSize
+}
+
+export type HeadingAttributes = {
+  class: typeof HEADING_CLASS
+  "data-size"?: NonDefaultHeadingSize
+}
+
+/**
+ * The attributes for a heading.
+ *
+ * Size and level are two different things. The level is `<h1>` to `<h6>`
+ * and sets the structure screen readers navigate by; `size` only sets how
+ * large the text looks. An `<h2>` that should look small is correct; an
+ * `<h4>` chosen because it was small enough skips a level in the structure.
+ *
+ * ```ts
+ * <h2 {...heading({ size: "m" })}>Attachments</h2>
+ * ```
+ */
+export const heading = Object.assign(
+  ({ size = "l" }: HeadingOptions = {}): HeadingAttributes =>
+    attributes({
+      class: HEADING_CLASS,
+      "data-size": size === "l" ? undefined : size,
+    }),
+  {
+    sizes: headingSizes,
+    isSize: createGuard(headingSizes),
+  },
+)

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

@@ -0,0 +1,24 @@
+@layer lotek {
+  .lt-help-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);
+    line-height: var(--lt-line-height-compact);
+    color: var(--lt-color-neutral-text-subtle);
+  }
+
+  .lt-help-text[data-variant="strong"] {
+    color: var(--lt-color-neutral-text-strong);
+  }
+
+  .lt-help-text[data-variant="success"] {
+    color: var(--lt-color-success-text);
+  }
+
+  .lt-help-text[data-variant="warning"] {
+    color: var(--lt-color-warning-text);
+  }
+}

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

@@ -0,0 +1,42 @@
+import { attributes, createGuard } from "../shared.js"
+
+export const HELP_TEXT_CLASS = "lt-help-text" as const
+
+export const helpTextVariants = [
+  "muted",
+  "strong",
+  "success",
+  "warning",
+] as const
+
+export type HelpTextVariant = (typeof helpTextVariants)[number]
+export type NonDefaultHelpTextVariant = Exclude<HelpTextVariant, "muted">
+
+export type HelpTextOptions = {
+  /** How loudly the text should speak. Default: `muted`. */
+  variant?: HelpTextVariant
+}
+
+export type HelpTextAttributes = {
+  class: typeof HELP_TEXT_CLASS
+  "data-variant"?: NonDefaultHelpTextVariant
+}
+
+/**
+ * The attributes for help text below a field.
+ *
+ * ```ts
+ * <p {...helpText({ variant: "warning" })}>…</p>
+ * ```
+ */
+export const helpText = Object.assign(
+  ({ variant = "muted" }: HelpTextOptions = {}): HelpTextAttributes =>
+    attributes({
+      class: HELP_TEXT_CLASS,
+      "data-variant": variant === "muted" ? undefined : variant,
+    }),
+  {
+    variants: helpTextVariants,
+    isVariant: createGuard(helpTextVariants),
+  },
+)

package/src/components/css/icon/icon.css

@@ -0,0 +1,20 @@
+@layer lotek {
+  /* The icon is an svg from the app's icon set. It is as large as the text
+     around it, and sits in the middle of the line with it, slightly below
+     the baseline, as icon sets are drawn for.
+
+     The size has no component variable. `--lt-icon-*` are the tokens for the
+     icons in the stylesheets, and `font-size` on the icon does the same job.
+
+     The colour comes from the svg, and with `currentColor` it follows the
+     text, also in high contrast. The stylesheet does not set `fill`, because
+     an icon drawn with strokes has `fill="none"`, and a rule here would have
+     filled it. */
+  .lt-icon {
+    display: inline-block;
+    inline-size: 1em;
+    block-size: 1em;
+    flex-shrink: 0;
+    vertical-align: -0.125em;
+  }
+}

package/src/components/css/icon/icon.ts

@@ -0,0 +1,44 @@
+import { attributes } from "../shared.js"
+
+export const ICON_CLASS = "lt-icon" as const
+
+export type IconOptions = {
+  /**
+   * What the icon means, when it stands alone and means something, such as a
+   * warning sign with no text next to it. Becomes `aria-label` with
+   * `role="img"`. Without it the icon is decoration, and is hidden from
+   * screen readers.
+   */
+  label?: string
+}
+
+export type IconAttributes = {
+  class: typeof ICON_CLASS
+  role?: "img"
+  "aria-label"?: string
+  "aria-hidden"?: "true"
+}
+
+/**
+ * The attributes for an icon. The class goes on an `<svg>`, and the svg comes
+ * from the app's icon set: LO-TEK ships no icons.
+ *
+ * The icon is as large as the text around it, and is drawn in the colour the
+ * svg says, which should be `currentColor`. Without `label` it is decoration,
+ * and if it stands alone in a button, the button must get its name somewhere
+ * else: `aria-label` on the button, or a text with `lt-sr-only`. The core
+ * reports a button that lacks one.
+ *
+ * ```ts
+ * <button {...button()} aria-label="Delete the application">
+ *   <svg {...icon()} viewBox="0 0 24 24">…</svg>
+ * </button>
+ * ```
+ */
+export const icon = ({ label }: IconOptions = {}): IconAttributes =>
+  attributes({
+    class: ICON_CLASS,
+    role: label ? ("img" as const) : undefined,
+    "aria-label": label || undefined,
+    "aria-hidden": label ? undefined : ("true" as const),
+  })

package/src/components/css/input/input.css

@@ -0,0 +1,145 @@
+@layer lotek {
+  .lt-input {
+    /* 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-input-width, 100%);
+    padding: var(--lt-input-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-input-radius, var(--lt-spacing-1));
+  }
+
+  .lt-input::placeholder {
+    color: var(--lt-color-neutral-text-subtle);
+  }
+
+  .lt-input:hover {
+    border-color: var(--lt-color-neutral-border-strong);
+  }
+
+  .lt-input:focus-visible {
+    outline: var(--lt-focus-ring);
+    outline-offset: 2px;
+    border-color: var(--lt-color-accent-border);
+  }
+
+  .lt-input:disabled,
+  .lt-input[aria-disabled="true"] {
+    /* `background-color` and not the shorthand, here and in the states
+       below. The shorthand resets `background-image`, and a search field
+       lost its magnifying glass when `input.css` was loaded after
+       `search.css`. */
+    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-input[aria-disabled="true"] {
+    pointer-events: none;
+  }
+
+  .lt-input[data-state="invalid"] {
+    border-color: var(--lt-color-danger-text);
+    background-color: var(--lt-color-danger-surface);
+  }
+
+  .lt-input[data-state="invalid"]:focus-visible {
+    outline-color: var(--lt-color-danger-text);
+  }
+
+  .lt-input[data-state="success"] {
+    border-color: var(--lt-color-success-text);
+    background-color: var(--lt-color-success-surface);
+  }
+
+  .lt-input[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-input: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);
+  }
+
+  .lt-input[data-variant="date"],
+  .lt-input[data-variant="time"],
+  .lt-input[data-variant="datetime-local"] {
+    position: relative;
+    min-height: calc(var(--lt-spacing-4) * 2.5);
+    font-variant-numeric: tabular-nums;
+    letter-spacing: 0.01em;
+    padding-inline-end: calc(var(--lt-spacing-6) + var(--lt-spacing-2));
+    background-repeat: no-repeat;
+    background-position: right var(--lt-spacing-2) center;
+    background-size: 0.95rem 0.95rem;
+  }
+
+  /* background-position has no logical variant, so the direction must be
+     flipped by hand. Everything else here is logical properties, which flip
+     by themselves. */
+  .lt-input[data-variant="date"]:dir(rtl),
+  .lt-input[data-variant="time"]:dir(rtl),
+  .lt-input[data-variant="datetime-local"]:dir(rtl) {
+    background-position: left var(--lt-spacing-2) center;
+  }
+
+  .lt-input[data-variant="date"],
+  .lt-input[data-variant="datetime-local"] {
+    background-image: var(--lt-icon-calendar);
+  }
+
+  .lt-input[data-variant="time"] {
+    background-image: var(--lt-icon-clock);
+  }
+
+  .lt-input[data-variant="date"]::-webkit-calendar-picker-indicator,
+  .lt-input[data-variant="time"]::-webkit-calendar-picker-indicator,
+  .lt-input[data-variant="datetime-local"]::-webkit-calendar-picker-indicator {
+    position: absolute;
+    inset-inline-end: var(--lt-spacing-2);
+    top: 50%;
+    transform: translateY(-50%);
+    opacity: 0;
+    width: var(--lt-spacing-6);
+    height: var(--lt-spacing-6);
+    min-width: var(--lt-spacing-6);
+    min-height: var(--lt-spacing-6);
+    cursor: pointer;
+  }
+
+  /* High contrast: the icon is painted into the image with a fixed colour,
+     and can become invisible in a dark theme. The browser's own button is
+     hidden behind our icon, and is brought back here. */
+  @media (forced-colors: active) {
+    .lt-input[data-variant="date"],
+    .lt-input[data-variant="time"],
+    .lt-input[data-variant="datetime-local"] {
+      background-image: none;
+    }
+
+    .lt-input[data-variant="date"]::-webkit-calendar-picker-indicator,
+    .lt-input[data-variant="time"]::-webkit-calendar-picker-indicator,
+    .lt-input[data-variant="datetime-local"]::-webkit-calendar-picker-indicator {
+      opacity: 1;
+    }
+  }
+}

package/src/components/css/input/input.ts

@@ -0,0 +1,77 @@
+import {
+  attributes,
+  createGuard,
+  type FieldState,
+  fieldStates,
+  isFieldState,
+  type NonDefaultFieldState,
+} from "../shared.js"
+
+export const INPUT_CLASS = "lt-input" as const
+
+export const inputTypes = [
+  "text",
+  "password",
+  "email",
+  "number",
+  "date",
+  "datetime-local",
+  "week",
+  "month",
+  "tel",
+  "url",
+  "search",
+  "time",
+] as const
+
+export type InputType = (typeof inputTypes)[number]
+
+/** The types that get an icon in the field, and that open the browser's own picker. */
+const TYPES_WITH_ICON = ["date", "time", "datetime-local"] as const
+type TypeWithIcon = (typeof TYPES_WITH_ICON)[number]
+
+export type InputOptions = {
+  /** The HTML type. Set as `type`, and decides the icon. Default: `text`. */
+  type?: InputType
+  /** Validation state. Default: `default`. */
+  state?: FieldState
+}
+
+export type InputAttributes = {
+  class: typeof INPUT_CLASS
+  type: InputType
+  "data-variant"?: TypeWithIcon
+  "data-state"?: NonDefaultFieldState
+  "aria-invalid"?: "true"
+}
+
+/**
+ * The attributes for a text field.
+ *
+ * `type` sets both the HTML type and the icon variant, so the two cannot get
+ * out of step. Write them by hand, and it is easy to get a date field that
+ * looks like a date field, but where nothing happens when the user presses
+ * the icon.
+ *
+ * ```ts
+ * <input {...input({ type: "date", state: "invalid" })} />
+ * ```
+ */
+export const input = Object.assign(
+  ({ type = "text", state = "default" }: InputOptions = {}): InputAttributes =>
+    attributes({
+      class: INPUT_CLASS,
+      type,
+      "data-variant": (TYPES_WITH_ICON as readonly string[]).includes(type)
+        ? (type as TypeWithIcon)
+        : undefined,
+      "data-state": state === "default" ? undefined : state,
+      "aria-invalid": state === "invalid" ? ("true" as const) : undefined,
+    }),
+  {
+    types: inputTypes,
+    isType: createGuard(inputTypes),
+    states: fieldStates,
+    isState: isFieldState,
+  },
+)

package/src/components/css/label/label.css

@@ -0,0 +1,42 @@
+@layer lotek {
+  .lt-label {
+    display: block;
+    font-family: inherit;
+    font-size: var(--lt-font-size-s);
+    font-weight: var(--lt-font-weight-semibold);
+    line-height: var(--lt-line-height-default);
+    color: var(--lt-color-neutral-text-strong);
+  }
+
+  .lt-label[data-required]::after {
+    content: var(--lt-label-required-symbol, " *");
+    color: var(--lt-color-danger-text);
+    font-weight: var(--lt-font-weight-bold);
+  }
+
+  .lt-label[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-label[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-label[aria-disabled="true"] {
+    color: var(--lt-color-neutral-text-subtle);
+  }
+}

package/src/components/css/label/label.ts

@@ -0,0 +1,51 @@
+import {
+  attributes,
+  createGuard,
+  type RequiredMarker,
+  requiredMarkers,
+} from "../shared.js"
+
+export const LABEL_CLASS = "lt-label" as const
+
+export type { RequiredMarker }
+export { requiredMarkers }
+
+export type LabelOptions = {
+  /** Marks the field as required, with an asterisk or with the word "(required)". */
+  required?: RequiredMarker
+  /** Marks the field as optional. Choose one of `required` and `optional`. */
+  optional?: boolean
+  /** Mutes the text when the control is disabled. */
+  disabled?: boolean
+}
+
+export type LabelAttributes = {
+  class: typeof LABEL_CLASS
+  "data-required"?: RequiredMarker
+  "data-optional"?: ""
+  "aria-disabled"?: "true"
+}
+
+/**
+ * The attributes for a label.
+ *
+ * The marker is only visual, so set `required` on the field itself as well,
+ * or the screen reader is not told that it must be filled in.
+ *
+ * ```ts
+ * <label {...label({ required: "symbol" })} htmlFor="email">Email address</label>
+ * ```
+ */
+export const label = Object.assign(
+  ({ required, optional, disabled }: LabelOptions = {}): LabelAttributes =>
+    attributes({
+      class: LABEL_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/link/link.css

@@ -0,0 +1,38 @@
+@layer lotek {
+  .lt-link {
+    color: var(--lt-color-accent-text);
+    font-family: inherit;
+    font-size: inherit;
+    line-height: var(--lt-line-height-default);
+    text-decoration-line: underline;
+    text-decoration-thickness: 0.08em;
+    text-underline-offset: 0.14em;
+    text-decoration-color: currentColor;
+    transition:
+      color 120ms ease,
+      text-decoration-color 120ms ease;
+  }
+
+  /* Before `:hover`, with the same specificity: the last one wins, and a
+     visited link should also change colour under the mouse. */
+  .lt-link:visited {
+    color: var(--lt-color-visited-text);
+  }
+
+  .lt-link:hover {
+    color: var(--lt-color-accent-text-strong);
+  }
+
+  .lt-link:focus-visible {
+    outline: var(--lt-focus-ring);
+    outline-offset: 2px;
+    border-radius: var(--lt-spacing-0-5);
+  }
+
+  .lt-link[aria-disabled="true"] {
+    color: var(--lt-color-neutral-text-subtle);
+    text-decoration: none;
+    cursor: not-allowed;
+    pointer-events: none;
+  }
+}

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

@@ -0,0 +1,38 @@
+import { attributes } from "../shared.js"
+
+export const LINK_CLASS = "lt-link" as const
+
+export type LinkOptions = {
+  /**
+   * The link cannot be clicked yet. Gives `aria-disabled`, `role="link"` and
+   * `tabindex="0"`, so screen readers still find it as a link and can say
+   * so. Remove `href` as well: otherwise Enter follows it.
+   */
+  disabled?: boolean
+}
+
+export type LinkAttributes = {
+  class: typeof LINK_CLASS
+  role?: "link"
+  tabindex?: "0"
+  "aria-disabled"?: "true"
+}
+
+/**
+ * The attributes for a link.
+ *
+ * ```ts
+ * <a {...link()} href="/receipt">See receipt</a>
+ * <a {...link({ disabled: true })}>See annual statement</a>
+ * ```
+ *
+ * An `<a>` without `href` is no link to a screen reader and is not in the
+ * tab order. `role` and `tabindex` give it both back while it is disabled.
+ */
+export const link = ({ disabled = false }: LinkOptions = {}): LinkAttributes =>
+  attributes({
+    class: LINK_CLASS,
+    role: disabled ? ("link" as const) : undefined,
+    tabindex: disabled ? ("0" as const) : undefined,
+    "aria-disabled": disabled ? ("true" as const) : undefined,
+  })

package/src/components/css/list/list.css

@@ -0,0 +1,53 @@
+@layer lotek {
+  .lt-list {
+    box-sizing: border-box;
+    margin: 0;
+    padding-inline-start: var(--lt-spacing-5);
+    /* The bullets and numbers are the browser's own, and are set here because
+       a layer declared before `lotek`, such as Tailwind's Preflight in
+       `base`, sets `list-style: none` on all lists. Without this rule
+       `lotek` said nothing about the bullets, and Preflight won. `revert`
+       goes back to the browser's stylesheet, so <ul> gets bullets, <ol>
+       numbers, and a nested list circles and squares, as without Tailwind.
+       Only the type, because the type is what Preflight takes; a
+       `list-style-position` the consumer has set in an earlier layer still
+       goes through. The variants below set `none` themselves, with higher
+       specificity. */
+    list-style-type: revert;
+    font-family: inherit;
+    font-size: var(--lt-font-size-m);
+    line-height: var(--lt-line-height-article);
+    color: var(--lt-color-neutral-text-strong);
+  }
+
+  .lt-list li + li {
+    margin-block-start: var(--lt-list-gap, var(--lt-spacing-1));
+  }
+
+  .lt-list .lt-list {
+    margin-block-start: var(--lt-list-gap, var(--lt-spacing-1));
+  }
+
+  /* Without bullets and indentation, for lists that carry their own
+     structure, such as rows of cards. The list stays a list for screen
+     readers, except a <ul> in Safari, which can need role="list". See the
+     component page. */
+  .lt-list[data-variant="plain"] {
+    list-style: none;
+    padding-inline-start: 0;
+  }
+
+  .lt-list[data-variant="divided"] {
+    list-style: none;
+    padding-inline-start: 0;
+  }
+
+  .lt-list[data-variant="divided"] li + li {
+    margin-block-start: 0;
+    border-block-start: 1px solid var(--lt-color-neutral-border-subtle);
+  }
+
+  .lt-list[data-variant="divided"] li {
+    padding-block: var(--lt-list-gap, var(--lt-spacing-2));
+  }
+}

package/src/components/css/list/list.ts

@@ -0,0 +1,44 @@
+import { attributes, createGuard } from "../shared.js"
+
+export const LIST_CLASS = "lt-list" as const
+
+export const listVariants = ["default", "plain", "divided"] as const
+
+export type ListVariant = (typeof listVariants)[number]
+export type NonDefaultListVariant = Exclude<ListVariant, "default">
+
+export type ListOptions = {
+  /** Bullets, plain rows, or rows with a line between them. Default: `default`. */
+  variant?: ListVariant
+}
+
+export type ListAttributes = {
+  class: typeof LIST_CLASS
+  "data-variant"?: NonDefaultListVariant
+}
+
+/**
+ * The attributes for a list.
+ *
+ * The class goes on `<ul>` or `<ol>`. `plain` and `divided` remove the
+ * bullets visually, but the list stays a list, so the screen reader still
+ * says how many items it has. That is why the variant exists: without it
+ * people would use `<div>` to get rid of the bullets. The exception is
+ * Safari, where a `<ul>` without visible bullets can need `role="list"`. See
+ * the component page.
+ *
+ * ```ts
+ * <ul {...list({ variant: "divided" })}>…</ul>
+ * ```
+ */
+export const list = Object.assign(
+  ({ variant = "default" }: ListOptions = {}): ListAttributes =>
+    attributes({
+      class: LIST_CLASS,
+      "data-variant": variant === "default" ? undefined : variant,
+    }),
+  {
+    variants: listVariants,
+    isVariant: createGuard(listVariants),
+  },
+)