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:
119
state-hub/dashboard/src/docs/reference.md
Normal file
119
state-hub/dashboard/src/docs/reference.md
Normal 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
|
||||
Reference in New Issue
Block a user