@allxsmith/bestax-bulma 5.26.2 → 5.26.4

package/dist/types-cjs/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-cjs/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-cjs/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-cjs/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-cjs/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-cjs/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-cjs/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-cjs/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-cjs/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-cjs/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. */

package/dist/types-cjs/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-cjs/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-cjs/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-cjs/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-cjs/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-cjs/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-cjs/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-cjs/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-cjs/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-cjs/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];
     /**