> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuturuuu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Notifications popover

> Read state, open in context, grouping, mark all read, keyboard model and loading boundaries of the shared notification bell.

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](https://docs.tuturuuu.com/platform/features/notification-access.md).

## 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.

| Notification | Opens |
| - | - |
| Task (`entity_type = 'task'`) | Tasks `/{wsId}/tasks/{taskId}`, in place when the current host already shows that workspace's tasks |
| `mail_received` | Mail `/personal?mailbox={mailboxId}&thread={threadId}` |
| Chat (`entity_type = 'chat_conversation'`) | Chat `/{wsId}?conversationId={id}` |
| Time-tracking request | Track `/{wsId}/requests` |

* 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`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.