create-bestax 4.2.18 → 4.3.0

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

@@ -37,7 +37,7 @@ instead of hand-writing markup.
 - Raw `*Base` form exports (`InputBase`, `SelectBase`, `TextAreaBase`, …) are
   escape-hatch variants of the convenience wrappers above them; see the Form docs.
 
-102 documented components. Generated from the API docs — every exported
+106 documented components. Generated from the API docs — every exported
 component is guaranteed to appear (the generator fails if one lacks an API page).
 
 ## Elements
@@ -100,6 +100,7 @@ component is guaranteed to appear (the generator fails if one lacks an API page)
 - [Panel](https://bestax.io/docs/api/components/panel) — The `Panel` component implements Bulma's versatile panel block for React.
 - [Popover](https://bestax.io/docs/api/components/popover) — The `Popover` component opens a panel of interactive content, such as a filter form or a set of share options, anchored to the element that toggles it.
 - [Reveal](https://bestax.io/docs/api/components/reveal) — The `Reveal` component animates its content into view as it scrolls into the viewport, backed by `IntersectionObserver`.
+- [ScrollArea](https://bestax.io/docs/api/components/scrollarea) — The `ScrollArea` component renders a box whose content scrolls inside it, on the browser's own scrollbars in Bulma's colors.
 - [SegmentedControl](https://bestax.io/docs/api/components/segmentedcontrol) — The `SegmentedControl` component renders a row of buttons where only one can be on, and tells a screen reader it's a radio group.
 - [Sidebar](https://bestax.io/docs/api/components/sidebar) — The `Sidebar` component provides a slide-out navigation panel that appears from the left or right side of the screen.
 - [Steps](https://bestax.io/docs/api/components/steps) — The `Steps` component provides a multi-step progress indicator for wizard flows, checkout processes, or any multi-step workflow.
@@ -114,6 +115,7 @@ component is guaranteed to appear (the generator fails if one lacks an API page)
 - [Autocomplete](https://bestax.io/docs/api/form/autocomplete) — The `Autocomplete` component provides an input field with dropdown suggestions that filter based on user input.
 - [Checkbox](https://bestax.io/docs/api/form/checkbox) — The `Checkbox` component provides a Bulma-styled checkbox input.
 - [Checkboxes](https://bestax.io/docs/api/form/checkboxes) — The `Checkboxes` component wraps multiple `Checkbox` components in a Bulma-styled group.
+- [Combobox](https://bestax.io/docs/api/form/combobox) — The `Combobox` component is a text field with a list to pick from under it, for a searchable select, a multi-select with tags, grouped items or a server search…
 - [Control](https://bestax.io/docs/api/form/control) — The `Control` component is a Bulma-styled wrapper for form controls (`Input`, `Select`, `TextArea`, etc.), supporting icons (left/right), loading state…
 - [DateInput](https://bestax.io/docs/api/form/datetime/dateinput) — The `DateInput` component is a form input that opens a popover calendar for date selection.
 - [DateRangeInput](https://bestax.io/docs/api/form/datetime/daterangeinput) — The `DateRangeInput` component is a form input for a start and end date, picked from one popover calendar or typed into two segmented inputs.
@@ -122,6 +124,7 @@ component is guaranteed to appear (the generator fails if one lacks an API page)
 - [File](https://bestax.io/docs/api/form/file) — The `File` component provides a Bulma-styled file input, supporting color, size, boxed/fullwidth/align styles, icons, "has name", and filename display.
 - [Input](https://bestax.io/docs/api/form/input) — The `Input` component provides a Bulma-styled text input, supporting colors, sizes, rounded corners, static state, hover/focus/loading states…
 - [Numberinput](https://bestax.io/docs/api/form/numberinput) — The `Numberinput` component provides a number input with increment/decrement buttons.
+- [PinInput](https://bestax.io/docs/api/form/pininput) — The `PinInput` component is a field for a short code, such as a one-time code or a PIN, drawn as a row of boxes with one character in each.
 - [Radio](https://bestax.io/docs/api/form/radio) — The `Radio` component provides a Bulma-styled radio button input with flexible labels and helper classes.
 - [Radios](https://bestax.io/docs/api/form/radios) — The `Radios` component wraps multiple `Radio` components in a Bulma-styled group.
 - [Rate](https://bestax.io/docs/api/form/rate) — The `Rate` component provides a star/icon-based rating system.
@@ -150,6 +153,7 @@ component is guaranteed to appear (the generator fails if one lacks an API page)
 - [Level](https://bestax.io/docs/api/layout/level) — The `Level` component provides a flexible horizontal layout for your Bulma React UI, perfect for aligning items on the left and right…
 - [Media](https://bestax.io/docs/api/layout/media) — The `Media` component implements Bulma’s powerful media object layout for React.
 - [Section](https://bestax.io/docs/api/layout/section) — The `Section` component provides vertical spacing and visual separation for your Bulma React UI.
+- [Splitter](https://bestax.io/docs/api/layout/splitter) — The `Splitter` component lays out two or more panes side by side or one above the other, with a handle between each pair to drag or move by keyboard.
 
 ## Helpers
 

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

@@ -1,6 +1,6 @@
 ---
 name: bestax-form
-description: Build forms with @allxsmith/bestax-bulma — Field/Control/Label/Help composition, inputs, selects, checkboxes, radios, switches, and advanced controls (Autocomplete, Slider, Numberinput, Rate, Taginput, File, date/time). There is no form/validation library; this skill shows the components and the validate-it-yourself error pattern. Use when building a form, wiring inputs to state, or showing validation/error state.
+description: Build forms with @allxsmith/bestax-bulma — Field/Control/Label/Help composition, inputs, selects, checkboxes, radios, switches, and advanced controls (Autocomplete, Combobox, Slider, Numberinput, PinInput, Rate, Taginput, File, date/time). There is no form/validation library; this skill shows the components and the validate-it-yourself error pattern. Use when building a form, wiring inputs to state, or showing validation/error state.
 license: MIT
 ---
 
@@ -93,9 +93,11 @@ All import from `@allxsmith/bestax-bulma`. Convenience components auto-wrap Fiel
 | `Radio` / `Radios`                                      | Single radio / managed single-select group.                               |
 | `Switch`                                                | Toggle switch (`isRounded`, `isThin`, `isOutlined`, RTL).                 |
 | `File`                                                  | File upload input with label/message.                                     |
-| `Autocomplete`                                          | Input with filtered dropdown suggestions + keyboard nav.                  |
+| `Autocomplete`                                          | Free text with suggestions it filters for you, + keyboard nav.            |
+| `Combobox`                                              | A value from a list: `data` for a select, tags or groups, or parts.       |
 | `Slider`                                                | Range slider; single/dual thumbs, steps, tooltips, vertical.              |
 | `Numberinput`                                           | Numeric input with increment/decrement, min/max, step, stepper.           |
+| `PinInput`                                              | A one-time code or PIN as a row of boxes, all in one real input.          |
 | `Rate`                                                  | Star rating; `max`, `precision` (half/quarter), custom icons, `disabled`. |
 | `Taginput`                                              | Tag/chip input; suggestions, confirm keys, closable tags.                 |
 | `DateInput` / `TimeInput` / `DateTimeInput` (+ `*Base`) | Date / time / datetime pickers; month or year via `granularity`.          |
@@ -104,6 +106,27 @@ All import from `@allxsmith/bestax-bulma`. Convenience components auto-wrap Fiel
 (`NumberInput` and `TagInput` also exist as deprecated aliases of `Numberinput`/`Taginput` —
 same components; prefer the lowercase-second-word spellings.)
 
+**Autocomplete or Combobox?** A field whose text is the value, with suggestions to help type it,
+is `Autocomplete`, which filters its `data` itself. A value picked from a list is `Combobox`. Given
+`data`, it filters by label, keeps the value (`value`/`onChange`) and shows the picks as tags with
+`multiple`, so a searchable select, a multi-select or a grouped list is one element. Build it from
+parts for a server search whose answer must show unfiltered, or a "Create" item: then it keeps no
+value and never sets the field's text, so you filter the items, keep the value and set the text in
+`onSelect`.
+
+**A verification code or a PIN is `PinInput`**, not a row of one-character `Input`s with focus
+moved by hand. It holds the code in one real input under a row of boxes, so a screen reader hears
+one field named by its `label`, and paste, autofill from a text message (`autoComplete` is
+`"one-time-code"`) and password managers work as they do on any input. Give it `length` (6 by
+default), `value`/`onChange` with the code as a string, and verify in `onComplete`, which fires
+once each time a change fills the last box. It takes digits unless `type="alphanumeric"`, turns a
+digit from any script (Arabic-Indic, Persian) into its ASCII digit, drops anything else typed or
+pasted, and `isMasked` shows dots for a PIN. A paste replaces the whole code. Its default `pattern`
+asks for the full length, so `required` rejects a partial code, not just an empty one. Say the
+length in the `label` ("Enter the 6-digit code"): the boxes are hidden from a screen reader, and the
+`message` isn't tied to the input, so it isn't read on focus. Separate help text needs
+`aria-describedby` on the PinInput.
+
 ## Common props
 
 Across the convenience inputs (`Input`, `Select`, `TextArea`, and similar):
@@ -130,13 +153,15 @@ spellings compile only where they historically existed: `isFullWidth` everywhere
 `Sidebar`, `fullwidth` on `Tabs` only, `fullWidth` on `Sidebar` only.
 
 **Labels.** Default to the convenience `label` prop, with `horizontal` for a side-by-side row.
-`Input`, `Select`, `TextArea`, `File`, `Numberinput`, `Slider`, `DateInput`, `TimeInput`,
-`DateTimeInput`, `Autocomplete` and `Taginput` then render the `Field` and the label and wire
-`htmlFor`/`id`, to your `id` when you pass one (`<Input label="Email" id="email" horizontal />`);
-an explicit `labelProps={{ htmlFor }}` wins. The group inputs (`Checkboxes`, `Radios`, `Rate`,
-`DateRangeInput`) name their `role="group"`/`"radiogroup"` wrapper through `aria-labelledby`
-instead. Inside a `Field` a convenience input drops its `label`, and an `inline` date/time picker
-has no visible input to wire.
+`Input`, `Select`, `TextArea`, `File`, `Numberinput`, `PinInput`, `Slider`, `DateInput`,
+`TimeInput`, `DateTimeInput`, `Autocomplete` and `Taginput` then render the `Field` and the label
+and wire `htmlFor`/`id`, to your `id` when you pass one
+(`<Input label="Email" id="email" horizontal />`); an explicit `labelProps={{ htmlFor }}` wins. `Combobox` renders its `Field` and label too, and wires
+them to its field. Given `data`, its `id`, `aria-label` and `aria-labelledby` go to the field;
+built from parts, put them on `Combobox.Input`, since on the `Combobox` they land on its wrapper
+`div`. The group inputs (`Checkboxes`, `Radios`, `Rate`, `DateRangeInput`) name their
+`role="group"`/`"radiogroup"` wrapper through `aria-labelledby` instead. Inside a `Field` a
+convenience input drops its `label`, and an `inline` date/time picker has no visible input to wire.
 
 Composed, a labeled `Field` names the one control it holds: a composed `InputBase`/`SelectBase`/
 `TextAreaBase`, a composed `DateInputBase`/`TimeInputBase`/`DateTimeInputBase` that is not
@@ -152,9 +177,9 @@ unmatched `for` out of server-rendered HTML.
 
 A `range` `Slider` points the `for` at its low thumb and starts both thumbs' names with the label
 ("Price range Minimum value"); its `ariaLabel={[low, high]}` replaces those names outright, so
-leave it off when a label already names the Slider. Those thumbs and an `Autocomplete`'s or
-`Taginput`'s suggestion list point `aria-labelledby` at the label's `id`, which a label wired by
-hand has only when you pass one, `labelProps={{ htmlFor, id }}`; without it they keep their
+leave it off when a label already names the Slider. Those thumbs and an `Autocomplete`'s, a
+`Combobox`'s or a `Taginput`'s list point `aria-labelledby` at the label's `id`, which a label
+wired by hand has only when you pass one, `labelProps={{ htmlFor, id }}`; without it they keep their
 fallback names ("Minimum value"/"Maximum value", "Suggestions"). A `<label htmlFor>` you put in
 `Field.Label` yourself (`references/patterns.md`) names its control through the `for` alone, so
 label a row holding either with the `Field`'s `label` prop. An `aria-label` or `aria-labelledby`
@@ -243,9 +268,9 @@ multi-field form plus the advanced inputs.
 
 ## Reuse the shipped components
 
-bestax ships the whole form surface — Input, Select, TextArea, Checkbox(es), Radio(s), Switch,
-File, Autocomplete, Slider, Numberinput, Rate, Taginput, and the date/time inputs (see the
-inventory above). **Compose these; don't hand-roll raw `<input class="input">` markup or
+bestax ships the whole form surface — Input, Select, TextArea, Checkbox(es), Radio(s), Switch, File,
+Autocomplete, Combobox, Slider, Numberinput, PinInput, Rate, Taginput, and the date/time inputs (see
+the inventory above). **Compose these; don't hand-roll raw `<input class="input">` markup or
 reinvent a control.** If you think a control is missing, check `bulma-ui/src/index.ts` and
 `docs/docs/api/form/` first — it's probably already there under a different name.
 

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

@@ -19,7 +19,7 @@ Container and layout. Compound parts: `Field.Label`, `Field.Body`.
 | `labelProps`            | label attributes                                  | Props for the `<label>`. An explicit `htmlFor` (even `undefined`) takes over the association; otherwise it is set automatically. For its `id`, see below.                                                                          |
 | `textColor` / `bgColor` | Bulma color                                       | Helper colors for the field.                                                                                                                                                                                                       |
 
-An `id` in `labelProps` is what a group's, a range `Slider`'s and an `Autocomplete` or `Taginput` suggestion list's `aria-labelledby` points at. A label wired by hand with `htmlFor` gets no generated id, so give it one, `labelProps={{ htmlFor, id }}`, for a range `Slider`, an `Autocomplete` or a `Taginput`. No group points at a label wired by hand.
+An `id` in `labelProps` is what a group's, a range `Slider`'s and an `Autocomplete`'s, a `Combobox`'s or a `Taginput`'s list's `aria-labelledby` points at. A label wired by hand with `htmlFor` gets no generated id, so give it one, `labelProps={{ htmlFor, id }}`, for a range `Slider`, an `Autocomplete`, a `Combobox` or a `Taginput`. No group points at a label wired by hand.
 
 ## Control — `form/Control.tsx`
 
@@ -87,13 +87,15 @@ File input with `label`, `message`, color/size, and icon support.
 
 ## Advanced inputs
 
-| Component      | Key props                                                                                                                                                                                                                                                 |
-| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `Autocomplete` | `data` (`string[]` or item objects), `value`, `onInput(value)` for typing, `onSelect(item)` for picks, `clearable` (the clear button hides while `loading`, or a loading `Control` around it, puts a spinner at the same edge), `openOnFocus`, `loading`. |
-| `Slider`       | `min`, `max`, `step`, single or dual thumb (`value` number or `[number, number]`), `tooltip` (`'auto' \| 'always' \| 'hidden'`), vertical orientation, `color`, `size`.                                                                                   |
-| `Numberinput`  | `value`/`onChange`, `min`, `max`, `step`, increment/decrement buttons, stepper variant, `color`, `size`, `isLoading` (set it here, not on a `Control` around it, whose spinner covers the right-hand button).                                             |
-| `Rate`         | `value`/`onChange`, `max`, `precision` (1 / 0.5 / 0.25), `customIcon` or `iconName`, `showScore`/`showText`/`texts`, `disabled`.                                                                                                                          |
-| `Taginput`     | `value` (array)/`onChange`, autocomplete suggestions, configurable confirm keys, closable tags, `color`, `size`.                                                                                                                                          |
+| Component      | Key props                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Autocomplete` | `data` (`string[]` or item objects), `value`, `onInput(value)` for typing, `onSelect(item)` for picks, `clearable` (the clear button hides while `loading`, or a loading `Control` around it, puts a spinner at the same edge), `openOnFocus`, `loading`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `Combobox`     | Either way: `multiple`, `keepFirst`, `inline`, `size`, `position` (`'auto'` keeps the list in the viewport), `appendToBody` (in a `Modal`, point a `ConfigProvider`'s `portalContainer` inside the modal), `open`/`defaultOpen`/`onOpenChange`, `onSelect(value)` and the Field props. Given `data` (strings or `{ value, label?, disabled?, group? }`): `value`/`defaultValue`/`onChange` (`string \| null`, or `string[]` with `multiple`, shown as tags), `placeholder`, `name`, `empty`, `itemTemplate`, and `disabled`, `required`, `form`, `id`, `aria-label`/`aria-labelledby` for the field; leaving the field empty clears one value. From parts: `.Input` (an `Input`, with `size` and the Field props on the root), `.Menu`, `.List`, `.Item` (`value`, `checked`, `disabled`), `.Group` (`label`), `.Empty`; you filter, keep the value and set the field's text in `onSelect`. |
+| `Slider`       | `min`, `max`, `step`, single or dual thumb (`value` number or `[number, number]`), `tooltip` (`'auto' \| 'always' \| 'hidden'`), vertical orientation, `color`, `size`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `Numberinput`  | `value`/`onChange`, `min`, `max`, `step`, increment/decrement buttons, stepper variant, `color`, `size`, `isLoading` (set it here, not on a `Control` around it, whose spinner covers the right-hand button).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `PinInput`     | `length` (6), `value`/`defaultValue`/`onChange` (the code as a string), `onComplete(code)` once a change fills the last box, `type` (`'number'` or `'alphanumeric'`), `isMasked`, `name`, `color`, `size`, `isRounded`, `disabled` and the Field props. One input holds the code (`autoComplete="one-time-code"`); a paste replaces it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `Rate`         | `value`/`onChange`, `max`, `precision` (1 / 0.5 / 0.25), `customIcon` or `iconName`, `showScore`/`showText`/`texts`, `disabled`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `Taginput`     | `value` (array)/`onChange`, autocomplete suggestions, configurable confirm keys, closable tags, `color`, `size`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 
 ## Date / time inputs
 

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

@@ -214,6 +214,60 @@ const [city, setCity] = useState('');
   openOnFocus
 />;
 
+// Combobox: a value from a list. Given data, it filters by label, keeps the
+// value and shows its label in the field.
+const [country, setCountry] = useState<string | null>(null);
+<Combobox
+  label="Country"
+  data={['Canada', 'France', 'Japan']}
+  value={country}
+  onChange={setCountry}
+  empty="No countries match"
+/>;
+
+// Several values, shown as tags under the field; groups come from `group`.
+const [labels, setLabels] = useState<string[]>([]);
+<Combobox
+  label="Labels"
+  multiple
+  data={[
+    { value: 'bug', label: 'Bug', group: 'Type' },
+    { value: 'docs', label: 'Docs', group: 'Area' },
+  ]}
+  value={labels}
+  onChange={setLabels}
+/>;
+
+// From parts, when data doesn't fit (a server search, a "Create" item): you
+// filter, keep the value and set the text, and a pick calls onSelect.
+const countries = ['Canada', 'France', 'Japan'];
+const [choice, setChoice] = useState<string | null>(null);
+const [query, setQuery] = useState('');
+const term = query === choice ? '' : query.trim().toLowerCase();
+const matches = countries.filter(c => c.toLowerCase().includes(term));
+<Combobox
+  label="Country"
+  onSelect={picked => {
+    setChoice(picked);
+    setQuery(picked);
+  }}
+>
+  <Combobox.Input value={query} onChange={e => setQuery(e.target.value)} />
+  <Combobox.Menu>
+    {matches.length > 0 ? (
+      <Combobox.List>
+        {matches.map(c => (
+          <Combobox.Item key={c} value={c} checked={c === choice}>
+            {c}
+          </Combobox.Item>
+        ))}
+      </Combobox.List>
+    ) : (
+      <Combobox.Empty>No countries match</Combobox.Empty>
+    )}
+  </Combobox.Menu>
+</Combobox>;
+
 // Slider (single and dual thumb)
 const [volume, setVolume] = useState(50);
 <Slider value={volume} onChange={setVolume} min={0} max={100} tooltip="auto" />;
@@ -233,6 +287,20 @@ const [range, setRange] = useState<[number, number]>([20, 80]);
 const [qty, setQty] = useState(1);
 <Numberinput value={qty} onChange={setQty} min={1} max={10} step={1} />;
 
+// PinInput: a one-time code or PIN, a box per character, all in one input.
+// onComplete fires once each time a change fills the last box.
+const [code, setCode] = useState('');
+const verify = (otp: string) => {
+  // Send it to your server, then show the result with color and message.
+};
+<PinInput
+  label="Enter the 6-digit code"
+  name="otp"
+  value={code}
+  onChange={setCode}
+  onComplete={verify}
+/>;
+
 // Rate
 const [stars, setStars] = useState(3);
 <Rate value={stars} onChange={setStars} max={5} />;

package/templates/skills/bestax-icons/references/icon-libraries.md

@@ -26,9 +26,22 @@ Set it once on `ConfigProvider` and omit `library` everywhere else.
 - **Variants** (`variant` → class): `solid` → `fas` (default), `regular` → `far`, `brands` →
   `fab`, `light` → `fal`, `duotone` → `fad`, `thin` → `fat`. The free package includes only
   solid, regular (partial), and brands — light/duotone/thin need a Font Awesome Pro kit.
+  Font Awesome 6's long class names (`fa-solid`, `fa-brands`, …) are the same styles, so write
+  them as these variants. Font Awesome 4's `fa` is `variant="fa"`, which `Icon` writes as given:
+  4 reads nothing else, and 5 and later read it as solid.
 - **Features:** Font Awesome utility classes — `'fa-lg'`, `'fa-2x'`…`'fa-10x'`, `'fa-spin'`,
   `'fa-pulse'`, `'fa-border'`, `'fa-fw'`, `'fa-flip-horizontal'`, `'fa-rotate-90'`.
 - Brand icons **require** `variant="brands"`: `<Icon name="github" variant="brands" />`.
+- **Older names:** 6 and 7 still read most of 5's names, many since renamed (`search` is
+  `magnifying-glass` now), and 4's through the v4 shims (`css/v4-shims.min.css`). Two kinds
+  draw something else:
+  - **4's brand glyphs under `fa`** (`fa fa-github`): 5 moved brands to a style of their own,
+    so without the shims they show a missing-glyph box. Write `variant="brands"`, and the
+    current name where 5 renamed one (4's `facebook` is `facebook-f`, `linkedin` is
+    `linkedin-in`, `youtube-play` is `youtube`).
+  - **5's handsets:** 6 turned them round. 5's `phone` and `phone-square` draw as 6's
+    `phone-flip` and `square-phone-flip`, and 5's `phone-alt` and `phone-square-alt` as `phone`
+    and `square-phone`, so write those names to keep a 5 page's look.
 
 ## Material Design Icons — `'mdi'`
 
@@ -140,7 +153,7 @@ Docs: https://bestax.io/docs/guides/getting-started/alternative-icons#making-the
 3. **The library's CSS/script is actually loaded** — the import in `main.tsx` (or the
    Ionicons script in `index.html`) must exist; bestax ships none of them.
 4. **Variant availability** — Font Awesome free has no `light`/`duotone`/`thin`; brand
-   glyphs need `variant="brands"`.
+   glyphs need `variant="brands"`, an old Font Awesome 4 one under `fa` included.
 
 ## IconText
 

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

@@ -110,8 +110,33 @@ Centered; a collection of items → Card grid. For mixed requests, pick the domi
   other: `<TreeView aria-label="Files" selectionMode="single">` with `selected`/`onSelectedChange`
   picks one, and `selectionMode="checkbox"` with `checked`/`onCheckedChange` draws boxes with
   mixed parents, where a parent's value checks its whole branch. Map the data with a recursive
-  function, and render an item's children whether it's open or not. Its items aren't links, so
-  the app's sidebar and any list of pages stay on `Menu` with `Menu.Item href`.
+  function, and render an item's children whether it's open or not. A folder that loads when it
+  opens takes `hasChildren`, `isLoading` while its children are on their way, and
+  `loadError="Couldn't load src"` with `onRetry` when the load fails, setting `isLoading` again
+  while the retry runs: the tree draws the Loading… and Retry rows and announces them, so don't
+  hand-write a placeholder item. Its items aren't
+  links, so the app's sidebar and any list of pages stay on `Menu` with `Menu.Item href`.
+- **A sidebar whose groups of links open and close is `Menu.Section`**, one per group, directly
+  in `Menu` (never inside a `Menu.Item` or `Menu.List`):
+  `<Menu.Section label="Components" defaultOpen>` around that group's `Menu.List`, with
+  `defaultOpen` on the group holding the current page (or `open`/`onOpenChange` to hold the state).
+  Its heading is a real button with `aria-expanded`, and its links stay links, each a tab stop.
+  Not `TreeView`, and not a `Collapse` inside a hand-written `<li>`.
+- **Panes the user resizes are `Splitter`** (a file tree beside an editor, a list beside its
+  detail, a query above its results), not hand-written drag code or fixed `Columns`:
+  `<Splitter height={480}>` with a `<Splitter.Pane label="Files" defaultSize={25} minSize="12rem">`
+  per pane. The handles go in on their own, each named by its pane's `label`, so give every pane
+  one. Sizes are percentages, limits also take `px` or `rem`, `orientation="vertical"` stacks
+  them (and needs a `height`), and `collapsible` with `collapsed`/`onCollapsedChange` lets a
+  button hide a pane. Put scrolling content in a `ScrollArea` inside the pane.
+- **Content taller or wider than its space is `ScrollArea`** (release notes in a Card, a sidebar
+  longer than the screen, a feed that grows then scrolls, a wide table on a phone), not a `Box`
+  with `overflowY="auto"` and a height in a style: `<ScrollArea height={240} aria-label="…">`,
+  or `maxHeight="20rem"` to grow with its content first. It needs `aria-label` or
+  `aria-labelledby`, since while it overflows it's a region a keyboard user tabs to. The
+  helper props and `className` go on its frame and the `ref` on the element that scrolls.
+  `hasFade` fades the edges that have more, `orientation="horizontal"` suits a wide table, and
+  `onEdgeReach={edge => …}` loads more at an edge.
 - Link lists (footer nav, sidebars): a bare `UnorderedList` of `ListItem`s is already
   marker-less and flush — Bulma's reset unstyles `ul` — so no prop or CSS is needed;
   bullets appear only inside `Content`.
@@ -167,9 +192,10 @@ Centered; a collection of items → Card grid. For mixed requests, pick the domi
   (`Hero color="primary"`, a dark banner), use **filled** buttons — `color="light"` or
   `color="primary" isInverted` — never a thin `isOutlined` secondary: a light outline + light
   label on a dark surface is low-contrast and gets worse under OS dark mode. And when the page's
-  design is single-mode (a fixed light or dark look), pin it at the root —
-  `<Theme isRoot colorMode="light">` — so a visitor's OS dark mode can't flip Bulma's text
-  colors out from under the fixed palette (details: the `bestax-theming` skill's contrast rules).
+  design is single-mode (a fixed light or dark look), pin it on the `<html>` in `index.html`,
+  `<html lang="en" data-theme="light">`, so a visitor's OS dark mode can't flip Bulma's text
+  colors out from under the fixed palette, from the first paint on (details: the
+  `bestax-theming` skill's contrast rules).
 
 ## Three components core Bulma will talk you out of
 

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

@@ -164,8 +164,8 @@ style, so bands cost zero custom CSS. The same values work on `Hero` (and its
 **Hero CTAs:** on a colored hero use **filled** buttons only — `color="light"` for the primary
 CTA and `color="primary" isInverted` (solid white, primary text) for a secondary. A thin
 `isOutlined` button on a fixed-color surface is low-contrast and degrades further under OS dark
-mode. Single-mode page designs should also pin the scheme at the root
-(`<Theme isRoot colorMode="light">`) — see the `bestax-theming` skill's contrast rules.
+mode. Single-mode page designs should also pin the scheme on the `<html>` in `index.html`
+(`<html lang="en" data-theme="light">`); see the `bestax-theming` skill's contrast rules.
 
 ---
 

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

@@ -39,12 +39,16 @@ Every component also accepts the shared Bulma helper props (`m`/`p` spacing, `te
 
 | Prop                              | Type                                    | Notes                                     |
 | --------------------------------- | --------------------------------------- | ----------------------------------------- |
+| `as`                              | `'div'` (default) or a landmark tag     | Renders that tag in place of the `div`.   |
 | `fluid`                           | `boolean`                               | Full width with a small gutter.           |
 | `widescreen` / `fullhd`           | `boolean`                               | Only constrain at that breakpoint and up. |
 | `breakpoint`                      | `'tablet' \| 'desktop' \| 'widescreen'` | Max-width breakpoint.                     |
 | `isMax`                           | `boolean`                               | Use the `is-max-*` width.                 |
 | `color` / `textColor` / `bgColor` | Bulma color                             | —                                         |
 
+`as` takes `'main' | 'section' | 'article' | 'aside' | 'header' | 'footer' | 'nav'`, so
+`<Container as="main">` renders `<main class="container">` with no wrapper.
+
 ## Section
 
 `<Section>` adds vertical page rhythm (padding).
@@ -63,6 +67,7 @@ Every component also accepts the shared Bulma helper props (`m`/`p` spacing, `te
 | `color`                | `primary \| link \| info \| success \| warning \| danger \| black \| white \| light \| dark` (CSS-backed). Also accepted but deprecated, no CSS, dev-warn: every other `validColors` member, plus `inherit` and `current` |
 | `size`                 | `'small' \| 'medium' \| 'large' \| 'fullheight' \| 'fullheight-with-navbar'`                                                                                                                                              |
 | `fullheightWithNavbar` | `boolean`                                                                                                                                                                                                                 |
+| `as`                   | `'section'` (default) \| `'div'` \| `'main'` \| `'header'` \| `'footer'` \| `'article'` \| `'aside'`                                                                                                                      |
 
 ```tsx
 <Hero color="primary" size="medium">
@@ -70,6 +75,11 @@ Every component also accepts the shared Bulma helper props (`m`/`p` spacing, `te
 </Hero>
 ```
 
+`Hero.Head` takes `as="header"` or `as="nav"` and `Hero.Foot` `as="footer"` or `as="nav"` (both
+`div` by default), so a page that is all hero is `<Hero as="main">` with no wrapper. A `header` or
+`footer` is the page's banner or footer landmark only outside a `section`, `article`, `aside`,
+`nav` or `main`, so for that render the hero itself `as="div"`.
+
 ## Footer
 
 `<Footer>` is the page footer.
@@ -230,6 +240,8 @@ flexDirection="column"` + `flexGrow="1"` pattern applies to `Cell` + `Card`.
 | --------------- | ---------------------------------------------------------------------------------------------------------------- |
 | `fixed`         | `'top' \| 'bottom'`                                                                                              |
 | `transparent`   | `boolean`                                                                                                        |
+| `isSpaced`      | `boolean` (Bulma's `is-spaced`, from desktop up)                                                                 |
+| `hasShadow`     | `boolean` (default `false`, unlike `Card`'s; Bulma's `has-shadow`)                                               |
 | `color`         | `'primary' \| 'link' \| 'info' \| 'success' \| 'warning' \| 'danger' \| 'black' \| 'dark' \| 'light' \| 'white'` |
 | `Navbar.Item`   | `as?`, `active?`, `href`                                                                                         |
 | `Navbar.Burger` | `active?`, `onClick`                                                                                             |
@@ -239,7 +251,12 @@ The burger/menu is controlled state — toggle `Navbar.Burger active`/`onClick`
 flag to `Navbar.Menu active`. **A `fixed="top"` navbar requires `has-navbar-fixed-top` on `<html>`**
 (Bulma offsets the page from it); the library adds no helper. Set it statically —
 `<html class="has-navbar-fixed-top">` in `index.html` — reserving a `classList.add` effect for
-a navbar that mounts conditionally.
+a navbar that mounts conditionally. **With `isSpaced`, add `has-spaced-navbar-fixed-top` too**
+(`<html class="has-navbar-fixed-top has-spaced-navbar-fixed-top">`): from desktop up the spaced
+navbar is taller than the plain class pads the page for, and there the spaced class pads it for
+the taller navbar, so with the plain class alone the top of the page sits under the navbar. A
+`fixed="bottom"` navbar takes `has-navbar-fixed-bottom`, and `has-spaced-navbar-fixed-bottom`
+beside it with `isSpaced`.
 
 **Routing:** in a routed app, don't use `href="#"` — render items as the router's link
 component. `Menu.Item as={Link} to="/x"` and `Navbar.Item as={Link} to="/x"` both compile
@@ -250,11 +267,13 @@ https://bestax.io/docs/guides/features/routing.
 
 ## Menu
 
-`<Menu>` is a vertical sidebar menu. Subcomponents: `Menu.Label`, `Menu.List`, `Menu.Item`.
+`<Menu>` is a vertical sidebar menu. Subcomponents: `Menu.Label`, `Menu.List`, `Menu.Item`,
+`Menu.Section`.
 
-| Prop        | Type                                                                                                                                                                                |
-| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `Menu.Item` | `active?` (the current page: `is-active` plus `aria-current="page"`, so don't add your own), `href?`, `as?` (custom link component); nest a `Menu.List` inside an item for submenus |
+| Prop           | Type                                                                                                                                                                                                                            |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Menu.Item`    | `active?` (the current page: `is-active` plus `aria-current="page"`, so don't add your own), `href?`, `as?` (custom link component); nest a `Menu.List` inside an item for submenus                                             |
+| `Menu.Section` | `label` (the heading, a `ReactNode`), `defaultOpen?`, or `open?` with `onOpenChange?(open)` to hold the state yourself, as `Collapse` does; its child is the group's `Menu.List`, and a closed section's links are out of reach |
 
 ```tsx
 <Menu>
@@ -268,6 +287,34 @@ https://bestax.io/docs/guides/features/routing.
 </Menu>
 ```
 
+A sidebar whose groups of links open and close (a docs sidebar, an admin app's sections) puts each
+group's `Menu.List` in a `Menu.Section`. Its heading is a real button drawn like `Menu.Label`, with
+`aria-expanded` and a chevron, and its links stay ordinary links, each a tab stop. Open the
+section that holds the current page. A section goes directly in `Menu`, never inside a `Menu.Item`
+(it would render inside the item's link) or a `Menu.List` (it isn't a list item). Don't build this
+from `TreeView` (its items aren't links) or from a `Collapse` in a hand-written `<li>` (its trigger
+is a `div` with `role="button"`).
+
+```tsx
+<nav aria-label="Documentation">
+  <Menu>
+    <Menu.Section label="Getting started">
+      <Menu.List>
+        <Menu.Item href="/docs/install">Installation</Menu.Item>
+      </Menu.List>
+    </Menu.Section>
+    <Menu.Section label="Components" defaultOpen>
+      <Menu.List>
+        <Menu.Item href="/docs/button" active>
+          Button
+        </Menu.Item>
+        <Menu.Item href="/docs/card">Card</Menu.Item>
+      </Menu.List>
+    </Menu.Section>
+  </Menu>
+</nav>
+```
+
 ## Card
 
 `<Card>` for catalog/grid items. Use the props form (`header`, `image`, `footer`) or the compound

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

@@ -52,11 +52,16 @@ Run these steps in order. Don't hand-convert what the codemod converts automatic
    Each page becomes a module beside it (`index.tsx`, or `.jsx` when the package isn't
    TypeScript) whose default export is `<Name>Page`, named from the file (its folder's for an
    `index.html`). The page stays as it was, and the codemod never writes over a module that's
-   already there, so a re-run writes nothing. Its head, its `<html>` and `<body>` attributes and
+   already there, so a re-run on the page writes nothing: after fixing a TODO, re-run on the
+   module, which is what each TODO says. Its head, its `<html>` and `<body>` attributes and
    its scripts become `html-*` TODOs: put the app-wide parts in the app's `index.html` and
    entry, and port each script's work into the component. Under `--css bestax` or `--css bulma`
    the module imports the stylesheet in place of the page's Bulma `<link>`.
 
+   A file that fails to parse or transform is marked `✖`, listed under `failed` in the report
+   and left as it was, and the run exits 1 while every other file still converts. Fix that file
+   and run the codemod on it again. TODOs alone leave the exit code at 0.
+
 2. **Apply it** (same command without `--dry`), then run the project's formatter — the
    codemod preserves surrounding formatting but doesn't prettify what it rewrites.
    Besides the components, it also migrates **stylesheets** (CSS imports →
@@ -132,9 +137,17 @@ code per the references, or deliberately keep the old markup with `className` st
   drift than the 0.9 → 1 guide alone describes.
 - **bulma-classes**: there is no library to remove. An element converts only when the bestax
   component renders the same markup (tag, classes, attributes), so a converted page renders
-  the same HTML; everything else stays as written, with a TODO when there is something to
-  decide. Static class strings convert, and so does a `clsx` or `classnames` call of strings
-  and conditional classes, where a condition on a flag becomes its prop (`isLoading={busy}`);
+  the same HTML, but for deliberate exceptions. Font Awesome's own hidden `<i>` in a `.icon`
+  that carries nothing else assistive tech reads becomes `Icon`, which hides the `.icon`
+  instead, the glyph hidden either way. Such a `.icon` around a bare glyph, in a link or button
+  its own `aria-label` names, becomes `Icon` too, which hides it, since the label is what a
+  screen reader reads there. Font Awesome 6's long style names (`fa-brands`) become the
+  `bestax-icons` skill's `variant` (`brands`), which renders the short name (`fab`), the same
+  style. And Bulma 0.9's `is-marginless` and `is-paddingless`,
+  which style nothing under v1, become `m="0"` and `p="0"`. Everything else stays as written, with a
+  TODO when there is something to decide. Static class strings convert, and so does a `clsx` or
+  `classnames` call of strings and conditional classes, where a condition on a flag becomes
+  its prop (`isLoading={busy}`);
   any other computed className gets `dynamic-class:<Target>`, naming the component the element
   would become. Files a Next.js
   App Router may render as server components are left alone (`rsc`), and the manifest gains
@@ -156,7 +169,8 @@ code per the references, or deliberately keep the old markup with `className` st
 
 - The codemod is safe to re-run after partial manual work: a library source only touches files
   that still import the library, and `bulma-classes` skips elements that are already
-  components and never repeats a TODO it already wrote.
+  components, never repeats a TODO it already wrote, and drops one that asked for a re-run once
+  it no longer applies.
 - Don't downgrade converted props back to the old names; bestax uses `is*` booleans
   (`isLoading`), string size unions (`textSize="4"`), and `as` rather than `renderAs`.
 - If a component the app uses isn't in the component map, it wasn't part of that library's

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

@@ -151,7 +151,7 @@ Some targets depend on a prop or a child, so the codemod picks them element by e
 | `PageControl`                                        | `Pagination.Previous` / `Pagination.Next`                          | `isNext` (bloomer's default is previous)                                                                                  |
 | `NavbarItem`                                         | `Navbar.Item` / `Navbar.Dropdown`                                  | `hasDropdown`                                                                                                             |
 | `Page`                                               | _folded into its child_ / `<li>`                                   | whether the child is a `PageLink`/`PageEllipsis`; attributes on the Page move onto the link, with a `component:Page` note |
-| `PanelBlock`                                         | `Panel.Block` / `<div class="panel-block">`                        | `href` — bestax's block is always an `<a>`                                                                                |
+| `PanelBlock`                                         | `Panel.Block` / _the plain block_                                  | the element: an `<a>`, a `<div>` or a `<label>` is the component; any other `tag`, or a dynamic one, stays plain markup   |
 | `MenuLink` in a literal `<li>`                       | `Menu.Item`, the `<li>` folded away                                | bestax's item renders its own `<li>`                                                                                      |
 | `Breadcrumb` around a literal `<ul>`                 | `Breadcrumb`, the `<ul>` folded away                               | bestax's breadcrumb renders its own `<ul>`                                                                                |
 | `Icon`, `PanelIcon`                                  | `name`/`library`/`variant` / an `<i>` child                        | whether the icon classes are FA5/6 or MDI                                                                                 |

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

@@ -119,8 +119,8 @@ narrowed to a literal union, so a value outside the union is a type error you ca
 than a silent rewrite. The components whose `tag` becomes `as`:
 
 `Button`, `Image`, `Title`, `Subtitle`, `Footer`, `Media`, `MediaLeft`, `LevelItem`, `Control`,
-`DropdownItem`,
-`MenuLink`, `NavbarItem`, `NavbarLink`.
+`DropdownItem`, `MenuLink`, `NavbarItem`, `NavbarLink`, `Container`, `Hero`, `HeroHeader`,
+`HeroFooter`, `Panel`.
 
 Everywhere else `tag` is left in place with a TODO. On the components that become plain markup
 (`Help`, `Label`, `Heading`, `BreadcrumbItem`, `PanelTab`, `TabLink`, `Page`, `HeroVideo`) a
@@ -148,9 +148,12 @@ rendered. `Button` and `LevelItem` gain `as="a"`; on the targets that already re
 stays — each of those takes the anchor's props under its default `as`. A `NavbarItem` or
 `DropdownItem` with neither `href` nor `tag` gains `as="div"`, because bestax's `Navbar.Item`
 and `Dropdown.Item` default to an `<a>`. An empty or false `href` selected nothing in bloomer
-and is dropped. bestax's `Panel.Block` is always an `<a>`, so only a `PanelBlock` with `href`
-becomes one — the rest stay the plain `<div class="panel-block">` (or the `tag` you gave) that
-bloomer rendered.
+and is dropped. bestax's `Panel.Block` is an `<a>` by default and a `<div>` or a `<label>`
+through `as`, so a `PanelBlock` with no `href` becomes `<Panel.Block as="div">`, or
+`as="label"` for `tag="label"`, and one with `tag="a"` a bare `<Panel.Block>`. One on any
+other `tag` stays the plain block, on that tag, that bloomer rendered. A dynamic `tag` becomes
+a plain `<div class="panel-block">` with a `prop:tag` TODO, since the codemod can't tell which
+tag it names.
 
 A dynamic `href={expr}` was a runtime decision bloomer made and bestax's `as` is one element or
 the other. It resolves to the anchor, which is the branch the `href` is there for, and the
@@ -189,7 +192,7 @@ value is flagged. The same conversion covers the modifiers bestax has no prop fo
 bloomer forwarded no refs. bestax forwards a ref from the form controls, plus `Avatar`, `Button`,
 `Carousel`, `CarouselItem`, `Dialog`, `Dropdown`, `EmptyState`, `Kbd`, `Kbd.Group`, `Link`,
 `LinkButton`, `Loader`, `Menu.Item`, `Modal`, `Navbar`, `Navbar.Burger`, `Navbar.Dropdown`,
-`Navbar.Item`, `Navbar.Link`, `SegmentedControl`, `SegmentedControl.Segment`, `Sidebar`, `Timeline`,
+`Navbar.Item`, `Navbar.Link`, `ScrollArea`, `SegmentedControl`, `SegmentedControl.Segment`, `Sidebar`, `Splitter`, `Splitter.Pane`, `Timeline`,
 `Timeline.Item`, `Toast`, `ToggleButton`, `TreeView` and `TreeView.Item` — pass `ref` directly on
 those. "The form controls" means the inputs themselves: the `Field`, `Field.Label`, `Field.Body`,
 `Checkboxes` and `Radios` wrappers around them forward nothing.

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

@@ -62,10 +62,13 @@ and `isSize={n}` becomes a column span:
 bloomer's `Modal` was an inert shell: `isActive` toggled the class and nothing else. bestax's
 `Modal` closes on Escape (calling `onClose`), locks body scroll, and traps focus **by default**,
 and renders inline unless `portal` is set. So every conversion changes behaviour, and every one
-is flagged. Pass `onClose` to get the close-on-Escape and background behaviour:
+is flagged. Pass `onClose` for Escape and `Modal.Close` to close it. `Modal.Background` doesn't
+call `onClose` on its own, so give it the same handler as `onClick` for the background to close
+it too:
 
 ```jsx
 <Modal active={open} onClose={() => setOpen(false)}>
+  <Modal.Background onClick={() => setOpen(false)} />
 ```
 
 or keep bloomer's inert behaviour with `closeOnEscape={false} lockScroll={false}`. Add