@swiftbrowser/web 0.17.7 → 0.18.0

package/src/notifications.ts

@@ -4,6 +4,13 @@
  * comes due; the page only answers for the permission and shows what it is
  * told to, with the browser's Notification API. Nothing is scheduled here, so
  * nothing fires once the page is closed.
+ *
+ * Remote notifications are Web Push ("Push notifications" there): the app's
+ * `registerForRemoteNotifications` becomes `pushSubscribe`, which registers
+ * the site's service worker (public/sw.js) and subscribes through it; the
+ * subscription is the app's device token. The worker shows each push and
+ * reports pushes and clicks to the page, which hands them to the app one
+ * `receive` request at a time.
  */
 
 import type { NotificationRequestParams } from './protocol';
@@ -11,11 +18,26 @@ import type { NotificationRequestParams } from './protocol';
 /** `NotificationPermission`, or no Notification API at all. */
 export type NotificationPermissionState = NotificationPermission | 'unsupported';
 
+/** A push subscription as `PushSubscription.toJSON()` gives it: what a server sends to. */
+export interface PushSubscriptionInfo {
+  endpoint: string;
+  keys: { p256dh: string; auth: string };
+}
+
+/** What the service worker reports: a push that arrived, or a click on a notification it showed. */
+export type PushEvent = { type: 'push'; payload: unknown } | { type: 'click'; payload: unknown; action: string };
+
 export interface NotificationResult {
   /** `status` and `request`. */
   permission?: NotificationPermissionState;
   /** `show`: whether a notification appeared. */
   shown?: boolean;
+  /** `pushSubscribe`. */
+  subscription?: PushSubscriptionInfo;
+  /** `receive`: the event's fields. */
+  type?: PushEvent['type'];
+  payload?: unknown;
+  action?: string;
 }
 
 /** The browser's notification facilities; tests substitute them. */
@@ -28,6 +50,17 @@ export interface NotificationHost {
   close(tags: readonly string[]): void;
   /** `navigator.setAppBadge` (0 clears), where the browser has it. */
   setBadge?(count: number): Promise<void>;
+  /** Web Push through the service worker, where the browser has it. */
+  push?: PushHost;
+}
+
+/** The push service, as the service worker reaches it; tests substitute it. */
+export interface PushHost {
+  /** Subscribes with the key (registering the worker first); the subscription. */
+  subscribe(applicationServerKey: string): Promise<PushSubscriptionInfo>;
+  unsubscribe(): Promise<void>;
+  /** Resolves with the next push or click the worker reported. */
+  receive(): Promise<PushEvent>;
 }
 
 export async function performNotification(params: NotificationRequestParams, host: NotificationHost | undefined): Promise<NotificationResult> {
@@ -55,13 +88,29 @@ export async function performNotification(params: NotificationRequestParams, hos
     case 'badge':
       await host?.setBadge?.(params.badge ?? 0).catch(() => undefined);
       return {};
+    case 'pushSubscribe': {
+      if (!host?.push) throw new Error('unsupported: this browser has no push service');
+      if (!params.applicationServerKey) throw new Error('push: no application server key (webPushKey in swiftbrowser.json)');
+      // A subscription needs the permission: asked for here when it has not been.
+      const granted = permission === 'default' ? await host.requestPermission() : permission;
+      if (granted !== 'granted') throw new Error('denied: notifications are not allowed');
+      return { subscription: await host.push.subscribe(params.applicationServerKey) };
+    }
+    case 'pushUnsubscribe':
+      await host?.push?.unsubscribe();
+      return {};
+    case 'receive': {
+      if (!host?.push) throw new Error('unsupported: this browser has no push service');
+      const event = await host.push.receive();
+      return event.type === 'click' ? { type: 'click', payload: event.payload, action: event.action } : { type: 'push', payload: event.payload };
+    }
     default:
       throw new Error(`unsupported: notification action ${String((params as { action: unknown }).action)}`);
   }
 }
 
 /** The Notification API, or nothing where the browser has none (an iPhone tab not on the Home Screen). */
-export function browserNotificationHost(): NotificationHost | undefined {
+export function browserNotificationHost(push?: PushHost): NotificationHost | undefined {
   if (typeof window === 'undefined' || typeof Notification === 'undefined') return undefined;
   const open = new Map<string, Notification>();
   const badgeNavigator = navigator as Navigator & { setAppBadge?: (n?: number) => Promise<void>; clearAppBadge?: () => Promise<void> };
@@ -105,5 +154,89 @@ export function browserNotificationHost(): NotificationHost | undefined {
             count > 0 ? badgeNavigator.setAppBadge!(count) : (badgeNavigator.clearAppBadge?.() ?? Promise.resolve()),
         }
       : {}),
+    ...(push ? { push } : {}),
+  };
+}
+
+/** The message types the service worker (public/sw.js) posts to the page. */
+export const PUSH_MESSAGE = 'swiftbrowser:push';
+export const CLICK_MESSAGE = 'swiftbrowser:notificationclick';
+
+/** The push event a service worker message carries, or null when `data` is not one. */
+export function pushEventOf(data: unknown): PushEvent | null {
+  if (typeof data !== 'object' || data === null) return null;
+  const message = data as { type?: unknown; payload?: unknown; action?: unknown };
+  if (message.type === PUSH_MESSAGE) return { type: 'push', payload: message.payload ?? {} };
+  if (message.type === CLICK_MESSAGE) return { type: 'click', payload: message.payload ?? {}, action: typeof message.action === 'string' ? message.action : '' };
+  return null;
+}
+
+/** A VAPID public key (base64url, as servers print it) as the bytes `subscribe` takes. */
+export function applicationServerKeyBytes(key: string): Uint8Array<ArrayBuffer> {
+  const base64 = key.replace(/-/g, '+').replace(/_/g, '/');
+  const padded = base64 + '='.repeat((4 - (base64.length % 4)) % 4);
+  const binary = atob(padded);
+  const bytes = new Uint8Array(new ArrayBuffer(binary.length));
+  for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+/** The subscription's `toJSON()`, checked for the fields a server needs. */
+function subscriptionInfo(subscription: PushSubscription): PushSubscriptionInfo {
+  const json = subscription.toJSON();
+  const keys = json.keys ?? {};
+  if (!json.endpoint || typeof keys['p256dh'] !== 'string' || typeof keys['auth'] !== 'string') throw new Error('push: the subscription has no keys');
+  return { endpoint: json.endpoint, keys: { p256dh: keys['p256dh'], auth: keys['auth'] } };
+}
+
+/**
+ * Web Push through the service worker at `workerURL` with `scope` (the
+ * site's base), or nothing where the browser has no push service (Safari
+ * before 16.4; an iPhone tab not on the Home Screen). Listens for the
+ * worker's messages from the start: a click that opened the page is posted
+ * before the app asks for it.
+ */
+export function browserPushHost(workerURL: string, scope: string): PushHost | undefined {
+  if (typeof navigator === 'undefined' || !('serviceWorker' in navigator) || !navigator.serviceWorker || typeof PushManager === 'undefined') return undefined;
+  const container = navigator.serviceWorker;
+  const queue: PushEvent[] = [];
+  const waiting: ((event: PushEvent) => void)[] = [];
+  container.addEventListener('message', (message: MessageEvent) => {
+    const event = pushEventOf(message.data);
+    if (!event) return;
+    const wake = waiting.shift();
+    if (wake) wake(event);
+    else queue.push(event);
+  });
+  const registration = async (): Promise<ServiceWorkerRegistration> => {
+    const existing = await container.getRegistration(scope);
+    if (existing?.active && existing.scope === new URL(scope, location.href).href) return existing;
+    return container.register(workerURL, { scope });
+  };
+  return {
+    subscribe: async (key) => {
+      const worker = await registration();
+      await container.ready;
+      const options: PushSubscriptionOptionsInit = { userVisibleOnly: true, applicationServerKey: applicationServerKeyBytes(key) };
+      const current = await worker.pushManager.getSubscription();
+      try {
+        return subscriptionInfo(current ?? (await worker.pushManager.subscribe(options)));
+      } catch (error) {
+        // A subscription under another key stands in the way: replaced.
+        if (!current) throw error;
+        await current.unsubscribe().catch(() => undefined);
+        return subscriptionInfo(await worker.pushManager.subscribe(options));
+      }
+    },
+    unsubscribe: async () => {
+      const worker = await container.getRegistration(scope);
+      const current = await worker?.pushManager.getSubscription();
+      await current?.unsubscribe();
+    },
+    receive: () => {
+      const queued = queue.shift();
+      if (queued) return Promise.resolve(queued);
+      return new Promise((resolve) => waiting.push(resolve));
+    },
   };
 }

package/src/pinch.ts

@@ -5,7 +5,7 @@
  *
  * - two touch (or pen) pointers on it: the scale is the distance between them
  *   over the distance when the second came down, the rotation the turn of the
- *   line between them;
+ *   line between them, the location their midpoint;
  * - a trackpad pinch, which Chrome, Edge and Firefox report as `wheel` events
  *   with `ctrlKey` (a scale only);
  * - Safari's `gesturestart` / `gesturechange` / `gestureend` on a computer
@@ -47,6 +47,10 @@ interface Pinch {
   rotation: number;
   startLocation: { x: number; y: number };
   startAnchor: { x: number; y: number };
+  /** Where the fingers' midpoint is now, in the element's coordinates. */
+  location: { x: number; y: number };
+  /** The element's top leading corner in the viewport when the pinch began. */
+  origin: { x: number; y: number };
   samples: { t: number; scale: number; rotation: number }[];
   raf: number | null;
 }
@@ -135,6 +139,8 @@ export class PinchController {
       rotation: 0,
       startLocation: { x: round(x, 2), y: round(y, 2) },
       startAnchor: { x: round(rect.width > 0 ? x / rect.width : 0.5), y: round(rect.height > 0 ? y / rect.height : 0.5) },
+      location: { x: round(x, 2), y: round(y, 2) },
+      origin: { x: rect.left, y: rect.top },
       samples: [],
       raf: null,
     };
@@ -185,6 +191,7 @@ export class PinchController {
       rotationVelocity: round(rotationVelocity, 2),
       startLocation: pinch.startLocation,
       startAnchor: pinch.startAnchor,
+      location: pinch.location,
     });
   }
 
@@ -239,6 +246,7 @@ export class PinchController {
     state.lastAngle = angle;
     const rotation = pinch.rotation + step;
     const scale = Math.hypot(pb.x - pa.x, pb.y - pa.y) / base.distance;
+    pinch.location = { x: round((pa.x + pb.x) / 2 - pinch.origin.x, 2), y: round((pa.y + pb.y) / 2 - pinch.origin.y, 2) };
     this.update(pinch, scale, rotation, event.timeStamp);
   };
 

package/src/pinnedViews.ts

@@ -0,0 +1,131 @@
+/**
+ * `pinnedViews` (docs/ops-protocol.md, "Scroll geometry, pinned views and
+ * animation completion"): a lazy stack or grid marked `pinned` keeps each
+ * `section` child's header at the leading edge of the scroll view's visible
+ * area while the section passes, and the next section's header pushes it
+ * out, as `LazyVStack(pinnedViews: [.sectionHeaders])` does; a pinned footer
+ * stays at the trailing edge while its section is in view the same way.
+ *
+ * The renderer registers the marked stacks; after every layout and on every
+ * scroll event each header is moved by a transform along the axis. The
+ * laid-out positions are left alone (offsets, not client rects), so the
+ * transform never feeds back into where the header is reckoned to be.
+ */
+
+import type { PinnedView } from './protocol';
+import { layoutOrigin } from './scrollTransition';
+
+export interface Span {
+  start: number;
+  length: number;
+}
+
+/**
+ * How far a header moves toward the trailing edge to stay at `viewStart`:
+ * nothing while its section's start is in view, then as far as the view has
+ * scrolled past it, and no further than its section's end (where the next
+ * section's header pushes it out).
+ */
+export function pinnedHeaderOffset(viewStart: number, header: Span, sectionEnd: number): number {
+  const room = Math.max(0, sectionEnd - header.start - header.length);
+  return Math.min(room, Math.max(0, viewStart - header.start));
+}
+
+/**
+ * How far a footer moves toward the leading edge (negative) to stay at
+ * `viewEnd` while its section is in view: no further than its section's
+ * start, where the previous section's footer takes over.
+ */
+export function pinnedFooterOffset(viewEnd: number, footer: Span, sectionStart: number): number {
+  const room = Math.min(0, sectionStart - footer.start);
+  return Math.max(room, Math.min(0, viewEnd - footer.start - footer.length));
+}
+
+const registered = new Map<HTMLElement, Set<PinnedView>>();
+
+/** Called by the renderer for every stack and grid: registers, updates or forgets its pinned views. */
+export function setPinnedViews(el: HTMLElement, pinned: PinnedView[] | undefined): void {
+  const views = new Set<PinnedView>(Array.isArray(pinned) ? pinned.filter((view) => view === 'sectionHeaders' || view === 'sectionFooters') : []);
+  if (views.size === 0) {
+    if (registered.delete(el)) {
+      delete el.dataset['sbPinned'];
+      for (const section of sections(el)) {
+        for (const kind of ['sectionheader', 'sectionfooter'] as const) {
+          const view = supplement(section, kind);
+          if (view) {
+            view.style.transform = '';
+            view.style.zIndex = '';
+          }
+        }
+      }
+    }
+    return;
+  }
+  registered.set(el, views);
+  el.dataset['sbPinned'] = [...views].join(' ');
+  draw(el, views);
+}
+
+function sections(stack: HTMLElement): HTMLElement[] {
+  return [...stack.children].filter((child): child is HTMLElement => child instanceof HTMLElement && child.classList.contains('sb-section'));
+}
+
+function supplement(section: HTMLElement, kind: 'sectionheader' | 'sectionfooter'): HTMLElement | null {
+  for (const child of section.children) {
+    if (child instanceof HTMLElement && child.classList.contains(`sb-${kind}`)) return child;
+  }
+  return null;
+}
+
+/** The inset of a bar the scroll view runs under (largeTitle.ts sets `--sb-top-inset`). */
+function topInset(scroller: HTMLElement): number {
+  return parseFloat(scroller.style.getPropertyValue('--sb-top-inset')) || 0;
+}
+
+function draw(stack: HTMLElement, views: Set<PinnedView>): void {
+  const scroller = stack.parentElement?.closest<HTMLElement>('.sb-scrollview, .sb-list');
+  if (!scroller) return;
+  const horizontal = stack.classList.contains('sb-hstack') || stack.classList.contains('sb-lazyhgrid');
+  const viewStart = horizontal ? scroller.scrollLeft : scroller.scrollTop + topInset(scroller);
+  const viewEnd = (horizontal ? scroller.scrollLeft + scroller.clientWidth : scroller.scrollTop + scroller.clientHeight);
+  for (const section of sections(stack)) {
+    const origin = layoutOrigin(section, scroller);
+    if (!origin) continue;
+    const sectionStart = horizontal ? origin.x : origin.y;
+    const sectionEnd = sectionStart + (horizontal ? section.offsetWidth : section.offsetHeight);
+    if (views.has('sectionHeaders')) {
+      const header = supplement(section, 'sectionheader');
+      if (header) {
+        const at = layoutOrigin(header, scroller);
+        const span: Span = { start: horizontal ? (at?.x ?? sectionStart) : (at?.y ?? sectionStart), length: horizontal ? header.offsetWidth : header.offsetHeight };
+        move(header, horizontal, pinnedHeaderOffset(viewStart, span, sectionEnd));
+      }
+    }
+    if (views.has('sectionFooters')) {
+      const footer = supplement(section, 'sectionfooter');
+      if (footer) {
+        const at = layoutOrigin(footer, scroller);
+        const span: Span = { start: horizontal ? (at?.x ?? sectionEnd) : (at?.y ?? sectionEnd), length: horizontal ? footer.offsetWidth : footer.offsetHeight };
+        move(footer, horizontal, pinnedFooterOffset(viewEnd, span, sectionStart));
+      }
+    }
+  }
+}
+
+function move(view: HTMLElement, horizontal: boolean, offset: number): void {
+  const rounded = Math.round(offset * 100) / 100;
+  view.style.transform = rounded === 0 ? '' : horizontal ? `translateX(${rounded}px)` : `translateY(${rounded}px)`;
+  // Over the rows of its section, which come after it in the stack.
+  view.style.zIndex = '1';
+}
+
+/** Moves every pinned view to its place: after a layout, and on every scroll event. */
+export function drawPinnedViews(): void {
+  for (const [stack, views] of registered) {
+    if (!stack.isConnected) {
+      registered.delete(stack);
+      continue;
+    }
+    draw(stack, views);
+  }
+}

package/src/plainEditor.ts

@@ -0,0 +1,79 @@
+/**
+ * The plain `texteditor` (a textarea) with a bound `selection`
+ * (docs/ops-protocol.md, "Rich text editors"): it reports the viewer's
+ * selection (`selectionStart`/`selectionEnd`, UTF-16 offsets as a string's
+ * indices) and moves to one the app sets, under the rich editor's rules
+ * (src/editorSelection.ts): at once while focused, else when the app focuses
+ * it; the selection the app sends back is not applied again, and one the
+ * viewer did not move is not reported again.
+ */
+
+import type { TextEditorProps, TextSelectionRange } from './protocol';
+import { editorBlurred, isSelectionBound, markSelectionBound, noteViewerSelection, selectionToApply, takePendingSelection, viewerFocused } from './editorSelection';
+
+export function isPlainEditor(el: unknown): el is HTMLTextAreaElement {
+  return el instanceof HTMLTextAreaElement && el.classList.contains('sb-texteditor');
+}
+
+/** After the text: a selection the app set (not the viewer's coming back), moved to now, or when the app focuses the editor. */
+export function applyPlainEditorSelection(area: HTMLTextAreaElement, props: TextEditorProps): void {
+  markSelectionBound(area, props.selection !== undefined);
+  const range = selectionToApply(area, props.selection);
+  if (range) area.setSelectionRange(range.start, range.end);
+}
+
+/** Focuses an editor for the app (a bound `focused`): its caret where the app last set the selection, else where the browser leaves it. */
+export function focusPlainEditor(area: HTMLTextAreaElement): void {
+  const range = takePendingSelection(area);
+  area.focus({ preventScroll: true });
+  if (range) area.setSelectionRange(range.start, range.end);
+}
+
+type Report = (event: { type: 'selection'; id: number; value: TextSelectionRange }) => void;
+
+/**
+ * The listeners every plain editor under `root` shares: the selection
+ * reported for bound editors. Returns what removes them.
+ */
+export function listenToPlainEditors(root: HTMLElement, idOf: (el: HTMLElement) => number | null, report: Report): () => void {
+  const doc = root.ownerDocument;
+  const editorOf = (target: EventTarget | null): HTMLTextAreaElement | null => (isPlainEditor(target) && root.contains(target) ? target : null);
+  const reportSelection = (area: HTMLTextAreaElement): void => {
+    if (!isSelectionBound(area)) return;
+    const id = idOf(area);
+    if (id === null) return;
+    const range = { start: area.selectionStart, end: area.selectionEnd };
+    if (noteViewerSelection(area, range)) report({ type: 'selection', id, value: range });
+  };
+  // Browsers differ in what a caret move in a textarea raises (the document's
+  // `selectionchange`, the control's `select`, or nothing until the key or
+  // button is up, as after an input): each is a look at the selection, which
+  // is reported once however many of them fire.
+  const onSelectionChange = (): void => {
+    const area = editorOf(doc.activeElement);
+    if (area) reportSelection(area);
+  };
+  const onEditorEvent = (event: Event): void => {
+    const area = editorOf(event.target);
+    if (area) reportSelection(area);
+  };
+  const onFocusIn = (event: FocusEvent): void => {
+    const area = editorOf(event.target);
+    if (area) viewerFocused(area);
+  };
+  const onFocusOut = (event: FocusEvent): void => {
+    const area = editorOf(event.target);
+    if (area) editorBlurred(area);
+  };
+  const looks = ['select', 'keyup', 'mouseup', 'input'] as const;
+  for (const type of looks) root.addEventListener(type, onEditorEvent);
+  root.addEventListener('focusin', onFocusIn);
+  root.addEventListener('focusout', onFocusOut);
+  doc.addEventListener('selectionchange', onSelectionChange);
+  return () => {
+    for (const type of looks) root.removeEventListener(type, onEditorEvent);
+    root.removeEventListener('focusin', onFocusIn);
+    root.removeEventListener('focusout', onFocusOut);
+    doc.removeEventListener('selectionchange', onSelectionChange);
+  };
+}