@allxsmith/bestax-bulma 5.26.2 → 5.26.4

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;
@@ -55,7 +63,11 @@ export interface TimeInputBaseProps extends Omit<React.InputHTMLAttributes<HTMLI
     closeOnSelect?: boolean;
     /** Popover anchor position relative to the input. */
     position?: PickerPosition;
-    /** Render the popover into `document.body` via portal. */
+    /**
+     * Render the popover into `document.body` via portal. On a narrow screen
+     * an in-place popover spans the bottom of the viewport, while a portaled
+     * one stays on its `position` corner.
+     */
     appendToBody?: boolean;
     /**
      * Bulma color modifier for the input, also carried by the wheels, where it
@@ -83,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;
@@ -18,13 +22,18 @@ export interface CalendarProps {
     size?: 'small' | 'medium' | 'large';
     className?: string;
     id?: string;
-    /** When true, focus the cell matching `focusedDate` after each render. */
+    /**
+     * When true, the day or month grid takes focus as it renders, and again as
+     * it comes back from the year list. With or without it, once a grid has
+     * focus, focus follows its tab stop from cell to cell.
+     */
     autoFocusCell?: boolean;
     /** Optional translatable string overrides. */
     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.
      */
@@ -38,5 +47,11 @@ export interface CalendarProps {
      */
     granularity?: DateGranularity;
 }
+/**
+ * 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. It runs
+ * against the whole panel, so it matches only inside the grid or the list.
+ */
+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/PickerPopover.d.ts

@@ -22,6 +22,12 @@ export interface PickerPopoverProps {
      * would be recorded instead, and that cell leaves with the panel.
      */
     restoreFocusRef?: React.RefObject<HTMLElement | null>;
+    /**
+     * Selects the element in the panel that takes focus as it opens, such as a
+     * calendar's focused date rather than the first button in its header. When
+     * nothing matches, or the match can't take focus, the first tab stop does.
+     */
+    initialFocusSelector?: string;
 }
 export declare const PickerPopover: React.FC<PickerPopoverProps>;
 export default PickerPopover;

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

@@ -11,10 +11,6 @@ type BulmaVars = Partial<Record<BulmaVarKey, string>>;
  *
  * @property {React.ReactNode} children - Content to render inside the theme scope.
  * @property {string} [className] - Additional CSS classes (only when isRoot is false).
- * @property {'light' | 'dark' | 'system'} [colorMode] - Set Bulma's light/dark scheme by writing
- *   the `data-theme` attribute on the document root (`<html>`). This is always global, even on a
- *   scoped Theme. `'system'` removes the attribute so Bulma follows the OS `prefers-color-scheme`.
- *   Omit to leave the current setting untouched.
  * @property {BulmaVars} [bulmaVars] - Object mapping Bulma CSS variable names to values.
  * @property {string} [schemeH] - Scheme hue value.
  * @property {string} [schemeS] - Scheme saturation value.
@@ -76,6 +72,19 @@ export interface ThemeProps extends Omit<BulmaClassesProps, 'color' | 'backgroun
      * server render does not include them.
      */
     isRoot?: boolean;
+    /**
+     * Set Bulma's light/dark scheme by writing its theme attribute on the
+     * document root (`<html>`). This is always global, even on a scoped Theme.
+     * `'system'` removes the attribute so Bulma follows the OS
+     * `prefers-color-scheme`. Omit to leave the current setting untouched.
+     *
+     * The attribute is `data-theme`. A stylesheet built with a class prefix
+     * reads Bulma's prefixed form instead (`data-bestax-theme` for the
+     * `bestax-prefixed` builds), so under a `ConfigProvider` `classPrefix`
+     * Theme writes both, and `'system'` or unmounting clears or restores both.
+     * If the prefix cannot form an attribute name, `'light'` and `'dark'`
+     * write only `data-theme` and warn in development.
+     */
     colorMode?: 'light' | 'dark' | 'system';
     bulmaVars?: BulmaVars;
     /**

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

@@ -56,7 +56,8 @@ export interface PortalProps {
  * Tab order and focus follow the DOM too. Content portaled from inside a
  * focus trap is no longer inside the trapped element, so the trap neither
  * reaches it nor holds focus there: render nested overlays inside the
- * trapped element, or give them a trap of their own.
+ * trapped element, or give them a trap of their own. To trap portaled
+ * content, put `useFocusTrap`'s ref on the element inside the `Portal`.
  *
  * @function
  * @param {PortalProps} props - Props for the Portal component.

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;
@@ -39,6 +42,12 @@ export interface UseAnchoredPositionOptions {
      */
     styledGap?: (panel: HTMLElement) => number;
 }
+/**
+ * A `styledGap` for a panel whose stylesheet puts the gap in a margin on the
+ * side facing the anchor, negative on a portaled panel above it, so the
+ * larger magnitude is the gap. In pixels.
+ */
+export declare function marginGap(panel: HTMLElement): number;
 /**
  * Places a floating panel against its anchor: resolves `auto` to a corner
  * and, for a panel fixed to the viewport, works out its coordinates. It

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

@@ -61,12 +61,20 @@ export interface UseFocusTrapOptions {
  * behaviour, and a modal also has to block the page behind it, which `Modal`
  * does. Content the container renders through a portal lives elsewhere in
  * the DOM, so it is outside the trap: render nested overlays inside the
- * container, or give them a trap of their own.
+ * 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/helpers/useOtherClasses.d.ts

@@ -25,7 +25,17 @@ export interface BulmaOtherProps {
      * on this axis.
      */
     overflowY?: (typeof validAxisOverflows)[number];
-    /** Applies overlay styling if true. */
+    /**
+     * Covers the nearest positioned ancestor (`is-overlay`): `position:
+     * absolute` with `top`, `right`, `bottom` and `left` at 0.
+     *
+     * `pos` and `relative` set `position` with `!important`, so beside
+     * `overlay` either one replaces the `absolute` and keeps the zero offsets.
+     * `pos="fixed"` then covers the viewport instead of the ancestor. `sticky`,
+     * `relative` and `static` put the element back in the normal flow, where it
+     * covers nothing, and a sticky one sticks at every edge of its scroll
+     * container.
+     */
     overlay?: boolean;
     /** Interaction behavior (e.g., 'unselectable', 'clickable'). */
     interaction?: (typeof validInteractions)[number];
@@ -63,6 +73,8 @@ export interface BulmaOtherProps {
      * own CSS. `sticky` in particular does nothing until one is set.
      *
      * When `pos` is set it decides the position, and `relative` adds nothing.
+     * Beside `overlay` it replaces the overlay's `absolute` but not its zero
+     * offsets; see `overlay`.
      */
     pos?: (typeof validPositions)[number];
     /**

package/dist/types-cjs/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-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/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-cjs/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-cjs/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-cjs/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-cjs/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-cjs/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-cjs/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 {};