Skip to main content
Every app that shows a notification bell renders the same shared popover from @tuturuuu/ui/custom/satellite-notification-popover. Web and Workspace mount it through their notification-popover.tsx wrappers; satellites mount @tuturuuu/satellite/notification-popover (server) or @tuturuuu/satellite/notification-popover-view (client-rendered apps). Apps do not ship their own popover. Who may see a notification is unchanged and described in Notification access.

Read state

  • Read state is the only state. The popover shows Unread (default) and All. There is no separate archive: the API has no archive state distinct from read_at.
  • Each row has one toggle that names its effect (Mark as read / Mark as unread). Opening a row that leads somewhere also marks it read; rows with nothing to open keep their state. Accepting or declining a workspace invite marks it read.
  • Toggles are optimistic. A failed request restores only rows that still show the optimistic value and only in lists that have not received newer server data since, and counts that still show the optimistic value. Polling and window-focus refreshes pause while a change is in flight, and overlapping changes reconcile once, after the last one settles, across every scope they touched.

Open in context

App-sourced rows show Open in <app> and open the exact item in its app. Opening marks the row read. Rows with no target (system notices, pending workspace invites) show no Open action.
  • Targets come only from UUID-checked row ids and the first-party app registry (resolveLaunchableAppUrl). Stored URLs (action_url, data.*) are never followed, so notification data cannot send the viewer to another origin.
  • The owning app authorizes the item when it loads; a revoked or deleted item shows that app’s own not-found or access state.
  • Resolver and tests: packages/ui/src/components/ui/custom/notification-targets.ts.

Scope

  • Inside a workspace route the popover lists that workspace. All workspaces switches the list, counts and Mark all read to every notification the account can access. Outside a workspace route it is always account-wide.
  • Optimistic updates and refreshes touch only caches that can contain the changed workspace, and only for the signed-in account.

Mark all read

  • Mark all read applies to the current scope only and zeroes the matching counts at once; a failed request restores the rows and counts that still show the optimistic value.
  • PATCH /api/v1/notifications with { action: 'mark_all_read' | 'mark_all_unread', wsId?, scope? } returns { success }. Each route keeps its own authentication and every statement is bounded by the account’s notification access filter. Clients call it through @tuturuuu/internal-api/notification-popover, never raw fetch.
  • Undo is not offered. The client shows Undo only when the server returns changed ids with per-row read revisions, which the current route does not.

Grouping

  • Needs action (unresolved workspace invites) stays on top until resolved.
  • Then Today, Yesterday and Earlier by the viewer’s local day.
  • Repeated events of one type on one entity within a section collapse into one row with an expandable count. A stack is unread while any member is unread, and marking it read marks every unread member.

Placement, focus and touch

  • A bell in the shared sidebar opens beside the rail (right, end-aligned) and never covers it; on narrow screens, where the sidebar is a sheet, it opens above the footer. A navbar bell opens below, end-aligned. Hosts can override with side/align.
  • Opening focuses the first row once rows load; Escape closes and returns focus to the bell. After Mark all read, focus stays in the dialog.
  • Rows use roving focus: ↑/↓, Home and End move; E toggles read state; Enter opens. Tab reaches row controls. Read changes are announced in a polite live region.
  • Every read toggle is visible and labelled, with a 44px hit area around a 32px visual. Other controls grow to 44px on coarse pointers.
  • The header, filters and footer stay fixed; only the list scrolls, with sticky section labels. Height is clamped to the space available next to the bell.

Loading and freshness

  • A closed bell runs only the unread-count query. The list query and the panel code load when the bell is hovered or focused (intent prefetch of the first Unread page) or opened.
  • Lists page by 20 rows as the end scrolls into view. Reopening refetches only the first page of a list closed with more pages loaded.
  • Freshness uses the existing per-user shared refresh registry (one interval per user per document, paused while hidden or offline). It skips a refresh while a read change is pending. Apps without the registry keep their explicit polling interval.

States

Loading skeleton, first-load error with Retry, refresh failure banner that keeps earlier results, loading more, load-more error with Retry, all caught up (with Show all) and no notifications yet.

Notifications page

Web’s /{wsId}/notifications page (for example /personal/notifications, the popover’s View all) is the full inbox. It renders @tuturuuu/ui/custom/notification-page-client with the same rows, read rules, open-in-context targets and caches as the popover.
  • Default and filters: opens on Unread. All shows every notification. The personal inbox is account-wide. A workspace route lists every accessible notification by default, and All workspaces narrows it to the route’s workspace.
  • Grouping: Time uses the popover sections. App puts Needs action first, then Tasks, Mail, Chat, Track, Workspaces and Account (system notices). A section’s Mark all read marks only that section’s loaded rows.
  • Selection: a checkbox appears on hover or focus, always on touch, and on every row once one is selected. Shift selects a range, and the header checkbox selects every loaded row. While rows are selected, the toolbar shows Mark as read, Mark as unread and Clear selection in the same bar. Mark as unread is disabled in Unread, where every row is already unread. Bulk changes use the per-row optimistic update rules. Afterwards focus moves to the select-all checkbox, or to the page heading when the list is now empty. Esc pressed on a row keeps focus on that row. Changing the filter or scope clears the selection.
  • Keyboard:
    • ↑/↓ or J/K, Home and End move between rows.
    • Enter opens a row, and E toggles its read state.
    • X or Space selects a row; Shift+X selects a range.
    • Esc clears the selection, and ? opens the shortcut sheet (shared Dialog). Both keys work from anywhere on the page except text fields and open overlays.
  • Failed loads: if a next page fails to load, loading stops until the user presses Retry, so a visible list end does not retry in a loop. The popover list uses the same rule.
  • No layout shift:
    • The title row and the fixed-height toolbar always render. Controls stay disabled until the first page loads, and the unread count has a reserved slot.
    • Skeleton rows use the selectable row grid.
    • Empty and error states fill the same minimum-height region.
    • Selection changes only the toolbar’s contents and the row background.
  • Rows load 30 at a time as the end of the list scrolls into view.
  • Archive is not available. Read state is the only state (see Read state).

Regression coverage

  • packages/users-core/src/lib/notifications/bulk-read-state.test.ts
  • apps/web/src/app/api/v1/notifications/list-notifications.test.ts
  • packages/internal-api/src/notification-popover.test.ts
  • packages/ui/src/components/ui/custom/notification-placement.test.tsx
  • apps/web/e2e/notification-popover-layout.fixture.ts (390/728/1024/1440, sidebar and navbar, EN/VI; fixture in packages/ui/fixtures/notification-popover)
  • packages/ui/src/hooks/__tests__/notification-cache.test.ts
  • packages/ui/src/hooks/__tests__/use-notifications-mutations.test.tsx
  • packages/ui/src/components/ui/custom/__tests__/notification-popover.test.tsx
  • packages/ui/src/components/ui/custom/notification-grouping.test.ts
  • packages/ui/src/components/ui/custom/__tests__/notification-page.test.tsx (page filters, grouping, selection, keyboard and the layout-stability regression)
  • packages/ui/src/components/ui/custom/notification-card.test.tsx
  • packages/satellite/src/components/notification-popover.test.tsx