@eifi1/ui-kit 0.45.0 → 0.46.1

package/src/index.ts

@@ -408,6 +408,8 @@ export * from "./components/form-actions";
 // (docs/billing-harmonization.md §12.36): the kinds, the holds, `CommitScope`,
 // `COMMIT_EXCEPT_BILLING` and the pure `writeLockFor`.
 export { WriteLockProvider, useWriteLock, writeLockFor, COMMIT_EXCEPT_BILLING, DEFAULT_WRITE_LOCK_LABELS } from "./components/write-lock";
+// 0.46 (kastlan K4): the offline lock kind, its scope and its source.
+export { OFFLINE_LOCK, COMMIT_EXCEPT_OFFLINE, useOfflineWriteLock } from "./components/write-lock";
 export type { WriteLock, WriteLockLabels, WriteLockProviderProps, WriteLockKind, WriteLockHold, CommitScope } from "./components/write-lock";
 // 0.18: the parts both apps' admin rosters repeat (Kurvenschmiede 6).
 export { RoleChip, AccountStateChip, DateMark, dateColumn, DEFAULT_ACCOUNT_STATE_LABELS, ACCOUNT_STATE_TONES } from "./components/account-chips";
@@ -552,6 +554,19 @@ export type {
 // actions, one of the behaviours at Large (§4, §10.7–10.9).
 export { DEFAULT_APPEARANCE_LABELS, useAppearanceLabels } from "./components/appearance-labels";
 export type { AppearanceLabels } from "./components/appearance-labels";
+// 0.46 (keksdose's date format, lifted): the preference, its resolver and renderer, the
+// provider's formatter for it, and the settings field.
+export {
+  DATE_FORMAT_PREFERENCES,
+  isDateFormatPreference,
+  resolveDateFormat,
+  formatDateWithPreference,
+  dateFormatSample,
+  dateFormatterFor,
+} from "./lib/date-format";
+export type { DateFormatPreference, DateFormatOptions, ResolvedDateFormat } from "./lib/date-format";
+export { DateFormatSetting } from "./components/date-format-setting";
+export type { DateFormatSettingProps } from "./components/date-format-setting";
 export { RowActions, rowActionsColumn, DEFAULT_ROW_ACTIONS_LABELS } from "./components/row-actions";
 export type {
   RowAction,
@@ -808,6 +823,10 @@ export type {
   AdminExtraTile,
   AdminOverviewProps,
   AttentionTileProps,
+  // 0.46 (Kurvenschmiede 1): the feedback tiles with the kit's words.
+  AdminFeedbackTile,
+  AdminFeedbackTileKey,
+  AdminOwnTile,
 } from "./admin/admin-overview";
 export { AdminToolLinks } from "./admin/admin-tool-links";
 export type { AdminToolLink, AdminToolLinksProps } from "./admin/admin-tool-links";
@@ -946,13 +965,27 @@ export type {
   NotificationTypeGroup,
   NotificationSettingsPatch,
   PushDeviceItem,
+  NotificationChannel,
 } 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 { TimeZoneSelect, timeZoneOptions } from "./notifications/time-zone-select";
 export type { TimeZoneSelectProps } from "./notifications/time-zone-select";
+// 0.46 (docs/notifications-harmonization.md §10.1, §10.3): the inbox list, the bell and
+// the device-zone report (the account's zone is automatic only, amended 2026-10-20).
+export { NotificationInbox, INBOX_BADGE_INTERVAL } from "./notifications/notification-inbox";
+export type {
+  NotificationInboxAction,
+  NotificationInboxItem,
+  NotificationInboxProps,
+} from "./notifications/notification-inbox";
+export { NotificationBell } from "./notifications/notification-bell";
+export type { NotificationBellProps } from "./notifications/notification-bell";
+// `deviceTimeZone` lives beside the report since 0.46.1 (keksdose N6; sign-up needs it).
+export { useDeviceZoneReport, deviceTimeZone } from "./notifications/device-zone-report";
+export type { DeviceZoneReportOptions } from "./notifications/device-zone-report";
 export {
   usePushDevice,
   PUSH_SUBSCRIPTION_CHANGED,
@@ -967,6 +1000,20 @@ export type {
   PushPermission,
   PushDeviceErrorCode,
 } from "./notifications/use-push-device";
+// 0.46 (NT:1028): the service worker re-registers a rotated subscription. A worker imports
+// them from `@eifi1/ui-kit/push-worker` (§10.6 rule 5); the barrel keeps them too.
+export {
+  handlePushSubscriptionChange,
+  resubscribeAfterChange,
+  pushSubscriptionInput,
+} from "./notifications/push-worker";
+export type {
+  PushReplaceInput,
+  PushSubscriptionChangeOptions,
+  PushSubscriptionChangeEventLike,
+  PushResubscribeOutcome,
+  PushWorkerScope,
+} from "./notifications/push-worker";
 export { PushDeviceSetting } from "./notifications/push-device-setting";
 export type { PushDeviceSettingProps, PushDeviceAction } from "./notifications/push-device-setting";
 export { PushDevicesSetting, describeUserAgent } from "./notifications/push-devices-setting";
@@ -974,8 +1021,10 @@ export type { PushDevicesSettingProps } from "./notifications/push-devices-setti
 export { UnsubscribePanel, unsubscribeTokenType } from "./notifications/unsubscribe-panel";
 export type { UnsubscribePanelProps } from "./notifications/unsubscribe-panel";
 // 0.38.0 (docs/feedback-harmonization.md §9.11): the two feedback types' setting words.
+// 0.46.1 (keksdose N9): `useFeedbackNotificationTypesLabels`, the words resolved, for `adminGroup`.
 export {
   useFeedbackNotificationTypes,
+  useFeedbackNotificationTypesLabels,
   DEFAULT_FEEDBACK_NOTIFICATION_TYPES_LABELS,
 } from "./notifications/feedback-notification-types";
 export type {

package/src/lib/date-format.ts

@@ -0,0 +1,151 @@
+import { formatLocaleOf } from "../i18n/languages";
+import type { KitDateFormatter } from "../i18n/kit-labels";
+
+/**
+ * The date-format preference (0.46, lifted from keksdose's `date-format-store.ts`,
+ * feedback #180): how a DAY is written — the order of day, month and year and the
+ * separator between them — as a choice of its own, apart from the interface language.
+ * "Read the app in English and still see German dates", or ISO everywhere.
+ *
+ * keksdose's rules, which the kit keeps:
+ *
+ * 1. **A label that identifies a day follows the preference** — anything that prints
+ *    day, month and year goes through {@link formatDateWithPreference} (or the
+ *    provider's `formatDate`, {@link dateFormatterFor}, for the kit's own date fields).
+ * 2. **A label without a day follows the language**: "August 2026", a month or weekday
+ *    NAME has no order to arrange. {@link dateFormatterFor} answers `""` for a month or a
+ *    year, so the kit keeps its own rendering in the language.
+ * 3. **A clock time follows the language**: `sv-SE` is a statement about digit order in
+ *    a date, not about a 12- or 24-hour clock.
+ * 4. **A weekday's NAME follows the language** (dev#546): `sv-SE` means "year first,
+ *    with dashes", not "the reader speaks Swedish" — so with `weekday` the day's name is
+ *    the language's, joined to the date the preference renders.
+ *
+ * The preference is the APP's to keep — keksdose holds it per device (a persisted store,
+ * not an account column: nothing server-written formats a date for the reader). The kit
+ * owns the vocabulary, the resolver, the renderer and the settings field
+ * ({@link DateFormatSetting}).
+ */
+
+/** `"auto"` follows the interface language (the default — nobody's dates move until
+ *  they ask); the rest are BCP 47 tags chosen for the SHAPE they produce: German
+ *  01.08.2026, British 01/08/2026, US 08/01/2026, ISO 2026-08-01. */
+export type DateFormatPreference = "auto" | "de-DE" | "en-GB" | "en-US" | "sv-SE";
+
+/** The options in the order the setting lists them: `auto` first (the default), then
+ *  German → UK → US → ISO. */
+export const DATE_FORMAT_PREFERENCES: readonly DateFormatPreference[] = ["auto", "de-DE", "en-GB", "en-US", "sv-SE"];
+
+/** Whether `value` is one of {@link DATE_FORMAT_PREFERENCES} — for a value read back from
+ *  storage, where anything else falls back to `"auto"`. */
+export function isDateFormatPreference(value: unknown): value is DateFormatPreference {
+  return typeof value === "string" && (DATE_FORMAT_PREFERENCES as readonly string[]).includes(value);
+}
+
+/** A resolved preference: the locale and `Intl` options the date itself is rendered
+ *  with, and — only when asked for — the locale the weekday's NAME comes from. */
+export interface ResolvedDateFormat {
+  locale: string | undefined;
+  options: Intl.DateTimeFormatOptions;
+  /** The language's format locale, present when `weekday` was asked for. */
+  weekday?: { locale: string | undefined };
+}
+
+/** What {@link resolveDateFormat} and the renderers take beyond the preference. */
+export interface DateFormatOptions {
+  /** Name the day of the week too, in the interface language ("Mo., 01.08.2026"). A date
+   *  in a COLUMN carries it; a date in a SENTENCE does not (keksdose dev#546). */
+  weekday?: boolean;
+}
+
+/**
+ * What a date is rendered with, given the preference and the interface language
+ * (`language`: a code or tag — `"de"`, `"en"`, i18next's `resolvedLanguage`; it is read
+ * through `formatLocaleOf`, so English is British and an unshipped tag stays itself).
+ *
+ * `"auto"` keeps the short-month shape ("01 Aug 2026", "01. Aug. 2026"); every explicit
+ * choice is all-numeric, the only way it produces the shape its option promises —
+ * `month: "short"` under `sv-SE` would print "2026 aug. 01", not ISO.
+ */
+export function resolveDateFormat(
+  preference: DateFormatPreference,
+  language: string | undefined,
+  options: DateFormatOptions = {},
+): ResolvedDateFormat {
+  const languageLocale = language ? formatLocaleOf(language) : undefined;
+  const weekday = options.weekday ? { weekday: { locale: languageLocale } } : {};
+  if (preference === "auto") {
+    return { locale: languageLocale, options: { year: "numeric", month: "short", day: "2-digit" }, ...weekday };
+  }
+  return { locale: preference, options: { year: "numeric", month: "2-digit", day: "2-digit" }, ...weekday };
+}
+
+/** A bare calendar day: no time, no zone. */
+const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+
+/**
+ * `dateText`, already rendered under the preference, with the day's NAME around it in
+ * `locale` (the language's). Not "weekday alone + comma": German says "So" alone and
+ * "So., 06.09.2026" in company. The full date is formatted in the language and split
+ * into parts; what that language puts before the first and after the last day/month/
+ * year part (the weekday, its comma) frames the preference's digits — so where the two
+ * locales coincide the output is the native string, character for character.
+ */
+function withWeekday(date: Date, dateText: string, locale: string | undefined, options: Intl.DateTimeFormatOptions) {
+  const isDatePart = (p: Intl.DateTimeFormatPart) => p.type === "day" || p.type === "month" || p.type === "year";
+  const parts = new Intl.DateTimeFormat(locale, { weekday: "short", ...options }).formatToParts(date);
+  const first = parts.findIndex(isDatePart);
+  if (first === -1) return dateText;
+  let last = first;
+  parts.forEach((p, i) => {
+    if (isDatePart(p)) last = i;
+  });
+  const join = (ps: Intl.DateTimeFormatPart[]) => ps.map((p) => p.value).join("");
+  return join(parts.slice(0, first)) + dateText + join(parts.slice(last + 1));
+}
+
+/**
+ * A date under the preference: `""` for no value, the input itself when it does not
+ * parse. A bare "YYYY-MM-DD" is the calendar day it names in every zone (formatted in
+ * UTC, undoing `new Date`'s UTC-midnight parse — west of Greenwich it read a day early);
+ * a timestamp is an instant and stays in the reader's zone. The weekday, when asked for,
+ * is rendered in the same zone, so a Sunday is never captioned Saturday.
+ */
+export function formatDateWithPreference(
+  value: string | Date | null | undefined,
+  preference: DateFormatPreference,
+  language: string | undefined,
+  options: DateFormatOptions = {},
+): string {
+  if (!value) return "";
+  const resolved = resolveDateFormat(preference, language, options);
+  const dateOnly = typeof value === "string" && DATE_ONLY.test(value);
+  const date = typeof value === "string" ? new Date(value) : value;
+  if (Number.isNaN(date.getTime())) return String(value);
+  const intl: Intl.DateTimeFormatOptions = dateOnly ? { ...resolved.options, timeZone: "UTC" } : resolved.options;
+  try {
+    const text = date.toLocaleDateString(resolved.locale, intl);
+    return resolved.weekday ? withWeekday(date, text, resolved.weekday.locale, intl) : text;
+  } catch {
+    // A language tag `Intl` refuses: the ISO day rather than nothing (keksdose's fallback).
+    return date.toISOString().slice(0, 10);
+  }
+}
+
+/** The sample an option is labelled with — 1 August 2026 in its shape, the shape being
+ *  the whole choice (a country name would say nothing about the digit order). */
+export function dateFormatSample(preference: DateFormatPreference, language: string | undefined): string {
+  return formatDateWithPreference("2026-08-01", preference, language);
+}
+
+/**
+ * The `<UiKitProvider formatDate>` for a preference — so the kit's own date fields
+ * (DatePicker, DateRangePicker, DateMark) write a day as the app's dates do. A day
+ * follows the preference, with the weekday where the kit suggests it; a month or a year
+ * answers `""` and keeps the kit's rendering in the language (rule 2). Rebuild it when
+ * the preference or the language changes (a `useMemo` on both).
+ */
+export function dateFormatterFor(preference: DateFormatPreference, language: string | undefined): KitDateFormatter {
+  return (iso, { unit, weekday, locale }) =>
+    unit === "day" ? formatDateWithPreference(iso, preference, locale ?? language, { weekday }) : "";
+}

package/src/lib/format.ts

@@ -1,5 +1,5 @@
 import { useMemo } from "react";
-import { useKitLocale } from "../i18n/kit-labels";
+import { useKitLocale, useKitTimeZone } from "../i18n/kit-labels";
 import { parseIsoDate } from "./dates";
 import { roundHalfAway } from "./round";
 
@@ -244,6 +244,9 @@ export function formatDate(
 }
 
 export interface FormatRelativeTimeOptions extends BaseOptions {
+  /** The zone of the date printed past `absoluteAfterDays` (0.46). Left out: the
+   *  device's. */
+  timeZone?: string;
   /** The moment it is measured from. Default: now. */
   now?: DateInput;
   /** `"auto"` (default): "yesterday", "now", "next week". `"always"`: "1 day ago". */
@@ -348,16 +351,19 @@ export interface KitFormat {
  */
 export function useKitFormat(locale?: string): KitFormat {
   const kitLocale = useKitLocale(locale);
+  // 0.46 (§10.3): the provider's `timeZone` for timestamps; a call's own wins, and a bare
+  // "YYYY-MM-DD" ignores it (formatDate).
+  const timeZone = useKitTimeZone();
   return useMemo<KitFormat>(
     () => ({
       locale: kitLocale,
       formatNumber: (value, options) => formatNumber(value, { locale: kitLocale, ...options }),
       formatMoney: (value, currency, options) => formatMoney(value, currency, { locale: kitLocale, ...options }),
       formatPercent: (value, options) => formatPercent(value, { locale: kitLocale, ...options }),
-      formatDate: (value, style, options) => formatDate(value, style, { locale: kitLocale, ...options }),
-      formatRelativeTime: (value, options) => formatRelativeTime(value, { locale: kitLocale, ...options }),
+      formatDate: (value, style, options) => formatDate(value, style, { locale: kitLocale, timeZone, ...options }),
+      formatRelativeTime: (value, options) => formatRelativeTime(value, { locale: kitLocale, timeZone, ...options }),
     }),
-    [kitLocale],
+    [kitLocale, timeZone],
   );
 }
 

package/src/notifications/device-zone-report.ts

@@ -0,0 +1,67 @@
+import { useEffect } from "react";
+
+import { settle } from "../account/account-parts";
+
+export interface DeviceZoneReportOptions {
+  /** The account's `device_timezone` from `/auth/me`; `undefined` while it loads (no
+   *  report until it is known). */
+  stored: string | null | undefined;
+  /** `PATCH /auth/me {device_timezone}` with this device's zone. */
+  report: (deviceTimezone: string) => Promise<unknown> | void;
+  /** A demo account: never reported (the server ignores it too, §10.3 Settled). */
+  isDemo?: boolean;
+  /** The signed-in account (its user id): the once-per-start guard is per account, so a
+   *  second person signed in on a shared PC in the same start is reported too. Without it
+   *  the guard is cleared when `stored` goes `undefined` (signed out). */
+  account?: string | number | null;
+}
+
+/**
+ * This device's IANA zone ("Europe/Zurich"), or `"UTC"` where the runtime names none —
+ * the zone `useDeviceZoneReport` reports, which becomes the account's (§10.3, automatic
+ * only), and the one sign-up sends (`RegisterRequest.device_timezone`). Here since 0.46.1
+ * (keksdose N6); the deprecated `time-zone-select` module re-exports it until 0.47.
+ */
+export function deviceTimeZone(): string {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+  } catch {
+    return "UTC";
+  }
+}
+
+/** The (account, stored, device) triples already reported in this start of the app. */
+const reportedThisStart = new Set<string>();
+
+/**
+ * Report this device's zone to the account (0.46, §10.3): the account's zone follows the
+ * device last used, else `Europe/Zurich`; screens keep showing device time. Once per start
+ * of the app, and only when it differs from the stored `device_timezone` — a bench PC in Zurich never
+ * PATCHes on a sign-in — and never for a demo. Per account: a sign-out (`stored` back to
+ * `undefined`) clears the guard, and `account` keys it. The report IS the account's zone: it is
+ * automatic only (§10.3, amended 2026-10-20), so nothing is ever picked. A failed report
+ * is not retried in the same start; the next start tries again. Sign-up sends the zone
+ * itself (`RegisterRequest.device_timezone`).
+ *
+ *     useDeviceZoneReport({ stored: me?.device_timezone, isDemo: me?.is_demo, account: me?.id,
+ *       report: async (zone) => setUser((await api.patch("/auth/me", { device_timezone: zone })).data) });
+ */
+export function useDeviceZoneReport({ stored, report, isDemo = false, account = null }: DeviceZoneReportOptions): void {
+  useEffect(() => {
+    if (stored === undefined) {
+      // Signed out (or still loading): the next account in this start is reported afresh.
+      reportedThisStart.clear();
+      return;
+    }
+    if (isDemo) return;
+    const device = deviceTimeZone();
+    if (device === stored) return;
+    const key = `${account ?? ""}|${stored ?? ""}→${device}`;
+    if (reportedThisStart.has(key)) return;
+    reportedThisStart.add(key);
+    void settle(() => report(device)).catch(() => undefined);
+    // `report` is the app's request function: a new closure each render must not report
+    // again, so only the values decide.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [stored, isDemo, account]);
+}

package/src/notifications/feedback-notification-types-labels.ts

@@ -2,7 +2,7 @@
 // component code, as every `*-labels.ts`: the English catalogue imports them alone.
 
 /**
- * `feedbackNotificationTypes` — the setting words of the two feedback notification types
+ * `feedbackNotificationTypes` — the setting words of the feedback notification types
  * (docs/feedback-harmonization.md §9.11). In the kit, not in each app, because two apps
  * declare them (keksdose, Kurvenschmiede; kastlan `feedback_answered` alone). The mail and
  * push texts stay the app's.
@@ -14,6 +14,12 @@ export interface FeedbackNotificationTypesLabels {
   /** `feedback_comment`: a visible comment on such a report. */
   comment: string;
   commentDescription: string;
+  /** 0.46 (feedback §11): `feedback_received`, an admin's alert for a new report, a
+   *  rework and a new crash. */
+  received: string;
+  receivedDescription: string;
+  /** A heading the apps may put over the admin's types ("Admin"). */
+  adminGroup: string;
 }
 
 export const DEFAULT_FEEDBACK_NOTIFICATION_TYPES_LABELS: FeedbackNotificationTypesLabels = {
@@ -21,4 +27,7 @@ export const DEFAULT_FEEDBACK_NOTIFICATION_TYPES_LABELS: FeedbackNotificationTyp
   answeredDescription: "When a report you wrote or commented on gets an answer.",
   comment: "Comments on reports you follow",
   commentDescription: "When someone comments on a report you wrote or commented on.",
+  received: "New feedback and reworks",
+  receivedDescription: "When someone files a report or sends one back.",
+  adminGroup: "Admin",
 };

package/src/notifications/feedback-notification-types.ts

@@ -9,9 +9,9 @@ import {
 export { DEFAULT_FEEDBACK_NOTIFICATION_TYPES_LABELS };
 export type { FeedbackNotificationTypesLabels };
 
-/** The two feedback notification ids (§9.11), as server-kit's `FEEDBACK_ANSWERED` and
- *  `FEEDBACK_COMMENT` name them. */
-export type FeedbackNotificationTypeId = "feedback_answered" | "feedback_comment";
+/** The feedback notification ids (§9.11, §11), as server-kit's `FEEDBACK_ANSWERED`,
+ *  `FEEDBACK_COMMENT` and `FEEDBACK_RECEIVED` (0.46: an admin's alert) name them. */
+export type FeedbackNotificationTypeId = "feedback_answered" | "feedback_comment" | "feedback_received";
 
 /**
  * The setting words of the two feedback notification types (round 0.38,
@@ -27,9 +27,16 @@ export type FeedbackNotificationTypeId = "feedback_answered" | "feedback_comment
  * - **"Comments on reports you follow"** (`feedback_comment`): a visible comment, to the
  *   author and the earlier commenters.
  *
- * Both entries are always returned: the card draws a type only when the server answered
+ * - **"New feedback and reworks"** (`feedback_received`, 0.46, feedback §11): to the
+ *   admins, when someone files a report or sends one back for rework. (A crash is mailed
+ *   only inside the bundle where an app runs the queue, so the text names no crash.)
+ *   `labels.adminGroup` ("Admin") is a heading an app may put over it — read it with
+ *   {@link useFeedbackNotificationTypesLabels} (0.46.1) for the app's own `groups`.
+ *
+ * Every entry is always returned: the card draws a type only when the server answered
  * it (notifications §2.1), so kastlan, which does not declare `feedback_comment` while its
- * public parts are off, shows the first alone. Words: `<UiKitProvider labels={{
+ * public parts are off, shows the first alone, and a person who is no admin is never
+ * answered `feedback_received`. Words: `<UiKitProvider labels={{
  * feedbackNotificationTypes }}>` over English, `labels` over both.
  */
 export function useFeedbackNotificationTypes(
@@ -40,7 +47,25 @@ export function useFeedbackNotificationTypes(
     () => [
       { id: "feedback_answered", label: words.answered, description: words.answeredDescription },
       { id: "feedback_comment", label: words.comment, description: words.commentDescription },
+      { id: "feedback_received", label: words.received, description: words.receivedDescription },
     ],
     [words],
   );
 }
+
+/**
+ * The `feedbackNotificationTypes` words, resolved — English, then the provider, then
+ * `labels` (0.46.1, keksdose N9): what an app reads to head its own `groups` with
+ * `adminGroup` ("Admin") in the provider's locale, as {@link useFeedbackNotificationTypes}
+ * labels the entries.
+ *
+ * ```tsx
+ * const { adminGroup } = useFeedbackNotificationTypesLabels();
+ * groups={[...appGroups, { id: "admin", label: adminGroup, types: ["feedback_received"] }]}
+ * ```
+ */
+export function useFeedbackNotificationTypesLabels(
+  labels?: LabelOverride<FeedbackNotificationTypesLabels>,
+): FeedbackNotificationTypesLabels {
+  return useKitLabels("feedbackNotificationTypes", DEFAULT_FEEDBACK_NOTIFICATION_TYPES_LABELS, labels);
+}

package/src/notifications/notification-bell.tsx

@@ -0,0 +1,116 @@
+import { Bell } from "lucide-react";
+import type { LucideIcon } from "lucide-react";
+
+import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
+import { useKitFormat } from "../lib/format";
+import { DEFAULT_LIST_LABELS } from "../components/list-labels";
+import { StatusDot } from "../components/status-dot";
+import { TopBarActionMenu } from "../shell/topbar-action-menu";
+import type { TopBarMenuEntry } from "../shell/topbar-action-menu";
+import { useNotificationsLabels } from "./notification-parts";
+import type { NotificationsLabels } from "./notifications-labels";
+import type { NotificationInboxItem } from "./notification-inbox";
+
+/** How many rows the bell's panel shows: the newest 20 (§10.1). */
+const BELL_ROWS = 20;
+
+export interface NotificationBellProps<Id extends string | number = string | number> {
+  /** The inbox, newest first (the bell shows the first 20); `undefined` while it loads. */
+  items: readonly NotificationInboxItem<Id>[] | undefined;
+  /** Every unread row of the account (`unread_count`): the badge. */
+  unreadCount: number;
+  /** Open a row: the app marks it read and routes to `item.url` (kastlan switches the
+   *  acting company first, to `item.company_id`). The panel closes. */
+  onOpen: (item: NotificationInboxItem<Id>) => void;
+  /** The app's inbox page or card, for "All notifications". */
+  href: string;
+  /** The row's glyph for a type, as {@link NotificationInbox}'s; `Bell` by default. */
+  icon?: (type: string) => LucideIcon | undefined;
+  /** A row's time. Default: the provider's locale and `timeZone`, date and time. */
+  formatDate?: (iso: string) => string;
+  labels?: LabelOverride<NotificationsLabels>;
+}
+
+/** The badge's text: "99+" past 99. */
+const badgeText = (count: number) => (count > 99 ? "99+" : String(Math.floor(count)));
+
+/**
+ * The top bar's bell (0.46, docs/notifications-harmonization.md §10.1), for
+ * `TopBarActions`' `notifications` slot, right before the account menu: an icon button
+ * with the unread count as a badge ("99+" past 99), opening the newest 20 rows in the
+ * kit's top-bar panel (`TopBarActionMenu`) with "All notifications" under them.
+ *
+ * **Optional per app.** "One badge per signal": an app shows the bell or an unread dot on
+ * the avatar, never both — keksdose keeps its avatar dot and no bell; kastlan's inbox
+ * lives in the bell. Shown to every signed-in account in an app that keeps an inbox, the
+ * demo included. Props only, as the inbox list: poll the count every
+ * {@link INBOX_BADGE_INTERVAL}.
+ */
+export function NotificationBell<Id extends string | number = string | number>({
+  items,
+  unreadCount,
+  onOpen,
+  href,
+  icon,
+  formatDate: formatDateProp,
+  labels: labelsProp,
+}: NotificationBellProps<Id>) {
+  const labels = useNotificationsLabels(labelsProp);
+  const list = useKitLabels("list", DEFAULT_LIST_LABELS);
+  const { formatDate } = useKitFormat();
+  const timeOf = (iso: string) => (formatDateProp ? formatDateProp(iso) : formatDate(iso, "dateTime"));
+  const unread = unreadCount > 0;
+  const shown = (items ?? []).slice(0, BELL_ROWS);
+
+  const entries: TopBarMenuEntry[] = shown.map((item) => {
+    const Icon = icon?.(item.notification_type) ?? Bell;
+    const isUnread = item.read_at === null;
+    return {
+      key: `item-${String(item.id)}`,
+      icon: <Icon aria-hidden className="size-4" />,
+      label: (
+        <span className="block min-w-0" data-bell-item={String(item.id)}>
+          {item.company && <span className="block truncate text-caption text-muted">{item.company}</span>}
+          <span className={isUnread ? "block font-semibold" : "block"}>{item.title}</span>
+          <span className="block line-clamp-2 text-xs text-secondary">{item.body}</span>
+          <span className="block text-caption text-muted">{timeOf(item.created_at)}</span>
+        </span>
+      ),
+      trailing: isUnread ? <StatusDot tone="brand" aria-label={list.unread} /> : undefined,
+      onSelect: () => onOpen(item),
+    };
+  });
+  if (entries.length > 0) entries.push({ kind: "divider", key: "divider" });
+  entries.push({ kind: "link", key: "all", to: href, label: labels.allNotifications });
+
+  return (
+    <TopBarActionMenu
+      aria-label={labels.bellLabel}
+      triggerAttributes={{ "data-notification-bell": "" }}
+      trigger={() => (
+        <span className="relative inline-flex" data-unread={unread ? unreadCount : undefined}>
+          <Bell aria-hidden className="size-5" />
+          {unread && (
+            <>
+              <span
+                aria-hidden
+                data-badge=""
+                className="pointer-events-none absolute -end-2 -top-1.5 h-4 min-w-4 rounded-full bg-danger px-1 text-center text-micro font-semibold leading-4 text-danger-contrast"
+              >
+                {badgeText(unreadCount)}
+              </span>
+              <span className="sr-only">{labels.bellUnread(unreadCount)}</span>
+            </>
+          )}
+        </span>
+      )}
+      header={
+        shown.length === 0
+          ? { title: labels.inboxTitle, subtitle: items === undefined ? labels.inboxLoading : labels.inboxEmpty }
+          : undefined
+      }
+      entries={entries}
+      panelClassName="w-80 max-w-[calc(100vw-2rem)]"
+    />
+  );
+}