fix(docs): fix timeseries page TOC and loading state hydration by mattrothenberg · Pull Request #549 · cloudflare/kumo

mattrothenberg · 2026-05-28T14:39:05Z

Fixes two issues on the timeseries chart docs page:

Empty Table of Contents
All section headings were ### (h3) with no ## (h2) parents. The TableOfContents component groups h3s under h2s and silently drops orphaned h3s, so the TOC rendered empty. Promoted all headings to h2.

Broken loading state demo
The LoadingChartDemo uses useIsDarkMode() which reads from the DOM. During SSR, it defaults to light mode and renders the wave SVG with a dark stroke color. On client hydration in dark mode, React detects the attribute mismatch and refuses to patch it — resulting in an invisible wave (black stroke on dark background). Switched to client:only="react" to skip SSR entirely.

Reviews
bonk has reviewed the change
automated review not possible because: docs-only change with no component logic
Tests
Additional testing not necessary because: docs-only MDX heading level and hydration directive change, verified locally

- Promote headings from h3 to h2 so the TableOfContents component picks them up (it groups h3s under h2s and drops orphaned h3s) - Use client:only="react" for LoadingChartDemo to avoid hydration mismatch caused by useIsDarkMode returning different values on server vs client

mattrothenberg · 2026-05-28T14:39:31Z

-<p>
-  Use the <code>tooltipBoundary</code> prop to constrain the tooltip to a
-  specific container element. By default the tooltip avoids overflowing any
-  clipping ancestor (scroll containers, viewports). Pass a DOM element to


This example wasn't rendering at all

pkg-pr-new · 2026-05-28T14:43:17Z

npm i https://pkg.pr.new/@cloudflare/kumo@549

commit: f9c8983

github-actions · 2026-05-28T14:44:21Z

Docs Preview

View docs preview

Commit: a04c11b

github-actions · 2026-05-28T14:47:21Z

Visual Regression Report — 25 changed, 14 unchanged

25 screenshot(s) with visual changes:

Button / Variant: Primary

370 px (0.36%) changed

Before	After	Diff

Button / Variant: Secondary

261 px (0.26%) changed

Before	After	Diff

Button / Variant: Outline

155 px (0.15%) changed

Before	After	Diff

Button / Variant: Secondary Destructive

383 px (0.38%) changed

Before	After	Diff

Button / With Icon

272 px (0.27%) changed

Before	After	Diff

Button / Icon Only

76 px (0.07%) changed

Before	After	Diff

Button / Loading State

857 px (0.84%) changed

Before	After	Diff

Button / Disabled State

117 px (0.12%) changed

Before	After	Diff

Button / Link as Button

483 px (0.48%) changed

Before	After	Diff

Dialog / Dialog With Actions

200 px (0.2%) changed

Before	After	Diff

Dialog / Dialog Alert

744 px (0.73%) changed

Before	After	Diff

Dialog / Dialog Confirmation

352 px (0.35%) changed

Before	After	Diff

Dialog / Dialog With Combobox

130 px (0.13%) changed

Before	After	Diff

Dialog / Dialog With Dropdown

236 px (0.23%) changed

Before	After	Diff

Select / Select Basic

486 px (0.48%) changed

Before	After	Diff

Select / Select Sizes

429 px (0.23%) changed

Before	After	Diff

Select / Select Without Label

105 px (0.1%) changed

Before	After	Diff

Select / Select With Description

889 px (0.75%) changed

Before	After	Diff

Select / Select Placeholder

595 px (0.59%) changed

Before	After	Diff

Select / Select Custom Rendering

414 px (0.41%) changed

Before	After	Diff

Select / Select Loading

0 px (0%) changed

Before	After	Diff

Select / Select Multiple

556 px (0.55%) changed

Before	After	Diff

Select / Select Disabled Items

176 px (0.17%) changed

Before	After	Diff

Select / Select Grouped

318 px (0.31%) changed

Before	After	Diff

Select (Open)

3,038 px (0.01%) changed

Before	After	Diff

14 screenshot(s) unchanged

Button / Basic
Button / Variant: Ghost
Button / Variant: Destructive
Button / Sizes
Button / Title
Dialog / Dialog Basic
Dialog / Dialog With Select
Dialog (Open)
Select / Select With Error
Select / Select With Tooltip
Select / Select Complex
Select / Select Disabled Options
Select / Select Grouped With Disabled
Select / Select Long List

Generated by Kumo Visual Regression

mattrothenberg · 2026-05-28T15:00:11Z

/bonk review please

ask-bonk · 2026-05-28T15:01:11Z

Two small fixes, both correctly identified and cleanly applied:

TOC fix: Promoting all section headings from ### → ## makes sense. The docs site's TableOfContents component expects h2 parents to group h3s, so orphaned h3s were being dropped. Now every section will appear in the TOC.
Hydration fix: LoadingChartDemo reads the DOM for dark mode via useIsDarkMode(), which causes a mismatch when SSR defaults to light mode and the client hydrates in dark mode. Switching from client:visible to client:only="react" skips SSR entirely for this demo, eliminating the mismatch. This is the right trade-off for an interactive demo that depends on runtime DOM state.

No issues found. Approved.

github run

mattrothenberg · 2026-05-28T15:08:04Z

/bonk also approve the PR

ask-bonk

Two clean fixes, both correctly diagnosed:

TOC fix: Promoting headings from ### → ## resolves the empty TOC. The docs site's TableOfContents component groups h3s under h2 parents and silently drops orphaned h3s, so every section now appears in the TOC.
Hydration fix: LoadingChartDemo uses useIsDarkMode() which reads DOM state. During SSR it defaults to light mode, causing a mismatch when the client hydrates in dark mode. Switching from client:visible to client:only="react" skips SSR for this demo, eliminating the mismatch. This is the right trade-off for a demo that depends on runtime DOM state.

No issues found.

ask-bonk · 2026-05-28T15:09:47Z

/bonk review posted and approved PR #549.

Review summary:

TOC fix: Promoting headings from ### → ## resolves the empty TOC. The docs site's TableOfContents groups h3s under h2 parents and drops orphaned h3s, so every section now appears correctly.
Hydration fix: LoadingChartDemo uses useIsDarkMode() which reads DOM state. SSR defaults to light mode, causing a hydration mismatch in dark mode. Switching from client:visible to client:only="react" skips SSR for this demo, eliminating the mismatch. Good trade-off for a DOM-dependent demo.

No issues found — approved.

github run

mattrothenberg commented May 28, 2026

View reviewed changes

merge: resolve conflict with main, promote new tooltip sections to h2

f9c8983

mattrothenberg added the no-changeset-required label May 28, 2026

ask-bonk Bot approved these changes May 28, 2026

View reviewed changes

mattrothenberg merged commit 1eac3aa into main May 28, 2026
16 of 17 checks passed

mattrothenberg deleted the fix/timeseries-docs branch May 28, 2026 15:10

Conversation

mattrothenberg commented May 28, 2026

Uh oh!

mattrothenberg May 28, 2026

Choose a reason for hiding this comment

Uh oh!

pkg-pr-new Bot commented May 28, 2026

Uh oh!

github-actions Bot commented May 28, 2026

Docs Preview

Uh oh!

github-actions Bot commented May 28, 2026

Button / Variant: Primary

Button / Variant: Secondary

Button / Variant: Outline

Button / Variant: Secondary Destructive

Button / With Icon

Button / Icon Only

Button / Loading State

Button / Disabled State

Button / Link as Button

Dialog / Dialog With Actions

Dialog / Dialog Alert

Dialog / Dialog Confirmation

Dialog / Dialog With Combobox

Dialog / Dialog With Dropdown

Select / Select Basic

Select / Select Sizes

Select / Select Without Label

Select / Select With Description

Select / Select Placeholder

Select / Select Custom Rendering

Select / Select Loading

Select / Select Multiple

Select / Select Disabled Items

Select / Select Grouped

Select (Open)

Uh oh!

mattrothenberg commented May 28, 2026

Uh oh!

ask-bonk Bot commented May 28, 2026

Uh oh!

mattrothenberg commented May 28, 2026

Uh oh!

ask-bonk Bot left a comment

Choose a reason for hiding this comment

Uh oh!

ask-bonk Bot commented May 28, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant