Update TableOfContents hover states, semantic HTML, and Group API

[pedromenezes1]

Updates the TableOfContents component to drop the background hover tint and border radius, use semantic HTML, and expand the Group API.

Component changes

• Left-border indicator: Replaced pill/background-tint hover with border-l pattern — items have a transparent left border that becomes visible on hover (subtle) and active (brand blue)
• Semantic HTML: TableOfContentsList renders <ul>, items wrap in <li>, groups render as <li> with nested <ul>
• Group API expansion: TableOfContents.Group now accepts href and active props. Pass href to make the group label a clickable link, or omit for a plain title
• Spacing: Switched to flex flex-col gap-2 (8px)

Docs site changes

• h3 support in TOC sidebar: h3 headings now appear as nested items under their parent h2 using TOC.Group
• Expanded API Reference: All sub-components (Title, List, Item, Group) documented with props tables
• Updated Group demo: Shows both clickable group labels (with href) and plain title labels

Registry codegen fix

• Fixed systemic bug where forwardRef-based sub-components had their props invisible to the registry. Affects all compound components (TableOfContents, Table, Dialog, Popover, etc.)

Screenshots

The table of contents sidebar now captures h3 headings and nests them under their parent h2, giving a more complete overview of the page structure.

Before	After

The API Reference section now documents all sub-components (Title, List, Item, Group) with their props, where previously only the root component was shown.

Before	After

Groups now support an optional href prop, making the group label a clickable navigation link instead of just a plain title.

Before	After

---

• Reviews
• bonk has reviewed the change
• automated review not possible because: visual design change requiring human review
• Tests
• Tests included/updated

[pkg-pr-new]

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

commit: f47aecf

[github-actions]

Docs Preview

View docs preview

Commit: c5ef4cb

[github-actions]

Visual Regression Report — 14 changed, 23 unchanged

14 screenshot(s) with visual changes:

Button / Loading State

2 px (0%) changed

Before	After	Diff

Button / Title

272 px (0.27%) changed

Before	After	Diff

Dialog / Dialog Basic

114 px (0.11%) changed

Before	After	Diff

Dialog / Dialog With Select

130 px (0.13%) changed

Before	After	Diff

Dialog / Dialog With Dropdown

244 px (0.24%) changed

Before	After	Diff

Dialog (Open)

1,534 px (0.01%) 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 Placeholder

418 px (0.41%) 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 Grouped

194 px (0.19%) changed

Before	After	Diff

Select / Select Grouped With Disabled

736 px (0.72%) changed

Before	After	Diff

Select (Open)

5,146 px (0.02%) changed

Before	After	Diff

23 screenshot(s) unchanged

• Button / Basic
• Button / Variant: Primary
• Button / Variant: Secondary
• Button / Variant: Ghost
• Button / Variant: Destructive
• Button / Variant: Outline
• Button / Variant: Secondary Destructive
• Button / Sizes
• Button / With Icon
• Button / Icon Only
• Button / Disabled State
• Dialog / Dialog With Actions
• Dialog / Dialog Alert
• Dialog / Dialog Confirmation
• Dialog / Dialog With Combobox
• Select / Select Basic
• Select / Select With Field
• Select / Select With Tooltip
• Select / Select Multiple
• Select / Select Complex
• Select / Select Disabled Options
• Select / Select Disabled Items
• Select / Select Long List

---

Generated by Kumo Visual Regression

[pedromenezes1]

/bonk

[ask-bonk]

PR Review: TableOfContents Redesign (#424)

After reviewing the changes, I can confirm this is a well-structured PR with focused improvements to the TableOfContents component. Here's my analysis:

✅ Component Changes - TableOfContents

Visual Design Improvements:

• Clean left-border indicator pattern replaces the previous pill/background-tint hover
• Subtle hover state (border-kumo-line) and active state (border-kumo-brand)
• Consistent flex flex-col gap-2 spacing throughout
• Uses semantic tokens correctly (text-kumo-subtle, text-kumo-default, border-kumo-hairline)

Semantic HTML:

• TableOfContentsList → <ul>
• TableOfContentsItem → wrapped in <li>
• TableOfContentsGroup → <li> with nested <ul> for children
• Proper accessibility with aria-current on active items

Group API Expansion:

• New href prop makes group label clickable
• New active prop for active state styling when href is provided
• Backward compatible: omit href for plain title labels

✅ Critical Fix: Registry Codegen

The fix in sub-components.ts addresses a systemic bug where forwardRef-based sub-components had invisible props to the registry:

// Now handles multi-line forwardRef generics correctly
const forwardRefPattern = new RegExp(
  `const\\s+${value}\\s*=\\s*forwardRef<[\\s\\S]*?,\\s*(\\w+)\\s*>\\s*\\(`
);

This affects all compound components (TableOfContents, Table, Dialog, Popover, etc.) - a significant improvement to the component registry accuracy.

✅ Documentation Site

• h3 headings now appear nested under parent h2 using TOC.Group
• All sub-components documented with props tables
• Updated Group demo showing both clickable and plain title modes

✅ Tests

All 20 TableOfContents tests pass:

• Semantic HTML structure (ul/li elements)
• Group with/without href rendering
• Active states with aria-current
• Custom render prop
• Display names

The registry utility tests (66 tests) also pass, validating the forwardRef props extraction fix.

Changeset

Appropriate minor version bump with clear description of changes.

---

Overall Assessment: This PR is well-crafted, focused, and improves both the visual design and technical implementation. The registry codegen fix is particularly valuable as it benefits all compound components in the library.

github run

[jcworth]

LGTM! nice improvements