@setsquare/review-sdk 0.0.1 → 0.1.1

package/dist/checks/context-change.d.ts

@@ -0,0 +1,96 @@
+import type { Page } from '@playwright/test';
+import type { DynamicCheckEvidence } from './dynamic.js';
+/**
+ * WCAG 3.2.1 On Focus (A) and 3.2.2 On Input (A): does touching a control
+ * change the context without being asked to?
+ *
+ * "Change of context" is normatively defined — user agent, viewport, focus, or
+ * content that changes the meaning of the page — and the first three are
+ * observable. The fourth is a judgement, so a large DOM mutation is
+ * needs-review rather than a violation.
+ *
+ * ---------------------------------------------------------------------------
+ * **The two halves have very different side effects, so they are gated
+ * differently. That is the decision this check exists around.**
+ *
+ * **3.2.1 is on by default.** It needs nothing the teardown focus walk does not
+ * already do — focusing every focusable element — so it adds no new class of
+ * side effect to a run that is already focusing them.
+ *
+ * **3.2.2 is opt-in, off by default** (`onInput: true`). It has to CHANGE a
+ * control's value, and a change event is where an application saves. A
+ * customer's page at teardown can be an authenticated application whose select
+ * has an autosave handler behind it, and mutating their data is a worse failure
+ * than any finding this rule could produce — worse, in particular, than being a
+ * flake, because a flake is visible and a silent write is not. So it is a
+ * choice somebody makes, and while it is off the criterion reports as "a check
+ * that did not run here", which is exactly what it is.
+ *
+ * **Text fields are never typed into, at any setting.** Only `<select>`,
+ * checkboxes and radios are touched, and their value is put back. Typing into a
+ * text field is a different risk class again: validation requests, autosave,
+ * character counters, and a half-filled form left behind.
+ * ---------------------------------------------------------------------------
+ */
+export declare const SETSQUARE_CONTEXT_CHECK_VERSION = "setsquare-context@1";
+export declare const ON_FOCUS_RULE_ID = "setsquare-on-focus";
+export declare const ON_INPUT_RULE_ID = "setsquare-on-input";
+declare const MAX_CONTROLS = 40;
+export interface ContextChangeRow {
+    selector: string;
+    /** What was observed: `focus-moved`, `window-opened`, `navigated`, `mutation`. */
+    kind: 'focus-moved' | 'window-opened' | 'navigated' | 'mutation';
+    /** Where focus went, or what was navigated to, when we could see it. */
+    detail?: string;
+    /** Nodes added or removed, for a `mutation` row. */
+    nodes?: number;
+}
+export interface ContextWalk {
+    /** Controls actually touched. Zero means nothing this criterion regulates. */
+    checked: number;
+    /** Candidates found, before the ceiling. */
+    found: number;
+    truncated: boolean;
+    changes: ContextChangeRow[];
+}
+/**
+ * Focus every focusable element and watch for an unrequested change of context.
+ *
+ * Runs entirely in the page, in one evaluate, because a round trip per element
+ * over a hundred and twenty of them at the end of every test is a cost nobody
+ * agreed to. That bounds what it can see, and the boundary is stated in the
+ * finding rather than papered over: `window.open` and `location.assign` /
+ * `location.replace` are patched and recorded, but `location.href = …` is a
+ * native setter on a non-configurable object and cannot be intercepted. A page
+ * that navigates that way on focus destroys the execution context, which
+ * surfaces as no evidence at all rather than as a pass.
+ */
+export declare function runOnFocus(page: Page): Promise<DynamicCheckEvidence>;
+/**
+ * Change each `<select>`, checkbox and radio, and watch for a change of
+ * context. Opt-in; see the decision at the top of this file.
+ *
+ * Driven from Node rather than from one evaluate, unlike 3.2.1, because the
+ * failure this exists to catch — a select whose handler does
+ * `location.href = this.value` — navigates through a native setter that cannot
+ * be patched from inside the page. Playwright can see the navigation request
+ * and abort it before it commits, which is both how we detect it and how we
+ * stop it destroying the run. There are rarely more than a handful of such
+ * controls on a page, so the round trips are affordable in a way a
+ * hundred-and-twenty-element focus walk is not.
+ *
+ * Three guards, in this order, and the first is the one that matters most:
+ *
+ * 1. **Nothing is ever submitted.** A capture-phase listener cancels every
+ *    `submit` event and records that it happened — so an attempted submit is
+ *    the finding AND the thing that did not occur. A submit triggered by our
+ *    own input would be worse than any finding: it writes.
+ * 2. **No navigation commits.** Navigation requests are aborted at the route
+ *    level. The attempt is what we report.
+ * 3. **Every value is put back**, in a `finally`, whatever happened.
+ */
+export declare function runOnInput(page: Page): Promise<DynamicCheckEvidence>;
+export declare function onFocusEvidence(walk: ContextWalk): DynamicCheckEvidence;
+export declare function onInputEvidence(walk: ContextWalk): DynamicCheckEvidence;
+export { MAX_CONTROLS };
+//# sourceMappingURL=context-change.d.ts.map

package/dist/checks/context-change.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-change.d.ts","sourceRoot":"","sources":["../../src/checks/context-change.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAI7C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,eAAO,MAAM,+BAA+B,wBAAwB,CAAC;AAErE,eAAO,MAAM,gBAAgB,uBAAuB,CAAC;AACrD,eAAO,MAAM,gBAAgB,uBAAuB,CAAC;AAIrD,QAAA,MAAM,YAAY,KAAK,CAAC;AAwBxB,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,IAAI,EAAE,aAAa,GAAG,eAAe,GAAG,WAAW,GAAG,UAAU,CAAC;IACjE,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAID;;;;;;;;;;;GAWG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAU1E;AA8OD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,oBAAoB,CAAC,CA2E1E;AAyKD,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,GAAG,oBAAoB,CAQvE;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,GAAG,oBAAoB,CAQvE;AAuFD,OAAO,EAAE,YAAY,EAAE,CAAC"}