@webround/editor 0.0.0-stage → 0.3.0

package/dist/measure-rules.d.ts

@@ -0,0 +1,34 @@
+export interface Box {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+/** WCAG 2.5.8 (AA): a pointer target is at least this many CSS pixels on each side. */
+export declare const MIN_TARGET_PX = 24;
+/**
+ * Which of these targets are too small (WCAG 2.5.8): a target under 24×24px passes when a circle of 24px centred on it touches no other target
+ * (there is room around it), or when it is a link inside a sentence (a link in a text cannot be larger than its words).
+ */
+export declare function undersizedTargets(targets: readonly {
+    box: Box;
+    inline: boolean;
+}[]): number[];
+/** Content is lost when a box that clips has MORE inside than it shows after the spacing was spread, and did not before. */
+export declare function lostContent(before: {
+    scrollHeight: number;
+    clientHeight: number;
+    scrollWidth: number;
+    clientWidth: number;
+}, after: typeof before): boolean;
+/** Text under this size is hard to read for many people. There is no number in WCAG: this is a rule of thumb, and says so. */
+export declare const MIN_TEXT_PX = 12;
+/** The page is a phone's width or narrower: WCAG 1.4.10 is judged at 320px, so a wider window says nothing. */
+export declare const REFLOW_MAX_WIDTH = 420;
+/**
+ * Which navigation areas need a name: when a page has more than one, a screen reader lists them all as "navigation", so each one needs a
+ * name of its own (`aria-label`), and not the same as another's. With one, no name is needed. `names` are the names as they are, in the order
+ * of the page ('' for none).
+ */
+export declare function navsNeedingAName(names: readonly string[]): number[];
+//# sourceMappingURL=measure-rules.d.ts.map

package/dist/measure-rules.js

@@ -0,0 +1,54 @@
+// The decisions of the page's measures, without the page: sizes and boxes in, a verdict out. Pure, so they can be tested without a browser.
+/** WCAG 2.5.8 (AA): a pointer target is at least this many CSS pixels on each side. */
+export const MIN_TARGET_PX = 24;
+/**
+ * Which of these targets are too small (WCAG 2.5.8): a target under 24×24px passes when a circle of 24px centred on it touches no other target
+ * (there is room around it), or when it is a link inside a sentence (a link in a text cannot be larger than its words).
+ */
+export function undersizedTargets(targets) {
+    const radius = MIN_TARGET_PX / 2;
+    const small = (box) => box.right - box.left < MIN_TARGET_PX || box.bottom - box.top < MIN_TARGET_PX;
+    const centre = (box) => ({ x: (box.left + box.right) / 2, y: (box.top + box.bottom) / 2 });
+    // The circle of a small target touches a large one when the large one's box comes within the radius; it touches another small one when
+    // their circles overlap (the centres are closer than the diameter)
+    const crowds = (box, other) => {
+        const { x, y } = centre(box);
+        if (small(other)) {
+            const o = centre(other);
+            return (x - o.x) ** 2 + (y - o.y) ** 2 < MIN_TARGET_PX ** 2;
+        }
+        const nearestX = Math.max(other.left, Math.min(x, other.right));
+        const nearestY = Math.max(other.top, Math.min(y, other.bottom));
+        return (x - nearestX) ** 2 + (y - nearestY) ** 2 < radius ** 2;
+    };
+    const found = [];
+    targets.forEach((target, index) => {
+        if (target.inline || !small(target.box))
+            return;
+        if (targets.some((other, i) => i !== index && crowds(target.box, other.box)))
+            found.push(index);
+    });
+    return found;
+}
+/** Content is lost when a box that clips has MORE inside than it shows after the spacing was spread, and did not before. */
+export function lostContent(before, after) {
+    const over = (a, b) => a > b + 1;
+    return (over(after.scrollHeight, after.clientHeight) && !over(before.scrollHeight, before.clientHeight))
+        || (over(after.scrollWidth, after.clientWidth) && !over(before.scrollWidth, before.clientWidth));
+}
+/** Text under this size is hard to read for many people. There is no number in WCAG: this is a rule of thumb, and says so. */
+export const MIN_TEXT_PX = 12;
+/** The page is a phone's width or narrower: WCAG 1.4.10 is judged at 320px, so a wider window says nothing. */
+export const REFLOW_MAX_WIDTH = 420;
+/**
+ * Which navigation areas need a name: when a page has more than one, a screen reader lists them all as "navigation", so each one needs a
+ * name of its own (`aria-label`), and not the same as another's. With one, no name is needed. `names` are the names as they are, in the order
+ * of the page ('' for none).
+ */
+export function navsNeedingAName(names) {
+    if (names.length < 2)
+        return [];
+    const trimmed = names.map(name => name.trim().toLowerCase());
+    return trimmed.flatMap((name, index) => (name === '' || trimmed.indexOf(name) !== trimmed.lastIndexOf(name) ? [index] : []));
+}
+//# sourceMappingURL=measure-rules.js.map

package/dist/measure.d.ts

@@ -0,0 +1,11 @@
+import { type Rgba } from './contrast';
+export interface MeasureFinding {
+    /** The rule it belongs to (`color-contrast`, `target-size`…). */
+    rule: string;
+    /** `data-wr-id` of the nearest element that can be edited. */
+    elementId: string;
+    message: string;
+}
+/** Everything the page's drawing says about its accessibility, now. */
+export declare function measurePage(doc: Document, resolve?: (css: string) => Rgba | null): MeasureFinding[];
+//# sourceMappingURL=measure.d.ts.map

package/dist/measure.js

@@ -0,0 +1,139 @@
+import { canvasResolver, measureContrast } from './contrast';
+import { MIN_TARGET_PX, MIN_TEXT_PX, REFLOW_MAX_WIDTH, lostContent, navsNeedingAName, undersizedTargets } from './measure-rules';
+const idOf = (el) => el.closest('[data-wr-id]')?.getAttribute('data-wr-id') ?? undefined;
+const visible = (el, view) => {
+    const style = view.getComputedStyle(el);
+    return style.display !== 'none' && style.visibility !== 'hidden' && el.getClientRects().length > 0;
+};
+const ownText = (el) => Array.from(el.childNodes).filter(n => n.nodeType === 3).map(n => n.textContent ?? '').join(' ').replace(/\s+/g, ' ').trim();
+const box = (el) => { const r = el.getBoundingClientRect(); return { left: r.left, top: r.top, right: r.right, bottom: r.bottom }; };
+const shortText = (text) => (text.length > 40 ? `${text.slice(0, 39)}…` : text);
+const TARGETS = 'a[href], button, input:not([type=hidden]), select, textarea, summary, [role=button], [role=link], [role=checkbox], [role=switch], [role=tab], [role=menuitem], [tabindex]:not([tabindex="-1"])';
+const NAME = { a: 'link', button: 'button', input: 'field', select: 'menu', textarea: 'field', summary: 'summary' };
+function measureTargets(doc) {
+    const view = doc.defaultView;
+    if (!view)
+        return [];
+    const elements = Array.from(doc.querySelectorAll(TARGETS)).filter(el => visible(el, view));
+    const targets = elements.map(el => {
+        const parent = el.parentElement;
+        // A link in the middle of a sentence is as large as its words: it is not asked to be 24px
+        const inline = el.tagName === 'A' && view.getComputedStyle(el).display === 'inline' && !!parent && (parent.textContent ?? '').trim().length > (el.textContent ?? '').trim().length + 3;
+        return { el, box: box(el), inline };
+    });
+    return undersizedTargets(targets).flatMap((index) => {
+        const { el, box: b } = targets[index];
+        const elementId = idOf(el);
+        if (!elementId)
+            return [];
+        const label = NAME[el.tagName.toLowerCase()] ?? 'control';
+        return [{ rule: 'target-size', elementId, message: `The ${label} is ${Math.round(b.right - b.left)}×${Math.round(b.bottom - b.top)}px: something to press should be at least ${MIN_TARGET_PX}×${MIN_TARGET_PX}px, or have that much free space around it (WCAG 2.5.8).` }];
+    });
+}
+function measureTextSize(doc) {
+    const view = doc.defaultView;
+    if (!view || !doc.body)
+        return [];
+    const smallest = new Map();
+    for (const el of Array.from(doc.body.querySelectorAll('*')).slice(0, 4000)) {
+        const text = ownText(el);
+        if (text.length < 3)
+            continue;
+        const id = idOf(el);
+        if (!id || !visible(el, view))
+            continue;
+        const px = parseFloat(view.getComputedStyle(el).fontSize);
+        if (px >= MIN_TEXT_PX || !Number.isFinite(px))
+            continue;
+        const known = smallest.get(id);
+        if (!known || px < known.px)
+            smallest.set(id, { px, text });
+    }
+    return [...smallest].map(([elementId, { px, text }]) => ({
+        rule: 'text-size', elementId,
+        message: `The text “${shortText(text)}” is ${Math.round(px * 10) / 10}px high: most people find text under ${MIN_TEXT_PX}px hard to read (WCAG has no minimum, this is a rule of thumb).`,
+    }));
+}
+/** The spacing WCAG 1.4.12 says a page must survive: lines 1.5×, letters 0.12em, words 0.16em apart, paragraphs 2em apart. */
+const SPACING_CSS = 'html *, html *::before, html *::after { line-height: 1.5 !important; letter-spacing: 0.12em !important; word-spacing: 0.16em !important; } html p { margin-bottom: 2em !important; }';
+function measureTextSpacing(doc) {
+    const view = doc.defaultView;
+    if (!view || !doc.body || !doc.head)
+        return [];
+    const clippers = Array.from(doc.body.querySelectorAll('*')).slice(0, 4000).filter(el => {
+        const style = view.getComputedStyle(el);
+        const clips = /hidden|clip/.test(style.overflowX) || /hidden|clip/.test(style.overflowY);
+        return clips && el.clientHeight > 0 && ownText(el).length + (el.textContent ?? '').trim().length > 0 && visible(el, view);
+    });
+    if (clippers.length === 0)
+        return [];
+    const sizes = (el) => ({ scrollHeight: el.scrollHeight, clientHeight: el.clientHeight, scrollWidth: el.scrollWidth, clientWidth: el.clientWidth });
+    const before = clippers.map(sizes);
+    // Spread the text, look, put it back: nothing is drawn in between (it all happens in one go of the script)
+    const style = doc.createElement('style');
+    style.textContent = SPACING_CSS;
+    doc.head.appendChild(style);
+    let after;
+    try {
+        after = clippers.map(sizes);
+    }
+    finally {
+        style.remove();
+    }
+    const found = new Map();
+    clippers.forEach((el, i) => {
+        if (!lostContent(before[i], after[i]))
+            return;
+        const elementId = idOf(el) ?? el.querySelector('[data-wr-id]')?.getAttribute('data-wr-id');
+        if (elementId && !found.has(elementId))
+            found.set(elementId, { rule: 'text-spacing', elementId, message: 'Text is cut off when its spacing is increased (lines 1.5×, letters and words a little further apart): the box it is in is too tight for it (WCAG 1.4.12).' });
+    });
+    return [...found.values()];
+}
+function measureReflow(doc) {
+    const root = doc.documentElement;
+    const width = root.clientWidth;
+    if (width === 0 || width > REFLOW_MAX_WIDTH || root.scrollWidth <= width + 1 || !doc.body)
+        return [];
+    // The element that goes furthest out of the window is where to look
+    let culprit;
+    for (const el of Array.from(doc.body.querySelectorAll('[data-wr-id]'))) {
+        const right = el.getBoundingClientRect().right;
+        if (right > width + 1 && (!culprit || right > culprit.right))
+            culprit = { id: el.getAttribute('data-wr-id'), right };
+    }
+    return [{ rule: 'reflow', elementId: culprit?.id ?? '', message: `The page scrolls sideways at ${width}px wide: on a narrow screen the content should fit in one column, without scrolling in two directions (WCAG 1.4.10).` }];
+}
+/** The navigation areas of the page — `<nav>`, `role=navigation` — and whether they can be told apart. They are often in a component's own file: only the drawn page knows them all. */
+function measureNavigation(doc) {
+    const view = doc.defaultView;
+    if (!view)
+        return [];
+    const navs = Array.from(doc.querySelectorAll('nav, [role=navigation]')).filter(el => visible(el, view));
+    const nameOf = (el) => {
+        const label = el.getAttribute('aria-label');
+        if (label?.trim())
+            return label;
+        const by = el.getAttribute('aria-labelledby');
+        return by ? by.split(/\s+/).map(id => doc.getElementById(id)?.textContent ?? '').join(' ') : '';
+    };
+    return navsNeedingAName(navs.map(nameOf)).flatMap((index) => {
+        const elementId = idOf(navs[index]);
+        const name = nameOf(navs[index]).trim();
+        return [{
+                rule: 'landmark-nav-name', elementId: elementId ?? '',
+                message: name
+                    ? `There are ${navs.length} navigation areas and two have the name "${name}": a screen reader lists them as ${navs.length} identical entries. Give each its own aria-label.`
+                    : `There are ${navs.length} navigation areas and this one has no name: a screen reader lists them all as "navigation". Give each its own aria-label (Main, Footer…).`,
+            }];
+    });
+}
+/** Everything the page's drawing says about its accessibility, now. */
+export function measurePage(doc, resolve = canvasResolver(doc)) {
+    const contrast = measureContrast(doc, resolve).map((f) => ({
+        rule: 'color-contrast', elementId: f.elementId,
+        message: `The text “${f.text}” has a contrast of ${f.ratio}:1 against its background; it should be at least ${f.required}:1 (WCAG 1.4.3).`,
+    }));
+    return [...contrast, ...measureTargets(doc), ...measureTextSize(doc), ...measureTextSpacing(doc), ...measureReflow(doc), ...measureNavigation(doc)];
+}
+//# sourceMappingURL=measure.js.map