@allxsmith/bestax-bulma 5.15.1 → 5.15.2

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/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/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.).
  *

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

@@ -0,0 +1,30 @@
+import React from 'react';
+import type { IconProps } from './Icon';
+/**
+ * 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.
+ */
+export declare function isIconProps(value: IconProps | React.ReactNode): value is IconProps;

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

@@ -73,10 +73,14 @@ export type PolymorphicProps<T extends React.ElementType, Own> = T extends unkno
  * **A wrapping HOC erases the genericity.** `React.memo(Button)`,
  * `React.lazy`, a `styled()` wrapper — anything that infers its props through
  * `ComponentProps<T>` — instantiates the type parameter once and hands back a
- * component with a single widened prop type. Calls still work, but the checks
- * stop: `<MemoButton as="div" href="/x" />` compiles where `<Button>` rejects
- * it. This is inherent to polymorphic components in TypeScript, not something
- * this library can fix. Re-assert the type to get the checks back:
+ * component with a single prop type. It takes the LAST call signature, which is
+ * the derivation overload, so the wrapper is pinned to the DEFAULT element:
+ * `React.memo(Button)` rejects `as="div"` outright, and `React.memo(Dropdown.Item)`
+ * renders neither a `<div>` nor a `<button>`, though both components accept those
+ * directly. Stricter, not looser — the checks do not stop, they collapse onto one
+ * element, and a `Dropdown.Item` memoized for a long menu list is the case that
+ * meets it. This is inherent to polymorphic components in TypeScript, not
+ * something this library can fix. Re-assert the type to get the rest back:
  *
  * ```tsx
  * const MemoButton = React.memo(Button) as typeof Button;
@@ -103,3 +107,32 @@ export interface PolymorphicComponentWithoutRef<Own, Default extends React.Eleme
     (props: PolymorphicProps<Default, Own>): React.ReactElement | null;
     displayName?: string;
 }
+/**
+ * A component whose props follow `as`, where `as` is a closed set of tags.
+ *
+ * `PolymorphicComponentWithoutRef` lets `as` name anything; this narrows it to
+ * `Allowed`. Bulma pins some elements by its own markup contract — a dropdown
+ * item is an `<a>`, a `<div>` or a `<button>` and nothing else — and the
+ * constraint keeps that promise while still deriving props from whichever of
+ * the three a caller picks.
+ *
+ * Genericity is what makes the derivation exact for a LITERAL `as`, and it is
+ * worth the extra type parameter. Typing such a component as `React.FC<Union>`
+ * instead — a union of the three prop shapes — reads as equivalent but is not:
+ * against a union target, an object literal's excess-property check passes if
+ * the property exists in ANY member, so `<Item as="div" href="/x" />` slips
+ * through. Inferring `T` from the literal checks against that one member.
+ *
+ * A UNION-typed `as` — a ternary, or a variable typed as the whole set — infers
+ * `T` as the union and lands back in that same permissive check, so
+ * `<Item as={tag} href="/x" />` compiles whatever `tag` turns out to be. That is
+ * the open `as` behaviour too, and deliberate there: `PolymorphicProps`
+ * distributes precisely so a union-typed `as` KEEPS each member's props rather
+ * than losing every prop the members do not share. Narrowing it is not a
+ * constrained-component question; it would have to change for `Button` first.
+ */
+export interface ConstrainedPolymorphicComponentWithoutRef<Own, Allowed extends React.ElementType, Default extends Allowed> {
+    <T extends Allowed = Default>(props: PolymorphicProps<T, Own>): React.ReactElement | null;
+    (props: PolymorphicProps<Default, Own>): React.ReactElement | null;
+    displayName?: string;
+}

package/dist/types/index.d.ts

@@ -100,7 +100,7 @@ export type { FormFieldProps } from './form/fieldProps';
 export * from './grid/Cell';
 export * from './grid/Grid';
 export * from './helpers/classNames';
-export type { PolymorphicComponent, PolymorphicComponentWithoutRef, PolymorphicProps, PolymorphicRef, } from './helpers/polymorphic';
+export type { ConstrainedPolymorphicComponentWithoutRef, PolymorphicComponent, PolymorphicComponentWithoutRef, PolymorphicProps, PolymorphicRef, } from './helpers/polymorphic';
 export * from './helpers/mergeBulmaStyles';
 export * from './helpers/useBulmaClasses';
 export * from './helpers/Theme';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allxsmith/bestax-bulma",
-  "version": "5.15.1",
+  "version": "5.15.2",
   "description": "A fully-typed React component library for the Bulma CSS framework. Build modern UIs quickly with reusable, accessible, and customizable Bulma-based React components.",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",
@@ -190,6 +190,7 @@
     "bundle:stats": "rollup -c --configPlugin visualizer",
     "lint": "eslint src",
     "typecheck": "tsc --noEmit",
+    "typecheck:tests": "tsc -p tsconfig.test.json --noEmit",
     "format": "prettier --write \"src/**/*.{ts,tsx}\"",
     "format:check": "prettier --check \"src/**/*.{ts,tsx}\"",
     "clean": "rimraf dist",