the-custodian/contrib/upstream-prs/2026-02-26--observablehq--framework--toc-sidebar-inject.md

id, type, target_org, target_repo, title, status, domain, related_workstream, state_hub_contribution_id, created, updated, local_component_path, target_upstream_file, upstream_pr_url

id	type	target_org	target_repo	title	status	domain	related_workstream	state_hub_contribution_id	created	updated	local_component_path	target_upstream_file	upstream_pr_url
upr-2026-02-26--observablehq--framework--toc-sidebar-inject	upr	observablehq	framework	Add injectTocTop() utility for injecting elements into the TOC sidebar	draft	custodian	contribution-tracking-sbom	null	2026-02-26	2026-02-28	state-hub/dashboard/src/components/toc-sidebar.js	src/client/toc.ts	null

Upstream PR: Add injectTocTop() utility for injecting elements into the TOC sidebar

Summary

Propose adding an injectTocTop(id, element) utility to Observable Framework that allows dashboard pages to prepend arbitrary HTML elements at the top of the automatically-generated table-of-contents sidebar. This enables KPI cards, live status indicators, and other contextual widgets to live alongside the page's section links.

Motivation

Observable Framework generates a TOC sidebar from headings automatically, but provides no standard way to inject content into it from page JavaScript. As a result, every project that wants sidebar widgets must implement its own DOM manipulation workaround.

By upstreaming a small, focused utility, the community gets a stable API for sidebar injection that doesn't depend on Observable Framework's internal DOM structure.

Local Component

Path in this repo: state-hub/dashboard/src/components/toc-sidebar.js Origin story: Created 2026-02-26 during implementation of the Decisions KPI dashboard (State Hub v0.2). The component provides two utilities:

• injectTocTop(id, element): remove-then-prepend to the TOC aside element
• withDocHelp(element, docPath): attaches a ? button that opens a doc page as an iframe overlay

Target Upstream Location

Repo: observablehq/framework File: src/client/toc.ts (or a new src/client/toc-inject.ts)

Draft PR Body

## Summary

Add `injectTocTop(id, element)` — a small utility for injecting custom elements
at the top of the Observable Framework table-of-contents sidebar.

## Motivation

Dashboard pages frequently need contextual widgets (KPI boxes, live status
indicators, navigation aids) that belong alongside the TOC, not in the page
content flow. Currently this requires each project to directly manipulate the
`#observablehq-toc` DOM element, coupling page code to an internal DOM detail.

`injectTocTop` provides a stable API for this pattern:

```js
import {injectTocTop} from "observablehq:toc";

const myWidget = html`<div class="kpi-box">...</div>`;
injectTocTop("my-kpi-box", myWidget);

Changes

• Add injectTocTop(id: string, element: HTMLElement): void to Framework's client runtime
• Export from the observablehq:toc module (or equivalent public API)
• Add documentation page: "Customising the sidebar"

Testing

• Unit test: injectTocTop prepends element to #observablehq-toc aside
• Unit test: calling again with same id removes old element before inserting new one (idempotent)
• Integration test: injected element appears above TOC links in rendered page

## Notes

- The local implementation (`toc-sidebar.js`) uses `querySelector('#observablehq-toc aside')`
  — this should be replaced with a stable API reference once upstreamed.
- The `withDocHelp` utility in the same file is a separate feature; this PR
  focuses solely on `injectTocTop`.
- Observable Framework issue tracker should be checked for any existing
  discussion of sidebar customisation before opening a new issue.