@eifi1/ui-kit 0.35.0 → 0.37.0

package/src/i18n/locales/zh.ts

@@ -249,6 +249,8 @@ export function uiKitLabelsZh(numberLocale = "zh-CN"): UiKitLabels {
       // Full-width colon, no space after it.
       fieldValue: (field, value) => `${field}：${value}`,
       opensInNewTab: "在新标签页中打开",
+      aboutField: (field) => `关于“${field}”`,
+      help: "帮助",
     },
     dataTable: {
       columns: "列",
@@ -1018,6 +1020,87 @@ export function uiKitLabelsZh(numberLocale = "zh-CN"): UiKitLabels {
       rateLimited,
       failed: "操作未成功，请重试。",
     },
+    // 0.36.0 — docs/notifications-harmonization.md §4.2: the notification cards.
+    notifications: {
+      typesTitle: "通知我以下内容",
+      typesDescription: "选择要接收哪些通知，以及接收方式。",
+      byEmail: "通过电子邮件",
+      emailUnverified: "请先确认您的邮箱地址，才能收到这些邮件。",
+      digestCadence: "频率",
+      digestWeekly: "每周",
+      digestMonthly: "每月",
+      typesLoading: "正在加载通知设置…",
+      typesEmpty: "此账户没有可用的通知。",
+      quietTitle: "免打扰时段",
+      quietDescription: (inbox) =>
+        inbox ? "此时段内不发送推送通知。通知仍会进入您的收件箱。" : "此时段内不发送推送通知。",
+      quietFrom: "从",
+      quietUntil: "到",
+      quietIncomplete: "请同时设置开始和结束时间。两者都设置后，免打扰时段才会生效。",
+      timeZone: "时区",
+      deviceZone: (zone) => `此设备位于 ${zone} 时区。`,
+      useDeviceZone: "使用此时区",
+      regions: {
+        Africa: "非洲",
+        America: "美洲",
+        Antarctica: "南极洲",
+        Arctic: "北极",
+        Asia: "亚洲",
+        Atlantic: "大西洋",
+        Australia: "澳大利亚",
+        Europe: "欧洲",
+        Indian: "印度洋",
+        Pacific: "太平洋",
+      },
+      pushTitle: "推送通知",
+      pushDescription: "在此设备上接收通知，即使应用已关闭。",
+      unsupported: "此浏览器不支持推送通知。",
+      iosInstall: (app) => `在 iPhone 或 iPad 上，请先将 ${app} 添加到主屏幕：iOS 只向已安装的应用发送通知。`,
+      notConfigured: "此服务器尚未设置推送通知。",
+      blocked: "此浏览器的设置已阻止通知。",
+      on: "此设备的通知已开启。",
+      off: "此设备的通知已关闭。",
+      otherAccount: "此浏览器正在接收另一个账户的通知。在此开启，即可接收您当前登录账户的通知。",
+      enable: "开启通知",
+      disable: "关闭",
+      sendTest: "发送测试",
+      enableFailed: "无法开启通知。",
+      noServiceWorker: "无法连接应用的 Service Worker。请重新加载页面后重试。",
+      pushTimeout: "浏览器的推送服务没有响应。请检查网络连接后重试。",
+      testSent: (count) => `测试已发送到 ${n(count)} 台设备`,
+      testNone: "没有设备接收此测试。请先为此设备开启通知。",
+      testFailed: "无法发送测试通知。",
+      explainerTitle: "开启通知？",
+      explainerBody: (app) => `${app} 只会就您选择的内容发送通知，您可以随时关闭。`,
+      explainerHint: "接下来浏览器会请求您的许可。",
+      explainerContinue: "继续",
+      devicesTitle: "通知设备",
+      devicesDescription: "为您的账户接收推送通知的所有设备。请移除不再使用的设备。",
+      devicesLoading: "正在加载设备…",
+      devicesEmpty: "还没有设备接收通知。",
+      unknownDevice: "未知设备",
+      thisDevice: "此设备",
+      added: (date) => `添加于 ${date}`,
+      lastDelivery: (date) => `上次送达：${date}`,
+      noDelivery: "尚未送达",
+      failures: (count) => `连续 ${n(count)} 次送达失败`,
+      remove: "移除",
+      // Starts with `remove`, the button's visible text, for voice control.
+      removeItem: (device) => `移除：${device}`,
+      removePrompt: "停止向此设备发送通知？",
+      unsubscribeTitle: "电子邮件通知",
+      unsubscribeAbout: (type) => `您会收到有关以下内容的邮件：${type}。`,
+      unsubscribeGeneric: "您会收到通知邮件。",
+      stopThese: "停止接收这些邮件",
+      stopAll: (app) => `停止接收来自 ${app} 的所有通知邮件`,
+      stoppedThese: "已完成。您将不再收到这些邮件。",
+      stoppedAll: (app) => `已完成。您将不再收到来自 ${app} 的通知邮件。`,
+      accountMail: "有关您账户的邮件仍会照常发送。",
+      turnBackOn: "您可以随时在“设置”中重新开启。",
+      openSettings: "打开设置",
+      invalidLink: "此链接已失效。您可以改为在“设置”中关闭这些邮件。",
+      failed: "操作未成功，请重试。",
+    },
     sessions: {
       title: "会话",
       description: "在不再使用或不信任的设备上登录过？请在所有设备上退出登录。",
@@ -1521,6 +1604,19 @@ export function uiKitLabelsZh(numberLocale = "zh-CN"): UiKitLabels {
       contrastModes: { system: "跟随系统", standard: "标准", more: "增强" },
       saveFailed: "无法保存到您的账户。此设备上仍然生效。",
     },
+    // 0.36.0 — docs/settings-harmonization.md §11.3: resetting this device's settings, the
+    // last card of "外观".
+    deviceReset: {
+      title: "重置此设备",
+      description: "将此设备的外观，以及表格和面板上次留下的状态，恢复为默认值。您的账户、数据和登录状态不受影响。",
+      action: "重置此设备的设置",
+      confirmTitle: "要重置此设备的设置吗？",
+      confirmBody:
+        "主题、颜色、文字大小、对比度和语言将在此设备上恢复为默认值，表格和面板会像第一次打开时那样显示。如果您的账户设置了语言、文字大小或对比度，此设备会重新沿用这些设置。您的账户和其他设备保持不变。",
+      confirmAction: "重置",
+      done: "此设备的设置已恢复为默认值。",
+      keywords: "重置 默认 设备 恢复 外观 表格 布局",
+    },
     rowActions: {
       actions: "操作",
       actionsFor: (name) => `${name} 的操作`,

package/src/i18n/review.ts

@@ -119,6 +119,7 @@ const operatorSample = [[LEGAL_OPERATOR_SAMPLE]] as const;
  */
 export const KIT_LABEL_SAMPLES: Readonly<Record<string, readonly (readonly unknown[])[]>> = {
   "common.fieldValue": [["{{field}}", "{{value}}"]],
+  "common.aboutField": [["{{field}}"]],
   "dataTable.filterResults": [
     [1, 1],
     [3, 12],
@@ -324,6 +325,18 @@ export const KIT_LABEL_SAMPLES: Readonly<Record<string, readonly (readonly unkno
   "sessions.lastActive": [["{{when}}"]],
   "sessions.ip": [["{{address}}"]],
   "sessions.revokeItem": [["{{device}}"]],
+  "notifications.quietDescription": [[false], [true]],
+  "notifications.deviceZone": [["{{zone}}"]],
+  "notifications.iosInstall": [["{{app}}"]],
+  "notifications.testSent": one,
+  "notifications.explainerBody": [["{{app}}"]],
+  "notifications.added": [["{{date}}"]],
+  "notifications.lastDelivery": [["{{date}}"]],
+  "notifications.failures": one,
+  "notifications.removeItem": [["{{device}}"]],
+  "notifications.unsubscribeAbout": [["{{type}}"]],
+  "notifications.stopAll": [["{{app}}"]],
+  "notifications.stoppedAll": [["{{app}}"]],
   "deleteAccount.afterDays": [[1], [30]],
   "deleteAccount.handOver": [[1], [3]],
   "deleteAccount.lastAdminOf": [["{{companies}}"]],

package/src/i18n/shared-labels.ts

@@ -37,6 +37,8 @@ export const DEFAULT_COMMON_LABELS: CommonLabels = {
   fieldValue: (field, value) => `${field}: ${value}`,
   dismiss: "Dismiss",
   opensInNewTab: "opens in a new tab",
+  aboutField: (field) => `About “${field}”`,
+  help: "Help",
 };
 
 export const DEFAULT_DATE_PICKER_LABELS: DatePickerLabels = {

package/src/index.ts

@@ -856,6 +856,13 @@ export type { PlanLimitToastOptions } from "./billing/plan-limit-toast";
 // come with `./shell` above (also `@eifi1/ui-kit/shell`).
 export { DEFAULT_SETTINGS_LABELS, useSettingsLabels } from "./settings/settings-labels";
 export type { SettingsLabels, SettingsGroupLabels, SettingsCoreGroup } from "./settings/settings-labels";
+// 0.36.0 (§11): "Reset this device's settings" — the registry the kit's stores, provider
+// and shell join on their own and an app adds its own device keys to, and the card, the
+// appearance group's last.
+export { registerDeviceSetting, deviceSettings, resetDeviceSettings } from "./lib/device-settings";
+export type { DeviceSetting, DeviceSettingKind } from "./lib/device-settings";
+export { DeviceResetSetting, DEVICE_RESET_ANCHOR, DEFAULT_DEVICE_RESET_LABELS } from "./settings/device-reset-setting";
+export type { DeviceResetSettingProps, DeviceResetLabels } from "./settings/device-reset-setting";
 // The language follows the account (§6.2); since 0.32 so do the text size and the
 // contrast (useAccountAppearance below, docs/text-size-harmonization.md §6).
 export { useAccountLanguage, resolveAccountLanguage, matchOfferedLanguage } from "./settings/use-account-language";
@@ -877,6 +884,49 @@ export type {
   AccountAppearance,
 } from "./settings/use-account-appearance";
 
+// ── notifications ────────────────────────────────────────────────────────────
+// 0.36.0 (docs/notifications-harmonization.md §4.2): the notification cards — the types
+// the server answers (the kit keeps no list of its own), quiet hours with the zone picker,
+// this device's push on its hook, the device list — and the signed-out unsubscribe page.
+// Each card takes the app's request functions; the kit makes no request itself.
+export { DEFAULT_NOTIFICATIONS_LABELS } from "./notifications/notifications-labels";
+export type { NotificationsLabels, NotificationRegionLabels } from "./notifications/notifications-labels";
+export type {
+  DigestCadence,
+  NotificationSwitches,
+  NotificationTypesValue,
+  NotificationTypeEntry,
+  NotificationTypeGroup,
+  NotificationSettingsPatch,
+  PushDeviceItem,
+} from "./notifications/notification-types";
+export { NotificationTypesSetting } from "./notifications/notification-types-setting";
+export type { NotificationTypesSettingProps } from "./notifications/notification-types-setting";
+export { QuietHoursSetting } from "./notifications/quiet-hours-setting";
+export type { QuietHoursSettingProps } from "./notifications/quiet-hours-setting";
+export { TimeZoneSelect, timeZoneOptions, deviceTimeZone } from "./notifications/time-zone-select";
+export type { TimeZoneSelectProps } from "./notifications/time-zone-select";
+export {
+  usePushDevice,
+  PUSH_SUBSCRIPTION_CHANGED,
+  notifyPushSubscriptionChanged,
+  pushSupported,
+  PushDeviceError,
+} from "./notifications/use-push-device";
+export type {
+  PushDevice,
+  UsePushDeviceOptions,
+  PushSubscriptionInput,
+  PushPermission,
+  PushDeviceErrorCode,
+} from "./notifications/use-push-device";
+export { PushDeviceSetting } from "./notifications/push-device-setting";
+export type { PushDeviceSettingProps, PushDeviceAction } from "./notifications/push-device-setting";
+export { PushDevicesSetting, describeUserAgent } from "./notifications/push-devices-setting";
+export type { PushDevicesSettingProps } from "./notifications/push-devices-setting";
+export { UnsubscribePanel, unsubscribeTokenType } from "./notifications/unsubscribe-panel";
+export type { UnsubscribePanelProps } from "./notifications/unsubscribe-panel";
+
 // ── landing ──────────────────────────────────────────────────────────────────
 // 0.31.0 (docs/landing-demo-harmonization.md): the public landing page. Its router-aware parts — the header and the resume (RootEntry,
 // RedirectIfAuthed, the last-visited page) — come with `./shell` above.

package/src/lib/device-settings.ts

@@ -0,0 +1,146 @@
+import { readSessionStored, readStored, removeStored, storedKeys, writeSessionStored } from "./safe-storage";
+
+/**
+ * What this device keeps of how it shows the app, and the one action that puts it all
+ * back: "Reset this device's settings" (docs/settings-harmonization.md §11).
+ *
+ * A registry, because no one part knows every key. The kit's own stores and components
+ * join it themselves — the theme, palette, text-size and contrast stores when they are
+ * created, `UiKitProvider` (the prefix its tables keep their views under) and `AppShell`
+ * (the sidebar's folded state) while they are mounted — and an app adds its own keys
+ * beside the store or accessor that owns each (keksdose's date format, kastlan's
+ * language, Kurvenschmiede's curve channels). {@link resetDeviceSettings} then clears
+ * exactly what joined, and nothing else: the sign-in, the session, what waits to be sent
+ * and the account never join (§11.2 decision 2), so a key nobody registered survives.
+ *
+ * No React and no router: a store joins at module scope, when it is created. Here in
+ * `src/lib` beside `safe-storage.ts`, which the stores and the shell already import, so
+ * `src/theme` and `src/shell` do not import `src/settings`. One module instance, one
+ * module-level list.
+ */
+
+/** What a reset of this device's settings clears (§11.2 decision 1): how the app looks
+ *  here, and how its tables and panels were left. An app's own list may add a third kind
+ *  of its own for what never goes (Kurvenschmiede's "never"). */
+export type DeviceSettingKind = "appearance" | "view";
+
+export interface DeviceSetting {
+  /** The storage key; with `prefix`, every key that starts with it. */
+  key: string;
+  /** `true`: `key` is a prefix (a table's views, keksdose's display currency per budget).
+   *  It matches by `startsWith`: `budget.displayCurrency.` does not take the legacy
+   *  `budget.displayCurrency`. */
+  prefix?: boolean;
+  /** Default `"local"`. */
+  storage?: "local" | "session";
+  kind: DeviceSettingKind;
+  /**
+   * Puts the live value back to its default through the store's own setter, the one its
+   * control calls, so whatever that setter also does still happens — never
+   * `setState(getInitialState())`, which skips it. REQUIRED for anything held in memory:
+   * every persisted zustand store (removing its key alone, it writes its value back on its
+   * next change), a mounted component's state. With `reset` the key is left to it (a
+   * persisted store writes its default itself); without, the key, or every key under the
+   * prefix, is removed — for what is read where it is next used (a table at its mount, a
+   * plain accessor).
+   */
+  reset?: () => void;
+}
+
+/** Whoever joined one key, in join order; the last one's entry is the key's entry. */
+type Holders = { entry: DeviceSetting }[];
+
+/** One slot per key and storage area, in the order each was first joined. */
+const slots = new Map<string, Holders>();
+
+const areaOf = (entry: DeviceSetting): "local" | "session" => (entry.storage === "session" ? "session" : "local");
+const slotOf = (entry: DeviceSetting) => `${areaOf(entry)}:${entry.key}`;
+
+/**
+ * Join the registry; answers the leave function. A store joins once, at creation, and
+ * never leaves; a component joins while mounted and leaves in its effect's cleanup.
+ *
+ * **One entry per key** (and storage area): joining a key again replaces its entry and
+ * adds a holder, and a leave drops its holder — the entry goes with the last one, and
+ * until then the latest remaining holder's entry is the key's. So a module evaluated twice
+ * (a test, a hot reload) does not reset twice, and two nested providers with one prefix
+ * keep their entry until the outer one unmounts.
+ */
+export function registerDeviceSetting(entry: DeviceSetting): () => void {
+  const slot = slotOf(entry);
+  const holder = { entry: { ...entry } };
+  const holders = slots.get(slot);
+  if (holders) holders.push(holder);
+  else slots.set(slot, [holder]);
+  let left = false;
+  return () => {
+    if (left) return;
+    left = true;
+    // A holder that has not left is in its slot: only its own leave takes it out, and a
+    // slot goes only once it is empty.
+    const current = slots.get(slot) as Holders;
+    current.splice(current.indexOf(holder), 1);
+    if (current.length === 0) slots.delete(slot);
+  };
+}
+
+/** Every entry, in join order: for an app's own test (Kurvenschmiede holds it to its
+ *  `STORAGE` list) or its privacy page. */
+export function deviceSettings(): readonly DeviceSetting[] {
+  return [...slots.values()].map((holders) => holders[holders.length - 1].entry);
+}
+
+/** Is this a development build? `import.meta.env` is a Vite injection, absent under Node. */
+function devBuild(): boolean {
+  return Boolean(import.meta.env?.DEV);
+}
+
+/** The keys an entry covers now: a prefix's keys found under it, else its own key. */
+function keysOf(entry: DeviceSetting): string[] {
+  return entry.prefix ? storedKeys(entry.key, areaOf(entry)) : [entry.key];
+}
+
+/** Remove what `entry` covers; answers the keys that were there. */
+function removeEntry(entry: DeviceSetting): string[] {
+  const session = areaOf(entry) === "session";
+  const present = keysOf(entry).filter((key) => (session ? readSessionStored(key) : readStored(key)) !== null);
+  for (const key of present) {
+    if (session) writeSessionStored(key, null);
+    else removeStored(key);
+  }
+  return present;
+}
+
+/**
+ * Reset every entry, at once; answers the keys it reset or removed, prefixes expanded.
+ *
+ * Synchronous, in two passes: first every `reset`, in join order, so each live store puts
+ * its value back (and writes its default); then the keys of the entries without one. A
+ * `reset` that throws is caught (`console.error` in development), its key is removed
+ * instead, and the rest still run. It never reloads, navigates or sends a request, and
+ * never touches a key nobody registered. Where the browser refuses storage, the live
+ * values still reset and nothing throws.
+ *
+ * The answer: an entry with a `reset` lists its key (a prefix, the keys found under it);
+ * an entry without lists the keys it removed, those that were there.
+ */
+export function resetDeviceSettings(): string[] {
+  const keys: string[] = [];
+  const remove: DeviceSetting[] = [];
+  for (const entry of deviceSettings()) {
+    if (!entry.reset) {
+      remove.push(entry);
+      continue;
+    }
+    const covered = keysOf(entry);
+    try {
+      entry.reset();
+      keys.push(...covered);
+    } catch (error) {
+      if (devBuild()) console.error(`resetDeviceSettings: the reset of "${entry.key}" threw; its key is removed instead.`, error);
+      remove.push(entry);
+    }
+  }
+  for (const entry of remove) keys.push(...removeEntry(entry));
+  return [...new Set(keys)];
+}

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/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;
+      }),
+  };
+}