@tristan2828/ui-foundation 4.42.0 → 4.44.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/conventions/docs/timed-screens.md

@@ -6,11 +6,11 @@
 - [The view](#the-view) · lines 36–109
   - [The dark stage](#the-dark-stage) · lines 73–109
 - [The clock](#the-clock) · lines 111–141
-- [Sound](#sound) · lines 143–190
-- [Background tabs](#background-tabs) · lines 192–246
-  - [Interruptions](#interruptions) · lines 226–246
-- [Motion](#motion) · lines 248–252
-- [Testing a timed screen in Playwright](#testing-a-timed-screen-in-playwright) · lines 254–408
+- [Sound](#sound) · lines 143–193
+- [Background tabs](#background-tabs) · lines 195–249
+  - [Interruptions](#interruptions) · lines 229–249
+- [Motion](#motion) · lines 251–255
+- [Testing a timed screen in Playwright](#testing-a-timed-screen-in-playwright) · lines 257–411
 
 <!-- /index -->
 
@@ -176,7 +176,10 @@ Browsers block sound until the person has clicked or tapped. So:
   another app's music. It returns `{ pause(), stop() }`: `pause()` shows
   Play (without calling `onToggle`), `stop()` ends it (on done, on leaving);
   to start again after `pause()`, call `keepAudioAlive` again from a click.
-  Only one runs at a time.
+  Only one runs at a time. Where Safari has an audio session
+  (`navigator.audioSession`) it's set to `"playback"` while the track
+  runs, so the ringer switch doesn't mute the cues either, and put back on
+  `stop()`.
 - Every one of them is a no-op where the browser can't make the sound, so
   none needs a check around it.
 - **Mute** is the app's: `const [muted, setMuted] = useMuted('my-app:routine:muted')`,

package/dist/lib/keep-audio-alive.d.ts

@@ -22,6 +22,10 @@ export type KeepAudioAliveEnvironment = {
     MediaMetadata?: new (init?: MediaMetadataInit) => MediaMetadata;
     createObjectURL?: (blob: Blob) => string;
     revokeObjectURL?: (url: string) => void;
+    /** Safari's `navigator.audioSession`, where it has one. */
+    audioSession?: {
+        type: string;
+    };
 };
 /** One second of silent 8-bit mono audio as a WAV file. */
 export declare function silentWav(): Uint8Array;
@@ -30,6 +34,8 @@ export declare function createKeepAudioAlive(env: KeepAudioAliveEnvironment): ({
  * Plays a silent looped track so iOS keeps the page's sound going with the
  * phone locked, with `title` and Pause and Play on the lock screen. Call it
  * from the click that starts the run, behind a setting that's off by default:
- * it pauses other apps' music. A no-op where the browser can't play audio.
+ * it pauses other apps' music. Where Safari has an audio session it's set to
+ * "playback" meanwhile, so the ringer switch doesn't mute the cues. A no-op
+ * where the browser can't play audio.
  */
 export declare const keepAudioAlive: (options: KeepAudioAliveOptions) => KeepAudioAlive;

package/dist/lib/keep-audio-alive.js

@@ -1,9 +1,12 @@
-// Keeps a page's audio going with the phone locked (#217). iOS pauses a
+// Keeps a page's audio going with the phone locked (#217, #261). iOS pauses a
 // page's sound on the lock screen unless the page is playing media, so
 // keepAudioAlive() plays a silent looped track, which also puts the page's
 // title and a Pause and Play on the lock screen (the Media Session). It's
 // opt-in and off by default: it takes the device's audio session, which
 // pauses another app's music (docs/foundation/timed-screens.md "Sound").
+// Where Safari has an audio session (navigator.audioSession, iOS 17+) it's
+// set to "playback" while the track runs, so the ringer switch doesn't mute
+// the page's cues either, and put back on stop().
 //
 // The track is a few bytes of silence made here, so there is no file to
 // ship. createKeepAudioAlive takes the browser's APIs, so the rules are
@@ -55,6 +58,18 @@ export function createKeepAudioAlive(env) {
         }
         audio.loop = true;
         const session = env.mediaSession;
+        const audioSession = env.audioSession;
+        let typeBefore = null;
+        try {
+            if (audioSession) {
+                typeBefore = audioSession.type;
+                audioSession.type = 'playback';
+            }
+        }
+        catch {
+            // A type this Safari doesn't take: the silent track alone.
+            typeBefore = null;
+        }
         const play = () => {
             // Refused without a click: the lock screen then shows nothing to keep.
             Promise.resolve(audio.play()).catch(() => { });
@@ -102,6 +117,14 @@ export function createKeepAudioAlive(env) {
                 audio.removeAttribute('src');
                 audio.load();
                 env.revokeObjectURL?.(url);
+                if (audioSession && typeBefore !== null) {
+                    try {
+                        audioSession.type = typeBefore;
+                    }
+                    catch {
+                        // Left as playback: harmless once the track has stopped.
+                    }
+                }
                 if (session) {
                     handle('play', null);
                     handle('pause', null);
@@ -119,7 +142,9 @@ let shared = null;
  * Plays a silent looped track so iOS keeps the page's sound going with the
  * phone locked, with `title` and Pause and Play on the lock screen. Call it
  * from the click that starts the run, behind a setting that's off by default:
- * it pauses other apps' music. A no-op where the browser can't play audio.
+ * it pauses other apps' music. Where Safari has an audio session it's set to
+ * "playback" meanwhile, so the ringer switch doesn't mute the cues. A no-op
+ * where the browser can't play audio.
  */
 export const keepAudioAlive = (options) => {
     if (!shared) {
@@ -130,6 +155,7 @@ export const keepAudioAlive = (options) => {
             MediaMetadata: hasWindow ? window.MediaMetadata : undefined,
             createObjectURL: typeof URL !== 'undefined' ? (blob) => URL.createObjectURL(blob) : undefined,
             revokeObjectURL: typeof URL !== 'undefined' ? (url) => URL.revokeObjectURL(url) : undefined,
+            audioSession: typeof navigator !== 'undefined' ? navigator.audioSession : undefined,
         });
     }
     return shared(options);

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.44.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": {