@multiplatform.one/backoffice 6.3.0

package/src/chrome/notifications-data.tsx

@@ -0,0 +1,287 @@
+import React from "react";
+/**
+ * Live Notification Log feed for the navbar bell (desk parity).
+ *
+ * Data flows through the live client (`useFrappeCollection` + `useLiveQuery`)
+ * so realtime inserts pop into the panel without a refetch. Read state is a
+ * different story: the desk RPCs flip `read` with `update_modified=False`
+ * (no realtime doc_update event), so this hook layers local optimistic
+ * overrides on top of the collection and lets a later sync reconcile.
+ *
+ * RPC shapes (probed against the reference bench):
+ * - POST /api/method/frappe.desk.doctype.notification_log.notification_log.mark_as_read
+ *   body {docname} → {} (sets read=1)
+ * - POST /api/method/frappe.desk.doctype.notification_log.notification_log.mark_all_as_read
+ *   body {} → {} (marks every unread row for the session user)
+ * - Fallback per doc: POST frappe.client.set_value
+ *   {doctype: "Notification Log", name, fieldname: "read", value: 1}
+ */
+import {
+  Order,
+  useFrappeCollection,
+  useLiveQuery,
+  type FixtureProvider,
+  type FrappeApp,
+} from "@multiplatform.one/frappe";
+import { useFrappeConfig } from "@multiplatform.one/frappe-ui";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { useFrappeApp } from "../shared/useFrappeApp";
+import { parseFrappeTimestamp, stripHtmlToText } from "./notifications-utils";
+
+export interface NotificationLogDoc {
+  name: string;
+  doctype: string;
+  subject?: string;
+  type?: string;
+  document_type?: string;
+  document_name?: string;
+  read?: 0 | 1;
+  from_user?: string;
+  creation?: string;
+}
+
+/** A Notification Log row prepared for display. */
+export interface NotificationItem extends NotificationLogDoc {
+  /** Server `read` merged with local optimistic mark-as-read overrides. */
+  unread: boolean;
+  /** Subject with HTML stripped ("Jane mentioned you in a comment: …"). */
+  subjectText: string;
+  /** `creation` as epoch ms (undefined when unparseable). */
+  timestampMs?: number;
+}
+
+const NOTIFICATION_FIELDS = [
+  "name",
+  "subject",
+  "type",
+  "document_type",
+  "document_name",
+  "read",
+  "from_user",
+  "creation",
+] as const;
+
+/** Recent-notifications window (desk loads pages of 20; badge caps at 99+). */
+const NOTIFICATION_WINDOW_LIMIT = 100;
+
+const MARK_AS_READ_METHOD = "frappe.desk.doctype.notification_log.notification_log.mark_as_read";
+const MARK_ALL_AS_READ_METHOD =
+  "frappe.desk.doctype.notification_log.notification_log.mark_all_as_read";
+
+// ---------------------------------------------------------------------------
+// Session user (module cache — one fetch per FrappeApp per session)
+// ---------------------------------------------------------------------------
+
+const sessionUserCache = new WeakMap<FrappeApp, Promise<string | undefined>>();
+
+interface SessionUserState {
+  user?: string;
+  /** True once the probe settled (Guest / unreachable resolve to no user). */
+  resolved: boolean;
+}
+
+function useNotificationsSessionUser(fixtureMode: boolean): SessionUserState {
+  const app = useFrappeApp();
+  const [state, setState] = useState<SessionUserState>({ resolved: false });
+
+  useEffect(() => {
+    // Fixture mode has no session endpoint; report resolved-with-no-user.
+    // No app (no provider config) settles the same way so the panel never
+    // skeletons forever.
+    if (fixtureMode || !app) {
+      setState({ resolved: true });
+      return;
+    }
+    let cancelled = false;
+    let promise = sessionUserCache.get(app);
+    if (!promise) {
+      promise = app
+        .call()
+        .get<{ message?: string }>("frappe.auth.get_logged_user")
+        .then((res) => {
+          const user = res.payload?.message;
+          return user && user !== "Guest" ? user : undefined;
+        })
+        .catch(() => {
+          // Evict failed probes so a later mount can retry.
+          sessionUserCache.delete(app);
+          return undefined;
+        });
+      sessionUserCache.set(app, promise);
+    }
+    promise.then((user) => {
+      if (!cancelled) setState({ user, resolved: true });
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [app, fixtureMode]);
+
+  return state;
+}
+
+// ---------------------------------------------------------------------------
+// Mark-as-read RPCs
+// ---------------------------------------------------------------------------
+
+async function setReadViaSetValue(app: FrappeApp, name: string): Promise<void> {
+  await app.call().post("frappe.client.set_value", {
+    doctype: "Notification Log",
+    name,
+    fieldname: "read",
+    value: 1,
+  });
+}
+
+async function markAsReadOnServer(app: FrappeApp, name: string): Promise<void> {
+  try {
+    await app.call().post(MARK_AS_READ_METHOD, { docname: name });
+  } catch {
+    // Desk RPC unavailable (older bench / stripped app) — plain doc write.
+    await setReadViaSetValue(app, name);
+  }
+}
+
+async function markAllAsReadOnServer(
+  app: FrappeApp,
+  unreadNames: readonly string[],
+): Promise<void> {
+  try {
+    await app.call().post(MARK_ALL_AS_READ_METHOD, {});
+  } catch {
+    await Promise.all(unreadNames.map((name) => setReadViaSetValue(app, name)));
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
+export interface UseNotificationsResult {
+  /** Prepared rows, newest first. */
+  items: NotificationItem[];
+  /** Unread rows within the window (badge value). */
+  unreadCount: number;
+  /** True until the session probe + first collection snapshot settle. */
+  isLoading: boolean;
+  /** Mark one notification read (optimistic; reverts if the RPC fails). */
+  markAsRead: (name: string) => Promise<void>;
+  /** Mark every unread notification read (optimistic; reverts on failure). */
+  markAllAsRead: () => Promise<void>;
+}
+
+export function useNotifications(): UseNotificationsResult {
+  const config = useFrappeConfig();
+  const app = useFrappeApp();
+  const fixtureMode = Boolean(config?.fixtures);
+  const { user: sessionUser, resolved: sessionResolved } = useNotificationsSessionUser(fixtureMode);
+
+  // Stable connection config (fresh identities would churn the collection).
+  const connectionConfig = useMemo(
+    () =>
+      config
+        ? {
+            baseURL: config.baseURL,
+            socketPort: config.socketPort,
+            auth: config.auth,
+            syncOptions: config.syncOptions,
+            socketOptions: config.socketOptions,
+            fixtures: config.fixtures as FixtureProvider | undefined,
+          }
+        : undefined,
+    [config],
+  );
+
+  // Live mode waits for the session user (the for_user filter needs it);
+  // fixture mode reads the fixture set unfiltered.
+  const ready = Boolean(connectionConfig) && (fixtureMode || Boolean(sessionUser));
+  const collection = useFrappeCollection<NotificationLogDoc>(
+    ready ? connectionConfig : undefined,
+    "Notification Log",
+    {
+      fields: NOTIFICATION_FIELDS,
+      filters: !fixtureMode && sessionUser ? [["for_user", "=", sessionUser]] : undefined,
+      orderBy: { field: "creation", order: Order.Desc },
+      limit: NOTIFICATION_WINDOW_LIMIT,
+    },
+  );
+
+  const { data: rawData, isLoading: queryLoading } = useLiveQuery(
+    (q) => (collection ? q.from({ _notification: collection }) : null),
+    [collection],
+  );
+
+  // Local read overrides — see module note on why realtime can't carry these.
+  const [readOverrides, setReadOverrides] = useState<ReadonlySet<string>>(new Set());
+
+  const items = useMemo<NotificationItem[]>(() => {
+    const docs = (rawData as NotificationLogDoc[] | undefined) ?? [];
+    return docs
+      .filter((doc) => doc.name)
+      .map((doc) => ({
+        ...doc,
+        unread: !doc.read && !readOverrides.has(doc.name),
+        subjectText: stripHtmlToText(doc.subject),
+        timestampMs: parseFrappeTimestamp(doc.creation),
+      }))
+      .sort((a, b) => (b.timestampMs ?? 0) - (a.timestampMs ?? 0) || a.name.localeCompare(b.name));
+  }, [rawData, readOverrides]);
+
+  const unreadCount = useMemo(() => items.filter((item) => item.unread).length, [items]);
+
+  const isLoading =
+    (Boolean(connectionConfig) && !fixtureMode && !sessionResolved) ||
+    // Session resolved without a user (Guest / unreachable bench): settle on
+    // an empty feed instead of skeleting forever.
+    (ready && (collection === undefined || Boolean(queryLoading)));
+
+  const addOverrides = useCallback((names: readonly string[]) => {
+    if (!names.length) return;
+    setReadOverrides((prev) => {
+      const next = new Set(prev);
+      for (const name of names) next.add(name);
+      return next;
+    });
+  }, []);
+
+  const removeOverrides = useCallback((names: readonly string[]) => {
+    if (!names.length) return;
+    setReadOverrides((prev) => {
+      const next = new Set(prev);
+      for (const name of names) next.delete(name);
+      return next;
+    });
+  }, []);
+
+  const markAsRead = useCallback(
+    async (name: string) => {
+      addOverrides([name]);
+      if (fixtureMode || !app) return;
+      try {
+        await markAsReadOnServer(app, name);
+      } catch (err) {
+        removeOverrides([name]);
+        throw err;
+      }
+    },
+    [app, fixtureMode, addOverrides, removeOverrides],
+  );
+
+  const markAllAsRead = useCallback(async () => {
+    const unreadNames = items.filter((item) => item.unread).map((item) => item.name);
+    if (!unreadNames.length) return;
+    addOverrides(unreadNames);
+    if (fixtureMode || !app) return;
+    try {
+      await markAllAsReadOnServer(app, unreadNames);
+    } catch (err) {
+      removeOverrides(unreadNames);
+      throw err;
+    }
+  }, [app, fixtureMode, items, addOverrides, removeOverrides]);
+
+  return useMemo(
+    () => ({ items, unreadCount, isLoading, markAsRead, markAllAsRead }),
+    [items, unreadCount, isLoading, markAsRead, markAllAsRead],
+  );
+}

package/src/chrome/notifications-panel.tsx

@@ -0,0 +1,175 @@
+/**
+ * Notifications panel body (desk bell-dropdown parity): header with
+ * "Notifications" + mark-all-as-read + settings placeholder, then the
+ * newest-first Notification Log list. Presentational — data, routing, and
+ * the popover/sheet shell live in NotificationsButton.
+ */
+import {
+  Avatar,
+  Button,
+  EmptyState,
+  Separator,
+  SizableText,
+  Skeleton,
+  SkeletonCircle,
+  Text,
+  View,
+  XStack,
+  YStack,
+} from "@multiplatform.one/components";
+import { formatRelativeTimestamp } from "@multiplatform.one/theme";
+import { GearSixIcon } from "@phosphor-icons/react";
+import { useTranslation } from "react-i18next";
+import { BACKOFFICE_I18N_NAMESPACE } from "../i18n";
+import type { NotificationItem } from "./notifications-data";
+
+export interface NotificationsPanelProps {
+  items: readonly NotificationItem[];
+  isLoading: boolean;
+  /** Panel width — a fixed measure when floating, "100%" in sheet mode. */
+  width?: number | string;
+  onItemPress: (item: NotificationItem) => void;
+  onMarkAllRead: () => void;
+}
+
+function NotificationRow({ item, onPress }: { item: NotificationItem; onPress: () => void }) {
+  const { t } = useTranslation(BACKOFFICE_I18N_NAMESPACE);
+  const subject = item.subjectText || t("notifications.untitled", "Notification");
+  const relative = formatRelativeTimestamp(item.timestampMs ?? item.creation);
+  return (
+    <XStack
+      alignItems="flex-start"
+      gap="$3"
+      paddingHorizontal="$3"
+      paddingVertical="$2.5"
+      backgroundColor={item.unread ? "$color2" : "transparent"}
+      hoverStyle={{ backgroundColor: "$color3" }}
+      pressStyle={{ backgroundColor: "$color4" }}
+      cursor="pointer"
+      onPress={onPress}
+      role="button"
+      aria-label={subject}
+      data-testid="backoffice-notification-row"
+    >
+      <Avatar name={item.from_user || "?"} size="$2.5" />
+      <YStack flex={1} minWidth={0} gap="$1">
+        <Text
+          fontSize="$3"
+          fontWeight={item.unread ? "600" : "400"}
+          color={item.unread ? "$color12" : "$color11"}
+          numberOfLines={2}
+        >
+          {subject}
+        </Text>
+        {relative ? (
+          <Text fontSize="$2" color="$color9">
+            {relative}
+          </Text>
+        ) : null}
+      </YStack>
+      {item.unread && (
+        <View
+          width={8}
+          height={8}
+          borderRadius={1000}
+          backgroundColor="$accentBackground"
+          marginTop="$1.5"
+          flexShrink={0}
+          aria-hidden
+        />
+      )}
+    </XStack>
+  );
+}
+
+function NotificationSkeletonRows() {
+  return (
+    <YStack data-testid="backoffice-notifications-loading">
+      {Array.from({ length: 3 }, (_, index) => (
+        <XStack
+          key={index}
+          alignItems="center"
+          gap="$3"
+          paddingHorizontal="$3"
+          paddingVertical="$2.5"
+        >
+          <SkeletonCircle size={28} />
+          <YStack flex={1} gap="$1.5">
+            <Skeleton height={12} width="85%" />
+            <Skeleton height={10} width={64} />
+          </YStack>
+        </XStack>
+      ))}
+    </YStack>
+  );
+}
+
+export function NotificationsPanel({
+  items,
+  isLoading,
+  width,
+  onItemPress,
+  onMarkAllRead,
+}: NotificationsPanelProps) {
+  const { t } = useTranslation(BACKOFFICE_I18N_NAMESPACE);
+  const hasUnread = items.some((item) => item.unread);
+
+  return (
+    <YStack
+      width={width}
+      maxWidth="100%"
+      paddingVertical="$2"
+      data-testid="backoffice-notifications-panel"
+    >
+      <XStack alignItems="center" gap="$2" paddingHorizontal="$3" paddingBottom="$2">
+        <SizableText size="$4" fontWeight="700" flex={1} numberOfLines={1}>
+          {t("notifications.title", "Notifications")}
+        </SizableText>
+        <Button
+          chromeless
+          size="$2"
+          disabled={!hasUnread}
+          opacity={hasUnread ? 1 : 0.5}
+          onPress={onMarkAllRead}
+          data-testid="backoffice-notifications-mark-all"
+        >
+          {t("notifications.markAllRead", "Mark all as read")}
+        </Button>
+        {/* Desk links to /app/notification-settings; the backoffice has no
+            settings surface yet — disabled placeholder documents the gap. */}
+        <Button
+          chromeless
+          circular
+          size="$2"
+          icon={GearSixIcon}
+          disabled
+          opacity={0.5}
+          aria-label={t(
+            "notifications.settingsUnavailable",
+            "Notification settings (not available yet)",
+          )}
+        />
+      </XStack>
+      <Separator />
+      {isLoading ? (
+        <NotificationSkeletonRows />
+      ) : items.length === 0 ? (
+        <EmptyState
+          compact
+          paddingVertical="$6"
+          title={t("notifications.emptyTitle", "No new notifications")}
+          description={t(
+            "notifications.emptyDescription",
+            "Mentions, assignments, and shares will show up here.",
+          )}
+        />
+      ) : (
+        <YStack>
+          {items.map((item) => (
+            <NotificationRow key={item.name} item={item} onPress={() => onItemPress(item)} />
+          ))}
+        </YStack>
+      )}
+    </YStack>
+  );
+}

package/src/chrome/notifications-utils.tsx

@@ -0,0 +1,44 @@
+/**
+ * Tiny pure helpers for the notifications panel. Notification Log subjects
+ * arrive as HTML fragments ('<b>Jane</b> mentioned you in <a>…</a>') and
+ * timestamps in frappe's "YYYY-MM-DD HH:mm:ss.ffffff" register.
+ */
+
+/**
+ * Strip HTML tags from a Notification Log subject and return readable text.
+ * Closing block tags / <br> become spaces so "<div>a</div><div>b</div>"
+ * reads "a b"; basic entities are decoded (&amp; last so "&amp;lt;" stays
+ * literal "&lt;"); whitespace collapses to single spaces.
+ */
+export function stripHtmlToText(html: string | null | undefined): string {
+  if (!html) return "";
+  const withBreaks = html.replace(/<\s*(?:br|\/p|\/div|\/li|\/tr|\/h[1-6])\s*\/?\s*>/gi, " ");
+  const withoutTags = withBreaks.replace(/<[^>]*>/g, "");
+  const decoded = withoutTags
+    .replace(/&nbsp;/gi, " ")
+    .replace(/&lt;/gi, "<")
+    .replace(/&gt;/gi, ">")
+    .replace(/&quot;/gi, '"')
+    .replace(/&#39;|&apos;/gi, "'")
+    .replace(/&amp;/gi, "&");
+  return decoded.replace(/\s+/g, " ").trim();
+}
+
+/**
+ * Parse a frappe timestamp ("2026-08-12 09:34:09.025850") to epoch ms.
+ * The space separator and microsecond precision trip Safari/JSC, so
+ * normalize to ISO-ish ("T" separator, milliseconds) before Date parsing.
+ * Frappe emits server-local wall time with no zone; parsing as local time
+ * matches how desk renders it. Unparseable input → undefined.
+ */
+export function parseFrappeTimestamp(value: string | null | undefined): number | undefined {
+  if (!value) return undefined;
+  const isoish = value
+    .trim()
+    .replace(" ", "T")
+    .replace(/(\.\d{3})\d+$/, "$1");
+  const parsed = new Date(isoish).getTime();
+  if (!Number.isNaN(parsed)) return parsed;
+  const fallback = new Date(value).getTime();
+  return Number.isNaN(fallback) ? undefined : fallback;
+}

package/src/chrome/shortcuts.ts

@@ -0,0 +1,53 @@
+/**
+ * Global backoffice keyboard shortcuts (web only).
+ *
+ * INTEGRATION: the shell (user-owned) should call this once near the root of
+ * the desk chrome and wire `onFocusSearch` to the awesomebar, e.g.:
+ *
+ *   useBackofficeShortcuts({ onFocusSearch: () => focusAwesomebar() });
+ *
+ * Bindings (keep chrome/help-shortcuts-dialog.tsx in sync):
+ *   - Mod+K / Mod+G → onFocusSearch (opens the command palette)
+ *
+ * SSR / native / GJS safe: no-ops when there is no DOM document. Events from
+ * editable targets (inputs, textareas, selects, contenteditable) are ignored
+ * so typing is never hijacked. Cleans up its listener on unmount.
+ */
+import { useEffect, useRef } from "react";
+
+export interface BackofficeShortcutHandlers {
+  /** Focus the awesomebar / global search (Mod+K, Mod+G). */
+  onFocusSearch?: () => void;
+}
+
+function isEditableTarget(target: EventTarget | null): boolean {
+  if (typeof HTMLElement === "undefined" || !(target instanceof HTMLElement)) return false;
+  if (target.isContentEditable) return true;
+  const tag = target.tagName;
+  return tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT";
+}
+
+export function useBackofficeShortcuts(handlers: BackofficeShortcutHandlers): void {
+  // Ref keeps the listener stable while consumers pass inline handler objects.
+  const handlersRef = useRef(handlers);
+  handlersRef.current = handlers;
+
+  useEffect(() => {
+    if (typeof document === "undefined" || typeof document.addEventListener !== "function") {
+      return;
+    }
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (!(event.metaKey || event.ctrlKey) || event.altKey || event.shiftKey) return;
+      if (event.repeat || isEditableTarget(event.target)) return;
+      const key = event.key.toLowerCase();
+      if (key === "k" || key === "g") {
+        const { onFocusSearch } = handlersRef.current;
+        if (!onFocusSearch) return;
+        event.preventDefault();
+        onFocusSearch();
+      }
+    };
+    document.addEventListener("keydown", onKeyDown);
+    return () => document.removeEventListener("keydown", onKeyDown);
+  }, []);
+}

package/src/chrome/user-session.tsx

@@ -0,0 +1,116 @@
+import React from "react";
+/**
+ * Session-user info for the navbar user menu, module-cached so the avatar
+ * button and the menu header fetch once per session (per FrappeApp).
+ *
+ * Flow (one cached promise): frappe.auth.get_logged_user →
+ * frappe.client.get_value(User, <name>, ["full_name","user_image","email"]).
+ */
+import type { FrappeApp } from "@multiplatform.one/frappe";
+import { useFrappeConfig } from "@multiplatform.one/frappe-ui";
+import { useEffect, useMemo, useState } from "react";
+import { useFrappeApp } from "../shared/useFrappeApp";
+
+export interface SessionUserInfo {
+  /** Session user docname (e.g. "Administrator" or an email login). */
+  user: string;
+  fullName: string;
+  email?: string;
+  /** Absolute avatar URL (User.user_image resolved against the bench). */
+  imageUrl?: string;
+}
+
+interface UserDocBits {
+  full_name?: string;
+  user_image?: string | null;
+  email?: string;
+}
+
+// Keyed by FrappeApp instance: a different bench/auth config gets its own
+// entry (useFrappeApp memoizes apps per config). Failed fetches self-evict
+// so the next mount retries.
+let sessionCache = new WeakMap<FrappeApp, Promise<SessionUserInfo>>();
+
+/** Logout hygiene: drops every cached session-user fetch in this module. */
+export function clearSessionUserCache(): void {
+  sessionCache = new WeakMap();
+}
+
+/** Resolve a User.user_image value (usually "/files/…") to an absolute URL. */
+export function resolveUserImageUrl(
+  userImage: string | null | undefined,
+  baseURL: string,
+): string | undefined {
+  if (!userImage) return undefined;
+  // Already absolute (http(s), data:, blob:, …) — leave untouched.
+  if (/^[a-z][a-z0-9+.-]*:/i.test(userImage)) return userImage;
+  return `${baseURL.replace(/\/+$/, "")}${userImage.startsWith("/") ? "" : "/"}${userImage}`;
+}
+
+async function fetchSessionUserInfo(app: FrappeApp, baseURL: string): Promise<SessionUserInfo> {
+  const user = await app.auth().getLoggedInUser();
+  if (!user) throw new Error("No session user");
+  // Param format probed against the bench: filters takes the plain docname,
+  // fieldname a JSON array (the http client JSON-encodes non-string params).
+  const res = await app.call().get<{ message?: UserDocBits }>("frappe.client.get_value", {
+    doctype: "User",
+    filters: user,
+    fieldname: ["full_name", "user_image", "email"],
+  });
+  const bits = res.payload?.message ?? {};
+  return {
+    user,
+    fullName: bits.full_name || user,
+    email: bits.email || (user.includes("@") ? user : undefined),
+    imageUrl: resolveUserImageUrl(bits.user_image, baseURL),
+  };
+}
+
+/** Module-cached session-user info from the ambient Frappe connection. */
+export function useSessionUserInfo(): {
+  info?: SessionUserInfo;
+  loading: boolean;
+  error?: Error;
+} {
+  const app = useFrappeApp();
+  const config = useFrappeConfig();
+  const baseURL = config?.baseURL ?? "";
+  const [info, setInfo] = useState<SessionUserInfo | undefined>(undefined);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error | undefined>(undefined);
+
+  useEffect(() => {
+    if (!app) {
+      setInfo(undefined);
+      setLoading(false);
+      return;
+    }
+    let cancelled = false;
+    let promise = sessionCache.get(app);
+    if (!promise) {
+      promise = fetchSessionUserInfo(app, baseURL);
+      sessionCache.set(app, promise);
+      promise.catch(() => {
+        if (sessionCache.get(app) === promise) sessionCache.delete(app);
+      });
+    }
+    setLoading(true);
+    setError(undefined);
+    promise
+      .then((value) => {
+        if (cancelled) return;
+        setInfo(value);
+        setLoading(false);
+      })
+      .catch((err: Error) => {
+        if (cancelled) return;
+        setError(err);
+        setLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [app, baseURL]);
+
+  return useMemo(() => ({ info, loading, error }), [info, loading, error]);
+}