@allxsmith/bestax-bulma 5.26.6 → 5.27.1

package/dist/esm/columns/Columns.js

@@ -0,0 +1,53 @@
+/* @allxsmith/bestax-bulma — AI agents: see AGENTS.md in the package root, or https://bestax.io/llms.txt */
+import { jsx } from 'react/jsx-runtime';
+import { usePrefixedClassNames, classNames } from '../helpers/classNames.js';
+import { withSubComponents } from '../helpers/withSubComponents.js';
+import { useBulmaClasses } from '../helpers/useBulmaClasses.js';
+import { Column } from './Column.js';
+
+/**
+ * The `Columns` component provides Bulma's flexible, responsive grid container for aligning and distributing [`Column`](./column.md) components.
+ *
+ * @function
+ * @param {ColumnsProps} props - Props for the Columns component.
+ * @returns {JSX.Element} The rendered columns container.
+ * @see {@link https://bulma.io/documentation/columns/ | Bulma Columns documentation}
+ */
+const ColumnsComponent = ({ className, textColor, color: _fieldColor, bgColor, isCentered, isGapless, isMultiline, isVCentered, isMobile, isDesktop, gap, gapMobile, gapTablet, gapDesktop, gapWidescreen, gapFullhd, gapSize, gapSizeMobile, gapSizeTablet, gapSizeDesktop, gapSizeWidescreen, gapSizeFullhd, children, ...props }) => {
+    const resolvedGap = gap ?? gapSize;
+    const resolvedGapMobile = gapMobile ?? gapSizeMobile;
+    const resolvedGapTablet = gapTablet ?? gapSizeTablet;
+    const resolvedGapDesktop = gapDesktop ?? gapSizeDesktop;
+    const resolvedGapWidescreen = gapWidescreen ?? gapSizeWidescreen;
+    const resolvedGapFullhd = gapFullhd ?? gapSizeFullhd;
+    // Untyped code can still pass the gap helpers ColumnsProps leaves out. They
+    // are dropped here, so they render no class and never reach the DOM.
+    const { columnGap: _columnGap, rowGap: _rowGap, ...helperProps } = props;
+    const { bulmaHelperClasses, rest } = useBulmaClasses({
+        color: textColor,
+        backgroundColor: bgColor,
+        ...helperProps,
+    });
+    const mainClass = usePrefixedClassNames('columns');
+    // Build gap classes with prefixes
+    const gapClasses = usePrefixedClassNames('', {
+        [`is-${resolvedGap}`]: resolvedGap !== undefined && resolvedGap !== null,
+        [`is-${resolvedGapMobile}-mobile`]: resolvedGapMobile !== undefined && resolvedGapMobile !== null,
+        [`is-${resolvedGapTablet}-tablet`]: resolvedGapTablet !== undefined && resolvedGapTablet !== null,
+        [`is-${resolvedGapDesktop}-desktop`]: resolvedGapDesktop !== undefined && resolvedGapDesktop !== null,
+        [`is-${resolvedGapWidescreen}-widescreen`]: resolvedGapWidescreen !== undefined && resolvedGapWidescreen !== null,
+        [`is-${resolvedGapFullhd}-fullhd`]: resolvedGapFullhd !== undefined && resolvedGapFullhd !== null,
+        'is-centered': !!isCentered,
+        'is-gapless': !!isGapless,
+        'is-multiline': !!isMultiline,
+        'is-vcentered': !!isVCentered,
+        'is-mobile': !!isMobile,
+        'is-desktop': !!isDesktop,
+    });
+    const columnsClasses = classNames(mainClass, gapClasses, className, bulmaHelperClasses);
+    return (jsx("div", { className: columnsClasses, ...rest, children: children }));
+};
+const Columns = withSubComponents(ColumnsComponent, { Column }, 'Columns');
+
+export { Columns };
+//# sourceMappingURL=Columns.js.map

package/dist/esm/columns/Columns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Columns.js","sources":["../../../src/columns/Columns.tsx"],"sourcesContent":["import React from 'react';\nimport { classNames, usePrefixedClassNames } from '../helpers/classNames';\nimport { withSubComponents } from '../helpers/withSubComponents';\nimport {\n  useBulmaClasses,\n  BulmaClassesProps,\n  validColors,\n} from '../helpers/useBulmaClasses';\nimport type { BulmaGapValue } from '../grid/Grid';\nimport { Column } from './Column';\n\n/**\n * Possible values for the Bulma columns gap size.\n * @deprecated Use {@link BulmaGapValue} instead — `gapSize*` and `gap*` share\n * the same 0-8 scale.\n */\nexport type BulmaGapSize = BulmaGapValue;\n\n/**\n * Props for the Columns component.\n */\nexport interface ColumnsProps\n  extends\n    React.HTMLAttributes<HTMLDivElement>,\n    // The column and row gap helpers are left out, as the `gap` helper is: the\n    // gutter is padding inside each column, so CSS `gap` would add to it, and\n    // only from the tablet width up, where `.columns` is flex.\n    Omit<\n      BulmaClassesProps,\n      'color' | 'backgroundColor' | 'columnGap' | 'rowGap'\n    > {\n  /** Additional CSS classes for the columns container. */\n  className?: string;\n  /** Text color. */\n  textColor?: (typeof validColors)[number] | 'inherit' | 'current';\n  /** Bulma color modifier for all columns. */\n  color?: 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger';\n  /** Background color for all columns. */\n  bgColor?: (typeof validColors)[number] | 'inherit' | 'current';\n  /** Horizontally center columns within the container. */\n  isCentered?: boolean;\n  /** Remove gap between columns. */\n  isGapless?: boolean;\n  /** Allow columns to wrap to multiple lines. */\n  isMultiline?: boolean;\n  /** Vertically center columns within the container. */\n  isVCentered?: boolean;\n  /** Apply columns layout on mobile and up. */\n  isMobile?: boolean;\n  /** Apply columns layout on desktop and up. */\n  isDesktop?: boolean;\n\n  /**\n   * Gap size for all breakpoints, the columns gutter (`is-<value>`). Whole\n   * steps of the same scale as `Grid`'s `gap` prop; wins over `gapSize` if\n   * both are set.\n   *\n   * This is not the `gap` helper prop other components take, which renders\n   * `is-gap-<value>`: on `Columns` the gutter is padding inside each column,\n   * so the helper's CSS `gap` would add to it rather than replace it.\n   */\n  gap?: BulmaGapValue;\n  /** Gap size for mobile. Wins over `gapSizeMobile` if both are set. */\n  gapMobile?: BulmaGapValue;\n  /** Gap size for tablet. Wins over `gapSizeTablet` if both are set. */\n  gapTablet?: BulmaGapValue;\n  /** Gap size for desktop. Wins over `gapSizeDesktop` if both are set. */\n  gapDesktop?: BulmaGapValue;\n  /** Gap size for widescreen. Wins over `gapSizeWidescreen` if both are set. */\n  gapWidescreen?: BulmaGapValue;\n  /** Gap size for fullhd. Wins over `gapSizeFullhd` if both are set. */\n  gapFullhd?: BulmaGapValue;\n\n  /** Gap size for all breakpoints. @deprecated Use `gap` instead — `gap` wins if both are set. */\n  gapSize?: BulmaGapSize;\n  /** Gap size for mobile. @deprecated Use `gapMobile` instead — `gapMobile` wins if both are set. */\n  gapSizeMobile?: BulmaGapSize;\n  /** Gap size for tablet. @deprecated Use `gapTablet` instead — `gapTablet` wins if both are set. */\n  gapSizeTablet?: BulmaGapSize;\n  /** Gap size for desktop. @deprecated Use `gapDesktop` instead — `gapDesktop` wins if both are set. */\n  gapSizeDesktop?: BulmaGapSize;\n  /** Gap size for widescreen. @deprecated Use `gapWidescreen` instead — `gapWidescreen` wins if both are set. */\n  gapSizeWidescreen?: BulmaGapSize;\n  /** Gap size for fullhd. @deprecated Use `gapFullhd` instead — `gapFullhd` wins if both are set. */\n  gapSizeFullhd?: BulmaGapSize;\n\n  /** Columns to render within the container. */\n  children?: React.ReactNode;\n}\n\n/**\n * The `Columns` component provides Bulma's flexible, responsive grid container for aligning and distributing [`Column`](./column.md) components.\n *\n * @function\n * @param {ColumnsProps} props - Props for the Columns component.\n * @returns {JSX.Element} The rendered columns container.\n * @see {@link https://bulma.io/documentation/columns/ | Bulma Columns documentation}\n */\nconst ColumnsComponent: React.FC<ColumnsProps> = ({\n  className,\n  textColor,\n  color: _fieldColor,\n  bgColor,\n  isCentered,\n  isGapless,\n  isMultiline,\n  isVCentered,\n  isMobile,\n  isDesktop,\n  gap,\n  gapMobile,\n  gapTablet,\n  gapDesktop,\n  gapWidescreen,\n  gapFullhd,\n  gapSize,\n  gapSizeMobile,\n  gapSizeTablet,\n  gapSizeDesktop,\n  gapSizeWidescreen,\n  gapSizeFullhd,\n  children,\n  ...props\n}) => {\n  const resolvedGap = gap ?? gapSize;\n  const resolvedGapMobile = gapMobile ?? gapSizeMobile;\n  const resolvedGapTablet = gapTablet ?? gapSizeTablet;\n  const resolvedGapDesktop = gapDesktop ?? gapSizeDesktop;\n  const resolvedGapWidescreen = gapWidescreen ?? gapSizeWidescreen;\n  const resolvedGapFullhd = gapFullhd ?? gapSizeFullhd;\n\n  // Untyped code can still pass the gap helpers ColumnsProps leaves out. They\n  // are dropped here, so they render no class and never reach the DOM.\n  const {\n    columnGap: _columnGap,\n    rowGap: _rowGap,\n    ...helperProps\n  } = props as typeof props & { columnGap?: unknown; rowGap?: unknown };\n\n  const { bulmaHelperClasses, rest } = useBulmaClasses({\n    color: textColor,\n    backgroundColor: bgColor,\n    ...helperProps,\n  });\n\n  const mainClass = usePrefixedClassNames('columns');\n\n  // Build gap classes with prefixes\n  const gapClasses = usePrefixedClassNames('', {\n    [`is-${resolvedGap}`]: resolvedGap !== undefined && resolvedGap !== null,\n    [`is-${resolvedGapMobile}-mobile`]:\n      resolvedGapMobile !== undefined && resolvedGapMobile !== null,\n    [`is-${resolvedGapTablet}-tablet`]:\n      resolvedGapTablet !== undefined && resolvedGapTablet !== null,\n    [`is-${resolvedGapDesktop}-desktop`]:\n      resolvedGapDesktop !== undefined && resolvedGapDesktop !== null,\n    [`is-${resolvedGapWidescreen}-widescreen`]:\n      resolvedGapWidescreen !== undefined && resolvedGapWidescreen !== null,\n    [`is-${resolvedGapFullhd}-fullhd`]:\n      resolvedGapFullhd !== undefined && resolvedGapFullhd !== null,\n    'is-centered': !!isCentered,\n    'is-gapless': !!isGapless,\n    'is-multiline': !!isMultiline,\n    'is-vcentered': !!isVCentered,\n    'is-mobile': !!isMobile,\n    'is-desktop': !!isDesktop,\n  });\n\n  const columnsClasses = classNames(\n    mainClass,\n    gapClasses,\n    className,\n    bulmaHelperClasses\n  );\n\n  return (\n    <div className={columnsClasses} {...rest}>\n      {children}\n    </div>\n  );\n};\n\nexport const Columns = withSubComponents(\n  ColumnsComponent,\n  { Column },\n  'Columns'\n);\n"],"names":["_jsx"],"mappings":";;;;;;;AA0FA;;;;;;;AAOG;AACH,MAAM,gBAAgB,GAA2B,CAAC,EAChD,SAAS,EACT,SAAS,EACT,KAAK,EAAE,WAAW,EAClB,OAAO,EACP,UAAU,EACV,SAAS,EACT,WAAW,EACX,WAAW,EACX,QAAQ,EACR,SAAS,EACT,GAAG,EACH,SAAS,EACT,SAAS,EACT,UAAU,EACV,aAAa,EACb,SAAS,EACT,OAAO,EACP,aAAa,EACb,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,QAAQ,EACR,GAAG,KAAK,EACT,KAAI;AACH,IAAA,MAAM,WAAW,GAAG,GAAG,IAAI,OAAO;AAClC,IAAA,MAAM,iBAAiB,GAAG,SAAS,IAAI,aAAa;AACpD,IAAA,MAAM,iBAAiB,GAAG,SAAS,IAAI,aAAa;AACpD,IAAA,MAAM,kBAAkB,GAAG,UAAU,IAAI,cAAc;AACvD,IAAA,MAAM,qBAAqB,GAAG,aAAa,IAAI,iBAAiB;AAChE,IAAA,MAAM,iBAAiB,GAAG,SAAS,IAAI,aAAa;;;AAIpD,IAAA,MAAM,EACJ,SAAS,EAAE,UAAU,EACrB,MAAM,EAAE,OAAO,EACf,GAAG,WAAW,EACf,GAAG,KAAiE;AAErE,IAAA,MAAM,EAAE,kBAAkB,EAAE,IAAI,EAAE,GAAG,eAAe,CAAC;AACnD,QAAA,KAAK,EAAE,SAAS;AAChB,QAAA,eAAe,EAAE,OAAO;AACxB,QAAA,GAAG,WAAW;AACf,KAAA,CAAC;AAEF,IAAA,MAAM,SAAS,GAAG,qBAAqB,CAAC,SAAS,CAAC;;AAGlD,IAAA,MAAM,UAAU,GAAG,qBAAqB,CAAC,EAAE,EAAE;QAC3C,CAAC,CAAA,GAAA,EAAM,WAAW,CAAA,CAAE,GAAG,WAAW,KAAK,SAAS,IAAI,WAAW,KAAK,IAAI;QACxE,CAAC,CAAA,GAAA,EAAM,iBAAiB,CAAA,OAAA,CAAS,GAC/B,iBAAiB,KAAK,SAAS,IAAI,iBAAiB,KAAK,IAAI;QAC/D,CAAC,CAAA,GAAA,EAAM,iBAAiB,CAAA,OAAA,CAAS,GAC/B,iBAAiB,KAAK,SAAS,IAAI,iBAAiB,KAAK,IAAI;QAC/D,CAAC,CAAA,GAAA,EAAM,kBAAkB,CAAA,QAAA,CAAU,GACjC,kBAAkB,KAAK,SAAS,IAAI,kBAAkB,KAAK,IAAI;QACjE,CAAC,CAAA,GAAA,EAAM,qBAAqB,CAAA,WAAA,CAAa,GACvC,qBAAqB,KAAK,SAAS,IAAI,qBAAqB,KAAK,IAAI;QACvE,CAAC,CAAA,GAAA,EAAM,iBAAiB,CAAA,OAAA,CAAS,GAC/B,iBAAiB,KAAK,SAAS,IAAI,iBAAiB,KAAK,IAAI;QAC/D,aAAa,EAAE,CAAC,CAAC,UAAU;QAC3B,YAAY,EAAE,CAAC,CAAC,SAAS;QACzB,cAAc,EAAE,CAAC,CAAC,WAAW;QAC7B,cAAc,EAAE,CAAC,CAAC,WAAW;QAC7B,WAAW,EAAE,CAAC,CAAC,QAAQ;QACvB,YAAY,EAAE,CAAC,CAAC,SAAS;AAC1B,KAAA,CAAC;AAEF,IAAA,MAAM,cAAc,GAAG,UAAU,CAC/B,SAAS,EACT,UAAU,EACV,SAAS,EACT,kBAAkB,CACnB;IAED,QACEA,GAAA,CAAA,KAAA,EAAA,EAAK,SAAS,EAAE,cAAc,EAAA,GAAM,IAAI,EAAA,QAAA,EACrC,QAAQ,EAAA,CACL;AAEV,CAAC;AAEM,MAAM,OAAO,GAAG,iBAAiB,CACtC,gBAAgB,EAChB,EAAE,MAAM,EAAE,EACV,SAAS;;"}

package/dist/esm/components/Avatar.js

@@ -0,0 +1,299 @@
+/* @allxsmith/bestax-bulma — AI agents: see AGENTS.md in the package root, or https://bestax.io/llms.txt */
+import { jsxs, jsx } from 'react/jsx-runtime';
+import { forwardRef, useState, useRef, useEffect } from 'react';
+import { usePrefixedClassNames, classNames } from '../helpers/classNames.js';
+import { useBulmaClasses } from '../helpers/useBulmaClasses.js';
+import { buttonType } from '../helpers/buttonType.js';
+import { isCustomElement } from '../helpers/polymorphic.js';
+import { warnOnce } from '../helpers/devWarnings.js';
+
+const avatarColors = [
+    'primary',
+    'link',
+    'info',
+    'success',
+    'warning',
+    'danger',
+    'black',
+    'dark',
+    'light',
+    'white',
+];
+const autoAvatarColors = [
+    'primary',
+    'link',
+    'info',
+    'success',
+    'warning',
+    'danger',
+];
+const avatarSizes = [
+    '16x16',
+    '24x24',
+    '32x32',
+    '48x48',
+    '64x64',
+    '96x96',
+    '128x128',
+];
+/**
+ * The roles a caller can use to say "this avatar is not a control", and so claim
+ * the non-interactive treatment for a custom `as` target we would otherwise have
+ * to guess about.
+ *
+ * Read by VALUE, not by presence. Any role at all used to count, which let
+ * `role="button"` — a claim of the opposite — route a real control into the
+ * decorative branch and come out `aria-hidden` and nameless. `img` is what the
+ * fallback itself applies; `presentation` and `none` are the standard ways to say
+ * an element carries no semantics, which is what pairs with `alt=""`.
+ */
+const NON_INTERACTIVE_ROLES = [
+    'img',
+    'presentation',
+    'none',
+];
+/**
+ * Elements other than `a` that declare `target` themselves, so on them it is
+ * the element's own attribute and not a link attribute Avatar withholds for
+ * want of one. The link attribute warning leaves `target` out on these, the way
+ * it leaves `rel` out everywhere. `area` and `base` are void elements, which
+ * Avatar's content rules out, so `form` is the one a caller can reach.
+ */
+const ELEMENTS_WITH_OWN_TARGET = [
+    'form',
+    'area',
+    'base',
+];
+/**
+ * Derives a small set of initials from a name (e.g. "Ada Lovelace" -> "AL").
+ */
+function getInitialsFromName(name) {
+    const words = name.trim().split(/\s+/).filter(Boolean);
+    if (words.length === 0)
+        return '';
+    // Iterate by code point (Array.from) so astral-plane characters (emoji, some
+    // CJK) don't get split into half surrogates.
+    if (words.length === 1) {
+        return Array.from(words[0]).slice(0, 2).join('').toUpperCase();
+    }
+    const first = Array.from(words[0])[0];
+    const last = Array.from(words[words.length - 1])[0];
+    return (first + last).toUpperCase();
+}
+/**
+ * Deterministically hashes a string to pick one of the auto avatar colors.
+ */
+function getAutoColor(name) {
+    let hash = 0;
+    for (let i = 0; i < name.length; i++) {
+        hash = (hash << 5) - hash + name.charCodeAt(i);
+        hash |= 0;
+    }
+    const index = Math.abs(hash) % autoAvatarColors.length;
+    return autoAvatarColors[index];
+}
+/**
+ * Default generic avatar icon shown when there is no image, name, initials, or icon.
+ */
+function DefaultAvatarIcon() {
+    return (jsx("svg", { viewBox: "0 0 24 24", width: "60%", height: "60%", "aria-hidden": "true", children: jsx("path", { fill: "currentColor", d: "M12 12a5 5 0 1 0 0-10 5 5 0 0 0 0 10Zm0 2c-4.42 0-9 2.24-9 5v2a1 1 0 0 0 1 1h16a1 1 0 0 0 1-1v-2c0-2.76-4.58-5-9-5Z" }) }));
+}
+/**
+ * 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
+ * <Avatar src="/users/ada.jpg" name="Ada Lovelace" size="64x64" />
+ * @example
+ * <Avatar name="Grace Hopper" />
+ */
+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
+    // keyed by src so a swap discards the old DOM node — a late error event
+    // from the previous request can't fire on a retained node and latch the
+    // replacement src as failed.
+    const [erroredSrc, setErroredSrc] = useState(undefined);
+    const [prevSrc, setPrevSrc] = useState(src);
+    if (src !== prevSrc) {
+        setPrevSrc(src);
+        setErroredSrc(undefined);
+    }
+    const imgRef = useRef(null);
+    const { bulmaHelperClasses, rest } = useBulmaClasses(props);
+    const showImage = !!src && src !== erroredSrc;
+    // Catch images that failed before hydration: in SSR/static pages a broken
+    // image can finish loading before React attaches its onError, so it never
+    // fires. A complete image with no intrinsic width is a load failure.
+    useEffect(() => {
+        const img = imgRef.current;
+        if (img && img.complete && img.naturalWidth === 0) {
+            setErroredSrc(src);
+        }
+    }, [src]);
+    const resolvedInitials = initials
+        ? initials.toUpperCase()
+        : name
+            ? getInitialsFromName(name)
+            : '';
+    const showInitials = !showImage && !!resolvedInitials;
+    const showIcon = !showImage && !showInitials && !!icon;
+    const showDefaultIcon = !showImage && !showInitials && !showIcon;
+    const resolvedColor = color ?? (name ? getAutoColor(name) : undefined);
+    const isPresetSize = typeof size === 'string' && avatarSizes.includes(size);
+    const sizeStyle = typeof size === 'number'
+        ? { width: size, height: size, fontSize: size / 2.5 }
+        : undefined;
+    const avatarClasses = usePrefixedClassNames('avatar', {
+        [`is-${size}`]: isPresetSize,
+        [`is-${shape}`]: shape,
+        [`is-${resolvedColor}`]: resolvedColor && !showImage && avatarColors.includes(resolvedColor),
+    });
+    const combinedClasses = classNames(avatarClasses, bulmaHelperClasses, className);
+    const initialsClass = usePrefixedClassNames('avatar-initials');
+    const Tag = as ?? (href ? 'a' : 'figure');
+    // A custom component counts as interactive whether or not it was given OUR
+    // href: a router link takes `to`, creates the anchor itself, and cannot be
+    // classified from the props it arrives with (#668). Marking a real link as a
+    // picture is the worse failure — and `alt=""` would go further and mark it
+    // decorative (aria-hidden), leaving it nameless.
+    //
+    // A custom ELEMENT still needs the href. A hyphenated tag renders a real DOM
+    // element of that name, so nothing is hidden from us: without a link to follow
+    // it is still a picture. `Navbar.Link` draws the same line for `role="button"`.
+    //
+    // Where we are guessing, the caller settles it: an explicit `role` or
+    // `aria-hidden` states the semantics, so a custom component that really is a
+    // wrapper gets `role="img"` and its `alt=""` opt-out back. `role` alone would
+    // be a half-override — interactivity also drives the decorative opt-out and the
+    // name fallback, and overriding one of the three is worse than overriding none.
+    //
+    // An `href` ENDS the guess, so it outranks the signal. `as="a"`, `as="button"`
+    // and a target we were handed an href for are known to be interactive, and there
+    // the rule that an interactive element always carries an accessible name is not
+    // the caller's to waive: without this, `as={RouterLink} href="/x" role="img"`
+    // with `alt=""` rendered a real anchor as `aria-hidden` and nameless — the very
+    // failure #668 is about. `Navbar.Link` orders the same two the same way.
+    //
+    // The signal has to MEAN what it is used for, so both halves read a value rather
+    // than a presence — the way `Navbar.Link` reads `role === 'button'`. A role only
+    // claims to be a picture if it says so: `role="button"` or `role="link"` is the
+    // opposite claim, and taking any role as the signal handed an interactive-role
+    // element `aria-hidden` and no name. Likewise `aria-hidden={false}` denies
+    // hiding, so only a truthy one counts.
+    const ariaHidden = rest['aria-hidden'];
+    const statesItIsNotAControl = (rest.role !== undefined && NON_INTERACTIVE_ROLES.includes(rest.role)) ||
+        ariaHidden === true ||
+        ariaHidden === 'true';
+    const customTargetStatesSemantics = typeof Tag !== 'string' && href == null && statesItIsNotAControl;
+    const isInteractive = Tag === 'a' ||
+        Tag === 'button' ||
+        (typeof Tag !== 'string' && !customTargetStatesSemantics) ||
+        (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' || isCustomElement(Tag);
+    // A plain element like a `div` declares no `href` or `target`, so the type
+    // accepts them as Avatar's own while the drop below withholds them, and
+    // without this they would vanish in silence (#733). Forwarding them would put
+    // them where HTML has no such attribute, so the drop stays and development
+    // reports it instead, naming only the ones actually passed.
+    //
+    // `rel` is withheld too but left out here. React declares it on every
+    // element, so on a plain `as` it is that element's own attribute, and
+    // "render it as a link" would be the wrong advice for it. `target` is the
+    // same on an element that declares it, such as `form`, so it is left out
+    // there. Whether to forward either one to such an element is a separate
+    // question from this warning.
+    //
+    // Only for an `as` the caller wrote. Without one the element is Avatar's own
+    // choice, and a message naming an `as` they never passed sends them looking
+    // for it. A value counts when it is truthy, the same test that picks `'a'`
+    // over `'figure'`, so an empty `href` from data asks for no link and draws no
+    // warning. The key is the element plus the attributes passed, so a re-render
+    // or a list of avatars warns once, while a different combination on the same
+    // element still gets its own warning rather than hiding behind the first.
+    //
+    // Development-only is `warnOnce`'s job, as it is for the colour warnings, so
+    // this block has no production check of its own. One here would have to read
+    // `process` safely, and a `typeof process` test is not something a bundler
+    // replaces: in a browser it is false, and the warning never fired in the
+    // development builds it exists for. The cost is that production still
+    // collects the attributes and builds the message for an avatar that needs
+    // it, which is small and limited to the case the warning is about.
+    if (as != null && !isLinkLike) {
+        const dropped = Object.entries({
+            href,
+            target: ELEMENTS_WITH_OWN_TARGET.includes(as) ? undefined : target,
+        })
+            .filter(([, value]) => value)
+            .map(([key]) => key);
+        if (dropped.length > 0) {
+            warnOnce(`Avatar:link-props-on-${as}:${dropped.join('+')}`, `[bestax-bulma] <Avatar as="${as}" ${dropped.join(' ')}>: this ` +
+                `<${as}> renders without ` +
+                `${dropped.map(key => `"${key}"`).join(' and ')}, because Avatar ` +
+                `passes link attributes on only to a target that can be a link (an ` +
+                `"a", a custom element, or a component). To make it a link, render ` +
+                `it as="a" or pass a link component to "as".`);
+        }
+    }
+    // Present-only, not `{ href, target, rel }`. An unconditional spread hands the
+    // target these keys whatever the caller passed, and a key existing is not free:
+    // a target that tests for one sees a link where there is none, and one that
+    // spreads its own `{...rest}` onward passes the nothing along. It is NOT about
+    // a destructuring default, which an explicit `undefined` triggers just as an
+    // absent key does. What stops a target that REQUIRES one from being rendered
+    // without it is the type (#665) — this is the smaller half, and the backstop for
+    // the callers a type does not reach: a plain-JavaScript one and a loose spread,
+    // the same pair `Button` and `Menu.Item` keep their own filters for.
+    const linkProps = isLinkLike
+        ? {
+            ...(href !== undefined && { href }),
+            ...(target !== undefined && { target }),
+            ...(rel !== undefined && { rel }),
+        }
+        : {};
+    // alt coalesces with ?? (not ||) so an explicit alt="" survives as the
+    // standard decorative marker instead of being overridden by name.
+    const accessibleName = alt ?? name;
+    // The decorative opt-out never applies to an interactive avatar — a link or
+    // button must always expose an accessible name.
+    const isDecorative = alt === '' && !isInteractive;
+    const a11yDefaults = showImage
+        ? isInteractive && !accessibleName
+            ? // The img alt normally names the control; with no alt/name (an API
+                // returning only a photo URL) the link/button would be nameless.
+                { 'aria-label': name || 'Avatar' }
+            : {}
+        : isDecorative
+            ? { 'aria-hidden': true }
+            : {
+                ...(isInteractive ? {} : { role: 'img' }),
+                'aria-label': accessibleName || name || 'Avatar',
+            };
+    // Each default yields to a value the caller passed, and is applied after
+    // `rest` reading through it rather than spread before it. React treats an
+    // `undefined` attribute as "remove it", and a spread carrying the key with no
+    // value is how that arrives, so a default spread first was erased by it: an
+    // `aria-label: undefined` left a button avatar nameless, and `role` and
+    // `aria-hidden` went the same way. The button `type` below has the same
+    // shape (#690).
+    const a11yProps = Object.fromEntries(Object.entries(a11yDefaults).map(([key, fallback]) => [
+        key,
+        rest[key] ?? fallback,
+    ]));
+    return (jsxs(Tag, { ref: ref, className: combinedClasses, style: { ...sizeStyle, ...style }, ...linkProps, ...rest, ...a11yProps, ...(Tag === 'button' ? { type: buttonType(rest.type) } : {}), 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';
+
+export { Avatar };
+//# sourceMappingURL=Avatar.js.map

package/dist/esm/components/Avatar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Avatar.js","sources":["../../../src/components/Avatar.tsx"],"sourcesContent":["import React, { forwardRef, useEffect, useRef, useState } from 'react';\nimport { classNames, usePrefixedClassNames } from '../helpers/classNames';\nimport { useBulmaClasses, BulmaClassesProps } from '../helpers/useBulmaClasses';\nimport { buttonType } from '../helpers/buttonType';\nimport {\n  isCustomElement,\n  type PolymorphicComponent,\n} from '../helpers/polymorphic';\nimport { warnOnce } from '../helpers/devWarnings';\n\nconst avatarColors = [\n  'primary',\n  'link',\n  'info',\n  'success',\n  'warning',\n  'danger',\n  'black',\n  'dark',\n  'light',\n  'white',\n] as const;\n\n/** Valid color values for the Avatar component. */\nexport type AvatarColor = (typeof avatarColors)[number];\n\nconst autoAvatarColors: AvatarColor[] = [\n  'primary',\n  'link',\n  'info',\n  'success',\n  'warning',\n  'danger',\n];\n\nconst avatarSizes = [\n  '16x16',\n  '24x24',\n  '32x32',\n  '48x48',\n  '64x64',\n  '96x96',\n  '128x128',\n] as const;\n\n/** Valid preset size values for the Avatar component. */\nexport type AvatarSize = (typeof avatarSizes)[number];\n\n/**\n * The roles a caller can use to say \"this avatar is not a control\", and so claim\n * the non-interactive treatment for a custom `as` target we would otherwise have\n * to guess about.\n *\n * Read by VALUE, not by presence. Any role at all used to count, which let\n * `role=\"button\"` — a claim of the opposite — route a real control into the\n * decorative branch and come out `aria-hidden` and nameless. `img` is what the\n * fallback itself applies; `presentation` and `none` are the standard ways to say\n * an element carries no semantics, which is what pairs with `alt=\"\"`.\n */\nconst NON_INTERACTIVE_ROLES: readonly string[] = [\n  'img',\n  'presentation',\n  'none',\n];\n\n/**\n * Elements other than `a` that declare `target` themselves, so on them it is\n * the element's own attribute and not a link attribute Avatar withholds for\n * want of one. The link attribute warning leaves `target` out on these, the way\n * it leaves `rel` out everywhere. `area` and `base` are void elements, which\n * Avatar's content rules out, so `form` is the one a caller can reach.\n */\nconst ELEMENTS_WITH_OWN_TARGET: readonly React.ElementType[] = [\n  'form',\n  'area',\n  'base',\n];\n\n/** Valid shape values for the Avatar component. */\nexport type AvatarShape = 'circle' | 'rounded' | 'square';\n\n/**\n * Derives a small set of initials from a name (e.g. \"Ada Lovelace\" -> \"AL\").\n */\nfunction getInitialsFromName(name: string): string {\n  const words = name.trim().split(/\\s+/).filter(Boolean);\n  if (words.length === 0) return '';\n  // Iterate by code point (Array.from) so astral-plane characters (emoji, some\n  // CJK) don't get split into half surrogates.\n  if (words.length === 1) {\n    return Array.from(words[0]).slice(0, 2).join('').toUpperCase();\n  }\n  const first = Array.from(words[0])[0];\n  const last = Array.from(words[words.length - 1])[0];\n  return (first + last).toUpperCase();\n}\n\n/**\n * Deterministically hashes a string to pick one of the auto avatar colors.\n */\nfunction getAutoColor(name: string): AvatarColor {\n  let hash = 0;\n  for (let i = 0; i < name.length; i++) {\n    hash = (hash << 5) - hash + name.charCodeAt(i);\n    hash |= 0;\n  }\n  const index = Math.abs(hash) % autoAvatarColors.length;\n  return autoAvatarColors[index];\n}\n\n/**\n * Default generic avatar icon shown when there is no image, name, initials, or icon.\n */\nfunction DefaultAvatarIcon() {\n  return (\n    <svg viewBox=\"0 0 24 24\" width=\"60%\" height=\"60%\" aria-hidden=\"true\">\n      <path\n        fill=\"currentColor\"\n        d=\"M12 12a5 5 0 1 0 0-10 5 5 0 0 0 0 10Zm0 2c-4.42 0-9 2.24-9 5v2a1 1 0 0 0 1 1h16a1 1 0 0 0 1-1v-2c0-2.76-4.58-5-9-5Z\"\n      />\n    </svg>\n  );\n}\n\n/**\n * The Avatar component's own props — everything it adds on top of the\n * attributes of whatever element `as` renders.\n */\nexport interface AvatarOwnProps extends Omit<BulmaClassesProps, 'color'> {\n  /** Additional CSS classes to apply. */\n  className?: string;\n  /** Image URL. On load error (or if absent), falls back to initials, then `icon`. */\n  src?: string;\n  /**\n   * Alternate text for the image (used for the accessible name in every render mode). An\n   * explicit `alt=\"\"` marks a non-interactive avatar as decorative.\n   *\n   * A link or button avatar is never decorative — it keeps an accessible name — and a custom\n   * component passed to `as` counts as one unless it states otherwise, so `alt=\"\"` on a custom\n   * wrapper needs that signal alongside it. `as` documents which props carry it.\n   */\n  alt?: string;\n  /** Derives initials and a deterministic background color when no `src` is shown. */\n  name?: string;\n  /** Explicit initials override (else derived from `name`). */\n  initials?: string;\n  /** Final fallback, rendered when there is no `src`, `name`, or `initials`. */\n  icon?: React.ReactNode;\n  /** Preset size, or a pixel size when a number. */\n  size?: AvatarSize | number;\n  /** Avatar shape. Default `'circle'`. */\n  shape?: AvatarShape;\n  /** Background color for initials/icon avatars (else auto-derived from `name`). */\n  color?: AvatarColor;\n  /**\n   * When set, renders the avatar as a link: an `<a>` unless `as` names the element itself. An\n   * `as` target declaring its own `href` supersedes this one, and its type and its requiredness\n   * are what apply.\n   *\n   * It is passed on only to a target that can be a link: an `a`, a custom element, or a\n   * component. Any other `as` you pass, such as `'figure'` or `'div'`, still accepts it but\n   * renders without it, because an `href` is not valid HTML on those elements, and a\n   * development build logs a console warning naming what was dropped. To make such an avatar a\n   * link, render it `as=\"a\"` or pass a link component to `as`. An empty `href` asks for no link:\n   * with no `as` it renders a `<figure>`, and it draws no warning.\n   */\n  href?: string;\n  /** Anchor target, passed on only where `href` is (an `a`, a custom element, or a component) and superseded by the target's own declaration the way `href` is. Any other `as` you pass renders without it, with the same development warning as `href`, except `'form'`: it declares its own `target`, so there the attribute is still withheld but draws no warning. */\n  target?: string;\n  /** Anchor rel, passed on only where `href` is (an `a`, a custom element, or a component) and superseded by the target's own declaration the way `href` is. */\n  rel?: string;\n  /** Extra props forwarded to the underlying `<img>` (e.g. `loading`, `crossOrigin`); its `onError` is chained before the fallback fires. */\n  imageProps?: React.ImgHTMLAttributes<HTMLImageElement>;\n  /** Inline styles, merged after the size style. */\n  style?: React.CSSProperties;\n  /**\n   * Not accepted. Avatar always renders its own content — the image, the\n   * initials, or the icon — so anything a caller passed would be replaced. It\n   * is declared unavailable rather than derived from `as`, which would let a\n   * target requiring `children` compel a value it then never receives.\n   * @internal\n   */\n  children?: never;\n}\n\n/**\n * The own props Avatar hands to the element `as` names rather than consuming.\n *\n * They are what *chooses* the element when `as` is absent — an `<a>` with an\n * `href`, a `<figure>` without one — so Avatar has to accept them before `as` is\n * known. Declaring them is only half of it. `PolymorphicProps` explains what\n * naming them here buys, and what leaving them unnamed cost (#665).\n */\ntype AvatarForwardedProp = 'href' | 'target' | 'rel';\n\n/**\n * Props for the Avatar component. The DOM attributes and the `ref` both follow\n * `as`.\n *\n * `href`, `target` and `rel` are Avatar's own props only for a target that has\n * none of its own: `<Avatar href=\"/x\" />` needs no `as`, while\n * `<Avatar as={NextLink} />` takes `next/link`'s `href` — required, and a URL\n * object as readily as a string.\n *\n * The type parameter defaults to `'figure'`, not to `React.ElementType`.\n * Defaulting to the constraint sounds truer to a runtime default that is\n * conditional, but `ComponentPropsWithoutRef<React.ElementType>` spreads across\n * every element at once and accepts anything — which is the false-positive this\n * whole change exists to remove. `'figure'` is the element a no-`href` avatar\n * actually renders, and the anchor props it can additionally take are declared\n * above.\n *\n * @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.\n */\nexport type AvatarProps<T extends React.ElementType = 'figure'> = Omit<\n  AvatarOwnProps,\n  Extract<AvatarForwardedProp, keyof React.ComponentPropsWithoutRef<T>>\n> &\n  Omit<\n    React.ComponentPropsWithoutRef<T>,\n    Exclude<keyof AvatarOwnProps, AvatarForwardedProp> | 'as'\n  > & {\n    /**\n     * Element/component to render as. Defaults to `'a'` when `href` is set, else `'figure'`.\n     *\n     * This also decides whether the avatar is treated as interactive, which is what keeps\n     * `role=\"img\"` and the `alt=\"\"` decorative opt-out off a link or button. A custom\n     * component counts — a router link takes `to` rather than this component's `href`, so\n     * its own props cannot say — while `'a'`, `'button'`, and a custom element given an\n     * `href` count for the reason they read.\n     *\n     * If your custom component renders something that really is just a picture, say so with\n     * `role=\"img\"` and it is treated as one, `alt=\"\"` included. A truthy `aria-hidden` says it\n     * too, and so do `role=\"presentation\"` and `role=\"none\"` — though ARIA's own conflict\n     * resolution drops those two whenever the avatar still carries a name, so prefer\n     * `role=\"img\"`. A role claiming the opposite, such as `\"button\"`, says nothing here, and\n     * neither does an `href`: that settles it on its own. A genuine `'a'`/`'button'`/`href`\n     * avatar keeps its accessible name either way.\n     *\n     * `'button'` renders `type=\"button\"` unless you pass `type=\"submit\"` or `type=\"reset\"`, so\n     * an avatar inside a form does not submit it.\n     */\n    as?: T;\n  };\n\n/**\n * The shape the implementation destructures. The public contract is the generic\n * `AvatarProps<T>` above — the body cannot see through `T`, so it names the\n * handful of DOM props it actually reads back off `rest`.\n */\ntype AvatarImplProps = AvatarOwnProps & {\n  as?: React.ElementType;\n  role?: React.AriaRole;\n  'aria-hidden'?: React.AriaAttributes['aria-hidden'];\n  'aria-label'?: string;\n  type?: React.ButtonHTMLAttributes<HTMLButtonElement>['type'];\n};\n\n/**\n * The `Avatar` component represents a person or entity as a compact image.\n *\n * @function\n * @param {AvatarProps} props - Props for the Avatar component.\n * @param {React.Ref} ref - Forwarded ref to the element `as` renders.\n * @returns {JSX.Element} The rendered avatar element.\n *\n * @example\n * <Avatar src=\"/users/ada.jpg\" name=\"Ada Lovelace\" size=\"64x64\" />\n * @example\n * <Avatar name=\"Grace Hopper\" />\n */\nexport const Avatar = forwardRef(function Avatar(\n  avatarProps: AvatarProps,\n  ref: React.Ref<HTMLElement>\n) {\n  const {\n    className,\n    src,\n    alt,\n    name,\n    initials,\n    icon,\n    size,\n    shape = 'circle',\n    color,\n    as,\n    href,\n    target,\n    rel,\n    imageProps,\n    style,\n    ...props\n  } = avatarProps as AvatarImplProps;\n  // Tracks the src that failed to load. A src change clears the latch during\n  // render (React's \"reset state when props change\" pattern) so a previously\n  // failed src is retried when switched back to. The img is additionally\n  // keyed by src so a swap discards the old DOM node — a late error event\n  // from the previous request can't fire on a retained node and latch the\n  // replacement src as failed.\n  const [erroredSrc, setErroredSrc] = useState<string | undefined>(undefined);\n  const [prevSrc, setPrevSrc] = useState(src);\n  if (src !== prevSrc) {\n    setPrevSrc(src);\n    setErroredSrc(undefined);\n  }\n  const imgRef = useRef<HTMLImageElement>(null);\n\n  const { bulmaHelperClasses, rest } = useBulmaClasses(props);\n\n  const showImage = !!src && src !== erroredSrc;\n\n  // Catch images that failed before hydration: in SSR/static pages a broken\n  // image can finish loading before React attaches its onError, so it never\n  // fires. A complete image with no intrinsic width is a load failure.\n  useEffect(() => {\n    const img = imgRef.current;\n    if (img && img.complete && img.naturalWidth === 0) {\n      setErroredSrc(src);\n    }\n  }, [src]);\n\n  const resolvedInitials = initials\n    ? initials.toUpperCase()\n    : name\n      ? getInitialsFromName(name)\n      : '';\n  const showInitials = !showImage && !!resolvedInitials;\n  const showIcon = !showImage && !showInitials && !!icon;\n  const showDefaultIcon = !showImage && !showInitials && !showIcon;\n\n  const resolvedColor = color ?? (name ? getAutoColor(name) : undefined);\n\n  const isPresetSize = typeof size === 'string' && avatarSizes.includes(size);\n  const sizeStyle =\n    typeof size === 'number'\n      ? { width: size, height: size, fontSize: size / 2.5 }\n      : undefined;\n\n  const avatarClasses = usePrefixedClassNames('avatar', {\n    [`is-${size}`]: isPresetSize,\n    [`is-${shape}`]: shape,\n    [`is-${resolvedColor}`]:\n      resolvedColor && !showImage && avatarColors.includes(resolvedColor),\n  });\n\n  const combinedClasses = classNames(\n    avatarClasses,\n    bulmaHelperClasses,\n    className\n  );\n\n  const initialsClass = usePrefixedClassNames('avatar-initials');\n\n  const Tag: React.ElementType = as ?? (href ? 'a' : 'figure');\n  // A custom component counts as interactive whether or not it was given OUR\n  // href: a router link takes `to`, creates the anchor itself, and cannot be\n  // classified from the props it arrives with (#668). Marking a real link as a\n  // picture is the worse failure — and `alt=\"\"` would go further and mark it\n  // decorative (aria-hidden), leaving it nameless.\n  //\n  // A custom ELEMENT still needs the href. A hyphenated tag renders a real DOM\n  // element of that name, so nothing is hidden from us: without a link to follow\n  // it is still a picture. `Navbar.Link` draws the same line for `role=\"button\"`.\n  //\n  // Where we are guessing, the caller settles it: an explicit `role` or\n  // `aria-hidden` states the semantics, so a custom component that really is a\n  // wrapper gets `role=\"img\"` and its `alt=\"\"` opt-out back. `role` alone would\n  // be a half-override — interactivity also drives the decorative opt-out and the\n  // name fallback, and overriding one of the three is worse than overriding none.\n  //\n  // An `href` ENDS the guess, so it outranks the signal. `as=\"a\"`, `as=\"button\"`\n  // and a target we were handed an href for are known to be interactive, and there\n  // the rule that an interactive element always carries an accessible name is not\n  // the caller's to waive: without this, `as={RouterLink} href=\"/x\" role=\"img\"`\n  // with `alt=\"\"` rendered a real anchor as `aria-hidden` and nameless — the very\n  // failure #668 is about. `Navbar.Link` orders the same two the same way.\n  //\n  // The signal has to MEAN what it is used for, so both halves read a value rather\n  // than a presence — the way `Navbar.Link` reads `role === 'button'`. A role only\n  // claims to be a picture if it says so: `role=\"button\"` or `role=\"link\"` is the\n  // opposite claim, and taking any role as the signal handed an interactive-role\n  // element `aria-hidden` and no name. Likewise `aria-hidden={false}` denies\n  // hiding, so only a truthy one counts.\n  const ariaHidden = rest['aria-hidden'];\n  const statesItIsNotAControl =\n    (rest.role !== undefined && NON_INTERACTIVE_ROLES.includes(rest.role)) ||\n    ariaHidden === true ||\n    ariaHidden === 'true';\n\n  const customTargetStatesSemantics =\n    typeof Tag !== 'string' && href == null && statesItIsNotAControl;\n\n  const isInteractive =\n    Tag === 'a' ||\n    Tag === 'button' ||\n    (typeof Tag !== 'string' && !customTargetStatesSemantics) ||\n    (isCustomElement(Tag) && href != null);\n\n  // Only forward link attributes when rendering an anchor or a custom (non-DOM)\n  // component; a plain `as=\"div\"` must not receive a stray `href`/`target`/`rel`.\n  const isLinkLike =\n    Tag === 'a' || typeof Tag !== 'string' || isCustomElement(Tag);\n  // A plain element like a `div` declares no `href` or `target`, so the type\n  // accepts them as Avatar's own while the drop below withholds them, and\n  // without this they would vanish in silence (#733). Forwarding them would put\n  // them where HTML has no such attribute, so the drop stays and development\n  // reports it instead, naming only the ones actually passed.\n  //\n  // `rel` is withheld too but left out here. React declares it on every\n  // element, so on a plain `as` it is that element's own attribute, and\n  // \"render it as a link\" would be the wrong advice for it. `target` is the\n  // same on an element that declares it, such as `form`, so it is left out\n  // there. Whether to forward either one to such an element is a separate\n  // question from this warning.\n  //\n  // Only for an `as` the caller wrote. Without one the element is Avatar's own\n  // choice, and a message naming an `as` they never passed sends them looking\n  // for it. A value counts when it is truthy, the same test that picks `'a'`\n  // over `'figure'`, so an empty `href` from data asks for no link and draws no\n  // warning. The key is the element plus the attributes passed, so a re-render\n  // or a list of avatars warns once, while a different combination on the same\n  // element still gets its own warning rather than hiding behind the first.\n  //\n  // Development-only is `warnOnce`'s job, as it is for the colour warnings, so\n  // this block has no production check of its own. One here would have to read\n  // `process` safely, and a `typeof process` test is not something a bundler\n  // replaces: in a browser it is false, and the warning never fired in the\n  // development builds it exists for. The cost is that production still\n  // collects the attributes and builds the message for an avatar that needs\n  // it, which is small and limited to the case the warning is about.\n  if (as != null && !isLinkLike) {\n    const dropped = Object.entries({\n      href,\n      target: ELEMENTS_WITH_OWN_TARGET.includes(as) ? undefined : target,\n    })\n      .filter(([, value]) => value)\n      .map(([key]) => key);\n    if (dropped.length > 0) {\n      warnOnce(\n        `Avatar:link-props-on-${as}:${dropped.join('+')}`,\n        `[bestax-bulma] <Avatar as=\"${as}\" ${dropped.join(' ')}>: this ` +\n          `<${as}> renders without ` +\n          `${dropped.map(key => `\"${key}\"`).join(' and ')}, because Avatar ` +\n          `passes link attributes on only to a target that can be a link (an ` +\n          `\"a\", a custom element, or a component). To make it a link, render ` +\n          `it as=\"a\" or pass a link component to \"as\".`\n      );\n    }\n  }\n  // Present-only, not `{ href, target, rel }`. An unconditional spread hands the\n  // target these keys whatever the caller passed, and a key existing is not free:\n  // a target that tests for one sees a link where there is none, and one that\n  // spreads its own `{...rest}` onward passes the nothing along. It is NOT about\n  // a destructuring default, which an explicit `undefined` triggers just as an\n  // absent key does. What stops a target that REQUIRES one from being rendered\n  // without it is the type (#665) — this is the smaller half, and the backstop for\n  // the callers a type does not reach: a plain-JavaScript one and a loose spread,\n  // the same pair `Button` and `Menu.Item` keep their own filters for.\n  const linkProps = isLinkLike\n    ? {\n        ...(href !== undefined && { href }),\n        ...(target !== undefined && { target }),\n        ...(rel !== undefined && { rel }),\n      }\n    : {};\n\n  // alt coalesces with ?? (not ||) so an explicit alt=\"\" survives as the\n  // standard decorative marker instead of being overridden by name.\n  const accessibleName = alt ?? name;\n  // The decorative opt-out never applies to an interactive avatar — a link or\n  // button must always expose an accessible name.\n  const isDecorative = alt === '' && !isInteractive;\n\n  const a11yDefaults: {\n    'aria-label'?: string;\n    role?: 'img';\n    'aria-hidden'?: true;\n  } = showImage\n    ? isInteractive && !accessibleName\n      ? // The img alt normally names the control; with no alt/name (an API\n        // returning only a photo URL) the link/button would be nameless.\n        { 'aria-label': name || 'Avatar' }\n      : {}\n    : isDecorative\n      ? { 'aria-hidden': true }\n      : {\n          ...(isInteractive ? {} : { role: 'img' as const }),\n          'aria-label': accessibleName || name || 'Avatar',\n        };\n\n  // Each default yields to a value the caller passed, and is applied after\n  // `rest` reading through it rather than spread before it. React treats an\n  // `undefined` attribute as \"remove it\", and a spread carrying the key with no\n  // value is how that arrives, so a default spread first was erased by it: an\n  // `aria-label: undefined` left a button avatar nameless, and `role` and\n  // `aria-hidden` went the same way. The button `type` below has the same\n  // shape (#690).\n  const a11yProps = Object.fromEntries(\n    Object.entries(a11yDefaults).map(([key, fallback]) => [\n      key,\n      rest[key as keyof typeof a11yDefaults] ?? fallback,\n    ])\n  );\n\n  return (\n    <Tag\n      ref={ref}\n      className={combinedClasses}\n      style={{ ...sizeStyle, ...style }}\n      {...linkProps}\n      {...rest}\n      {...a11yProps}\n      // A clickable avatar inside a form must not submit it, and `<button>`\n      // defaults to type=\"submit\". A caller's `submit` or `reset` still wins.\n      // Anything else becomes `button`, since HTML reads a value it does not\n      // define for a button as submit too; `buttonType` says more.\n      //\n      // After `rest`, reading through it rather than before it: React treats\n      // `type={undefined}` as \"remove the attribute\", and a spread carrying the\n      // key with no value is how that arrives. Spreading the default first let\n      // such a spread erase it (#690), so the guard only held for callers who\n      // passed nothing. `Dropdown.Item` and `Menu.Item` apply their button\n      // type after the spread too.\n      {...(Tag === 'button' ? { type: buttonType(rest.type) } : {})}\n    >\n      {showImage && (\n        <img\n          key={src}\n          {...imageProps}\n          ref={imgRef}\n          src={src}\n          alt={accessibleName ?? ''}\n          onError={e => {\n            imageProps?.onError?.(e);\n            setErroredSrc(src);\n          }}\n        />\n      )}\n      {showInitials && (\n        <span className={initialsClass}>{resolvedInitials}</span>\n      )}\n      {showIcon && icon}\n      {showDefaultIcon && <DefaultAvatarIcon />}\n    </Tag>\n  );\n}) as PolymorphicComponent<AvatarOwnProps, 'figure', AvatarForwardedProp>;\n\nAvatar.displayName = 'Avatar';\n\nexport default Avatar;\n"],"names":["_jsx","_jsxs"],"mappings":"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"}

package/dist/esm/components/Avatars.js

@@ -0,0 +1,81 @@
+/* @allxsmith/bestax-bulma — AI agents: see AGENTS.md in the package root, or https://bestax.io/llms.txt */
+import { jsxs, jsx } from 'react/jsx-runtime';
+import React from 'react';
+import { usePrefixedClassNames, classNames } from '../helpers/classNames.js';
+import { withSubComponents } from '../helpers/withSubComponents.js';
+import { useBulmaClasses } from '../helpers/useBulmaClasses.js';
+import { Avatar } from './Avatar.js';
+
+/**
+ * Flattens Fragment children (recursively) into a flat element array so they
+ * participate in max clamping and size/shape injection. Children.toArray keys
+ * restart at ".0" inside each fragment, so fragment children are re-keyed by
+ * prefixing the fragment's own key — otherwise a fragment sibling of a direct
+ * child would collide (both ".0") and trigger duplicate-key warnings.
+ */
+function flattenChildren$1(children, keyPrefix = '') {
+    return React.Children.toArray(children).flatMap(child => {
+        if (!React.isValidElement(child))
+            return [];
+        if (child.type === React.Fragment) {
+            return flattenChildren$1(child.props.children, keyPrefix + child.key);
+        }
+        const el = child;
+        return [
+            keyPrefix ? React.cloneElement(el, { key: keyPrefix + el.key }) : el,
+        ];
+    });
+}
+/**
+ * The `Avatars` component renders an overlapping/stacked group of `Avatar`s, the "members" list pattern.
+ *
+ * @function
+ * @param {AvatarsProps} props - Props for the Avatars component.
+ * @returns {JSX.Element} The rendered avatars group.
+ *
+ * @example
+ * <Avatars max={3} size="48x48">
+ *   {members.map(m => <Avatar key={m.id} src={m.photo} name={m.name} />)}
+ * </Avatars>
+ */
+const AvatarsComponent = ({ className, max, size, shape, spacing = 'md', spaced = false, surplusLabel, style, children, ...props }) => {
+    const { bulmaHelperClasses, rest } = useBulmaClasses({ ...props });
+    // A preset spacing maps to a class; a numeric spacing sets the CSS var inline
+    // (mirrors Sidebar's inline --bulma-* width var).
+    const isPresetSpacing = typeof spacing === 'string';
+    const avatarsClasses = usePrefixedClassNames('avatars', {
+        [`is-spacing-${spacing}`]: isPresetSpacing,
+        'is-spaced': spaced,
+    });
+    const spacingStyle = typeof spacing === 'number'
+        ? { '--bulma-avatars-spacing': `${spacing}px` }
+        : undefined;
+    const surplusClass = usePrefixedClassNames('is-surplus');
+    const combinedClasses = classNames(avatarsClasses, bulmaHelperClasses, className);
+    const childArray = flattenChildren$1(children);
+    const maxCount = typeof max === 'number' && Number.isInteger(max) && max >= 0
+        ? max
+        : undefined;
+    const overshoot = maxCount !== undefined ? childArray.length - maxCount : 0;
+    // A "+1" surplus bubble occupies the same slot the hidden avatar would, so
+    // only collapse into a surplus when it stands in for two or more avatars; a
+    // single overflow avatar is shown directly.
+    const clamp = maxCount !== undefined && overshoot >= 2;
+    const visibleChildren = clamp ? childArray.slice(0, maxCount) : childArray;
+    const overflowCount = clamp ? overshoot : 0;
+    return (jsxs("div", { className: combinedClasses, style: { ...spacingStyle, ...style }, ...rest, children: [visibleChildren.map(child => 
+            // Conditional-spread so an unset group size/shape doesn't clobber a
+            // child that set its own.
+            React.cloneElement(child, {
+                ...(size !== undefined ? { size } : {}),
+                ...(shape !== undefined ? { shape } : {}),
+            })), overflowCount > 0 && (jsx(Avatar, { initials: `+${overflowCount}`, alt: 
+                // `||` (not a plain ternary): an empty string from surplusLabel
+                // would make the bubble decorative (alt="") and hide the count
+                // from assistive tech — fall back to the default label instead.
+                surplusLabel?.(overflowCount) || `${overflowCount} more`, size: size, shape: shape, className: surplusClass }))] }));
+};
+const Avatars = withSubComponents(AvatarsComponent, { Avatar }, 'Avatars');
+
+export { Avatars };
+//# sourceMappingURL=Avatars.js.map

package/dist/esm/components/Avatars.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Avatars.js","sources":["../../../src/components/Avatars.tsx"],"sourcesContent":["import React from 'react';\nimport { classNames, usePrefixedClassNames } from '../helpers/classNames';\nimport { withSubComponents } from '../helpers/withSubComponents';\nimport { useBulmaClasses, BulmaClassesProps } from '../helpers/useBulmaClasses';\nimport { Avatar, AvatarProps } from './Avatar';\n\n/** Valid overlap spacing values for the Avatars component. */\nexport type AvatarsSpacing = 'sm' | 'md' | 'lg';\n\n/**\n * Props for the Avatars component.\n */\nexport interface AvatarsProps\n  extends\n    Omit<React.HTMLAttributes<HTMLDivElement>, 'color'>,\n    Omit<BulmaClassesProps, 'backgroundColor' | 'color'> {\n  /** Additional CSS classes to apply. */\n  className?: string;\n  /** Show only the first `max` children, replacing the overflow with a \"+N\" surplus avatar. A single overflow avatar is shown directly rather than as a pointless \"+1\". */\n  max?: number;\n  /** Uniform size applied to every child `Avatar` (and the surplus avatar). */\n  size?: AvatarProps['size'];\n  /** Uniform shape applied to every child `Avatar` (and the surplus avatar); a child's own `shape` wins when this is unset. */\n  shape?: AvatarProps['shape'];\n  /** Space between avatars: a preset or a pixel `number`. The overlap distance, or the gap when `spaced`. */\n  spacing?: AvatarsSpacing | number;\n  /** Lay the avatars out side by side (non-overlapping), using `spacing` as the gap. */\n  spaced?: boolean;\n  /** Builds the surplus avatar's accessible name from the hidden count, for localization. Default: `` `${count} more` ``. */\n  surplusLabel?: (count: number) => string;\n  /** `Avatar` elements to render inside the group. */\n  children?: React.ReactNode;\n}\n\n/**\n * Flattens Fragment children (recursively) into a flat element array so they\n * participate in max clamping and size/shape injection. Children.toArray keys\n * restart at \".0\" inside each fragment, so fragment children are re-keyed by\n * prefixing the fragment's own key — otherwise a fragment sibling of a direct\n * child would collide (both \".0\") and trigger duplicate-key warnings.\n */\nfunction flattenChildren(\n  children: React.ReactNode,\n  keyPrefix = ''\n): React.ReactElement<AvatarProps>[] {\n  return React.Children.toArray(children).flatMap(child => {\n    if (!React.isValidElement(child)) return [];\n    if (child.type === React.Fragment) {\n      return flattenChildren(\n        (child.props as { children?: React.ReactNode }).children,\n        keyPrefix + child.key\n      );\n    }\n    const el = child as React.ReactElement<AvatarProps>;\n    return [\n      keyPrefix ? React.cloneElement(el, { key: keyPrefix + el.key }) : el,\n    ];\n  });\n}\n\n/**\n * The `Avatars` component renders an overlapping/stacked group of `Avatar`s, the \"members\" list pattern.\n *\n * @function\n * @param {AvatarsProps} props - Props for the Avatars component.\n * @returns {JSX.Element} The rendered avatars group.\n *\n * @example\n * <Avatars max={3} size=\"48x48\">\n *   {members.map(m => <Avatar key={m.id} src={m.photo} name={m.name} />)}\n * </Avatars>\n */\nconst AvatarsComponent: React.FC<AvatarsProps> = ({\n  className,\n  max,\n  size,\n  shape,\n  spacing = 'md',\n  spaced = false,\n  surplusLabel,\n  style,\n  children,\n  ...props\n}) => {\n  const { bulmaHelperClasses, rest } = useBulmaClasses({ ...props });\n\n  // A preset spacing maps to a class; a numeric spacing sets the CSS var inline\n  // (mirrors Sidebar's inline --bulma-* width var).\n  const isPresetSpacing = typeof spacing === 'string';\n  const avatarsClasses = usePrefixedClassNames('avatars', {\n    [`is-spacing-${spacing}`]: isPresetSpacing,\n    'is-spaced': spaced,\n  });\n  const spacingStyle: React.CSSProperties | undefined =\n    typeof spacing === 'number'\n      ? ({ '--bulma-avatars-spacing': `${spacing}px` } as React.CSSProperties)\n      : undefined;\n\n  const surplusClass = usePrefixedClassNames('is-surplus');\n\n  const combinedClasses = classNames(\n    avatarsClasses,\n    bulmaHelperClasses,\n    className\n  );\n\n  const childArray = flattenChildren(children);\n\n  const maxCount =\n    typeof max === 'number' && Number.isInteger(max) && max >= 0\n      ? max\n      : undefined;\n  const overshoot = maxCount !== undefined ? childArray.length - maxCount : 0;\n  // A \"+1\" surplus bubble occupies the same slot the hidden avatar would, so\n  // only collapse into a surplus when it stands in for two or more avatars; a\n  // single overflow avatar is shown directly.\n  const clamp = maxCount !== undefined && overshoot >= 2;\n  const visibleChildren = clamp ? childArray.slice(0, maxCount) : childArray;\n  const overflowCount = clamp ? overshoot : 0;\n\n  return (\n    <div\n      className={combinedClasses}\n      style={{ ...spacingStyle, ...style }}\n      {...rest}\n    >\n      {visibleChildren.map(child =>\n        // Conditional-spread so an unset group size/shape doesn't clobber a\n        // child that set its own.\n        React.cloneElement(child, {\n          ...(size !== undefined ? { size } : {}),\n          ...(shape !== undefined ? { shape } : {}),\n        })\n      )}\n      {overflowCount > 0 && (\n        <Avatar\n          initials={`+${overflowCount}`}\n          alt={\n            // `||` (not a plain ternary): an empty string from surplusLabel\n            // would make the bubble decorative (alt=\"\") and hide the count\n            // from assistive tech — fall back to the default label instead.\n            surplusLabel?.(overflowCount) || `${overflowCount} more`\n          }\n          size={size}\n          shape={shape}\n          className={surplusClass}\n        />\n      )}\n    </div>\n  );\n};\n\nexport const Avatars = withSubComponents(\n  AvatarsComponent,\n  { Avatar },\n  'Avatars'\n);\n\nexport default Avatars;\n"],"names":["flattenChildren","_jsxs","_jsx"],"mappings":"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"}