@tristan2828/ui-foundation 4.18.1 → 4.18.2

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

@@ -511,6 +511,29 @@ is a filled-in example while the Widgets demo is still here).
    `onError` — and stub it through the override, never `page.route`,
    which cannot see requests the MSW service worker makes
    (`e2e/msw-contract.spec.ts` has an example).
+   **Forcing a mutation's success forces its refetch too.** A mutation
+   invalidates its queries when it answers, and the refetch reads the
+   mock store, which the override never changed, so the screen goes back
+   to the old record and the test fails on a value it just saw. Answer
+   the follow-up GET with the record the mutation answered:
+
+   ```ts
+   // The record as the server would save it: what the PATCH answers.
+   const saved = { ...WIRELESS_MOUSE, status: 'archived' }
+   await waitForMswReady(page)
+   await page.evaluate((saved) => {
+     const { worker, http, HttpResponse } = window.__msw
+     worker.use(
+       http.patch('*/api/widgets/1', () => HttpResponse.json(saved)),
+       // The invalidation refetch: without this it shows the old status.
+       http.get('*/api/widgets/1', () => HttpResponse.json(saved)),
+     )
+   }, saved)
+   ```
+
+   Answer the list's GET the same way if the screen shows the list. Only
+   a forced error needs no GET: a refused mutation changes nothing to
+   read back.
 9. **Register the nav entry and route names** in `e2e/shell.spec.ts`'s
    `NAV_ENTRIES` so the shell smoke test covers the new screen, add
    `/<entity>/new` to `e2e/a11y.spec.ts`'s `formRoutes`, and add the view

package/conventions/docs/timed-screens.md

@@ -153,3 +153,40 @@ test('running, paused and done', async ({ page }) => {
   before the page loads:
   `page.addInitScript(() => localStorage.setItem('my-app:routine:muted', 'true'))`.
 - **Reduced motion:** `await page.emulateMedia({ reducedMotion: 'reduce' })`.
+
+**An open-ended count-up: pause the fake clock.** After
+`clock.install()` the fake clock still moves in real time between
+steps, so every reading picks up however long the machine took since the
+last `fastForward`. A count-up with no end (a stopwatch, a hold that
+ends on a tap) has nothing to stop at, so under load its readings are
+off by a second or more. Pause the clock once the session opens and
+move it only with `fastForward`:
+
+```ts
+test('the hold counts up until the tap', async ({ page }) => {
+  await page.clock.install()
+  await page.goto('/routine')
+  await page.getByRole('button', { name: 'Start' }).click()
+  // Slightly ahead, never Date.now() itself: the page's clock has already
+  // moved past the test's, and pauseAt() refuses an earlier time with
+  // "Cannot fast-forward to the past".
+  await page.clock.pauseAt(Date.now() + 50)
+
+  await page.clock.fastForward('00:42')
+  await expect(page.getByRole('timer', { name: 'Held for' })).toHaveText('0:42')
+
+  // A paused clock stops axe and the dialog's close animation: resume first.
+  await page.clock.resume()
+  await expectNoAxeViolations(page)   // @tristan2828/ui-foundation/testing
+  await page.getByRole('button', { name: 'Close' }).click()
+  await expect(page.getByRole('dialog')).toBeHidden()
+})
+```
+
+- **`pauseAt(Date.now() + 50)`, not `pauseAt(Date.now())`.** The page's
+  fake time is already a little ahead of the test's `Date.now()`, and
+  `pauseAt` fast-forwards to the time it's given, so a time already
+  passed fails with "Cannot fast-forward to the past".
+- **`clock.resume()` before axe or closing the view.** With the clock
+  paused, axe's scan never finishes and the dialog's close animation
+  never ends, so the test times out with nothing pointing at the clock.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "4.18.1",
+  "version": "4.18.2",
   "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": {