@allxsmith/bestax-bulma 5.28.0 → 5.30.0

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