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

package/src/modules/notifications/data/entities.ts

@@ -77,6 +77,21 @@ export class Notification {
   @Property({ name: 'group_key', type: 'text', nullable: true })
   groupKey?: string | null
 
+  // Arbitrary app-readable key/values delivered with the push payload and exposed to in-app clients.
+  @Property({ name: 'data', type: 'json', nullable: true })
+  data?: Record<string, string> | null
+
+  // Per-provider push customization (sound/badge/image/priority/channelId/body); push-only.
+  // Typed loosely to keep notifications decoupled from communication_channels' PushOptions.
+  @Property({ name: 'push_options', type: 'json', nullable: true })
+  pushOptions?: Record<string, unknown> | null
+
+  // Resolved delivery channels for this notification (target ∩ type-eligibility ∩ registered ∩ preference).
+  // Authoritative target filter the dispatcher loops over; `in_app` membership also gates bell/inbox visibility.
+  // NULL = legacy/all-channels (delivered and visible everywhere) — preserves pre-Phase-7 behavior.
+  @Property({ name: 'channels', type: 'json', nullable: true })
+  channels?: string[] | null
+
   @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
   createdAt: Date = new Date()
 
@@ -98,3 +113,132 @@ export class Notification {
   @Property({ name: 'organization_id', type: 'uuid', nullable: true })
   organizationId?: string | null
 }
+
+/**
+ * DB-backed mirror of the code-registered notification type catalogue
+ * (the in-memory `NotificationTypeDefinition` seam stays the source of truth).
+ * Lets remote clients (mobile apps) enumerate types over HTTP to render a
+ * preferences screen without shipping a copy of the catalogue.
+ *
+ * `tenant_id` is nullable: code-registered types are system-wide (`null`).
+ * The string `id` is the frozen notification-type id (e.g. `sales.order.created`).
+ */
+@Entity({ tableName: 'notification_types' })
+@Index({ name: 'notification_types_tenant_idx', properties: ['tenantId'] })
+export class NotificationType {
+  [OptionalProps]?: 'tenantId' | 'descriptionKey' | 'category' | 'silent' | 'nonOptOut' | 'createdAt' | 'updatedAt'
+
+  @PrimaryKey({ name: 'id', type: 'text' })
+  id!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid', nullable: true })
+  tenantId?: string | null
+
+  @Property({ name: 'label_key', type: 'text' })
+  labelKey!: string
+
+  @Property({ name: 'description_key', type: 'text', nullable: true })
+  descriptionKey?: string | null
+
+  @Property({ name: 'category', type: 'text', nullable: true })
+  category?: string | null
+
+  @Property({ name: 'silent', type: 'boolean', default: false })
+  silent: boolean = false
+
+  @Property({ name: 'non_opt_out', type: 'boolean', default: false })
+  nonOptOut: boolean = false
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+
+  @Property({ name: 'updated_at', type: Date, onCreate: () => new Date(), onUpdate: () => new Date() })
+  updatedAt: Date = new Date()
+}
+
+/**
+ * Tenant-scoped operator override of a notification type's delivery contract.
+ * Lazy-seeded like `NotificationPreference`: an absent row means the code
+ * declarations apply unchanged. `channels` REPLACES the code-declared
+ * `NotificationTypeDefinition.channels` when set (`null` inherits it) — a
+ * channel outside the effective set never delivers for the type in this tenant
+ * (checked before both the `nonOptOut` bypass and user preferences) and users
+ * cannot opt into it; the preference UIs render the cell locked off.
+ * `nonOptOut` overrides the code-declared flag the same way: `true` forces the
+ * type on for the tenant's users, `false` makes a code-required type
+ * user-editable, `null` inherits. The `notification_type_id` is a soft string
+ * reference to a `notification_types.id` (no cross-module ORM relationship);
+ * `syncNotificationTypes` never touches this table, so operator edits survive
+ * catalogue re-syncs.
+ */
+@Entity({ tableName: 'notification_type_overrides' })
+@Index({
+  name: 'notification_type_overrides_unique',
+  expression:
+    'create unique index "notification_type_overrides_unique" on "notification_type_overrides" ("tenant_id", "notification_type_id");',
+})
+export class NotificationTypeOverride {
+  [OptionalProps]?: 'createdAt' | 'updatedAt'
+
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  @Property({ name: 'notification_type_id', type: 'text' })
+  notificationTypeId!: string
+
+  @Property({ name: 'channels', type: 'json', nullable: true })
+  channels?: string[] | null
+
+  @Property({ name: 'non_opt_out', type: 'boolean', nullable: true })
+  nonOptOut?: boolean | null
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+
+  @Property({ name: 'updated_at', type: Date, onCreate: () => new Date(), onUpdate: () => new Date() })
+  updatedAt: Date = new Date()
+}
+
+/**
+ * Channel-agnostic per-user notification preference. Lazy-seeded: an absent row
+ * means the channel is enabled (default-on). Channels (in_app, push, future
+ * email/sms) are free-form strings; the `notification_type_id` is a soft string
+ * reference to a `notification_types.id` (no cross-module ORM relationship).
+ */
+@Entity({ tableName: 'notification_preferences' })
+@Index({ name: 'notification_preferences_tenant_user_idx', properties: ['tenantId', 'userId'] })
+@Index({
+  name: 'notification_preferences_unique',
+  expression:
+    'create unique index "notification_preferences_unique" on "notification_preferences" ("tenant_id", "user_id", "notification_type_id", "channel");',
+})
+export class NotificationPreference {
+  [OptionalProps]?: 'enabled' | 'createdAt' | 'updatedAt'
+
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  @Property({ name: 'user_id', type: 'uuid' })
+  userId!: string
+
+  @Property({ name: 'notification_type_id', type: 'text' })
+  notificationTypeId!: string
+
+  @Property({ name: 'channel', type: 'text' })
+  channel!: string
+
+  @Property({ name: 'enabled', type: 'boolean', default: true })
+  enabled: boolean = true
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+
+  @Property({ name: 'updated_at', type: Date, onCreate: () => new Date(), onUpdate: () => new Date() })
+  updatedAt: Date = new Date()
+}

package/src/modules/notifications/data/validators.ts

@@ -21,6 +21,22 @@ export const notificationActionSchema = z.object({
   confirmMessage: z.string().optional(),
 })
 
+/**
+ * Flat per-provider push customization. Known keys are mapped onto each provider's native message
+ * by the push adapters; unknown keys are accepted (passthrough) for providers that understand them.
+ * See `communication_channels/lib/push-envelope.ts` (`PushOptions`).
+ */
+export const pushOptionsSchema = z
+  .object({
+    sound: z.string().optional(),
+    badge: z.number().int().nonnegative().optional(),
+    image: z.string().optional(),
+    priority: z.enum(['high', 'normal']).optional(),
+    channelId: z.string().optional(),
+    body: z.string().optional(),
+  })
+  .catchall(z.unknown())
+
 const baseNotificationFieldsSchema = z.object({
   type: z.string().min(1).max(100),
   titleKey: z.string().min(1).max(200).optional(),
@@ -39,6 +55,16 @@ const baseNotificationFieldsSchema = z.object({
   linkHref: safeRelativeHrefSchema.optional(),
   groupKey: z.string().optional(),
   expiresAt: z.string().datetime().optional(),
+  // Arbitrary app-readable key/values delivered with the push (and visible to in-app clients).
+  data: z.record(z.string(), z.string()).optional(),
+  // Per-provider push customization (sound, badge, image, priority, channelId, body override).
+  pushOptions: pushOptionsSchema.optional(),
+  // Explicit per-send channel target. When present, delivery is restricted to these channels
+  // (intersected with the type's eligibility, the registered strategies, and the recipient's
+  // preferences). Absent → all registered channels (pre-Phase-7 behavior). Must be non-empty when
+  // provided: an empty array would resolve to zero deliverable channels and silently black-hole the
+  // notification (invisible + undelivered) — omit the field instead to target every channel.
+  channels: z.array(z.string().min(1).max(32)).min(1).optional(),
 })
 
 const titleRequiredRefinement = {
@@ -113,3 +139,93 @@ export type CreateFeatureNotificationInput = z.infer<typeof createFeatureNotific
 export type ListNotificationsInput = z.infer<typeof listNotificationsSchema>
 export type ExecuteActionInput = z.infer<typeof executeActionSchema>
 export type NotificationDeliveryConfigInput = z.infer<typeof notificationDeliveryConfigSchema>
+
+// Notification type catalogue (DB-mirrored read model)
+export const notificationTypeItemSchema = z.object({
+  id: z.string(),
+  labelKey: z.string(),
+  descriptionKey: z.string().nullable().optional(),
+  // Free-form grouping label so a client can list/group types under a heading. Defaults to
+  // the prefix before the first dot in the type id (`sales.order.created` → `sales`), so in
+  // practice it is always populated; kept nullable to avoid narrowing the response contract.
+  // This is the STABLE grouping key — clients group on it and display `categoryLabel`.
+  category: z.string().nullable().optional(),
+  // Localized heading for `category`, resolved server-side from
+  // `notifications.categories.<key>` with a humanized fallback. Display-only: grouping on it
+  // re-partitions the list whenever the locale changes.
+  categoryLabel: z.string().nullable(),
+  // Server-resolved display strings so clients without the app dictionary (the mobile app)
+  // need no i18n bundle. `null` iff the corresponding `*Key` is null.
+  label: z.string().nullable(),
+  description: z.string().nullable(),
+  // When true the type is delivered as a silent / content-available push.
+  silent: z.boolean(),
+  // Effective "cannot be opted out of" flag (operator override ?? code-declared); a preferences
+  // UI should lock the type on when true.
+  nonOptOut: z.boolean(),
+  // Effective channel eligibility for the caller's tenant (stored override ?? code-declared
+  // `type.channels`). `null` = no restriction (every registered channel). A channel outside
+  // the set never delivers for this type in the tenant and users cannot opt into it —
+  // preference UIs lock the cell off.
+  channels: z.array(z.string()).nullable(),
+  // The raw tenant-stored override (`notification_type_overrides.channels`; `null` = inherit
+  // code). Admin editors base PATCH payloads on the EFFECTIVE set, but this shows whether an
+  // override exists at all.
+  storedChannels: z.array(z.string()).nullable(),
+  // The raw tenant-stored `nonOptOut` override (`null` = inherit the code-declared flag).
+  storedNonOptOut: z.boolean().nullable(),
+  // Optimistic-lock version of the tenant's override row (ISO timestamp; `null` when the
+  // tenant stores no override yet). PATCH callers echo it back via the standard
+  // `x-om-ext-optimistic-lock-expected-updated-at` header.
+  updatedAt: z.string().nullable(),
+})
+
+// PATCH /api/notifications/types — operator override of a type's channel eligibility and/or
+// nonOptOut governance. Omitted fields stay untouched; `null` clears the stored override so
+// the code declaration applies again.
+export const updateNotificationTypeSchema = z
+  .object({
+    id: z.string().min(1),
+    // Mirror the create guard: a non-empty array restricts eligibility, `null` clears the override
+    // (code declaration reapplies). An empty array is rejected — it would resolve to zero deliverable
+    // channels and silently black-hole the type (invisible + undelivered); clear with `null` instead.
+    channels: z.array(z.string().min(1)).min(1).nullable().optional(),
+    nonOptOut: z.boolean().nullable().optional(),
+  })
+  .refine((value) => value.channels !== undefined || value.nonOptOut !== undefined, {
+    message: 'At least one of channels or nonOptOut must be provided',
+  })
+
+// Per-user channel preferences
+export const notificationPreferenceItemSchema = z.object({
+  notificationTypeId: z.string(),
+  channel: z.string(),
+  enabled: z.boolean(),
+})
+
+export const updatePreferencesSchema = z.object({
+  preferences: z
+    .array(
+      z.object({
+        notificationTypeId: z.string().trim().min(1).max(128),
+        channel: z.string().trim().min(1).max(32),
+        enabled: z.boolean(),
+      }),
+    )
+    .max(500),
+})
+
+// Admin-on-behalf preference management (target a specific user)
+export const adminPreferencesQuerySchema = z.object({
+  userId: z.string().uuid(),
+})
+
+export const adminUpdatePreferencesSchema = updatePreferencesSchema.extend({
+  userId: z.string().uuid(),
+})
+
+export type NotificationTypeItem = z.infer<typeof notificationTypeItemSchema>
+export type UpdateNotificationTypeInput = z.infer<typeof updateNotificationTypeSchema>
+export type NotificationPreferenceItem = z.infer<typeof notificationPreferenceItemSchema>
+export type UpdatePreferencesInput = z.infer<typeof updatePreferencesSchema>
+export type AdminUpdatePreferencesInput = z.infer<typeof adminUpdatePreferencesSchema>

package/src/modules/notifications/di.ts

@@ -1,11 +1,18 @@
 import type { AppContainer } from '@open-mercato/shared/lib/di/container'
 import { asFunction } from 'awilix'
 import { createNotificationService } from './lib/notificationService'
+import { createNotificationPreferenceService } from './lib/notificationPreferenceService'
 
 export function register(container: AppContainer): void {
   container.register({
     notificationService: asFunction(({ em, eventBus, commandBus }) =>
       createNotificationService({ em, eventBus, commandBus, container })
     ).scoped().proxy(),
+    // Cross-module/worker seam advertised by AGENTS.md ("DI: notificationPreferenceService").
+    // In-module routes resolve via resolveNotificationPreferenceService() (news up from the
+    // request-scoped em) since the request container does not expose this binding.
+    notificationPreferenceService: asFunction(({ em }) =>
+      createNotificationPreferenceService({ em })
+    ).scoped().proxy(),
   })
 }

package/src/modules/notifications/events.ts

@@ -1,6 +1,16 @@
 import { createModuleEvents } from '@open-mercato/shared/modules/events'
 import { NOTIFICATION_SSE_EVENTS } from './lib/events'
 
+/**
+ * Reconcile the code-registered notification type catalogue into the
+ * `notification_types` table. Emitted at tenant init; consumed by
+ * `subscribers/sync-notification-types.ts`.
+ */
+export const TYPE_REGISTRY_SYNC_EVENT = 'notifications.type_registry.sync'
+
+/** Lifecycle event emitted after a user's channel preferences change (workflow-trigger / subscriber surface). */
+export const PREFERENCE_UPDATED_EVENT = 'notifications.preference.updated'
+
 const events = [
   {
     id: NOTIFICATION_SSE_EVENTS.CREATED,
@@ -18,6 +28,19 @@ const events = [
     clientBroadcast: true,
     portalBroadcast: true,
   },
+  {
+    id: TYPE_REGISTRY_SYNC_EVENT,
+    label: 'Notification Type Registry Sync',
+    entity: 'notification_type',
+    category: 'system',
+    excludeFromTriggers: true,
+  },
+  {
+    id: PREFERENCE_UPDATED_EVENT,
+    label: 'Notification Preference Updated',
+    entity: 'notification_preference',
+    category: 'crud',
+  },
 ] as const
 
 export const eventsConfig = createModuleEvents({

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

@@ -0,0 +1,287 @@
+"use client"
+
+import * as React from 'react'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { Switch } from '@open-mercato/ui/primitives/switch'
+import { SimpleTooltip } from '@open-mercato/ui/primitives/tooltip'
+import { FilterBar, type FilterDef, type FilterValues } from '@open-mercato/ui/backend/FilterBar'
+import { FilteredEmptyResults } from '@open-mercato/ui/backend/filters/FilteredEmptyResults'
+
+export type NotificationTypeItem = {
+  id: string
+  labelKey: string
+  descriptionKey?: string | null
+  // Stable grouping key from /api/notifications/types (the declared category, else the type-id
+  // prefix). Filter on this — never on `categoryLabel`, which changes with the locale.
+  category?: string | null
+  // Server-resolved heading for `category`. Equals `category` when the owning module ships no
+  // `notifications.categories.<key>` translation.
+  categoryLabel?: string | null
+  // When true the type cannot be opted out of; the matrix locks its cells ON (the server drops
+  // opt-out writes for these, so a toggleable switch would silently lie on reload).
+  nonOptOut?: boolean
+  // Effective channel eligibility from /api/notifications/types (operator override, else the
+  // code-declared set; null/absent = every channel). A channel outside the set renders locked
+  // OFF and toggles are refused server-side too, so the lock is enforcement, not presentation.
+  channels?: string[] | null
+}
+export type PreferenceItem = { notificationTypeId: string; channel: string; enabled: boolean }
+
+export type ChannelDef = { key: string; labelKey: string; labelFallback: string; hintKey: string; hintFallback: string }
+
+/**
+ * Resilient fallback channel list used only while the `/api/notifications/channels` catalogue is
+ * loading or when the fetch fails. The authoritative source is the module-registered channel
+ * catalogue (see `notification-channels.ts`); callers pass the fetched channels into the helpers
+ * and the component. Keep this list minimal — it is a safety net, not the source of truth.
+ */
+export const PREFERENCE_CHANNELS: ChannelDef[] = [
+  {
+    key: 'in_app',
+    labelKey: 'notifications.preferences.channels.inApp',
+    labelFallback: 'In-app',
+    hintKey: 'notifications.preferences.channels.inAppHint',
+    hintFallback: 'Notification center and bell.',
+  },
+  {
+    key: 'email',
+    labelKey: 'notifications.preferences.channels.email',
+    labelFallback: 'Email',
+    hintKey: 'notifications.preferences.channels.emailHint',
+    hintFallback: 'Sent to your account email address.',
+  },
+  {
+    key: 'push',
+    labelKey: 'notifications.preferences.channels.push',
+    labelFallback: 'Push',
+    hintKey: 'notifications.preferences.channels.pushHint',
+    hintFallback: 'Mobile push (active once a push channel is connected).',
+  },
+]
+
+/** Map a `/api/notifications/channels` item to the UI channel shape. */
+export function toChannelDef(item: { id: string; labelKey: string; descriptionKey?: string | null }): ChannelDef {
+  return {
+    key: item.id,
+    labelKey: item.labelKey,
+    labelFallback: item.id,
+    hintKey: item.descriptionKey ?? '',
+    hintFallback: '',
+  }
+}
+
+export function preferenceKey(typeId: string, channel: string): string {
+  return `${typeId}::${channel}`
+}
+
+/** Whether the channel is outside the type's effective eligibility (cell locked off, tenant-wide). */
+export function isChannelDisabledForType(type: NotificationTypeItem, channel: string): boolean {
+  return Array.isArray(type.channels) && !type.channels.includes(channel)
+}
+
+/** Build the default-on preference map for a catalogue + stored rows; ineligible cells are forced off. */
+export function buildPreferenceMap(
+  types: NotificationTypeItem[],
+  stored: PreferenceItem[],
+  channels: ChannelDef[] = PREFERENCE_CHANNELS,
+): Record<string, boolean> {
+  const storedMap = new Map(stored.map((item) => [preferenceKey(item.notificationTypeId, item.channel), item.enabled]))
+  const next: Record<string, boolean> = {}
+  for (const type of types) {
+    for (const channel of channels) {
+      const key = preferenceKey(type.id, channel.key)
+      next[key] = isChannelDisabledForType(type, channel.key) ? false : storedMap.get(key) ?? true
+    }
+  }
+  return next
+}
+
+/**
+ * Return only the entries whose value differs from the originally-loaded state. The server upserts
+ * exactly what it receives (last-write-wins), so sending the diff keeps the payload bounded by the
+ * number of toggles — not the catalogue size — and avoids materializing redundant default-on rows.
+ */
+export function diffPreferenceItems(
+  types: NotificationTypeItem[],
+  initial: Record<string, boolean>,
+  current: Record<string, boolean>,
+  channels: ChannelDef[] = PREFERENCE_CHANNELS,
+): PreferenceItem[] {
+  const items: PreferenceItem[] = []
+  for (const type of types) {
+    for (const channel of channels) {
+      if (isChannelDisabledForType(type, channel.key)) continue
+      const key = preferenceKey(type.id, channel.key)
+      const before = initial[key] ?? true
+      const after = current[key] ?? true
+      if (before !== after) {
+        items.push({ notificationTypeId: type.id, channel: channel.key, enabled: after })
+      }
+    }
+  }
+  return items
+}
+
+export type NotificationPreferenceMatrixProps = {
+  types: NotificationTypeItem[]
+  prefs: Record<string, boolean>
+  onToggle: (typeId: string, channel: string, enabled: boolean) => void
+  disabled?: boolean
+  channels?: ChannelDef[]
+}
+
+export function NotificationPreferenceMatrix({
+  types,
+  prefs,
+  onToggle,
+  disabled,
+  channels = PREFERENCE_CHANNELS,
+}: NotificationPreferenceMatrixProps) {
+  const t = useT()
+  const [filterValues, setFilterValues] = React.useState<FilterValues>({})
+
+  // Options come from the catalogue itself, so a module introducing a new category shows up
+  // without touching this component. Sorted by the localized label, keyed by the stable slug.
+  const categoryOptions = React.useMemo(() => {
+    const byCategory = new Map<string, string>()
+    for (const type of types) {
+      if (!type.category) continue
+      if (!byCategory.has(type.category)) byCategory.set(type.category, type.categoryLabel ?? type.category)
+    }
+    return Array.from(byCategory, ([value, label]) => ({ value, label })).sort((left, right) =>
+      left.label.localeCompare(right.label),
+    )
+  }, [types])
+
+  const filters = React.useMemo<FilterDef[]>(
+    () =>
+      categoryOptions.length > 1
+        ? [
+            {
+              id: 'category',
+              label: t('notifications.preferences.filters.category', 'Category'),
+              // `tags` (searchable chips), not a `select` checkbox list: the catalogue grows a
+              // category per module, so the list gets long enough that scanning checkboxes stops
+              // scaling. Mirrors the customer/tag filters in SalesDocumentsTable.
+              type: 'tags',
+              options: categoryOptions,
+              placeholder: t('notifications.preferences.filters.categoryPlaceholder', 'Search categories'),
+              formatValue: (value: string) =>
+                categoryOptions.find((option) => option.value === value)?.label ?? value,
+            },
+          ]
+        : [],
+    [categoryOptions, t],
+  )
+
+  const selectedCategories = React.useMemo(() => {
+    const raw = filterValues.category
+    if (Array.isArray(raw)) return raw.filter((value): value is string => typeof value === 'string' && value !== '')
+    return typeof raw === 'string' && raw !== '' ? [raw] : []
+  }, [filterValues])
+
+  // Filtering happens at render only. The parent keeps the full `types` array, which
+  // `diffPreferenceItems` walks on save — narrowing it upstream would silently drop pending
+  // toggles for rows the filter hides.
+  const visibleTypes = React.useMemo(
+    () =>
+      selectedCategories.length === 0
+        ? types
+        : types.filter((type) => type.category != null && selectedCategories.includes(type.category)),
+    [types, selectedCategories],
+  )
+
+  if (types.length === 0) {
+    return (
+      <p className="text-sm text-muted-foreground">
+        {t('notifications.preferences.empty', 'No notification types are registered yet.')}
+      </p>
+    )
+  }
+
+  return (
+    <div className="flex flex-col gap-3">
+      {filters.length > 0 ? (
+        <FilterBar
+          filters={filters}
+          values={filterValues}
+          onApply={setFilterValues}
+          onClear={() => setFilterValues({})}
+        />
+      ) : null}
+      {visibleTypes.length === 0 ? (
+        <FilteredEmptyResults
+          entityNamePlural={t('notifications.preferences.entityNamePlural', 'notification types')}
+          canRemoveLast={selectedCategories.length > 0}
+          onClearAll={() => setFilterValues({})}
+          onRemoveLast={() => setFilterValues({})}
+        />
+      ) : (
+    <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.preferences.columns.type', 'Notification type')}</th>
+            {channels.map((channel) => (
+              <th key={channel.key} className="px-4 py-3 font-medium">
+                <div>{t(channel.labelKey, channel.labelFallback)}</div>
+                <div className="text-xs font-normal text-muted-foreground">{t(channel.hintKey, channel.hintFallback)}</div>
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {visibleTypes.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) => {
+                // Operator hard-off wins over the nonOptOut forced-on lock — mirrors the gate,
+                // where the tenant-wide channel block runs before the nonOptOut bypass.
+                const channelDisabled = isChannelDisabledForType(type, channel.key)
+                const locked = !channelDisabled && type.nonOptOut === true
+                const cellLabel = `${t(type.labelKey, type.id)} – ${t(channel.labelKey, channel.labelFallback)}`
+                const requiredHint = t(
+                  'notifications.preferences.requiredHint',
+                  'This notification is required and cannot be turned off.',
+                )
+                const channelDisabledHint = t(
+                  'notifications.preferences.channelDisabledHint',
+                  'This channel is turned off for this notification by your administrator.',
+                )
+                const lockHint = channelDisabled ? channelDisabledHint : requiredHint
+                const switchEl = (
+                  <Switch
+                    checked={channelDisabled ? false : locked ? true : prefs[preferenceKey(type.id, channel.key)] ?? true}
+                    disabled={disabled || locked || channelDisabled}
+                    onCheckedChange={(checked) => onToggle(type.id, channel.key, checked)}
+                    aria-label={locked || channelDisabled ? `${cellLabel} (${lockHint})` : cellLabel}
+                  />
+                )
+                return (
+                  <td key={channel.key} className="px-4 py-3">
+                    {locked || channelDisabled ? (
+                      <SimpleTooltip content={lockHint}>
+                        <span className="inline-flex">{switchEl}</span>
+                      </SimpleTooltip>
+                    ) : (
+                      switchEl
+                    )}
+                  </td>
+                )
+              })}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+      )}
+    </div>
+  )
+}
+
+export default NotificationPreferenceMatrix