create-freakpunch 0.0.0-stage → 0.2.0

package/template/src/core/layout/command-menu.tsx

@@ -0,0 +1,117 @@
+import { createContext, useCallback, useContext, useEffect, useMemo, useState, type ReactNode } from 'react'
+import { useNavigate } from 'react-router'
+import { LogOut } from 'lucide-react'
+
+import {
+  Command,
+  CommandDialog,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+  CommandSeparator,
+} from '@/components/ui/command'
+import type { Permission } from '@/core/auth/permissions'
+import { useAuth } from '@/core/auth/use-auth'
+import { useAnyT } from '@/core/i18n/keys'
+import { usePermissions } from '@/core/auth/can'
+import { navItems, quickActions } from '@/core/modules/navigation'
+import { useTheme } from '@/core/theme/theme-context'
+import { themeOptions } from '@/core/theme/theme-options'
+
+type CommandMenuContextValue = { open: () => void }
+const CommandMenuContext = createContext<CommandMenuContextValue | null>(null)
+
+// eslint-disable-next-line react/only-export-components
+export const isMac = typeof navigator !== 'undefined' && /Mac|iPhone|iPad/.test(navigator.platform)
+
+/** ⌘K / Ctrl+K palette: navigation, quick actions, theme, sign out. */
+export function CommandMenuProvider({ children }: { children: ReactNode }) {
+  const [isOpen, setOpen] = useState(false)
+  const navigate = useNavigate()
+  const { setTheme } = useTheme()
+  const { logout } = useAuth()
+  const t = useAnyT()
+  const { can } = usePermissions()
+  const allowed = <T extends { permission?: Permission }>(items: T[]) =>
+    items.filter((item) => !item.permission || can(item.permission))
+
+  useEffect(() => {
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key.toLowerCase() === 'k' && (e.metaKey || e.ctrlKey)) {
+        e.preventDefault()
+        setOpen((o) => !o)
+      }
+    }
+    window.addEventListener('keydown', onKeyDown)
+    return () => window.removeEventListener('keydown', onKeyDown)
+  }, [])
+
+  const run = useCallback((fn: () => void) => {
+    setOpen(false)
+    fn()
+  }, [])
+
+  const value = useMemo(() => ({ open: () => setOpen(true) }), [])
+
+  return (
+    <CommandMenuContext value={value}>
+      {children}
+      <CommandDialog open={isOpen} onOpenChange={setOpen} title={t('command.title')} description={t('command.description')}>
+        <Command>
+          <CommandInput placeholder={t('command.placeholder')} />
+          <CommandList>
+            <CommandEmpty>{t('command.empty')}</CommandEmpty>
+            <CommandGroup heading={t('command.pages')}>
+              {allowed(navItems).map(({ path, label, icon: Icon }) => (
+                <CommandItem key={path} value={`page ${t(label)}`} onSelect={() => run(() => navigate(path))}>
+                  <Icon />
+                  {t(label)}
+                </CommandItem>
+              ))}
+            </CommandGroup>
+            {allowed(quickActions).length > 0 && (
+              <CommandGroup heading={t('command.actions')}>
+                {allowed(quickActions).map(({ path, label, icon: Icon }) => (
+                  <CommandItem key={path} value={`action ${t(label)}`} onSelect={() => run(() => navigate(path))}>
+                    <Icon />
+                    {t(label)}
+                  </CommandItem>
+                ))}
+              </CommandGroup>
+            )}
+            <CommandSeparator />
+            <CommandGroup heading={t('command.preferences')}>
+              {themeOptions.map(({ value, icon: Icon }) => (
+                <CommandItem key={value} value={`theme ${value} ${t(`theme.${value}`)}`} onSelect={() => run(() => setTheme(value))}>
+                  <Icon />
+                  {t('theme.command', { theme: t(`theme.${value}`) })}
+                </CommandItem>
+              ))}
+              <CommandItem
+                value={`sign out logout ${t('shell.signOut')}`}
+                onSelect={() =>
+                  run(() => {
+                    void logout()
+                    navigate('/login')
+                  })
+                }
+              >
+                <LogOut />
+                {t('shell.signOut')}
+              </CommandItem>
+            </CommandGroup>
+          </CommandList>
+        </Command>
+      </CommandDialog>
+    </CommandMenuContext>
+  )
+}
+
+// eslint-disable-next-line react/only-export-components
+export function useCommandMenu() {
+  const ctx = useContext(CommandMenuContext)
+  if (!ctx) throw new Error('useCommandMenu must be used within <CommandMenuProvider>')
+  return ctx
+}

package/template/src/core/layout/top-bar.tsx

@@ -0,0 +1,100 @@
+import { Fragment, lazy, Suspense, useEffect, useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { Link, useMatches } from 'react-router'
+
+import {
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+} from '@/components/ui/breadcrumb'
+import { Separator } from '@/components/ui/separator'
+import { SidebarTrigger } from '@/components/ui/sidebar'
+import { authMode, isFeatureOn } from '@/core/config/runtime'
+import { LanguageSwitcher } from '@/core/i18n/language-switcher'
+import { NotificationBell } from '@/core/notifications/notification-center'
+import { useAnyT } from '@/core/i18n/keys'
+import { useFormat } from '@/core/i18n/use-format'
+import type { RouteHandle } from '@/core/modules/types'
+import { ThemeToggle } from '@/core/theme/theme-toggle'
+
+/** Dev-only role switcher; `import.meta.env.DEV` is false in production so the chunk is dropped. */
+const DevRoleSwitcher = import.meta.env.DEV && authMode === 'mock'
+  ? lazy(() => import('@/core/auth/dev-role-switcher').then((m) => ({ default: m.DevRoleSwitcher })))
+  : null
+
+/** Breadcrumbs come from `handle.crumb` on matched routes. */
+function Breadcrumbs() {
+  const matches = useMatches()
+  const t = useAnyT()
+  const crumbs = matches
+    .map((m) => {
+      const crumb = (m.handle as RouteHandle | undefined)?.crumb
+      if (!crumb) return null
+      return { path: m.pathname, label: t(crumb) }
+    })
+    .filter((c): c is { path: string; label: string } => c !== null)
+    // Index routes repeat their parent's pathname; keep the deepest.
+    .filter((c, i, all) => all.findIndex((o) => o.path === c.path) === i)
+
+  return (
+    <Breadcrumb className="min-w-0" aria-label={t('shell.breadcrumb')}>
+      <BreadcrumbList className="flex-nowrap">
+        {crumbs.map((c, i) => {
+          const last = i === crumbs.length - 1
+          return (
+            <Fragment key={c.path}>
+              {i > 0 && <BreadcrumbSeparator className="hidden sm:inline-flex" />}
+              <BreadcrumbItem className={last ? 'min-w-0' : 'hidden sm:inline-flex'}>
+                {last ? (
+                  <BreadcrumbPage className="truncate">{c.label}</BreadcrumbPage>
+                ) : (
+                  <BreadcrumbLink render={<Link to={c.path} />}>{c.label}</BreadcrumbLink>
+                )}
+              </BreadcrumbItem>
+            </Fragment>
+          )
+        })}
+      </BreadcrumbList>
+    </Breadcrumb>
+  )
+}
+
+function Clock() {
+  const [now, setNow] = useState(() => new Date())
+  const fmt = useFormat()
+  useEffect(() => {
+    const t = setInterval(() => setNow(new Date()), 30_000)
+    return () => clearInterval(t)
+  }, [])
+  return (
+    <span className="hidden h-7 items-center gap-1.5 rounded-full border px-2.5 tabular-nums text-[10.5px] tracking-wide text-muted-foreground uppercase md:inline-flex">
+      <span aria-hidden className="size-1.5 rounded-full bg-success" />
+      <time dateTime={now.toISOString()}>{fmt.clock(now)}</time>
+    </span>
+  )
+}
+
+export function TopBar() {
+  const { t } = useTranslation()
+  return (
+    <header className="flex h-(--topbar-height) shrink-0 items-center gap-2 border-b px-3 md:px-4">
+      <SidebarTrigger className="-ml-1 text-muted-foreground" aria-label={t('shell.toggleSidebar')} />
+      <Separator orientation="vertical" className="mx-1 self-center data-vertical:h-4" />
+      <Breadcrumbs />
+      <div className="ml-auto flex items-center gap-1.5">
+        {DevRoleSwitcher && (
+          <Suspense>
+            <DevRoleSwitcher />
+          </Suspense>
+        )}
+        <LanguageSwitcher />
+        <Clock />
+        {isFeatureOn('notifications') && <NotificationBell />}
+        <ThemeToggle />
+      </div>
+    </header>
+  )
+}

package/template/src/core/lib/csv.ts

@@ -0,0 +1,27 @@
+export type CsvColumn<T> = { header: string; value: (row: T) => string | number | boolean | null | undefined }
+
+/** Spreadsheet apps run cells starting with these as formulas; a leading quote keeps them as text. */
+const FORMULA_START = /^[=+\-@\t\r]/
+
+function cell(value: string | number | boolean | null | undefined) {
+  if (value === null || value === undefined) return ''
+  const text = typeof value === 'string' && FORMULA_START.test(value) ? `'${value}` : String(value)
+  return /[",;\r\n]/.test(text) ? `"${text.replaceAll('"', '""')}"` : text
+}
+
+/**
+ * Downloads rows as a CSV file. The BOM makes Excel read UTF-8 correctly
+ * (ç ğ ı İ ö ş ü); `;` is the list separator Excel expects in Turkish locales.
+ */
+export function downloadCsv<T>(filename: string, columns: CsvColumn<T>[], rows: T[], delimiter: ',' | ';' = ',') {
+  const lines = [
+    columns.map((c) => cell(c.header)).join(delimiter),
+    ...rows.map((row) => columns.map((c) => cell(c.value(row))).join(delimiter)),
+  ]
+  const url = URL.createObjectURL(new Blob([`${lines.join('\r\n')}`], { type: 'text/csv;charset=utf-8' }))
+  const link = document.createElement('a')
+  link.href = url
+  link.download = filename.endsWith('.csv') ? filename : `${filename}.csv`
+  link.click()
+  URL.revokeObjectURL(url)
+}

package/template/src/core/lib/format.ts

@@ -0,0 +1,87 @@
+export type FormatOptions = {
+  /** BCP 47 locale, e.g. en-US, tr-TR. */
+  locale: string
+  /** ISO 4217 code, e.g. USD, TRY. */
+  currency: string
+  /** IANA zone; undefined = the browser's. */
+  timeZone?: string
+  /** Fixed numeric pattern, or 'auto' for the locale's medium date. */
+  dateFormat?: 'auto' | 'dd.MM.yyyy' | 'MM/dd/yyyy' | 'yyyy-MM-dd'
+}
+
+/**
+ * Locale-aware formatters. Components get them from useFormat()
+ * (core/i18n/use-format.ts), which follows the active language and
+ * preferences; don't format numbers or dates by hand.
+ */
+export function createFormatters({ locale, currency, timeZone, dateFormat = 'auto' }: FormatOptions) {
+  const currencyFmt = new Intl.NumberFormat(locale, { style: 'currency', currency })
+  const currencyWhole = new Intl.NumberFormat(locale, { style: 'currency', currency, maximumFractionDigits: 0 })
+  const compact = new Intl.NumberFormat(locale, { notation: 'compact', maximumFractionDigits: 1 })
+  const compactCurrency = new Intl.NumberFormat(locale, { style: 'currency', currency, notation: 'compact', maximumFractionDigits: 1 })
+  const number = new Intl.NumberFormat(locale)
+  const percent = new Intl.NumberFormat(locale, { style: 'percent', minimumFractionDigits: 1, maximumFractionDigits: 2 })
+  const delta = new Intl.NumberFormat(locale, { style: 'percent', signDisplay: 'exceptZero', minimumFractionDigits: 1, maximumFractionDigits: 1 })
+  const date = new Intl.DateTimeFormat(locale, { month: 'short', day: 'numeric', year: 'numeric', timeZone })
+  const dateTime = new Intl.DateTimeFormat(locale, { dateStyle: 'medium', timeStyle: 'short', timeZone })
+  const dayMonth = new Intl.DateTimeFormat(locale, { month: 'short', day: 'numeric', timeZone })
+  const weekdayDayMonth = new Intl.DateTimeFormat(locale, { weekday: 'short', month: 'short', day: 'numeric', timeZone })
+  const clock = new Intl.DateTimeFormat(locale, { weekday: 'short', month: 'short', day: 'numeric', hour: 'numeric', minute: '2-digit', timeZone })
+  const relative = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' })
+  const time = new Intl.DateTimeFormat(locale, { timeStyle: 'short', timeZone })
+  const numericParts = new Intl.DateTimeFormat('en-US', { day: '2-digit', month: '2-digit', year: 'numeric', timeZone })
+
+  const toDate = (value: string | Date) => (typeof value === 'string' ? new Date(value) : value)
+
+  /** Applies the user's numeric date pattern (in the right time zone). */
+  function pattern(d: Date) {
+    const parts = Object.fromEntries(numericParts.formatToParts(d).map((p) => [p.type, p.value]))
+    return dateFormat.replace('dd', parts.day!).replace('MM', parts.month!).replace('yyyy', parts.year!)
+  }
+
+  return {
+    locale,
+    /** "$", "₺", "€" — for input prefixes. */
+    currencySymbol: currencyFmt.formatToParts(0).find((p) => p.type === 'currency')?.value ?? currency,
+    currency: (value: number) => currencyFmt.format(value),
+    /** Currency without decimals, for KPIs. */
+    currencyWhole: (value: number) => currencyWhole.format(value),
+    compact: (value: number) => compact.format(value),
+    compactCurrency: (value: number) => compactCurrency.format(value),
+    number: (value: number) => number.format(value),
+    /** 3.42 → "3.42%" (input is already a percentage). */
+    percent: (value: number) => percent.format(value / 100),
+    /** 12.4 → "+12.4%" for changes vs a previous period. */
+    delta: (value: number) => delta.format(value / 100),
+    date: (value: string | Date) => (dateFormat === 'auto' ? date.format(toDate(value)) : pattern(toDate(value))),
+    dateTime: (value: string | Date) =>
+      dateFormat === 'auto' ? dateTime.format(toDate(value)) : `${pattern(toDate(value))} ${time.format(toDate(value))}`,
+    time: (value: string | Date) => time.format(toDate(value)),
+    dayMonth: (value: string | Date) => dayMonth.format(toDate(value)),
+    weekdayDayMonth: (value: string | Date) => weekdayDayMonth.format(toDate(value)),
+    clock: (value: string | Date) => clock.format(toDate(value)),
+    relative(value: string | Date) {
+      const diff = (toDate(value).getTime() - Date.now()) / 1000
+      const units: [Intl.RelativeTimeFormatUnit, number][] = [
+        ['day', 86400],
+        ['hour', 3600],
+        ['minute', 60],
+      ]
+      for (const [unit, seconds] of units) {
+        if (Math.abs(diff) >= seconds) return relative.format(Math.round(diff / seconds), unit)
+      }
+      return relative.format(0, 'second')
+    },
+  }
+}
+
+export type Formatters = ReturnType<typeof createFormatters>
+
+export function initials(name: string) {
+  return name
+    .split(/\s+/)
+    .map((part) => part[0])
+    .join('')
+    .slice(0, 2)
+    .toLocaleUpperCase()
+}

package/template/src/core/lib/phone.ts

@@ -0,0 +1,50 @@
+/**
+ * Minimal phone handling: a country calling code plus a national number,
+ * stored as E.164 (+905321234567). Lengths are national significant digits.
+ */
+export const phoneCountries = [
+  { code: 'TR', dial: '+90', min: 10, max: 10 },
+  { code: 'US', dial: '+1', min: 10, max: 10 },
+  { code: 'GB', dial: '+44', min: 9, max: 10 },
+  { code: 'DE', dial: '+49', min: 6, max: 11 },
+  { code: 'FR', dial: '+33', min: 9, max: 9 },
+  { code: 'NL', dial: '+31', min: 9, max: 9 },
+  { code: 'AZ', dial: '+994', min: 9, max: 9 },
+  { code: 'AE', dial: '+971', min: 8, max: 9 },
+] as const
+
+export type PhoneCountry = (typeof phoneCountries)[number]['code']
+export const defaultPhoneCountry: PhoneCountry = 'TR'
+
+const digits = (value: string) => value.replace(/\D/g, '')
+const country = (code: string) => phoneCountries.find((c) => c.code === code) ?? phoneCountries[0]
+
+/** National digits without a trunk prefix (Turkish numbers are often typed as 0532…). */
+function national(code: string, number: string) {
+  const d = digits(number)
+  return code === 'TR' && d.length === 11 && d.startsWith('0') ? d.slice(1) : d
+}
+
+export function isValidPhone(code: string, number: string) {
+  const { min, max } = country(code)
+  const d = national(code, number)
+  if (/[^\d\s()+.-]/.test(number)) return false
+  if (code === 'TR' && !/^[2-5]/.test(d)) return false
+  return d.length >= min && d.length <= max
+}
+
+export function toE164(code: string, number: string) {
+  return `${country(code).dial}${national(code, number)}`
+}
+
+export function dialCode(code: string) {
+  return country(code).dial
+}
+
+/** Splits a stored E.164 number back into country + national number. */
+export function splitPhone(e164: string | undefined): { country: PhoneCountry; number: string } {
+  if (!e164) return { country: defaultPhoneCountry, number: '' }
+  // Longest dial code first so +994 wins over +9x.
+  const match = [...phoneCountries].sort((a, b) => b.dial.length - a.dial.length).find((c) => e164.startsWith(c.dial))
+  return match ? { country: match.code, number: e164.slice(match.dial.length) } : { country: defaultPhoneCountry, number: digits(e164) }
+}

package/template/src/core/lib/storage.ts

@@ -0,0 +1,27 @@
+/** Namespaced, JSON-safe localStorage access that never throws. */
+const PREFIX = 'fp:'
+
+export const storage = {
+  get<T>(key: string): T | null {
+    try {
+      const raw = localStorage.getItem(PREFIX + key)
+      return raw ? (JSON.parse(raw) as T) : null
+    } catch {
+      return null
+    }
+  },
+  set(key: string, value: unknown) {
+    try {
+      localStorage.setItem(PREFIX + key, JSON.stringify(value))
+    } catch {
+      // Storage full or blocked: settings simply won't persist.
+    }
+  },
+  remove(key: string) {
+    try {
+      localStorage.removeItem(PREFIX + key)
+    } catch {
+      // ignore
+    }
+  },
+}

package/template/src/core/modules/lazy-page.ts

@@ -0,0 +1,9 @@
+import type { ComponentType } from 'react'
+
+/**
+ * Route `lazy` helper for code-split pages with a default export:
+ *   { path: 'products', lazy: lazyPage(() => import('./pages/products-list-page')) }
+ */
+export const lazyPage = (load: () => Promise<{ default: ComponentType }>) => async () => ({
+  Component: (await load()).default,
+})

package/template/src/core/modules/navigation.ts

@@ -0,0 +1,39 @@
+import { LayoutGrid, SlidersHorizontal, Settings } from 'lucide-react'
+
+import { appConfig } from '@/app.config'
+import type { Permission } from '@/core/auth/permissions'
+import { enabledModules } from '@/modules/registry'
+import type { NavItem, QuickAction } from './types'
+
+/** Core entries present in every project. */
+const coreNav: NavItem[] = [
+  { label: 'common:nav.dashboard', path: '/app', icon: LayoutGrid, group: 'overview', end: true, permission: 'dashboard.view' },
+  { label: 'common:nav.settings', path: '/app/settings', icon: Settings, group: 'system' },
+]
+
+const coreQuickActions: QuickAction[] = [
+  {
+    label: 'dashboard:quickActions.appearance',
+    description: 'dashboard:quickActions.appearanceDescription',
+    path: '/app/settings/preferences',
+    icon: SlidersHorizontal,
+  },
+]
+
+export const navItems: NavItem[] = [...coreNav, ...enabledModules.flatMap((m) => m.nav)]
+
+/** Nav items the user may see, grouped in the order of appConfig.navGroups; empty groups are dropped. */
+export function getNavGroups(can: (permission: Permission) => boolean) {
+  return appConfig.navGroups
+    .map((group) => ({
+      ...group,
+      items: navItems.filter((item) => item.group === group.id && (!item.permission || can(item.permission))),
+    }))
+    .filter((group) => group.items.length > 0)
+}
+
+export const quickActions: QuickAction[] = [...enabledModules.flatMap((m) => m.quickActions ?? []), ...coreQuickActions]
+
+export function isNavItemActive(item: NavItem, pathname: string) {
+  return item.end ? pathname === item.path : pathname === item.path || pathname.startsWith(item.path + '/')
+}

package/template/src/core/modules/types.ts

@@ -0,0 +1,55 @@
+import type { ComponentType } from 'react'
+import type { LucideIcon } from 'lucide-react'
+import type { RouteObject } from 'react-router'
+
+import type { Permission } from '@/core/auth/permissions'
+import type { I18nKey } from '@/core/i18n/keys'
+
+/** A sidebar entry. `group` must match an id in appConfig.navGroups. */
+export type NavItem = {
+  /** Translation key, e.g. 'products:nav'. */
+  label: I18nKey
+  /** Absolute path, e.g. "/app/products". */
+  path: string
+  icon: LucideIcon
+  group: string
+  /** Optional hook returning a count for the badge (e.g. items needing attention). */
+  useBadge?: () => number | undefined
+  /** Match only the exact path when deciding the active state. */
+  end?: boolean
+  /** Hidden unless the user has this permission (use the same one on the route). */
+  permission?: Permission
+}
+
+/** Shortcut shown on the dashboard and in the ⌘K menu. */
+export type QuickAction = {
+  label: I18nKey
+  description?: I18nKey
+  path: string
+  icon: LucideIcon
+  permission?: Permission
+}
+
+/**
+ * A self-contained feature area. Routes are mounted under /app and rendered
+ * inside the app shell. Add a crumb via `handle: { crumb: 'ns:key' }`.
+ */
+export type AppModule = {
+  id: string
+  nav: NavItem[]
+  routes: RouteObject[]
+  quickActions?: QuickAction[]
+  /** Cards shown on the dashboard, e.g. a module's KPIs. Gate them with `<Can>` inside. */
+  dashboardWidgets?: ComponentType[]
+}
+
+/** Route `handle` shape: breadcrumbs and access control. */
+export type RouteHandle = {
+  /** Translation key of the breadcrumb label. */
+  crumb?: I18nKey
+  /**
+   * Required permission for this route and its children. The app shell
+   * redirects to /app/no-access when the user lacks it (UI only, not security).
+   */
+  permission?: Permission
+}

package/template/src/core/notifications/hooks.ts

@@ -0,0 +1,84 @@
+import { useEffect } from 'react'
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+
+import { useSession } from '@/core/auth/use-auth'
+import { notificationsService } from './notifications.service'
+import type { AppNotification, NotificationSettings } from './types'
+
+/** How often the feed is refetched. A push channel (`subscribe`) makes changes appear sooner. */
+const POLL_INTERVAL = 30_000
+
+/** Keys are scoped to the signed-in user, so the role switcher never shows another user's feed. */
+export function useNotificationKeys() {
+  const userId = useSession()?.user.id ?? 'anonymous'
+  const all = ['notifications', userId] as const
+  return { all, list: [...all, 'list'] as const, settings: [...all, 'settings'] as const }
+}
+
+export function useNotifications() {
+  const keys = useNotificationKeys()
+  const qc = useQueryClient()
+  const userId = keys.all[1]
+
+  // Push (SSE / WebSocket) when the service supports it; polling below stays as the fallback.
+  useEffect(
+    () => notificationsService.subscribe?.(() => void qc.invalidateQueries({ queryKey: ['notifications', userId, 'list'] })),
+    [qc, userId],
+  )
+
+  return useQuery({
+    queryKey: keys.list,
+    queryFn: () => notificationsService.list(),
+    refetchInterval: POLL_INTERVAL,
+  })
+}
+
+export const isUnread = (n: AppNotification) => !n.readAt
+
+export function useUnreadNotificationCount() {
+  return useNotifications().data?.filter(isUnread).length ?? 0
+}
+
+/** Optimistically marks notifications read in the cached feed, then syncs with the server. */
+function useReadMutation<T>(fn: (input: T) => Promise<void>, match: (n: AppNotification, input: T) => boolean) {
+  const qc = useQueryClient()
+  const keys = useNotificationKeys()
+  return useMutation({
+    mutationFn: fn,
+    onMutate: async (input) => {
+      await qc.cancelQueries({ queryKey: keys.list })
+      const previous = qc.getQueryData<AppNotification[]>(keys.list)
+      const now = new Date().toISOString()
+      qc.setQueryData<AppNotification[]>(keys.list, (list) =>
+        list?.map((n) => (!n.readAt && match(n, input) ? { ...n, readAt: now } : n)),
+      )
+      return { previous }
+    },
+    onError: (_error, _input, context) => qc.setQueryData(keys.list, context?.previous),
+    onSettled: () => qc.invalidateQueries({ queryKey: keys.list }),
+  })
+}
+
+export const useMarkNotificationRead = () =>
+  useReadMutation((id: string) => notificationsService.markRead(id), (n, id) => n.id === id)
+
+export const useMarkAllNotificationsRead = () =>
+  useReadMutation(() => notificationsService.markAllRead(), () => true)
+
+export function useNotificationSettings() {
+  const keys = useNotificationKeys()
+  return useQuery({ queryKey: keys.settings, queryFn: () => notificationsService.settings() })
+}
+
+export function useUpdateNotificationSettings() {
+  const qc = useQueryClient()
+  const keys = useNotificationKeys()
+  return useMutation({
+    mutationFn: (settings: NotificationSettings) => notificationsService.updateSettings(settings),
+    onSuccess: (data) => {
+      qc.setQueryData(keys.settings, data)
+      // Turning an event off (or on) changes which notifications the feed contains.
+      return qc.invalidateQueries({ queryKey: keys.list })
+    },
+  })
+}