@allxsmith/bestax-bulma 5.57.1 → 5.57.3

package/dist/types/components/Toast.d.ts

@@ -50,9 +50,17 @@ export interface ToastProps extends Omit<React.HTMLAttributes<HTMLDivElement>, '
     onAction?: () => void;
     /** Callback when toast closes. */
     onClose?: () => void;
-    /** CSS selector or DOM node to mount the toast into. */
+    /**
+     * CSS selector or DOM node to mount the toast into. Through `toast.show()`,
+     * a toast with one portals there in a box of its own, rather than joining
+     * `ToastContainer`'s stack for its position.
+     */
     container?: string | HTMLElement;
-    /** Renders inline instead of using a portal. */
+    /**
+     * Renders inline instead of using a portal. Through `toast.show()`, a toast
+     * already renders inline in `ToastContainer`'s stack for its position, and
+     * `inline` keeps one with a `container` in that stack too.
+     */
     inline?: boolean;
 }
 /**
@@ -153,7 +161,10 @@ export declare const toast: {
  * Container component for rendering programmatic toasts.
  * Place once at your app root to enable the toast API. A toast shown with a
  * `position` appears there, and one shown without goes to the container's
- * `position`.
+ * `position`. The toasts at one position stack in one `.toast-container`,
+ * with a gap between them, in the order they were shown, growing away from
+ * the edge of the screen. A toast shown with a `container` of its own, and
+ * not `inline`, portals there instead, in a box of its own.
  *
  * @function
  * @param {{ position?: ToastPosition }} props - Container props.

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

@@ -13,9 +13,9 @@ export interface TrProps extends Omit<React.HTMLAttributes<HTMLTableRowElement>,
     /**
      * Whether the row is selected (adds Bulma's is-selected class). It's a look
      * only: it says nothing to assistive tech, so pair it with a checkbox named
-     * for the row when the selection matters. A bestax `Checkbox` placed
-     * straight in one of the row's cells takes the row's text color, so a
-     * checked box shows on the row's fill. One in a menu or a table nested in a
+     * for the row when the selection matters. A bestax `Checkbox` or `Radio`
+     * placed straight in one of the row's cells takes the row's text color, so
+     * a checked one shows on the row's fill. One in a menu or a table nested in a
      * cell, or in a cell with a `color` of its own, keeps its own colors, since
      * it sits on that surface instead, and so does every one in a row with a
      * `color`, whose cells paint that color over the fill.

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

@@ -7,7 +7,7 @@ declare const checkboxCardColors: readonly ["primary", "link", "info", "success"
  * @helperProps Helper props go on the outer `<label>`, the `.card`, with
  * `className`. The other attributes go on the `<input>`.
  * @extraProp {string} [name] - The form field name. Inside `Checkboxes`, the group's `name` when this is unset.
- * @extraProp {string} [value] - What a form sends for the card when it's checked. Inside a `Checkboxes` group that takes `value`, `defaultValue` or `onChange`, the card is checked while the group's value holds it.
+ * @extraProp {string} [value] - What a form sends for the card when it's checked. Inside a `Checkboxes` group that takes `value`, `defaultValue` or `onChange`, the card is checked while the group's value holds it. A group given only `onChange` starts from the cards' own `defaultChecked`.
  */
 export interface CheckboxCardProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size' | 'type' | 'color' | 'title'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor' | 'size'> {
     /**

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

@@ -26,7 +26,13 @@ export interface CheckboxesProps extends Omit<BulmaClassesProps, 'color'>, FormF
     value?: string[];
     /** Initial selected values (uncontrolled mode). */
     defaultValue?: string[];
-    /** Fires when the selection changes; receives the new array. */
+    /**
+     * Fires when the selection changes; receives the new array. Passed without
+     * `value` or `defaultValue`, it still has the group manage the selection,
+     * starting from the checkboxes' own `defaultChecked`: a box that starts
+     * checked stays checked when another is clicked, and the first array holds
+     * it.
+     */
     onChange?: (values: string[]) => void;
     /** Checkbox elements to render in the group. */
     children?: React.ReactNode;

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

@@ -210,21 +210,54 @@ export declare const useFieldLabelTarget: (id: string | undefined, hasInput?: bo
  * (i.e., the user passed `value`, `defaultValue`, or `onChange` to `<Radios>`).
  * When only `name` is provided, the group is in "name-only" mode and child
  * Radios manage their own checked state independently.
+ *
+ * A group given only `onChange` manages the selection but holds no value
+ * until its first change. Until then a Radio with a value shows its own
+ * `defaultChecked`, still controlled, so that change doesn't flip it from
+ * uncontrolled to controlled.
  */
 export interface RadiosGroupContextValue {
     name?: string;
-    value?: string;
+    /** `null` once a radio without a value was picked before the group held one, so no radio with a value shows checked. */
+    value?: string | null;
     onChange?: (value: string) => void;
+    /** Set with `onChange`. Tells the group a radio without a value, sharing its name, was picked. */
+    pickWithoutValue?: () => void;
 }
+/**
+ * Tells a surrounding `<Radios>` that one of its radios was picked. A radio
+ * with a value hands the group that value. One without a value tells the
+ * group nothing it reports, but when it shares the group's name the browser
+ * has just unchecked the radio that showed checked, so the group learns the
+ * pick left its radios and React doesn't check that one again, undoing the
+ * pick. `Radio` and `RadioCard` call it with their effective name.
+ */
+export declare const pickInRadiosGroup: (group: RadiosGroupContextValue | undefined, value: string | number | readonly string[] | undefined, name: string | undefined) => void;
 /**
  * Shape of the Checkboxes group context. Like Radios but with array semantics
  * for multi-select.
+ *
+ * While the group manages the selection it also sets `registerChecked` and
+ * `startingValue`. A group given only `onChange` holds no value until its
+ * first change, so its choices register the values they start checked with,
+ * and that change starts from them rather than from an empty array.
  */
 export interface CheckboxesGroupContextValue {
     name?: string;
     value?: string[];
     onChange?: (values: string[]) => void;
+    /** Registers a value a choice starts checked with, and returns the function that takes it back. */
+    registerChecked?: (value: string) => () => void;
+    /** The values registered as starting checked, each once, in the order they came. */
+    startingValue?: () => string[];
 }
+/**
+ * Registers a choice with its surrounding `<Checkboxes>` while it starts
+ * checked, so a group with no value yet starts its first change from the
+ * choices that were checked. `Checkbox` and `CheckboxCard` call it. It does
+ * nothing outside a group that manages the selection, or without a value.
+ */
+export declare const useRegisterChecked: (group: CheckboxesGroupContextValue | undefined, value: string | undefined, startsChecked: boolean) => void;
 /**
  * Hook to read the full surrounding `<Radios>` group context (name + selection).
  * Returns `undefined` when not inside a `<Radios>` group.

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

@@ -7,7 +7,7 @@ declare const radioCardColors: readonly ["primary", "link", "info", "success", "
  * @helperProps Helper props go on the outer `<label>`, the `.card`, with
  * `className`. The other attributes go on the `<input>`.
  * @extraProp {string} [name] - The form field name, which the cards of one choice share, so the arrow keys move between them. Inside `Radios`, the group's `name` when this is unset.
- * @extraProp {string} [value] - What a form sends when this card is the one picked. Inside a `Radios` group that takes `value`, `defaultValue` or `onChange`, the card is checked while the group's value is this.
+ * @extraProp {string} [value] - What a form sends when this card is the one picked. Inside a `Radios` group that takes `value`, `defaultValue` or `onChange`, the card is checked while the group's value is this. A group given only `onChange` starts from the card with `defaultChecked`.
  */
 export interface RadioCardProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size' | 'type' | 'color' | 'title'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor' | 'size'> {
     /**

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

@@ -26,7 +26,11 @@ export interface RadiosProps extends Omit<BulmaClassesProps, 'color'>, FormField
     value?: string;
     /** Initial selected value (uncontrolled mode). */
     defaultValue?: string;
-    /** Fires when the selection changes. */
+    /**
+     * Fires when the selection changes; receives the value picked. Passed
+     * without `value` or `defaultValue`, it still has the group manage the
+     * selection, starting from the radio with `defaultChecked`.
+     */
     onChange?: (value: string) => void;
     /** Radio elements to render in the group. */
     children: React.ReactNode;

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

@@ -51,7 +51,11 @@ export interface RateProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'o
     max?: number;
     /** Size variant. */
     size?: RateSize;
-    /** Whether the rating is disabled. */
+    /**
+     * Whether the rating is disabled. A disabled Rate ignores clicks and keys,
+     * leaves the tab order, and sets `aria-disabled` on the group and on every
+     * star, so a screen reader announces them as unavailable.
+     */
     disabled?: boolean;
     /**
      * Show the numeric score next to stars, written the way the `locale` of a

package/dist/types-cjs/components/Toast.d.ts

@@ -50,9 +50,17 @@ export interface ToastProps extends Omit<React.HTMLAttributes<HTMLDivElement>, '
     onAction?: () => void;
     /** Callback when toast closes. */
     onClose?: () => void;
-    /** CSS selector or DOM node to mount the toast into. */
+    /**
+     * CSS selector or DOM node to mount the toast into. Through `toast.show()`,
+     * a toast with one portals there in a box of its own, rather than joining
+     * `ToastContainer`'s stack for its position.
+     */
     container?: string | HTMLElement;
-    /** Renders inline instead of using a portal. */
+    /**
+     * Renders inline instead of using a portal. Through `toast.show()`, a toast
+     * already renders inline in `ToastContainer`'s stack for its position, and
+     * `inline` keeps one with a `container` in that stack too.
+     */
     inline?: boolean;
 }
 /**
@@ -153,7 +161,10 @@ export declare const toast: {
  * Container component for rendering programmatic toasts.
  * Place once at your app root to enable the toast API. A toast shown with a
  * `position` appears there, and one shown without goes to the container's
- * `position`.
+ * `position`. The toasts at one position stack in one `.toast-container`,
+ * with a gap between them, in the order they were shown, growing away from
+ * the edge of the screen. A toast shown with a `container` of its own, and
+ * not `inline`, portals there instead, in a box of its own.
  *
  * @function
  * @param {{ position?: ToastPosition }} props - Container props.

package/dist/types-cjs/elements/Tr.d.ts

@@ -13,9 +13,9 @@ export interface TrProps extends Omit<React.HTMLAttributes<HTMLTableRowElement>,
     /**
      * Whether the row is selected (adds Bulma's is-selected class). It's a look
      * only: it says nothing to assistive tech, so pair it with a checkbox named
-     * for the row when the selection matters. A bestax `Checkbox` placed
-     * straight in one of the row's cells takes the row's text color, so a
-     * checked box shows on the row's fill. One in a menu or a table nested in a
+     * for the row when the selection matters. A bestax `Checkbox` or `Radio`
+     * placed straight in one of the row's cells takes the row's text color, so
+     * a checked one shows on the row's fill. One in a menu or a table nested in a
      * cell, or in a cell with a `color` of its own, keeps its own colors, since
      * it sits on that surface instead, and so does every one in a row with a
      * `color`, whose cells paint that color over the fill.

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

@@ -7,7 +7,7 @@ declare const checkboxCardColors: readonly ["primary", "link", "info", "success"
  * @helperProps Helper props go on the outer `<label>`, the `.card`, with
  * `className`. The other attributes go on the `<input>`.
  * @extraProp {string} [name] - The form field name. Inside `Checkboxes`, the group's `name` when this is unset.
- * @extraProp {string} [value] - What a form sends for the card when it's checked. Inside a `Checkboxes` group that takes `value`, `defaultValue` or `onChange`, the card is checked while the group's value holds it.
+ * @extraProp {string} [value] - What a form sends for the card when it's checked. Inside a `Checkboxes` group that takes `value`, `defaultValue` or `onChange`, the card is checked while the group's value holds it. A group given only `onChange` starts from the cards' own `defaultChecked`.
  */
 export interface CheckboxCardProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size' | 'type' | 'color' | 'title'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor' | 'size'> {
     /**

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

@@ -26,7 +26,13 @@ export interface CheckboxesProps extends Omit<BulmaClassesProps, 'color'>, FormF
     value?: string[];
     /** Initial selected values (uncontrolled mode). */
     defaultValue?: string[];
-    /** Fires when the selection changes; receives the new array. */
+    /**
+     * Fires when the selection changes; receives the new array. Passed without
+     * `value` or `defaultValue`, it still has the group manage the selection,
+     * starting from the checkboxes' own `defaultChecked`: a box that starts
+     * checked stays checked when another is clicked, and the first array holds
+     * it.
+     */
     onChange?: (values: string[]) => void;
     /** Checkbox elements to render in the group. */
     children?: React.ReactNode;

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

@@ -210,21 +210,54 @@ export declare const useFieldLabelTarget: (id: string | undefined, hasInput?: bo
  * (i.e., the user passed `value`, `defaultValue`, or `onChange` to `<Radios>`).
  * When only `name` is provided, the group is in "name-only" mode and child
  * Radios manage their own checked state independently.
+ *
+ * A group given only `onChange` manages the selection but holds no value
+ * until its first change. Until then a Radio with a value shows its own
+ * `defaultChecked`, still controlled, so that change doesn't flip it from
+ * uncontrolled to controlled.
  */
 export interface RadiosGroupContextValue {
     name?: string;
-    value?: string;
+    /** `null` once a radio without a value was picked before the group held one, so no radio with a value shows checked. */
+    value?: string | null;
     onChange?: (value: string) => void;
+    /** Set with `onChange`. Tells the group a radio without a value, sharing its name, was picked. */
+    pickWithoutValue?: () => void;
 }
+/**
+ * Tells a surrounding `<Radios>` that one of its radios was picked. A radio
+ * with a value hands the group that value. One without a value tells the
+ * group nothing it reports, but when it shares the group's name the browser
+ * has just unchecked the radio that showed checked, so the group learns the
+ * pick left its radios and React doesn't check that one again, undoing the
+ * pick. `Radio` and `RadioCard` call it with their effective name.
+ */
+export declare const pickInRadiosGroup: (group: RadiosGroupContextValue | undefined, value: string | number | readonly string[] | undefined, name: string | undefined) => void;
 /**
  * Shape of the Checkboxes group context. Like Radios but with array semantics
  * for multi-select.
+ *
+ * While the group manages the selection it also sets `registerChecked` and
+ * `startingValue`. A group given only `onChange` holds no value until its
+ * first change, so its choices register the values they start checked with,
+ * and that change starts from them rather than from an empty array.
  */
 export interface CheckboxesGroupContextValue {
     name?: string;
     value?: string[];
     onChange?: (values: string[]) => void;
+    /** Registers a value a choice starts checked with, and returns the function that takes it back. */
+    registerChecked?: (value: string) => () => void;
+    /** The values registered as starting checked, each once, in the order they came. */
+    startingValue?: () => string[];
 }
+/**
+ * Registers a choice with its surrounding `<Checkboxes>` while it starts
+ * checked, so a group with no value yet starts its first change from the
+ * choices that were checked. `Checkbox` and `CheckboxCard` call it. It does
+ * nothing outside a group that manages the selection, or without a value.
+ */
+export declare const useRegisterChecked: (group: CheckboxesGroupContextValue | undefined, value: string | undefined, startsChecked: boolean) => void;
 /**
  * Hook to read the full surrounding `<Radios>` group context (name + selection).
  * Returns `undefined` when not inside a `<Radios>` group.

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

@@ -7,7 +7,7 @@ declare const radioCardColors: readonly ["primary", "link", "info", "success", "
  * @helperProps Helper props go on the outer `<label>`, the `.card`, with
  * `className`. The other attributes go on the `<input>`.
  * @extraProp {string} [name] - The form field name, which the cards of one choice share, so the arrow keys move between them. Inside `Radios`, the group's `name` when this is unset.
- * @extraProp {string} [value] - What a form sends when this card is the one picked. Inside a `Radios` group that takes `value`, `defaultValue` or `onChange`, the card is checked while the group's value is this.
+ * @extraProp {string} [value] - What a form sends when this card is the one picked. Inside a `Radios` group that takes `value`, `defaultValue` or `onChange`, the card is checked while the group's value is this. A group given only `onChange` starts from the card with `defaultChecked`.
  */
 export interface RadioCardProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size' | 'type' | 'color' | 'title'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor' | 'size'> {
     /**

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

@@ -26,7 +26,11 @@ export interface RadiosProps extends Omit<BulmaClassesProps, 'color'>, FormField
     value?: string;
     /** Initial selected value (uncontrolled mode). */
     defaultValue?: string;
-    /** Fires when the selection changes. */
+    /**
+     * Fires when the selection changes; receives the value picked. Passed
+     * without `value` or `defaultValue`, it still has the group manage the
+     * selection, starting from the radio with `defaultChecked`.
+     */
     onChange?: (value: string) => void;
     /** Radio elements to render in the group. */
     children: React.ReactNode;

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

@@ -51,7 +51,11 @@ export interface RateProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'o
     max?: number;
     /** Size variant. */
     size?: RateSize;
-    /** Whether the rating is disabled. */
+    /**
+     * Whether the rating is disabled. A disabled Rate ignores clicks and keys,
+     * leaves the tab order, and sets `aria-disabled` on the group and on every
+     * star, so a screen reader announces them as unavailable.
+     */
     disabled?: boolean;
     /**
      * Show the numeric score next to stars, written the way the `locale` of a