feat(bulma-ui): make Button and Link as prop polymorphic (React.ElementType)

[bestaxbot]

Summary

• Widen the Button as prop from a fixed 'a' | 'button' union to React.ElementType, so it can render as a router Link component (React Router, Next.js, TanStack Router, etc.) while keeping Bulma styling and real anchor semantics.
• Add a new as prop (default 'a') to Link for the same polymorphic rendering.
• LinkButton inherits the same polymorphism for free, since it already forwards its props to Button — no code change needed there.
• Add an accessibility admonition to the top of the Button docs page steering readers toward LinkButton for link-styled or navigating click targets.
• Add Storybook stories and Jest tests for the new polymorphic as usage; update the Button, Link, and LinkButton docs pages.

Fixes #188

Test plan

• pnpm --filter @allxsmith/bestax-bulma run typecheck
• pnpm --filter @allxsmith/bestax-bulma run lint (0 errors, pre-existing unrelated warnings only)
• pnpm --filter @allxsmith/bestax-bulma run test:coverage (3325/3325 passing, Button.tsx/Link.tsx/LinkButton.tsx at 100% coverage)
• pnpm run format:check
• pnpm run gen:catalog:check (catalog unchanged — no component added/renamed)

Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Button, Link, and LinkButton now support rendering with a custom as component, making them more flexible for router-style links and other custom elements.
  • Added examples in Storybook showing polymorphic usage for each component.

• Bug Fixes

  • Improved prop forwarding so component-specific attributes are passed through correctly.
  • Prevented button-only attributes from leaking onto non-button render targets.

• Documentation

  • Updated API docs and usage examples to cover the new polymorphic rendering behavior and related accessibility guidance.

[coderabbitai]

Walkthrough

The as prop on Button and Link (and by extension LinkButton) is widened from a restricted string union to React.ElementType, enabling polymorphic rendering via custom components (e.g., router Link). Rendering logic, prop stripping, stories, tests, and docs are updated accordingly.

Changes

Polymorphic as prop implementation

Layer / File(s)	Summary
Button core rendering logic bulma-ui/src/elements/Button.tsx	ButtonProps.as widened to React.ElementType; internal Component variable defaults to 'button'; render path switches on Component !== 'button' and renders <Component> with anchor-only prop stripping.
Button stories and tests bulma-ui/src/elements/Button.stories.tsx, bulma-ui/src/elements/__tests__/Button.test.tsx	New PolymorphicAs story and tests verify custom-component rendering, forwarded link props, and stripped button-only attributes.
Link core rendering logic bulma-ui/src/elements/Link.tsx	LinkProps gains as?: React.ElementType (default 'a'); component destructures Component and renders it instead of a hardcoded <a>.
Link stories and tests bulma-ui/src/elements/Link.stories.tsx, bulma-ui/src/elements/__tests__/Link.test.tsx	New PolymorphicAs story and tests verify default <a> rendering and custom component prop/class forwarding.
LinkButton stories and tests bulma-ui/src/elements/LinkButton.stories.tsx, bulma-ui/src/elements/__tests__/LinkButton.test.tsx	New PolymorphicAs story and test confirm LinkButton inherits polymorphic rendering via Button.
Documentation updates docs/docs/api/elements/button.md, docs/docs/api/elements/link.md, docs/docs/api/elements/linkbutton.md	Props tables updated to React.ElementType; new "Polymorphic as (Router Links)" usage sections added; accessibility caution added to Button docs.

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

Sequence Diagram(s)

sequenceDiagram
  participant App
  participant Button
  participant Component as "Custom Component (e.g., RouterLink)"

  App->>Button: render with as=RouterLink, to="/visit"
  Button->>Button: destructure as Component (default 'button')
  Button->>Button: check Component !== 'button'
  Button->>Button: strip button-only props (type, disabled, form)
  Button->>Component: render <Component> with remaining props + className
  Component-->>App: rendered anchor/router element

Loading

Possibly related issues

• [Integration] No documented story for using bestax with React Router / Next.js (client-side navigation) #190: Requests polymorphic as support for router-link integration, which this PR directly implements for Button, Link, and LinkButton.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: polymorphic as support for Button and Link.
Description check	✅ Passed	The description covers the summary and test plan, but it omits several template sections like package checklist, change type, and screenshots.
Linked Issues check	✅ Passed	The PR implements the linked feature by making Button and Link polymorphic, preserving LinkButton behavior, and updating docs/tests/stories.
Out of Scope Changes check	✅ Passed	The changed files all support the polymorphic as feature and related documentation/testing, with no clear unrelated additions.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/issue-188-20260707-0205

---

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

[github-actions]

Preview Deployment

Preview URL: https://9d24ba79.bestax.pages.dev

[claude]

**Deep review complete** — 0 finding(s) posted as inline comments.

Reviewed the polymorphic as (React.ElementType) change across Button, Link, and LinkButton. Verified: old 'a'/'button' behavior preserved (Component !== 'button' branch), as destructured so it never leaks to the DOM, button-only attributes stripped for the link branch (documented), and accessibility handling (aria-disabled, tabIndex, disabled onClick preventDefault) intact. Ran the affected suites (60 tests pass), confirmed 100% coverage on all three changed files, and typecheck is clean. All five artifacts present — component, tests, stories, and docs pages — and the skills component catalog is not stale (description extractor skips the new :::caution admonition). No correctness, a11y, API-consistency, or coverage defects found.

[coderabbitai]

Actionable comments posted: 4

♻️ Duplicate comments (1)

bulma-ui/src/elements/Link.tsx (1)

30-30: 🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift

Same polymorphism gap as Button: as?: React.ElementType doesn't widen the prop surface.

Link is React.FC<LinkProps> and LinkProps extends only React.AnchorHTMLAttributes. <Link as={RouterLikeLink} to="/about"> (story/test) passes to, which isn't in LinkProps, so it won't type-check under strict TS. Consider a generic polymorphic signature so custom-component props are inferred from as.

See the companion comment on Button.tsx (Line 67) for the root-cause detail and verification.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@bulma-ui/src/elements/Link.tsx` at line 30, `Link` currently only accepts
anchor attributes even when `as` points to a custom component, so props like
`to` are not inferred. Update the `Link` typing to use a polymorphic generic
signature (similar to the `Button` fix) so `LinkProps` widens based on the `as`
component, and make sure `Link` itself and its prop definitions reflect that
inferred prop surface.

🧹 Nitpick comments (1)

bulma-ui/src/elements/Button.stories.tsx (1)

415-431: 🎯 Functional Correctness | 🔵 Trivial | 💤 Low value

Extract the shared RouterLikeLink story helper. It’s duplicated in Button.stories.tsx, Link.stories.tsx, and LinkButton.stories.tsx, so a small shared helper would reduce drift in the polymorphic stories.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@bulma-ui/src/elements/Button.stories.tsx` around lines 415 - 431, The
polymorphic Router-like link helper is duplicated across the Button, Link, and
LinkButton stories, so extract the shared RouterLikeLink component into a
reusable story helper and import it where needed. Update the PolymorphicAs story
in Button.stories.tsx to use the shared helper, and keep the same props shape
and anchor passthrough behavior so the polymorphic stories stay consistent.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@bulma-ui/src/elements/Button.tsx`:
- Line 67: The Button component is only partially polymorphic: the current as
prop changes the rendered element, but ButtonProps still do not inherit props
from the chosen element, so router-specific props like to won’t type-check.
Update Button to use a generic polymorphic type based on the selected element
(for example via ComponentProps<T> and a generic Button signature), or restrict
the API to only button/anchor props if full polymorphism is not intended. Focus
on the Button component types and its public props definition so RouterLikeLink
usages are accepted correctly.

In `@docs/docs/api/elements/button.md`:
- Around line 292-306: The router-link example in the Button docs is not
type-safe because ButtonProps currently does not accept router-specific props
like to when using as={RouterLink}. Update the docs example to match the actual
polymorphic API exposed by Button, either by widening the Button/ButtonProps
typing to forward the router component’s props or by replacing to with a prop
shape that is already supported by the component. Also tighten the “real anchor
semantics” copy in the Button polymorphic as section unless Button truly renders
or forwards an anchor element for custom components.

In `@docs/docs/api/elements/link.md`:
- Around line 109-121: The router-link example in Link documentation uses props
like to that are not part of the current Link type surface, so update the
example to avoid implying direct support for router-specific props unless Link
is truly polymorphic. Either rewrite the example to use a small wrapper
component that accepts and forwards router props, or adjust Link’s
typing/implementation so the as prop carries through the target component’s
props; reference the Link component and its polymorphic as usage in the docs
example.

In `@docs/docs/api/elements/linkbutton.md`:
- Around line 129-141: The router-link example in LinkButton docs is not
supported by the current type surface because LinkButton is only a
React.FC<LinkButtonProps> over ButtonProps, so it does not expose a typed to
prop. Update the documentation near the LinkButton “Polymorphic as” section to
either remove the RouterLink example or change LinkButton/Button to a truly
polymorphic API first; use the LinkButtonProps and ButtonProps symbols to verify
the documented usage matches the actual exported types.

---

Duplicate comments:
In `@bulma-ui/src/elements/Link.tsx`:
- Line 30: `Link` currently only accepts anchor attributes even when `as` points
to a custom component, so props like `to` are not inferred. Update the `Link`
typing to use a polymorphic generic signature (similar to the `Button` fix) so
`LinkProps` widens based on the `as` component, and make sure `Link` itself and
its prop definitions reflect that inferred prop surface.

---

Nitpick comments:
In `@bulma-ui/src/elements/Button.stories.tsx`:
- Around line 415-431: The polymorphic Router-like link helper is duplicated
across the Button, Link, and LinkButton stories, so extract the shared
RouterLikeLink component into a reusable story helper and import it where
needed. Update the PolymorphicAs story in Button.stories.tsx to use the shared
helper, and keep the same props shape and anchor passthrough behavior so the
polymorphic stories stay consistent.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 826fe6ad-0f64-4c76-82fa-71c6e8e18bd0

📥 Commits

Reviewing files that changed from the base of the PR and between 46d4e6e and 1f38a5b.

📒 Files selected for processing (11)

• bulma-ui/src/elements/Button.stories.tsx
• bulma-ui/src/elements/Button.tsx
• bulma-ui/src/elements/Link.stories.tsx
• bulma-ui/src/elements/Link.tsx
• bulma-ui/src/elements/LinkButton.stories.tsx
• bulma-ui/src/elements/__tests__/Button.test.tsx
• bulma-ui/src/elements/__tests__/Link.test.tsx
• bulma-ui/src/elements/__tests__/LinkButton.test.tsx
• docs/docs/api/elements/button.md
• docs/docs/api/elements/link.md
• docs/docs/api/elements/linkbutton.md

[github-actions]

AI loop status: iteration 1/4 — fix-reviews at 1f38a5b (2026-07-07T02:47:31Z).
Managed by claude-pr-loop.yml. To resume after a pause: set iteration back to 0 on the first line, re-add ai-loop, remove ai-loop-paused, then re-run via workflow_dispatch.

[github-actions]

AI loop paused: the fix run failed without pushing (see the Actions log). Remove ai-loop-paused, re-add ai-loop, and re-run via workflow_dispatch to retry.

[bestaxbot]

FIX agent (iteration 1/4, mode: fix-reviews) — summary

No code changes this pass. All four open CodeRabbit findings are the same underlying request and I am refuting them.

Finding (thread)	Verdict	Reason
Button.tsx:67 — make Button truly polymorphic (ComponentProps)	Refuted	Full generic polymorphic API is explicitly deferred by issue #188 (ideal but not required); a large public-API/type-system refactor, out of scope for a fix pass
button.md:306 — router example not type-safe	Refuted	Example mirrors the exact usage requested in #188; to is forwarded at runtime; static typing of forwarded props needs the deferred generic API
link.md:121 — router props not in type surface	Refuted	Link now adds as?: React.ElementType + ...rest per #188; runtime-forwards to; generic typing deferred
linkbutton.md:141 — router example misleading	Refuted	LinkButton forwards ...props to Button per #188; runtime-forwards to; generic typing deferred

Why refuted (shared reasoning):

• Issue [Feature] Make Button, Link, and LinkButton as prop polymorphic (React.ElementType) for router Link integration #188 sets the contract. It states a fully generic as with prop inference would be ideal, but that widening to React.ElementType and spreading ...rest onto the element would unblock the common case — and the per-component notes are literally widen as and forward ...rest (Button), add as?: React.ElementType default a (Link), flows for free (LinkButton). The PR implements exactly this.
• The type point is technically real but is the known, issue-accepted limitation: under a standalone strict tsc, <Button as={RouterLink} to=...> reports TS2322 because to is not on ButtonProps. However to is forwarded at runtime — the tests assert the rendered element receives data-to — so the documented common case works.
• Repo gates are green: pnpm run typecheck excludes *.stories.tsx/__tests__ (bulma-ui/tsconfig.json), and the jest suite passes (ts-jest does not surface this as a failure here).
• Making the trio fully generic (ComponentProps<T> inference) is a deliberate public-API decision that should be reviewed on its own, not folded into a review-fix pass. Escalating that call to a human maintainer.

Verification performed this pass:

• Read issue [Feature] Make Button, Link, and LinkButton as prop polymorphic (React.ElementType) for router Link integration #188 to establish scope.
• Confirmed runtime forwarding via existing passing tests (Button/Link/LinkButton data-to assertions).
• Ran pnpm --filter @allxsmith/bestax-bulma run typecheck (passes) and the Button test suite (19/19 passing).
• Reproduced the reviewers strict-tsc observation directly (TS2322 on to) to confirm the finding is technically accurate but out of scope.

No commit made (no cosmetic changes). CodeRabbit threads left open and unresolved for the reviewer to reconcile.

[github-actions]

AI loop stopped — contested findings. The fix agent pushed no changes and 1 review thread(s) remain open (refuted or unaddressable). A human ruling is needed; see the fix agent's summary above.

[github-actions]

🎉 This PR is included in version 5.2.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀

[github-actions]

🎉 This PR is included in version 3.2.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀

[github-actions]

🎉 This PR is included in version 1.0.0 🎉

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.0.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀