create-bestax 2.2.0 → 3.1.0

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

@@ -0,0 +1,77 @@
+# Reference: helper APIs for building components
+
+The shared helpers live in `bulma-ui/src/helpers/`. Import them from there in components.
+
+## `useBulmaClasses(props)` — `helpers/useBulmaClasses.tsx`
+
+Turns Bulma helper props into a class string and returns the leftover (non-helper) props.
+
+```ts
+const { bulmaHelperClasses, rest } = useBulmaClasses(props);
+// bulmaHelperClasses: e.g. 'has-text-primary is-size-3 m-3'
+// rest: every prop that was NOT a recognized helper (safe to spread on the DOM)
+```
+
+`BulmaClassesProps` is the union of all helper prop groups, composed from per-concern hooks
+that can also be used on their own:
+
+| Group      | Hook                   | Representative props                                                                                                             |
+| ---------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| Color      | `useColorClasses`      | `color`, `colorShade`, `backgroundColor`, `backgroundColorShade`                                                                 |
+| Spacing    | `useSpacingClasses`    | `m`, `mt`, `mr`, `mb`, `ml`, `mx`, `my`, `p`, `pt`, `pr`, `pb`, `pl`, `px`, `py`                                                 |
+| Typography | `useTypographyClasses` | `textSize`, `textAlign`, `textTransform`, `textWeight`, `fontFamily` (+ responsive variants)                                     |
+| Visibility | `useVisibilityClasses` | `display`, `visibility` (+ per-viewport variants)                                                                                |
+| Flexbox    | `useFlexboxClasses`    | `flexDirection`, `flexWrap`, `justifyContent`, `alignItems`, `alignContent`, `alignSelf`, `flexGrow`, `flexShrink`               |
+| Other      | `useOtherClasses`      | `float`, `overflow`, `radius`, `shadow`, `interaction`, `cursor`, `skeleton`, `clearfix`, `relative`, `fullHeight`, `responsive` |
+
+Because the component destructures these into `bulmaHelperClasses`, callers get the full Bulma
+helper surface for free on every component, and `rest` stays clean for DOM spreading.
+
+## `classNames(...)` and friends — `helpers/classNames.ts`
+
+```ts
+classNames('foo', ['bar', { baz: true }], { qux: false }); // => 'foo bar baz'
+```
+
+Accepts strings, numbers, arrays, and objects (truthy keys included); flattens recursively and
+de-dupes. Related exports:
+
+- `usePrefixedClassNames(...args)` — **use this in components.** Reads `classPrefix` from the
+  `Config` context and prefixes every class. With `classPrefix="bulma-"`,
+  `usePrefixedClassNames('button', { 'is-primary': true })` → `'bulma-button bulma-is-primary'`.
+- `prefixedClassNames(prefix, ...args)` — non-hook form; pass `undefined` for no prefix.
+- `createPrefixedClassNames(prefix)` — factory returning a bound `classNames`.
+
+## Valid-value constants — `helpers/bulmaClassHelpers.ts`
+
+Re-exported through `useBulmaClasses`. Use them to type component-specific props and to drive
+Storybook `argTypes`/tests:
+
+`validColors`, `validColorShades`, `validSizes`, `validTextSizes`, `validAlignments`,
+`validTextTransforms`, `validTextWeights`, `validFontFamilies`, `validDisplays`,
+`validVisibilities`, `validFlexDirections`, `validFlexWraps`, `validJustifyContents`,
+`validAlignContents`, `validAlignItems`, `validAlignSelfs`, `validFlexGrowShrink`,
+`validViewports`.
+
+```ts
+export type MyColor = (typeof validColors)[number];
+```
+
+## `Config` / `Theme` — `helpers/Config.tsx`, `helpers/Theme.tsx`
+
+`Config` provides the runtime `classPrefix` consumed by `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
+hard-coding values.
+
+## SCSS utilities — from the `bulma` package
+
+```scss
+@use 'bulma/sass/utilities/initial-variables' as iv; // iv.$class-prefix
+@use 'bulma/sass/utilities/css-variables' as cv; // cv.getVar, cv.register-vars
+```
+
+- `iv.$class-prefix` — the configurable class prefix; prepend to every selector.
+- `cv.getVar("name")` — emits `var(--bulma-name)`; use for both Bulma vars (`"primary"`,
+  `"radius"`, `"scheme-main"`, `"text"`) and your own registered vars.
+- `cv.register-vars((...))` — declares `--bulma-*` custom properties on the current selector.

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

@@ -0,0 +1,133 @@
+# Reference: Dialog, the canonical worked example
+
+`Dialog` is the library's reference implementation of the custom-component pattern. Read the
+real files alongside this:
+
+- `bulma-ui/src/components/Dialog.tsx`
+- `bulma-ui/src/scss/components/_dialog.scss`
+- `bulma-ui/src/components/Dialog.stories.tsx`
+- `bulma-ui/src/components/__tests__/Dialog.test.tsx`
+- `docs/docs/api/components/dialog.md`
+
+## What Dialog demonstrates
+
+### Props interface
+
+```tsx
+export type DialogType = 'default' | 'success' | 'danger' | 'warning' | 'info';
+
+export interface DialogProps
+  extends
+    Omit<React.HTMLAttributes<HTMLDivElement>, 'color'>,
+    Omit<BulmaClassesProps, 'color'> {
+  isOpen: boolean;
+  title?: string;
+  message: string | React.ReactNode;
+  type?: DialogType;
+  confirmText?: string;
+  cancelText?: string;
+  onConfirm?: () => void;
+  onCancel?: () => void;
+  showCancel?: boolean;
+  canCancel?: boolean;
+  focusCancel?: boolean;
+  icon?: React.ReactNode;
+}
+```
+
+It omits `color` from both `HTMLAttributes` and `BulmaClassesProps` and exposes its own typed
+`type` variant instead — the standard move when a component has bespoke color/variant semantics.
+
+### Render body
+
+```tsx
+export const Dialog = forwardRef<HTMLDivElement, DialogProps>(
+  (
+    { isOpen, title, message, type = 'default', /* ... */ className, ...props },
+    ref
+  ) => {
+    const { bulmaHelperClasses, rest } = useBulmaClasses(props);
+    const dialogClasses = usePrefixedClassNames('dialog', {
+      [`is-${type}`]: type !== 'default',
+    });
+    const combined = classNames(dialogClasses, bulmaHelperClasses, className);
+    // ...keyboard handling, focus management, scroll lock, render via <Modal>
+  }
+);
+```
+
+Note the order — `usePrefixedClassNames` for the component's own classes, then `classNames`
+merges them with the helper classes and the caller's `className`. `rest` (not `props`) is what
+gets spread onto the DOM node.
+
+### SCSS
+
+`_dialog.scss` is the model for the CSS-variable pattern:
+
+```scss
+@use 'bulma/sass/utilities/initial-variables' as iv;
+@use 'bulma/sass/utilities/css-variables' as cv;
+
+$dialog-width: 420px !default;
+$dialog-radius: cv.getVar('radius') !default;
+$dialog-background: cv.getVar('scheme-main') !default;
+$dialog-title-color: cv.getVar('text-strong') !default;
+
+.#{iv.$class-prefix}dialog {
+  @include cv.register-vars(
+    (
+      'dialog-width': #{$dialog-width},
+      'dialog-radius': #{$dialog-radius},
+      'dialog-background': #{$dialog-background},
+      'dialog-title-color': #{$dialog-title-color},
+    )
+  );
+}
+
+.#{iv.$class-prefix}dialog {
+  width: cv.getVar('dialog-width');
+  background-color: cv.getVar('dialog-background');
+  border-radius: cv.getVar('dialog-radius');
+}
+
+// Variant: colorize the header per type, reusing Bulma's color vars.
+.#{iv.$class-prefix}dialog.#{iv.$class-prefix}is-success
+  .#{iv.$class-prefix}dialog-header {
+  color: cv.getVar('success');
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .#{iv.$class-prefix}dialog {
+    animation: none;
+  }
+}
+```
+
+Takeaways:
+
+1. Local layout values (`$dialog-width`) and Bulma references (`cv.getVar("radius")`) both get a
+   `!default` SCSS var, then are registered so they're overridable at runtime.
+2. Multi-part components (`-header`, `-body`, `-footer`, `-title`, `-icon`) prefix **every**
+   sub-selector with `iv.$class-prefix`.
+3. Variant classes (`is-success`, etc.) are also prefixed, and reuse Bulma's registered color
+   vars (`cv.getVar("success")`) rather than hard-coded hex.
+
+### Beyond the basics
+
+Dialog also shows optional patterns you can borrow when relevant:
+
+- An **imperative API** (`dialog.alert`, `dialog.confirm`, `dialog.close`) plus a
+  `DialogContainer` for programmatic mounting, exported from the same module.
+- **Accessibility**: `role="alertdialog"`, Escape-to-cancel, and focus management on open.
+- **Body scroll lock** via a module-level ref count so chained/overlapping dialogs behave.
+
+These are not required for every component — start from the simple template in `SKILL.md` and
+add only what your component needs.
+
+## Other components worth reading for variety
+
+- `Switch`, `Slider`, `Rate` — components with their own typed `color`/`size`/variant unions.
+- `Carousel`, `Tabs` — components with internal state and sub-elements.
+
+All of them follow the same `useBulmaClasses` + `usePrefixedClassNames` + `classNames` spine and
+the same SCSS register-vars/getVar convention shown above.

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

@@ -0,0 +1,209 @@
+---
+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 into the components via the `color`, `message`, and `messageColor` props. 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).                            |
+| `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`.
+
+## 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 error =
+    touched && !/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email)
+      ? 'Please enter a valid email address.'
+      : undefined;
+
+  return (
+    <form
+      onSubmit={e => {
+        e.preventDefault();
+        setTouched(true);
+        if (!error && email) {
+          // 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.
+
+## 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 `npm run 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.
+
+## Checklist
+
+- [ ] Built from the shipped form components (no hand-rolled inputs / reinvented controls).
+- [ ] Every input has an associated label (`label` prop, or a `<label htmlFor>` when composing).
+- [ ] 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.
+- [ ] **Rendered and visually inspected in a browser** — layout and the error/validation states
+      look right, not just green tests.

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

@@ -0,0 +1,102 @@
+# 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.                                                 |
+| `labelSize`             | `'small' \| 'normal' \| 'medium' \| 'large'`      | Label size.                                                        |
+| `labelProps`            | label attributes                                  | Props for the `<label>`.                                           |
+| `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`, 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'`, …).