@allxsmith/bestax-bulma 5.22.0 → 5.23.0

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

@@ -1,3 +1,4 @@
+import React from 'react';
 /**
  * Resolves a portal target: an `HTMLElement` is used directly, a non-empty
  * `string` is treated as a `document.querySelector` selector (falling back to
@@ -13,3 +14,64 @@
  * @returns The resolved DOM node to portal into.
  */
 export declare function resolvePortalContainer(container?: string | HTMLElement): HTMLElement;
+/**
+ * Props for the Portal component.
+ */
+export interface PortalProps {
+    /** Content to render into the container. */
+    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
+     * 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`.
+     * Render the target first, or pass the element once you have it.
+     */
+    container?: string | HTMLElement;
+    /**
+     * Render the children in place instead, on the server as well as the
+     * client. Lets a component that portals only sometimes keep a single code
+     * path.
+     * @defaultValue false
+     */
+    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.
+ *
+ * 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
+ * that follows. The first client render then matches the server markup. In an app
+ * without server rendering it portals on the first render.
+ *
+ * React context, such as `ConfigProvider`'s class prefix, reaches the
+ * 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.
+ *
+ * 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
+ * reaches it nor holds focus there: render nested overlays inside the
+ * trapped element, or give them a trap of their own.
+ *
+ * @function
+ * @param {PortalProps} props - Props for the Portal component.
+ * @returns The portal, the children in place when `disabled`, or nothing
+ * before hydration.
+ *
+ * @example
+ * <Portal>
+ *   <div className="box">Rendered at the end of document.body</div>
+ * </Portal>
+ *
+ * @example
+ * // Into a dedicated overlay root
+ * <Portal container="#overlays">
+ *   <CommandPalette />
+ * </Portal>
+ */
+export declare function Portal({ children, container, disabled }: PortalProps): React.JSX.Element | null;

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

@@ -49,6 +49,8 @@ export declare function getActiveElementInTree(node: Node | null | undefined): E
  * opener sits in. A closed shadow root cannot be entered, so focus inside one
  * reads as its host.
  *
+ * @param doc - The document to start from: the component's own, when it may
+ * render into one other than the page's (an iframe's). Defaults to `document`.
  * @returns The focused element, or `null` when the document has none.
  */
-export declare function getDeepestActiveElement(): Element | null;
+export declare function getDeepestActiveElement(doc?: Document): Element | null;

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

@@ -0,0 +1,74 @@
+import type { RefObject } from 'react';
+/**
+ * Options for `useFocusTrap`.
+ */
+export interface UseFocusTrapOptions {
+    /**
+     * Whether the trap is on. Turning it on moves focus into the container;
+     * turning it off (or unmounting) releases Tab and restores focus.
+     * @defaultValue true
+     */
+    active?: boolean;
+    /**
+     * The element to focus when the trap turns on. Without it, or while it
+     * points at nothing, focus goes to the first tab stop inside the container,
+     * and to the container itself when there is none.
+     */
+    initialFocusRef?: RefObject<HTMLElement | null>;
+    /**
+     * Where focus goes when the trap turns off. `true` returns it to the element
+     * that had focus when the trap turned on; a ref sends it to that element
+     * instead; `false` leaves it alone. Focus is only moved while the trap still
+     * holds it, so a click that already put focus somewhere else outside the
+     * container keeps it there.
+     *
+     * `true` reads focus after the container's content has mounted, so content
+     * that focuses itself as it mounts (an `autoFocus` input) hides the element
+     * that opened it. And some browsers don't focus a button when it is
+     * clicked. For a panel opened from a button, pass the button's ref.
+     * @defaultValue true
+     */
+    restoreFocus?: boolean | RefObject<HTMLElement | null>;
+}
+/**
+ * Keeps keyboard focus inside a container while it is active: focus moves in
+ * when the trap turns on, Tab and Shift+Tab wrap between the first and last
+ * tab stops, and focus goes back where it came from when the trap turns off.
+ *
+ * Tab stops are what the browser's Tab visits, in document order: links,
+ * form controls, frames, media with controls, a `<details>` summary, editable
+ * regions, anything with `tabIndex={0}`, and the content of open shadow
+ * roots. Hidden, disabled, inert and `tabIndex={-1}` elements are skipped,
+ * and a radio group counts once. Give the container `tabIndex={-1}` so it can
+ * hold focus itself when nothing inside can. The trap listens on the
+ * container, so a trap nested inside another handles Tab first and the outer
+ * one stands aside.
+ *
+ * The trap is about Tab. If a Tab it let through still takes focus out (a
+ * browser can leave out a stop the page has, such as links when its settings
+ * say to), it sends focus back to the other end. A pointer or a script moving
+ * focus out is left alone, because pulling focus back from a click is modal
+ * behaviour, and a modal also has to block the page behind it, which `Modal`
+ * does. Content the container renders through a portal lives elsewhere in
+ * the DOM, so it is outside the trap: render nested overlays inside the
+ * container, or give them a trap of their own.
+ *
+ * The container has to be in the DOM when the trap turns on. The trap waits
+ * for hydration, so a container that only appears once the page has
+ * hydrated, the way portaled content does, still has it attach in the commit
+ * where the container appears.
+ *
+ * @function useFocusTrap
+ * @param containerRef - Ref to the element focus stays inside.
+ * @param options - When the trap is on, and where focus starts and ends.
+ *
+ * @example
+ * const panelRef = useRef<HTMLDivElement>(null);
+ * useFocusTrap(panelRef, { active: isOpen });
+ * return isOpen ? (
+ *   <div ref={panelRef} role="dialog" aria-label="Filters" tabIndex={-1}>
+ *     …
+ *   </div>
+ * ) : null;
+ */
+export declare function useFocusTrap(containerRef: RefObject<HTMLElement | null>, options?: UseFocusTrapOptions): void;

package/dist/types/index.d.ts

@@ -110,6 +110,10 @@ export * from './helpers/Config.js';
 export { ClientOnly } from './helpers/ClientOnly.js';
 export type { ClientOnlyProps } from './helpers/ClientOnly.js';
 export { useIsHydrated } from './helpers/useIsHydrated.js';
+export { Portal } from './helpers/portal.js';
+export type { PortalProps } from './helpers/portal.js';
+export { useFocusTrap } from './helpers/useFocusTrap.js';
+export type { UseFocusTrapOptions } from './helpers/useFocusTrap.js';
 export * from './layout/Container.js';
 export * from './layout/Footer.js';
 export * from './layout/Hero.js';

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

@@ -1,3 +1,4 @@
+import React from 'react';
 /**
  * Resolves a portal target: an `HTMLElement` is used directly, a non-empty
  * `string` is treated as a `document.querySelector` selector (falling back to
@@ -13,3 +14,64 @@
  * @returns The resolved DOM node to portal into.
  */
 export declare function resolvePortalContainer(container?: string | HTMLElement): HTMLElement;
+/**
+ * Props for the Portal component.
+ */
+export interface PortalProps {
+    /** Content to render into the container. */
+    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
+     * 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`.
+     * Render the target first, or pass the element once you have it.
+     */
+    container?: string | HTMLElement;
+    /**
+     * Render the children in place instead, on the server as well as the
+     * client. Lets a component that portals only sometimes keep a single code
+     * path.
+     * @defaultValue false
+     */
+    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.
+ *
+ * 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
+ * that follows. The first client render then matches the server markup. In an app
+ * without server rendering it portals on the first render.
+ *
+ * React context, such as `ConfigProvider`'s class prefix, reaches the
+ * 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.
+ *
+ * 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
+ * reaches it nor holds focus there: render nested overlays inside the
+ * trapped element, or give them a trap of their own.
+ *
+ * @function
+ * @param {PortalProps} props - Props for the Portal component.
+ * @returns The portal, the children in place when `disabled`, or nothing
+ * before hydration.
+ *
+ * @example
+ * <Portal>
+ *   <div className="box">Rendered at the end of document.body</div>
+ * </Portal>
+ *
+ * @example
+ * // Into a dedicated overlay root
+ * <Portal container="#overlays">
+ *   <CommandPalette />
+ * </Portal>
+ */
+export declare function Portal({ children, container, disabled }: PortalProps): React.JSX.Element | null;

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

@@ -49,6 +49,8 @@ export declare function getActiveElementInTree(node: Node | null | undefined): E
  * opener sits in. A closed shadow root cannot be entered, so focus inside one
  * reads as its host.
  *
+ * @param doc - The document to start from: the component's own, when it may
+ * render into one other than the page's (an iframe's). Defaults to `document`.
  * @returns The focused element, or `null` when the document has none.
  */
-export declare function getDeepestActiveElement(): Element | null;
+export declare function getDeepestActiveElement(doc?: Document): Element | null;

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

@@ -0,0 +1,74 @@
+import type { RefObject } from 'react';
+/**
+ * Options for `useFocusTrap`.
+ */
+export interface UseFocusTrapOptions {
+    /**
+     * Whether the trap is on. Turning it on moves focus into the container;
+     * turning it off (or unmounting) releases Tab and restores focus.
+     * @defaultValue true
+     */
+    active?: boolean;
+    /**
+     * The element to focus when the trap turns on. Without it, or while it
+     * points at nothing, focus goes to the first tab stop inside the container,
+     * and to the container itself when there is none.
+     */
+    initialFocusRef?: RefObject<HTMLElement | null>;
+    /**
+     * Where focus goes when the trap turns off. `true` returns it to the element
+     * that had focus when the trap turned on; a ref sends it to that element
+     * instead; `false` leaves it alone. Focus is only moved while the trap still
+     * holds it, so a click that already put focus somewhere else outside the
+     * container keeps it there.
+     *
+     * `true` reads focus after the container's content has mounted, so content
+     * that focuses itself as it mounts (an `autoFocus` input) hides the element
+     * that opened it. And some browsers don't focus a button when it is
+     * clicked. For a panel opened from a button, pass the button's ref.
+     * @defaultValue true
+     */
+    restoreFocus?: boolean | RefObject<HTMLElement | null>;
+}
+/**
+ * Keeps keyboard focus inside a container while it is active: focus moves in
+ * when the trap turns on, Tab and Shift+Tab wrap between the first and last
+ * tab stops, and focus goes back where it came from when the trap turns off.
+ *
+ * Tab stops are what the browser's Tab visits, in document order: links,
+ * form controls, frames, media with controls, a `<details>` summary, editable
+ * regions, anything with `tabIndex={0}`, and the content of open shadow
+ * roots. Hidden, disabled, inert and `tabIndex={-1}` elements are skipped,
+ * and a radio group counts once. Give the container `tabIndex={-1}` so it can
+ * hold focus itself when nothing inside can. The trap listens on the
+ * container, so a trap nested inside another handles Tab first and the outer
+ * one stands aside.
+ *
+ * The trap is about Tab. If a Tab it let through still takes focus out (a
+ * browser can leave out a stop the page has, such as links when its settings
+ * say to), it sends focus back to the other end. A pointer or a script moving
+ * focus out is left alone, because pulling focus back from a click is modal
+ * behaviour, and a modal also has to block the page behind it, which `Modal`
+ * does. Content the container renders through a portal lives elsewhere in
+ * the DOM, so it is outside the trap: render nested overlays inside the
+ * container, or give them a trap of their own.
+ *
+ * The container has to be in the DOM when the trap turns on. The trap waits
+ * for hydration, so a container that only appears once the page has
+ * hydrated, the way portaled content does, still has it attach in the commit
+ * where the container appears.
+ *
+ * @function useFocusTrap
+ * @param containerRef - Ref to the element focus stays inside.
+ * @param options - When the trap is on, and where focus starts and ends.
+ *
+ * @example
+ * const panelRef = useRef<HTMLDivElement>(null);
+ * useFocusTrap(panelRef, { active: isOpen });
+ * return isOpen ? (
+ *   <div ref={panelRef} role="dialog" aria-label="Filters" tabIndex={-1}>
+ *     …
+ *   </div>
+ * ) : null;
+ */
+export declare function useFocusTrap(containerRef: RefObject<HTMLElement | null>, options?: UseFocusTrapOptions): void;

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

@@ -110,6 +110,10 @@ export * from './helpers/Config.js';
 export { ClientOnly } from './helpers/ClientOnly.js';
 export type { ClientOnlyProps } from './helpers/ClientOnly.js';
 export { useIsHydrated } from './helpers/useIsHydrated.js';
+export { Portal } from './helpers/portal.js';
+export type { PortalProps } from './helpers/portal.js';
+export { useFocusTrap } from './helpers/useFocusTrap.js';
+export type { UseFocusTrapOptions } from './helpers/useFocusTrap.js';
 export * from './layout/Container.js';
 export * from './layout/Footer.js';
 export * from './layout/Hero.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allxsmith/bestax-bulma",
-  "version": "5.22.0",
+  "version": "5.23.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",

package/dist/types/form/_pickerInternals/useFocusTrap.d.ts

@@ -1,7 +0,0 @@
-import * as React from 'react';
-interface UseFocusTrapOptions {
-    initialFocusRef?: React.RefObject<HTMLElement | null>;
-    restoreFocus?: boolean;
-}
-export declare function useFocusTrap(containerRef: React.RefObject<HTMLElement | null>, active: boolean, options?: UseFocusTrapOptions): void;
-export {};

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

@@ -1,7 +0,0 @@
-import * as React from 'react';
-interface UseFocusTrapOptions {
-    initialFocusRef?: React.RefObject<HTMLElement | null>;
-    restoreFocus?: boolean;
-}
-export declare function useFocusTrap(containerRef: React.RefObject<HTMLElement | null>, active: boolean, options?: UseFocusTrapOptions): void;
-export {};