@eifi1/ui-kit 0.44.0 → 0.46.0

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,15 @@ 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.
+ *
+ * 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,6 +46,7 @@ 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],
   );

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). 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)]"
+    />
+  );
+}

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;