feat(bestax-migrate): convert .icon-text, building its icons from props

[allxsmith]

Refs #809. This is its .icon-text item. .file is still open there, and I've proposed dropping the .tabs item.

IconText builds each icon from iconProps (items, for more than one) and wraps each text in a <span> of its own, so until now the codemod left .icon-text as markup. It now converts it when its children are .icons, each followed by at most one bare <span> of static text:

<span className="icon-text">
  <span className="icon" aria-label="Home">
    <i className="fas fa-home"></i>
  </span>
  <span>Home</span>
</span>
// becomes
<IconText iconProps={{ library: "fa", name: "home", ariaLabel: "Home" }}>Home</IconText>

How an icon is read. Each .icon's <i> becomes library, name and, where needed, variant and features. That covers Font Awesome, with each of its style classes, and Material Design Icons. library is always written, so a ConfigProvider with another iconLibrary can't change what renders. Whatever the .icon's own classes and attributes become on Icon joins those props, with aria-label as ariaLabel. This is the name form we picked over keeping the <i> as children, because it's what a person would write.

What still keeps it markup:

• A .icon has to convert to Icon on its own first, so the aria-label rule still holds. That limits the reach: Bulma's own example has no aria-label. Those icons still get their defaults:Icon TODO telling people to add one.
• Anything else stays markup with a children:IconText TODO: an aria-hidden on the <i>, another icon font, text before an icon, a div.icon-text, and so on. The .icons inside still convert on their own.

Things worth a look:

• Re-runs. When an icon-text refuses, a .icon inside may convert on its own, and a second run then sees an Icon component where the first saw markup. addTodo dedupes by exact text, so the TODO has to read the same both times. The planner therefore gives the general reason whenever a child converted on its own, and checks the children after the element's own checks, like the tag.
  • For the same reason, a computed className on the icon-text keeps its .icons as markup too.
  • The fixture and a transform test both check that a second run changes nothing.
• data-* attributes. The props typecheck caught that a .icon with a data-* attribute can't move into iconProps. JSX lets any dashed name through, but an object literal typed as Icon's props only accepts the declared aria- ones. Those stay markup.
• Formatting. Recast prints the object across several lines, as it does for any object it builds, so run your formatter over the output.

Tests:

• A render truth test over every glyph shape, an icon's own classes and attributes, and multi-icon layouts. Breaking the glyph reader on purpose fails it.
• A props typecheck over the same.
• Planner and glyph-reader unit tests, a fixture pair and transform tests, and an icon-text in the kitchen sink.

Also in this PR:

• MCP: lookup_bulma_classes describes what IconText builds, and the index carries the new buildsIcons.
• ESLint plugin: no-bulma-component-class now reports .icon-text as a class the codemod converts.
• Docs: the skill's component map and unmappables, plus the migration guide.

pnpm all passes locally.

[coderabbitai]

Warning

Review limit reached

Next included review available in 56 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: Repository: allxsmith/bestax/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 3014d0ba-9308-412a-84a3-f97fcf026857

📥 Commits

Reviewing files that changed from the base of the PR and between ef5db9d and 15c329b.

⛔ Files ignored due to path filters (1)

• eslint-plugin/src/generated/metadata.ts is excluded by !**/generated/**

📒 Files selected for processing (22)

• bestax-mcp/data/bulma-classes.json
• bestax-mcp/data/skills.json
• bestax-mcp/src/__tests__/bulma-classes-agree.test.ts
• bestax-mcp/src/bulma-classes.ts
• bestax-migrate/CLAUDE.md
• bestax-migrate/e2e/bulma-classes-props.test.ts
• bestax-migrate/e2e/bulma-classes-truth.test.ts
• bestax-migrate/e2e/support/icon-text.ts
• bestax-migrate/fixtures/bulma-classes-kitchen-sink/src/elements.tsx
• bestax-migrate/src/sources/bulma-classes/__testfixtures__/icon-text.input.tsx
• bestax-migrate/src/sources/bulma-classes/__testfixtures__/icon-text.output.tsx
• bestax-migrate/src/sources/bulma-classes/__tests__/glyph.test.ts
• bestax-migrate/src/sources/bulma-classes/__tests__/plan.test.ts
• bestax-migrate/src/sources/bulma-classes/__tests__/transform.test.ts
• bestax-migrate/src/sources/bulma-classes/class-map.ts
• bestax-migrate/src/sources/bulma-classes/glyph.ts
• bestax-migrate/src/sources/bulma-classes/plan.ts
• bestax-migrate/src/sources/bulma-classes/transform.ts
• docs/docs/guides/getting-started/migration/bulma-classes.md
• scripts/gen-mcp-index.mjs
• skills/bestax-migrate/references/bulma-classes/component-map.md
• skills/bestax-migrate/references/bulma-classes/unmappables.md

---

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.}

[github-actions]

Preview Deployment

Preview URL: https://8be57c55.bestax.pages.dev

[claude]

Deep review — 0 blocking · 3 advisory

#	Severity	Area	Finding	Location
1	🔵 Advisory	API	The lookup_bulma_classes prose ends with a sufficiency claim that isn't one — "The codemod does that when each .icon holds a bare, empty naming a Font Awesome or Material Design Icons glyph" omits the conditions that actually gate it (the .icon must convert to Icon on its own, i.e. carry an aria-label and no key/ref/non-aria dashed attribute; the element must be a <span>; the only other children must be bare static-text <span>s). The skill's component-map.md states it correctly. Deleting that last sentence leaves the paragraph true.	bestax-mcp/src/bulma-classes.ts:789
2	🔵 Advisory	Coverage	transform.ts:1250 is the one uncovered line of the new code — the branch that keeps a built-in .icon in elements when its own plan carried a TODO alongside its conversion. Reachable today only through LEGACY_09, whose sole entry is tile (className="icon tile"). Package thresholds are met either way.	bestax-migrate/src/sources/bulma-classes/transform.ts:1250
3	🔵 Advisory	Robustness	Two safe under-reaches worth recording: an .icon-text written on one line refuses, because the inline space between children reaches React and childElementsOf bails (a newline-separated one is fine, which is how Bulma's docs and any formatter write it); and a .icon whose className is a clsx/classnames call is never seen as an icon at all, because childFacts gives it tokens: null. Both leave the markup alone rather than converting it wrongly.	bestax-migrate/src/sources/bulma-classes/plan.ts:822

Overall: The change is sound and unusually well fenced. The key design decision — read the <i> back into library/name/variant/features rather than keeping it as Icon children — is safe by construction, not just by test: readGlyph picks exactly one non-modifier prefixed token as the name and hands everything else but the style/base token to features, and Icon re-emits [style, prefix+name, ...features], so the rendered class set is always identical to the input's; the only ways out are "two candidates" or "no candidate" → refuse, and the fa-fa-/mdi-mdi- guard covers the one transform Icon applies to name. The riskiest part is the re-run story, and it holds for the reason the PR gives plus one it doesn't spell out: once any child converts on its own, childFacts returns undefined for it (it is no longer an intrinsic tag), so childElementsOf returns undefined wholesale and buildIcons falls straight to the shape message — which is exactly what the alone flag makes the first run say. A human should focus on the MCP sentence in row 1, since that text is what an agent acts on.

Residual risk:

• A glyph read into props that renders different classes. Refuted structurally (above) and empirically: bulma-classes-truth.test.ts renders all 14 GLYPHS plus every .icon class/attribute shape and compares normalised HTML, bulma-classes-fixtures-render.test.ts renders icon-text.input.tsx against .output.tsx, and bulma-classes-kitchen-sink.test.ts asserts the whole app renders identically, typechecks, and is unchanged by a second run. All green here (2098 tests), as are gen:mcp:check, gen:eslint-meta:check, check:conformance and format:check.
• Props that don't typecheck. bulma-classes-props.test.ts typechecks the built object for every glyph, every .icon modifier class and every COMMON attribute including data-test (which is refused). The guard is buildIcons' loose check — a dashed name that isn't aria- refuses — and everything else must live in React.HTMLAttributes<HTMLSpanElement>, which IconBaseProps extends. aria-describedby is exercised by the planner and render tests but not by the typecheck sweep; AriaAttributes declares it, so that is a test-surface gap rather than an exposure.
• A spread or a duplicate key inside iconProps. Refuted: plan refuses hasSpread before anything else, so iconObject never meets a JSXSpreadAttribute (which would crash attributeName); and an attribute sharing a name with an Icon prop (name, library, size, …) refuses at plan.ts:466 because .icon's ownProps lists them, so the glyph's name can never be overwritten by a later key.
• A TODO that reads differently on a re-run. One shape is still open, and it is narrow: alone is some(child => child.becomes), and becomes reads only conversion, never fold. So an .icon-text holding both a non-converting .icon and a fold sibling (.table-container / .fixed-grid — the only two) would say "see the TODO on each" on run 1 and the general shape message on run 2. I could not construct a realistic input for it, and the fixture plus transform.test.ts cover the re-run shapes that do occur.
• A TODO left on a node the conversion deleted. Open but benign: the cleanup loop un-plans the .icon children only, not their descendants. An <i> can never convert (i is not in WRAPPERS) but can still carry a legacy:/family: TODO (class="fas fa-home tile"), which would then be reported for markup that is gone — while the class itself survives in features, so the hint stays accurate.
• Point-in-time evidence in docs or comments: none added.

🏄 Total glassy set, dude — the glyph reader paddles out and comes back with the exact same wave it caught, and the re-run story holds together on its own two fins. Nothing to bail on here; just tidy that one MCP sentence before you kick out.

[allxsmith]

On the review's advisories:

1. Fixed in d9c9007 by deleting the sentence. What IconText is written from stays in the lookup text. When the codemod does it is the skill's to say, and it says it in full.
2. Covered in fdc7366: a .icon tile inside an .icon-text converts with its legacy:tile TODO kept and tile in its props, which reaches that branch.
3. Leaving both under-reaches as they are. Each keeps the markup rather than converting it wrong, and the skill's recipe already says that anything between the children keeps it markup.

[github-actions]

Preview Deployment

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

[github-actions]

📸 Story screenshots at handoff — fdc7366

No Storybook stories map to this PR's changed files — nothing to screenshot. (workflow run)

[github-actions]

Preview Deployment

Preview URL: https://75709c73.bestax.pages.dev

[bestax-release-bot]

🎉 This PR is included in version 2.23.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 5.18.1 🎉

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.13.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 4.2.13 🎉

The release is available on:

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

Your semantic-release bot 📦🚀