@allxsmith/bestax-bulma 5.29.0 → 5.30.0

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

@@ -14,7 +14,13 @@ export type TooltipSize = 'small' | 'medium' | 'large';
 export interface TooltipProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'color' | 'content'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
     /** The tooltip text content. */
     label?: string;
-    /** Rich tooltip content (alternative to `label`). */
+    /**
+     * Rich tooltip content (alternative to `label`), to read rather than use.
+     * Nothing in it should take focus or a click: it isn't in the Tab order
+     * while hidden, focus there isn't counted as being in the tooltip, and
+     * Escape hiding it would drop that focus. For links or buttons, use
+     * `HoverCard` or `Popover`.
+     */
     content?: React.ReactNode;
     /** Position of the tooltip. Default: 'top'. */
     position?: TooltipPosition;
@@ -22,7 +28,11 @@ export interface TooltipProps extends Omit<React.HTMLAttributes<HTMLSpanElement>
     color?: TooltipColor;
     /** Size of the tooltip. */
     size?: TooltipSize;
-    /** Force tooltip to be always visible. */
+    /**
+     * Force tooltip to be always visible. Hover, focus and Escape leave it
+     * shown, so Escape goes on to whatever has focus, or to a `Modal` or
+     * `Popover` around it.
+     */
     active?: boolean;
     /** Allow tooltip to wrap to multiple lines. */
     multiline?: boolean;
@@ -32,16 +42,47 @@ export interface TooltipProps extends Omit<React.HTMLAttributes<HTMLSpanElement>
     square?: boolean;
     /** Show dashed underline on trigger. */
     dashed?: boolean;
-    /** Delay before showing tooltip (ms). */
+    /**
+     * How long the pointer or keyboard focus waits on the trigger before the
+     * tooltip shows, in milliseconds.
+     */
     delay?: number;
-    /** Delay in ms before hiding the tooltip. */
+    /**
+     * How long the tooltip stays after the pointer and focus have left the
+     * trigger and the tooltip, in milliseconds. The pointer can move from the
+     * trigger onto a shown tooltip without one, across the default gap. A
+     * theme that raises `--bulma-tooltip-arrow-size` or
+     * `--bulma-tooltip-arrow-margin` widens the gap past what the pointer can
+     * cross on its own, so give it a `closeDelay` long enough to cross the
+     * rest.
+     */
     closeDelay?: number;
+    /**
+     * Show the tooltip with a tap on a touch screen. Touch has no hover, so
+     * without this a phone or tablet never shows it. With it, a tap on the
+     * trigger shows it at once, and it stays until another tap on the trigger
+     * or the tooltip, a tap anywhere else, or Escape. The tap still does
+     * whatever the trigger does, so turn this on only for a trigger with no
+     * tap action of its own. Mouse and pen work the same either way.
+     * @defaultValue false
+     */
+    openOnTap?: boolean;
     /** Additional classes for the tooltip element. */
     tooltipClassName?: string;
 }
 /**
  * The `Tooltip` component displays helpful information when users hover over or focus on an element.
  *
+ * Hovering the trigger or giving it keyboard focus shows it. Touch doesn't,
+ * unless `openOnTap` is on, and neither does focus a click or a tap brings,
+ * so tapping the trigger just does what the trigger does. The pointer can
+ * move onto a shown tooltip. Escape hides it wherever focus is, without
+ * moving the pointer or focus, and it stays hidden until one of them leaves
+ * the trigger and comes back, or, with `openOnTap`, until the next tap on
+ * the trigger. The key always goes on too, to whatever has focus or a
+ * `Modal` or `Popover` around it, since a tooltip only adds to what's
+ * there.
+ *
  * @function
  * @param {TooltipProps} props - Props for the Tooltip component.
  * @returns {JSX.Element} The rendered tooltip wrapper.

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

@@ -39,7 +39,7 @@ export interface ButtonOwnProps extends Omit<BulmaClassesProps, 'color' | 'backg
     isInverted?: boolean;
     /** Applies focused styling (visual only). */
     isFocused?: boolean;
-    /** Applies active styling (visual only). */
+    /** Applies active styling (visual only), with no `aria-pressed`. For a button that stays pressed, use `ToggleButton`. */
     isActive?: boolean;
     /** Applies hovered styling (visual only). */
     isHovered?: boolean;

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

@@ -0,0 +1,90 @@
+import React from 'react';
+import { type ButtonOwnProps } from './Button.js';
+/**
+ * The fills a pressed `ToggleButton` takes: `Button`'s colors, minus `text`
+ * and `ghost`, which don't fill, and `white`, `light`, `dark` and `black`.
+ * Bulma's color modifier fills the button and drops its border, and those four
+ * fill it with about the lightness a plain button already has in one theme or
+ * the other, so pressed would look like off without its border.
+ */
+export type ToggleButtonColor = 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger';
+/**
+ * Props for the ToggleButton component. The helper props, the other button
+ * attributes and the `ref` all land on the `<button>`.
+ *
+ * Some of `Button`'s props are left out on purpose. `as`, since only a button
+ * can be pressed, and `type`, which is always `button`. `isActive`, which is
+ * `pressed` here, and `isStatic`, a toggle you couldn't press. And the props
+ * that change the fill (`isLight`, `isOutlined`, `isInverted`, `textColor`,
+ * `bgColor` and their shades), since each would color the button in both
+ * states or turn "on" into a faint tint. `color` takes only the fills that
+ * stand out from a plain button: see `ToggleButtonColor`.
+ *
+ * @extraProp {React.Ref<HTMLButtonElement>} [ref] - Ref forwarded to the `<button>`.
+ */
+export interface ToggleButtonProps extends Omit<ButtonOwnProps, 'color' | 'isActive' | 'isStatic' | 'isLight' | 'isOutlined' | 'isInverted' | 'textColor' | 'bgColor' | 'colorShade' | 'backgroundColorShade'>, Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, keyof ButtonOwnProps | 'type' | 'aria-pressed'> {
+    /**
+     * Whether it's pressed, when you hold the state. Setting it makes the toggle
+     * controlled: a click only calls `onPressedChange`, and nothing changes until
+     * you pass the new value. Pick this or `defaultPressed` for the button's
+     * lifetime.
+     */
+    pressed?: boolean;
+    /** Whether it starts pressed, when it holds its own state. */
+    defaultPressed?: boolean;
+    /**
+     * Called with the new state each time it's toggled, by a click, Enter or
+     * Space, whether or not `pressed` is set. An `onClick` that calls
+     * `preventDefault()` stops the toggle, and this doesn't fire.
+     */
+    onPressedChange?: (pressed: boolean) => void;
+    /**
+     * The fill while it's pressed. Not pressed, it's a plain button, so the fill
+     * is the difference people see. `white`, `light`, `dark` and `black` aren't
+     * offered, since in one theme or the other each fills about as light or dark
+     * as a plain button already is. Of the rest, a pale one such as `warning`
+     * changes less than the default `link`.
+     */
+    color?: ToggleButtonColor;
+    /**
+     * The label, which stays the same in both states: a screen reader announces
+     * whether it's pressed, so "Mute" stays "Mute". An icon can swap, but an
+     * icon-only toggle needs an `aria-label` that doesn't. A label that changes
+     * ("Play", then "Pause") belongs on a plain `Button`.
+     */
+    children?: React.ReactNode;
+    /**
+     * Not accepted: `aria-pressed` follows the state. Declared because JSX lets a
+     * hyphenated attribute through when the props don't name it, so leaving it
+     * out of the type alone would not reject `aria-pressed="mixed"`.
+     * @internal
+     */
+    'aria-pressed'?: never;
+}
+/**
+ * The `ToggleButton` component renders a button that stays pressed until it's pressed again, and says whether it's on through `aria-pressed`.
+ *
+ * It's always a `<button type="button">`, so it never submits a form and
+ * carries no form value: a setting saved with a form is a `Checkbox` or a
+ * `Switch`. A set of toggles that each turn on and off on their own goes in
+ * `Buttons hasAddons` with `role="group"` and an `aria-label`. A set where only
+ * one can be on is a radio group rather than a row of these: use `Radios`.
+ *
+ * @function
+ * @param {ToggleButtonProps} props - Props for the ToggleButton component.
+ * @param {React.Ref<HTMLButtonElement>} ref - Forwarded ref to the `<button>`.
+ * @returns {JSX.Element} The rendered toggle button.
+ * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/button/ | APG button pattern}
+ *
+ * @example
+ * <ToggleButton onPressedChange={setMuted}>Mute</ToggleButton>
+ *
+ * @example
+ * <Buttons hasAddons role="group" aria-label="Text style">
+ *   <ToggleButton aria-label="Bold" pressed={bold} onPressedChange={setBold}>
+ *     <Icon name="bold" />
+ *   </ToggleButton>
+ * </Buttons>
+ */
+export declare const ToggleButton: React.ForwardRefExoticComponent<ToggleButtonProps & React.RefAttributes<HTMLButtonElement>>;
+export default ToggleButton;

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

@@ -131,7 +131,10 @@ export interface DateTimeInputBaseProps extends Omit<React.InputHTMLAttributes<H
     audioTick?: boolean;
     /** Auto-route tactile feedback per wheel tick (vibrate on Android, audio thunk on iOS). Default `false`. */
     haptics?: boolean;
-    /** Optional translatable string overrides. */
+    /**
+     * Optional translatable string overrides. In a 12-hour picker, `ampm`
+     * names the AM/PM column, `'AM/PM'` by default.
+     */
     labels?: PickerLabels;
 }
 /**

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

@@ -82,7 +82,7 @@ export interface TimeInputBaseProps extends Omit<React.InputHTMLAttributes<HTMLI
     size?: 'small' | 'medium' | 'large';
     /** Render the input with rounded corners. */
     isRounded?: boolean;
-    /** Hour format. `'12'` shows an AM/PM toggle. */
+    /** Hour format. `'12'` adds an AM/PM column to the wheels. */
     hourFormat?: HourFormat;
     /** Show a seconds column. Note: iOS Safari's native time picker UI does not include a seconds wheel; pass `mobileNative={false}` if you need one on iOS. */
     enableSeconds?: boolean;
@@ -105,7 +105,10 @@ export interface TimeInputBaseProps extends Omit<React.InputHTMLAttributes<HTMLI
     triggerIcon?: boolean;
     /** Glyph for the right launcher button. */
     triggerIconName?: string;
-    /** Optional translatable string overrides. */
+    /**
+     * Optional translatable string overrides. In a 12-hour picker, `ampm`
+     * names the AM/PM column, `'AM/PM'` by default.
+     */
     labels?: PickerLabels;
     /** Play a short audible click on each wheel-item crossing. Substitute for haptic feedback on iOS Safari (which has no web haptic API as of May 2026); on Android, `navigator.vibrate(5)` fires automatically regardless. */
     audioTick?: boolean;

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

@@ -49,13 +49,24 @@ export interface PickerLabels {
     hours?: string;
     minutes?: string;
     seconds?: string;
+    /**
+     * Time wheels: names the AM/PM column a 12-hour picker shows.
+     * @defaultValue 'AM/PM'
+     */
     ampm?: string;
+    /** @deprecated Rendered nowhere: no picker reads it. It goes in the next major. */
     increaseHours?: string;
+    /** @deprecated Rendered nowhere: no picker reads it. It goes in the next major. */
     decreaseHours?: string;
+    /** @deprecated Rendered nowhere: no picker reads it. It goes in the next major. */
     increaseMinutes?: string;
+    /** @deprecated Rendered nowhere: no picker reads it. It goes in the next major. */
     decreaseMinutes?: string;
+    /** @deprecated Rendered nowhere: no picker reads it. It goes in the next major. */
     increaseSeconds?: string;
+    /** @deprecated Rendered nowhere: no picker reads it. It goes in the next major. */
     decreaseSeconds?: string;
+    /** @deprecated Rendered nowhere: no picker reads it. It goes in the next major. */
     toggleAmPm?: string;
     chooseTime?: string;
     chooseDateTime?: string;
@@ -72,5 +83,9 @@ export interface PickerLabels {
     time?: string;
 }
 export declare const DEFAULT_PICKER_LABELS: Required<PickerLabels>;
-/** Merge user-supplied label overrides with the defaults. */
+/**
+ * Merge user-supplied label overrides with the defaults. A key set to
+ * `undefined` keeps its default, so a locale table that is missing a string
+ * still names its control instead of leaving it with no accessible name.
+ */
 export declare const mergeLabels: (overrides?: PickerLabels) => Required<PickerLabels>;

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

@@ -0,0 +1,67 @@
+import type { MouseEvent, PointerEvent, TouchEvent } from 'react';
+/** A point in the viewport, in CSS pixels. */
+export interface ContextMenuPoint {
+    x: number;
+    y: number;
+}
+/**
+ * Options for `useContextMenuTrigger`.
+ */
+export interface UseContextMenuTriggerOptions {
+    /**
+     * Asks to open at `point`. `trigger` is the element the handlers are on,
+     * for its document.
+     */
+    onOpen: (point: ContextMenuPoint, trigger: HTMLElement) => void;
+    /** Leave the browser's own menu alone, and start no long press. */
+    disabled: boolean;
+}
+/** Handlers for the trigger element. */
+export interface ContextMenuTriggerHandlers {
+    onContextMenu: (event: MouseEvent<HTMLElement>) => void;
+    onPointerDown: (event: PointerEvent<HTMLElement>) => void;
+    onPointerMove: (event: PointerEvent<HTMLElement>) => void;
+    onPointerUp: (event: PointerEvent<HTMLElement>) => void;
+    onPointerCancel: (event: PointerEvent<HTMLElement>) => void;
+    onTouchEnd: (event: TouchEvent<HTMLElement>) => void;
+}
+/** How long a touch or a pen has to stay down to open the menu, in milliseconds. */
+export declare const LONG_PRESS_DELAY = 500;
+/** How far a long press can move before it counts as something else, in CSS pixels. */
+export declare const LONG_PRESS_TOLERANCE = 10;
+/**
+ * Decides when a context menu asks to open, and where. It renders nothing,
+ * and knows nothing about ARIA or the menu.
+ *
+ * - **`contextmenu`:** a right-click, and Shift+F10 or the context menu key
+ *   where the browser fires the event for them, asks to open at the point
+ *   `contextMenuPoint` works out, and prevents the browser's own menu. Each
+ *   one asks again, so a right-click elsewhere on the trigger moves it.
+ * - **Long press:** a touch or a pen held still on the trigger for
+ *   `LONG_PRESS_DELAY` fires a `contextmenu` at what it landed on, so it
+ *   takes the same path, handlers on the way included. Moving more than
+ *   `LONG_PRESS_TOLERANCE`, lifting, another pointer coming down anywhere in
+ *   the document, or `pointercancel`, which is the browser taking the
+ *   gesture for a scroll or a zoom, cancels it, and a mouse never starts
+ *   one. A pointer that comes down while another is held starts no long
+ *   press of its own, on this trigger or another, so two fingers on two rows
+ *   open nothing. While the finger is down, and only then, a listener on the
+ *   document hears other pointers coming down. Where the
+ *   browser fires `contextmenu` for a long press itself, the first of the two
+ *   opens it, and the end of a touch that opened it is prevented, so lifting
+ *   doesn't click what is under the finger.
+ * - **Who opens:** a handler that calls `preventDefault()` on the
+ *   `contextmenu` before this one keeps it from asking, which is how a
+ *   trigger's own handler opts out and how the innermost of nested triggers
+ *   wins. A long press goes to the innermost trigger that takes it. Events
+ *   from content portaled out of the trigger, which React brings here
+ *   anyway, are ignored.
+ * - **`disabled`:** nothing asks, and the browser's menu shows.
+ *
+ * Nothing it scheduled runs after the component unmounts.
+ *
+ * @function useContextMenuTrigger
+ * @param options - How to ask to open, and whether to.
+ * @returns Handlers for the trigger element.
+ */
+export declare function useContextMenuTrigger({ onOpen, disabled, }: UseContextMenuTriggerOptions): ContextMenuTriggerHandlers;

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

@@ -38,6 +38,14 @@ export interface UseHoverOpenOptions {
      * @defaultValue false
      */
     openOnTap?: boolean;
+    /**
+     * Whether an Escape that closes it stops there when focus is on the
+     * trigger, in the floating element or nowhere, so a `Popover` or `Modal`
+     * around it keeps its own. Off, Escape still closes it and always goes on
+     * to whatever has focus, as suits content that only adds to the trigger.
+     * @defaultValue true
+     */
+    consumeEscape?: boolean;
 }
 /**
  * Pointer and focus handlers for the element that holds the trigger. The
@@ -48,12 +56,18 @@ export interface UseHoverOpenOptions {
  */
 export interface HoverOpenHandlers {
     onPointerEnter: (event: PointerEvent<HTMLElement>) => void;
+    onPointerOver: (event: PointerEvent<HTMLElement>) => void;
     onPointerLeave: (event: PointerEvent<HTMLElement>) => void;
     onFocus: (event: FocusEvent<HTMLElement>) => void;
     onBlur: (event: FocusEvent<HTMLElement>) => void;
     onPointerDown: (event: PointerEvent<HTMLElement>) => void;
     onPointerUp: (event: PointerEvent<HTMLElement>) => void;
 }
+/**
+ * Runs the caller's own handler on the element that holds the trigger, then
+ * the hook's, so neither replaces the other.
+ */
+export declare function chain<E>(own: ((event: E) => void) | undefined, ours: (event: E) => void): (event: E) => void;
 /**
  * Decides when a floating element that opens on hover or keyboard focus asks
  * to open and to close. It renders nothing, and leaves roles, ARIA and
@@ -62,7 +76,8 @@ export interface HoverOpenHandlers {
  * - The pointer entering, or keyboard focus arriving on the trigger, asks to
  *   open after `openDelay`. A touch pointer doesn't count. Neither does focus
  *   that a press brings to the trigger: it counts when the browser shows it
- *   as `:focus-visible`.
+ *   as `:focus-visible`. The pointer arriving from outside a shadow root the
+ *   trigger renders into counts too, though React sends no enter for it.
  * - Focus in the floating element holds it open however it got there,
  *   including focus in content it portals elsewhere, such as a nested card.
  *   Whether a click focuses what it lands on is up to the browser: Safari
@@ -73,8 +88,9 @@ export interface HoverOpenHandlers {
  *   else closes it on a timer.
  * - Escape closes it at once, wherever focus is, and stops there when focus
  *   is in it, on its trigger or nowhere, so a `Popover` or `Modal` around it
- *   keeps its own. With focus somewhere else, the key goes on after closing
- *   it. Inside another one, the inner one closes first. Escape before it
+ *   keeps its own. With focus somewhere else, or with `consumeEscape` off,
+ *   the key goes on after closing it. Inside another one, the inner one
+ *   closes first. Escape before it
  *   opens takes the opening back and goes on its way. One key listener per
  *   document serves every hook on it, there only while one of them is open
  *   or on its way to open.

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

@@ -0,0 +1,57 @@
+import type { KeyboardEvent } from 'react';
+/**
+ * Every menu-item role, so an item a caller gives `menuitemcheckbox` or
+ * `menuitemradio` (a filter or sort menu) stays reachable.
+ */
+export declare const MENU_ITEM_SELECTOR = "[role=\"menuitem\"], [role=\"menuitemcheckbox\"], [role=\"menuitemradio\"]";
+/**
+ * Whether a menu item can be reached and activated: it isn't disabled, as a
+ * native control or through `aria-disabled="true"`.
+ */
+export declare function isEnabledMenuItem(item: Element): boolean;
+/** The items in `menu` the keys reach, in document order. */
+export declare function enabledMenuItems(menu: Element): HTMLElement[];
+/** How long typed characters keep adding up to one search, in milliseconds. */
+export declare const TYPEAHEAD_TIMEOUT = 500;
+/** What `useMenuKeys` returns. */
+export interface MenuKeys {
+    /** The `keydown` handler for the `role="menu"` element. */
+    onKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
+    /**
+     * Forgets what has been typed, so the next character starts a new search.
+     * Call it when the menu opens, so a search typed just before it last
+     * closed doesn't carry over.
+     */
+    reset: () => void;
+}
+/**
+ * Moves through and activates the items of a `role="menu"` element from the
+ * keyboard. Put the `onKeyDown` it returns on that element. It reads the
+ * items from the element each time, so items that come and go are found,
+ * and it renders nothing.
+ *
+ * It acts only while focus is on the menu element itself or on one of its
+ * items, so anything else focusable inside the menu, such as a filter
+ * field, keeps its own keys.
+ *
+ * - Down and Up move to the next and previous enabled item, wrapping, and
+ *   Home and End go to the first and last. From no item, Down goes to the
+ *   first and Up to the last.
+ * - Enter and Space activate the focused item. A `<button>`, and a link with
+ *   an `href` for Enter, get the browser's own click, and anything else gets
+ *   one from here, so its `onClick` runs either way. A key held down
+ *   activates it once. A key handler on the item that called
+ *   `preventDefault()` has claimed the key, and nothing else runs it.
+ * - A printable character moves to the next enabled item whose text starts
+ *   with what has been typed. Characters typed within `TYPEAHEAD_TIMEOUT` of
+ *   each other add up to one search, until `reset` starts a new one.
+ *
+ * Items are `MENU_ITEM_SELECTOR` matches, and disabled ones are skipped by
+ * all of the above. Escape and Tab are left to the menu's owner, since what
+ * closing means is up to it, and so is any other key.
+ *
+ * @function useMenuKeys
+ * @returns The `keydown` handler for the menu element, and a way to forget
+ * what has been typed.
+ */
+export declare function useMenuKeys(): MenuKeys;

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

@@ -19,6 +19,7 @@ export * from './components/Collapses.js';
 export * from './components/Tooltip.js';
 export * from './components/Popover.js';
 export * from './components/HoverCard.js';
+export * from './components/ContextMenu.js';
 export * from './components/Steps.js';
 export * from './components/Sidebar.js';
 export * from './components/Toast.js';
@@ -30,6 +31,7 @@ export * from './elements/Box.js';
 export * from './elements/Button.js';
 export * from './elements/Buttons.js';
 export * from './elements/LinkButton.js';
+export * from './elements/ToggleButton.js';
 export * from './elements/Code.js';
 export * from './elements/Content.js';
 export * from './elements/Delete.js';