create-bestax 4.2.17 → 4.2.18

package/templates/skills/bestax-form/references/api.md

@@ -70,6 +70,9 @@ Field/Control/message props. `TextArea` adds `rows` and `hasFixedSize`.
 
 - `Checkbox` / `Radio` — single controls with `color`, `size`, `checked`/`defaultChecked`,
   `onChange`, `disabled`.
+- `Checkbox` also takes `indeterminate`, the mixed state of a "Select all" box over a partly
+  checked list. It changes the look and the announcement, not the value: `checked` stays the
+  value, so set both from the list.
 - `Checkboxes` — group wrapper managing an **array** value.
 - `Radios` — group wrapper managing a **single** selected value.
 

package/templates/skills/bestax-form/references/patterns.md

@@ -131,7 +131,7 @@ Notes:
 // Search box: input + button attached.
 <Field hasAddons>
   <Control isExpanded>
-    <InputBase placeholder="Search" />
+    <InputBase placeholder="Search" aria-label="Search" />
   </Control>
   <Control>
     <Button color="primary">Search</Button>
@@ -141,14 +141,18 @@ Notes:
 // Two controls on one row.
 <Field grouped>
   <Control>
-    <InputBase placeholder="First" />
+    <InputBase placeholder="First" aria-label="First name" />
   </Control>
   <Control>
-    <InputBase placeholder="Last" />
+    <InputBase placeholder="Last" aria-label="Last name" />
   </Control>
 </Field>
 ```
 
+A `grouped` or `hasAddons` Field names none of the controls it holds, and a placeholder
+disappears once the user types, so each input above carries an `aria-label`. For a visible
+label instead, see the last item below.
+
 Recipes built on addons, each written out in full in the docs:
 
 - **Password reveal** ([docs](https://bestax.io/docs/api/form/input#password-reveal)): the

package/templates/skills/bestax-layout-scaffold/SKILL.md

@@ -97,6 +97,21 @@ Centered; a collection of items → Card grid. For mixed requests, pick the domi
   "Clear search" put focus back in the field. While data loads show a `Skeleton` or a `Loader`,
   and a failed load is a `Message` or a `Notification`, never an EmptyState. The archetypes
   reference has the full pattern under Card grid.
+- **An order's history, a ticket's activity, a changelog or an activity feed is `Timeline`**,
+  not a hand-built list with a border down the side: `<Timeline titleAs="h3">` with a
+  `<Timeline.Item title="Shipped" time="14 October 2026" dateTime="2026-10-14">` per event, any
+  detail as its children, and the whole date in `time`. `titleAs` is the level under the
+  section's heading, or `"p"` in a busy feed. For something that moves along on its own, like a
+  parcel or a deployment, `active={i}` marks progress and `pending="Out for delivery"` ends it on
+  what's under way, oldest first. A journey the user moves through, like a wizard or a checkout,
+  stays `Steps`.
+- **A file browser, a checkbox tree (permissions, filters) or an outline you browse is
+  `TreeView`**, with `<TreeView.Item value="…" label="…" icon="folder">` items nested inside each
+  other: `<TreeView aria-label="Files" selectionMode="single">` with `selected`/`onSelectedChange`
+  picks one, and `selectionMode="checkbox"` with `checked`/`onCheckedChange` draws boxes with
+  mixed parents, where a parent's value checks its whole branch. Map the data with a recursive
+  function, and render an item's children whether it's open or not. Its items aren't links, so
+  the app's sidebar and any list of pages stay on `Menu` with `Menu.Item href`.
 - Link lists (footer nav, sidebars): a bare `UnorderedList` of `ListItem`s is already
   marker-less and flush — Bulma's reset unstyles `ul` — so no prop or CSS is needed;
   bullets appear only inside `Content`.
@@ -199,9 +214,11 @@ background comes from the semantic `color` prop, not `bgColor`.
 | `display: 'none'`                        | `visibility="hidden"`, or responsive `display*` props (`displayMobile`, `displayTablet`, …)                                                                    |
 | `gap: '1rem'` (flex or grid)             | `gap="2"`, or one axis: `columnGap`, `rowGap`; gap scale: `1`=0.5rem, `2`=1rem, `4`=2rem, half steps (`"1.5"`)                                                 |
 
-No helper matches (e.g. `maxWidth`, a one-off gradient)? Add a named class to the project
-stylesheet (`src/App.css` in a scaffolded app) and pass it via `className` — still never
-inline `style`.
+No helper matches (e.g. `maxWidth`, a one-off gradient)? Add a named class to the project's
+global stylesheet and pass it via `className` — still never inline `style`. In a create-bestax
+app that is `src/index.css`, which its entry file imports after bestax's stylesheet, so the
+class wins over a Bulma rule of the same weight. The starter page's `src/App.css` loads after
+bestax's too, but only while the starter's `App` imports it.
 
 ## References
 

package/templates/skills/bestax-layout-scaffold/references/layout-components.md

@@ -252,9 +252,9 @@ https://bestax.io/docs/guides/features/routing.
 
 `<Menu>` is a vertical sidebar menu. Subcomponents: `Menu.Label`, `Menu.List`, `Menu.Item`.
 
-| Prop        | Type                                                                                              |
-| ----------- | ------------------------------------------------------------------------------------------------- |
-| `Menu.Item` | `active?`, `href?`, `as?` (custom link component); nest a `Menu.List` inside an item for submenus |
+| Prop        | Type                                                                                                                                                                                |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Menu.Item` | `active?` (the current page: `is-active` plus `aria-current="page"`, so don't add your own), `href?`, `as?` (custom link component); nest a `Menu.List` inside an item for submenus |
 
 ```tsx
 <Menu>

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

@@ -1,6 +1,6 @@
 ---
 name: bestax-migrate
-description: Migrate an existing React app to @allxsmith/bestax-bulma on Bulma v1, from raw Bulma CSS classes on plain JSX (className="button is-primary") or from an unmaintained React Bulma library (react-bulma-components v4, rbx v2, bloomer 0.6). Run the bestax-migrate codemod, then resolve every TODO(bestax-migrate) comment it leaves using the per-source mapping references. Use when a React app styles its markup with Bulma classes and wants bestax components instead, when a repo imports react-bulma-components, rbx or bloomer, when TODO(bestax-migrate) comments are present in a codebase, or when asked to convert Bulma classNames to bestax-bulma.
+description: Migrate an existing React app to @allxsmith/bestax-bulma on Bulma v1, from raw Bulma CSS classes on plain JSX (className="button is-primary") or in static HTML pages and templates styled with Bulma, or from an unmaintained React Bulma library (react-bulma-components v4, rbx v2, bloomer 0.6). Run the bestax-migrate codemod, then resolve every TODO(bestax-migrate) comment it leaves using the per-source mapping references. Use when a React app styles its markup with Bulma classes and wants bestax components instead, when static HTML pages or templates styled with Bulma should become React components, when a repo imports react-bulma-components, rbx or bloomer, when TODO(bestax-migrate) comments are present in a codebase, or when asked to convert Bulma classNames to bestax-bulma.
 license: MIT
 ---
 
@@ -21,6 +21,7 @@ The codemod's first argument names the library you are migrating _from_. Check t
 | `rbx` v2 (abandoned 2019, pins Bulma **0.7.5** plus four extensions)             | `rbx`                    | [`references/rbx/`](references/rbx/component-map.md)                                       |
 | `bloomer` 0.6 (archived 2018, Bulma 0.6 era, React 16 + `create-react-class`)    | `bloomer`                | [`references/bloomer/`](references/bloomer/component-map.md)                               |
 | Raw Bulma classes on plain JSX (`<div className="box">`), no React Bulma library | `bulma-classes`          | [`references/bulma-classes/`](references/bulma-classes/component-map.md)                   |
+| Static HTML pages or templates styled with Bulma (`<div class="box">`)           | `bulma-classes`          | [`references/bulma-classes/`](references/bulma-classes/unmappables.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`,
@@ -38,6 +39,24 @@ Run these steps in order. Don't hand-convert what the codemod converts automatic
    pnpm dlx bestax-migrate <source> src/ --dry
    ```
 
+   For HTML pages, name a page, or walk a folder with `-e html` (`-e html,htm` for `.htm` pages
+   too; a plain walk skips them,
+   since most of it in a React project isn't a page to convert, and reports the Bulma pages it
+   skipped as `html-file:not-included`):
+
+   ```sh
+   pnpm dlx bestax-migrate bulma-classes src/pages/login/index.html --dry
+   pnpm dlx bestax-migrate bulma-classes -e html src/pages/ --dry
+   ```
+
+   Each page becomes a module beside it (`index.tsx`, or `.jsx` when the package isn't
+   TypeScript) whose default export is `<Name>Page`, named from the file (its folder's for an
+   `index.html`). The page stays as it was, and the codemod never writes over a module that's
+   already there, so a re-run writes nothing. Its head, its `<html>` and `<body>` attributes and
+   its scripts become `html-*` TODOs: put the app-wide parts in the app's `index.html` and
+   entry, and port each script's work into the component. Under `--css bestax` or `--css bulma`
+   the module imports the stylesheet in place of the page's Bulma `<link>`.
+
 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 →
@@ -121,7 +140,9 @@ code per the references, or deliberately keep the old markup with `className` st
   App Router may render as server components are left alone (`rsc`), and the manifest gains
   `@allxsmith/bestax-bulma` while the app's Bulma and stylesheets stay (the default
   `--css keep`). Its rules are `kind:<name>` shaped; see
-  `references/bulma-classes/unmappables.md`.
+  `references/bulma-classes/unmappables.md`. An HTML page converts the same way once it is JSX,
+  and what a component can't carry (the head, scripts, inline handlers, `<html>` and `<body>`
+  classes such as `has-navbar-fixed-top`) gets an `html-*` rule with its recipe there.
 - **bloomer**: every export is a flat name and most become dotted bestax compounds
   (`CardHeaderTitle` → `Card.Header.Title`). Most of its `is*` booleans already are bestax's
   (`isActive` becomes `active` where bestax names it so; `isFullWidth` becomes `isFullwidth`

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

@@ -189,10 +189,10 @@ value is flagged. The same conversion covers the modifiers bestax has no prop fo
 bloomer forwarded no refs. bestax forwards a ref from the form controls, plus `Avatar`, `Button`,
 `Carousel`, `CarouselItem`, `Dialog`, `Dropdown`, `EmptyState`, `Kbd`, `Kbd.Group`, `Link`,
 `LinkButton`, `Loader`, `Menu.Item`, `Modal`, `Navbar`, `Navbar.Burger`, `Navbar.Dropdown`,
-`Navbar.Item`, `Navbar.Link`, `SegmentedControl`, `SegmentedControl.Segment`, `Sidebar`, `Toast` and
-`ToggleButton` — pass `ref` directly on those. "The form controls" means the inputs themselves: the
-`Field`, `Field.Label`, `Field.Body`, `Checkboxes` and `Radios` wrappers around them forward
-nothing.
+`Navbar.Item`, `Navbar.Link`, `SegmentedControl`, `SegmentedControl.Segment`, `Sidebar`, `Timeline`,
+`Timeline.Item`, `Toast`, `ToggleButton`, `TreeView` and `TreeView.Item` — pass `ref` directly on
+those. "The form controls" means the inputs themselves: the `Field`, `Field.Label`, `Field.Body`,
+`Checkboxes` and `Radios` wrappers around them forward nothing.
 
 A `ref` on anything else is unsupported, and the two React majors fail differently: React 18
 drops it and logs "Function components cannot be given refs", while React 19 hands it to the

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

@@ -154,11 +154,16 @@ element is a `.menu-list`, a bestax `Menu.List`, or the bare `<ul>` nested in on
 so the `<li>`s a `.map()` renders count too. One handed to any other function doesn't, since that
 function could render it anywhere. `Menu.Item` renders the `<li>` and its `<a>`
 together, so an item converts when its `<li>` holds one `<a>` and at most one bare `<ul>` after
-it, which becomes a `Menu.List`. `is-active` on the `<a>` becomes `active`, and the `<li>`'s own
+it, which becomes a `Menu.List`. `is-active` on the `<a>` becomes `active` beside an
+`aria-current` of the `<a>`'s own, since `active` writes `aria-current="page"` otherwise; without
+one, the item stays markup with an `attr:aria-current` TODO. If the item is the current page, add
+`aria-current="page"` to the `<a>` and re-run. The `<li>`'s own
 classes stay in `className`, which `Menu.Item` puts on the `<li>`. It puts `id`, `title`, `role`,
 `tabIndex`, `style` and `data-testid` there too, and everything else on the `<a>`, so an item
 converts only when its attributes already sit that way. A `.menu-item` gets a
-`family:menu-item` TODO. `Menu.List` drops `.menu-list` on a list inside another, so a
+`family:menu-item` TODO. `Menu.List` writes `role="list"` on its `<ul>`, which is the role a
+list already has, so a `.menu-list` with no `role` converts, and one with another `role` stays
+markup with an `attr:role` TODO. `Menu.List` drops `.menu-list` on a list inside another, so a
 `.menu-list` inside another, or around a bestax `Menu.List`, stays markup with a
 `context:Menu.List` TODO, and an item's nested list converts only inside a list that is a
 `Menu.List` or becomes one.
@@ -166,7 +171,7 @@ converts only when its attributes already sit that way. A `.menu-item` gets a
 ```tsx
 <ul className="menu-list">
   <li>
-    <a className="is-active" href="/team">Team</a>
+    <a className="is-active" href="/team" aria-current="page">Team</a>
     <ul>
       <li><a href="/team/members">Members</a></li>
     </ul>
@@ -174,7 +179,7 @@ converts only when its attributes already sit that way. A `.menu-item` gets a
 </ul>
 // becomes
 <Menu.List>
-  <Menu.Item active href="/team">
+  <Menu.Item active href="/team" aria-current="page">
     Team
     <Menu.List>
       <Menu.Item href="/team/members">Members</Menu.Item>

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

@@ -109,7 +109,7 @@ renders the same `<h2>`.
 | `.tabs` → `Tabs`                                                             | `is-centered`, `is-right`, `is-left`                                                                                                             | `align`                                                                                           |
 | `.tabs` → `Tabs`                                                             | `is-small`, `is-medium`, `is-large`                                                                                                              | `size`                                                                                            |
 | `.tabs` → `Tabs`                                                             | `is-fullwidth`, `is-boxed`, `is-toggle`, `is-toggle-rounded`                                                                                     | `isFullwidth`, `boxed`, `toggle`, `rounded` (`is-<color>` stays a class: `color` is deprecated)   |
-| the `<a>` in a menu item → `Menu.Item`                                       | `is-active`                                                                                                                                      | `active`                                                                                          |
+| the `<a>` in a menu item → `Menu.Item`                                       | `is-active`, beside an `aria-current` of the `<a>`'s own                                                                                         | `active` (without one, the item stays markup with an `attr:aria-current` TODO)                    |
 | `.pagination` → `Pagination`                                                 | `is-small`, `is-medium`, `is-large`                                                                                                              | `size`                                                                                            |
 | `.pagination` → `Pagination`                                                 | `is-centered`, `is-right`, `is-rounded`                                                                                                          | `align`, `rounded` (`is-<color>` stays a class: `color` is deprecated)                            |
 | `.pagination-link` → `Pagination.Link`                                       | `is-current`, beside an `aria-current` of the element's own                                                                                      | `active` (without one, it stays a class; `is-disabled` stays a class)                             |

package/templates/skills/bestax-migrate/references/bulma-classes/unmappables.md

@@ -36,9 +36,10 @@ color. Rename or drop the attribute, then re-run.
 
 It also covers an attribute the component's props type rejects. `Delete` takes no `type`
 (`type="button"` is the one value that converts, because `Delete` renders it anyway), and
-`Progress` types `value` and `max` as numbers, so `value="half"` stays. Every component types
-`tabIndex` as a number too, so `tabIndex="0"` converts as `tabIndex={0}`. A number converts only
-when it is spelled the way it renders (`value="40"`, not `value="040"`).
+`Progress` types `value` and `max` as numbers, so `value="half"` stays. `InputBase` and
+`TextAreaBase` type `maxLength` and `minLength` as numbers, and `TextAreaBase` `rows` and `cols`
+too. Every component types `tabIndex` as a number, so `tabIndex="0"` converts as `tabIndex={0}`.
+A number converts only when it is spelled the way it renders (`value="40"`, not `value="040"`).
 
 `attr:dangerouslySetInnerHTML` is the same kind of refusal: the element sets its own content,
 and some bestax components render content of their own beside `children`, which React
@@ -67,6 +68,17 @@ empty one, keeps the item as markup too, and so does an empty `className` on the
 nothing is left to render its `class=""`. Move the attribute to where `Menu.Item` puts it if
 that's what you want, then re-run.
 
+`attr:role` on a `.menu-list` is a `role` other than `list`. `Menu.List` writes `role="list"` on
+its `<ul>` whatever it's given, for Safari, which stops treating a list as one once its markers are
+hidden, so that role would be lost. Keep the list as markup. One with no `role`, or `role="list"`,
+converts, since that's the role a `<ul>` already has.
+
+`attr:aria-current` is the `<a>`'s `is-active` with no `aria-current` beside it. `Menu.Item`'s
+`active` writes `aria-current="page"` on the `<a>` unless it has one of its own, so the item would
+gain it. If the item marks the page you're on, which is what `is-active` usually means in a menu,
+add `aria-current="page"` to the `<a>` and re-run, and the item converts with it. If it marks
+something else, keep the markup, or convert it by hand and pass the `aria-current` you want.
+
 ### `defaults:<Target>`
 
 The component renders attributes of its own when the element doesn't set them. `Delete`
@@ -270,7 +282,9 @@ The classes in a computed `className` still count for every other rule: a `clsx(
 `<span>` gets `tag:Box`, and a `clsx('dropdown', …)` gets `family:dropdown`. A computed
 `className` on the `<select>` inside a `.select`, the `<ul>` inside a `.breadcrumb` or the `<a>`
 in a menu item gets this TODO too. For the `<a>`, a condition on `is-active` is `Menu.Item`'s
-`active`: `<a className={on ? 'is-active' : undefined}>` becomes `<Menu.Item active={on}>`.
+`active`: `<a className={on ? 'is-active' : undefined}>` becomes `<Menu.Item active={on}>`, which
+also writes `aria-current="page"` while `on` holds. Pass an `aria-current` of your own if the item
+marks something other than the current page.
 
 ## A family it leaves as markup: `family:<class>`
 
@@ -338,6 +352,305 @@ alone: every other TODO names a React component to use.
   another runtime (Preact, Solid), or a package that sets one in its tsconfig or depends on one
   instead of React. bestax-bulma components are React components.
 
+## A page converted from HTML: `html-*`
+
+Run on an HTML page (`bestax-migrate bulma-classes page.html`, or a folder with `-e html`, or
+`-e html,htm` to take `.htm` pages too), the
+codemod writes a module beside the page and runs everything above on it, so a page gets the same
+TODOs its markup would as JSX. What a component can't carry gets an `html-*` rule. TODOs about the
+whole page sit above the component, the rest above its `return`, and each ends with the page and
+the line it came from (`(index.html:42)`). The page itself stays as it was, so the code a TODO
+points at is still there to read. A rule names only a tag, an attribute or a fixed word, never
+anything the page says.
+
+### The page's head: `html-head:<tag>`
+
+A component renders into the `<body>` of the app's own document, so nothing in the page's
+`<head>` comes with it.
+
+- **`html-head:title`**: set the title where the app sets each page's title (its router's or
+  framework's head API). Under React 19 the component can render `<title>` itself and React moves
+  it into the head; React 18 leaves it in the body, so use `document.title` in an effect there.
+- **`html-head:meta`**: `charset` and `viewport` go once in the app's `index.html`. A page's own
+  (a description, Open Graph tags) go where the app sets each page's head.
+- **`html-head:link`**: icons, preconnects and preloads are app-wide, so keep them in
+  `index.html`; a `canonical` is per page.
+- **`html-head:style`**: the `<style>` block was dropped. Move its rules into the app's stylesheet.
+- **`html-head:base`**: `<base href>` changed how the page's relative URLs resolved, and the app
+  has one document for every route. Make those URLs absolute instead (see `html-url:relative`).
+- **`html-head`**: anything else in the head (a `<noscript>`, a `<template>`). Move it into
+  `index.html` if the app needs it.
+
+### Stylesheets and scripts it loads: `html-asset:<kind>`
+
+Each `<link rel="stylesheet">` and `<script src>`, by what its URL says it is. A component loads
+neither, so load what the app still needs once for the whole app, from its entry module or
+`index.html`. The TODO quotes the URL.
+
+- **`html-asset:bulma`**: Bulma's own stylesheet, with the version its URL names
+  (`bulma@0.9.4`, or none for a copy of the page's own).
+  - Under the default `--css keep` it is only reported: keep loading Bulma
+    (`import 'bulma/css/bulma.min.css'` in the entry, with that version of `bulma` installed, or the
+    CDN `<link>` in `index.html`).
+  - Under `--css bestax` the module imports `@allxsmith/bestax-bulma/bestax.css` in the link's
+    place, and under `--css bulma` it imports `bulma/css/bulma.min.css` and
+    `@allxsmith/bestax-bulma/extras.css`, the way the same import in a JSX file is retargeted, so the
+    package.json step sees the module's `bulma` import too. One import from each page module is
+    fine, since the bundler loads it once. What is left gets the TODO: a page made for Bulma 0.9, or
+    one whose URL doesn't say, moves to Bulma 1 (the docs' Bulma 0.9 to 1 guide), and under
+    `--css bestax` a page with a primary color class (`is-primary`, `has-text-primary`) changes
+    color, since `bestax.css` builds Bulma with bestax's own primary. To keep it, set the
+    `--bulma-primary-*` variables as [css-migration.md](../css-migration.md) says, or use
+    `--css bulma`. A Bulma 1 page with no primary class gets the import and no TODO. A TypeScript
+    build resolves the import through the bundler's CSS types (Vite's `vite/client`), as it does
+    every stylesheet import.
+  - No import is written in a Next.js app, whose Pages Router takes a global stylesheet only in
+    `pages/_app`, nor for a link with a media query (`media="print"`), since an import applies to
+    every medium. The TODO says where it goes instead: the root layout or `pages/_app`, or a
+    `<link>` with the same `media` in `index.html`.
+  - One of Bulma's other builds (`bulma-no-dark-mode`, `bulma-prefixed`, 0.9's `bulma-rtl`) is
+    reported in every mode, since the codemod imports only the standard one. bestax's own builds,
+    Bulma with its extras, are under `@allxsmith/bestax-bulma/versions/`.
+- **`html-asset:font-awesome`**: Font Awesome, with the major its URL names. bestax's `Icon`
+  writes its classes (`fas fa-<name>`) and loads no font of its own, so keep loading it, from the
+  `<link>` in `index.html` or from npm: bestax-bulma's optional peer range for
+  `@fortawesome/fontawesome-free` is `^6.7.2 || ^7.0.0`, and an older one fails `npm install`
+  with `ERESOLVE`.
+  - 6 and 7: keep it as it is, or install it and import its `css/all.min.css` from the entry.
+  - 5: the CDN link keeps working, since 5 reads the classes `Icon` writes. From npm, take 6 or 7,
+    which still read 5's names.
+  - 4: its classes are `fa fa-<name>`, and `Icon` writes `fas fa-<name>`, which 4 doesn't style.
+    Install 6 or 7 with `css/all.min.css`, then either import `css/v4-shims.min.css` beside it so
+    the page's 4 names keep working, or move them to the current names (`fa-envelope-o` is
+    `envelope` with `variant="regular"`).
+  - A kit (`kit.fontawesome.com`): keep loading it from `index.html`, or install Font Awesome from
+    npm instead. A URL with no version: the same, with the v4 shims beside it if the page's names
+    are 4's (`fa fa-<name>`).
+- **`html-asset:bulma-extension`**: a `bulma-*` package (or `@creativebulma/bulma-*`). An
+  extension's stylesheet and script are one TODO, with both lines. Where bestax has a component
+  for what it does, the TODO names it; render that in place of the extension's markup and script,
+  whose styles ship in `extras.css` and `bestax.css`, and stop loading the extension once nothing
+  the app keeps uses its classes:
+
+  | Extension                                               | bestax                                                          |
+  | ------------------------------------------------------- | --------------------------------------------------------------- |
+  | `bulma-carousel`                                        | `Carousel`, with a `CarouselItem` for each slide                |
+  | `bulma-slider`                                          | `Slider`                                                        |
+  | `bulma-switch`                                          | `Switch`                                                        |
+  | `bulma-checkradio`                                      | `Checkbox` and `Radio`, which draw their own box                |
+  | `bulma-tooltip`, `@creativebulma/bulma-tooltip`         | `Tooltip`                                                       |
+  | `bulma-badge`, `@creativebulma/bulma-badge`             | `Badge`                                                         |
+  | `bulma-steps`                                           | `Steps`                                                         |
+  | `bulma-timeline`                                        | `Timeline`                                                      |
+  | `bulma-tagsinput`, `@creativebulma/bulma-tagsinput`     | `Taginput`                                                      |
+  | `bulma-calendar`                                        | `DateInput`, `TimeInput`, `DateTimeInput` and `DateRangeInput`  |
+  | `bulma-accordion`                                       | `Collapses`, with a `Collapse` for each item                    |
+  | `bulma-collapsible`, `@creativebulma/bulma-collapsible` | `Collapse` (`Collapses` for an accordion)                       |
+  | `bulma-pageloader`                                      | `Loading`, `isFullPage` for one over the whole page             |
+  | `bulma-quickview`                                       | `Sidebar`                                                       |
+  | `bulma-toast`                                           | `Toast`: `toast.show()` from code, with a `ToastContainer` once |
+
+  `bulma-extensions`, the bundle, holds several of these: replace the ones in the table, and keep
+  loading the bundle only for the rest. **bulma-social** has no bestax component: keep loading it,
+  since its classes (`is-twitter`, `is-github`) style Bulma's `.button`, which `Button` renders,
+  so they go on `Button` through `className`:
+
+  ```tsx
+  <Button as="a" className="is-github" href="https://github.com/example">
+    <Icon name="github" variant="brands" />
+  </Button>
+  ```
+
+  Any other extension: keep loading it while the page's markup uses its classes, which go on
+  bestax's components through `className`, and under `--css bestax` or `--css bulma` check it
+  works with Bulma 1, which an extension can predate.
+
+- **`html-asset:jquery`**: jQuery itself (a plugin such as jQuery UI is `html-asset:script`).
+  React renders the page now, so what the page's scripts did with jQuery (toggling classes,
+  handlers, showing and hiding) becomes state and event props; load jQuery only if a library the
+  app keeps still needs it.
+- **`html-asset:webfont`**: a web font's stylesheet (Google Fonts, Bunny Fonts, Adobe Fonts).
+  Keep the `<link>` in `index.html` with its preconnects, or self-host the font and import it from
+  the entry. Google's Material Icons and Material Symbols are icon fonts, which `Icon` writes with
+  `library="material-icons"` or `library="material-symbols"`; keep the link, or install the
+  `material-icons` or `material-symbols` package.
+- **`html-asset:stylesheet`**: any other stylesheet. The page's own, beside it (in its folder or
+  one below), is imported once for the app in the order the page loads it, so its rules still win
+  over Bulma's where they did (a module beside the page imports `css/styles.css` as
+  `./css/styles.css`), or its rules move into the app's stylesheet. For one that isn't in the
+  page's folder, the TODO says only that: the page's `<base href>`, if it has one, may have loaded
+  it from somewhere else, so find the one it meant, or drop it.
+- **`html-asset:script`**: any other script. The component runs none: load a library the app still
+  needs in `index.html` (or install it), and port what the page's own scripts did into the
+  component. A script of the page's own, beside it, is read the way an inline script is, so one
+  that toggles the burger, drives a carousel or switches the theme gets that `html-script:<pattern>`
+  TODO instead, quoting the file. One a `../` reaches outside the page's folder isn't read. A
+  `<script src>` of a type a browser loads nothing for (`text/template`, `application/json`) isn't
+  code: it gets the `html-script` TODO for data (`html-script:json-ld` for JSON-LD), naming its
+  file.
+
+### Inline scripts: `html-script:<pattern>`
+
+Every inline `<script>` is dropped, and its TODO gives the lines in the page where its code still
+is. One that does something bestax has a component for gets that pattern's rule, and a script
+can get more than one. A script of the page's own, beside it (`<script src="js/scripts.js">`), is
+read for the burger, a carousel and a theme toggle too, and its TODO names the file:
+
+- **`html-script:burger`** toggles the navbar burger (`.navbar-burger`, or the `.burger` class
+  Bulma 0.x's docs put beside it). Keep the open state in `useState` and pass it to
+  `Navbar.Burger` and `Navbar.Menu` (the `family:navbar-burger` TODO on the burger says why the
+  markup stays):
+
+  ```tsx
+  function SiteNavbar() {
+    const [open, setOpen] = useState(false);
+    return (
+      <Navbar role="navigation" aria-label="main navigation">
+        <Navbar.Brand>
+          <Navbar.Item href="/">Home</Navbar.Item>
+          <Navbar.Burger
+            active={open}
+            onClick={() => setOpen(!open)}
+            aria-label="menu"
+          />
+        </Navbar.Brand>
+        <Navbar.Menu active={open}>
+          <Navbar.Start>
+            <Navbar.Item href="/docs">Docs</Navbar.Item>
+          </Navbar.Start>
+        </Navbar.Menu>
+      </Navbar>
+    );
+  }
+  ```
+
+- **`html-script:modal`** opens or closes a modal. `Modal` shows while `active` is true and calls
+  `onClose` from its background, its close button and Escape, so keep the open state in
+  `useState` (the `family:modal` TODO covers rebuilding the markup).
+- **`html-script:dismiss`** removes an element when its `.delete` is clicked. `Notification`
+  takes `hasDelete` and `onDelete`, `Tag` takes `onDelete` and `Message` takes `onClose`; render
+  the element only while it's in state.
+- **`html-script:carousel`** drives a carousel. `Carousel` takes its slides as `CarouselItem`
+  children and renders its own arrows and indicators (`autoplay` for a timed one). Its styles ship
+  in bestax's `extras.css` and `bestax.css`, not in Bulma's stylesheet.
+- **`html-script:theme`** switches Bulma's light and dark schemes. The toggle is `Theme`'s: it
+  writes `data-theme` on `<html>` from its `colorMode` (`light`, `dark` or `system`), so keep the
+  choice in state, save it in `localStorage`, and pass it. The first paint is `index.html`'s:
+  `Theme` writes from an effect, after the first paint, so a visitor whose saved choice differs
+  from their OS sees the OS's scheme first. A small inline script in the `<head>` of `index.html`
+  that reads the saved choice (or the OS's, with none saved) and writes `data-theme` before the
+  app loads paints the right one, and the toggle's state starts from what it wrote. The
+  bestax-theming skill covers `Theme` and `colorMode`.
+- **`html-script:json-ld`** is structured data for search engines. Render it where the app sets
+  each page's head, as
+  `<script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(data) }} />`.
+- **`html-script`**: any other inline script, or a `<script type>` that isn't code (a template,
+  JSON data). Port what it does into the component as state, effects and event handlers.
+
+### `<html>` and `<body>`: `html-document:<name>`
+
+The app's document has its own `<html>` and `<body>`, which a component can't reach.
+
+- **`html-document:has-navbar-fixed-top`**, and the same for `has-navbar-fixed-bottom`,
+  `has-navbar-fixed-top-desktop`, `has-navbar-fixed-top-touch`, `has-navbar-fixed-bottom-desktop`,
+  `has-navbar-fixed-bottom-touch`, `has-spaced-navbar-fixed-top` and
+  `has-spaced-navbar-fixed-bottom` (`html-document:has-navbar-fixed-bottom` and so on): Bulma
+  pads the page for a fixed navbar from it. Put the class on the `<html>` in `index.html`, since
+  bestax's `Navbar` adds none there, whatever its `fixed` says.
+- **`html-document:data-theme`**, **`html-document:theme-dark`**, **`html-document:theme-light`**:
+  the page's color scheme. Put it on the `<html>` in `index.html`, or render
+  `<Theme colorMode="dark">`, which writes `data-theme` on `<html>`.
+- **`html-document:lang`**, **`html-document:dir`**: set them on the `<html>` in `index.html`.
+- **`html-document:class`**: the page's own classes on `<html>` or `<body>`. Put them on the
+  app's own `<body>` (or `<html>`), or on an element around the page's content if the styles
+  allow it.
+- **`html-document:id`**, **`html-document:style`**, **`html-document`**: any other attribute
+  there, which moves the same way.
+
+### Event handlers: `html-event:<attribute>`
+
+An `onclick="…"` and its kind, on any element or on `<body>` (`onload`). React takes a function,
+not code in a string, so the attribute was dropped; the TODO quotes the code and names the prop
+that takes it (`onClick`). Port the code into a handler, reading the element from the event rather
+than `this`. A `<body onload>` becomes an effect.
+
+### Elements: `html-element:<kind>`
+
+- **`html-element:custom`**: a custom element (`<my-widget>`) renders as written, but the script
+  that defines it isn't loaded by the module: import its definition in the app. A TypeScript
+  build also needs the tag declared in `JSX.IntrinsicElements`.
+- **`html-element:obsolete`**: `<center>`, `<font>`, `<marquee>` and their kind still render, but
+  React's types list few of them. Replace each with current markup (`has-text-centered` for
+  `<center>`, a class for `<font>`).
+- **`html-element:unknown`**: a tag that isn't HTML renders as an unknown inline element, and
+  TypeScript rejects it. Replace it with the element it stands for.
+- **`html-element:template`**: `<template>` holds markup for a script to clone. Render that
+  markup from the component where the script used it.
+- **`html-element:name`**: a tag JSX can't write (`<o:p>`, from Word), so its children were
+  written in its place. Put back the element it stood for, if it mattered.
+- **`html-element:conditional-comment`**: an Internet Explorer conditional comment was dropped;
+  no browser React supports reads one.
+
+### URLs: `html-url:<kind>`
+
+- **`html-url:javascript`**: a `javascript:` URL won't run (React 19 replaces it with one that
+  throws, and React 18 warns). Move the code into an `onClick` handler.
+- **`html-url:relative`**: `img/logo.png` resolved against the page's folder, and in the app it
+  resolves against the address the component renders at. The file is there beside the page, so
+  copy it into the app's `public/` folder and point at it from the site root (`/img/logo.png`), or
+  import it. A link to another page beside this one should point at the route that page becomes.
+  Each relative URL in a `srcset` is its own entry, quoted as itself (`` `hero@2x.png` in `srcset` ``).
+  Several of these share one TODO line, and each is its own report entry.
+- **`html-url:missing`**: a relative URL whose target isn't beside the page, read the way the
+  browser read it, so it was a dead link or a missing file already. Point it somewhere real, or
+  drop it.
+
+### Attributes: `html-attr:<kind>`
+
+- **`html-attr:name`**: an attribute JSX can't write (`@click`, `:class`, `x-on:click`), or one the
+  element already had under another spelling, was left out. A framework's directive is code to port
+  into the component.
+- **`html-attr:unknown`**: an attribute React has no prop for by that name, written as it was.
+  React renders it. Whether a TypeScript build takes it depends on the element (React's types
+  list `valign` on a `<td>` and not on a `<th>`), so the TODO doesn't say; what to do depends on
+  the attribute, and the TODO says which:
+  - React's own prop in the wrong case (`defaultvalue`, `defaultchecked`), which the page never
+    read since it isn't HTML: rename it to the prop (`defaultValue`), or drop it if it isn't
+    meant.
+  - An obsolete presentational attribute (`valign`, `bgcolor`, `nowrap`), which CSS replaced:
+    write it as CSS or a class.
+  - Anything else: drop it if nothing reads it, make it a `data-` attribute if a script of the
+    page's reads it, and if React's types don't list it on that element, declare it for a
+    TypeScript build.
+- **`html-attr:style`**: a `style` declaration a browser can't read (`*zoom: 1`) was left out, as a
+  browser leaves it out. Delete it, or rewrite it if it meant something.
+- **`html-attr:important`**: React sets a style without a priority, so the declaration is written
+  without its `!important`. If a stylesheet rule beats it now, move it into a class in the app's
+  stylesheet.
+
+### Parse errors: `html-parse:<code>`
+
+The HTML has an error the browser repaired (`html-parse:duplicate-attribute`,
+`html-parse:end-tag-without-matching-open-element`), reported once for each kind, with how many
+more there are. The module follows the DOM the browser builds from it, which may not be what the
+markup meant, so check that part of the page. A code too long for a rule id is reported as the bare
+`html-parse`.
+
+### The page itself: `html-file:<case>`
+
+- **`html-file:exists`**: the module beside the page is already there, and the codemod never
+  writes over a file. That makes a second run change nothing. Move or delete the module to convert
+  the page again.
+- **`html-file:not-included`**: a folder walk found the page, and it has Bulma classes, but a walk
+  takes a page only when `--extensions` lists its extension, since most `.html` files in a React
+  project aren't pages to convert (Vite's `index.html`, `public/`). `-e` matches an extension
+  exactly, as it does for every file, so `-e html` takes no `.htm` page; the TODO names the one
+  the page needs. Name the page, or add its extension to `--extensions` (`-e html,htm` for both).
+- **`html-file:template-syntax`**: the page is a server template (`{{`, `{%`, `<?php`, `<%`), which
+  isn't HTML a browser reads as written. Convert the HTML it renders, or the template by hand.
+
+A page with no Bulma component class writes nothing and reports nothing.
+
 ## Things that get no TODO
 
 - Helper classes on a `<div>` (`<div className="is-flex mt-4">`): bestax has no plain `<div>`

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

@@ -26,7 +26,11 @@ choice below applies.
   **Visual note**: `bestax.css` ships with `$primary` set to bestax blue (`#1e6b99`),
   not Bulma's stock turquoise — `is-primary` surfaces (hero, navbar, buttons) change
   color. Keep the stock Bulma look with `--css bulma`, or set your own brand color via
-  `--bulma-primary-*` CSS variables / a Sass build.
+  `--bulma-primary-*` CSS variables / a Sass build. Set `--bulma-primary-invert-l` along with
+  `--bulma-primary-h`, `--bulma-primary-s` and `--bulma-primary-l`: it is the lightness of the
+  text on a primary surface, and bestax's build fixes it for its dark blue, so a light primary set
+  through the other three alone keeps white labels. To get stock Bulma's turquoise back on top of
+  `bestax.css`, copy those four from Bulma's own `bulma/css/bulma.css`.
 
 - **SCSS files**: Bulma 0.9's `@import 'bulma/bulma.sass'` (plus preceding
   `$var: value !default;` overrides) became Bulma v1 module syntax, with simple literal

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

@@ -183,10 +183,10 @@ An existing `ref` is passed through untouched — which is safe only where the b
 one. rbx forwards a ref on every component; bestax does so on the form controls, plus `Avatar`,
 `Button`, `Carousel`, `CarouselItem`, `Dialog`, `Dropdown`, `EmptyState`, `Kbd`, `Kbd.Group`,
 `Link`, `LinkButton`, `Loader`, `Menu.Item`, `Modal`, `Navbar`, `Navbar.Burger`, `Navbar.Dropdown`,
-`Navbar.Item`, `Navbar.Link`, `SegmentedControl`, `SegmentedControl.Segment`, `Sidebar`, `Toast` and
-`ToggleButton`. "The form controls" there means the inputs themselves: the `Field`, `Field.Label`,
-`Field.Body`, `Checkboxes` and `Radios` wrappers around them forward nothing, and `Field` is a
-target this codemod emits.
+`Navbar.Item`, `Navbar.Link`, `SegmentedControl`, `SegmentedControl.Segment`, `Sidebar`, `Timeline`,
+`Timeline.Item`, `Toast`, `ToggleButton`, `TreeView` and `TreeView.Item`. "The form controls" there
+means the inputs themselves: the `Field`, `Field.Label`, `Field.Body`, `Checkboxes` and `Radios`
+wrappers around them forward nothing, and `Field` is a target this codemod emits.
 
 Carry a `ref` onto anything else — `Card`, `Box`, `Section`, `Message`, `Tabs` and most of the
 catalogue — and it is unsupported, but the two React majors fail differently. React 18 drops

package/templates/skills/bestax-migrate/references/react-bulma-components/unmappables.md

@@ -166,10 +166,10 @@ bestax components don't take `domRef`, but many forward a plain `ref` — the fo
 `Avatar`, `Button`, `Carousel`, `CarouselItem`, `Dialog`, `Dropdown`, `EmptyState`, `Kbd`,
 `Kbd.Group`, `Link`, `LinkButton`, `Loader`, `Menu.Item`, `Modal`, `Navbar`, `Navbar.Burger`,
 `Navbar.Dropdown`, `Navbar.Item`, `Navbar.Link`, `SegmentedControl`, `SegmentedControl.Segment`,
-`Sidebar`, `Toast` and `ToggleButton`. On those, rename `domRef` to `ref` and it works; do not
-restructure the markup. "The form controls" means the inputs themselves: the `Field`, `Field.Label`,
-`Field.Body`, `Checkboxes` and `Radios` wrappers around them forward nothing, and `Field` is a
-target this codemod emits.
+`Sidebar`, `Timeline`, `Timeline.Item`, `Toast`, `ToggleButton`, `TreeView` and `TreeView.Item`. On
+those, rename `domRef` to `ref` and it works; do not restructure the markup. "The form controls"
+means the inputs themselves: the `Field`, `Field.Label`, `Field.Body`, `Checkboxes` and `Radios`
+wrappers around them forward nothing, and `Field` is a target this codemod emits.
 
 Everywhere else the rename is not enough, and the two React majors differ: React 18 drops the
 ref and logs "Function components cannot be given refs", while React 19 passes it through as