Lutra/ui/tests/theme/contrast.test.ts
danny a8daf269fb M3.6: integrated terminal with PTY sessions and xterm.js sub-tabs
- crates/terminal: portable-pty sessions (ConPTY on Windows) with reader,
  writer and waiter threads, UTF-8 chunking, a 1 MiB output buffer with
  backpressure, a non-blocking input queue, resize, kill and exit codes;
  default shell pwsh -> powershell -> cmd on Windows, $SHELL or /bin/sh.
- Engine: terminal.create/input/resize/close, terminalOutput (capped per
  terminal and per pump, round-robin) and terminalExited through the pump;
  terminals close with the project and on app.quit.
- UI: Terminal tab in the bottom panel (tabs next to Find), xterm.js with
  the fit addon, sub-tabs, copy/paste, a focus rule that leaves plain Ctrl
  keys to the shell, terminal.open (Mod+Shift+T), --lt-terminal-* ANSI
  tokens in both themes (text colours AA) and a 4.5:1 minimum contrast.
- Tests: real-shell crate tests (UTF-8, backpressure), engine and TCP
  control tests, Vitest with a mocked xterm; live check on port 7936;
  docs and parity rows.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20 21:10:37 +02:00

164 lines
5.6 KiB
TypeScript

/**
* WCAG 2.1 contrast check of the built-in themes
* (https://www.w3.org/TR/WCAG21/#contrast-minimum). Every token pair the
* UI draws text with reaches AA: 4.5:1 for body text, 3:1 for non-text
* marks (cursor, modified dot, settings switch knob; WCAG 1.4.11). Every
* syntax colour (`--lt-syntax-*`) reaches 4.5:1 on the editor background
* and on the active line. The terminal's text, cursor and every ANSI colour
* that shows as text reach AA on the terminal background (M3.6); the colour
* meant to vanish into it is exempt per theme (`TERMINAL_EXEMPT`). The
* themes come from
* `themes.json`, a snapshot that the Rust test `ui_snapshot_is_current`
* keeps equal to `lutra_engine::theme`.
*/
import { describe, expect, it } from "vitest";
import themes from "./themes.json";
/** Minimum ratio for normal-size text (AA). */
const TEXT = 4.5;
/** Minimum ratio for large text and non-text marks (AA). */
const LARGE = 3;
/**
* Foreground token, background token and minimum ratio, for every
* combination the components use (see `ui/src/**` `color`/`background`).
*/
const PAIRS: [string, string, number][] = [
["fg", "bg", TEXT],
["fg", "editor-bg", TEXT],
["fg", "tab-active-bg", TEXT],
["fg", "notice-bg", TEXT],
["fg", "editor-active-line-bg", TEXT],
["fg", "editor-selection-bg", TEXT],
["fg", "editor-match-bg", TEXT],
["fg-muted", "bg", TEXT],
["fg-muted", "editor-bg", TEXT],
["accent", "bg", TEXT],
["error", "bg", TEXT],
["error", "statusbar-bg", TEXT],
["statusbar-fg", "statusbar-bg", TEXT],
["editor-gutter-fg", "editor-gutter-bg", TEXT],
["editor-gutter-fg", "editor-active-line-bg", TEXT],
["editor-cursor", "editor-bg", LARGE],
["bg", "accent", LARGE],
["fg", "editor-bg", LARGE],
["editor-cursor", "editor-active-line-bg", LARGE],
["tab-modified", "bg", LARGE],
["tab-modified", "tab-active-bg", LARGE],
];
/** Syntax token names (`--lt-syntax-<name>`), as `SYNTAX_TOKENS` in `theme.rs`. */
export const SYNTAX = [
"keyword",
"string",
"number",
"comment",
"variable",
"function",
"type",
"constant",
"tag",
"attribute",
"operator",
] as const;
/** Every syntax token as text on the editor background and the active line. */
const SYNTAX_PAIRS: [string, string, number][] = SYNTAX.flatMap((name): [string, string, number][] => [
[`syntax-${name}`, "editor-bg", TEXT],
[`syntax-${name}`, "editor-active-line-bg", TEXT],
]);
/** ANSI colour names, as in `TERMINAL_TOKENS` in `theme.rs`. */
const ANSI = ["black", "red", "green", "yellow", "blue", "magenta", "cyan", "white"] as const;
/** ANSI tokens that may blend into the background, per theme id. */
const TERMINAL_EXEMPT: Record<string, readonly string[]> = {
"lutra-dark": ["terminal-ansi-black"],
"lutra-light": ["terminal-ansi-white", "terminal-ansi-bright-white"],
};
/**
* The terminal's pairs for one theme: text and selection, the cursor, and
* every ANSI colour (normal and bright) that is not exempt.
*
* @param id - the theme id.
* @returns foreground token, background token and minimum ratio.
*/
function terminalPairs(id: string): [string, string, number][] {
const exempt = TERMINAL_EXEMPT[id] ?? [];
const ansi = ANSI.flatMap((name) => [`terminal-ansi-${name}`, `terminal-ansi-bright-${name}`]).filter(
(name) => !exempt.includes(name),
);
return [
["terminal-fg", "terminal-bg", TEXT],
["terminal-fg", "terminal-selection-bg", TEXT],
["terminal-cursor", "terminal-bg", LARGE],
...ansi.map((name): [string, string, number] => [name, "terminal-bg", TEXT]),
];
}
/**
* Relative luminance of a `#rrggbb` colour (WCAG 2.1 definition).
*
* @param hex - the colour.
* @returns the luminance, 0 (black) to 1 (white).
*/
export function luminance(hex: string): number {
const match = /^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i.exec(hex);
if (!match) {
throw new Error(`not a #rrggbb colour: ${hex}`);
}
const [r, g, b] = match.slice(1).map((part) => {
const c = parseInt(part, 16) / 255;
return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
}) as [number, number, number];
return 0.2126 * r + 0.7152 * g + 0.0722 * b;
}
/**
* Contrast ratio of two colours.
*
* @param a - one `#rrggbb` colour.
* @param b - the other.
* @returns the ratio, 1 to 21.
*/
export function contrast(a: string, b: string): number {
const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x) as [number, number];
return (hi + 0.05) / (lo + 0.05);
}
describe("contrast helper", () => {
it("matches the WCAG extremes", () => {
expect(contrast("#000000", "#ffffff")).toBeCloseTo(21, 5);
expect(contrast("#777777", "#777777")).toBe(1);
expect(contrast("#767676", "#ffffff")).toBeGreaterThanOrEqual(4.5);
});
});
describe.each(themes)("theme $id", (theme) => {
const tokens: Record<string, string> = theme.tokens;
const token = (name: string): string => {
const value = tokens[`--lt-${name}`];
if (value === undefined) {
throw new Error(`${theme.id} has no --lt-${name}`);
}
return value;
};
it("checks every syntax token it defines", () => {
const defined = Object.keys(tokens)
.filter((name) => name.startsWith("--lt-syntax-"))
.map((name) => name.slice("--lt-syntax-".length))
.sort();
expect(defined).toEqual([...SYNTAX].sort());
});
it("checks every terminal ANSI token it defines", () => {
const defined = Object.keys(tokens).filter((name) => name.startsWith("--lt-terminal-ansi-"));
expect(defined).toHaveLength(ANSI.length * 2);
});
it.each([...PAIRS, ...SYNTAX_PAIRS, ...terminalPairs(theme.id)])("%s on %s reaches %d:1", (fg, bg, min) => {
expect(contrast(token(fg), token(bg))).toBeGreaterThanOrEqual(min);
});
});