@tristan2828/ui-foundation 4.15.0 → 4.17.0

package/dist/lib/audio-cues.js

@@ -0,0 +1,138 @@
+// Sound cues for timed screens, with no audio files: a sine-tone chime
+// (a short attack, a slow fade) from Web Audio, spoken lines from the
+// browser's speech synthesis, and a vibration on Android.
+//
+// Browsers block sound until the person has clicked or tapped, so a
+// session's start button calls unlockAudio() from its click; every cue
+// before that is silently dropped rather than played late. Everything
+// here is a no-op where the browser can't make the sound
+// (docs/foundation/timed-screens.md "Sound").
+//
+// createAudioCues takes the browser's APIs, so the rules are unit tested
+// against fakes (tests/audio-cues.test.ts); the functions exported below
+// are one shared instance over the real ones.
+const ATTACK = 0.015;
+// An exponential ramp can't reach zero, so a chime starts and ends here.
+const SILENT = 0.0001;
+export function createAudioCues(env) {
+    let context = null;
+    // A resume asked for from a click: the context is still "suspended" for
+    // a moment, and a chime from that same click should still play.
+    let resuming = false;
+    const playable = () => context !== null && (context.state === 'running' || resuming);
+    const strike = (ctx, { pitch = 660, volume = 0.25, duration = 1200 }, delay) => {
+        const start = ctx.currentTime + delay / 1000;
+        const end = start + Math.max(duration, 50) / 1000;
+        const peak = Math.min(Math.max(volume, SILENT), 1);
+        const oscillator = ctx.createOscillator();
+        oscillator.type = 'sine';
+        oscillator.frequency.setValueAtTime(pitch, start);
+        const gain = ctx.createGain();
+        gain.gain.setValueAtTime(SILENT, start);
+        gain.gain.exponentialRampToValueAtTime(peak, start + ATTACK);
+        gain.gain.exponentialRampToValueAtTime(SILENT, end);
+        oscillator.connect(gain).connect(ctx.destination);
+        oscillator.start(start);
+        oscillator.stop(end + 0.05);
+    };
+    return {
+        unlockAudio() {
+            if (env.AudioContext) {
+                try {
+                    context ??= new env.AudioContext();
+                    if (context.state !== 'running' && context.state !== 'closed') {
+                        resuming = true;
+                        context.resume().then(() => (resuming = false), () => (resuming = false));
+                    }
+                }
+                catch {
+                    context = null;
+                }
+            }
+            // iOS speaks only once speech has started from a gesture: a silent,
+            // empty line here lets later cues through.
+            if (env.speechSynthesis && env.SpeechSynthesisUtterance) {
+                try {
+                    const primer = new env.SpeechSynthesisUtterance('');
+                    primer.volume = 0;
+                    env.speechSynthesis.speak(primer);
+                }
+                catch {
+                    // No speech: say() stays a no-op.
+                }
+            }
+        },
+        chime(options = {}) {
+            if (!playable() || !context)
+                return;
+            strike(context, options, 0);
+        },
+        sequence(chimes, { spacing = 180 } = {}) {
+            if (!playable() || !context)
+                return;
+            const ctx = context;
+            chimes.forEach((options, index) => strike(ctx, options, index * spacing));
+        },
+        say(text, { lang, rate, volume } = {}) {
+            if (!env.speechSynthesis || !env.SpeechSynthesisUtterance)
+                return;
+            try {
+                env.speechSynthesis.cancel();
+                const line = new env.SpeechSynthesisUtterance(text);
+                if (lang)
+                    line.lang = lang;
+                if (rate !== undefined)
+                    line.rate = rate;
+                if (volume !== undefined)
+                    line.volume = volume;
+                env.speechSynthesis.speak(line);
+            }
+            catch {
+                // Speech unavailable: the cue is dropped.
+            }
+        },
+        hush() {
+            try {
+                env.speechSynthesis?.cancel();
+            }
+            catch {
+                // Nothing to stop.
+            }
+        },
+        vibrate(pattern) {
+            try {
+                env.vibrate?.(pattern);
+            }
+            catch {
+                // No vibration motor, or not allowed here.
+            }
+        },
+    };
+}
+let shared = null;
+function browserCues() {
+    if (shared)
+        return shared;
+    const win = typeof window === 'undefined' ? undefined : window;
+    shared = createAudioCues({
+        AudioContext: win?.AudioContext ?? win?.webkitAudioContext,
+        speechSynthesis: win?.speechSynthesis,
+        SpeechSynthesisUtterance: win?.SpeechSynthesisUtterance,
+        vibrate: typeof navigator !== 'undefined' && typeof navigator.vibrate === 'function'
+            ? (pattern) => navigator.vibrate(pattern)
+            : undefined,
+    });
+    return shared;
+}
+/** Call from the click or tap that starts a session; sound is allowed from then on. */
+export const unlockAudio = () => browserCues().unlockAudio();
+/** A soft sine chime; dropped before unlockAudio() or where there's no Web Audio. */
+export const chime = (options) => browserCues().chime(options);
+/** Several chimes `spacing` ms apart (a closing pair). */
+export const sequence = (chimes, options) => browserCues().sequence(chimes, options);
+/** Speaks a line, cutting off the one before. A no-op without speech synthesis. */
+export const say = (text, options) => browserCues().say(text, options);
+/** Stops whatever is being spoken. */
+export const hush = () => browserCues().hush();
+/** A vibration pattern in ms; Android only, a no-op elsewhere. */
+export const vibrate = (pattern) => browserCues().vibrate(pattern);

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/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.15.0",
+  "version": "4.17.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