@crewhaus/tool-media 0.7.0

package/dist/lib/chart.js

@@ -0,0 +1,290 @@
+/**
+ * Bar, line, scatter and pie charts, laid out and emitted as SVG.
+ *
+ * The layout is arithmetic on the data plus a handful of fixed constants —
+ * no measurement, no iteration to convergence, no randomness — so the same
+ * spec renders byte-identical SVG on every machine. The one approximation
+ * is label width (see `estimateTextWidth`), which is deliberately an
+ * estimate so it cannot vary with installed fonts.
+ */
+import { MediaFormatError } from "./bytes";
+import { FONT_STACK, circle, escapeXml, estimateTextWidth, formatValue, line, niceScale, num, paletteColor, polyline, rect, svgDocument, text, } from "./svg";
+const AXIS = "#8a919b";
+const GRID = "#e2e5ea";
+const INK = "#1f2329";
+const MUTED = "#5a6069";
+const TITLE_SIZE = 16;
+const LABEL_SIZE = 12;
+const TICK_SIZE = 11;
+function colorAt(spec, index) {
+    const custom = spec.colors?.[index % Math.max(1, spec.colors.length)];
+    return custom ?? paletteColor(index);
+}
+function requireFinite(values, what) {
+    for (const value of values) {
+        if (!Number.isFinite(value))
+            throw new MediaFormatError(`${what} contains ${value}`);
+    }
+}
+/** Legend rows, laid out in one horizontal strip under the plot. */
+function legendStrip(names, spec, y, width) {
+    const out = [];
+    const swatch = 10;
+    const gap = 16;
+    const widths = names.map((name) => swatch + 5 + estimateTextWidth(name, LABEL_SIZE));
+    const total = widths.reduce((a, b) => a + b, 0) + gap * Math.max(0, names.length - 1);
+    let x = Math.max(8, (width - total) / 2);
+    for (let i = 0; i < names.length; i++) {
+        out.push(rect(x, y - swatch + 2, swatch, swatch, colorAt(spec, i), 'rx="2"'));
+        out.push(text(x + swatch + 5, y, names[i], LABEL_SIZE, { fill: MUTED }));
+        x += widths[i] + gap;
+    }
+    return out;
+}
+/** Margins, derived from what the chart actually has to show. */
+function plotArea(spec, yTickLabels, legendRows) {
+    const widest = yTickLabels.reduce((w, label) => Math.max(w, estimateTextWidth(label, TICK_SIZE)), 0);
+    const left = Math.ceil(12 + widest + 8 + (spec.yLabel === undefined ? 0 : LABEL_SIZE + 6));
+    const top = spec.title === undefined ? 16 : 16 + TITLE_SIZE + 10;
+    const bottom = 16 + TICK_SIZE + 8 + (spec.xLabel === undefined ? 0 : LABEL_SIZE + 6) + legendRows * 22;
+    return { left, top, right: spec.width - 16, bottom: spec.height - bottom };
+}
+function axisFrame(spec, plot, yTicks, yMin, yMax) {
+    const out = [];
+    const span = yMax - yMin;
+    for (const tick of yTicks) {
+        const y = plot.bottom - ((tick - yMin) / span) * (plot.bottom - plot.top);
+        out.push(line(plot.left, y, plot.right, y, GRID, 1));
+        out.push(text(plot.left - 6, y, formatValue(tick), TICK_SIZE, {
+            fill: MUTED,
+            anchor: "end",
+            baseline: "middle",
+        }));
+    }
+    out.push(line(plot.left, plot.top, plot.left, plot.bottom, AXIS, 1));
+    out.push(line(plot.left, plot.bottom, plot.right, plot.bottom, AXIS, 1));
+    if (spec.yLabel !== undefined) {
+        const cx = 14;
+        const cy = (plot.top + plot.bottom) / 2;
+        out.push(`<g transform="rotate(-90 ${num(cx)} ${num(cy)})">${text(cx, cy, spec.yLabel, LABEL_SIZE, { fill: MUTED, anchor: "middle", baseline: "middle" })}</g>`);
+    }
+    return out;
+}
+function renderBar(spec) {
+    const categories = spec.categories ?? [];
+    const series = spec.series ?? [];
+    if (categories.length === 0)
+        throw new MediaFormatError("a bar chart needs `categories`");
+    if (series.length === 0)
+        throw new MediaFormatError("a bar chart needs at least one series");
+    for (const s of series) {
+        if (s.values === undefined) {
+            throw new MediaFormatError(`bar series "${s.name}" needs \`values\``);
+        }
+        if (s.values.length !== categories.length) {
+            throw new MediaFormatError(`bar series "${s.name}" has ${s.values.length} values but there are ${categories.length} categories`);
+        }
+        requireFinite(s.values, `bar series "${s.name}"`);
+    }
+    const stacked = spec.stacked === true && series.length > 1;
+    const columnTotals = categories.map((_, i) => series.reduce((sum, s) => sum + s.values[i], 0));
+    const flat = series.flatMap((s) => [...s.values]);
+    const dataMin = stacked ? Math.min(0, ...columnTotals) : Math.min(0, ...flat);
+    const dataMax = stacked ? Math.max(0, ...columnTotals) : Math.max(0, ...flat);
+    const scale = niceScale(dataMin, dataMax, 5);
+    const legendRows = (spec.legend ?? series.length > 1) ? 1 : 0;
+    const plot = plotArea(spec, scale.ticks.map(formatValue), legendRows);
+    const body = [];
+    if (spec.title !== undefined) {
+        body.push(text(spec.width / 2, 16 + TITLE_SIZE, spec.title, TITLE_SIZE, {
+            fill: INK,
+            anchor: "middle",
+            weight: "bold",
+        }));
+    }
+    body.push(...axisFrame(spec, plot, scale.ticks, scale.min, scale.max));
+    const plotWidth = plot.right - plot.left;
+    const plotHeight = plot.bottom - plot.top;
+    const span = scale.max - scale.min;
+    const slot = plotWidth / categories.length;
+    const bandPadding = Math.min(12, slot * 0.2);
+    const band = slot - bandPadding;
+    const barWidth = stacked ? band : band / series.length;
+    const zeroY = plot.bottom - ((0 - scale.min) / span) * plotHeight;
+    for (let c = 0; c < categories.length; c++) {
+        const slotLeft = plot.left + c * slot + bandPadding / 2;
+        let stackTop = 0;
+        let stackBottom = 0;
+        for (let s = 0; s < series.length; s++) {
+            const value = (series[s]?.values)[c];
+            let y0;
+            let y1;
+            if (stacked) {
+                const base = value >= 0 ? stackTop : stackBottom;
+                const tip = base + value;
+                if (value >= 0)
+                    stackTop = tip;
+                else
+                    stackBottom = tip;
+                y0 = plot.bottom - ((Math.max(base, tip) - scale.min) / span) * plotHeight;
+                y1 = plot.bottom - ((Math.min(base, tip) - scale.min) / span) * plotHeight;
+            }
+            else {
+                const valueY = plot.bottom - ((value - scale.min) / span) * plotHeight;
+                y0 = Math.min(valueY, zeroY);
+                y1 = Math.max(valueY, zeroY);
+            }
+            const x = stacked ? slotLeft : slotLeft + s * barWidth;
+            body.push(rect(x, y0, Math.max(1, barWidth - (stacked ? 0 : 1)), Math.max(0, y1 - y0), colorAt(spec, s)));
+        }
+        body.push(text(slotLeft + band / 2, plot.bottom + TICK_SIZE + 6, categories[c], TICK_SIZE, {
+            fill: MUTED,
+            anchor: "middle",
+        }));
+    }
+    if (spec.xLabel !== undefined) {
+        body.push(text((plot.left + plot.right) / 2, plot.bottom + TICK_SIZE + 6 + LABEL_SIZE + 6, spec.xLabel, LABEL_SIZE, { fill: MUTED, anchor: "middle" }));
+    }
+    if (legendRows > 0) {
+        body.push(...legendStrip(series.map((s) => s.name), spec, spec.height - 12, spec.width));
+    }
+    return svgDocument(spec.width, spec.height, spec.background ?? "#ffffff", body, spec.title);
+}
+function renderXy(spec, mode) {
+    const series = spec.series ?? [];
+    if (series.length === 0)
+        throw new MediaFormatError(`a ${mode} chart needs at least one series`);
+    for (const s of series) {
+        if (s.points === undefined || s.points.length === 0) {
+            throw new MediaFormatError(`${mode} series "${s.name}" needs a non-empty \`points\` array`);
+        }
+        requireFinite(s.points.flatMap((p) => [p[0], p[1]]), `${mode} series "${s.name}"`);
+    }
+    const xs = series.flatMap((s) => s.points.map((p) => p[0]));
+    const ys = series.flatMap((s) => s.points.map((p) => p[1]));
+    const xScale = niceScale(Math.min(...xs), Math.max(...xs), 6);
+    const yScale = niceScale(Math.min(...ys), Math.max(...ys), 5);
+    const legendRows = (spec.legend ?? series.length > 1) ? 1 : 0;
+    const plot = plotArea(spec, yScale.ticks.map(formatValue), legendRows);
+    const body = [];
+    if (spec.title !== undefined) {
+        body.push(text(spec.width / 2, 16 + TITLE_SIZE, spec.title, TITLE_SIZE, {
+            fill: INK,
+            anchor: "middle",
+            weight: "bold",
+        }));
+    }
+    body.push(...axisFrame(spec, plot, yScale.ticks, yScale.min, yScale.max));
+    const toX = (value) => plot.left + ((value - xScale.min) / (xScale.max - xScale.min)) * (plot.right - plot.left);
+    const toY = (value) => plot.bottom - ((value - yScale.min) / (yScale.max - yScale.min)) * (plot.bottom - plot.top);
+    for (const tick of xScale.ticks) {
+        body.push(text(toX(tick), plot.bottom + TICK_SIZE + 6, formatValue(tick), TICK_SIZE, {
+            fill: MUTED,
+            anchor: "middle",
+        }));
+    }
+    for (let s = 0; s < series.length; s++) {
+        const points = series[s]?.points;
+        // Sorted by x so a line never doubles back on itself for the same data
+        // given in a different order — the same series always draws the same.
+        const ordered = [...points].sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+        const mapped = ordered.map((p) => [toX(p[0]), toY(p[1])]);
+        const color = colorAt(spec, s);
+        if (mode === "line") {
+            body.push(polyline(mapped, color, 2));
+            for (const [x, y] of mapped)
+                body.push(circle(x, y, 2.5, color));
+        }
+        else {
+            for (const [x, y] of mapped)
+                body.push(circle(x, y, 3.5, color));
+        }
+    }
+    if (spec.xLabel !== undefined) {
+        body.push(text((plot.left + plot.right) / 2, plot.bottom + TICK_SIZE + 6 + LABEL_SIZE + 6, spec.xLabel, LABEL_SIZE, { fill: MUTED, anchor: "middle" }));
+    }
+    if (legendRows > 0) {
+        body.push(...legendStrip(series.map((s) => s.name), spec, spec.height - 12, spec.width));
+    }
+    return svgDocument(spec.width, spec.height, spec.background ?? "#ffffff", body, spec.title);
+}
+function renderPie(spec) {
+    const slices = spec.slices ?? [];
+    if (slices.length === 0)
+        throw new MediaFormatError("a pie chart needs `slices`");
+    requireFinite(slices.map((s) => s.value), "pie slices");
+    for (const slice of slices) {
+        if (slice.value < 0) {
+            throw new MediaFormatError(`slice "${slice.label}" is ${slice.value}; a pie cannot show a negative share`);
+        }
+    }
+    const total = slices.reduce((sum, s) => sum + s.value, 0);
+    if (total <= 0)
+        throw new MediaFormatError("every slice is zero, so there is no pie to draw");
+    const body = [];
+    const top = spec.title === undefined ? 16 : 16 + TITLE_SIZE + 10;
+    if (spec.title !== undefined) {
+        body.push(text(spec.width / 2, 16 + TITLE_SIZE, spec.title, TITLE_SIZE, {
+            fill: INK,
+            anchor: "middle",
+            weight: "bold",
+        }));
+    }
+    const legendHeight = 22 * Math.ceil(slices.length / 3) + 8;
+    const available = spec.height - top - legendHeight - 12;
+    const radius = Math.max(10, Math.min(available, spec.width - 32) / 2);
+    const cx = spec.width / 2;
+    const cy = top + available / 2;
+    let angle = -Math.PI / 2; // start at twelve o'clock
+    for (let i = 0; i < slices.length; i++) {
+        const slice = slices[i];
+        const sweep = (slice.value / total) * Math.PI * 2;
+        const color = colorAt(spec, i);
+        if (sweep <= 0)
+            continue;
+        if (sweep >= Math.PI * 2 - 1e-9) {
+            body.push(circle(cx, cy, radius, color));
+        }
+        else {
+            const x0 = cx + radius * Math.cos(angle);
+            const y0 = cy + radius * Math.sin(angle);
+            const x1 = cx + radius * Math.cos(angle + sweep);
+            const y1 = cy + radius * Math.sin(angle + sweep);
+            const largeArc = sweep > Math.PI ? 1 : 0;
+            body.push(`<path d="M ${num(cx)} ${num(cy)} L ${num(x0)} ${num(y0)} A ${num(radius)} ${num(radius)} 0 ${largeArc} 1 ${num(x1)} ${num(y1)} Z" fill="${escapeXml(color)}"/>`);
+        }
+        angle += sweep;
+    }
+    // Legend: three columns, each row a swatch, a label and the share.
+    const columns = Math.min(3, slices.length);
+    const columnWidth = (spec.width - 32) / columns;
+    for (let i = 0; i < slices.length; i++) {
+        const slice = slices[i];
+        const column = i % columns;
+        const row = Math.floor(i / columns);
+        const x = 16 + column * columnWidth;
+        const y = spec.height - legendHeight + 12 + row * 22;
+        const percent = Math.round((slice.value / total) * 1000) / 10;
+        body.push(rect(x, y - 9, 10, 10, colorAt(spec, i), 'rx="2"'));
+        body.push(text(x + 15, y, `${slice.label} (${num(percent)}%)`, LABEL_SIZE, { fill: MUTED }));
+    }
+    return svgDocument(spec.width, spec.height, spec.background ?? "#ffffff", body, spec.title);
+}
+/** The font stack the renderers name, re-exported for the tests. */
+export const CHART_FONT_STACK = FONT_STACK;
+/** Render a chart spec to a complete SVG document. */
+export function renderChart(spec) {
+    if (spec.width < 120 || spec.height < 80) {
+        throw new MediaFormatError(`${spec.width}x${spec.height} is too small to draw a readable chart`);
+    }
+    switch (spec.type) {
+        case "bar":
+            return renderBar(spec);
+        case "line":
+            return renderXy(spec, "line");
+        case "scatter":
+            return renderXy(spec, "scatter");
+        case "pie":
+            return renderPie(spec);
+    }
+}

package/dist/lib/color.d.ts

@@ -0,0 +1,53 @@
+export type Rgb = {
+    readonly r: number;
+    readonly g: number;
+    readonly b: number;
+    readonly a: number;
+};
+/** Colour keywords this package accepts, sorted. */
+export declare function colorKeywords(): ReadonlyArray<string>;
+/**
+ * Parse `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `rgb()`, `rgba()`, `hsl()`,
+ * `hsla()` or one of the basic colour keywords. Throws `MediaFormatError`
+ * with the offending text on anything else.
+ */
+export declare function parseColor(input: string): Rgb;
+/** HSL with hue in degrees and saturation/lightness in percent, to 8-bit RGB. */
+export declare function hslToRgb(h: number, s: number, l: number): {
+    r: number;
+    g: number;
+    b: number;
+};
+/** 8-bit RGB to HSL, hue in degrees, saturation and lightness in percent. */
+export declare function rgbToHsl(r: number, g: number, b: number): {
+    h: number;
+    s: number;
+    l: number;
+};
+/** `#rrggbb`, or `#rrggbbaa` when the colour is not fully opaque. */
+export declare function toHexString(color: Rgb): string;
+/** WCAG 2.x relative luminance of an opaque sRGB colour. */
+export declare function relativeLuminance(r: number, g: number, b: number): number;
+/**
+ * Composite a possibly-translucent colour over an opaque backdrop. WCAG's
+ * ratio is defined for opaque colours only, so a caller passing `#0008`
+ * gets a defensible answer rather than a wrong one.
+ */
+export declare function compositeOver(top: Rgb, backdrop: Rgb): Rgb;
+export type ContrastReport = {
+    readonly ratio: number;
+    readonly foreground: string;
+    readonly background: string;
+    readonly normalTextAA: boolean;
+    readonly normalTextAAA: boolean;
+    readonly largeTextAA: boolean;
+    readonly largeTextAAA: boolean;
+    readonly uiComponentAA: boolean;
+    /** The highest level the pair clears for body text. */
+    readonly verdict: "AAA" | "AA" | "AA-large-only" | "fail";
+};
+/**
+ * Contrast ratio and the levels it clears. "Large" text is WCAG's own
+ * definition: at least 18pt, or 14pt bold.
+ */
+export declare function contrastReport(foreground: Rgb, background: Rgb): ContrastReport;

package/dist/lib/color.js

@@ -0,0 +1,267 @@
+/**
+ * Colour parsing, conversion and the WCAG contrast check.
+ *
+ * The contrast maths is WCAG 2.x (the version every audit tool and every
+ * procurement checklist still keys on): sRGB channels linearised with the
+ * 0.03928 piecewise curve, luminance weighted 0.2126/0.7152/0.0722, ratio
+ * `(lighter + 0.05) / (darker + 0.05)`.
+ */
+import { MediaFormatError } from "./bytes";
+const HEX3 = /^#?([0-9a-f])([0-9a-f])([0-9a-f])$/i;
+const HEX4 = /^#?([0-9a-f])([0-9a-f])([0-9a-f])([0-9a-f])$/i;
+const HEX6 = /^#?([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i;
+const HEX8 = /^#?([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i;
+const RGB_FN = /^rgba?\(\s*([^)]+)\)$/i;
+const HSL_FN = /^hsla?\(\s*([^)]+)\)$/i;
+/**
+ * The 16 colour keywords every CSS level has had, lowercase. The full
+ * 148-name list is deliberately not carried here: a caller who means
+ * `rebeccapurple` can write `#663399`, and a half-remembered table is
+ * worse than none.
+ */
+const KEYWORDS = Object.freeze({
+    black: "#000000",
+    silver: "#c0c0c0",
+    gray: "#808080",
+    grey: "#808080",
+    white: "#ffffff",
+    maroon: "#800000",
+    red: "#ff0000",
+    purple: "#800080",
+    fuchsia: "#ff00ff",
+    green: "#008000",
+    lime: "#00ff00",
+    olive: "#808000",
+    yellow: "#ffff00",
+    navy: "#000080",
+    blue: "#0000ff",
+    teal: "#008080",
+    aqua: "#00ffff",
+    transparent: "#00000000",
+});
+/** Colour keywords this package accepts, sorted. */
+export function colorKeywords() {
+    return Object.keys(KEYWORDS).sort();
+}
+function clamp(value, low, high) {
+    return value < low ? low : value > high ? high : value;
+}
+function channel(text) {
+    const trimmed = text.trim();
+    if (trimmed.endsWith("%")) {
+        const pct = Number.parseFloat(trimmed.slice(0, -1));
+        if (Number.isNaN(pct))
+            throw new MediaFormatError(`"${text}" is not a percentage`);
+        return clamp(Math.round((pct / 100) * 255), 0, 255);
+    }
+    const value = Number.parseFloat(trimmed);
+    if (Number.isNaN(value))
+        throw new MediaFormatError(`"${text}" is not a channel value`);
+    return clamp(Math.round(value), 0, 255);
+}
+function alphaValue(text) {
+    if (text === undefined)
+        return 255;
+    const trimmed = text.trim();
+    const raw = trimmed.endsWith("%")
+        ? Number.parseFloat(trimmed.slice(0, -1)) / 100
+        : Number.parseFloat(trimmed);
+    if (Number.isNaN(raw))
+        throw new MediaFormatError(`"${text}" is not an alpha value`);
+    return clamp(Math.round(raw * 255), 0, 255);
+}
+/**
+ * Parse `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `rgb()`, `rgba()`, `hsl()`,
+ * `hsla()` or one of the basic colour keywords. Throws `MediaFormatError`
+ * with the offending text on anything else.
+ */
+export function parseColor(input) {
+    const text = input.trim();
+    const keyword = KEYWORDS[text.toLowerCase()];
+    if (keyword !== undefined)
+        return parseColor(keyword);
+    const hex8 = HEX8.exec(text);
+    if (hex8) {
+        return {
+            r: Number.parseInt(hex8[1], 16),
+            g: Number.parseInt(hex8[2], 16),
+            b: Number.parseInt(hex8[3], 16),
+            a: Number.parseInt(hex8[4], 16),
+        };
+    }
+    const hex6 = HEX6.exec(text);
+    if (hex6) {
+        return {
+            r: Number.parseInt(hex6[1], 16),
+            g: Number.parseInt(hex6[2], 16),
+            b: Number.parseInt(hex6[3], 16),
+            a: 255,
+        };
+    }
+    const hex4 = HEX4.exec(text);
+    if (hex4) {
+        const double = (d) => Number.parseInt(d + d, 16);
+        return {
+            r: double(hex4[1]),
+            g: double(hex4[2]),
+            b: double(hex4[3]),
+            a: double(hex4[4]),
+        };
+    }
+    const hex3 = HEX3.exec(text);
+    if (hex3) {
+        const double = (d) => Number.parseInt(d + d, 16);
+        return {
+            r: double(hex3[1]),
+            g: double(hex3[2]),
+            b: double(hex3[3]),
+            a: 255,
+        };
+    }
+    const rgbFn = RGB_FN.exec(text);
+    if (rgbFn) {
+        const parts = rgbFn[1]
+            .split(/[,/]/)
+            .map((p) => p.trim())
+            .filter((p) => p !== "");
+        if (parts.length < 3)
+            throw new MediaFormatError(`"${input}" needs three channels`);
+        return {
+            r: channel(parts[0]),
+            g: channel(parts[1]),
+            b: channel(parts[2]),
+            a: alphaValue(parts[3]),
+        };
+    }
+    const hslFn = HSL_FN.exec(text);
+    if (hslFn) {
+        const parts = hslFn[1]
+            .split(/[,/]/)
+            .map((p) => p.trim())
+            .filter((p) => p !== "");
+        if (parts.length < 3)
+            throw new MediaFormatError(`"${input}" needs hue, saturation and lightness`);
+        const h = Number.parseFloat(parts[0].replace(/deg$/i, ""));
+        const s = Number.parseFloat(parts[1].replace(/%$/, ""));
+        const l = Number.parseFloat(parts[2].replace(/%$/, ""));
+        if (Number.isNaN(h) || Number.isNaN(s) || Number.isNaN(l)) {
+            throw new MediaFormatError(`"${input}" has a component that is not a number`);
+        }
+        return { ...hslToRgb(h, s, l), a: alphaValue(parts[3]) };
+    }
+    throw new MediaFormatError(`"${input}" is not a colour this package reads (hex, rgb(), hsl(), or a basic keyword)`);
+}
+/** HSL with hue in degrees and saturation/lightness in percent, to 8-bit RGB. */
+export function hslToRgb(h, s, l) {
+    const hue = ((h % 360) + 360) % 360;
+    const sat = clamp(s, 0, 100) / 100;
+    const light = clamp(l, 0, 100) / 100;
+    const c = (1 - Math.abs(2 * light - 1)) * sat;
+    const hp = hue / 60;
+    const x = c * (1 - Math.abs((hp % 2) - 1));
+    let r = 0;
+    let g = 0;
+    let b = 0;
+    if (hp < 1)
+        [r, g, b] = [c, x, 0];
+    else if (hp < 2)
+        [r, g, b] = [x, c, 0];
+    else if (hp < 3)
+        [r, g, b] = [0, c, x];
+    else if (hp < 4)
+        [r, g, b] = [0, x, c];
+    else if (hp < 5)
+        [r, g, b] = [x, 0, c];
+    else
+        [r, g, b] = [c, 0, x];
+    const m = light - c / 2;
+    return {
+        r: Math.round((r + m) * 255),
+        g: Math.round((g + m) * 255),
+        b: Math.round((b + m) * 255),
+    };
+}
+/** 8-bit RGB to HSL, hue in degrees, saturation and lightness in percent. */
+export function rgbToHsl(r, g, b) {
+    const rn = r / 255;
+    const gn = g / 255;
+    const bn = b / 255;
+    const max = Math.max(rn, gn, bn);
+    const min = Math.min(rn, gn, bn);
+    const l = (max + min) / 2;
+    const d = max - min;
+    let h = 0;
+    let s = 0;
+    if (d !== 0) {
+        s = d / (1 - Math.abs(2 * l - 1));
+        if (max === rn)
+            h = ((gn - bn) / d) % 6;
+        else if (max === gn)
+            h = (bn - rn) / d + 2;
+        else
+            h = (rn - gn) / d + 4;
+        h *= 60;
+        if (h < 0)
+            h += 360;
+    }
+    const round1 = (v) => Math.round(v * 10) / 10;
+    return { h: round1(h), s: round1(s * 100), l: round1(l * 100) };
+}
+/** `#rrggbb`, or `#rrggbbaa` when the colour is not fully opaque. */
+export function toHexString(color) {
+    const pair = (v) => v.toString(16).padStart(2, "0");
+    const base = `#${pair(color.r)}${pair(color.g)}${pair(color.b)}`;
+    return color.a === 255 ? base : `${base}${pair(color.a)}`;
+}
+/** WCAG 2.x relative luminance of an opaque sRGB colour. */
+export function relativeLuminance(r, g, b) {
+    const linear = (value) => {
+        const c = value / 255;
+        return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+    };
+    return 0.2126 * linear(r) + 0.7152 * linear(g) + 0.0722 * linear(b);
+}
+/**
+ * Composite a possibly-translucent colour over an opaque backdrop. WCAG's
+ * ratio is defined for opaque colours only, so a caller passing `#0008`
+ * gets a defensible answer rather than a wrong one.
+ */
+export function compositeOver(top, backdrop) {
+    const alpha = top.a / 255;
+    const mix = (t, b) => Math.round(t * alpha + b * (1 - alpha));
+    return {
+        r: mix(top.r, backdrop.r),
+        g: mix(top.g, backdrop.g),
+        b: mix(top.b, backdrop.b),
+        a: 255,
+    };
+}
+/**
+ * Contrast ratio and the levels it clears. "Large" text is WCAG's own
+ * definition: at least 18pt, or 14pt bold.
+ */
+export function contrastReport(foreground, background) {
+    const bg = background.a === 255
+        ? background
+        : compositeOver(background, { r: 255, g: 255, b: 255, a: 255 });
+    const fg = foreground.a === 255 ? foreground : compositeOver(foreground, bg);
+    const lf = relativeLuminance(fg.r, fg.g, fg.b);
+    const lb = relativeLuminance(bg.r, bg.g, bg.b);
+    const lighter = Math.max(lf, lb);
+    const darker = Math.min(lf, lb);
+    const raw = (lighter + 0.05) / (darker + 0.05);
+    // Two decimal places is what every accessibility report quotes, and it
+    // keeps the number stable against floating-point noise.
+    const ratio = Math.round(raw * 100) / 100;
+    return {
+        ratio,
+        foreground: toHexString(fg),
+        background: toHexString(bg),
+        normalTextAA: ratio >= 4.5,
+        normalTextAAA: ratio >= 7,
+        largeTextAA: ratio >= 3,
+        largeTextAAA: ratio >= 4.5,
+        uiComponentAA: ratio >= 3,
+        verdict: ratio >= 7 ? "AAA" : ratio >= 4.5 ? "AA" : ratio >= 3 ? "AA-large-only" : "fail",
+    };
+}

package/dist/lib/diagram.d.ts

@@ -0,0 +1,48 @@
+export type DiagramNode = {
+    readonly id: string;
+    readonly label?: string;
+};
+export type DiagramEdge = {
+    readonly from: string;
+    readonly to: string;
+    readonly label?: string;
+};
+export type DiagramSpec = {
+    readonly nodes: ReadonlyArray<DiagramNode>;
+    readonly edges: ReadonlyArray<DiagramEdge>;
+    /** `"TB"` stacks layers downward; `"LR"` runs them left to right. */
+    readonly direction?: "TB" | "LR";
+    readonly title?: string;
+    readonly background?: string;
+    readonly nodeFill?: string;
+    readonly nodeStroke?: string;
+};
+export type DiagramResult = {
+    readonly svg: string;
+    readonly width: number;
+    readonly height: number;
+    /** Layer index per node id, in declaration order. */
+    readonly layers: ReadonlyArray<{
+        id: string;
+        layer: number;
+    }>;
+    /** Edges that close a cycle: drawn dashed, and not used for layering. */
+    readonly backEdges: ReadonlyArray<{
+        from: string;
+        to: string;
+    }>;
+};
+/**
+ * Layer assignment. A depth-first pass in declaration order finds the edges
+ * that close a cycle; the rest form a DAG, and each node's layer is one
+ * past its deepest remaining predecessor.
+ */
+export declare function assignLayers(nodes: ReadonlyArray<DiagramNode>, edges: ReadonlyArray<DiagramEdge>): {
+    layers: Map<string, number>;
+    backEdges: Array<{
+        from: string;
+        to: string;
+    }>;
+};
+/** Render a node and edge list to SVG with a layered layout. */
+export declare function renderDiagram(spec: DiagramSpec): DiagramResult;