uidex 0.7.0 → 0.8.0

package/dist/playwright/states.d.ts

@@ -0,0 +1,120 @@
+import { Page, TestInfo } from '@playwright/test';
+
+/**
+ * Deterministic render-state capture for `uidex/playwright`.
+ *
+ * Two jobs, deliberately split:
+ *   1. RECORD which `entity/state` a test captured (a `uidex-states`
+ *      attachment) — the reporter aggregates these into `uidex-states.json`,
+ *      which the scanner's completeness gate cross-checks against the states
+ *      declared in `export const uidex = { states: [...] }`.
+ *   2. SHOOT the pixels — a thin wrapper over native `page.screenshot`. The
+ *      determinism knobs are Playwright's own: `animations: "disabled"` and
+ *      `caret: "hide"` are defaults, `style`/`stylePath` pierces the shadow DOM
+ *      to hide dev chrome, `mask` covers non-deterministic regions, and the
+ *      frozen clock / locale / timezone / colour-scheme live in the project's
+ *      `use` block. uidex does not re-implement `settle()`.
+ *
+ * The recording is the load-bearing half: even a spec that shoots nothing can
+ * call `recordState` so the gate knows the state exists.
+ */
+declare const STATES_ATTACHMENT = "uidex-states";
+/** Default light + dark; many surfaces use theme-dependent colours. */
+declare const THEMES: readonly ["light", "dark"];
+/** Desktop is primary; narrow exercises the responsive reflow. */
+declare const WIDTHS: {
+    readonly desktop: 1440;
+    readonly narrow: 430;
+};
+type Theme = (typeof THEMES)[number];
+type WidthLabel = keyof typeof WIDTHS;
+type StateEntityKind = "page" | "feature" | "widget";
+/** The four kinds the state-matrix gate expects every captured route to cover. */
+declare const CORE_STATE_KINDS: readonly ["loading", "empty", "populated", "error"];
+type CoreStateKind = (typeof CORE_STATE_KINDS)[number];
+/** `variant` = any state outside the matrix (dialog, wizard step, multi-currency…). */
+type StateKind = CoreStateKind | "variant";
+/** One captured `entity/state` variant. */
+interface StateRecord {
+    /** Registry entity id whose state was rendered (e.g. "products"). */
+    entity: string;
+    /** Entity kind, so the gate can disambiguate a page vs feature of the same id. */
+    kind?: StateEntityKind;
+    /** Declared state name (e.g. "new-filled"). */
+    state: string;
+    /** Canonical kind for the state-matrix axis (defaults inferred from the name). */
+    stateKind?: StateKind;
+    theme?: string;
+    width?: string;
+    /** Screenshot path, when one was written. */
+    path?: string;
+    /**
+     * The URL pathname the capture ran against, observed from `page.url()`. The
+     * page-coverage gate normalizes it to a derived route pattern — so which route
+     * a capture exercised is observed, never hand-declared. A `/shots/*` harness
+     * URL matches no real route and gates nothing (correct for component captures).
+     */
+    url?: string;
+    /** Explicit route pattern override, when the observed URL can't be trusted. */
+    route?: string;
+}
+/** The `uidex-states` attachment body — an array of records from one test. */
+interface StatesPayload {
+    records: StateRecord[];
+}
+type TestInfoLike = Pick<TestInfo, "attach">;
+/**
+ * Attach one or more captured-state records to the test. Idempotent per call;
+ * the reporter concatenates every test's records. Use directly when you shoot
+ * with your own screenshot call and only need the state registered for the gate.
+ */
+declare function recordStates(testInfo: TestInfoLike, records: StateRecord[]): Promise<void>;
+interface CaptureStateOptions {
+    /** Registry entity id whose state this is. */
+    entity: string;
+    kind?: StateEntityKind;
+    /** Declared state name (must match a name in the entity's `states`). */
+    state: string;
+    /**
+     * Canonical state kind for the matrix. Defaults to the state name when it is
+     * itself a core kind (`loading`/`empty`/`populated`/`error`), else `variant`.
+     */
+    stateKind?: StateKind;
+    /**
+     * Output dir for PNGs; defaults to `process.env.UIDEX_SHOTS_DIR`. When unset
+     * the capture only RECORDS the state (no screenshot) — so a spec left in the
+     * normal suite is a no-op beyond the attachment.
+     */
+    dir?: string;
+    themes?: readonly Theme[];
+    widths?: readonly WidthLabel[];
+    /** Awaited after each theme/width change, before the shutter (the state's tell). */
+    ready?: (page: Page) => Promise<unknown>;
+    /**
+     * Switch the app's theme. App-specific (next-themes uses localStorage + a
+     * reload; others a class or cookie), so it is injected. Defaults to
+     * Playwright's `emulateMedia({ colorScheme })`, which suits prefers-color-scheme.
+     */
+    setTheme?: (page: Page, theme: Theme) => Promise<void>;
+    /** CSS selectors to mask (opaque box) — for legitimately non-deterministic regions. */
+    mask?: string[];
+    /** Path to a stylesheet injected before the shot (hide dev chrome; pierces shadow DOM). */
+    stylePath?: string;
+    fullPage?: boolean;
+    /**
+     * Explicit route pattern this capture covers (e.g. "/[scope]/products"). By
+     * default the observed `page.url()` pathname is recorded and the gate matches
+     * it; pass `route` only when the observed URL is unreliable (e.g. a `/shots`
+     * harness standing in for a real route).
+     */
+    route?: string;
+}
+/**
+ * Capture one declared state across themes × widths, then record every variant
+ * for the gate. Screenshot mechanics are native Playwright; determinism knobs
+ * come from the project `use` block and the options above. Returns the records
+ * it attached (also handy in tests).
+ */
+declare function captureState(page: Page, testInfo: TestInfoLike, opts: CaptureStateOptions): Promise<StateRecord[]>;
+
+export { CORE_STATE_KINDS, type CaptureStateOptions, type CoreStateKind, STATES_ATTACHMENT, type StateEntityKind, type StateKind, type StateRecord, type StatesPayload, THEMES, type Theme, WIDTHS, type WidthLabel, captureState, recordStates };

package/dist/playwright/states.js

@@ -0,0 +1,88 @@
+// src/integrations/playwright/states.ts
+var STATES_ATTACHMENT = "uidex-states";
+var THEMES = ["light", "dark"];
+var WIDTHS = { desktop: 1440, narrow: 430 };
+var CORE_STATE_KINDS = [
+  "loading",
+  "empty",
+  "populated",
+  "error"
+];
+async function recordStates(testInfo, records) {
+  if (records.length === 0) return;
+  const payload = { records };
+  await testInfo.attach(STATES_ATTACHMENT, {
+    body: JSON.stringify(payload),
+    contentType: "application/json"
+  });
+}
+function currentPathname(page) {
+  try {
+    return new URL(page.url()).pathname;
+  } catch {
+    return void 0;
+  }
+}
+async function defaultSetTheme(page, theme) {
+  await page.emulateMedia({ colorScheme: theme });
+}
+function inferStateKind(state, explicit) {
+  if (explicit) return explicit;
+  return CORE_STATE_KINDS.includes(state) ? state : "variant";
+}
+function shotName(opts, theme, label, suffixWidth) {
+  const base = `${opts.entity}/${opts.state}`;
+  return suffixWidth ? `${base}-${theme}-${label}` : `${base}-${theme}`;
+}
+async function captureState(page, testInfo, opts) {
+  const themes = opts.themes ?? THEMES;
+  const widths = opts.widths ?? ["desktop"];
+  const suffixWidth = widths.length > 1;
+  const dir = opts.dir ?? process.env.UIDEX_SHOTS_DIR;
+  const setTheme = opts.setTheme ?? defaultSetTheme;
+  const observedUrl = currentPathname(page);
+  const records = [];
+  for (const theme of themes) {
+    await setTheme(page, theme);
+    if (opts.ready) await opts.ready(page);
+    for (const label of widths) {
+      await page.setViewportSize({ width: WIDTHS[label], height: 900 });
+      if (opts.ready) await opts.ready(page);
+      const record = {
+        entity: opts.entity,
+        state: opts.state,
+        stateKind: inferStateKind(opts.state, opts.stateKind),
+        theme,
+        width: label,
+        ...opts.kind ? { kind: opts.kind } : {},
+        ...opts.route ? { route: opts.route } : {},
+        ...observedUrl ? { url: observedUrl } : {}
+      };
+      if (dir) {
+        const path = `${dir}/${shotName(opts, theme, label, suffixWidth)}.png`;
+        await page.screenshot({
+          path,
+          fullPage: opts.fullPage ?? true,
+          ...opts.stylePath ? { stylePath: opts.stylePath } : {},
+          ...opts.mask?.length ? {
+            mask: opts.mask.map((s) => page.locator(s)),
+            maskColor: "#000000"
+          } : {}
+        });
+        record.path = path;
+      }
+      records.push(record);
+    }
+  }
+  await recordStates(testInfo, records);
+  return records;
+}
+export {
+  CORE_STATE_KINDS,
+  STATES_ATTACHMENT,
+  THEMES,
+  WIDTHS,
+  captureState,
+  recordStates
+};
+//# sourceMappingURL=states.js.map

package/dist/playwright/states.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/integrations/playwright/states.ts"],"sourcesContent":["import type { Page, TestInfo } from \"@playwright/test\"\n\n/**\n * Deterministic render-state capture for `uidex/playwright`.\n *\n * Two jobs, deliberately split:\n *   1. RECORD which `entity/state` a test captured (a `uidex-states`\n *      attachment) — the reporter aggregates these into `uidex-states.json`,\n *      which the scanner's completeness gate cross-checks against the states\n *      declared in `export const uidex = { states: [...] }`.\n *   2. SHOOT the pixels — a thin wrapper over native `page.screenshot`. The\n *      determinism knobs are Playwright's own: `animations: \"disabled\"` and\n *      `caret: \"hide\"` are defaults, `style`/`stylePath` pierces the shadow DOM\n *      to hide dev chrome, `mask` covers non-deterministic regions, and the\n *      frozen clock / locale / timezone / colour-scheme live in the project's\n *      `use` block. uidex does not re-implement `settle()`.\n *\n * The recording is the load-bearing half: even a spec that shoots nothing can\n * call `recordState` so the gate knows the state exists.\n */\n\nexport const STATES_ATTACHMENT = \"uidex-states\"\n\n/** Default light + dark; many surfaces use theme-dependent colours. */\nexport const THEMES = [\"light\", \"dark\"] as const\n/** Desktop is primary; narrow exercises the responsive reflow. */\nexport const WIDTHS = { desktop: 1440, narrow: 430 } as const\n\nexport type Theme = (typeof THEMES)[number]\nexport type WidthLabel = keyof typeof WIDTHS\nexport type StateEntityKind = \"page\" | \"feature\" | \"widget\"\n\n/** The four kinds the state-matrix gate expects every captured route to cover. */\nexport const CORE_STATE_KINDS = [\n  \"loading\",\n  \"empty\",\n  \"populated\",\n  \"error\",\n] as const\nexport type CoreStateKind = (typeof CORE_STATE_KINDS)[number]\n/** `variant` = any state outside the matrix (dialog, wizard step, multi-currency…). */\nexport type StateKind = CoreStateKind | \"variant\"\n\n/** One captured `entity/state` variant. */\nexport interface StateRecord {\n  /** Registry entity id whose state was rendered (e.g. \"products\"). */\n  entity: string\n  /** Entity kind, so the gate can disambiguate a page vs feature of the same id. */\n  kind?: StateEntityKind\n  /** Declared state name (e.g. \"new-filled\"). */\n  state: string\n  /** Canonical kind for the state-matrix axis (defaults inferred from the name). */\n  stateKind?: StateKind\n  theme?: string\n  width?: string\n  /** Screenshot path, when one was written. */\n  path?: string\n  /**\n   * The URL pathname the capture ran against, observed from `page.url()`. The\n   * page-coverage gate normalizes it to a derived route pattern — so which route\n   * a capture exercised is observed, never hand-declared. A `/shots/*` harness\n   * URL matches no real route and gates nothing (correct for component captures).\n   */\n  url?: string\n  /** Explicit route pattern override, when the observed URL can't be trusted. */\n  route?: string\n}\n\n/** The `uidex-states` attachment body — an array of records from one test. */\nexport interface StatesPayload {\n  records: StateRecord[]\n}\n\ntype TestInfoLike = Pick<TestInfo, \"attach\">\n\n/**\n * Attach one or more captured-state records to the test. Idempotent per call;\n * the reporter concatenates every test's records. Use directly when you shoot\n * with your own screenshot call and only need the state registered for the gate.\n */\nexport async function recordStates(\n  testInfo: TestInfoLike,\n  records: StateRecord[]\n): Promise<void> {\n  if (records.length === 0) return\n  const payload: StatesPayload = { records }\n  await testInfo.attach(STATES_ATTACHMENT, {\n    body: JSON.stringify(payload),\n    contentType: \"application/json\",\n  })\n}\n\nexport interface CaptureStateOptions {\n  /** Registry entity id whose state this is. */\n  entity: string\n  kind?: StateEntityKind\n  /** Declared state name (must match a name in the entity's `states`). */\n  state: string\n  /**\n   * Canonical state kind for the matrix. Defaults to the state name when it is\n   * itself a core kind (`loading`/`empty`/`populated`/`error`), else `variant`.\n   */\n  stateKind?: StateKind\n  /**\n   * Output dir for PNGs; defaults to `process.env.UIDEX_SHOTS_DIR`. When unset\n   * the capture only RECORDS the state (no screenshot) — so a spec left in the\n   * normal suite is a no-op beyond the attachment.\n   */\n  dir?: string\n  themes?: readonly Theme[]\n  widths?: readonly WidthLabel[]\n  /** Awaited after each theme/width change, before the shutter (the state's tell). */\n  ready?: (page: Page) => Promise<unknown>\n  /**\n   * Switch the app's theme. App-specific (next-themes uses localStorage + a\n   * reload; others a class or cookie), so it is injected. Defaults to\n   * Playwright's `emulateMedia({ colorScheme })`, which suits prefers-color-scheme.\n   */\n  setTheme?: (page: Page, theme: Theme) => Promise<void>\n  /** CSS selectors to mask (opaque box) — for legitimately non-deterministic regions. */\n  mask?: string[]\n  /** Path to a stylesheet injected before the shot (hide dev chrome; pierces shadow DOM). */\n  stylePath?: string\n  fullPage?: boolean\n  /**\n   * Explicit route pattern this capture covers (e.g. \"/[scope]/products\"). By\n   * default the observed `page.url()` pathname is recorded and the gate matches\n   * it; pass `route` only when the observed URL is unreliable (e.g. a `/shots`\n   * harness standing in for a real route).\n   */\n  route?: string\n}\n\n/** The URL pathname the page is currently on, for route observation. */\nfunction currentPathname(page: Page): string | undefined {\n  try {\n    return new URL(page.url()).pathname\n  } catch {\n    return undefined\n  }\n}\n\nasync function defaultSetTheme(page: Page, theme: Theme): Promise<void> {\n  await page.emulateMedia({ colorScheme: theme })\n}\n\n/** Infer the matrix kind: the state name if it is itself a core kind, else variant. */\nfunction inferStateKind(state: string, explicit?: StateKind): StateKind {\n  if (explicit) return explicit\n  return (CORE_STATE_KINDS as readonly string[]).includes(state)\n    ? (state as StateKind)\n    : \"variant\"\n}\n\nfunction shotName(\n  opts: CaptureStateOptions,\n  theme: Theme,\n  label: WidthLabel,\n  suffixWidth: boolean\n): string {\n  const base = `${opts.entity}/${opts.state}`\n  return suffixWidth ? `${base}-${theme}-${label}` : `${base}-${theme}`\n}\n\n/**\n * Capture one declared state across themes × widths, then record every variant\n * for the gate. Screenshot mechanics are native Playwright; determinism knobs\n * come from the project `use` block and the options above. Returns the records\n * it attached (also handy in tests).\n */\nexport async function captureState(\n  page: Page,\n  testInfo: TestInfoLike,\n  opts: CaptureStateOptions\n): Promise<StateRecord[]> {\n  const themes = opts.themes ?? THEMES\n  const widths = opts.widths ?? ([\"desktop\"] as WidthLabel[])\n  const suffixWidth = widths.length > 1\n  const dir = opts.dir ?? process.env.UIDEX_SHOTS_DIR\n  const setTheme = opts.setTheme ?? defaultSetTheme\n  const observedUrl = currentPathname(page)\n  const records: StateRecord[] = []\n\n  for (const theme of themes) {\n    await setTheme(page, theme)\n    if (opts.ready) await opts.ready(page)\n    for (const label of widths) {\n      await page.setViewportSize({ width: WIDTHS[label], height: 900 })\n      if (opts.ready) await opts.ready(page)\n      const record: StateRecord = {\n        entity: opts.entity,\n        state: opts.state,\n        stateKind: inferStateKind(opts.state, opts.stateKind),\n        theme,\n        width: label,\n        ...(opts.kind ? { kind: opts.kind } : {}),\n        ...(opts.route ? { route: opts.route } : {}),\n        ...(observedUrl ? { url: observedUrl } : {}),\n      }\n      if (dir) {\n        const path = `${dir}/${shotName(opts, theme, label, suffixWidth)}.png`\n        await page.screenshot({\n          path,\n          fullPage: opts.fullPage ?? true,\n          ...(opts.stylePath ? { stylePath: opts.stylePath } : {}),\n          ...(opts.mask?.length\n            ? {\n                mask: opts.mask.map((s) => page.locator(s)),\n                maskColor: \"#000000\",\n              }\n            : {}),\n        })\n        record.path = path\n      }\n      records.push(record)\n    }\n  }\n\n  await recordStates(testInfo, records)\n  return records\n}\n"],"mappings":";AAqBO,IAAM,oBAAoB;AAG1B,IAAM,SAAS,CAAC,SAAS,MAAM;AAE/B,IAAM,SAAS,EAAE,SAAS,MAAM,QAAQ,IAAI;AAO5C,IAAM,mBAAmB;AAAA,EAC9B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AA0CA,eAAsB,aACpB,UACA,SACe;AACf,MAAI,QAAQ,WAAW,EAAG;AAC1B,QAAM,UAAyB,EAAE,QAAQ;AACzC,QAAM,SAAS,OAAO,mBAAmB;AAAA,IACvC,MAAM,KAAK,UAAU,OAAO;AAAA,IAC5B,aAAa;AAAA,EACf,CAAC;AACH;AA4CA,SAAS,gBAAgB,MAAgC;AACvD,MAAI;AACF,WAAO,IAAI,IAAI,KAAK,IAAI,CAAC,EAAE;AAAA,EAC7B,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAEA,eAAe,gBAAgB,MAAY,OAA6B;AACtE,QAAM,KAAK,aAAa,EAAE,aAAa,MAAM,CAAC;AAChD;AAGA,SAAS,eAAe,OAAe,UAAiC;AACtE,MAAI,SAAU,QAAO;AACrB,SAAQ,iBAAuC,SAAS,KAAK,IACxD,QACD;AACN;AAEA,SAAS,SACP,MACA,OACA,OACA,aACQ;AACR,QAAM,OAAO,GAAG,KAAK,MAAM,IAAI,KAAK,KAAK;AACzC,SAAO,cAAc,GAAG,IAAI,IAAI,KAAK,IAAI,KAAK,KAAK,GAAG,IAAI,IAAI,KAAK;AACrE;AAQA,eAAsB,aACpB,MACA,UACA,MACwB;AACxB,QAAM,SAAS,KAAK,UAAU;AAC9B,QAAM,SAAS,KAAK,UAAW,CAAC,SAAS;AACzC,QAAM,cAAc,OAAO,SAAS;AACpC,QAAM,MAAM,KAAK,OAAO,QAAQ,IAAI;AACpC,QAAM,WAAW,KAAK,YAAY;AAClC,QAAM,cAAc,gBAAgB,IAAI;AACxC,QAAM,UAAyB,CAAC;AAEhC,aAAW,SAAS,QAAQ;AAC1B,UAAM,SAAS,MAAM,KAAK;AAC1B,QAAI,KAAK,MAAO,OAAM,KAAK,MAAM,IAAI;AACrC,eAAW,SAAS,QAAQ;AAC1B,YAAM,KAAK,gBAAgB,EAAE,OAAO,OAAO,KAAK,GAAG,QAAQ,IAAI,CAAC;AAChE,UAAI,KAAK,MAAO,OAAM,KAAK,MAAM,IAAI;AACrC,YAAM,SAAsB;AAAA,QAC1B,QAAQ,KAAK;AAAA,QACb,OAAO,KAAK;AAAA,QACZ,WAAW,eAAe,KAAK,OAAO,KAAK,SAAS;AAAA,QACpD;AAAA,QACA,OAAO;AAAA,QACP,GAAI,KAAK,OAAO,EAAE,MAAM,KAAK,KAAK,IAAI,CAAC;AAAA,QACvC,GAAI,KAAK,QAAQ,EAAE,OAAO,KAAK,MAAM,IAAI,CAAC;AAAA,QAC1C,GAAI,cAAc,EAAE,KAAK,YAAY,IAAI,CAAC;AAAA,MAC5C;AACA,UAAI,KAAK;AACP,cAAM,OAAO,GAAG,GAAG,IAAI,SAAS,MAAM,OAAO,OAAO,WAAW,CAAC;AAChE,cAAM,KAAK,WAAW;AAAA,UACpB;AAAA,UACA,UAAU,KAAK,YAAY;AAAA,UAC3B,GAAI,KAAK,YAAY,EAAE,WAAW,KAAK,UAAU,IAAI,CAAC;AAAA,UACtD,GAAI,KAAK,MAAM,SACX;AAAA,YACE,MAAM,KAAK,KAAK,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC;AAAA,YAC1C,WAAW;AAAA,UACb,IACA,CAAC;AAAA,QACP,CAAC;AACD,eAAO,OAAO;AAAA,MAChB;AACA,cAAQ,KAAK,MAAM;AAAA,IACrB;AAAA,EACF;AAEA,QAAM,aAAa,UAAU,OAAO;AACpC,SAAO;AACT;","names":[]}