@allxsmith/bestax-bulma 5.26.3 → 5.26.4

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/DateInput.d.ts

@@ -5,8 +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` within a `Field` it renders no `Field` or
- * `Control` of its own, so set the Control-level props on that `Control` instead.
+ * 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.
@@ -45,11 +50,21 @@ export interface DateInputProps extends DateInputBaseProps {
     /** Force the right icon container. */
     hasIconsRight?: boolean;
     /**
-     * Shows a loading spinner on the `Control` it renders.
+     * 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,8 +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` within a `Field` it renders no `Field` or
- * `Control` of its own, so set the Control-level props on that `Control` instead.
+ * 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.
@@ -43,11 +48,21 @@ export interface DateTimeInputProps extends DateTimeInputBaseProps {
     /** Force the right icon container. */
     hasIconsRight?: boolean;
     /**
-     * Shows a loading spinner on the `Control` it renders.
+     * 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,8 +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` within a `Field` it renders no `Field` or
- * `Control` of its own, so set the Control-level props on that `Control` instead.
+ * 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`). */

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

@@ -8,8 +8,13 @@ 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) props.
- * Inside an existing `Control` within a `Field` it renders no `Field` or
- * `Control` of its own, so set the Control-level props on that `Control` instead.
+ * 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`). */

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,8 +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` within a `Field` it renders no `Field` or
- * `Control` of its own, so set the Control-level props on that `Control` instead.
+ * 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`). */

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

@@ -5,8 +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` within a `Field` it renders no `Field` or
- * `Control` of its own, so set the Control-level props on that `Control` instead.
+ * 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.
@@ -45,11 +50,21 @@ export interface TimeInputProps extends TimeInputBaseProps {
     /** Force the right icon container. */
     hasIconsRight?: boolean;
     /**
-     * Shows a loading spinner on the `Control` it renders.
+     * 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/TimeInputBase.d.ts

@@ -17,7 +17,11 @@ export interface TimeInputBaseProps extends Omit<React.InputHTMLAttributes<HTMLI
     onOpen?: () => void;
     /** Fired when the popover closes. */
     onClose?: () => void;
-    /** Earliest selectable time. */
+    /**
+     * Earliest selectable time. A `min` before year 1 is raised to midnight on
+     * 1 January of year 1, and a `value` dated before then is out of range, so
+     * the wheels and typing change nothing on it, as in the date pickers.
+     */
     min?: Date;
     /** Latest selectable time. */
     max?: Date;
@@ -32,7 +36,11 @@ export interface TimeInputBaseProps extends Omit<React.InputHTMLAttributes<HTMLI
      * @defaultValue (see below)
      */
     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 and the date.
+     */
     parse?: (s: string) => Date | null;
     /** BCP-47 locale tag for Intl formatting. */
     locale?: string;
@@ -87,7 +95,12 @@ export interface TimeInputBaseProps extends Omit<React.InputHTMLAttributes<HTMLI
     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/_pickerInternals/Calendar.d.ts

@@ -5,6 +5,10 @@ export interface CalendarProps {
     focusedDate: Date;
     onSelect: (d: Date) => void;
     onFocusedDateChange: (d: Date) => void;
+    /**
+     * Earliest selectable date. One before year 1, or none, counts as the start
+     * of year 1.
+     */
     min?: Date;
     max?: Date;
     shouldDisableDate?: (d: Date) => boolean;
@@ -28,7 +32,8 @@ export interface CalendarProps {
     labels?: PickerLabels;
     /**
      * Inclusive `[min, max]` year range shown in the year-dropdown view.
-     * Defaults to ±100 years around the focused year, clamped by `min`/`max`.
+     * Defaults to ±100 years around the focused year, clamped by `min`/`max`
+     * and never reaching below year 1.
      * At `'year'` granularity the window centres on the year focused when the
      * calendar mounted, so moving focus never reflows the list.
      */
@@ -44,8 +49,9 @@ export interface CalendarProps {
 }
 /**
  * Selects the calendar's focused cell, the one tab stop of whichever grid or
- * year list is on show, for a popover to put focus on as it opens.
+ * year list is on show, for a popover to put focus on as it opens. It runs
+ * against the whole panel, so it matches only inside the grid or the list.
  */
-export declare const CALENDAR_FOCUSED_CELL = "[data-focused=\"true\"], [data-focused-year=\"true\"]";
+export declare const CALENDAR_FOCUSED_CELL = "[role=\"grid\"] [data-focused=\"true\"], [role=\"listbox\"] [data-focused-year=\"true\"]";
 export declare const Calendar: React.FC<CalendarProps>;
 export default Calendar;

package/dist/types/form/_pickerInternals/dateUtils.d.ts

@@ -19,6 +19,18 @@ export declare function endOfMonth(d: Date): Date;
  * turning into 1900–1999.
  */
 export declare function makeDate(year: number, month?: number, day?: number): Date;
+/**
+ * The earliest year the pickers accept. HTML's date, month and datetime-local
+ * inputs hold no year below 1, so the calendar, typing and parsing stop there
+ * too.
+ */
+export declare const FIRST_YEAR = 1;
+/**
+ * The lower bound a picker applies: `min`, raised to local midnight on
+ * 1 January of {@link FIRST_YEAR} when it is earlier or absent. A `min` in
+ * range comes back as the same object.
+ */
+export declare function floorMin(min?: Date): Date;
 /**
  * First instant of the day, month or year containing `d`. Works by setters on
  * a copy rather than the `Date(y, m, d)` constructor, which reads years 0–99
@@ -64,6 +76,11 @@ export declare function getTimeOfDay(d: Date): {
     minutes: number;
     seconds: number;
 };
+/**
+ * A copy of `d` moved into `[min, max]`. When `min` is after `max` nothing is
+ * in range and `min` wins, so clamping twice gives the same date and a
+ * picker's focus stays off the years before 1 under a `max` before then.
+ */
 export declare function clampDate(d: Date, min?: Date, max?: Date): Date;
 /**
  * Snap a Date's time-of-day to the nearest grid defined by the given

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

@@ -0,0 +1,4 @@
+/** Provider for the loading state, used internally by `Control`. */
+export declare const ControlLoadingProvider: import("react").Provider<boolean>;
+/** Whether the nearest enclosing `Control` is loading; `false` outside one. */
+export declare const useControlLoading: () => boolean;

package/dist/types/helpers/useAnchoredPosition.d.ts

@@ -28,7 +28,10 @@ export interface UseAnchoredPositionOptions {
     /**
      * The gap between the anchor and the panel, in pixels, that the hook puts
      * there itself: added to the fixed coordinates and to the room `auto` asks
-     * for below the anchor.
+     * for below the anchor. Popover and the pickers' popover pass `0` and take
+     * their gap from a margin in their stylesheet, read through `styledGap`, so
+     * a theme's offset moves the panel and `auto` alike. A new panel should do
+     * the same rather than rely on this default, which no stylesheet sees.
      * @defaultValue 4
      */
     offset?: number;

package/dist/types/helpers/useFocusTrap.d.ts

@@ -64,10 +64,17 @@ export interface UseFocusTrapOptions {
  * container, or give them a trap of their own. To trap content a `Portal`
  * renders, pass a ref to the element inside the `Portal` as `containerRef`.
  *
- * The container has to be in the DOM when the trap turns on. The trap waits
- * for hydration, so a container that only appears once the page has
- * hydrated, the way portaled content does, still has it attach in the commit
- * where the container appears.
+ * The trap looks at `containerRef` again each time the component calling it
+ * renders. A container that mounts after the trap turns on, such as a panel
+ * waiting for a `Portal` target held in state, has it attach once that
+ * component renders with the container in the DOM. When the container leaves
+ * or is replaced, the trap lets go of it as it would turning off, handing
+ * focus back, and attaches to the next one.
+ * A child that mounts the container in a render of its own (from its own
+ * state, or as a `Suspense` boundary resolves) goes unseen until the
+ * component calling the hook renders again. The trap waits for hydration, so
+ * that component renders again when the page hydrates, and portaled content,
+ * which first appears then, is found.
  *
  * @function useFocusTrap
  * @param containerRef - Ref to the element focus stays inside.

package/dist/types-cjs/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-cjs/form/DateInput.d.ts

@@ -5,8 +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` within a `Field` it renders no `Field` or
- * `Control` of its own, so set the Control-level props on that `Control` instead.
+ * 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.
@@ -45,11 +50,21 @@ export interface DateInputProps extends DateInputBaseProps {
     /** Force the right icon container. */
     hasIconsRight?: boolean;
     /**
-     * Shows a loading spinner on the `Control` it renders.
+     * 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. */