@wildo-ai/saas-frontend-lib 1.1.3 → 1.1.5

package/dist/esm/core/events/NotificationContext.js

@@ -19,11 +19,13 @@ import { toast } from './toast.js';
 import { useEventBus } from './useEventBus.js';
 import { FrontendEvents, } from './events.frontend.schemas.js';
 import { LoggerFrontendService } from '../../core/monitoring/logger.frontend.service.js';
+import { userNotificationTargetIsSuppressibleByRecipientPreference } from '@wildo-ai/saas-models';
 import { APP_LEVEL_NAVIGATION_SOURCE } from '../../core/navigation/navigation.schemas.js';
 import { FrontendResourceUtils } from '../../core/resources/frontend-resource.utils.js';
-import { FrontendComponentType } from '@wildo-ai/presets-components-models';
+import { FrontendComponentType, LabellingTypes } from '@wildo-ai/presets-components-models';
 import { useI18n } from '../../core/i18n/useI18n.js';
-import { getNotificationDisplayBehavior, getDefaultNotificationMessage, } from './notification-display-policy.frontend.schemas.js';
+import { resolveErrorReferenceLabel, resolveRefusalCodeLabel } from '../../core/errors/user-facing-error-message.frontend.utils.js';
+import { getNotificationDisplayBehavior, } from './notification-display-policy.frontend.schemas.js';
 const notifLogger = LoggerFrontendService.getLogger();
 const logDebug = notifLogger.debugByType('NotificationContext');
 notifLogger.setDebugTypeLogging('NotificationContext', false);
@@ -69,11 +71,68 @@ function notificationReducer(state, action) {
             return state;
     }
 }
+/**
+ * Did an i18n lookup actually RESOLVE, or answer with its own key path?
+ *
+ * Every `t*` in this file returns the full key when the label is not authored — that is the
+ * missing-looks-missing contract — so "resolved" is decided by comparing the answer against the
+ * key's namespace. That decision was written out FOUR times against two different prefixes, which
+ * is how the two halves of one rule come to disagree: a fifth caller, or a namespace rename, only
+ * has to miss one copy.
+ *
+ * Named here so the next reader inherits it rather than re-deriving it, and so the comparison is
+ * stated once. It is deliberately a namespace test and not `answer === key`: the callers pass an
+ * identifier, while the unresolved answer is the full dotted path built from it.
+ *
+ * The EMPTY answer is unresolved too. A label-family resolver answers `''` while its bundle is still
+ * in flight (#1450), and this provider never requests `resources.<type>` itself — so a websocket
+ * notification about an off-screen resource can ask for an operation title nobody has loaded. Read
+ * as "resolved", that `''` became the toast's whole message, in place of the authored default.
+ */
+function resolvedLabelOrNull(answer, keyNamespace) {
+    return answer === '' || answer.startsWith(`${keyNamespace}.`) ? null : answer;
+}
+/**
+ * The milestone label a notification about a milestone should show, or `null` when the
+ * notification is NOT about a milestone.
+ *
+ * The subject is read from `data.milestoneRef`, which both milestone emitters in `GuidanceContext`
+ * set. An UNAUTHORED label is returned as its raw key, not as `null`: `null` would fall through to
+ * the generic "Action completed successfully.", which is invented text standing in for a missing
+ * label — the gap would look finished and nobody would author it
+ * (`.claude/rules/display-text-comes-from-i18n.md`). The labelling planner generates these keys for
+ * every declared milestone, so a raw key here means generation has not run.
+ *
+ * Exported for its unit pin.
+ */
+export function resolveMilestoneLabel(data, lookup) {
+    const milestoneRef = data?.milestoneRef;
+    if (typeof milestoneRef !== 'string' || milestoneRef.length === 0)
+        return null;
+    return lookup(milestoneRef);
+}
 export const NotificationContext = createContext(undefined);
 function generateNotificationId() {
     return `notification-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
 }
 const CELEBRATION_AUTO_DISMISS_MS = 5000;
+/**
+ * A CEILING for a celebration that asks for a decision, not a policy for it.
+ *
+ * That branch deliberately has no auto-dismiss — it is modal, it takes focus, and vanishing
+ * mid-read after five seconds is the defect the conditional timer below exists to fix. But its only
+ * remaining exits are user interactions, and every one of them is LAYER-CONDITIONAL: Radix delivers
+ * Escape to the topmost layer, refuses an outside press while a higher layer disables outside
+ * pointer events, and sets the buried layer's own `pointer-events: none` so its dismiss button
+ * cannot be clicked. Radix's layer set is a module-level global, so this composes across
+ * independently-portaled dialogs.
+ *
+ * So a celebration with a next step, buried under a dialog that mounts above it, was visible and
+ * unreachable — and nothing else clears it, including a route change. Two minutes is long enough
+ * that nobody loses a decision they were actually making, and short enough that a buried overlay
+ * does not outlive the session.
+ */
+const CELEBRATION_DECISION_MAX_LIFETIME_MS = 120_000;
 export function NotificationProvider({ children }) {
     const [state, dispatch] = useReducer(notificationReducer, initialState);
     const { on, emit } = useEventBus();
@@ -81,9 +140,11 @@ export function NotificationProvider({ children }) {
     const [celebration, setCelebration] = useState({ isActive: false });
     const celebrationTimerRef = useRef(null);
     // i18n hooks
-    const { tNotificationCustom, tResourceOperation, tComponent, tErrorMessage, t, isReady } = useI18n({
+    const { tNotificationCustom, tResourceOperation, tComponent, tErrorMessage, tMilestone, tMilestoneReward, t, isReady } = useI18n({
         component: FrontendComponentType.APPLICATION_LEVEL_NOTIFICATION_CENTER,
-        keys: ['notifications_custom'],
+        // `milestones` because a milestone notification speaks with the milestone's OWN words — see
+        // `resolveMilestoneMessage`. Without it that root is never loaded here and every lookup misses.
+        keys: ['notifications_custom', LabellingTypes.MILESTONES],
     });
     // Preferences state (synced from UserOrgsContext via events)
     const [notificationsPreferences, setNotificationsPreferences] = useState(null);
@@ -92,14 +153,36 @@ export function NotificationProvider({ children }) {
     const tResourceOperationRef = useRef(tResourceOperation);
     const tComponentRef = useRef(tComponent);
     const tErrorMessageRef = useRef(tErrorMessage);
+    const tMilestoneRef = useRef(tMilestone);
+    const tMilestoneRewardRef = useRef(tMilestoneReward);
     const tRef = useRef(t);
+    /**
+     * A notification raised BEFORE the i18n bundle settles must wait for it, not render its key.
+     *
+     * `isReady` was destructured here and used nowhere — one line, no reader. Every message this
+     * provider shows ends at a `t*` call, and an unresolved label now renders the raw KEY, because
+     * the humanized fallbacks were removed (#420). That is the right contract for a label nobody
+     * authored; it is the wrong one for a label that simply has not LOADED yet, and
+     * `display-text-comes-from-i18n.md` names readiness as the thing that covers exactly that
+     * window. A toast is one-shot — there is no re-resolution when the bundle lands — so a
+     * connectivity error raised during boot was displayed as
+     * `components.APPLICATION_LEVEL_NOTIFICATION_CENTER.defaultError`, permanently.
+     *
+     * Deferring rather than dropping: the notification is still delivered, one bundle later. The
+     * queue also covers `setLanguage`, which clears the loaded keys mid-session and flips `isReady`
+     * back to false — a notification raised in that window would otherwise show keys too.
+     */
+    const isReadyRef = useRef(isReady);
+    const pendingUntilI18nReadyRef = useRef([]);
     useEffect(() => {
         tNotificationCustomRef.current = tNotificationCustom;
         tResourceOperationRef.current = tResourceOperation;
         tComponentRef.current = tComponent;
         tErrorMessageRef.current = tErrorMessage;
+        tMilestoneRef.current = tMilestone;
+        tMilestoneRewardRef.current = tMilestoneReward;
         tRef.current = t;
-    }, [tNotificationCustom, tResourceOperation, tComponent, tErrorMessage, t]);
+    }, [tNotificationCustom, tResourceOperation, tComponent, tErrorMessage, tMilestone, tMilestoneReward, t]);
     // ================================
     // Toast Display
     // ================================
@@ -182,14 +265,27 @@ export function NotificationProvider({ children }) {
             mode: celebrationHints,
             notificationIdentifier: options.notificationIdentifier,
             message: options.message,
+            heading: options.heading,
             nextStep: options.nextStep,
         });
-        // Auto-dismiss after timeout
+        /**
+         * Auto-dismiss ONLY when the celebration asks for nothing.
+         *
+         * The timer used to fire unconditionally, and `nextStep` is exactly the case it must not: the
+         * overlay is modal for that branch — it takes focus and locks the page's scroll deliberately,
+         * because the user is being asked to answer — and then vanished after five seconds, mid-read,
+         * having stolen the focus of whatever they were doing. The two halves justified each other in
+         * opposite directions: the modality's reason is "you are expected to interact with this", and
+         * the timer's is "nobody is expected to interact with this".
+         *
+         * A celebration with an action closes on that action, on its dismiss control, on Escape or on
+         * an outside click — all of which the overlay already wires.
+         */
         celebrationTimerRef.current = setTimeout(() => {
             setCelebration({ isActive: false });
             celebrationTimerRef.current = null;
-            logDebug('Celebration auto-dismissed');
-        }, CELEBRATION_AUTO_DISMISS_MS);
+            logDebug(options.nextStep ? 'Celebration reached its maximum lifetime' : 'Celebration auto-dismissed');
+        }, options.nextStep ? CELEBRATION_DECISION_MAX_LIFETIME_MS : CELEBRATION_AUTO_DISMISS_MS);
         logDebug('Celebration shown', {
             mode: celebrationHints.mode,
             identifier: options.notificationIdentifier,
@@ -208,7 +304,7 @@ export function NotificationProvider({ children }) {
     // Message Resolution
     // ================================
     /**
-     * Resolve notification message using i18n
+     * Resolve a notification's message using i18n — the LADDER, without the bulk count.
      *
      * Resolution order:
      * 1. Explicit message in options (edge case)
@@ -216,37 +312,69 @@ export function NotificationProvider({ children }) {
      * 3. Error-ref label (errors) / resource operation title (info + warning only —
      *    success and error both skip the imperative operation title, see 3a/3b)
      * 4. Default fallback message
+     *
+     * A bulk action's row COUNT is not a rung here: it quantifies whatever this answers, and
+     * {@link resolveMessage} applies it.
      */
-    const resolveMessage = useCallback((type, source, options) => {
+    const resolveBaseMessage = useCallback((type, source, options) => {
         // 1. Explicit message override
         if (options.message) {
             return options.message;
         }
+        /*
+         * 1b. A notification that carries a backend ERROR is about that error, and speaks with its words.
+         *
+         * The generic error path (`ErrorContext.executeFrontendActions`) wraps every displayed error in a
+         * custom notification whose identifier is a TRANSPORT placeholder
+         * (`FrontendNotificationCustomMessageRefs.A_TEMP_REF`), not a message. Once the labelling
+         * pipeline generated words for that placeholder ("Next step"), step 2 below answered every such
+         * toast with them: an administrator refused with `organization_unit_directory_managed` read
+         * "Next step" instead of being told the directory owns the unit (#1447).
+         *
+         * The same path also emits a medium-severity error (a 409 CONFLICT) as a WARNING, and the error
+         * branch below was error-only — so a conflict's words were unreachable even without the
+         * placeholder. Both types are covered here.
+         *
+         * Order inside: the DECLARED refusal first (#1048), then the error reference's label. When neither
+         * resolves, the identifier is still skipped for an error-carrying notification — its words
+         * describe no error — and the default for the type answers (step 4).
+         */
+        const payload = options.data;
+        const carriedErrorRef = (payload?.errorCustomMessageReference ?? payload?.customMessageReference);
+        const carriesError = (type === 'error' || type === 'warning')
+            && (typeof carriedErrorRef === 'string' || typeof payload?.errorRefusalCode === 'string');
+        if (carriesError) {
+            const refusal = resolveRefusalCodeLabel({ tErrorMessage: tErrorMessageRef.current, t: tRef.current }, typeof payload?.errorRefusalCode === 'string' ? payload.errorRefusalCode : undefined);
+            if (refusal)
+                return refusal;
+            const resolvedError = resolveErrorReferenceLabel(tErrorMessageRef.current, carriedErrorRef);
+            if (resolvedError)
+                return resolvedError;
+        }
         // 2. i18n lookup by identifier
-        if (options.identifier) {
+        if (options.identifier && !carriesError) {
             const translated = tNotificationCustomRef.current(options.identifier, 'msg', options.i18nParams);
-            // Check if translation exists (not equal to key path)
-            if (!translated.startsWith('notifications_custom.')) {
-                return translated;
-            }
-        }
-        // 3a. Resource ERRORS — resolve the backend error reference to a localized
-        //     human message. Never fall back to the operation title for an error: a
-        //     red toast reading "Create key" looks like a success label. When no
-        //     error label exists we fall through to the generic default-error message
-        //     below; the form's inline field errors still carry per-field specifics.
-        if (type === 'error') {
-            const data = options.data;
-            const errorRef = (data?.errorCustomMessageReference ?? data?.customMessageReference);
-            if (errorRef) {
-                const resolved = tErrorMessageRef.current(errorRef);
-                // tErrorMessage returns the key path (`...{ref}.msg`) when unresolved.
-                if (resolved && !resolved.endsWith(`.${errorRef}.msg`)) {
-                    return resolved;
-                }
-            }
-            // fall through to the default-error label (step 4).
+            const resolved = resolvedLabelOrNull(translated, 'notifications_custom');
+            if (resolved !== null)
+                return resolved;
         }
+        // 2b. A notification ABOUT A MILESTONE speaks with the milestone's own reward message.
+        //
+        //     Both milestone notifications — the celebration (`milestone.<ref>`) and the feature-unlock
+        //     toast (`milestone.feature_unlock.<ref>`) — carry `data.milestoneRef`, and neither
+        //     identifier has a `notifications_custom` label: nothing plans that namespace. So step 2
+        //     always missed and every milestone rendered `defaultSuccess` — a celebration reading
+        //     "Action completed successfully." with no milestone in it (#1406).
+        //
+        //     The words already exist: the labelling planner generates `milestones.<ref>.reward.*` for
+        //     every declared milestone. Minting a parallel `notifications_custom.milestone.*` for the
+        //     same text was rejected — two sources for one string drift apart. Step 2 still runs FIRST,
+        //     so an application that authors a notification-specific message keeps it.
+        const milestoneMessage = resolveMilestoneLabel(options.data, (ref) => tMilestoneRewardRef.current(ref, 'message'));
+        if (milestoneMessage !== null)
+            return milestoneMessage;
+        // 3a. Resource ERRORS are resolved in 1b, for both error and warning toasts. An error never falls
+        //     back to the operation title: a red toast reading "Create key" looks like a success label.
         // 3b. Resource operation title — info / warning only. SUCCESS deliberately
         //     skips the operation title for the same reason the error branch above
         //     does: the `title` label tier is the operation's imperative BUTTON
@@ -259,32 +387,56 @@ export function NotificationProvider({ children }) {
         //     A notification that wants an operation-specific success message
         //     already has a channel: an explicit `message` (step 1) or a custom
         //     notification identifier (step 2).
-        else if (type !== 'success' && source === 'resource' && options.resourceContext) {
+        if (type !== 'success' && type !== 'error' && !carriesError && source === 'resource' && options.resourceContext) {
             const { resourceType, operationIdentifier } = options.resourceContext;
             if (resourceType && operationIdentifier) {
                 const opTitle = tResourceOperationRef.current(resourceType, String(operationIdentifier), 'title');
-                // Check if translation exists
-                if (!opTitle.startsWith('resources.')) {
-                    return opTitle;
-                }
+                const resolved = resolvedLabelOrNull(opTitle, 'resources');
+                if (resolved !== null)
+                    return resolved;
             }
         }
-        // 4. Default fallback — try i18n component label, then hardcoded
+        // 4. Default — the notification center's authored label. A missing label renders as its key, so the
+        //    gap stays visible and gets authored; there is deliberately no hard-coded English behind it
+        //    (`.claude/rules/display-text-comes-from-i18n.md`).
         const DEFAULT_MESSAGE_LABEL_KEYS = {
             success: 'defaultSuccess',
             info: 'defaultInfo',
             warning: 'defaultWarning',
             error: 'defaultError',
         };
-        const labelKey = DEFAULT_MESSAGE_LABEL_KEYS[type];
-        if (labelKey) {
-            const i18nDefault = tComponentRef.current(FrontendComponentType.APPLICATION_LEVEL_NOTIFICATION_CENTER, labelKey);
-            if (!i18nDefault.startsWith('components.')) {
-                return i18nDefault;
-            }
-        }
-        return getDefaultNotificationMessage(type);
+        return tComponentRef.current(FrontendComponentType.APPLICATION_LEVEL_NOTIFICATION_CENTER, DEFAULT_MESSAGE_LABEL_KEYS[type]);
     }, []);
+    /**
+     * A BULK success states HOW MANY rows it changed, and the count QUANTIFIES the message rather
+     * than replacing it.
+     *
+     * The count used to be a rung of the ladder above, below the explicit message and the custom
+     * notification identifier — so it was reachable only for an operation that had nothing else to
+     * say, which is the opposite of the population that needs it. Measured live in Wonder Todos
+     * (#1468): a two-row bulk status change rendered its authored "To-do status changed" and no
+     * count, because `todos_change_status_user_self` answered at step 2. Moving the count ABOVE the
+     * ladder was rejected for the mirror reason — a batch would then drop the operation's own words
+     * in favour of a generic sentence, and the words say what happened while the count only says how
+     * much.
+     *
+     * A base message that IS the generic default keeps the count-only wording ("Action completed for
+     * 3 items."), which reads better than the composition would. The comparison is against the same
+     * label call the default branch makes, so it is exact by construction; an application whose
+     * authored message happens to equal the default gets the count-only form, which says the same
+     * thing.
+     */
+    const resolveMessage = useCallback((type, source, options) => {
+        const base = resolveBaseMessage(type, source, options);
+        const affectedCount = options.data?.affectedCount;
+        if (type !== 'success' || source !== 'resource' || typeof affectedCount !== 'number' || affectedCount <= 1) {
+            return base;
+        }
+        const genericSuccess = tComponentRef.current(FrontendComponentType.APPLICATION_LEVEL_NOTIFICATION_CENTER, 'defaultSuccess');
+        return base === genericSuccess
+            ? tComponentRef.current(FrontendComponentType.APPLICATION_LEVEL_NOTIFICATION_CENTER, 'bulkSucceeded', { count: affectedCount })
+            : tComponentRef.current(FrontendComponentType.APPLICATION_LEVEL_NOTIFICATION_CENTER, 'bulkSucceededWithMessage', { message: base, count: affectedCount });
+    }, [resolveBaseMessage]);
     // ================================
     // Core Notification Handler
     // ================================
@@ -296,25 +448,21 @@ export function NotificationProvider({ children }) {
      */
     const processNotification = useCallback((type, source, options) => {
         /*
-         * The recipient's own in-app switch (#409). `UserPreferences.notifications.inApp` was stored,
-         * editable on the self-preferences screen, classified as personal data, subject-exported and
-         * reset on erasure — and read by nothing: the switches arrived here, were held in state, and
-         * the getter below was called by no one. Turning in-app notifications off changed nothing.
-         *
-         * Only `backend`-sourced notifications are suppressed, and that boundary is the point. A
-         * `resource` or `custom` notification is this application's own UI feedback — the confirmation
-         * that a save succeeded, a validation message. Silencing those would not honour a preference,
-         * it would break the interface: a person who switched off "notifications" did not ask for their
-         * forms to stop confirming. What they asked about is the stream of messages the SERVER pushes
-         * at them, which is exactly `backend`.
-         *
-         * The dispatcher applies the same preference to email/SMS/push on its side. The two halves are
-         * deliberately separate: suppressing the WebSocket frame itself would also suppress the live
-         * resource updates that ride the same channel, so in-app suppression belongs here, at the point
-         * where a frame becomes something a person sees.
+         * Hold it until the labels exist. Re-entered through the same function on flush, and
+         * `isReadyRef` is true by then, so this branch cannot loop.
          */
-        if (source === 'backend' && notificationsPreferences?.inApp === false) {
-            logDebug('Suppressing backend notification: recipient switched in-app notifications off', {
+        if (!isReadyRef.current) {
+            pendingUntilI18nReadyRef.current.push(() => processNotificationRef.current(type, source, options));
+            return;
+        }
+        // Resource events include both local feedback and server messages. Only the latter carry
+        // delivery policy. Reuse the dispatcher's canonical personal-target rule; required notices
+        // and responsibility/fanout messages remain visible. This gate never drops refresh events.
+        const suppressibleServerMessage = options.serverNotification !== undefined
+            && !options.serverNotification.alwaysDeliver
+            && userNotificationTargetIsSuppressibleByRecipientPreference(options.serverNotification.target);
+        if (notificationsPreferences?.inApp === false && (source === 'backend' || suppressibleServerMessage)) {
+            logDebug('Suppressing personal server notification: recipient switched in-app notifications off', {
                 type,
                 identifier: options.identifier,
             });
@@ -332,9 +480,7 @@ export function NotificationProvider({ children }) {
             let nextStepLabel = '';
             if (options.identifier) {
                 const translated = tNotificationCustomRef.current(options.identifier, 'nextStepLabel');
-                if (!translated.startsWith('notifications_custom.')) {
-                    nextStepLabel = translated;
-                }
+                nextStepLabel = resolvedLabelOrNull(translated, 'notifications_custom') ?? '';
             }
             // Fallback: try to resolve as resource operation title (format: "RESOURCE.OPERATION")
             if (!nextStepLabel && nextStepHint.operationRef) {
@@ -342,9 +488,7 @@ export function NotificationProvider({ children }) {
                 if (parts.length >= 2) {
                     const [resourceType, operationId] = parts;
                     const opTitle = tResourceOperationRef.current(resourceType, operationId, 'title');
-                    if (!opTitle.startsWith('resources.')) {
-                        nextStepLabel = opTitle;
-                    }
+                    nextStepLabel = resolvedLabelOrNull(opTitle, 'resources') ?? '';
                 }
             }
             if (!nextStepLabel) {
@@ -390,6 +534,7 @@ export function NotificationProvider({ children }) {
             // Show celebration overlay instead of standard toast
             showCelebration(celebrationHint, {
                 message,
+                heading: resolveMilestoneLabel(options.data, (ref) => tMilestoneRef.current(ref, 'title')) ?? undefined,
                 notificationIdentifier: options.identifier,
                 nextStep: resolvedNextStep,
             });
@@ -441,6 +586,29 @@ export function NotificationProvider({ children }) {
             dispatch({ type: 'ADD_NOTIFICATION', notification });
         }
     }, [resolveMessage, showToast, showCelebration, notificationsPreferences]);
+    /*
+     * A stable handle, so a queued notification is replayed through the CURRENT implementation
+     * rather than the one captured when it was queued — by the time it flushes, `resolveMessage`
+     * has been rebuilt against the loaded bundle, which is the whole point of waiting.
+     */
+    const processNotificationRef = useRef(processNotification);
+    useEffect(() => { processNotificationRef.current = processNotification; }, [processNotification]);
+    useEffect(() => {
+        isReadyRef.current = isReady;
+        if (!isReady)
+            return;
+        /*
+         * Drain by SWAPPING the queue first: each replay re-enters `processNotification`, and draining
+         * in place while that happens would skip entries or loop. `isReadyRef` is true here, so a
+         * replayed entry takes the normal path instead of re-queueing itself.
+         */
+        const pending = pendingUntilI18nReadyRef.current;
+        if (pending.length === 0)
+            return;
+        pendingUntilI18nReadyRef.current = [];
+        for (const replay of pending)
+            replay();
+    }, [isReady]);
     // ================================
     // Event Handlers
     // ================================
@@ -451,6 +619,7 @@ export function NotificationProvider({ children }) {
             const additionalContext = resourceContext.additionalContext || {};
             processNotification(type, 'resource', {
                 resourceContext,
+                serverNotification: payload.serverNotification,
                 identifier: additionalContext.notificationIdentifier,
                 data: additionalContext,
                 frontendDisplayHints: additionalContext.frontendDisplayHints,