@tristan2828/ui-foundation 4.16.0 → 4.18.0

package/dist/index.d.ts

@@ -22,6 +22,7 @@ export { RouteErrorBoundary } from './components/app/route-error-boundary.js';
 export { PillFilter, type PillFilterOption, type PillFilterProps } from './components/app/pill-filter.js';
 export { SecondaryFilters, type ActiveFilter, type SecondaryFiltersProps } from './components/app/secondary-filters.js';
 export { SessionView, type SessionViewProps } from './components/app/session-view.js';
+export { AllowReminders, type AllowRemindersProps } from './components/app/allow-reminders.js';
 export { StageCircle, type StageCircleProps, type StageCircleStage, type StageCircleTone, } from './components/app/stage-circle.js';
 export { Notice, type NoticeProps, type NoticeTone } from './components/app/notice.js';
 export { SourceCredit, type Source, type SourceCreditProps } from './components/app/source-credit.js';
@@ -50,5 +51,6 @@ export { useWakeLock } from './hooks/use-wake-lock.js';
 export { useSessionClock, type SessionClock, type SessionClockOptions, type SessionClockState, type SessionStatus, } from './hooks/use-session-clock.js';
 export { usePrefersReducedMotion } from './hooks/use-prefers-reduced-motion.js';
 export { useMuted } from './hooks/use-muted.js';
+export { createPushController, usePushPermission, type PushController, type PushControllerOptions, type PushEnvironment, type PushPermission, type PushStatus, } from './hooks/use-push-permission.js';
 export { cn } from './lib/utils.js';
 export { chime, hush, say, sequence, unlockAudio, vibrate, type ChimeOptions, type SayOptions, type SequenceOptions, } from './lib/audio-cues.js';

package/dist/index.js

@@ -27,6 +27,7 @@ export { RouteErrorBoundary } from './components/app/route-error-boundary.js';
 export { PillFilter } from './components/app/pill-filter.js';
 export { SecondaryFilters } from './components/app/secondary-filters.js';
 export { SessionView } from './components/app/session-view.js';
+export { AllowReminders } from './components/app/allow-reminders.js';
 export { StageCircle, } from './components/app/stage-circle.js';
 export { Notice } from './components/app/notice.js';
 export { SourceCredit } from './components/app/source-credit.js';
@@ -55,6 +56,7 @@ export { useWakeLock } from './hooks/use-wake-lock.js';
 export { useSessionClock, } from './hooks/use-session-clock.js';
 export { usePrefersReducedMotion } from './hooks/use-prefers-reduced-motion.js';
 export { useMuted } from './hooks/use-muted.js';
+export { createPushController, usePushPermission, } from './hooks/use-push-permission.js';
 // Utilities
 export { cn } from './lib/utils.js';
 export { chime, hush, say, sequence, unlockAudio, vibrate, } from './lib/audio-cues.js';

package/dist/lib/link-href.d.ts

@@ -1,2 +1,4 @@
 /** The `href` to save, `''` to remove the link, or `null` when it's refused. */
 export declare function linkHref(typed: string): string | null;
+/** Why `linkHref` refused what was typed, for the message shown with it. */
+export declare function linkRefusal(typed: string): 'whitespace' | 'scheme';

package/dist/lib/link-href.js

@@ -3,12 +3,16 @@
 // `https://example.com` and a bare `name@example.com` a `mailto:`; a path
 // on this site (`/x`, never `//x`) or a heading (`#x`) is kept. Any other scheme
 // (`javascript:`, `data:`, `file:`) is refused, so a link can't run code
-// or reach a local file.
+// or reach a local file. An address with whitespace inside it
+// (`example wiki`, `https://a b`) is refused too: it isn't a working link,
+// and adding https:// to two words would save one that looks like it is.
 /** The `href` to save, `''` to remove the link, or `null` when it's refused. */
 export function linkHref(typed) {
     const value = typed.trim();
     if (value === '')
         return '';
+    if (/\s/.test(value))
+        return null;
     if (/^(https?:\/\/|mailto:|tel:)/i.test(value))
         return value;
     // A scheme of its own (`javascript:`), not a port (`example.com:8080`).
@@ -24,3 +28,7 @@ export function linkHref(typed) {
         return `mailto:${value}`;
     return `https://${value}`;
 }
+/** Why `linkHref` refused what was typed, for the message shown with it. */
+export function linkRefusal(typed) {
+    return /\s/.test(typed.trim()) ? 'whitespace' : 'scheme';
+}

package/dist/mocks/index.d.ts

@@ -1,5 +1,6 @@
 export { authHandlers, getMockCurrentUser, isMockAuthenticated, MOCK_PASSWORD, MOCK_RECOVERY_CODE, MOCK_TOTP_CODE, MOCK_TOTP_USER, MOCK_USER, resetMockAuth, setMockAuthenticated, } from './auth.js';
 export { clientErrorHandlers, getMockClientErrors, resetMockClientErrors } from './client-errors.js';
 export { environmentHandlers } from './environment.js';
+export { getMockPushSubscriptions, MOCK_PUSH_PUBLIC_KEY, pushHandlers, resetMockPush } from './push.js';
 export { exposeMswForE2E } from './e2e-hooks.js';
 export type { MswHandle, MswOverride } from './override.js';

package/dist/mocks/index.js

@@ -4,4 +4,5 @@
 export { authHandlers, getMockCurrentUser, isMockAuthenticated, MOCK_PASSWORD, MOCK_RECOVERY_CODE, MOCK_TOTP_CODE, MOCK_TOTP_USER, MOCK_USER, resetMockAuth, setMockAuthenticated, } from './auth.js';
 export { clientErrorHandlers, getMockClientErrors, resetMockClientErrors } from './client-errors.js';
 export { environmentHandlers } from './environment.js';
+export { getMockPushSubscriptions, MOCK_PUSH_PUBLIC_KEY, pushHandlers, resetMockPush } from './push.js';
 export { exposeMswForE2E } from './e2e-hooks.js';

package/dist/mocks/push.d.ts

@@ -0,0 +1,9 @@
+import type { components } from '../api/schema.js';
+type PushSubscriptionRequest = components['schemas']['PushSubscriptionRequest'];
+/** RFC 8291's example key: a valid P-256 point, and nobody's real one. */
+export declare const MOCK_PUSH_PUBLIC_KEY = "BP4z9KsN6nGRTbVYI_c7VJSPQTBtkgcy27mlmlMoZIIgDll6e3vCYLocInmYWAmS6TlzAC8wEqKK6PBru3jl7A8";
+/** What POST /push/subscriptions has saved since the last reset. */
+export declare function getMockPushSubscriptions(): readonly PushSubscriptionRequest[];
+export declare function resetMockPush(): void;
+export declare const pushHandlers: import("msw").HttpHandler[];
+export {};

package/dist/mocks/push.js

@@ -0,0 +1,40 @@
+// MSW handlers for /push/* (openapi/foundation.yaml), for an app whose
+// contract has them. Like the reference backend they need the mock
+// session, and a device subscribing again gets its id back. Nothing is
+// ever sent: under MSW, usePushPermission reads 'mock' and never
+// subscribes, since MSW's own worker holds the page.
+import { http, HttpResponse } from 'msw';
+import { isMockAuthenticated } from './auth.js';
+/** RFC 8291's example key: a valid P-256 point, and nobody's real one. */
+export const MOCK_PUSH_PUBLIC_KEY = 'BP4z9KsN6nGRTbVYI_c7VJSPQTBtkgcy27mlmlMoZIIgDll6e3vCYLocInmYWAmS6TlzAC8wEqKK6PBru3jl7A8';
+let subscriptions = new Map();
+let nextId = 1;
+/** What POST /push/subscriptions has saved since the last reset. */
+export function getMockPushSubscriptions() {
+    return [...subscriptions.values()].map(({ request }) => request);
+}
+export function resetMockPush() {
+    subscriptions = new Map();
+    nextId = 1;
+}
+const unauthorized = () => HttpResponse.json({ detail: 'Not authenticated' }, { status: 401 });
+export const pushHandlers = [
+    http.get('*/api/push/public-key', () => isMockAuthenticated() ? HttpResponse.json({ publicKey: MOCK_PUSH_PUBLIC_KEY }) : unauthorized()),
+    http.post('*/api/push/subscriptions', async ({ request }) => {
+        if (!isMockAuthenticated())
+            return unauthorized();
+        const body = (await request.json());
+        const id = subscriptions.get(body.endpoint)?.id ?? nextId++;
+        subscriptions.set(body.endpoint, { id, request: body });
+        return HttpResponse.json({ id }, { status: 201 });
+    }),
+    http.delete('*/api/push/subscriptions/:id', ({ params }) => {
+        if (!isMockAuthenticated())
+            return unauthorized();
+        const entry = [...subscriptions.entries()].find(([, value]) => String(value.id) === params.id);
+        if (!entry)
+            return HttpResponse.json({ detail: 'No such subscription.' }, { status: 404 });
+        subscriptions.delete(entry[0]);
+        return new HttpResponse(null, { status: 204 });
+    }),
+];

package/dist/testing/index.d.ts

@@ -55,6 +55,18 @@ export type A11ySuiteOptions = {
      */
     nav?: readonly NavEntry[];
 };
+/**
+ * Every data view on the page has loaded: at least one shows its data (or,
+ * with `{ success: false }`, the page has its screen up), and none still
+ * shows its skeleton. A page may hold several (two `DataTable`s, an
+ * `EntityView` over a table of its sub-records), so this never waits on a
+ * locator that matches each of them: Playwright's strict mode refuses
+ * `expect(page.locator('[data-state="success"]')).toBeVisible()` as soon
+ * as two match. Use it before reading or scanning a screen.
+ */
+export declare function expectDataViewsLoaded(page: Page, { success }?: {
+    success?: boolean;
+}): Promise<void>;
 /**
  * Accessibility of the real screens in light and dark mode: every page in
  * the Primary nav (one test each from `nav`, or discovered in the sidebar

package/dist/testing/index.js

@@ -107,11 +107,31 @@ const NAV_PAGE_BUDGET_MS = 10_000;
 function navEntryRoutes(nav) {
     return [...new Set(nav.flatMap((entry) => (isNavSection(entry) ? entry.items : [entry]).map((item) => item.to)))];
 }
+/**
+ * Every data view on the page has loaded: at least one shows its data (or,
+ * with `{ success: false }`, the page has its screen up), and none still
+ * shows its skeleton. A page may hold several (two `DataTable`s, an
+ * `EntityView` over a table of its sub-records), so this never waits on a
+ * locator that matches each of them: Playwright's strict mode refuses
+ * `expect(page.locator('[data-state="success"]')).toBeVisible()` as soon
+ * as two match. Use it before reading or scanning a screen.
+ */
+export async function expectDataViewsLoaded(page, { success = true } = {}) {
+    if (success)
+        await expect(page.locator('[data-state="success"]').first()).toBeVisible();
+    // A data view renders its skeleton from its first paint, so once the
+    // screen is up every one of them is either loading or settled.
+    else
+        await expect(page.getByRole('main').first()).toBeVisible();
+    await expect(page.locator('[data-state="loading"]')).toHaveCount(0);
+}
 async function expectNavPageAccessible(page, route, colorScheme) {
     await page.goto(route);
     await expect(page.locator('html')).toHaveClass(colorScheme);
-    // Wait for data, not the loading skeleton, so the real UI is checked.
-    await expect(page.locator('[data-state="loading"]')).toHaveCount(0);
+    // Wait for data, not the loading skeleton, so the real UI is checked. A
+    // nav page may have no data view, or only an empty one, so none has to
+    // show data.
+    await expectDataViewsLoaded(page, { success: false });
     await expectNoAxeViolations(page);
 }
 /**
@@ -163,8 +183,9 @@ export function defineA11ySuite({ formRoutes, viewRoutes = [], loggedOutRoutes,
             for (const route of viewRoutes) {
                 test(`${route} has zero axe violations`, async ({ page }) => {
                     await page.goto(route);
-                    // EntityView's loaded state, not its skeleton or an error.
-                    await expect(page.locator('[data-state="success"]')).toBeVisible();
+                    // EntityView's loaded state, not its skeleton or an error, and
+                    // every other data view on the page loaded too.
+                    await expectDataViewsLoaded(page);
                     await expectNoAxeViolations(page);
                 });
             }

package/openapi/foundation.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: UI Foundation — the contract every app shares
-  version: "4.1.0"
+  version: "4.17.0"
   description: >
     The part of an app's API contract that the foundation package's own code
     calls: session-cookie auth under /auth/*, and the two error envelopes the
@@ -13,8 +13,8 @@ info:
 
     A path marked `x-optional: true` may be left out of an app's spec (an
     app without self-service sign-up omits /auth/register, an app that
-    doesn't render DataEnvironmentBanner omits /environment), but if
-    present it must match.
+    doesn't render DataEnvironmentBanner omits /environment, an app without
+    reminders omits /push/*), but if present it must match.
 
 servers:
   - url: /api
@@ -161,6 +161,68 @@ paths:
         "422": { $ref: "#/components/responses/ValidationError" }
         "500": { $ref: "#/components/responses/ServerError" }
 
+  /push/public-key:
+    x-optional: true
+    get:
+      operationId: getPushPublicKey
+      summary: The app's VAPID public key, which a browser subscribes to push with
+      description: >
+        For usePushPermission. 404 when the backend has push turned off.
+      tags: [push]
+      responses:
+        "200":
+          description: OK.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/PushPublicKey" }
+        "401": { $ref: "#/components/responses/UnauthorizedError" }
+        "404": { $ref: "#/components/responses/NotFoundError" }
+        "500": { $ref: "#/components/responses/ServerError" }
+
+  /push/subscriptions:
+    x-optional: true
+    post:
+      operationId: savePushSubscription
+      summary: Save this device's push subscription for the signed-in user
+      description: >
+        The browser's PushSubscription.toJSON(). The same endpoint again
+        replaces its keys and owner and answers the same id. The endpoint
+        must be a push service's (422 otherwise): the backend POSTs to it.
+      tags: [push]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/PushSubscriptionRequest" }
+      responses:
+        "201":
+          description: Saved.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/PushSubscriptionCreated" }
+        "401": { $ref: "#/components/responses/UnauthorizedError" }
+        "404": { $ref: "#/components/responses/NotFoundError" }
+        "422": { $ref: "#/components/responses/ValidationError" }
+        "500": { $ref: "#/components/responses/ServerError" }
+
+  /push/subscriptions/{id}:
+    x-optional: true
+    delete:
+      operationId: deletePushSubscription
+      summary: Stop sending to one of the signed-in user's devices
+      tags: [push]
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema: { type: integer }
+      responses:
+        "204":
+          description: Deleted.
+        "401": { $ref: "#/components/responses/UnauthorizedError" }
+        "404": { $ref: "#/components/responses/NotFoundError" }
+        "500": { $ref: "#/components/responses/ServerError" }
+
 components:
   schemas:
     DataEnvironment:
@@ -235,6 +297,40 @@ components:
         status: { type: integer, minimum: 100, maximum: 599, description: The HTTP status of a failed request. }
         release: { type: string, maxLength: 100, description: The frontend build (its commit). }
 
+    PushPublicKey:
+      type: object
+      required: [publicKey]
+      properties:
+        publicKey:
+          type: string
+          minLength: 1
+          description: The P-256 public key, base64url (applicationServerKey).
+
+    PushSubscriptionRequest:
+      type: object
+      required: [endpoint, keys]
+      properties:
+        endpoint:
+          type: string
+          minLength: 1
+          maxLength: 2048
+          description: The push service's URL for this device.
+        expirationTime:
+          type: ["number", "null"]
+          description: Milliseconds since the epoch, sent by some browsers, ignored.
+        keys:
+          type: object
+          required: [p256dh, auth]
+          properties:
+            p256dh: { type: string, minLength: 1, maxLength: 100 }
+            auth: { type: string, minLength: 1, maxLength: 32 }
+
+    PushSubscriptionCreated:
+      type: object
+      required: [id]
+      properties:
+        id: { type: integer }
+
     ValidationErrorBody:
       type: object
       description: FastAPI's default 422 shape (RequestValidationError).

package/package.json

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

package/vite/index.d.ts

@@ -24,3 +24,30 @@ export type BuildInfoOptions = {
  * `BUILD_REPO_URL`.
  */
 export default function buildInfo(options?: BuildInfoOptions): Plugin
+
+export type PwaOptions = {
+  /** The app's name, as the Home Screen and the install prompt show it. */
+  name: string
+  /** A shorter one for under the icon. Defaults to `name`; its first letter is the SVG icon's. */
+  shortName?: string
+  description?: string
+  /** `#rrggbb`. Defaults to the package's `--primary` token. */
+  themeColor?: string
+  /** The letter's colour on the SVG icon, `#rrggbb`. Defaults to `--primary-foreground`. */
+  themeForegroundColor?: string
+  /** The splash screen's, `#rrggbb`. Defaults to `--background`. */
+  backgroundColor?: string
+  /**
+   * The app's own icon, a square PNG of at least 512×512 (path from the Vite
+   * root). Replaces the generated ones everywhere.
+   */
+  icon?: string
+}
+
+/**
+ * Makes the app installable and receives reminders: serves and builds
+ * `/manifest.webmanifest`, `/icons/*` and `/push-sw.js` (the service worker
+ * usePushPermission registers), and adds the manifest, theme-color and
+ * apple-touch-icon tags to index.html.
+ */
+export function pwa(options: PwaOptions): Plugin

package/vite/index.js

@@ -26,6 +26,8 @@
 import fs from 'node:fs'
 import path from 'node:path'
 
+export { pwa } from './pwa.js'
+
 const OWN_FIELDS = ['api', 'commit', 'pr', 'builtAt', 'schema']
 
 /** @param {string | undefined} value */

package/vite/push-sw.js

@@ -0,0 +1,46 @@
+// The app's service worker, written by pwa() (./index.js) as /push-sw.js.
+// Push and notification clicks only: no fetch handler, so it never caches
+// the app or stands between it and Vite's hashed files. Registered by
+// usePushPermission's enable(), not on load. ICON is set by pwa().
+/* global self, clients */
+const ICON = '__ICON__'
+
+self.addEventListener('install', () => self.skipWaiting())
+self.addEventListener('activate', (event) => event.waitUntil(self.clients.claim()))
+
+// app/push.py sends {title, body, url, tag}. Anything else still shows.
+self.addEventListener('push', (event) => {
+  let data = {}
+  try {
+    data = event.data ? event.data.json() : {}
+  } catch {
+    data = { body: event.data ? event.data.text() : '' }
+  }
+  const options = { body: data.body || '', icon: ICON, data: { url: data.url || '/' } }
+  if (data.tag) options.tag = data.tag
+  event.waitUntil(self.registration.showNotification(data.title || 'Reminder', options))
+})
+
+// Opens the message's path in the app: in a window already open on the
+// app if there is one, else a new one. Never another site.
+self.addEventListener('notificationclick', (event) => {
+  event.notification.close()
+  const target = new URL((event.notification.data && event.notification.data.url) || '/', self.location.origin)
+  if (target.origin !== self.location.origin) return
+  event.waitUntil(
+    (async () => {
+      const windows = await clients.matchAll({ type: 'window', includeUncontrolled: true })
+      const open = windows.find((client) => new URL(client.url).origin === target.origin)
+      if (open) {
+        await open.focus()
+        try {
+          await open.navigate(target.href)
+          return
+        } catch {
+          // An uncontrolled window can't be navigated from here.
+        }
+      }
+      await clients.openWindow(target.href)
+    })(),
+  )
+})

package/vite/pwa.d.ts

@@ -0,0 +1,18 @@
+// The helpers behind pwa(), typed for the package's own tests. Apps use
+// `pwa` from `@tristan2828/ui-foundation/vite` (./index.d.ts).
+import type { HtmlTagDescriptor, Plugin } from 'vite'
+import type { PwaOptions } from './index'
+
+export function themeToken(css: string, name: string): string
+export function oklchToHex(value: string): string
+export function solidPng(size: number, hex: string): Buffer
+export function letterSvg(name: string, background: string, foreground: string): string
+export function pwaFiles(
+  options: PwaOptions,
+  base?: string,
+  root?: string,
+): {
+  files: Map<string, { type: string; source: string | Buffer }>
+  tags: (HtmlTagDescriptor & { attrs: Record<string, string> })[]
+}
+export function pwa(options: PwaOptions): Plugin