@allxsmith/bestax-bulma 5.15.0 → 5.15.2

package/dist/index.esm.js

@@ -1,6 +1,6 @@
 /* @allxsmith/bestax-bulma — AI agents: see AGENTS.md in the package root, or https://bestax.io/llms.txt */
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
-import React, { createContext, useContext, useMemo, useState, useRef, useEffect, forwardRef, useCallback, useSyncExternalStore, useId, useLayoutEffect, Children, isValidElement, cloneElement } from 'react';
+import React, { createContext, useContext, useMemo, forwardRef, useState, useRef, useEffect, useCallback, useSyncExternalStore, useId, useLayoutEffect, Children, isValidElement, cloneElement } from 'react';
 import { createPortal } from 'react-dom';
 
 const ConfigContext = createContext({});
@@ -1187,6 +1187,21 @@ const ColumnsComponent = ({ className, textColor, color: _fieldColor, bgColor, i
 };
 const Columns = withSubComponents(ColumnsComponent, { Column }, 'Columns');
 
+/**
+ * Whether an `as` target is a custom element rather than a built-in tag.
+ *
+ * HTML requires a custom element's name to contain a hyphen, and no built-in
+ * element name has one, so this is exact rather than a heuristic. It matters
+ * because a custom element is an intrinsic STRING — `typeof as === 'string'` is
+ * true — while its props are whatever a consumer declared through
+ * `React.JSX.IntrinsicElements`, the way this package declares `<ion-icon>`.
+ * A runtime backstop that filters built-in attributes must leave those alone,
+ * or it strips props the derived type just promised to forward.
+ */
+function isCustomElement(as) {
+    return typeof as === 'string' && as.includes('-');
+}
+
 const avatarColors = [
     'primary',
     'link',
@@ -1255,6 +1270,7 @@ function DefaultAvatarIcon() {
  *
  * @function
  * @param {AvatarProps} props - Props for the Avatar component.
+ * @param {React.Ref} ref - Forwarded ref to the element `as` renders.
  * @returns {JSX.Element} The rendered avatar element.
  *
  * @example
@@ -1262,7 +1278,8 @@ function DefaultAvatarIcon() {
  * @example
  * <Avatar name="Grace Hopper" />
  */
-const Avatar = ({ className, src, alt, name, initials, icon, size, shape = 'circle', color, as, href, target, rel, imageProps, style, ...props }) => {
+const Avatar = forwardRef(function Avatar(avatarProps, ref) {
+    const { className, src, alt, name, initials, icon, size, shape = 'circle', color, as, href, target, rel, imageProps, style, ...props } = avatarProps;
     // Tracks the src that failed to load. A src change clears the latch during
     // render (React's "reset state when props change" pattern) so a previously
     // failed src is retried when switched back to. The img is additionally
@@ -1314,10 +1331,10 @@ const Avatar = ({ className, src, alt, name, initials, icon, size, shape = 'circ
     // decorative (aria-hidden) and it could render nameless.
     const isInteractive = Tag === 'a' ||
         Tag === 'button' ||
-        (typeof Tag !== 'string' && href != null);
+        ((typeof Tag !== 'string' || isCustomElement(Tag)) && href != null);
     // Only forward link attributes when rendering an anchor or a custom (non-DOM)
     // component; a plain `as="div"` must not receive a stray `href`/`target`/`rel`.
-    const isLinkLike = Tag === 'a' || typeof Tag !== 'string';
+    const isLinkLike = Tag === 'a' || typeof Tag !== 'string' || isCustomElement(Tag);
     const linkProps = isLinkLike ? { href, target, rel } : {};
     // alt coalesces with ?? (not ||) so an explicit alt="" survives as the
     // standard decorative marker instead of being overridden by name.
@@ -1340,11 +1357,11 @@ const Avatar = ({ className, src, alt, name, initials, icon, size, shape = 'circ
     // A clickable avatar inside a form must not submit it; default the native
     // button type (an explicit type passed through rest still wins).
     const buttonTypeProps = Tag === 'button' ? { type: 'button' } : {};
-    return (jsxs(Tag, { className: combinedClasses, style: { ...sizeStyle, ...style }, ...buttonTypeProps, ...linkProps, ...a11yProps, ...rest, children: [showImage && (jsx("img", { ...imageProps, ref: imgRef, src: src, alt: accessibleName ?? '', onError: e => {
+    return (jsxs(Tag, { ref: ref, className: combinedClasses, style: { ...sizeStyle, ...style }, ...buttonTypeProps, ...linkProps, ...a11yProps, ...rest, children: [showImage && (jsx("img", { ...imageProps, ref: imgRef, src: src, alt: accessibleName ?? '', onError: e => {
                     imageProps?.onError?.(e);
                     setErroredSrc(src);
                 } }, src)), showInitials && (jsx("span", { className: initialsClass, children: resolvedInitials })), showIcon && icon, showDefaultIcon && jsx(DefaultAvatarIcon, {})] }));
-};
+});
 Avatar.displayName = 'Avatar';
 
 /**
@@ -1983,6 +2000,33 @@ const DropdownComponent = forwardRef(function DropdownComponent({ label, childre
     const dropdownClasses = classNames(bulmaClasses, bulmaHelperClasses, className);
     return (jsxs("div", { className: dropdownClasses, ref: setRefs, id: id, "data-testid": "dropdown-root", ...rest, children: [jsx("div", { className: usePrefixedClassNames('dropdown-trigger'), children: 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: [jsx("span", { children: label }), jsx("span", { className: usePrefixedClassNames('icon', 'is-small'), "aria-hidden": "true", children: jsx("i", { className: "fas fa-angle-down" }) })] }) }), jsx("div", { className: classNames(usePrefixedClassNames('dropdown-menu'), menuClassName), id: id ? `${id}-menu` : undefined, role: "menu", "data-testid": "dropdown-menu", onKeyDown: handleMenuKeyDown, children: jsx("div", { className: usePrefixedClassNames('dropdown-content'), onClick: handleMenuClick, tabIndex: -1, children: children }) })] }));
 });
+/**
+ * The anchor-only attributes, withheld from a `<div>` or a `<button>`.
+ *
+ * Mirrors `LINK_ATTRS` in `bestax-migrate/src/sources/_shared/polymorphic.ts`,
+ * which drops the same set when a migration lands one on a non-anchor. `rel` is
+ * absent from both on purpose: React declares it on `HTMLAttributes<T>` — every
+ * element — so withholding it would diverge from React's own typing, the same
+ * call #641 recorded for `Navbar.Link`.
+ */
+const LINK_ONLY_ATTRS = [
+    'href',
+    'target',
+    'download',
+    'hrefLang',
+    'ping',
+    'referrerPolicy',
+    'media',
+];
+/** `props` without any attribute only an anchor can carry. */
+function omitLinkAttrs(props) {
+    const out = {};
+    for (const [key, value] of Object.entries(props)) {
+        if (!LINK_ONLY_ATTRS.includes(key))
+            out[key] = value;
+    }
+    return out;
+}
 /**
  * Bulma Dropdown item.
  *
@@ -1990,12 +2034,34 @@ const DropdownComponent = forwardRef(function DropdownComponent({ label, childre
  * @param {DropdownItemProps} props - Props for the DropdownItem component.
  * @returns {JSX.Element} The rendered dropdown item.
  */
-const DropdownItem = ({ children, active, className, as: Component = 'a', ...props }) => {
+const DropdownItem = ((itemProps) => {
+    const { children, active, className, as: Component = 'a', ...props } = itemProps;
     const { bulmaHelperClasses, rest } = useBulmaClasses(props);
+    // The anchor's attributes reach an anchor and nothing else — `<div href>` and
+    // `<button target>` are invalid HTML. The same rule Menu applies, for the same
+    // reason: the type now derives these from `as`, and deriving them must not
+    // quietly widen where they land. The type stops a direct caller; this stops a
+    // plain-JS one, a loose `{...props}` spread, and the genericity a wrapping HOC
+    // erases.
+    //
+    // The whole link set, not `href` alone. Menu strips only `href` because its
+    // props never gained the rest; here they all arrive together under `as="a"`,
+    // and `bestax-migrate` already removes exactly this set (`LINK_ATTRS`) when it
+    // migrates onto a non-anchor — so stripping less would leave the codemod
+    // stricter than the component it migrates to.
+    //
+    // Menu's condition also admits a custom component and a custom element, which
+    // own their prop contracts. `as` is closed to three intrinsic tags here, so
+    // neither can arrive and the anchor test is the whole rule.
+    const forwarded = Component === 'a' ? rest : omitLinkAttrs(rest);
     return (jsx(Component, { className: classNames(usePrefixedClassNames('dropdown-item', {
             'is-active': active,
-        }), bulmaHelperClasses, className), tabIndex: 0, role: "menuitem", "data-testid": "dropdown-item", ...rest, children: children }));
-};
+        }), bulmaHelperClasses, className), tabIndex: 0, role: "menuitem", "data-testid": "dropdown-item", ...forwarded, ...(Component === 'button'
+            ? {
+                type: forwarded.type ?? 'button',
+            }
+            : {}), children: children }));
+});
 /**
  * Bulma Dropdown divider.
  *
@@ -2057,13 +2123,23 @@ const MenuList = ({ className, children, ...props }) => {
  *
  * @function
  * @param {MenuItemProps} props - Props for the MenuItem component.
+ * @param {React.Ref} ref - Forwarded ref to the inner element `as` renders.
  * @returns {JSX.Element} The rendered menu item.
  */
-const MenuItem = ({ className, children, active, href, as: Component = 'a', 'data-testid': testId, ...rest }) => {
-    const { bulmaHelperClasses, rest: bulmaRest } = useBulmaClasses(rest);
+const MenuItem = forwardRef(function MenuItem(itemProps, ref) {
+    const { className, children, active, as: Component = 'a', 'data-testid': testId, style, id, title, role, tabIndex, ...rest } = itemProps;
+    const { bulmaHelperClasses, rest: forwarded } = useBulmaClasses(rest);
+    // `href` reaches an anchor or a custom component (which owns its own prop
+    // contract), but not another intrinsic tag — `<span href>` is invalid HTML.
+    // The same rule Avatar applies through `isLinkLike` and Button through its
+    // intrinsic-only strip. Before #641 `href` was an own prop re-applied only
+    // for `as="a"`; deriving it from `as` must not quietly widen that.
+    const isLinkLike = Component === 'a' ||
+        typeof Component !== 'string' ||
+        isCustomElement(Component);
+    const { href: _href, ...withoutHref } = forwarded;
+    const linkProps = isLinkLike ? forwarded : withoutHref;
     const itemClass = classNames({ [usePrefixedClassNames('is-active')]: active }, bulmaHelperClasses);
-    // Standard <li> props
-    const { style, id, title, role, tabIndex, ...linkProps } = bulmaRest;
     // Split children into label and nested MenuList(s)
     const labelChildren = [];
     const nestedMenuLists = [];
@@ -2075,15 +2151,9 @@ const MenuItem = ({ className, children, active, href, as: Component = 'a', 'dat
             labelChildren.push(child);
         }
     });
-    // href/to should go to the link component
-    if (Component === 'a' && href) {
-        linkProps.href = href;
-    }
-    if (Object.prototype.hasOwnProperty.call(rest, 'to')) {
-        linkProps.to = rest.to;
-    }
-    return (jsxs("li", { className: className, "data-testid": testId, style: style, id: id, title: title, role: role, tabIndex: tabIndex, children: [jsx(Component, { className: itemClass, ...linkProps, children: labelChildren }), nestedMenuLists] }));
-};
+    return (jsxs("li", { className: className, "data-testid": testId, style: style, id: id, title: title, role: role, tabIndex: tabIndex, children: [jsx(Component, { ref: ref, className: itemClass, ...linkProps, children: labelChildren }), nestedMenuLists] }));
+});
+MenuItem.displayName = 'MenuItem';
 // Attach static subcomponents
 const Menu = withSubComponents(MenuComponent, {
     Label: MenuLabel,
@@ -2595,18 +2665,21 @@ const NavbarBrand = ({ className, children, textColor, ...props }) => {
  *
  * @function
  * @param {NavbarItemProps} props - Props for the NavbarItem component.
+ * @param {React.Ref} ref - Forwarded ref to the element `as` renders.
  * @returns {JSX.Element} The rendered item.
  */
-const NavbarItem = ({ className, as: Component = 'a', active, textColor, bgColor, children, ...props }) => {
+const NavbarItem = forwardRef(function NavbarItem(itemProps, ref) {
+    const { className, as: Component = 'a', active, textColor, bgColor, children, ...props } = itemProps;
     const { bulmaHelperClasses, rest } = useBulmaClasses({
         color: textColor,
         backgroundColor: bgColor,
         ...props,
     });
-    return (jsx(Component, { className: classNames(usePrefixedClassNames('navbar-item', {
+    return (jsx(Component, { ref: ref, className: classNames(usePrefixedClassNames('navbar-item', {
             'is-active': active,
         }), bulmaHelperClasses, className), ...rest, children: children }));
-};
+});
+NavbarItem.displayName = 'NavbarItem';
 /**
  * Responsive menu toggle (mobile)
  *
@@ -2670,10 +2743,11 @@ 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.
+ * @param {React.Ref} ref - Forwarded ref to the element `as` renders.
  * @returns {JSX.Element} The rendered navbar link.
  */
-const NavbarLink = forwardRef(function NavbarLink({ className, as: Component = 'a', arrowless, textColor, bgColor, children, ...props }, ref) {
+const NavbarLink = forwardRef(function NavbarLink(linkProps, ref) {
+    const { className, as: Component = 'a', arrowless, textColor, bgColor, children, ...props } = linkProps;
     const { bulmaHelperClasses, rest } = useBulmaClasses({
         color: textColor,
         backgroundColor: bgColor,
@@ -2682,8 +2756,16 @@ const NavbarLink = forwardRef(function NavbarLink({ className, as: Component = '
     const dropdownContext = useContext(NavbarDropdownContext);
     const hasHref = rest.href !== undefined;
     const isNativeInteractive = Component === 'button' || hasHref;
+    // Guarded like Button's disabled blocker: these run on whatever `as` renders,
+    // and a custom target's callback need not take a DOM event. One declaring
+    // `onKeyDown: (k: {key: string}) => void` reaches `e.preventDefault()` and
+    // throws. Composing the caller's handler is unconditional; acting on the
+    // event is not ours to do when the payload is foreign.
+    const isDomEvent = (e) => typeof e?.preventDefault === 'function';
     const handleKeyDown = (e) => {
         rest.onKeyDown?.(e);
+        if (!isDomEvent(e))
+            return;
         if (!dropdownContext || e.defaultPrevented)
             return;
         if (e.key === 'Enter' || e.key === ' ') {
@@ -2702,6 +2784,8 @@ const NavbarLink = forwardRef(function NavbarLink({ className, as: Component = '
     // click semantics (navigation / the caller's handler).
     const handleClick = (e) => {
         rest.onClick?.(e);
+        if (!isDomEvent(e))
+            return;
         if (!dropdownContext || isNativeInteractive || e.defaultPrevented)
             return;
         dropdownContext.toggle();
@@ -3093,10 +3177,11 @@ containerClassName, children, ...restProps }) => {
         // component, …) in place of a class-based glyph. Library/variant/features don't apply.
         return (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.
+    // `name` is guaranteed once `children` is absent UNLESS the caller is on the deprecated
+    // `icon` path, which `IconDeprecatedProps` declares with `name?: undefined`.
+    // (`IconChildrenProps['children']` excludes `undefined`, so `children={undefined}` can't
+    // slip past into this branch.) The cast covers that third member, and the `!name && icon`
+    // fallback below is what fills it in.
     let finalName = name;
     if (!name && icon) {
         // If icon prop is provided instead of name, try to parse it
@@ -3120,9 +3205,10 @@ containerClassName, children, ...restProps }) => {
     // library is 'fa'), so `name` behaves identically with or without the prefix.
     finalName = stripRedundantLibraryPrefix(finalName, finalLibrary);
     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.
+        // No glyph to name. Reachable through the public type only as `icon=""`, and otherwise
+        // by a plain-JS caller (or one that casts). Building a class off an absent name produced
+        // a bogus `fa-undefined` glyph; render the bare container instead, matching the
+        // `children` branch.
         return (jsx("span", { className: iconContainerClasses, "aria-label": ariaLabel, style: style, ...rest }));
     }
     // Backward compatibility: if libraryFeatures is provided, parse it for variant and features
@@ -4691,15 +4777,16 @@ 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.
+ * @param {React.Ref} ref - Forwarded ref to the element `as` renders.
+ * @returns {JSX.Element} The rendered button, anchor, or custom element.
  * @see {@link https://bulma.io/documentation/elements/button/ | Bulma Button documentation}
  */
-const Button = 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 Button = forwardRef(function Button(props, ref) {
+    const { 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, ...bulmaProps } = props;
     const { bulmaHelperClasses, rest } = useBulmaClasses({
         color: textColor,
         backgroundColor: bgColor,
-        ...props,
+        ...bulmaProps,
     });
     // Generate Bulma classes with prefix
     const bulmaClasses = usePrefixedClassNames('button', {
@@ -4721,13 +4808,93 @@ const Button = forwardRef(function Button({ color, size, isLight, isRounded, isL
     // Combine prefixed Bulma classes with unprefixed user className and prefixed helper classes
     const buttonClasses = classNames(bulmaClasses, bulmaHelperClasses, className);
     if (Component !== 'button') {
-        // Create anchor-specific props by excluding button-specific ones, so
-        // 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;
+        // Strip the form-control attributes a link-like element cannot carry, so a
+        // JavaScript consumer or a spread object doesn't put them on the DOM. The
+        // types no longer allow them through; this is the runtime backstop.
+        //
+        // Only for INTRINSIC tags. A custom component (a router Link, ...) owns its
+        // prop contract, and `ComponentPropsWithoutRef<T>` promises the caller that
+        // its props reach it. Stripping names by their spelling alone broke that
+        // promise silently: `<Button as={Custom} name="x" />` type-checked while
+        // `Custom` never received the `name` it requires.
+        //
+        // `autoFocus` and `type` are deliberately NOT stripped: both are valid on
+        // targets this list was filtering them from. `autoFocus` is a global
+        // attribute (React decides per element whether to honour it, which is not
+        // ours to pre-empt), and `type` on an anchor is the MIME hint that
+        // `ButtonProps<'a'>` now types it as.
+        //
+        // The types already answer this for a TypeScript caller: `ButtonProps<T>`
+        // derives from `ComponentPropsWithoutRef<T>`, so only what the target
+        // accepts can be passed. What is left is a runtime backstop for JavaScript
+        // consumers and spread objects.
+        //
+        // Keep it to the two cases where a stray attribute does something. The
+        // submit-overrides belong to a submit control and never make sense on the
+        // anchor path. `disabled` is the one that is VISIBLE: Bulma styles
+        // `.button[disabled]` (background, border, shadow, opacity), so letting it
+        // through to a `<span>` greys the element out — main stripped it, and not
+        // stripping it would be a silent visual change on a types-only release.
+        //
+        // Everything else (`name`, `value`, `form`) is inert where it does not
+        // belong, and enumerating which tags own it is what kept going wrong:
+        // first all nine names on every non-button tag (so `<Button as="input"
+        // name="query" value="Search">` submitted nothing), then a form-control
+        // allowlist that still lost `formAction` on an input and `value` on an
+        // option. Those now ride on the types instead.
+        //
+        // A custom component is exempt entirely — it owns its prop contract, and
+        // `ComponentPropsWithoutRef<T>` promises the caller its props arrive.
+        //
+        // The elements that own `disabled`, per the HTML spec. A closed set, unlike
+        // the open-ended question of which tag owns which attribute.
+        const SUBMIT_OVERRIDES = [
+            'formAction',
+            'formEncType',
+            'formMethod',
+            'formNoValidate',
+            'formTarget',
+        ];
+        const OWNS_DISABLED = [
+            'button',
+            'fieldset',
+            'input',
+            'optgroup',
+            'option',
+            'select',
+            'textarea',
+        ];
+        // Two independent filters. They are not exclusive — an `<a>` owns neither
+        // the submit-overrides nor `disabled`, so it takes both — and deriving them
+        // from one destructure, or from one if/else, is what broke each of them in
+        // turn: first the overrides came off every intrinsic (an `as="input"` lost
+        // `formAction`), then scoping them to the anchor let `disabled` back onto
+        // it.
+        const forwardedRest = { ...rest };
+        if (typeof Component === 'string' && !isCustomElement(Component)) {
+            // Meaningless anywhere but a submit control, and an anchor is not one.
+            if (Component === 'a') {
+                for (const key of SUBMIT_OVERRIDES)
+                    delete forwardedRest[key];
+            }
+            // Visible via Bulma's `.button[disabled]`, so withheld from any element
+            // that does not own it.
+            if (!OWNS_DISABLED.includes(Component))
+                delete forwardedRest.disabled;
+        }
         return (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 }));
+                ? // Guarded, because this handler is installed into whatever `as`
+                    // renders and a custom component's `onClick` need not be a DOM
+                    // event handler at all. One declaring `onClick: (v: string) =>
+                    // void` calls this with a string, and an unguarded
+                    // `e.preventDefault()` throws `is not a function`. Blocking the
+                    // real event is the point; a foreign payload is simply not ours
+                    // to act on.
+                    (e) => {
+                        if (typeof e?.preventDefault === 'function')
+                            e.preventDefault();
+                    }
+                : onClick, ...forwardedRest, children: children }));
     }
     return (jsx("button", { ref: ref, className: buttonClasses, disabled: isDisabled, onClick: onClick, ...rest, children: children }));
 });
@@ -5116,7 +5283,8 @@ function usePrefersReducedMotion() {
  *   ))}
  * </Reveal>
  */
-const Reveal = ({ animation = 'fade-up', delay = 0, duration = 600, threshold = 0.15, once = true, as: Component = 'div', cascade = false, cascadeInterval = 80, className, style, children, ...props }) => {
+function RevealImpl(revealProps) {
+    const { animation = 'fade-up', delay = 0, duration = 600, threshold = 0.15, once = true, as: Component = 'div', cascade = false, cascadeInterval = 80, className, style, children, ...props } = revealProps;
     const { bulmaHelperClasses, rest } = useBulmaClasses(props);
     const classPrefix = useClassPrefix();
     const prefersReducedMotion = usePrefersReducedMotion();
@@ -5193,12 +5361,16 @@ const Reveal = ({ animation = 'fade-up', delay = 0, duration = 600, threshold =
             return (jsx("span", { className: itemAnimationClasses, style: itemStyle, children: child }, index));
         })
         : children;
-    // Scroll observation needs a real DOM node. Intrinsic tags ('div',
-    // 'section', ...) always accept a ref directly. A custom component passed
-    // via `as` (Section, Card, ...) is rendered by this library as a plain
-    // React.FC with no ref forwarding, so the ref (and the animation classes
-    // that depend on it) go on a plain wrapper `div` instead, with `Component`
-    // rendered inside it.
+    // Scroll observation needs a DOM node this component OWNS — the observer and
+    // the animation classes both key off it. An intrinsic tag is that node, so
+    // the ref goes straight on it. A component passed via `as` is not: whatever
+    // it renders is its own business, and it may render several elements or
+    // none. So it gets wrapped in an observed `div`.
+    //
+    // Not a statement about ref forwarding. Several components in this library
+    // forward refs (#641 added four more), and that changes nothing here — a
+    // forwarded ref would still point at the target's node rather than at one
+    // this component controls.
     if (typeof Component === 'string') {
         // A plain createElement call sidesteps the combinatorial JSX prop types
         // for `ref` across every possible intrinsic tag `as` could be.
@@ -5210,7 +5382,9 @@ const Reveal = ({ animation = 'fade-up', delay = 0, duration = 600, threshold =
         }, content);
     }
     return (jsx("div", { ref: setNode, className: combinedClasses, style: wrapperStyle, children: jsx(Component, { ...rest, children: content }) }));
-};
+}
+const Reveal = RevealImpl;
+Reveal.displayName = 'Reveal';
 
 /**
  * The `Block` component renders a simple container with Bulma's `.block` class, adding vertical margin between sections of content.
@@ -5263,7 +5437,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.
+ * @param {React.Ref} ref - Forwarded ref to the element `as` renders.
  * @returns {JSX.Element} The rendered link-styled button element.
  *
  * @example
@@ -5277,7 +5451,13 @@ const Box = ({ className, textColor, color, bgColor, hasShadow = true, children,
 const LinkButton = 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 (jsx(Button, { ref: ref, color: buttonColor, className: classNames(prefixedClasses, className), ...props }));
+    return (jsx(Button
+    // LinkButton is polymorphic through to Button, which resolves the element
+    // from `as`. TS cannot infer that through the spread below.
+    , { 
+        // LinkButton is polymorphic through to Button, which resolves the element
+        // from `as`. TS cannot infer that through the spread below.
+        ref: ref, color: buttonColor, className: classNames(prefixedClasses, className), ...props }));
 });
 LinkButton.displayName = 'LinkButton';
 
@@ -5471,15 +5651,49 @@ const Figure = withSubComponents(FigureComponent, {
 }, 'Figure');
 
 /**
- * Distinguishes an `IconProps` object from a plain custom node (an inline SVG, a `react-icons`
- * component, …) passed to a slot that accepts either.
+ * Distinguishes an `IconProps` object from a plain custom node (an inline SVG, a
+ * `react-icons` component, …) in a slot that accepts either — `Control`'s
+ * `iconLeft`/`iconRight`, `IconText`'s `iconProps`.
+ *
+ * One copy, imported by both consumers: two hand-maintained copies, one per
+ * consumer, is how the deprecated `icon` path came to crash both (#663).
+ *
+ * Its own module rather than `Icon.tsx` because `src/index.ts` wildcard-exports
+ * that file, and everything published there is public forever. `polymorphic.ts`
+ * makes the same call for `isCustomElement`: an internal discriminator is not
+ * something to support for the life of the package.
+ *
+ * It tests each member's VALUE, not merely its key, and only after everything
+ * React owns is out of the way. `'icon' in value` was enough
+ * to claim a Font Awesome `IconDefinition` — `{ prefix, iconName, icon: [w, h, …,
+ * path] }` — whose `icon` is a path array rather than a class string. That object
+ * is not a renderable node either, so the honest outcome is the one this slot has
+ * always had for it: the node branch, and React's own "Objects are not valid as a
+ * React child". Claiming it here instead rendered a blank container that still
+ * reserved layout.
+ *
+ * A member added to `IconProps` needs a line here, and a missed one is a crash
+ * rather than a fallthrough. That is the cost of a slot taking either a props
+ * object or a node; keeping the guard in one place is what keeps the cost to a
+ * single line.
  */
-function isIconProps$1(value) {
-    return (typeof value === 'object' &&
-        value !== null &&
-        !React.isValidElement(value) &&
-        ('name' in value || 'children' in value));
+function isIconProps(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    // Anything React owns. `isValidElement` covers elements only; a PORTAL is a
+    // valid `ReactNode` that fails it and carries a `children` key, so the member
+    // test below claimed it and `Control` spread it into `<Icon>` as props —
+    // rendering the portal's child locally instead of in its container. Every
+    // React internal carries `$$typeof`, so testing for it covers lazy, context
+    // and whatever React adds next, rather than portals alone.
+    if (React.isValidElement(value) || '$$typeof' in value)
+        return false;
+    const candidate = value;
+    return (typeof candidate.name === 'string' ||
+        typeof candidate.icon === 'string' ||
+        'children' in candidate);
 }
+
 /**
  * The `IconText` component provides a Bulma-styled horizontal arrangement of one or more `Icon` components and optional text.
  *
@@ -5500,8 +5714,8 @@ const IconTextComponent = ({ className, textColor, color, bgColor, iconProps, ch
     const bulmaClasses = usePrefixedClassNames('icon-text');
     const iconTextClasses = classNames(bulmaClasses, bulmaHelperClasses, className);
     return (jsx("span", { className: iconTextClasses, ...rest, children: items ? (items.map((item, index) => (jsxs(React.Fragment, { children: [item.iconProps &&
-                    (isIconProps$1(item.iconProps) ? (jsx(Icon, { ...item.iconProps })) : (jsx(Icon, { children: item.iconProps }))), item.text && jsx("span", { children: item.text })] }, index)))) : (jsxs(Fragment, { children: [iconProps &&
-                    (isIconProps$1(iconProps) ? (jsx(Icon, { ...iconProps })) : (jsx(Icon, { children: iconProps }))), children && jsx("span", { children: children })] })) }));
+                    (isIconProps(item.iconProps) ? (jsx(Icon, { ...item.iconProps })) : (jsx(Icon, { children: item.iconProps }))), item.text && jsx("span", { children: item.text })] }, index)))) : (jsxs(Fragment, { children: [iconProps &&
+                    (isIconProps(iconProps) ? (jsx(Icon, { ...iconProps })) : (jsx(Icon, { children: iconProps }))), children && jsx("span", { children: children })] })) }));
 };
 const IconText = withSubComponents(IconTextComponent, { Icon }, 'IconText');
 
@@ -5549,10 +5763,12 @@ const Image = ({ as, className, textColor, color, bgColor, size, isRounded, isRe
  *
  * @function
  * @param {LinkProps} props - Props for the Link component.
- * @returns {JSX.Element} The rendered anchor element.
+ * @param {React.Ref} ref - Forwarded ref to the element `as` renders.
+ * @returns {JSX.Element} The rendered anchor, or whatever `as` names.
  * @see {@link https://bulma.io/documentation/elements/content/ | Bulma Content documentation}
  */
-const Link = ({ className, textColor, bgColor, isActive, as: Component = 'a', children, ...props }) => {
+const Link = forwardRef(function Link(linkProps, ref) {
+    const { className, textColor, bgColor, isActive, as: Component = 'a', children, ...props } = linkProps;
     /**
      * Generates Bulma helper classes and separates out remaining props.
      */
@@ -5565,8 +5781,9 @@ const Link = ({ className, textColor, bgColor, isActive, as: Component = 'a', ch
         'is-active': isActive,
     });
     const linkClasses = classNames(bulmaClasses, bulmaHelperClasses, className);
-    return (jsx(Component, { className: linkClasses || undefined, ...rest, children: children }));
-};
+    return (jsx(Component, { ref: ref, className: linkClasses || undefined, ...rest, children: children }));
+});
+Link.displayName = 'Link';
 
 /**
  * The `ListItem` component renders a styled list item (`<li>`) element with Bulma helper class integration.
@@ -6412,16 +6629,6 @@ const Checkbox = forwardRef(({ color, size, className, children, textColor, disa
 });
 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.