fix(bulma-ui): let Level.Item's anchor take the rest of an anchor's attributes

[allxsmith]

The non-breaking half of #672. The rest is deferred — see below.

Important

Do not squash-merge. bestax-migrate/release.config.js opens with { scope: '!(bestax-migrate)', release: false }, so a fix(bulma-ui) squash commit would publish the library and silently suppress the codemod release. Rebase or merge commit.

What was wrong

LevelItemProps enumerated href, target and rel, so every other anchor attribute was a type error even on the anchor form:

<Level.Item as="a" download="f" />               // ❌ before
<Level.Item as="a" referrerPolicy="no-referrer" /> // ❌ before

Both are the literal symptom #641 reported.

AnchorOnlyAttributes subtracts React.HTMLAttributes from React.AnchorHTMLAttributes, so what the anchor form accepts is exactly what <a> adds — href, target, rel, download, hrefLang, ping, referrerPolicy, media, type — and it tracks React rather than this file. An earlier revision of this PR swapped the three-name list for a seven-name one; reviewers pointed out that still left media and type rejected, and still needed a human to notice the next one. A list gains an entry when someone notices; a subtraction gains it when React does.

Why enumerated rather than derived from as

Deriving them is the better shape and it is source-breaking, so it waits for the major.

This PR originally did derive them, by making Level.Item polymorphic through the shared ConstrainedPolymorphicComponentWithoutRef. That version was reviewed and reverted. It worked, and it broke three things — each verified by compiling identical probes against main and the branch:

• <Dropdown.Item {...bag} /> where bag: DropdownItemProps<'button'> → TS2769. That component is already released. The break came from editing a shared helper, which a PR about Level.Item had no business touching.
• const p: LevelItemProps = { onClick: e => … } → TS7006. Replacing extends HTMLAttributes<A | B | C> with a non-distributive Omit turns one handler over a union element into a union of three handler types, and contextual typing stops.
• keyof ComponentProps<typeof Dropdown.Item> collapsed to the shared keys, so 'href' stopped being one.

None of that is needed to fix #641's symptom. What ships here cannot reach Dropdown.Item, changes no shared helper, and leaves every existing shape compiling — the spread round-trip, event handlers, ComponentProps, keyof, and React.memo, all asserted.

The half that is deferred

href and friends are declared at every as, so this still compiles:

<Level.Item as="p" download="f" />   // type-checks; renders a <p> without it

The type permits it and the runtime refuses it — the new attributes are withheld from any tag that is not an <a>, asserted in both directions. Making it a type error is what #672 keeps, under next-major, alongside #667 and #681.

The codemod half

TARGET_LINK_ATTRS records what a target declares when its props do not follow as. Level.Item was its only row, listing ['target'] — which would now strip a download the component accepts and write a TODO saying it was rejected.

Since the component carries the anchor's whole surface, a row naming every attribute decides nothing a row naming none does, so the row is gone and the existing sweep covers the target: every href-capable target without a row is asserted to accept every link attribute on its anchor. That does leave the rejectedBy = 'component' arm without a live caller — noted in the code as worth deleting rather than kept for a hypothetical.

Three shipped skill references stated the old claim verbatim and are corrected. Nothing catches that class of drift: the copies agree with each other, so skills-sync and the generators are green either way.

Filed from the review

• [Bug] bulma-ui: an explicit type argument picks a polymorphic element without as #681 — an explicit type argument picks a polymorphic element without as (<Button<'a'> href /> renders a <button>). Pre-existing on main, on every component with an as. next-major.
• [Refactor] bulma-ui: the anchor-attribute strip is implemented three times #682 — the anchor-attribute strip is implemented three times, each a different subset. Not breaking.

Also fixed here

catchAllRow in the docs extractor read the props base with String.match and no /g, so a component whose base is a union of elements was described by whichever came first. Level.Item said "All standard <div> attributes" while rendering a <p> and an <a> too; Title and SubTitle lost their <p> the same way. Both generators call extractComponent, so the API pages and the MCP index were wrong together.

Verification

pnpm all green, check:conformance green, all four generators current, 1213 migrate tests, Level suite green with tests for forwarding and withholding — the withholding fixture supplies every attribute it asserts against, since checking four while passing two made two of them vacuous.

Non-breaking is measured, not asserted: the same probes compile against main and this branch with zero errors on both — event handlers, the spread round-trip, assignability to HTMLAttributes<HTMLDivElement>, ComponentProps/keyof/index access, React.memo, the released Dropdown.Item, and ordinary usage. Those probes now live in bulma-ui/src/__typetests__/polymorphic.tsx rather than in a scratch file, because the earlier revision of this PR broke five of them and a deleted probe proves nothing.

Summary by CodeRabbit

• New Features

  • Level.Item now supports the full set of standard anchor attributes, including download, media, and type, when rendered as an anchor.
  • Anchor-only attributes remain excluded when rendered as another element.
  • Added a Storybook example demonstrating anchor-specific attributes.

• Documentation

  • Updated component and migration guidance for anchor attributes and rendering behavior.
  • Clarified supported attributes for title and subtitle elements.

• Tests

  • Added coverage for anchor attribute forwarding and non-anchor filtering.

[coderabbitai]

Warning

Review limit reached

Next included review available in 27 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: d414f574-fb63-4b5a-ad49-4fb80482d9ba

📥 Commits

Reviewing files that changed from the base of the PR and between 1509f69 and b2a1405.

📒 Files selected for processing (3)

• bestax-migrate/src/sources/_shared/polymorphic.ts
• bulma-ui/src/layout/Level.tsx
• scripts/props-extract.test.mjs

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: f44d1411-794a-498f-b3ea-c38985d2bc49

📥 Commits

Reviewing files that changed from the base of the PR and between e901f91 and 1509f69.

📒 Files selected for processing (14)

• bestax-mcp/data/components/Level.json
• bestax-mcp/data/components/SubTitle.json
• bestax-mcp/data/components/Title.json
• bestax-mcp/data/skills.json
• bestax-migrate/src/sources/_shared/polymorphic.ts
• bulma-ui/src/__typetests__/polymorphic.tsx
• bulma-ui/src/layout/__tests__/Level.test.tsx
• docs/docs/api/elements/subtitle.md
• docs/docs/api/elements/title.md
• docs/docs/api/layout/level.md
• scripts/lib/props-extract.mjs
• skills/bestax-migrate/references/bloomer/unmappables.md
• skills/bestax-migrate/references/rbx/unmappables.md
• skills/bestax-migrate/references/react-bulma-components/unmappables.md

🚧 Files skipped from review as they are similar to previous changes (6)

• skills/bestax-migrate/references/rbx/unmappables.md
• bulma-ui/src/layout/tests/Level.test.tsx
• skills/bestax-migrate/references/bloomer/unmappables.md
• bestax-mcp/data/components/Level.json
• skills/bestax-migrate/references/react-bulma-components/unmappables.md
• docs/docs/api/layout/level.md

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

Walkthrough

Level.Item now derives anchor-only props from React types, forwards them only for as="a", and removes them from non-anchor output. Tests, stories, migration guidance, documentation, and metadata reflect the updated behavior.

Changes

Level.Item anchor attributes

Layer / File(s)	Summary
Anchor attribute forwarding bulma-ui/src/layout/Level.tsx, bestax-migrate/src/sources/_shared/polymorphic.ts	LevelItemProps derives anchor-only attributes from React types, including media and type. Anchor rendering forwards the full prop set. Non-anchor rendering filters anchor-only names. Component-level link-attribute restrictions no longer apply to Level.Item.
Forwarding validation bulma-ui/src/layout/__tests__/Level.test.tsx, bulma-ui/src/layout/Level.stories.tsx, bulma-ui/src/__typetests__/polymorphic.tsx, bestax-migrate/e2e/as-unions.test.ts	Tests verify anchor attribute typing, forwarding, and filtering. The AnchorItem story demonstrates anchor-specific attributes. The former Level.Item-specific negative type assertion is removed.
Migration and published metadata scripts/lib/props-extract.mjs, skills/bestax-migrate/references/*/unmappables.md, docs/docs/api/layout/level.md, docs/docs/api/elements/{subtitle,title}.md, bestax-mcp/data/components/{Level,SubTitle,Title}.json, bestax-mcp/data/catalog.json, bestax-mcp/data/skills.json	Documentation describes the derived anchor attributes and paragraph attributes. Props extraction now includes all HTML element types in union bases. Catalog counts and reference byte counts are updated.

Priority: ⚪ Pending latest changes

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Bug fix · Severity of issue fixed: Medium

Suggested reviewers: claude

Merge Risk: ⚪ Minimal · up to 1509f

The documented Level.Item element surface now includes paragraph rendering alongside anchor and div support. No actionable merge-blocking risk remains.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	Issue #641 requires polymorphic props and ref types derived from as, rejection of invalid attributes for non-matching elements, and type-level coverage for Button, Navbar.Link, Navbar.Item, an…	Implement the generic prop and ref model for every component in issue #641, including valid and invalid type-level tests for each listed component. Then satisfy the issue acceptance checks, including typecheck, test coverage, conformance, a…
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 9 files. (10 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Out of Scope Changes check	✅ Passed	The source change, runtime tests, migration updates, type tests, documentation, skill references, and generated outputs support the Level.Item anchor-attribute compatibility work or its generated re…
Title check	✅ Passed	The title clearly identifies the primary change: allowing Level.Item anchors to receive the remaining anchor attributes.
Description check	✅ Passed	The description gives a detailed summary, affected areas, linked issues, rationale, deferred scope, tests, documentation, and verification results. It does not reproduce the template headings or check…

Full details: Linked Issues check

Explanation

Issue #641 requires polymorphic props and ref types derived from as, rejection of invalid attributes for non-matching elements, and type-level coverage for Button, Navbar.Link, Navbar.Item, and Menu.Item. The reviewed changes modify only Level.Item. Its type tests explicitly preserve a non-polymorphic contract and defer deriving attributes from as. The required component coverage and invalid-attribute checks are not present.

Resolution

Implement the generic prop and ref model for every component in issue #641, including valid and invalid type-level tests for each listed component. Then satisfy the issue acceptance checks, including typecheck, test coverage, conformance, and regenerated documentation.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 9 files. (10 skipped: 10 unsupported.)

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/672-level-item-polymorphic

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

🟡 Changes recommended

The public props alias lacks the claimed compatibility tests, and migration test documentation remains stale.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Updates Level.Item so anchor variants accept native anchor attributes while preserving compatibility.

Changes:

• Adds constrained polymorphic typing and type/story coverage.
• Removes the obsolete migration exception.
• Regenerates API and MCP documentation.

File summaries

File	Description
docs/docs/api/layout/level.md	Updates generated API documentation.
bulma-ui/src/layout/Level.tsx	Adds polymorphic Level.Item props.
bulma-ui/src/layout/Level.stories.tsx	Demonstrates anchor attributes.
bulma-ui/src/__typetests__/polymorphic.tsx	Tests component-level typing.
bestax-migrate/src/sources/_shared/polymorphic.ts	Removes the obsolete link-attribute exception.
bestax-migrate/e2e/as-unions.test.ts	Tests the constrained as union by use.
bestax-mcp/data/components/Level.json	Regenerates component metadata.

Review details

• Files reviewed: 7/7 changed files
• Comments generated: 2
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

Preview Deployment

Preview URL: https://e05de395.bestax.pages.dev

[github-actions]

Preview Deployment

Preview URL: https://298524cb.bestax.pages.dev

[Copilot]

🔵 Needs a closer look

The new overload breaks existing ComponentProps and React.memo usage for non-default Level.Item elements.

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

bulma-ui/src/layout/Level.tsx:288

• This cast's final derivation overload is pinned to 'div', so React.ComponentProps<typeof Level.Item> and React.memo(Level.Item) now reject as="p" and as="a". Previously LevelItem was React.FC<LevelItemProps>, whose prop type included all three tags, making this a source-breaking change in a patch described as non-breaking. Preserve a final derivation overload based on the whole-union LevelItemProps while retaining the generic overload for direct-call precision, and pin both ComponentProps and memo compatibility in the type tests.

• Files reviewed: 8/8 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[github-actions]

Preview Deployment

Preview URL: https://633a7562.bestax.pages.dev

[Copilot]

🟡 Changes recommended

The new HOC-derived union loses element-specific prop correlation and accepts invalid attribute combinations.

Get a fresh assessment by requesting another Copilot review.

Review details

• Files reviewed: 9/9 changed files
• Comments generated: 1
• Review effort level: Balanced

[github-actions]

Preview Deployment

Preview URL: https://fda8cca1.bestax.pages.dev

[Copilot]

🔵 Needs a closer look

The fallback overload accepts anchor-only props without as="a", and related shipped guidance is stale.

Review details

Suppressed comments (2)

Previously missed (1) — in code that hasn't changed since the last review.

bulma-ui/src/helpers/polymorphic.ts:174

• This new constrained-HOC behavior leaves the shipped contributor guidance stale: skills/bestax-custom-component/references/library-contributor.md:130-132 still says React.memo collapses a constrained component onto its default element. bulma-ui/CLAUDE.md:30 requires guidance invalidated by a component change to be updated in the same PR.

bulma-ui/src/helpers/polymorphic.ts:179

• This fallback overload makes as optional in every member of the Allowed union. Consequently <Level.Item download="f" /> (and the memoized equivalent) can match the anchor member even though runtime defaults to <div> and forwards download there. Keep as optional only for the default member and require it for every non-default member.

  (props: PolymorphicProps<Allowed, Own>): React.ReactElement | null;

• Files reviewed: 9/9 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[github-actions]

Preview Deployment

Preview URL: https://6237d3f9.bestax.pages.dev

[Copilot]

🟡 Changes recommended

The derived union still accepts anchor-only properties without an explicit anchor as.

Get a fresh assessment by requesting another Copilot review.

Review details

• Files reviewed: 11/11 changed files
• Comments generated: 1
• Review effort level: Balanced

[github-actions]

Preview Deployment

Preview URL: https://c745d53f.bestax.pages.dev

[Copilot]

🟡 Changes recommended

The generic overload still permits selecting a non-default element type without supplying as, causing the rendered element and accepted attributes to diverge.

Get a fresh assessment by requesting another Copilot review.

Review details

• Files reviewed: 11/11 changed files
• Comments generated: 2
• Review effort level: Balanced

[github-actions]

Preview Deployment

Preview URL: https://e85317e6.bestax.pages.dev

[Copilot]

🟡 Changes recommended

The derived union remains non-exclusive, and shipped migration guidance still describes the removed exception.

Get a fresh assessment by requesting another Copilot review.

Review details

• Files reviewed: 11/11 changed files
• Comments generated: 1
• Review effort level: Balanced

[github-actions]

Preview Deployment

Preview URL: https://7809a0c3.bestax.pages.dev

[Copilot]

🟡 Changes recommended

The runtime filter can drift from its derived type, and the extractor fix lacks a focused regression test.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (2)

Previously missed (1) — in code that hasn't changed since the last review.

bulma-ui/src/layout/Level.tsx:168

• rel is already declared by React.HTMLAttributes, so this Omit removes it from AnchorOnlyAttributes. Listing it as an attribute supplied by this alias misstates the type and contradicts the migration code's explanation that rel is global; clarify that it remains available through the other base interface.

This issue also appears on line 255 of the same file.

bulma-ui/src/layout/Level.tsx:265

• The public type now gains new anchor-only keys automatically from React, but this filter remains an unchecked manual list. After such a type update, a new key would compile on as="p" and leak to the <p>, violating the documented withholding guarantee. Make the runtime map statically exhaustive against keyof AnchorOnlyAttributes (plus the deliberately stripped global rel) so type checking forces the two surfaces to stay synchronized.

  const ANCHOR_ONLY = [
    'href',
    'target',
    'rel',
    'download',
    'hrefLang',
    'ping',
    'referrerPolicy',
    'media',
    'type',
  ] as const;

• Files reviewed: 18/18 changed files
• Comments generated: 1
• Review effort level: Balanced

[github-actions]

Preview Deployment

Preview URL: https://64b49c4c.bestax.pages.dev

[Copilot]

🔵 Needs a closer look

The runtime attribute list can drift from its derived type, and the extractor fix lacks a direct regression test.

Review details

Suppressed comments (3)

Previously missed (2) — in code that hasn't changed since the last review.

bulma-ui/src/layout/Level.tsx:265

• This manually maintained array can drift from the derived AnchorOnlyAttributes, recreating the failure mode the subtraction is intended to prevent: a future React anchor key would become accepted at every as but would leak onto <div>/<p> because it is absent here. Make this an exhaustive keyed object such as Record<keyof AnchorOnlyAttributes | 'rel', true> and filter with key in ANCHOR_ONLY, so an upstream type addition causes a compile-time failure until runtime filtering is updated.
  bulma-ui/src/layout/Level.tsx:168
• rel is not part of this derived type: this repository's React contract explicitly treats rel as a member of HTMLAttributes (see components/Dropdown.tsx:415-419 and bestax-migrate/e2e/as-unions.test.ts:350-352), so the Omit removes it. LevelItemProps still accepts rel through its HTMLAttributes base, but this documentation currently misstates what AnchorOnlyAttributes contains.

scripts/lib/props-extract.mjs:1198

• The new multi-element extraction path has no direct regression test. scripts/props-extract.test.mjs already pins several catch-all contracts, but none asserts the Level/Title union output, so a return to first-match behavior could be accepted simply by regenerating the currently checked-in docs and MCP data. Add an extractor test that expects every element in one of these union bases.

    for (const m of e.text.matchAll(/HTML\w*Element/g)) {
      elements.add(DOM_ELEMENT_LABELS[m[0]] ?? 'HTML');
    }

• Files reviewed: 18/18 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[github-actions]

Preview Deployment

Preview URL: https://5fa4281c.bestax.pages.dev

[Copilot]

🟢 Approval recommended

The behavior is comprehensively covered and generated surfaces are synchronized; only a minor inline documentation correction remains.

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

bulma-ui/src/layout/Level.tsx:168

• rel is not produced by this subtraction: as the migration code notes, React declares it on HTMLAttributes, so AnchorOnlyAttributes excludes it. Listing it here as anchor-only contradicts the actual type and obscures why the runtime filter treats rel as a separate compatibility case.

• Files reviewed: 19/19 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Copilot]

🟢 Approval recommended

The compatibility-preserving implementation is consistently documented and covered across runtime, types, migrations, and generated outputs.

Review details

• Files reviewed: 19/19 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[github-actions]

Preview Deployment

Preview URL: https://129a1fc3.bestax.pages.dev

[bestax-release-bot]

🎉 This PR is included in version 5.15.3 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[bestax-release-bot]

🎉 This PR is included in version 2.3.4 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[bestax-release-bot]

🎉 This PR is included in version 1.2.5 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[bestax-release-bot]

🎉 This PR is included in version 4.2.9 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀