@allxsmith/bestax-bulma 5.26.2 → 5.26.3

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

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

@@ -8,6 +8,8 @@ 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.
  */
 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 +21,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 +38,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,8 @@ 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.
  * @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 +22,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,7 +45,7 @@ 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.
      * Under `prefers-reduced-motion: reduce` the spinner stops and stays
      * drawn (with bestax's CSS loaded).
      */

package/dist/types-cjs/form/TimeInputBase.d.ts

@@ -55,7 +55,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

package/dist/types-cjs/form/_pickerInternals/Calendar.d.ts

@@ -18,7 +18,11 @@ 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;
@@ -38,5 +42,10 @@ 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.
+ */
+export declare const CALENDAR_FOCUSED_CELL = "[data-focused=\"true\"], [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/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

@@ -39,6 +39,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,7 +61,8 @@ 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

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];
     /**