@parallelworks/ui 0.44.0 → 0.46.0

package/dist/theme/color.d.ts

@@ -0,0 +1,40 @@
+/** A color in OKLCH: lightness 0–1, chroma 0–~0.37, hue in degrees. */
+export interface Oklch {
+    l: number;
+    c: number;
+    h: number;
+}
+type Vec3 = [number, number, number];
+/** An RGB space the generator writes into. Both gamma-encode as sRGB does. */
+export type Gamut = 'srgb' | 'p3';
+/** Parses `#rgb`, `#rrggbb`, `oklch(L C H)` (L as 0–1 or a percentage) or
+ *  `color(display-p3 r g b)`, or returns null. */
+export declare function parseColor(input: string): Oklch | null;
+/** Like `parseColor`, for colors the code itself wrote. */
+export declare function oklch(input: string): Oklch;
+export declare function toOklab({ l, c, h }: Oklch): Vec3;
+export declare function fromOklab([l, a, b]: Vec3): Oklch;
+/** The color that gamma-encoded channels in a gamut show. */
+export declare function fromRgb(rgb: Vec3, gamut?: Gamut): Oklch;
+/** The distance between two colors in OKLab (ΔEOK). */
+export declare function deltaE(a: Oklch, b: Oklch): number;
+/** About one just-noticeable difference in ΔEOK, as CSS Color 4 uses it. */
+export declare const JND = 0.02;
+/** CSS Color 4's gamut mapping: lower chroma at fixed lightness and hue until
+ *  clipping the rest is no longer noticeable. Returns channels, 0–1. */
+export declare function gamutMap(color: Oklch, gamut?: Gamut): Vec3;
+/** The sRGB hex a color shows as, gamut-mapped. */
+export declare function toHex(color: Oklch): string;
+/** A color's display-p3 channels, gamut-mapped and rounded as `toP3` writes them. */
+export declare function p3Channels(color: Oklch): Vec3;
+/** `color(display-p3 …)` of a color, gamut-mapped into display-p3, with an optional alpha. */
+export declare function toP3(color: Oklch, alpha?: number): string;
+/** The color a generated color shows as in a gamut. */
+export declare function rendered(color: Oklch, gamut?: Gamut): Oklch;
+/** Part of the way from `a` to `b`, interpolated in OKLab. */
+export declare function mixOklab(a: Oklch, b: Oklch, t: number): Oklch;
+/** `rgba()` of a hex color at an alpha. */
+export declare function withAlpha(hex: string, alpha: number): string;
+/** A color written as a hex, or an `rgba()` over a backdrop, as the hex it shows as. */
+export declare function composite(color: string, backdrop: string): string;
+export {};

package/dist/theme/color.js

@@ -0,0 +1,228 @@
+//#region src/theme/color.ts
+var HEX = /^#?([\da-f]{3}|[\da-f]{6})$/i;
+var OKLCH = /^oklch\(\s*([\d.]+)(%?)\s+([\d.]+)\s+([\d.]+)(?:deg)?\s*\)$/i;
+var P3 = /^color\(\s*display-p3\s+([\d.]+)\s+([\d.]+)\s+([\d.]+)\s*\)$/i;
+/** Parses `#rgb`, `#rrggbb`, `oklch(L C H)` (L as 0–1 or a percentage) or
+*  `color(display-p3 r g b)`, or returns null. */
+function parseColor(input) {
+	const text = input.trim();
+	const hex = HEX.exec(text)?.[1];
+	if (hex) {
+		const full = hex.length === 3 ? [...hex].map((c) => c + c).join("") : hex;
+		return fromRgb([
+			0,
+			2,
+			4
+		].map((i) => Number.parseInt(full.slice(i, i + 2), 16) / 255));
+	}
+	const p3 = P3.exec(text);
+	if (p3) {
+		const rgb = [
+			p3[1],
+			p3[2],
+			p3[3]
+		].map(Number);
+		return rgb.every((v) => Number.isFinite(v) && v >= 0 && v <= 1) ? fromRgb(rgb, "p3") : null;
+	}
+	const m = OKLCH.exec(text);
+	if (m) {
+		const l = Number(m[1]) / (m[2] ? 100 : 1);
+		const c = Number(m[3]);
+		const h = Number(m[4]);
+		if ([
+			l,
+			c,
+			h
+		].every(Number.isFinite) && l >= 0 && l <= 1) return {
+			l,
+			c,
+			h: (h % 360 + 360) % 360
+		};
+	}
+	return null;
+}
+/** Like `parseColor`, for colors the code itself wrote. */
+function oklch(input) {
+	const color = parseColor(input);
+	if (!color) throw new Error(`Invalid color: ${input}`);
+	return color;
+}
+var toLinear = (v) => v <= .04045 ? v / 12.92 : ((v + .055) / 1.055) ** 2.4;
+var toGamma = (v) => v <= .0031308 ? 12.92 * v : 1.055 * Math.sign(v) * Math.abs(v) ** (1 / 2.4) - .055;
+function linearSrgbToOklab([r, g, b]) {
+	const l = Math.cbrt(.4122214708 * r + .5363325363 * g + .0514459929 * b);
+	const m = Math.cbrt(.2119034982 * r + .6806995451 * g + .1073969566 * b);
+	const s = Math.cbrt(.0883024619 * r + .2817188376 * g + .6299787005 * b);
+	return [
+		.2104542553 * l + .793617785 * m - .0040720468 * s,
+		1.9779984951 * l - 2.428592205 * m + .4505937099 * s,
+		.0259040371 * l + .7827717662 * m - .808675766 * s
+	];
+}
+function oklabToLinearSrgb([L, a, b]) {
+	const l = (L + .3963377774 * a + .2158037573 * b) ** 3;
+	const m = (L - .1055613458 * a - .0638541728 * b) ** 3;
+	const s = (L - .0894841775 * a - 1.291485548 * b) ** 3;
+	return [
+		4.0767416621 * l - 3.3077115913 * m + .2309699292 * s,
+		-1.2684380046 * l + 2.6097574011 * m - .3413193965 * s,
+		-.0041960863 * l - .7034186147 * m + 1.707614701 * s
+	];
+}
+var SRGB_TO_P3 = [
+	[
+		.8224621209,
+		.177537879,
+		0
+	],
+	[
+		.0331941989,
+		.9668058011,
+		0
+	],
+	[
+		.0170826307,
+		.0723974407,
+		.9105199286
+	]
+];
+var P3_TO_SRGB = [
+	[
+		1.2249401763,
+		-.2249401763,
+		0
+	],
+	[
+		-.0420569547,
+		1.0420569547,
+		0
+	],
+	[
+		-.0196375546,
+		-.0786360456,
+		1.0982736001
+	]
+];
+var multiply = (m, [r, g, b]) => m.map((row) => row[0] * r + row[1] * g + row[2] * b);
+function toOklab({ l, c, h }) {
+	const rad = h * Math.PI / 180;
+	return [
+		l,
+		c * Math.cos(rad),
+		c * Math.sin(rad)
+	];
+}
+function fromOklab([l, a, b]) {
+	const c = Math.hypot(a, b);
+	return {
+		l,
+		c,
+		h: c < 1e-6 ? 0 : (Math.atan2(b, a) * 180 / Math.PI % 360 + 360) % 360
+	};
+}
+/** The color that gamma-encoded channels in a gamut show. */
+function fromRgb(rgb, gamut = "srgb") {
+	const linear = rgb.map(toLinear);
+	return fromOklab(linearSrgbToOklab(gamut === "p3" ? multiply(P3_TO_SRGB, linear) : linear));
+}
+/** Gamma-encoded channels in a gamut, outside 0–1 when the color is out of it. */
+function toRgb(color, gamut) {
+	const linear = oklabToLinearSrgb(toOklab(color));
+	return (gamut === "p3" ? multiply(SRGB_TO_P3, linear) : linear).map(toGamma);
+}
+var inGamut = (rgb) => rgb.every((v) => v >= -1e-6 && v <= 1.000001);
+var clip = (rgb) => rgb.map((v) => Math.min(1, Math.max(0, v)));
+/** The distance between two colors in OKLab (ΔEOK). */
+function deltaE(a, b) {
+	const [l1, a1, b1] = toOklab(a);
+	const [l2, a2, b2] = toOklab(b);
+	return Math.hypot(l1 - l2, a1 - a2, b1 - b2);
+}
+/** About one just-noticeable difference in ΔEOK, as CSS Color 4 uses it. */
+var JND = .02;
+/** CSS Color 4's gamut mapping: lower chroma at fixed lightness and hue until
+*  clipping the rest is no longer noticeable. Returns channels, 0–1. */
+function gamutMap(color, gamut = "srgb") {
+	if (color.l >= 1) return [
+		1,
+		1,
+		1
+	];
+	if (color.l <= 0) return [
+		0,
+		0,
+		0
+	];
+	const direct = toRgb(color, gamut);
+	if (inGamut(direct)) return clip(direct);
+	const near = (c) => deltaE(fromRgb(clip(toRgb(c, gamut)), gamut), c) < JND;
+	if (near(color)) return clip(direct);
+	let lo = 0;
+	let hi = color.c;
+	let current = { ...color };
+	while (hi - lo > 1e-4) {
+		current = {
+			...color,
+			c: (lo + hi) / 2
+		};
+		const rgb = toRgb(current, gamut);
+		if (inGamut(rgb)) lo = current.c;
+		else if (near(current)) return clip(rgb);
+		else hi = current.c;
+	}
+	return clip(toRgb(current, gamut));
+}
+/** The sRGB hex a color shows as, gamut-mapped. */
+function toHex(color) {
+	return `#${gamutMap(color).map((v) => Math.round(v * 255).toString(16).padStart(2, "0")).join("")}`;
+}
+/** A color's display-p3 channels, gamut-mapped and rounded as `toP3` writes them. */
+function p3Channels(color) {
+	return gamutMap(color, "p3").map((v) => Number(v.toFixed(4)));
+}
+/** `color(display-p3 …)` of a color, gamut-mapped into display-p3, with an optional alpha. */
+function toP3(color, alpha) {
+	const [r, g, b] = p3Channels(color);
+	return `color(display-p3 ${r} ${g} ${b}${alpha === void 0 ? "" : ` / ${Number(alpha.toFixed(3))}`})`;
+}
+/** The color a generated color shows as in a gamut. */
+function rendered(color, gamut = "srgb") {
+	return gamut === "p3" ? fromRgb(p3Channels(color), "p3") : oklch(toHex(color));
+}
+/** Part of the way from `a` to `b`, interpolated in OKLab. */
+function mixOklab(a, b, t) {
+	const x = toOklab(a);
+	const y = toOklab(b);
+	return fromOklab([
+		0,
+		1,
+		2
+	].map((i) => x[i] + (y[i] - x[i]) * t));
+}
+/** `rgba()` of a hex color at an alpha. */
+function withAlpha(hex, alpha) {
+	const [r, g, b] = [
+		1,
+		3,
+		5
+	].map((i) => Number.parseInt(hex.slice(i, i + 2), 16));
+	return `rgba(${r}, ${g}, ${b}, ${Number(alpha.toFixed(3))})`;
+}
+/** A color written as a hex, or an `rgba()` over a backdrop, as the hex it shows as. */
+function composite(color, backdrop) {
+	const m = /^rgba\(\s*(\d+),\s*(\d+),\s*(\d+),\s*([\d.]+)\s*\)$/.exec(color.trim());
+	if (!m) return color;
+	const alpha = Number(m[4]);
+	const under = [
+		1,
+		3,
+		5
+	].map((i) => Number.parseInt(backdrop.slice(i, i + 2), 16));
+	return `#${[
+		1,
+		2,
+		3
+	].map((i, k) => Math.round(Number(m[i]) * alpha + under[k] * (1 - alpha)).toString(16).padStart(2, "0")).join("")}`;
+}
+//#endregion
+export { JND, composite, deltaE, fromOklab, fromRgb, gamutMap, mixOklab, oklch, p3Channels, parseColor, rendered, toHex, toOklab, toP3, withAlpha };

package/dist/theme/contrast.d.ts

@@ -0,0 +1,42 @@
+import { type Gamut, type Oklch } from './color.js';
+type Rgb = [number, number, number];
+/** WCAG 2's contrast ratio between two hex colors, 1–21. */
+export declare function contrastRatio(a: string, b: string): number;
+/** Whether a background reads better under white text than black: the theme's mode. */
+export declare function isDarkColor(hex: string): boolean;
+/** APCA lightness contrast of text on a background, as a magnitude 0–~108. */
+export declare function apcaContrast(text: string, background: string): number;
+/** How much contrast a foreground needs: a WCAG 2 ratio and, for text, an APCA Lc. */
+export interface ContrastTarget {
+    wcag: number;
+    apca?: number;
+}
+/** Whether a foreground meets a target on every background it sits on, in sRGB. */
+export declare function meets(fg: string, backgrounds: readonly string[], target: ContrastTarget): boolean;
+/** A color as a screen shows it: channels in the gamut it's written in. */
+export interface Shown {
+    rgb: Rgb;
+    gamut: Gamut;
+}
+/** How a generated color shows when written in a gamut: as a hex for sRGB, as `color(display-p3)` for p3. */
+export declare function shown(color: Oklch, gamut: Gamut): Shown;
+/** A translucent fill over a backdrop, composited in the fill's gamut. */
+export declare function over(fill: Shown, alpha: number, backdrop: Oklch): Shown;
+/** Whether a shown foreground meets a target on every shown background. Each is measured in its own gamut. */
+export declare function meetsIn(fg: Shown, backgrounds: readonly Shown[], target: ContrastTarget): boolean;
+/** How a written color shows: a hex in sRGB, or `color(display-p3 …)` in display-p3. */
+export declare function shownValue(value: string): Shown | null;
+/** Both contrasts of a foreground on a background as written, in whichever gamut each is. */
+export declare function measure(fg: Shown, bg: Shown): {
+    wcag: number;
+    apca: number;
+};
+/**
+ * The color nearest `start` in lightness, at its hue and chroma, that meets
+ * `target` on every background in sRGB. It moves away from the backgrounds
+ * toward black on light grounds and white on dark ones; a color that already
+ * meets the target comes back unchanged, so a brand color is kept wherever it
+ * reads.
+ */
+export declare function solve(start: Oklch, backgrounds: readonly string[], target: ContrastTarget): Oklch;
+export {};

package/dist/theme/contrast.js

@@ -0,0 +1,145 @@
+import { p3Channels, toHex } from "./color.js";
+//#region src/theme/contrast.ts
+var hexChannels = (hex) => [
+	1,
+	3,
+	5
+].map((i) => Number.parseInt(hex.slice(i, i + 2), 16) / 255);
+var WEIGHTS = {
+	srgb: {
+		wcag: [
+			.2126,
+			.7152,
+			.0722
+		],
+		apca: [
+			.2126729,
+			.7151522,
+			.072175
+		]
+	},
+	p3: {
+		wcag: [
+			.2289745641,
+			.6917385218,
+			.0792869141
+		],
+		apca: [
+			.2289829595,
+			.6917492626,
+			.0792677779
+		]
+	}
+};
+function luminance(rgb, gamut) {
+	const w = WEIGHTS[gamut].wcag;
+	return rgb.reduce((sum, v, i) => sum + w[i] * (v <= .04045 ? v / 12.92 : ((v + .055) / 1.055) ** 2.4), 0);
+}
+function ratio(la, lb) {
+	const [hi, lo] = la > lb ? [la, lb] : [lb, la];
+	return (hi + .05) / (lo + .05);
+}
+var cache = /* @__PURE__ */ new Map();
+function cachedLuminance(hex) {
+	let v = cache.get(hex);
+	if (v === void 0) {
+		if (cache.size > 4096) cache.clear();
+		v = luminance(hexChannels(hex), "srgb");
+		cache.set(hex, v);
+	}
+	return v;
+}
+/** WCAG 2's contrast ratio between two hex colors, 1–21. */
+function contrastRatio(a, b) {
+	return ratio(cachedLuminance(a), cachedLuminance(b));
+}
+/** Whether a background reads better under white text than black: the theme's mode. */
+function isDarkColor(hex) {
+	return contrastRatio(hex, "#ffffff") >= contrastRatio(hex, "#000000");
+}
+var APCA = {
+	exponent: 2.4,
+	normBg: .56,
+	normText: .57,
+	revText: .62,
+	revBg: .65,
+	blackThreshold: .022,
+	blackClamp: 1.414,
+	scale: 1.14,
+	offset: .027,
+	minDeltaY: 5e-4,
+	clip: .1
+};
+function apcaY(rgb, gamut) {
+	const w = WEIGHTS[gamut].apca;
+	const y = rgb.reduce((sum, v, i) => sum + w[i] * Math.max(0, v) ** APCA.exponent, 0);
+	return y > APCA.blackThreshold ? y : y + (APCA.blackThreshold - y) ** APCA.blackClamp;
+}
+function lc(yText, yBg) {
+	if (Math.abs(yBg - yText) < APCA.minDeltaY) return 0;
+	if (yBg > yText) {
+		const sapc = (yBg ** APCA.normBg - yText ** APCA.normText) * APCA.scale;
+		return sapc < APCA.clip ? 0 : (sapc - APCA.offset) * 100;
+	}
+	const sapc = (yBg ** APCA.revBg - yText ** APCA.revText) * APCA.scale;
+	return sapc > -APCA.clip ? 0 : -(sapc + APCA.offset) * 100;
+}
+/** APCA lightness contrast of text on a background, as a magnitude 0–~108. */
+function apcaContrast(text, background) {
+	return lc(apcaY(hexChannels(text), "srgb"), apcaY(hexChannels(background), "srgb"));
+}
+/** Whether a foreground meets a target on every background it sits on, in sRGB. */
+function meets(fg, backgrounds, target) {
+	return backgrounds.every((bg) => contrastRatio(fg, bg) >= target.wcag && (target.apca === void 0 || apcaContrast(fg, bg) >= target.apca));
+}
+/** How a generated color shows when written in a gamut: as a hex for sRGB, as `color(display-p3)` for p3. */
+function shown(color, gamut) {
+	return {
+		rgb: gamut === "p3" ? p3Channels(color) : hexChannels(toHex(color)),
+		gamut
+	};
+}
+/** A translucent fill over a backdrop, composited in the fill's gamut. */
+function over(fill, alpha, backdrop) {
+	const under = shown(backdrop, fill.gamut).rgb;
+	return {
+		rgb: fill.rgb.map((v, i) => v * alpha + under[i] * (1 - alpha)),
+		gamut: fill.gamut
+	};
+}
+/** Whether a shown foreground meets a target on every shown background. Each is measured in its own gamut. */
+function meetsIn(fg, backgrounds, target) {
+	const yWcag = luminance(fg.rgb, fg.gamut);
+	const yApca = apcaY(fg.rgb, fg.gamut);
+	return backgrounds.every((bg) => ratio(yWcag, luminance(bg.rgb, bg.gamut)) >= target.wcag - 1e-9 && (target.apca === void 0 || lc(yApca, apcaY(bg.rgb, bg.gamut)) >= target.apca - 1e-9));
+}
+/**
+* The color nearest `start` in lightness, at its hue and chroma, that meets
+* `target` on every background in sRGB. It moves away from the backgrounds
+* toward black on light grounds and white on dark ones; a color that already
+* meets the target comes back unchanged, so a brand color is kept wherever it
+* reads.
+*/
+function solve(start, backgrounds, target) {
+	if (meets(toHex(start), backgrounds, target)) return start;
+	const pole = isDarkColor(backgrounds[0] ?? "#ffffff") ? 1 : 0;
+	const at = (t) => ({
+		...start,
+		l: start.l + (pole - start.l) * t
+	});
+	if (!meets(toHex(at(1)), backgrounds, target)) return {
+		l: pole,
+		c: 0,
+		h: 0
+	};
+	let lo = 0;
+	let hi = 1;
+	while (hi - lo > .002) {
+		const mid = (lo + hi) / 2;
+		if (meets(toHex(at(mid)), backgrounds, target)) hi = mid;
+		else lo = mid;
+	}
+	return at(hi);
+}
+//#endregion
+export { apcaContrast, contrastRatio, isDarkColor, meets, meetsIn, over, shown, solve };

package/dist/theme/derive.d.ts

@@ -0,0 +1,25 @@
+import { type CodeStyle, type Scheme } from './model.js';
+export declare const THEME_TOKENS: readonly ['--theme-app-bg', '--theme-panel-bg', '--theme-panel-hover', '--theme-muted-panel-bg', '--theme-hover', '--theme-input-bg', '--theme-input-disabled-bg', '--theme-app', '--theme-muted-text-color', '--theme-placeholder', '--theme-link', '--theme-border', '--theme-border-strong', '--theme-accent', '--theme-accent-text', '--theme-accent-hover', '--theme-accent-subtle', '--theme-focus', '--theme-focus-ring', '--theme-success', '--theme-success-muted', '--theme-error', '--theme-error-muted', '--theme-warning', '--theme-warning-muted', '--theme-info', '--theme-info-muted', '--theme-favorite', '--theme-favorite-muted', '--theme-shadow-sm', '--theme-shadow', '--theme-shadow-lg', '--theme-shadow-xl', '--theme-sidebar-bg', '--theme-sidebar-text', '--theme-sidebar-hover', '--theme-sidebar-active-bg', '--theme-sidebar-active-text', '--theme-code-bg', '--theme-code-text', '--theme-code-comment', '--theme-code-keyword', '--theme-code-string', '--theme-code-number', '--theme-code-function', '--theme-code-type', '--theme-code-property', '--theme-ansi-black', '--theme-ansi-red', '--theme-ansi-green', '--theme-ansi-yellow', '--theme-ansi-blue', '--theme-ansi-magenta', '--theme-ansi-cyan', '--theme-ansi-white'];
+export type ThemeToken = (typeof THEME_TOKENS)[number];
+export type ThemeVariables = Record<ThemeToken, string>;
+/** The tokens the sidebar owns. A host's chrome may supply its own fallbacks, so the stylesheet gives them no defaults. */
+export declare const SIDEBAR_TOKENS: readonly ThemeToken[];
+/** A theme as both outputs: every token in sRGB, and the tokens a display-p3 screen shows noticeably more of. */
+export interface GeneratedTheme {
+    srgb: ThemeVariables;
+    /** `color(display-p3 …)` for the tokens whose display-p3 mapping is more than one just-noticeable difference from their sRGB one. */
+    p3: Partial<ThemeVariables>;
+}
+export interface DeriveOptions {
+    /** How the code theme colors syntax. */
+    code?: CodeStyle;
+}
+/** Every token as sRGB, plus display-p3 overrides that keep every contrast the sRGB output meets. */
+export declare function generateTheme(scheme: Scheme, options?: DeriveOptions): GeneratedTheme;
+/** Every `--theme-*` token for a scheme, in sRGB. */
+export declare function deriveTheme(scheme: Scheme, options?: DeriveOptions): ThemeVariables;
+/** A stylesheet for a scheme: sRGB under `selector`, and the display-p3 overrides under
+ *  `@media (color-gamut: p3)`. `omit` leaves tokens out, such as ones a host supplies. */
+export declare function themeStylesheet(selector: string, scheme: Scheme, options?: DeriveOptions & {
+    omit?: readonly ThemeToken[];
+}): string;