@eifi1/ui-kit 0.35.0 → 0.36.0

package/src/notifications/notification-types.ts

@@ -0,0 +1,80 @@
+import type { ReactNode } from "react";
+
+/**
+ * The shapes the notification cards share (docs/notifications-harmonization.md §3.2,
+ * §3.5, §4.2): the server's `GET /notifications/settings` answer, the parts of its
+ * `PATCH` the cards send, one push device, and the app's words for its types.
+ *
+ * Types only — the kit keeps no list of notification types and no defaults (§2.1): the
+ * server's registry is the one list, and the cards draw what it answers.
+ */
+
+/** The digest's cadence, one for the account (§2.5): Monday, or the 1st, in its zone. */
+export type DigestCadence = "weekly" | "monthly";
+
+/**
+ * One type's two switches in the `GET` (§3.2). `null` where the type does not offer
+ * that channel: `email` for a type with no mail, `app` in an app with no "in the app"
+ * channel (Kurvenschmiede: `{app: null, email: true}`). An unset switch already reads as
+ * its default — the server fills it in.
+ */
+export interface NotificationSwitches {
+  app: boolean | null;
+  email: boolean | null;
+}
+
+/** The `GET`'s `types`: every type the account can receive, in the registry's order. */
+export type NotificationTypesValue = Readonly<Record<string, NotificationSwitches>>;
+
+/**
+ * The app's words for one of its types — where an app TYPES its ids, so its own maps
+ * (keksdose's inbox icons) are keyed on the same list (§5.1). The kit draws the type
+ * only when the server answered it.
+ */
+export interface NotificationTypeEntry<Id extends string = string> {
+  id: Id;
+  /** The switch's label: what the person hears about. */
+  label: string;
+  /** The line under it, attached to the switch. */
+  description?: ReactNode;
+}
+
+/** A heading over some of the types, in the app's words (keksdose's "Budget", "Scans &
+ *  sharing", "Summaries & news"). */
+export interface NotificationTypeGroup<Id extends string = string> {
+  /** A stable key for the group. */
+  id: string;
+  label: ReactNode;
+  /** The group's types, in the order they are drawn. */
+  types: readonly Id[];
+}
+
+/**
+ * The parts of `PATCH /notifications/settings` (§3.2) the cards send. Omitted keeps; a
+ * type's `null` puts both its switches back to their defaults; `quiet_hours_*: null`
+ * clears a time. One switch per call from the types card (`{types: {digest: {app:
+ * true}}}`), or `{digest_cadence}`; quiet hours send a time, with the device's zone the
+ * first time; the zone picker sends `{timezone}`.
+ */
+export interface NotificationSettingsPatch<Id extends string = string> {
+  types?: Partial<Record<Id, { app?: boolean; email?: boolean } | null>>;
+  digest_cadence?: DigestCadence;
+  quiet_hours_start?: string | null;
+  quiet_hours_end?: string | null;
+  timezone?: string;
+}
+
+/** One registered push device, as `GET /notifications/devices` lists it (§3.5), oldest
+ *  first. The owner gets the whole endpoint, which marks "this device". */
+export interface PushDeviceItem<Id extends string | number = string> {
+  id: Id;
+  endpoint: string;
+  /** The browser's user agent at registration; `null` when it sent none. */
+  user_agent: string | null;
+  /** ISO date-time. */
+  created_at: string;
+  /** ISO date-time of the last delivery the push service accepted, or `null`. */
+  last_success_at: string | null;
+  /** Failed deliveries in a row; the server removes the device at 10. */
+  failure_count: number;
+}

package/src/notifications/notifications-labels.ts

@@ -0,0 +1,238 @@
+// The words of the notification cards (docs/notifications-harmonization.md §4.2), in a
+// module with no component code: the English catalogue (src/i18n/defaults.ts) imports
+// them without the components, so `en` loads as one chunk like the other languages
+// (0.34, KS U8). The cards read it through `useKitLabels("notifications", …)`.
+
+/** The ten IANA regions `Intl` lists zones under — keksdose's `tz_region_*` — in the
+ *  kit's words. A region a runtime adds later keeps its IANA name. */
+export interface NotificationRegionLabels {
+  Africa: string;
+  America: string;
+  Antarctica: string;
+  Arctic: string;
+  Asia: string;
+  Atlantic: string;
+  Australia: string;
+  Europe: string;
+  Indian: string;
+  Pacific: string;
+}
+
+/**
+ * Every string the notification parts render — the `notifications` namespace of
+ * `<UiKitProvider labels>`, overridable per instance through `labels`: the types card,
+ * quiet hours and the zone picker, this device's push, the device list, and the
+ * unsubscribe page. Cancel is `common.cancel`.
+ */
+export interface NotificationsLabels {
+  /* ── The types card ─────────────────────────────────────────────────── */
+  /** The types card's title. */
+  typesTitle: string;
+  /** The line under it. */
+  typesDescription: string;
+  /** The e-mail switch under a type that offers mail. */
+  byEmail: string;
+  /** Under every e-mail switch while the account's address is unverified (decision 16):
+   *  no notification mail goes to an unverified address. */
+  emailUnverified: string;
+  /** The digest's cadence select. */
+  digestCadence: string;
+  digestWeekly: string;
+  digestMonthly: string;
+  /** While the settings load. */
+  typesLoading: string;
+  /** The server answered no types for this account. */
+  typesEmpty: string;
+
+  /* ── Quiet hours ────────────────────────────────────────────────────── */
+  quietTitle: string;
+  /** The line under the title; `inbox`: the app keeps an inbox, which a held push still
+   *  reaches. */
+  quietDescription: (inbox: boolean) => string;
+  /** The start time's label. */
+  quietFrom: string;
+  /** The end time's label. */
+  quietUntil: string;
+  /** One time set, the other not: quiet hours fail open until both are. */
+  quietIncomplete: string;
+  /** The zone picker's label. */
+  timeZone: string;
+  /** Given the device's zone, as the picker names it, when it differs from the one the
+   *  server applies. */
+  deviceZone: (zone: string) => string;
+  /** The button that takes the device's zone. */
+  useDeviceZone: string;
+  /** The zone picker's region headings. */
+  regions: NotificationRegionLabels;
+
+  /* ── This device ────────────────────────────────────────────────────── */
+  pushTitle: string;
+  pushDescription: string;
+  /** The browser has no push. */
+  unsupported: string;
+  /** iOS outside the installed app, given the app's name. */
+  iosInstall: (app: string) => string;
+  /** The server has no VAPID keys. */
+  notConfigured: string;
+  /** The browser's permission is denied. */
+  blocked: string;
+  /** This device gets notifications for the signed-in account. */
+  on: string;
+  off: string;
+  /** This browser's subscription belongs to another account. */
+  otherAccount: string;
+  enable: string;
+  disable: string;
+  sendTest: string;
+  /** Turning on did not finish (the permission prompt dismissed, a refusal). */
+  enableFailed: string;
+  /** No service worker, or one that is not ready in 10 s. */
+  noServiceWorker: string;
+  /** The browser's push service did not answer in 15 s. */
+  pushTimeout: string;
+  /** Given how many devices the push service accepted the test for (≥ 1). */
+  testSent: (count: number) => string;
+  /** The test reached no device. */
+  testNone: string;
+  testFailed: string;
+  /** The explainer before the browser's one permission prompt. */
+  explainerTitle: string;
+  explainerBody: (app: string) => string;
+  explainerHint: string;
+  explainerContinue: string;
+
+  /* ── The device list ────────────────────────────────────────────────── */
+  devicesTitle: string;
+  devicesDescription: string;
+  devicesLoading: string;
+  devicesEmpty: string;
+  /** A device whose user agent says nothing the kit recognises. */
+  unknownDevice: string;
+  /** The chip on this browser's row. */
+  thisDevice: string;
+  /** Given the registration date, formatted. */
+  added: (date: string) => string;
+  /** Given the last accepted delivery, formatted. */
+  lastDelivery: (date: string) => string;
+  noDelivery: string;
+  /** Given the failed deliveries in a row (≥ 1). */
+  failures: (count: number) => string;
+  /** A row's button, visible text — and the confirm's answer. */
+  remove: string;
+  /** The same button's accessible name, given the device: it starts with `remove`. */
+  removeItem: (device: string) => string;
+  /** The question the row asks before it removes. */
+  removePrompt: string;
+
+  /* ── The unsubscribe page ───────────────────────────────────────────── */
+  unsubscribeTitle: string;
+  /** Given the type's name in the app's words. */
+  unsubscribeAbout: (type: string) => string;
+  /** No type name to give. */
+  unsubscribeGeneric: string;
+  stopThese: string;
+  stopAll: (app: string) => string;
+  stoppedThese: string;
+  stoppedAll: (app: string) => string;
+  /** Account mail is not a notification, and keeps coming. */
+  accountMail: string;
+  turnBackOn: string;
+  openSettings: string;
+  /** A token the server refused, or one that does not parse. */
+  invalidLink: string;
+
+  /* ── Every card ─────────────────────────────────────────────────────── */
+  /** A request failed, and the app had no words of its own. */
+  failed: string;
+}
+
+export const DEFAULT_NOTIFICATIONS_LABELS: NotificationsLabels = {
+  typesTitle: "Notify me about",
+  typesDescription: "Choose what you hear about, and how.",
+  byEmail: "By e-mail",
+  emailUnverified: "Confirm your address to receive these.",
+  digestCadence: "Frequency",
+  digestWeekly: "Weekly",
+  digestMonthly: "Monthly",
+  typesLoading: "Loading notification settings…",
+  typesEmpty: "There are no notifications for this account.",
+
+  quietTitle: "Quiet hours",
+  quietDescription: (inbox) =>
+    inbox
+      ? "No push notifications during this window. They still reach your inbox."
+      : "No push notifications during this window.",
+  quietFrom: "From",
+  quietUntil: "Until",
+  quietIncomplete: "Set both a start and an end time. Quiet hours take effect once both are set.",
+  timeZone: "Time zone",
+  deviceZone: (zone) => `This device is in ${zone}.`,
+  useDeviceZone: "Use it",
+  regions: {
+    Africa: "Africa",
+    America: "Americas",
+    Antarctica: "Antarctica",
+    Arctic: "Arctic",
+    Asia: "Asia",
+    Atlantic: "Atlantic",
+    Australia: "Australia",
+    Europe: "Europe",
+    Indian: "Indian Ocean",
+    Pacific: "Pacific",
+  },
+
+  pushTitle: "Push notifications",
+  pushDescription: "Notifications on this device, also while the app is closed.",
+  unsupported: "This browser doesn’t support push notifications.",
+  iosInstall: (app) =>
+    `On iPhone or iPad, add ${app} to your Home Screen first: iOS delivers notifications only to the installed app.`,
+  notConfigured: "Push notifications aren’t set up on this server.",
+  blocked: "Notifications are blocked in this browser’s settings.",
+  on: "Notifications are on for this device.",
+  off: "Notifications are off for this device.",
+  otherAccount:
+    "This browser gets notifications for another account. Turn them on here to get them for the account you’re signed in with.",
+  enable: "Turn on notifications",
+  disable: "Turn off",
+  sendTest: "Send a test",
+  enableFailed: "Couldn’t turn on notifications.",
+  noServiceWorker: "Couldn’t reach the app’s service worker. Reload the page and try again.",
+  pushTimeout: "The browser’s push service didn’t answer. Check your connection and try again.",
+  testSent: (count) => (count === 1 ? "Test sent to 1 device" : `Test sent to ${count} devices`),
+  testNone: "No device accepted the test. Turn notifications on for this device first.",
+  testFailed: "Couldn’t send a test notification.",
+  explainerTitle: "Turn on notifications?",
+  explainerBody: (app) =>
+    `${app} sends a notification only for the kinds you choose, and you can turn them off at any time.`,
+  explainerHint: "Your browser asks for permission next.",
+  explainerContinue: "Continue",
+
+  devicesTitle: "Notification devices",
+  devicesDescription: "Every device that gets push notifications for your account. Remove any you no longer use.",
+  devicesLoading: "Loading devices…",
+  devicesEmpty: "No device gets notifications yet.",
+  unknownDevice: "Unknown device",
+  thisDevice: "This device",
+  added: (date) => `Added ${date}`,
+  lastDelivery: (date) => `Last delivery ${date}`,
+  noDelivery: "No delivery yet",
+  failures: (count) =>
+    count === 1 ? "1 failed delivery in a row" : `${count} failed deliveries in a row`,
+  remove: "Remove",
+  removeItem: (device) => `Remove ${device}`,
+  removePrompt: "Stop sending notifications to this device?",
+
+  unsubscribeTitle: "E-mail notifications",
+  unsubscribeAbout: (type) => `You get e-mails about: ${type}.`,
+  unsubscribeGeneric: "You get notification e-mails.",
+  stopThese: "Stop these e-mails",
+  stopAll: (app) => `Stop all notification e-mails from ${app}`,
+  stoppedThese: "Done. You won’t get these e-mails any more.",
+  stoppedAll: (app) => `Done. You won’t get notification e-mails from ${app} any more.`,
+  accountMail: "E-mails about your account still come.",
+  turnBackOn: "You can turn them back on at any time in Settings.",
+  openSettings: "Open Settings",
+  invalidLink: "This link doesn’t work any more. You can turn e-mails off in Settings instead.",
+
+  failed: "That didn’t work. Please try again.",
+};

package/src/notifications/push-device-setting.tsx

@@ -0,0 +1,224 @@
+import { useState } from "react";
+import type { ComponentPropsWithRef, ReactNode } from "react";
+
+import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
+import { DEFAULT_COMMON_LABELS } from "../i18n/shared-labels";
+import { cn } from "../lib/cn";
+import { AlertBanner } from "../components/alert-banner";
+import { Button } from "../components/button";
+import { Card } from "../components/card";
+import { DialogFrame } from "../components/dialog-frame";
+import { COMMIT_EXCEPT_BILLING } from "../components/write-lock";
+import { CARD_DESCRIPTION_CLASS } from "../settings/settings-card-classes";
+import { SettingsCardTitle } from "../settings/settings-heading";
+import { useMounted } from "../account/account-parts";
+import { describeFailure, FailureLine, useNotificationsLabels } from "./notification-parts";
+import type { NotificationsLabels } from "./notifications-labels";
+import { PushDeviceError } from "./use-push-device";
+import type { PushDevice } from "./use-push-device";
+
+/** Which action failed — {@link PushDeviceSettingProps.describeError}'s second argument. */
+export type PushDeviceAction = "enable" | "disable" | "test";
+
+export interface PushDeviceSettingProps extends Omit<ComponentPropsWithRef<"div">, "children"> {
+  /** This browser's push, from {@link usePushDevice}. */
+  push: PushDevice;
+  /** The app's name, for the iOS line and the explainer. */
+  appName: string;
+  /** The app's own words for a failure, or `undefined` for the kit's. The kit already
+   *  has words for a missing service worker and an unanswered push service. */
+  describeError?: (error: unknown, action: PushDeviceAction) => ReactNode | undefined;
+  labels?: LabelOverride<NotificationsLabels>;
+}
+
+/** What the line under the buttons says. */
+type Outcome = { tone: "status" | "warning" | "danger"; text: ReactNode } | null;
+
+/**
+ * Push on THIS device (docs/notifications-harmonization.md §2.2, §2.7, §4.2): keksdose's
+ * push block, as a card of its own. Registering the device is the switch — push has no
+ * account switch. One state at a time, in keksdose's order
+ * (`notifications-card.tsx:333-402`):
+ *
+ * 1. the browser has no push;
+ * 2. iOS outside the installed app (iOS delivers only to the installed app);
+ * 3. push is not set up on the server (no VAPID keys);
+ * 4. notifications blocked in the browser;
+ * 5. on or off — with "another account" when this browser's subscription is someone
+ *    else's — and "Turn on notifications", or "Send a test" and "Turn off".
+ *
+ * **The explainer comes before the browser's one prompt**: turning on while the
+ * permission is still `"default"` opens a dialog first (what the notifications are for,
+ * that the browser asks next); with it granted, it goes straight on. A test that reached
+ * no device says so (`testNone`) — a 404/410 removes the row on the server while this
+ * browser still holds its subscription. Outcomes are a line under the buttons; nothing
+ * toasts.
+ */
+export function PushDeviceSetting({
+  push,
+  appName,
+  describeError,
+  labels: labelsProp,
+  className,
+  ...rest
+}: PushDeviceSettingProps) {
+  const labels = useNotificationsLabels(labelsProp);
+  const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
+  const [explainer, setExplainer] = useState(false);
+  const [running, setRunning] = useState<PushDeviceAction | null>(null);
+  const [outcome, setOutcome] = useState<Outcome>(null);
+  const mounted = useMounted();
+
+  const failureOf = (error: unknown, action: PushDeviceAction, fallback: string): ReactNode => {
+    if (error instanceof PushDeviceError) {
+      return error.code === "no_service_worker" ? labels.noServiceWorker : labels.pushTimeout;
+    }
+    return describeFailure(describeError?.(error, action), fallback);
+  };
+
+  const run = <T,>(action: PushDeviceAction, call: () => Promise<T>, done: (value: T) => Outcome, fallback: string) => {
+    if (running) return;
+    setRunning(action);
+    setOutcome(null);
+    call().then(
+      (value) => {
+        if (!mounted.current) return;
+        setRunning(null);
+        setOutcome(done(value));
+      },
+      (error: unknown) => {
+        if (!mounted.current) return;
+        setRunning(null);
+        setOutcome({ tone: "danger", text: failureOf(error, action, fallback) });
+      },
+    );
+  };
+
+  const enable = () =>
+    run(
+      "enable",
+      () => push.enable(),
+      (ok): Outcome => (ok ? null : { tone: "danger", text: labels.enableFailed }),
+      labels.enableFailed,
+    );
+  const disable = () => run("disable", () => push.disable(), () => null, labels.failed);
+  const test = () =>
+    run(
+      "test",
+      () => push.sendTest(),
+      ({ sent }): Outcome =>
+        sent > 0 ? { tone: "status", text: labels.testSent(sent) } : { tone: "warning", text: labels.testNone },
+      labels.testFailed,
+    );
+
+  const turnOn = () => {
+    if (push.permission === "granted") enable();
+    else setExplainer(true);
+  };
+
+  let state: ReactNode;
+  if (!push.supported) {
+    state = <p className={CARD_DESCRIPTION_CLASS}>{labels.unsupported}</p>;
+  } else if (push.ios && !push.installed) {
+    state = <p className={CARD_DESCRIPTION_CLASS}>{labels.iosInstall(appName)}</p>;
+  } else if (push.configured === false) {
+    state = <p className={CARD_DESCRIPTION_CLASS}>{labels.notConfigured}</p>;
+  } else if (push.permission === "denied") {
+    state = <p className="text-xs text-warning">{labels.blocked}</p>;
+  } else {
+    const busy = push.busy || running !== null;
+    state = (
+      <>
+        <p className={CARD_DESCRIPTION_CLASS} data-push-state={push.subscribed ? "on" : "off"}>
+          {push.subscribed ? labels.on : labels.off}
+        </p>
+        {push.foreignSubscription && <p className="text-xs text-warning">{labels.otherAccount}</p>}
+        <div className="flex flex-wrap gap-2">
+          {push.subscribed ? (
+            <>
+              <Button
+                type="button"
+                size="sm"
+                variant="secondary"
+                commit={COMMIT_EXCEPT_BILLING}
+                pending={running === "test"}
+                disabled={busy && running !== "test"}
+                onClick={test}
+              >
+                {labels.sendTest}
+              </Button>
+              <Button
+                type="button"
+                size="sm"
+                variant="ghost"
+                commit={COMMIT_EXCEPT_BILLING}
+                pending={running === "disable"}
+                disabled={busy && running !== "disable"}
+                onClick={disable}
+              >
+                {labels.disable}
+              </Button>
+            </>
+          ) : (
+            <Button
+              type="button"
+              size="sm"
+              commit={COMMIT_EXCEPT_BILLING}
+              pending={running === "enable"}
+              disabled={busy && running !== "enable"}
+              onClick={turnOn}
+            >
+              {labels.enable}
+            </Button>
+          )}
+        </div>
+        {outcome?.tone === "status" && (
+          <p role="status" className={CARD_DESCRIPTION_CLASS}>
+            {outcome.text}
+          </p>
+        )}
+        {outcome?.tone === "warning" && (
+          <AlertBanner tone="warning" size="sm" role="status">
+            {outcome.text}
+          </AlertBanner>
+        )}
+        {outcome?.tone === "danger" && <FailureLine>{outcome.text}</FailureLine>}
+      </>
+    );
+  }
+
+  return (
+    <Card {...rest} className={cn("p-4 space-y-3", className)}>
+      <div>
+        <SettingsCardTitle>{labels.pushTitle}</SettingsCardTitle>
+        <div className={CARD_DESCRIPTION_CLASS}>{labels.pushDescription}</div>
+      </div>
+      {state}
+      <DialogFrame
+        open={explainer}
+        onClose={() => setExplainer(false)}
+        title={labels.explainerTitle}
+        description={labels.explainerBody(appName)}
+        actions={(close) => (
+          <div className="flex justify-end gap-2">
+            <Button type="button" variant="ghost" onClick={close}>
+              {common.cancel}
+            </Button>
+            <Button
+              type="button"
+              onClick={() => {
+                setExplainer(false);
+                // Only now the browser's one permission prompt.
+                enable();
+              }}
+            >
+              {labels.explainerContinue}
+            </Button>
+          </div>
+        )}
+      >
+        <p className={CARD_DESCRIPTION_CLASS}>{labels.explainerHint}</p>
+      </DialogFrame>
+    </Card>
+  );
+}