tosijs-ui 1.17.0-beta.2 → 1.17.0-beta.3

package/CHANGELOG.md

@@ -1,6 +1,20 @@
 # Changelog
 
-## 1.17.0-beta.2
+## 1.17.0-beta.3
+
+> Prerelease, published under the `beta` dist-tag: install with `tosijs-ui@beta`. `latest` stays
+> on 1.16.41. beta.2 was staged and never published; its notes follow.
+
+- **The axe audit waits for a page marked `aria-busy`, and one slow page no longer ends it.** A
+  page that is still loading (a 3D scene fetching large models, say) marks an element
+  `aria-busy="true"`, the standard ARIA signal, and is waited for up to 30 seconds; other pages
+  are audited once they have stopped adding elements, or after five seconds. A page that never
+  loads, or is still busy at 30 seconds, is listed as not fully checked, and the build makes no
+  claim about it. Before, each page load waited for the network to go idle, so a page that kept
+  downloading for 30 seconds, or that polled, threw and ended the audit of every page. The doc
+  site reference shows a component setting and clearing `aria-busy`.
+
+### 1.17.0-beta.2 (prerelease detail)
 
 > Prerelease, published under the `beta` dist-tag: install with `tosijs-ui@beta`. `latest` stays
 > on 1.16.41. Fixes from Learn 3D's first run of beta.1.

package/dist/doc-system/site/a11y-audit-cli.js

@@ -10,7 +10,7 @@ tosijs-ui. When either is missing, or Chromium is not installed, it says which a
 NOT_RUN_EXIT, so the build can say the audit did not run instead of reporting a pass.
 
   bun a11y-audit-cli.ts <payload.json>   # payload = { outputDir, basePath, pages }
-  stdout: one JSON line, { violations: AxeFinding[] }
+  stdout: one JSON line, { violations: AxeFinding[], unsettled: { page, reason }[] }
 
 Build-time only. Never import this from browser code.
 */
@@ -19,7 +19,7 @@ import { createRequire } from 'module';
 import { existsSync } from 'fs';
 import { NOT_RUN_EXIT, AXE_TAGS } from './a11y-audit.js';
 const payloadPath = process.argv[2];
-const { outputDir, basePath, pages } = JSON.parse(await Bun.file(payloadPath).text());
+const { outputDir, basePath, pages, slowPageMs } = JSON.parse(await Bun.file(payloadPath).text());
 const notRun = (why) => {
     console.error(why);
     process.exit(NOT_RUN_EXIT);
@@ -69,7 +69,12 @@ Pages are audited a few at a time, each in its own tab: one at a time took Learn
 to ~73s (#3585). Results are kept in page order, so the report reads the same either way.
 */
 const CONCURRENCY = 4;
+/** How long a page may take to fire `load`, and to finish being `aria-busy`. */
+const SLOW_PAGE_MS = slowPageMs ?? 30_000;
+/** How long an un-busy page may keep adding elements before it is audited as it stands. */
+const QUIET_CAP_MS = 5_000;
 const perPage = [];
+const unsettled = [];
 try {
     const context = await browser.newContext();
     /*
@@ -83,9 +88,32 @@ try {
         while (next < pages.length) {
             const index = next++;
             const pagePath = pages[index];
-            await page.goto(`http://localhost:${server.port}${prefix}${pagePath}`, {
-                waitUntil: 'networkidle',
-            });
+            /*
+            One slow or broken page must not end the audit of every other page, and must not pass
+            unremarked either: it is listed as not fully checked.
+            */
+            try {
+                await page.goto(`http://localhost:${server.port}${prefix}${pagePath}`, {
+                    waitUntil: 'load',
+                    timeout: SLOW_PAGE_MS,
+                });
+            }
+            catch (error) {
+                const message = error.message.split('\n')[0];
+                if (!/timeout/i.test(message)) {
+                    unsettled.push({ page: pagePath, reason: `not audited: ${message}` });
+                    perPage[index] = [];
+                    continue;
+                }
+                unsettled.push({
+                    page: pagePath,
+                    reason: `did not finish loading in ${SLOW_PAGE_MS / 1000}s; audited as it stood`,
+                });
+            }
+            // Best effort: a page that polls or streams never goes idle, and that is not a defect.
+            await page
+                .waitForLoadState('networkidle', { timeout: 10_000 })
+                .catch(() => undefined);
             // Audit the page a reader uses: hydrated when the bundle loads, static if it does not.
             if (await page.$('tosi-doc-system'))
                 await page
@@ -94,26 +122,42 @@ try {
                 })
                     .catch(() => undefined);
             /*
-            Then until no element has been added or removed for half a second (at most five): live examples render
-            after hydration, and a fixed pause audited a busy machine's pages half-built, so the
-            findings changed from run to run.
+            Then until the page has settled: no element added or removed for half a second, and
+            nothing marked `aria-busy="true"`. A fixed pause audited a busy machine's pages
+            half-built. A page that is still loading (a 3D scene fetching its models, say) says so with
+            aria-busy, which screen readers also announce, and is waited for up to SLOW_PAGE_MS; one
+            that merely keeps changing is audited after QUIET_CAP_MS.
             */
-            await page.evaluate(() => new Promise((resolve) => {
-                let timer = setTimeout(done, 500);
-                const deadline = setTimeout(done, 5000);
+            const settled = await page.evaluate(({ quietCap, busyCap }) => new Promise((resolve) => {
+                const start = performance.now();
+                let last = start;
                 const observer = new MutationObserver(() => {
-                    clearTimeout(timer);
-                    timer = setTimeout(done, 500);
+                    last = performance.now();
                 });
-                function done() {
-                    observer.disconnect();
-                    clearTimeout(timer);
-                    clearTimeout(deadline);
-                    resolve();
-                }
                 // Elements arriving, not attributes: an animation changes a style forever.
                 observer.observe(document, { subtree: true, childList: true });
-            }));
+                const tick = () => {
+                    const now = performance.now();
+                    const busy = !!document.querySelector('[aria-busy="true"]');
+                    const outcome = now - last >= 500 && !busy
+                        ? 'settled'
+                        : !busy && now - start >= quietCap
+                            ? 'changing'
+                            : now - start >= busyCap
+                                ? 'busy'
+                                : '';
+                    if (!outcome)
+                        return void setTimeout(tick, 100);
+                    observer.disconnect();
+                    resolve(outcome);
+                };
+                tick();
+            }), { quietCap: QUIET_CAP_MS, busyCap: SLOW_PAGE_MS });
+            if (settled === 'busy')
+                unsettled.push({
+                    page: pagePath,
+                    reason: `still aria-busy after ${SLOW_PAGE_MS / 1000}s; audited as it stood`,
+                });
             await page.addScriptTag({ path: axePath });
             const found = await page.evaluate(async (tags) => {
                 const result = await window.axe.run(document, {
@@ -136,4 +180,4 @@ finally {
     server.stop(true);
 }
 const violations = perPage.flat();
-console.log(JSON.stringify({ violations }));
+console.log(JSON.stringify({ violations, unsettled }));

package/dist/doc-system/site/a11y-audit.d.ts

@@ -11,9 +11,15 @@ export interface AxeFinding {
     /** a CSS selector for each element that fails the rule */
     targets: string[];
 }
+/** A page the audit could not check fully: it never loaded, or never stopped being busy. */
+export interface UnsettledPage {
+    page: string;
+    reason: string;
+}
 export type AxeAuditResult = {
     ran: true;
     violations: AxeFinding[];
+    unsettled: UnsettledPage[];
 } | {
     ran: false;
     reason: string;
@@ -25,6 +31,8 @@ export declare function auditBuiltSite(opts: {
     pages: string[];
     /** the project Playwright and axe-core are resolved from (default: the working directory) */
     projectDir?: string;
+    /** how long a page may take to load, or stay `aria-busy="true"` (default 30s) */
+    slowPageMs?: number;
 }): Promise<AxeAuditResult>;
 /** The report: one line per rule per page, worst impact first. */
 export declare function formatAxeFindings(violations: AxeFinding[]): string;

package/dist/doc-system/site/a11y-audit.js

@@ -25,6 +25,7 @@ export async function auditBuiltSite(opts) {
         outputDir: path.resolve(opts.outputDir),
         basePath: opts.basePath ?? '',
         pages: opts.pages,
+        slowPageMs: opts.slowPageMs,
     }));
     // `--no-install`: without it Bun resolves a package the project does not have from its global
     // cache, so "not installed" would never be said and the audit would use a Playwright nobody chose.
@@ -42,8 +43,10 @@ export async function auditBuiltSite(opts) {
         return { ran: false, reason: stderr.trim() };
     const line = stdout.trim().split('\n').pop() ?? '';
     try {
-        if (code === 0)
-            return { ran: true, ...JSON.parse(line) };
+        if (code === 0) {
+            const { violations, unsettled = [] } = JSON.parse(line);
+            return { ran: true, violations, unsettled };
+        }
     }
     catch {
         // fall through: a run that printed no result did not run

package/dist/doc-system/site/orchestrator.js

@@ -1706,12 +1706,25 @@ export async function buildSite(config, opts = {}) {
                     console.warn(`\n⚠️  Accessibility: the axe audit did not run, so this build makes no claim\n` +
                         `    about what it would find. ${audit.reason}\n`);
                 }
-                else if (audit.violations.length) {
-                    misconfigured(config.strict, `\n⚠️  Accessibility: axe found ${audit.violations.length} WCAG 2.2 AA failure(s) in the built pages:\n` +
-                        `${formatAxeFindings(audit.violations)}\n`);
-                }
                 else {
-                    console.log(`♿ axe: no WCAG 2.2 AA failures in ${pages.length} page(s)`);
+                    // A page the audit could not check fully is said, never counted as clean.
+                    if (audit.unsettled.length)
+                        console.warn(`\n⚠️  Accessibility: ${audit.unsettled.length} page(s) were not fully checked, so ` +
+                            `this build makes no claim about them. A page that is still loading should mark ` +
+                            `itself aria-busy="true"; the audit waits up to 30s for it:\n` +
+                            audit.unsettled
+                                .map((u) => `    ${u.page}  ${u.reason}`)
+                                .join('\n') +
+                            '\n');
+                    const checked = pages.length - audit.unsettled.length;
+                    if (audit.violations.length)
+                        misconfigured(config.strict, `\n⚠️  Accessibility: axe found ${audit.violations.length} WCAG 2.2 AA failure(s) in the built pages:\n` +
+                            `${formatAxeFindings(audit.violations)}\n`);
+                    else
+                        console.log(`♿ axe: no WCAG 2.2 AA failures in ${checked} fully checked page(s)` +
+                            (audit.unsettled.length
+                                ? ` (${audit.unsettled.length} not fully checked, above)`
+                                : ''));
                 }
             }
             console.timeEnd('build');