@allxsmith/bestax-bulma 5.15.0 → 5.15.2

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

@@ -1,5 +1,6 @@
 import React from 'react';
 import { BulmaClassesProps } from '../helpers/useBulmaClasses';
+import { type PolymorphicComponent } from '../helpers/polymorphic';
 declare const avatarColors: readonly ["primary", "link", "info", "success", "warning", "danger", "black", "dark", "light", "white"];
 /** Valid color values for the Avatar component. */
 export type AvatarColor = (typeof avatarColors)[number];
@@ -9,9 +10,10 @@ export type AvatarSize = (typeof avatarSizes)[number];
 /** Valid shape values for the Avatar component. */
 export type AvatarShape = 'circle' | 'rounded' | 'square';
 /**
- * Props for the Avatar component.
+ * The Avatar component's own props — everything it adds on top of the
+ * attributes of whatever element `as` renders.
  */
-export interface AvatarProps extends Omit<React.HTMLAttributes<HTMLElement>, 'color'>, Omit<BulmaClassesProps, 'color'> {
+export interface AvatarOwnProps extends Omit<BulmaClassesProps, 'color'> {
     /** Additional CSS classes to apply. */
     className?: string;
     /** Image URL. On load error (or if absent), falls back to initials, then `icon`. */
@@ -30,8 +32,6 @@ export interface AvatarProps extends Omit<React.HTMLAttributes<HTMLElement>, 'co
     shape?: AvatarShape;
     /** Background color for initials/icon avatars (else auto-derived from `name`). */
     color?: AvatarColor;
-    /** Element/component to render as. Defaults to `'a'` when `href` is set, else `'figure'`. */
-    as?: React.ElementType;
     /** When set, renders the avatar as a link. */
     href?: string;
     /** Anchor target — forwarded only when rendering a link (an `a` or a custom `as` component). */
@@ -40,12 +40,46 @@ export interface AvatarProps extends Omit<React.HTMLAttributes<HTMLElement>, 'co
     rel?: string;
     /** Extra props forwarded to the underlying `<img>` (e.g. `loading`, `crossOrigin`); its `onError` is chained before the fallback fires. */
     imageProps?: React.ImgHTMLAttributes<HTMLImageElement>;
+    /** Inline styles, merged after the size style. */
+    style?: React.CSSProperties;
+    /**
+     * Not accepted. Avatar always renders its own content — the image, the
+     * initials, or the icon — so anything a caller passed would be replaced. It
+     * is declared unavailable rather than derived from `as`, which would let a
+     * target requiring `children` compel a value it then never receives.
+     * @internal
+     */
+    children?: never;
 }
+/**
+ * Props for the Avatar component. The DOM attributes and the `ref` both follow
+ * `as`.
+ *
+ * `href`, `target` and `rel` stay Avatar's own props rather than being derived:
+ * they are what *chooses* the element when `as` is absent (an `<a>` with an
+ * `href`, a `<figure>` without one), so they have to be accepted before `as` is
+ * known.
+ *
+ * The type parameter defaults to `'figure'`, not to `React.ElementType`.
+ * Defaulting to the constraint sounds truer to a runtime default that is
+ * conditional, but `ComponentPropsWithoutRef<React.ElementType>` spreads across
+ * every element at once and accepts anything — which is the false-positive this
+ * whole change exists to remove. `'figure'` is the element a no-`href` avatar
+ * actually renders, and the anchor props it can additionally take are declared
+ * above.
+ *
+ * @extraProp {PolymorphicRef<React.ElementType>} [ref] - Ref forwarded to the element `as` renders, typed from `as`: the DOM node for an intrinsic tag, or whatever handle a custom component exposes.
+ */
+export type AvatarProps<T extends React.ElementType = 'figure'> = AvatarOwnProps & Omit<React.ComponentPropsWithoutRef<T>, keyof AvatarOwnProps | 'as'> & {
+    /** Element/component to render as. Defaults to `'a'` when `href` is set, else `'figure'`. */
+    as?: T;
+};
 /**
  * The `Avatar` component represents a person or entity as a compact image.
  *
  * @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
@@ -53,5 +87,5 @@ export interface AvatarProps extends Omit<React.HTMLAttributes<HTMLElement>, 'co
  * @example
  * <Avatar name="Grace Hopper" />
  */
-export declare const Avatar: React.FC<AvatarProps>;
+export declare const Avatar: PolymorphicComponent<AvatarOwnProps, "figure">;
 export default Avatar;

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

@@ -25,6 +25,6 @@ export interface AvatarsProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
     children?: React.ReactNode;
 }
 export declare const Avatars: React.FC<AvatarsProps> & {
-    Avatar: React.FC<AvatarProps>;
+    Avatar: import("..").PolymorphicComponent<import("./Avatar").AvatarOwnProps, "figure">;
 };
 export default Avatars;

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

@@ -1,5 +1,6 @@
 import React from 'react';
 import { BulmaClassesProps } from '../helpers/useBulmaClasses';
+import type { ConstrainedPolymorphicComponentWithoutRef } from '../helpers/polymorphic';
 /**
  * Checks if code is running in a browser environment.
  * @param win - Window object.
@@ -38,20 +39,48 @@ export interface DropdownProps extends Omit<React.HTMLAttributes<HTMLDivElement>
     id?: string;
 }
 /**
- * Props for the DropdownItem component.
+ * The elements a dropdown item may render as. Bulma's dropdown markup names
+ * these three and no others, so `as` is a closed set rather than an open
+ * `React.ElementType`.
  */
-export interface DropdownItemProps extends Omit<React.HTMLAttributes<HTMLElement>, keyof BulmaClassesProps>, BulmaClassesProps {
+export type DropdownItemElement = 'a' | 'div' | 'button';
+/**
+ * The DropdownItem component's own props.
+ */
+export interface DropdownItemOwnProps extends BulmaClassesProps {
     /** Whether the item is active. */
     active?: boolean;
     /** Additional CSS classes. */
     className?: string;
-    /** The element type to render. */
-    as?: 'a' | 'div' | 'button';
     /** Marks the item as disabled; disabled items are skipped during keyboard navigation. Use with `as="button"` for a native disabled control, or pair with `aria-disabled` on a link. */
     disabled?: boolean;
     /** Item content. */
     children?: React.ReactNode;
 }
+/**
+ * Props for the DropdownItem component. Everything the item does not own
+ * follows `as`: `href`, `target` and `rel` under the default `'a'`, `type` and
+ * `form` under `'button'`, and the shared HTML attributes under any of them.
+ *
+ * Pinning these to `React.HTMLAttributes<HTMLElement>` instead — which is what
+ * this type did before — rejected `href` on an anchor and `type` on a button,
+ * both of which have always worked at runtime. Same defect as #641, in the
+ * narrower shape a constrained `as` takes.
+ *
+ * **Name the tag you mean.** The type parameter defaults to the whole union, not
+ * to the rendered element, so bare `DropdownItemProps` keeps accepting
+ * `{ as: 'div' }` the way it always has. The cost is that it is not
+ * distributive: `Omit` over a union keeps only the shared keys, so the bare
+ * alias carries no `href` even though the component takes one under `as="a"`.
+ * Write `DropdownItemProps<'a'>` for the anchor's props. That is the #667 alias
+ * limitation Button carries, labelled next-major because closing it is
+ * source-breaking, and pinned for this component in
+ * `__typetests__/polymorphic.tsx`; the component itself is unaffected.
+ */
+export type DropdownItemProps<T extends DropdownItemElement = DropdownItemElement> = DropdownItemOwnProps & Omit<React.ComponentPropsWithoutRef<T>, keyof DropdownItemOwnProps | 'as'> & {
+    /** The element type to render. */
+    as?: T;
+};
 /**
  * Bulma Dropdown item.
  *
@@ -59,7 +88,7 @@ export interface DropdownItemProps extends Omit<React.HTMLAttributes<HTMLElement
  * @param {DropdownItemProps} props - Props for the DropdownItem component.
  * @returns {JSX.Element} The rendered dropdown item.
  */
-export declare const DropdownItem: React.FC<DropdownItemProps>;
+export declare const DropdownItem: ConstrainedPolymorphicComponentWithoutRef<DropdownItemOwnProps, DropdownItemElement, "a">;
 /**
  * Bulma Dropdown divider.
  *
@@ -69,7 +98,7 @@ export declare const DropdownItem: React.FC<DropdownItemProps>;
 export declare const DropdownDivider: React.FC;
 /** Bulma Dropdown component with Item and Divider sub-components. */
 export declare const Dropdown: React.ForwardRefExoticComponent<DropdownProps & React.RefAttributes<HTMLDivElement>> & {
-    Item: React.FC<DropdownItemProps>;
+    Item: ConstrainedPolymorphicComponentWithoutRef<DropdownItemOwnProps, DropdownItemElement, "a">;
     Divider: React.FC<{}>;
 };
 export default Dropdown;

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

@@ -1,5 +1,6 @@
 import React from 'react';
 import { BulmaClassesProps } from '../helpers/useBulmaClasses';
+import { type PolymorphicComponent } from '../helpers/polymorphic';
 /**
  * Props for the Menu component.
  */
@@ -44,32 +45,56 @@ export interface MenuListProps extends Omit<React.HTMLAttributes<HTMLUListElemen
  */
 export declare const MenuList: React.FC<MenuListProps>;
 /**
- * Props for the MenuItem component.
+ * The MenuItem component's own props.
+ *
+ * A menu item is two elements: a wrapping `<li>` and, inside it, the element
+ * `as` names. The props here are the ones the `<li>` consumes; everything else
+ * follows `as` onto the inner element.
  */
-export interface MenuItemProps extends Omit<React.LiHTMLAttributes<HTMLLIElement>, keyof BulmaClassesProps>, BulmaClassesProps {
-    /** Additional CSS classes. */
+export interface MenuItemOwnProps extends BulmaClassesProps {
+    /** Additional CSS classes for the wrapping `<li>`. */
     className?: string;
     /** Item content and optional nested MenuList. */
     children: React.ReactNode;
     /** Highlight item as active. */
     active?: boolean;
-    /** Href for link items (if rendered as `<a>`). */
-    href?: string;
-    /** Custom link component (e.g. `Link` from router). */
-    as?: React.ElementType;
-    [key: string]: unknown;
+    /** Inline styles for the wrapping `<li>`. */
+    style?: React.CSSProperties;
+    /** `id` for the wrapping `<li>`. */
+    id?: string;
+    /** `title` for the wrapping `<li>`. */
+    title?: string;
+    /** ARIA role for the wrapping `<li>`. */
+    role?: React.AriaRole;
+    /** Tab index for the wrapping `<li>`. */
+    tabIndex?: number;
+    /** Test id for the wrapping `<li>`. */
+    'data-testid'?: string;
 }
+/**
+ * Props for the MenuItem component. Everything the `<li>` does not consume
+ * follows `as` onto the inner element: with the default `'a'` that means `href`
+ * and the other anchor attributes, and with `as={Link}` it means that
+ * component's own props.
+ *
+ * @extraProp {PolymorphicRef<React.ElementType>} [ref] - Ref forwarded to the inner element `as` renders, not the wrapping `<li>`, typed from `as`: the DOM node for an intrinsic tag, or whatever handle a custom component exposes.
+ */
+export type MenuItemProps<T extends React.ElementType = 'a'> = MenuItemOwnProps & Omit<React.ComponentPropsWithoutRef<T>, keyof MenuItemOwnProps | 'as'> & {
+    /** Custom link component (e.g. `Link` from router). */
+    as?: T;
+};
 /**
  * MenuItem supports `as` prop for custom link components, e.g., react-router-dom Link.
  *
  * @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.
  */
-export declare const MenuItem: React.FC<MenuItemProps>;
+export declare const MenuItem: PolymorphicComponent<MenuItemOwnProps, "a">;
 export declare const Menu: React.FC<MenuProps> & {
     Label: React.FC<MenuLabelProps>;
     List: React.FC<MenuListProps>;
-    Item: React.FC<MenuItemProps>;
+    Item: PolymorphicComponent<MenuItemOwnProps, "a">;
 };
 export default Menu;

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

@@ -1,4 +1,5 @@
 import React from 'react';
+import type { PolymorphicComponent } from '../helpers/polymorphic';
 import { BulmaClassesProps, validColors } from '../helpers/useBulmaClasses';
 /**
  * Props for the Navbar component.
@@ -42,13 +43,27 @@ export interface NavbarBrandProps extends React.HTMLAttributes<HTMLDivElement>,
  */
 export declare const NavbarBrand: React.FC<NavbarBrandProps>;
 /**
- * Props for the NavbarItem component.
+ * The NavbarItem component's own props — everything it adds on top of the
+ * attributes of whatever element `as` renders.
  */
-export interface NavbarItemProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'color'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+export interface NavbarItemOwnProps extends Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /**
+     * Not accepted. `color` here would be the deprecated presentational HTML
+     * attribute, and `useBulmaClasses` consumes any `color` key as a Bulma helper
+     * before the target could see it — so it is declared unavailable rather than
+     * silently eaten. Use `textColor` / `bgColor`.
+     * @internal
+     */
+    color?: never;
+    /**
+     * Not accepted under this name. `useBulmaClasses` consumes any
+     * `backgroundColor` key before `rest` is spread, so a custom `as` target
+     * declaring one would never receive it. Use `bgColor`.
+     * @internal
+     */
+    backgroundColor?: never;
     /** Additional CSS classes. */
     className?: string;
-    /** Render as a custom component (e.g., a router link). */
-    as?: React.ElementType;
     /** Whether the item is active. */
     active?: boolean;
     /** Text color for the item. */
@@ -57,16 +72,27 @@ export interface NavbarItemProps extends Omit<React.AnchorHTMLAttributes<HTMLAnc
     bgColor?: (typeof validColors)[number] | 'inherit' | 'current';
     /** Navbar item content. */
     children?: React.ReactNode;
-    [key: string]: unknown;
 }
+/**
+ * Props for the NavbarItem component. The DOM attributes and the `ref` both
+ * follow `as`: rendering as a router link accepts that component's props (`to`
+ * and friends) by inference, and `as="span"` rejects `href`.
+ *
+ * @extraProp {PolymorphicRef<React.ElementType>} [ref] - Ref forwarded to the element `as` renders, typed from `as`: the DOM node for an intrinsic tag, or whatever handle a custom component exposes.
+ */
+export type NavbarItemProps<T extends React.ElementType = 'a'> = NavbarItemOwnProps & Omit<React.ComponentPropsWithoutRef<T>, keyof NavbarItemOwnProps | 'as'> & {
+    /** Render as another intrinsic element (`'span'`, `'div'`) or a custom component (e.g. a router link). Defaults to `'a'`. */
+    as?: T;
+};
 /**
  * Navigation links, buttons, or custom content
  *
  * @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.
  */
-export declare const NavbarItem: React.FC<NavbarItemProps>;
+export declare const NavbarItem: PolymorphicComponent<NavbarItemOwnProps, "a">;
 /**
  * Props for the NavbarBurger component.
  * @extraProp {React.Ref<HTMLButtonElement>} [ref] - Ref forwarded to the burger button element.
@@ -151,14 +177,27 @@ export declare const NavbarStart: React.FC<NavbarStartEndProps>;
  */
 export declare const NavbarEnd: React.FC<NavbarStartEndProps>;
 /**
- * Props for the NavbarLink component.
- * @extraProp {React.Ref<HTMLAnchorElement | HTMLButtonElement>} [ref] - Ref forwarded to the rendered link or button element.
+ * The NavbarLink component's own props — everything it adds on top of the
+ * attributes of whatever element `as` renders.
  */
-export interface NavbarLinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'color'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+export interface NavbarLinkOwnProps extends Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /**
+     * Not accepted. `color` here would be the deprecated presentational HTML
+     * attribute, and `useBulmaClasses` consumes any `color` key as a Bulma helper
+     * before the target could see it — so it is declared unavailable rather than
+     * silently eaten. Use `textColor` / `bgColor`.
+     * @internal
+     */
+    color?: never;
+    /**
+     * Not accepted under this name. `useBulmaClasses` consumes any
+     * `backgroundColor` key before `rest` is spread, so a custom `as` target
+     * declaring one would never receive it. Use `bgColor`.
+     * @internal
+     */
+    backgroundColor?: never;
     /** Additional CSS classes. */
     className?: string;
-    /** Render as a custom component (default: 'a'). */
-    as?: React.ElementType;
     /** Remove the dropdown arrow indicator. */
     arrowless?: boolean;
     /** Text color. */
@@ -168,15 +207,28 @@ export interface NavbarLinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnc
     /** Link content. */
     children?: React.ReactNode;
 }
+/**
+ * Props for the NavbarLink component. The DOM attributes and the `ref` both
+ * follow `as`: `as="button"` accepts the button attributes and a button ref,
+ * and `as="span"` rejects `href` and `target`. Not `rel` — React declares it on
+ * `HTMLAttributes<T>`, so it is valid on every element, and rejecting it would
+ * mean diverging from React's own typing.
+ *
+ * @extraProp {PolymorphicRef<React.ElementType>} [ref] - Ref forwarded to the element `as` renders, typed from `as`: the DOM node for an intrinsic tag, or whatever handle a custom component exposes.
+ */
+export type NavbarLinkProps<T extends React.ElementType = 'a'> = NavbarLinkOwnProps & Omit<React.ComponentPropsWithoutRef<T>, keyof NavbarLinkOwnProps | 'as'> & {
+    /** Render as another intrinsic element (`'button'`, `'span'`) or a custom component. Defaults to `'a'`. */
+    as?: T;
+};
 /**
  * Dropdown trigger with arrow indicator (use as first child of `Navbar.Dropdown`)
  *
  * @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.
  */
-export declare const NavbarLink: React.ForwardRefExoticComponent<NavbarLinkProps & React.RefAttributes<HTMLButtonElement | HTMLAnchorElement>>;
+export declare const NavbarLink: PolymorphicComponent<NavbarLinkOwnProps, "a">;
 /**
  * Props for the NavbarDropdown component.
  * @extraProp {React.Ref<HTMLDivElement>} [ref] - Ref forwarded to the dropdown container element.
@@ -237,8 +289,8 @@ export declare const NavbarDropdownMenu: React.FC<NavbarDropdownMenuProps>;
 export declare const NavbarDivider: React.FC<React.HTMLAttributes<HTMLHRElement>>;
 export declare const Navbar: React.ForwardRefExoticComponent<NavbarProps & React.RefAttributes<HTMLElement>> & {
     Brand: React.FC<NavbarBrandProps>;
-    Item: React.FC<NavbarItemProps>;
-    Link: React.ForwardRefExoticComponent<NavbarLinkProps & React.RefAttributes<HTMLButtonElement | HTMLAnchorElement>>;
+    Item: PolymorphicComponent<NavbarItemOwnProps, "a">;
+    Link: PolymorphicComponent<NavbarLinkOwnProps, "a">;
     Burger: React.ForwardRefExoticComponent<NavbarBurgerProps & React.RefAttributes<HTMLButtonElement>>;
     Menu: React.FC<NavbarMenuProps>;
     Start: React.FC<NavbarStartEndProps>;

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

@@ -1,6 +1,6 @@
 import React from 'react';
 import { BulmaClassesProps } from '../helpers/useBulmaClasses';
-import { IconChildrenProps, IconNameProps } from '../elements/Icon';
+import { IconChildrenProps, IconDeprecatedProps, IconNameProps } from '../elements/Icon';
 /**
  * Props for the Panel component.
  */
@@ -45,7 +45,7 @@ export interface PanelBlockProps extends React.AnchorHTMLAttributes<HTMLAnchorEl
  * Props for the PanelIcon component.
  * Extends IconProps but uses 'panel-icon' as the container class.
  */
-export type PanelIconProps = Omit<IconNameProps, 'containerClassName'> | Omit<IconChildrenProps, 'containerClassName'>;
+export type PanelIconProps = Omit<IconNameProps, 'containerClassName'> | Omit<IconChildrenProps, 'containerClassName'> | Omit<IconDeprecatedProps, 'containerClassName'>;
 /**
  * Props for the PanelInputBlock component.
  */

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

@@ -1,14 +1,15 @@
 import React from 'react';
+import type { PolymorphicComponentWithoutRef } from '../helpers/polymorphic';
 import { BulmaClassesProps } from '../helpers/useBulmaClasses';
 /**
  * Animation styles available for the Reveal component.
  */
 export type RevealAnimation = 'fade' | 'fade-up' | 'fade-down' | 'slide-left' | 'slide-right' | 'zoom' | 'flip';
 /**
- * Props for the Reveal component.
- * @extraProp {string} [className] - Additional CSS classes.
+ * The Reveal component's own props — everything it adds on top of the
+ * attributes of whatever element `as` renders.
  */
-export interface RevealProps extends Omit<React.HTMLAttributes<HTMLElement>, 'color'>, BulmaClassesProps {
+export interface RevealOwnProps extends BulmaClassesProps {
     /** Animation style applied when the element enters the viewport. */
     animation?: RevealAnimation;
     /** Delay in milliseconds before the animation starts. Default: 0. */
@@ -19,35 +20,28 @@ export interface RevealProps extends Omit<React.HTMLAttributes<HTMLElement>, 'co
     threshold?: number;
     /** Animate only the first time the element enters the viewport. If `false`, it re-animates on every entry/exit. */
     once?: boolean;
-    /** Element or component to render as. Default: 'div'. When `as` is a plain intrinsic tag (e.g. `'section'`), your `className`, `style`, and Bulma helper classes plus everything in `...rest` all land on that single element. When `as` is a component (e.g. `Section`, `Card`), scroll detection needs a real DOM node with a ref, so `Reveal` wraps it in an observed `div`: `className`/`style`/helper classes go on that wrapper `div`, while `...rest` (`id`, `aria-*`, `data-*`, event handlers) is forwarded to the inner component. */
-    as?: React.ElementType;
     /** Stagger direct children with an incrementing delay instead of animating this element as a single block. */
     cascade?: boolean;
     /** Milliseconds added to each successive child's delay when `cascade` is set. Default: 80. */
     cascadeInterval?: number;
     /** Content to reveal. */
     children?: React.ReactNode;
+    /** Additional CSS classes. Applied to the observed element (the wrapper `div` when `as` is a component). */
+    className?: string;
+    /** Inline styles, merged after the animation's own. Applied to the observed element. */
+    style?: React.CSSProperties;
 }
 /**
- * The `Reveal` component animates its content into view as it scrolls into the viewport, backed by `IntersectionObserver`.
- *
- * @function
- * @param {RevealProps} props - Props for the Reveal component.
- * @returns {JSX.Element} The rendered reveal wrapper.
+ * Props for the Reveal component. The DOM attributes follow `as`.
  *
- * @example
- * // Fade a section up into view
- * <Reveal animation="fade-up" as={Section}>
- *   <Title>Why Grass Doctor</Title>
- * </Reveal>
- *
- * @example
- * // Stagger a set of cards as they enter the viewport
- * <Reveal animation="fade-up" cascade cascadeInterval={80}>
- *   {services.map(service => (
- *     <Card key={service.name}>{service.name}</Card>
- *   ))}
- * </Reveal>
+ * Reveal forwards no `ref`: it owns the node it observes for scroll
+ * intersection, and when `as` is a component that node is a wrapper `div`
+ * rather than the element `as` names — so a ref derived from `as` would point
+ * at the wrong thing.
  */
-export declare const Reveal: React.FC<RevealProps>;
+export type RevealProps<T extends React.ElementType = 'div'> = RevealOwnProps & Omit<React.ComponentPropsWithoutRef<T>, keyof RevealOwnProps | 'as'> & {
+    /** Element or component to render as. Default: 'div'. When `as` is a plain intrinsic tag (e.g. `'section'`), your `className`, `style`, and Bulma helper classes plus everything in `...rest` all land on that single element. When `as` is a component (e.g. `Section`, `Card`), scroll detection needs a real DOM node with a ref, so `Reveal` wraps it in an observed `div`: `className`/`style`/helper classes go on that wrapper `div`, while `...rest` (`id`, `aria-*`, `data-*`, event handlers) is forwarded to the inner component. */
+    as?: T;
+};
+export declare const Reveal: PolymorphicComponentWithoutRef<RevealOwnProps, "div">;
 export default Reveal;

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

@@ -1,10 +1,18 @@
 import React from 'react';
+import { type PolymorphicComponent } from '../helpers/polymorphic';
 import { BulmaClassesProps, validColors } from '../helpers/useBulmaClasses';
 /**
- * Props for the Button component.
- * @extraProp {React.Ref<HTMLButtonElement | HTMLAnchorElement>} [ref] - Ref forwarded to the rendered button or anchor element.
+ * The Button component's own props — everything it adds on top of the
+ * attributes of whatever element `as` renders.
  */
-export interface ButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'color' | 'onClick'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor' | 'size'> {
+export interface ButtonOwnProps extends Omit<BulmaClassesProps, 'color' | 'backgroundColor' | 'size'> {
+    /**
+     * Not accepted under this name. `useBulmaClasses` consumes any
+     * `backgroundColor` key before `rest` is spread, so a custom `as` target
+     * declaring one would never receive it. Use `bgColor`.
+     * @internal
+     */
+    backgroundColor?: never;
     /** Bulma color variant for the button. `ghost` renders a link-like button; `text` renders a minimal text-only button. */
     color?: 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger' | 'white' | 'light' | 'dark' | 'black' | 'text' | 'ghost';
     /** Size of the button. */
@@ -39,27 +47,28 @@ export interface ButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonE
     textColor?: (typeof validColors)[number] | 'inherit' | 'current';
     /** Background color helper. */
     bgColor?: (typeof validColors)[number] | 'inherit' | 'current';
-    /** Render as a `<button>`, `<a>`, or a custom component (e.g. a router `Link`). Defaults to `'button'`; anything else (including `'a'`) uses anchor-style prop handling. */
-    as?: React.ElementType;
-    /** Href value (if rendering as `<a>`). */
-    href?: string;
-    /** Click event handler. */
-    onClick?: React.MouseEventHandler<HTMLButtonElement> | React.MouseEventHandler<HTMLAnchorElement>;
-    /** Anchor tag target. */
-    target?: string;
-    /** Anchor tag rel. */
-    rel?: string;
     /** Button content. */
     children?: React.ReactNode;
 }
+/**
+ * Props for the Button component. The DOM attributes and the `ref` both follow
+ * `as`: with `as="a"` the anchor attributes are accepted, with `as="div"` they
+ * are not.
+ *
+ * @extraProp {PolymorphicRef<React.ElementType>} [ref] - Ref forwarded to the element `as` renders, typed from `as`: the DOM node for an intrinsic tag, or whatever handle a custom component exposes.
+ */
+export type ButtonProps<T extends React.ElementType = 'button'> = ButtonOwnProps & Omit<React.ComponentPropsWithoutRef<T>, keyof ButtonOwnProps | 'as'> & {
+    /** Render as a `<button>`, `<a>`, or a custom component (e.g. a router `Link`). Defaults to `'button'`; anything else renders through the anchor path, which adds `href`/`target`/`rel` and withholds the submit-override attributes (`formAction` and friends) from an `<a>`. */
+    as?: T;
+};
 /**
  * The `Button` component provides a flexible and highly customizable button for your Bulma React UI.
  *
  * @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}
  */
-export declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement | HTMLAnchorElement>>;
+export declare const Button: PolymorphicComponent<ButtonOwnProps, "button">;
 export default Button;

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

@@ -34,7 +34,7 @@ interface ButtonsProps extends React.HTMLAttributes<HTMLDivElement>, Omit<BulmaC
     children: React.ReactNode;
 }
 export declare const Buttons: React.FC<ButtonsProps> & {
-    Button: React.ForwardRefExoticComponent<import("./Button").ButtonProps & React.RefAttributes<HTMLButtonElement | HTMLAnchorElement>>;
-    LinkButton: React.ForwardRefExoticComponent<import("./LinkButton").LinkButtonProps & React.RefAttributes<HTMLButtonElement | HTMLAnchorElement>>;
+    Button: import("..").PolymorphicComponent<import("./Button").ButtonOwnProps, "button">;
+    LinkButton: import("..").PolymorphicComponent<import("./LinkButton").LinkButtonOwnProps, "button">;
 };
 export {};

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

@@ -33,7 +33,14 @@ interface IconBaseProps extends React.HTMLAttributes<HTMLSpanElement>, BulmaClas
     color?: 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger';
     /** Background color helper. */
     bgColor?: (typeof validColors)[number] | 'inherit' | 'current';
-    /** DEPRECATED: Legacy prop, use `name` instead. */
+    /**
+     * Legacy icon class string (e.g. `'fas fa-star'`). Only its last segment is read, as the
+     * glyph name; the library still comes from `library` or `ConfigProvider`, so
+     * `'mdi mdi-rocket'` renders an `fa` class unless the effective library is already `mdi` —
+     * set it here or on the provider.
+     *
+     * @deprecated Use `name` instead.
+     */
     icon?: string;
     /**
      * The icon library to use ('fa' = Font Awesome, 'mdi' = Material Design Icons, 'ion' = Ionicons Web Components, 'material-icons' = Google Material Icons, 'material-symbols' = Google Material Symbols). Defaults to the value set in ConfigProvider or 'fa' if not configured. Ignored when `children` supplies the glyph instead of `name`.
@@ -44,7 +51,11 @@ interface IconBaseProps extends React.HTMLAttributes<HTMLSpanElement>, BulmaClas
     variant?: string;
     /** Additional modifiers (e.g. `'fa-lg'`, `'fa-spin'`, `'is-size-1'`). Ignored when `children` supplies the glyph instead of `name`. */
     features?: string | string[];
-    /** **DEPRECATED:** Use `variant` and `features` instead. */
+    /**
+     * Additional modifiers in the older combined form, parsed into `variant` and `features`.
+     *
+     * @deprecated Use `variant` and `features` instead.
+     */
     libraryFeatures?: string | string[];
     /** Size modifier for the icon container. */
     size?: 'small' | 'medium' | 'large';
@@ -83,10 +94,38 @@ export interface IconChildrenProps extends IconBaseProps {
     children: Exclude<React.ReactNode, undefined>;
 }
 /**
- * Props for the Icon component — a discriminated union of a class-based `name` and a custom
- * `children` node.
+ * Props for `Icon` naming its glyph through the deprecated `icon` prop instead of `name`.
+ *
+ * The runtime has always accepted `icon` on its own — it strips a leading library prefix off
+ * the class string and falls through to the `name` path — but the type offered no member without
+ * a `name` or `children`, so every caller still on the deprecated prop got an error the
+ * package could not see — until #663 nothing here type-checked a test or a story, so the
+ * three `Icon.test.tsx` cases exercising this path proved the runtime and said nothing about
+ * the type. Declaring the path is the honest resolution: it is deprecated, not removed, and a
+ * deprecation that does not type-check is a removal announced only to whoever tries it.
+ *
+ * @deprecated Pass `name` instead. This member goes when `icon` does.
+ */
+export interface IconDeprecatedProps extends IconBaseProps {
+    /**
+     * Legacy icon class string (e.g. `'fas fa-star'`). Only its last segment is read, as the
+     * glyph name; the library still comes from `library` or `ConfigProvider`, so
+     * `'mdi mdi-rocket'` renders an `fa` class unless the effective library is already `mdi` —
+     * set it here or on the provider.
+     *
+     * @deprecated Use `name` instead.
+     */
+    icon: string;
+    /** The icon name. Absent on this path — `icon` supplies the glyph. */
+    name?: undefined;
+    /** A custom node. Mutually exclusive with `icon`. */
+    children?: never;
+}
+/**
+ * Props for the Icon component — a discriminated union of a class-based `name`, a custom
+ * `children` node, and the deprecated `icon` class string.
  */
-export type IconProps = IconNameProps | IconChildrenProps;
+export type IconProps = IconNameProps | IconChildrenProps | IconDeprecatedProps;
 /**
  * The `Icon` component is a Bulma-styled wrapper for displaying icons from various libraries (Font Awesome, Material Design Icons, Ionicons, Google Material Icons, Material Symbols, etc.).
  *