@allxsmith/bestax-bulma 5.28.0 → 5.29.0

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/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

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.
      */

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

package/dist/types-cjs/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-cjs/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-cjs/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-cjs/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-cjs/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-cjs/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

package/dist/types-cjs/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.
      */

package/dist/types-cjs/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-cjs/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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allxsmith/bestax-bulma",
-  "version": "5.28.0",
+  "version": "5.29.0",
   "description": "A fully-typed React component library for the Bulma CSS framework. Build modern UIs quickly with reusable, accessible, and customizable Bulma-based React components.",
   "main": "dist/index.cjs",
   "module": "dist/index.esm.js",