@allxsmith/bestax-bulma 5.28.0 → 5.30.0

package/dist/index.esm.js

@@ -20,6 +20,7 @@ export { Collapses } from './esm/components/Collapses.js';
 export { Tooltip } from './esm/components/Tooltip.js';
 export { Popover, PopoverBody, PopoverClose, PopoverFooter, PopoverHeader } from './esm/components/Popover.js';
 export { HoverCard } from './esm/components/HoverCard.js';
+export { ContextMenu } from './esm/components/ContextMenu.js';
 export { Step, Steps } from './esm/components/Steps.js';
 export { Sidebar } from './esm/components/Sidebar.js';
 export { Toast, ToastContainer, toast } from './esm/components/Toast.js';
@@ -31,6 +32,7 @@ export { Box } from './esm/elements/Box.js';
 export { Button } from './esm/elements/Button.js';
 export { Buttons } from './esm/elements/Buttons.js';
 export { LinkButton } from './esm/elements/LinkButton.js';
+export { ToggleButton } from './esm/elements/ToggleButton.js';
 export { Code } from './esm/elements/Code.js';
 export { Content } from './esm/elements/Content.js';
 export { Delete } from './esm/elements/Delete.js';

package/dist/index.esm.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.esm.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.esm.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

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

@@ -0,0 +1,66 @@
+import React from 'react';
+import { BulmaClassesProps } from '../helpers/useBulmaClasses.js';
+/**
+ * Props for the ContextMenu component. `className`, `id`, `aria-label`, the
+ * other HTML attributes and the helper props land on the menu
+ * (`role="menu"`). The trigger keeps its own.
+ * @extraProp {string} [aria-label] - The menu's accessible name, such as "Actions for report.pdf". There's no button to borrow a name from, so pass this or `aria-labelledby`, and a development build warns when the menu opens with neither.
+ * @extraProp {string} [className] - Additional classes for the menu (`role="menu"`). The trigger keeps its own.
+ */
+export interface ContextMenuProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'color' | 'children'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /**
+     * The element a right-click, Shift+F10, the context menu key or a long
+     * press opens the menu from: a table row, a card, an image. It's cloned,
+     * not wrapped, so a row stays a row, which means it has to be a single
+     * element that passes `className` and the `onContextMenu`,
+     * `onPointerDown`, `onPointerMove`, `onPointerUp`, `onPointerCancel` and
+     * `onTouchEnd` handlers to its DOM node. Its own handlers for those run
+     * first, and one that calls `preventDefault()` on `contextmenu` keeps the
+     * menu closed. A `ContextMenu` inside it opens instead of this one.
+     *
+     * It gets no ARIA and no tab stop, since it can be any element and a
+     * right-click isn't an activation. Keyboard users reach it through
+     * something focusable inside it, such as the row's own `Dropdown` button,
+     * or a `tabIndex={0}` you give it, and press Shift+F10 or the context menu
+     * key there. It gets `-webkit-touch-callout: none`, so iOS doesn't put its
+     * own callout for a link or an image over the menu. A long press still
+     * selects text the way it does anywhere, so give a region where it
+     * shouldn't `interaction="unselectable"`.
+     */
+    trigger: React.ReactElement;
+    /**
+     * The menu's items: `ContextMenu.Item` and `ContextMenu.Divider`, the same
+     * components as `Dropdown.Item` and `Dropdown.Divider`. Every action in it
+     * needs a visible way in as well, such as a `Dropdown` on the same row:
+     * nothing tells a screen reader user the menu is there, and on macOS only
+     * VoiceOver opens it from the keyboard.
+     */
+    children: React.ReactNode;
+    /**
+     * Called with `true` when the menu opens and `false` when it closes,
+     * whatever closed it, such as for highlighting the row whose menu is open.
+     * Nothing fires after ContextMenu unmounts. There's no `open` prop to go
+     * with it: a menu opened from code has no point to open at.
+     */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * Close the menu when an item is clicked, or activated with Enter or
+     * Space. A click on a divider or between items leaves it open either way.
+     */
+    closeOnClick?: boolean;
+    /**
+     * Leave the trigger to the browser: a right-click shows the browser's own
+     * menu, a long press does what it does anywhere, and an open menu closes.
+     */
+    disabled?: boolean;
+}
+/**
+ * ContextMenu with Item and Divider sub-components, which are `Dropdown.Item`
+ * and `Dropdown.Divider`, so items written for a Dropdown work here
+ * unchanged.
+ */
+export declare const ContextMenu: React.FC<ContextMenuProps> & {
+    Item: import("../index.js").ConstrainedPolymorphicComponentWithoutRef<import("./Dropdown.js").DropdownItemOwnProps, import("./Dropdown.js").DropdownItemElement, "a", never>;
+    Divider: React.FC<{}>;
+};
+export default ContextMenu;

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

@@ -80,18 +80,20 @@ export interface HoverCardProps extends Omit<React.HTMLAttributes<HTMLSpanElemen
      */
     position?: HoverCardPosition;
     /**
-     * Render the card at the end of `document.body` through `Portal`, fixed to
-     * the viewport, so an ancestor's `overflow`, `transform` or stacking
-     * context can't clip it. A trigger in running text needs it too, since the
-     * card's block content can't sit inside a `<p>`. The card then shows from
-     * the commit after hydration, never in server markup, and it sits last in
-     * the Tab order, at the end of `<body>`. Tab reaches it only after the rest
-     * of the page, and focus leaving the trigger on the way closes it, so
-     * keyboard users can open it, read it and close it with Escape, and
-     * whatever it links to has to be reachable from the page as well. It is
-     * measured against the trigger when it opens and on resize and scroll, so
-     * it doesn't follow content that changes size while it is open. Theming
-     * variables set on an ancestor of the trigger don't reach it there.
+     * Render the card through `Portal`, into the `portalContainer` a
+     * `ConfigProvider` sets, `document.body` by default, fixed to the viewport,
+     * so an ancestor's `overflow`, `transform` or stacking context can't clip
+     * it. A trigger in running text needs it too, since the card's block
+     * content can't sit inside a `<p>`. The card then shows from the commit
+     * after hydration, never in server markup, and it sits in the Tab order
+     * where its container is. At the end of `<body>`, the default, Tab reaches
+     * it only after the rest of the page, and focus leaving the trigger on the
+     * way closes it, so keyboard users can open it, read it and close it with
+     * Escape, and whatever it links to has to be reachable from the page as
+     * well. It is measured against the trigger when it opens and on resize and
+     * scroll, so it doesn't follow content that changes size while it is open.
+     * Theming variables set on an ancestor of the trigger reach it only when its
+     * container is inside that ancestor.
      * @defaultValue false
      */
     appendToBody?: boolean;

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

@@ -44,7 +44,8 @@ export interface ModalProps extends Omit<React.HTMLAttributes<HTMLDivElement>, '
     /**
      * Renders the modal into a portal target instead of inline, so it isn't
      * clipped by an ancestor with `overflow: hidden`, `filter` or `transform`.
-     * `true` portals to `document.body`; a string is used as a
+     * `true` portals to the `portalContainer` a `ConfigProvider` sets,
+     * `document.body` by default; a string is used as a
      * `document.querySelector` selector; an element is used directly. Renders
      * inline on the server and while hydrating, moving into the portal once the
      * client takes over, so hydration matches.

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

@@ -53,13 +53,14 @@ export interface PopoverProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
      */
     position?: PopoverPosition;
     /**
-     * Render the panel at the end of `document.body` through `Portal`, fixed to
-     * the viewport, so an ancestor's `overflow`, `transform` or stacking context
-     * can't clip it. The panel then shows from the commit after hydration,
-     * never in server markup. It is measured against the trigger when it opens
-     * and on resize and scroll, so it doesn't follow content that changes size
-     * while it is open. Theming variables set on an ancestor of the trigger
-     * don't reach it there.
+     * Render the panel through `Portal`, into the `portalContainer` a
+     * `ConfigProvider` sets, `document.body` by default, fixed to the viewport,
+     * so an ancestor's `overflow`, `transform` or stacking context can't clip
+     * it. The panel then shows from the commit after hydration, never in server
+     * markup. It is measured against the trigger when it opens and on resize
+     * and scroll, so it doesn't follow content that changes size while it is
+     * open. Theming variables set on an ancestor of the trigger reach it only
+     * when its container is inside that ancestor.
      * @defaultValue false
      */
     appendToBody?: boolean;

package/dist/types/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/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/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/form/DateInputBase.d.ts

@@ -97,7 +97,10 @@ export interface DateInputBaseProps extends Omit<React.InputHTMLAttributes<HTMLI
     closeOnSelect?: boolean;
     /** Popover anchor position relative to the input. */
     position?: PickerPosition;
-    /** Render the popover into `document.body` via portal. */
+    /**
+     * Render the popover through a portal, into the `portalContainer` a
+     * `ConfigProvider` sets, `document.body` by default.
+     */
     appendToBody?: boolean;
     /**
      * Bulma color modifier for the input, also carried by the calendar, where it

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

@@ -84,7 +84,10 @@ export interface DateRangeInputBaseProps extends Omit<React.HTMLAttributes<HTMLD
     closeOnSelect?: boolean;
     /** Popover anchor position relative to the field. */
     position?: PickerPosition;
-    /** Render the popover into `document.body` via portal. */
+    /**
+     * Render the popover through a portal, into the `portalContainer` a
+     * `ConfigProvider` sets, `document.body` by default.
+     */
     appendToBody?: boolean;
     /**
      * Bulma color modifier for the field, also carried by the calendar, where it

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

@@ -70,7 +70,10 @@ export interface DateTimeInputBaseProps extends Omit<React.InputHTMLAttributes<H
     closeOnSelect?: boolean;
     /** Popover anchor position. */
     position?: PickerPosition;
-    /** Render the popover into `document.body` via portal. */
+    /**
+     * Render the popover through a portal, into the `portalContainer` a
+     * `ConfigProvider` sets, `document.body` by default.
+     */
     appendToBody?: boolean;
     /**
      * Bulma color modifier for the input, also carried by the calendar and the
@@ -128,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/form/TimeInputBase.d.ts

@@ -64,7 +64,8 @@ export interface TimeInputBaseProps extends Omit<React.InputHTMLAttributes<HTMLI
     /** Popover anchor position relative to the input. */
     position?: PickerPosition;
     /**
-     * Render the popover into `document.body` via portal. On a narrow screen
+     * Render the popover through a portal, into the `portalContainer` a
+     * `ConfigProvider` sets, `document.body` by default. On a narrow screen
      * an in-place popover spans the bottom of the viewport, while a portaled
      * one stays on its `position` corner.
      */
@@ -81,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;
@@ -104,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/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/helpers/Config.d.ts

@@ -3,13 +3,14 @@ import React, { ReactNode } from 'react';
 type IconLibrary = 'fa' | 'mdi' | 'ion' | 'material-icons' | 'material-symbols';
 /**
  * Shape of the configuration context value.
- *
- * @property {string} [classPrefix] - Prefix applied to all Bulma class names.
- * @property {IconLibrary} [iconLibrary] - Default icon library for Icon components.
  */
 export interface ConfigContextProps {
+    /** Prefix applied to all Bulma class names. */
     classPrefix?: string;
+    /** Default icon library for Icon components. */
     iconLibrary?: IconLibrary;
+    /** Where portaled content goes when it has no target of its own. */
+    portalContainer?: string | HTMLElement;
 }
 /**
  * Hook to access the bulma-ui configuration context.
@@ -28,10 +29,40 @@ export interface ConfigProviderProps {
     classPrefix?: string;
     /** Default icon library for Icon components. */
     iconLibrary?: IconLibrary;
+    /**
+     * Where portaled content goes when it has no target of its own: what a
+     * `Portal` without a `container` renders, and what the library's components
+     * portal, such as Popover's `appendToBody` panel, a `Modal` with `portal`
+     * set to `true`, or a `Toast`. An element, or a `document.querySelector`
+     * selector. Unset, or a selector that matches nothing, that content goes to
+     * `document.body`. A target a component is given, such as a `Toast`'s
+     * `container`, still wins, and nothing portals that would otherwise render
+     * in place.
+     *
+     * The overlays and panels this moves are `position: fixed`, so pick an
+     * element with no ancestor that has a `transform`, `filter`,
+     * `backdrop-filter`, `perspective`, `will-change: transform`, or a
+     * `contain` that includes `paint` or `layout`. That ancestor becomes their
+     * containing block, and they cover or line up against it instead of the
+     * viewport. An ancestor that starts a stacking context, with a `z-index` or
+     * `isolation: isolate`, keeps them inside it, under anything the page
+     * stacks above it. `NotificationContainer`'s status region moves too, so
+     * this also decides where its announcements come from, and an `aria-hidden`
+     * ancestor silences them.
+     *
+     * A selector can't find an element inside a shadow root, so pass the
+     * element itself there, held in state from a ref callback. Content that
+     * portals before the element is set goes to `document.body` and moves when
+     * it is, which remounts it, as `Portal`'s `container` describes.
+     */
+    portalContainer?: string | HTMLElement;
 }
 /**
  * ConfigProvider injects configuration into all child components via React context.
  *
+ * A nested provider replaces the outer one's settings rather than adding to
+ * them, so inside it any setting it leaves out is back to its default.
+ *
  * @function
  * @param {ConfigProviderProps} props - Provider props.
  * @returns {JSX.Element} The context provider wrapping children.

package/dist/types/helpers/portal.d.ts

@@ -14,6 +14,22 @@ import React from 'react';
  * @returns The resolved DOM node to portal into.
  */
 export declare function resolvePortalContainer(container?: string | HTMLElement): HTMLElement;
+/**
+ * Where a component's portal goes, as a function to call when the portal is
+ * created: the target the component was given, else the `portalContainer` a
+ * `ConfigProvider` sets, else `document.body`, each read as
+ * `resolvePortalContainer` reads it. A component that portals resolves its
+ * target through this, so the provider's default reaches it.
+ *
+ * The hook only reads context, so it is safe to call on the server, ahead of
+ * any early return. The function it returns reads the DOM, so call it only
+ * where the portal is created, which the server never reaches.
+ *
+ * @function usePortalContainer
+ * @returns A function that takes the component's own target, if any, and
+ * returns the DOM node to portal into.
+ */
+export declare function usePortalContainer(): (container?: string | HTMLElement) => HTMLElement;
 /**
  * Props for the Portal component.
  */
@@ -22,8 +38,10 @@ export interface PortalProps {
     children?: React.ReactNode;
     /**
      * Where the content goes: an element, or a `document.querySelector`
-     * selector. Omitted, empty, or a selector that matches nothing, it goes to
-     * `document.body`. A selector is looked up again on each render, so the
+     * selector. Omitted or empty, it goes to the `portalContainer` a
+     * `ConfigProvider` sets, and to `document.body` when none is set. A
+     * selector that matches nothing means `document.body` too. A selector is
+     * looked up again on each render, so the
      * content follows the target when it changes. Moving to another target
      * remounts the children and resets their state, which includes a selector
      * that only starts matching after the content has shown in `document.body`.
@@ -39,7 +57,7 @@ export interface PortalProps {
     disabled?: boolean;
 }
 /**
- * Renders its children into another part of the page, `document.body` unless `container` says otherwise, so floating content escapes an ancestor's `overflow`, `transform` or stacking context.
+ * Renders its children into another part of the page, `document.body` unless `container` or a `ConfigProvider` says otherwise, so floating content escapes an ancestor's `overflow`, `transform` or stacking context.
  *
  * React's server renderer can't render a portal, so `Portal` renders nothing
  * on the server and during hydration, and mounts its children in the commit
@@ -50,8 +68,12 @@ export interface PortalProps {
  * portaled children, and their React events bubble through the React tree.
  * CSS inheritance follows the DOM instead: a scoped (non-`isRoot`) `Theme`
  * sets its variables on a wrapper element the portaled content has left, so
- * that content sees the page-level theme. Point `container` at an element
- * inside the themed area to keep it.
+ * that content sees the page-level theme, and styles scoped to a shadow root
+ * don't reach `document.body` at all. To keep them, portal into an element
+ * inside the themed area or the shadow root: pass it as `container`, or as
+ * the `portalContainer` of a `ConfigProvider` around that area. The second
+ * also reaches what the library's components portal, such as Popover's
+ * `appendToBody` panel or a `Modal` with `portal`.
  *
  * Tab order and focus follow the DOM too. Content portaled from inside a
  * focus trap is no longer inside the trapped element, so the trap neither