@allxsmith/bestax-bulma 5.15.0 → 5.15.2

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

@@ -1,12 +1,26 @@
 import React from 'react';
+import type { PolymorphicComponent } from '../helpers/polymorphic';
 import { BulmaClassesProps, validColors } from '../helpers/useBulmaClasses';
 /**
- * Props for the Link component.
- * @extraProp {string} [href] - The URL the link points to.
- * @extraProp {'_self' | '_blank' | '_parent' | '_top'} [target] - Where to open the linked document.
- * @extraProp {string} [rel] - Relationship between current and linked document.
+ * The Link component's own props — everything it adds on top of the attributes
+ * of whatever element `as` renders.
  */
-export interface LinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+export interface LinkOwnProps extends Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /**
+     * Not accepted. `color` on this component 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 to apply. */
     className?: string;
     /** Text color helper. */
@@ -15,17 +29,27 @@ export interface LinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement>
     bgColor?: (typeof validColors)[number] | 'inherit' | 'current';
     /** Whether the link appears active. */
     isActive?: boolean;
-    /** Render as a custom component (e.g. a router `Link`) instead of `<a>`. Defaults to `'a'`. */
-    as?: React.ElementType;
     /** Content to render inside the link. */
     children?: React.ReactNode;
 }
+/**
+ * Props for the Link component. The DOM attributes and the `ref` both follow
+ * `as`: with the default `'a'` the anchor attributes (`href`, `target`, `rel`)
+ * are accepted, with `as="span"` 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 LinkProps<T extends React.ElementType = 'a'> = LinkOwnProps & Omit<React.ComponentPropsWithoutRef<T>, keyof LinkOwnProps | 'as'> & {
+    /** Render as another intrinsic element (`'span'`, `'button'`) or a custom component (e.g. a router `Link`) instead of `<a>`. Defaults to `'a'`. */
+    as?: T;
+};
 /**
  * The `Link` component renders a styled anchor (`<a>`) element with Bulma helper class integration.
  *
  * @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}
  */
-export declare const Link: React.FC<LinkProps>;
+export declare const Link: PolymorphicComponent<LinkOwnProps, "a">;

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

@@ -1,19 +1,48 @@
-import { ButtonProps } from './Button';
+import React from 'react';
+import { ButtonOwnProps } from './Button';
+import type { PolymorphicComponent } from '../helpers/polymorphic';
 /**
- * Props for the LinkButton component.
+ * The LinkButton component's own props — everything it adds on top of the
+ * attributes of whatever element `as` renders.
  */
-export interface LinkButtonProps extends Omit<ButtonProps, 'color' | 'isOutlined' | 'isInverted' | 'isLight'> {
+export interface LinkButtonOwnProps extends Omit<ButtonOwnProps, 'color' | 'isOutlined' | 'isInverted' | 'isLight'> {
     /** Display mode. `text` has no underline and highlights its background on hover; `ghost` uses the default text color and underlines on hover; `underline` drops the button chrome entirely (transparent background and border) and underlines on hover or focus. */
     variant?: 'text' | 'ghost' | 'underline';
     /** Text color override for the button. */
     color?: 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger' | 'white' | 'light' | 'dark' | 'black';
+    /**
+     * Not available on `LinkButton`, and declared so that a custom `as` target
+     * cannot reintroduce it. `Button` consumes these three for styling variants
+     * `LinkButton` does not offer, and strips them before rendering the target —
+     * so without this a component requiring one would type-check and silently
+     * never receive it.
+     * @internal
+     */
+    isOutlined?: never;
+    /** @internal Not available on `LinkButton` — see `isOutlined`. */
+    isInverted?: never;
+    /** @internal Not available on `LinkButton` — see `isOutlined`. */
+    isLight?: never;
 }
+/**
+ * Props for the LinkButton component. The DOM attributes and the `ref` both
+ * follow `as`, exactly as they do on `Button`.
+ *
+ * @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 LinkButtonProps<T extends React.ElementType = 'button'> = LinkButtonOwnProps & Omit<React.ComponentPropsWithoutRef<T>, keyof LinkButtonOwnProps | 'as'> & {
+    /**
+     * Render as a `<button>`, `<a>`, or a custom component (e.g. a router `Link`).
+     * @defaultValue 'button'
+     */
+    as?: T;
+};
 /**
  * The `LinkButton` component renders a `<button>` that visually looks like text or a link.
  *
  * @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
@@ -24,5 +53,5 @@ export interface LinkButtonProps extends Omit<ButtonProps, 'color' | 'isOutlined
  * // Underline variant with color
  * <LinkButton variant="underline" color="primary">Learn more</LinkButton>
  */
-export declare const LinkButton: import("react").ForwardRefExoticComponent<LinkButtonProps & import("react").RefAttributes<HTMLButtonElement | HTMLAnchorElement>>;
+export declare const LinkButton: PolymorphicComponent<LinkButtonOwnProps, "button">;
 export default LinkButton;

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

@@ -0,0 +1,138 @@
+import type React from 'react';
+/**
+ * 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.
+ */
+export declare function isCustomElement(as: unknown): as is string;
+/**
+ * The ref type of whatever element `as` renders.
+ *
+ * Derived from `ComponentPropsWithRef` rather than `React.ComponentRef` so it
+ * resolves on every `@types/react` a consumer may be on: this package supports
+ * React 18 and 19, and the CI matrix pins only `react`/`react-dom`, never the
+ * types, so a types-only regression here would not be caught.
+ *
+ * `never` when the target takes no ref. A plain function component has no `ref`
+ * key at all, and React's own types reject `<PlainFC ref={…} />`; without the
+ * guard the indexed access degraded to `unknown` and we accepted a ref that
+ * silently does nothing — `ref.current` stays null and a later `.focus()`
+ * throws. Matching React's strictness is the point.
+ */
+export type PolymorphicRef<T extends React.ElementType> = 'ref' extends keyof React.ComponentPropsWithRef<T> ? React.ComponentPropsWithRef<T>['ref'] : never;
+/**
+ * A component's own props, plus the attributes of the element `as` names.
+ *
+ * `Own` wins every collision — a component that declares `color` as a Bulma
+ * variant keeps it, rather than inheriting the DOM attribute of the same name.
+ * That subtraction is the ONLY one. `color` used to be dropped here as well, to
+ * stop the deprecated presentational HTML attribute reaching the three
+ * components whose own props do not declare one — but doing it in the shared
+ * type also stripped `color` from a CUSTOM target that legitimately has one.
+ * Those three declare `color?: never` themselves instead, which lands in
+ * `keyof Own` and reaches the same result without a special case here.
+ *
+ * Distributive over `T` on purpose. `Omit<A | B, K>` keys off `keyof (A | B)`,
+ * which is only what A and B share — so a union-typed `as` (a ternary, or a
+ * variable typed `'a' | 'button'`) silently lost every prop that belongs to
+ * just one member, `href` among them. Distributing produces a union of prop
+ * shapes instead, and each member keeps its own.
+ *
+ * Each component writes this intersection out in its own `*Props` alias rather
+ * than referring to this type: the API-docs extractor
+ * (`scripts/lib/props-extract.mjs`) walks heritage syntactically, and a generic
+ * alias leaves it resolving a type parameter it cannot see through.
+ * This type is here for the component's cast target and for consumers writing
+ * wrappers.
+ */
+export type PolymorphicProps<T extends React.ElementType, Own> = T extends unknown ? Own & Omit<React.ComponentPropsWithoutRef<T>, keyof Own | 'as'> & {
+    /** The element or component to render. */
+    as?: T;
+} : never;
+/**
+ * A component whose props and forwarded ref both follow `as`.
+ *
+ * `forwardRef` cannot express a generic component, so the implementation is
+ * cast to this. `displayName` is part of the type because the library sets it
+ * on every `forwardRef` component, and `withSubComponents` constrains its base
+ * to `{ displayName?: string }`.
+ *
+ * The second, non-generic signature exists for type DERIVATION rather than for
+ * calls. `React.ComponentProps<typeof Button>` infers from the last overload;
+ * with only the generic one it instantiated at the constraint and collapsed to
+ * `any`, so a consumer building their own prop type on ours lost every check.
+ * Calls still resolve against the generic signature first, so ordering here is
+ * load-bearing — swapping the two puts the collapse back.
+ *
+ * **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 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;
+ * ```
+ */
+export interface PolymorphicComponent<Own, Default extends React.ElementType> {
+    <T extends React.ElementType = Default>(props: PolymorphicProps<T, Own> & {
+        ref?: PolymorphicRef<T>;
+    }): React.ReactElement | null;
+    (props: PolymorphicProps<Default, Own> & {
+        ref?: PolymorphicRef<Default>;
+    }): React.ReactElement | null;
+    displayName?: string;
+}
+/**
+ * A component whose props follow `as` but which forwards no ref.
+ *
+ * For components that own the node they observe — `Reveal` keeps its own ref on
+ * the element it watches for scroll intersection, which is not always the
+ * element `as` names.
+ */
+export interface PolymorphicComponentWithoutRef<Own, Default extends React.ElementType> {
+    <T extends React.ElementType = Default>(props: PolymorphicProps<T, Own>): React.ReactElement | null;
+    (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,6 +100,7 @@ export type { FormFieldProps } from './form/fieldProps';
 export * from './grid/Cell';
 export * from './grid/Grid';
 export * from './helpers/classNames';
+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.0",
+  "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",

package/src/scss/CLAUDE.md

@@ -63,6 +63,6 @@ Rules the pattern encodes:
   prefix together: name your variables `<your-prefix>-*` or the matcher assigns them to
   nobody. After adding one, run `pnpm gen:api-sources` and confirm the component's
   `SCSS_SOURCES` entry is non-empty — an empty entry silently suppresses the API page's
-  CSS & Sass Variables section, which is how LinkButton shipped four variables invisibly
+  CSS & Sass Variables section, which is how LinkButton shipped its variables invisibly
   (#464). The orphan rule in `check:conformance` now fails on a partial that no component
   claims, so the miss is loud, but the fix is still yours to make.