@allxsmith/bestax-bulma 5.13.0 → 5.15.0

package/dist/index.cjs.js

@@ -1776,14 +1776,46 @@ const isBrowser$1 = (win, doc) => typeof win !== 'undefined' && typeof doc !== '
  *
  * @function
  * @param {DropdownProps} props - Props for the Dropdown component.
+ * @param {React.Ref<HTMLDivElement>} ref - Forwarded ref to the root dropdown element.
  * @returns {JSX.Element} The rendered dropdown.
  * @see {@link https://bulma.io/documentation/components/dropdown/ | Bulma Dropdown documentation}
  */
-const DropdownComponent = ({ label, children, className, menuClassName, active: activeProp, up, right, hoverable, disabled, onActiveChange, closeOnClick = true, id, ...props }) => {
+const DropdownComponent = React.forwardRef(function DropdownComponent({ label, children, className, menuClassName, active: activeProp, up, right, hoverable, disabled, onActiveChange, closeOnClick = true, id, ...props }, ref) {
     const [active, setActive] = React.useState(!!activeProp);
     const dropdownRef = React.useRef(null);
     const triggerRef = React.useRef(null);
     const pendingFocusRef = React.useRef(null);
+    // Cleanup returned by a consumer's callback ref on attach, held until detach.
+    const consumerCleanupRef = React.useRef(null);
+    const setRefs = React.useCallback((node) => {
+        dropdownRef.current =
+            node;
+        if (typeof ref === 'function') {
+            // React 19 lets a callback ref return a cleanup function and detaches
+            // by running it instead of calling the ref with `null`; React 18
+            // discards the return value entirely. Returning it from here would be
+            // a React-19-only contract, so instead we hold the cleanup and run it
+            // ourselves on detach — a consumer's cleanup ref then behaves the same
+            // on both majors of the CI matrix.
+            if (node === null) {
+                const consumerCleanup = consumerCleanupRef.current;
+                consumerCleanupRef.current = null;
+                if (consumerCleanup) {
+                    consumerCleanup();
+                }
+                else {
+                    ref(null);
+                }
+                return;
+            }
+            const cleanup = ref(node);
+            consumerCleanupRef.current =
+                typeof cleanup === 'function' ? cleanup : null;
+        }
+        else if (ref) {
+            ref.current = node;
+        }
+    }, [ref]);
     const { bulmaHelperClasses, rest } = useBulmaClasses(props);
     // Generate Bulma classes with prefix
     const bulmaClasses = usePrefixedClassNames('dropdown', {
@@ -1951,8 +1983,8 @@ const DropdownComponent = ({ label, children, className, menuClassName, active:
         }
     };
     const dropdownClasses = classNames(bulmaClasses, bulmaHelperClasses, className);
-    return (jsxRuntime.jsxs("div", { className: dropdownClasses, ref: dropdownRef, id: id, "data-testid": "dropdown-root", ...rest, children: [jsxRuntime.jsx("div", { className: usePrefixedClassNames('dropdown-trigger'), children: jsxRuntime.jsxs("button", { ref: triggerRef, className: buttonClass, "aria-haspopup": "true", "aria-controls": id ? `${id}-menu` : undefined, "aria-expanded": active, onClick: handleToggle, onKeyDown: handleTriggerKeyDown, disabled: disabled, type: "button", children: [jsxRuntime.jsx("span", { children: label }), jsxRuntime.jsx("span", { className: usePrefixedClassNames('icon', 'is-small'), "aria-hidden": "true", children: jsxRuntime.jsx("i", { className: "fas fa-angle-down" }) })] }) }), jsxRuntime.jsx("div", { className: classNames(usePrefixedClassNames('dropdown-menu'), menuClassName), id: id ? `${id}-menu` : undefined, role: "menu", "data-testid": "dropdown-menu", onKeyDown: handleMenuKeyDown, children: jsxRuntime.jsx("div", { className: usePrefixedClassNames('dropdown-content'), onClick: handleMenuClick, tabIndex: -1, children: children }) })] }));
-};
+    return (jsxRuntime.jsxs("div", { className: dropdownClasses, ref: setRefs, id: id, "data-testid": "dropdown-root", ...rest, children: [jsxRuntime.jsx("div", { className: usePrefixedClassNames('dropdown-trigger'), children: jsxRuntime.jsxs("button", { ref: triggerRef, className: buttonClass, "aria-haspopup": "true", "aria-controls": id ? `${id}-menu` : undefined, "aria-expanded": active, onClick: handleToggle, onKeyDown: handleTriggerKeyDown, disabled: disabled, type: "button", children: [jsxRuntime.jsx("span", { children: label }), jsxRuntime.jsx("span", { className: usePrefixedClassNames('icon', 'is-small'), "aria-hidden": "true", children: jsxRuntime.jsx("i", { className: "fas fa-angle-down" }) })] }) }), jsxRuntime.jsx("div", { className: classNames(usePrefixedClassNames('dropdown-menu'), menuClassName), id: id ? `${id}-menu` : undefined, role: "menu", "data-testid": "dropdown-menu", onKeyDown: handleMenuKeyDown, children: jsxRuntime.jsx("div", { className: usePrefixedClassNames('dropdown-content'), onClick: handleMenuClick, tabIndex: -1, children: children }) })] }));
+});
 /**
  * Bulma Dropdown item.
  *
@@ -2108,6 +2140,105 @@ const Message = withSubComponents(MessageComponent, {
     Body: MessageBody,
 }, 'Message');
 
+// Ref-counted across every caller (e.g. a Dialog rendering its own Modal)
+// so overlapping/nested locks don't fight over which one restores `overflow`.
+// Every overlay that locks body scroll — Modal, Dialog, Sidebar, Loading —
+// goes through here; a component setting `document.body.style.overflow`
+// itself would clear a lock another overlay still needs.
+let lockCount = 0;
+let originalOverflow = '';
+/**
+ * Locks (and ref-counted-ly unlocks) `document.body` scrolling while `active`
+ * is true. Safe to call from multiple components at once — the body scroll
+ * is only restored once every active caller has released its lock.
+ *
+ * @function useScrollLock
+ * @param active - Whether this caller wants the body scroll locked.
+ */
+function useScrollLock(active) {
+    React.useEffect(() => {
+        if (!active)
+            return undefined;
+        lockCount++;
+        if (lockCount === 1) {
+            originalOverflow = document.body.style.overflow;
+            document.body.style.overflow = 'hidden';
+        }
+        return () => {
+            lockCount--;
+            if (lockCount === 0) {
+                document.body.style.overflow = originalOverflow;
+            }
+        };
+    }, [active]);
+}
+
+/**
+ * Resolves a portal target: an `HTMLElement` is used directly, a non-empty
+ * `string` is treated as a `document.querySelector` selector (falling back to
+ * `document.body` when it matches nothing), and any falsy value — `undefined`
+ * or the empty string — resolves to `document.body`.
+ *
+ * The empty string is deliberately treated as "no target" rather than passed
+ * through: `document.querySelector('')` throws a `SyntaxError`, and callers
+ * building a selector from state can easily hand us `''`.
+ *
+ * @function resolvePortalContainer
+ * @param container - The requested portal target, if any.
+ * @returns The resolved DOM node to portal into.
+ */
+function resolvePortalContainer(container) {
+    if (!container) {
+        return document.body;
+    }
+    if (typeof container === 'string') {
+        return (document.querySelector(container) ?? document.body);
+    }
+    return container;
+}
+
+// "Are we past hydration?" as a store that never changes: React reads the
+// server snapshot both while server-rendering and while hydrating, and the
+// client snapshot from the first post-hydration render onward.
+const subscribeToNothing = () => () => { };
+const getClientSnapshot = () => true;
+const getServerSnapshot = () => false;
+/**
+ * Reports whether the component has passed hydration.
+ *
+ * Returns `false` during server rendering and during the hydrating client
+ * render, then `true` from the commit that follows. Use it to defer
+ * DOM-only behaviour (such as portalling) past hydration so the first client
+ * render matches the server markup instead of tripping hydration recovery.
+ *
+ * @function useIsHydrated
+ * @returns `true` once the hydrating render has completed, otherwise `false`.
+ */
+function useIsHydrated() {
+    return React.useSyncExternalStore(subscribeToNothing, getClientSnapshot, getServerSnapshot);
+}
+
+/**
+ * Every currently active modal, in the order they opened. Only the last entry
+ * — the topmost modal — reacts to Escape and Tab, so one keypress can't
+ * dismiss a whole stack (e.g. a `Dialog` opened on top of a `Modal`).
+ */
+const activeModalStack = [];
+/**
+ * Controls the modal can hand focus to. Disabled and hidden controls are
+ * excluded because `focus()` on them is a no-op, which would leave focus
+ * outside the modal.
+ */
+const FOCUSABLE_SELECTOR$1 = 'button:not(:disabled), [href], input:not(:disabled):not([type="hidden"]), select:not(:disabled), textarea:not(:disabled), [tabindex]';
+/**
+ * The modal's tab stops, in document order. The selector alone is not the
+ * tabbable set — `[href]` and `button` match regardless of `tabindex`, so an
+ * `<a href tabIndex={-1}>` would otherwise be treated as a tab stop and let
+ * Tab escape the modal when it sorts last. `el.tabIndex` is the browser's own
+ * resolved value, so filtering on it drops every negative index (not just
+ * `-1`) without a second selector to keep in sync.
+ */
+const getTabbable = (node) => Array.from(node.querySelectorAll(FOCUSABLE_SELECTOR$1)).filter(el => el.tabIndex >= 0);
 /**
  * Modal.Background - Renders the modal background overlay.
  *
@@ -2238,7 +2369,7 @@ const ModalClose = ({ className, size = 'large', variant = 'delete', ...props })
  *
  * @see {@link https://bulma.io/documentation/components/modal/ | Bulma Modal documentation}
  */
-const ModalRoot = ({ active, isActive, onClose, className, textColor, bgColor, modalCardTitle, modalCardFoot, type, children, ...props }) => {
+const ModalRoot = React.forwardRef(function ModalRoot({ active, isActive, onClose, className, textColor, bgColor, modalCardTitle, modalCardFoot, type, children, closeOnEscape = true, lockScroll = true, portal = false, role, 'aria-modal': ariaModalProp, ...props }, ref) {
     const { classPrefix } = useConfig();
     const { bulmaHelperClasses, rest } = useBulmaClasses({
         color: textColor,
@@ -2247,6 +2378,133 @@ const ModalRoot = ({ active, isActive, onClose, className, textColor, bgColor, m
     });
     // Support both active and isActive props
     const isModalActive = active ?? isActive ?? false;
+    const modalRootRef = React.useRef(null);
+    // Cleanup returned by a consumer's callback ref on attach, held until detach.
+    const consumerCleanupRef = React.useRef(null);
+    // The forwarded ref and the internal one must both see the node: focus
+    // management, the scroll lock and the topmost-modal check all read
+    // `modalRootRef`, while consumers expect their own ref to resolve.
+    const combinedRef = React.useCallback((node) => {
+        modalRootRef.current =
+            node;
+        if (typeof ref === 'function') {
+            // React 19 lets a callback ref return a cleanup function and detaches
+            // by running it instead of calling the ref with `null`; React 18
+            // discards the return value entirely. Returning it from here would be
+            // a React-19-only contract, so instead we hold the cleanup and run it
+            // ourselves on detach — a consumer's cleanup ref then behaves the same
+            // on both majors of the CI matrix. Same shape as `Dropdown`.
+            if (node === null) {
+                const consumerCleanup = consumerCleanupRef.current;
+                consumerCleanupRef.current = null;
+                if (consumerCleanup) {
+                    consumerCleanup();
+                }
+                else {
+                    ref(null);
+                }
+                return;
+            }
+            const cleanup = ref(node);
+            consumerCleanupRef.current =
+                typeof cleanup === 'function' ? cleanup : null;
+        }
+        else if (ref) {
+            ref.current = node;
+        }
+    }, [ref]);
+    const previouslyFocusedRef = React.useRef(null);
+    const stackTokenRef = React.useRef({});
+    const generatedTitleId = React.useId();
+    // A portal has no server-rendered counterpart, so the server render and the
+    // hydrating render have to stay inline and only move into the portal once
+    // we're past hydration.
+    const onClient = useIsHydrated();
+    // Moving into the portal remounts the modal's subtree, so any effect holding
+    // a DOM node from before the move is holding a detached one. Effects that
+    // touch the modal's nodes key on this so they re-run against the new tree.
+    const isPortaled = Boolean(portal) && onClient;
+    useScrollLock(isModalActive && lockScroll);
+    // Record open order so keyboard handling only applies to the topmost modal.
+    React.useEffect(() => {
+        if (!isModalActive)
+            return undefined;
+        const token = stackTokenRef.current;
+        activeModalStack.push(token);
+        return () => {
+            const index = activeModalStack.indexOf(token);
+            if (index !== -1)
+                activeModalStack.splice(index, 1);
+        };
+    }, [isModalActive]);
+    // Escape closes; Tab cycles inside the modal. Both only for the topmost one.
+    React.useEffect(() => {
+        if (!isModalActive)
+            return undefined;
+        const handleKeyDown = (e) => {
+            const node = modalRootRef.current;
+            if (activeModalStack[activeModalStack.length - 1] !== stackTokenRef.current) {
+                return;
+            }
+            if (e.key === 'Escape') {
+                if (closeOnEscape)
+                    onClose?.();
+                return;
+            }
+            if (e.key !== 'Tab' || !node)
+                return;
+            // Keep Tab within the modal — `aria-modal` hides the rest of the page
+            // from assistive technology, so the keyboard order has to agree.
+            const focusable = getTabbable(node);
+            const activeElement = document.activeElement;
+            if (focusable.length === 0) {
+                e.preventDefault();
+                node.focus();
+                return;
+            }
+            const first = focusable[0];
+            const last = focusable[focusable.length - 1];
+            const outside = !node.contains(activeElement);
+            if (e.shiftKey) {
+                if (outside || activeElement === first) {
+                    e.preventDefault();
+                    last.focus();
+                }
+            }
+            else if (outside || activeElement === last) {
+                e.preventDefault();
+                first.focus();
+            }
+        };
+        document.addEventListener('keydown', handleKeyDown);
+        return () => document.removeEventListener('keydown', handleKeyDown);
+    }, [isModalActive, closeOnEscape, onClose]);
+    // Move focus into the modal on open, restore it on close
+    React.useEffect(() => {
+        if (!isModalActive)
+            return undefined;
+        previouslyFocusedRef.current = document.activeElement;
+        const node = modalRootRef.current;
+        const focusable = node ? getTabbable(node)[0] : undefined;
+        (focusable ?? node)?.focus();
+        return () => {
+            // Only hand focus back if this modal still owns it: closing a background
+            // modal must not pull focus out of one that is still open on top. A
+            // removed subtree leaves focus on <body>, which still counts as ours.
+            const activeElement = document.activeElement;
+            if (activeElement &&
+                activeElement !== document.body &&
+                !node?.contains(activeElement)) {
+                return;
+            }
+            previouslyFocusedRef.current?.focus?.();
+        };
+        // `isPortaled` flips once when a hydrated portal modal moves out of the
+        // inline tree; re-running rebinds focus onto the remounted nodes. The
+        // cleanup above restores focus to the pre-open element first (the detached
+        // subtree has left focus on <body>), so the re-run re-records the same
+        // element and restore-on-close still lands in the right place.
+    }, [isModalActive, isPortaled]);
     // Check if children contain compound components
     const hasCompoundComponents = React.Children.toArray(children).some(child => React.isValidElement(child) &&
         (child.type === ModalBackground ||
@@ -2259,20 +2517,35 @@ const ModalRoot = ({ active, isActive, onClose, className, textColor, bgColor, m
     });
     const deleteClass = usePrefixedClassNames('delete');
     const modalClasses = classNames(bulmaClasses, bulmaHelperClasses, className);
+    const resolvedRole = role ?? (isModalActive ? 'dialog' : undefined);
+    const resolvedAriaModal = ariaModalProp ??
+        (isModalActive && resolvedRole !== 'presentation' ? 'true' : undefined);
+    // A dialog needs an accessible name: the legacy card title is wired up
+    // automatically, compound users pass their own aria-label/aria-labelledby
+    // (both arrive in `rest`, which is spread last and so wins).
+    const titleId = modalCardTitle ? generatedTitleId : undefined;
+    let modalElement;
     // If using compound components, render children as-is
     if (hasCompoundComponents) {
-        return (jsxRuntime.jsx("div", { className: modalClasses, ...rest, "data-testid": "modal", children: children }));
-    }
-    // Legacy API: EXPLICIT type wins; fallback to auto detection if not provided
-    let isModalCard;
-    if (type === 'card')
-        isModalCard = true;
-    else if (type === 'content')
-        isModalCard = false;
-    else
-        isModalCard = !!modalCardTitle || !!modalCardFoot;
-    return (jsxRuntime.jsxs("div", { className: modalClasses, ...rest, "data-testid": "modal", children: [jsxRuntime.jsx("div", { className: prefixedClassNames(classPrefix, 'modal-background'), onClick: onClose, "data-testid": "modal-background" }), isModalCard ? (jsxRuntime.jsxs("div", { className: prefixedClassNames(classPrefix, 'modal-card'), children: [modalCardTitle && (jsxRuntime.jsxs("header", { className: prefixedClassNames(classPrefix, 'modal-card-head'), children: [jsxRuntime.jsx("p", { className: prefixedClassNames(classPrefix, 'modal-card-title'), children: modalCardTitle }), onClose && (jsxRuntime.jsx("button", { className: deleteClass, "aria-label": "close", onClick: onClose, type: "button", "data-testid": "modal-close" }))] })), jsxRuntime.jsx("section", { className: prefixedClassNames(classPrefix, 'modal-card-body'), "data-testid": "modal-body", children: children }), modalCardFoot && (jsxRuntime.jsx("footer", { className: prefixedClassNames(classPrefix, 'modal-card-foot'), children: modalCardFoot }))] })) : (jsxRuntime.jsx("div", { className: prefixedClassNames(classPrefix, 'modal-content'), "data-testid": "modal-content", children: children })), (!isModalCard || (!modalCardTitle && onClose)) && onClose && (jsxRuntime.jsx("button", { className: prefixedClassNames(classPrefix, 'modal-close', 'is-large'), "aria-label": "close", onClick: onClose, type: "button", "data-testid": "modal-close-float" }))] }));
-};
+        modalElement = (jsxRuntime.jsx("div", { className: modalClasses, ref: combinedRef, role: resolvedRole, "aria-modal": resolvedAriaModal, tabIndex: -1, ...rest, "data-testid": "modal", children: children }));
+    }
+    else {
+        // Legacy API: EXPLICIT type wins; fallback to auto detection if not provided
+        let isModalCard;
+        if (type === 'card')
+            isModalCard = true;
+        else if (type === 'content')
+            isModalCard = false;
+        else
+            isModalCard = !!modalCardTitle || !!modalCardFoot;
+        modalElement = (jsxRuntime.jsxs("div", { className: modalClasses, ref: combinedRef, role: resolvedRole, "aria-modal": resolvedAriaModal, "aria-labelledby": titleId, tabIndex: -1, ...rest, "data-testid": "modal", children: [jsxRuntime.jsx("div", { className: prefixedClassNames(classPrefix, 'modal-background'), onClick: onClose, "data-testid": "modal-background" }), isModalCard ? (jsxRuntime.jsxs("div", { className: prefixedClassNames(classPrefix, 'modal-card'), children: [modalCardTitle && (jsxRuntime.jsxs("header", { className: prefixedClassNames(classPrefix, 'modal-card-head'), children: [jsxRuntime.jsx("p", { id: titleId, className: prefixedClassNames(classPrefix, 'modal-card-title'), children: modalCardTitle }), onClose && (jsxRuntime.jsx("button", { className: deleteClass, "aria-label": "close", onClick: onClose, type: "button", "data-testid": "modal-close" }))] })), jsxRuntime.jsx("section", { className: prefixedClassNames(classPrefix, 'modal-card-body'), "data-testid": "modal-body", children: children }), modalCardFoot && (jsxRuntime.jsx("footer", { className: prefixedClassNames(classPrefix, 'modal-card-foot'), children: modalCardFoot }))] })) : (jsxRuntime.jsx("div", { className: prefixedClassNames(classPrefix, 'modal-content'), "data-testid": "modal-content", children: children })), (!isModalCard || (!modalCardTitle && onClose)) && onClose && (jsxRuntime.jsx("button", { className: prefixedClassNames(classPrefix, 'modal-close', 'is-large'), "aria-label": "close", onClick: onClose, type: "button", "data-testid": "modal-close-float" }))] }));
+    }
+    if (isPortaled) {
+        const target = resolvePortalContainer(typeof portal === 'boolean' ? undefined : portal);
+        return reactDom.createPortal(modalElement, target);
+    }
+    return modalElement;
+});
 const Modal = withSubComponents(ModalRoot, {
     Background: ModalBackground,
     Content: ModalContent,
@@ -2286,10 +2559,11 @@ const NavbarDropdownContext = React.createContext(null);
  *
  * @function
  * @param {NavbarProps} props - Props for the Navbar component.
+ * @param {React.Ref<HTMLElement>} ref - Forwarded ref to the root `<nav>` element.
  * @returns {JSX.Element} The rendered navbar.
  * @see {@link https://bulma.io/documentation/components/navbar/ | Bulma Navbar documentation}
  */
-const NavbarComponent = ({ className, textColor, bgColor, color, transparent, fixed, children, ...props }) => {
+const NavbarComponent = React.forwardRef(function NavbarComponent({ className, textColor, bgColor, color, transparent, fixed, children, ...props }, ref) {
     const { bulmaHelperClasses, rest } = useBulmaClasses({
         color: textColor,
         backgroundColor: bgColor,
@@ -2302,8 +2576,8 @@ const NavbarComponent = ({ className, textColor, bgColor, color, transparent, fi
         [`is-fixed-${fixed}`]: fixed,
     });
     const navbarClasses = classNames(bulmaClasses, bulmaHelperClasses, className);
-    return (jsxRuntime.jsx("nav", { className: navbarClasses, role: "navigation", "aria-label": "main navigation", ...rest, children: children }));
-};
+    return (jsxRuntime.jsx("nav", { ref: ref, className: navbarClasses, role: "navigation", "aria-label": "main navigation", ...rest, children: children }));
+});
 /**
  * For logo and branding (left side)
  *
@@ -2340,16 +2614,18 @@ const NavbarItem = ({ className, as: Component = 'a', active, textColor, bgColor
  *
  * @function
  * @param {NavbarBurgerProps} props - Props for the NavbarBurger component.
+ * @param {React.Ref<HTMLButtonElement>} ref - Forwarded ref to the burger button element.
  * @returns {JSX.Element} The rendered burger.
  */
-const NavbarBurger = ({ className, active, children, ...props }) => {
+const NavbarBurger = React.forwardRef(function NavbarBurger({ className, active, children, ...props }, ref) {
     const { bulmaHelperClasses, rest } = useBulmaClasses({
         ...props,
     });
-    return (jsxRuntime.jsxs("button", { type: "button", className: classNames(usePrefixedClassNames('navbar-burger', {
+    return (jsxRuntime.jsxs("button", { ref: ref, type: "button", className: classNames(usePrefixedClassNames('navbar-burger', {
             'is-active': active,
         }), bulmaHelperClasses, className), "aria-label": props['aria-label'] || 'menu', "aria-expanded": props['aria-expanded'] ?? !!active, ...rest, children: [jsxRuntime.jsx("span", { "aria-hidden": "true" }), jsxRuntime.jsx("span", { "aria-hidden": "true" }), jsxRuntime.jsx("span", { "aria-hidden": "true" }), children] }));
-};
+});
+NavbarBurger.displayName = 'NavbarBurger';
 /**
  * Collapsible content (contains `Navbar.Start` and `Navbar.End`)
  *
@@ -2396,9 +2672,10 @@ const NavbarEnd = ({ className, children, ...props }) => {
  *
  * @function
  * @param {NavbarLinkProps} props - Props for the NavbarLink component.
+ * @param {React.Ref<HTMLAnchorElement | HTMLButtonElement>} ref - Forwarded ref to the rendered link or button element.
  * @returns {JSX.Element} The rendered navbar link.
  */
-const NavbarLink = ({ className, as: Component = 'a', arrowless, textColor, bgColor, children, ...props }) => {
+const NavbarLink = React.forwardRef(function NavbarLink({ className, as: Component = 'a', arrowless, textColor, bgColor, children, ...props }, ref) {
     const { bulmaHelperClasses, rest } = useBulmaClasses({
         color: textColor,
         backgroundColor: bgColor,
@@ -2431,7 +2708,7 @@ const NavbarLink = ({ className, as: Component = 'a', arrowless, textColor, bgCo
             return;
         dropdownContext.toggle();
     };
-    return (jsxRuntime.jsx(Component, { className: classNames(usePrefixedClassNames('navbar-link', {
+    return (jsxRuntime.jsx(Component, { ref: ref, className: classNames(usePrefixedClassNames('navbar-link', {
             'is-arrowless': arrowless,
         }), bulmaHelperClasses, className), ...rest, ...(dropdownContext && {
             'aria-haspopup': 'true',
@@ -2443,15 +2720,17 @@ const NavbarLink = ({ className, as: Component = 'a', arrowless, textColor, bgCo
                 onClick: handleClick,
             }),
         }), children: children }));
-};
+});
+NavbarLink.displayName = 'NavbarLink';
 /**
  * Dropdown parent (with options for hover, up, right, active)
  *
  * @function
  * @param {NavbarDropdownProps} props - Props for the NavbarDropdown component.
+ * @param {React.Ref<HTMLDivElement>} ref - Forwarded ref to the dropdown container element.
  * @returns {JSX.Element} The rendered dropdown.
  */
-const NavbarDropdown = ({ className, right, up, hoverable, active: activeProp, onActiveChange, children, ...props }) => {
+const NavbarDropdown = React.forwardRef(function NavbarDropdown({ className, right, up, hoverable, active: activeProp, onActiveChange, children, ...props }, ref) {
     const [active, setActive] = React.useState(!!activeProp);
     React.useEffect(() => {
         // eslint-disable-next-line react-hooks/set-state-in-effect -- syncing to controlled prop
@@ -2472,13 +2751,14 @@ const NavbarDropdown = ({ className, right, up, hoverable, active: activeProp, o
         setActive(false);
         onActiveChange?.(false);
     };
-    return (jsxRuntime.jsx(NavbarDropdownContext.Provider, { value: { active, toggle, close }, children: jsxRuntime.jsx("div", { className: classNames(usePrefixedClassNames('navbar-item', 'has-dropdown', {
+    return (jsxRuntime.jsx(NavbarDropdownContext.Provider, { value: { active, toggle, close }, children: jsxRuntime.jsx("div", { ref: ref, className: classNames(usePrefixedClassNames('navbar-item', 'has-dropdown', {
                 'has-dropdown-up': up,
                 'is-right': right,
                 'is-hoverable': hoverable,
                 'is-active': active,
             }), className), ...props, children: children }) }));
-};
+});
+NavbarDropdown.displayName = 'NavbarDropdown';
 /**
  * Dropdown menu container
  *
@@ -2788,8 +3068,37 @@ function getIconClasses(library, name, variant, features) {
 const Icon = ({ className, textColor, bgColor, name, library, variant, features, libraryFeatures, // Deprecated but maintained for backward compatibility
 size, ariaLabel = 'icon', style, icon, // Capture and exclude the deprecated 'icon' prop from DOM
 color: _color, // Exclude 'color' prop if passed directly
-containerClassName, ...restProps }) => {
-    // Handle deprecated 'icon' prop - parse it to extract the actual name
+containerClassName, children, ...restProps }) => {
+    // Get the default icon library from context, fallback to 'fa' if not set
+    const defaultLibrary = useIconLibrary();
+    /**
+     * Generates Bulma helper classes and separates out remaining props.
+     * Note: variant, features, and libraryFeatures are excluded from props spread
+     */
+    const { bulmaHelperClasses, rest } = useBulmaClasses({
+        color: textColor,
+        backgroundColor: bgColor,
+        ...restProps,
+    });
+    // Hoisted unconditionally to respect rules-of-hooks; the branches below
+    // pick which result to consume.
+    const defaultIconClasses = usePrefixedClassNames('icon', {
+        [`is-${size}`]: size,
+    });
+    const sizeModifierClass = usePrefixedClassNames(size ? `is-${size}` : undefined);
+    const bulmaClasses = containerClassName
+        ? containerClassName
+        : defaultIconClasses;
+    const iconContainerClasses = classNames(bulmaClasses, containerClassName && size ? sizeModifierClass : undefined, bulmaHelperClasses, className);
+    if (children !== undefined) {
+        // `IconChildrenProps`: render the caller's node (an inline SVG, a `react-icons`
+        // component, …) in place of a class-based glyph. Library/variant/features don't apply.
+        return (jsxRuntime.jsx("span", { className: iconContainerClasses, "aria-label": ariaLabel, style: style, ...rest, children: children }));
+    }
+    // `name` is guaranteed once `children` is absent (`IconProps` is a discriminated union of
+    // the two, and `IconChildrenProps['children']` excludes `undefined` so `children={undefined}`
+    // can't slip past into this branch) — the cast only matters for legacy callers that bypass
+    // the type and rely solely on the deprecated `icon` prop below.
     let finalName = name;
     if (!name && icon) {
         // If icon prop is provided instead of name, try to parse it
@@ -2808,31 +3117,16 @@ containerClassName, ...restProps }) => {
             }
         }
     }
-    // Get the default icon library from context, fallback to 'fa' if not set
-    const defaultLibrary = useIconLibrary();
     const finalLibrary = library || defaultLibrary || 'fa';
     // Normalize a redundant leading library prefix (e.g. "fa-check" -> "check" when the
     // library is 'fa'), so `name` behaves identically with or without the prefix.
     finalName = stripRedundantLibraryPrefix(finalName, finalLibrary);
-    /**
-     * Generates Bulma helper classes and separates out remaining props.
-     * Note: variant, features, and libraryFeatures are excluded from props spread
-     */
-    const { bulmaHelperClasses, rest } = useBulmaClasses({
-        color: textColor,
-        backgroundColor: bgColor,
-        ...restProps,
-    });
-    // Hoisted unconditionally to respect rules-of-hooks; the ternaries below
-    // pick which result to consume.
-    const defaultIconClasses = usePrefixedClassNames('icon', {
-        [`is-${size}`]: size,
-    });
-    const sizeModifierClass = usePrefixedClassNames(size ? `is-${size}` : undefined);
-    const bulmaClasses = containerClassName
-        ? containerClassName
-        : defaultIconClasses;
-    const iconContainerClasses = classNames(bulmaClasses, containerClassName && size ? sizeModifierClass : undefined, bulmaHelperClasses, className);
+    if (!finalName) {
+        // No glyph to name. Unreachable through the public type, but a plain-JS caller (or one
+        // that casts) can land here, and building a class off an absent name produced a bogus
+        // `fa-undefined` glyph. Render the bare container instead, matching the `children` branch.
+        return (jsxRuntime.jsx("span", { className: iconContainerClasses, "aria-label": ariaLabel, style: style, ...rest }));
+    }
     // Backward compatibility: if libraryFeatures is provided, parse it for variant and features
     let finalVariant = variant;
     let finalFeatures = features;
@@ -2951,8 +3245,9 @@ const PanelTabs = ({ className, children, ...props }) => (jsxRuntime.jsx("p", {
  */
 const PanelBlock = ({ className, active, children, ...props }) => (jsxRuntime.jsx("a", { className: classNames(usePrefixedClassNames('panel-block', { 'is-active': active }), className), ...props, children: children }));
 /**
- * Icon wrapper with panel styling (renders as `<span class="panel-icon"><i/></span>`).
- * Accepts all Icon props (`name`, `variant`, `features`, etc.)
+ * 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`).
+ * Accepts all Icon props (`name`, `variant`, `features`, etc.), or `children` for a custom node.
  *
  * @function
  * @param {PanelIconProps} props - Props for the PanelIcon component.
@@ -3233,16 +3528,10 @@ const Loading = ({ active = false, isFullPage = false, size, color, canCancel =
         document.addEventListener('keydown', handleKeyDown);
         return () => document.removeEventListener('keydown', handleKeyDown);
     }, [active, canCancel, onCancel]);
-    // Prevent body scroll when full page loading is active
-    React.useEffect(() => {
-        if (isFullPage && active) {
-            document.body.style.overflow = 'hidden';
-            return () => {
-                document.body.style.overflow = '';
-            };
-        }
-        return undefined;
-    }, [isFullPage, active]);
+    // Prevent body scroll when full page loading is active. Ref-counted through
+    // the shared helper so an overlapping Modal/Dialog/Sidebar doesn't have its
+    // lock cleared when this one releases.
+    useScrollLock(isFullPage && active);
     if (!active) {
         return null;
     }
@@ -3733,6 +4022,8 @@ const Steps = withSubComponents(StepsComponent, { Step }, 'Steps');
 const SidebarComponent = React.forwardRef(({ isOpen, onClose, position = 'left', width = '260px', isFullwidth, fullWidth, overlay = true, overlayClose = true, escapeClose = true, canCancel = true, children, inline = false, className, style, ...props }, ref) => {
     const { bulmaHelperClasses, rest } = useBulmaClasses(props);
     const sidebarRef = React.useRef(null);
+    // Cleanup returned by a consumer's callback ref on attach, held until detach.
+    const consumerCleanupRef = React.useRef(null);
     const resolvedFullwidth = isFullwidth ?? fullWidth ?? false;
     // Close handler
     const handleClose = React.useCallback(() => {
@@ -3758,17 +4049,9 @@ const SidebarComponent = React.forwardRef(({ isOpen, onClose, position = 'left',
         document.addEventListener('keydown', handleKeyDown);
         return () => document.removeEventListener('keydown', handleKeyDown);
     }, [isOpen, escapeClose, handleClose]);
-    // Prevent body scroll when sidebar is open
-    React.useEffect(() => {
-        if (isOpen && overlay) {
-            const originalOverflow = document.body.style.overflow;
-            document.body.style.overflow = 'hidden';
-            return () => {
-                document.body.style.overflow = originalOverflow;
-            };
-        }
-        return undefined;
-    }, [isOpen, overlay]);
+    // Prevent body scroll when sidebar is open. Ref-counted through the shared
+    // helper so an overlapping Modal/Dialog/Loading doesn't unlock underneath.
+    useScrollLock(isOpen && overlay);
     // Focus trap (basic - focus sidebar when opened)
     React.useEffect(() => {
         if (isOpen) {
@@ -3790,7 +4073,28 @@ const SidebarComponent = React.forwardRef(({ isOpen, onClose, position = 'left',
         sidebarRef.current =
             node;
         if (typeof ref === 'function') {
-            ref(node);
+            // React 19 lets a callback ref return a cleanup function and detaches by
+            // running it instead of calling the ref with `null`; React 18 discards the
+            // return value entirely. Returning it from here would be a React-19-only
+            // contract, so we hold the cleanup and run it ourselves on detach — the
+            // same shape as `Dropdown`, `Modal`, `Dialog`, `Toast` and `Carousel`.
+            // The form controls that merge a forwarded ref still discard the cleanup
+            // and detach with `ref(null)`, so this is not yet library-wide — grep
+            // `typeof ref === 'function'` for the current split.
+            if (node === null) {
+                const consumerCleanup = consumerCleanupRef.current;
+                consumerCleanupRef.current = null;
+                if (consumerCleanup) {
+                    consumerCleanup();
+                }
+                else {
+                    ref(null);
+                }
+                return;
+            }
+            const cleanup = ref(node);
+            consumerCleanupRef.current =
+                typeof cleanup === 'function' ? cleanup : null;
         }
         else if (ref) {
             ref.current = node;
@@ -3907,6 +4211,8 @@ const Toast = React.forwardRef(({ message, type = 'default', actionType, positio
     const [isVisible, setIsVisible] = React.useState(true);
     const [isPaused, setIsPaused] = React.useState(false);
     const toastRef = React.useRef(null);
+    // Cleanup returned by a consumer's callback ref on attach, held until detach.
+    const consumerCleanupRef = React.useRef(null);
     const handleClose = React.useCallback(() => {
         setIsVisible(false);
         onClose?.();
@@ -3977,27 +4283,41 @@ const Toast = React.forwardRef(({ message, type = 'default', actionType, positio
     const toastActionClass = usePrefixedClassNames('toast-action');
     const toastButtonClass = usePrefixedClassNames('button');
     const toastCloseClass = usePrefixedClassNames('delete', 'is-small');
-    if (!isVisible) {
-        return null;
-    }
-    const resolveContainer = () => {
-        if (container) {
-            if (typeof container === 'string') {
-                return (document.querySelector(container) || document.body);
-            }
-            return container;
-        }
-        return document.body;
-    };
-    const setRef = (node) => {
+    const setRef = React.useCallback((node) => {
         toastRef.current = node;
         if (typeof ref === 'function') {
-            ref(node);
+            // React 19 lets a callback ref return a cleanup function and detaches by
+            // running it instead of calling the ref with `null`; React 18 discards the
+            // return value entirely. Returning it from here would be a React-19-only
+            // contract, so we hold the cleanup and run it ourselves on detach — the
+            // same shape as `Dropdown`, `Modal`, `Dialog`, `Sidebar` and `Carousel`.
+            // The form controls that merge a forwarded ref still discard the cleanup
+            // and detach with `ref(null)`, so this is not yet library-wide — grep
+            // `typeof ref === 'function'` for the current split. Memoized because an
+            // unstable ref identity makes React detach and re-attach on every render,
+            // which would run that cleanup each time.
+            if (node === null) {
+                const consumerCleanup = consumerCleanupRef.current;
+                consumerCleanupRef.current = null;
+                if (consumerCleanup) {
+                    consumerCleanup();
+                }
+                else {
+                    ref(null);
+                }
+                return;
+            }
+            const cleanup = ref(node);
+            consumerCleanupRef.current =
+                typeof cleanup === 'function' ? cleanup : null;
         }
         else if (ref) {
             ref.current = node;
         }
-    };
+    }, [ref]);
+    if (!isVisible) {
+        return null;
+    }
     const toastElement = (jsxRuntime.jsxs("div", { ref: setRef, className: combinedClasses, role: "alert", "aria-live": type === 'danger' || type === 'warning' ? 'assertive' : 'polite', onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, onClick: dismissible ? handleClose : undefined, ...rest, children: [jsxRuntime.jsx("span", { className: toastMessageClass, children: message }), (cancelText || actionText) && (jsxRuntime.jsxs("div", { className: toastActionsClass, children: [cancelText && (jsxRuntime.jsx("span", { className: toastCancelClass, children: jsxRuntime.jsx("button", { type: "button", className: toastButtonClass, onClick: e => {
                                 e.stopPropagation();
                                 handleClose();
@@ -4013,7 +4333,7 @@ const Toast = React.forwardRef(({ message, type = 'default', actionType, positio
     }
     const toastContent = jsxRuntime.jsx("div", { className: containerClasses, children: toastElement });
     if (typeof document !== 'undefined') {
-        return reactDom.createPortal(toastContent, resolveContainer());
+        return reactDom.createPortal(toastContent, resolvePortalContainer(container));
     }
     return null;
 });
@@ -4153,9 +4473,6 @@ const ToastContainer = ({ position = 'top-right', }) => {
         }) }), document.body);
 };
 
-// Ref-counted body scroll lock for chained/overlapping dialogs
-let _scrollLockCount = 0;
-let _originalOverflow = '';
 /**
  * The `Dialog` component provides ready-made confirm and alert dialogs, so a destructive action stays one `await dialog.confirm()` call away.
  *
@@ -4187,9 +4504,11 @@ let _originalOverflow = '';
  *   onCancel={() => setShowConfirm(false)}
  * />
  */
-const Dialog = React.forwardRef(({ isOpen, title, message, type = 'default', confirmText = 'OK', cancelText = 'Cancel', onConfirm, onCancel, showCancel = true, canCancel = true, focusCancel = false, icon, className, ...props }, ref) => {
+const Dialog = React.forwardRef(({ isOpen, title, message, type = 'default', confirmText = 'OK', cancelText = 'Cancel', onConfirm, onCancel, showCancel = true, canCancel = true, focusCancel = false, icon, portal, className, ...props }, ref) => {
     const { bulmaHelperClasses, rest } = useBulmaClasses(props);
     const dialogRef = React.useRef(null);
+    // Cleanup returned by a consumer's callback ref on attach, held until detach.
+    const consumerCleanupRef = React.useRef(null);
     const confirmRef = React.useRef(null);
     const cancelRef = React.useRef(null);
     // Handle cancel
@@ -4208,48 +4527,47 @@ const Dialog = React.forwardRef(({ isOpen, title, message, type = 'default', con
             handleCancel();
         }
     }, [canCancel, handleCancel]);
-    // Handle escape key
-    React.useEffect(() => {
-        if (!isOpen || !canCancel)
-            return undefined;
-        const handleKeyDown = (e) => {
-            if (e.key === 'Escape') {
-                handleCancel();
-            }
-        };
-        document.addEventListener('keydown', handleKeyDown);
-        return () => document.removeEventListener('keydown', handleKeyDown);
-    }, [isOpen, canCancel, handleCancel]);
-    // Focus management
+    // Moving into the portal remounts the Modal's subtree — these buttons
+    // included — so the focus effect below has to re-run against the new
+    // nodes, exactly as the Modal's own focus effect does.
+    const isHydrated = useIsHydrated();
+    const isPortaled = Boolean(portal) && isHydrated;
+    // Focus management — Dialog picks a specific button rather than the
+    // Modal's default (first focusable/root); this effect runs after the
+    // inner Modal's own focus-on-open effect, so it wins.
     React.useEffect(() => {
         if (isOpen) {
             const buttonToFocus = focusCancel && showCancel ? cancelRef.current : confirmRef.current;
             buttonToFocus?.focus();
         }
-    }, [isOpen, focusCancel, showCancel]);
-    // Prevent body scroll (ref-counted so chained dialogs work correctly)
-    React.useEffect(() => {
-        if (isOpen) {
-            _scrollLockCount++;
-            if (_scrollLockCount === 1) {
-                _originalOverflow = document.body.style.overflow;
-                document.body.style.overflow = 'hidden';
-            }
-            return () => {
-                _scrollLockCount--;
-                if (_scrollLockCount === 0) {
-                    document.body.style.overflow = _originalOverflow;
-                }
-            };
-        }
-        return undefined;
-    }, [isOpen]);
+    }, [isOpen, focusCancel, showCancel, isPortaled]);
     // Use combined ref
     const combinedRef = React.useCallback((node) => {
         dialogRef.current =
             node;
         if (typeof ref === 'function') {
-            ref(node);
+            // React 19 lets a callback ref return a cleanup function and detaches by
+            // running it instead of calling the ref with `null`; React 18 discards the
+            // return value entirely. Returning it from here would be a React-19-only
+            // contract, so we hold the cleanup and run it ourselves on detach — the
+            // same shape as `Dropdown`, `Modal`, `Sidebar`, `Toast` and `Carousel`.
+            // The form controls that merge a forwarded ref still discard the cleanup
+            // and detach with `ref(null)`, so this is not yet library-wide — grep
+            // `typeof ref === 'function'` for the current split.
+            if (node === null) {
+                const consumerCleanup = consumerCleanupRef.current;
+                consumerCleanupRef.current = null;
+                if (consumerCleanup) {
+                    consumerCleanup();
+                }
+                else {
+                    ref(null);
+                }
+                return;
+            }
+            const cleanup = ref(node);
+            consumerCleanupRef.current =
+                typeof cleanup === 'function' ? cleanup : null;
         }
         else if (ref) {
             ref.current = node;
@@ -4292,7 +4610,7 @@ const Dialog = React.forwardRef(({ isOpen, title, message, type = 'default', con
     if (!isOpen) {
         return null;
     }
-    return (jsxRuntime.jsxs(Modal, { isActive: isOpen, children: [jsxRuntime.jsx(Modal.Background, { onClick: handleBackgroundClick }), jsxRuntime.jsxs("div", { ref: combinedRef, className: combinedClasses, role: "alertdialog", "aria-modal": "true", "aria-labelledby": title ? 'dialog-title' : undefined, "aria-describedby": "dialog-message", ...rest, children: [title && (jsxRuntime.jsxs("div", { className: headerClass, children: [displayIcon && jsxRuntime.jsx("span", { className: iconClass, children: displayIcon }), jsxRuntime.jsx("h3", { id: "dialog-title", className: titleClass, children: title })] })), jsxRuntime.jsx("div", { id: "dialog-message", className: bodyClass, children: message }), jsxRuntime.jsxs("div", { className: footerClass, children: [showCancel && (jsxRuntime.jsx("button", { ref: cancelRef, type: "button", className: cancelButtonClass, onClick: handleCancel, children: cancelText })), jsxRuntime.jsx("button", { ref: confirmRef, type: "button", className: confirmButtonClass, onClick: handleConfirm, children: confirmText })] })] })] }));
+    return (jsxRuntime.jsxs(Modal, { isActive: isOpen, onClose: handleCancel, role: "presentation", portal: portal, children: [jsxRuntime.jsx(Modal.Background, { onClick: handleBackgroundClick }), jsxRuntime.jsxs("div", { ref: combinedRef, className: combinedClasses, role: "alertdialog", "aria-modal": "true", "aria-labelledby": title ? 'dialog-title' : undefined, "aria-describedby": "dialog-message", ...rest, children: [title && (jsxRuntime.jsxs("div", { className: headerClass, children: [displayIcon && jsxRuntime.jsx("span", { className: iconClass, children: displayIcon }), jsxRuntime.jsx("h3", { id: "dialog-title", className: titleClass, children: title })] })), jsxRuntime.jsx("div", { id: "dialog-message", className: bodyClass, children: message }), jsxRuntime.jsxs("div", { className: footerClass, children: [showCancel && (jsxRuntime.jsx("button", { ref: cancelRef, type: "button", className: cancelButtonClass, onClick: handleCancel, children: cancelText })), jsxRuntime.jsx("button", { ref: confirmRef, type: "button", className: confirmButtonClass, onClick: handleConfirm, children: confirmText })] })] })] }));
 });
 Dialog.displayName = 'Dialog';
 let dialogListeners = new Set();
@@ -4375,10 +4693,11 @@ const validButtonColors = [...validColors, 'text', 'ghost'];
  *
  * @function
  * @param {ButtonProps} props - Props for the Button component.
+ * @param {React.Ref<HTMLButtonElement | HTMLAnchorElement>} ref - Forwarded ref to the rendered button or anchor element.
  * @returns {JSX.Element} The rendered button or anchor element.
  * @see {@link https://bulma.io/documentation/elements/button/ | Bulma Button documentation}
  */
-const Button = ({ color, size, isLight, isRounded, isLoading, isStatic, isFullwidth, isFullWidth, isOutlined, isInverted, isFocused, isActive, isHovered, isDisabled, className, children, textColor, bgColor, as: Component = 'button', href, onClick, target, rel, ...props }) => {
+const Button = React.forwardRef(function Button({ color, size, isLight, isRounded, isLoading, isStatic, isFullwidth, isFullWidth, isOutlined, isInverted, isFocused, isActive, isHovered, isDisabled, className, children, textColor, bgColor, as: Component = 'button', href, onClick, target, rel, ...props }, ref) {
     const { bulmaHelperClasses, rest } = useBulmaClasses({
         color: textColor,
         backgroundColor: bgColor,
@@ -4408,12 +4727,13 @@ const Button = ({ color, size, isLight, isRounded, isLoading, isStatic, isFullwi
         // native/custom link-like elements (an <a>, a router Link, ...) don't
         // receive button-only HTML attributes.
         const { type: _type, disabled: _disabled, form: _form, formAction: _formAction, formEncType: _formEncType, formMethod: _formMethod, formNoValidate: _formNoValidate, formTarget: _formTarget, name: _name, value: _value, autoFocus: _autoFocus, ...anchorRest } = rest;
-        return (jsxRuntime.jsx(Component, { className: buttonClasses, href: href, target: target, rel: rel, "aria-disabled": isDisabled, tabIndex: isDisabled ? -1 : undefined, onClick: isDisabled
+        return (jsxRuntime.jsx(Component, { ref: ref, className: buttonClasses, href: href, target: target, rel: rel, "aria-disabled": isDisabled, tabIndex: isDisabled ? -1 : undefined, onClick: isDisabled
                 ? (e) => e.preventDefault()
                 : onClick, ...anchorRest, children: children }));
     }
-    return (jsxRuntime.jsx("button", { className: buttonClasses, disabled: isDisabled, onClick: onClick, ...rest, children: children }));
-};
+    return (jsxRuntime.jsx("button", { ref: ref, className: buttonClasses, disabled: isDisabled, onClick: onClick, ...rest, children: children }));
+});
+Button.displayName = 'Button';
 
 /**
  * Individual carousel item/slide.
@@ -4472,6 +4792,8 @@ const DefaultNextIcon = () => (jsxRuntime.jsx("svg", { xmlns: "http://www.w3.org
 const Carousel = React.forwardRef(({ value: controlledValue, autoplay = false, interval = 5000, pauseOnHover = true, repeat = true, hasDrag = true, arrow = true, arrowHover = false, indicator = true, indicatorInside = false, indicatorPosition = 'bottom', indicatorStyle = 'dots', iconPrev, iconNext, iconLibrary, iconVariant, iconSize, iconFeatures, arrowBackground = true, arrowColor, ariaLabel = 'Image carousel', onChange, className, children, ...props }, ref) => {
     const { bulmaHelperClasses, rest } = useBulmaClasses(props);
     const carouselRef = React.useRef(null);
+    // Cleanup returned by a consumer's callback ref on attach, held until detach.
+    const consumerCleanupRef = React.useRef(null);
     const containerRef = React.useRef(null);
     const [internalValue, setInternalValue] = React.useState(0);
     const [isPaused, setIsPaused] = React.useState(false);
@@ -4657,7 +4979,28 @@ const Carousel = React.forwardRef(({ value: controlledValue, autoplay = false, i
         carouselRef.current =
             node;
         if (typeof ref === 'function') {
-            ref(node);
+            // React 19 lets a callback ref return a cleanup function and detaches by
+            // running it instead of calling the ref with `null`; React 18 discards the
+            // return value entirely. Returning it from here would be a React-19-only
+            // contract, so we hold the cleanup and run it ourselves on detach — the
+            // same shape as `Dropdown`, `Modal`, `Dialog`, `Sidebar` and `Toast`.
+            // The form controls that merge a forwarded ref still discard the cleanup
+            // and detach with `ref(null)`, so this is not yet library-wide — grep
+            // `typeof ref === 'function'` for the current split.
+            if (node === null) {
+                const consumerCleanup = consumerCleanupRef.current;
+                consumerCleanupRef.current = null;
+                if (consumerCleanup) {
+                    consumerCleanup();
+                }
+                else {
+                    ref(null);
+                }
+                return;
+            }
+            const cleanup = ref(node);
+            consumerCleanupRef.current =
+                typeof cleanup === 'function' ? cleanup : null;
         }
         else if (ref) {
             ref.current = node;
@@ -4922,6 +5265,7 @@ const Box = ({ className, textColor, color, bgColor, hasShadow = true, children,
  *
  * @function
  * @param {LinkButtonProps} props - Props for the LinkButton component.
+ * @param {React.Ref<HTMLButtonElement | HTMLAnchorElement>} ref - Forwarded ref to the rendered button or anchor element.
  * @returns {JSX.Element} The rendered link-styled button element.
  *
  * @example
@@ -4932,11 +5276,12 @@ const Box = ({ className, textColor, color, bgColor, hasShadow = true, children,
  * // Underline variant with color
  * <LinkButton variant="underline" color="primary">Learn more</LinkButton>
  */
-const LinkButton = ({ variant = 'text', color, className, ...props }) => {
+const LinkButton = React.forwardRef(function LinkButton({ variant = 'text', color, className, ...props }, ref) {
     const buttonColor = variant === 'underline' ? 'text' : variant;
     const prefixedClasses = usePrefixedClassNames('link-button', color && `link-button-${color}`, variant === 'underline' && 'link-button-underline');
-    return (jsxRuntime.jsx(Button, { color: buttonColor, className: classNames(prefixedClasses, className), ...props }));
-};
+    return (jsxRuntime.jsx(Button, { ref: ref, color: buttonColor, className: classNames(prefixedClasses, className), ...props }));
+});
+LinkButton.displayName = 'LinkButton';
 
 const validButtonsSizes = ['small', 'medium', 'large'];
 /**
@@ -5127,6 +5472,16 @@ const Figure = withSubComponents(FigureComponent, {
     Caption: FigureCaption,
 }, 'Figure');
 
+/**
+ * Distinguishes an `IconProps` object from a plain custom node (an inline SVG, a `react-icons`
+ * component, …) passed to a slot that accepts either.
+ */
+function isIconProps$1(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !React.isValidElement(value) &&
+        ('name' in value || 'children' in value));
+}
 /**
  * The `IconText` component provides a Bulma-styled horizontal arrangement of one or more `Icon` components and optional text.
  *
@@ -5146,7 +5501,9 @@ const IconTextComponent = ({ className, textColor, color, bgColor, iconProps, ch
     });
     const bulmaClasses = usePrefixedClassNames('icon-text');
     const iconTextClasses = classNames(bulmaClasses, bulmaHelperClasses, className);
-    return (jsxRuntime.jsx("span", { className: iconTextClasses, ...rest, children: items ? (items.map((item, index) => (jsxRuntime.jsxs(React.Fragment, { children: [jsxRuntime.jsx(Icon, { ...item.iconProps }), item.text && jsxRuntime.jsx("span", { children: item.text })] }, index)))) : (jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [iconProps && jsxRuntime.jsx(Icon, { ...iconProps }), children && jsxRuntime.jsx("span", { children: children })] })) }));
+    return (jsxRuntime.jsx("span", { className: iconTextClasses, ...rest, children: items ? (items.map((item, index) => (jsxRuntime.jsxs(React.Fragment, { children: [item.iconProps &&
+                    (isIconProps$1(item.iconProps) ? (jsxRuntime.jsx(Icon, { ...item.iconProps })) : (jsxRuntime.jsx(Icon, { children: item.iconProps }))), item.text && jsxRuntime.jsx("span", { children: item.text })] }, index)))) : (jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [iconProps &&
+                    (isIconProps$1(iconProps) ? (jsxRuntime.jsx(Icon, { ...iconProps })) : (jsxRuntime.jsx(Icon, { children: iconProps }))), children && jsxRuntime.jsx("span", { children: children })] })) }));
 };
 const IconText = withSubComponents(IconTextComponent, { Icon }, 'IconText');
 
@@ -6057,6 +6414,16 @@ const Checkbox = React.forwardRef(({ color, size, className, children, textColor
 });
 Checkbox.displayName = 'Checkbox';
 
+/**
+ * Distinguishes an `IconProps` object from a plain custom node (an inline SVG, a `react-icons`
+ * component, …) passed to a slot that accepts either.
+ */
+function isIconProps(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !React.isValidElement(value) &&
+        ('name' in value || 'children' in value));
+}
 const allowedColors = [...validColors, 'inherit', 'current'];
 /**
  * The `Control` component is a Bulma-styled wrapper for form controls (`Input`, `Select`, `TextArea`, etc.), supporting icons (left/right), loading state, expansion, size, and Bulma helper props for layout and color.
@@ -6088,15 +6455,19 @@ const Control = React.forwardRef(({ as = 'div', hasIconsLeft, hasIconsRight, isL
         backgroundColor: safeBgColor,
         ...restProps,
     });
-    // Prepare icon props for the shortcut
-    const leftIconProps = iconLeft ||
+    // Prepare icon props for the shortcut. A truthiness test (not `!== undefined`)
+    // so a falsy node from the idiomatic `iconLeft={cond && <Node/>}` / `iconLeft={maybe ?? null}`
+    // pattern counts as "no icon" — otherwise `false`/`null` would reserve the icon column and
+    // mount an empty `.icon` span. A falsy `iconLeft` also correctly falls through to the
+    // `iconLeftName` shortcut, matching the pre-node behavior.
+    const leftIconValue = iconLeft ||
         (iconLeftName
             ? {
                 name: iconLeftName,
                 size: iconLeftSize,
             }
             : undefined);
-    const rightIconProps = iconRight ||
+    const rightIconValue = iconRight ||
         (iconRightName
             ? {
                 name: iconRightName,
@@ -6104,15 +6475,17 @@ const Control = React.forwardRef(({ as = 'div', hasIconsLeft, hasIconsRight, isL
             }
             : undefined);
     const mainClass = usePrefixedClassNames('control', {
-        'has-icons-left': hasIconsLeft || !!leftIconProps,
-        'has-icons-right': hasIconsRight || !!rightIconProps,
+        'has-icons-left': hasIconsLeft || !!leftIconValue,
+        'has-icons-right': hasIconsRight || !!rightIconValue,
         'is-loading': isLoading,
         'is-expanded': isExpanded,
         [`is-${size}`]: !!size,
     });
     const controlClass = classNames(mainClass, bulmaHelperClasses, className);
     // --- FIX: Spread both restProps (for data-testid, etc) AND rest (from useBulmaClasses) ---
-    return (jsxRuntime.jsx(ControlProvider, { value: true, children: jsxRuntime.jsxs(Component, { className: controlClass, ref: ref, ...restProps, ...rest, children: [children, leftIconProps && leftIconProps.name && (jsxRuntime.jsx(Icon, { ...leftIconProps, className: prefixedClassNames(classPrefix, 'is-left') })), rightIconProps && rightIconProps.name && (jsxRuntime.jsx(Icon, { ...rightIconProps, className: prefixedClassNames(classPrefix, 'is-right') }))] }) }));
+    return (jsxRuntime.jsx(ControlProvider, { value: true, children: jsxRuntime.jsxs(Component, { className: controlClass, ref: ref, ...restProps, ...rest, children: [children, leftIconValue &&
+                    (isIconProps(leftIconValue) ? (jsxRuntime.jsx(Icon, { ...leftIconValue, className: prefixedClassNames(classPrefix, 'is-left') })) : (jsxRuntime.jsx(Icon, { className: prefixedClassNames(classPrefix, 'is-left'), children: leftIconValue }))), rightIconValue &&
+                    (isIconProps(rightIconValue) ? (jsxRuntime.jsx(Icon, { ...rightIconValue, className: prefixedClassNames(classPrefix, 'is-right') })) : (jsxRuntime.jsx(Icon, { className: prefixedClassNames(classPrefix, 'is-right'), children: rightIconValue })))] }) }));
 });
 Control.displayName = 'Control';