sow-nodebb-theme/docs/superpowers/specs/2026-07-17-topbar-unread-drawer-design.md

Topbar Unread Drawer — Design

Date: 2026-07-17

Goal

Add an "Unread" item to the topbar utilities, next to notifications. It shows a live badge with the number of unread topics. Clicking it opens a dropdown that lists recent unread topics.

Template

New partial templates/partials/header/unread-drawer.tpl, imported in templates/partials/header/topbar.tpl just before the notifications <li> (logged-in menu only). It follows the structure of the neighboring utility dropdowns:

• Toggle button: fa-inbox icon, title="[[unread:title]]", badge <span component="unread/count" class="badge ... {{{ if !unreadCount.topic }}}hidden{{{ end }}}">{unreadCount.topic}</span>. NodeBB core sends unreadCount.topic in header data and live-updates any component="unread/count" badge over sockets, so the count needs no theme JS.
• Dropdown body: an empty <ul class="dropdown-menu wg-topbar__dropdown"> shell with a loading placeholder item.

Client JS

Small addition to public/client.js (inside the existing topbar init):

• On show.bs.dropdown for the unread item, call api.get('/unread', ...) (same data the /unread page uses).
• Render up to 10 topics as plain links: topic title, category name, unread-post count. Footer link "See all unread" → /unread.
• Re-fetch on every open (always fresh, no caching). Errors show a short "could not load" item — never a blank menu.

Skipped: mark-all-read, pagination, watched-filter tabs — the /unread page already has all of those.

SCSS

Reuse the existing .wg-topbar__dropdown styles. Only a few lines for the topic rows (truncation, spacing).

Mobile drawer

Add a plain "Unread" link with the same component="unread/count" badge to the burger-drawer actions block in topbar.tpl, matching the existing notifications/chats rows.

Accessibility

• Toggle is a real <a role="button">/dropdown like the other utility items, with aria-label and Bootstrap's dropdown keyboard handling.
• Badge count also appears in the accessible name (matching how the notifications item does it).

Verification

Manual + Playwright checks run against the sow-nodebb dev container (../sow-nodebb):

1. In ../sow-nodebb, set .env for theme work (PLUGIN_PATH=../sow-nodebb-theme, PLUGIN_ID=nodebb-theme-westgate, EXTRA_PLUGINS=nodebb-plugin-westgate-wiki), then make dev → forum at http://localhost:4567.
2. After template/JS/SCSS edits: make dev-build in ../sow-nodebb, then reload the browser.
3. Playwright (playwright-skill / MCP browser tools) against http://localhost:4567: log in, confirm the Unread button exists next to notifications, badge shows the unread count, opening the dropdown lists unread topics with working links, and the footer link lands on /unread. Also check the mobile burger drawer shows the Unread row.

Existing template contract test tests/global-topbar-contract.test.js is updated if it asserts the utility-list structure.