@allxsmith/bestax-bulma 5.40.0 → 5.41.0

package/dist/index.esm.js

@@ -8,7 +8,7 @@ export { Breadcrumb } from './esm/components/Breadcrumb.js';
 export { Card } from './esm/components/Card.js';
 export { Dropdown, DropdownDivider, DropdownItem, isBrowser } from './esm/components/Dropdown.js';
 export { EmptyState, EmptyStateActions, EmptyStateDescription, EmptyStateIndicator, EmptyStateTitle } from './esm/components/EmptyState.js';
-export { Menu, MenuItem, MenuLabel, MenuList } from './esm/components/Menu.js';
+export { Menu, MenuItem, MenuLabel, MenuList, MenuSection } from './esm/components/Menu.js';
 export { Message } from './esm/components/Message.js';
 export { Modal } from './esm/components/Modal.js';
 export { Navbar, NavbarBrand, NavbarBurger, NavbarDivider, NavbarDropdown, NavbarDropdownMenu, NavbarEnd, NavbarItem, NavbarLink, NavbarMenu, NavbarStart } from './esm/components/Navbar.js';

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

@@ -115,9 +115,58 @@ export type MenuItemProps<T extends React.ElementType = 'a'> = MenuItemOwnProps
  * @returns {JSX.Element} The rendered menu item.
  */
 export declare const MenuItem: PolymorphicComponent<MenuItemOwnProps, "a">;
+/**
+ * Props for the MenuSection component. The helper props and the other
+ * attributes land on the wrapping `<div>`.
+ */
+export interface MenuSectionProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof BulmaClassesProps>, BulmaClassesProps {
+    /** Additional CSS classes for the wrapping `<div>`. */
+    className?: string;
+    /** **Required.** The section's heading, drawn like `Menu.Label` inside the button that opens and closes it. Keep links and buttons out of it, since it's inside one. */
+    label: React.ReactNode;
+    /**
+     * The `Menu.List` of links the section shows while it's open. The section
+     * itself goes directly in `Menu`, beside its labels and lists: inside a
+     * `Menu.Item` it would render inside the item's link, and inside a
+     * `Menu.List` it wouldn't be a list item.
+     */
+    children: React.ReactNode;
+    /** Controlled open state. If provided, the section is controlled, and its button only reports through `onOpenChange`. */
+    open?: boolean;
+    /** Initial open state for uncontrolled usage. Open the section that holds the current page, so the reader sees where they are. */
+    defaultOpen?: boolean;
+    /** Called with the state the button asks for (`true` to open) each time it is clicked or activated with Enter or Space, in every mode. Pair it with `open` to let the button drive a controlled section. */
+    onOpenChange?: (open: boolean) => void;
+}
+/**
+ * A section of the menu that opens and closes: its heading is a button drawn like `Menu.Label`, and its `Menu.List` of links shows while it's open.
+ *
+ * It's APG's disclosure navigation, for a sidebar of link groups: the links
+ * stay ordinary links, each its own tab stop, and a closed section's list is
+ * `hidden` and `inert`, so Tab and assistive tech skip it. It goes directly in
+ * `Menu`, holding a `Menu.List`. Closing it while focus is on one of its links
+ * moves focus to its heading.
+ *
+ * @function
+ * @param {MenuSectionProps} props - Props for the MenuSection component.
+ * @returns {JSX.Element} The rendered menu section.
+ * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/examples/disclosure-navigation/ | APG Disclosure Navigation Menu example}
+ *
+ * @example
+ * <Menu>
+ *   <Menu.Section label="Components" defaultOpen>
+ *     <Menu.List>
+ *       <Menu.Item href="/button" active>Button</Menu.Item>
+ *       <Menu.Item href="/card">Card</Menu.Item>
+ *     </Menu.List>
+ *   </Menu.Section>
+ * </Menu>
+ */
+export declare const MenuSection: React.FC<MenuSectionProps>;
 export declare const Menu: React.FC<MenuProps> & {
     Label: React.FC<MenuLabelProps>;
     List: React.FC<MenuListProps>;
     Item: PolymorphicComponent<MenuItemOwnProps, "a", never>;
+    Section: React.FC<MenuSectionProps>;
 };
 export default Menu;

package/dist/types/elements/Image.d.ts

@@ -17,7 +17,12 @@ export interface ImageProps extends React.HTMLAttributes<HTMLElement>, Omit<Bulm
     color?: 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger';
     /** Background color helper for the container. */
     bgColor?: (typeof validColors)[number] | 'inherit' | 'current';
-    /** Fixed size or aspect ratio modifier for the image container. */
+    /**
+     * Fixed size or aspect ratio modifier for the image container. A ratio
+     * (`16by9` and the rest) renders only its `is-<ratio>` class there. Bulma
+     * stretches an `<img>` inside to fill the ratio, but any other child, such
+     * as an `iframe`, fills it only with `className="has-ratio"` of its own.
+     */
     size?: '16x16' | '24x24' | '32x32' | '48x48' | '64x64' | '96x96' | '128x128' | 'square' | '1by1' | '5by4' | '4by3' | '3by2' | '5by3' | '16by9' | '2by1' | '3by1' | '4by5' | '3by4' | '2by3' | '3by5' | '9by16' | '1by2' | '1by3';
     /** Renders the image with rounded corners. */
     isRounded?: boolean;

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

@@ -5,16 +5,24 @@ import type { RefObject } from 'react';
  * can read `-1` for an editable region or an `<embed>` that Tab still visits,
  * and `0` for a `<video>` without controls that it doesn't. So a valid
  * `tabindex` attribute decides, and otherwise the element's kind does.
- * Internal like `firstTabStop`: `src/index.ts` names what it takes from here.
+ * Internal like `focusTabStop`: `src/index.ts` names what it takes from here.
  */
 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
- * itself rather than through the hook. `src/index.ts` names its exports from
+ * Moves focus to the first tab stop inside `container`, or the last when
+ * `fromLast`, and to the container when there is none. Every move a trap
+ * makes goes through here: into the container as it opens, to the other end
+ * on a wrap, and back in after a Tab the browser carried out.
+ *
+ * A stop that doesn't take focus is passed over for the next one in. An
+ * `<object>` or `<embed>` with nothing to show is one: it counts as a stop by
+ * its kind, but browsers refuse to focus it, and which ones they refuse
+ * depends on the browser and on what has loaded, so only trying tells. A
+ * stop took focus when focus moved, wherever it went (a stop can hand focus
+ * on), or when focus was on it already. `src/index.ts` names its exports from
  * this module, so this one stays internal.
  */
-export declare function firstTabStop(container: HTMLElement): HTMLElement | null;
+export declare function focusTabStop(container: HTMLElement, fromLast?: boolean): void;
 /**
  * Holds Tab inside the element `container` returns until the returned
  * function is called. Tab and Shift+Tab heard on `keyTarget` wrap at the
@@ -25,7 +33,7 @@ export declare function firstTabStop(container: HTMLElement): HTMLElement | null
  * overlay whose nodes are remounted while it's open, as moving to another
  * portal target does, stays trapped without attaching again. `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
+ * like `focusTabStop`. 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.
@@ -46,8 +54,8 @@ export interface UseFocusTrapOptions {
      * to be one that can take focus, so a heading needs `tabIndex={-1}`. When
      * focusing it doesn't put focus inside the container (the ref is empty, or
      * its element is outside, disabled, hidden or can't take focus), focus goes
-     * to the first tab stop inside the container, and to the container itself
-     * when there is none.
+     * to the first tab stop inside the container that takes focus, and to the
+     * container itself when none does.
      */
     initialFocusRef?: RefObject<HTMLElement | null>;
     /**

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

@@ -115,9 +115,58 @@ export type MenuItemProps<T extends React.ElementType = 'a'> = MenuItemOwnProps
  * @returns {JSX.Element} The rendered menu item.
  */
 export declare const MenuItem: PolymorphicComponent<MenuItemOwnProps, "a">;
+/**
+ * Props for the MenuSection component. The helper props and the other
+ * attributes land on the wrapping `<div>`.
+ */
+export interface MenuSectionProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof BulmaClassesProps>, BulmaClassesProps {
+    /** Additional CSS classes for the wrapping `<div>`. */
+    className?: string;
+    /** **Required.** The section's heading, drawn like `Menu.Label` inside the button that opens and closes it. Keep links and buttons out of it, since it's inside one. */
+    label: React.ReactNode;
+    /**
+     * The `Menu.List` of links the section shows while it's open. The section
+     * itself goes directly in `Menu`, beside its labels and lists: inside a
+     * `Menu.Item` it would render inside the item's link, and inside a
+     * `Menu.List` it wouldn't be a list item.
+     */
+    children: React.ReactNode;
+    /** Controlled open state. If provided, the section is controlled, and its button only reports through `onOpenChange`. */
+    open?: boolean;
+    /** Initial open state for uncontrolled usage. Open the section that holds the current page, so the reader sees where they are. */
+    defaultOpen?: boolean;
+    /** Called with the state the button asks for (`true` to open) each time it is clicked or activated with Enter or Space, in every mode. Pair it with `open` to let the button drive a controlled section. */
+    onOpenChange?: (open: boolean) => void;
+}
+/**
+ * A section of the menu that opens and closes: its heading is a button drawn like `Menu.Label`, and its `Menu.List` of links shows while it's open.
+ *
+ * It's APG's disclosure navigation, for a sidebar of link groups: the links
+ * stay ordinary links, each its own tab stop, and a closed section's list is
+ * `hidden` and `inert`, so Tab and assistive tech skip it. It goes directly in
+ * `Menu`, holding a `Menu.List`. Closing it while focus is on one of its links
+ * moves focus to its heading.
+ *
+ * @function
+ * @param {MenuSectionProps} props - Props for the MenuSection component.
+ * @returns {JSX.Element} The rendered menu section.
+ * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/examples/disclosure-navigation/ | APG Disclosure Navigation Menu example}
+ *
+ * @example
+ * <Menu>
+ *   <Menu.Section label="Components" defaultOpen>
+ *     <Menu.List>
+ *       <Menu.Item href="/button" active>Button</Menu.Item>
+ *       <Menu.Item href="/card">Card</Menu.Item>
+ *     </Menu.List>
+ *   </Menu.Section>
+ * </Menu>
+ */
+export declare const MenuSection: React.FC<MenuSectionProps>;
 export declare const Menu: React.FC<MenuProps> & {
     Label: React.FC<MenuLabelProps>;
     List: React.FC<MenuListProps>;
     Item: PolymorphicComponent<MenuItemOwnProps, "a", never>;
+    Section: React.FC<MenuSectionProps>;
 };
 export default Menu;

package/dist/types-cjs/elements/Image.d.ts

@@ -17,7 +17,12 @@ export interface ImageProps extends React.HTMLAttributes<HTMLElement>, Omit<Bulm
     color?: 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger';
     /** Background color helper for the container. */
     bgColor?: (typeof validColors)[number] | 'inherit' | 'current';
-    /** Fixed size or aspect ratio modifier for the image container. */
+    /**
+     * Fixed size or aspect ratio modifier for the image container. A ratio
+     * (`16by9` and the rest) renders only its `is-<ratio>` class there. Bulma
+     * stretches an `<img>` inside to fill the ratio, but any other child, such
+     * as an `iframe`, fills it only with `className="has-ratio"` of its own.
+     */
     size?: '16x16' | '24x24' | '32x32' | '48x48' | '64x64' | '96x96' | '128x128' | 'square' | '1by1' | '5by4' | '4by3' | '3by2' | '5by3' | '16by9' | '2by1' | '3by1' | '4by5' | '3by4' | '2by3' | '3by5' | '9by16' | '1by2' | '1by3';
     /** Renders the image with rounded corners. */
     isRounded?: boolean;

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

@@ -5,16 +5,24 @@ import type { RefObject } from 'react';
  * can read `-1` for an editable region or an `<embed>` that Tab still visits,
  * and `0` for a `<video>` without controls that it doesn't. So a valid
  * `tabindex` attribute decides, and otherwise the element's kind does.
- * Internal like `firstTabStop`: `src/index.ts` names what it takes from here.
+ * Internal like `focusTabStop`: `src/index.ts` names what it takes from here.
  */
 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
- * itself rather than through the hook. `src/index.ts` names its exports from
+ * Moves focus to the first tab stop inside `container`, or the last when
+ * `fromLast`, and to the container when there is none. Every move a trap
+ * makes goes through here: into the container as it opens, to the other end
+ * on a wrap, and back in after a Tab the browser carried out.
+ *
+ * A stop that doesn't take focus is passed over for the next one in. An
+ * `<object>` or `<embed>` with nothing to show is one: it counts as a stop by
+ * its kind, but browsers refuse to focus it, and which ones they refuse
+ * depends on the browser and on what has loaded, so only trying tells. A
+ * stop took focus when focus moved, wherever it went (a stop can hand focus
+ * on), or when focus was on it already. `src/index.ts` names its exports from
  * this module, so this one stays internal.
  */
-export declare function firstTabStop(container: HTMLElement): HTMLElement | null;
+export declare function focusTabStop(container: HTMLElement, fromLast?: boolean): void;
 /**
  * Holds Tab inside the element `container` returns until the returned
  * function is called. Tab and Shift+Tab heard on `keyTarget` wrap at the
@@ -25,7 +33,7 @@ export declare function firstTabStop(container: HTMLElement): HTMLElement | null
  * overlay whose nodes are remounted while it's open, as moving to another
  * portal target does, stays trapped without attaching again. `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
+ * like `focusTabStop`. 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.
@@ -46,8 +54,8 @@ export interface UseFocusTrapOptions {
      * to be one that can take focus, so a heading needs `tabIndex={-1}`. When
      * focusing it doesn't put focus inside the container (the ref is empty, or
      * its element is outside, disabled, hidden or can't take focus), focus goes
-     * to the first tab stop inside the container, and to the container itself
-     * when there is none.
+     * to the first tab stop inside the container that takes focus, and to the
+     * container itself when none does.
      */
     initialFocusRef?: RefObject<HTMLElement | null>;
     /**