feat(dashboard): nav restructure, full context-help coverage, 11 new ref docs

Navigation:
- New order: Overview · Todo · Domains · Repos · Workstreams (collapsible,
  open:false, with atomic sub-entries: Decisions, Tasks, Debt, Extends,
  Dependencies) · Contributions · SBOM · Progress · Reference (collapsible)
- Reference section gains path:/reference landing page; all 18 doc pages
  listed in nav (alphabetical) and in reference.md table

New pages:
- todo.md — Internal / Ecosystem / Third-party todo classification
- dependencies.md — dependency edge table derived from state/summary
- reference.md — Reference landing page with full doc index

New reference doc pages (11):
  contributions, debt, dependencies, domains, extensions, overview,
  repos, tasks, todo + reference (meta) already added previously

doc-overlay.js — lazy bubblehelp tooltip:
- _titleCache Map + _fetchDocTitle(docPath): on first hover of any ?
  button, fetches the target doc page, parses <h1>, sets btn.title
- Native browser tooltip appears exactly on the ? circle on subsequent hover

Context-help wired on all 14 dashboard pages:
- h1 withDocHelp added to: index, todo, domains, repos, tasks, techdept,
  extensions, dependencies (contributions/workstreams/decisions/sbom/
  progress/reference were already wired)
- domains.md + repos.md: added missing withDocHelp import and live-data link
- tasks/techdept/extensions: removed duplicate _h1 const that caused
  SyntaxError: Identifier '_h1' has already been declared

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-03-01 23:46:26 +01:00
parent 894c8b3934
commit 235355eb58
22 changed files with 1468 additions and 25 deletions

View File

@@ -0,0 +1,119 @@
---
title: Reference & Context Help — Reference
---
# Reference & Context Help
The **Reference** section is a collection of in-depth documentation pages
explaining the data model, design conventions, and mechanics of each dashboard
view. Reference pages are readable as standalone articles and also surfaced
inline via the **? context-help button** on dashboard pages.
---
## The ? context-help button
Every dashboard page exposes one or more **?** buttons — small circular
controls that open the relevant reference page in an overlay without leaving
the current view.
### Where ? buttons appear
| Location | Opens |
|----------|-------|
| Page **h1** heading | Reference page for that dashboard view |
| **KPI sidebar cards** | Reference page for the specific metric shown |
| **Live indicator** | [Live Data](/docs/live-data) — poll interval, offline recovery |
### How to use it
1. Hover over the element — the **?** button fades in at the top-right corner.
2. Click **?** — the reference page opens in a modal overlay.
3. Read the docs, then dismiss with **✕ close**, **Esc**, or by clicking the
backdrop.
The overlay does not interrupt the live data polling loop — the dashboard
continues refreshing in the background while the overlay is open.
---
## Overlay behaviour
| Detail | Value |
|--------|-------|
| Size | `min(780px, 92vw)` wide · `82vh` tall |
| Content | Observable Framework page rendered in an `<iframe>` |
| Dismiss | ✕ button · Esc key · click outside the box |
| Animation | Fade-in backdrop + slide-up box (150 ms) |
| Stacking | `z-index: 9000` — always above dashboard content |
Only one overlay can be open at a time. Opening a second **?** replaces the
first automatically.
---
## Adding ? help to a new page
The helper is exported from `src/components/doc-overlay.js`:
```js
import {withDocHelp} from "./components/doc-overlay.js";
```
**On a page h1:**
```js
const _h1 = document.querySelector("#observablehq-main h1");
if (_h1) { _h1.style.position = "relative"; withDocHelp(_h1, "/docs/my-page"); }
```
**On a sidebar card or other element** (must have `position: relative`):
```js
const _card = html`<div class="kpi-infobox" style="position:relative">…</div>`;
withDocHelp(_card, "/docs/my-page");
```
`withDocHelp(element, docPath)` mutates the element in place and returns it,
so it can be chained directly before `display()` or `injectTocTop()`.
---
## Writing a reference page
Reference pages live in `state-hub/dashboard/src/docs/` and follow a consistent
structure:
```
---
title: Topic — Reference
---
# Topic — Reference
One-sentence purpose statement.
---
## Section 1
## Section 2
---
*Footer note (optional — e.g. governance constraint, append-only policy).*
```
**Conventions:**
- Title frontmatter: `"Topic — Reference"` (em dash, not hyphen)
- Sections separated by `---` horizontal rules
- Tables preferred over prose lists for structured data
- Code blocks for MCP tool calls and REST examples
- No live data fetching — reference pages are static
After writing the page, register it in two places:
1. **`observablehq.config.js`** — add to the Reference `pages` array (alphabetical)
2. **`src/reference.md`** — add a row to the dashboard-pages table