@usableapp/cardds 0.7.95 → 0.7.96

package/dist/cards/cardGrounds.d.ts

@@ -0,0 +1,22 @@
+export type CardGround = {
+    /** where the card stands: the screen (`--surface`), a sheet's body (`--card-1-bg`, a `Sheet`'s default tone), a `paper` sheet's body (`--color-paper`) */
+    ground: 'screen' | 'sheet' | 'paper sheet';
+    tone: 1 | 2 | 3 | 4 | 5;
+    /** the card's fill against its ground, as a contrast ratio (1–21) */
+    fill: number;
+    /** the strongest hard edge (its border, or a shadow with no blur) against the ground; 1 when it has none */
+    edge: number;
+    /** fill or edge reaches 3:1 (WCAG 2.2 SC 1.4.11, non-text contrast) */
+    pass: boolean;
+    /** what fails and which tokens to move, by how much; empty when it passes */
+    problem: string;
+};
+/**
+ * Can the member see each card's boundary? Builds a card of every tone (1–5) on each ground a card stands on (the screen, a
+ * sheet's body, a `paper` sheet's body) inside `root`, reads what the browser draws (so the project's own theme.css, palette and
+ * finish are what is measured) and returns one row per pair: the fill's contrast with the ground, the edge's, and whether one of
+ * them reaches 3:1. Run it where the theme is loaded: a dev page (`console.table(cardGrounds())`) or a Playwright test
+ * (`await page.evaluate(cardGrounds)`). It reports; the theme's values stay the project's call. Self-contained on purpose: Playwright
+ * sends the function's source to the page, so it reads nothing from outside its own body.
+ */
+export declare function cardGrounds(root?: Element): CardGround[];

package/dist/cards/cardGrounds.js

@@ -0,0 +1,84 @@
+/**
+ * Can the member see each card's boundary? Builds a card of every tone (1–5) on each ground a card stands on (the screen, a
+ * sheet's body, a `paper` sheet's body) inside `root`, reads what the browser draws (so the project's own theme.css, palette and
+ * finish are what is measured) and returns one row per pair: the fill's contrast with the ground, the edge's, and whether one of
+ * them reaches 3:1. Run it where the theme is loaded: a dev page (`console.table(cardGrounds())`) or a Playwright test
+ * (`await page.evaluate(cardGrounds)`). It reports; the theme's values stay the project's call. Self-contained on purpose: Playwright
+ * sends the function's source to the page, so it reads nothing from outside its own body.
+ */
+export function cardGrounds(root = document.body) {
+    const ctx = document.createElement('canvas').getContext('2d', { willReadFrequently: true });
+    const paint = (layers) => {
+        ctx.globalCompositeOperation = 'copy';
+        ctx.fillStyle = '#fff';
+        ctx.fillRect(0, 0, 1, 1);
+        ctx.globalCompositeOperation = 'source-over';
+        for (const c of layers) {
+            ctx.fillStyle = c;
+            ctx.fillRect(0, 0, 1, 1);
+        }
+        return [...ctx.getImageData(0, 0, 1, 1).data.slice(0, 3)];
+    };
+    const lum = (rgb) => {
+        const [r, g, b] = rgb.map((v) => { const s = v / 255; return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4; });
+        return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+    };
+    const ratio = (a, b) => { const [x, y] = [lum(a), lum(b)].sort((p, q) => q - p); return Math.round(((x + 0.05) / (y + 0.05)) * 100) / 100; };
+    const hex = (rgb) => `#${rgb.map((v) => v.toString(16).padStart(2, '0')).join('')}`;
+    // a computed box-shadow lists `colour x y blur spread [inset]` per shadow; one with no blur draws a hard edge
+    const hardShadows = (value) => {
+        if (value === 'none')
+            return [];
+        const parts = [];
+        let depth = 0, from = 0;
+        for (let i = 0; i < value.length; i++) {
+            if (value[i] === '(')
+                depth++;
+            else if (value[i] === ')')
+                depth--;
+            else if (value[i] === ',' && depth === 0) {
+                parts.push(value.slice(from, i));
+                from = i + 1;
+            }
+        }
+        parts.push(value.slice(from));
+        return parts.flatMap((p) => {
+            const colour = p.trim().match(/^([a-z-]+\([^)]*\)|[a-z]+)/i)?.[0] ?? 'transparent';
+            const [x = 0, y = 0, blur = 0, spread = 0] = (p.replace(colour, '').match(/-?[\d.]+px/g) ?? []).map(parseFloat);
+            return !/inset/.test(p) && blur === 0 && (spread > 0 || x !== 0 || y !== 0) ? [colour] : [];
+        });
+    };
+    const below = (el) => {
+        const out = [];
+        for (let e = el; e; e = e.parentElement)
+            out.unshift(getComputedStyle(e).backgroundColor);
+        return out;
+    };
+    const probe = document.createElement('div');
+    probe.style.cssText = 'position:absolute;inset-inline-start:-200vw;inset-block-start:0;inline-size:20rem;';
+    const grounds = [
+        { ground: 'screen', html: '', end: '', token: '--surface' },
+        { ground: 'sheet', html: '<article class="card sheet"><div class="sheet__body">', end: '</div></article>', token: '--card-1-bg' },
+        { ground: 'paper sheet', html: '<article class="card sheet sheet--paper"><div class="sheet__body">', end: '</div></article>', token: '--color-paper' },
+    ];
+    const tones = [1, 2, 3, 4, 5];
+    probe.innerHTML = grounds.map((g) => `<div>${g.html}${tones.map((t) => `<div class="card${t > 1 ? ` card--${t}` : ''}"></div>`).join('')}${g.end}</div>`).join('');
+    root.append(probe);
+    try {
+        return grounds.flatMap((g, i) => tones.map((tone, j) => {
+            const card = probe.children[i].querySelectorAll('.card:not(.sheet)')[j];
+            const cs = getComputedStyle(card);
+            const under = below(card.parentElement);
+            const ground = paint(under), fill = paint([...under, cs.backgroundColor]);
+            const edges = [...(parseFloat(cs.borderTopWidth) > 0 ? [cs.borderTopColor] : []), ...hardShadows(cs.boxShadow)];
+            const edge = Math.max(1, ...edges.map((c) => ratio(paint([...under, c]), ground)));
+            const f = ratio(fill, ground), pass = f >= 3 || edge >= 3;
+            const where = g.ground === 'screen' ? 'on the screen' : `in a ${g.ground}'s body`;
+            const problem = pass ? '' : `tone ${tone} card ${where}: fill ${f}:1 (--card-${tone}-bg ${hex(fill)} on ${g.token} ${hex(ground)}), edge ${edge}:1 (--card-border); one of them needs 3:1 — the fill is short by ${Math.round((3 - f) * 100) / 100}, or give --card-border a colour of 3:1 on ${hex(ground)}`;
+            return { ground: g.ground, tone, fill: f, edge, pass, problem };
+        }));
+    }
+    finally {
+        probe.remove();
+    }
+}

package/dist/cards/inkGrounds.d.ts

@@ -0,0 +1,34 @@
+export type InkGround = {
+    /** what is read: the element's first class (or its tag) and its words, `icon in .<parent>`, or `glyph .<class>` for a mark drawn as a fill */
+    piece: string;
+    /** the nearest ancestor that paints a fill under it: its classes, e.g. `.card.card--3` */
+    surface: string;
+    /** the side that ground declares (`--dark`, or `--accent-dark` where it is the accent fill): its words and glyphs read that side's ink set */
+    side: 'light' | 'dark';
+    /** the ink set the colour is, read where it is drawn: `onlight`, `ondark`, or `` when it is neither (a fixed colour, a highlight) */
+    set: 'onlight' | 'ondark' | '';
+    kind: 'words' | 'large words' | 'icon' | 'glyph';
+    /** the colour as drawn (its alpha and every opacity on the way down), and the ground it is drawn on */
+    ink: string;
+    ground: string;
+    /** contrast ratio, 1–21 */
+    ratio: number;
+    /** 4.5 for words, 3 for large words (24px, or 18.66px bold), icons and glyphs: WCAG 2.2 SC 1.4.3 and 1.4.11 */
+    needs: 4.5 | 3;
+    pass: boolean;
+    /** what fails and by how much; empty when it passes */
+    problem: string;
+};
+/**
+ * Can the member read what stands on each surface? Walks every visible piece of words, every field's value, every icon (`svg.icon`) and
+ * every glyph drawn as a fill (a dot, a day's dot, the pager's dots, a check's tick, a switch's knob, a strong calendar mark's ring) inside
+ * `root`, finds the ground it is really drawn on (each ancestor's fill, from the page down, through every opacity on the way, to the first
+ * opaque one and past it) and returns one row per piece: words 4.5:1, large words, icons and glyphs 3:1. Each row names the side its ground
+ * declares and the ink set its colour is (README "Ink follows its ground": light ground → onlight, dark ground → ondark). What the browser
+ * draws is what is measured, so the project's theme.css, palette and finish are in it. Not measured: a piece on a picture (a `url()` ground
+ * is not one colour; a gradient is read as decoration unless it is one colour, a fill laid as an image), a disabled control (WCAG exempts
+ * it), a hidden one, words drawn by CSS `content`. Run it where the theme is loaded:
+ * `console.table(inkGrounds().filter((r) => !r.pass))` on a dev page, or `await page.evaluate(inkGrounds)` in Playwright.
+ * Self-contained for the same reason as cardGrounds(): Playwright sends the function's source to the page.
+ */
+export declare function inkGrounds(root?: Element): InkGround[];

package/dist/cards/inkGrounds.js

@@ -0,0 +1,181 @@
+/**
+ * Can the member read what stands on each surface? Walks every visible piece of words, every field's value, every icon (`svg.icon`) and
+ * every glyph drawn as a fill (a dot, a day's dot, the pager's dots, a check's tick, a switch's knob, a strong calendar mark's ring) inside
+ * `root`, finds the ground it is really drawn on (each ancestor's fill, from the page down, through every opacity on the way, to the first
+ * opaque one and past it) and returns one row per piece: words 4.5:1, large words, icons and glyphs 3:1. Each row names the side its ground
+ * declares and the ink set its colour is (README "Ink follows its ground": light ground → onlight, dark ground → ondark). What the browser
+ * draws is what is measured, so the project's theme.css, palette and finish are in it. Not measured: a piece on a picture (a `url()` ground
+ * is not one colour; a gradient is read as decoration unless it is one colour, a fill laid as an image), a disabled control (WCAG exempts
+ * it), a hidden one, words drawn by CSS `content`. Run it where the theme is loaded:
+ * `console.table(inkGrounds().filter((r) => !r.pass))` on a dev page, or `await page.evaluate(inkGrounds)` in Playwright.
+ * Self-contained for the same reason as cardGrounds(): Playwright sends the function's source to the page.
+ */
+export function inkGrounds(root = document.body) {
+    const ctx = document.createElement('canvas').getContext('2d', { willReadFrequently: true });
+    const parsed = new Map();
+    const rgba = (c) => {
+        let v = parsed.get(c);
+        if (!v) {
+            ctx.clearRect(0, 0, 1, 1);
+            ctx.fillStyle = '#0000';
+            ctx.fillStyle = c;
+            ctx.fillRect(0, 0, 1, 1);
+            const d = ctx.getImageData(0, 0, 1, 1).data;
+            v = [d[0], d[1], d[2], d[3] / 255];
+            parsed.set(c, v);
+        }
+        return v;
+    };
+    const over = (below, c) => { const [r, g, b, a] = rgba(c); return [r, g, b].map((x, i) => below[i] * (1 - a) + x * a); };
+    const lum = (rgb) => {
+        const [r, g, b] = rgb.map((v) => { const s = Math.round(v) / 255; return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4; });
+        return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+    };
+    const ratio = (a, b) => { const [x, y] = [lum(a), lum(b)].sort((p, q) => q - p); return Math.round(((x + 0.05) / (y + 0.05)) * 100) / 100; };
+    const hex = (rgb) => `#${rgb.map((v) => Math.round(v).toString(16).padStart(2, '0')).join('')}`;
+    const styles = new Map();
+    const style = (el) => { let s = styles.get(el); if (!s) {
+        s = getComputedStyle(el);
+        styles.set(el, s);
+    } return s; };
+    const name = (el) => (el.classList.length ? `.${[...el.classList].join('.')}` : el.tagName.toLowerCase());
+    // what an element paints under its content: its colour, and a gradient of one colour over it (a fill laid as an image); any other
+    // gradient is a decoration (a button's sheen, a grip's dots) and is left out; null for a picture, where the ground is not one colour
+    const fills = (el) => {
+        const cs = style(el), image = cs.backgroundImage;
+        if (/url\(/.test(image))
+            return null;
+        const one = /^linear-gradient\(((?:rgba?|color)\([^)]*\)), \1\)$/.exec(image);
+        return one ? [cs.backgroundColor, one[1]] : [cs.backgroundColor];
+    };
+    // the pixel under a piece: the page's white, then each ancestor's fill; an ancestor's opacity is the lerp from what lies behind it to
+    // what it draws (exact for one pixel), so the ink and the ground it fades into are faded together
+    const draw = (chain, ink, i = 0, behind = [255, 255, 255]) => {
+        if (i === chain.length)
+            return ink ? over(behind, ink) : behind;
+        const o = parseFloat(style(chain[i]).opacity);
+        const inside = draw(chain, ink, i + 1, fills(chain[i]).reduce(over, behind));
+        return o === 1 ? inside : inside.map((v, k) => behind[k] + (v - behind[k]) * o);
+    };
+    // a side switch as the browser holds it (`1`, `0`, or a calc() such as `calc(1 - 1)`), read as a number through a probe's width
+    const probe = document.createElement('i');
+    probe.style.cssText = 'position:absolute;visibility:hidden;height:0';
+    document.body.append(probe);
+    const number = (v) => { if (/^[\d.]+$/.test(v))
+        return parseFloat(v); probe.style.width = `calc((${v || 0}) * 1px)`; return parseFloat(getComputedStyle(probe).width) || 0; };
+    const sideOf = (surface) => {
+        if (!surface)
+            return 'light';
+        // a surface (a card, a tile) paints its own --card-bg and declares --dark; a control filled with the accent paints --accent, whose side is --accent-dark
+        const cs = style(surface), fill = rgba(cs.backgroundColor).join(), same = (n) => { const v = cs.getPropertyValue(n).trim(); return v !== '' && rgba(v).join() === fill; };
+        const isAccent = !same('--card-bg') && same('--accent');
+        return number(cs.getPropertyValue(isAccent ? '--accent-dark' : '--dark').trim()) >= 0.5 ? 'dark' : 'light';
+    };
+    // which role a failing colour is, read where it is drawn: the token a theme moves to fix it, and the ink set behind it
+    const SETS = ['--ink-onlight', '--ink-onlight-muted', '--ink-ondark', '--ink-ondark-muted', ...['ok', 'warn', 'error', 'info'].flatMap((s) => [`--signal-${s}-onlight`, `--signal-${s}-ondark`])];
+    const INKS = ['--card-ink', '--card-muted', '--on-accent', '--accent-ink', '--accent', '--action-ink', '--action-muted', '--action-accent', '--on-surface', '--on-surface-muted',
+        '--signal-ok', '--signal-warn', '--signal-error', '--signal-info'];
+    const GROUNDS = ['--card-bg', '--accent', '--action-bg', '--surface', '--neg', '--pos', ...[1, 2, 3, 4, 5].map((t) => `--card-${t}-bg`), '--highlight-1', '--highlight-2', '--highlight-3', '--highlight-4'];
+    const tokenOf = (el, colour, names) => {
+        const want = rgba(colour).join();
+        return names.find((n) => { const v = style(el).getPropertyValue(n).trim(); return v !== '' && rgba(v).join() === want; }) ?? '';
+    };
+    const setOf = (token) => (token.includes('ondark') ? 'ondark' : token.includes('onlight') ? 'onlight' : '');
+    // GLYPHS drawn as a fill: the selector, and where its colour is: the element's own fill over what is under it, its ::after's fill over
+    // the element's, or its inset ring over the element's ground
+    const GLYPHS = [
+        ['.dot:is(.dot--ok, .dot--warn, .dot--error, .dot--info)', 'fill'], ['.day__dot', 'fill'], ['.pager__at > *', 'fill'],
+        ['.check:checked', 'after'], ['.toggle', 'after'],
+        ['.calendar__day--mark2', 'ring'],
+    ];
+    const pieces = new Map();
+    const walk = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+    for (let n = walk.nextNode(); n; n = walk.nextNode()) {
+        const el = n.parentElement;
+        if (el && n.textContent.trim() && !el.closest('svg, style, script, textarea'))
+            pieces.set(el, { what: 'words' });
+    }
+    for (const el of root.querySelectorAll('svg.icon'))
+        if (!el.parentElement?.closest('svg'))
+            pieces.set(el, { what: 'icon' });
+    for (const el of root.querySelectorAll('input:not([type=checkbox], [type=radio], [type=range], [type=hidden], [type=color], [type=file]), textarea, select'))
+        if (el.value)
+            pieces.set(el, { what: 'value' });
+    for (const [sel, read] of GLYPHS)
+        for (const el of root.querySelectorAll(sel))
+            if (!pieces.has(el))
+                pieces.set(el, { what: 'glyph', read });
+    const out = [];
+    for (const [el, { what, read }] of pieces) {
+        if (!el.checkVisibility({ opacityProperty: true, visibilityProperty: true }))
+            continue;
+        const box = el.getBoundingClientRect();
+        if (box.width <= 1 || box.height <= 1)
+            continue; // visually hidden: words for a screen reader
+        if (el.closest(':disabled, [aria-disabled="true"], label:has(:disabled)'))
+            continue; // an inactive control: WCAG asks no contrast of it
+        const chain = [];
+        for (let e = el; e; e = e.parentElement)
+            chain.unshift(e);
+        const cs = style(el);
+        // a glyph drawn as its own fill stands on what is under it; any other piece stands on its own element's fill too (a chip's label is its text)
+        const under = read === 'fill' ? chain.slice(0, -1) : chain;
+        let pictured = false, surface;
+        for (let k = under.length - 1; k >= 0; k--) {
+            const f = fills(under[k]);
+            if (!f) {
+                pictured = true;
+                break;
+            }
+            const alpha = Math.max(...f.map((c) => rgba(c)[3]));
+            if (alpha > 0)
+                surface ??= under[k];
+            if (alpha === 1)
+                break;
+        }
+        if (pictured)
+            continue;
+        let inkColour;
+        if (what === 'icon')
+            inkColour = cs.stroke !== 'none' ? cs.stroke : cs.fill;
+        else if (read === 'fill')
+            inkColour = cs.backgroundColor;
+        else if (read === 'after')
+            inkColour = getComputedStyle(el, '::after').backgroundColor;
+        else if (read === 'ring')
+            inkColour = /^(?:rgba?|color)\([^)]*\)/.exec(cs.boxShadow)?.[0] ?? 'transparent';
+        else
+            inkColour = cs.color;
+        if (what === 'glyph' && rgba(inkColour)[3] === 0)
+            continue; // the glyph is not drawn (an unchecked check's tick)
+        const ground = draw(under, null);
+        let ink = draw(under, inkColour);
+        if (read === 'fill') {
+            const o = parseFloat(cs.opacity);
+            ink = ink.map((v, k) => ground[k] + (v - ground[k]) * o);
+        }
+        if (read === 'after') {
+            const o = parseFloat(getComputedStyle(el, '::after').opacity);
+            ink = ink.map((v, k) => ground[k] + (v - ground[k]) * o);
+        }
+        const px = parseFloat(cs.fontSize), bold = parseInt(cs.fontWeight) >= 700;
+        const kind = what === 'icon' ? 'icon' : what === 'glyph' ? 'glyph' : px >= 24 || (px >= 18.66 && bold) ? 'large words' : 'words';
+        const needs = kind === 'words' ? 4.5 : 3;
+        const r = ratio(ink, ground), pass = r >= needs;
+        const words = (what === 'value' ? el.value : el.textContent).trim().replace(/\s+/g, ' ').slice(0, 32);
+        const piece = what === 'icon' ? `icon in ${name(el.parentElement)}` : what === 'glyph' ? `glyph ${name(el)}${read === 'fill' ? '' : `'s ${read === 'after' ? 'mark' : 'ring'}`}` : `${name(el)} "${words}"`;
+        const on = surface ? name(surface) : 'the page';
+        const side = sideOf(surface);
+        const set = setOf(tokenOf(el, inkColour, SETS));
+        let problem = '';
+        if (!pass) {
+            const role = tokenOf(el, inkColour, INKS), from = tokenOf(el, inkColour, SETS);
+            const named = role || from ? ` (${[role, from].filter(Boolean).join(' = ')})` : '';
+            const groundToken = surface ? tokenOf(surface, fills(surface).at(-1), GROUNDS) : '';
+            problem = `${piece} on ${on} (${side} side): ${hex(ink)}${named} on ${hex(ground)}${groundToken ? ` (${groundToken})` : ''} is ${r}:1, ${kind} need ${needs}:1`;
+        }
+        out.push({ piece, surface: on, side, set, kind, ink: hex(ink), ground: hex(ground), ratio: r, needs, pass, problem });
+    }
+    probe.remove();
+    return out;
+}