@0001-labs/design-system-1 0.3.0-alpha.28 → 0.3.1

package/dist/0-face/constraint-site.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constraint-site.d.ts","sourceRoot":"","sources":["../../DS1/0-face/constraint-site.ts"],"names":[],"mappings":"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"}

package/dist/0-face/constraint-site.js

@@ -0,0 +1,186 @@
+// The constraints on every page of a site, at every phone width, from inside the browser: the constraint
+// panel's Site check (constraint-panel.ts). Each page in the site's sitemap is opened once in a frame of
+// the site's own, out of sight, then made as wide as each phone in turn and drawn at that phone's scale,
+// and measured with every rule in constraints.ts at each width. Three pages are checked at a time.
+// scripts/constraints-phone.ts does the same from a terminal, in WebKit as an iPhone.
+import { constraints, measureConstraints } from './constraints';
+import { calculateScalingFactor, defaultScalingConfig } from './scaling';
+/** The narrowest phone still sold, the common ones and the widest. */
+export const PHONE_WIDTHS = [320, 375, 393, 430];
+export const VIEWPORT_WIDTHS = [...PHONE_WIDTHS, 768, 1024, 1440];
+/** Pages checked side by side, each in its own frame. */
+export const PAGES_AT_ONCE = 3;
+/** An element as a person finds it: its tag, id and classes, and the start of its words. */
+export function describeElement(element) {
+    const name = element.localName + (element.id ? `#${element.id}` : '') + Array.from(element.classList, c => `.${c}`).join('');
+    const words = (element.textContent ?? '').trim().replace(/\s+/g, ' ').slice(0, 40);
+    return words ? `${name} "${words}"` : name;
+}
+/** The pages a sitemap lists on the site's own origin, in its order and once each; none when it lists none. */
+export function sitemapPages(xml, origin) {
+    const pages = [...xml.matchAll(/<loc>\s*([^<\s]+)\s*<\/loc>/g)].flatMap(([, loc]) => {
+        try {
+            const url = new URL(loc.replace(/&amp;/g, '&'), origin);
+            return url.origin === origin ? [url.href] : [];
+        }
+        catch {
+            return [];
+        }
+    });
+    return [...new Set(pages)];
+}
+/** The site's pages: its sitemap's, or else the page itself and every page it links to on the site. */
+export async function findSitePages(page = document) {
+    const { origin } = page.location ?? window.location;
+    try {
+        const answer = await fetch(new URL('/sitemap.xml', origin));
+        if (answer.ok) {
+            const pages = sitemapPages(await answer.text(), origin);
+            if (pages.length)
+                return pages;
+        }
+    }
+    catch { /* No sitemap: the links below. */ }
+    const links = Array.from(page.querySelectorAll('a[href]'), link => new URL(link.href, origin))
+        .filter(url => url.origin === origin && !/\.\w+$/.test(url.pathname))
+        .map(url => `${url.origin}${url.pathname}`);
+    return [...new Set([`${origin}${(page.location ?? window.location).pathname}`, ...links])];
+}
+const wait = (ms) => new Promise(done => setTimeout(done, ms));
+/**
+ * Opens a page once in a frame inside `host`, then makes the frame as wide as each width in turn, draws
+ * the page at that width's phone scale, and returns what every rule measured and found at each, in the
+ * order of `widths`. The page reflows at each width without loading again. The address carries `ph=out`,
+ * the analytics opt-out most trackers honour, so the check counts no visits.
+ */
+export async function inspectInFrame(host, url, widths = VIEWPORT_WIDTHS, height = 844) {
+    const frame = document.createElement('iframe');
+    frame.setAttribute('aria-hidden', 'true');
+    frame.tabIndex = -1;
+    frame.style.cssText = `position:absolute;top:0;left:-1000px;width:${widths[0]}px;height:${height}px;border:0;visibility:hidden;pointer-events:none`;
+    const address = new URL(url);
+    address.searchParams.set('ph', 'out');
+    try {
+        const loaded = new Promise((done, fail) => {
+            frame.addEventListener('load', () => done(), { once: true });
+            setTimeout(() => fail(new Error('did not load in 30 seconds')), 30000);
+        });
+        frame.src = address.href;
+        host.appendChild(frame);
+        await loaded;
+        const page = frame.contentDocument;
+        if (!page?.documentElement)
+            throw new Error('could not be read');
+        await page.fonts?.ready;
+        const root = page.documentElement;
+        const checks = [];
+        for (const width of widths) {
+            frame.style.width = `${width}px`;
+            // The phone's scale for this width, whichever browser draws the frame: a computer's would draw it
+            // at 1, and a page that scales once on load would keep the first width's.
+            root.style.setProperty('--sf', String(calculateScalingFactor(width, { ...defaultScalingConfig, snap: 'layout' })));
+            root.setAttribute('data-mobile', '');
+            void root.scrollWidth;
+            // Room for what follows a resize on its own: resize observers, a carousel measuring its slides.
+            await wait(80);
+            checks.push(checkPage(page));
+        }
+        return checks;
+    }
+    finally {
+        frame.remove();
+    }
+}
+/** Every rule on a page: what it measured, and each place it is broken, said in words. */
+export function checkPage(page) {
+    const measured = {};
+    const findings = [];
+    for (const { constraint, measured: count, findings: found } of measureConstraints(page)) {
+        measured[constraint.code] = count;
+        for (const { message, element, review } of found)
+            findings.push({ code: constraint.code, rule: constraint.rule, message, element: describeElement(element), ...(review ? { review } : {}) });
+    }
+    return { findings, measured };
+}
+/**
+ * Checks every page at every width, `PAGES_AT_ONCE` pages side by side, and reports each page's result at
+ * each width as it comes. Stops starting pages when `signal` aborts. Whatever the pages store in this
+ * browser while they are checked is put back afterwards.
+ */
+export async function checkSite({ pages, widths = VIEWPORT_WIDTHS, inspect, onResult, signal, atOnce = PAGES_AT_ONCE }) {
+    const kept = storedNow();
+    const results = [];
+    const total = pages.length * widths.length;
+    const queue = [...pages];
+    const next = async () => {
+        for (let url = queue.shift(); url && !signal?.aborted; url = queue.shift()) {
+            const checks = await inspect(url, widths).catch((error) => error);
+            for (const [index, width] of widths.entries()) {
+                const result = checks instanceof Error
+                    ? { url, width, findings: [], measured: {}, error: checks.message }
+                    : { url, width, ...(checks[index] ?? { findings: [], measured: {} }) };
+                results.push(result);
+                if (!signal?.aborted)
+                    onResult(result, results.length, total);
+            }
+        }
+    };
+    try {
+        await Promise.all(Array.from({ length: Math.max(1, atOnce) }, next));
+    }
+    finally {
+        putBack(kept);
+    }
+    return results;
+}
+/** This site's storage in this browser, to put back after the check. */
+function storedNow() {
+    try {
+        return new Map(Object.keys(localStorage).map(key => [key, localStorage.getItem(key)]));
+    }
+    catch {
+        return null;
+    }
+}
+function putBack(kept) {
+    if (!kept)
+        return;
+    try {
+        for (const key of Object.keys(localStorage))
+            if (!kept.has(key))
+                localStorage.removeItem(key);
+        for (const [key, value] of kept)
+            if (localStorage.getItem(key) !== value)
+                localStorage.setItem(key, value);
+    }
+    catch { /* Storage blocked: nothing was kept either. */ }
+}
+export function summarizeRules(results) {
+    return constraints.map(constraint => {
+        const counts = results.map(result => result.measured[constraint.code] ?? 0);
+        return {
+            constraint,
+            measured: counts.reduce((sum, count) => sum + count, 0),
+            views: counts.filter(count => count > 0).length,
+            broken: results.reduce((sum, result) => sum + result.findings.filter(finding => finding.code === constraint.code && !finding.review).length, 0),
+        };
+    });
+}
+const count = (n, [one, many]) => `${n.toLocaleString('en')} ${n === 1 ? one : many}`;
+/** What a rule did, in a sentence: kept, broken, or nothing on the pages for it to measure. `views` is how many page views were checked; one is this page. */
+export function ruleLine({ constraint, measured, views, broken }, total) {
+    if (!measured)
+        return `Nothing to measure: no ${constraint.measures[1]} ${total === 1 ? 'on this page' : 'on these pages'}.`;
+    const where = total === 1 ? 'on this page' : `on ${views.toLocaleString('en')} of ${total.toLocaleString('en')} page views`;
+    return broken
+        ? `Broken ${broken === 1 ? 'once' : `${broken.toLocaleString('en')} times`}, among ${count(measured, constraint.measures)} measured ${where}.`
+        : `Kept by ${count(measured, constraint.measures)} measured ${where}.`;
+}
+/** Every page checked, in the order checked, with how much it broke at each width. */
+export function summarizePages(results) {
+    const pages = new Map();
+    for (const { url, width, findings, error } of results) {
+        pages.set(url, [...(pages.get(url) ?? []), { width, broken: findings.filter(finding => !finding.review).length, error }].sort((a, b) => a.width - b.width));
+    }
+    return [...pages].map(([url, widths]) => ({ url, widths }));
+}

package/dist/0-face/constraints.d.ts

@@ -0,0 +1,47 @@
+/** Where a page breaks a rule: the element, and what is wrong with it in a sentence. `review` marks what the
+ *  check could not measure (words over a picture, a blend) and asks a person to look, which breaks no rule. */
+export type Finding = {
+    element: Element;
+    message: string;
+    review?: boolean;
+};
+export type Constraint = {
+    /** `<component>.<what>`, lower case, never changed once given. */
+    code: string;
+    /** The rule, one sentence, said of the thing and not of a product. */
+    rule: string;
+    /** Why it holds, when the rule alone does not say. */
+    why?: string;
+    /** The elements that keep it, by tag. */
+    components: string[];
+    /** The test that measures it in the source: a file in tests/ and the name it is given there. */
+    check: {
+        file: string;
+        test: string;
+    };
+    /** Measures it on a page as drawn, and returns where the page breaks it. */
+    inspect: (root: ParentNode) => Finding[];
+    /** What it measures on a page, one and many (`['card', 'cards']`), and how many of them a page has. */
+    measures: [one: string, many: string];
+    count: (root: ParentNode) => number;
+};
+export declare const constraints: Constraint[];
+/** Every rule a page breaks, in the list's order. */
+export declare function inspectConstraints(root?: ParentNode): (Finding & {
+    constraint: Constraint;
+})[];
+/** Every rule with how many things it measured on the page and where the page breaks it, in the list's order. */
+export declare function measureConstraints(root?: ParentNode): {
+    constraint: Constraint;
+    measured: number;
+    findings: Finding[];
+}[];
+/** The component's name as its page is called: `ds-card` is Card. */
+export declare const componentName: (tag: string) => string;
+/** The rules grouped by the first component that keeps them, in the list's order. */
+export declare function byComponent(list?: Constraint[]): [string, Constraint[]][];
+export declare const skillStart = "<!-- constraints:start (written by scripts/write-constraints.ts from DS1/0-face/constraints.ts) -->";
+export declare const skillEnd = "<!-- constraints:end -->";
+/** The skill's list: a line a rule, under its component, between the markers. */
+export declare function skillBlock(list?: Constraint[]): string;
+//# sourceMappingURL=constraints.d.ts.map

package/dist/0-face/constraints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constraints.d.ts","sourceRoot":"","sources":["../../DS1/0-face/constraints.ts"],"names":[],"mappings":"AAgBA;+GAC+G;AAC/G,MAAM,MAAM,OAAO,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAE9E,MAAM,MAAM,UAAU,GAAG;IACvB,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,gGAAgG;IAChG,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACtC,4EAA4E;IAC5E,OAAO,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,OAAO,EAAE,CAAC;IACzC,uGAAuG;IACvG,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IACtC,KAAK,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,MAAM,CAAC;CACrC,CAAC;AA6EF,eAAO,MAAM,WAAW,EAAE,UAAU,EA0JnC,CAAC;AAEF,qDAAqD;AACrD,wBAAgB,kBAAkB,CAAC,IAAI,GAAE,UAAqB,GAAG,CAAC,OAAO,GAAG;IAAE,UAAU,EAAE,UAAU,CAAA;CAAE,CAAC,EAAE,CAExG;AAED,iHAAiH;AACjH,wBAAgB,kBAAkB,CAAC,IAAI,GAAE,UAAqB,GAAG;IAAE,UAAU,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,EAAE,CAAA;CAAE,EAAE,CAEnI;AAED,qEAAqE;AACrE,eAAO,MAAM,aAAa,GAAI,KAAK,MAAM,WAGxC,CAAC;AAEF,qFAAqF;AACrF,wBAAgB,WAAW,CAAC,IAAI,GAAE,UAAU,EAAgB,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,EAAE,CAOtF;AAED,eAAO,MAAM,UAAU,wGAAwG,CAAC;AAChI,eAAO,MAAM,QAAQ,6BAA6B,CAAC;AAEnD,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,IAAI,GAAE,UAAU,EAAgB,GAAG,MAAM,CAQnE"}

package/dist/0-face/constraints.js

@@ -0,0 +1,274 @@
+import { faultLineGrids, inspectFaultLines } from './fault-lines';
+import { labelledButtons, inspectButtonLabels } from './button-label';
+import { inspectTextContrast, measureTextContrast } from "./text-contrast";
+import { inspectWordWrap, wordHeaders } from './word-wrap';
+/** The actual initial, including a component nested in another open shadow root. */
+function isAvatarInitial(element) {
+    for (let parent = element; parent; parent = parent.assignedSlot ?? parent.parentElement ?? parent.getRootNode().host ?? null) {
+        if (parent.matches('ds-avatar, .ds-avatar'))
+            return true;
+    }
+    return false;
+}
+/** A pixel either way is the same place. */
+const near = (a, b) => Math.abs(a - b) <= 1;
+const px = (n) => `${Math.round(n)}px`;
+/** An element's style, from its own window: a page checked in a frame is measured by the frame's. */
+const styleOf = (element) => (element.ownerDocument.defaultView ?? window).getComputedStyle(element);
+/** Every drawn card with its picture: `ds-card` and its slotted picture, or `.ds-card` and its media's. */
+function cards(root) {
+    return Array.from(root.querySelectorAll('ds-card, .ds-card')).flatMap(card => {
+        const slotted = card.localName === 'ds-card'
+            ? card.querySelector(':scope > [slot="media"]')
+            : card.querySelector(':scope > .ds-card__media > *');
+        const picture = slotted?.localName === 'picture' ? slotted.querySelector('img') ?? slotted : slotted;
+        if (!picture)
+            return [];
+        const box = card.getBoundingClientRect();
+        const face = picture.getBoundingClientRect();
+        if (!box.height || !face.height)
+            return [];
+        return [{ card, picture, box, face }];
+    });
+}
+/** The element's parent as drawn: the slot it is given to, the host of the shadow root it is in, or its parent. */
+function drawnParent(element) {
+    if (element.assignedSlot)
+        return element.assignedSlot;
+    const parent = element.parentNode;
+    if (parent && parent.nodeType === Node.DOCUMENT_FRAGMENT_NODE && 'host' in parent)
+        return parent.host;
+    return element.parentElement;
+}
+/** Whether something the element stands in cuts it off or scrolls it, so it cannot widen the page: a slide in
+ *  a carousel's track stands in the track, whichever side of a shadow root the two are on. */
+function contained(element) {
+    for (let box = drawnParent(element); box && box !== element.ownerDocument.documentElement; box = drawnParent(box)) {
+        const style = styleOf(box);
+        if (/hidden|clip|auto|scroll/.test(style.overflowX) || style.position === 'fixed')
+            return true;
+    }
+    return false;
+}
+/** Every piece of the page that is drawn: it has a size. */
+function drawn(root) {
+    return Array.from(root.querySelectorAll('body *')).filter(element => {
+        const box = element.getBoundingClientRect();
+        return box.width > 0 && box.height > 0;
+    });
+}
+/** Sideways scrolling by design: a carousel's track, a table, a block of code and a matrix scroll in their own frame. */
+const SIDEWAYS_BY_DESIGN = '.ds-carousel__track, .ds-carousel, ds-carousel, .ds-table-scroll, .ds-table, ds-table, table, pre, ds-matrix, .ds-matrix';
+/** Every box on the page that scrolls sideways: its overflow lets it, and it holds more than its width. */
+function sidewaysScrollers(root) {
+    return Array.from(root.querySelectorAll('body *')).filter(element => element.clientWidth > 0 && element.scrollWidth > element.clientWidth + 1 && /auto|scroll/.test(styleOf(element).overflowX));
+}
+/** Cards side by side: one parent, one top and one height. */
+function rows(found) {
+    const groups = [];
+    for (const entry of found) {
+        const row = groups.find(([first]) => first.card.parentElement === entry.card.parentElement
+            && near(first.box.top, entry.box.top) && near(first.box.height, entry.box.height));
+        if (row)
+            row.push(entry);
+        else
+            groups.push([entry]);
+    }
+    return groups.filter(row => row.length > 1);
+}
+export const constraints = [
+    {
+        code: 'page.fault-lines',
+        rule: 'Fault lines keep related card and control grids aligned across the whole page, with matching track edges and gaps at every checked viewport width.',
+        why: 'Compare separate sections in the same alignment family; responsive layouts may change together, while unrelated groups and intentional exceptions remain independent.',
+        components: ['ds-page'],
+        check: { file: 'tests/fault-lines.test.ts', test: 'fault lines catch shifted tracks and unequal gaps across sections at each viewport' },
+        measures: ['alignment group', 'alignment groups'], count: root => faultLineGrids(root).length, inspect: inspectFaultLines,
+    },
+    {
+        code: 'select.hug',
+        rule: 'Select and date-picker triggers use hug sizing, never fill sizing or growing to occupy the available row.',
+        components: ['ds-select', 'ds-calendar'],
+        check: { file: 'tests/select-hug.test.ts', test: 'select triggers hug instead of filling their row' },
+        measures: ['select', 'selects'],
+        count: root => root.querySelectorAll('ds-select[data-field]:not([data-listbox]), ds-calendar[picker]').length,
+        inspect: root => Array.from(root.querySelectorAll('ds-select[data-field]:not([data-listbox]), ds-calendar[picker]')).flatMap(element => {
+            const control = element.querySelector('select') ?? element.shadowRoot?.querySelector('.trigger');
+            if (!control || !element.getBoundingClientRect().width)
+                return [];
+            const fills = Number(styleOf(element).flexGrow) > 0 || element.getBoundingClientRect().width > control.getBoundingClientRect().width + 1;
+            return fills ? [{ element, message: 'Use hug sizing; the select must not fill its row.' }] : [];
+        }),
+    },
+    {
+        code: 'button.visible-label',
+        rule: 'Button labels stay fully visible, never faded, gradient-masked or truncated; round the required width up to whole grid squares.',
+        why: 'The action must remain readable; a chosen width cannot cut off its label.',
+        components: ['ds-button'],
+        check: { file: 'tests/button-cut-fade-measure.test.ts', test: 'button labels stay whole without gradients and snap up to the grid' },
+        measures: ['button', 'buttons'], count: root => labelledButtons(root).length, inspect: inspectButtonLabels,
+    },
+    {
+        code: 'text.whole-words',
+        rule: 'Headings and table headers keep each word intact across lines; only a long word that cannot fit may split at a valid language-specific hyphenation point, with a visible hyphen.',
+        why: 'Wrap between words or give the heading more room; never leave a final letter on its own, use break-all or anywhere, or insert an arbitrary line break inside a word. Use the correct lang with automatic hyphenation, or a soft hyphen at an editorially verified break; scripts with other line-breaking conventions keep their own typesetting rules.',
+        components: ['ds-text', 'ds-table'],
+        check: { file: 'tests/word-wrap.test.ts', test: 'headings and table headers keep whole words or use a typesetting hyphen' },
+        measures: ['heading or table header', 'headings and table headers'],
+        count: root => wordHeaders(root).length,
+        inspect: inspectWordWrap,
+    },
+    {
+        code: 'color.text-contrast',
+        rule: 'Visible text, including muted labels, placeholders and avatar initials, has at least 4.5:1 contrast against the background it is drawn on.',
+        why: 'Measure resolved colours through slots and open shadow roots, including transparency and opacity; image backgrounds and effects that cannot be measured need a visual review.',
+        components: ['ds-color', 'ds-text', 'ds-avatar'],
+        check: { file: 'tests/text-contrast.test.ts', test: 'rendered text contrast catches component overrides, slots, alpha and opacity' },
+        measures: ['text sample', 'text samples'],
+        count: root => measureTextContrast(root).length,
+        inspect: inspectTextContrast,
+    },
+    {
+        code: 'avatar.initial-contrast',
+        rule: 'Avatar initials have at least 4.5:1 contrast against their rendered fill, including after a theme or identity colour changes.',
+        why: 'Check each initial inside the avatar’s shadow root and in overlapping groups; decorative initials still need to be readable. Explicit ink overrides must pass too.',
+        components: ['ds-avatar'],
+        check: { file: 'tests/avatar-contrast.test.ts', test: 'avatar initials stay readable after theme and CSS-variable changes, and the avatar constraint catches overrides' },
+        measures: ['avatar initial', 'avatar initials'],
+        count: root => measureTextContrast(root).filter(result => isAvatarInitial(result.element)).length,
+        inspect: root => inspectTextContrast(root).filter(finding => isAvatarInitial(finding.element)),
+    },
+    {
+        code: 'card.media-level',
+        rule: "A card's picture stands on the card's foot, a square below the words at least, so the pictures of cards side by side stand on one level whatever the words above them.",
+        why: 'The room a taller card leaves goes above its picture, never below it, so pictures of one height side by side start on one line too; a taller picture starts higher.',
+        components: ['ds-card'],
+        check: { file: 'tests/card.test.ts', test: "a picture stands on the card's foot, so pictures side by side stand on one level" },
+        measures: ['card with a media picture', 'cards with a media picture'],
+        count: root => cards(root).length,
+        inspect(root) {
+            const found = cards(root);
+            const findings = [];
+            for (const { picture, box, face } of found) {
+                if (face.bottom < box.bottom - 1)
+                    findings.push({ element: picture, message: `The picture stands ${px(box.bottom - face.bottom)} above the card's foot.` });
+            }
+            for (const [first, ...rest] of rows(found)) {
+                for (const { picture, face } of rest) {
+                    if (near(face.height, first.face.height) && !near(face.top, first.face.top))
+                        findings.push({ element: picture, message: `The picture starts ${px(Math.abs(face.top - first.face.top))} ${face.top > first.face.top ? 'lower' : 'higher'} than the one in the first card beside it.` });
+                }
+            }
+            return findings;
+        },
+    },
+    {
+        code: 'card.media-corners',
+        rule: "A picture is never rounded where it meets the card's edge: the card cuts it square there, and only a corner standing free inside the card, towards the words, keeps a picture's corner.",
+        components: ['ds-card'],
+        check: { file: 'tests/card.test.ts', test: "a picture is square where it meets the card's edge" },
+        measures: ['card with a media picture', 'cards with a media picture'],
+        count: root => cards(root).length,
+        inspect(root) {
+            return cards(root).flatMap(({ picture, box, face }) => {
+                const top = face.top <= box.top + 1;
+                const bottom = face.bottom >= box.bottom - 1;
+                const start = face.left <= box.left + 1;
+                const end = face.right >= box.right - 1;
+                const style = styleOf(picture);
+                const corners = [
+                    ['top left', style.borderTopLeftRadius, top || start],
+                    ['top right', style.borderTopRightRadius, top || end],
+                    ['bottom right', style.borderBottomRightRadius, bottom || end],
+                    ['bottom left', style.borderBottomLeftRadius, bottom || start],
+                ];
+                const rounded = corners.filter(([, radius, meets]) => meets && parseFloat(radius) > 0).map(([name]) => name);
+                return rounded.length ? [{ element: picture, message: `The picture's ${rounded.join(' and ')} ${rounded.length > 1 ? 'corners are' : 'corner is'} rounded where it meets the card.` }] : [];
+            });
+        },
+    },
+    {
+        code: 'page.window-width',
+        rule: 'A page is never wider than its window: nothing reaches past either edge unless something it stands in cuts it off or scrolls it, so a phone never zooms the page out or slides it sideways.',
+        why: 'A phone widens a page that is too wide and zooms it out, words and all, so a piece one square too wide spoils every piece on the page; check it at every phone width from 320px up.',
+        components: ['ds-page'],
+        check: { file: 'tests/page.test.ts', test: 'every column of a page can shrink to the window, and below thirty squares every layout stacks' },
+        measures: ['piece', 'pieces'],
+        count: root => drawn(root).length,
+        inspect(root) {
+            const page = root.ownerDocument ?? root;
+            const width = page.documentElement.clientWidth || page.defaultView?.innerWidth || 0;
+            if (!width)
+                return [];
+            const past = (element) => {
+                const box = element.getBoundingClientRect();
+                if (!box.width || !box.height)
+                    return 0;
+                return Math.max(box.right - width, -box.left, 0);
+            };
+            const findings = [];
+            for (const element of drawn(root)) {
+                const reach = past(element);
+                if (reach <= 1 || styleOf(element).position === 'fixed' || contained(element))
+                    continue;
+                // Only the outermost: the element whose own box first passes the edge.
+                if (element.parentElement && past(element.parentElement) > 1)
+                    continue;
+                const box = element.getBoundingClientRect();
+                const side = box.right - width >= -box.left ? 'right' : 'left';
+                findings.push({ element, message: `It reaches ${px(reach)} past the window's ${side} edge, in a window ${px(width)} wide.` });
+            }
+            return findings;
+        },
+    },
+    {
+        code: 'carousel.sideways-scroll',
+        rule: 'Only a carousel scrolls pieces sideways: pieces wider than their column stand in a carousel strip or stack, and nothing else scrolls sideways but a table, a block of code or a matrix in its own frame.',
+        why: 'A box given overflow auto to keep a page in its window hides what is past its edge with nothing to say it is there, no snap and no controls, and a phone slides it where a finger meant to scroll down; make it a ds-carousel strip (slide-width="auto") or stack it.',
+        components: ['ds-carousel'],
+        check: { file: 'tests/carousel.test.ts', test: 'only a carousel scrolls sideways: a plain box that scrolls sideways breaks the rule, a track, a table or a block of code does not' },
+        measures: ['box that scrolls sideways', 'boxes that scroll sideways'],
+        count: root => sidewaysScrollers(root).length,
+        inspect(root) {
+            return sidewaysScrollers(root).filter(element => !element.closest(SIDEWAYS_BY_DESIGN)).map(element => ({
+                element,
+                message: `It holds ${px(element.scrollWidth)} of pieces in ${px(element.clientWidth)} and scrolls them sideways; only a carousel does that.`,
+            }));
+        },
+    },
+];
+/** Every rule a page breaks, in the list's order. */
+export function inspectConstraints(root = document) {
+    return constraints.flatMap(constraint => constraint.inspect(root).map(finding => ({ ...finding, constraint })));
+}
+/** Every rule with how many things it measured on the page and where the page breaks it, in the list's order. */
+export function measureConstraints(root = document) {
+    return constraints.map(constraint => ({ constraint, measured: constraint.count(root), findings: constraint.inspect(root) }));
+}
+/** The component's name as its page is called: `ds-card` is Card. */
+export const componentName = (tag) => {
+    const name = tag.replace(/^ds-/, '').replace(/-/g, ' ');
+    return name.charAt(0).toUpperCase() + name.slice(1);
+};
+/** The rules grouped by the first component that keeps them, in the list's order. */
+export function byComponent(list = constraints) {
+    const groups = new Map();
+    for (const constraint of list) {
+        const tag = constraint.components[0];
+        groups.set(tag, [...(groups.get(tag) ?? []), constraint]);
+    }
+    return [...groups];
+}
+export const skillStart = '<!-- constraints:start (written by scripts/write-constraints.ts from DS1/0-face/constraints.ts) -->';
+export const skillEnd = '<!-- constraints:end -->';
+/** The skill's list: a line a rule, under its component, between the markers. */
+export function skillBlock(list = constraints) {
+    const lines = [skillStart];
+    for (const [tag, rules] of byComponent(list)) {
+        lines.push('', `**${componentName(tag)}** (\`${tag}\`)`, '');
+        for (const { code, rule, why } of rules)
+            lines.push(`- \`${code}\`: ${rule}${why ? ` ${why}` : ''}`);
+    }
+    lines.push('', skillEnd);
+    return lines.join('\n');
+}

package/dist/0-face/copy-text.js

@@ -93,5 +93,5 @@ async function say(copied, words) {
     if (copied)
         toast.success(words);
     else
-        toast.error(words);
+        toast.error(words, { failure: { code: "clipboard.copy", message: "Clipboard copy failed" } });
 }

package/dist/0-face/cut-fade.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Cut words fade, never an ellipsis. Wherever Design system 1 cuts words that do
+ * not fit (a row's name, a tag, a menu entry, a calendar's title), they fade out
+ * over their last square (`var(--ds-unit)`), a mask on the words, so they fade
+ * into whatever is behind them. Words that fit stay crisp: the fade is drawn
+ * only while an element is marked `data-cut="end"`, and this module is what
+ * measures and marks it.
+ *
+ * Every stylesheet writes the fade the same way: the element clips
+ * (`text-overflow: clip`), and only under `[data-cut="end"]` takes
+ * `mask-image: linear-gradient(to right, #000 calc(100% - var(--ds-unit)), transparent)`,
+ * the gradient running to the left in a right-to-left page.
+ *
+ * - `watchCuts()` is the watcher a component owns: it marks the elements it
+ *   watches while `scrollWidth > clientWidth + 1`, measures again when they
+ *   resize, when `measure()` is called (after a render, since words can change
+ *   without the box resizing), once the page's fonts have loaded and, with
+ *   `text: true`, when the words inside them change. `disconnect()` lets go.
+ * - Every watcher measures in the next frame, together with every other one:
+ *   all widths are read, then all marks written, so a page building a few
+ *   hundred words lays itself out once for them rather than once each. Read
+ *   one by one, after each element connected or updated, the words of Ezo's
+ *   landing page laid it out again two hundred times, over half a second.
+ *   Elements that resize are measured the same way, in one pass for all.
+ * - `CutFades` is the same watcher as a Lit reactive controller: it starts when
+ *   its element connects, measures after every update and stops when it
+ *   disconnects.
+ * - `startCutFades()` is for a page without Lit: it marks DS1's native classes
+ *   (`.ds-row__name`, `.ds-sidebar__label`, `.ds-menu__item`, …) in the page,
+ *   and keeps marking them as the page changes. It returns a function that
+ *   stops it.
+ */
+/** The attribute a cut element carries: `data-cut="end"`. */
+export declare const CUT_ATTRIBUTE = "data-cut";
+/**
+ * The native classes DS1's stylesheets fade when they are marked cut, for
+ * `startCutFades()` on a page without Lit.
+ */
+export declare const CUT_FADE_SELECTOR: string;
+/** Whether an element's words are wider than its box. */
+export declare function isCut(element: Element): boolean;
+/** Marks an element `data-cut="end"` while its words do not fit, and takes the mark off when they do. Returns whether it is cut. */
+export declare function markCut(element: Element): boolean;
+/** Elements to watch: one, several, or a function that finds them again at each measure. */
+export type CutSource = Element | Iterable<Element> | (() => Iterable<Element>);
+export type CutWatchOptions = {
+    /** Also measure again when the words inside a watched element change (a MutationObserver). */
+    text?: boolean;
+};
+export type CutWatcher = {
+    /** Watches these elements and measures them. A function is asked again at each measure, so elements a render adds are taken in. */
+    watch(source: CutSource): void;
+    /** Watches what matches `selector` inside `root`, found again at each measure. */
+    select(root: ParentNode, selector: string): void;
+    /** Measures every watched element again: after a render, or when words change. */
+    measure(): void;
+    /** Stops watching and lets every element go. Marks stay as they are. */
+    disconnect(): void;
+};
+/** A watcher that marks the elements it watches `data-cut="end"` while their words do not fit. */
+export declare function watchCuts(options?: CutWatchOptions): CutWatcher;
+/**
+ * The part of a Lit element `CutFades` uses, so this module needs nothing from
+ * Lit. The render root is read as a node to search; it is typed loosely so an
+ * element type-checks in every product, whichever DOM library it compiles with.
+ */
+type ControllerHost = Element & {
+    addController(controller: {
+        hostConnected?(): void;
+        hostUpdated?(): void;
+        hostDisconnected?(): void;
+    }): void;
+    readonly renderRoot?: unknown;
+};
+export type CutFadeOptions = {
+    /** What to measure in the element's render root (its shadow root), found again after every update. */
+    selector?: string;
+    /** Other elements to measure, asked again after every update: the host itself, its slotted children. */
+    targets?: () => Iterable<Element>;
+    /** Also measure again when the element's own children or words change (the words slotted into it). */
+    text?: boolean;
+};
+/**
+ * The cut-words watcher as a Lit reactive controller:
+ * `protected readonly cuts = new CutFades(this, { selector: ".label" })`. It watches from
+ * when the element connects to when it disconnects, and measures after every
+ * update; call `measure()` when words change outside an update.
+ */
+export declare class CutFades {
+    private watcher;
+    private words;
+    private readonly host;
+    private readonly options;
+    constructor(host: ControllerHost, options: CutFadeOptions);
+    hostConnected(): void;
+    hostUpdated(): void;
+    hostDisconnected(): void;
+    /** Measures again, as after an update. */
+    measure(): void;
+}
+/**
+ * Marks DS1's native classes cut on a page without Lit, so their words fade
+ * where they are cut, and keeps marking them as the page changes. Returns a
+ * function that stops it.
+ *
+ * @example
+ * // A module script on the page, beside one.css and controls.css (Sync 1 `root` `"modules": ["cut-fade"]`):
+ * startCutFades();
+ */
+export declare function startCutFades(root?: ParentNode, selector?: string): () => void;
+export {};
+//# sourceMappingURL=cut-fade.d.ts.map

package/dist/0-face/cut-fade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cut-fade.d.ts","sourceRoot":"","sources":["../../DS1/0-face/cut-fade.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,6DAA6D;AAC7D,eAAO,MAAM,aAAa,aAAa,CAAC;AAExC;;;GAGG;AACH,eAAO,MAAM,iBAAiB,QAYlB,CAAC;AAEb,yDAAyD;AACzD,wBAAgB,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAE/C;AAED,oIAAoI;AACpI,wBAAgB,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAOjD;AAED,4FAA4F;AAC5F,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;AAEhF,MAAM,MAAM,eAAe,GAAG;IAC5B,8FAA8F;IAC9F,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,mIAAmI;IACnI,KAAK,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC;IAC/B,kFAAkF;IAClF,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjD,kFAAkF;IAClF,OAAO,IAAI,IAAI,CAAC;IAChB,wEAAwE;IACxE,UAAU,IAAI,IAAI,CAAC;CACpB,CAAC;AAoFF,kGAAkG;AAClG,wBAAgB,SAAS,CAAC,OAAO,GAAE,eAAoB,GAAG,UAAU,CAoDnE;AAGD;;;;GAIG;AACH,KAAK,cAAc,GAAG,OAAO,GAAG;IAC9B,aAAa,CAAC,UAAU,EAAE;QAAE,aAAa,CAAC,IAAI,IAAI,CAAC;QAAC,WAAW,CAAC,IAAI,IAAI,CAAC;QAAC,gBAAgB,CAAC,IAAI,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IAC7G,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,sGAAsG;IACtG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wGAAwG;IACxG,OAAO,CAAC,EAAE,MAAM,QAAQ,CAAC,OAAO,CAAC,CAAC;IAClC,sGAAsG;IACtG,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF;;;;;GAKG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiB;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;gBAE7B,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,cAAc;IAMzD,aAAa;IAcb,WAAW;IAEX,gBAAgB;IAOhB,0CAA0C;IAC1C,OAAO;CACR;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,GAAE,UAAqB,EAAE,QAAQ,GAAE,MAA0B,GAAG,MAAM,IAAI,CAY3G"}