@allxsmith/bestax-bulma 5.37.0 → 5.38.0

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

@@ -10,6 +10,11 @@ export interface AnchoredPosition {
     position: AnchoredCorner;
     top?: number;
     left?: number;
+    /**
+     * With `matchWidth`, the anchor's width, which a fixed panel takes as its
+     * `min-width`.
+     */
+    minWidth?: number;
 }
 /**
  * Options for `useAnchoredPosition`.
@@ -41,6 +46,23 @@ export interface UseAnchoredPositionOptions {
      * well; the coordinates don't include it, because the stylesheet applies it.
      */
     styledGap?: (panel: HTMLElement) => number;
+    /**
+     * Whether the panel is at least as wide as the anchor, as a list under its
+     * field is. A panel in place gets that from its stylesheet. A fixed one
+     * can't, so its placement carries the anchor's width as `minWidth` for the
+     * panel to set, and its coordinates and `auto` already allow for it.
+     * @defaultValue false
+     */
+    matchWidth?: boolean;
+    /**
+     * Measures again after each render of the component holding the hook, for
+     * a panel whose content changes while it's open, as a filtered list's
+     * does. A fixed panel above its anchor is placed from its height, and
+     * `auto` reads the height too, so a measurement taken when it opened goes
+     * stale as the content changes.
+     * @defaultValue false
+     */
+    followContent?: boolean;
 }
 /**
  * A `styledGap` for a panel whose stylesheet puts the gap in a margin on the
@@ -53,7 +75,8 @@ export declare function marginGap(panel: HTMLElement): number;
  * and, for a panel fixed to the viewport, works out its coordinates. It
  * measures again on resize and on any scroll of the anchor's window (an
  * iframe's, when the anchor renders into one), so a fixed panel follows its
- * anchor. A measurement that changes nothing doesn't render again.
+ * anchor, and with `followContent` after each render too. A measurement that
+ * changes nothing doesn't render again.
  *
  * Measuring happens in a layout effect, so the panel is placed before it
  * paints. It needs both elements on the page while `active` is on, and
@@ -65,4 +88,4 @@ export declare function marginGap(panel: HTMLElement): number;
  * @param options - Whether to measure, the corner asked for, and how the panel is placed.
  * @returns The corner the panel opens from, with coordinates when it is fixed.
  */
-export declare function useAnchoredPosition(anchorRef: RefObject<HTMLElement | null>, panelRef: RefObject<HTMLElement | null>, { active, position, fixed, offset, styledGap }: UseAnchoredPositionOptions): AnchoredPosition;
+export declare function useAnchoredPosition(anchorRef: RefObject<HTMLElement | null>, panelRef: RefObject<HTMLElement | null>, { active, position, fixed, offset, styledGap, matchWidth, followContent, }: UseAnchoredPositionOptions): AnchoredPosition;

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

@@ -0,0 +1,111 @@
+import type React from 'react';
+/** What an item tells the engine about itself. */
+export interface ComboboxItemState {
+    /** What a pick hands back. Unique within the combobox. */
+    value: string;
+    /** Reachable with the arrows, never picked. */
+    disabled: boolean;
+    /** The value, or one of them. */
+    checked: boolean;
+}
+/** Options for `useComboboxEngine`. */
+export interface ComboboxEngineOptions {
+    /** Controlled open state. When set, opening and closing only report through `onOpenChange`. */
+    open?: boolean;
+    /** Initial open state when uncontrolled. */
+    defaultOpen: boolean;
+    /** Called with the open state asked for, when it differs from the current one. */
+    onOpenChange?: (open: boolean) => void;
+    /** Called with an item's `value` when it's picked. */
+    onSelect?: (value: string) => void;
+    /**
+     * Called when Enter goes on to the form with nothing to pick, before the
+     * list closes, so an owner that shows something other than the typing can
+     * put it back before the form reads the field. An `inline` list doesn't
+     * close, so this is the one word it gets.
+     */
+    onSettle?: () => void;
+    /** Highlights the first enabled item whenever the list opens or its items change. */
+    keepFirst: boolean;
+    /** Several values: a pick keeps the list open. */
+    multiple: boolean;
+    /** The list is always on screen, so nothing opens or closes it. */
+    inline: boolean;
+    /**
+     * The list's panel is portaled, so it has no server markup and shows only
+     * from the commit after hydration. Until it has rendered, an open list
+     * isn't taken to be on the page, so no `aria-controls` names it early.
+     */
+    deferred: boolean;
+}
+/** What `useComboboxEngine` hands the parts of a combobox. */
+export interface ComboboxEngine {
+    /** Whether the list is open. Always, with `inline`. */
+    open: boolean;
+    /**
+     * The field's `aria-expanded`: open, with a listbox that has an option in
+     * it on the page. Until the open list has rendered, it's taken to have
+     * one, so server markup for an open list in place says it's expanded. A
+     * `deferred` list isn't in server markup, so it's taken to have none.
+     */
+    expanded: boolean;
+    /** The highlighted option's value, if any. */
+    highlighted: string | null;
+    /** Whether the user has typed since the list opened. */
+    typed: boolean;
+    /** The listbox's id. */
+    listboxId: string;
+    /** An item's id, which follows from its value. */
+    itemId: (value: string) => string;
+    /** For the element around the field and, unless it's portaled, the list. */
+    rootRef: React.MutableRefObject<HTMLDivElement | null>;
+    /** For the field. */
+    inputRef: React.MutableRefObject<HTMLInputElement | null>;
+    /** For the listbox. */
+    listboxRef: React.MutableRefObject<HTMLDivElement | null>;
+    /**
+     * Records the floating panel while it's on screen, which makes it count as
+     * inside, and makes an Escape that closes it stop there. Returns the
+     * function that forgets it.
+     */
+    registerPopup: (element: HTMLElement) => () => void;
+    /** Records an item's element. Returns the function that forgets it. */
+    registerItem: (element: HTMLElement, state: ComboboxItemState) => () => void;
+    /** The field's keys, to run after the caller's own handler. */
+    onKeyDown: (event: React.KeyboardEvent<HTMLInputElement>) => void;
+    /** A change to the field's value: the user typed. */
+    onChange: () => void;
+    /** A click in the field. */
+    onClick: () => void;
+    /** Focus leaving the field. */
+    onBlur: (event: React.FocusEvent<HTMLInputElement>) => void;
+    /** The pointer moved over an enabled option. */
+    hover: (value: string) => void;
+    /** A click on an enabled option. Focus ends up in the field. */
+    pick: (value: string) => void;
+    /** For anything in the list: a press there doesn't take focus from the field. */
+    keepFocus: (event: React.MouseEvent) => void;
+    /**
+     * For the floating panel: marks a press as inside, which React reports from
+     * content the panel portals elsewhere as well.
+     */
+    markInside: (event: React.PointerEvent) => void;
+}
+/**
+ * The keys, the open state, the highlight and the ARIA of an editable
+ * combobox whose list the app renders and filters (#1083). DOM focus stays
+ * in the field the whole time: the highlight is `aria-activedescendant`, as
+ * the ARIA Authoring Practices ask of a combobox, where `useMenuKeys` moves
+ * real focus, as a menu should.
+ *
+ * The options are read from the listbox in document order whenever they're
+ * needed, so options in groups and options that come and go are found, and
+ * the highlight is remembered by value, so it survives a re-render. The text
+ * in the field and any value are the app's: a pick only calls
+ * `onSelect`.
+ *
+ * @function useComboboxEngine
+ * @param options - The open state, the pick callback and the shape.
+ * @returns The state and handlers the parts wire up.
+ */
+export declare function useComboboxEngine({ open: controlledOpen, defaultOpen, onOpenChange, onSelect, onSettle, keepFirst, multiple, inline, deferred, }: ComboboxEngineOptions): ComboboxEngine;

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

@@ -11,10 +11,23 @@ export declare function isTabbableKind(el: Element): boolean;
 /**
  * The first tab stop inside `container`, found the way the trap finds it, or
  * `null` when there is none. For a component that moves focus into a panel
- * without trapping it there. `src/index.ts` names its exports from this
- * module, so this one stays internal.
+ * itself rather than through the hook. `src/index.ts` names its exports from
+ * this module, so this one stays internal.
  */
 export declare function firstTabStop(container: HTMLElement): HTMLElement | null;
+/**
+ * Holds Tab inside `container` until the returned function is called. Tab
+ * and Shift+Tab heard on `keyTarget` wrap at the ends, unless something
+ * already marked the key used, and if a Tab the trap let through still takes
+ * focus out, it sends focus back to the other end.
+ *
+ * `holds` is asked on every Tab, and the trap leaves the key alone while it
+ * says no. Internal like `firstTabStop`. It's for an overlay that holds Tab
+ * from a listener of its own on `window` and asks the overlay stack first,
+ * so it stands aside while another overlay is open over it, which a trap
+ * listening on the container can't do.
+ */
+export declare function trapTab(container: HTMLElement, keyTarget?: EventTarget, holds?: () => boolean): () => void;
 /**
  * Options for `useFocusTrap`.
  */

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

@@ -0,0 +1,30 @@
+import type { RefObject } from 'react';
+/**
+ * Makes the elements beside `ref`'s element inert while `active` is true,
+ * and takes it off again when `active` turns false or the caller unmounts.
+ * With `wholePage`, it does the same beside each element above it up to
+ * `<body>`, so everything on the page but `ref`'s element is inert, the way a
+ * modal layer leaves it. The element itself and its own content are never
+ * touched.
+ *
+ * It sets the `inert` attribute through the DOM in an effect, so it works the
+ * same on React 18 and 19 and a server render has nothing to show for it. An
+ * element that was inert already is left alone, and keeps its `inert` once
+ * this lets go. It makes inert what's there when it turns on: an element that
+ * mounts beside it afterwards isn't. It follows the DOM, so content a web
+ * component renders around a slot this sits in, and text with no element of
+ * its own, stays as it is.
+ *
+ * Focus on an element that turns inert is lost: the browser moves it to
+ * `<body>`. So when focus was inside what this made inert, and is still on
+ * `<body>` when this lets go, it goes back to the element that had it. Focus
+ * this never took isn't handed anywhere, and focus the user or the app has
+ * put somewhere else meanwhile stays there.
+ *
+ * @function useInertSiblings
+ * @param ref - Ref to the element that stays reachable.
+ * @param active - Whether what's beside it is inert.
+ * @param wholePage - Whether that goes for the whole page rather than only
+ * the element's siblings.
+ */
+export declare function useInertSiblings(ref: RefObject<Element | null>, active: boolean, wholePage: boolean): void;

package/dist/types/index.d.ts

@@ -81,6 +81,7 @@ export * from './form/Slider.js';
 export * from './form/Numberinput.js';
 export * from './form/Rate.js';
 export * from './form/Autocomplete.js';
+export * from './form/Combobox.js';
 export * from './form/Taginput.js';
 export { InputBase } from './form/InputBase.js';
 export type { InputBaseProps } from './form/InputBase.js';

package/dist/types/layout/Container.d.ts

@@ -7,7 +7,15 @@ export type ContainerBreakpoint = 'tablet' | 'desktop' | 'widescreen';
 /**
  * Props for the Container component.
  */
-export interface ContainerProps extends React.HTMLAttributes<HTMLDivElement>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+export interface ContainerProps extends React.HTMLAttributes<HTMLElement>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /**
+     * HTML element to render (default: `div`). Bulma pages often put the
+     * container on a landmark, such as `<main class="container">` or
+     * `<footer class="container">`. A page has only one visible `main`, and a
+     * `section` is a `region` landmark only once it has an accessible name
+     * (`aria-label`, or `aria-labelledby` pointing at its heading).
+     */
+    as?: 'div' | 'main' | 'section' | 'article' | 'aside' | 'header' | 'footer' | 'nav';
     /** Additional CSS classes. */
     className?: string;
     /** Text color helper. */

package/dist/types/layout/Hero.d.ts

@@ -8,6 +8,15 @@ export type HeroSize = 'small' | 'medium' | 'large' | 'fullheight' | 'fullheight
  * Props for the Hero component.
  */
 export interface HeroProps extends React.HTMLAttributes<HTMLElement>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /**
+     * HTML element to render (default: `section`). Bulma pages often put the
+     * hero on a landmark: `main` when the hero is the page's main content,
+     * `header` for a banner above it, `footer` for one below it. A page has
+     * only one visible `main`, and a `section` is a `region` landmark only once
+     * it has an accessible name (`aria-label`, or `aria-labelledby` pointing at
+     * its heading).
+     */
+    as?: 'section' | 'div' | 'main' | 'header' | 'footer' | 'article' | 'aside';
     /** Additional CSS classes. */
     className?: string;
     /**
@@ -37,7 +46,15 @@ export interface HeroProps extends React.HTMLAttributes<HTMLElement>, Omit<Bulma
 /**
  * Props for the HeroHead component.
  */
-export interface HeroHeadProps extends React.HTMLAttributes<HTMLDivElement>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+export interface HeroHeadProps extends React.HTMLAttributes<HTMLElement>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /**
+     * HTML element to render (default: `div`). `nav` suits a head that holds
+     * only the site's navigation. A `header` is a `banner` landmark only when
+     * no `section`, `article`, `aside`, `nav` or `main` is around it, so inside
+     * the default `<section>` hero it is not one: render the hero as a `div`
+     * for that. A `header` may not sit inside another `header` or a `footer`.
+     */
+    as?: 'div' | 'header' | 'nav';
     /** Additional CSS classes. */
     className?: string;
     /** Bulma color modifier for text. */
@@ -93,7 +110,15 @@ export declare const HeroBody: React.FC<HeroBodyProps>;
 /**
  * Props for the HeroFoot component.
  */
-export interface HeroFootProps extends React.HTMLAttributes<HTMLDivElement>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+export interface HeroFootProps extends React.HTMLAttributes<HTMLElement>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /**
+     * HTML element to render (default: `div`). `nav` suits a foot that holds
+     * tabs or links. A `footer` is a `contentinfo` landmark only when no
+     * `section`, `article`, `aside`, `nav` or `main` is around it, so inside
+     * the default `<section>` hero it is not one: render the hero as a `div`
+     * for that. A `footer` may not sit inside another `footer` or a `header`.
+     */
+    as?: 'div' | 'footer' | 'nav';
     /** Additional CSS classes. */
     className?: string;
     /** Bulma color modifier for text. */

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

@@ -14,10 +14,24 @@ export type LoadingColor = 'primary' | 'link' | 'info' | 'success' | 'warning' |
  * @extraProp {string} [className] - Additional CSS classes.
  */
 export interface LoadingProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'color'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor' | 'size' | 'overlay'> {
-    /** Whether the loading overlay is visible. */
+    /**
+     * Whether the loading overlay is visible. While it is, what it covers is
+     * inert, out of reach of Tab, Enter, Space and screen readers as well as
+     * the mouse: the other children of the element it's rendered in, so render
+     * it directly inside the element it covers, or with `isFullPage` the rest
+     * of the page. Its own content, the cancel button included, stays
+     * reachable. Only what's there when it turns on is made inert, and an
+     * element that was inert already is left as it was. A control under it
+     * that had focus loses it, and gets it back when the loading goes away,
+     * unless focus has moved on in the meantime. Show one at a time over the
+     * same content: two that cover each other, such as two in one container
+     * or two full-page ones, make each other inert, cancel buttons and all.
+     */
     active?: boolean;
     /**
-     * Cover the entire viewport. A full-page loading also takes its turn with
+     * Cover the entire viewport. While it's active, the rest of the page is
+     * inert, as it is under a modal, rather than only the element it's
+     * rendered in. A full-page loading also takes its turn with
      * Modal and Sidebar for Escape: while it's the topmost open overlay, the
      * Modal or Sidebar under it doesn't answer Escape or hold Tab, whether or
      * not the loading can be cancelled.

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

@@ -1,10 +1,19 @@
 import React from 'react';
 import { BulmaClassesProps } from '../helpers/useBulmaClasses.js';
+import type { ConstrainedPolymorphicComponentWithoutRef } from '../helpers/polymorphic.js';
 import { IconChildrenProps, IconDeprecatedProps, IconNameProps } from '../elements/Icon.js';
 /**
  * Props for the Panel component.
  */
 export interface PanelProps extends React.HTMLAttributes<HTMLElement>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /**
+     * HTML element to render (default: `nav`). A `nav` is a `navigation`
+     * landmark, which suits a panel of links; a panel that is not navigation
+     * takes another tag. Bulma's own colored panels use `article`. A `section`
+     * is a `region` landmark only once it has an accessible name, such as
+     * `aria-labelledby` pointing at the `id` of its `Panel.Heading`.
+     */
+    as?: 'nav' | 'article' | 'section' | 'aside' | 'div';
     /** Bulma color modifier for the panel. */
     color?: 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger' | 'black' | 'dark' | 'light' | 'white';
     /** Additional CSS classes. */
@@ -31,9 +40,14 @@ export interface PanelTabsProps extends React.HTMLAttributes<HTMLDivElement> {
     children?: React.ReactNode;
 }
 /**
- * Props for the PanelBlock component.
+ * The elements a panel block may render as: the tags Bulma's panel markup
+ * puts `.panel-block` on.
  */
-export interface PanelBlockProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
+export type PanelBlockElement = 'a' | 'div' | 'label';
+/**
+ * The PanelBlock component's own props.
+ */
+export interface PanelBlockOwnProps {
     /** Additional CSS classes. */
     className?: string;
     /** Whether the block is active. */
@@ -41,6 +55,32 @@ export interface PanelBlockProps extends React.AnchorHTMLAttributes<HTMLAnchorEl
     /** Block content. */
     children?: React.ReactNode;
 }
+/**
+ * Props for the PanelBlock component. Everything the block does not own
+ * follows `as`: the anchor's attributes and an `HTMLAnchorElement`
+ * `currentTarget` under the default `'a'`, `htmlFor` under `'label'`, and the
+ * shared HTML attributes under any of them.
+ *
+ * The type parameter defaults to `'a'`, the element a block renders with no
+ * `as`, rather than to the whole union the way `DropdownItemProps` does. Before
+ * `as` existed this type was the anchor's attributes, so bare
+ * `PanelBlockProps` stays exactly that, `href` and anchor-typed handlers
+ * included. Write `PanelBlockProps<'div'>` or `PanelBlockProps<'label'>` for
+ * the others.
+ */
+export type PanelBlockProps<T extends PanelBlockElement = 'a'> = PanelBlockOwnProps & Omit<React.ComponentPropsWithoutRef<T>, keyof PanelBlockOwnProps | 'as'> & {
+    /**
+     * HTML element to render (default: `a`). Bulma styles a `label` block
+     * as clickable, like an `a`, and a `div` block as static content, such
+     * as a table. The props follow the tag, so the anchor attributes
+     * (`href`, `target`, `download` and the rest) are typed only on an `a`
+     * and `htmlFor` only on a `label`; at runtime the block also drops them,
+     * and `rel`, on the other tags. `Panel.CheckboxBlock`,
+     * `Panel.InputBlock` and `Panel.ButtonBlock` render the usual `label`
+     * and `div` blocks with their contents.
+     */
+    as?: T;
+};
 /**
  * Props for the PanelIcon component.
  * Extends IconProps but uses 'panel-icon' as the container class.
@@ -94,13 +134,13 @@ export declare const PanelHeading: React.FC<PanelHeadingProps>;
  */
 export declare const PanelTabs: React.FC<PanelTabsProps>;
 /**
- * Individual panel block (renders as `<a class="panel-block">`)
+ * Individual panel block (renders as `<a class="panel-block">` unless `as` says otherwise)
  *
  * @function
  * @param {PanelBlockProps} props - Props for the PanelBlock component.
  * @returns {JSX.Element} The rendered panel block.
  */
-export declare const PanelBlock: React.FC<PanelBlockProps>;
+export declare const PanelBlock: ConstrainedPolymorphicComponentWithoutRef<PanelBlockOwnProps, PanelBlockElement, "a">;
 /**
  * Icon wrapper with panel styling (renders as `<span class="panel-icon">`, containing an
  * `<i/>` when a `name` is given, or the custom node passed as `children`).
@@ -138,7 +178,7 @@ export declare const PanelButtonBlock: React.FC<PanelButtonBlockProps>;
 export declare const Panel: React.FC<PanelProps> & {
     Heading: React.FC<PanelHeadingProps>;
     Tabs: React.FC<PanelTabsProps>;
-    Block: React.FC<PanelBlockProps>;
+    Block: ConstrainedPolymorphicComponentWithoutRef<PanelBlockOwnProps, PanelBlockElement, "a", never>;
     Icon: React.FC<PanelIconProps>;
     InputBlock: React.FC<PanelInputBlockProps>;
     CheckboxBlock: React.FC<PanelCheckboxBlockProps>;

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

@@ -8,7 +8,15 @@ export type SidebarPosition = 'left' | 'right';
  * @extraProp {React.Ref<HTMLElement>} [ref] - Ref forwarded to the sidebar element.
  */
 export interface SidebarProps extends Omit<React.HTMLAttributes<HTMLElement>, 'children' | 'color'>, BulmaClassesProps {
-    /** Whether the sidebar is open (required). */
+    /**
+     * Whether the sidebar is open (required). Opening moves focus into the
+     * sidebar, to its first tab stop or the sidebar itself. Closing hands focus
+     * back to whatever had it when the sidebar opened, unless focus has already
+     * left the sidebar, as it does for an overlay opened over it. A closed
+     * sidebar stays in the page, so it can slide out, and is `inert` and
+     * `aria-hidden` there: Tab passes over its content and assistive
+     * technology doesn't read it.
+     */
     isOpen: boolean;
     /** Callback when sidebar should close. */
     onClose?: () => void;
@@ -20,7 +28,14 @@ export interface SidebarProps extends Omit<React.HTMLAttributes<HTMLElement>, 'c
     isFullwidth?: boolean;
     /** Sidebar takes full width (mobile-style). @deprecated Use `isFullwidth` instead — `isFullwidth` wins if both are set. */
     fullWidth?: boolean;
-    /** Show overlay behind sidebar. Default: true. */
+    /**
+     * Show an overlay behind the sidebar, which makes it modal: it gets
+     * `aria-modal="true"`, locks body scroll, and keeps Tab and Shift+Tab
+     * inside it while it is the topmost overlay. A Modal or Dialog opened over
+     * it, even one rendered inside it, holds Tab until it closes. Without an
+     * overlay the sidebar isn't modal, and Tab moves in and out of it freely.
+     * Default: true.
+     */
     overlay?: boolean;
     /** Close sidebar when overlay is clicked. Default: true. */
     overlayClose?: boolean;