bestax-mcp 0.0.0

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

@@ -0,0 +1,254 @@
+---
+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.
+license: MIT
+---
+
+# Building forms with bestax-bulma
+
+This skill covers the form components in `@allxsmith/bestax-bulma` and how to compose them.
+
+**Important:** bestax-bulma ships **no form/validation library** — there is no integration with
+formik, react-hook-form, yup, or zod, and no `useForm`-style hook. You own your form state with
+plain React (`useState` / `useReducer` or any library you choose) and feed validation results
+back via each input's own `color`, `message`, and `messageColor` props on the convenience inputs
+(`Input`, `Select`, `TextArea`, …). Always put validation state on the **input**: `Field` has no
+`message`/`messageColor`, and although `FieldProps` types a `color`, `Field` discards it — it
+renders no class, so setting it looks right and does nothing. (`FieldLabel`/`FieldBody` do honor
+`color`, as the `has-text-*` helper.) See **Validation without a library** below.
+
+## Use when
+
+- Building a form out of bestax inputs, selects, checkboxes, switches, or advanced controls.
+- Deciding between the convenience components (`<Input label=… />`) and explicit
+  `Field` + `Control` + `*Base` composition.
+- Showing help text and error/success states on fields.
+
+To build a brand-new input component (not just use the existing ones), use the
+`bestax-custom-component` skill instead.
+
+## Field / Control / Label / Help composition
+
+Bulma forms are a three-tier structure. bestax models it directly:
+
+```
+Field            // container + layout (horizontal / grouped / hasAddons)
+├── label        // rendered from Field's `label` prop, or <Field.Label> when horizontal
+└── Control       // wraps ONE input; adds icons + loading
+    ├── InputBase / SelectBase / TextAreaBase   // the raw styled element
+    └── <p class="help">…</p>                    // help / validation message
+```
+
+You rarely write all of this by hand. The convenience components (`Input`, `Select`,
+`TextArea`, …) auto-wrap themselves in `Field` + `Control` when they aren't already inside one,
+using context (`useInsideField` / `useInsideControl`) to detect their surroundings.
+
+```tsx
+// Convenience: one line, auto-wrapped in Field + Control.
+<Input label="Email" type="email" placeholder="you@example.com" />
+
+// Explicit composition: full control over layout.
+<Field label="Email">
+  <Control iconLeftName="envelope" hasIconsLeft>
+    <InputBase type="email" placeholder="you@example.com" />
+  </Control>
+</Field>
+```
+
+### Layout via Field
+
+- `horizontal` — label and control side by side (wraps children in `Field.Body`; use
+  `Field.Label` / `Field.Body` directly for multi-control rows).
+- `grouped` — `true | 'centered' | 'right' | 'multiline'`, controls in a row.
+- `hasAddons` — `true | 'centered' | 'right'`, attached controls (input + button).
+
+```tsx
+<Field hasAddons>
+  <Control isExpanded>
+    <InputBase placeholder="Search" />
+  </Control>
+  <Control>
+    <Button color="primary">Go</Button>
+  </Control>
+</Field>
+```
+
+## Component inventory
+
+All import from `@allxsmith/bestax-bulma`. Convenience components auto-wrap Field+Control;
+`*Base` components are the raw styled elements for explicit composition.
+
+| Component                                               | What it is                                                                |
+| ------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `Field`, `Field.Label`, `Field.Body`                    | Field container + horizontal label/body parts.                            |
+| `Control`                                               | Wraps one input; left/right icons, `isLoading`, `isExpanded`, `size`.     |
+| `Input` / `InputBase`                                   | Text input (convenience / raw).                                           |
+| `Select` / `SelectBase`                                 | Dropdown select.                                                          |
+| `TextArea` / `TextAreaBase`                             | Multiline text.                                                           |
+| `Checkbox` / `Checkboxes`                               | Single checkbox / managed group (array value).                            |
+| `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.                  |
+| `Slider`                                                | Range slider; single/dual thumbs, steps, tooltips, vertical.              |
+| `Numberinput`                                           | Numeric input with increment/decrement, min/max, step, stepper.           |
+| `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.                                           |
+
+## Common props
+
+Across the convenience inputs (`Input`, `Select`, `TextArea`, and similar):
+
+| Prop                             | Type                                                                  | Purpose                                                              |
+| -------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `color`                          | `'primary' \| 'link' \| 'info' \| 'success' \| 'warning' \| 'danger'` | Visual state — use `'danger'` for errors, `'success'` for valid.     |
+| `size`                           | `'small' \| 'medium' \| 'large'`                                      | Input size.                                                          |
+| `value` / `onChange`             | controlled value + handler                                            | Standard React controlled inputs.                                    |
+| `defaultValue`                   | uncontrolled initial value                                            | When not controlling state.                                          |
+| `disabled`, `readOnly`           | `boolean`                                                             | Native states (`readOnly` on `*Base`).                               |
+| `label`                          | `ReactNode`                                                           | Field label (convenience components; auto-associated via `htmlFor`). |
+| `message`                        | `ReactNode`                                                           | Help / validation text rendered as `<p class="help">`.               |
+| `messageColor`                   | a Bulma color                                                         | Colors the help text (`'danger'` for errors).                        |
+| `iconLeftName` / `iconRightName` | `string`                                                              | Icon shortcuts; pair with `hasIconsLeft/Right`.                      |
+| `isLoading`                      | `boolean`                                                             | Loading indicator on the Control.                                    |
+
+Plus the full Bulma **helper props** (`m`, `p`, `textColor`, `display`, …) on every component
+via `useBulmaClasses`.
+
+⚠️ Full-width casing is inconsistent across the library: `Select`, `File`, and `Table` take
+`isFullwidth` (lowercase w); `Button` alone takes `isFullWidth`; `Tabs` takes bare `fullwidth`.
+
+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). The group inputs (`Checkboxes`, `Radios`, `Rate`)
+associate their `label` too, but group-style: the wrapper gets `role="group"`/`"radiogroup"`
+and `aria-labelledby` pointing at the label. Composing `Field` + bases yourself also
+associates: `Field`'s own `label` wires to a single composed `InputBase`/`SelectBase`/
+`TextAreaBase` (skipped for `grouped`/`hasAddons`). Pass `labelProps={{ htmlFor }}` plus a
+matching `id` only when you want a stable id, or `labelProps={{ htmlFor: undefined }}` to
+opt out — e.g. when the labeled `Field` wraps something that is not one of those bases.
+
+## Convenience vs composed
+
+- **Convenience** (`<Input label message … />`) — for typical, single-control fields. Fewer
+  lines, auto-wrapping, built-in `message`/`messageColor`. Default to this.
+- **Composed** (`Field` + `Control` + `InputBase`) — when you need grouped controls, addons,
+  multiple controls per field, or custom layout. The convenience components detect they're
+  already inside a `Field`/`Control` and won't double-wrap, so you can mix the two.
+
+## Validation without a library
+
+There is no built-in validation. The pattern is: **own your state, compute errors yourself, and
+reflect them with `color` + `message` + `messageColor`.**
+
+```tsx
+import { useState } from 'react';
+import { Input, Button } from '@allxsmith/bestax-bulma';
+
+function SignupForm() {
+  const [email, setEmail] = useState('');
+  const [touched, setTouched] = useState(false);
+
+  const valid = /^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email);
+  const error =
+    touched && !valid ? 'Please enter a valid email address.' : undefined;
+
+  return (
+    <form
+      onSubmit={e => {
+        e.preventDefault();
+        setTouched(true);
+        if (valid) {
+          // submit…
+        }
+      }}
+    >
+      <Input
+        label="Email"
+        type="email"
+        value={email}
+        onChange={e => setEmail(e.target.value)}
+        onBlur={() => setTouched(true)}
+        color={error ? 'danger' : undefined}
+        message={error}
+        messageColor={error ? 'danger' : undefined}
+        iconLeftName="envelope"
+      />
+      <Button color="primary" type="submit" mt="3">
+        Sign up
+      </Button>
+    </form>
+  );
+}
+```
+
+Rules of thumb:
+
+- Set `color="danger"` on the input **and** `messageColor="danger"` on the help text so both the
+  control and the message read as an error. Use `'success'` to signal a valid field.
+- Want a different validation library? Wire it up yourself — pass its `value`/`onChange`/error
+  string into these props. bestax does not prescribe one.
+- For grouped controls, render the `<p class="help">` via the `message` prop of the convenience
+  component, or add it manually inside the `Field` when composing.
+
+See `references/api.md` for per-component props and `references/patterns.md` for a full
+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
+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.
+
+## What happens after submit
+
+A form is not finished at the last field. The two components that carry the result are easy to
+miss because Bulma has something that looks close:
+
+- **Confirmation** — `Toast`, not `Notification`/`Message`. Mount
+  `<ToastContainer position="top-right" />` once at the app root, then call
+  `toast.success('Demo booked')` from the submit handler (`.danger` for a failed submit). It
+  self-dismisses; a `Notification` is a static element you place and tear down yourself.
+- **"Are you sure?"** — `Dialog`, not `Modal`. Mount `<DialogContainer />` at the root, then
+  `if (await dialog.confirm({ title: 'Delete this key?', message: '…', type: 'danger' })) …`.
+  It resolves to a boolean, so a destructive action stays one `if` rather than a state machine.
+  `Modal` is an empty shell — with it you rebuild the title, message and button row by hand.
+
+Both also work as plain controlled components (`<Toast message … onClose>`,
+`<Dialog isOpen … onConfirm onCancel>`) when the state should live in your component.
+
+## Visually inspect it in a browser
+
+Forms have layout, spacing, and _stateful_ behavior that types and unit tests don't cover.
+Before calling a form done, **render it and look at it**: run `pnpm storybook` (in `bulma-ui`)
+or the docs dev server, open the form, and check field alignment/spacing, the help-text/error
+states, and the validation flow (submit empty → fields turn `danger` with messages; fix → errors
+clear). If claude-in-chrome or Playwright is available, drive the browser and screenshot the
+valid and error states; otherwise eyeball it yourself. No browser at all (headless CI)? Fall
+back to a production build plus a Node `renderToString` smoke render, grep the emitted HTML
+for the expected classes/states, and say plainly that the visual pass is still owed.
+
+## 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`).
+- [ ] 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.
+- [ ] No assumption of a built-in validation/form library — state is owned by the app.
+- [ ] Submit feedback is a `Toast` and any "are you sure?" is a `Dialog` — not a hand-placed
+      `Notification` or a `Modal` you filled in yourself.
+- [ ] **Rendered and visually inspected in a browser** — layout and the error/validation states
+      look right, not just green tests. No browser available? The `renderToString` fallback above
+      counts only if you grepped the emitted classes/states **and** said the visual pass is owed.

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

@@ -0,0 +1,103 @@
+# Reference: form component props
+
+All components import from `@allxsmith/bestax-bulma`. Source lives in `bulma-ui/src/form/`.
+Every component also accepts the full Bulma helper props (`m`, `p`, `textColor`, `display`, …)
+via `useBulmaClasses`.
+
+## Field — `form/Field.tsx`
+
+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`                                       | Convenience label; auto-associates with a single composed `InputBase`/`SelectBase`/`TextAreaBase` (skipped for `grouped`/`hasAddons`). |
+| `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.       |
+| `textColor` / `bgColor` | Bulma color                                       | Helper colors for the field.                                                                                                           |
+
+## Control — `form/Control.tsx`
+
+Wraps a single input; adds icons and loading.
+
+| Prop                             | Type                             | Notes                           |
+| -------------------------------- | -------------------------------- | ------------------------------- |
+| `hasIconsLeft` / `hasIconsRight` | `boolean`                        | Icon containers.                |
+| `iconLeft` / `iconRight`         | `IconProps`                      | Full icon config.               |
+| `iconLeftName` / `iconRightName` | `string`                         | Icon name shortcut.             |
+| `iconLeftSize` / `iconRightSize` | `'small' \| 'medium' \| 'large'` | Icon size.                      |
+| `isLoading`                      | `boolean`                        | Loading spinner on the control. |
+| `isExpanded`                     | `boolean`                        | Fill available width.           |
+| `size`                           | `'small' \| 'medium' \| 'large'` | Control size.                   |
+| `as`                             | `'div' \| 'p'`                   | Root element (default `div`).   |
+
+## Input / InputBase — `form/Input.tsx`, `form/InputBase.tsx`
+
+`Input` composes `Field` + `Control` + `InputBase`. Beyond `InputBase` props it adds Field-level
+(`label`, `labelSize`, `labelProps`, `horizontal`), Control-level (`iconLeftName`,
+`iconRightName`, `iconLeftSize`, `iconRightSize`, `hasIconsLeft`, `hasIconsRight`, `isLoading`,
+`isExpanded`, `controlSize`), message (`message`, `messageColor`), and container class overrides
+(`fieldClassName`, `controlClassName`).
+
+`InputBase` props:
+
+| Prop                                  | Type                                                                  | Notes                          |
+| ------------------------------------- | --------------------------------------------------------------------- | ------------------------------ |
+| `color`                               | `'primary' \| 'link' \| 'info' \| 'success' \| 'warning' \| 'danger'` | Visual state.                  |
+| `size`                                | `'small' \| 'medium' \| 'large'`                                      | Size.                          |
+| `isRounded`                           | `boolean`                                                             | Pill shape.                    |
+| `isStatic`                            | `boolean`                                                             | Static, read-only-styled text. |
+| `isLoading`                           | `boolean`                                                             | Loading state.                 |
+| `value` / `defaultValue` / `onChange` | —                                                                     | Standard React input.          |
+| `disabled` / `readOnly`               | `boolean`                                                             | Native states.                 |
+
+`messageColor` accepts `'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger'`.
+
+## Select / SelectBase, TextArea / TextAreaBase
+
+Same convenience/raw split as Input. `Select` supports `isLoading` (on the control), `color`,
+`size`, `isRounded`, `isFullwidth` (lowercase w — Button's is `isFullWidth`), `multiple` +
+`multipleSize`, plus the Field/Control/message props. `TextArea` adds `rows` and
+`hasFixedSize`.
+
+## Checkbox / Checkboxes, Radio / Radios
+
+- `Checkbox` / `Radio` — single controls with `color`, `size`, `checked`/`defaultChecked`,
+  `onChange`, `disabled`.
+- `Checkboxes` — group wrapper managing an **array** value.
+- `Radios` — group wrapper managing a **single** selected value.
+
+## Switch — `form/Switch.tsx`
+
+`color`, `size`, `checked`/`defaultChecked`, `onChange`, `isRounded`, `isThin`, `isOutlined`,
+`passiveType`, plus RTL support.
+
+## File — `form/File.tsx`
+
+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`, `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`.                                                                |
+| `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
+
+`DateInput`, `TimeInput`, `DateTimeInput` (convenience) and their `*Base` variants. Field/Control
+composition like the other convenience inputs, with picker UIs (native with custom fallback).
+
+## Validation-related props (no library)
+
+There is no validation engine. The props you use to reflect externally-computed validation are:
+
+- `color` — `'danger'` for an error, `'success'` for valid.
+- `message` — the help/validation text (rendered as `<p class="help">`).
+- `messageColor` — colors that help text to match (`'danger'`, `'success'`, …).

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

@@ -0,0 +1,210 @@
+# Reference: form patterns
+
+## A complete multi-field form (controlled + manual validation)
+
+No form library — state is plain React, validation is a function, errors surface through
+`color` + `message` + `messageColor`.
+
+```tsx
+import { useState } from 'react';
+import {
+  Input,
+  Select,
+  TextArea,
+  Checkbox,
+  Button,
+  Field,
+} from '@allxsmith/bestax-bulma';
+
+interface Values {
+  name: string;
+  email: string;
+  country: string;
+  bio: string;
+  agree: boolean;
+}
+
+function validate(v: Values) {
+  const errors: Partial<Record<keyof Values, string>> = {};
+  if (!v.name.trim()) errors.name = 'Name is required.';
+  if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(v.email))
+    errors.email = 'Enter a valid email.';
+  if (!v.country) errors.country = 'Pick a country.';
+  if (!v.agree) errors.agree = 'You must accept the terms.';
+  return errors;
+}
+
+export function ProfileForm() {
+  const [values, setValues] = useState<Values>({
+    name: '',
+    email: '',
+    country: '',
+    bio: '',
+    agree: false,
+  });
+  const [submitted, setSubmitted] = useState(false);
+
+  const errors = validate(values);
+  const show = (k: keyof Values) => (submitted ? errors[k] : undefined);
+  const set = (k: keyof Values, val: Values[keyof Values]) =>
+    setValues(prev => ({ ...prev, [k]: val }));
+
+  return (
+    <form
+      onSubmit={e => {
+        e.preventDefault();
+        setSubmitted(true);
+        if (Object.keys(errors).length === 0) {
+          // submit values…
+        }
+      }}
+    >
+      <Input
+        label="Name"
+        value={values.name}
+        onChange={e => set('name', e.target.value)}
+        color={show('name') ? 'danger' : undefined}
+        message={show('name')}
+        messageColor="danger"
+      />
+
+      <Input
+        label="Email"
+        type="email"
+        value={values.email}
+        onChange={e => set('email', e.target.value)}
+        color={show('email') ? 'danger' : undefined}
+        message={show('email')}
+        messageColor="danger"
+        iconLeftName="envelope"
+      />
+
+      <Select
+        label="Country"
+        value={values.country}
+        onChange={e => set('country', e.target.value)}
+        color={show('country') ? 'danger' : undefined}
+        message={show('country')}
+        messageColor="danger"
+      >
+        <option value="">Select…</option>
+        <option value="us">United States</option>
+        <option value="ca">Canada</option>
+      </Select>
+
+      <TextArea
+        label="Bio"
+        value={values.bio}
+        onChange={e => set('bio', e.target.value)}
+        rows={3}
+      />
+
+      <Field>
+        <Checkbox
+          checked={values.agree}
+          onChange={e => set('agree', e.target.checked)}
+        >
+          {' '}
+          I accept the terms
+        </Checkbox>
+        {show('agree') && <p className="help is-danger">{show('agree')}</p>}
+      </Field>
+
+      <Button color="primary" type="submit" mt="4">
+        Save
+      </Button>
+    </form>
+  );
+}
+```
+
+Notes:
+
+- Validation runs every render as a pure function; `submitted` gates when errors are shown so the
+  form isn't red before the user interacts. You could gate per-field on blur instead.
+- For the checkbox the convenience `message` prop isn't used; the help text is rendered manually
+  inside the `Field` — a good illustration of dropping to composition when needed.
+
+## Grouped controls and addons
+
+```tsx
+// Search box: input + button attached.
+<Field hasAddons>
+  <Control isExpanded>
+    <InputBase placeholder="Search" />
+  </Control>
+  <Control>
+    <Button color="primary">Search</Button>
+  </Control>
+</Field>
+
+// Two controls on one row.
+<Field grouped>
+  <Control>
+    <InputBase placeholder="First" />
+  </Control>
+  <Control>
+    <InputBase placeholder="Last" />
+  </Control>
+</Field>
+```
+
+## Horizontal field with explicit label/body
+
+```tsx
+<Field horizontal>
+  <Field.Label size="normal">Email</Field.Label>
+  <Field.Body>
+    <Control iconLeftName="envelope" hasIconsLeft>
+      <InputBase type="email" placeholder="you@example.com" />
+    </Control>
+  </Field.Body>
+</Field>
+```
+
+## Advanced inputs
+
+These are controlled the same way — own the value, pass `value`/`onChange`.
+
+```tsx
+// Autocomplete — onInput fires on typing, onSelect when a suggestion is chosen.
+const [city, setCity] = useState('');
+<Autocomplete
+  value={city}
+  onInput={setCity}
+  onSelect={item =>
+    setCity(typeof item === 'string' ? item : (item?.value ?? ''))
+  }
+  data={['Austin', 'Boston', 'Chicago']}
+  openOnFocus
+/>;
+
+// Slider (single and dual thumb)
+const [volume, setVolume] = useState(50);
+<Slider value={volume} onChange={setVolume} min={0} max={100} tooltip="auto" />;
+
+const [range, setRange] = useState<[number, number]>([20, 80]);
+<Slider range value={range} onChange={setRange} min={0} max={100} />;
+
+// Numberinput
+const [qty, setQty] = useState(1);
+<Numberinput value={qty} onChange={setQty} min={1} max={10} step={1} />;
+
+// Rate
+const [stars, setStars] = useState(3);
+<Rate value={stars} onChange={setStars} max={5} />;
+
+// Taginput — tags can be strings or { value, label } objects; onChange yields TaginputTag[].
+const [tags, setTags] = useState<string[]>(['react']);
+<Taginput
+  value={tags}
+  onChange={next =>
+    setTags(next.map(t => (typeof t === 'string' ? t : t.value)))
+  }
+  data={['react', 'bulma', 'ts']}
+/>;
+```
+
+Each renders inside Bulma's field/control structure already, so wrap them in a `Field` only when
+you need a label or grouped layout. Reflect validation on them with the same `color` /
+`message` / `messageColor` approach used for text inputs.

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

@@ -0,0 +1,80 @@
+---
+name: bestax-icons
+description: Use icons in an app built with @allxsmith/bestax-bulma — the Icon/IconText components and the five supported libraries (Font Awesome, Material Design Icons, Ionicons, Google Material Icons, Material Symbols). Use when adding an icon, choosing or configuring the app-wide icon library, fixing an icon that renders blank, pairing icons with text, or making icons accessible (decorative vs labeled).
+license: MIT
+---
+
+# Icons with @allxsmith/bestax-bulma
+
+`Icon` renders a Bulma icon container (`span.icon`) around a glyph from any of five icon
+libraries behind one normalized API. `IconText` pairs icons with text. The library ships **no
+icon fonts** — the chosen library's package (or CDN script) must be installed in the app.
+
+## Quick start
+
+```tsx
+import { ConfigProvider, Icon, IconText } from '@allxsmith/bestax-bulma';
+
+// Set the library ONCE at the app root; <Icon> then never needs `library`.
+<ConfigProvider iconLibrary="fa">
+  <App />
+</ConfigProvider>;
+
+// Inside the app:
+<Icon name="rocket" ariaLabel="Launch" />;
+<IconText iconProps={{ name: 'star', 'aria-hidden': 'true' }}>
+  Starred
+</IconText>;
+```
+
+## The five libraries
+
+| Library                | `iconLibrary` / `library` value | Name format                  | Example `name`  |
+| ---------------------- | ------------------------------- | ---------------------------- | --------------- |
+| Font Awesome (default) | `'fa'`                          | kebab-case, no `fa-` prefix  | `rocket`        |
+| Material Design Icons  | `'mdi'`                         | kebab-case, no `mdi-` prefix | `rocket-launch` |
+| Ionicons               | `'ion'`                         | kebab-case                   | `rocket`        |
+| Google Material Icons  | `'material-icons'`              | snake_case (a text ligature) | `rocket_launch` |
+| Material Symbols       | `'material-symbols'`            | snake_case (a text ligature) | `rocket_launch` |
+
+⚠️ **The Ionicons value is `'ion'`, not `'ionicons'`.** The `npm create bestax` scaffold's
+`--icon ionicons` flag maps to `iconLibrary="ion"` — passing `'ionicons'` to `ConfigProvider`
+or `library` silently renders nothing.
+
+**The same glyph has a different name per library** (`rocket` vs `rocket-launch` vs
+`rocket_launch`). When an icon renders blank, the name format for the active library is the
+first thing to check. A redundant `fa-`/`mdi-` prefix in `name` is tolerated (stripped), but
+don't rely on it.
+
+## Styling
+
+- `size` — `'small' | 'medium' | 'large'` sizes the Bulma **container** (`is-small` ≈ 1rem,
+  `is-medium` ≈ 2rem, `is-large` ≈ 3rem box). To scale the **glyph**, use `features`
+  (Font Awesome `'fa-lg'`/`'fa-2x'`) or a Bulma text-size class (`'is-size-3'`).
+- `variant` — per-library style: Font Awesome `solid` (default) / `regular` / `brands` /
+  `light` / `duotone` / `thin`; Material Icons `filled` (default) / `outlined` / `round` /
+  `sharp`; Material Symbols `outlined` (default) / `rounded` / `sharp`; Ionicons `outline` /
+  `sharp`. MDI has no variants. Note Material **Icons** uses `round`, Material **Symbols**
+  uses `rounded`.
+- `features` — extra library classes, string or array: `'fa-spin'`, `['fa-lg', 'fa-border']`.
+- Color via the helper props: `textColor="primary"`, `textColor="danger"`, etc.
+
+## Accessibility
+
+Every `Icon` renders `aria-label` (default `"icon"`), set via its camelCase `ariaLabel` prop.
+Only a few components declare that prop (`Icon`, `Delete`, `Slider`, `Carousel`) — everything
+else takes the standard `aria-label` attribute, e.g. `<Navbar.Burger aria-label="menu" />`.
+
+- **Meaningful icon** (stands alone, conveys information): pass a descriptive
+  `ariaLabel="Delete item"`.
+- **Decorative icon** (next to visible text that says the same thing, e.g. inside `IconText`
+  or a labeled `Button`): hide it from screen readers with `aria-hidden`:
+  `<Icon name="check" aria-hidden="true" />` — otherwise "icon" (or a duplicate label) is
+  announced alongside the text.
+
+## 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.
+- `examples/icon-usage.tsx` — runnable example: ConfigProvider setup, sizes, variants,
+  colors, IconText, and decorative-vs-labeled patterns.