@lo-tek/interfaces 0.0.0 → 0.38.0

package/src/components/css/alert/alert.ts

@@ -0,0 +1,48 @@
+import { attributes, createGuard } from "../shared.js"
+
+export const ALERT_CLASS = "lt-alert" as const
+/** The heading inside the message. */
+export const ALERT_TITLE_CLASS = "lt-alert__title" as const
+
+export const alertColors = ["info", "success", "warning", "danger"] as const
+
+export type AlertColor = (typeof alertColors)[number]
+export type NonNeutralAlertColor = AlertColor
+
+export type AlertOptions = {
+  /** What the message means. Left out, it is the neutral one. */
+  color?: AlertColor
+}
+
+export type AlertAttributes = {
+  class: typeof ALERT_CLASS
+  "data-color"?: AlertColor
+}
+
+/**
+ * The attributes for a message about the whole page or a whole form.
+ *
+ * The role is not set here, because it depends on when the message comes.
+ * If it is in the markup from the start, it should have no role. If it
+ * appears while the page is idle, it needs `role="status"`, or
+ * `role="alert"` if the user must stop.
+ *
+ * ```ts
+ * <div {...alert({ color: "warning" })}>
+ *   <p class={alert.title}>The application has not been sent</p>
+ * </div>
+ * ```
+ */
+export const alert = Object.assign(
+  ({ color }: AlertOptions = {}): AlertAttributes =>
+    attributes({
+      class: ALERT_CLASS,
+      "data-color": color,
+    }),
+  {
+    /** The class on the heading inside the message. */
+    title: ALERT_TITLE_CLASS,
+    colors: alertColors,
+    isColor: createGuard(alertColors),
+  },
+)

package/src/components/css/avatar/avatar.css

@@ -0,0 +1,96 @@
+@layer lotek {
+  .lt-avatar {
+    box-sizing: border-box;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    inline-size: var(--lt-avatar-size, var(--lt-spacing-10));
+    block-size: var(--lt-avatar-size, var(--lt-spacing-10));
+    overflow: hidden;
+    font-family: inherit;
+    font-size: var(--lt-font-size-s);
+    font-weight: var(--lt-font-weight-semibold);
+    line-height: 1;
+    color: var(--lt-color-accent-text);
+    background: var(--lt-color-accent-surface);
+    border-radius: 50%;
+    /* The image can be anything. The ring keeps the shape clear also against
+       a light area in the image. An inward `outline` and not a `box-shadow`:
+       an inset shadow is painted under the content, and the image covered
+       it completely. The longhands, since the shorthand with `solid` is
+       reserved for `--lt-focus-ring`. */
+    outline-width: 1px;
+    outline-style: solid;
+    outline-color: var(--lt-color-neutral-border-subtle);
+    outline-offset: -1px;
+  }
+
+  /* The ring above is an `outline` in the layer, and it beats the browser's
+     own focus indicator. An avatar that is a button, for example for a
+     profile menu, therefore gets its focus ring from here. */
+  .lt-avatar:focus-visible {
+    outline: var(--lt-focus-ring);
+    outline-offset: 2px;
+  }
+
+  .lt-avatar img {
+    inline-size: 100%;
+    block-size: 100%;
+    object-fit: cover;
+  }
+
+  .lt-avatar[data-size="small"] {
+    inline-size: var(--lt-spacing-6);
+    block-size: var(--lt-spacing-6);
+    font-size: var(--lt-font-size-xs);
+  }
+
+  .lt-avatar[data-size="large"] {
+    inline-size: var(--lt-spacing-16);
+    block-size: var(--lt-spacing-16);
+    font-size: var(--lt-font-size-l);
+  }
+
+  .lt-avatar[data-variant="square"] {
+    border-radius: var(--lt-avatar-radius, var(--lt-spacing-1));
+  }
+
+  /* Several profile pictures that overlap. The order is reversed in CSS: the
+     first element in the markup sits furthest to the right. */
+  .lt-avatar-stack {
+    display: inline-flex;
+    flex-direction: row-reverse;
+    justify-content: flex-end;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  .lt-avatar-stack > * + * {
+    margin-inline-end: var(
+      --lt-avatar-stack-overlap,
+      calc(var(--lt-spacing-2) * -1)
+    );
+  }
+
+  /* The inward ring comes from the `outline` above. The shadow outside
+     separates the overlapping pictures. An `outline` is painted after all
+     the content in the stacking context, so without a separate context per
+     avatar the ring of the one behind lay on top of the picture of the one
+     in front, like an arc through it. With `isolation` each avatar is
+     painted by itself, in order, and the one in front covers the one
+     behind, ring and all. */
+  .lt-avatar-stack .lt-avatar {
+    box-shadow: 0 0 0 2px var(--lt-color-neutral-canvas);
+    isolation: isolate;
+  }
+
+  /* The separate context also applies to the focus ring: an avatar that is a
+     button and sits behind another had its ring covered where the
+     neighbour overlaps. The one with focus is lifted above its neighbours
+     so the ring shows in full. */
+  .lt-avatar-stack .lt-avatar:focus-visible {
+    position: relative;
+    z-index: 1;
+  }
+}

package/src/components/css/avatar/avatar.ts

@@ -0,0 +1,57 @@
+import { attributes, createGuard } from "../shared.js"
+
+export const AVATAR_CLASS = "lt-avatar" as const
+/** Several profile pictures that overlap. */
+export const AVATAR_STACK_CLASS = "lt-avatar-stack" as const
+
+export const avatarSizes = ["small", "medium", "large"] as const
+export const avatarVariants = ["circle", "square"] as const
+
+export type AvatarSize = (typeof avatarSizes)[number]
+export type AvatarVariant = (typeof avatarVariants)[number]
+export type NonDefaultAvatarSize = Exclude<AvatarSize, "medium">
+export type NonDefaultAvatarVariant = Exclude<AvatarVariant, "circle">
+
+export type AvatarOptions = {
+  /** Size. Default: `medium`. */
+  size?: AvatarSize
+  /** Round or rounded square. Default: `circle`. */
+  variant?: AvatarVariant
+}
+
+export type AvatarAttributes = {
+  class: typeof AVATAR_CLASS
+  "data-size"?: NonDefaultAvatarSize
+  "data-variant"?: NonDefaultAvatarVariant
+}
+
+/**
+ * The attributes for a profile picture or initials.
+ *
+ * If the name is already next to it, the picture is decoration: set
+ * `aria-hidden="true"` on it, or the name is announced twice. If the
+ * picture stands alone, it must have a text that says who it is.
+ *
+ * ```ts
+ * <span {...avatar({ size: "small" })} aria-hidden="true">ON</span>
+ * ```
+ */
+export const avatar = Object.assign(
+  ({
+    size = "medium",
+    variant = "circle",
+  }: AvatarOptions = {}): AvatarAttributes =>
+    attributes({
+      class: AVATAR_CLASS,
+      "data-size": size === "medium" ? undefined : size,
+      "data-variant": variant === "circle" ? undefined : variant,
+    }),
+  {
+    /** The class on the list of overlapping profile pictures. */
+    stack: AVATAR_STACK_CLASS,
+    sizes: avatarSizes,
+    isSize: createGuard(avatarSizes),
+    variants: avatarVariants,
+    isVariant: createGuard(avatarVariants),
+  },
+)

package/src/components/css/badge/badge.css

@@ -0,0 +1,42 @@
+@layer lotek {
+  .lt-badge {
+    /* The design system cannot assume the consumer has a CSS reset. Without
+       border-box, padding and border are added outside the width, and the
+       element becomes wider than the box it sits in. */
+    box-sizing: border-box;
+
+    display: inline-flex;
+    align-items: center;
+    gap: var(--lt-spacing-1);
+    padding: var(--lt-badge-padding, var(--lt-spacing-0-5) var(--lt-spacing-2));
+    font-family: inherit;
+    font-size: var(--lt-font-size-xs);
+    font-weight: var(--lt-font-weight-semibold);
+    line-height: var(--lt-line-height-default);
+    border-radius: var(--lt-badge-radius, var(--lt-spacing-4));
+    white-space: nowrap;
+    user-select: none;
+    background: var(--lt-color-accent-surface);
+    color: var(--lt-color-accent-text);
+  }
+
+  .lt-badge[data-color="success"] {
+    background: var(--lt-color-success-surface);
+    color: var(--lt-color-success-text);
+  }
+
+  .lt-badge[data-color="warning"] {
+    background: var(--lt-color-warning-surface);
+    color: var(--lt-color-warning-text);
+  }
+
+  .lt-badge[data-color="danger"] {
+    background: var(--lt-color-danger-surface);
+    color: var(--lt-color-danger-text);
+  }
+
+  .lt-badge[data-color="neutral"] {
+    background: var(--lt-color-neutral-surface);
+    color: var(--lt-color-neutral-text);
+  }
+}

package/src/components/css/badge/badge.ts

@@ -0,0 +1,43 @@
+import { attributes, createGuard } from "../shared.js"
+
+export const BADGE_CLASS = "lt-badge" as const
+
+export const badgeColors = [
+  "info",
+  "success",
+  "warning",
+  "danger",
+  "neutral",
+] as const
+
+export type BadgeColor = (typeof badgeColors)[number]
+export type NonInfoBadgeColor = Exclude<BadgeColor, "info">
+
+export type BadgeOptions = {
+  /** What the status means. Default: `info`. */
+  color?: BadgeColor
+}
+
+export type BadgeAttributes = {
+  class: typeof BADGE_CLASS
+  "data-color"?: NonInfoBadgeColor
+}
+
+/**
+ * The attributes for a status badge.
+ *
+ * ```ts
+ * <span {...badge({ color: "success" })}>Approved</span>
+ * ```
+ */
+export const badge = Object.assign(
+  ({ color = "info" }: BadgeOptions = {}): BadgeAttributes =>
+    attributes({
+      class: BADGE_CLASS,
+      "data-color": color === "info" ? undefined : color,
+    }),
+  {
+    colors: badgeColors,
+    isColor: createGuard(badgeColors),
+  },
+)

package/src/components/css/breadcrumbs/breadcrumbs.css

@@ -0,0 +1,62 @@
+@layer lotek {
+  .lt-breadcrumbs {
+    box-sizing: border-box;
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--lt-breadcrumbs-gap, var(--lt-spacing-2));
+    margin: 0;
+    padding: 0;
+    list-style: none;
+    font-family: inherit;
+    font-size: var(--lt-font-size-s);
+    line-height: var(--lt-line-height-default);
+    color: var(--lt-color-neutral-text-subtle);
+  }
+
+  .lt-breadcrumbs li {
+    display: flex;
+    align-items: center;
+    gap: var(--lt-breadcrumbs-gap, var(--lt-spacing-2));
+  }
+
+  /* The separator is decoration. Generated content is still announced, so
+     it gets an empty alternative text after the slash. Browsers that do not
+     know that form discard the whole declaration, and the separator
+     disappeared: so it sits behind `@supports`, and those browsers keep the
+     slash without silencing it. */
+  .lt-breadcrumbs li + li::before {
+    content: "/";
+    color: var(--lt-color-neutral-text-subtle);
+  }
+
+  @supports (content: "/" / "") {
+    .lt-breadcrumbs li + li::before {
+      content: "/" / "";
+    }
+  }
+
+  .lt-breadcrumbs a {
+    color: var(--lt-color-accent-text);
+    text-decoration: underline;
+    text-underline-offset: 0.14em;
+  }
+
+  /* The current step is excluded. Without `:not()` this rule won on
+     specificity over `[aria-current="page"]`, and the last step turned blue
+     under the mouse even though it is not a place to go. */
+  .lt-breadcrumbs a:not([aria-current="page"]):hover {
+    color: var(--lt-color-accent-text-strong);
+  }
+
+  .lt-breadcrumbs a:focus-visible {
+    outline: var(--lt-focus-ring);
+    outline-offset: 2px;
+  }
+
+  .lt-breadcrumbs [aria-current="page"] {
+    color: var(--lt-color-neutral-text-strong);
+    font-weight: var(--lt-font-weight-semibold);
+    text-decoration: none;
+  }
+}

package/src/components/css/breadcrumbs/breadcrumbs.ts

@@ -0,0 +1,30 @@
+import { attributes } from "../shared.js"
+
+export const BREADCRUMBS_CLASS = "lt-breadcrumbs" as const
+
+export type BreadcrumbsAttributes = {
+  class: typeof BREADCRUMBS_CLASS
+}
+
+/**
+ * The attributes for a breadcrumb trail.
+ *
+ * The class goes on an `<ol>` inside a `<nav>` with a text that says what
+ * the navigation is, for example `aria-label="You are here"`. The order
+ * matters, so the list must be numbered even though the numbers are not
+ * shown.
+ *
+ * The separator between the steps is added with CSS. Had it been in the
+ * markup, screen readers would have read "slash" between every step.
+ *
+ * ```ts
+ * <nav aria-label="You are here">
+ *   <ol {...breadcrumbs()}>
+ *     <li><a href="/">Home</a></li>
+ *     <li><a href="/cases" aria-current="page">My cases</a></li>
+ *   </ol>
+ * </nav>
+ * ```
+ */
+export const breadcrumbs = (): BreadcrumbsAttributes =>
+  attributes({ class: BREADCRUMBS_CLASS })

package/src/components/css/button/button.css

@@ -0,0 +1,128 @@
+@layer lotek {
+  .lt-button {
+    /* The design system cannot assume the consumer has a CSS reset. Without
+       border-box, padding and border are added outside the width, and the
+       element becomes wider than the box it sits in. */
+    box-sizing: border-box;
+
+    display: inline-flex;
+    align-items: center;
+    gap: var(--lt-spacing-2);
+    padding: var(--lt-button-padding, var(--lt-spacing-2) var(--lt-spacing-4));
+    font-family: inherit;
+    font-size: var(--lt-font-size-m);
+    /* Weight, line height and border width are shape, and shape is read from
+       a component variable with the token value as the fallback. A theme
+       that wants bold buttons with a thick border, as some design systems
+       have, sets them without overriding a single selector. */
+    font-weight: var(--lt-button-font-weight, var(--lt-font-weight-medium));
+    line-height: var(--lt-button-line-height, var(--lt-line-height-default));
+    border: var(--lt-button-border-width, 1px) solid var(--lt-color-accent-fill);
+    border-radius: var(--lt-button-radius, var(--lt-spacing-1));
+    background: var(--lt-color-accent-fill);
+    color: var(--lt-color-accent-content);
+    cursor: pointer;
+    text-decoration: none;
+    user-select: none;
+
+    /* The text may wrap. With `white-space: nowrap` a button with a long
+       label burst its box on a phone, and then the whole page scrolls
+       sideways. The button must never become wider than the room it gets.
+
+       `normal` is explicit because `white-space` is inherited: a consumer
+       with `nowrap` on something around it would otherwise get the problem
+       back. Checked in Chromium, `text-wrap: balance` alone is enough, since
+       it sets `text-wrap-mode: wrap` and so beats the inherited value, but
+       the explicit line also applies where `text-wrap` is not supported. */
+    white-space: normal;
+    max-inline-size: 100%;
+    text-align: center;
+    text-wrap: balance;
+  }
+
+  /* Hover moves away from `content`: darker in the light theme, lighter in
+     the dark one. `text` is the role that sits there, and since the
+     lightness belongs to the role and not the brand colour, the text on the
+     button keeps its contrast whatever the hue. `content on text` is a
+     promise in the contract. */
+  .lt-button:hover {
+    background: var(--lt-color-accent-text);
+    border-color: var(--lt-color-accent-text);
+  }
+
+  .lt-button:focus-visible {
+    outline: var(--lt-focus-ring);
+    outline-offset: 2px;
+  }
+
+  /* Secondary: outline, transparent background */
+  .lt-button[data-variant="secondary"] {
+    background: transparent;
+    color: var(--lt-color-accent-text);
+    border-color: var(--lt-color-accent-border);
+  }
+
+  .lt-button[data-variant="secondary"]:hover:not(
+    :disabled,
+    [aria-disabled="true"]
+  ) {
+    background: var(--lt-color-accent-surface);
+  }
+
+  /* Ghost: no border, no background */
+  .lt-button[data-variant="ghost"] {
+    background: transparent;
+    color: var(--lt-color-accent-text);
+    border-color: transparent;
+  }
+
+  .lt-button[data-variant="ghost"]:hover:not(
+    :disabled,
+    [aria-disabled="true"]
+  ) {
+    background: var(--lt-color-accent-surface);
+  }
+
+  /* Danger */
+  .lt-button[data-variant="danger"] {
+    background: var(--lt-color-danger-surface);
+    color: var(--lt-color-danger-text);
+    border-color: var(--lt-color-danger-text);
+  }
+
+  .lt-button[data-variant="danger"]:hover:not(
+    :disabled,
+    [aria-disabled="true"]
+  ) {
+    background: var(--lt-color-danger-fill);
+    border-color: var(--lt-color-danger-fill);
+    color: var(--lt-color-danger-content);
+  }
+
+  /*
+   * Disabled comes last.
+   *
+   * When the rule was above the variants, they won on order: a disabled
+   * secondary, ghost or danger button looked like an active one. The
+   * variants' hover is more specific than this wherever it stands, and a
+   * disabled button is still matched by `:hover`. So each of them excludes
+   * the disabled state itself.
+   */
+  .lt-button:disabled,
+  .lt-button[aria-disabled="true"] {
+    background: 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-button[aria-disabled="true"] {
+    pointer-events: none;
+  }
+}

package/src/components/css/button/button.ts

@@ -0,0 +1,44 @@
+import { attributes, createGuard } from "../shared.js"
+
+export const BUTTON_CLASS = "lt-button" as const
+
+export const buttonVariants = [
+  "primary",
+  "secondary",
+  "ghost",
+  "danger",
+] as const
+
+export type ButtonVariant = (typeof buttonVariants)[number]
+export type NonPrimaryButtonVariant = Exclude<ButtonVariant, "primary">
+
+export type ButtonOptions = {
+  /** How weighty the action is. Default: `primary`. */
+  variant?: ButtonVariant
+}
+
+export type ButtonAttributes = {
+  class: typeof BUTTON_CLASS
+  "data-variant"?: NonPrimaryButtonVariant
+}
+
+/**
+ * The attributes for a button.
+ *
+ * ```ts
+ * <button {...button({ variant: "secondary" })}>Save draft</button>
+ * ```
+ */
+export const button = Object.assign(
+  ({ variant = "primary" }: ButtonOptions = {}): ButtonAttributes =>
+    attributes({
+      class: BUTTON_CLASS,
+      "data-variant": variant === "primary" ? undefined : variant,
+    }),
+  {
+    /** The valid variants, for lookup and branching. */
+    variants: buttonVariants,
+    /** Checks whether a string from outside is a valid variant. */
+    isVariant: createGuard(buttonVariants),
+  },
+)

package/src/components/css/card/card.css

@@ -0,0 +1,65 @@
+@layer lotek {
+  .lt-card {
+    box-sizing: border-box;
+    display: flex;
+    flex-direction: column;
+    gap: var(--lt-spacing-2);
+    padding: var(--lt-card-padding, var(--lt-spacing-4));
+    /* The whole `font`, not just the family: a card that is a <button>
+       otherwise inherited the browser's button font, 13 pixels. */
+    font: inherit;
+    color: var(--lt-color-neutral-text-strong);
+    background: var(--lt-color-neutral-canvas);
+    border: 1px solid var(--lt-color-neutral-border-subtle);
+    border-radius: var(--lt-card-radius, var(--lt-spacing-2));
+  }
+
+  /*
+   * The card is a flex column, and a child is then stretched to the full
+   * width. A badge, a label, a button or a link should keep its natural
+   * width, or "Approved" became a band across the card. The rule asks for
+   * the element type and not the class: if other components' classes were
+   * here, the vocabulary would count them as the card's. Paragraphs, lists
+   * and images stretch as before.
+   */
+  .lt-card > :where(span, a, button) {
+    align-self: flex-start;
+  }
+
+  .lt-card__title {
+    margin: 0;
+    font-size: var(--lt-font-size-l);
+    font-weight: var(--lt-font-weight-semibold);
+    line-height: var(--lt-line-height-compact);
+  }
+
+  /* Only the element counts, so a class on the paragraph wins: `lt-paragraph`
+     with its line height, `lt-help-text`, `lt-error-text` and an
+     `lt-card__title` that is a <p>. With `.lt-card p` the card beat them. */
+  :where(.lt-card) p {
+    margin: 0;
+    line-height: var(--lt-line-height-article);
+  }
+
+  .lt-card[data-variant="filled"] {
+    background: var(--lt-color-neutral-surface);
+    border-color: transparent;
+  }
+
+  /* The whole card is clickable. The element is then an <a> or a <button>,
+     and the focus ring comes from there, not from here. */
+  .lt-card[data-interactive] {
+    text-align: start;
+    text-decoration: none;
+    cursor: pointer;
+  }
+
+  .lt-card[data-interactive]:hover {
+    border-color: var(--lt-color-accent-border);
+  }
+
+  .lt-card[data-interactive]:focus-visible {
+    outline: var(--lt-focus-ring);
+    outline-offset: 2px;
+  }
+}

package/src/components/css/card/card.ts

@@ -0,0 +1,50 @@
+import { attributes, createGuard } from "../shared.js"
+
+export const CARD_CLASS = "lt-card" as const
+/** The heading inside the card. */
+export const CARD_TITLE_CLASS = "lt-card__title" as const
+
+export const cardVariants = ["outline", "filled"] as const
+
+export type CardVariant = (typeof cardVariants)[number]
+export type NonDefaultCardVariant = Exclude<CardVariant, "outline">
+
+export type CardOptions = {
+  /** Surface or outline. Default: `outline`. */
+  variant?: CardVariant
+  /** The whole card is clickable. Use only on `<a>` or `<button>`. */
+  interactive?: boolean
+}
+
+export type CardAttributes = {
+  class: typeof CARD_CLASS
+  "data-variant"?: NonDefaultCardVariant
+  "data-interactive"?: ""
+}
+
+/**
+ * The attributes for a card.
+ *
+ * `interactive` gives hover and a focus ring, but makes nothing clickable by
+ * itself. If the whole card should be pressable, the element must be an
+ * `<a>` or a `<button>`. A `<div>` with a click listener can neither be
+ * reached with the keyboard nor be announced as something to press.
+ *
+ * ```ts
+ * <a {...card({ interactive: true })} href="/case/481">…</a>
+ * ```
+ */
+export const card = Object.assign(
+  ({ variant = "outline", interactive }: CardOptions = {}): CardAttributes =>
+    attributes({
+      class: CARD_CLASS,
+      "data-variant": variant === "outline" ? undefined : variant,
+      "data-interactive": interactive ? ("" as const) : undefined,
+    }),
+  {
+    /** The class on the heading inside the card. */
+    title: CARD_TITLE_CLASS,
+    variants: cardVariants,
+    isVariant: createGuard(cardVariants),
+  },
+)