@eifi1/ui-kit 0.45.0 → 0.46.0

package/src/notifications/notification-inbox.tsx

@@ -0,0 +1,304 @@
+import { useEffect, useId, useRef, useState } from "react";
+import type { ComponentPropsWithRef, KeyboardEvent, ReactNode } from "react";
+import { Bell, CheckCheck, Trash2 } from "lucide-react";
+import type { LucideIcon } from "lucide-react";
+
+import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
+import { DEFAULT_COMMON_LABELS } from "../i18n/shared-labels";
+import { cn } from "../lib/cn";
+import { useKitFormat } from "../lib/format";
+import { Button } from "../components/button";
+import { Card } from "../components/card";
+import { EmptyState } from "../components/empty-state";
+import { IconButton } from "../components/icon-button";
+import { List, ListItem } from "../components/list";
+import { Skeleton } from "../components/skeleton";
+import { COMMIT_EXCEPT_BILLING } from "../components/write-lock";
+import { SettingsCardTitle } from "../settings/settings-heading";
+import { settle, useMounted } from "../account/account-parts";
+import { describeFailure, FailureLine, useNotificationsLabels } from "./notification-parts";
+import type { NotificationsLabels } from "./notifications-labels";
+
+/**
+ * One inbox row as `GET /notifications/inbox` answers it (server-kit `InboxItem`, §3.7):
+ * the title and body already in the recipient's language.
+ */
+export interface NotificationInboxItem<Id extends string | number = string | number> {
+  id: Id;
+  /** The type id, for the row's icon. */
+  notification_type: string;
+  title: string;
+  body: string;
+  /** A path in the app, an absolute URL, or `null` (nothing to open). */
+  url: string | null;
+  /** ISO date-time. */
+  created_at: string;
+  /** ISO date-time, or `null` while unread. */
+  read_at: string | null;
+  /** 0.46 (server-kit 0.16 `InboxItem.company`): the company the row is about, named on
+   *  the row — kastlan's inbox holds every company's rows. */
+  company?: string | null;
+}
+
+export interface NotificationInboxProps<Id extends string | number = string | number>
+  extends Omit<ComponentPropsWithRef<"div">, "children" | "title"> {
+  /** The rows, newest first; `undefined` while the first page loads. */
+  items: readonly NotificationInboxItem<Id>[] | undefined;
+  /** Every unread row of the account (`unread_count`), not only this page's. */
+  unreadCount: number;
+  loading?: boolean;
+  /** `POST /notifications/inbox/read {ids}` — these rows, or `null` for all. */
+  onMarkRead: (ids: Id[] | null) => Promise<unknown> | void;
+  /** `DELETE /notifications/inbox`. Asked first, in the header. */
+  onClear: () => Promise<unknown> | void;
+  /**
+   * Open a row: the kit marks it read first, then calls this, and the app routes to
+   * `item.url` (kastlan switches the acting company first). Every row is a button then.
+   * Left out, a row with a `url` is a real link — an in-app path through the provider's
+   * router link, an absolute URL in a new tab — that marks itself read on a click or a
+   * middle click (keksdose #451), and a row without one marks itself read.
+   */
+  onOpen?: (item: NotificationInboxItem<Id>) => void;
+  /** The row's glyph for a type — the app's map (keksdose's `TYPE_ICONS`). `undefined`,
+   *  or a type it does not know (a retired one), is the `Bell`. */
+  icon?: (type: string) => LucideIcon | undefined;
+  /** More rows than shown: a "Show more" row calls `onLoadMore` (the API pages by
+   *  `offset`). */
+  hasMore?: boolean;
+  onLoadMore?: () => void;
+  /** The next page is loading. */
+  loadingMore?: boolean;
+  /** A row's time. Default: the provider's locale and `timeZone`, date and time. */
+  formatDate?: (iso: string) => string;
+  /** The heading. Default `labels.inboxTitle` ("Inbox"). */
+  title?: ReactNode;
+  /** The app's own words for a failed request, or `undefined` for the kit's `failed`. */
+  describeError?: (error: unknown) => ReactNode | undefined;
+  labels?: LabelOverride<NotificationsLabels>;
+}
+
+/**
+ * The in-app inbox (0.46, docs/notifications-harmonization.md §10.1), keksdose's list
+ * lifted: newest first, an icon per type (`Bell` for one the app does not map), the
+ * title and two lines of body, the time, and — kastlan — the company the row is about.
+ * Unread rows are bold with a dot. Props only: the app keeps the data (poll the badge
+ * every {@link INBOX_BADGE_INTERVAL}, invalidate on its worker's push message).
+ *
+ * - **Opening a row marks it read** (see `onOpen`).
+ * - **"Mark all as read"** while anything is unread; **"Clear all"** asks first, in the
+ *   header — no `ConfirmProvider` needed — with focus on Cancel.
+ * - **"Show more"** with `hasMore`; the list scrolls inside a box of at most
+ *   `min(24rem, 70vh)`, so it never pushes the settings below it off the page.
+ *
+ * Under a write lock the header's actions are `commit` controls exempt from billing.
+ */
+export function NotificationInbox<Id extends string | number = string | number>({
+  items,
+  unreadCount,
+  loading,
+  onMarkRead,
+  onClear,
+  onOpen,
+  icon,
+  hasMore = false,
+  onLoadMore,
+  loadingMore = false,
+  formatDate: formatDateProp,
+  title,
+  describeError,
+  labels: labelsProp,
+  className,
+  ...rest
+}: NotificationInboxProps<Id>) {
+  const labels = useNotificationsLabels(labelsProp);
+  const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
+  const { formatDate } = useKitFormat();
+  const [asking, setAsking] = useState(false);
+  const [busy, setBusy] = useState<"read" | "clear" | null>(null);
+  const [failure, setFailure] = useState<ReactNode>(null);
+  const mounted = useMounted();
+  const headingId = useId();
+  const cancelRef = useRef<HTMLButtonElement>(null);
+  const clearRef = useRef<HTMLButtonElement>(null);
+  const [returning, setReturning] = useState(false);
+  useEffect(() => {
+    if (asking) cancelRef.current?.focus();
+    else if (returning) clearRef.current?.focus();
+  }, [asking, returning]);
+
+  const timeOf = (iso: string) => (formatDateProp ? formatDateProp(iso) : formatDate(iso, "dateTime"));
+  const iconOf = (type: string): LucideIcon => icon?.(type) ?? Bell;
+
+  const run = (which: "read" | "clear", call: () => unknown, after?: () => void) => {
+    setBusy(which);
+    setFailure(null);
+    settle(call).then(
+      () => {
+        if (!mounted.current) return;
+        setBusy(null);
+        after?.();
+      },
+      (error: unknown) => {
+        if (!mounted.current) return;
+        setBusy(null);
+        setFailure(describeFailure(describeError?.(error), labels.failed));
+      },
+    );
+  };
+
+  /** Mark one row read; a failure is said under the list, the row stays as it is. */
+  const markOne = (item: NotificationInboxItem<Id>) => {
+    if (item.read_at !== null) return;
+    settle(() => onMarkRead([item.id])).catch((error: unknown) => {
+      if (mounted.current) setFailure(describeFailure(describeError?.(error), labels.failed));
+    });
+  };
+
+  const leave = () => {
+    setReturning(true);
+    setAsking(false);
+  };
+  const escapeLeaves = (event: KeyboardEvent<HTMLButtonElement>) => {
+    if (event.key === "Escape") {
+      event.preventDefault();
+      event.stopPropagation();
+      leave();
+    }
+  };
+
+  const count = items?.length ?? 0;
+
+  const header = asking ? (
+    <div className="space-y-2 border-b border-subtle px-3 py-2" data-inbox-confirm="">
+      <p role="alert" className="text-sm">
+        {labels.clearPrompt}
+      </p>
+      <div className="flex flex-wrap gap-2">
+        <Button
+          type="button"
+          size="sm"
+          variant="danger"
+          commit={COMMIT_EXCEPT_BILLING}
+          pending={busy === "clear"}
+          onClick={() => run("clear", onClear, () => setAsking(false))}
+          onKeyDown={escapeLeaves}
+        >
+          {labels.clearAll}
+        </Button>
+        <Button ref={cancelRef} type="button" size="sm" variant="ghost" onClick={leave} onKeyDown={escapeLeaves}>
+          {common.cancel}
+        </Button>
+      </div>
+    </div>
+  ) : (
+    <div className="flex items-center justify-between gap-2 border-b border-subtle px-3 py-2">
+      <SettingsCardTitle id={headingId}>{title ?? labels.inboxTitle}</SettingsCardTitle>
+      <div className="flex items-center gap-0.5">
+        <IconButton
+          type="button"
+          size="xs"
+          tone="muted"
+          commit={COMMIT_EXCEPT_BILLING}
+          onClick={() => run("read", () => onMarkRead(null))}
+          disabled={unreadCount === 0 || busy !== null}
+          label={labels.markAllRead}
+        >
+          <CheckCheck />
+        </IconButton>
+        <IconButton
+          ref={clearRef}
+          type="button"
+          size="xs"
+          tone="danger"
+          commit={COMMIT_EXCEPT_BILLING}
+          onClick={() => {
+            setReturning(false);
+            setAsking(true);
+          }}
+          disabled={count === 0 || busy !== null}
+          label={labels.clearAll}
+        >
+          <Trash2 />
+        </IconButton>
+      </div>
+    </div>
+  );
+
+  let body: ReactNode;
+  if (loading || items === undefined) {
+    body = <Skeleton lines={3} label={labels.inboxLoading} className="p-3" />;
+  } else if (items.length === 0) {
+    body = <EmptyState variant="inline" title={labels.inboxEmpty} className="px-3 py-2" />;
+  } else {
+    body = (
+      // Named by the heading — except while "Clear all" asks, when the heading is away.
+      <List className="p-1" aria-labelledby={asking ? undefined : headingId} aria-label={asking ? labels.inboxTitle : undefined}>
+        {items.map((item) => {
+          const row = {
+            title: item.title,
+            subtitle: item.body,
+            subtitleLines: 2 as const,
+            overline: item.company ?? undefined,
+            meta: timeOf(item.created_at),
+            icon: iconOf(item.notification_type),
+            unread: item.read_at === null,
+            align: "start" as const,
+          };
+          if (onOpen) {
+            return (
+              <ListItem
+                key={item.id}
+                {...row}
+                data-inbox-item={String(item.id)}
+                onClick={() => {
+                  markOne(item);
+                  onOpen(item);
+                }}
+              />
+            );
+          }
+          if (!item.url) {
+            return <ListItem key={item.id} {...row} data-inbox-item={String(item.id)} onClick={() => markOne(item)} />;
+          }
+          // A real link, so a middle click opens a background tab; a middle click fires no
+          // `click`, hence `onAuxClick` (keksdose #451).
+          return (
+            <ListItem
+              key={item.id}
+              {...row}
+              data-inbox-item={String(item.id)}
+              href={item.url}
+              external={!item.url.startsWith("/")}
+              onClick={() => markOne(item)}
+              onAuxClick={(event) => {
+                if (event.button === 1) markOne(item);
+              }}
+            />
+          );
+        })}
+        {hasMore && onLoadMore && (
+          <li className="px-2 py-1">
+            <Button type="button" size="sm" variant="ghost" pending={loadingMore} onClick={onLoadMore} className="w-full">
+              {labels.showMore}
+            </Button>
+          </li>
+        )}
+      </List>
+    );
+  }
+
+  return (
+    <Card {...rest} className={cn("overflow-hidden p-0", className)}>
+      {header}
+      <div className="max-h-[min(24rem,70vh)] overflow-y-auto overscroll-contain">{body}</div>
+      {failure !== null && (
+        <div className="px-3 pb-3">
+          <FailureLine>{failure}</FailureLine>
+        </div>
+      )}
+    </Card>
+  );
+}
+
+/** How often an app polls the unread count for the badge (keksdose's 60 s, `limit:1`). */
+export const INBOX_BADGE_INTERVAL = 60_000;

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

@@ -10,6 +10,7 @@ import { Skeleton } from "../components/skeleton";
 import { Switch } from "../components/switch";
 import { SectionLabel } from "../components/text";
 import { COMMIT_EXCEPT_BILLING } from "../components/write-lock";
+import { usePhoneLayout } from "../hooks/use-breakpoint";
 import { CARD_DESCRIPTION_CLASS } from "../settings/settings-card-classes";
 import { SettingsCardTitle } from "../settings/settings-heading";
 import { settle, useMounted } from "../account/account-parts";
@@ -18,6 +19,7 @@ import type { WriteOverlay } from "./notification-parts";
 import type { NotificationsLabels } from "./notifications-labels";
 import type {
   DigestCadence,
+  NotificationChannel,
   NotificationSettingsPatch,
   NotificationSwitches,
   NotificationTypeEntry,
@@ -73,15 +75,33 @@ interface Row<Id extends string> {
 }
 
 /** A switch's key in the write overlay. */
-const switchKey = (id: string, channel: "app" | "email") => `${id}.${channel}`;
+const switchKey = (id: string, channel: NotificationChannel) => `${id}.${channel}`;
 const CADENCE_KEY = "digest_cadence";
 
+/** The grid of a several-channel row on a wide screen: the type's words, then one narrow
+ *  column per channel drawn. Literal classes, so Tailwind's scan finds them. */
+const COLUMN_GRID: Record<number, string> = {
+  1: "grid-cols-[minmax(0,1fr)_4.5rem]",
+  2: "grid-cols-[minmax(0,1fr)_repeat(2,4.5rem)]",
+  3: "grid-cols-[minmax(0,1fr)_repeat(3,4.5rem)]",
+};
+
+/** The channels in the card's column order (§10.2). */
+const CHANNELS: readonly NotificationChannel[] = ["app", "push", "email"];
+
+/** The channels a type offers: every one the server did not answer `null` (or leave out,
+ *  as `push` before server-kit 0.16). */
+const channelsOf = (switches: NotificationSwitches): NotificationChannel[] =>
+  CHANNELS.filter((channel) => switches[channel] !== null && switches[channel] !== undefined);
+
 /**
  * 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.
+ * §4.2, §10.2): one row per type the SERVER answered, the app's words on it, and a switch
+ * per channel the type offers — "In the app", "Push", "E-mail". On a wide screen they are
+ * narrow columns under those headings; on a phone they stack under the type's label. A
+ * channel the server answers `null` is not drawn (kastlan and KS offer no push; KS no
+ * "in the app"), and a row with one channel keeps a single switch named by the type
+ * (Kurvenschmiede's e-mail-only rows).
  *
  * **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
@@ -140,23 +160,24 @@ export function NotificationTypesSetting<Id extends string = string>({
     }
   }
 
+  const phone = usePhoneLayout();
   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;
+    if (!switches || !entry || channelsOf(switches).length === 0) 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 shown = (id: string, channel: NotificationChannel, 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 channelOn = ({ entry, switches }: Row<Id>, channel: NotificationChannel) =>
+    shown(entry.id, channel, switches[channel] === true);
+  /** The type reaches the person at all: some channel is on (the cadence and the app's
+   *  extra show then). */
+  const rowOn = (row: Row<Id>) => channelsOf(row.switches).some((channel) => channelOn(row, channel));
 
   const save = <V,>(key: string, patch: NotificationSettingsPatch<Id>, which: WriteOverlay<V>, next: V) => {
     if (which.pending(key)) return;
@@ -174,7 +195,7 @@ export function NotificationTypesSetting<Id extends string = string>({
     );
   };
 
-  const flip = (id: Id, channel: "app" | "email", on: boolean) =>
+  const flip = (id: Id, channel: NotificationChannel, on: boolean) =>
     save(
       switchKey(id, channel),
       { types: { [id]: { [channel]: on } } as NotificationSettingsPatch<Id>["types"] },
@@ -190,11 +211,33 @@ export function NotificationTypesSetting<Id extends string = string>({
     </span>
   ) : null;
 
+  const channelLabel: Record<NotificationChannel, string> = {
+    app: labels.channelApp,
+    push: labels.channelPush,
+    email: labels.channelEmail,
+  };
+  /** The columns on a wide screen: every channel some several-channel row offers. */
+  const drawnRows = value && !loading ? rowsOf(groups ? groups.flatMap((group) => group.types) : types.map((entry) => entry.id)) : [];
+  const multi = drawnRows.filter((row) => channelsOf(row.switches).length > 1);
+  const columns = CHANNELS.filter((channel) => multi.some((row) => channelsOf(row.switches).includes(channel)));
+  const columnHeadings =
+    !phone && columns.length > 0 ? (
+      // The switches carry the channel's name themselves; the headings are for the eye.
+      <div aria-hidden className={cn("grid gap-x-2", COLUMN_GRID[columns.length])} data-channel-headings="">
+        <span />
+        {columns.map((channel) => (
+          <span key={channel} className="text-center text-caption font-medium text-muted">
+            {channelLabel[channel]}
+          </span>
+        ))}
+      </div>
+    ) : 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 offered = channelsOf(switches);
+    const single = offered.length === 1 ? offered[0] : null;
     const cadenceSelect =
       on && digest?.type === entry.id && cadence ? (
         <Select
@@ -213,52 +256,99 @@ export function NotificationTypesSetting<Id extends string = string>({
         </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
+    const below =
+      cadenceSelect || hasContent(extra) ? (
+        <div className="ps-4 space-y-2">
+          {cadenceSelect}
+          {extra}
+        </div>
+      ) : null;
+
+    // One channel: today's single switch, named by the type (KS's e-mail-only rows).
+    if (single) {
+      const description =
+        single === "email" && unverifiedLine ? (
+          <>
+            {entry.description !== undefined && <span className="block">{entry.description}</span>}
+            {unverifiedLine}
+          </>
+        ) : (
+          entry.description
+        );
+      return (
+        <div key={entry.id} data-notification-type={entry.id} data-channels={single} className="space-y-2">
+          <Switch
+            label={entry.label}
+            description={description}
+            checked={channelOn(row, single)}
+            disabled={disabled}
+            commit={COMMIT_EXCEPT_BILLING}
+            onCheckedChange={(next) => flip(entry.id, single, next)}
+          />
+          {below}
+        </div>
       );
+    }
+
+    // Several channels: a group named by its type, a switch per channel — columns on a
+    // wide screen (the headings above the list name them), stacked on a phone.
+    const labelId = `${groupId}-type-${entry.id}`;
+    const unverifiedId = `${groupId}-unverified-${entry.id}`;
+    const channelSwitch = (channel: NotificationChannel) => (
+      <Switch
+        key={channel}
+        size="sm"
+        label={phone ? channelLabel[channel] : undefined}
+        aria-label={phone ? undefined : channelLabel[channel]}
+        description={phone && channel === "email" ? (unverifiedLine ?? undefined) : undefined}
+        aria-describedby={!phone && channel === "email" && unverifiedLine ? unverifiedId : undefined}
+        checked={channelOn(row, channel)}
+        disabled={disabled}
+        commit={COMMIT_EXCEPT_BILLING}
+        onCheckedChange={(next) => flip(entry.id, channel, next)}
+        data-channel={channel}
+      />
+    );
+    const text = (
+      <div className="min-w-0">
+        <div id={labelId} className="text-sm font-medium text-primary">
+          {entry.label}
+        </div>
+        {(entry.description !== undefined || (!phone && offered.includes("email") && unverifiedLine)) && (
+          <div className={CARD_DESCRIPTION_CLASS}>
+            {entry.description !== undefined && <span className="block">{entry.description}</span>}
+            {!phone && offered.includes("email") && <span id={unverifiedId}>{unverifiedLine}</span>}
+          </div>
+        )}
+      </div>
+    );
     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}
+        data-channels={offered.join(" ")}
+        role="group"
+        aria-labelledby={labelId}
         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}
+        {phone ? (
+          <>
+            {text}
+            <div className="ps-4 space-y-2" data-stacked="">
+              {offered.map(channelSwitch)}
+            </div>
+          </>
+        ) : (
+          <div className={cn("grid items-start gap-x-2", COLUMN_GRID[columns.length])}>
+            {text}
+            {columns.map((channel) => (
+              <div key={channel} className="flex justify-center pt-0.5">
+                {offered.includes(channel) ? channelSwitch(channel) : null}
+              </div>
+            ))}
           </div>
         )}
+        {below}
       </div>
     );
   };
@@ -274,7 +364,9 @@ export function NotificationTypesSetting<Id extends string = string>({
       drawn.length === 0 ? (
         <p className={CARD_DESCRIPTION_CLASS}>{labels.typesEmpty}</p>
       ) : (
-        drawn.map(({ group, rows }) => {
+        <>
+        {columnHeadings}
+        {drawn.map(({ group, rows }) => {
           const headingId = `${groupId}-${group.id}`;
           return (
             <div key={group.id} role="group" aria-labelledby={headingId} className="space-y-3">
@@ -284,7 +376,8 @@ export function NotificationTypesSetting<Id extends string = string>({
               {rows.map(renderRow)}
             </div>
           );
-        })
+        })}
+        </>
       );
   } else {
     const rows = rowsOf(types.map((entry) => entry.id));
@@ -292,7 +385,10 @@ export function NotificationTypesSetting<Id extends string = string>({
       rows.length === 0 ? (
         <p className={CARD_DESCRIPTION_CLASS}>{labels.typesEmpty}</p>
       ) : (
-        <div className="space-y-3">{rows.map(renderRow)}</div>
+        <div className="space-y-3">
+          {columnHeadings}
+          {rows.map(renderRow)}
+        </div>
       );
   }
 

package/src/notifications/notification-types.ts

@@ -13,16 +13,23 @@ import type { ReactNode } from "react";
 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.
+ * One type's switches in the `GET` (§3.2; §10.2: one per channel). `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, push: null, email: true}`), `push` in
+ * an app with no push (server-kit `NotificationTypes(..., push_channel=False)`: kastlan,
+ * KS). An unset switch already reads as its default — the server fills it in.
  */
 export interface NotificationSwitches {
   app: boolean | null;
+  /** 0.46 (§10.2): push, independent of `app`. Left out by a server before
+   *  server-kit 0.16, which reads as `null` (not offered). */
+  push?: boolean | null;
   email: boolean | null;
 }
 
+/** A channel a type may offer (§10.2), in the order the types card draws them. */
+export type NotificationChannel = "app" | "push" | "email";
+
 /** The `GET`'s `types`: every type the account can receive, in the registry's order. */
 export type NotificationTypesValue = Readonly<Record<string, NotificationSwitches>>;
 
@@ -51,16 +58,18 @@ export interface NotificationTypeGroup<Id extends string = string> {
 
 /**
  * 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`
+ * type's `null` puts 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}`.
+ * true}}}`), or `{digest_cadence}`; quiet hours send a time. No zone: it is the
+ * account's, automatic only (§10.3, amended 2026-10-20).
  */
 export interface NotificationSettingsPatch<Id extends string = string> {
-  types?: Partial<Record<Id, { app?: boolean; email?: boolean } | null>>;
+  types?: Partial<Record<Id, { app?: boolean; push?: boolean; email?: boolean } | null>>;
   digest_cadence?: DigestCadence;
   quiet_hours_start?: string | null;
   quiet_hours_end?: string | null;
+  /** @deprecated 0.46 — the zone is the account's, automatic only (§10.3), and server-kit 0.16 refuses it here;
+   *  removed in 0.47. No kit card sends it. */
   timezone?: string;
 }
 
@@ -77,4 +86,7 @@ export interface PushDeviceItem<Id extends string | number = string> {
   last_success_at: string | null;
   /** Failed deliveries in a row; the server removes the device at 10. */
   failure_count: number;
+  /** 0.46 (§10.2): the type ids this device mutes — a device can mute types, never add
+   *  them. Left out by a server before server-kit 0.16 (none muted). */
+  muted_types?: string[];
 }