@lo-tek/interfaces 0.0.0 → 0.37.0

package/src/tokens/boundary.css

@@ -0,0 +1,104 @@
+/*
+ * The boundary towards a host page: `data-lt-boundary` on the root element of
+ * a component embedded in a page you do not control.
+ *
+ * This file is deliberately outside `@layer lotek`, the only one in the
+ * package. Unlayered styles beat every layer, so the host's
+ * `button { background: none }` removes the background from `.lt-button`.
+ * `revert-layer` in an unlayered rule ignores every unlayered rule for the
+ * element and falls back to the layers. Then `@layer lotek` applies again,
+ * and where no layer says anything, the browser's default rules apply.
+ *
+ * `all` does not touch custom properties, so `--lt-*` works as before. The
+ * root itself is not matched: it is left to the consumer, and inheritance
+ * from the host, such as the font, comes in through it.
+ *
+ * The attribute is written twice for specificity. With one, the rule was
+ * (0,1,0) and lost to common resets such as `button:not(:disabled)`,
+ * `a:hover` and `input[type="text"]`, which are all (0,1,1). Source order
+ * cannot decide it, since the host's stylesheet is often loaded after this
+ * one. A host rule with (0,2,0) wins if it comes after this one, one with
+ * more always wins, and so does `!important`.
+ *
+ * The pseudo-elements are the ones LO-TEK styles, and the ones normalize
+ * styles, since it is the most common reset a host has. Each has a rule of
+ * its own. A pseudo-element the browser does not recognise makes the whole
+ * rule invalid, and Firefox drops a list with `::picker(select)` in it, so
+ * the boundary would have disappeared there.
+ */
+
+[data-lt-boundary][data-lt-boundary] * {
+  all: revert-layer;
+}
+
+[data-lt-boundary][data-lt-boundary] *::before {
+  all: revert-layer;
+}
+
+[data-lt-boundary][data-lt-boundary] *::after {
+  all: revert-layer;
+}
+
+[data-lt-boundary][data-lt-boundary] *::marker {
+  all: revert-layer;
+}
+
+[data-lt-boundary][data-lt-boundary] *::placeholder {
+  all: revert-layer;
+}
+
+[data-lt-boundary][data-lt-boundary] *::backdrop {
+  all: revert-layer;
+}
+
+[data-lt-boundary][data-lt-boundary] *::file-selector-button {
+  all: revert-layer;
+}
+
+[data-lt-boundary][data-lt-boundary] *::checkmark {
+  all: revert-layer;
+}
+
+[data-lt-boundary][data-lt-boundary] *::picker-icon {
+  all: revert-layer;
+}
+
+[data-lt-boundary][data-lt-boundary] *::picker(select) {
+  all: revert-layer;
+}
+
+[data-lt-boundary][data-lt-boundary] *::-webkit-details-marker {
+  all: revert-layer;
+}
+
+[data-lt-boundary][data-lt-boundary] *::-webkit-search-cancel-button {
+  all: revert-layer;
+}
+
+[data-lt-boundary][data-lt-boundary] *::-webkit-search-decoration {
+  all: revert-layer;
+}
+
+[data-lt-boundary][data-lt-boundary] *::-webkit-inner-spin-button {
+  all: revert-layer;
+}
+
+[data-lt-boundary][data-lt-boundary] *::-webkit-outer-spin-button {
+  all: revert-layer;
+}
+
+[data-lt-boundary][data-lt-boundary] *::-webkit-calendar-picker-indicator {
+  all: revert-layer;
+}
+
+[data-lt-boundary][data-lt-boundary] *::-webkit-progress-bar {
+  all: revert-layer;
+}
+
+[data-lt-boundary][data-lt-boundary] *::-webkit-progress-value {
+  all: revert-layer;
+}
+
+[data-lt-boundary][data-lt-boundary] *::-moz-progress-bar {
+  all: revert-layer;
+}

package/src/tokens/color-contract.json

@@ -0,0 +1,231 @@
+{
+  "$comment": "The colour contract: the families, LO-TEK's brand colours, the lightness and saturation per role, the layers only the neutral family has, the contrast requirements and the promises. Read by the core (core/src/theme/) and by the scripts in interfaces/. A promise with own: true is checked against the family's own role, otherwise against the layer in the neutral family.",
+  "families": [
+    "accent",
+    "visited",
+    "brand1",
+    "brand2",
+    "brand3",
+    "neutral",
+    "danger",
+    "warning",
+    "success"
+  ],
+  "brands": {
+    "accent": "#1362ae",
+    "visited": "#5a77a8",
+    "brand1": "#0d7a5f",
+    "brand2": "#5b3fa0",
+    "brand3": "#b04c5c",
+    "neutral": "#24272b",
+    "danger": "#a82e39",
+    "warning": "#896508",
+    "success": "#316f2a"
+  },
+  "roles": {
+    "surface": {
+      "lightness": {
+        "light": 0.96,
+        "dark": 0.26
+      },
+      "chroma": 0.22
+    },
+    "borderSubtle": {
+      "lightness": {
+        "light": 0.88,
+        "dark": 0.34
+      },
+      "chroma": 0.35
+    },
+    "border": {
+      "lightness": {
+        "light": 0.575,
+        "dark": 0.625
+      },
+      "chroma": 0.55
+    },
+    "borderStrong": {
+      "lightness": {
+        "light": 0.48,
+        "dark": 0.74
+      },
+      "chroma": 0.6
+    },
+    "fill": {
+      "lightness": {
+        "light": 0.53,
+        "dark": 0.65
+      },
+      "chroma": 1
+    },
+    "text": {
+      "lightness": {
+        "light": 0.42,
+        "dark": 0.82
+      },
+      "chroma": 0.85
+    },
+    "textStrong": {
+      "lightness": {
+        "light": 0.28,
+        "dark": 0.93
+      },
+      "chroma": 0.5
+    },
+    "textSubtle": {
+      "lightness": {
+        "light": 0.485,
+        "dark": 0.73
+      },
+      "chroma": 0.7
+    },
+    "content": {
+      "lightness": {
+        "light": 0.99,
+        "dark": 0.16
+      },
+      "chroma": 0.04
+    }
+  },
+  "layers": {
+    "canvas": {
+      "lightness": {
+        "light": 1,
+        "dark": 0.18
+      },
+      "chroma": 0.08
+    },
+    "raised": {
+      "lightness": {
+        "light": 0.92,
+        "dark": 0.32
+      },
+      "chroma": 0.12
+    }
+  },
+  "requirements": {
+    "text": 4.6,
+    "graphic": 3.1
+  },
+  "promises": [
+    {
+      "name": "text on canvas",
+      "foreground": "text",
+      "background": "canvas",
+      "own": false,
+      "requirement": "text"
+    },
+    {
+      "name": "text on surface",
+      "foreground": "text",
+      "background": "surface",
+      "own": false,
+      "requirement": "text"
+    },
+    {
+      "name": "text on raised",
+      "foreground": "text",
+      "background": "raised",
+      "own": false,
+      "requirement": "text"
+    },
+    {
+      "name": "text on its own surface",
+      "foreground": "text",
+      "background": "surface",
+      "own": true,
+      "requirement": "text"
+    },
+    {
+      "name": "textStrong on canvas",
+      "foreground": "textStrong",
+      "background": "canvas",
+      "own": false,
+      "requirement": "text"
+    },
+    {
+      "name": "textStrong on surface",
+      "foreground": "textStrong",
+      "background": "surface",
+      "own": false,
+      "requirement": "text"
+    },
+    {
+      "name": "textStrong on raised",
+      "foreground": "textStrong",
+      "background": "raised",
+      "own": false,
+      "requirement": "text"
+    },
+    {
+      "name": "textSubtle on canvas",
+      "foreground": "textSubtle",
+      "background": "canvas",
+      "own": false,
+      "requirement": "text"
+    },
+    {
+      "name": "textSubtle on surface",
+      "foreground": "textSubtle",
+      "background": "surface",
+      "own": false,
+      "requirement": "text"
+    },
+    {
+      "name": "textSubtle on raised",
+      "foreground": "textSubtle",
+      "background": "raised",
+      "own": false,
+      "requirement": "text"
+    },
+    {
+      "name": "border on canvas",
+      "foreground": "border",
+      "background": "canvas",
+      "own": false,
+      "requirement": "graphic"
+    },
+    {
+      "name": "border on raised",
+      "foreground": "border",
+      "background": "raised",
+      "own": false,
+      "requirement": "graphic"
+    },
+    {
+      "name": "border on its own surface",
+      "foreground": "border",
+      "background": "surface",
+      "own": true,
+      "requirement": "graphic"
+    },
+    {
+      "name": "fill on canvas",
+      "foreground": "fill",
+      "background": "canvas",
+      "own": false,
+      "requirement": "graphic"
+    },
+    {
+      "name": "fill on raised",
+      "foreground": "fill",
+      "background": "raised",
+      "own": false,
+      "requirement": "graphic"
+    },
+    {
+      "name": "content on top of fill",
+      "foreground": "content",
+      "background": "fill",
+      "own": true,
+      "requirement": "text"
+    },
+    {
+      "name": "content on top of text",
+      "foreground": "content",
+      "background": "text",
+      "own": true,
+      "requirement": "text"
+    }
+  ]
+}

package/src/tokens/color.ts

@@ -0,0 +1,150 @@
+/**
+ * Colour arithmetic: sRGB, OKLCH and contrast, as `@lo-tek/interfaces/color`.
+ *
+ * The theme is computed in the core, written in Rust (`core/src/theme/color.rs`).
+ * These five calculations are the same, for anyone who wants to compute colours
+ * in JavaScript, including in the browser. The tests that check the colours a
+ * browser actually paints use them too, and so check the core against an
+ * independent implementation of the formula.
+ *
+ * The arithmetic is done in OKLCH, not HSL. In HSL, lightness means something
+ * different for each hue: `hsl(60 100% 50%)` is bright yellow and
+ * `hsl(240 100% 50%)` is almost black, with the same numbers. In OKLCH the
+ * lightness is the same perceived lightness whatever the hue, so the contract
+ * can set one lightness per role and apply it to every colour.
+ *
+ * Contrast is computed with the WCAG 2.1 formula, the same one the tests use,
+ * so the contract and the check agree.
+ */
+
+export type Rgb = { r: number; g: number; b: number }
+export type Oklch = { l: number; c: number; h: number }
+
+/** Reads `#rrggbb` or `#rgb`. */
+export function parseHex(hex: string): Rgb {
+  const clean = hex.trim().replace(/^#/, "")
+  const full =
+    clean.length === 3
+      ? clean
+          .split("")
+          .map((char) => char + char)
+          .join("")
+      : clean
+
+  if (!/^[0-9a-fA-F]{6}$/.test(full)) {
+    throw new Error(`"${hex}" is not a valid hexadecimal colour`)
+  }
+
+  return {
+    r: Number.parseInt(full.slice(0, 2), 16),
+    g: Number.parseInt(full.slice(2, 4), 16),
+    b: Number.parseInt(full.slice(4, 6), 16),
+  }
+}
+
+export function toHex({ r, g, b }: Rgb): string {
+  const channel = (value: number) =>
+    Math.round(Math.min(255, Math.max(0, value)))
+      .toString(16)
+      .padStart(2, "0")
+
+  return `#${channel(r)}${channel(g)}${channel(b)}`
+}
+
+function toLinear(channel: number): number {
+  const c = channel / 255
+  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4
+}
+
+function fromLinear(channel: number): number {
+  const c =
+    channel <= 0.0031308
+      ? channel * 12.92
+      : 1.055 * channel ** (1 / 2.4) - 0.055
+  return c * 255
+}
+
+export function rgbToOklch({ r, g, b }: Rgb): Oklch {
+  const lr = toLinear(r)
+  const lg = toLinear(g)
+  const lb = toLinear(b)
+
+  const l = 0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb
+  const m = 0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb
+  const s = 0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb
+
+  const l_ = Math.cbrt(l)
+  const m_ = Math.cbrt(m)
+  const s_ = Math.cbrt(s)
+
+  const lightness = 0.2104542553 * l_ + 0.793617785 * m_ - 0.0040720468 * s_
+  const a = 1.9779984951 * l_ - 2.428592205 * m_ + 0.4505937099 * s_
+  const bb = 0.0259040371 * l_ + 0.7827717662 * m_ - 0.808675766 * s_
+
+  return {
+    l: lightness,
+    c: Math.hypot(a, bb),
+    h: (Math.atan2(bb, a) * 180) / Math.PI,
+  }
+}
+
+function oklchToRgbRaw({ l, c, h }: Oklch): Rgb {
+  const rad = (h * Math.PI) / 180
+  const a = c * Math.cos(rad)
+  const b = c * Math.sin(rad)
+
+  const l_ = l + 0.3963377774 * a + 0.2158037573 * b
+  const m_ = l - 0.1055613458 * a - 0.0638541728 * b
+  const s_ = l - 0.0894841775 * a - 1.291485548 * b
+
+  const lr = l_ ** 3
+  const mr = m_ ** 3
+  const sr = s_ ** 3
+
+  return {
+    r: fromLinear(4.0767416621 * lr - 3.3077115913 * mr + 0.2309699292 * sr),
+    g: fromLinear(-1.2684380046 * lr + 2.6097574011 * mr - 0.3413193965 * sr),
+    b: fromLinear(-0.0041960863 * lr - 0.7034186147 * mr + 1.707614701 * sr),
+  }
+}
+
+function outside({ r, g, b }: Rgb): boolean {
+  const margin = 0.5
+  return [r, g, b].some(
+    (channel) => channel < -margin || channel > 255 + margin,
+  )
+}
+
+/**
+ * Converts an OKLCH colour to an rgb colour a screen can show.
+ *
+ * Not every combination of lightness and chroma can be shown in sRGB. If the
+ * colour falls outside, the chroma is reduced until it is inside, instead of
+ * clipping each channel separately. Clipping would change the hue.
+ */
+export function oklchToRgb(color: Oklch): Rgb {
+  const attempt = oklchToRgbRaw(color)
+  if (!outside(attempt)) return attempt
+
+  let low = 0
+  let high = color.c
+
+  for (let i = 0; i < 24; i += 1) {
+    const middle = (low + high) / 2
+    if (outside(oklchToRgbRaw({ ...color, c: middle }))) high = middle
+    else low = middle
+  }
+
+  return oklchToRgbRaw({ ...color, c: low })
+}
+
+function luminance({ r, g, b }: Rgb): number {
+  return 0.2126 * toLinear(r) + 0.7152 * toLinear(g) + 0.0722 * toLinear(b)
+}
+
+/** The contrast ratio between two colours, as WCAG 2.1 computes it. */
+export function contrastRatio(a: Rgb, b: Rgb): number {
+  const la = luminance(a)
+  const lb = luminance(b)
+  return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05)
+}

package/src/tokens/contract.ts

@@ -0,0 +1,24 @@
+/**
+ * The colour contract, as `@lo-tek/interfaces/contract`: what each role is,
+ * and what it promises.
+ *
+ * One colour layer, not two. A colour is a point in a matrix of **family**
+ * (what it means) and **role** (what it does), and every family has the same
+ * roles. The hue comes from the consumer, the lightness from the role, and so
+ * the contrast is guaranteed by construction rather than by a check
+ * afterwards.
+ *
+ * The numbers are in `color-contract.json`, which the core reads, and the
+ * arithmetic happens there. Here is the data, for anyone who wants to read it.
+ * A theme is built with `buildTheme` from `@lo-tek/interfaces/theme`, and a
+ * hand-written theme is checked with `inspectTheme` from
+ * `@lo-tek/interfaces/theme-check`.
+ */
+
+export {
+  type Appearance,
+  NEUTRAL_LAYERS,
+  REQUIREMENT,
+  ROLES,
+  type Role,
+} from "./matrix-cells.js"