@micha.bigler/ui-core-micha 2.12.0 → 2.14.0

package/src/notifications/NotificationsProvider.jsx

@@ -2,9 +2,7 @@ import { createContext, useCallback, useContext, useEffect, useRef, useState } f
 
 import { AuthContext } from '../auth/AuthContext';
 import { getNotificationFeed, getUnreadCount, markNotifications } from './feedApi';
-
-const INITIAL_BACKOFF_MS = 1_000;
-const MAX_BACKOFF_MS = 30_000;
+import { DEFAULT_ENVELOPE, RealtimeContext, useRealtimeCore } from './realtime';
 
 const NotificationsContext = createContext(null);
 
@@ -62,7 +60,6 @@ export function NotificationsProvider({ children, wsUrlBase }) {
   const [notifications, setNotifications] = useState([]);
   const [unreadCount, setUnreadCount] = useState(0);
   const notificationsRef = useRef([]);
-  const socketRef = useRef(null);
 
   const replaceNotifications = useCallback((nextNotifications) => {
     notificationsRef.current = nextNotifications;
@@ -84,99 +81,92 @@ export function NotificationsProvider({ children, wsUrlBase }) {
     return { notifications: nextNotifications, unreadCount: nextUnreadCount };
   }, [authenticated, replaceNotifications]);
 
-  useEffect(() => {
-    if (!authenticated) {
-      replaceNotifications([]);
-      setUnreadCount(0);
-      return undefined;
-    }
-
-    let active = true;
-    let reconnectTimer = null;
-    let backoffMs = INITIAL_BACKOFF_MS;
+  // Seeded gates the socket connect, not just `authenticated`: the prior single-purpose
+  // socket owner awaited the initial REST feed/unread-count fetch before opening the
+  // WebSocket, so a live push could never race an empty/incomplete `notificationsRef`.
+  // Preserved here rather than connecting immediately, since `refresh()`'s
+  // `replaceNotifications(...)` is unconditional and would silently drop a message that
+  // arrived and patched state before the initial REST response landed.
+  const [seeded, setSeeded] = useState(false);
+
+  const { subscribe } = useRealtimeCore({
+    active: authenticated && seeded,
+    wsUrl: getWebSocketUrl(wsUrlBase),
+  });
 
-    const patchNotifications = (updater) => {
-      const nextNotifications = updater(notificationsRef.current);
+  const handleRealtimeMessage = useCallback((data) => {
+    if (data.type === 'notification.status') {
+      let unreadDelta = 0;
+      const nextNotifications = notificationsRef.current.map((notification) => {
+        if (notification.notification_id !== data.notification_id) return notification;
+
+        const wasUnread = !notification.seen && !notification.dismissed;
+        const patched = patchStatus(notification, data.status || {});
+        const isUnread = !patched.seen && !patched.dismissed;
+        if (wasUnread !== isUnread) {
+          unreadDelta += isUnread ? 1 : -1;
+        }
+        return patched;
+      });
       replaceNotifications(nextNotifications);
-    };
-
-    const handleMessage = (event) => {
-      let data;
-      try {
-        data = JSON.parse(event.data);
-      } catch {
-        return;
+      if (unreadDelta) {
+        setUnreadCount((count) => Math.max(0, count + unreadDelta));
       }
+      return;
+    }
 
-      if (data.type === 'notification.status') {
-        let unreadDelta = 0;
-        patchNotifications((current) => current.map((notification) => {
-          if (notification.notification_id !== data.notification_id) return notification;
-
-          const wasUnread = !notification.seen && !notification.dismissed;
-          const patched = patchStatus(notification, data.status || {});
-          const isUnread = !patched.seen && !patched.dismissed;
-          if (wasUnread !== isUnread) {
-            unreadDelta += isUnread ? 1 : -1;
-          }
-          return patched;
-        }));
-        if (unreadDelta) {
-          setUnreadCount((count) => Math.max(0, count + unreadDelta));
-        }
-        return;
-      }
+    const pushedNotification = normalizeNotificationPush(data);
+
+    // NOTIF-12 D2: a notification routed to more than one channel (e.g. chip
+    // + popup) arrives as multiple WS messages sharing one notification_id.
+    // Fold repeats into the existing feed entry (last-write-wins on content)
+    // instead of appending a duplicate and double-incrementing the badge.
+    const existingIndex = pushedNotification.notification_id == null
+      ? -1
+      : notificationsRef.current.findIndex(
+        (notification) => notification.notification_id === pushedNotification.notification_id,
+      );
+
+    if (existingIndex !== -1) {
+      const nextNotifications = notificationsRef.current.map((notification, index) => (
+        index === existingIndex
+          ? { ...notification, notification_type: pushedNotification.notification_type, content: pushedNotification.content }
+          : notification
+      ));
+      replaceNotifications(nextNotifications);
+      return;
+    }
 
-      const pushedNotification = normalizeNotificationPush(data);
-      patchNotifications((current) => [pushedNotification, ...current]);
-      setUnreadCount((count) => count + 1);
-    };
+    replaceNotifications([pushedNotification, ...notificationsRef.current]);
+    setUnreadCount((count) => count + 1);
+  }, [replaceNotifications]);
 
-    const connect = () => {
-      if (!active || socketRef.current) return;
-
-      const socket = new WebSocket(getWebSocketUrl(wsUrlBase));
-      socketRef.current = socket;
-
-      socket.onopen = () => {
-        backoffMs = INITIAL_BACKOFF_MS;
-      };
-      socket.onmessage = handleMessage;
-      socket.onerror = () => {
-        socket.close();
-      };
-      socket.onclose = () => {
-        if (socketRef.current === socket) {
-          socketRef.current = null;
-        }
-        if (!active || reconnectTimer) return;
-        reconnectTimer = setTimeout(() => {
-          reconnectTimer = null;
-          connect();
-        }, backoffMs);
-        backoffMs = Math.min(backoffMs * 2, MAX_BACKOFF_MS);
-      };
-    };
+  useEffect(() => {
+    if (!authenticated) return undefined;
+    return subscribe(DEFAULT_ENVELOPE, handleRealtimeMessage);
+  }, [authenticated, subscribe, handleRealtimeMessage]);
 
-    const seedAndConnect = async () => {
-      try {
-        await refresh();
-      } catch {
-        // The live stream remains useful if the initial REST request is temporarily unavailable.
-      }
-      if (active) connect();
-    };
+  useEffect(() => {
+    if (!authenticated) {
+      replaceNotifications([]);
+      setUnreadCount(0);
+      setSeeded(false);
+      return undefined;
+    }
 
-    seedAndConnect();
+    let cancelled = false;
+    refresh()
+      .catch(() => {
+        // The live stream remains useful if the initial REST request is temporarily unavailable.
+      })
+      .finally(() => {
+        if (!cancelled) setSeeded(true);
+      });
 
     return () => {
-      active = false;
-      clearTimeout(reconnectTimer);
-      const socket = socketRef.current;
-      socketRef.current = null;
-      if (socket) socket.close();
+      cancelled = true;
     };
-  }, [authenticated, refresh, replaceNotifications, wsUrlBase]);
+  }, [authenticated, refresh, replaceNotifications]);
 
   const mark = useCallback((action, ids) => {
     const selectedIds = Array.isArray(ids) ? ids : [];
@@ -210,16 +200,18 @@ export function NotificationsProvider({ children, wsUrlBase }) {
   const markDone = useCallback((ids) => mark('done', ids), [mark]);
 
   return (
-    <NotificationsContext.Provider value={{
-      notifications,
-      unreadCount,
-      markSeen,
-      markDismissed,
-      markDone,
-      refresh,
-    }}>
-      {children}
-    </NotificationsContext.Provider>
+    <RealtimeContext.Provider value={{ subscribe }}>
+      <NotificationsContext.Provider value={{
+        notifications,
+        unreadCount,
+        markSeen,
+        markDismissed,
+        markDone,
+        refresh,
+      }}>
+        {children}
+      </NotificationsContext.Provider>
+    </RealtimeContext.Provider>
   );
 }
 

package/src/notifications/PopupSurface.jsx

@@ -0,0 +1,103 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import Button from '@mui/material/Button';
+import Stack from '@mui/material/Stack';
+import Typography from '@mui/material/Typography';
+import { useOnboarding } from '../onboarding/OnboardingProvider';
+import { WizardDialogShell } from '../onboarding/WizardDialogShell';
+import { useNotifications } from './NotificationsProvider';
+import { DEFAULT_ENVELOPE, useRealtime } from './realtime';
+
+function PopupStepComponent({ onDismiss, ctx }) {
+  const { t } = useTranslation();
+  const content = ctx?.content || {};
+
+  return (
+    <Stack spacing={2}>
+      {content.body_key && (
+        <Typography variant="body1">{t(content.body_key, content.params || {})}</Typography>
+      )}
+      <Button onClick={onDismiss} sx={{ alignSelf: 'flex-end' }}>
+        {t('PopupSurface.CLOSE')}
+      </Button>
+    </Stack>
+  );
+}
+
+const POPUP_STEP = { blocking: false, Component: PopupStepComponent };
+
+/**
+ * Renders popup-eligible notifications (NOTIF-12) through the onboarding
+ * wizard's dialog shell, reusing only the renderer (design D-F7) — status
+ * lives on NotificationRecipient via the existing feed/mark path, never in
+ * the onboarding progress store.
+ *
+ * Deliberately session-live only: it watches the raw realtime stream for
+ * `channel === "popup"` messages rather than the already-seeded feed list,
+ * since the feed carries no per-channel discriminator (see NotificationsProvider).
+ */
+export function PopupSurface() {
+  const { t } = useTranslation();
+  const { markSeen, markDismissed } = useNotifications();
+  const { subscribe } = useRealtime();
+  const onboarding = useOnboarding();
+  const [queue, setQueue] = useState([]);
+  const seenIdsRef = useRef(new Set());
+
+  const handleRealtimeMessage = useCallback((data) => {
+    if (data.type === 'notification.status') return;
+    if (data.channel !== 'popup') return;
+    setQueue((previous) => {
+      if (previous.some((item) => item.notification_id === data.notification_id)) return previous;
+      return [...previous, {
+        notification_id: data.notification_id,
+        // recipient_id is the id feed/mark/ actually resolves against
+        // (NotificationRecipient.pk, not Notification.pk). Fall back to
+        // notification_id only for an older dcm that predates it — matching
+        // NotificationsProvider's own normalizeNotificationPush precedent.
+        markId: data.recipient_id ?? data.notification_id,
+        content: data.content || {},
+      }];
+    });
+  }, []);
+
+  useEffect(() => subscribe(DEFAULT_ENVELOPE, handleRealtimeMessage), [subscribe, handleRealtimeMessage]);
+
+  // Any active onboarding step — blocking or not — must win: OnboardingWizard
+  // renders its own dialog for as long as onboarding.activeSteps is non-empty,
+  // and two independent MUI Dialogs must never be mounted at once.
+  const onboardingActive = Boolean(onboarding?.activeSteps?.length);
+  const activePopup = queue[0];
+
+  useEffect(() => {
+    if (!activePopup || onboardingActive) return;
+    if (activePopup.markId == null) return;
+    if (seenIdsRef.current.has(activePopup.notification_id)) return;
+    seenIdsRef.current.add(activePopup.notification_id);
+    markSeen([activePopup.markId]);
+  }, [activePopup, onboardingActive, markSeen]);
+
+  const dismissActivePopup = useCallback(() => {
+    if (!activePopup) return;
+    if (activePopup.markId != null) markDismissed([activePopup.markId]);
+    setQueue((previous) => previous.filter((item) => item.notification_id !== activePopup.notification_id));
+  }, [activePopup, markDismissed]);
+
+  if (!activePopup || onboardingActive) return null;
+
+  return (
+    <WizardDialogShell
+      step={POPUP_STEP}
+      stepIndex={0}
+      total={1}
+      onComplete={dismissActivePopup}
+      onDismiss={dismissActivePopup}
+      ctx={{ content: activePopup.content }}
+      title={activePopup.content.title_key
+        ? t(activePopup.content.title_key, activePopup.content.params || {})
+        : t('PopupSurface.TITLE')}
+    />
+  );
+}
+
+export default PopupSurface;

package/src/notifications/realtime.jsx

@@ -0,0 +1,118 @@
+import { createContext, useCallback, useContext, useEffect, useRef } from 'react';
+
+const INITIAL_BACKOFF_MS = 1_000;
+const MAX_BACKOFF_MS = 30_000;
+
+// Envelope discriminator for the notifications domain. A message with no
+// `envelope` field (pre-NOTIF-13 dcm) is treated as this default so an
+// un-bumped backend keeps working unchanged (backward-compat).
+export const DEFAULT_ENVELOPE = 'notification';
+
+const RealtimeContext = createContext(null);
+
+export function useRealtime() {
+  const context = useContext(RealtimeContext);
+  if (!context) {
+    throw new Error('useRealtime must be used within a NotificationsProvider');
+  }
+  return context;
+}
+
+export { RealtimeContext };
+
+/**
+ * Owns the single WebSocket connection and an envelope-keyed subscriber
+ * registry. Internal — consumed only by NotificationsProvider, which
+ * re-exposes `subscribe` via RealtimeContext so useRealtime() works without
+ * a separate provider apps have to mount.
+ *
+ * Backoff, reconnect, and cleanup semantics are unchanged from the prior
+ * single-purpose socket owner. `active`/`wsUrl` are primitives, so the
+ * effect does not re-run (and does not reconnect) on unrelated re-renders.
+ */
+export function useRealtimeCore({ active, wsUrl }) {
+  const socketRef = useRef(null);
+  const subscribersRef = useRef(new Map());
+
+  const subscribe = useCallback((envelope, handler) => {
+    const subscribers = subscribersRef.current;
+    if (!subscribers.has(envelope)) {
+      subscribers.set(envelope, new Set());
+    }
+    subscribers.get(envelope).add(handler);
+    return () => {
+      const handlers = subscribers.get(envelope);
+      if (!handlers) return;
+      handlers.delete(handler);
+      if (handlers.size === 0) {
+        subscribers.delete(envelope);
+      }
+    };
+  }, []);
+
+  useEffect(() => {
+    if (!active) return undefined;
+
+    let isActive = true;
+    let reconnectTimer = null;
+    let backoffMs = INITIAL_BACKOFF_MS;
+
+    const handleMessage = (event) => {
+      let data;
+      try {
+        data = JSON.parse(event.data);
+      } catch {
+        return;
+      }
+
+      const envelope = data.envelope ?? DEFAULT_ENVELOPE;
+      const handlers = subscribersRef.current.get(envelope);
+      if (!handlers || handlers.size === 0) return;
+      handlers.forEach((handler) => {
+        try {
+          handler(data);
+        } catch (error) {
+          console.error('Realtime subscriber error', error);
+        }
+      });
+    };
+
+    const connect = () => {
+      if (!isActive || socketRef.current) return;
+
+      const socket = new WebSocket(wsUrl);
+      socketRef.current = socket;
+
+      socket.onopen = () => {
+        backoffMs = INITIAL_BACKOFF_MS;
+      };
+      socket.onmessage = handleMessage;
+      socket.onerror = () => {
+        socket.close();
+      };
+      socket.onclose = () => {
+        if (socketRef.current === socket) {
+          socketRef.current = null;
+        }
+        if (!isActive || reconnectTimer) return;
+        reconnectTimer = setTimeout(() => {
+          reconnectTimer = null;
+          connect();
+        }, backoffMs);
+        backoffMs = Math.min(backoffMs * 2, MAX_BACKOFF_MS);
+      };
+    };
+
+    connect();
+
+    return () => {
+      isActive = false;
+      clearTimeout(reconnectTimer);
+      const socket = socketRef.current;
+      socketRef.current = null;
+      if (socket) socket.close();
+    };
+  }, [active, wsUrl]);
+
+  return { subscribe };
+}

package/src/onboarding/OnboardingWizard.jsx

@@ -1,16 +1,9 @@
 import React, { useContext, useEffect, useRef, useState } from 'react';
-import { useTranslation } from 'react-i18next';
-import Box from '@mui/material/Box';
-import Dialog from '@mui/material/Dialog';
-import DialogContent from '@mui/material/DialogContent';
-import DialogTitle from '@mui/material/DialogTitle';
-import LinearProgress from '@mui/material/LinearProgress';
-import Typography from '@mui/material/Typography';
 import { AuthContext } from '../auth/AuthContext';
 import { useOnboarding } from './OnboardingProvider';
+import { WizardDialogShell } from './WizardDialogShell';
 
 export function OnboardingWizard() {
-  const { t } = useTranslation();
   const onboarding = useOnboarding();
   const authContext = useContext(AuthContext);
   const [sessionDismissed, setSessionDismissed] = useState(() => new Set());
@@ -39,8 +32,6 @@ export function OnboardingWizard() {
 
   const { dismissStep, ctx } = onboarding;
   const total = totalRef.current || visibleSteps.length;
-  const progress = total > 1 ? Math.round((completed / total) * 100) : 0;
-  const StepComponent = currentStep.Component;
 
   const completeCurrentStep = () => {
     setSessionDismissed((previous) => new Set([...previous, currentStep.id]));
@@ -56,19 +47,14 @@ export function OnboardingWizard() {
   };
 
   return (
-    <Dialog open fullWidth maxWidth="sm" disableEscapeKeyDown={currentStep.blocking} onClose={currentStep.blocking ? undefined : dismissCurrentStep}>
-      <DialogTitle sx={{ pb: 0 }}>
-        <Box sx={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}>
-          <Typography variant="subtitle2" color="text.secondary">
-            {total > 1 ? t('Onboarding.STEP_COUNTER', { current: completed + 1, total }) : t('Onboarding.SETUP')}
-          </Typography>
-        </Box>
-        {total > 1 && <LinearProgress variant="determinate" value={progress} sx={{ mt: 1, borderRadius: 1 }} />}
-      </DialogTitle>
-      <DialogContent sx={{ pt: 2 }}>
-        <StepComponent onComplete={completeCurrentStep} onDismiss={dismissCurrentStep} ctx={ctx} />
-      </DialogContent>
-    </Dialog>
+    <WizardDialogShell
+      step={currentStep}
+      stepIndex={completed}
+      total={total}
+      onComplete={completeCurrentStep}
+      onDismiss={dismissCurrentStep}
+      ctx={ctx}
+    />
   );
 }
 

package/src/onboarding/WizardDialogShell.jsx

@@ -0,0 +1,51 @@
+import React from 'react';
+import { useTranslation } from 'react-i18next';
+import Box from '@mui/material/Box';
+import Dialog from '@mui/material/Dialog';
+import DialogContent from '@mui/material/DialogContent';
+import DialogTitle from '@mui/material/DialogTitle';
+import LinearProgress from '@mui/material/LinearProgress';
+import Typography from '@mui/material/Typography';
+
+/**
+ * Presentational dialog shell shared by OnboardingWizard and the popup
+ * notification surface (NOTIF-12). Owns only the dialog frame, the
+ * counter/progress header, and the onComplete/onDismiss/ctx child contract —
+ * step selection, dismissal persistence, and any progress store stay with
+ * the caller.
+ */
+export function WizardDialogShell({ step, stepIndex, total, onComplete, onDismiss, ctx, title }) {
+  const { t } = useTranslation();
+  const progress = total > 1 ? Math.round((stepIndex / total) * 100) : 0;
+  const StepComponent = step.Component;
+  // `title` lets a non-onboarding caller (e.g. the popup surface) supply its
+  // own header instead of the onboarding-specific step counter/"Setup" copy.
+  // Omitted by OnboardingWizard, so its header text is unchanged.
+  const headerLabel = title ?? (total > 1
+    ? t('Onboarding.STEP_COUNTER', { current: stepIndex + 1, total })
+    : t('Onboarding.SETUP'));
+
+  return (
+    <Dialog
+      open
+      fullWidth
+      maxWidth="sm"
+      disableEscapeKeyDown={step.blocking}
+      onClose={step.blocking ? undefined : onDismiss}
+    >
+      <DialogTitle sx={{ pb: 0 }}>
+        <Box sx={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}>
+          <Typography variant="subtitle2" color="text.secondary">
+            {headerLabel}
+          </Typography>
+        </Box>
+        {total > 1 && <LinearProgress variant="determinate" value={progress} sx={{ mt: 1, borderRadius: 1 }} />}
+      </DialogTitle>
+      <DialogContent sx={{ pt: 2 }}>
+        <StepComponent onComplete={onComplete} onDismiss={onDismiss} ctx={ctx} />
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+export default WizardDialogShell;

package/tests/NotificationsProvider.test.jsx

@@ -136,6 +136,7 @@ describe('NotificationsProvider', () => {
   it('decrements unread count on a cross-tab status push and does not double-count a repeat push', async () => {
     renderProvider();
     await waitFor(() => expect(screen.getByTestId('unread-count').textContent).toBe('2'));
+    await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1));
 
     MockWebSocket.instances[0].onmessage({ data: JSON.stringify({
       type: 'notification.status',
@@ -194,4 +195,42 @@ describe('NotificationsProvider', () => {
     expect(currentNotifications()[0]).toEqual(expect.objectContaining({ done: true }));
     expect(feedApi.markNotifications).toHaveBeenCalledWith({ action: 'done', ids: [1] });
   });
+
+  it('folds two WS messages for the same notification_id into one feed entry with a single unread increment (NOTIF-12 D2)', async () => {
+    renderProvider();
+    await waitFor(() => expect(screen.getByTestId('unread-count').textContent).toBe('2'));
+    await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1));
+
+    MockWebSocket.instances[0].onmessage({ data: JSON.stringify({
+      type: 'payment_due',
+      channel: 'chip',
+      notification_id: 404,
+      content: { title_key: 'chip.title' },
+    }) });
+    await waitFor(() => expect(screen.getByTestId('unread-count').textContent).toBe('3'));
+
+    MockWebSocket.instances[0].onmessage({ data: JSON.stringify({
+      type: 'payment_due',
+      channel: 'popup',
+      notification_id: 404,
+      content: { title_key: 'popup.title' },
+    }) });
+
+    await waitFor(() => expect(currentNotifications().find((n) => n.notification_id === 404).content)
+      .toEqual({ title_key: 'popup.title' }));
+    expect(currentNotifications().filter((n) => n.notification_id === 404)).toHaveLength(1);
+    expect(screen.getByTestId('unread-count').textContent).toBe('3');
+  });
+
+  it('NOTIF-13 R1 guard: does not open the socket until the REST seed resolves', async () => {
+    let resolveFeed;
+    feedApi.getNotificationFeed.mockReturnValue(new Promise((resolve) => { resolveFeed = resolve; }));
+
+    renderProvider();
+
+    expect(MockWebSocket.instances).toHaveLength(0);
+
+    resolveFeed({ results: [] });
+    await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1));
+  });
 });