tegwick 235355eb58 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>

2026-03-01 23:46:26 +01:00

3.2 KiB

Raw Blame History

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 — poll interval, offline recovery

How to use it

Hover over the element — the ? button fades in at the top-right corner.
Click ? — the reference page opens in a modal overlay.
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:

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

On a page h1:

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

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:

observablehq.config.js — add to the Reference pages array (alphabetical)
src/reference.md — add a row to the dashboard-pages table

3.2 KiB Raw Blame History