@open-mercato/core 0.6.8-develop.6983.1.e4f794099e → 0.6.8-develop.6985.1.fb93574faa

package/src/modules/notifications/frontend/NotificationPreferencesPageClient.tsx

@@ -0,0 +1,155 @@
+"use client"
+
+import * as React from 'react'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { apiCall, readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
+import { flash } from '@open-mercato/ui/backend/FlashMessages'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { LoadingMessage, ErrorMessage } from '@open-mercato/ui/backend/detail'
+import {
+  NotificationPreferenceMatrix,
+  PREFERENCE_CHANNELS,
+  buildPreferenceMap,
+  diffPreferenceItems,
+  preferenceKey,
+  toChannelDef,
+  type ChannelDef,
+  type NotificationTypeItem,
+  type PreferenceItem,
+} from './NotificationPreferenceMatrix'
+
+type TypesResponse = { items?: NotificationTypeItem[] }
+type PreferencesResponse = { items?: PreferenceItem[] }
+type ChannelsResponse = { items?: Array<{ id: string; labelKey: string; descriptionKey?: string | null }> }
+type SaveResponse = { ok?: boolean; error?: string }
+
+const PREFERENCES_CONTEXT_ID = 'notifications-preferences'
+
+export function NotificationPreferencesPageClient() {
+  const t = useT()
+  const [types, setTypes] = React.useState<NotificationTypeItem[] | null>(null)
+  const [channels, setChannels] = React.useState<ChannelDef[]>(PREFERENCE_CHANNELS)
+  const [prefs, setPrefs] = React.useState<Record<string, boolean>>({})
+  // The state as last loaded/saved; saves send only the entries that differ from this.
+  const initialPrefs = React.useRef<Record<string, boolean>>({})
+  const [loading, setLoading] = React.useState(true)
+  const [saving, setSaving] = React.useState(false)
+  const [error, setError] = React.useState<string | null>(null)
+
+  const { runMutation, retryLastMutation } = useGuardedMutation<{
+    formId: string
+    resourceKind: string
+    retryLastMutation: () => Promise<boolean>
+  }>({
+    contextId: PREFERENCES_CONTEXT_ID,
+    blockedMessage: t('ui.forms.flash.saveBlocked', 'Save blocked by validation'),
+  })
+
+  const fetchData = React.useCallback(async () => {
+    setLoading(true)
+    setError(null)
+    try {
+      const [typesBody, prefsBody, channelsBody] = await Promise.all([
+        readApiResultOrThrow<TypesResponse>('/api/notifications/types', undefined, {
+          errorMessage: t('notifications.preferences.loadError', 'Failed to load notification preferences'),
+          allowNullResult: true,
+        }),
+        readApiResultOrThrow<PreferencesResponse>('/api/notifications/preferences', undefined, {
+          errorMessage: t('notifications.preferences.loadError', 'Failed to load notification preferences'),
+          allowNullResult: true,
+        }),
+        readApiResultOrThrow<ChannelsResponse>('/api/notifications/channels', undefined, {
+          errorMessage: t('notifications.preferences.loadError', 'Failed to load notification preferences'),
+          allowNullResult: true,
+        }),
+      ])
+      const typeItems = typesBody?.items ?? []
+      setTypes(typeItems)
+      const channelDefs = channelsBody?.items?.length ? channelsBody.items.map(toChannelDef) : PREFERENCE_CHANNELS
+      setChannels(channelDefs)
+      const map = buildPreferenceMap(typeItems, prefsBody?.items ?? [], channelDefs)
+      initialPrefs.current = map
+      setPrefs(map)
+    } catch (err) {
+      const message = err instanceof Error ? err.message : t('notifications.preferences.loadError', 'Failed to load notification preferences')
+      setError(message)
+      flash(message, 'error')
+    } finally {
+      setLoading(false)
+    }
+  }, [t])
+
+  React.useEffect(() => {
+    fetchData()
+  }, [fetchData])
+
+  const togglePref = (typeId: string, channel: string, enabled: boolean) => {
+    setPrefs((prev) => ({ ...prev, [preferenceKey(typeId, channel)]: enabled }))
+  }
+
+  const handleSave = async () => {
+    if (!types) return
+    setSaving(true)
+    try {
+      const preferences = diffPreferenceItems(types, initialPrefs.current, prefs, channels)
+      // Nothing changed since load/last save — skip the no-op write entirely.
+      if (preferences.length === 0) {
+        flash(t('notifications.preferences.saveSuccess', 'Notification preferences saved'), 'success')
+        return
+      }
+      const response = await runMutation({
+        // optimistic-lock-exempt: the preference matrix is an idempotent per-cell toggle grid.
+        // The client sends only changed (type, channel) cells (diffPreferenceItems) and the server
+        // upserts them last-write-wins per cell, so there is no lost-update hazard on a shared
+        // aggregate that version-locking would guard.
+        operation: () =>
+          apiCall<SaveResponse>('/api/notifications/preferences', {
+            method: 'PUT',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ preferences }),
+          }),
+        context: { formId: PREFERENCES_CONTEXT_ID, resourceKind: 'notifications.preference', retryLastMutation },
+        mutationPayload: { preferences },
+      })
+      if (!response.ok) {
+        const message = response.result?.error || t('notifications.preferences.saveError', 'Failed to save notification preferences')
+        throw new Error(message)
+      }
+      initialPrefs.current = prefs
+      flash(t('notifications.preferences.saveSuccess', 'Notification preferences saved'), 'success')
+    } catch (err) {
+      const message = err instanceof Error ? err.message : t('notifications.preferences.saveError', 'Failed to save notification preferences')
+      flash(message, 'error')
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  if (loading || !types) {
+    return <LoadingMessage label={t('notifications.preferences.loading', 'Loading notification preferences...')} />
+  }
+
+  return (
+    <div className="flex flex-col gap-6">
+      <div>
+        <h1 className="text-2xl font-semibold">{t('notifications.preferences.pageTitle', 'Notification Preferences')}</h1>
+        <p className="text-muted-foreground text-sm">
+          {t('notifications.preferences.pageDescription', 'Choose which channels deliver each notification type. Unset choices stay enabled by default.')}
+        </p>
+      </div>
+
+      <NotificationPreferenceMatrix types={types} prefs={prefs} onToggle={togglePref} channels={channels} />
+
+      {error && <ErrorMessage label={error} />}
+
+      <div className="flex items-center gap-3">
+        <Button type="button" onClick={handleSave} disabled={saving}>
+          {saving ? t('notifications.preferences.saving', 'Saving...') : t('notifications.preferences.save', 'Save preferences')}
+        </Button>
+      </div>
+    </div>
+  )
+}
+
+export default NotificationPreferencesPageClient

package/src/modules/notifications/frontend/NotificationSettingsPageClient.tsx

@@ -2,9 +2,11 @@
 
 import * as React from 'react'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
-import { apiCall, readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCall, readApiResultOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
 import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
-import { flash } from '@open-mercato/ui/backend/FlashMessages'
+import { flash, type FlashKind } from '@open-mercato/ui/backend/FlashMessages'
 import { Button } from '@open-mercato/ui/primitives/button'
 import { Input } from '@open-mercato/ui/primitives/input'
 import { Label } from '@open-mercato/ui/primitives/label'
@@ -12,6 +14,26 @@ import { Switch } from '@open-mercato/ui/primitives/switch'
 import { Spinner } from '@open-mercato/ui/primitives/spinner'
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@open-mercato/ui/primitives/card'
 
+type NotificationTypeCatalogueItem = {
+  id: string
+  labelKey: string
+  descriptionKey?: string | null
+  // Effective "required" flag (tenant override ?? code-declared).
+  nonOptOut?: boolean
+  // Effective channel eligibility for this tenant (stored override ?? code-declared; null = every channel).
+  channels: string[] | null
+  // Raw tenant-stored override (null = inherit the code-declared set).
+  storedChannels: string[] | null
+  // Raw tenant-stored nonOptOut override (null = inherit the code-declared flag).
+  storedNonOptOut: boolean | null
+  // Optimistic-lock version of the tenant's override row (null = no override stored yet).
+  updatedAt: string | null
+}
+
+type TypesResponse = { items?: NotificationTypeCatalogueItem[] }
+type ChannelsResponse = { items?: Array<{ id: string; labelKey: string; descriptionKey?: string | null }> }
+type PatchTypeResponse = { ok?: boolean; item?: NotificationTypeCatalogueItem; error?: string }
+
 type NotificationDeliveryConfig = {
   appUrl?: string
   panelPath: string
@@ -48,12 +70,170 @@ export function NotificationSettingsPageClient() {
   const { runMutation, retryLastMutation } = useGuardedMutation<{
     formId: string
     resourceKind: string
+    resourceId?: string
     retryLastMutation: () => Promise<boolean>
   }>({
     contextId: SETTINGS_CONTEXT_ID,
     blockedMessage: t('ui.forms.flash.saveBlocked', 'Save blocked by validation'),
   })
 
+  const [types, setTypes] = React.useState<NotificationTypeCatalogueItem[]>([])
+  const [channels, setChannels] = React.useState<Array<{ id: string; labelKey: string }>>([])
+  const [savingTypeCell, setSavingTypeCell] = React.useState<string | null>(null)
+
+  const fetchCatalogue = React.useCallback(async () => {
+    try {
+      const [typesBody, channelsBody] = await Promise.all([
+        readApiResultOrThrow<TypesResponse>('/api/notifications/types', undefined, {
+          errorMessage: t('notifications.settings.types.loadError', 'Failed to load notification types'),
+          allowNullResult: true,
+        }),
+        readApiResultOrThrow<ChannelsResponse>('/api/notifications/channels', undefined, {
+          errorMessage: t('notifications.settings.types.loadError', 'Failed to load notification types'),
+          allowNullResult: true,
+        }),
+      ])
+      setTypes(typesBody?.items ?? [])
+      setChannels((channelsBody?.items ?? []).map((item) => ({ id: item.id, labelKey: item.labelKey })))
+    } catch (err) {
+      const message = err instanceof Error ? err.message : t('notifications.settings.types.loadError', 'Failed to load notification types')
+      flash(message, 'error')
+    }
+  }, [t])
+
+  React.useEffect(() => {
+    fetchCatalogue()
+  }, [fetchCatalogue])
+
+  const saveTypeCell = async (
+    type: NotificationTypeCatalogueItem,
+    cellKey: string,
+    mutationPayload: Record<string, unknown>,
+    operation: () => Promise<Awaited<ReturnType<typeof apiCall<PatchTypeResponse>>>>,
+    resolveSavedFlash?: (saved: NotificationTypeCatalogueItem) => { message: string; kind: FlashKind } | null,
+  ) => {
+    setSavingTypeCell(cellKey)
+    try {
+      const response = await runMutation({
+        operation,
+        context: {
+          formId: SETTINGS_CONTEXT_ID,
+          resourceKind: 'notifications.settings',
+          resourceId: type.id,
+          retryLastMutation,
+        },
+        mutationPayload,
+      })
+      if (!response.ok || !response.result?.ok) {
+        if (surfaceRecordConflict({ status: response.status, body: response.result }, t, { onRefresh: fetchCatalogue })) {
+          await fetchCatalogue()
+          return
+        }
+        const message = response.result?.error || t('notifications.settings.types.saveError', 'Failed to save notification type settings')
+        throw new Error(message)
+      }
+      const saved = response.result.item
+      setTypes((prev) =>
+        prev.map((item) =>
+          item.id === type.id && saved
+            ? {
+                ...item,
+                channels: saved.channels,
+                storedChannels: saved.storedChannels,
+                nonOptOut: saved.nonOptOut,
+                storedNonOptOut: saved.storedNonOptOut,
+                updatedAt: saved.updatedAt,
+              }
+            : item,
+        ),
+      )
+      const savedFlash = saved ? resolveSavedFlash?.(saved) ?? null : null
+      flash(
+        savedFlash?.message ?? t('notifications.settings.types.saveSuccess', 'Notification type settings saved'),
+        savedFlash?.kind ?? 'success',
+      )
+    } catch (err) {
+      const message = err instanceof Error ? err.message : t('notifications.settings.types.saveError', 'Failed to save notification type settings')
+      flash(message, 'error')
+    } finally {
+      setSavingTypeCell(null)
+    }
+  }
+
+  /**
+   * `nonOptOut` is a single scalar the request replaces wholesale, so it keeps the
+   * optimistic-lock header: a concurrent operator save flips the override row's `updatedAt`
+   * and the server 409s rather than letting a stale blind write revert their edit.
+   */
+  const patchType = (
+    type: NotificationTypeCatalogueItem,
+    cellKey: string,
+    payload: { channels?: string[] | null; nonOptOut?: boolean | null },
+  ) =>
+    saveTypeCell(type, cellKey, { id: type.id, ...payload }, () =>
+      withScopedApiRequestHeaders(buildOptimisticLockHeader(type.updatedAt), () =>
+        apiCall<PatchTypeResponse>('/api/notifications/types', {
+          method: 'PATCH',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ id: type.id, ...payload }),
+        }),
+      ),
+    )
+
+  /**
+   * optimistic-lock-exempt: notification type channel add/remove. Addressing the single
+   * channel lets the server derive the next eligibility set from the CURRENT stored state
+   * under a row lock, so two operators toggling different channels both land instead of the
+   * later one clobbering the earlier with a client-computed array. There is no shared
+   * aggregate left for a version check to protect — the same reason the sibling preference
+   * matrix and the customers/catalog add-remove endpoints are exempt.
+   */
+  const toggleTypeChannel = (
+    type: NotificationTypeCatalogueItem,
+    cellKey: string,
+    channel: string,
+    enabled: boolean,
+  ) =>
+    saveTypeCell(
+      type,
+      cellKey,
+      { id: type.id, channel, enabled },
+      () =>
+        apiCall<PatchTypeResponse>(
+          `/api/notifications/types/${encodeURIComponent(type.id)}/channels/${encodeURIComponent(channel)}`,
+          { method: enabled ? 'PUT' : 'DELETE' },
+        ),
+      // Unchecking the last channel clears the override instead of storing an empty set (which would
+      // black-hole the type), so the code-declared default reapplies and the box the operator just
+      // unticked can come back ticked. The write succeeded, so say what happened rather than letting a
+      // green "saved" sit next to a checkbox that visibly ignored the click.
+      (saved) =>
+        !enabled && saved.storedChannels === null && (saved.channels === null || saved.channels.includes(channel))
+          ? {
+              message: t(
+                'notifications.settings.types.lastChannelRestored',
+                'A notification type must keep at least one channel, so the module default was restored.',
+              ),
+              kind: 'warning' as FlashKind,
+            }
+          : null,
+    )
+
+  const handleTypeChannelToggle = async (
+    type: NotificationTypeCatalogueItem,
+    channelId: string,
+    enabled: boolean,
+  ) => {
+    // The server resolves the base set (stored override ?? code declaration ?? every
+    // registered channel) and clears the override when the last channel is unchecked, so the
+    // client no longer computes — or can stale-clobber — the whole array.
+    await toggleTypeChannel(type, `${type.id}::${channelId}`, channelId, enabled)
+  }
+
+  const handleTypeNonOptOutToggle = async (type: NotificationTypeCatalogueItem, required: boolean) => {
+    await patchType(type, `${type.id}::nonOptOut`, { nonOptOut: required })
+  }
+
   const fetchSettings = React.useCallback(async () => {
     setLoading(true)
     setError(null)
@@ -237,6 +417,97 @@ export function NotificationSettingsPageClient() {
         </CardContent>
       </Card>
 
+      <Card>
+        <CardHeader>
+          <CardTitle>{t('notifications.settings.types.title', 'Delivery channels per type')}</CardTitle>
+          <CardDescription>
+            {t(
+              'notifications.settings.types.description',
+              'Delivery channels per notification type. Turning a channel off disables it completely for that type in your tenant — it never delivers and users cannot enable it in their preferences. Turning it on lets users opt in or out per type; required (non-opt-out) types always deliver on enabled channels. Your setting overrides the module default.',
+            )}
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          {types.length === 0 || channels.length === 0 ? (
+            <p className="text-sm text-muted-foreground">
+              {t('notifications.settings.types.empty', 'No notification types are registered yet.')}
+            </p>
+          ) : (
+            <div className="overflow-x-auto rounded-lg border border-border">
+              <table className="w-full text-sm">
+                <thead>
+                  <tr className="border-b border-border bg-muted/50 text-left">
+                    <th className="px-4 py-3 font-medium">
+                      {t('notifications.settings.types.typeColumn', 'Notification type')}
+                    </th>
+                    {channels.map((channel) => (
+                      <th key={channel.id} className="px-4 py-3 font-medium">
+                        {t(channel.labelKey, channel.id)}
+                      </th>
+                    ))}
+                    <th className="px-4 py-3 font-medium">
+                      <div>{t('notifications.settings.types.requiredColumn', 'Required')}</div>
+                      <div className="text-xs font-normal text-muted-foreground">
+                        {t('notifications.settings.types.requiredHint', 'Users cannot opt out when on.')}
+                      </div>
+                    </th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {types.map((type) => (
+                    <tr key={type.id} className="border-b border-border last:border-0">
+                      <td className="px-4 py-3">
+                        <div className="font-medium">{t(type.labelKey, type.id)}</div>
+                        {type.descriptionKey ? (
+                          <div className="text-xs text-muted-foreground">{t(type.descriptionKey, '')}</div>
+                        ) : null}
+                      </td>
+                      {channels.map((channel) => {
+                        const cellKey = `${type.id}::${channel.id}`
+                        const channelEnabled = type.channels === null || type.channels.includes(channel.id)
+                        return (
+                          <td key={channel.id} className="px-4 py-3">
+                            {/* The saving spinner is absolutely positioned so it never joins the cell's
+                                layout flow — an in-flow sibling would widen the column mid-toggle and
+                                make the whole table jump for the duration of the save. */}
+                            <span className="relative inline-flex items-center">
+                              <Switch
+                                checked={channelEnabled}
+                                disabled={savingTypeCell !== null}
+                                aria-label={`${t(type.labelKey, type.id)} – ${t(channel.labelKey, channel.id)}`}
+                                onCheckedChange={(checked) =>
+                                  handleTypeChannelToggle(type, channel.id, checked)
+                                }
+                              />
+                              {savingTypeCell === cellKey ? (
+                                <Spinner size="sm" className="absolute left-full ml-2" />
+                              ) : null}
+                            </span>
+                          </td>
+                        )
+                      })}
+                      <td className="px-4 py-3">
+                        <span className="relative inline-flex">
+                          <Switch
+                            checked={type.nonOptOut === true}
+                            disabled={savingTypeCell !== null}
+                            aria-label={`${t(type.labelKey, type.id)} – ${t('notifications.settings.types.requiredColumn', 'Required')}`}
+                            onCheckedChange={(checked) => handleTypeNonOptOutToggle(type, checked)}
+                          />
+                          {savingTypeCell === `${type.id}::nonOptOut` ? (
+                            <Spinner size="sm" className="absolute left-full ml-2" />
+                          ) : null}
+                        </span>
+                      </td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            </div>
+          )}
+        </CardContent>
+      </Card>
+
       <div className="flex items-center gap-3">
         <Button type="button" onClick={handleSave} disabled={saving}>
           {saving ? t('notifications.settings.saving', 'Saving...') : t('notifications.settings.save', 'Save settings')}

package/src/modules/notifications/frontend/NotificationUserPreferencesAdminPageClient.tsx

@@ -0,0 +1,214 @@
+"use client"
+
+import * as React from 'react'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { apiCall, readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
+import { flash } from '@open-mercato/ui/backend/FlashMessages'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { LoadingMessage } from '@open-mercato/ui/backend/detail'
+import { LookupSelect, type LookupSelectItem } from '@open-mercato/ui/backend/inputs'
+import {
+  NotificationPreferenceMatrix,
+  PREFERENCE_CHANNELS,
+  buildPreferenceMap,
+  diffPreferenceItems,
+  preferenceKey,
+  toChannelDef,
+  type ChannelDef,
+  type NotificationTypeItem,
+  type PreferenceItem,
+} from './NotificationPreferenceMatrix'
+
+type TypesResponse = { items?: NotificationTypeItem[] }
+type PreferencesResponse = { items?: PreferenceItem[] }
+type ChannelsResponse = { items?: Array<{ id: string; labelKey: string; descriptionKey?: string | null }> }
+type SaveResponse = { ok?: boolean; error?: string }
+
+type UserRow = { id: string; name?: string | null; email?: string | null }
+type UsersResponse = { items?: UserRow[] }
+
+const ADMIN_PREFERENCES_CONTEXT_ID = 'notifications-admin-preferences'
+
+function userLabel(user: UserRow): string {
+  return user.name?.trim() || user.email?.trim() || user.id
+}
+
+export function NotificationUserPreferencesAdminPageClient() {
+  const t = useT()
+  const [types, setTypes] = React.useState<NotificationTypeItem[]>([])
+  const [channels, setChannels] = React.useState<ChannelDef[]>(PREFERENCE_CHANNELS)
+  const [typesLoading, setTypesLoading] = React.useState(true)
+  const [selectedUserId, setSelectedUserId] = React.useState<string | null>(null)
+  // id -> display label, populated as options are fetched so the heading can name the selected user.
+  const userLabels = React.useRef<Map<string, string>>(new Map())
+  const [prefs, setPrefs] = React.useState<Record<string, boolean>>({})
+  // Baseline for the selected user; saves send only entries that differ from this.
+  const initialPrefs = React.useRef<Record<string, boolean>>({})
+  const [prefsLoading, setPrefsLoading] = React.useState(false)
+  const [saving, setSaving] = React.useState(false)
+
+  const { runMutation, retryLastMutation } = useGuardedMutation<{
+    formId: string
+    resourceKind: string
+    retryLastMutation: () => Promise<boolean>
+  }>({
+    contextId: ADMIN_PREFERENCES_CONTEXT_ID,
+    blockedMessage: t('ui.forms.flash.saveBlocked', 'Save blocked by validation'),
+  })
+
+  React.useEffect(() => {
+    let cancelled = false
+    ;(async () => {
+      setTypesLoading(true)
+      try {
+        const [body, channelsBody] = await Promise.all([
+          readApiResultOrThrow<TypesResponse>('/api/notifications/types', undefined, {
+            errorMessage: t('notifications.preferences.loadError', 'Failed to load notification preferences'),
+            allowNullResult: true,
+          }),
+          readApiResultOrThrow<ChannelsResponse>('/api/notifications/channels', undefined, {
+            errorMessage: t('notifications.preferences.loadError', 'Failed to load notification preferences'),
+            allowNullResult: true,
+          }),
+        ])
+        if (!cancelled) {
+          setTypes(body?.items ?? [])
+          setChannels(channelsBody?.items?.length ? channelsBody.items.map(toChannelDef) : PREFERENCE_CHANNELS)
+        }
+      } catch (err) {
+        if (!cancelled) flash(err instanceof Error ? err.message : t('notifications.preferences.loadError', 'Failed to load notification preferences'), 'error')
+      } finally {
+        if (!cancelled) setTypesLoading(false)
+      }
+    })()
+    return () => { cancelled = true }
+  }, [t])
+
+  // Async user lookup for LookupSelect. Devices admins may lack auth.users.list; degrade to no
+  // options (x-om-forbidden-redirect: 0 + swallow) instead of redirecting the whole page.
+  const fetchUsers = React.useCallback(async (query?: string): Promise<LookupSelectItem[]> => {
+    const params = new URLSearchParams({ page: '1', pageSize: '10' })
+    if (query && query.trim().length) params.set('search', query.trim())
+    const call = await apiCall<UsersResponse>(
+      `/api/auth/users?${params.toString()}`,
+      { headers: { 'x-om-forbidden-redirect': '0' } },
+      { fallback: null },
+    ).catch(() => null)
+    if (!call || !call.ok) return []
+    return (call.result?.items ?? []).flatMap((user) => {
+      if (!user || typeof user.id !== 'string' || !user.id.trim()) return []
+      const label = userLabel(user)
+      userLabels.current.set(user.id, label)
+      const email = user.email?.trim() ?? null
+      return [{ id: user.id, title: label, subtitle: email && email !== label ? email : null }]
+    })
+  }, [])
+
+  const loadPreferencesFor = React.useCallback(async (userId: string) => {
+    setPrefsLoading(true)
+    try {
+      const body = await readApiResultOrThrow<PreferencesResponse>(
+        `/api/notifications/admin/preferences?userId=${encodeURIComponent(userId)}`,
+        undefined,
+        { errorMessage: t('notifications.preferences.loadError', 'Failed to load notification preferences'), allowNullResult: true },
+      )
+      const map = buildPreferenceMap(types, body?.items ?? [], channels)
+      initialPrefs.current = map
+      setPrefs(map)
+    } catch (err) {
+      flash(err instanceof Error ? err.message : t('notifications.preferences.loadError', 'Failed to load notification preferences'), 'error')
+      setSelectedUserId(null)
+    } finally {
+      setPrefsLoading(false)
+    }
+  }, [t, types, channels])
+
+  const handleSelectUser = (userId: string | null) => {
+    setSelectedUserId(userId)
+    if (userId) void loadPreferencesFor(userId)
+  }
+
+  const togglePref = (typeId: string, channel: string, enabled: boolean) => {
+    setPrefs((prev) => ({ ...prev, [preferenceKey(typeId, channel)]: enabled }))
+  }
+
+  const handleSave = async () => {
+    if (!selectedUserId) return
+    setSaving(true)
+    try {
+      const preferences = diffPreferenceItems(types, initialPrefs.current, prefs, channels)
+      // Nothing changed for this user since load/last save — skip the no-op write.
+      if (preferences.length === 0) {
+        flash(t('notifications.preferences.saveSuccess', 'Notification preferences saved'), 'success')
+        return
+      }
+      const response = await runMutation({
+        // optimistic-lock-exempt: idempotent per-cell preference toggle grid — the client sends only
+        // changed (type, channel) cells (diffPreferenceItems) and the server upserts them
+        // last-write-wins per cell, so there is no lost-update hazard to version-lock.
+        operation: () =>
+          apiCall<SaveResponse>('/api/notifications/admin/preferences', {
+            method: 'PUT',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ userId: selectedUserId, preferences }),
+          }),
+        context: { formId: ADMIN_PREFERENCES_CONTEXT_ID, resourceKind: 'notifications.preference', retryLastMutation },
+        mutationPayload: { userId: selectedUserId, preferences },
+      })
+      if (!response.ok) {
+        throw new Error(response.result?.error || t('notifications.preferences.saveError', 'Failed to save notification preferences'))
+      }
+      initialPrefs.current = prefs
+      flash(t('notifications.preferences.saveSuccess', 'Notification preferences saved'), 'success')
+    } catch (err) {
+      flash(err instanceof Error ? err.message : t('notifications.preferences.saveError', 'Failed to save notification preferences'), 'error')
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  const selectedLabel = selectedUserId ? (userLabels.current.get(selectedUserId) ?? selectedUserId) : ''
+
+  return (
+    <div className="flex flex-col gap-6">
+      <div>
+        <h1 className="text-2xl font-semibold">{t('notifications.preferences.admin.pageTitle', 'User Notification Preferences')}</h1>
+        <p className="text-muted-foreground text-sm">
+          {t('notifications.preferences.admin.pageDescription', "Search for a user to review and edit their notification channel preferences.")}
+        </p>
+      </div>
+
+      <LookupSelect
+        value={selectedUserId}
+        onChange={handleSelectUser}
+        fetchOptions={fetchUsers}
+        defaultOpen
+        searchPlaceholder={t('notifications.preferences.admin.searchPlaceholder', 'Search users by name or email...')}
+        emptyLabel={t('notifications.preferences.admin.noUsers', 'No users found.')}
+      />
+
+      {selectedUserId ? (
+        <div className="flex flex-col gap-4">
+          <h2 className="text-lg font-medium">
+            {t('notifications.preferences.admin.editingFor', 'Preferences for {user}').replace('{user}', selectedLabel)}
+          </h2>
+          {prefsLoading || typesLoading ? (
+            <LoadingMessage label={t('notifications.preferences.loading', 'Loading notification preferences...')} />
+          ) : (
+            <>
+              <NotificationPreferenceMatrix types={types} prefs={prefs} onToggle={togglePref} channels={channels} />
+              <div>
+                <Button type="button" onClick={handleSave} disabled={saving}>
+                  {saving ? t('notifications.preferences.saving', 'Saving...') : t('notifications.preferences.save', 'Save preferences')}
+                </Button>
+              </div>
+            </>
+          )}
+        </div>
+      ) : null}
+    </div>
+  )
+}
+
+export default NotificationUserPreferencesAdminPageClient