@raylang/elements 0.0.0-stage → 0.4.0

package/components/toggle/toggle.js

@@ -0,0 +1,130 @@
+// <ray-toggle>: a two-state button (aria-pressed), like shadcn's Toggle — bold
+// in a toolbar, "mute", "favorite". A RayButton, so sizes, radius, color,
+// icons in the left/right slots and ray-button-group all work.
+//
+// The variant describes how "on" looks; "off" is always neutral, so the two
+// states differ by more than color (WCAG 1.4.1):
+//   subtle  — off: transparent; on: tinted fill (default)
+//   outline — off: neutral border; on: colored border + tint
+//   light   — off: muted fill; on: colored tint
+//   filled  — off: neutral surface with border; on: solid color
+//   raised  — off: a neutral key standing up; on: latched down and lit
+// Button variants left out: default (no "on" look of its own), transparent
+// (would change only the text color) and gradient (a second filled).
+
+import { css, define } from "../../core/core.js";
+import { RayButton } from "../button/button.js";
+
+const styles = css`
+  :host([square]) .button { width: var(--_h); padding: 0; }
+  :host([square]) .label { font-size: calc(var(--_fs) * 1.15); }
+  ::slotted(svg) { width: 1.15em; height: 1.15em; }
+
+  /* Base of the drawn variants, at the specificity of one class so each
+     variant's own off look below wins. */
+  .button:where([data-toggle]:not([data-toggle="raised"])) { color: var(--ray-foreground); background: transparent; }
+  .button[data-toggle] ::slotted(ray-icon), .button[data-toggle] ::slotted(svg) { opacity: 0.85; }
+  .button[data-toggle][aria-pressed="true"] ::slotted(*) { opacity: 1; }
+
+  /* subtle */
+  .button[data-toggle="subtle"]:not([data-disabled]):hover { background: var(--ray-default-hover); }
+  .button[data-toggle="subtle"][aria-pressed="true"] { background: var(--_light); color: var(--_light-color); }
+  .button[data-toggle="subtle"][aria-pressed="true"]:not([data-disabled]):hover { background: var(--_light-hover); }
+
+  /* outline */
+  .button[data-toggle="outline"] { border-color: var(--ray-border); }
+  .button[data-toggle="outline"]:not([data-disabled]):hover { background: var(--ray-default-hover); }
+  .button[data-toggle="outline"][aria-pressed="true"] { border-color: color-mix(in srgb, var(--_outline) 65%, var(--ray-border)); background: var(--_light); color: var(--_light-color); }
+  .button[data-toggle="outline"][aria-pressed="true"]:not([data-disabled]):hover { background: var(--_light-hover); }
+
+  /* light */
+  .button[data-toggle="light"] { background: var(--ray-muted); }
+  .button[data-toggle="light"]:not([data-disabled]):hover { background: var(--ray-default-hover); }
+  .button[data-toggle="light"][aria-pressed="true"] { background: var(--_light); color: var(--_light-color); }
+  .button[data-toggle="light"][aria-pressed="true"]:not([data-disabled]):hover { background: var(--_light-hover); }
+
+  /* filled */
+  .button[data-toggle="filled"] { background: var(--ray-default); border-color: var(--ray-border); }
+  .button[data-toggle="filled"]:not([data-disabled]):hover { background: var(--ray-default-hover); }
+  .button[data-toggle="filled"][aria-pressed="true"] { background: var(--_filled); color: var(--_contrast); border-color: transparent; }
+  .button[data-toggle="filled"][aria-pressed="true"]:not([data-disabled]):hover { background: var(--_filled-hover); }
+
+  /* Disabled keeps showing its state, dimmed. */
+  .button[data-toggle][data-disabled]:not([data-toggle="raised"]) { opacity: 0.5; }
+
+  /* raised: off is an unlit neutral key (ray-kbd's colors) ... */
+  .button[data-toggle="raised"]:not([aria-pressed="true"]) {
+    --_face: var(--ray-raised);
+    --_face-text: var(--ray-foreground);
+    --_rim: light-dark(color-mix(in srgb, var(--_face), black 12%), color-mix(in srgb, var(--_face) 82%, var(--ray-background)));
+    --_edge: light-dark(color-mix(in srgb, var(--_face), black 24%), color-mix(in srgb, var(--_face) 62%, var(--ray-background)));
+    /* ray-kbd's top highlight: a strong one reads as an edge on top in dark. */
+    box-shadow:
+      0 var(--_depth) 0 var(--_edge),
+      0 calc(var(--_depth) + 1px) 6px -1px rgb(0 0 0 / 0.28),
+      inset 0 1px 0 light-dark(rgb(255 255 255 / 0.7), rgb(255 255 255 / 0.07));
+  }
+  /* ... and on stays down, lit in its color, like a latching switch. */
+  .button[data-toggle="raised"][aria-pressed="true"]:not([data-disabled]) {
+    transform: translateY(var(--_depth));
+    /* Sunk: shaded under the top rim. In dark a touch deeper (a light
+       shadow does not show on the color there); light keeps the original. */
+    box-shadow:
+      0 0 0 var(--_edge),
+      inset 0 1px 3px light-dark(rgb(0 0 0 / 0.28), rgb(0 0 0 / 0.4));
+    border-top-color: light-dark(var(--_rim), color-mix(in srgb, var(--_face), black 24%));
+  }
+`;
+
+const VARIANTS = ["subtle", "outline", "light", "filled", "raised"];
+
+export class RayToggle extends RayButton {
+  static properties = {
+    ...RayButton.properties,
+    variant: { type: String, reflect: true, default: "subtle" },
+    pressed: { type: Boolean, reflect: true },
+    square: { type: Boolean, reflect: true },
+    label: { type: String, reflect: true },
+  };
+  static styles = [...RayButton.styles, styles];
+
+  #initial = null;
+
+  constructor() {
+    super();
+    // Clicks reach the host after the inner button's own handler, which stops
+    // them while disabled or loading.
+    this.addEventListener("click", () => {
+      if (this.disabled || this.loading || this._fieldsetDisabled) return;
+      this.pressed = !this.pressed;
+      this.dispatchEvent(new Event("change", { bubbles: true }));
+    });
+  }
+
+  connectedCallback() {
+    this.#initial ??= this.hasAttribute("pressed");
+    super.connectedCallback();
+  }
+
+  formResetCallback() {
+    this.pressed = this.#initial ?? false;
+  }
+
+  update() {
+    super.update();
+    const el = this._el;
+    const variant = VARIANTS.includes(this.variant) ? this.variant : "subtle";
+    // raised reuses ray-button's key; the others are drawn here.
+    el.dataset.variant = variant === "raised" ? "raised" : "toggle";
+    el.dataset.toggle = variant;
+    el.setAttribute("aria-pressed", String(Boolean(this.pressed)));
+    if (this.label) {
+      el.setAttribute("aria-label", this.label);
+      el.title = this.label;
+    }
+    // Submitted like a checkbox: value (default "on") under name while pressed.
+    this.internals.setFormValue(this.pressed && this.name ? (this.value ?? "on") : null);
+  }
+}
+
+define("ray-toggle", RayToggle);

package/components/toggle-group/toggle-group.js

@@ -0,0 +1,216 @@
+// <ray-toggle-group>: a set of <ray-toggle> with one shared value (shadcn's
+// ToggleGroup). type="single": at most one on (text alignment, a view mode);
+// type="multiple": any number (bold / italic / underline).
+//
+// A ray-button-group, so the toggles are joined (corners squared, borders
+// overlapped); `spaced` keeps them apart. variant, color, size and square on
+// the group reach every toggle that does not set its own. Arrow keys move
+// between toggles (one tab stop, the selected one); Space/Enter flips the
+// focused one. Each toggle's `value` (else its text) is its key.
+//
+//   <ray-toggle-group type="single" value="left" label="Alignment">
+//     <ray-toggle value="left">Left</ray-toggle> …
+//   </ray-toggle-group>
+
+import { css, define } from "../../core/core.js";
+import { RayButtonGroup } from "../button-group/button-group.js";
+import "../toggle/toggle.js";
+
+const styles = css`
+  /* spaced: apart, each toggle with its own corners. */
+  :host([spaced]) { gap: var(--ray-space-1); flex-wrap: wrap; }
+  /* !important: the joined rules of ray-button-group are more specific. */
+  :host([spaced]) ::slotted(*) {
+    margin: 0 !important;
+    --ray-group-radius-ss: initial !important;
+    --ray-group-radius-se: initial !important;
+    --ray-group-radius-es: initial !important;
+    --ray-group-radius-ee: initial !important;
+  }
+`;
+
+// Group properties handed down to toggles that do not set their own.
+const INHERITED = ["variant", "color", "size", "square", "radius"];
+
+export class RayToggleGroup extends RayButtonGroup {
+  static formAssociated = true;
+  static properties = {
+    ...RayButtonGroup.properties,
+    type: { type: String, reflect: true, default: "single" },
+    value: { type: String },
+    name: { type: String, reflect: true },
+    required: { type: Boolean, reflect: true },
+    disabled: { type: Boolean, reflect: true },
+    spaced: { type: Boolean, reflect: true },
+    variant: { type: String, reflect: true },
+    color: { type: String, reflect: true },
+    size: { type: String, reflect: true },
+    radius: { type: String, reflect: true },
+    square: { type: Boolean, reflect: true },
+  };
+  static styles = [...RayButtonGroup.styles, styles];
+
+  /** What the group set on each toggle (so the toggle's own attributes win). */
+  #handed = new WeakMap();
+  #initial = null;
+  #fieldsetDisabled = false;
+
+  constructor() {
+    super();
+    this.internals = this.attachInternals();
+    this.$("slot").addEventListener("slotchange", () => this.requestUpdate());
+    // A toggle flipped itself: apply the group's rule, then announce the
+    // group's value. The toggles' own change events stop here.
+    this.addEventListener("change", (e) => {
+      const t = e.target;
+      if (t === this) return;
+      e.stopPropagation();
+      if (t.localName === "ray-toggle" && t.closest("ray-toggle-group") === this) this.#flipped(t);
+    });
+    this.addEventListener("keydown", (e) => this.#key(e));
+    this.addEventListener("focusin", (e) => {
+      const t = e.composedPath().find((n) => n.localName === "ray-toggle");
+      if (t && this.toggles.includes(t)) this.#rove(t);
+    });
+  }
+
+  connectedCallback() {
+    this.#initial ??= this.getAttribute("value");
+    super.connectedCallback();
+  }
+
+  formDisabledCallback(disabled) {
+    this.#fieldsetDisabled = disabled;
+    this.requestUpdate();
+  }
+
+  formResetCallback() {
+    this.value = this.#initial ?? undefined;
+  }
+
+  /** The toggles of this group (not of a nested one). */
+  get toggles() {
+    return [...this.querySelectorAll("ray-toggle")].filter((t) => t.closest("ray-toggle-group") === this);
+  }
+
+  get #multiple() {
+    return this.type === "multiple";
+  }
+
+  /** The selected values as a list (single: zero or one). */
+  get values() {
+    const v = this.value;
+    if (Array.isArray(v)) return [...v];
+    if (v === null || v === undefined || v === "") return [];
+    return this.#multiple ? String(v).split(",").map((s) => s.trim()).filter(Boolean) : [String(v)];
+  }
+
+  set values(list) {
+    this.value = this.#multiple ? [...(list ?? [])] : (list?.[0] ?? undefined);
+  }
+
+  #key(e) {
+    const vertical = this.orientation === "vertical";
+    const next = vertical ? "ArrowDown" : "ArrowRight";
+    const prev = vertical ? "ArrowUp" : "ArrowLeft";
+    if (![next, prev, "Home", "End"].includes(e.key)) return;
+    const items = this.toggles.filter((t) => !t.disabled);
+    if (items.length === 0) return;
+    const current = items.findIndex((t) => t.matches(":focus-within"));
+    let i = current;
+    if (e.key === "Home") i = 0;
+    else if (e.key === "End") i = items.length - 1;
+    else if (e.key === next) i = (current + 1) % items.length;
+    else i = (current - 1 + items.length) % items.length;
+    e.preventDefault();
+    this.#rove(items[i]);
+    items[i].focus();
+  }
+
+  // One tab stop: the given toggle gets tabindex 0, the others -1 (a host
+  // with a negative tabindex takes its shadow button out of the tab order).
+  #rove(target) {
+    for (const t of this.toggles) t.tabIndex = t === target ? 0 : -1;
+  }
+
+  #keyOf(t) {
+    return t.value ?? t.textContent.trim();
+  }
+
+  #flipped(t) {
+    const key = this.#keyOf(t);
+    const before = this.values;
+    let next;
+    if (this.#multiple) {
+      next = t.pressed ? [...before.filter((v) => v !== key), key] : before.filter((v) => v !== key);
+      // Keep the order of the toggles, not of the clicks.
+      const order = this.toggles.map((x) => this.#keyOf(x));
+      next.sort((a, b) => order.indexOf(a) - order.indexOf(b));
+    } else if (t.pressed) {
+      next = [key];
+    } else {
+      // Single and required: the selected toggle cannot be turned off.
+      next = this.required ? [key] : [];
+    }
+    this.values = next;
+    this.#sync();
+    if (next.join("\n") !== before.join("\n")) {
+      this.dispatchEvent(new Event("change", { bubbles: true }));
+    }
+  }
+
+  // Pressed states, handed-down properties and tab stops from the value.
+  #sync() {
+    const selected = this.values;
+    const toggles = this.toggles;
+    const disabled = Boolean(this.disabled) || this.#fieldsetDisabled;
+    for (const t of toggles) {
+      t.pressed = selected.includes(this.#keyOf(t));
+      let handed = this.#handed.get(t);
+      if (!handed) this.#handed.set(t, (handed = new Set()));
+      for (const prop of [...INHERITED, "disabled"]) {
+        const groupValue = prop === "disabled" ? (disabled || undefined) : this[prop];
+        const attr = prop;
+        if (t.hasAttribute(attr) && !handed.has(prop)) continue;
+        if (groupValue === undefined || groupValue === null || groupValue === false) {
+          if (handed.has(prop)) {
+            t[prop] = prop === "square" || prop === "disabled" ? false : undefined;
+            handed.delete(prop);
+          }
+        } else {
+          t[prop] = groupValue;
+          handed.add(prop);
+        }
+      }
+    }
+    const stop = toggles.find((t) => t.pressed && !t.disabled) ?? toggles.find((t) => !t.disabled);
+    if (!toggles.some((t) => t.matches(":focus-within"))) this.#rove(stop);
+  }
+
+  update(changed) {
+    super.update(changed);
+    // A single group never keeps more than one value.
+    if (!this.#multiple && this.values.length > 1) this.commitProperty("value", this.values[0]);
+    this.#sync();
+    const values = this.values;
+    if (this.name && values.length) {
+      if (this.#multiple) {
+        const data = new FormData();
+        for (const v of values) data.append(this.name, v);
+        this.internals.setFormValue(data);
+      } else {
+        this.internals.setFormValue(values[0]);
+      }
+    } else {
+      this.internals.setFormValue(null);
+    }
+    const first = this.toggles[0];
+    if (this.required && values.length === 0) {
+      this.internals.setValidity({ valueMissing: true }, "Select an option.", first?._el ?? undefined);
+    } else {
+      this.internals.setValidity({});
+    }
+  }
+}
+
+define("ray-toggle-group", RayToggleGroup);

package/components/tooltip/tooltip.js

@@ -0,0 +1,101 @@
+// <ray-tooltip label="…">: a short hint shown on hover and focus of its
+// child. The label also becomes the child's accessible description.
+
+import { css, define, uid } from "../../core/core.js";
+import { Floating, floatingStyles } from "../../core/floating.js";
+import { applyColor } from "../../core/styles.js";
+
+const styles = css`
+  :host { display: inline-flex; }
+  .panel {
+    max-width: 20rem;
+    padding: var(--ray-space-1) var(--ray-space-2);
+    font-size: var(--ray-font-size-xs);
+    line-height: var(--ray-line-height-sm);
+    color: var(--ray-background);
+    background: var(--ray-foreground);
+    border: 0;
+    border-radius: var(--ray-radius-sm);
+    box-shadow: var(--ray-shadow-sm);
+    pointer-events: none;
+    white-space: normal;
+    overflow: visible;
+  }
+  .panel[data-colored] { color: var(--_contrast); background: var(--_filled); }
+`;
+
+export class RayTooltip extends Floating {
+  static properties = {
+    ...Floating.properties,
+    label: { type: String },
+    placement: { type: String, reflect: true, default: "top" },
+    offset: { type: Number, default: 6 },
+    openDelay: { type: Number, default: 300 },
+    closeDelay: { type: Number, default: 0 },
+    color: { type: String, reflect: true },
+    disabled: { type: Boolean, reflect: true },
+  };
+  static styles = [floatingStyles, styles];
+  static popoverMode = "manual";
+  static lightDismiss = false;
+  static haspopup = null;
+  static triggerSlot = "slot:not([name])";
+  static template = `<slot></slot><div class="panel" part="tooltip" role="tooltip"></div>`;
+
+  constructor() {
+    super();
+    this._open = () => this._schedule(true);
+    this._close = () => this._schedule(false);
+    this._esc = (e) => { if (e.key === "Escape") this._schedule(false, 0); };
+  }
+
+  wireTrigger(t) {
+    // The description lives in the light DOM (an unassigned, unrendered child)
+    // so the trigger can reference it by id.
+    if (!this._desc) {
+      this._desc = document.createElement("span");
+      this._desc.slot = "description";
+      this._desc.id = uid("tooltip");
+      this._desc.hidden = true;
+      this.append(this._desc);
+    }
+    const ids = new Set((t.getAttribute("aria-describedby") ?? "").split(/\s+/).filter(Boolean));
+    ids.add(this._desc.id);
+    t.setAttribute("aria-describedby", [...ids].join(" "));
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.addEventListener("pointerenter", this._open);
+    this.addEventListener("pointerleave", this._close);
+    this.addEventListener("focusin", this._open);
+    this.addEventListener("focusout", this._close);
+    this.addEventListener("pointerdown", this._close);
+    document.addEventListener("keydown", this._esc);
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    document.removeEventListener("keydown", this._esc);
+    clearTimeout(this._timer);
+  }
+
+  update(changed) {
+    this.panel.textContent = this.label ?? "";
+    if (this._desc) this._desc.textContent = this.label ?? "";
+    this.panel.toggleAttribute("data-colored", Boolean(this.color));
+    if (this.color) applyColor(this.panel, this.color);
+    if ((this.disabled || !this.label) && this.open) this.commitProperty("open", false);
+    super.update(changed);
+  }
+
+  _schedule(open, delay = open ? this.openDelay : this.closeDelay) {
+    clearTimeout(this._timer);
+    if (open && (this.disabled || !this.label)) return;
+    const apply = () => { this.open = open; };
+    if (delay > 0) this._timer = setTimeout(apply, delay);
+    else apply();
+  }
+}
+
+define("ray-tooltip", RayTooltip);

package/core/charts.js

@@ -0,0 +1,107 @@
+// Chart theming: ray-elements draws no charts; this hands the chart tokens
+// (--ray-chart-*, tokens.toml) to a chart library.
+//
+// SVG/HTML charts can use the CSS variables directly (fill: var(--ray-chart-1))
+// and follow the theme by themselves. Canvas libraries (Chart.js, uPlot,
+// ECharts…) need concrete colors: chartTheme() resolves them for the
+// current theme of an element, and onChartThemeChange() tells when to redraw.
+
+import { onThemeChange, resolvedTheme } from "./core.js";
+
+/** Number of series colors (--ray-chart-1 … --ray-chart-8). */
+export const CHART_SERIES = 8;
+
+let ctx = null;
+
+/**
+ * A computed CSS color as "#rrggbb" (opaque) or "rgba(r, g, b, a)" — what every
+ * canvas accepts. Computed values come as rgb()/rgba() or, for color-mix() and
+ * friends, as color(srgb r g b / a), which WebKit's canvas does not take:
+ * parsed here rather than trusted to the canvas.
+ */
+function normalize(color) {
+  const c = String(color).trim();
+  let rgba = null;
+  const srgb = c.match(/^color\(srgb\s+([^)]+)\)$/i);
+  const fn = c.match(/^rgba?\(([^)]+)\)$/i);
+  if (srgb) {
+    const [chan, alpha] = srgb[1].split("/");
+    const [r, g, b] = chan.trim().split(/\s+/).map((x) => Number(x) * 255);
+    rgba = [r, g, b, alpha === undefined ? 1 : Number(alpha)];
+  } else if (fn) {
+    const parts = fn[1].replace("/", " ").split(/[\s,]+/).filter(Boolean).map(Number);
+    rgba = [parts[0], parts[1], parts[2], parts.length > 3 ? parts[3] : 1];
+  }
+  if (!rgba || rgba.some((x) => Number.isNaN(x))) {
+    // Anything else (a named color, hex): let the canvas serialize it.
+    ctx ??= document.createElement("canvas").getContext("2d");
+    ctx.fillStyle = "#000000";
+    ctx.fillStyle = c;
+    return ctx.fillStyle;
+  }
+  const [r, g, b, a] = rgba.map((x, i) => (i < 3 ? Math.round(Math.min(255, Math.max(0, x))) : x));
+  if (a >= 1) return `#${[r, g, b].map((x) => x.toString(16).padStart(2, "0")).join("")}`;
+  return `rgba(${r}, ${g}, ${b}, ${a})`;
+}
+
+/**
+ * A color with an alpha, for area fills and highlights: withAlpha("#1c7ed6", 0.2).
+ * @returns {string} rgba(...)
+ */
+export function withAlpha(color, alpha) {
+  const c = normalize(color);
+  const hex = c.startsWith("#") ? c : null;
+  let r, g, b;
+  if (hex) {
+    const n = parseInt(hex.slice(1), 16);
+    [r, g, b] = [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+  } else {
+    [r, g, b] = c.match(/[\d.]+/g).map(Number);
+  }
+  return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+}
+
+/**
+ * The chart tokens resolved for the theme of `el` (default: the document):
+ * its color scheme, data-primary and any token overrides apply.
+ * @param {Element} [el]
+ */
+export function chartTheme(el = document.documentElement) {
+  const host = el === document.documentElement ? document.body ?? el : el;
+  const probe = document.createElement("span");
+  probe.style.cssText = "position:absolute;visibility:hidden;pointer-events:none;width:0;height:0;overflow:hidden";
+  host.append(probe);
+  const color = (name) => {
+    probe.style.color = `var(--ray-${name})`;
+    return normalize(getComputedStyle(probe).color);
+  };
+  try {
+    const series = [];
+    for (let i = 1; i <= CHART_SERIES; i++) series.push(color(`chart-${i}`));
+    probe.style.fontFamily = "var(--ray-font-sans)";
+    probe.style.fontSize = "var(--ray-font-size-xs)";
+    const cs = getComputedStyle(probe);
+    return {
+      scheme: resolvedTheme(el),
+      series,
+      background: color("background"),
+      grid: color("chart-grid"),
+      axis: color("chart-axis"),
+      text: color("chart-text"),
+      tooltip: { background: color("chart-tooltip"), text: color("chart-tooltip-text"), border: color("chart-tooltip-border") },
+      font: { family: cs.fontFamily, size: parseFloat(cs.fontSize) },
+    };
+  } finally {
+    probe.remove();
+  }
+}
+
+/**
+ * Calls `cb(chartTheme(el))` whenever the theme changes (setTheme,
+ * setPrimary, definePrimary, the system scheme). Returns a function that stops.
+ * @param {(theme: ReturnType<typeof chartTheme>) => void} cb
+ */
+export function onChartThemeChange(cb, el = document.documentElement) {
+  // After the change has applied (attributes and styles are set synchronously).
+  return onThemeChange(() => queueMicrotask(() => cb(chartTheme(el))));
+}

package/core/color.js

@@ -0,0 +1,110 @@
+// Color math for definePrimary(): parse any CSS color, build a ten-shade
+// scale in OKLCH (perceptually even lightness, same hue), and measure WCAG
+// contrast. OKLab from Björn Ottosson (https://bottosson.github.io/posts/oklab/).
+
+/** Target lightness (OKLab L) of shades 0…9, like the open-color scales. */
+const LIGHTNESS = [0.97, 0.93, 0.87, 0.8, 0.73, 0.67, 0.61, 0.55, 0.49, 0.43];
+/** Chroma of each shade relative to the base color's (pale ends are less saturated). */
+const CHROMA = [0.12, 0.25, 0.45, 0.65, 0.8, 0.92, 1, 1, 0.95, 0.88];
+
+let ctx = null;
+
+/**
+ * Any CSS color the browser understands ("#7c3aed", "rebeccapurple",
+ * "oklch(60% 0.2 280)") as sRGB channels 0…1, or null if it is not a color.
+ */
+export function parseColor(input) {
+  if (typeof input !== "string" || !input.trim()) return null;
+  ctx ??= document.createElement("canvas").getContext("2d");
+  // A sentinel tells an invalid color (fillStyle keeps the previous value) apart.
+  for (const sentinel of ["#010203", "#040506"]) {
+    ctx.fillStyle = sentinel;
+    ctx.fillStyle = input.trim();
+    const v = ctx.fillStyle;
+    if (v !== sentinel) return fromCanvas(v);
+  }
+  // Both sentinels survived: the input is one of them, or invalid.
+  const t = input.trim().toLowerCase();
+  return t === "#010203" || t === "#040506" ? fromCanvas(t) : null;
+}
+
+function fromCanvas(v) {
+  if (v.startsWith("#")) {
+    const n = parseInt(v.slice(1), 16);
+    return { r: ((n >> 16) & 255) / 255, g: ((n >> 8) & 255) / 255, b: (n & 255) / 255 };
+  }
+  const m = v.match(/rgba?\(([^)]+)\)/);
+  if (!m) return null;
+  const [r, g, b] = m[1].split(",").map((x) => Number(x.trim()) / 255);
+  return { r, g, b };
+}
+
+export function toHex({ r, g, b }) {
+  const h = (x) => Math.round(Math.min(1, Math.max(0, x)) * 255).toString(16).padStart(2, "0");
+  return `#${h(r)}${h(g)}${h(b)}`;
+}
+
+const toLinear = (c) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+const fromLinear = (c) => (c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055);
+
+export function toOklch({ r, g, b }) {
+  const [lr, lg, lb] = [toLinear(r), toLinear(g), toLinear(b)];
+  const l = Math.cbrt(0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb);
+  const m = Math.cbrt(0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb);
+  const s = Math.cbrt(0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb);
+  const L = 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s;
+  const A = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s;
+  const B = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s;
+  return { l: L, c: Math.hypot(A, B), h: Math.atan2(B, A) };
+}
+
+export function fromOklch({ l: L, c, h }) {
+  const A = c * Math.cos(h);
+  const B = c * Math.sin(h);
+  const l = (L + 0.3963377774 * A + 0.2158037573 * B) ** 3;
+  const m = (L - 0.1055613458 * A - 0.0638541728 * B) ** 3;
+  const s = (L - 0.0894841775 * A - 1.291485548 * B) ** 3;
+  return {
+    r: fromLinear(4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s),
+    g: fromLinear(-1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s),
+    b: fromLinear(-0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s),
+  };
+}
+
+const inGamut = ({ r, g, b }) => [r, g, b].every((x) => x >= -0.0005 && x <= 1.0005);
+
+/** The color with chroma reduced until it fits in sRGB. */
+function fit(lch) {
+  let c = lch.c;
+  let rgb = fromOklch({ ...lch, c });
+  for (let i = 0; i < 60 && !inGamut(rgb); i++) {
+    c *= 0.95;
+    rgb = fromOklch({ ...lch, c });
+  }
+  return rgb;
+}
+
+/**
+ * Ten shades (0 = lightest) around `rgb`: the base color itself sits at the
+ * shade whose lightness is closest to its own; the others keep its hue.
+ * @returns {string[]} hex colors
+ */
+export function shades(rgb) {
+  const base = toOklch(rgb);
+  let closest = 0;
+  LIGHTNESS.forEach((l, i) => {
+    if (Math.abs(l - base.l) < Math.abs(LIGHTNESS[closest] - base.l)) closest = i;
+  });
+  return LIGHTNESS.map((l, i) => (i === closest ? toHex(rgb) : toHex(fit({ l, c: base.c * CHROMA[i], h: base.h }))));
+}
+
+function luminance(hex) {
+  const { r, g, b } = fromCanvas(hex);
+  return 0.2126 * toLinear(r) + 0.7152 * toLinear(g) + 0.0722 * toLinear(b);
+}
+
+/** WCAG contrast ratio of two hex colors (1…21). */
+export function contrastRatio(a, b) {
+  const [x, y] = [luminance(a), luminance(b)].sort((p, q) => q - p);
+  return (x + 0.05) / (y + 0.05);
+}