feat: sticky table of contents with scrollspy for canvas dashboards by rohithreddykota · Pull Request #9693 · rilldata/rill

rohithreddykota · 2026-07-16T16:25:03Z

Adds a persistent, minimap-style table of contents to canvas dashboards (view surfaces only; not the iframe embed).

Derives entries from the headings (h1–h3) rendered inside markdown components of the active tab — no new section primitive; stays in sync as content/tabs change via a debounced MutationObserver.
Scrollspy via a single IntersectionObserver (no scroll-event math); exactly one active section, with the highlight pinned during click-to-scroll so it doesn't flicker through intermediate sections.
Collapsed rail of tick bars by default (dots on narrow viewports so they don't overlap content); hover/focus reveals the full list as an overlay flyout that never reflows the dashboard.
Click smooth-scrolls (respecting prefers-reduced-motion) and updates the URL hash; deep-linking on mount is supported. Accessible: <nav aria-label>, real links, aria-current="location", focus rings, full heading as the accessible name.

Checklist:

Covered by tests
Ran it and it works as intended
Reviewed the diff before requesting a review
Checked for unhandled edge cases
Linked the issues it closes
Checked if the docs need to be updated. If so, create a separate Linear DOCS issue
Intend to cherry-pick into the release branch
I'm proud of this work!

Developed in collaboration with Claude Code

AdityaHegde · 2026-07-17T06:45:49Z

A couple of UXQA items,

When there are 2 markdown components side-by-side,
1. Clicking on the right one in sidebar will not highlight it, only the left one gets highlighted.
2. Scrolling just down will quickly highlight the right one.
  Not sure if there is a legitimate use case for this, so perhaps we can keep the existing behaviour.
When the last markdown component is towards the bottom it never gets highlighted. But clicking it does take the user to the bottom so probably not a bad experience?

What do you think @nishantmonu51 ?

AdityaHegde · 2026-07-20T03:47:31Z

+  /* The rail itself: vertically centered, expanding to the full flyout on hover/focus (which
+     overlays the content to its right rather than reflowing it). `p-2` keeps the first and last bars
+     clear of the rounded corners so they aren't clipped. */
+  .toc__panel {


Lets use toc-panel. The naming convention of double underscore is not standard for css. Same applies to double dash classes like toc__item--active.

Done - renamed all classes to kebab-case (toc-panel, toc-item, toc-item-active, toc-bar, toc-text, toc-list, toc-compact) and updated every selector.

AdityaHegde · 2026-07-20T03:59:58Z

+      : "smooth";
+  }
+
+  function jumpTo(event: MouseEvent, entry: TocEntry) {


We can move this and watchScrollEnd to a separate class that has logic from loc and scrollspy. Also we should move to svelte5 way for using cross file state. Check web-common/src/lib/store-utils/types.svelte.ts for reference.

Extracted everything into toc-controller.svelte.ts - a CanvasTocController class following the types.svelte.ts convention, with $state entries/activeId as the cross-file state. It absorbs the former scrollspy.ts (IntersectionObserver tracking + lock/unlock) along with refresh, the MutationObserver, jumpTo, and watchScrollEnd; slugify/deriveTocEntries stay as pure helpers in toc.ts. The component is now thin and runes-based, with an $effect owning the controller's lifecycle.

AdityaHegde · 2026-07-21T04:15:40Z

+      behavior: this.scrollBehavior(),
+      block: "start",
+    });
+    history.replaceState(history.state, "", `#${entry.id}`);


Do we need replace state here? Using goto will instead add support for back and forward navigation buttons. More of a product question @nishantmonu51

AdityaHegde · 2026-07-21T04:31:06Z

+    // Re-derive on any content change: tab switch, async markdown resolution, edits, filters, or the
+    // `.row-container` appearing (e.g. after required filters are satisfied). Observing the scroll
+    // container rather than `.row-container` keeps this resilient to remounts.
+    this.mutationObserver = new MutationObserver(() => this.scheduleRefresh());


This is a bit too aggressive. Lets fire events from web-common/src/features/canvas/components/markdown/Markdown.svelte on mount and destroy?

Done — replaced the subtree MutationObserver with a CANVAS_TOC_REFRESH_EVENT that Markdown.svelte dispatches on mount, content change, and unmount via a Svelte action; the controller just listens for it, so the TOC no longer re-derives on unrelated chart/table/tooltip updates.

AdityaHegde · 2026-07-21T04:34:04Z

+  return headings.map(({ el, text, level }) => {
+    let id = el.id || slugify(text);
+    // Dedupe collisions with a numeric suffix, e.g. "overview", "overview-2".
+    if (usedIds.has(id)) {


Lets use getName from web-common/src/features/entity-management/name-utils.ts . While it is not 1-1 it will suffice to give us a number appended id.

Done — now using getName from name-utils.ts for the dedup; duplicate anchor ids become overview_1, overview_2, etc.

AdityaHegde · 2026-07-21T04:36:15Z

+};
+
+/** Turn arbitrary heading text into a URL-hash-safe slug. */
+export function slugify(text: string): string {


Lets merge this with web-common/src/lib/string-utils.ts::sanitizeSlug

Done — slugify now builds on sanitizeSlug for the character replacement, keeping the TOC-specific lowercasing, hyphen-collapsing, and "section" fallback.

…ug/name utils

AdityaHegde

Approving from code side. @nishantmonu51 please do a UXQA once

nishantmonu51

The branch no longer merges: main rewrote CanvasDashboardWrapper.svelte to Svelte 5 runes in #9746, and git merge-tree reports a content conflict in that file, so export let showTableOfContents and the bandWidth/scrollContainer bindings will need porting to the runes form on rebase.

Two smaller points:

deepLinked latches on the first derive that yields any entries, but templated markdown initially renders its raw content — resolvedContent falls back to content before the resolve query returns. A heading like ## Revenue {{ ... }} therefore produces id revenue-... on the first pass and its resolved id only later, so a deep link to the resolved id is never honored because the latch has already flipped (toc-controller.svelte.ts:100, components/markdown/Markdown.svelte:82).

web-admin/src/features/scheduled-reports/export/CanvasPdfReportExport.svelte:170 mounts CanvasDashboardEmbed with the default tableOfContents = true, so the TOC controller and its IntersectionObserver run inside the off-screen capture host for no benefit. Pass tableOfContents={false} as the embed route does.

nishantmonu51 · 2026-09-21T08:03:47Z

+    // existing `tabs` URL param). Use an instant jump so the page doesn't animate on load.
+    if (!this.deepLinked && this.entries.length > 0) {
+      this.deepLinked = true;
+      const hash = decodeURIComponent(window.location.hash.slice(1));


The hash read here is usually gone by the time refresh runs. CanvasInitialization.svelte:122 calls canvasEntity.onUrlChange as soon as the store resolves, and for a non-isolated canvas handleCanvasRedirect does goto(`?${snapshotSearchParams}`, { replaceState: true }) (and the equivalent for a home bookmark or for default params) whenever searchParams.size === 0 — see stores/canvas-entity.ts, handleCanvasRedirect. Resolving a relative ?... URL against the current location discards the fragment, so /canvas/foo#overview becomes /canvas/foo?tr=... before, or racing with, the first refresh. Any canvas with a last-visited snapshot, a home bookmark, or default params therefore never honors the deep link, and even when the scroll wins the race the hash is stripped from the URL. Either carry the hash through the redirect or capture it once before onUrlChange runs.

nishantmonu51 · 2026-09-21T08:03:47Z

+
+  return headings.map(({ el, text, level }) => {
+    // Dedupe collisions with a numeric suffix, e.g. "overview", "overview_1".
+    const id = getName(el.id || slugify(text), usedIds);


getName increments a trailing number (INCREMENT = /(\d+)$/, applied as result.replace(INCREMENT, (m) => (+m + 1).toString())) rather than appending a suffix, so headings 2024, 2024, 2025 are assigned ids 2024, 2025, 2026 — #2025 then scrolls to the second 2024 heading instead of the 2025 one, and a duplicate q1-2025 is likewise renamed to q1-2026. toc.spec.ts only covers the alphabetic case (overview_1), which is why this passes. A local -1/-2 suffix loop avoids borrowing the resource-name helper's semantics.

feat: add table of contents with scrollspy to canvas dashboards

8849f4f

rohithreddykota requested review from AdityaHegde and nishantmonu51 July 16, 2026 16:26

Hide canvas table of contents when it has only one section

52255cd

rohithreddykota force-pushed the rohithreddykota/canvas-toc-scrollspy branch from 0ac3794 to 52255cd Compare July 17, 2026 18:41

AdityaHegde requested changes Jul 20, 2026

View reviewed changes

Extract canvas TOC logic into a controller class and use kebab-case CSS

d7bae17

rohithreddykota requested a review from AdityaHegde July 20, 2026 15:33

AdityaHegde requested changes Jul 21, 2026

View reviewed changes

nishantmonu51 added Type:Feature New feature request Area:Dashboard claude-code-assisted Size:L Large change: 500-1,999 lines labels Jul 23, 2026

refactor: derive canvas TOC from markdown refresh events and reuse sl…

30c08db

…ug/name utils

rohithreddykota requested a review from AdityaHegde July 28, 2026 02:58

AdityaHegde approved these changes Jul 28, 2026

View reviewed changes

nishantmonu51 reviewed Sep 21, 2026

View reviewed changes

Conversation

rohithreddykota commented Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AdityaHegde commented Jul 17, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AdityaHegde left a comment

Choose a reason for hiding this comment

Uh oh!

nishantmonu51 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

rohithreddykota commented Jul 16, 2026 •

edited

Loading