@tristan2828/ui-foundation 4.16.0 → 4.18.0

package/README.md

@@ -18,11 +18,11 @@ than installing this by hand:
 
 | Import | What |
 |---|---|
-| `@tristan2828/ui-foundation` | `AppShell`, `DataTable`, `EntityView` (with `EditableValue`, `editInPlace`), `EntityForm`, `Markdown`, `RichTextEditor`, `ErrorState`, `MultiChoice`, `MultiReference`, `ListEditor`, `PasswordInput`, `RouteErrorBoundary`, `FoundationProviders`, `DataEnvironmentBanner`, `LoginRoute`, `RegisterRoute`, `useAuth`, `useTableUrlState`, `useRecordUpdate`, `useDebouncedValue`, `createQueryClient`, `cn`; types `Page`, `AppError`, `QuerySpec`. For timed screens (`docs/foundation/timed-screens.md`): `SessionView`, `useSessionClock`, `useWakeLock`, `useMuted`, `usePrefersReducedMotion`, and the audio cues `unlockAudio`, `chime`, `sequence`, `say`, `hush`, `vibrate` |
+| `@tristan2828/ui-foundation` | `AppShell`, `DataTable`, `EntityView` (with `EditableValue`, `editInPlace`), `EntityForm`, `Markdown`, `RichTextEditor`, `ErrorState`, `MultiChoice`, `MultiReference`, `ListEditor`, `PasswordInput`, `RouteErrorBoundary`, `FoundationProviders`, `DataEnvironmentBanner`, `LoginRoute`, `RegisterRoute`, `useAuth`, `useTableUrlState`, `useRecordUpdate`, `useDebouncedValue`, `createQueryClient`, `cn`; types `Page`, `AppError`, `QuerySpec`. For timed screens (`docs/foundation/timed-screens.md`): `SessionView`, `useSessionClock`, `useWakeLock`, `useMuted`, `usePrefersReducedMotion`, and the audio cues `unlockAudio`, `chime`, `sequence`, `say`, `hush`, `vibrate`. For reminders (`docs/foundation/reminders.md`): `AllowReminders`, `usePushPermission` |
 | `@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` |
+| `@tristan2828/ui-foundation/testing` | Playwright: `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/AGENTS.md

@@ -96,6 +96,13 @@ routine) is built from the package's parts: `SessionView`,
 `docs/foundation/timed-screens.md`, including its Playwright recipe
 (`clock.install()` before `goto`, then `fastForward`, never `runFor`).
 
+## Reminders
+A notification at a time the user chose, with the app closed, is Web
+Push: `pwa()` in `vite.config.ts`, `AllowReminders` with
+`usePushPermission()`, and the backend's `send_push` and reminders job.
+Follow `docs/foundation/reminders.md`. Never ask for notification
+permission on page load: only from the click on "Allow reminders".
+
 ## Scope and Stopping
 - Do the task you were given and nothing beyond it. A task is done when
   `npm run verify` passes — not when it feels complete.

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

@@ -554,6 +554,24 @@ is a filled-in example while the Widgets demo is still here).
   one into `src/` to change it: raise it for the foundation (AGENTS.md
   "Changing the Foundation") and build the screen once the release ships.
 
+## After a commit, in the backend
+
+A router reads who's signed in from the `User` that `get_current_user`
+loaded in the request's own database session. `session.commit()` expires
+every object in that session (`expire_on_commit`, on by default), the user
+included, and reading an expired attribute is a lazy load, which under
+asyncio is a `MissingGreenlet` and a 500.
+
+- **After a commit, read by a `user_id` saved before it, never by the
+  `User`.** Take `user_id = user.id` at the top of the handler and use that
+  from then on; or `await session.refresh(user)` first, as `_start_session`
+  in `routers/auth.py` does to return it.
+- **Test signed in for real.** The backend's `client` fixture
+  (`tests/conftest.py`) holds a `sessions` row and sends its cookie,
+  so the real `get_current_user` runs (`tests/signed_in.py`). Never stand
+  a `User(...)` in for `get_current_user` in an override: a detached user
+  never expires, so the test passes and the route fails live.
+
 ## Deleting
 
 The plan's "Deleting" line says which of three. The Widget reference is the

package/conventions/docs/reminders.md

@@ -0,0 +1,85 @@
+# Reminders
+
+A notification at a time the user chose ("time for your morning routine",
+"a short break at 3 pm", a habit, a medication) that reaches them with the
+app closed. It's Web Push: the browser subscribes with its push service
+(Google's, Mozilla's, Apple's, Microsoft's), the backend encrypts a message
+to that subscription and posts it there, and the push service delivers it
+to the device, where the app's service worker shows it.
+
+| Part | Where | What it does |
+|---|---|---|
+| `pwa({ name })` | `vite.config.ts`, from `@tristan2828/ui-foundation/vite` | The app installable: a manifest, icons in the theme's colours, and `/push-sw.js`, the service worker that shows pushes and opens their path |
+| `usePushPermission()` | the package | Whether this device gets reminders, and `enable`/`disable` |
+| `AllowReminders` | the package | The control: says what reminders are, then asks, on a click |
+| `/push/public-key`, `/push/subscriptions` | `openapi.yaml`, the foundation's part (optional) | The VAPID key to subscribe with; this device's subscription saved or dropped |
+| `app/push.py` | the reference backend | `send_push(session, user_id, title, body, url)`: encrypted (RFC 8291), signed (VAPID), to every device the user allowed |
+| `app/reminders.py`, `reminders` | the reference backend | A reminder row (when, which days, the text, the path), and the `send-reminders` job that sends each one when it's due |
+
+Off until the backend turns it on (`PUSH_ENABLED`, `docs/deploy.md`
+"Reminders (Web Push)"). An app without reminders leaves `/push/*` out of
+`openapi.yaml` and `pwa()` out of its config.
+
+## Allowing reminders
+
+```tsx
+import { AllowReminders, usePushPermission } from '@tristan2828/ui-foundation'
+
+const push = usePushPermission()
+<AllowReminders push={push} description="We'll remind you when it's time for your routine." />
+```
+
+- **Never ask on page load.** A prompt nobody expected gets refused, and a
+  refusal is final: only the browser's site settings undo it. The button
+  says what reminders are first; `enable()` asks then, from the click.
+- **Put it where reminders are set**: the top of the reminders list, or a
+  settings page. One per device: each phone or browser allows its own.
+- **Every state says what to do next.** `AllowReminders` shows them all
+  (the package's Storybook, `app/AllowReminders`):
+
+| `status` | Means | Shows |
+|---|---|---|
+| `off` | Can be turned on | The description and "Allow reminders" |
+| `on` | This device gets them | "Reminders are on for this device", and "Turn off" |
+| `needs-install` | iPhone or iPad in a browser tab | How to add the app to the Home Screen |
+| `blocked` | The person said no | Where to allow it again |
+| `unsupported` | No push in this browser | That it can't |
+| `mock` | The app runs on MSW | That reminders need the real backend |
+
+## On iPhone and iPad
+
+Push works only in the app added to the Home Screen (Share, then Add to
+Home Screen) and opened from there, on iOS 16.4 or later. In a Safari tab
+there is no push at all, so `usePushPermission` says `needs-install` and
+`AllowReminders` shows the steps. `pwa()`'s manifest (`display:
+standalone`) is what makes the Home Screen app an app.
+
+## A reminder is the app's own row
+
+The reference backend has a `reminders` table and the job that sends it;
+what a reminder means is the app's. Give it an API and screens like any
+entity (`add-an-entity.md`): its fields are `title`, `body`, `url` (a
+path in the app, opened when it's tapped), `timeOfDay` ("07:30"), `days`
+(some of mon,tue,wed,thu,fri,sat,sun), `timeZone` (the person's IANA
+zone: `Intl.DateTimeFormat().resolvedOptions().timeZone`) and `enabled`.
+Scope it to the signed-in user, as Widgets are.
+
+- **The job** (`send-reminders`, every minute, with `JOBS_ENABLED`)
+  sends a reminder when today is one of its days in its time zone and the
+  time has come, once a day at most. More than 15 minutes late (the
+  backend was down) and it's skipped for the day rather than sent late.
+- **Something else to send?** Call `send_push` from the app's own code or
+  job: a message when a long task finishes, a daily summary. The `url` is
+  always the app's own path.
+- **Time zones** come from the system's time zone database. On Windows
+  that's the `tzdata` package, which the backend doesn't install: a
+  Windows dev machine reads only `UTC` until it's added.
+
+## Testing
+
+Under MSW the page is held by MSW's service worker, so `usePushPermission`
+reads `mock` and never subscribes: screens show the `mock` state, and a
+Playwright spec checks it the same way. The rest is the backend's: its
+tests decrypt every message as a browser would. To try it end to end, run
+the real backend with push on, allow reminders in the browser, then
+`backend/scripts/send_test_push.py <email>`.

package/dist/api/gateway/push.d.ts

@@ -0,0 +1,8 @@
+import type { components } from "../schema.js";
+export type PushSubscriptionRequest = components["schemas"]["PushSubscriptionRequest"];
+/** The key to subscribe with. A 404 is a backend with push turned off. */
+export declare function getPushPublicKey(): Promise<string>;
+/** Saves the subscription; the same device again answers the same id. */
+export declare function savePushSubscription(subscription: PushSubscriptionRequest): Promise<number>;
+/** Already gone (404) counts as done. */
+export declare function deletePushSubscription(id: number): Promise<void>;

package/dist/api/gateway/push.js

@@ -0,0 +1,25 @@
+import { safeFetch, toAppError } from "./errors.js";
+/** The key to subscribe with. A 404 is a backend with push turned off. */
+export async function getPushPublicKey() {
+    const res = await safeFetch("/push/public-key");
+    if (res.status !== 200)
+        throw toAppError(res.status, res.body, res.headers);
+    return res.body.publicKey;
+}
+/** Saves the subscription; the same device again answers the same id. */
+export async function savePushSubscription(subscription) {
+    const res = await safeFetch("/push/subscriptions", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(subscription),
+    });
+    if (res.status !== 201)
+        throw toAppError(res.status, res.body, res.headers);
+    return res.body.id;
+}
+/** Already gone (404) counts as done. */
+export async function deletePushSubscription(id) {
+    const res = await safeFetch(`/push/subscriptions/${id}`, { method: "DELETE" });
+    if (res.status !== 204 && res.status !== 404)
+        throw toAppError(res.status, res.body, res.headers);
+}

package/dist/api/schema.d.ts

@@ -131,6 +131,63 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/push/public-key": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * The app's VAPID public key, which a browser subscribes to push with
+         * @description For usePushPermission. 404 when the backend has push turned off.
+         */
+        get: operations["getPushPublicKey"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/push/subscriptions": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * 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.
+         */
+        post: operations["savePushSubscription"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/push/subscriptions/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post?: never;
+        /** Stop sending to one of the signed-in user's devices */
+        delete: operations["deletePushSubscription"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 }
 export type webhooks = Record<string, never>;
 export interface components {
@@ -185,6 +242,23 @@ export interface components {
             /** @description The frontend build (its commit). */
             release?: string;
         };
+        PushPublicKey: {
+            /** @description The P-256 public key, base64url (applicationServerKey). */
+            publicKey: string;
+        };
+        PushSubscriptionRequest: {
+            /** @description The push service's URL for this device. */
+            endpoint: string;
+            /** @description Milliseconds since the epoch, sent by some browsers, ignored. */
+            expirationTime?: number | null;
+            keys: {
+                p256dh: string;
+                auth: string;
+            };
+        };
+        PushSubscriptionCreated: {
+            id: number;
+        };
         /** @description FastAPI's default 422 shape (RequestValidationError). */
         ValidationErrorBody: {
             detail: {
@@ -442,4 +516,78 @@ export interface operations {
             500: components["responses"]["ServerError"];
         };
     };
+    getPushPublicKey: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PushPublicKey"];
+                };
+            };
+            401: components["responses"]["UnauthorizedError"];
+            404: components["responses"]["NotFoundError"];
+            500: components["responses"]["ServerError"];
+        };
+    };
+    savePushSubscription: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["PushSubscriptionRequest"];
+            };
+        };
+        responses: {
+            /** @description Saved. */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PushSubscriptionCreated"];
+                };
+            };
+            401: components["responses"]["UnauthorizedError"];
+            404: components["responses"]["NotFoundError"];
+            422: components["responses"]["ValidationError"];
+            500: components["responses"]["ServerError"];
+        };
+    };
+    deletePushSubscription: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Deleted. */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            401: components["responses"]["UnauthorizedError"];
+            404: components["responses"]["NotFoundError"];
+            500: components["responses"]["ServerError"];
+        };
+    };
 }

package/dist/components/app/allow-reminders.d.ts

@@ -0,0 +1,9 @@
+import type { ReactNode } from 'react';
+import type { PushPermission } from '../../hooks/use-push-permission.js';
+export type AllowRemindersProps = {
+    push: PushPermission;
+    /** What reminders are for, in the app's words, shown before asking. */
+    description?: ReactNode;
+    className?: string;
+};
+export declare function AllowReminders({ push, description, className }: AllowRemindersProps): import("react").JSX.Element;

package/dist/components/app/allow-reminders.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { BellIcon, BellOffIcon } from 'lucide-react';
+import { cn } from 'cn';
+import { Button } from '../ui/button.js';
+import { Skeleton } from '../ui/skeleton.js';
+import { Notice } from './notice.js';
+const DEFAULT_DESCRIPTION = 'Get a notification on this device at the times you set, even when the app is closed. Your browser will ask first.';
+export function AllowReminders({ push, description = DEFAULT_DESCRIPTION, className }) {
+    const { status, pending, error } = push;
+    return (_jsxs("div", { "data-slot": "allow-reminders", className: cn('flex flex-col gap-3', className), "aria-busy": status === undefined || pending, children: [status === undefined && _jsx(Skeleton, { className: "h-9 w-full max-w-md" }), status === 'off' && (_jsxs(_Fragment, { children: [_jsx("p", { className: "text-sm text-foreground", children: description }), _jsx("div", { children: _jsxs(Button, { onClick: push.enable, disabled: pending, children: [_jsx(BellIcon, { "aria-hidden": "true" }), pending ? 'Turning on…' : 'Allow reminders'] }) })] })), status === 'on' && (_jsx(Notice, { tone: "success", icon: BellIcon, action: _jsxs(Button, { size: "sm", variant: "outline", onClick: push.disable, disabled: pending, children: [_jsx(BellOffIcon, { "aria-hidden": "true" }), pending ? 'Turning off…' : 'Turn off'] }), children: "Reminders are on for this device." })), status === 'needs-install' && (_jsx(Notice, { title: "Add the app to your Home Screen first", children: "On iPhone and iPad, reminders work in the app from the Home Screen. Tap Share, then Add to Home Screen, open the app from there and allow reminders." })), status === 'blocked' && (_jsx(Notice, { tone: "warning", title: "Notifications are blocked", icon: BellOffIcon, children: "This browser was told not to show this app\u2019s notifications. Allow them in the site\u2019s settings (the icon beside the address), then reload." })), status === 'unsupported' && (_jsx("p", { className: "text-sm text-muted-foreground", children: "This browser can\u2019t show reminders." })), status === 'mock' && (_jsx("p", { className: "text-sm text-muted-foreground", children: "Reminders need the real backend: with mock data nothing can send them." })), error && (_jsx("p", { role: "alert", className: "text-sm text-destructive-text", children: error }))] }));
+}

package/dist/components/app/milkdown-editor.js

@@ -54,7 +54,7 @@ import { Button } from '../ui/button.js';
 import { Field, FieldError, FieldLabel } from '../ui/field.js';
 import { Input } from '../ui/input.js';
 import { Popover, PopoverContent } from '../ui/popover.js';
-import { linkHref } from '../../lib/link-href.js';
+import { linkHref, linkRefusal } from '../../lib/link-href.js';
 import { passEscapeThrough } from './escape-passthrough.js';
 import { calloutHandler, remarkCalloutNodes } from '../../lib/markdown-callout.js';
 import { MarkdownMergeError, markdownStyle, mergeMarkdown } from '../../lib/markdown-merge.js';
@@ -751,7 +751,9 @@ function LinkForm({ box, onApply }) {
     const apply = () => {
         const href = linkHref(typed);
         if (href === null) {
-            setError('Enter a web or email address, like https://example.com.');
+            setError(linkRefusal(typed) === 'whitespace'
+                ? 'An address has no spaces. Remove them, or write each as %20.'
+                : 'Enter a web or email address, like https://example.com.');
             return;
         }
         onApply(href);

package/dist/components/app/row-edit-cells.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { ExternalLinkIcon } from 'lucide-react';
 import { Input } from '../ui/input.js';
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../ui/select.js';
-import { linkHref } from '../../lib/link-href.js';
+import { linkHref, linkRefusal } from '../../lib/link-href.js';
 import { editInPlace } from './edit-in-place.js';
 import { EditableValue } from './editable-value.js';
 /** A name in one line: Enter saves, the form's rule runs first, a taken name's 422 shows in the cell. */
@@ -31,14 +31,17 @@ export function ChoiceCell({ label, value, options, render, save, triggerClassNa
         }), children: render(value) }));
 }
 // A web or email address (`example.com` gains https://), blank for none.
-// Another scheme (`javascript:`) is refused before anything is sent.
+// Another scheme (`javascript:`) or a space inside the address is refused
+// before anything is sent.
 const LINK_RULE = {
     safeParse: (value) => {
-        const href = linkHref(String(value ?? ''));
+        const typed = String(value ?? '');
+        const href = linkHref(typed);
         if (href === '')
             return { success: true, data: null };
         if (href === null) {
-            return { success: false, error: { issues: [{ message: 'Use a web or email address' }] } };
+            const message = linkRefusal(typed) === 'whitespace' ? 'An address has no spaces' : 'Use a web or email address';
+            return { success: false, error: { issues: [{ message }] } };
         }
         return { success: true, data: href };
     },

package/dist/hooks/use-push-permission.d.ts

@@ -0,0 +1,72 @@
+import { type PushSubscriptionRequest } from '../api/gateway/push.js';
+/**
+ * - `unsupported`: this browser has no push.
+ * - `needs-install`: iPhone or iPad in a browser tab; push works once the
+ *   app is added to the Home Screen and opened from there.
+ * - `mock`: the page runs on MSW; reminders need the real backend.
+ * - `blocked`: the person said no; only the browser's site settings undo it.
+ * - `off`: can be turned on. `on`: this device gets reminders.
+ */
+export type PushStatus = 'unsupported' | 'needs-install' | 'mock' | 'blocked' | 'off' | 'on';
+type PushRegistration = {
+    active: {
+        scriptURL: string;
+    } | null;
+    pushManager: Pick<PushManager, 'getSubscription' | 'subscribe'>;
+};
+/** What createPushController needs from the browser and the backend. */
+export type PushEnvironment = {
+    notification: {
+        permission: NotificationPermission;
+        requestPermission: () => Promise<NotificationPermission>;
+    } | undefined;
+    serviceWorker: {
+        register: (url: string, options: RegistrationOptions) => Promise<unknown>;
+        getRegistration: () => Promise<PushRegistration | undefined>;
+        ready: () => Promise<PushRegistration>;
+        /** The script of the worker controlling this page, if any. */
+        controllerScript: () => string | undefined;
+    } | undefined;
+    /** `'PushManager' in window`. */
+    pushSupported: boolean;
+    /** Opened from the Home Screen (display-mode: standalone). */
+    standalone: boolean;
+    /** An iPhone or iPad, whatever the browser says it is. */
+    appleMobile: boolean;
+    api: {
+        getPublicKey: () => Promise<string>;
+        save: (subscription: PushSubscriptionRequest) => Promise<number>;
+        remove: (id: number) => Promise<void>;
+    };
+};
+export type PushController = {
+    status: () => Promise<PushStatus>;
+    /** Asks the browser, subscribes, and saves it. Call it straight from a click. */
+    enable: () => Promise<PushStatus>;
+    /** Stops sending to this device, and unsubscribes it. */
+    disable: () => Promise<PushStatus>;
+};
+export type PushControllerOptions = {
+    /** Where pwa() serves the worker. Default `/push-sw.js`. */
+    serviceWorkerUrl?: string;
+};
+export declare function createPushController(env: PushEnvironment, options?: PushControllerOptions): PushController;
+export declare const PUSH_STATUS_QUERY_KEY: readonly ["ui-foundation", "push-status"];
+/** What usePushPermission returns, and what AllowReminders shows. */
+export type PushPermission = {
+    /** Undefined while it's being worked out. */
+    status: PushStatus | undefined;
+    enable: () => void;
+    disable: () => void;
+    /** Turning on or off is under way. */
+    pending: boolean;
+    /** Why the last enable or disable failed, in words to show. */
+    error: string | null;
+};
+/**
+ * Whether this device gets reminders, and `enable`/`disable` for one
+ * button (AllowReminders is that button, with the words around it).
+ * `enable` asks the browser for permission: only ever call it from a click.
+ */
+export declare function usePushPermission(options?: PushControllerOptions): PushPermission;
+export {};

package/dist/hooks/use-push-permission.js

@@ -0,0 +1,154 @@
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { deletePushSubscription, getPushPublicKey, savePushSubscription, } from '../api/gateway/push.js';
+const isMockWorker = (script) => !!script && script.includes('mockServiceWorker');
+function base64UrlToBytes(value) {
+    const base64 = value.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - (value.length % 4)) % 4);
+    const binary = atob(base64);
+    const bytes = new Uint8Array(new ArrayBuffer(binary.length));
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+function sameKey(current, wanted) {
+    if (!current)
+        return false;
+    const bytes = new Uint8Array(current);
+    return bytes.length === wanted.length && bytes.every((byte, i) => byte === wanted[i]);
+}
+function toRequest(subscription) {
+    const json = subscription.toJSON();
+    const p256dh = json.keys?.p256dh;
+    const auth = json.keys?.auth;
+    if (!json.endpoint || !p256dh || !auth)
+        throw new Error('The browser gave a subscription without its keys.');
+    return { endpoint: json.endpoint, expirationTime: json.expirationTime ?? null, keys: { p256dh, auth } };
+}
+export function createPushController(env, options = {}) {
+    const workerUrl = options.serviceWorkerUrl ?? '/push-sw.js';
+    // What can be told without waiting on anything, so enable() can ask
+    // the browser in the same task as the click.
+    const knownNow = () => {
+        if (env.appleMobile && !env.standalone)
+            return 'needs-install';
+        if (!env.notification || !env.serviceWorker || !env.pushSupported)
+            return 'unsupported';
+        if (isMockWorker(env.serviceWorker.controllerScript()))
+            return 'mock';
+        if (env.notification.permission === 'denied')
+            return 'blocked';
+        return null;
+    };
+    const ours = (registration) => registration?.active && !isMockWorker(registration.active.scriptURL) ? registration : undefined;
+    return {
+        async status() {
+            const known = knownNow();
+            if (known)
+                return known;
+            const registration = await env.serviceWorker.getRegistration();
+            if (isMockWorker(registration?.active?.scriptURL))
+                return 'mock';
+            if (env.notification.permission !== 'granted')
+                return 'off';
+            const subscription = await ours(registration)?.pushManager.getSubscription();
+            return subscription ? 'on' : 'off';
+        },
+        async enable() {
+            const known = knownNow();
+            if (known)
+                return known;
+            const permission = await env.notification.requestPermission();
+            if (permission !== 'granted')
+                return permission === 'denied' ? 'blocked' : 'off';
+            await env.serviceWorker.register(workerUrl, { scope: '/' });
+            const registration = await env.serviceWorker.ready();
+            const key = base64UrlToBytes(await env.api.getPublicKey());
+            let subscription = await registration.pushManager.getSubscription();
+            // Made with another key (the backend's was replaced): it can't be
+            // sent to any more, so start again.
+            if (subscription && !sameKey(subscription.options.applicationServerKey, key)) {
+                await subscription.unsubscribe();
+                subscription = null;
+            }
+            subscription ??= await registration.pushManager.subscribe({ userVisibleOnly: true, applicationServerKey: key });
+            await env.api.save(toRequest(subscription));
+            return 'on';
+        },
+        async disable() {
+            const subscription = await ours(await env.serviceWorker?.getRegistration())?.pushManager.getSubscription();
+            if (subscription) {
+                // Saving again is how the device learns its id (the same endpoint
+                // answers the same one), so nothing is kept on the device.
+                const id = await env.api.save(toRequest(subscription));
+                await env.api.remove(id);
+                await subscription.unsubscribe();
+            }
+            return 'off';
+        },
+    };
+}
+function browserEnvironment() {
+    const hasWindow = typeof window !== 'undefined';
+    const container = hasWindow && 'serviceWorker' in navigator ? navigator.serviceWorker : undefined;
+    const ua = hasWindow ? navigator.userAgent : '';
+    return {
+        notification: hasWindow && 'Notification' in window ? Notification : undefined,
+        serviceWorker: container && {
+            register: (url, options) => container.register(url, options),
+            getRegistration: () => container.getRegistration(),
+            ready: () => container.ready,
+            controllerScript: () => container.controller?.scriptURL,
+        },
+        pushSupported: hasWindow && 'PushManager' in window,
+        standalone: hasWindow &&
+            (window.matchMedia?.('(display-mode: standalone)').matches ||
+                navigator.standalone === true),
+        // iPadOS says it's a Mac; a Mac has no touch screen.
+        appleMobile: /iPhone|iPad|iPod/.test(ua) || (/Macintosh/.test(ua) && hasWindow && navigator.maxTouchPoints > 1),
+        api: { getPublicKey: getPushPublicKey, save: savePushSubscription, remove: deletePushSubscription },
+    };
+}
+function messageOf(error) {
+    const appError = error;
+    if (appError && typeof appError.kind === 'string') {
+        if (appError.kind === 'notfound')
+            return "This app's backend doesn't send reminders yet.";
+        if (appError.kind === 'network')
+            return "Couldn't reach the app. Check the connection and try again.";
+        return appError.message ?? 'Something went wrong. Try again.';
+    }
+    return "The browser couldn't turn on reminders. Try again, or check its notification settings.";
+}
+export const PUSH_STATUS_QUERY_KEY = ['ui-foundation', 'push-status'];
+/**
+ * Whether this device gets reminders, and `enable`/`disable` for one
+ * button (AllowReminders is that button, with the words around it).
+ * `enable` asks the browser for permission: only ever call it from a click.
+ */
+export function usePushPermission(options = {}) {
+    const queryClient = useQueryClient();
+    const controller = createPushController(browserEnvironment(), options);
+    const { data: status } = useQuery({
+        queryKey: PUSH_STATUS_QUERY_KEY,
+        queryFn: () => controller.status(),
+        staleTime: Infinity,
+    });
+    const settle = (next) => queryClient.setQueryData(PUSH_STATUS_QUERY_KEY, next);
+    // Each takes the run already started: enable() must ask the browser in
+    // the click itself, and mutate() may call its function a tick later.
+    const enable = useMutation({ mutationFn: (run) => run, onSuccess: settle });
+    const disable = useMutation({ mutationFn: (run) => run, onSuccess: settle });
+    const failed = enable.error ?? disable.error;
+    return {
+        status,
+        enable: () => {
+            disable.reset();
+            enable.mutate(controller.enable());
+        },
+        disable: () => {
+            enable.reset();
+            disable.mutate(controller.disable());
+        },
+        pending: enable.isPending || disable.isPending,
+        error: failed ? messageOf(failed) : null,
+    };
+}