create-bestax 4.2.18 → 4.2.19

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

@@ -72,7 +72,9 @@ Sizes are `1` to `12`, `full`, `half`, `one-third`, `two-thirds`, `one-quarter`,
 
 bestax picks the heading from `size` (`size="3"` renders an `<h3>`) unless `as="p"`. So on an
 `<h2>`, `is-4` stays a class and the element becomes `<Title as="h2" className="is-4">`, which
-renders the same `<h2>`.
+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.
 
 ### Other components
 
@@ -85,6 +87,8 @@ renders the same `<h2>`.
 | `.content` → `Content`                                                       | `is-small`, `is-medium`, `is-large`                                                                                                              | `size`                                                                                            |
 | `.delete` → `Delete`                                                         | `is-small`, `is-medium`, `is-large`                                                                                                              | `size`                                                                                            |
 | `.field` → `Field`                                                           | `is-horizontal`, `is-grouped`, `has-addons`, `is-narrow`                                                                                         | `horizontal`, `grouped`, `hasAddons`, `narrow`                                                    |
+| `.field` → `Field`                                                           | `has-addons-centered`, `has-addons-right`, beside `has-addons`                                                                                   | `hasAddons="centered"`, `hasAddons="right"`, which render both classes                            |
+| `.field` → `Field`                                                           | `is-grouped-centered`, `is-grouped-right`, `is-grouped-multiline`, beside `is-grouped`                                                           | `grouped="centered"`, `grouped="right"`, `grouped="multiline"`, which render both classes         |
 | `.grid` → `Grid`                                                             | `is-gap-{step}`, `is-column-gap-{step}`, `is-row-gap-{step}`, `0` to `8` in half steps (`is-gap-1.5`)                                            | `gap`, `columnGap`, `rowGap`                                                                      |
 | `.grid` → `Grid`                                                             | `is-col-min-{1-32}`                                                                                                                              | `minCol` (a number: `minCol={8}`)                                                                 |
 | `.fixed-grid` → `Grid isFixed` (folded)                                      | `has-{1-12}-cols`, `has-{1-12}-cols-{viewport}`, `has-auto-count`                                                                                | `fixedCols`, `fixedCols{Viewport}` (numbers: `fixedCols={3}`), `fixedCols="auto"`                 |
@@ -103,7 +107,8 @@ renders the same `<h2>`.
 | the `<select>` inside `.select`                                              | `is-hovered`, `is-focused`                                                                                                                       | `isHovered`, `isFocused`                                                                          |
 | `.hero` → `Hero`                                                             | `is-primary`, `is-link`, `is-info`, `is-success`, `is-warning`, `is-danger`, `is-black`, `is-white`, `is-light`, `is-dark`                       | `color`                                                                                           |
 | `.hero` → `Hero`                                                             | `is-small`, `is-medium`, `is-large`, `is-fullheight`, `is-fullheight-with-navbar`                                                                | `size`                                                                                            |
-| `.image` → `Image`                                                           | `is-16x16`, `is-24x24`, `is-32x32`, `is-48x48`, `is-64x64`, `is-96x96`, `is-128x128`, `is-square`                                                | `size` (a ratio such as `is-4by3` stays a class, since `size` would add `has-ratio`)              |
+| `.image` → `Image`                                                           | `is-16x16`, `is-24x24`, `is-32x32`, `is-48x48`, `is-64x64`, `is-96x96`, `is-128x128`, `is-square`                                                | `size`                                                                                            |
+| `.image` → `Image`                                                           | `is-{ratio}`, for each of the Ratios under Helper classes (`is-16by9`), but not `is-square` (see below)                                          | `size`, on the `<figure>` it renders with no `as` (see below)                                     |
 | the `<img>` inside `.image`                                                  | `is-rounded`                                                                                                                                     | `isRounded`                                                                                       |
 | `.icon` → `Icon`                                                             | `is-small`, `is-medium`, `is-large`                                                                                                              | `size`                                                                                            |
 | `.tabs` → `Tabs`                                                             | `is-centered`, `is-right`, `is-left`                                                                                                             | `align`                                                                                           |
@@ -116,7 +121,7 @@ renders the same `<h2>`.
 | `.level` → `Level`                                                           | `is-mobile`                                                                                                                                      | `isMobile`                                                                                        |
 | `.navbar` → `Navbar`                                                         | the ten `.hero` colors                                                                                                                           | `color`                                                                                           |
 | `.navbar` → `Navbar`                                                         | `is-fixed-top`, `is-fixed-bottom`                                                                                                                | `fixed` (`top`, `bottom`)                                                                         |
-| `.navbar` → `Navbar`                                                         | `is-transparent`                                                                                                                                 | `transparent`                                                                                     |
+| `.navbar` → `Navbar`                                                         | `is-transparent`, `is-spaced`, `has-shadow`                                                                                                      | `transparent`, `isSpaced`, `hasShadow`                                                            |
 | `.navbar-menu` → `Navbar.Menu`, `.navbar-item` → `Navbar.Item`               | `is-active`                                                                                                                                      | `active`                                                                                          |
 | `.navbar-dropdown` → `Navbar.DropdownMenu`                                   | `is-right`, `is-up`                                                                                                                              | `right`, `up`                                                                                     |
 | `.notification` → `Notification`                                             | `is-primary`, `is-link`, `is-info`, `is-success`, `is-warning`, `is-danger`, `is-black`, `is-white`, `is-dark`                                   | `color`                                                                                           |
@@ -130,6 +135,16 @@ renders the same `<h2>`.
 | `.tag` → `Tag`                                                               | `is-light`, `is-rounded`, `is-hoverable`                                                                                                         | `isLight`, `isRounded`, `isHoverable`                                                             |
 | `.tag` → `Tag`                                                               | `is-medium`, `is-large`                                                                                                                          | `size`                                                                                            |
 
+`is-square` sits with the fixed sizes, not the ratios. Bulma sizes it like `is-1by1`, but `Image`
+renders `size="square"` on a `<div>`, as it does a fixed size. So
+`<figure className="image is-square">` becomes `<Image as="figure" size="square">`, while
+`<figure className="image is-1by1">` becomes `<Image size="1by1">`.
+
+A ratio converts to identical markup only on a bestax-bulma whose `Image` writes nothing but the
+ratio class on its container. An older one also writes `has-ratio` there, which Bulma reads only
+on a child, so the page looks the same, unless that `.image` sits inside another ratio `.image`,
+which then stretches it to fill. Upgrade bestax-bulma, or keep that ratio as a class.
+
 `Progress` takes `value` and `max` as numbers: `value="40"` becomes `value={40}`. An
 expression (`value={percent}`) carries over as written, so if it holds a string the migrated
 file fails to typecheck while still rendering the same; wrap it in `Number(…)`. `Delete`
@@ -137,14 +152,14 @@ converts only with `type` and `aria-label` set (see `defaults:<Target>` in the u
 and a `type="button"` is dropped, since bestax renders it by itself. `Card.Header.Icon` likewise
 converts only with an `aria-label` and a `type` of `button`, `submit` or `reset`, since it renders
 `aria-label="more options"` and `type="button"` otherwise.
-`.tag`'s `is-delete` stays a class: `isDelete` turns the tag into a `<button>`. `.navbar`'s
-`is-spaced` and `has-shadow`, and a `.navbar-item`'s `has-dropdown` and `is-hoverable`, stay
-classes too: bestax has no prop for them on those components. So do a `.field`'s
-`has-addons-centered`, `has-addons-right` and `is-grouped-*`, because the `hasAddons` and
-`grouped` values that render them render `has-addons` and `is-grouped` as well, and an input's,
-textarea's or select's color, because `color` renders `has-text-<color>` on it too. On a
-`.columns`, the gap helpers (`is-gap-*`, `is-column-gap-*`, `is-row-gap-*`) stay classes as well:
-`Columns`' own `gap` is its gutter (`is-<step>`), and it leaves the column and row gap helpers out.
+`.tag`'s `is-delete` stays a class: `isDelete` turns the tag into a `<button>`. A
+`.navbar-item`'s `has-dropdown` and `is-hoverable` stay classes too, since bestax has no prop for
+them on that component. So do a `.field`'s `has-addons-centered`, `has-addons-right` and
+`is-grouped-*` without `has-addons` or `is-grouped` beside them, because the `hasAddons` and
+`grouped` values that render them render those as well, and an input's, textarea's or select's
+color, because `color` renders `has-text-<color>` on it too. On a `.columns`, the gap helpers
+(`is-gap-*`, `is-column-gap-*`, `is-row-gap-*`) stay classes as well: `Columns`' own `gap` is its
+gutter (`is-<step>`), and it leaves the column and row gap helpers out.
 
 ## Helper classes
 
@@ -152,7 +167,10 @@ These convert on every component above and on the plain-tag wrappers.
 
 Colors are `primary`, `link`, `info`, `success`, `warning`, `danger`, `black`, `black-bis`,
 `black-ter`, `grey-darker`, `grey-dark`, `grey`, `grey-light`, `grey-lighter`, `white`,
-`white-bis`, `white-ter`, `light`, `dark`, `inherit` and `current`. Gap steps are `0` to `8` in
+`white-bis`, `white-ter`, `light`, `dark`, `inherit` and `current`. Shades are `00` to `95` in
+steps of five, `invert`, `light`, `dark`, `soft`, `bold` and `on-scheme`, on the colors Bulma
+shades: `primary`, `link`, `info`, `success`, `warning`, `danger`, `black`, `white`, `light` and
+`dark`. Gap steps are `0` to `8` in
 half steps (`0`, `0.5`, `1`, … `7.5`, `8`). Overflow values are `auto`, `clip`, `hidden`, `scroll`
 and `visible`. Ratios are `1by1`, `5by4`, `4by3`, `3by2`, `5by3`, `16by9`, `2by1`, `3by1`,
 `4by5`, `3by4`, `2by3`, `3by5`, `9by16`, `1by2` and `1by3`.
@@ -161,8 +179,10 @@ and `visible`. Ratios are `1by1`, `5by4`, `4by3`, `3by2`, `5by3`, `16by9`, `2by1
 | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
 | `m-{n}`, `mt-{n}`, `mr-{n}`, `mb-{n}`, `ml-{n}`, `mx-{n}`, `my-{n}` (`0` to `6`, `auto`)                  | `m`, `mt`, `mr`, `mb`, `ml`, `mx`, `my`                                                                                          |
 | `p-{n}`, `pt-{n}`, `pr-{n}`, `pb-{n}`, `pl-{n}`, `px-{n}`, `py-{n}`                                       | `p`, `pt`, `pr`, `pb`, `pl`, `px`, `py`                                                                                          |
+| `is-marginless`, `is-paddingless` (Bulma 0.9's, which v1 removed)                                         | `m="0"`, `p="0"`, which render v1's `m-0` and `p-0`                                                                              |
 | `has-text-{color}`                                                                                        | `textColor` (on `Menu`, `Menu.Label`, `Menu.List` and `Table`, `color`)                                                          |
 | `has-background-{color}`                                                                                  | `bgColor` (on `Menu`, `Menu.Label`, `Menu.List`, `Tag`, `File`, `InputBase`, `TextAreaBase` and `SelectBase`, `backgroundColor`) |
+| `has-text-{color}-{shade}`, `has-background-{color}-{shade}`                                              | the same color prop, with `colorShade` or `backgroundColorShade` (`textColor="primary" colorShade="on-scheme"`)                  |
 | `is-size-1` … `is-size-7`, and `-{viewport}`                                                              | `textSize`, `textSize{Viewport}`                                                                                                 |
 | `has-text-centered`, `-justified`, `-left`, `-right`, and `-{viewport}`                                   | `textAlign`, `textAlign{Viewport}`                                                                                               |
 | `is-capitalized`, `is-lowercase`, `is-uppercase`, `is-italic`                                             | `textTransform`                                                                                                                  |
@@ -221,10 +241,21 @@ Some classes stay put because of how bestax renders them:
   instead of as its own class.
 - `is-hidden` becomes `visibility="hidden"`, which renders the same class and doesn't interact
   with `display`.
+- `is-marginless` and `is-paddingless` are the only classes a conversion changes: they style
+  nothing under v1, so they become the prop of the v1 helper that does their job. A live class
+  for the same prop keeps it, whichever is written first, so beside `p-2` the class stays with a
+  `legacy:` TODO, and so it does wherever the element stays markup. Beside a class for another
+  prop, such as `px-2`, it still converts: v1 puts every side and axis class after `p-0`, so
+  `px-2` keeps its sides.
 
 ## Classes that stay classes
 
-Color shades (`has-text-primary-65`), the `-touch` and `-only` breakpoints of text size and
-alignment, Grid and `.image` modifiers away from their own element, an `.image` ratio, and the
-Bulma helpers bestax has no prop for (`is-display-*`, `is-visibility-*`, `is-float-*`,
-`is-clear-*`, …) stay in `className`. They render exactly as before.
+A color shade one color and one shade can't write (`has-text-primary-100`, the `-invert` of a
+shade such as `has-text-primary-30-invert`, a shade of the `text` color), a shade or color for a
+prop another class already wrote (`has-text-primary-30 has-text-info-40` keeps the second), the
+palettes and `is-bold` and `is-soft`, the `-touch` and `-only` breakpoints of text size and
+alignment, Grid and `.image` modifiers away from their own element, v1's `marginless` and
+`paddingless` (the rules of `m-0` and `p-0` under other names), and the Bulma helpers bestax has
+no prop for (`is-display-*`, `is-visibility-*`, `is-float-*`, `is-clear-*`, …) stay in
+`className`. They render exactly as before. An `.image` size or ratio away from its `.image` also
+gets a `modifier:image` TODO, since Bulma styles it only there.

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

@@ -92,7 +92,29 @@ give the `<nav>` both, with your own label if you like. `Breadcrumb` renders
 makes one named by `aria-label` or `aria-labelledby` an image, with `role="img"`. Give a decorative
 `.icon` `aria-hidden="true"`, and a meaningful one an `aria-label` that says what it means and
 `role="img"`. One whose name is an expression may render with no name, so it needs a `role` of its
-own.
+own. `Icon` writes `aria-hidden` on the `.icon` and never on the `<i>` inside. Font Awesome's own
+markup, `<i class="fas fa-envelope" aria-hidden="true">` alone in a `.icon` that carries
+nothing but its classes, an `id`, a `style` and `data-` attributes, converts anyway, with the
+attribute moved up onto the `.icon`, an exception to identical markup. A `.icon` that
+carries anything more never takes the move. A `role` or `tabIndex` written out converts around
+the `<i>` as it is, since `Icon` then hides nothing itself. Anything else, or either of those as
+an expression, keeps the `.icon` as markup: a `title` or a description would be hidden with it,
+and beside a `role` or `tabIndex` `Icon` writes no `aria-hidden` at all. Give a meaningful one an
+`aria-label` and `role="img"`, or drop the attribute from a decorative one, then re-run. An `<i>`
+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
+`<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
+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
 `Pagination.Previous`, `Pagination.Next` and `Pagination.Link` render `tabIndex={0}`, so give each
 element the attribute it's missing.
@@ -151,6 +173,32 @@ or when what's inside is an expression or text, since `Image` renders an `<img>`
 its children come out empty. Keep it as markup, or write the `Image` by hand if the expression
 never is.
 
+A `<label>` beside the `<select>` in a `.select` (a visually hidden one, say) is that case too,
+since `SelectBase` renders no label. bestax's convenience `Select` takes it: the label's text as
+`label` and its classes in `labelProps`, and it points the label at the `<select>`'s `id` itself.
+A computed `className` on the label goes in `labelProps` as the same expression, since it may be
+what hides the label, and so does what a spread on it carries. `Select` renders the `.select`
+inside a `Field` and a `Control`, so convert the two by hand and check the layout:
+
+```tsx
+<Select
+  id="language"
+  size="small"
+  label="Select language"
+  labelProps={{ className: 'is-sr-only' }}
+>
+  <option>English</option>
+  <option>French</option>
+</Select>
+```
+
+That holds only where the `.select` isn't inside a `.field` or a `.control` (or a `Field` or
+`Control`). Inside a `Field`, `Select` renders no label of its own and drops `label` and
+`labelProps`, so the select would lose its name; inside a bare `Control`, it puts its label's
+`.field` inside the `.control`. There, keep the label the page's: move the `<label>` out beside
+the `.select`, its `htmlFor` on the `<select>`'s `id`, or give the `<select>` an `aria-label` in
+its place, then re-run, and the `.select` converts to `SelectBase`.
+
 A menu item is the same from the `<li>`'s side: `Menu.Item` renders the `<a>` inside it, and a
 `Menu.List` after that, so an item converts only when its `<li>` holds one `<a>` and at most one
 `<ul>` after it, with nothing else beside them. Text or a comment beside the `<a>` keeps it as
@@ -164,13 +212,14 @@ element converts only holding exactly that (`&hellip;` or the character), and cl
 
 On an `.icon-text`, `IconText` builds its icons from props and wraps each text in a `<span>` of
 its own, so it converts only when its children are `.icon`s, each followed by at most one bare
-`<span>` of static text. Each `.icon` has to convert to `Icon` on its own, so one with no
-`aria-label` gets a `defaults:Icon` TODO of its own first: give it one that says what the icon
-means, then re-run. Its `<i>` has to be bare and empty and name one Font Awesome or Material Design
-Icons glyph, so an `aria-hidden` on the `<i>`, another icon font, or anything between the children
-keeps it as markup, and the `.icon`s inside convert on their own. The markup renders the same as
-it is; to use `IconText` anyway, write it by hand with `iconProps={{ name: ... }}` (the
-`bestax-icons` skill covers `Icon`'s library and name props).
+`<span>` of static text. Each `.icon` has to convert to `Icon` on its own, so one with neither
+`aria-hidden` nor `aria-label` gets a `defaults:Icon` TODO of its own first: hide a decorative one,
+or give a meaningful one a name, then re-run. Its `<i>` has to be empty, carry nothing but Font
+Awesome's own `aria-hidden`, which moves up as it does on a `.icon` alone, and name one Font
+Awesome or Material Design Icons glyph, so another attribute on the `<i>`, another icon font, or
+anything between the children keeps it as markup, and the `.icon`s inside convert on their own. The markup renders the same as it is; to use
+`IconText` anyway, write it by hand with `iconProps={{ name: ... }}` (the `bestax-icons` skill
+covers `Icon`'s library and name props).
 
 On a `.file`, `File` renders the whole tree from props, so it converts only when its tree is the one
 `File` renders: one bare `.file-label` `<label>` holding a `.file-input` `<input type="file">`, a
@@ -286,6 +335,25 @@ in a menu item gets this TODO too. For the `<a>`, a condition on `is-active` is
 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.
 
+## An element it converted: `second-component:<Target>`
+
+The element carried a second Bulma component class (`<div className="columns box">`), and an
+element converts to one component. It became the one whose component fits its tag best (the
+tag it renders with the element's classes and no `as`, such as the `<figure>` an `.image`
+ratio picks, then one it reaches through `as`), the layout one or a component's part between
+equals, and the other class stayed in `className`, which renders the same. The TODO names the component that class belongs to. A raw component
+class on a bestax component is what the ESLint plugin's `no-bulma-component-class` reports, so
+move it to a component of its own:
+
+- **Most classes**: give `<Target>` an element of its own, around the converted one or inside
+  it, and drop the class: `<Box><Columns>…</Columns></Box>`. Two elements space differently
+  from one (a `.columns` has negative side margins, which a `.box` on the same element shares
+  and one around it doesn't), so check the layout.
+- **`second-component:Container`**: where `.container` is only there to center the element, as
+  it often is on a sized `.image`, write `mx="auto"` in its place
+  (`<Image size="128x128" mx="auto">`), which centers it and does nothing else `.container`
+  does. Otherwise wrap the element in a `Container`. Either way, check the layout.
+
 ## A family it leaves as markup: `family:<class>`
 
 The bestax component renders parts of its own, or adds attributes, so a one-element-at-a-time
@@ -320,9 +388,9 @@ in the browser:
 - **`family:message`**: `Message` always wraps its children in `.message-body`.
 - **`family:panel-icon`**: `Panel.Icon` renders through `Icon`, which always writes an
   `aria-label`, so write `<Panel.Icon>` by hand with the `<i>` inside. The rest of a panel converts,
-  but for a `<label>` or `<div>` `.panel-block`, which stays markup with no TODO: bestax renders
-  those as `Panel.CheckboxBlock`, `Panel.InputBlock` and `Panel.ButtonBlock`, which build their own
-  contents from props.
+  a `<label>` or `<div>` `.panel-block` included, as `Panel.Block` with `as` and its contents as
+  written. `Panel.CheckboxBlock`, `Panel.InputBlock` and `Panel.ButtonBlock` build the usual
+  checkbox, search and button blocks from props, if you would rather write those by hand.
 
 ## A class Bulma v1 removed: `legacy:<class>`
 
@@ -330,6 +398,24 @@ in the browser:
 0.9 to 1 guide shows the translation. Until then the element has no styles at all under
 Bulma v1.
 
+`legacy:is-marginless`, `legacy:is-paddingless`: v1 removed both, so they style nothing.
+Wherever the element converts, the codemod writes them as `m="0"` and `p="0"`, which render
+v1's `m-0` and `p-0`, and says nothing. The TODO comes only where the class stays: on an
+element that stays markup (a `<div>` with no component class, or one refused for another
+reason), or beside a class for the same prop (`p-2`, before it or after), which keeps the prop
+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>`
+
+`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
+can't see may be the `.image`.
+
 ## A whole file it left alone
 
 These come only when the file has an element the codemod would convert (a computed className
@@ -359,7 +445,8 @@ Run on an HTML page (`bestax-migrate bulma-classes page.html`, or a folder with
 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
+the line it came from (`(index.html:42)`), or every line, for a TODO several elements share
+(`(index.html:42, 57)`). 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.
 
@@ -373,6 +460,11 @@ A component renders into the `<body>` of the app's own document, so nothing in t
   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:csp`**: a `<meta http-equiv="Content-Security-Policy">`. Its policy was written for
+  what the page loads, and copied into `index.html` as it is, it can block what the app loads
+  instead: a Vite dev server runs an inline script for React's fast refresh and opens a socket for
+  hot reloading, and the build serves the app's own scripts, styles and fonts. Write the app's own
+  policy, best sent as a response header, and try it under both the dev server and the build.
 - **`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.
@@ -412,15 +504,18 @@ neither, so load what the app still needs once for the whole app, from its entry
     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
+  writes its classes (`fas fa-<name>`, or the style its `variant` names) 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
+  - 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"`).
   - A kit (`kit.fontawesome.com`): keep loading it from `index.html`, or install Font Awesome from
@@ -432,23 +527,23 @@ neither, so load what the app still needs once for the whole app, from its entry
   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 |
+  | Extension                                               | bestax                                                                                 |
+  | ------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+  | `bulma-carousel`                                        | `Carousel`, with a `CarouselItem` for each slide and `itemsToShow` for several in view |
+  | `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,
@@ -531,8 +626,24 @@ read for the burger, a carousel and a theme toggle too, and its TODO names the f
   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.
+  children and renders its own arrows and indicators (`autoplay` for a timed one). For several
+  slides in view, set `itemsToShow`, with a variant per viewport (`itemsToShowMobile`,
+  `itemsToShowTablet`, …), and `itemsToScroll`: bulma-carousel calls them `slidesToShow` and
+  `slidesToScroll`. bulma-carousel's `breakpoints` replace both at and below pixel widths of its
+  own (each entry's `changePoint`), and a page that sets none gets its defaults: 1 slide up to
+  480px, 2 up to 640px and 3 up to 768px, each scrolling as many, so `slidesToShow` applies only
+  from 769px up. Below that the defaults decide whatever `slidesToShow` says: a phone shows 1
+  slide, and a page that sets `slidesToShow: 1` shows 2 or 3 between a phone's width and a
+  tablet's. A page's own `breakpoints` replace the defaults, and an empty list turns them off.
+  `Carousel` has no pixel widths: `itemsToShowMobile` covers every width below 769px, where all
+  of those defaults sit, and the wider variants start at Bulma's breakpoints. So set
+  `itemsToShow` to the page's `slidesToShow`, and `itemsToShowMobile` to what the page shows on
+  a phone (1 under the defaults) where that differs; one `itemsToScroll` covers every width. To
+  keep the steps bulma-carousel takes between those widths, compute `itemsToShow` from the
+  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.
 - **`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:
@@ -540,8 +651,11 @@ read for the burger, a carousel and a theme toggle too, and its TODO names the f
   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
+  bestax-theming skill covers `Theme` and `colorMode`, and its `examples/dark-mode.tsx` has the
+  script and the app's side.
+- **`html-script:json-ld`** is structured data for search engines. Data about the whole site, or
+  about a single-page app's one page, goes in the app's `index.html` as it is, where a crawler that
+  runs no JavaScript still reads it. Data that differs from page to page goes 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,
@@ -558,8 +672,10 @@ The app's document has its own `<html>` and `<body>`, which a component can't re
   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>`.
+  the page's color scheme. Put it on the `<html>` in `index.html`, where the first paint has it.
+  For a scheme the visitor switches, `Theme colorMode` writes the choice only after that paint,
+  so write a saved one before it too, as `html-script:theme` says and the bestax-theming skill's
+  `examples/dark-mode.tsx` does.
 - **`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
@@ -598,9 +714,51 @@ than `this`. A `<body onload>` becomes an effect.
 - **`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.
+  import it. 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.
+
+  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:
+
+  ```ts
+  // router.ts: the page the address's hash names (`#/about`).
+  import { useEffect, useState } from 'react';
+
+  export const routes = { home: '#/', about: '#/about' } as const;
+  export type Route = keyof typeof routes;
+
+  function routeOf(hash: string): Route {
+    const found = (Object.keys(routes) as Route[]).find(
+      route => routes[route] === hash
+    );
+    return found ?? 'home';
+  }
+
+  export function useRoute(): Route {
+    const [route, setRoute] = useState(() => routeOf(window.location.hash));
+    useEffect(() => {
+      const onHashChange = () => {
+        const hash = window.location.hash;
+        // Only `#/…` (or no hash) names a page; leave an in-page anchor such
+        // as `#features`, or a placeholder `#`, to the browser.
+        if (hash !== '' && !hash.startsWith('#/')) return;
+        setRoute(routeOf(hash));
+        window.scrollTo(0, 0); // a new page starts at the top, as it did
+      };
+      window.addEventListener('hashchange', onHashChange);
+      return () => window.removeEventListener('hashchange', onHashChange);
+    }, []);
+    return route;
+  }
+  ```
+
+  The app renders the page the route names, from the modules the pages became
+  (`const Page = { home: HomePage, about: AboutPage }[useRoute()]`), with the parts the pages
+  share around it, and a link to `about.html` takes `href={routes.about}`.
+
 - **`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.
@@ -610,6 +768,12 @@ than `this`. A `<body onload>` becomes an effect.
 - **`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:stray`**: a stray character in a tag, with no letter or digit in it (`\` in
+  `<figure class="image" \>`, a typo for `/>`), which the browser read as the name of an empty
+  attribute. It was left out, so there is nothing to port; delete it from the page too.
+- **`html-attr:ignored`**: an attribute HTML gives the element no meaning for, so the browser
+  ignored it, and React's types reject it there: `type` on a `<textarea>`. It was left out, so the
+  module typechecks. Nothing reads it, unless a stylesheet or script of the page's selects on it.
 - **`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
@@ -632,9 +796,15 @@ than `this`. A `<body onload>` becomes an effect.
 
 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`.
+more there are, except a duplicate attribute (below). 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`.
+
+A duplicate attribute on an element gets an entry of its own, naming the attribute, the copy the
+element keeps (the first) and the one the browser drops (`placeholder="Email"` kept,
+`placeholder="Your email"` dropped). The module has the kept one, so if the page meant the other,
+change the value there. One the codemod can't name, such as one on an end tag, is counted with the
+rest.
 
 ### The page itself: `html-file:<case>`
 
@@ -656,7 +826,9 @@ 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.
 - `.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`.
+- 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
+  other names, so they stay as written while the element converts on its other classes.
 
 ## After the codemod
 

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

@@ -26,11 +26,18 @@ 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. 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`.
+  `--bulma-primary-*` CSS variables / a Sass build. With the variables, set
+  `--bulma-primary-invert-l` and `--bulma-primary-on-scheme-l` along with `--bulma-primary-h`,
+  `--bulma-primary-s` and `--bulma-primary-l`. The first is the lightness of the label on a
+  primary surface and the second of primary text on the page, and bestax's build fixes both for
+  its dark blue, so a light primary set through the trio alone keeps white labels and pale text.
+  To get stock Bulma's turquoise back on top of `bestax.css`, copy those five from Bulma's own
+  `bulma/css/bulma.css`. The on-scheme lightness differs between its light and dark schemes, so
+  set each scheme's value where the app shows both; the `bestax-theming` skill's
+  `references/css-variables.md` ("The lightnesses Bulma's build picks for contrast") shows how,
+  and what reads each one. Text the page colors with `has-text-primary` converts to
+  `textColor="primary"`, which reads the trio's own lightness, under 2:1 on white for turquoise
+  (in stock Bulma too); add `colorShade="on-scheme"` to take the shade made for text.
 
 - **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

@@ -88,19 +88,25 @@ several of those narrow it to specific tags (`Footer` is `'footer' | 'div'`, `Co
 `'div' | 'p'`). 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' \| 'p'`             |
-| `Menu.Item`                  | any element type           |
-| `Dropdown.Item`              | `'a' \| 'div' \| 'button'` |
-| `Navbar.Item`, `Navbar.Link` | any element type           |
+| 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' \| 'p'`                                                                          |
+| `Menu.Item`                  | any element type                                                                        |
+| `Dropdown.Item`              | `'a' \| 'div' \| 'button'`                                                              |
+| `Navbar.Item`, `Navbar.Link` | any element type                                                                        |
+| `Container`                  | `'div' \| 'main' \| 'section' \| 'article' \| 'aside' \| 'header' \| 'footer' \| 'nav'` |
+| `Hero`                       | `'section' \| 'div' \| 'main' \| 'header' \| 'footer' \| 'article' \| 'aside'`          |
+| `Hero.Head`                  | `'div' \| 'header' \| 'nav'`                                                            |
+| `Hero.Foot`                  | `'div' \| 'footer' \| 'nav'`                                                            |
+| `Panel`                      | `'nav' \| 'article' \| 'section' \| 'aside' \| 'div'`                                   |
+| `Panel.Block`                | `'a' \| 'div' \| 'label'`                                                               |
 
 Three traps worth naming, because rbx supplies `as` universally and the obvious guesses are
 wrong: