@allxsmith/bestax-bulma 5.26.2 → 5.26.4

package/dist/types/elements/Progress.d.ts

@@ -18,7 +18,12 @@ export interface ProgressProps extends React.ProgressHTMLAttributes<HTMLProgress
     color?: (typeof validColors)[number];
     /** Size modifier for the progress bar. */
     size?: 'small' | 'medium' | 'large';
-    /** Current value of the progress bar. */
+    /**
+     * Current value of the progress bar. Leave it unset for an indeterminate
+     * bar, which sweeps across the track. Under `prefers-reduced-motion: reduce`
+     * that bar holds still (with bestax's CSS loaded), so it can read as
+     * partly filled.
+     */
     value?: number;
     /** Maximum value of the progress bar. */
     max?: number;

package/dist/types/form/Checkboxes.d.ts

@@ -3,6 +3,13 @@ import { BulmaClassesProps } from '../helpers/useBulmaClasses.js';
 import { FormFieldProps } from './fieldProps.js';
 /**
  * Props for the Checkboxes component.
+ * Inside an existing `Control` it renders no `Control` of its own. Inside an
+ * outer `Field`, or a `Control` with no `Field` around it, it renders no
+ * `Field` of its own either. The exception is `label`, `message`, `horizontal`
+ * or `fieldClassName` in that bare `Control`: it keeps a `Field` for them,
+ * nested in the `.control`, and warns in development. Wrap the `Control` in a
+ * `Field` instead, and set the `label`, `horizontal` and class name on that
+ * `Field`.
  */
 export interface CheckboxesProps extends Omit<BulmaClassesProps, 'color'>, FormFieldProps {
     /** Field label naming the whole group. Automatically associated via `aria-labelledby` on the `role="group"` wrapper — uses your `labelProps.id` when provided, otherwise a generated one. Dropped inside an outer `Field` (label that `Field` yourself). */

package/dist/types/form/Control.d.ts

@@ -13,6 +13,8 @@ export interface ControlBaseProps extends React.HTMLAttributes<HTMLDivElement>,
      * Shows a loading spinner inside the control.
      * Under `prefers-reduced-motion: reduce` the spinner stops and stays
      * drawn (with bestax's CSS loaded).
+     * The spinner sits at the right edge, where a right icon also sits, and the
+     * two overlap; leave the right icon out while loading.
      */
     isLoading?: boolean;
     /** Makes the control expand to fill available space. */
@@ -25,9 +27,19 @@ export interface ControlBaseProps extends React.HTMLAttributes<HTMLDivElement>,
     color?: 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger';
     /** Background color. */
     bgColor?: (typeof validColors)[number] | 'inherit' | 'current';
-    /** Icon props for left icon, or a custom node (an inline SVG, a `react-icons` component, …) rendered in place of a class-based glyph. */
+    /**
+     * Icon props for left icon, or a custom node (an inline SVG, a `react-icons` component, …) rendered in place of a class-based glyph.
+     * Bulma gives control icons `pointer-events: none`, so a click lands on
+     * the input and a clickable node placed here never receives one. Put a button beside the input
+     * in its own addon `Control` instead.
+     */
     iconLeft?: IconProps | React.ReactNode;
-    /** Icon props for right icon, or a custom node (an inline SVG, a `react-icons` component, …) rendered in place of a class-based glyph. */
+    /**
+     * Icon props for right icon, or a custom node (an inline SVG, a `react-icons` component, …) rendered in place of a class-based glyph.
+     * Bulma gives control icons `pointer-events: none`, so a click lands on
+     * the input and a clickable node placed here never receives one. Put a button beside the input
+     * in its own addon `Control` instead.
+     */
     iconRight?: IconProps | React.ReactNode;
     /** Shortcut for left icon name. */
     iconLeftName?: string;

package/dist/types/form/DateInput.d.ts

@@ -5,6 +5,13 @@ import { DateInputBaseProps } from './DateInputBase.js';
 /**
  * Props for the DateInput convenience wrapper. Extends `DateInputBaseProps`
  * with Field-level (label, horizontal) and Control-level (icons, loading) props.
+ * Inside an existing `Control` it renders no `Control` of its own, so set the
+ * Control-level props on that `Control` instead. Inside an outer `Field`, or a
+ * `Control` with no `Field` around it, it renders no `Field` of its own either.
+ * The exception is `label`, `message`, `horizontal` or `fieldClassName` in that
+ * bare `Control`: it keeps a `Field` for them, nested in the `.control`, and
+ * warns in development. Wrap the `Control` in a `Field` instead, and set the
+ * `label`, `horizontal` and class name on that `Field`.
  * @extraProp {string} [name] - Form field name. The text field submits the text it displays. The native input on touch devices submits the ISO value (`YYYY-MM-DD`, or `YYYY-MM` at month granularity), and an `inline` calendar, which has no visible input, submits it from a hidden input (`YYYY-MM-DD`, `YYYY-MM` or `YYYY`).
  * @extraProp {string} [form] - Form id the input belongs to.
  * @extraProp {boolean} [required=false] - Marks the input as required.
@@ -20,9 +27,17 @@ export interface DateInputProps extends DateInputBaseProps {
     labelProps?: FieldProps['labelProps'];
     /** Render the field with horizontal layout. */
     horizontal?: boolean;
-    /** Icon props for the left icon. */
+    /**
+     * Icon props for the left icon.
+     * Bulma gives control icons `pointer-events: none`, so a clickable node here
+     * never receives a click. Put a button beside the input in its own addon `Control` instead.
+     */
     iconLeft?: ControlBaseProps['iconLeft'];
-    /** Icon props for the right icon. */
+    /**
+     * Icon props for the right icon.
+     * Bulma gives control icons `pointer-events: none`, so a clickable node here
+     * never receives a click. Put a button beside the input in its own addon `Control` instead.
+     */
     iconRight?: ControlBaseProps['iconRight'];
     /** Shortcut for the right icon name. */
     iconRightName?: string;
@@ -35,11 +50,21 @@ export interface DateInputProps extends DateInputBaseProps {
     /** Force the right icon container. */
     hasIconsRight?: boolean;
     /**
-     * Show a loading spinner on the control.
+     * Shows a loading spinner on the `Control` it renders, and hides the
+     * launcher (`triggerIcon`) while it does. Inside your own `Control` it
+     * renders none, so this draws nothing; set `isLoading` on that `Control`.
      * Under `prefers-reduced-motion: reduce` the spinner stops and stays
      * drawn (with bestax's CSS loaded).
      */
     isLoading?: boolean;
+    /**
+     * Show a clickable launcher button on the right that toggles the popover.
+     * Hidden by default while a spinner shows at the same right edge: this
+     * component's `isLoading` when it renders its own `Control`, or the
+     * enclosing `Control`'s `isLoading` inside one.
+     * @defaultValue true
+     */
+    triggerIcon?: boolean;
     /** Expand the control to fill its container. */
     isExpanded?: boolean;
     /** Size of the wrapping Control. */

package/dist/types/form/DateInputBase.d.ts

@@ -17,7 +17,11 @@ export interface DateInputBaseProps extends Omit<React.InputHTMLAttributes<HTMLI
     onOpen?: () => void;
     /** Fired when the popover closes. */
     onClose?: () => void;
-    /** Earliest selectable date. */
+    /**
+     * Earliest selectable date. A `min` before year 1 is raised to 1 January of
+     * year 1, where the range starts without one too: HTML's date and month
+     * inputs hold no earlier year, so the calendar and typing stop there.
+     */
     min?: Date;
     /** Latest selectable date. */
     max?: Date;
@@ -54,7 +58,12 @@ export interface DateInputBaseProps extends Omit<React.InputHTMLAttributes<HTMLI
      * @defaultValue 'YYYY-MM-DD'
      */
     format?: DateFormatOption;
-    /** Custom parser (use when `format` is `Intl.DateTimeFormatOptions`). */
+    /**
+     * Custom parser (use when `format` is `Intl.DateTimeFormatOptions`).
+     * Enter and leaving the field call it only if the user changed the text,
+     * so focus passing through commits nothing and the value keeps what the
+     * format leaves out, such as the time of day.
+     */
     parse?: (s: string) => Date | null;
     /** BCP-47 locale tag for day/month names and Intl formatting. */
     locale?: string;
@@ -115,7 +124,12 @@ export interface DateInputBaseProps extends Omit<React.InputHTMLAttributes<HTMLI
     nearbyMonthDays?: boolean;
     /** Decorative left icon glyph for the wrapping `Control` (shown by default). Set `''` to hide. */
     iconLeftName?: string;
-    /** Show a clickable launcher button on the right that toggles the popover. Default `true`. */
+    /**
+     * Show a clickable launcher button on the right that toggles the popover.
+     * Hidden by default while a `Control` it sits in shows its `isLoading`
+     * spinner, which shares that right edge.
+     * @defaultValue true
+     */
     triggerIcon?: boolean;
     /** Glyph for the right launcher button. */
     triggerIconName?: string;

package/dist/types/form/DateTimeInput.d.ts

@@ -5,6 +5,13 @@ import { DateTimeInputBaseProps } from './DateTimeInputBase.js';
 /**
  * Props for the DateTimeInput convenience wrapper. Extends
  * `DateTimeInputBaseProps` with Field-level and Control-level props.
+ * Inside an existing `Control` it renders no `Control` of its own, so set the
+ * Control-level props on that `Control` instead. Inside an outer `Field`, or a
+ * `Control` with no `Field` around it, it renders no `Field` of its own either.
+ * The exception is `label`, `message`, `horizontal` or `fieldClassName` in that
+ * bare `Control`: it keeps a `Field` for them, nested in the `.control`, and
+ * warns in development. Wrap the `Control` in a `Field` instead, and set the
+ * `label`, `horizontal` and class name on that `Field`.
  * @extraProp {string} [name] - Form field name.
  * @extraProp {string} [form] - Optional id of the form the input belongs to.
  * @extraProp {boolean} [required=false] - Marks the field as required for native HTML form validation.
@@ -18,9 +25,17 @@ export interface DateTimeInputProps extends DateTimeInputBaseProps {
     labelProps?: FieldProps['labelProps'];
     /** Render the field with horizontal layout. */
     horizontal?: boolean;
-    /** Icon props for the left icon. */
+    /**
+     * Icon props for the left icon.
+     * Bulma gives control icons `pointer-events: none`, so a clickable node here
+     * never receives a click. Put a button beside the input in its own addon `Control` instead.
+     */
     iconLeft?: ControlBaseProps['iconLeft'];
-    /** Icon props for the right icon. */
+    /**
+     * Icon props for the right icon.
+     * Bulma gives control icons `pointer-events: none`, so a clickable node here
+     * never receives a click. Put a button beside the input in its own addon `Control` instead.
+     */
     iconRight?: ControlBaseProps['iconRight'];
     /** Shortcut for the right icon name. */
     iconRightName?: string;
@@ -33,11 +48,21 @@ export interface DateTimeInputProps extends DateTimeInputBaseProps {
     /** Force the right icon container. */
     hasIconsRight?: boolean;
     /**
-     * Show a loading spinner on the control.
+     * Shows a loading spinner on the `Control` it renders, and hides the
+     * launcher (`triggerIcon`) while it does. Inside your own `Control` it
+     * renders none, so this draws nothing; set `isLoading` on that `Control`.
      * Under `prefers-reduced-motion: reduce` the spinner stops and stays
      * drawn (with bestax's CSS loaded).
      */
     isLoading?: boolean;
+    /**
+     * Show a clickable launcher button on the right that toggles the popover.
+     * Hidden by default while a spinner shows at the same right edge: this
+     * component's `isLoading` when it renders its own `Control`, or the
+     * enclosing `Control`'s `isLoading` inside one.
+     * @defaultValue true
+     */
+    triggerIcon?: boolean;
     /** Expand the control to fill its container. */
     isExpanded?: boolean;
     /** Size of the wrapping Control. */

package/dist/types/form/DateTimeInputBase.d.ts

@@ -18,7 +18,12 @@ export interface DateTimeInputBaseProps extends Omit<React.InputHTMLAttributes<H
     onOpen?: () => void;
     /** Fired when the popover closes. */
     onClose?: () => void;
-    /** Lower bound for the combined date-time. */
+    /**
+     * Lower bound for the combined date-time. A `min` before year 1 is raised
+     * to midnight on 1 January of year 1, where the range starts without one
+     * too: HTML's datetime-local input holds no earlier year, so the calendar,
+     * the time wheels and typing stop there.
+     */
     min?: Date;
     /** Upper bound for the combined date-time. */
     max?: Date;
@@ -33,7 +38,11 @@ export interface DateTimeInputBaseProps extends Omit<React.InputHTMLAttributes<H
      * @defaultValue 'YYYY-MM-DD HH:mm'
      */
     format?: DateFormatOption;
-    /** Custom parser. */
+    /**
+     * Custom parser. Enter and leaving the field call it only if the user
+     * changed the text, so focus passing through commits nothing and the value
+     * keeps what the format leaves out, such as seconds.
+     */
     parse?: (s: string) => Date | null;
     /** BCP-47 locale tag. */
     locale?: string;
@@ -102,7 +111,12 @@ export interface DateTimeInputBaseProps extends Omit<React.InputHTMLAttributes<H
     unselectableTimes?: (d: Date) => boolean;
     /** Decorative left icon glyph for the wrapping `Control` (shown by default). Set `''` to hide. */
     iconLeftName?: string;
-    /** Show a clickable launcher button on the right that toggles the popover. Default `true`. */
+    /**
+     * Show a clickable launcher button on the right that toggles the popover.
+     * Hidden by default while a `Control` it sits in shows its `isLoading`
+     * spinner, which shares that right edge.
+     * @defaultValue true
+     */
     triggerIcon?: boolean;
     /** Glyph for the right launcher button. */
     triggerIconName?: string;

package/dist/types/form/File.d.ts

@@ -3,6 +3,12 @@ import { BulmaClassesProps } from '../helpers/useBulmaClasses.js';
 import { FormFieldProps } from './fieldProps.js';
 /**
  * Props for the File component.
+ * Inside an outer `Field`, or a `Control` with no `Field` around it, it
+ * renders no `Field` of its own. The exception is `label`, `message`,
+ * `horizontal` or `fieldClassName` in that bare `Control`: it keeps a `Field`
+ * for them, nested in the `.control`, and warns in development. Wrap the
+ * `Control` in a `Field` instead, and set the `label`, `horizontal` and class
+ * name on that `Field`.
  */
 export interface FileProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size' | 'color' | 'type'>, Omit<BulmaClassesProps, 'color'>, FormFieldProps {
     /** Field label. Automatically associated with the file input via `htmlFor` — uses your `id` when provided, otherwise a generated one. The input then has two labels (this one plus the wrapping `file-label`); assistive tech reads both. Dropped inside an outer `Field` (label that `Field` yourself). */

package/dist/types/form/FormContext.d.ts

@@ -1,3 +1,4 @@
+import React from 'react';
 /**
  * Hook to detect if the component is inside a Field wrapper.
  * Form components use this to skip rendering their own Field.
@@ -9,9 +10,39 @@ export declare const useInsideField: () => boolean;
  */
 export declare const useInsideControl: () => boolean;
 /** Provider for Field context — used internally by Field component. */
-export declare const FieldProvider: import("react").Provider<boolean>;
+export declare const FieldProvider: React.Provider<boolean>;
 /** Provider for Control context — used internally by Control component. */
-export declare const ControlProvider: import("react").Provider<boolean>;
+export declare const ControlProvider: React.Provider<boolean>;
+/** The wrapper props that change what its own `Field` renders. */
+interface FieldShapingProps {
+    /** Rendered as the `Field`'s label. */
+    label?: React.ReactNode;
+    /** Rendered as help text after the widget. */
+    message?: React.ReactNode;
+    /** Lays the `Field` out horizontally. */
+    horizontal?: boolean;
+    /** Set on the `Field` as its class. */
+    fieldClassName?: string;
+}
+interface OwnFieldOptions extends FieldShapingProps {
+    /** `useInsideField()` as the wrapper read it. */
+    insideField: boolean;
+    /** `useInsideControl()` as the wrapper read it. */
+    insideControl: boolean;
+}
+/**
+ * Whether a convenience form wrapper renders a `Field` of its own (#905).
+ * Never inside an outer `Field`. Inside a `Control` with no `Field` around
+ * it, a `Field` of its own would put a `.field` inside the `.control`, where
+ * Bulma's control styles break (its icon rules are sibling selectors on the
+ * input). So it renders one there only when a prop that shapes the `Field`'s
+ * markup is set (`label`, `message`, `horizontal`, `fieldClassName`), keeping
+ * the markup it always had, and warns in development that the fix is a
+ * `Field` around that `Control`. A prop counts when it is truthy, the same
+ * test that decides whether it changes the `Field`'s output.
+ * Internal; not part of the public API.
+ */
+export declare const rendersOwnField: (component: string, options: OwnFieldOptions) => boolean;
 /**
  * The id a labeled Field wants its single composed control to adopt (#495).
  * `undefined` outside a Field, in unlabeled/grouped/addons Fields, or when the
@@ -21,7 +52,7 @@ export declare const ControlProvider: import("react").Provider<boolean>;
  */
 export declare const useFieldLabelId: () => string | undefined;
 /** Provider for the Field label-target id — used internally by Field. */
-export declare const FieldLabelIdProvider: import("react").Provider<string | undefined>;
+export declare const FieldLabelIdProvider: React.Provider<string | undefined>;
 /**
  * Shape of the Radios group context. The group provides:
  * - `name`: shared form field name (Stage 1)
@@ -69,10 +100,11 @@ export declare const useRadiosName: () => string | undefined;
  */
 export declare const useCheckboxesName: () => string | undefined;
 /** Provider for the Radios group context — used internally by Radios. */
-export declare const RadiosProvider: import("react").Provider<RadiosGroupContextValue | undefined>;
+export declare const RadiosProvider: React.Provider<RadiosGroupContextValue | undefined>;
 /** Provider for the Checkboxes group context — used internally by Checkboxes. */
-export declare const CheckboxesProvider: import("react").Provider<CheckboxesGroupContextValue | undefined>;
+export declare const CheckboxesProvider: React.Provider<CheckboxesGroupContextValue | undefined>;
 /** @deprecated Use `RadiosProvider` (provides {name, value, onChange}). */
-export declare const RadiosNameProvider: import("react").Provider<RadiosGroupContextValue | undefined>;
+export declare const RadiosNameProvider: React.Provider<RadiosGroupContextValue | undefined>;
 /** @deprecated Use `CheckboxesProvider` (provides {name, value, onChange}). */
-export declare const CheckboxesNameProvider: import("react").Provider<CheckboxesGroupContextValue | undefined>;
+export declare const CheckboxesNameProvider: React.Provider<CheckboxesGroupContextValue | undefined>;
+export {};

package/dist/types/form/Input.d.ts

@@ -8,6 +8,13 @@ import { InputBaseProps } from './InputBase.js';
  * Composes Field, Control, and Input into a single convenience component.
  * Supports all Input props, plus Field-level (label, horizontal) and
  * Control-level (icons, loading) props.
+ * Inside an existing `Control` it renders no `Control` of its own, so set the
+ * Control-level props on that `Control` instead. Inside an outer `Field`, or a
+ * `Control` with no `Field` around it, it renders no `Field` of its own either.
+ * The exception is `label`, `message`, `horizontal` or `fieldClassName` in that
+ * bare `Control`: it keeps a `Field` for them, nested in the `.control`, and
+ * warns in development. Wrap the `Control` in a `Field` instead, and set the
+ * `label`, `horizontal` and class name on that `Field`.
  */
 export interface InputProps extends InputBaseProps {
     /** Field label. Automatically associated with the input via `htmlFor` — uses your `id` when provided, otherwise a generated one. Dropped inside an outer `Field`, whose own label associates instead when that `Field` generates a target id (not `grouped`/`hasAddons`, no explicit `labelProps.htmlFor`). */
@@ -18,9 +25,17 @@ export interface InputProps extends InputBaseProps {
     labelProps?: FieldProps['labelProps'];
     /** Horizontal field layout. */
     horizontal?: boolean;
-    /** Icon props for left icon. */
+    /**
+     * Icon props for left icon.
+     * Bulma gives control icons `pointer-events: none`, so a clickable node here
+     * never receives a click. Put a button beside the input in its own addon `Control` instead.
+     */
     iconLeft?: ControlBaseProps['iconLeft'];
-    /** Icon props for right icon. */
+    /**
+     * Icon props for right icon.
+     * Bulma gives control icons `pointer-events: none`, so a clickable node here
+     * never receives a click. Put a button beside the input in its own addon `Control` instead.
+     */
     iconRight?: ControlBaseProps['iconRight'];
     /** Shortcut for left icon name. */
     iconLeftName?: string;
@@ -35,9 +50,11 @@ export interface InputProps extends InputBaseProps {
     /** Force right icon container. */
     hasIconsRight?: boolean;
     /**
-     * Shows a loading spinner on the wrapping Control.
+     * Shows a loading spinner on the `Control` it renders.
      * Under `prefers-reduced-motion: reduce` the spinner stops and stays
      * drawn (with bestax's CSS loaded).
+     * The spinner sits at the right edge, where `iconRight` also sits, and the
+     * two overlap; leave the right icon out while loading.
      */
     isLoading?: boolean;
     /** Expand the control. */
@@ -54,7 +71,7 @@ export interface InputProps extends InputBaseProps {
     controlClassName?: string;
 }
 /**
- * The `Input` component provides a Bulma-styled text input, supporting colors, sizes, rounded corners, static/read-only state, hover/focus/loading states, and all Bulma helper props.
+ * The `Input` component provides a Bulma-styled text input, supporting colors, sizes, rounded corners, static state, hover/focus/loading states, and all Bulma helper props.
  *
  * @function
  * @param {InputProps} props - Props for Input.

package/dist/types/form/InputBase.d.ts

@@ -10,13 +10,16 @@ export interface InputBaseProps extends Omit<React.InputHTMLAttributes<HTMLInput
     size?: 'small' | 'medium' | 'large';
     /** Rounded input corners. */
     isRounded?: boolean;
-    /** Renders input as static (read only, styled). */
+    /** Styles the input as static text. It stays editable; add `readOnly` to stop edits. */
     isStatic?: boolean;
     /** Applies hovered state. */
     isHovered?: boolean;
     /** Applies focused state. */
     isFocused?: boolean;
-    /** Shows loading indicator. */
+    /**
+     * Adds the `is-loading` class to the `<input>`. Bulma draws no spinner for it there: the
+     * spinner belongs to the wrapping `Control`, so set `isLoading` on that `Control`.
+     */
     isLoading?: boolean;
     /** Additional CSS classes to apply. */
     className?: string;

package/dist/types/form/Radios.d.ts

@@ -3,6 +3,13 @@ import { BulmaClassesProps } from '../helpers/useBulmaClasses.js';
 import { FormFieldProps } from './fieldProps.js';
 /**
  * Props for the Radios component.
+ * Inside an existing `Control` it renders no `Control` of its own. Inside an
+ * outer `Field`, or a `Control` with no `Field` around it, it renders no
+ * `Field` of its own either. The exception is `label`, `message`, `horizontal`
+ * or `fieldClassName` in that bare `Control`: it keeps a `Field` for them,
+ * nested in the `.control`, and warns in development. Wrap the `Control` in a
+ * `Field` instead, and set the `label`, `horizontal` and class name on that
+ * `Field`.
  */
 export interface RadiosProps extends Omit<BulmaClassesProps, 'color'>, FormFieldProps {
     /** Field label naming the whole group. Automatically associated via `aria-labelledby` on the `role="radiogroup"` wrapper — uses your `labelProps.id` when provided, otherwise a generated one. Dropped inside an outer `Field` (label that `Field` yourself). */

package/dist/types/form/Rate.d.ts

@@ -22,6 +22,13 @@ export interface RateIconProps {
 }
 /**
  * Props for the Rate component.
+ * Inside an existing `Control` it renders no `Control` of its own. Inside an
+ * outer `Field`, or a `Control` with no `Field` around it, it renders no
+ * `Field` of its own either. The exception is `label`, `message`, `horizontal`
+ * or `fieldClassName` in that bare `Control`: it keeps a `Field` for them,
+ * nested in the `.control`, and warns in development. Wrap the `Control` in a
+ * `Field` instead, and set the `label`, `horizontal` and class name on that
+ * `Field`.
  * @extraProp {string} [className] - Additional CSS classes.
  * @extraProp {React.Ref<HTMLElement>} [ref] - Ref forwarded to the container element.
  */

package/dist/types/form/Select.d.ts

@@ -7,7 +7,14 @@ import { SelectBaseProps } from './SelectBase.js';
  *
  * Composes Field, Control, and SelectBase into a single convenience component.
  * Supports all SelectBase props, plus Field-level (label, horizontal) and
- * Control-level (icons, loading) props.
+ * Control-level (icons) props.
+ * Inside an existing `Control` it renders no `Control` of its own, so set the
+ * Control-level props on that `Control` instead. Inside an outer `Field`, or a
+ * `Control` with no `Field` around it, it renders no `Field` of its own either.
+ * The exception is `label`, `message`, `horizontal` or `fieldClassName` in that
+ * bare `Control`: it keeps a `Field` for them, nested in the `.control`, and
+ * warns in development. Wrap the `Control` in a `Field` instead, and set the
+ * `label`, `horizontal` and class name on that `Field`.
  */
 export interface SelectProps extends SelectBaseProps {
     /** Field label. Automatically associated with the select via `htmlFor` — uses your `id` when provided, otherwise a generated one. Dropped inside an outer `Field`, whose own label associates instead when that `Field` generates a target id (not `grouped`/`hasAddons`, no explicit `labelProps.htmlFor`). */
@@ -18,7 +25,11 @@ export interface SelectProps extends SelectBaseProps {
     labelProps?: FieldProps['labelProps'];
     /** Horizontal field layout. */
     horizontal?: boolean;
-    /** Icon props for left icon. */
+    /**
+     * Icon props for left icon.
+     * Bulma gives control icons `pointer-events: none`, so a clickable node here
+     * never receives a click. Put a button beside the input in its own addon `Control` instead.
+     */
     iconLeft?: ControlBaseProps['iconLeft'];
     /** Shortcut for left icon name. */
     iconLeftName?: string;

package/dist/types/form/Slider.d.ts

@@ -117,6 +117,13 @@ export interface SliderRangeProps extends SliderBaseProps {
 }
 /**
  *  Props for the Slider component — a discriminated union of single and range modes.
+ * Inside an existing `Control` it renders no `Control` of its own. Inside an
+ * outer `Field`, or a `Control` with no `Field` around it, it renders no
+ * `Field` of its own either. The exception is `label`, `message`, `horizontal`
+ * or `fieldClassName` in that bare `Control`: it keeps a `Field` for them,
+ * nested in the `.control`, and warns in development. Wrap the `Control` in a
+ * `Field` instead, and set the `label`, `horizontal` and class name on that
+ * `Field`.
  * @extraProp {boolean} [disabled=false] - Whether the slider is disabled.
  * @extraProp {string} [className] - Additional CSS classes.
  * @extraProp {React.Ref<HTMLElement>} [ref] - Ref forwarded to the input element.

package/dist/types/form/Taginput.d.ts

@@ -16,6 +16,12 @@ export type TaginputTag = TaginputItem | string;
 type IconLibrary = 'fa' | 'mdi' | 'ion' | 'material-icons' | 'material-symbols';
 /**
  * Props for the Taginput component.
+ * Inside an outer `Field`, or a `Control` with no `Field` around it, it
+ * renders no `Field` of its own. The exception is `label`, `message`,
+ * `horizontal` or `fieldClassName` in that bare `Control`: it keeps a `Field`
+ * for them, nested in the `.control`, and warns in development. Wrap the
+ * `Control` in a `Field` instead, and set the `label`, `horizontal` and class
+ * name on that `Field`.
  * @extraProp {string} [className] - Additional CSS classes.
  * @extraProp {React.Ref<HTMLInputElement>} [ref] - Ref forwarded to the input element.
  */

package/dist/types/form/TextArea.d.ts

@@ -8,6 +8,13 @@ import { TextAreaBaseProps } from './TextAreaBase.js';
  * Composes Field, Control, and TextAreaBase into a single convenience component.
  * Supports all TextAreaBase props, plus Field-level (label, horizontal) and
  * Control-level (loading) props.
+ * Inside an existing `Control` it renders no `Control` of its own, so set the
+ * Control-level props on that `Control` instead. Inside an outer `Field`, or a
+ * `Control` with no `Field` around it, it renders no `Field` of its own either.
+ * The exception is `label`, `message`, `horizontal` or `fieldClassName` in that
+ * bare `Control`: it keeps a `Field` for them, nested in the `.control`, and
+ * warns in development. Wrap the `Control` in a `Field` instead, and set the
+ * `label`, `horizontal` and class name on that `Field`.
  */
 export interface TextAreaProps extends TextAreaBaseProps {
     /** Field label. Automatically associated with the textarea via `htmlFor` — uses your `id` when provided, otherwise a generated one. Dropped inside an outer `Field`, whose own label associates instead when that `Field` generates a target id (not `grouped`/`hasAddons`, no explicit `labelProps.htmlFor`). */
@@ -19,7 +26,7 @@ export interface TextAreaProps extends TextAreaBaseProps {
     /** Horizontal field layout. */
     horizontal?: boolean;
     /**
-     * Shows a loading spinner on the wrapping Control.
+     * Shows a loading spinner on the `Control` it renders.
      * Under `prefers-reduced-motion: reduce` the spinner stops and stays
      * drawn (with bestax's CSS loaded).
      */
@@ -36,7 +43,7 @@ export interface TextAreaProps extends TextAreaBaseProps {
     controlClassName?: string;
 }
 /**
- * The `TextArea` component provides a Bulma-styled multi-line text input, supporting color, size, rounded corners, static/read-only state, hover/focus/loading states, fixed size, and all Bulma helper props.
+ * The `TextArea` component provides a Bulma-styled multi-line text input, supporting color, size, hover/focus/loading states, fixed size, and all Bulma helper props.
  *
  * @function
  * @param {TextAreaProps} props - Props for TextArea.

package/dist/types/form/TextAreaBase.d.ts

@@ -8,15 +8,24 @@ export interface TextAreaBaseProps extends Omit<React.TextareaHTMLAttributes<HTM
     color?: 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger' | 'black' | 'dark' | 'light' | 'white';
     /** Size modifier for the textarea. */
     size?: 'small' | 'medium' | 'large';
-    /** Rounded textarea corners. */
+    /**
+     * Adds the `is-rounded` class to the `<textarea>`. Bulma styles it on `.input` only, so the
+     * textarea's corners don't change.
+     */
     isRounded?: boolean;
-    /** Renders textarea as static (styled readonly). */
+    /**
+     * Adds the `is-static` class to the `<textarea>`. Bulma styles it on `.input` only, so the
+     * textarea keeps its border, background and padding.
+     */
     isStatic?: boolean;
     /** Applies hovered state. */
     isHovered?: boolean;
     /** Applies focused state. */
     isFocused?: boolean;
-    /** Shows loading indicator on the wrapping Control. */
+    /**
+     * Accepted and ignored: `TextAreaBase` renders no loading state. The spinner belongs to the
+     * wrapping `Control`, so set `isLoading` on that `Control`.
+     */
     isLoading?: boolean;
     /** Applies Bulma's is-active modifier. */
     isActive?: boolean;

package/dist/types/form/TimeInput.d.ts

@@ -5,6 +5,13 @@ import { TimeInputBaseProps } from './TimeInputBase.js';
 /**
  * Props for the TimeInput convenience wrapper. Extends `TimeInputBaseProps`
  * with Field-level (label, horizontal) and Control-level (icons, loading) props.
+ * Inside an existing `Control` it renders no `Control` of its own, so set the
+ * Control-level props on that `Control` instead. Inside an outer `Field`, or a
+ * `Control` with no `Field` around it, it renders no `Field` of its own either.
+ * The exception is `label`, `message`, `horizontal` or `fieldClassName` in that
+ * bare `Control`: it keeps a `Field` for them, nested in the `.control`, and
+ * warns in development. Wrap the `Control` in a `Field` instead, and set the
+ * `label`, `horizontal` and class name on that `Field`.
  * @extraProp {string} [name] - Form field name.
  * @extraProp {string} [form] - Form id the input belongs to.
  * @extraProp {boolean} [required=false] - Marks the input as required.
@@ -20,9 +27,17 @@ export interface TimeInputProps extends TimeInputBaseProps {
     labelProps?: FieldProps['labelProps'];
     /** Render the field with horizontal layout. */
     horizontal?: boolean;
-    /** Icon props for the left icon. */
+    /**
+     * Icon props for the left icon.
+     * Bulma gives control icons `pointer-events: none`, so a clickable node here
+     * never receives a click. Put a button beside the input in its own addon `Control` instead.
+     */
     iconLeft?: ControlBaseProps['iconLeft'];
-    /** Icon props for the right icon. */
+    /**
+     * Icon props for the right icon.
+     * Bulma gives control icons `pointer-events: none`, so a clickable node here
+     * never receives a click. Put a button beside the input in its own addon `Control` instead.
+     */
     iconRight?: ControlBaseProps['iconRight'];
     /** Shortcut for the right icon name. */
     iconRightName?: string;
@@ -35,11 +50,21 @@ export interface TimeInputProps extends TimeInputBaseProps {
     /** Force the right icon container. */
     hasIconsRight?: boolean;
     /**
-     * Show a loading spinner on the control.
+     * Shows a loading spinner on the `Control` it renders, and hides the
+     * launcher (`triggerIcon`) while it does. Inside your own `Control` it
+     * renders none, so this draws nothing; set `isLoading` on that `Control`.
      * Under `prefers-reduced-motion: reduce` the spinner stops and stays
      * drawn (with bestax's CSS loaded).
      */
     isLoading?: boolean;
+    /**
+     * Show a clickable launcher button on the right that toggles the popover.
+     * Hidden by default while a spinner shows at the same right edge: this
+     * component's `isLoading` when it renders its own `Control`, or the
+     * enclosing `Control`'s `isLoading` inside one.
+     * @defaultValue true
+     */
+    triggerIcon?: boolean;
     /** Expand the control to fill its container. */
     isExpanded?: boolean;
     /** Size of the wrapping Control. */