create-bestax 4.2.19 → 4.3.0

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

@@ -6,9 +6,13 @@ wrapper library. The codemod converts an element only when the bestax component
 stays as written, with a `TODO(bestax-migrate)` when there is something to decide (see
 [unmappables.md](unmappables.md)). The exceptions are deliberate. Font Awesome's own
 `<i aria-hidden="true">` alone in a `.icon` that carries nothing assistive tech reads becomes
-`Icon`, which puts that attribute on the `.icon` instead, since the glyph is hidden either way
-(see `.icon` below). And a Bulma 0.9 helper that v1 removed, which styles nothing now, becomes
-the v1 helper that does its job (the [prop map](prop-map.md) lists them).
+`Icon`, which puts that attribute on the `.icon` instead, since the glyph is hidden either way.
+Such a `.icon` around a bare glyph, in a link or button its own `aria-label` or
+`aria-labelledby` names, becomes `Icon` too, which hides it, since the label is what assistive
+tech reads for the control. Font Awesome 6's long name for a style (`fa-brands`) becomes the
+`bestax-icons` skill's `variant` (`brands`), which renders the short name (`fab`), the same
+style (see `.icon` below). And a Bulma 0.9 helper that v1 removed, which styles nothing now,
+becomes the v1 helper that does its job (the [prop map](prop-map.md) lists them).
 
 A class the codemod doesn't know, such as the app's own `pricing-card`, rides along in
 `className`, which every bestax component passes through. So does a Bulma class with no bestax
@@ -156,16 +160,17 @@ renders its own `<a>` with tab roles and puts its label in a `<span>`, so conver
 themselves is by hand (something that sat beside the text in the `<a>`, a `Tag` say, then wants a
 `Span display="flex" alignItems="center"` around it and the label). A `.icon` converts when it
 carries the attribute `Icon` writes otherwise: `aria-hidden` with no name, no `role` and no
-`tabIndex`, and `role="img"` beside an `aria-label` or `aria-labelledby`. When all it holds is a
-bare, empty `<i>` naming a Font Awesome or Material Design Icons glyph, the `<i>` goes and its
-classes become `Icon`'s props, read as `IconText` reads them (below), and the `Icon` closes itself:
+`tabIndex`, and `role="img"` beside an `aria-label` or `aria-labelledby`. Those attributes are
+left out, since `Icon` renders them by itself. When all it holds is a bare, empty `<i>` naming a
+Font Awesome or Material Design Icons glyph, the `<i>` goes and its classes become `Icon`'s
+props, read as `IconText` reads them (below), and the `Icon` closes itself:
 
 ```jsx
 <span className="icon is-small" aria-hidden="true">
   <i className="fab fa-github fa-lg"></i>
 </span>
-// becomes
-<Icon library="fa" name="github" variant="brands" features="fa-lg" size="small" aria-hidden="true" />
+// becomes, rendering aria-hidden="true" on the .icon
+<Icon name="github" variant="brands" features="fa-lg" size="small" />
 ```
 
 Font Awesome's own markup hides the `<i>` instead, and converts the same way when the `.icon`
@@ -178,12 +183,39 @@ place a conversion changes the markup, on purpose:
   <i className="fas fa-envelope" aria-hidden="true"></i>
 </span>
 // becomes, rendering aria-hidden="true" on the .icon
-<Icon library="fa" name="envelope" size="small" className="is-left" />
+<Icon name="envelope" size="small" className="is-left" />
+```
+
+A `.icon` with no `aria-hidden` converts the same way when it sits in a `<button>`, or in a link
+(an `<a>` with an `href`), that its own `aria-label` or `aria-labelledby` names. That label is
+what assistive tech reads for the control, in place of what it holds, so the icon is decoration
+there, and `Icon` hides it. That is another place a conversion changes the markup, on purpose,
+held to the same shape: a bare glyph, in a `.icon` that carries nothing but its classes, an `id`,
+a `style` and `data-` attributes.
+
+```jsx
+<a className="button" href="https://github.com/" aria-label="GitHub">
+  <span className="icon"><i className="fab fa-github"></i></span>
+</a>
+// becomes, rendering aria-hidden="true" on the .icon
+<Button as="a" href="https://github.com/" aria-label="GitHub">
+  <Icon name="github" variant="brands" />
+</Button>
 ```
 
 Around anything else, an `<i>` with an attribute of its own or an `<svg>` say, it converts around
-what it holds, kept as written. Font Awesome 4's `fa` reads as `variant="fa"`, which `Icon`
-renders as written.
+what it holds, kept as written.
+
+The glyph's props are spelled the way the `bestax-icons` skill writes them. `library` is left out
+for Font Awesome, `Icon`'s default, and written for Material Design Icons. The style is `variant`:
+none for `fas`, and `regular`, `brands`, `light`, `duotone` or `thin` for the others. Font
+Awesome 6's long names for them (`fa-solid`, `fa-brands`, ...) read the same way, and `Icon`
+renders the short name (`fab`), the class Font Awesome 5 knows, which 6 and 7 style the same:
+a third place the markup changes on purpose. Beside `fa-sharp`, whose family Font Awesome 7's
+short name would set back to the classic one, the long name stays as written. Font Awesome 4's
+`fa` reads as `variant="fa"`, which `Icon` renders as written: 4 styles nothing else, and some
+4 names draw another glyph in 5 and later (the `bestax-icons` skill's
+`references/icon-libraries.md` lists them).
 
 A `.menu` converts with its `.menu-label`s and `.menu-list`s, and so do the items in a list. An
 item has no class to go by, so the codemod finds it by where it sits: a `<li>` whose nearest
@@ -314,14 +346,16 @@ as `items`.
   <span>Home</span>
 </span>
 // becomes
-<IconText iconProps={{ library: "fa", name: "home", "aria-hidden": "true" }}>Home</IconText>
+<IconText iconProps={{ name: "home" }}>Home</IconText>
 ```
 
 The glyph is read from the `<i>`: its Font Awesome style class (`fas`, `far`, `fa-solid`, ...) or
 `mdi`, the one class that names the glyph (`fa-home` as `name: "home"`), and the rest as
-`features`. `library` is always written, so a `ConfigProvider` with another `iconLibrary` doesn't
-change what renders. The `.icon`'s own classes and attributes join the glyph's props as they
-would on `Icon`, under their own names.
+`features`, spelled as on `Icon` (above). Like every conversion, this takes the app's
+`ConfigProvider` as unset: one with another `iconLibrary` needs `library: "fa"` written back on
+the Font Awesome ones, as one with a `classPrefix` changes every component's classes. The
+`.icon`'s own classes and attributes join the glyph's props as they would on `Icon`, under their
+own names, but for those `Icon` renders by itself.
 
 It converts only when every `.icon` inside converts to `Icon` on its own and holds a bare, empty
 `<i>` naming a Font Awesome or Material Design Icons glyph, and the only other children are those

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

@@ -2,7 +2,8 @@
 
 Which class becomes which prop, per component, then the helper classes every component takes.
 A class that becomes no prop stays in `className`. So does a second class for a prop already
-written (`is-small is-large` keeps `is-large`), so the element still renders both.
+written (`is-small is-large` keeps `is-large`), so the element still renders both. A second
+color gets a `modifier:<root>` TODO (`modifier:button`), since only one of the two may show.
 
 `{viewport}` is one of `mobile`, `tablet`, `desktop`, `widescreen`, `fullhd` unless a row says
 otherwise, and the prop takes the matching suffix: `is-6-tablet` → `sizeTablet="6"`.
@@ -74,7 +75,8 @@ bestax picks the heading from `size` (`size="3"` renders an `<h3>`) unless `as="
 `<h2>`, `is-4` stays a class and the element becomes `<Title as="h2" className="is-4">`, which
 renders the same `<h2>`. To write it as a prop, `textSize="4"` keeps the `<h2>` and sizes it the
 same: it renders Bulma's `is-size-4`, which has the font size `is-4` gives a title or subtitle,
-and as a Bulma helper it is `!important`, so check a title the page's own CSS sizes.
+and as a Bulma helper it is `!important`, so check a title the page's own CSS sizes. The
+codemod's `modifier:title` (or `modifier:subtitle`) TODO on the element says the same.
 
 ### Other components
 

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

@@ -104,15 +104,21 @@ and beside a `role` or `tabIndex` `Icon` writes no `aria-hidden` at all. Give a
 that carries it beside something else,
 an `id` say, keeps its `.icon` as markup too: the `.icon` holds nothing else, so the attribute
 hides the same glyph on the `.icon`. Move it up and re-run, and the `.icon` converts around the
-`<i>`. An icon in a link or
-button that its `aria-label` or its text names is decoration there, so give it
-`aria-hidden="true"`. One that is all a link or button shows names nothing a screen reader can
-read: give the link or button an `aria-label` that says what it does, then hide the icon. The
+`<i>`. An icon around a bare glyph in a `<button>`, or a link, that its own `aria-label` or
+`aria-labelledby` names converts as it is, another exception: the label is what assistive tech
+reads for the control, so the icon is decoration there, and `Icon` hides it. That takes the same
+`.icon` as the move: its classes, an `id`, a `style` and `data-` attributes, and no
+`aria-hidden`. An icon in a control its text names is decoration too, so give it
+`aria-hidden="true"`, and so is one in a named control it doesn't convert in (a `title` on the
+`.icon`, say). An `<a>` with no `href` is no link and has no role, and ARIA lets nothing name it,
+so its `aria-label` does nothing: give it an `href`, or make it a `<button>`, then re-run. One
+that is all a link or button shows names nothing a screen reader can read: give the link or
+button an `aria-label` that says what it does, then re-run, and the icon converts hidden. The
 `<svg class="svg-inline--fa">` Font Awesome's script draws in place of an `<i>` converts as
 `Icon`'s children once its `.icon` is hidden, or write `Icon` with the glyph's `name` in its place,
 which renders the `<i>` the script draws from. Inside a `.control` with `has-icons-left` or
 `has-icons-right`, a hidden `.icon` can go instead, as that `Control`'s `iconLeft` or
-`iconRight` (`iconLeft={{ library: "fa", name: "envelope", size: "small" }}`), which renders it
+`iconRight` (`iconLeft={{ name: "envelope", size: "small" }}`), which renders it
 after the `Control`'s children. Each TODO says which of these applies, and what the icon converts
 to.
 `Pagination` renders Bulma's own `role="navigation"` and `aria-label="pagination"`, and
@@ -370,13 +376,47 @@ in the browser:
   `aria-expanded` and keyboard handling. The codemod turned the `.has-dropdown` item around it
   into a `Navbar.Item` that keeps the class; to get the dropdown behavior, replace that item
   with `Navbar.Dropdown` (`hoverable` for `is-hoverable`) and the link with `Navbar.Link`.
-- **`family:checkbox`**, **`family:radio`**, **`family:checkboxes`**, **`family:radios`**:
-  bestax renders its own styled checkbox and radio markup, not Bulma's.
+- **`family:checkbox`**: `Checkbox` renders a `<label class="styled-checkbox checkbox">` around
+  its `<input>`, hidden, and draws a box of its own beside it. Write it in place of the element
+  that carries `.checkbox`, Bulma's `<label>` or a bare `<input type="checkbox">`:
+  - The `<input>`'s attributes go on `Checkbox`, which passes `id`, `name`, `aria-label` and the
+    rest to its `<input>`. A `<label>`'s text becomes its children.
+  - Drive it with `checked` and `onChange`, and add `indeterminate` for a select-all box that
+    shows some of its rows checked.
+  - Its `className` goes on its `<label>`, which declares the `--bulma-checkbox-*` variables. For
+    the page's colors, set those in a rule for your class beside `.styled-checkbox`, so the rule
+    wins whatever order the stylesheets load in, and leave `color` unset.
+  - Where the page put `.checkbox` on a bare `<input>`, drop its own rules for that box. bestax
+    draws its own, and `.checkbox` is on its `<label>` now, so those rules would land there.
+
+  ```tsx
+  <Checkbox
+    id="select-all"
+    aria-label="Select all guests"
+    className="guest-check"
+    checked={allChecked}
+    indeterminate={someChecked && !allChecked}
+    onChange={toggleAll}
+  />
+  ```
+
+  ```css
+  .styled-checkbox.guest-check {
+    --bulma-checkbox-active-color: #e8505b;
+  }
+  ```
+
+- **`family:radio`**, **`family:checkboxes`**, **`family:radios`**: bestax renders its own
+  styled radio markup, and its own `.field` and `.control` around a group, not Bulma's.
 - **`family:modal`**: `Modal` writes a `data-testid` of its own and adds dialog attributes and
   focus handling, so the `.modal` root stays markup while its background, content and card parts
-  convert on their own. Rebuild the root with `Modal` around them, and drive it with its open prop.
+  convert on their own. Rebuild the root with `Modal` around them, drive it with its open prop,
+  and pass `onClose`, which Escape and `Modal.Close` call. The converted `Modal.Background`
+  doesn't call it on its own: give it `onClick={onClose}` for the background to close the modal.
   A `.modal-close` stays too, since `Modal.Close` renders `.delete` unless it's floating: write
-  `<Modal.Close variant="floating" />` in its place. When the
+  `<Modal.Close variant="floating" />` in its place. A card head's `.delete` converts to `Delete`,
+  which doesn't call `onClose` either, so write `<Modal.Close />` there instead: it renders the
+  same `.delete`. When the
   page has to look the same, keep `Modal` rather than `Dialog` or `Toast`: those render
   bestax's own `.dialog` and `.toast` markup, which Bulma's stylesheet doesn't style.
 - **`family:dropdown`**: `Dropdown` renders its own trigger and menu from props.
@@ -406,16 +446,35 @@ reason), or beside a class for the same prop (`p-2`, before it or after), which
 since it's what the page renders today. Write `m-0` or `p-0` in its place, or drop it if the
 spacing it once removed no longer matters.
 
-## A class that styles nothing where it is: `modifier:<root>`
+## A modifier class that needs a look: `modifier:<root>`
 
 `modifier:image`: an `.image` size or ratio (`is-64x64`, `is-square`, `is-4by3`) on an element
 without `.image`. Bulma styles them only on the element that carries `.image`, so this one
 sizes nothing, unless the project's own CSS gives the class a rule. If the element is the
 image's box, add `image`. On a tag `Image` renders (the component map's `.image` row lists
-them), re-run and it can convert; on any other tag it stays markup, and the TODO says so.
-Otherwise drop the class. A computed `className` the codemod can't read whole gets no such TODO, since a class it
+them), re-run and it can convert; on any other tag it stays markup, and the TODO says so. Where
+the element converted to something else anyway (a `<figure>` to `Figure`), a re-run finds a
+component, so the TODO says to convert it to `Image` by hand. Otherwise drop the class. A computed `className` the codemod can't read whole gets no such TODO, since a class it
 can't see may be the `.image`.
 
+`modifier:button` (and `modifier:hero`, `modifier:tag`, `modifier:notification`,
+`modifier:progress`, `modifier:navbar`): a second color on an element that converted
+(`button is-black is-primary`). The component takes one `color`, the first color class on the
+element, and the other stays in `className`, which renders the same. Two colors on one element
+look the way Bulma's stylesheet settles them, not the order they're written in, so one of
+them may be doing nothing. Look at what the page shows, write the color you want as `color`,
+and drop the other class. A color a `clsx` or `classnames` condition adds gets no TODO, since
+that is a state the page asks for.
+
+`modifier:title`, `modifier:subtitle`: a heading size on a heading it doesn't name
+(`<h1 className="title is-3">`). bestax picks the heading from `size` (`size="3"` renders an
+`<h3>`), so the size stays in `className` and the element becomes `<Title className="is-3">`,
+the same `<h1>`. To write it as a prop, as the MCP server's `lookup_bulma_classes` says,
+`textSize="3"` in its place keeps the `<h1>` and sizes it the same. It renders Bulma's
+`is-size-3`, which is `!important`, so check a title the page's own CSS sizes. There is no TODO
+when an `is-size-*` beside it writes `textSize` already, or when the element has two size
+classes.
+
 ## A whole file it left alone
 
 These come only when the file has an element the codemod would convert (a computed className
@@ -511,21 +570,30 @@ neither, so load what the app still needs once for the whole app, from its entry
   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.
+    which still read 5's names, many of them since renamed (`search` is `magnifying-glass`). But
+    6 turned the handsets round, so to keep the glyph the page shows, write 5's `phone` and
+    `phone-square` as `phone-flip` and `square-phone-flip`, and 5's `phone-alt` and
+    `phone-square-alt` as `phone` and `square-phone`.
   - 4: its classes are `fa fa-<name>`. The codemod keeps that `fa` on each icon it converts
     (`variant="fa"`), which 4 styles, but an `Icon` given no `variant` writes `fas fa-<name>`,
     which 4 doesn't, so for the icons written from here on, 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"`).
+    `envelope` with `variant="regular"`). A brand's glyph under `fa` (`fa fa-github`) needs
+    `variant="brands"` then: 5 and later draw brands in a style of their own, and without the
+    shims show a missing-glyph box for one under `fa`.
+  - A URL that doesn't say its version: the TODO points at the `bestax-icons` skill's
+    `references/icon-libraries.md`, which lists the older names that draw another glyph in 6
+    and 7.
   - 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:
+- **`html-asset:bulma-extension`**: a `bulma-*` package (or `@creativebulma/bulma-*`). A file of
+  one extension inside the `bulma-extensions` package (`bulma-extensions/bulma-carousel/dist/…`)
+  counts as that extension's. 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                                                                                 |
   | ------------------------------------------------------- | -------------------------------------------------------------------------------------- |
@@ -545,6 +613,10 @@ neither, so load what the app still needs once for the whole app, from its entry
   | `bulma-quickview`                                       | `Sidebar`                                                                              |
   | `bulma-toast`                                           | `Toast`: `toast.show()` from code, with a `ToastContainer` once                        |
 
+  bulma-carousel's `is-covered` images are the exception: its stylesheet crops them only inside
+  its own slides, which `Carousel` doesn't render, so keeping it wouldn't keep them cropped. The
+  TODO says so when the page has them, and `html-extension:is-covered` has the rule to add.
+
   `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,
@@ -556,6 +628,20 @@ neither, so load what the app still needs once for the whole app, from its entry
   </Button>
   ```
 
+  It also ships one stylesheet per brand, `css/single/<brand>/<brand>.min.css`, a few kB each
+  against about 100 kB for every brand in `css/all.min.css`. Each holds the brand's button color
+  (`is-<brand>`) and its text and background helpers (`has-text-<brand>`,
+  `has-background-<brand>`, with `-dark` and `-light`). Every brand has a file from 3.2.0 on
+  (`slack`'s came in 2.1.0, `x`'s in 3.1.0 and `twitch`'s in 3.2.0). So with `bulma-social` 3.2.0
+  or later installed from npm, import only the brands the app shows, from its entry. The TODO names the files for the brands
+  in the page's markup, so an app of several pages imports each brand any of them shows, and one
+  a script adds as well:
+
+  ```ts
+  import 'bulma-social/css/single/github/github.min.css';
+  import 'bulma-social/css/single/twitter/twitter.min.css';
+  ```
+
   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.
@@ -572,9 +658,17 @@ neither, so load what the app still needs once for the whole app, from its entry
 - **`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.
+  `./css/styles.css`), or its rules move into the app's stylesheet. A relative URL in it (a
+  `url()`, or an `@import` written as a string) resolves against the stylesheet's own folder, not
+  the page's, so the TODO names each one it finds: `url('../media/background.webp')` in
+  `css/styles.css` points at `media/background.webp` beside the page. Imported where it is, the
+  bundler still resolves them. Moved into the app's stylesheet (`src/index.css`), each needs
+  rewriting against that file's folder, or copy the files into the app's `public/` folder and
+  point at them from the site root (`url('/media/background.webp')`), which the TODO spells out
+  for each one inside the page's folder. An `image-set()` that names a file as a bare string
+  isn't read, so check those by hand. For a stylesheet 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
@@ -620,8 +714,9 @@ read for the burger, a carousel and a theme toggle too, and its TODO names the f
   ```
 
 - **`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).
+  `onClose` on Escape and from a `Modal.Close` with no `onClick` of its own. `Modal.Background`
+  doesn't call it on its own, so give it `onClick={onClose}` for the background to close the
+  modal. 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.
@@ -643,7 +738,8 @@ read for the burger, a carousel and a theme toggle too, and its TODO names the f
   window's width in your own code. `Carousel` loops unless `repeat={false}`, while
   bulma-carousel stops at the ends unless `loop` (back to the start) or `infinite` (round
   without a break) is set, so a carousel with neither takes `repeat={false}`. Its styles ship in
-  bestax's `extras.css` and `bestax.css`, not in Bulma's stylesheet.
+  bestax's `extras.css` and `bestax.css`, not in Bulma's stylesheet. The element the script
+  drives gets `html-extension:carousel`, below, when the codemod can read its selector.
 - **`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:
@@ -661,6 +757,40 @@ read for the burger, a carousel and a theme toggle too, and its TODO names the f
 - **`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.
 
+### A Bulma extension's own markup: `html-extension:<name>`
+
+A component takes the place of an extension's markup, but nothing converts that markup, so these
+point at the elements to rebuild.
+
+- **`html-extension:carousel`**: an element bulma-carousel makes a carousel of. When a script of
+  the page's, inline or beside it, attaches bulma-carousel with a selector written as a string of
+  tags, ids and classes (`bulmaCarousel.attach('#carousel-demo')`), the codemod finds every
+  element that selector matches, the way `querySelectorAll` does, and the TODO lists their
+  lines. bulma-carousel makes a carousel of each one, so a page that gives one id to two elements
+  has two carousels, and the TODO says so. Render a `Carousel` in the place of each, with a
+  `CarouselItem` for each slide (bulma-carousel 4 makes a slide of each child), and carry its
+  options over as `html-script:carousel` says. On a page that uses bulma-carousel, an element
+  with its `carousel` class that no selector reached gets the TODO too. `carousel` is also bestax
+  `Carousel`'s own class, so `bestax.css` and `extras.css` style that markup as `Carousel`'s root
+  (`position: relative`, `overflow: hidden`, `width: 100%`) until a `Carousel` takes its place. A
+  selector the codemod can't read (a variable, or a selector with a combinator or an attribute)
+  gets no TODO of its own: find what it selects by hand.
+- **`html-extension:is-covered`**: bulma-carousel's `is-covered` on an `.image`, on a page that
+  loads its stylesheet (the bundle's combined `bulma-extensions.min.css` has no rule for it).
+  Inside one of the slides its script builds, that stylesheet makes the `<img>` fill the frame
+  and crops it to fit (`object-fit: cover`). Nothing in bestax reads the class: `Image` has no
+  prop for it, and the rule reaches only bulma-carousel's own slides, not `Carousel`'s. So in the
+  app a ratio image stretches its photo instead. Keep the class and give it the rule in the app's
+  stylesheet:
+
+  ```css
+  .image.is-covered img {
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+  }
+  ```
+
 ### `<html>` and `<body>`: `html-document:<name>`
 
 The app's document has its own `<html>` and `<body>`, which a component can't reach.
@@ -719,9 +849,9 @@ than `this`. A `<body onload>` becomes an effect.
   report entry.
 
   A link to another page beside this one should point at the route that page becomes: the
-  router's, in an app with one. A site of static pages, with no router to join, can route on the
-  URL's hash in a small module of its own and install no router package, so every page still
-  opens from a static host as it is:
+  router's, in an app with one. A multi-page site of static pages, with no router to join, can do
+  its routing on the URL's hash in a small module of its own and install no router package, so
+  every page still opens from a static host as it is:
 
   ```ts
   // router.ts: the page the address's hash names (`#/about`).
@@ -809,8 +939,9 @@ rest.
 ### 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.
+  writes over a file. That makes a second run on the page change nothing. To carry on from the
+  module's TODOs, run the codemod on the module itself, which is where each TODO from the page
+  says to re-run ("re-run on `index.tsx`"). 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
@@ -825,6 +956,11 @@ A page with no Bulma component class writes nothing and reports nothing.
 
 - Helper classes on a `<div>` (`<div className="is-flex mt-4">`): bestax has no plain `<div>`
   wrapper, and the classes are valid Bulma, so the element stays.
+- Helper classes on a table's rows and cells (`<th className="has-text-centered">`): the codemod
+  converts the `.table` and leaves the `<thead>`, `<tbody>`, `<tfoot>`, `<tr>`, `<th>` and `<td>`
+  inside it as they are. To write them by hand, `Table.Thead`, `Table.Tbody`, `Table.Tfoot`,
+  `Table.Tr`, `Table.Th` and `Table.Td` render each tag as it is and take the helper props, and
+  `Table.Th` and `Table.Td` take `isAligned` for their alignment (`<Table.Td isAligned="right">`).
 - `.help`, `.label`, `.loader` and the other classes in the component map's "left alone" list.
 - A class with no bestax prop on a converted element: it stays in `className`. That covers
   v1's `marginless` and `paddingless`, which have the same rules as `m-0` and `p-0` under

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

@@ -189,7 +189,7 @@ 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`, `Timeline`,
+`Navbar.Item`, `Navbar.Link`, `ScrollArea`, `SegmentedControl`, `SegmentedControl.Segment`, `Sidebar`, `Splitter`, `Splitter.Pane`, `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.

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

@@ -165,8 +165,8 @@ The same TODO marks a `Heading` that sets `size` and `textSize` both: drop `size
 bestax components don't take `domRef`, but many forward a plain `ref` — 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`, `Timeline`, `Timeline.Item`, `Toast`, `ToggleButton`, `TreeView` and `TreeView.Item`. On
+`Navbar.Dropdown`, `Navbar.Item`, `Navbar.Link`, `ScrollArea`, `SegmentedControl`, `SegmentedControl.Segment`,
+`Sidebar`, `Splitter`, `Splitter.Pane`, `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.

package/templates/skills/bestax-optimize/references/modular-build.md

@@ -81,7 +81,9 @@ is **more complete** than the docs page's Option C example, which omits several)
 **Components** (`@allxsmith/bestax-bulma/scss/components/<name>`):
 `loading`, `collapse`, `tooltip`, `popover`, `hovercard`, `contextmenu`, `steps`, `sidebar`,
 `toast`, `dialog`, `carousel`, `tabs`, `menu`, `reveal`, `avatar`, `avatars`, `badge`,
-`emptystate`, `timeline`, `treeview`
+`emptystate`, `timeline`, `treeview`, `scrollarea`
+
+**Layout** (`@allxsmith/bestax-bulma/scss/layout/<name>`): `splitter`
 
 **Form** (`@allxsmith/bestax-bulma/scss/form/<name>`):
 `checkbox`, `radio`, `switch`, `slider`, `numberinput`, `pininput`, `rate`, `autocomplete`,

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

@@ -16,9 +16,10 @@ Recolor a brand color by overriding its **hue/saturation/lightness trio**
 follow the hue and saturation, at lightnesses the trio doesn't set. Among those, the stylesheet's
 build picked the label on a solid color (`--bulma-<color>-invert-l`) and the color's text on the
 page (`--bulma-<color>-on-scheme-l`, which for `link` is every link) for contrast with the color
-it was built with, so when the new color reads lighter or darker than the built one, set them in
-your CSS as well, or labels and text lose their contrast (`references/css-variables.md`,
-"Colors").
+it was built with, so when the new color reads lighter or darker than the built one, set them as
+well, or labels and text lose their contrast. `Theme`'s `bulmaVars` takes both, and on an
+`isRoot` `Theme` the on-scheme one takes a value per scheme, `{ light, dark }`
+(`references/css-variables.md`, "Colors").
 
 Choose an override path:
 
@@ -36,10 +37,12 @@ For **dark mode**, pass `colorMode` to `Theme` (`'light' | 'dark' | 'system'`).
 `data-theme` attribute on `<html>` (plus `data-<prefix>theme` inside a `ConfigProvider` with a
 `classPrefix`, which the prefixed flavors read), flipping the light/dark scheme — global, even on a scoped
 `Theme`; `'system'` follows the OS `prefers-color-scheme`. Drive it from state on the app-root
-`Theme`: `<Theme isRoot colorMode={mode}>`. `Theme` writes the attribute from an effect, after a
-client-rendered app's first paint, so the scheme of that first frame comes from `index.html`:
-`data-theme` on the `<html>` for a scheme that never changes, or an inline `<head>` script that
-writes the visitor's saved choice for a toggle (`examples/dark-mode.tsx`).
+`Theme`: `<Theme isRoot colorMode={mode}>`. `Theme` writes the attribute, and an `isRoot` Theme's
+variables, before the browser paints what it rendered, but the page can paint before the app's
+script runs at all, so the scheme of that first frame comes from `index.html`: `data-theme` on
+the `<html>` for a scheme that never changes, or an inline `<head>` script that writes the
+visitor's saved choice for a toggle (`examples/dark-mode.tsx`). A server render includes neither,
+so a server-rendered page sets what it needs from its first paint in `index.html` and CSS.
 
 ## Contrast rules (dark mode is on by default)
 
@@ -52,8 +55,8 @@ color tokens or fixed-color surfaces exist:
 
 - **Single-mode design → pin the scheme on `<html>`.** `<html lang="en" data-theme="light">` (or
   `"dark"`) in `index.html`, so the first paint has it and an OS preference can never invert text
-  out from under the fixed palette. `<Theme isRoot colorMode="light">` alone sets it only after
-  that paint, which shows the OS scheme first.
+  out from under the fixed palette. `<Theme isRoot colorMode="light">` alone sets it only once
+  the app's script runs, and the page can show the OS scheme before that.
 - **Both modes → no exposed fixed tokens.** Derive custom tokens from scheme variables
   (`--my-canvas: var(--bulma-scheme-main)`) — or flip them yourself under **both** dark-mode
   paths: `[data-theme='dark']` **and** `@media (prefers-color-scheme: dark)` scoped to
@@ -127,7 +130,7 @@ Nest `Theme` and `ConfigProvider` together at the root (order doesn't matter).
 
 ## Checklist
 
-- [ ] Recolor brand colors via the HSL trio (`*-h` / `*-s` / `*-l`), not by hard-coding hex on components; a color that reads lighter or darker than the built one also sets `*-invert-l` and `*-on-scheme-l` in CSS.
+- [ ] Recolor brand colors via the HSL trio (`*-h` / `*-s` / `*-l`), not by hard-coding hex on components. A color that reads lighter or darker than the built one also sets `*-invert-l` and `*-on-scheme-l`, through `Theme bulmaVars` (the on-scheme one per scheme, on an `isRoot` Theme) or CSS.
 - [ ] Apply a global theme once with `<Theme isRoot>` (or `:root`); use scoped `<Theme>` for one-off sections.
 - [ ] Set non-color tokens (radius, fonts, sizes) through `bulmaVars` or `:root`; a custom `--bulma-family-*` needs its font actually loaded (`index.html` `<link>` or an `@fontsource` import).
 - [ ] Implement dark mode with `data-theme` on `<html>` (plus `data-<prefix>theme` inside a `ConfigProvider` with a `classPrefix`, which the prefixed flavors read); do not expect a shipped dark-mode component.

package/templates/skills/bestax-theming/examples/dark-mode.tsx

@@ -2,12 +2,13 @@
 // the visitor's choice.
 //
 // Bulma reads the scheme from `data-theme` on <html>. `Theme colorMode` writes
-// that attribute from an effect, which runs after a client-rendered app's
-// first paint, so on its own the page shows the OS scheme for a frame and then
-// flips. The scheme for that first frame comes from a script in index.html,
-// which writes the saved choice, or else the OS preference, before anything
-// renders. Put it inside <head> as a plain inline script, not
-// `type="module"`, so it runs before the body renders:
+// that attribute before the browser paints what the app rendered, but only
+// once the app's script runs, and the page can paint before that, so on its
+// own it can show the OS scheme for a frame and then flip. The scheme for
+// that first frame comes from a script in index.html, which writes the saved
+// choice, or else the OS preference, before anything renders. Put it inside
+// <head> as a plain inline script, not `type="module"`, so it runs before the
+// body renders:
 //
 //   <script>
 //     // Bulma's scheme on <html> before the first paint: the saved choice,

package/templates/skills/bestax-theming/examples/theme-config.tsx

@@ -12,9 +12,10 @@
 // Of those built lightnesses, the label on a solid color
 // (--bulma-<color>-invert-l) and the color's text on the page
 // (--bulma-<color>-on-scheme-l, which for `link` is every link) were picked
-// for contrast. A color that reads lighter or darker than the stylesheet's
-// own needs those set in your CSS too, which Theme does not do;
-// references/css-variables.md ("Colors") says how.
+// for contrast with the stylesheet's own color. A color that reads lighter or
+// darker than that one sets them too, through bulmaVars. On an isRoot Theme
+// the on-scheme one takes a value for each scheme. references/css-variables.md
+// ("Colors") says how to pick them.
 import type { ReactNode } from 'react';
 import {
   Theme,
@@ -37,6 +38,12 @@ export function ThemedApp({ children }: { children: ReactNode }) {
       // Anything without a named prop goes through `bulmaVars`, keyed by the real
       // --bulma-* variable names (string values).
       bulmaVars={{
+        // Purple text reads darker than the stylesheet's blue at the same
+        // lightness, so on a dark page it needs a lighter shade than the one
+        // built for the blue. Each scheme gets its own, and these read at 4.5:1
+        // or more on Bulma's white and near-black pages. The white label the
+        // blue was built with still reads on this purple, so the invert stays.
+        '--bulma-primary-on-scheme-l': { light: '41%', dark: '65%' },
         '--bulma-radius': '0.75rem',
         '--bulma-radius-large': '1.25rem',
         // 'Inter' must actually be loaded (index.html <link> or an @fontsource