@eifi1/ui-kit 0.34.0 → 0.36.0

package/src/lib/plain-text.ts

@@ -0,0 +1,22 @@
+import { isValidElement } from "react";
+import type { ReactNode } from "react";
+
+/**
+ * The text of a label node: a string or number as is, an element by its children,
+ * recursively, whitespace collapsed. A `<Tooltip label="…">Spend</Tooltip>` label yields
+ * "Spend" — the text the reader sees, not the bubble's. `undefined` when there is no text
+ * to find (an icon), so the caller falls back to a name of its own.
+ *
+ * Package-private — not re-exported from the barrel. StatTile names its sparkline by it;
+ * a field names its `help` "?" by it ("About <label>", round 0.36).
+ */
+export function plainText(node: ReactNode): string | undefined {
+  const walk = (n: ReactNode): string => {
+    if (typeof n === "string" || typeof n === "number") return String(n);
+    if (Array.isArray(n)) return n.map(walk).join("");
+    if (isValidElement<{ children?: ReactNode }>(n)) return walk(n.props.children);
+    return "";
+  };
+  const text = walk(node).replace(/\s+/g, " ").trim();
+  return text === "" ? undefined : text;
+}

package/src/lib/refs.ts

@@ -0,0 +1,22 @@
+/** Internal (not exported from the package): the kit's ref plumbing. Here, rather than in
+ *  components/field-parts (which re-exports both), since round 0.35: Tooltip needs them,
+ *  and field-parts renders a Tooltip, so importing them from there closed a cycle. */
+import type { Ref, RefCallback } from "react";
+
+/** Point a ref — a callback or an object — at `node`. `undefined` and `null` are no ref. */
+export function assignRef<T>(ref: Ref<T> | undefined, node: T | null): void {
+  if (typeof ref === "function") ref(node);
+  else if (ref) (ref as { current: T | null }).current = node;
+}
+
+/**
+ * One callback ref feeding several — the caller's forwarded `ref` and a field's own
+ * (DUP-11: AmountInput, FormActions, ScrollArea and SearchField each wrote this by hand).
+ * Wrap it in `useCallback` (or `useMemo`) over the same refs where a new callback every
+ * render would detach and re-attach the node.
+ */
+export function mergeRefs<T>(...refs: Array<Ref<T> | undefined>): RefCallback<T> {
+  return (node) => {
+    for (const ref of refs) assignRef(ref, node);
+  };
+}

package/src/lib/safe-storage.ts

@@ -59,3 +59,19 @@ export function writeSessionStored(key: string, value: string | null): void {
     value === null ? storage.removeItem(key) : storage.setItem(key, value),
   );
 }
+
+/**
+ * Every key in `area` that starts with `prefix`, or `[]` where storage refuses — for the
+ * reset of this device's settings, which removes a table's views by their prefix
+ * (docs/settings-harmonization.md §11.4). Package-private, like {@link removeStored}.
+ */
+export function storedKeys(prefix: string, area: "local" | "session" = "local"): string[] {
+  return guarded(area === "session" ? "sessionStorage" : "localStorage", [], (storage) => {
+    const keys: string[] = [];
+    for (let i = 0; i < storage.length; i++) {
+      const key = storage.key(i);
+      if (key !== null && key.startsWith(prefix)) keys.push(key);
+    }
+    return keys;
+  });
+}

package/src/notifications/notification-parts.tsx

@@ -0,0 +1,83 @@
+import { useState } from "react";
+import type { ReactNode } from "react";
+
+import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
+import { hasContent } from "../lib/presence";
+import { AlertBanner } from "../components/alert-banner";
+import { DEFAULT_NOTIFICATIONS_LABELS } from "./notifications-labels";
+import type { NotificationsLabels } from "./notifications-labels";
+
+/**
+ * What the notification cards share: their words, the failure line under a card, and
+ * the overlay a card shows while its write runs.
+ *
+ * @internal Not part of the barrel; the cards are.
+ */
+
+/** The `notifications` namespace: English, then the provider, then the card's prop. */
+export function useNotificationsLabels(prop?: LabelOverride<NotificationsLabels>): NotificationsLabels {
+  return useKitLabels("notifications", DEFAULT_NOTIFICATIONS_LABELS, prop);
+}
+
+/** The app's words for a failure, else `fallback`. */
+export function describeFailure(own: ReactNode | undefined, fallback: ReactNode): ReactNode {
+  return hasContent(own) ? own : fallback;
+}
+
+/** A failure, said under the card's controls — nothing toasts (§4.2). */
+export function FailureLine({ children }: { children: ReactNode }) {
+  if (!hasContent(children)) return null;
+  return (
+    <AlertBanner tone="danger" size="sm" role="alert">
+      {children}
+    </AlertBanner>
+  );
+}
+
+/** What {@link useWriteOverlay} answers. */
+export interface WriteOverlay<V> {
+  has: (key: string) => boolean;
+  get: (key: string) => V | undefined;
+  pending: (key: string) => boolean;
+  set: (key: string, value: V) => void;
+  settle: (key: string, ok: boolean) => void;
+}
+
+/**
+ * Values a card shows while its write runs, over what the server last answered.
+ *
+ * `set(key, value)` shows `value` at once; `settle(key, ok)` drops it again when the
+ * write failed (the server's value comes back) and keeps it when it succeeded, until the
+ * app hands the card a new `source` — the PATCH's answer, or a refetch — which clears
+ * every settled entry, so a card whose app does not update its query on success does not
+ * flick back to the old value in between. `pending(key)` says whether a write for `key`
+ * is still running.
+ *
+ * The reset on a new `source` is React's "adjust state while rendering" pattern, not an
+ * effect: the overlay is gone in the same render that shows the new value.
+ */
+export function useWriteOverlay<V>(source: unknown): WriteOverlay<V> {
+  const [entries, setEntries] = useState<ReadonlyMap<string, { value: V; running: boolean }>>(new Map());
+  const [seen, setSeen] = useState(source);
+  if (seen !== source) {
+    setSeen(source);
+    const kept = new Map([...entries].filter(([, entry]) => entry.running));
+    if (kept.size !== entries.size) setEntries(kept);
+  }
+  return {
+    has: (key: string) => entries.has(key),
+    get: (key: string) => entries.get(key)?.value,
+    pending: (key: string) => entries.get(key)?.running === true,
+    set: (key: string, value: V) =>
+      setEntries((current) => new Map(current).set(key, { value, running: true })),
+    settle: (key: string, ok: boolean) =>
+      setEntries((current) => {
+        const entry = current.get(key);
+        if (!entry) return current;
+        const next = new Map(current);
+        if (ok) next.set(key, { value: entry.value, running: false });
+        else next.delete(key);
+        return next;
+      }),
+  };
+}

package/src/notifications/notification-types-setting.tsx

@@ -0,0 +1,309 @@
+import { useId, useState } from "react";
+import type { ComponentPropsWithRef, ReactNode } from "react";
+
+import type { LabelOverride } from "../i18n/kit-labels";
+import { cn } from "../lib/cn";
+import { hasContent } from "../lib/presence";
+import { Card } from "../components/card";
+import { Select } from "../components/select";
+import { Skeleton } from "../components/skeleton";
+import { Switch } from "../components/switch";
+import { SectionLabel } from "../components/text";
+import { COMMIT_EXCEPT_BILLING } from "../components/write-lock";
+import { CARD_DESCRIPTION_CLASS } from "../settings/settings-card-classes";
+import { SettingsCardTitle } from "../settings/settings-heading";
+import { settle, useMounted } from "../account/account-parts";
+import { describeFailure, FailureLine, useNotificationsLabels, useWriteOverlay } from "./notification-parts";
+import type { WriteOverlay } from "./notification-parts";
+import type { NotificationsLabels } from "./notifications-labels";
+import type {
+  DigestCadence,
+  NotificationSettingsPatch,
+  NotificationSwitches,
+  NotificationTypeEntry,
+  NotificationTypeGroup,
+  NotificationTypesValue,
+} from "./notification-types";
+
+/** Is this a development build? Dead code in a consumer's production bundle; on under
+ *  vitest, where a type the card cannot draw is a bug a test should fail on (as
+ *  `SettingsSection`'s catalogue check). */
+function devChecks(): boolean {
+  return Boolean(import.meta.env?.DEV);
+}
+
+export interface NotificationTypesSettingProps<Id extends string = string>
+  extends Omit<ComponentPropsWithRef<"div">, "children" | "onChange"> {
+  /** The app's words for its types, in its order. Where an app types its ids. */
+  types: readonly NotificationTypeEntry<Id>[];
+  /** The `GET`'s `types` (§3.2); `undefined` while the first load runs. */
+  value: NotificationTypesValue | undefined;
+  /** The settings are loading. */
+  loading?: boolean;
+  /**
+   * Save one change — `PATCH /notifications/settings` with this body: one switch per
+   * call (`{types: {digest: {app: true}}}`), or `{digest_cadence}`. The switch shows its
+   * new state while the call runs and goes back if it rejects; hand the card the
+   * PATCH's answer (or refetch) when it resolves.
+   */
+  onChange: (patch: NotificationSettingsPatch<Id>) => Promise<unknown> | void;
+  /** Headings over the types, in the app's words (keksdose's three). Without them, one
+   *  list in the order of `types`. In development every type the server answered must
+   *  be in one. */
+  groups?: readonly NotificationTypeGroup<Id>[];
+  /** The digest type and the account's cadence: a cadence `Select` under that type
+   *  while it is on. */
+  digest?: { type: Id; cadence: DigestCadence };
+  /** Under a type while it is on — keksdose's low-balance threshold field. */
+  renderExtra?: (id: Id) => ReactNode;
+  /** The account's address is unverified: every e-mail switch says
+   *  `labels.emailUnverified` under it (decision 16). */
+  emailUnverified?: boolean;
+  /** Nothing can be changed (the switches stay readable). */
+  disabled?: boolean;
+  /** The app's own words for a failed save, or `undefined` for the kit's `failed`. */
+  describeError?: (error: unknown) => ReactNode | undefined;
+  labels?: LabelOverride<NotificationsLabels>;
+}
+
+/** One drawn type: the app's words and the server's switches. */
+interface Row<Id extends string> {
+  entry: NotificationTypeEntry<Id>;
+  switches: NotificationSwitches;
+}
+
+/** A switch's key in the write overlay. */
+const switchKey = (id: string, channel: "app" | "email") => `${id}.${channel}`;
+const CADENCE_KEY = "digest_cadence";
+
+/**
+ * What the person hears about, and how (docs/notifications-harmonization.md §2.1–§2.3,
+ * §4.2): one row per type the SERVER answered, the app's words on it, a switch for "in
+ * the app" and "By e-mail" under it where the type offers mail. Where the app has no
+ * "in the app" channel (Kurvenschmiede), the e-mail switch is the row's own, with the
+ * type's label.
+ *
+ * **The server's list is the only list.** The card keeps no defaults and no list of
+ * types: it draws what `value` holds, in the order of `groups`, else of `types`. A type
+ * the app names that the server did not answer is not drawn (kastlan's tenant receives
+ * neither of its types). In development a type the server answered with no entry in
+ * `types`, or in no group when `groups` is given, throws — keksdose's compile-time
+ * `_EVERY_TYPE_IS_GROUPED`, now at run time, since the list is the server's.
+ *
+ * **Each flip saves at once**, one switch per call; the switch shows its new state while
+ * the call runs and goes back if it rejects, with the failure said under the card. The
+ * digest's cadence and the app's extra field (`renderExtra`) show under their type while
+ * it is on.
+ *
+ * Under a write lock the switches are `commit` controls exempt from billing: a lapsed
+ * plan never keeps a person from turning notifications off (billing §12.13).
+ */
+export function NotificationTypesSetting<Id extends string = string>({
+  types,
+  value,
+  loading,
+  onChange,
+  groups,
+  digest,
+  renderExtra,
+  emailUnverified = false,
+  disabled = false,
+  describeError,
+  labels: labelsProp,
+  className,
+  ...rest
+}: NotificationTypesSettingProps<Id>) {
+  const labels = useNotificationsLabels(labelsProp);
+  const overlay = useWriteOverlay<boolean>(value);
+  const cadenceOverlay = useWriteOverlay<DigestCadence>(digest?.cadence);
+  const [failure, setFailure] = useState<ReactNode>(null);
+  const mounted = useMounted();
+  const groupId = useId();
+
+  const answered = value ? Object.keys(value) : [];
+  const entries = new Map(types.map((entry) => [entry.id as string, entry]));
+  if (value && devChecks()) {
+    const unnamed = answered.filter((id) => !entries.has(id));
+    if (unnamed.length) {
+      throw new Error(
+        `NotificationTypesSetting: the server answered ${unnamed.map((id) => `"${id}"`).join(", ")} with no entry in \`types\` — give every type the server can send its words.`,
+      );
+    }
+    if (groups) {
+      const grouped = new Set<string>(groups.flatMap((group) => group.types));
+      const loose = answered.filter((id) => !grouped.has(id));
+      if (loose.length) {
+        throw new Error(
+          `NotificationTypesSetting: ${loose.map((id) => `"${id}"`).join(", ")} is in no group — a type in no group is drawn nowhere, and could not be turned off.`,
+        );
+      }
+    }
+  }
+
+  const rowOf = (id: Id): Row<Id> | null => {
+    const switches = value?.[id];
+    const entry = entries.get(id);
+    if (!switches || !entry || (switches.app === null && switches.email === null)) return null;
+    return { entry, switches };
+  };
+  const rowsOf = (ids: readonly Id[]) => ids.map(rowOf).filter((row): row is Row<Id> => row !== null);
+
+  const shown = (id: string, channel: "app" | "email", server: boolean): boolean => {
+    const key = switchKey(id, channel);
+    return overlay.get(key) ?? server;
+  };
+  /** The row's own switch: `app`, or `email` where the app has no `app` channel. */
+  const rowOn = ({ entry, switches }: Row<Id>) =>
+    switches.app !== null
+      ? shown(entry.id, "app", switches.app)
+      : shown(entry.id, "email", switches.email === true);
+
+  const save = <V,>(key: string, patch: NotificationSettingsPatch<Id>, which: WriteOverlay<V>, next: V) => {
+    if (which.pending(key)) return;
+    setFailure(null);
+    which.set(key, next);
+    settle(() => onChange(patch)).then(
+      () => {
+        if (mounted.current) which.settle(key, true);
+      },
+      (error: unknown) => {
+        if (!mounted.current) return;
+        which.settle(key, false);
+        setFailure(describeFailure(describeError?.(error), labels.failed));
+      },
+    );
+  };
+
+  const flip = (id: Id, channel: "app" | "email", on: boolean) =>
+    save(
+      switchKey(id, channel),
+      { types: { [id]: { [channel]: on } } as NotificationSettingsPatch<Id>["types"] },
+      overlay,
+      on,
+    );
+
+  const cadence = cadenceOverlay.get(CADENCE_KEY) ?? digest?.cadence;
+
+  const unverifiedLine = emailUnverified ? (
+    <span className="block" data-email-unverified="">
+      {labels.emailUnverified}
+    </span>
+  ) : null;
+
+  const renderRow = (row: Row<Id>) => {
+    const { entry, switches } = row;
+    const on = rowOn(row);
+    const emailOnly = switches.app === null;
+    const both = !emailOnly && switches.email !== null;
+    const cadenceSelect =
+      on && digest?.type === entry.id && cadence ? (
+        <Select
+          label={labels.digestCadence}
+          value={cadence}
+          disabled={disabled}
+          commit={COMMIT_EXCEPT_BILLING}
+          onChange={(event) => {
+            const next = event.target.value as DigestCadence;
+            if (next !== cadence) save(CADENCE_KEY, { digest_cadence: next }, cadenceOverlay, next);
+          }}
+          className="max-w-44"
+        >
+          <option value="weekly">{labels.digestWeekly}</option>
+          <option value="monthly">{labels.digestMonthly}</option>
+        </Select>
+      ) : null;
+    const extra = on ? renderExtra?.(entry.id) : null;
+    const description =
+      emailOnly && unverifiedLine ? (
+        <>
+          {entry.description !== undefined && <span className="block">{entry.description}</span>}
+          {unverifiedLine}
+        </>
+      ) : (
+        entry.description
+      );
+    return (
+      <div
+        key={entry.id}
+        data-notification-type={entry.id}
+        // A row with two switches is a group named by its type, so "By e-mail" is heard
+        // with the type it belongs to.
+        role={both ? "group" : undefined}
+        aria-label={both ? entry.label : undefined}
+        className="space-y-2"
+      >
+        <Switch
+          label={entry.label}
+          description={description}
+          checked={on}
+          disabled={disabled}
+          commit={COMMIT_EXCEPT_BILLING}
+          onCheckedChange={(next) => flip(entry.id, emailOnly ? "email" : "app", next)}
+        />
+        {both && (
+          <div className="ps-4">
+            <Switch
+              size="sm"
+              label={labels.byEmail}
+              description={unverifiedLine ?? undefined}
+              checked={shown(entry.id, "email", switches.email === true)}
+              disabled={disabled}
+              commit={COMMIT_EXCEPT_BILLING}
+              onCheckedChange={(next) => flip(entry.id, "email", next)}
+            />
+          </div>
+        )}
+        {(cadenceSelect || hasContent(extra)) && (
+          <div className="ps-4 space-y-2">
+            {cadenceSelect}
+            {extra}
+          </div>
+        )}
+      </div>
+    );
+  };
+
+  let body: ReactNode;
+  if (loading || value === undefined) {
+    body = <Skeleton lines={3} label={labels.typesLoading} />;
+  } else if (groups) {
+    const drawn = groups
+      .map((group) => ({ group, rows: rowsOf(group.types) }))
+      .filter(({ rows }) => rows.length > 0);
+    body =
+      drawn.length === 0 ? (
+        <p className={CARD_DESCRIPTION_CLASS}>{labels.typesEmpty}</p>
+      ) : (
+        drawn.map(({ group, rows }) => {
+          const headingId = `${groupId}-${group.id}`;
+          return (
+            <div key={group.id} role="group" aria-labelledby={headingId} className="space-y-3">
+              <SectionLabel as="div" size="xs" id={headingId}>
+                {group.label}
+              </SectionLabel>
+              {rows.map(renderRow)}
+            </div>
+          );
+        })
+      );
+  } else {
+    const rows = rowsOf(types.map((entry) => entry.id));
+    body =
+      rows.length === 0 ? (
+        <p className={CARD_DESCRIPTION_CLASS}>{labels.typesEmpty}</p>
+      ) : (
+        <div className="space-y-3">{rows.map(renderRow)}</div>
+      );
+  }
+
+  return (
+    <Card {...rest} className={cn("p-4 space-y-3", className)}>
+      <div>
+        <SettingsCardTitle>{labels.typesTitle}</SettingsCardTitle>
+        <div className={CARD_DESCRIPTION_CLASS}>{labels.typesDescription}</div>
+      </div>
+      {body}
+      <FailureLine>{failure}</FailureLine>
+    </Card>
+  );
+}

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;
+}