create-bestax 4.2.16 → 4.2.18

package/templates/skills/bestax-custom-component/SKILL.md

@@ -63,10 +63,45 @@ Wrap it in the library's `ClientOnly` rather than checking `typeof window`: it r
 until the page has hydrated, so the server and client markup match. `references/api.md` has the
 details.
 
+A button that turns something on or off and stays that way (Bold, Mute, Show archived) is
+`ToggleButton`: use it rather than `Button isActive`, which only draws a shade and sets no
+`aria-pressed`. It's always `type="button"`, holds its own state (`defaultPressed`) or takes
+`pressed` with `onPressedChange`, and fills with `color` (default `link`) only while pressed.
+Its label stays the same in both states, and an icon-only one needs an `aria-label`. A set goes
+in `Buttons hasAddons role="group" aria-label="…"`, where it's also `Buttons.ToggleButton`. A row
+where only one can be on is a radio group, so it's `SegmentedControl` (below), never toggles that
+switch each other off. A setting saved with a form is a `Switch` or a `Checkbox`.
+
+A row of buttons where only one can be on (text alignment, a list or grid view, monthly or yearly
+billing) is `SegmentedControl`: use it rather than `Buttons hasAddons` with `isActive` or a fill
+you move yourself. Give it an `aria-label`, put one `SegmentedControl.Segment value="…"` inside per
+option, and hold the choice with `defaultValue`, or `value` with `onChange(value)`. A screen reader
+hears a radio group, and the single tab stop, the arrow keys, Home and End come built in, so add
+no `onKeyDown` or `role` of your own. An icon-only segment needs its own `aria-label`, as an
+icon-only `ToggleButton` does. The arrow keys check the segment they land on, so `onChange` fires
+on each, and pressing the checked segment keeps it checked. It carries no form value: a choice
+the form submits is `Radios`.
+
 A panel opened from a button (a filter form, share options, an inline edit) is `Popover`: use
 it rather than building one. It anchors the panel, moves focus in and back, and closes on
 Escape and outside presses.
 
+A preview that shows up on hover (a profile card on a username, a summary on a link) is
+`HoverCard`: use it rather than wiring pointer events to a `Popover`. It opens on hover and
+keyboard focus after a delay, lets the pointer move onto the card, closes on Escape, and ignores
+touch unless `openOnTap` is on, which suits only a trigger with no tap action of its own (a
+`Button` with no `onClick`, never a link). Its `trigger` has to be a link or a button, and a trigger in running text takes
+`appendToBody`. A form never goes in one; that's `Popover`.
+
+A menu of actions that opens on a right-click (Rename and Delete on a table row, Archive on a
+card) is `ContextMenu`: use it rather than an `onContextMenu` handler that positions a
+`Dropdown`. It opens at the point, also on Shift+F10, the context menu key and a long press,
+and its items are `ContextMenu.Item` and `ContextMenu.Divider`, the same components as
+`Dropdown.Item` and `Dropdown.Divider`. Its `trigger` is cloned, not wrapped, so a `Table.Tr`
+works, and the menu needs `aria-label`. Put the same items in a visible `Dropdown` as well:
+nothing tells a screen reader user a context menu is there, and on macOS only VoiceOver opens
+it from the keyboard.
+
 Building something else that floats (a command palette)? Render it through the library's
 `Portal` rather than `createPortal`: it renders nothing on the server and during hydration, so
 the server and client markup match. `references/api.md` has the details.
@@ -139,7 +174,7 @@ the children with `gap`. Before writing `style={{ … }}` anywhere, translate ea
 | `textAlign: 'center'`                    | `textAlign="centered"` (also `left`, `right`, `justified`)                                                                                                     |
 | `color: '#…'`                            | `textColor` with the nearest Bulma color: `primary`, `link`, `info`, `success`, `warning`, `danger`, `white`, `black`, `grey` (+ `grey-light`, `grey-dark`, …) |
 | `backgroundColor: '#…'`                  | `bgColor` (same palette)                                                                                                                                       |
-| `fontSize: …`                            | `textSize="1"`…`"7"` (`1` largest) — for headings use `Title`/`SubTitle` `size`                                                                                |
+| `fontSize: …`                            | `textSize="1"`…`"7"` (`1` largest). On `Title`/`SubTitle`, `as` sets the level and `size` picks it too, so an `<h3>` at size 4 is `as="h3" textSize="4"`       |
 | `fontWeight: …`                          | `textWeight`: `light`, `normal`, `medium`, `semibold`, `bold`                                                                                                  |
 | `textTransform`, italics                 | `textTransform`: `uppercase`, `lowercase`, `capitalized`, `italic`                                                                                             |
 | `display: 'flex'` + flex properties      | same-named props: `display="flex"`, `flexDirection`, `justifyContent`, `alignItems`, `flexWrap`                                                                |

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

@@ -88,7 +88,8 @@ union (a compile error beats a silent no-op).
 
 ## `ConfigProvider` / `Theme` — `helpers/Config.tsx`, `helpers/Theme.tsx`
 
-`ConfigProvider` provides the runtime `classPrefix` (and `iconLibrary`) consumed via `useConfig`;
+`ConfigProvider` provides the runtime `classPrefix` (and `iconLibrary` and `portalContainer`)
+consumed via `useConfig`;
 `classPrefix` feeds `usePrefixedClassNames` (opt-in class prefixing to avoid collisions). `Theme`
 overrides `--bulma-*` custom properties at runtime —
 which is exactly why component SCSS must register its vars via `cv.register-vars` rather than
@@ -114,17 +115,23 @@ hard-coding values.
 ## Floating content: `Portal`
 
 A panel anchored to the button that opens it is `Popover`, which already portals
-(`appendToBody`), traps focus and dismisses itself. `Portal` is for the overlays it doesn't
-cover.
-
-`<Portal container?>` (`helpers/portal.tsx`) renders its children into `document.body`, or into
-`container` (an element or a selector), so floating content escapes an ancestor's `overflow`,
+(`appendToBody`), traps focus and dismisses itself, a preview that opens on hover is
+`HoverCard`, which portals the same way, and a menu that opens at a right-click or a long press
+is `ContextMenu`, which always portals and places itself at the point. `Portal` is for the
+overlays they don't cover.
+
+`<Portal container?>` (`helpers/portal.tsx`) renders its children into `container` (an element or
+a selector), or without one into the `portalContainer` a `ConfigProvider` sets, and
+`document.body` when none is set, so floating content escapes an ancestor's `overflow`,
 `transform` or stacking context. It renders nothing on the server and during hydration, so the
 first client render matches; `disabled` renders in place instead. Use it rather than calling
 `createPortal` yourself, which React's server renderer can't render.
 
-Focus follows the DOM, not the React tree: portaled content comes last in the Tab order, so move
-focus into it when it opens and back to its trigger when it closes. To trap portaled content,
+Focus follows the DOM, not the React tree: portaled content sits in the Tab order where its
+container is, which for the default `document.body` is last, so an overlay you build that takes
+focus moves it in when it opens and back to its trigger when it closes. A `HoverCard` moves no
+focus when it opens, and a `ContextMenu` moves it to its first item and closes on Tab, handing
+focus back. To trap portaled content,
 put the trap's ref on the element inside the `Portal`, as below with
 `useFocusTrap(panelRef, { active: open, restoreFocus: buttonRef })`. A focus trap doesn't cover
 what a `Portal` inside it renders, so render nested overlays inside the trapped element.
@@ -141,17 +148,28 @@ what a `Portal` inside it renders, so render nested overlays inside the trapped
 }
 ```
 
+Content in `document.body` loses a scoped `Theme`'s variables and a shadow root's styles. In a web
+component or a themed section, wrap the area in a `ConfigProvider` whose `portalContainer` is an
+element inside it, which also covers what the library's components portal, such as `Popover`'s
+`appendToBody` panel or a `Modal` with `portal`. In a shadow root, pass the
+element itself, held in state from a ref callback, since a selector can't reach inside one. What
+moves there is `position: fixed`, so the element must not sit under an ancestor with a
+`transform`, `filter`, `backdrop-filter`, `perspective`, `will-change: transform`, or a `contain`
+that includes `paint` or `layout`: that ancestor becomes the containing block, and overlays and
+anchored panels land against it instead of the viewport.
+
 ## Holding focus: `useFocusTrap`
 
 `useFocusTrap(ref, { active, initialFocusRef, restoreFocus })` (`helpers/useFocusTrap.ts`) moves
 focus into `ref` when `active` turns on, wraps Tab at the first and last tab stops (the ones the
 browser visits, so hidden, disabled, inert and `tabIndex={-1}` elements are skipped and a radio
 group counts once) and restores focus when it turns off. It handles Tab only: wire Escape to
-close. Pass the trigger's ref as `restoreFocus` for a panel opened from a button. It looks for
-the container again each time the component calling it renders, so `active` can follow `open`
-alone even when the panel mounts a render later, as portaled content can. The example below
-shows the hook's wiring; for a real filter panel opened from a button, use `Popover`, which does
-all of this.
+close, and call `preventDefault()` on the Escape it closes on, so a `Modal` or `Sidebar` around
+the panel stays open for the next one. Pass the trigger's ref as `restoreFocus` for a panel
+opened from a button. It looks for the container again each time the component calling it
+renders, so `active` can follow `open` alone even when the panel mounts a render later, as
+portaled content can. The example below shows the hook's wiring; for a real filter panel opened
+from a button, use `Popover`, which does all of this.
 
 ```tsx
 function FilterPanel({ children }: { children: React.ReactNode }) {
@@ -176,7 +194,11 @@ function FilterPanel({ children }: { children: React.ReactNode }) {
           role="dialog"
           aria-label="Filters"
           tabIndex={-1}
-          onKeyDown={e => e.key === 'Escape' && setOpen(false)}
+          onKeyDown={e => {
+            if (e.key !== 'Escape') return;
+            e.preventDefault();
+            setOpen(false);
+          }}
         >
           {children}
         </div>

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.
 
-94 documented components. Generated from the API docs — every exported
+102 documented components. Generated from the API docs — every exported
 component is guaranteed to appear (the generator fails if one lacks an API page).
 
 ## Elements
@@ -55,6 +55,7 @@ component is guaranteed to appear (the generator fails if one lacks an API page)
 - [Icon](https://bestax.io/docs/api/elements/icon) — The `Icon` component is a Bulma-styled wrapper for displaying icons from various libraries (Font Awesome, Material Design Icons, Ionicons…
 - [IconText](https://bestax.io/docs/api/elements/icontext) — The `IconText` component provides a Bulma-styled horizontal arrangement of one or more `Icon` components and optional text.
 - [Image](https://bestax.io/docs/api/elements/image) — The `Image` component wraps images, iframes, or custom content in a Bulma-styled container, supporting fixed sizes, aspect ratios, rounded corners…
+- [Kbd](https://bestax.io/docs/api/elements/kbd) — The `Kbd` component renders a `<kbd>` drawn as a keycap, for a key the reader presses.
 - [Link](https://bestax.io/docs/api/elements/link) — The `Link` component renders a styled anchor (`<a>`) element with Bulma helper class integration.
 - [LinkButton](https://bestax.io/docs/api/elements/linkbutton) — The `LinkButton` component renders a `<button>` that visually looks like text or a link.
 - [ListItem](https://bestax.io/docs/api/elements/listitem) — The `ListItem` component renders a styled list item (`<li>`) element with Bulma helper class integration.
@@ -72,6 +73,7 @@ component is guaranteed to appear (the generator fails if one lacks an API page)
 - [Tag](https://bestax.io/docs/api/elements/tag) — The `Tag` component renders a Bulma-styled label or badge.
 - [Tags](https://bestax.io/docs/api/elements/tags) — The `Tags` component groups multiple `Tag` components together in a Bulma-styled container that wraps onto multiple lines by default.
 - [Title](https://bestax.io/docs/api/elements/title) — The `Title` component renders a Bulma-styled title (heading), supporting sizes `1`-`6`, spacing, and rendering as any heading or paragraph element (`h1`-`h6`…
+- [ToggleButton](https://bestax.io/docs/api/elements/togglebutton) — The `ToggleButton` component renders a button that stays pressed until it's pressed again, and says whether it's on through `aria-pressed`.
 - [UnorderedList](https://bestax.io/docs/api/elements/unorderedlist) — The `UnorderedList` component renders a styled unordered list (`<ul>`) element with Bulma helper class integration.
 
 ## Components
@@ -84,8 +86,11 @@ component is guaranteed to appear (the generator fails if one lacks an API page)
 - [Carousel](https://bestax.io/docs/api/components/carousel) — The `Carousel` component provides an image/content slider with navigation arrows and indicators.
 - [Collapse](https://bestax.io/docs/api/components/collapse) — The `Collapse` component provides an expandable/collapsible content panel.
 - [Collapses](https://bestax.io/docs/api/components/collapses) — The `Collapses` component groups `Collapse` items into an accordion that keeps one item open at a time, or any number with `multiple`.
+- [ContextMenu](https://bestax.io/docs/api/components/contextmenu) — The `ContextMenu` component opens a menu of actions where you right-click an element, such as a table row or a card, or long press it on a touch screen.
 - [Dialog](https://bestax.io/docs/api/components/dialog) — The `Dialog` component provides ready-made confirm and alert dialogs, so a destructive action stays one `await dialog.confirm()` call away.
 - [Dropdown](https://bestax.io/docs/api/components/dropdown) — The `Dropdown` component provides Bulma's versatile dropdown menu for your Bulma React UI.
+- [EmptyState](https://bestax.io/docs/api/components/emptystate) — The `EmptyState` component renders the block an app shows where content would be: an empty list, a search with no results, or a first-run screen.
+- [HoverCard](https://bestax.io/docs/api/components/hovercard) — The `HoverCard` component shows a card previewing what's behind a link or a button while the pointer rests on it or keyboard focus is on it.
 - [Loading](https://bestax.io/docs/api/components/loading) — The `Loading` component provides a loading overlay with a spinner animation.
 - [Menu](https://bestax.io/docs/api/components/menu) — The `Menu` component provides Bulma's vertical navigation menu: a simple, accessible sidebar or section menu for your Bulma React UI.
 - [Message](https://bestax.io/docs/api/components/message) — The `Message` component provides Bulma's flexible notice/message box for your Bulma React UI.
@@ -95,11 +100,14 @@ 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`.
+- [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.
 - [Tabs](https://bestax.io/docs/api/components/tabs) — The `Tabs` component provides flexible and fully-featured Bulma tab navigation for your Bulma React UI.
+- [Timeline](https://bestax.io/docs/api/components/timeline) — The `Timeline` component renders a list of events in the order they happened, each with a marker on a line down the side.
 - [Toast](https://bestax.io/docs/api/components/toast) — The `Toast` component provides brief notification messages with optional action and cancel buttons.
 - [Tooltip](https://bestax.io/docs/api/components/tooltip) — The `Tooltip` component displays helpful information when users hover over or focus on an element.
+- [TreeView](https://bestax.io/docs/api/components/treeview) — The `TreeView` component renders a tree of items you browse and pick from, the way a file explorer works: one tab stop, the arrow keys to move…
 
 ## Form
 
@@ -147,7 +155,7 @@ component is guaranteed to appear (the generator fails if one lacks an API page)
 
 - [ClientOnly](https://bestax.io/docs/api/helpers/clientonly) — `ClientOnly` renders its children only in the browser, after hydration, and a `fallback` until then…
 - [ConfigProvider](https://bestax.io/docs/api/helpers/config) — The `ConfigProvider` component provides a React context for configuring global settings across all Bulma UI components.
-- [Portal](https://bestax.io/docs/api/helpers/portal) — `Portal` renders its children into another part of the page, `document.body` unless `container` says otherwise…
+- [Portal](https://bestax.io/docs/api/helpers/portal) — `Portal` renders its children into another part of the page, `document.body` unless `container` or a `ConfigProvider` says otherwise…
 - [Theme](https://bestax.io/docs/api/helpers/theme) — The `Theme` component provides a powerful way to customize Bulma's appearance using CSS custom properties (CSS variables).
 - [Valid value constants](https://bestax.io/docs/api/helpers/valid-values) — The helper tuples enumerate the core accepted values for the shared Bulma helper props — public API for building prop types and validation.
 - [classNames](https://bestax.io/docs/api/helpers/classnames) — `classNames` is a utility function for conditionally joining class names together.

package/templates/skills/bestax-custom-component/references/library-contributor.md

@@ -168,7 +168,10 @@ Rules that keep components consistent:
   place in the DOM uses `Portal` (`helpers/portal.tsx`) rather than its own `createPortal` and
   `typeof document` check. `Portal` renders nothing on the server or during hydration, so the
   first client render matches the server markup. Test that with `renderToString` plus
-  `hydrateRoot` and a `console.error` spy, as `portal.test.tsx` does.
+  `hydrateRoot` and a `console.error` spy, as `portal.test.tsx` does. A component that has to
+  call `createPortal` itself, as `Modal` does to render in place until hydration, resolves its
+  target with `usePortalContainer` from the same module, so the `portalContainer` a
+  `ConfigProvider` sets reaches it too. Add it to `src/__tests__/portal-container.test.tsx`.
 
 - **Focus management builds on `useFocusTrap`.** A new component that holds focus while it is
   open uses `useFocusTrap` (`helpers/useFocusTrap.ts`) rather than its own Tab handler, so it

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

@@ -65,7 +65,7 @@ using context (`useInsideField` / `useInsideControl`) to detect their surroundin
 ```tsx
 <Field hasAddons>
   <Control isExpanded>
-    <InputBase placeholder="Search" />
+    <InputBase placeholder="Search" aria-label="Search" />
   </Control>
   <Control>
     <Button color="primary">Go</Button>
@@ -73,6 +73,10 @@ using context (`useInsideField` / `useInsideControl`) to detect their surroundin
 </Field>
 ```
 
+A `grouped` or `hasAddons` Field names none of its controls, and a placeholder disappears once
+the user types, so give each input in the row an `aria-label`, or a visible label on an outer
+`Field` (`references/patterns.md`, "Grouped controls and addons").
+
 ## Component inventory
 
 All import from `@allxsmith/bestax-bulma`. Convenience components auto-wrap Field+Control;
@@ -125,30 +129,41 @@ Full-width is `isFullwidth` on every component that supports it (`Button`, `Link
 spellings compile only where they historically existed: `isFullWidth` everywhere except
 `Sidebar`, `fullwidth` on `Tabs` only, `fullWidth` on `Sidebar` only.
 
-The `label` prop on the single-control convenience inputs (`Input`, `Select`, `TextArea`,
-`File`, `Numberinput`, `Slider`, `DateInput`, `TimeInput`, `DateTimeInput`, `Autocomplete`,
-`Taginput`) wires `htmlFor`/`id` automatically — your `id` is used when provided, a
-generated one otherwise, and an explicit `labelProps={{ htmlFor }}` wins. The wiring only
-happens when the component renders its own `Field` (nested inside one, the `label` prop is
-dropped); the date/time pickers skip it in `inline` mode and `Taginput` skips it at
-`maxTags` (no visible input to label). A `range` `Slider` points the `for` at its low thumb
-and also puts the label at the start of both thumbs' names through `aria-labelledby`
-("Price range Minimum value"). Its `ariaLabel={[low, high]}` replaces those names outright, so
-leave it off when a label already names the Slider. The group inputs (`Checkboxes`, `Radios`, `Rate`,
-`DateRangeInput`) associate their `label` too, but group-style: the wrapper gets
-`role="group"`/`"radiogroup"` and `aria-labelledby` pointing at the label. Composing yourself
-also associates: a labeled `Field` names the one control it holds, whether a composed
-`InputBase`/`SelectBase`/`TextAreaBase`, a composed `DateInputBase`/`TimeInputBase`/
-`DateTimeInputBase` that is not `inline`, or any input above (through the id), or a group
-(through `aria-labelledby`). Either way, an `aria-label` or `aria-labelledby` you give a
-group wins over the label. A `Checkbox`, `Radio` or `Switch` takes nothing from a `Field`:
-each is named by its own children, so put the text there. The association is skipped for
-`grouped`/`hasAddons`, and a nested `Field` starts its own scope, so a
-horizontal `Field` whose body holds an inner `Field` needs `labelProps={{ htmlFor }}` plus the
-control's `id` (for a group, `labelProps={{ id, htmlFor: undefined }}` plus its
-`aria-labelledby`, since nothing takes the label's `for` there). Pass
-`labelProps={{ htmlFor }}` plus a matching `id` only when you want a stable id, or
-`labelProps={{ htmlFor: undefined }}` to opt out.
+**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.
+
+Composed, a labeled `Field` names the one control it holds: a composed `InputBase`/`SelectBase`/
+`TextAreaBase`, a composed `DateInputBase`/`TimeInputBase`/`DateTimeInputBase` that is not
+`inline`, or any input above takes its generated id, and a group (a composed `DateRangeInputBase`
+too, `inline` or not) points `aria-labelledby` at the label's own id. **A control with an `id` of
+its own never takes that id**, so `<Field label="Email"><Input id="email" /></Field>` renders a
+label that names nothing: leave the `id` off, or pass the same value as
+`labelProps={{ htmlFor: 'email' }}`. Wire it that way too where the association is skipped, in a
+`grouped`/`hasAddons` row and in a horizontal `Field` whose body holds an inner `Field` (a nested
+`Field` starts its own scope). For a group there, put `labelProps={{ id, htmlFor: undefined }}` on
+the outer `Field` and a matching `aria-labelledby` on the group; the `htmlFor: undefined` keeps an
+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
+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`
+you give a group wins over any label, and a `Checkbox`, `Radio` or `Switch` takes nothing from a
+`Field` on its own: its children name it, and a `Field`'s label names one only when you wire it as
+you would any control with an `id` of its own, `labelProps={{ htmlFor }}` plus that control's
+`id`. A labeled `Field` whose `for` nothing takes (a group, a `Checkbox`, `Radio` or `Switch`, an
+input with an `id` of its own, your own markup) drops it once mounted, though server-rendered HTML
+keeps it. `labelProps={{ htmlFor: undefined }}` opts out of the association entirely.
 
 ## Convenience vs composed
 
@@ -265,11 +280,12 @@ for the expected classes/states, and say plainly that the visual pass is still o
 ## Checklist
 
 - [ ] Built from the shipped form components (no hand-rolled inputs / reinvented controls).
-- [ ] Every label is programmatically associated — the convenience `label` prop, the group
-      inputs, and `Field` + single-base composition all do this automatically; pass
-      `labelProps={{ htmlFor }}` plus a matching `id` only for a stable id, and label a
-      multi-control `Field`'s controls individually (`aria-label`, `aria-labelledby`, or
-      a `<label htmlFor>` matching each control's `id`).
+- [ ] Every label is programmatically associated: the convenience `label` prop, the group
+      inputs, and `Field` + single-control composition do it on their own. A composed labeled
+      `Field` names a control with an `id` of its own, or one in an inner `Field`, only when its
+      `labelProps={{ htmlFor }}` matches that `id`, and a multi-control `Field`'s controls are
+      labeled individually (`aria-label`, `aria-labelledby`, or a `<label htmlFor>` matching
+      each control's `id`).
 - [ ] Controlled inputs have both `value` and `onChange` (or use `defaultValue` uncontrolled).
 - [ ] Error state shows via `color="danger"` + `message` + `messageColor="danger"`.
 - [ ] Grouped/addon layouts use explicit `Field` + `Control` composition.

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

@@ -8,16 +8,18 @@ via `useBulmaClasses`.
 
 Container and layout. Compound parts: `Field.Label`, `Field.Body`.
 
-| Prop                    | Type                                              | Notes                                                                                                                                                                                              |
-| ----------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `horizontal`            | `boolean`                                         | Label + control side by side. Auto-wraps children in `Field.Body`.                                                                                                                                 |
-| `grouped`               | `boolean \| 'centered' \| 'right' \| 'multiline'` | Controls in a row.                                                                                                                                                                                 |
-| `hasAddons`             | `boolean \| 'centered' \| 'right'`                | Attached controls.                                                                                                                                                                                 |
-| `narrow`                | `boolean`                                         | Constrain to content width (inside horizontal bodies).                                                                                                                                             |
-| `label`                 | `ReactNode`                                       | Names the one control it holds: a composed base or convenience input through its id, a group through `aria-labelledby` (skipped for `grouped`/`hasAddons`; a nested `Field` starts its own scope). |
-| `labelSize`             | `'small' \| 'normal' \| 'medium' \| 'large'`      | Label size.                                                                                                                                                                                        |
-| `labelProps`            | label attributes                                  | Props for the `<label>`. An explicit `htmlFor` (even `undefined`) takes over the association; otherwise it is set automatically. An `id` here is what a group's `aria-labelledby` points at.       |
-| `textColor` / `bgColor` | Bulma color                                       | Helper colors for the field.                                                                                                                                                                       |
+| Prop                    | Type                                              | Notes                                                                                                                                                                                                                              |
+| ----------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `horizontal`            | `boolean`                                         | Label + control side by side. Auto-wraps children in `Field.Body`.                                                                                                                                                                 |
+| `grouped`               | `boolean \| 'centered' \| 'right' \| 'multiline'` | Controls in a row.                                                                                                                                                                                                                 |
+| `hasAddons`             | `boolean \| 'centered' \| 'right'`                | Attached controls.                                                                                                                                                                                                                 |
+| `narrow`                | `boolean`                                         | Constrain to content width (inside horizontal bodies).                                                                                                                                                                             |
+| `label`                 | `ReactNode`                                       | Names the one control it holds: a composed base or convenience input with no `id` of its own through a generated id, a group through `aria-labelledby` (skipped for `grouped`/`hasAddons`; a nested `Field` starts its own scope). |
+| `labelSize`             | `'small' \| 'normal' \| 'medium' \| 'large'`      | Label size.                                                                                                                                                                                                                        |
+| `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.
 
 ## Control — `form/Control.tsx`
 
@@ -68,6 +70,9 @@ Field/Control/message props. `TextArea` adds `rows` and `hasFixedSize`.
 
 - `Checkbox` / `Radio` — single controls with `color`, `size`, `checked`/`defaultChecked`,
   `onChange`, `disabled`.
+- `Checkbox` also takes `indeterminate`, the mixed state of a "Select all" box over a partly
+  checked list. It changes the look and the announcement, not the value: `checked` stays the
+  value, so set both from the list.
 - `Checkboxes` — group wrapper managing an **array** value.
 - `Radios` — group wrapper managing a **single** selected value.
 

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

@@ -131,7 +131,7 @@ Notes:
 // Search box: input + button attached.
 <Field hasAddons>
   <Control isExpanded>
-    <InputBase placeholder="Search" />
+    <InputBase placeholder="Search" aria-label="Search" />
   </Control>
   <Control>
     <Button color="primary">Search</Button>
@@ -141,14 +141,18 @@ Notes:
 // Two controls on one row.
 <Field grouped>
   <Control>
-    <InputBase placeholder="First" />
+    <InputBase placeholder="First" aria-label="First name" />
   </Control>
   <Control>
-    <InputBase placeholder="Last" />
+    <InputBase placeholder="Last" aria-label="Last name" />
   </Control>
 </Field>
 ```
 
+A `grouped` or `hasAddons` Field names none of the controls it holds, and a placeholder
+disappears once the user types, so each input above carries an `aria-label`. For a visible
+label instead, see the last item below.
+
 Recipes built on addons, each written out in full in the docs:
 
 - **Password reveal** ([docs](https://bestax.io/docs/api/form/input#password-reveal)): the
@@ -164,9 +168,10 @@ Recipes built on addons, each written out in full in the docs:
 - **Split button** ([docs](https://bestax.io/docs/api/components/dropdown#split-button)): a
   `Button` and a `Dropdown` in `Field hasAddons`, one `Control` each. `Buttons hasAddons` does
   not join the Dropdown's trigger. Keep the default color, since the trigger takes no `color`.
-- To label an addon row, put the label on an outer `Field` with `labelProps={{ htmlFor }}` and a
-  matching `id` on the input. A label inside the `hasAddons` field sits in the row beside the
-  controls.
+- To label an addon row, put the label on an outer `Field` with `labelProps={{ htmlFor, id }}`
+  and a matching `id` on the input. The label's `id` names an `Autocomplete`'s or `Taginput`'s
+  suggestion list or a range `Slider`'s thumbs, which point `aria-labelledby` at it. A label
+  inside the `hasAddons` field sits in the row beside the controls.
 
 ## Horizontal field with explicit label/body
 

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

@@ -46,6 +46,12 @@ or `library` silently renders nothing.
 first thing to check. A redundant `fa-`/`mdi-` prefix in `name` is tolerated (stripped), but
 don't rely on it.
 
+**Material Symbols' font is several megabytes however few icons the app shows.** Keep the
+default `material-symbols/outlined.css` import. When the user cares about download size,
+offer a smaller font as an optimisation (a Google Fonts `icon_names` subset, a self-hosted
+subset, or a single-weight package): `references/icon-libraries.md` has each one and its
+trade-offs.
+
 ## Styling
 
 - `size` — `'small' | 'medium' | 'large'` sizes the Bulma **container** (`is-small` ≈ 1rem,
@@ -105,6 +111,7 @@ everything else takes the standard `aria-label` attribute, e.g.
 ## References
 
 - `references/icon-libraries.md` — per-library setup (install/import/CDN), the full
-  name-format and variant tables, `features` values, and the blank-icon troubleshooting list.
+  name-format and variant tables, `features` values, making the Material Symbols font
+  smaller, and the blank-icon troubleshooting list.
 - `examples/icon-usage.tsx` — runnable example: ConfigProvider setup, sizes, variants,
   colors, IconText, and decorative-vs-labeled patterns.

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

@@ -44,7 +44,7 @@ Set it once on `ConfigProvider` and omit `library` everywhere else.
 
 ## Ionicons — `'ion'` ⚠️ value is `ion`, not `ionicons`
 
-- **Setup:** a CDN script pair in `index.html` (no npm package — it registers the
+- **Setup:** a CDN script in `index.html` (no npm package — it registers the
   `<ion-icon>` web component):
 
   ```html
@@ -89,6 +89,39 @@ Set it once on `ConfigProvider` and omit `library` everywhere else.
   Material Icons' `round`.
 - **Features:** Bulma classes like `'is-size-1'`.
 
+### Making the font smaller
+
+`outlined.css` loads the whole variable font (every symbol at every fill, weight, grade and
+optical size), several megabytes however few icons the app shows. Keep that import as the
+default: it is one line, works offline, and any name renders. Offer a smaller font only when
+the user cares about download size (a size budget, a Lighthouse flag, slow networks), and
+present it as an optimisation with the trade-offs below:
+
+- **One stylesheet per style rendered.** If the app has the bare `import 'material-symbols';`,
+  replace it with `outlined.css`, adding `rounded.css` or `sharp.css` only where a `variant`
+  uses them. The bare import ships every style's font in the build (a browser fetches each one
+  only when a page renders it). This is where the scaffold already stands, and the style left
+  is still the whole variable font, which the options below shrink.
+- **Google Fonts subset.** Replace the import with a stylesheet link in `index.html`:
+  `<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined&icon_names=home,palette,settings&display=block" />`.
+  `icon_names` takes the ligature names comma-separated and sorted alphabetically, and keep
+  `&display=block` (it stops the names flashing as text). The returned CSS defines the same
+  `material-symbols-outlined` class, so components don't change. Costs: the browser fetches
+  the icons from Google (privacy, no offline use), and the list must hold every name the app
+  renders, since a missing one shows as plain text. `variant="rounded"`/`"sharp"` need
+  `Material+Symbols+Rounded`/`Material+Symbols+Sharp` requested too, and an app that sets
+  `font-variation-settings` must request those axes in the URL.
+- **Self-hosted subset.** Cut a subset from the package's `.woff2` with a font subsetting tool
+  (fontTools' subsetter, for one), keeping the glyphs for the names the app renders, and load
+  it with the app's own `@font-face` plus the `.material-symbols-outlined` rules. No request to
+  Google, same list upkeep.
+- **Fewer variations.** `@material-symbols/font-400`, from the same project, keeps every
+  symbol with weight, grade and optical size fixed, at a fraction of the size. Import
+  `@material-symbols/font-400/outlined.css` in place of `material-symbols/outlined.css`; it
+  defines the same class, and there is no list to maintain.
+
+Docs: https://bestax.io/docs/guides/getting-started/alternative-icons#making-the-font-smaller
+
 ## One glyph, five names
 
 | Glyph    | fa                 | mdi             | ion        | material-icons / material-symbols |
@@ -105,7 +138,7 @@ Set it once on `ConfigProvider` and omit `library` everywhere else.
 2. **Name format for that library** — kebab vs snake_case (see the table above); for
    material-* a wrong name renders as literal text instead of a glyph.
 3. **The library's CSS/script is actually loaded** — the import in `main.tsx` (or the
-   Ionicons scripts in `index.html`) must exist; bestax ships none of them.
+   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"`.
 

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

@@ -59,13 +59,59 @@ Centered; a collection of items → Card grid. For mixed requests, pick the domi
   `aria-controls`/`aria-labelledby` links come built in, so add no `onKeyDown` or ARIA
   of your own; `onChange` fires when a tab is activated, never on
   arrow-key focus), `Dropdown active/onActiveChange`,
+  `ToggleButton pressed/defaultPressed onPressedChange` for a button that stays on or off (not
+  `Button isActive`, which sets no `aria-pressed`; the label stays the same in both states; a
+  set goes in `Buttons hasAddons role="group"` with an `aria-label`, where it's also
+  `Buttons.ToggleButton`, and a row where only one can be on is `SegmentedControl`),
+  `SegmentedControl aria-label="…" value/defaultValue onChange` for a row of buttons where
+  only one can be on, such as a list or grid view (one `SegmentedControl.Segment value="…"` per
+  option; a radio group with the single tab stop and the arrow keys built in, so add no
+  `onKeyDown` of your own; an icon-only segment needs its own `aria-label`; the arrows check as
+  they move, so `onChange(value)` fires on each, and it can't be cleared; it carries no form
+  value, so a choice a form submits is `Radios`),
   `Popover trigger={<Button>…</Button>} open/defaultOpen onOpenChange` (`trigger` is one
   element, not a node: Popover clones it to add the click and ARIA, so never wrap it in a
   clickable of your own; build the panel from `Popover.Header`/`Body`/`Footer`/`Close`, and a
   panel without a `Popover.Header` needs `ariaLabel`),
+  `HoverCard trigger={<Link href="…">…</Link>}` for a preview on hover or keyboard focus
+  (`trigger` is one link or button, cloned the same way; the card's content goes straight in as
+  children with no sub-components; a trigger inside a `Paragraph` needs `appendToBody`; hover
+  and focus only unless `openOnTap` is set, which suits only a trigger with no tap action of its
+  own, such as a `Button` with no `onClick`; on touch a link trigger just follows the link, so
+  what the card shows must be on that page too, and a form is a `Popover`),
+  `ContextMenu aria-label="…" trigger={<Table.Tr>…</Table.Tr>}` for actions on a right-click
+  or a long press (`trigger` is one element, a row or a card, cloned rather than wrapped; the
+  items are `ContextMenu.Item`/`ContextMenu.Divider`, which are `Dropdown`'s; no `open` prop,
+  `onOpenChange` reports it; always put the same items in a visible `Dropdown` on the row too,
+  since a context menu is only a shortcut),
   `Steps value={i}/onStepClick items={[{label, icon?}]}` (child form is `Steps.Step`, not
   `Steps.Item`). `Reveal cascade` staggers only its **direct children** — to stagger a grid,
   put `<Reveal delay={i * 80}>` inside each `Cell`, not around the container.
+- **An empty list, table or search with no results is `EmptyState`**, not a hand-built `Box`
+  of `Icon`, `Title` and `Buttons isCentered`:
+  `<EmptyState icon="folder-open" title="No projects yet" titleAs="h3" description="…">` with
+  its one `<Button>` as a child (two or more go in `EmptyState.Actions`). Its `title` is always a
+  heading, so set `titleAs` to the level under the list's own heading. It has no live region:
+  after a search or a filter, keep a `Paragraph` with `role="status"`, `aria-atomic="true"` and
+  `visibility="sr-only"` beside the search field the whole time, saying the count, and have
+  "Clear search" put focus back in the field. While data loads show a `Skeleton` or a `Loader`,
+  and a failed load is a `Message` or a `Notification`, never an EmptyState. The archetypes
+  reference has the full pattern under Card grid.
+- **An order's history, a ticket's activity, a changelog or an activity feed is `Timeline`**,
+  not a hand-built list with a border down the side: `<Timeline titleAs="h3">` with a
+  `<Timeline.Item title="Shipped" time="14 October 2026" dateTime="2026-10-14">` per event, any
+  detail as its children, and the whole date in `time`. `titleAs` is the level under the
+  section's heading, or `"p"` in a busy feed. For something that moves along on its own, like a
+  parcel or a deployment, `active={i}` marks progress and `pending="Out for delivery"` ends it on
+  what's under way, oldest first. A journey the user moves through, like a wizard or a checkout,
+  stays `Steps`.
+- **A file browser, a checkbox tree (permissions, filters) or an outline you browse is
+  `TreeView`**, with `<TreeView.Item value="…" label="…" icon="folder">` items nested inside each
+  other: `<TreeView aria-label="Files" selectionMode="single">` with `selected`/`onSelectedChange`
+  picks one, and `selectionMode="checkbox"` with `checked`/`onCheckedChange` draws boxes with
+  mixed parents, where a parent's value checks its whole branch. Map the data with a recursive
+  function, and render an item's children whether it's open or not. Its items aren't links, so
+  the app's sidebar and any list of pages stay on `Menu` with `Menu.Item href`.
 - Link lists (footer nav, sidebars): a bare `UnorderedList` of `ListItem`s is already
   marker-less and flush — Bulma's reset unstyles `ul` — so no prop or CSS is needed;
   bullets appear only inside `Content`.
@@ -160,7 +206,7 @@ background comes from the semantic `color` prop, not `bgColor`.
 | `textAlign: 'center'`                    | `textAlign="centered"` (also `left`, `right`, `justified`)                                                                                                     |
 | `color: '#…'`                            | `textColor` with the nearest Bulma color: `primary`, `link`, `info`, `success`, `warning`, `danger`, `white`, `black`, `grey` (+ `grey-light`, `grey-dark`, …) |
 | `backgroundColor: '#…'`                  | `bgColor` (same palette)                                                                                                                                       |
-| `fontSize: …`                            | `textSize="1"`…`"7"` (`1` largest) — for headings use `Title`/`SubTitle` `size`                                                                                |
+| `fontSize: …`                            | `textSize="1"`…`"7"` (`1` largest). On `Title`/`SubTitle`, `as` sets the level and `size` picks it too, so an `<h3>` at size 4 is `as="h3" textSize="4"`       |
 | `fontWeight: …`                          | `textWeight`: `light`, `normal`, `medium`, `semibold`, `bold`                                                                                                  |
 | `textTransform`, italics                 | `textTransform`: `uppercase`, `lowercase`, `capitalized`, `italic`                                                                                             |
 | `display: 'flex'` + flex properties      | same-named props: `display="flex"`, `flexDirection`, `justifyContent`, `alignItems`, `flexWrap`                                                                |
@@ -168,9 +214,11 @@ background comes from the semantic `color` prop, not `bgColor`.
 | `display: 'none'`                        | `visibility="hidden"`, or responsive `display*` props (`displayMobile`, `displayTablet`, …)                                                                    |
 | `gap: '1rem'` (flex or grid)             | `gap="2"`, or one axis: `columnGap`, `rowGap`; gap scale: `1`=0.5rem, `2`=1rem, `4`=2rem, half steps (`"1.5"`)                                                 |
 
-No helper matches (e.g. `maxWidth`, a one-off gradient)? Add a named class to the project
-stylesheet (`src/App.css` in a scaffolded app) and pass it via `className` — still never
-inline `style`.
+No helper matches (e.g. `maxWidth`, a one-off gradient)? Add a named class to the project's
+global stylesheet and pass it via `className` — still never inline `style`. In a create-bestax
+app that is `src/index.css`, which its entry file imports after bestax's stylesheet, so the
+class wins over a Bulma rule of the same weight. The starter page's `src/App.css` loads after
+bestax's too, but only while the starter's `App` imports it.
 
 ## References
 
@@ -200,6 +248,8 @@ inline `style`.
 - [ ] Do not use `Tile` — it is not shipped.
 - [ ] Action feedback goes through `Toast`, a confirmation through `Dialog`, a text-styled
       action through `LinkButton` — not `Notification`, `Modal` or a bare `<a>`.
+- [ ] An empty list or a search with no results renders `EmptyState`, and a search or a filter
+      keeps a `role="status"` region beside its field that says the count.
 - [ ] Style with helper props, not inline `style` — translate via the mapping table; values
       with no helper get a named class in the stylesheet, never `style={{}}`. No raw Bulma
       `className`s either (`Span`/`Paragraph` wrap bare text; `Th`/`Td` take `textAlign`/`textWeight`).