create-bestax 4.2.3 → 4.2.5

package/dist/constants.js

@@ -182,7 +182,7 @@ automatically when the task matches:
 - **bestax-layout-scaffold** — scaffold full pages (app shell, landing, centered, card grid).
 - **bestax-icons** — icons via \`Icon\`/\`IconText\`: library setup, name formats, variants, a11y.
 - **bestax-optimize** — shrink the built CSS: measure raw+gzip, then flavor switch or a modular Sass build.
-- **bestax-migrate** — migrate code off react-bulma-components (v4): run the codemod, resolve its TODOs.
+- **bestax-migrate** — migrate code off react-bulma-components (v4) or rbx (v2): run the codemod, resolve its TODOs.
 
 Prefer the library's components and these skills over hand-written Bulma markup or custom CSS.
 Read skill \`references/\` files with absolute paths — the shell's cwd is not stable between commands.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bestax",
-  "version": "4.2.3",
+  "version": "4.2.5",
   "description": "Create a new bestax-bulma project",
   "type": "module",
   "bin": {
@@ -42,10 +42,10 @@
   },
   "devDependencies": {
     "@jest/globals": "^30.0.0",
-    "@playwright/test": "^1.62.0",
+    "@playwright/test": "^1.62.1",
     "@types/fs-extra": "^11.0.4",
     "@types/jest": "^30.0.0",
-    "@types/node": "^26.1.2",
+    "@types/node": "^26.3.0",
     "@types/prompts": "^2.4.9",
     "@types/wait-on": "^5.3.4",
     "jest": "^30.2.0",

package/templates/skills/bestax-custom-component/references/component-catalog.md

@@ -69,7 +69,7 @@ component is guaranteed to appear (the generator fails if one lacks an API page)
 - [SubTitle](https://bestax.io/docs/api/elements/subtitle) — The `SubTitle` component renders a Bulma-styled subtitle (secondary heading), supporting sizes `1-6` and rendering as any heading or paragraph element (`h1-h6`…
 - [Table](https://bestax.io/docs/api/elements/table) — The `Table` component and its subcomponents provide a highly composable, Bulma-styled table system for React.
 - [Tag](https://bestax.io/docs/api/elements/tag) — The `Tag` component renders a Bulma-styled label or badge.
-- [Tags](https://bestax.io/docs/api/elements/tags) — The `Tags` component groups multiple `Tag` components together in a horizontal (or multiline) Bulma-styled container.
+- [Tags](https://bestax.io/docs/api/elements/tags) — The `Tags` component groups multiple `Tag` components together in a Bulma-styled container that wraps onto multiple lines by default.
 - [Title](https://bestax.io/docs/api/elements/title) — The `Title` component renders a Bulma-styled title (heading), supporting sizes `1`-`6`, spacing, and rendering as any heading or paragraph element (`h1`-`h6`…
 - [UnorderedList](https://bestax.io/docs/api/elements/unorderedlist) — The `UnorderedList` component renders a styled unordered list (`<ul>`) element with Bulma helper class integration.
 

package/templates/skills/bestax-icons/SKILL.md

@@ -59,6 +59,34 @@ don't rely on it.
 - `features` — extra library classes, string or array: `'fa-spin'`, `['fa-lg', 'fa-border']`.
 - Color via the helper props: `textColor="primary"`, `textColor="danger"`, etc.
 
+## Custom node (SVG, react-icons, FontAwesome React)
+
+`Icon` also accepts `children` instead of `name` — an inline SVG, a `react-icons` component, a
+Font Awesome React `<FontAwesomeIcon>`, … — rendered in place of a class-based glyph. `name`
+and `children` are mutually exclusive (the type rejects passing both, or neither). `size`,
+`textColor`, `bgColor`, `ariaLabel` and `containerClassName` behave identically; `library`,
+`variant`, `features` and `libraryFeatures` are ignored since there's no class-based glyph to
+style.
+
+```tsx
+<Icon ariaLabel="Custom icon">
+  <MyReactIconsComponent />
+</Icon>
+```
+
+`IconText`'s `iconProps` / `items[].iconProps` and `Control`'s `iconLeft`/`iconRight` accept
+the same escape hatch — pass a node directly (instead of an `IconProps` object) and it is
+wrapped in an `Icon` for you: `<IconText iconProps={<MySvg />}>Starred</IconText>`.
+
+`Panel.Icon` takes the same `children`, but its container is `panel-icon` rather than `icon` —
+it always overrides `containerClassName`, so style and query that class instead.
+
+⚠️ **`children` excludes `undefined`.** Write a conditional icon as `cond ? <MySvg /> : null`
+(or `cond && <MySvg />`), never `cond ? <MySvg /> : undefined` — the latter is a type error,
+because the renderer would fall through to the `name` path with no name. In the `IconText` and
+`Control` slots a falsy node counts as "no icon": nothing is rendered, and `Control` falls back
+to `iconLeftName`/`iconRightName` if one is given, otherwise leaving the icon column unreserved.
+
 ## Accessibility
 
 Every `Icon` renders `aria-label` (default `"icon"`), set via its camelCase `ariaLabel` prop.

package/templates/skills/bestax-migrate/SKILL.md

@@ -1,15 +1,30 @@
 ---
 name: bestax-migrate
-description: Migrate an existing app from react-bulma-components (v4) to @allxsmith/bestax-bulma on Bulma v1 — run the bestax-migrate codemod, then resolve every TODO(bestax-migrate) comment it leaves using the mapping references. Use when a repo imports react-bulma-components and wants to move to bestax-bulma, when TODO(bestax-migrate) comments are present in a codebase, or when asked to migrate off an unmaintained React Bulma library.
+description: Migrate an existing app from an unmaintained React Bulma library — react-bulma-components (v4) or rbx (v2) — to @allxsmith/bestax-bulma on Bulma v1. Run the bestax-migrate codemod, then resolve every TODO(bestax-migrate) comment it leaves using the per-source mapping references. Use when a repo imports react-bulma-components or rbx and wants to move to bestax-bulma, when TODO(bestax-migrate) comments are present in a codebase, or when asked to migrate off an unmaintained React Bulma library.
 license: MIT
 ---
 
-# Migrating from react-bulma-components to bestax-bulma
+# Migrating to bestax-bulma
 
-`react-bulma-components` is unmaintained (last release 2022, Bulma 0.9.x).
 `@allxsmith/bestax-bulma` is an actively maintained React library for **Bulma v1**. The
-`bestax-migrate` codemod automates most of the conversion; this skill drives the codemod and
-finishes what it flags.
+`bestax-migrate` codemod automates most of the conversion from an unmaintained predecessor;
+this skill drives the codemod and finishes what it flags.
+
+## Pick the source
+
+The codemod's first argument names the library you are migrating _from_. Check the app's
+`package.json` and imports:
+
+| Source                                                               | Argument                 | References                                                                                 |
+| -------------------------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------ |
+| `react-bulma-components` v4 (unmaintained since 2022, Bulma 0.9.x)   | `react-bulma-components` | [`references/react-bulma-components/`](references/react-bulma-components/component-map.md) |
+| `rbx` v2 (abandoned 2019, pins Bulma **0.7.5** plus four extensions) | `rbx`                    | [`references/rbx/`](references/rbx/component-map.md)                                       |
+
+Everything below is written as `<source>`; substitute the argument from that table. The
+reference paths follow the same split — `references/<source>/component-map.md`,
+`prop-map.md`, `unmappables.md` — while
+[`references/css-migration.md`](references/css-migration.md) is shared, because the stylesheet
+work is about Bulma, not about which wrapper you came from.
 
 ## Workflow
 
@@ -18,15 +33,14 @@ Run these steps in order. Don't hand-convert what the codemod converts automatic
 1. **Dry-run the codemod** on the source directory and review the report:
 
    ```sh
-   pnpm dlx bestax-migrate react-bulma-components src/ --dry
+   pnpm dlx bestax-migrate <source> src/ --dry
    ```
 
 2. **Apply it** (same command without `--dry`), then run the project's formatter — the
    codemod preserves surrounding formatting but doesn't prettify what it rewrites.
    Besides the components, it also migrates **stylesheets** (CSS imports →
    `@allxsmith/bestax-bulma/bestax.css`; SCSS `@import 'bulma/bulma'` + `$var` overrides
-   → `@use 'bulma/sass' with (…)` plus the bestax extras) and **package.json**
-   (react-bulma-components removed, bestax-bulma added, bulma → ^1, node-sass → sass).
+   → `@use 'bulma/sass' with (…)` plus the bestax extras) and **package.json**.
    Flags: `--css bulma|keep` for other stylesheet targets, `--no-deps` to leave
    package.json alone.
 
@@ -36,16 +50,25 @@ Run these steps in order. Don't hand-convert what the codemod converts automatic
    npm install   # or pnpm/yarn
    ```
 
+   The report groups its entries by rule. `deps` covers every package.json edit —
+   what was removed, added, or left for you to decide; `imports` covers a source
+   import the codemod could not rewrite and left in place; `unsupported-file` names
+   a file type it cannot parse (`.vue`, `.astro`) that still imports the source;
+   `value-reference` marks a component used as a value rather than as JSX. Rules
+   named `component:X` and `prop:y` are per-component and per-prop, and each is
+   documented in the per-source `references/` pages.
+
    The report's `peer-deps` entries predict install failures: bestax-bulma needs
-   **React 18/19** (RBC also ran on 17 — upgrade react/react-dom first) and its optional
-   Font Awesome peer wants **FA ≥ 6.7** (an app pinned to FA 5 either upgrades or
-   installs with `npm install --legacy-peer-deps`).
+   **React 18/19** (react-bulma-components also ran on 17, and rbx peer-depended on
+   **React 16** — upgrade react/react-dom first) and its optional Font Awesome peer wants
+   **FA ≥ 6.7** (an app pinned to FA 5 either upgrades or installs with
+   `npm install --legacy-peer-deps`).
 
 4. **Resolve every TODO**: `grep -rn "TODO(bestax-migrate)" src/`. Each comment names the
    prop/component and a hint. Recipes for every recurring case are in
-   [references/unmappables.md](references/unmappables.md); the full component and prop
-   tables are in [references/component-map.md](references/component-map.md) and
-   [references/prop-map.md](references/prop-map.md). Delete each comment as you resolve it.
+   `references/<source>/unmappables.md`; the full tables are in
+   `references/<source>/component-map.md` and `references/<source>/prop-map.md`. Delete each
+   comment as you resolve it.
 
 5. **Finish the stylesheet layer** — flagged Sass cases (computed variables,
    indented-syntax `.sass` files), CSS flavor choice, and Bulma 0.9→1 styling changes:
@@ -56,23 +79,34 @@ Run these steps in order. Don't hand-convert what the codemod converts automatic
 
 ## What the codemod handles vs. flags
 
-All 32 react-bulma-components v4 components have a mapping. Imports (named, namespace, and
-`const { Input } = Form` destructuring), component renames, prop renames/value conversions,
-responsive breakpoint objects, CSS/SCSS stylesheet imports, and package.json dependencies
-convert automatically. It flags with
-`TODO(bestax-migrate)` instead of guessing: `Element` and `Tile` (no bestax equivalent —
-Tile is replaced by Bulma v1's Grid), controlled `Dropdown`/`Dropdown.Item value`,
-`touch`/`until*` breakpoints, dynamic prop values it can't rewrite, and props with no
-bestax counterpart. Files in formats it can't parse (`.astro`, `.vue`, `.svelte`, `.mdx`)
-that import react-bulma-components are reported as `unsupported-file` — migrate those by
-hand with the component map. Never "fix" a TODO by silencing it — convert the code per the
-references, or deliberately keep the old markup with `className` styling.
+Every export of every supported source has a mapping entry, held to that library's real export
+surface by a coverage test. Imports (named, namespace, and destructuring), component renames,
+prop renames and value conversions, breakpoint objects, CSS/SCSS stylesheet imports, and
+package.json dependencies convert automatically.
+
+It flags with `TODO(bestax-migrate)` instead of guessing: components with no bestax equivalent,
+controlled APIs whose shape differs, breakpoints bestax has no prop for, dynamic prop values it
+can't rewrite, and props with no counterpart. Files in formats it can't parse (`.astro`,
+`.vue`, `.svelte`, `.mdx`) that import the source library are reported as `unsupported-file` —
+migrate those by hand with the component map. Never "fix" a TODO by silencing it — convert the
+code per the references, or deliberately keep the old markup with `className` styling.
+
+### Source-specific headlines
+
+- **react-bulma-components**: all 32 v4 components are mapped. `Element` and `Tile` have no
+  bestax equivalent; `renderAs` becomes `as` where supported.
+- **rbx**: migrating removes rbx itself — it pinned `bulma@0.7.5` as a direct
+  dependency plus `bulma-badge`, `bulma-divider`, `bulma-pageloader` and `bulma-tooltip`, so
+  the app can finally choose its own Bulma version. rbx's badge and tooltip _helper props_
+  become real wrapping `<Badge>` / `<Tooltip>` components. Its `as` is universal, bestax's is
+  not. Because rbx pinned Bulma 0.7.5, you cross **two** Bulma majors — expect more visual
+  drift than the 0.9 → 1 guide alone describes.
 
 ## Rules
 
-- The codemod is idempotent on already-migrated files (it only touches files importing
-  `react-bulma-components`) — safe to re-run after partial manual work.
-- Don't downgrade converted props back to RBC names; bestax uses `is*` booleans
-  (`isLoading`), string size unions (`textSize="4"`), and `as` instead of `renderAs`.
-- If a component the app uses isn't in the component map, it wasn't part of RBC v4 —
-  check for a local wrapper component and migrate its internals instead.
+- The codemod is idempotent on already-migrated files (it only touches files importing the
+  source library) — safe to re-run after partial manual work.
+- Don't downgrade converted props back to the old names; bestax uses `is*` booleans
+  (`isLoading`), string size unions (`textSize="4"`), and `as` rather than `renderAs`.
+- If a component the app uses isn't in the component map, it wasn't part of that library's
+  public API — check for a local wrapper component and migrate its internals instead.

package/templates/skills/bestax-migrate/references/css-migration.md

@@ -1,13 +1,17 @@
-# Stylesheets: Bulma 0.9 → Bulma v1 + bestax
+# Stylesheets: pre-1 Bulma → Bulma v1 + bestax
 
-react-bulma-components apps style with Bulma 0.9.x; bestax-bulma targets Bulma v1. The
-codemod automates most of this layer — this reference explains what it did and how to
-finish what it flagged.
+Every library `bestax-migrate` migrates from is pinned to a pre-1 Bulma: react-bulma-components
+to 0.9.x, rbx to 0.7.5. bestax-bulma targets Bulma v1. The codemod automates most of that
+stylesheet layer; this reference explains what it did and how to finish what it flagged.
+
+Coming from rbx you are crossing **two** Bulma majors rather than one, so expect more visual
+drift than the 0.9 → 1 notes below describe on their own.
 
 ## What the codemod already did (default `--css bestax`)
 
 - **CSS imports**: `bulma/css/bulma(.min).css` and v3-era
-  `react-bulma-components/dist/*.css` imports became the recommended combined bundle
+  the source library's own CSS imports (`react-bulma-components/dist/*.css`,
+  `rbx/index.css`) became the recommended combined bundle
   `@allxsmith/bestax-bulma/bestax.css` (Bulma v1 + the bestax extras that themed
   Radio/Checkbox and the advanced form controls need). A separate `extras.css` import
   next to it is collapsed.
@@ -43,9 +47,9 @@ finish what it flagged.
   **dart-sass ≥ 1.79** — the codemod's node-sass replacement installs that, but check
   bundler-pinned older versions (Parcel's sass transformer pins 1.66).
 
-  react-bulma-components' own stylesheet — any `react-bulma-components/…` specifier,
+  the source library's own stylesheet — any `react-bulma-components/…` or `rbx/…` specifier,
   bare, `~`-prefixed, or a relative `node_modules/` path, covering the documented v3
-  entry points (`src/index.sass`, `dist/react-bulma-components(.min).css`) as well as
+  entry points (`src/index.sass`, `dist/react-bulma-components(.min).css`, `rbx/rbx`) as well as
   deep partials and extensionless forms — is not a third-party extension; it's the
   library being migrated away from. It targets Bulma 0.9, not the v1 your components now
   use, and (unless `--no-deps` is passed) `package.json` no longer lists it, so the
@@ -68,8 +72,11 @@ finish what it flagged.
   given partial's styles, so it gets a `// TODO(bestax-migrate)` and a report entry
   ("port any styles it carried beyond Bulma's own by hand") rather than vanishing silently.
 
-- **package.json**: `react-bulma-components` removed, `@allxsmith/bestax-bulma` added,
-  `bulma` bumped to `^1.0.4` (or added when sources still import `bulma/…` directly),
+- **package.json**: the source library removed, `@allxsmith/bestax-bulma` added, a declared
+  pre-1.0 `bulma` raised to `^1.0.4` (or `bulma` added when sources still import `bulma/…`
+  directly). For rbx, the four `bulma-*` extensions it pinned are **reported** for you to
+  remove, not deleted — a manifest entry is a deliberate declaration, and the same goes for
+  their CSS imports in source files (kept, with a TODO each),
   and dead `node-sass` replaced with dart `sass`. Run the package manager's install
   afterwards — the codemod never installs anything.
 
@@ -93,7 +100,7 @@ elements,form,components,grid,layout,helpers,themes}` with leaf partials like
   compatibility. Class-based usage (`className="is-checkradio"`) keeps needing the
   extension; usage that migrated to bestax components (Radio, Checkbox, the advanced
   form controls) is already styled by the bestax extras, so the import can go.
-  react-bulma-components' own stylesheet is never flagged this way (see above) — only
+  the source library's own stylesheet is never flagged this way (see above) — only
   packages actually named `bulma-*` are.
 
 ## Choosing a CSS flavor (optional)

package/templates/skills/bestax-migrate/references/rbx/component-map.md

@@ -0,0 +1,171 @@
+# rbx → bestax-bulma component map
+
+Every rbx v2 export and its dot-notation compounds. `structural` means the codemod rewrites the
+element's shape rather than renaming it (see [unmappables.md](unmappables.md) for what each one
+produces). A `todo` row has no bestax counterpart — the codemod keeps the rbx import, annotated,
+so the app still runs while you convert it.
+
+This table mirrors `MAPPING` in `bestax-migrate/src/sources/rbx/mapping.ts`, which a coverage
+test holds to rbx's own export surface in both directions.
+
+| rbx                        | bestax-bulma          | status  |
+| -------------------------- | --------------------- | ------- |
+| `Block`                    | `Block`               | mapped  |
+| `Box`                      | `Box`                 | mapped  |
+| `Breadcrumb`               | `Breadcrumb`          | mapped  |
+| `Breadcrumb.Item`          | _structural_          | mapped  |
+| `Button`                   | `Button`              | mapped  |
+| `Button.Group`             | `Buttons`             | mapped  |
+| `Card`                     | `Card`                | mapped  |
+| `Card.Content`             | `Card.Content`        | mapped  |
+| `Card.Image`               | `Card.Image`          | mapped  |
+| `Card.Header`              | `Card.Header`         | mapped  |
+| `Card.Header.Title`        | `Card.Header.Title`   | mapped  |
+| `Card.Header.Icon`         | `Card.Header.Icon`    | mapped  |
+| `Card.Footer`              | `Card.Footer`         | mapped  |
+| `Card.Footer.Item`         | `Card.FooterItem`     | mapped  |
+| `Checkbox`                 | `Checkbox`            | mapped  |
+| `Column`                   | `Column`              | mapped  |
+| `Column.Group`             | `Columns`             | mapped  |
+| `Container`                | `Container`           | mapped  |
+| `Content`                  | `Content`             | mapped  |
+| `Content.OrderedList`      | `OrderedList`         | mapped  |
+| `Content.OrderedList.Item` | `OrderedList.Item`    | mapped  |
+| `Control`                  | `Control`             | mapped  |
+| `Delete`                   | `Delete`              | mapped  |
+| `Divider`                  | `Divider`             | partial |
+| `Dropdown`                 | `Dropdown`            | partial |
+| `Dropdown.Container`       | _structural_          | mapped  |
+| `Dropdown.Content`         | _structural_          | mapped  |
+| `Dropdown.Menu`            | _structural_          | mapped  |
+| `Dropdown.Trigger`         | _structural_          | mapped  |
+| `Dropdown.Item`            | `Dropdown.Item`       | mapped  |
+| `Dropdown.Divider`         | `Dropdown.Divider`    | mapped  |
+| `Dropdown.Context`         | — _(see unmappables)_ | todo    |
+| `Field`                    | `Field`               | mapped  |
+| `Field.Label`              | `Field.Label`         | mapped  |
+| `Field.Body`               | `Field.Body`          | mapped  |
+| `Fieldset`                 | — _(see unmappables)_ | todo    |
+| `File`                     | `File`                | mapped  |
+| `File.CTA`                 | — _(see unmappables)_ | todo    |
+| `File.Icon`                | — _(see unmappables)_ | todo    |
+| `File.Input`               | — _(see unmappables)_ | todo    |
+| `File.Label`               | — _(see unmappables)_ | todo    |
+| `File.Name`                | — _(see unmappables)_ | todo    |
+| `Footer`                   | `Footer`              | mapped  |
+| `Generic`                  | — _(see unmappables)_ | todo    |
+| `Heading`                  | _structural_          | mapped  |
+| `Help`                     | _structural_          | mapped  |
+| `Hero`                     | `Hero`                | mapped  |
+| `Hero.Body`                | `Hero.Body`           | mapped  |
+| `Hero.Foot`                | `Hero.Foot`           | mapped  |
+| `Hero.Head`                | `Hero.Head`           | mapped  |
+| `Highlight`                | — _(see unmappables)_ | todo    |
+| `Icon`                     | `Icon`                | partial |
+| `Image`                    | `Image`               | mapped  |
+| `Image.Container`          | _structural_          | mapped  |
+| `Input`                    | `Input`               | mapped  |
+| `Label`                    | _structural_          | mapped  |
+| `Level`                    | `Level`               | mapped  |
+| `Level.Item`               | _structural_          | mapped  |
+| `List`                     | — _(see unmappables)_ | todo    |
+| `List.Item`                | — _(see unmappables)_ | todo    |
+| `Loader`                   | _structural_          | mapped  |
+| `Media`                    | `Media`               | mapped  |
+| `Media.Item`               | _structural_          | mapped  |
+| `Menu`                     | `Menu`                | mapped  |
+| `Menu.Label`               | `Menu.Label`          | mapped  |
+| `Menu.List`                | `Menu.List`           | mapped  |
+| `Menu.List.Item`           | `Menu.Item`           | mapped  |
+| `Message`                  | `Message`             | mapped  |
+| `Message.Body`             | `Message.Body`        | mapped  |
+| `Message.Header`           | `Message.Header`      | mapped  |
+| `Modal`                    | `Modal`               | partial |
+| `Modal.Background`         | `Modal.Background`    | mapped  |
+| `Modal.Close`              | `Modal.Close`         | mapped  |
+| `Modal.Content`            | `Modal.Content`       | mapped  |
+| `Modal.Container`          | _structural_          | mapped  |
+| `Modal.Card`               | `Modal.Card`          | mapped  |
+| `Modal.Card.Body`          | `Modal.Card.Body`     | mapped  |
+| `Modal.Card.Foot`          | `Modal.Card.Foot`     | mapped  |
+| `Modal.Card.Head`          | `Modal.Card.Head`     | mapped  |
+| `Modal.Card.Title`         | `Modal.Card.Title`    | mapped  |
+| `Modal.Context`            | — _(see unmappables)_ | todo    |
+| `Modal.Portal`             | — _(see unmappables)_ | todo    |
+| `Navbar`                   | `Navbar`              | mapped  |
+| `Navbar.Brand`             | `Navbar.Brand`        | mapped  |
+| `Navbar.Burger`            | `Navbar.Burger`       | mapped  |
+| `Navbar.Divider`           | `Navbar.Divider`      | mapped  |
+| `Navbar.Menu`              | `Navbar.Menu`         | mapped  |
+| `Navbar.Link`              | `Navbar.Link`         | mapped  |
+| `Navbar.Item`              | _structural_          | mapped  |
+| `Navbar.Item.Container`    | _structural_          | mapped  |
+| `Navbar.Dropdown`          | _structural_          | mapped  |
+| `Navbar.Segment`           | _structural_          | mapped  |
+| `Navbar.Container`         | _structural_          | mapped  |
+| `Navbar.Context`           | — _(see unmappables)_ | todo    |
+| `Notification`             | `Notification`        | mapped  |
+| `Numeric`                  | — _(see unmappables)_ | todo    |
+| `PageLoader`               | `Loading`             | mapped  |
+| `Pagination`               | `Pagination`          | mapped  |
+| `Pagination.Link`          | `Pagination.Link`     | mapped  |
+| `Pagination.List`          | `Pagination.List`     | mapped  |
+| `Pagination.Ellipsis`      | `Pagination.Ellipsis` | mapped  |
+| `Pagination.Step`          | _structural_          | mapped  |
+| `Panel`                    | `Panel`               | mapped  |
+| `Panel.Heading`            | `Panel.Heading`       | mapped  |
+| `Panel.Block`              | `Panel.Block`         | mapped  |
+| `Panel.Icon`               | `Panel.Icon`          | partial |
+| `Panel.Tab`                | _structural_          | mapped  |
+| `Panel.Tab.Group`          | `Panel.Tabs`          | mapped  |
+| `Progress`                 | `Progress`            | mapped  |
+| `Radio`                    | `Radio`               | mapped  |
+| `Section`                  | `Section`             | mapped  |
+| `Select`                   | `Select`              | mapped  |
+| `Select.Container`         | _structural_          | mapped  |
+| `Select.Option`            | _structural_          | mapped  |
+| `Tab`                      | `Tabs.Item`           | mapped  |
+| `Tab.Group`                | `Tabs`                | mapped  |
+| `Table`                    | `Table`               | mapped  |
+| `Table.Body`               | `Table.Tbody`         | mapped  |
+| `Table.Cell`               | `Table.Td`            | mapped  |
+| `Table.Foot`               | `Table.Tfoot`         | mapped  |
+| `Table.Head`               | `Table.Thead`         | mapped  |
+| `Table.Heading`            | `Table.Th`            | mapped  |
+| `Table.Row`                | `Table.Tr`            | mapped  |
+| `Tag`                      | `Tag`                 | mapped  |
+| `Tag.Group`                | `Tags`                | mapped  |
+| `Textarea`                 | `TextArea`            | mapped  |
+| `Tile`                     | — _(see unmappables)_ | todo    |
+| `Title`                    | _structural_          | mapped  |
+| `forwardRefAs`             | — _(see unmappables)_ | todo    |
+
+## The renames worth memorising
+
+| rbx                                | bestax-bulma                                                                                               |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `Tag.Group`                        | `Tags`                                                                                                     |
+| `Button.Group`                     | `Buttons`                                                                                                  |
+| `Column.Group`                     | `Columns`                                                                                                  |
+| `Card.Footer.Item`                 | `Card.FooterItem`                                                                                          |
+| `Table.Head` / `.Body` / `.Foot`   | `Table.Thead` / `.Tbody` / `.Tfoot`                                                                        |
+| `Table.Row` / `.Cell` / `.Heading` | `Table.Tr` / `.Td` / `.Th`                                                                                 |
+| `Textarea`                         | `TextArea`                                                                                                 |
+| `PageLoader`                       | `Loading` with `isFullPage`                                                                                |
+| `Loader`                           | a plain `<div className="loader">` — bestax's `Loading` is an overlay that renders nothing unless `active` |
+| `Menu.List.Item`                   | `Menu.Item`                                                                                                |
+| `Tab` / `Tab.Group`                | `Tabs.Item` / `Tabs`                                                                                       |
+| `Panel.Tab.Group`                  | `Panel.Tabs`                                                                                               |
+| `Title subtitle`                   | `SubTitle`                                                                                                 |
+
+## Value-chosen targets
+
+These pick a bestax component from a literal prop value; a dynamic value gets a TODO instead.
+
+| rbx               | value                                    | bestax-bulma                                   |
+| ----------------- | ---------------------------------------- | ---------------------------------------------- |
+| `Level.Item`      | `align="left"` / `"right"`               | `Level.Left` / `Level.Right`                   |
+| `Media.Item`      | `align="left"` / `"content"` / `"right"` | `Media.Left` / `Media.Content` / `Media.Right` |
+| `Navbar.Segment`  | `align="start"` / `"end"`                | `Navbar.Start` / `Navbar.End`                  |
+| `Pagination.Step` | `align="previous"` / `"next"`            | `Pagination.Previous` / `Pagination.Next`      |
+| `Navbar.Item`     | `dropdown`                               | `Navbar.Dropdown`                              |

package/templates/skills/bestax-migrate/references/rbx/prop-map.md

@@ -0,0 +1,116 @@
+# rbx → bestax-bulma prop map
+
+rbx and bestax both target Bulma, so most helper _values_ are already identical — the shapes
+differ, not the vocabulary. What follows is only what actually changes.
+
+## Universal helper props
+
+rbx mixes these into every component via `HelpersProps`.
+
+| rbx                               | bestax-bulma                 | note                                                       |
+| --------------------------------- | ---------------------------- | ---------------------------------------------------------- |
+| `backgroundColor`                 | `bgColor`                    | rename only                                                |
+| `textColor`                       | `textColor`                  | unchanged                                                  |
+| `textAlign`                       | `textAlign`                  | unchanged — both use `centered`/`justified`/`left`/`right` |
+| `textWeight`                      | `textWeight`                 | unchanged                                                  |
+| `textTransform`                   | `textTransform`              | unchanged                                                  |
+| `textSize={4}`                    | `textSize="4"`               | number → string                                            |
+| `italic`                          | `textTransform="italic"`     |                                                            |
+| `pull="left"`                     | `float="left"`               |                                                            |
+| `clearfix`, `overlay`, `relative` | same                         | unchanged booleans                                         |
+| `clipped`                         | `overflow="clipped"`         |                                                            |
+| `hidden`                          | `visibility="hidden"`        |                                                            |
+| `invisible`                       | `visibility="invisible"`     |                                                            |
+| `srOnly`                          | `visibility="sr-only"`       |                                                            |
+| `marginless`                      | `m="0"`                      | Bulma v1 removed `is-marginless`                           |
+| `paddingless`                     | `p="0"`                      | Bulma v1 removed `is-paddingless`                          |
+| `radiusless`                      | `radius="radiusless"`        |                                                            |
+| `shadowless`                      | `shadow="shadowless"`        |                                                            |
+| `unselectable`                    | `interaction="unselectable"` |                                                            |
+
+Two rbx colour names have no bestax equivalent: **`white-ter`** and **`white-bis`**. Everything
+else in rbx's `colors` and `shades` unions exists in bestax verbatim.
+
+## Bare boolean modifiers → `is*`
+
+`outlined` → `isOutlined`, `rounded` → `isRounded`, `inverted` → `isInverted`,
+`fullwidth` → `isFullwidth`, `static` → `isStatic`, `narrow` → `isNarrow`,
+`bordered`/`striped`/`hoverable` on `Table` → `isBordered`/`isStriped`/`isHoverable`,
+`delete` on `Tag` → `isDelete`.
+
+## State props → booleans
+
+| rbx                                                 | bestax-bulma                           |
+| --------------------------------------------------- | -------------------------------------- |
+| `Button state="loading"`                            | `isLoading`                            |
+| `Button state="hovered"` / `"focused"` / `"active"` | `isHovered` / `isFocused` / `isActive` |
+| `Input state="focused"` / `"hovered"`               | `isFocused` / `isHovered`              |
+| `Select.Container state="loading"`                  | `isLoading`                            |
+
+## Form grouping
+
+bestax folds rbx's `kind` + `multiline` + `align` into two value-taking props.
+
+| rbx                                     | bestax-bulma                                                                                                            |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `Field kind="addons"`                   | `hasAddons`                                                                                                             |
+| `Field kind="group"`                    | `grouped`                                                                                                               |
+| `Field multiline` (with `kind="group"`) | `grouped="multiline"`                                                                                                   |
+| `Field align="centered"`                | ambiguous — TODO; set `grouped`/`hasAddons` to `"centered"` by hand                                                     |
+| `Control expanded` / `loading`          | `isExpanded` / `isLoading`                                                                                              |
+| `Control iconLeft` / `iconRight`        | `hasIconsLeft` / `hasIconsRight` — note bestax's own `iconLeft` takes an `IconProps` object, which is a different thing |
+| `Textarea fixedSize`                    | `hasFixedSize`                                                                                                          |
+
+## Breakpoint objects
+
+rbx has three shapes; all three flatten to bestax's per-viewport props.
+
+```jsx
+// 1. the universal `responsive` helper prop
+<Box responsive={{ tablet: { display: { value: "flex" }, textSize: { value: 5 } } }} />
+<Box displayTablet="flex" textSizeTablet="5" />
+
+// 2. Column sizing
+<Column tablet={{ size: 6, narrow: true }} />
+<Column sizeTablet={6} isNarrowTablet />
+
+// 3. Column.Group gaps
+<Column.Group tablet={{ gapSize: 2 }} />
+<Columns gapTablet={2} />
+```
+
+`hide: { value: true }` becomes `visibility<Viewport>="hidden"`. The **`touch`** breakpoint and
+`{ only: true }` have no bestax props — both are TODOs.
+
+## `as`
+
+rbx's `forwardRefAs` puts `as` on **every** component. bestax declares it on a smaller set, and
+several of those narrow it to specific tags (`Footer` is `'footer' | 'div'`, `Control` is
+`'div'`). The codemod passes `as` through only where bestax really accepts it, and TODOs it
+everywhere else:
+
+| bestax component             | `as` accepts               |
+| ---------------------------- | -------------------------- |
+| `Button`                     | any element type           |
+| `Title`, `SubTitle`          | `h1`–`h6`, `p`             |
+| `Image`                      | `'figure' \| 'div' \| 'p'` |
+| `Footer`                     | `'footer' \| 'div'`        |
+| `Media`                      | `'article' \| 'div'`       |
+| `Media.Left`                 | `'figure' \| 'div'`        |
+| `Level.Item`                 | `'div' \| 'p' \| 'a'`      |
+| `Control`                    | `'div'`                    |
+| `Menu.Item`                  | any element type           |
+| `Dropdown.Item`              | `'a' \| 'div' \| 'button'` |
+| `Navbar.Item`, `Navbar.Link` | any element type           |
+
+Three traps worth naming, because rbx supplies `as` universally and the obvious guesses are
+wrong:
+
+- The **`Dropdown` and `Navbar` roots do not take `as`** — only their `.Item` / `.Link`
+  sub-components do.
+- **`Media.Item` depends on its `align`.** It resolves to `Media.Left`, `Media.Content` or
+  `Media.Right`, and only `Media.Left` declares `as`; the codemod drops it with a TODO on the
+  other two.
+- Several of the accepted props are **narrow literal unions**, so `as={SomeComponent}` still
+  fails to typecheck even where `as` is allowed — which is deliberate: a visible type error
+  beats a silent rewrite.

package/templates/skills/bestax-migrate/references/rbx/unmappables.md

@@ -0,0 +1,169 @@
+# Recipes for every TODO(bestax-migrate) the rbx codemod leaves
+
+Ordered by how often they appear when the codemod runs over rbx's own documentation examples.
+Resolve the comment, then delete it. Never silence a TODO without converting the code.
+
+## `component:Icon` — the icon child
+
+bestax's `Icon` takes a **required `name`** instead of an icon child, and rbx's docs teach the
+FontAwesome component form, which carries no readable name.
+
+```jsx
+<Icon size="small"><FontAwesomeIcon icon={faHome} /></Icon>
+<Icon name="home" library="fa" variant="solid" size="small" />
+```
+
+`library` is `fa` | `mdi` | `ion` | `material-icons` | `material-symbols`; `variant` is the style
+(`solid`, `regular`, `brands`, …). Icon-font children the parser _can_ read
+(`<i className="fas fa-home" />`) are converted automatically.
+
+## `component:Tile` — Bulma v1 removed tiles
+
+Use Grid and Cell. `Tile kind="ancestor"` becomes `<Grid>`, `kind="parent"`/`kind="child"`
+become `<Cell>`, and `size={n}` becomes a column span.
+
+```jsx
+<Tile kind="ancestor"><Tile kind="parent" size={4}><Tile kind="child">x</Tile></Tile></Tile>
+<Grid><Cell colSpan={4}>x</Cell></Grid>
+```
+
+## `component:File.*` — the file-input parts
+
+bestax's `<File>` renders the whole Bulma structure itself, so `File.Label`, `File.Input`,
+`File.CTA`, `File.Icon` and `File.Name` have nothing to become.
+
+```jsx
+<File hasName>
+  <File.Label>
+    <File.Input name="upload" />
+    <File.CTA><File.Label>Choose…</File.Label></File.CTA>
+    <File.Name>none</File.Name>
+  </File.Label>
+</File>
+
+<File name="upload" label="Choose…" hasName />
+```
+
+## `prop:as` — polymorphism
+
+rbx puts `as` on everything; bestax does not. Either render the tag directly, or restructure.
+See the `as` section of [prop-map.md](prop-map.md) for the components that do accept it.
+
+## `component:Generic` — rbx's base element
+
+`Generic` is rbx's untyped passthrough. Render the underlying tag, and move its helper props to
+the nearest bestax component (or a `className`).
+
+## `component:Dropdown` and its parts
+
+bestax's `Dropdown` takes a `label` and renders its own trigger and menu, so rbx's four-element
+structure collapses to one.
+
+```jsx
+<Dropdown>
+  <Dropdown.Trigger>Open</Dropdown.Trigger>
+  <Dropdown.Menu><Dropdown.Content>
+    <Dropdown.Item active>one</Dropdown.Item>
+  </Dropdown.Content></Dropdown.Menu>
+</Dropdown>
+
+<Dropdown label="Open">
+  <Dropdown.Item active>one</Dropdown.Item>
+</Dropdown>
+```
+
+## `Navbar.Item dropdown` — open/close state is not carried over
+
+The structural rewrite is automatic (`<Navbar.Item dropdown>` becomes
+`<Navbar.Dropdown>`, and rbx's `<Navbar.Dropdown>` becomes `<Navbar.DropdownMenu>`), but the
+**behaviour is not the same**. rbx's dropdown owns its own click and outside-click state; bestax's
+`Navbar.Dropdown` is presentational and opens from `hoverable` or a controlled `active`.
+
+So a migrated dropdown renders correctly and does nothing on click. Pick one:
+
+```jsx
+<Navbar.Dropdown hoverable>…</Navbar.Dropdown>          // opens on hover
+<Navbar.Dropdown active={open}>…</Navbar.Dropdown>      // you own the state
+```
+
+Nothing flags this — the markup is valid either way — so audit your navbars after migrating.
+
+## `component:List` — the bulma-list extension
+
+Bulma v1 does not ship it. Use `<UnorderedList>`/`<UnorderedList.Item>` for a plain list, or
+`<Menu>`/`<Menu.Item>` when the items are navigation.
+
+## `component:Fieldset`, `component:Numeric`, `component:Highlight`
+
+No bestax equivalents, and none needed: render a plain `<fieldset>` (its `disabled` attribute
+works natively), use `Intl.NumberFormat` directly, and use `<Pre>` with your own highlighter.
+
+## `responsive` — `touch` and `{ only: true }`
+
+bestax's viewports are `mobile`/`tablet`/`desktop`/`widescreen`/`fullhd`, with no `touch` and no
+`-only` variants. Reach for a `className` with the Bulma class, or restyle in CSS.
+
+The codemod always removes the whole `responsive` prop, even when part of it could not be
+converted — bestax has its own unrelated `responsive` prop (`'mobile' | 'narrow'`), so leaving a
+half-emptied rbx object behind would be a type error rather than a leftover. The TODO names
+which breakpoints did not carry.
+
+## Props with no counterpart
+
+| TODO                                               | What to do                                                                                                                                                                                                                                               |
+| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `prop:closeOnEsc` on `Modal`                       | bestax implements no Escape handling at all; add your own keydown listener, or drop the prop                                                                                                                                                             |
+| `prop:closeOnBlur` on `Modal`                      | the migrated compound form renders `Modal.Background` as you wrote it; wire its `onClick` to your `onClose`                                                                                                                                              |
+| `prop:selected`, `prop:text` on `Button`           | `className="is-selected"`; for `is-text` use `color="ghost"` or a link                                                                                                                                                                                   |
+| `prop:size` on `Button.Group` / `Tags` / `Message` | set `size` on each child instead                                                                                                                                                                                                                         |
+| `prop:gradient` on `Hero`                          | Bulma v1 removed `is-bold` gradients; use `bgColor` or a custom class                                                                                                                                                                                    |
+| `prop:color`, `prop:vertical` on `Divider`         | bestax's `Divider` takes only `bgColor` and renders an `<hr>`                                                                                                                                                                                            |
+| `component:Divider` (a labelled divider)           | rbx rendered `<Divider>OR</Divider>`'s children as a centred label via `data-content`; bestax's `Divider` is a bare `<hr>` and takes no children -- React rejects children on a void element at runtime. Put the label in surrounding markup, or drop it |
+| `prop:direction` on `PageLoader`                   | no directional variant; drop it or add a class                                                                                                                                                                                                           |
+| `prop:innerRef`                                    | the affected roots (`Dropdown`, `Modal`, `Navbar`) are plain function components and forward no ref — drop it, or put the ref on a wrapping element you control                                                                                          |
+| `prop:managed`                                     | bestax components are uncontrolled; drive the `Modal` with `active` and `onClose`                                                                                                                                                                        |
+| `prop:document` on `Modal`                         | bestax renders the Modal inline rather than portalling into any document — see [Modal behaviours bestax does not implement](#modal-behaviours-bestax-does-not-implement)                                                                                 |
+| `prop:document` on `Navbar`                        | bestax's `Navbar` has no `document` prop; drop it                                                                                                                                                                                                        |
+| `badgeOutlined`, `badgeRounded`, `badgeSize`       | bestax's `Badge` has no outline, pill or size variant                                                                                                                                                                                                    |
+| `tooltipResponsive`                                | bestax's `Tooltip` has one `position` for all viewports                                                                                                                                                                                                  |
+
+## Modal behaviours bestax does not implement
+
+`component:Modal` — emitted on **every** Modal the codemod converts, whether or not you passed
+any of the props above.
+
+rbx's Modal did three things by default that bestax's does not do at all:
+
+| rbx default                      | bestax                                              |
+| -------------------------------- | --------------------------------------------------- |
+| portals into `document.body`     | renders inline, exactly where you place it          |
+| closes on Escape                 | no keydown handling of any kind                     |
+| clips document scroll while open | no scroll locking; the page behind stays scrollable |
+
+The markup migrates cleanly, so nothing fails to compile and nothing looks wrong in a
+screenshot — which is why this one is flagged unconditionally rather than left to review. Re-add
+whichever your UI actually relied on:
+
+- **Portal** — wrap the render in `createPortal(…, document.body)` yourself. This matters most if
+  an ancestor has `overflow: hidden`, `filter`, or a `transform`, any of which will now clip or
+  re-parent the modal that used to escape them.
+- **Escape** — add a `keydown` listener while the modal is open and call your `onClose`.
+- **Scroll lock** — Bulma still ships `.is-clipped`; put it on `<html>` while the modal is open.
+
+Background click is the one that does carry over, but only because you write it: the migrated
+compound form renders your `Modal.Background`, so wire its `onClick` to the same `onClose`.
+
+## `prop:textColor="white-ter"` / `"white-bis"`
+
+The only two rbx colour names bestax does not carry. Use `white`, or a custom class.
+
+## `value-reference` — a component used as a value
+
+`const X = Card.Header;` and similar. The codemod rewrites what it can prove safe and flags the
+rest; convert the usage by hand.
+
+## Dynamic values
+
+Anything the codemod cannot read statically (`state={x}`, `align={side}`,
+`subtitle={isSub}`) is left in place with a TODO. Split the branch by hand — the codemod never
+guesses at a runtime value.