state-hub/dashboard/src/docs/reference.md

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

```javascript
import {withDocHelp} from "./components/doc-overlay.js";
```

**On a page h1:**

```javascript
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`):

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