Fix typedoc signature heading levels: uniform sibling sections for signature parts

[NullVoxPopuli-ai-agent]

Problem

The Element / Arguments / Blocks / Return headings in rendered signatures could violate axe's heading-order audit ("Heading levels should only increase by one") on consuming docs pages — concretely, nvp.ui's /Docs/3-components/theme-toggle fails with axe-core >= 4.12 (pulled in by no-lockfile CI installs): its signature has only an Element, whose heading rendered as an <h1> mid-page, so the markdown's ### State Attributes that follows was a 2-level jump. See NullVoxPopuli/nvp.ui#99 and its review discussion.

Root cause (two layers)

1. Detection (fixed upstream, pulled in here): which-heading-do-i-need treated a nested heading-less <section> as a dead-end boundary and pinned any heading inside it to <h1>, and its fallback traversal leaked headings out of nested sectioning content. Both fixed in which-heading-do-i-need: nested sections are not heading context; heading-less boundaries are transparent ember-primitives#776, released as ember-primitives 0.60.1 (which-heading-do-i-need 0.4.1) — this PR bumps to ^0.60.1.
2. Markup (fixed here): the signature parts were structured inconsistently — Element, Blocks, and Return each wrapped in a <section>, but Arguments was not. A heading placed directly in <Load>'s section is level-context for the sibling <section>s after it: per the sectioning rules, a <section> following a sibling <h3> is a subsection of it, so even with fixed detection the parts render Element h3 / Arguments h3 / Blocks h4.

Fix

No level numbers; sectioning rules only. Every signature part (Element, Arguments, Blocks, Return) is now a uniform sibling <section> containing its heading and its content. Sibling sections resolve to equal levels — one below whatever heading precedes the api-docs block:

## API Reference        <- authored in markdown
  Element               <- h3
  Arguments             <- h3
  Blocks                <- h3
### State Attributes    <- authored in markdown

Because each part's content lives inside its section, headings authored in a declaration's markdown comments stay contained instead of becoming level-context for the parts that follow (Element's comment moved inside its section for that reason).

Verification

• rendering test: an <h2> before a ComponentSignature yields three h3.typedoc__headings (Element, Arguments, Blocks) and no h1/h2/h4
• rendering test: a signature whose Element/Blocks comments contain markdown headings (#### …) renders them contained in their sections — the three signature headings stay h3, and no h5 appears (no drift)
• full kolay suite green: pnpm turbo test:browser (6/6 tasks, docs-app 30 pass / 5 skip / 0 fail), pnpm turbo test:node (75/75), pnpm lint (17/17 tasks: js, types, hbs, prettier, publint)
• end-to-end against nvp.ui with floating deps (axe-core 4.12.1): packed this branch, overrode kolay there, restored its original ### State Attributes markdown — full suite 83/83 (previously failing heading-order on theme-toggle)

🤖 Generated with Claude Code

[bolt-new-by-stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[vercel]

Someone is attempting to deploy a commit to the universal-ember Team on Vercel.

A member of the Team first needs to authorize it.

[NullVoxPopuli]

Don't use hard-coded level numbers. Use the sectioning rules alone, and the automatic heading will be figured out.

[NullVoxPopuli-ai-agent]

Done in 3bf9acb — all level numbers (HeadingScope / SectionHeading / @level threading, and the ember-element-helper dep) are gone. The actual bug was markup: Element / Blocks / Return each nested their <Heading> inside an inner heading-less <section> within <Load>'s section, and a nested empty section is its own boundary — detection finds nothing between the two boundaries and pins the heading to <h1>. Removing the inner wrappers (Return keeps its styling hook as a div.typedoc__helper__return) lets the sectioning rules resolve everything: ## API Reference → h3 Element on nvp.ui's theme-toggle page, with its ### State Attributes markdown unchanged. Net diff is two removed <section>s and one <section> → <div>.

One observation from verifying, for your radar rather than this PR: through non-boundary wrapper layers (like the repl demo divs), the detection's fallback subtree traversal resolves subsequent sibling headings one level below the first (timeline renders h3 Timeline → h4 Element, h5 Arguments, h5 Blocks), because the fallback recurses into boundary children that the previous-sibling scan deliberately skips (findHeadingIn's for (const child of node.children) doesn't check BOUNDARY_ELEMENTS, while the docstring says the search should stop at other boundary elements). Every step still increases by at most one, so heading-order passes everywhere — but if which-heading-do-i-need's fallback skipped boundary children like the sibling scan does, siblings would come out at equal levels.

Verification: kolay suite green (browser 29/29 incl. a new regression test — <h2> before a signature yields three h3.typedoc__headings and no h1 — plus node 75/75, lint); nvp.ui floating-deps repro (axe-core 4.12.1, original h3 markdown) 83/83, with theme-toggle and timeline hierarchies checked in-browser for zero >1 increases.

[NullVoxPopuli]

that sounds like a bug, rather than something to avoid

[NullVoxPopuli-ai-agent]

Agreed — fixed at the source: universal-ember/ember-primitives#776. Two bugs in getSectionHeadingLevel, both contradicting its own docstring ("stopping if we encounter other boundary elements"):

1. findHeadingIn's fallback child-traversal recursed into nested sectioning content, so headings inside a sibling/nested <section> leaked out as context — that's what made sibling headings resolve one-deeper and union variants cascade h3→h4→h5. The fallback now skips section/article/aside/nav, consistent with the previous-sibling scan. (header/footer/main are still traversed — a <header> contains its section's heading; a blanket boundary skip fails 4 of the existing "wrapped headings" rendering tests.)
2. levelOf returned 1 when the walk reached a boundary that had no heading of its own — that's what pinned headings inside heading-less wrapper sections to <h1>. Such boundaries are now transparent: the walk keeps searching outward.

With that fix, this PR needs no code change — the headings here just sit in <Load>'s section and all resolve to the same level, one below whatever heading precedes the block. I reworded these comments in cc92e97 so they state intent rather than describe the (now-fixed) quirk.

Verified the full chain: ember-primitives suite green with the fix (388 pass, incl. all existing wrapped-headings/extraneous-sections/shadow cases + 2 new unit tests); kolay suite green with the fixed package injected (regression test unchanged — it never encoded the buggy levels); nvp.ui floating-deps repro with both packed fixes: 83/83 under axe-core 4.12.1, timeline now renders h3 Timeline → h4 Element / h4 Arguments / h4 Blocks with union variants at equal levels, theme-toggle h2 API Reference → h3 Element → h3 State Attributes.

Note: until ember-primitives#776 lands and a release flows through (ember-primitives pins which-heading-do-i-need exactly, currently 0.2.6), published kolay + this PR yields h3/h4/h4-style siblings through the repl wrappers — still heading-order-legal everywhere, so nothing is blocked on the ordering of the two merges.

[NullVoxPopuli-ai-agent]

The Browser Tests failures on this PR are an unrelated CI race, not the heading change: @embroider/vite 1.5.2's jump-dir race guard only catches EEXIST, but parallel test-app builds renaming onto the same content-addressed /tmp/embroider-vite-jump-<hash> throw ENOTEMPTY on Linux (it hit markdown-only twice and custom-root-url once, racing for the same target hash — it fires on any PR that changes kolay's dist, since all three test apps rebuild in parallel with no turbo cache hit). Embroider already fixed the guard upstream in @embroider/vite 1.7.7+; #319 bumps the test apps' pins accordingly. Once #319 lands, a rebase/re-run here should be green — the suites themselves pass locally on this branch (browser 29/29 incl. the new regression test, node 75/75).

[NullVoxPopuli-ai-agent]

0093f54 bumps ember-primitives to ^0.60.1 (addon package, docs-app, and both test apps that pin it) — 0.60.1 ships which-heading-do-i-need 0.4.1 with the traversal fixes from universal-ember/ember-primitives#776, so this PR now delivers the complete heading fix (kolay markup + primitives detection) in one release.

Re-verified with the real 0.60.1 from npm (not a packed build): browser suites 6/6 tasks — docs-app 29/29 including the heading regression test, which asserts the flattened behavior (an <h2> before a ComponentSignature yields three sibling h3.typedoc__headings: Element / Arguments / Blocks — no more h3/h4/h4 stepping through wrapper layers, no union-variant cascade); node tests 75/75; lint (js, types, hbs, prettier, publint) all green. No test or docs expectation encoded the pre-fix levels.

Downstream effect once this releases: nvp.ui's floating-deps a11y jobs go green with its markdown untouched (## API Reference → h3 signature headings → ### State Attributes), which unblocks NullVoxPopuli/nvp.ui#99.

[NullVoxPopuli]

do these still need to be moved out of the sections?

[NullVoxPopuli]

it's possible that declarations within here could have headers as well

[NullVoxPopuli-ai-agent]

No — they're back in 57ffca5, and you're right on both counts. With the ember-primitives@0.60.1 bump this PR now carries (which-heading-do-i-need 0.4.1), a heading-less boundary is transparent instead of pinning h1, so headings inside these sections resolve correctly again.

One catch, found empirically: restoring the sections exactly as they were renders Element h3 / Arguments h3 / Blocks h4 — the regression test fails with "h3.typedoc__heading exists twice". Arguments never had a <section>, so its heading sits directly in <Load>'s section, and per the sectioning rules a <section> following a sibling h3 is a subsection of it — the detection's previous-sibling scan finds the Arguments h3 and nests Blocks under it. So 57ffca5 makes the structure uniform instead: every part (Element, Arguments, Blocks, Return) is a sibling <section> containing its heading and its content, and uniform sibling sections all resolve to the same level, one below the preceding document heading.

And yes — declarations in here can carry headings, since comments are compiled markdown. That's the strongest reason to keep the sections: content contained in a part's <section> can't become level-context for the parts that follow (both the sibling scan and the fallback traversal skip sectioning content). Element's comment moved inside its section for the same reason — it used to render after </section>, directly in <Load>'s section, where a comment-authored heading would push Arguments/Blocks down a level. Covered by a new sample + test: SignatureWithCommentHeadings has #### Element notes / #### Block usage in its comments; the test asserts the three signature headings stay h3, the comment h4s render contained in their sections, and no h5 appears (no drift).

Verification on 57ffca5: browser suites 6/6 turbo tasks (docs-app 30 pass / 5 skip / 0 fail, incl. both heading tests), test:node 75/75, pnpm lint 17/17 tasks. The rendered result is unchanged from the flattened markup: h2 API Reference → h3 Element / h3 Arguments / h3 Blocks.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
kolay-docs-app	Ready	Preview, Comment	Jul 13, 2026 4:25pm