@allxsmith/bestax-bulma 5.18.2 → 5.20.0

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

@@ -54,10 +54,17 @@ export interface DateTimeInputBaseProps extends Omit<React.InputHTMLAttributes<H
     /** Render the popover into `document.body` via portal. */
     appendToBody?: boolean;
     /**
-     * Bulma color modifier for the input, also carried by the time wheels, where
-     * it colors the selection band and the keyboard focus ring. Unset, the
-     * wheels use `--bulma-timeinput-wheel-selected-bg`, which defaults to
-     * `primary`. The calendar does not take it.
+     * Bulma color modifier for the input, also carried by the calendar and the
+     * time wheels, where it colors the selected date and the selection band.
+     * Today's date and the calendar's keyboard focus ring take the color's
+     * `-on-scheme` variant, which Bulma adjusts to contrast with the background,
+     * so pale colors stay readable; that makes `'primary'` a shade off the unset
+     * calendar, which uses plain `primary` for them. A focused wheel's ring is
+     * drawn inside the band in the color's `-invert`, like the selected value,
+     * so it shows on the fill. Unset, they use their
+     * `--bulma-dateinput-*` and `--bulma-timeinput-wheel-*` variables, which
+     * follow `primary` by default. The footer's time pill and Done button stay
+     * `primary` either way.
      */
     color?: 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger';
     /** Size variant. */

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

@@ -34,7 +34,11 @@ export interface InputProps extends InputBaseProps {
     hasIconsLeft?: boolean;
     /** Force right icon container. */
     hasIconsRight?: boolean;
-    /** Shows loading indicator. */
+    /**
+     * Shows a loading spinner on the wrapping Control.
+     * Under `prefers-reduced-motion: reduce` the spinner stops and stays
+     * drawn (with bestax's CSS loaded).
+     */
     isLoading?: boolean;
     /** Expand the control. */
     isExpanded?: boolean;

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

@@ -53,7 +53,11 @@ export interface NumberinputProps extends Omit<React.InputHTMLAttributes<HTMLInp
     disabled?: boolean;
     /** Whether the input can be typed in. */
     editable?: boolean;
-    /** Shows a loading state. */
+    /**
+     * Shows a loading spinner on the input's control.
+     * Under `prefers-reduced-motion: reduce` the spinner stops and stays
+     * drawn (with bestax's CSS loaded).
+     */
     isLoading?: boolean;
     /** Enables exponential step increments when holding buttons. */
     exponential?: boolean;

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

@@ -26,7 +26,11 @@ export interface SelectProps extends SelectBaseProps {
     iconLeftSize?: ControlBaseProps['iconLeftSize'];
     /** Force left icon container. */
     hasIconsLeft?: boolean;
-    /** Shows loading indicator. */
+    /**
+     * Replaces the chevron with a loading spinner.
+     * Under `prefers-reduced-motion: reduce` the spinner stops and stays
+     * drawn (with bestax's CSS loaded).
+     */
     isLoading?: boolean;
     /** Expand the control. */
     isExpanded?: boolean;

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

@@ -10,7 +10,11 @@ export interface SelectBaseProps extends Omit<React.SelectHTMLAttributes<HTMLSel
     size?: 'small' | 'medium' | 'large';
     /** Rounded select corners. */
     isRounded?: boolean;
-    /** Shows loading indicator. */
+    /**
+     * Replaces the chevron with a loading spinner.
+     * Under `prefers-reduced-motion: reduce` the spinner stops and stays
+     * drawn (with bestax's CSS loaded).
+     */
     isLoading?: boolean;
     /** Applies Bulma's is-active modifier. */
     isActive?: boolean;

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

@@ -76,7 +76,11 @@ export interface TaginputProps extends Omit<React.HTMLAttributes<HTMLDivElement>
     keepFirst?: boolean;
     /** Keeps the autocomplete dropdown open after selection. */
     keepOpen?: boolean;
-    /** Shows a loading indicator. */
+    /**
+     * Shows a loading spinner in the input.
+     * Under `prefers-reduced-motion: reduce` the spinner stops and stays
+     * drawn (with bestax's CSS loaded).
+     */
     loading?: boolean;
     /** ARIA label for tag close buttons. */
     ariaCloseLabel?: string;

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

@@ -18,7 +18,11 @@ export interface TextAreaProps extends TextAreaBaseProps {
     labelProps?: FieldProps['labelProps'];
     /** Horizontal field layout. */
     horizontal?: boolean;
-    /** Shows loading indicator on the wrapping Control. */
+    /**
+     * Shows a loading spinner on the wrapping Control.
+     * Under `prefers-reduced-motion: reduce` the spinner stops and stays
+     * drawn (with bestax's CSS loaded).
+     */
     isLoading?: boolean;
     /** Control size. */
     controlSize?: ControlBaseProps['size'];

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

@@ -34,7 +34,11 @@ export interface TimeInputProps extends TimeInputBaseProps {
     hasIconsLeft?: boolean;
     /** Force the right icon container. */
     hasIconsRight?: boolean;
-    /** Show a loading indicator on the control. */
+    /**
+     * Show a loading spinner on the control.
+     * Under `prefers-reduced-motion: reduce` the spinner stops and stays
+     * drawn (with bestax's CSS loaded).
+     */
     isLoading?: boolean;
     /** Expand the control to fill its container. */
     isExpanded?: boolean;

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

@@ -54,8 +54,10 @@ export interface TimeInputBaseProps extends Omit<React.InputHTMLAttributes<HTMLI
     appendToBody?: boolean;
     /**
      * Bulma color modifier for the input, also carried by the wheels, where it
-     * colors the selection band and the keyboard focus ring. Unset, the wheels
-     * use `--bulma-timeinput-wheel-selected-bg`, which defaults to `primary`.
+     * colors the selection band. A focused wheel's keyboard focus ring is drawn
+     * inside the band in the color's `-invert`, like the selected value, so it
+     * shows on the fill. Unset, the wheels use
+     * `--bulma-timeinput-wheel-selected-bg`, which defaults to `primary`.
      */
     color?: 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger';
     /** Size variant. */

package/dist/types-cjs/helpers/Theme.d.ts

@@ -77,7 +77,12 @@ export interface ThemeProps extends Omit<BulmaClassesProps, 'color' | 'backgroun
      * written at `:root`, which squares everything on the page that takes its
      * radius from it.
      *
-     * For any other radius, set the variable through `bulmaVars`
+     * The sizes (`small`, `normal`, `large`, `rounded`) add their
+     * `has-radius-<value>` class to the wrapper div and set no variable, so
+     * they round the wrapper and leave what is inside it alone. Under `isRoot`
+     * there is no wrapper, so they do nothing, and say so in development.
+     *
+     * To change the radius of what is inside, set the variable through `bulmaVars`
      * (`bulmaVars={{ '--bulma-radius': '6px' }}`). This prop used to write the
      * variable for every value, so any other non-empty string still does, but
      * that route is deprecated and logs a warning in development. A number or

package/dist/types-cjs/helpers/bulmaClassHelpers.d.ts

@@ -104,10 +104,31 @@ export declare const validViewports: readonly ["mobile", "tablet", "tablet-only"
  */
 export declare const validFloats: readonly ["left", "right"];
 /**
- * Valid Bulma overflow classes.
- * @example 'clipped'
+ * Valid Bulma overflow values for one axis, taken by `overflowX` and
+ * `overflowY`. Each renders `is-overflow-x-<value>` or `is-overflow-y-<value>`.
+ * @example 'auto', 'hidden', 'scroll'
  */
-export declare const validOverflows: readonly ["clipped"];
+export declare const validAxisOverflows: readonly ["auto", "clip", "hidden", "scroll", "visible"];
+/**
+ * Valid Bulma overflow values for `overflow`.
+ *
+ * `clipped` renders `is-clipped`, the helper `overflow` started with. Every
+ * other value renders `is-overflow-<value>`.
+ * @example 'clipped', 'auto', 'hidden'
+ */
+export declare const validOverflows: readonly ["clipped", "auto", "clip", "hidden", "scroll", "visible"];
+/**
+ * Valid Bulma position values, taken by `pos`. Each renders
+ * `is-position-<value>`.
+ * @example 'relative', 'absolute', 'sticky'
+ */
+export declare const validPositions: readonly ["absolute", "fixed", "relative", "static", "sticky"];
+/**
+ * Valid Bulma aspect ratios, taken by `aspectRatio`. Each renders
+ * `is-aspect-ratio-<value>`.
+ * @example '1by1', '4by3', '16by9'
+ */
+export declare const validAspectRatios: readonly ["1by1", "5by4", "4by3", "3by2", "5by3", "16by9", "2by1", "3by1", "4by5", "3by4", "2by3", "3by5", "9by16", "1by2", "1by3"];
 /**
  * Valid Bulma interaction classes.
  * @example 'unselectable', 'clickable'
@@ -132,10 +153,13 @@ export declare const validCursors: readonly ["pointer", "help"];
  */
 export declare const cursorClasses: Record<(typeof validCursors)[number], string>;
 /**
- * Valid Bulma border-radius helper classes.
- * @example 'radiusless'
+ * Valid Bulma border-radius helper values.
+ *
+ * `radiusless` renders `is-radiusless` and removes the radius. The sizes
+ * render `has-radius-<value>` and set one from Bulma's radius scale.
+ * @example 'radiusless', 'small', 'rounded'
  */
-export declare const validRadii: readonly ["radiusless"];
+export declare const validRadii: readonly ["radiusless", "small", "normal", "large", "rounded"];
 /**
  * Valid Bulma shadow helper classes.
  * @example 'shadowless'

package/dist/types-cjs/helpers/shadowDom.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Event and focus checks that still hold when a component renders inside a
+ * shadow root.
+ *
+ * Code outside a shadow root cannot see into it. A listener on `document`
+ * reads an event from inside one with its `target` set to the shadow host,
+ * and `document.activeElement` names the host instead of the element that has
+ * focus. A component asking either question from `document` then takes a
+ * click on its own menu for an outside click, or cannot tell which of its
+ * items is focused. A web component or a sandboxed preview puts a component
+ * in exactly that position.
+ *
+ * Focus comes in two questions, and each has its own function here. "Is focus
+ * inside me, and on which of my elements?" is `getActiveElementInTree`. "Which
+ * element has focus, wherever it is?", the one to record before moving focus
+ * away and restore to later, is `getDeepestActiveElement`.
+ */
+/**
+ * Whether `event` happened inside `node`. The event's composed path still
+ * holds the element that was really clicked, where a `document` listener
+ * reads the shadow host as the event's `target`.
+ *
+ * @param event - An event read by a listener outside `node`, usually on `document`.
+ * @param node - The component's element, or nothing while it is unmounted.
+ * @returns True when `node` is on the event's path.
+ */
+export declare function isEventInside(event: Event, node: Node | null | undefined): boolean;
+/**
+ * The focused element as `node`'s own tree sees it: its shadow root's
+ * `activeElement` when `node` is inside one, `document.activeElement` when it
+ * is not. The result is comparable with `node` and its descendants, which
+ * live in that same tree, so use it to ask whether focus is inside `node`.
+ * Focus inside a shadow root nested within `node` reads as that root's host,
+ * which `node` contains.
+ *
+ * A shadow root with nothing focused inside reports `null`, and a detached
+ * node has no document above it. Both fall back to `document.activeElement`,
+ * so focus elsewhere on the page still reads as outside `node`.
+ *
+ * @param node - An element of the component, or nothing while it is unmounted.
+ * @returns The focused element in `node`'s tree, or the document's.
+ */
+export declare function getActiveElementInTree(node: Node | null | undefined): Element | null;
+/**
+ * The element that really has focus, followed down from
+ * `document.activeElement` through every open shadow root on the way. Use it
+ * to record where focus was before moving it, so it can be restored to that
+ * element later: the tree a component renders into need not be the tree its
+ * opener sits in. A closed shadow root cannot be entered, so focus inside one
+ * reads as its host.
+ *
+ * @returns The focused element, or `null` when the document has none.
+ */
+export declare function getDeepestActiveElement(): Element | null;

package/dist/types-cjs/helpers/statusRegion.d.ts

@@ -0,0 +1,61 @@
+import React from 'react';
+/**
+ * How long after an item appears its announcement is written, in ms. The wait
+ * lets a screen reader register a region the container has only just mounted,
+ * and items shown in quick succession are written, and read out, together.
+ */
+export declare const announceDelay = 100;
+/**
+ * How long an announcement stays in the region once written, in ms. That's
+ * long enough for a screen reader to pick it up. Clearing it after keeps a
+ * second copy of the item's text from sitting in the page, where someone
+ * reading through the page, or a test looking the text up, would find it
+ * again.
+ */
+export declare const announcementLifetime = 1000;
+/**
+ * Reads an element out roughly the way a screen reader would: its text, with
+ * an element's `aria-label`, or an image's `alt`, standing in for what's
+ * inside it, a break between block-level elements, and parts that are
+ * `aria-hidden`, `hidden` or inline-styled `display: none` left out. It isn't
+ * the full accessible name computation, so `aria-labelledby`, CSS-generated
+ * content, content hidden by a stylesheet and other ways of naming or hiding
+ * content aren't followed.
+ *
+ * @function spokenText
+ * @param element - The element to read.
+ * @returns Its text, with runs of whitespace collapsed and the ends trimmed.
+ */
+export declare function spokenText(element: Element): string;
+/**
+ * Props for StatusRegion.
+ */
+export interface StatusRegionProps<Item extends {
+    id: string;
+}> {
+    /** The items to announce politely, in the order they were shown. */
+    items: readonly Item[];
+    /**
+     * The text to announce for an item, or nothing to skip it, as
+     * `useAnnouncements` takes it.
+     */
+    describe: (item: Item) => string | null;
+}
+/**
+ * A visually hidden, polite `status` live region that a programmatic
+ * container announces its items through. The container renders it from the
+ * moment it mounts, whether or not it has anything to show, so the region is
+ * already in the page when an announcement is written into it.
+ *
+ * The announcements are this component's own state, so writing and clearing
+ * them re-renders the region and leaves the container's items alone. Each one
+ * is its own keyed node, so a re-render that leaves the announcements alone
+ * leaves the region's content alone too, and nothing is read out twice.
+ *
+ * @function StatusRegion
+ * @param props - The items to announce, and the text to announce for each.
+ * @returns The region.
+ */
+export declare function StatusRegion<Item extends {
+    id: string;
+}>({ items, describe, }: StatusRegionProps<Item>): React.ReactElement;

package/dist/types-cjs/helpers/useBulmaClasses.d.ts

@@ -50,7 +50,7 @@ export declare const useBulmaClasses: <T extends object>(props: BulmaClassesProp
     bulmaHelperStyles?: CSSProperties;
     rest: Omit<T, keyof BulmaClassesProps>;
 };
-export { validColors, validColorShades, validSchemeColors, validSizes, validTextSizes, validAlignments, validTextTransforms, validTextWeights, validFontFamilies, validDisplays, validVisibilities, validFlexDirections, validFlexWraps, validJustifyContents, validAlignContents, validAlignItems, validAlignSelfs, validFlexGrowShrink, validViewports, validFloats, validOverflows, validInteractions, validCursors, validRadii, validShadows, validResponsives, } from './bulmaClassHelpers.js';
+export { validColors, validColorShades, validSchemeColors, validSizes, validTextSizes, validAlignments, validTextTransforms, validTextWeights, validFontFamilies, validDisplays, validVisibilities, validFlexDirections, validFlexWraps, validJustifyContents, validAlignContents, validAlignItems, validAlignSelfs, validFlexGrowShrink, validViewports, validFloats, validOverflows, validAxisOverflows, validInteractions, validCursors, validRadii, validShadows, validResponsives, validPositions, validAspectRatios, } from './bulmaClassHelpers.js';
 export type { BulmaViewportProps, BulmaDisplayProps };
 export * from './useColorClasses.js';
 export * from './useSpacingClasses.js';

package/dist/types-cjs/helpers/useOtherClasses.d.ts

@@ -1,19 +1,48 @@
-import { validCursors, validFloats, validInteractions, validOverflows, validRadii, validResponsives, validShadows } from './bulmaClassHelpers.js';
+import { validAspectRatios, validAxisOverflows, validCursors, validFloats, validInteractions, validOverflows, validPositions, validRadii, validResponsives, validShadows } from './bulmaClassHelpers.js';
 /**
  * Props for applying miscellaneous Bulma helper classes.
  */
 export interface BulmaOtherProps {
     /** Float direction (e.g., 'left', 'right'). */
     float?: (typeof validFloats)[number];
-    /** Overflow behavior (e.g., 'clipped'). */
+    /**
+     * Overflow behavior on both axes. `clipped` renders `is-clipped`; the CSS
+     * keywords (`auto`, `clip`, `hidden`, `scroll`, `visible`) render
+     * `is-overflow-<value>`.
+     *
+     * Beside `overflowX` or `overflowY`, the axis prop wins on its own axis and
+     * `overflow` sets only the other one, with `clipped` counting as `hidden`:
+     * `overflow="hidden" overflowY="auto"` clips sideways and scrolls down.
+     */
     overflow?: (typeof validOverflows)[number];
+    /**
+     * Horizontal overflow behavior (e.g., 'auto', 'hidden'). Wins over
+     * `overflow` on this axis.
+     */
+    overflowX?: (typeof validAxisOverflows)[number];
+    /**
+     * Vertical overflow behavior (e.g., 'auto', 'scroll'). Wins over `overflow`
+     * on this axis.
+     */
+    overflowY?: (typeof validAxisOverflows)[number];
     /** Applies overlay styling if true. */
     overlay?: boolean;
     /** Interaction behavior (e.g., 'unselectable', 'clickable'). */
     interaction?: (typeof validInteractions)[number];
     /** Cursor style (e.g., 'pointer', 'help'). */
     cursor?: (typeof validCursors)[number];
-    /** Border radius style (e.g., 'radiusless'). */
+    /**
+     * Border radius. `radiusless` removes it (`is-radiusless`). `small`,
+     * `normal`, `large` and `rounded` set one from Bulma's radius scale
+     * (`has-radius-<value>`), where `rounded` is the pill shape.
+     *
+     * The class lands on the component's root element, so where an inner
+     * element draws the radius, such as the `<img>` in `Image` or the
+     * `<select>` in `Select`, that element keeps its own. The sizes are not
+     * `!important`, unlike `radiusless`, so a component rule more specific than
+     * one class still wins: an `isRounded` control stays a pill, and a joined
+     * addon keeps its square inner corners.
+     */
     radius?: (typeof validRadii)[number];
     /** Shadow style (e.g., 'shadowless'). */
     shadow?: (typeof validShadows)[number];
@@ -23,15 +52,42 @@ export interface BulmaOtherProps {
     skeleton?: boolean;
     /** Applies clearfix to fix floating children if true. */
     clearfix?: boolean;
-    /** Applies position: relative if true. */
+    /**
+     * CSS `position` (`is-position-<value>`).
+     *
+     * Named `pos` because several components already have a `position` prop
+     * of their own, for where they place a popup or a toast.
+     *
+     * It sets `position` and nothing else, so an element that is `absolute`,
+     * `fixed` or `sticky` still needs its offsets (`top`, `left`, …) from your
+     * own CSS. `sticky` in particular does nothing until one is set.
+     *
+     * When `pos` is set it decides the position, and `relative` adds nothing.
+     */
+    pos?: (typeof validPositions)[number];
+    /**
+     * Applies position: relative if true (`is-relative`). The shortcut for
+     * `pos="relative"`, kept working as it always has; `pos` wins when both are
+     * set.
+     */
     relative?: boolean;
     /** Applies height: 100% if true. */
     fullHeight?: boolean;
+    /**
+     * Fixed width-to-height ratio (`is-aspect-ratio-<value>`), e.g. `16by9`.
+     * The height follows the width, so leave the height unset. Content taller
+     * than the ratio allows grows the element unless `overflow` or `overflowY`
+     * makes it scroll or clip.
+     *
+     * On `Image`, prefer its own `size` ratios, which also fit the picture to
+     * the box; this class sizes only the wrapper.
+     */
+    aspectRatio?: (typeof validAspectRatios)[number];
 }
 /**
  * A hook that generates miscellaneous Bulma helper classes (float, overflow,
  * overlay, interaction, cursor, radius, shadow, responsive, skeleton,
- * clearfix, relative, and full height).
+ * clearfix, position, full height, and aspect ratio).
  *
  * @function useOtherClasses
  * @param props - Miscellaneous Bulma helper props.

package/dist/types-cjs/index.d.ts

@@ -38,6 +38,7 @@ export * from './elements/IconText.js';
 export * from './elements/Image.js';
 export * from './elements/Link.js';
 export * from './elements/ListItem.js';
+export * from './elements/Loader.js';
 export * from './elements/Notification.js';
 export * from './elements/OrderedList.js';
 export * from './elements/Paragraph.js';