@setsquare/review-sdk 0.0.1 → 0.1.0

package/dist/viewports.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Width bands, and the names the artifacts group by.
+ *
+ * ## These name a WIDTH, not a device
+ *
+ * "Laptop", "tablet" and "mobile" are what a reader scanning a page of evidence
+ * is actually asking about, so the grouping uses those words — but nothing here
+ * detects a device and nothing could. A viewport is a number of CSS pixels; the
+ * machine behind it might be a phone, a tablet, a laptop window dragged narrow,
+ * or a desktop browser with text at 200%. This repository's own suite produces
+ * that last one: `reflow.spec.ts` halves 1280×1024 to emulate 200% text for
+ * WCAG 1.4.4, and its 640×512 scans land in the mobile band despite no phone
+ * being anywhere near them.
+ *
+ * That is not a flaw in the grouping, it is the reason the legend exists and is
+ * rendered beside every one of these tables. The band is shorthand; the exact
+ * size is always shown next to it, and the legend says which is which. A
+ * document that said "mobile" and hid the number would be claiming something it
+ * cannot know.
+ *
+ * ## Where the boundaries come from
+ *
+ * 768 and 1024, which are the conventional `md` and `lg` breakpoints — the ones
+ * Tailwind, Bootstrap and most design systems already use, and therefore the
+ * widths a customer's own CSS is most likely to change at. A band boundary that
+ * does not line up with a real breakpoint groups together layouts that are not
+ * the same layout, which is the one thing this is for.
+ *
+ * Three bands rather than five. The question a reader has is "did anything look
+ * at this narrow", and splitting mobile from small-mobile answers a question
+ * nobody asked while making every table a third longer.
+ */
+/** A viewport, as the envelope records it. */
+export interface ViewportSize {
+    width: number;
+    height: number;
+}
+export interface ViewportBand {
+    id: 'laptop' | 'tablet' | 'mobile';
+    /** The word shown as a group heading. */
+    label: string;
+    /** Inclusive lower bound, in CSS pixels. */
+    minWidth: number;
+    /** The bound in words, for the legend: `1024px and wider`. */
+    range: string;
+}
+/**
+ * Widest first, which is the order every artifact groups in.
+ *
+ * Widest first rather than narrowest because a reader arrives knowing what the
+ * desktop looks like, and the interesting rows are the ones further down. The
+ * order is also the order the bands were added to a suite: nobody starts with
+ * the phone.
+ */
+export declare const VIEWPORT_BANDS: readonly ViewportBand[];
+/** The one sentence every artifact prints beside a band name. */
+export declare const VIEWPORT_BAND_NOTE: string;
+/**
+ * The fragment a band's heading answers to, so one document can link into
+ * another's grouping.
+ *
+ * Here rather than at either call site because it is a contract between two
+ * files: the contact sheet writes these ids onto its headings and the report
+ * writes them into its hrefs, and a link that agrees with nothing is worse than
+ * no link. Derived from the band id, so a band cannot be renamed on one side
+ * only.
+ */
+export declare function viewportBandAnchor(band: ViewportBand): string;
+/** `1280×720`. The multiplication sign, not an x: this is a size. */
+export declare function viewportSize(viewport: ViewportSize): string;
+/**
+ * Which band a width falls in. Never undefined — the last band has no floor.
+ *
+ * Takes the width alone. Height is recorded and displayed because it is a fact
+ * about the run, but no breakpoint in anybody's CSS is a height, so grouping by
+ * one would split a band for a reason no layout has.
+ */
+export declare function viewportBand(width: number): ViewportBand;
+export interface BandGroup<T> {
+    band: ViewportBand;
+    /** Every distinct size seen in this band, widest first. */
+    sizes: string[];
+    items: T[];
+}
+/**
+ * Group anything that carries a viewport into bands, widest band first.
+ *
+ * Bands with nothing in them are dropped rather than rendered empty: a heading
+ * whose only content is "nothing here" is worse than the absence device, which
+ * is what the documents use to say a band was never looked at.
+ *
+ * **Order within a band is the order given.** Every caller has already sorted
+ * its items for a reason — the contact sheet leads with comparisons and then
+ * failures, the surfaces table leads with the worst — and re-sorting here would
+ * quietly overrule that.
+ *
+ * Items with no viewport at all go in a group with no band, returned last: a
+ * run driving a real device controls no viewport, and dropping those rows would
+ * lose evidence to make a table tidy.
+ */
+export declare function groupByBand<T>(items: readonly T[], viewportOf: (item: T) => ViewportSize | undefined): {
+    groups: BandGroup<T>[];
+    unbanded: T[];
+};
+//# sourceMappingURL=viewports.d.ts.map

package/dist/viewports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewports.d.ts","sourceRoot":"","sources":["../src/viewports.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,8CAA8C;AAC9C,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACnC,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,YAAY,EAIjD,CAAC;AAEF,iEAAiE;AACjE,eAAO,MAAM,kBAAkB,QAGuC,CAAC;AAEvE;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAE7D;AAED,qEAAqE;AACrE,wBAAgB,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,CAE3D;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAOxD;AAED,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,IAAI,EAAE,YAAY,CAAC;IACnB,2DAA2D;IAC3D,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,CAAC,EAAE,CAAC;CACZ;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,UAAU,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,YAAY,GAAG,SAAS,GAChD;IAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;IAAC,QAAQ,EAAE,CAAC,EAAE,CAAA;CAAE,CAoC3C"}

package/dist/viewports.js

@@ -0,0 +1,134 @@
+/**
+ * Width bands, and the names the artifacts group by.
+ *
+ * ## These name a WIDTH, not a device
+ *
+ * "Laptop", "tablet" and "mobile" are what a reader scanning a page of evidence
+ * is actually asking about, so the grouping uses those words — but nothing here
+ * detects a device and nothing could. A viewport is a number of CSS pixels; the
+ * machine behind it might be a phone, a tablet, a laptop window dragged narrow,
+ * or a desktop browser with text at 200%. This repository's own suite produces
+ * that last one: `reflow.spec.ts` halves 1280×1024 to emulate 200% text for
+ * WCAG 1.4.4, and its 640×512 scans land in the mobile band despite no phone
+ * being anywhere near them.
+ *
+ * That is not a flaw in the grouping, it is the reason the legend exists and is
+ * rendered beside every one of these tables. The band is shorthand; the exact
+ * size is always shown next to it, and the legend says which is which. A
+ * document that said "mobile" and hid the number would be claiming something it
+ * cannot know.
+ *
+ * ## Where the boundaries come from
+ *
+ * 768 and 1024, which are the conventional `md` and `lg` breakpoints — the ones
+ * Tailwind, Bootstrap and most design systems already use, and therefore the
+ * widths a customer's own CSS is most likely to change at. A band boundary that
+ * does not line up with a real breakpoint groups together layouts that are not
+ * the same layout, which is the one thing this is for.
+ *
+ * Three bands rather than five. The question a reader has is "did anything look
+ * at this narrow", and splitting mobile from small-mobile answers a question
+ * nobody asked while making every table a third longer.
+ */
+/**
+ * Widest first, which is the order every artifact groups in.
+ *
+ * Widest first rather than narrowest because a reader arrives knowing what the
+ * desktop looks like, and the interesting rows are the ones further down. The
+ * order is also the order the bands were added to a suite: nobody starts with
+ * the phone.
+ */
+export const VIEWPORT_BANDS = [
+    { id: 'laptop', label: 'Laptop', minWidth: 1024, range: '1024px and wider' },
+    { id: 'tablet', label: 'Tablet', minWidth: 768, range: '768px to 1023px' },
+    { id: 'mobile', label: 'Mobile', minWidth: 0, range: 'narrower than 768px' },
+];
+/** The one sentence every artifact prints beside a band name. */
+export const VIEWPORT_BAND_NOTE = 'These name a width, not a device. Nothing here detects what a page was opened on — ' +
+    'a 640px viewport is in the mobile band whether it is a phone or a desktop browser ' +
+    'with text at 200%. The exact size is always shown beside the name.';
+/**
+ * The fragment a band's heading answers to, so one document can link into
+ * another's grouping.
+ *
+ * Here rather than at either call site because it is a contract between two
+ * files: the contact sheet writes these ids onto its headings and the report
+ * writes them into its hrefs, and a link that agrees with nothing is worse than
+ * no link. Derived from the band id, so a band cannot be renamed on one side
+ * only.
+ */
+export function viewportBandAnchor(band) {
+    return `band-${band.id}`;
+}
+/** `1280×720`. The multiplication sign, not an x: this is a size. */
+export function viewportSize(viewport) {
+    return `${viewport.width}×${viewport.height}`;
+}
+/**
+ * Which band a width falls in. Never undefined — the last band has no floor.
+ *
+ * Takes the width alone. Height is recorded and displayed because it is a fact
+ * about the run, but no breakpoint in anybody's CSS is a height, so grouping by
+ * one would split a band for a reason no layout has.
+ */
+export function viewportBand(width) {
+    for (const band of VIEWPORT_BANDS) {
+        if (width >= band.minWidth)
+            return band;
+    }
+    // Unreachable while the last band's floor is 0, and cheaper than a non-null
+    // assertion that would stop being true if somebody reordered the list.
+    return VIEWPORT_BANDS[VIEWPORT_BANDS.length - 1];
+}
+/**
+ * Group anything that carries a viewport into bands, widest band first.
+ *
+ * Bands with nothing in them are dropped rather than rendered empty: a heading
+ * whose only content is "nothing here" is worse than the absence device, which
+ * is what the documents use to say a band was never looked at.
+ *
+ * **Order within a band is the order given.** Every caller has already sorted
+ * its items for a reason — the contact sheet leads with comparisons and then
+ * failures, the surfaces table leads with the worst — and re-sorting here would
+ * quietly overrule that.
+ *
+ * Items with no viewport at all go in a group with no band, returned last: a
+ * run driving a real device controls no viewport, and dropping those rows would
+ * lose evidence to make a table tidy.
+ */
+export function groupByBand(items, viewportOf) {
+    const byBand = new Map();
+    const unbanded = [];
+    for (const item of items) {
+        const viewport = viewportOf(item);
+        if (!viewport) {
+            unbanded.push(item);
+            continue;
+        }
+        const band = viewportBand(viewport.width);
+        const slot = byBand.get(band.id) ?? {
+            band,
+            sizes: new Map(),
+            items: [],
+        };
+        slot.sizes.set(viewportSize(viewport), viewport.width);
+        slot.items.push(item);
+        byBand.set(band.id, slot);
+    }
+    const groups = VIEWPORT_BANDS.flatMap((band) => {
+        const slot = byBand.get(band.id);
+        if (!slot)
+            return [];
+        return [
+            {
+                band,
+                sizes: [...slot.sizes]
+                    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+                    .map(([size]) => size),
+                items: slot.items,
+            },
+        ];
+    });
+    return { groups, unbanded };
+}
+//# sourceMappingURL=viewports.js.map

package/dist/viewports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewports.js","sourceRoot":"","sources":["../src/viewports.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@setsquare/review-sdk",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Accessibility, e2e and performance evidence capture for Playwright. Phase 0 ships the packaging skeleton only — scan/fixture/reporter logic is Phase 1.",
   "license": "Apache-2.0",
   "homepage": "https://setsquare.dev",
@@ -50,8 +50,8 @@
   "dependencies": {
     "axe-core": "4.13.0",
     "text-readability": "1.1.1",
-    "@setsquare/review-cli": "^0.0.1",
-    "@setsquare/schema": "^0.0.1"
+    "@setsquare/review-cli": "^0.1.0",
+    "@setsquare/schema": "^0.1.0"
   },
   "devDependencies": {
     "@axe-core/playwright": "4.13.0",
@@ -59,7 +59,7 @@
     "@types/node": "^22.20.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.10",
-    "@setsquare/review-sdk": "0.0.1"
+    "@setsquare/review-sdk": "0.1.0"
   },
   "publishConfig": {
     "access": "public"
@@ -74,6 +74,7 @@
     "test": "vitest run --passWithNoTests",
     "fixtures:serve": "node fixtures/serve.mjs",
     "fixtures:test": "playwright test -c fixtures/playwright.config.ts",
+    "fixtures:test:aaa": "playwright test -c fixtures/playwright.aaa.config.ts",
     "fixtures:test:parallel": "playwright test -c fixtures/playwright.parallel.config.ts",
     "fixtures:test:engines": "pnpm build && playwright test -c fixtures/playwright.engines.config.ts",
     "fixtures:test:grouped": "pnpm build && node fixtures/run-grouped.mjs"