docs: topbar unread drawer implementation plan
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Claude Fable 5
@@ -0,0 +1,346 @@
|
||||
# Topbar Unread Drawer Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Add an "Unread" dropdown to the topbar utilities (next to notifications) with a live unread-topic count badge and a fetched list of unread topics.
|
||||
|
||||
**Architecture:** A new template partial imported by `topbar.tpl` gives the button + badge (core's `component="unread/count"` socket updates make the badge live for free). A small addition to `public/client.js` fetches `/api/unread` on dropdown open and renders topic links with plain DOM building. SCSS reuses the existing `.wg-topbar__dropdown` vocabulary.
|
||||
|
||||
**Tech Stack:** NodeBB templates (benchpress `.tpl`), jQuery/Bootstrap 5 dropdown events, NodeBB client `api` module, SCSS. Tests are plain-Node assert scripts in `tests/` (run with `node tests/<file>.test.js`).
|
||||
|
||||
## Global Constraints
|
||||
|
||||
- NixOS host: no global installs; run tests with plain `node`.
|
||||
- One branch, one PR: all commits go on the existing `feat/topbar-unread-drawer` branch.
|
||||
- Verification against the dev container in `../sow-nodebb` (`make dev`, `make dev-build`), forum at http://localhost:4567. Theme edits need `make dev-build` before they show up.
|
||||
- Titles from the API must be inserted with `textContent` (never HTML strings) — trust boundary.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Unread drawer template + mobile drawer link
|
||||
|
||||
**Files:**
|
||||
- Create: `templates/partials/header/unread-drawer.tpl`
|
||||
- Modify: `templates/partials/header/topbar.tpl` (logged-in utility list, before the notifications `<li>`; and the drawer-actions block)
|
||||
- Test: `tests/global-topbar-contract.test.js` (append assertions)
|
||||
|
||||
**Interfaces:**
|
||||
- Produces: `<li component="unread" ...>` containing a dropdown toggle and `<ul ... data-wg-unread-menu>`; Task 2's JS binds to `.wg-topbar [component="unread"]` and renders into `[data-wg-unread-menu]`.
|
||||
|
||||
- [ ] **Step 1: Write the failing test** — append to `tests/global-topbar-contract.test.js`:
|
||||
|
||||
```js
|
||||
const unreadDrawer = read('templates/partials/header/unread-drawer.tpl');
|
||||
assertIncludes(
|
||||
topbar,
|
||||
'<!-- IMPORT partials/header/unread-drawer.tpl -->',
|
||||
'Topbar should mount the unread drawer before notifications'
|
||||
);
|
||||
assert(
|
||||
topbar.indexOf('partials/header/unread-drawer.tpl') < topbar.indexOf('partials/sidebar/notifications.tpl'),
|
||||
'Unread drawer should sit before the notifications item'
|
||||
);
|
||||
assertIncludes(
|
||||
unreadDrawer,
|
||||
'component="unread/count"',
|
||||
'Unread toggle should carry the live core count badge'
|
||||
);
|
||||
assertIncludes(
|
||||
unreadDrawer,
|
||||
'data-wg-unread-menu',
|
||||
'Unread dropdown menu should expose the JS mount hook'
|
||||
);
|
||||
assertMatches(
|
||||
topbar,
|
||||
/href="\{relative_path\}\/unread"[^>]*>[\s\S]*?component="unread\/count"/,
|
||||
'Mobile drawer actions should include an Unread link with count badge'
|
||||
);
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `node tests/global-topbar-contract.test.js`
|
||||
Expected: FAIL with `templates/partials/header/unread-drawer.tpl should exist`
|
||||
|
||||
- [ ] **Step 3: Create `templates/partials/header/unread-drawer.tpl`**
|
||||
|
||||
```html
|
||||
<a class="nav-link dropdown-toggle d-flex gap-2 align-items-center" href="#" role="button" data-bs-toggle="dropdown" aria-haspopup="true" aria-expanded="false" aria-label="[[unread:title]]">
|
||||
<i class="fa fa-fw fa-inbox" aria-hidden="true"></i>
|
||||
<span component="unread/count" class="badge rounded-1 bg-primary {{{ if !unreadCount.topic }}}hidden{{{ end }}}">{unreadCount.topic}</span>
|
||||
</a>
|
||||
<ul class="dropdown-menu wg-topbar__dropdown unread-dropdown p-1 shadow" role="menu" data-wg-unread-menu>
|
||||
<li class="dropdown-item disabled"><i class="fa fa-fw fa-spinner fa-spin" aria-hidden="true"></i> [[unread:title]]</li>
|
||||
</ul>
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Mount it in `topbar.tpl`** — insert before the notifications `<li>` (line 40):
|
||||
|
||||
```html
|
||||
<li component="unread" class="nav-item unread dropdown" title="[[unread:title]]">
|
||||
<!-- IMPORT partials/header/unread-drawer.tpl -->
|
||||
</li>
|
||||
|
||||
```
|
||||
|
||||
And in the drawer-actions block, insert before the notifications `<a>` (line 112):
|
||||
|
||||
```html
|
||||
<a href="{relative_path}/unread"><i class="fa fa-fw fa-inbox" aria-hidden="true"></i><span>[[unread:title]]</span><span component="unread/count" class="badge rounded-1 bg-primary {{{ if !unreadCount.topic }}}hidden{{{ end }}}">{unreadCount.topic}</span></a>
|
||||
```
|
||||
|
||||
- [ ] **Step 5: Run test to verify it passes**
|
||||
|
||||
Run: `node tests/global-topbar-contract.test.js`
|
||||
Expected: exits 0, no output
|
||||
|
||||
- [ ] **Step 6: Commit**
|
||||
|
||||
```bash
|
||||
git add templates/partials/header/unread-drawer.tpl templates/partials/header/topbar.tpl tests/global-topbar-contract.test.js
|
||||
git commit -m "feat: add unread drawer button to topbar"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 2: Client JS — fetch and render unread topics on open
|
||||
|
||||
**Files:**
|
||||
- Modify: `public/client.js` (inside `initWestgateTopbar()`, next to the existing `shown.bs.dropdown.westgateTopbar` handler)
|
||||
- Test: `tests/unread-drawer-client.test.js` (new)
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: `[component="unread"]` / `[data-wg-unread-menu]` markup from Task 1; NodeBB client `api.get('/unread', {}, cb)` whose payload has `topics: [{ title, slug, category: { name } }, ...]`.
|
||||
- Produces: `window.westgateTheme.renderUnreadMenu(menuEl, topics)` (exported for the test): clears `menuEl`, appends up to 10 `<li><a class="dropdown-item" href="<relative_path>/topic/<slug>">` items with title text and a category `<small>`, then a footer link to `/unread`. Empty list → single disabled item `[[unread:no-unread-topics]]`.
|
||||
|
||||
- [ ] **Step 1: Write the failing test** — create `tests/unread-drawer-client.test.js`:
|
||||
|
||||
```js
|
||||
'use strict';
|
||||
|
||||
const assert = require('assert');
|
||||
const fs = require('fs');
|
||||
const path = require('path');
|
||||
|
||||
const client = fs.readFileSync(path.join(__dirname, '..', 'public', 'client.js'), 'utf8');
|
||||
|
||||
assert(
|
||||
client.includes("'show.bs.dropdown.westgateUnread'"),
|
||||
'client.js should fetch unread topics when the unread dropdown opens'
|
||||
);
|
||||
assert(
|
||||
client.includes("api.get('/unread'"),
|
||||
'client.js should load the unread list from the /unread API'
|
||||
);
|
||||
assert(
|
||||
client.includes('renderUnreadMenu'),
|
||||
'client.js should expose the unread menu renderer'
|
||||
);
|
||||
assert(
|
||||
/textContent/.test(client) && !/innerHTML\s*=[^=]*title/.test(client),
|
||||
'Topic titles must be inserted via textContent, never innerHTML'
|
||||
);
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `node tests/unread-drawer-client.test.js`
|
||||
Expected: FAIL with "client.js should fetch unread topics when the unread dropdown opens"
|
||||
|
||||
- [ ] **Step 3: Implement.** In `public/client.js`, add above `initWestgateTopbar()`:
|
||||
|
||||
```js
|
||||
function renderUnreadMenu(menuEl, topics) {
|
||||
if (!menuEl) {
|
||||
return;
|
||||
}
|
||||
|
||||
menuEl.textContent = '';
|
||||
const relativePath = (window.config && window.config.relative_path) || '';
|
||||
|
||||
function addItem(node) {
|
||||
const li = document.createElement('li');
|
||||
li.appendChild(node);
|
||||
menuEl.appendChild(li);
|
||||
}
|
||||
|
||||
const list = (topics || []).slice(0, 10);
|
||||
if (!list.length) {
|
||||
const empty = document.createElement('span');
|
||||
empty.className = 'dropdown-item disabled';
|
||||
empty.textContent = '[[unread:no-unread-topics]]';
|
||||
addItem(empty);
|
||||
}
|
||||
|
||||
list.forEach((topic) => {
|
||||
const link = document.createElement('a');
|
||||
link.className = 'dropdown-item wg-unread-item text-truncate';
|
||||
link.href = `${relativePath}/topic/${topic.slug}`;
|
||||
link.textContent = topic.title;
|
||||
if (topic.category && topic.category.name) {
|
||||
const category = document.createElement('small');
|
||||
category.className = 'wg-unread-item__category';
|
||||
category.textContent = topic.category.name;
|
||||
link.appendChild(category);
|
||||
}
|
||||
addItem(link);
|
||||
});
|
||||
|
||||
const divider = document.createElement('hr');
|
||||
divider.className = 'dropdown-divider';
|
||||
addItem(divider);
|
||||
|
||||
const seeAll = document.createElement('a');
|
||||
seeAll.className = 'dropdown-item wg-unread-item--all';
|
||||
seeAll.href = `${relativePath}/unread`;
|
||||
seeAll.textContent = '[[unread:title]]';
|
||||
addItem(seeAll);
|
||||
|
||||
if (window.require) {
|
||||
window.require(['translator'], function (translator) {
|
||||
translator.translate(menuEl.innerHTML, (translated) => {
|
||||
menuEl.innerHTML = translated;
|
||||
});
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
And inside `initWestgateTopbar()`, next to the existing search-focus handler:
|
||||
|
||||
```js
|
||||
$(document)
|
||||
.off('show.bs.dropdown.westgateUnread')
|
||||
.on('show.bs.dropdown.westgateUnread', '.wg-topbar [component="unread"]', function () {
|
||||
const menuEl = this.querySelector('[data-wg-unread-menu]');
|
||||
require(['api'], function (api) {
|
||||
api.get('/unread', {}, function (err, data) {
|
||||
if (err) {
|
||||
renderUnreadMenu(menuEl, []);
|
||||
return;
|
||||
}
|
||||
renderUnreadMenu(menuEl, data && data.topics);
|
||||
});
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
And with the other exports near the bottom:
|
||||
|
||||
```js
|
||||
window.westgateTheme.renderUnreadMenu = renderUnreadMenu;
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Run tests to verify they pass**
|
||||
|
||||
Run: `node tests/unread-drawer-client.test.js && node tests/global-topbar-contract.test.js`
|
||||
Expected: exits 0, no output
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add public/client.js tests/unread-drawer-client.test.js
|
||||
git commit -m "feat: load unread topics into topbar drawer on open"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 3: SCSS for unread rows
|
||||
|
||||
**Files:**
|
||||
- Modify: `scss/westgate/_topbar.scss` (append after the `.notifications-dropdown` width block, ~line 177)
|
||||
- Test: `tests/global-topbar-contract.test.js` (append)
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: `.unread-dropdown`, `.wg-unread-item`, `.wg-unread-item__category` class names from Tasks 1–2.
|
||||
|
||||
- [ ] **Step 1: Write the failing test** — append to `tests/global-topbar-contract.test.js`:
|
||||
|
||||
```js
|
||||
assertIncludes(
|
||||
stylesheet,
|
||||
'.unread-dropdown',
|
||||
'Topbar styles should cover the unread dropdown'
|
||||
);
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `node tests/global-topbar-contract.test.js`
|
||||
Expected: FAIL with "Topbar styles should cover the unread dropdown"
|
||||
|
||||
- [ ] **Step 3: Implement** — in `scss/westgate/_topbar.scss`, extend the existing width rule so it reads:
|
||||
|
||||
```scss
|
||||
.wg-topbar .notifications-dropdown,
|
||||
.wg-topbar .chats-dropdown,
|
||||
.wg-topbar .drafts-dropdown,
|
||||
.wg-topbar .unread-dropdown {
|
||||
width: min(24rem, calc(100vw - 1.5rem));
|
||||
}
|
||||
```
|
||||
|
||||
and append:
|
||||
|
||||
```scss
|
||||
.wg-topbar .wg-unread-item {
|
||||
display: flex;
|
||||
align-items: baseline;
|
||||
gap: 0.5rem;
|
||||
}
|
||||
|
||||
.wg-topbar .wg-unread-item__category {
|
||||
margin-left: auto;
|
||||
flex-shrink: 0;
|
||||
opacity: 0.7;
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Run test to verify it passes**
|
||||
|
||||
Run: `node tests/global-topbar-contract.test.js`
|
||||
Expected: exits 0, no output
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add scss/westgate/_topbar.scss tests/global-topbar-contract.test.js
|
||||
git commit -m "feat: style topbar unread dropdown rows"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 4: Verify in the sow-nodebb dev container (Playwright)
|
||||
|
||||
**Files:** none (verification only)
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: the running dev forum at http://localhost:4567 (`../sow-nodebb`).
|
||||
|
||||
- [ ] **Step 1: Build and start the dev forum.** In `../sow-nodebb`: confirm `.env` has `PLUGIN_PATH=../sow-nodebb-theme`, `PLUGIN_ID=nodebb-theme-westgate`, `EXTRA_PLUGINS=nodebb-plugin-westgate-wiki`, then:
|
||||
|
||||
```bash
|
||||
make dev
|
||||
make dev-build
|
||||
```
|
||||
|
||||
Expected: NodeBB build succeeds; http://localhost:4567 responds.
|
||||
|
||||
- [ ] **Step 2: Playwright checks** (playwright-skill / MCP browser tools) against http://localhost:4567, logged in with the admin creds from `../sow-nodebb/.env`:
|
||||
- The topbar utility list shows the unread item (`li[component="unread"]`) immediately before the notifications item.
|
||||
- With unread topics present (create a topic from a second account or incognito post), the badge `[component="unread/count"]` is visible with a number.
|
||||
- Clicking the toggle opens the dropdown and lists unread topic links; clicking one lands on that topic.
|
||||
- The dropdown footer link lands on `/unread`.
|
||||
- At mobile width (~390px), the burger drawer shows the Unread row with badge.
|
||||
|
||||
Expected: all checks pass; screenshot the open dropdown for the PR.
|
||||
|
||||
- [ ] **Step 3: Run the full local test suite**
|
||||
|
||||
```bash
|
||||
for t in tests/*.test.js; do node "$t" || exit 1; done
|
||||
```
|
||||
|
||||
Expected: exits 0.
|
||||
|
||||
- [ ] **Step 4: Commit any fixes made during verification, then push and open the PR** on the existing `feat/topbar-unread-drawer` branch.
|
||||
Reference in New Issue
Block a user