@tristan2828/ui-foundation 4.42.0 → 4.43.0

package/README.md

@@ -22,7 +22,7 @@ than installing this by hand:
 | `@tristan2828/ui-foundation/ui/<name>` | shadcn primitives: badge, button, calendar, card, checkbox, combobox, dialog, empty, field, input, input-group, label, popover, select, separator, sheet, sidebar, skeleton, sonner, spinner, switch, table, textarea, tooltip |
 | `@tristan2828/ui-foundation/gateway` | `safeFetch`, `toAppError`, `networkError` — for an app's `src/api/gateway/` only |
 | `@tristan2828/ui-foundation/mocks` | MSW: `authHandlers`, `environmentHandlers`, `resetMockAuth`, `getMockCurrentUser`, `MOCK_USER`, `exposeMswForE2E` |
-| `@tristan2828/ui-foundation/testing` | Playwright: `defineA11ySuite`, `defineMockModeBannerSuite`, `defineDataEnvironmentBannerSuite`, `forceMswOverride`, `forceLoggedOut`, `waitForMswReady`, `expectDataViewsLoaded` |
+| `@tristan2828/ui-foundation/testing` | Playwright: `test` and `expect` (a page whose `goto()`/`reload()` wait for the app's boot; `withBootWait` for a page of your own), `defineA11ySuite`, `defineMockModeBannerSuite`, `defineDataEnvironmentBannerSuite`, `forceMswOverride`, `forceLoggedOut`, `waitForMswReady`, `expectDataViewsLoaded` |
 | `@tristan2828/ui-foundation/eslint` | the lint rules, as a flat config: `export default [...uiFoundation()]` |
 | `@tristan2828/ui-foundation/styles.css` | tokens and base styles, after `@import "tailwindcss";` |
 | `@tristan2828/ui-foundation/openapi.yaml` | the part of an app's API contract the package calls: `/auth/*`, `/environment` (optional) and the error bodies |

package/conventions/docs/add-an-entity.md

@@ -4,7 +4,7 @@
 ## Index
 
 - [The reference files](#the-reference-files) · lines 37–59
-- [Before anything: the entity plan](#before-anything-the-entity-plan) · lines 61–702
+- [Before anything: the entity plan](#before-anything-the-entity-plan) · lines 61–706
   - Step 1: Add `<Entity>` to `openapi.yaml` · lines 99–106
   - Step 2: `npm run gen:api` · lines 107–108
   - Step 3: Add gateway tests in `tests/gateway/<entity>.test.ts`, derived from the spec · lines 109–120
@@ -12,13 +12,13 @@
   - Step 5: Add a gateway module in `src/api/gateway/<entity>.ts` · lines 131–135
   - Step 6: Copy the reference files, one for one, not just the two screens · lines 136–598
   - Step 7: Register routes · lines 599–609
-  - Step 8: Add Playwright specs for all three screens · lines 610–684
-  - Step 9: Register the nav entry and route names · lines 685–699
-  - Step 10: `npm run verify`. · lines 700–702
-- [What not to copy](#what-not-to-copy) · lines 704–730
-- [After a commit, in the backend](#after-a-commit-in-the-backend) · lines 732–749
-- [Deleting](#deleting) · lines 751–780
-- [Fields only a script writes](#fields-only-a-script-writes) · lines 782–803
+  - Step 8: Add Playwright specs for all three screens · lines 610–688
+  - Step 9: Register the nav entry and route names · lines 689–703
+  - Step 10: `npm run verify`. · lines 704–706
+- [What not to copy](#what-not-to-copy) · lines 708–734
+- [After a commit, in the backend](#after-a-commit-in-the-backend) · lines 736–753
+- [Deleting](#deleting) · lines 755–784
+- [Fields only a script writes](#fields-only-a-script-writes) · lines 786–807
 
 <!-- /index -->
 
@@ -612,7 +612,11 @@ is a filled-in example while the Widgets demo is still here).
    MSW overrides — `forceMswOverride`, `waitForMswReady` and the
    `window.__msw` handle from `@tristan2828/ui-foundation/testing`, and
    `e2e/widgets-table.spec.ts`/`e2e/widget-form.spec.ts`/
-   `e2e/widget-view.spec.ts` for the pattern. The view's states are
+   `e2e/widget-view.spec.ts` for the pattern. Import `test` and
+   `expect` from there too, not from `@playwright/test`: its page's
+   `goto()` and `reload()` return once the app has rendered (after MSW's
+   start), and load once more if the server refused one of its files,
+   so a spec's first expect never meets an empty page. The view's states are
    loading, not found (a 404: "Not found", the way back, no retry), error
    (a failed load, then Try again recovering) and success (every section,
    each value as its cell shows it), plus the sparse record showing its

package/dist/testing/index.d.ts

@@ -1,7 +1,24 @@
-import { type Page } from '@playwright/test';
+import { expect, type Page } from '@playwright/test';
 import { type NavEntry } from '../components/app/app-shell-nav.js';
 import type { MswOverride } from '../mocks/override.js';
 export type { MswHandle, MswOverride } from '../mocks/override.js';
+export { expect };
+/**
+ * Makes the page's `goto()` and `reload()` return once the app has
+ * booted (its first render into `#root`), not at the load event, and load
+ * the page once more when one of the app's own files is refused before
+ * then; a second refusal fails naming the file. The wait is bounded by
+ * the test's timeout like any navigation, and the page's own expects keep
+ * their time from there. The `test` exported here applies it to every
+ * test's `page`; this is for a page an app's own fixture opens.
+ */
+export declare function withBootWait(page: Page): Page;
+/**
+ * Playwright's `test`, with a `page` whose `goto()` and `reload()` wait
+ * for the app's boot (`withBootWait`). Import `test` and `expect` from
+ * here instead of '@playwright/test'; the suites below use it too.
+ */
+export declare const test: import("playwright/test").TestType<import("playwright/test").PlaywrightTestArgs & import("playwright/test").PlaywrightTestOptions, import("playwright/test").PlaywrightWorkerArgs & import("playwright/test").PlaywrightWorkerOptions>;
 /**
  * Forces a response for the page's *first* load: set before navigation, so
  * it wins the race against the app's own first fetch. For states forced

package/dist/testing/index.js

@@ -12,8 +12,75 @@
 // Runs in Node, inside Playwright: @playwright/test and @axe-core/playwright
 // are optional peer dependencies, needed only by apps that import this.
 import AxeBuilder from '@axe-core/playwright';
-import { expect, test } from '@playwright/test';
+import { expect, test as base } from '@playwright/test';
 import { navPathname, navTargets } from '../components/app/app-shell-nav.js';
+export { expect };
+// A page load returns at the load event, but the app isn't up yet: React
+// renders only after MSW's worker.start(), which took up to 2.4 s past
+// load in a busy run, and a test's first 5 s expect then failed on an
+// empty page. Under the same load `vite preview` sometimes refuses a
+// connection (about 1 page in 1500): one of the entry's chunks fails, the
+// browser never retries a module script, and the page stays empty until
+// the test's timeout. Both were seen as "never rendered" in every suite.
+const REFUSED = /ERR_CONNECTION_(REFUSED|RESET)/;
+// The app's first render into the template's `<div id="root">`, which is
+// the boot in a mock build (after MSW's start) and a real one alike. A
+// page without one (another site, about:blank) has nothing to wait for.
+const rendered = (page) => page.waitForFunction(() => {
+    const root = document.getElementById('root');
+    return !root || root.hasChildNodes();
+});
+async function boot(page, load, again) {
+    for (let attempt = 1;; attempt++) {
+        let onFailed = () => { };
+        const refused = new Promise((resolve) => {
+            onFailed = (request) => {
+                const url = new URL(request.url());
+                const own = url.origin === new URL(page.url()).origin;
+                if (own && REFUSED.test(request.failure()?.errorText ?? ''))
+                    resolve(url.pathname);
+            };
+            page.on('requestfailed', onFailed);
+        });
+        try {
+            const response = await (attempt === 1 ? load() : again());
+            const file = await Promise.race([rendered(page).then(() => null), refused]);
+            if (file === null)
+                return response;
+            if (attempt === 2)
+                throw new Error(`The server refused ${file} twice: the app never booted`);
+        }
+        finally {
+            page.off('requestfailed', onFailed);
+        }
+    }
+}
+/**
+ * Makes the page's `goto()` and `reload()` return once the app has
+ * booted (its first render into `#root`), not at the load event, and load
+ * the page once more when one of the app's own files is refused before
+ * then; a second refusal fails naming the file. The wait is bounded by
+ * the test's timeout like any navigation, and the page's own expects keep
+ * their time from there. The `test` exported here applies it to every
+ * test's `page`; this is for a page an app's own fixture opens.
+ */
+export function withBootWait(page) {
+    const goto = page.goto.bind(page);
+    const reload = page.reload.bind(page);
+    page.goto = (url, options) => boot(page, () => goto(url, options), () => reload(options));
+    page.reload = (options) => boot(page, () => reload(options), () => reload(options));
+    return page;
+}
+/**
+ * Playwright's `test`, with a `page` whose `goto()` and `reload()` wait
+ * for the app's boot (`withBootWait`). Import `test` and `expect` from
+ * here instead of '@playwright/test'; the suites below use it too.
+ */
+export const test = base.extend({
+    page: async ({ page }, provide) => {
+        await provide(withBootWait(page));
+    },
+});
 /**
  * Forces a response for the page's *first* load: set before navigation, so
  * it wins the race against the app's own first fetch. For states forced

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "4.42.0",
+  "version": "4.43.0",
   "description": "Shared UI foundation for contract-first, database-backed React apps: shadcn primitives, DataTable/EntityForm composites, auth, the gateway error seam, design tokens, lint rules and the AI playbook.",
   "license": "MIT",
   "repository": {