@allxsmith/bestax-bulma 5.18.2 → 5.19.0

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

@@ -156,6 +156,8 @@ export interface CardHeaderTitleProps extends React.HTMLAttributes<HTMLDivElemen
 }
 /**
  * Props for the Card.Header.Icon compound component.
+ * @extraProp {'button' | 'submit' | 'reset'} [type='button'] - Button type. Defaults to `'button'`, so a header icon inside a form does not submit it. Pass `'submit'` or `'reset'` and yours is used; any other value, or a spread carrying `type: undefined`, renders `'button'`.
+ * @extraProp {string} [aria-label='more options'] - Accessible name. Pass your own to replace it. An empty one, or a spread carrying `'aria-label': undefined`, keeps the default rather than leaving the button unnamed.
  */
 export interface CardHeaderIconProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
     /** Bulma color modifier (text color helper). */

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

@@ -38,11 +38,17 @@ export interface CarouselProps extends Omit<React.HTMLAttributes<HTMLDivElement>
     repeat?: boolean;
     /** Enable drag/swipe navigation. Default: true. */
     hasDrag?: boolean;
-    /** Show navigation arrows. Default: true. */
+    /**
+     * Show navigation arrows. Default: true. They render `type="button"`, so a
+     * carousel inside a form is not submitted by moving between slides.
+     */
     arrow?: boolean;
     /** Only show arrows on hover. */
     arrowHover?: boolean;
-    /** Show slide indicators. Default: true. */
+    /**
+     * Show slide indicators. Default: true. They render `type="button"`, so a
+     * carousel inside a form is not submitted by picking a slide.
+     */
     indicator?: boolean;
     /** Position indicators inside carousel. */
     indicatorInside?: boolean;

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

@@ -103,6 +103,8 @@ export interface ModalCardFootProps extends React.HTMLAttributes<HTMLElement> {
 }
 /**
  * Props for Modal.Close component.
+ * @extraProp {'button' | 'submit' | 'reset'} [type='button'] - Button type. Defaults to `'button'`, so a close button inside a form does not submit it. Pass `'submit'` or `'reset'` and yours is used; any other value, or a spread carrying `type: undefined`, renders `'button'`.
+ * @extraProp {string} [aria-label='close'] - Accessible name. Pass your own to replace it. An empty one, or a spread carrying `'aria-label': undefined`, keeps the default rather than leaving the button unnamed.
  */
 export interface ModalCloseProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
     /** Additional CSS classes. */

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

@@ -86,7 +86,13 @@ export interface NavbarItemOwnProps extends Omit<BulmaClassesProps, 'color' | 'b
  * @extraProp {PolymorphicRef<React.ElementType>} [ref] - Ref forwarded to the element `as` renders, typed from `as`: the DOM node for an intrinsic tag, or whatever handle a custom component exposes.
  */
 export type NavbarItemProps<T extends React.ElementType = 'a'> = NavbarItemOwnProps & Omit<React.ComponentPropsWithoutRef<T>, keyof NavbarItemOwnProps | 'as'> & {
-    /** Render as another intrinsic element (`'span'`, `'div'`) or a custom component (e.g. a router link). Defaults to `'a'`. */
+    /**
+     * Render as another intrinsic element (`'span'`, `'div'`, `'button'`) or a custom component (e.g. a router link). Defaults to `'a'`.
+     *
+     * `'button'` renders `type="button"`, so an item inside a form does not submit it. Pass
+     * `type="submit"` or `type="reset"` and yours is used; any other value, or a spread
+     * carrying `type: undefined`, renders `type="button"`.
+     */
     as?: T;
 };
 /**
@@ -101,6 +107,7 @@ export declare const NavbarItem: PolymorphicComponent<NavbarItemOwnProps, "a">;
 /**
  * Props for the NavbarBurger component.
  * @extraProp {React.Ref<HTMLButtonElement>} [ref] - Ref forwarded to the burger button element.
+ * @extraProp {'button' | 'submit' | 'reset'} [type='button'] - Button type. Defaults to `'button'`, so a burger inside a form does not submit it. Pass `'submit'` or `'reset'` and yours is used; any other value, or a spread carrying `type: undefined`, renders `'button'`.
  */
 export interface NavbarBurgerProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
     /** Additional CSS classes. */
@@ -122,9 +129,19 @@ export interface NavbarBurgerProps extends React.ButtonHTMLAttributes<HTMLButton
      * draws an extra bar.
      */
     children?: React.ReactNode;
-    /** Aria label for accessibility. */
+    /**
+     * Accessible name. Pass your own to replace it. An empty one, or a spread
+     * carrying `'aria-label': undefined`, keeps the default rather than leaving
+     * the button unnamed.
+     * @defaultValue 'menu'
+     */
     'aria-label'?: string;
-    /** Aria expanded state. */
+    /**
+     * Expanded state for assistive technology. It follows `active` unless you
+     * pass `true` or `false`; a spread carrying `'aria-expanded': undefined`
+     * still follows `active`.
+     * @defaultValue active
+     */
     'aria-expanded'?: boolean;
     /** Click handler. */
     onClick?: React.MouseEventHandler<HTMLButtonElement>;
@@ -254,6 +271,10 @@ export type NavbarLinkProps<T extends React.ElementType = 'a'> = NavbarLinkOwnPr
      * If your custom component renders something non-interactive, pass `role="button"` and
      * it takes that fallback too — `tabIndex` and click included. The keyboard path is
      * attached either way.
+     *
+     * `'button'` renders `type="button"`, so a link inside a form does not submit it. Pass
+     * `type="submit"` or `type="reset"` and yours is used; any other value, or a spread
+     * carrying `type: undefined`, renders `type="button"`.
      */
     as?: T;
 };

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

@@ -50,6 +50,8 @@ interface SidebarTitleProps extends React.HTMLAttributes<HTMLParagraphElement> {
 /**
  * Props for the SidebarClose component.
  * Extends standard button attributes.
+ * @extraProp {'button' | 'submit' | 'reset'} [type='button'] - Button type. Defaults to `'button'`, so a close button inside a form does not submit it. Pass `'submit'` or `'reset'` and yours is used; any other value, or a spread carrying `type: undefined`, renders `'button'`.
+ * @extraProp {string} [aria-label='Close'] - Accessible name. Pass your own to replace it. An empty one, or a spread carrying `'aria-label': undefined`, keeps the default rather than leaving the button unnamed.
  */
 type SidebarCloseProps = React.ButtonHTMLAttributes<HTMLButtonElement>;
 /**

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

@@ -50,7 +50,11 @@ export interface StepsProps extends Omit<React.HTMLAttributes<HTMLDivElement>, '
     mobileMode?: 'minimal' | 'compact' | 'right';
     /** Displays step numbers in the markers. */
     showStepNumbers?: boolean;
-    /** Shows previous/next navigation buttons. */
+    /**
+     * Shows previous/next navigation buttons. They render `type="button"`, so a
+     * multi-step form wrapped around the steps is not submitted by moving
+     * between them.
+     */
     hasNavigation?: boolean;
     /** Label for the previous button. */
     prevLabel?: string;

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

@@ -21,7 +21,13 @@ interface DeleteProps extends React.HTMLAttributes<HTMLButtonElement>, BulmaClas
     onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
     /** Size modifier for the delete button. */
     size?: 'small' | 'medium' | 'large';
-    /** ARIA label for accessibility (default: 'Close'). */
+    /**
+     * Accessible name for the button. An `aria-label` you pass takes precedence
+     * over it, unless it is empty or arrives as `undefined` through a spread.
+     * An empty `ariaLabel` falls back to the default too, so the button is never
+     * left unnamed.
+     * @defaultValue 'Close'
+     */
     ariaLabel?: string;
     /** Whether the button is disabled (default: false). */
     disabled?: boolean;
@@ -29,6 +35,8 @@ interface DeleteProps extends React.HTMLAttributes<HTMLButtonElement>, BulmaClas
 /**
  * The `Delete` component provides a Bulma-styled close/delete button for dismissing modals, notifications, tags, messages, and more.
  *
+ * It renders `type="button"`, so a delete button inside a form does not submit it.
+ *
  * @function
  * @param {DeleteProps} props - Props for the Delete component.
  * @returns {JSX.Element} The rendered delete button.

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

@@ -40,7 +40,13 @@ export interface LinkOwnProps extends Omit<BulmaClassesProps, 'color' | 'backgro
  * @extraProp {PolymorphicRef<React.ElementType>} [ref] - Ref forwarded to the element `as` renders, typed from `as`: the DOM node for an intrinsic tag, or whatever handle a custom component exposes.
  */
 export type LinkProps<T extends React.ElementType = 'a'> = LinkOwnProps & Omit<React.ComponentPropsWithoutRef<T>, keyof LinkOwnProps | 'as'> & {
-    /** Render as another intrinsic element (`'span'`, `'button'`) or a custom component (e.g. a router `Link`) instead of `<a>`. Defaults to `'a'`. */
+    /**
+     * Render as another intrinsic element (`'span'`, `'button'`) or a custom component (e.g. a router `Link`) instead of `<a>`. Defaults to `'a'`.
+     *
+     * `'button'` renders `type="button"`, so a link inside a form does not submit it. Pass
+     * `type="submit"` or `type="reset"` and yours is used; any other value, or a spread
+     * carrying `type: undefined`, renders `type="button"`.
+     */
     as?: T;
 };
 /**

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

@@ -20,7 +20,10 @@ export interface NotificationProps extends React.HTMLAttributes<HTMLDivElement>,
     textColor?: (typeof validColors)[number] | 'inherit' | 'current';
     /** Use the light color variant. */
     isLight?: boolean;
-    /** Shows a close (delete) button in the notification. */
+    /**
+     * Shows a close (delete) button in the notification. It renders
+     * `type="button"`, so it does not submit a form around it.
+     */
     hasDelete?: boolean;
     /** Callback fired when the delete button is clicked. */
     onDelete?: () => void;
@@ -42,7 +45,18 @@ export type NotificationPosition = 'top-left' | 'top' | 'top-right' | 'bottom-le
  * Options for showing a programmatic notification.
  */
 export interface NotificationOptions {
-    /** The message to display. */
+    /**
+     * The message to display.
+     *
+     * For a notification other than `danger` and `warning`, NotificationContainer
+     * announces the text the message renders, 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. Other ways of naming or hiding
+     * content, such as `aria-labelledby`, CSS-generated content or a
+     * stylesheet's `display: none`, aren't followed, so a message that relies on
+     * them can be announced differently from what a screen reader would read.
+     */
     message: string | React.ReactNode;
     /**
      * Bulma color modifier for the notification (renders `is-<color>`).
@@ -147,9 +161,21 @@ export declare const notification: {
  * container's `position`, so the container renders a stack for each position
  * in use.
  *
+ * It keeps a visually hidden `role="status"` live region in the page from the
+ * moment it mounts, even while nothing is showing, and announces every
+ * notification other than `danger` and `warning` through it, a moment after
+ * the notification appears. Those notifications carry no `role="status"` of
+ * their own, so `getByRole('status')` finds the region, not the notification.
+ * The text stays in the region briefly, even if the notification closes in
+ * the meantime, and while both are up the page holds two copies of it. A
+ * polite notification that closes before its announcement is written, a
+ * moment after it appears, isn't announced at all. `danger` and `warning`
+ * notifications announce themselves as assertive alerts. The region is hidden
+ * with inline styles, so it needs no stylesheet.
+ *
  * @function
  * @param {{ position?: NotificationPosition }} props - Container props.
- * @returns {JSX.Element | null} The rendered notification container, or null if empty.
+ * @returns {JSX.Element | null} The rendered notification container, or null on the server and while hydrating.
  */
 export declare const NotificationContainer: React.FC<{
     /**

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

@@ -24,7 +24,13 @@ export interface TagProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'c
     isLight?: boolean;
     /** Renders a rounded tag. */
     isRounded?: boolean;
-    /** Renders a delete-style tag (delete button). */
+    /**
+     * Renders a delete-style tag (delete button). The button renders
+     * `type="button"`, so it does not submit a form around it, and is named
+     * "Delete tag" unless you pass an `aria-label`. An empty one, or a spread
+     * carrying `'aria-label': undefined`, keeps that name rather than leaving
+     * the button unnamed.
+     */
     isDelete?: boolean;
     /** Adds hover effect to the tag. */
     isHoverable?: boolean;

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

@@ -3,10 +3,29 @@
  */
 import React from 'react';
 import { BulmaClassesProps } from '../helpers/useBulmaClasses.js';
-/** Valid Bulma color values for table cells. */
+/**
+ * The values the table `color` prop accepts, as a readonly tuple.
+ *
+ * `TableColor` is typed from it, and `Tr`, `Th` and `Td` all take a
+ * `TableColor`, so the tuple and those props list the same values. Map over
+ * it to build a color picker, or check a value that arrives at runtime before
+ * passing it in: the components add no color class for a value outside the
+ * tuple.
+ *
+ * @example
+ * import { Tr, Td, validTableColors } from '@allxsmith/bestax-bulma';
+ *
+ * <Tr>
+ *   {validTableColors.map(color => (
+ *     <Td key={color} color={color}>
+ *       {color}
+ *     </Td>
+ *   ))}
+ * </Tr>;
+ */
 export declare const validTableColors: readonly ["primary", "link", "info", "success", "warning", "danger", "black", "dark", "light", "white"];
 /**
- * Valid color values for the Td component (Bulma table cell colors).
+ * The color values `Tr`, `Th` and `Td` accept, typed from `validTableColors`.
  */
 export type TableColor = (typeof validTableColors)[number];
 /**

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

@@ -52,7 +52,15 @@ export interface DateInputBaseProps extends Omit<React.InputHTMLAttributes<HTMLI
     position?: PickerPosition;
     /** Render the popover into `document.body` via portal. */
     appendToBody?: boolean;
-    /** Bulma color modifier. */
+    /**
+     * Bulma color modifier for the input, also carried by the calendar, where it
+     * colors the selected date. Today's date and the 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 both. Unset, the
+     * calendar uses its `--bulma-dateinput-*` variables, which follow `primary`
+     * by default.
+     */
     color?: 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger';
     /** Size variant. */
     size?: 'small' | 'medium' | 'large';

package/dist/types/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/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/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/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/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/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/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/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/components/Card.d.ts

@@ -156,6 +156,8 @@ export interface CardHeaderTitleProps extends React.HTMLAttributes<HTMLDivElemen
 }
 /**
  * Props for the Card.Header.Icon compound component.
+ * @extraProp {'button' | 'submit' | 'reset'} [type='button'] - Button type. Defaults to `'button'`, so a header icon inside a form does not submit it. Pass `'submit'` or `'reset'` and yours is used; any other value, or a spread carrying `type: undefined`, renders `'button'`.
+ * @extraProp {string} [aria-label='more options'] - Accessible name. Pass your own to replace it. An empty one, or a spread carrying `'aria-label': undefined`, keeps the default rather than leaving the button unnamed.
  */
 export interface CardHeaderIconProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
     /** Bulma color modifier (text color helper). */