@allxsmith/bestax-bulma 5.27.0 → 5.27.2

package/dist/esm/elements/Icon.js

@@ -0,0 +1,256 @@
+/* @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 { useBulmaClasses } from '../helpers/useBulmaClasses.js';
+import { useIconLibrary } from '../helpers/Config.js';
+
+/**
+ * Strips a redundant leading library prefix from an icon name (e.g. `fa-check` -> `check`
+ * for the `fa` library, `mdi-account` -> `account` for `mdi`), so `name` behaves the same
+ * whether or not the caller includes the prefix. Font Awesome and Material Design Icons docs
+ * conventionally refer to icons with their class prefix (`fa-check`), which otherwise gets
+ * doubled by `getIconClasses` (producing `fa-fa-check`, matching no glyph).
+ *
+ * @param {string} name - The icon name, possibly including a redundant library prefix.
+ * @param {IconLibrary} library - The icon library the name will be rendered with.
+ * @returns {string} The icon name with any redundant leading library prefix removed.
+ */
+function stripRedundantLibraryPrefix(name, library) {
+    if (!name) {
+        return name;
+    }
+    if (library === 'fa' && name.startsWith('fa-')) {
+        return name.substring(3);
+    }
+    if (library === 'mdi' && name.startsWith('mdi-')) {
+        return name.substring(4);
+    }
+    return name;
+}
+/**
+ * Gets the correct classes for the icon element based on the library and features.
+ *
+ * @param {IconLibrary} library - The icon library.
+ * @param {string} name - The icon name.
+ * @param {string} [variant] - Icon style variant (e.g., 'solid', 'outlined', 'rounded').
+ * @param {string | string[]} [features] - Additional library-specific modifiers.
+ * @returns {string} The combined class string for the icon.
+ */
+function getIconClasses(library, name, variant, features) {
+    let baseClass;
+    let iconClass;
+    const featureList = Array.isArray(features)
+        ? features
+        : features
+            ? [features]
+            : [];
+    switch (library) {
+        case 'fa': {
+            // Font Awesome: use variant as style ('solid' -> 'fas', 'regular' -> 'far', etc.)
+            const styleMap = {
+                solid: 'fas',
+                regular: 'far',
+                brands: 'fab',
+                light: 'fal',
+                duotone: 'fad',
+                thin: 'fat',
+            };
+            const faStyle = variant ? styleMap[variant] || variant : 'fas';
+            baseClass = faStyle;
+            iconClass = `fa-${name}`;
+            return [baseClass, iconClass, ...featureList].join(' ');
+        }
+        case 'mdi':
+            // Material Design Icons: no variants, just features
+            baseClass = 'mdi';
+            iconClass = `mdi-${name}`;
+            return [baseClass, iconClass, ...featureList].join(' ');
+        case 'material-icons': {
+            // Google Material Icons: map variants to full class names
+            const styleVariants = {
+                filled: 'material-icons',
+                outlined: 'material-icons-outlined',
+                round: 'material-icons-round',
+                sharp: 'material-icons-sharp',
+            };
+            baseClass = variant
+                ? styleVariants[variant] || `material-icons-${variant}`
+                : 'material-icons';
+            return [baseClass, ...featureList].join(' ');
+        }
+        case 'material-symbols': {
+            // Google Material Symbols: map variants to full class names
+            const styleVariants = {
+                outlined: 'material-symbols-outlined',
+                rounded: 'material-symbols-rounded',
+                sharp: 'material-symbols-sharp',
+            };
+            baseClass = variant
+                ? styleVariants[variant] || `material-symbols-${variant}`
+                : 'material-symbols-outlined';
+            return [baseClass, ...featureList].join(' ');
+        }
+        default:
+            // fallback: just icon name and features
+            return [name, ...featureList].join(' ');
+    }
+}
+/**
+ * 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.).
+ *
+ * @function
+ * @param {IconProps} props - Props for the Icon component.
+ * @returns {JSX.Element} The rendered icon element.
+ * @see {@link https://bulma.io/documentation/elements/icon/ | Bulma Icon documentation}
+ */
+const Icon = ({ className, textColor, bgColor, name, library, variant, features, libraryFeatures, // Deprecated but maintained for backward compatibility
+size, ariaLabel, style, icon, // Capture and exclude the deprecated 'icon' prop from DOM
+color: _color, // Exclude 'color' prop if passed directly
+containerClassName, children, ...restProps }) => {
+    // Get the default icon library from context, fallback to 'fa' if not set
+    const defaultLibrary = useIconLibrary();
+    /**
+     * Generates Bulma helper classes and separates out remaining props.
+     * Note: variant, features, and libraryFeatures are excluded from props spread
+     */
+    const { bulmaHelperClasses, rest } = useBulmaClasses({
+        color: textColor,
+        backgroundColor: bgColor,
+        ...restProps,
+    });
+    // Hoisted unconditionally to respect rules-of-hooks; the branches below
+    // pick which result to consume.
+    const defaultIconClasses = usePrefixedClassNames('icon', {
+        [`is-${size}`]: size,
+    });
+    const sizeModifierClass = usePrefixedClassNames(size ? `is-${size}` : undefined);
+    const bulmaClasses = containerClassName
+        ? containerClassName
+        : defaultIconClasses;
+    const iconContainerClasses = classNames(bulmaClasses, containerClassName && size ? sizeModifierClass : undefined, bulmaHelperClasses, className);
+    // A named icon is an image, whose name is its label alone, so a ligature inside
+    // never leaks into it. An unnamed one is decorative and hidden outright. Spread
+    // before `rest`, so a caller's own `role` or `aria-hidden` still wins.
+    const named = !!ariaLabel || !!restProps['aria-label'] || !!restProps['aria-labelledby'];
+    // A caller's own `role` or `tabIndex` on an unnamed icon means it isn't decoration (an
+    // icon made a button, say), so it isn't hidden either: `aria-hidden` on something
+    // focusable is a failure of its own.
+    const a11yProps = named
+        ? { role: 'img', 'aria-label': ariaLabel || undefined }
+        : restProps.role !== undefined || restProps.tabIndex !== undefined
+            ? {}
+            : { 'aria-hidden': true };
+    if (children !== undefined) {
+        // `IconChildrenProps`: render the caller's node (an inline SVG, a `react-icons`
+        // component, …) in place of a class-based glyph. Library/variant/features don't apply.
+        return (jsx("span", { className: iconContainerClasses, ...a11yProps, style: style, ...rest, children: children }));
+    }
+    // `name` is guaranteed once `children` is absent UNLESS the caller is on the deprecated
+    // `icon` path, which `IconDeprecatedProps` declares with `name?: undefined`.
+    // (`IconChildrenProps['children']` excludes `undefined`, so `children={undefined}` can't
+    // slip past into this branch.) The cast covers that third member, and the `!name && icon`
+    // fallback below is what fills it in.
+    let finalName = name;
+    if (!name && icon) {
+        // If icon prop is provided instead of name, try to parse it
+        // e.g., "mdi mdi-rocket-launch" -> "rocket-launch"
+        if (typeof icon === 'string') {
+            const parts = icon.split(' ');
+            const lastPart = parts[parts.length - 1];
+            if (lastPart.startsWith('mdi-')) {
+                finalName = lastPart.substring(4); // Remove "mdi-" prefix
+            }
+            else if (lastPart.startsWith('fa-')) {
+                finalName = lastPart.substring(3); // Remove "fa-" prefix
+            }
+            else {
+                finalName = lastPart;
+            }
+        }
+    }
+    const finalLibrary = library || defaultLibrary || 'fa';
+    // Normalize a redundant leading library prefix (e.g. "fa-check" -> "check" when the
+    // library is 'fa'), so `name` behaves identically with or without the prefix.
+    finalName = stripRedundantLibraryPrefix(finalName, finalLibrary);
+    if (!finalName) {
+        // No glyph to name. Reachable through the public type only as `icon=""`, and otherwise
+        // by a plain-JS caller (or one that casts). Building a class off an absent name produced
+        // a bogus `fa-undefined` glyph; render the bare container instead, matching the
+        // `children` branch.
+        return (jsx("span", { className: iconContainerClasses, ...a11yProps, style: style, ...rest }));
+    }
+    // Backward compatibility: if libraryFeatures is provided, parse it for variant and features
+    let finalVariant = variant;
+    let finalFeatures = features;
+    if (libraryFeatures && !variant && !features) {
+        const legacyFeatures = Array.isArray(libraryFeatures)
+            ? libraryFeatures
+            : [libraryFeatures];
+        // For Font Awesome, extract style from features
+        if (finalLibrary === 'fa') {
+            const faStyle = legacyFeatures.find(f => [
+                'fas',
+                'far',
+                'fab',
+                'fal',
+                'fad',
+                'fat',
+                'solid',
+                'regular',
+                'brands',
+                'light',
+                'duotone',
+                'thin',
+            ].includes(f));
+            if (faStyle) {
+                finalVariant = faStyle;
+                finalFeatures = legacyFeatures.filter(f => f !== faStyle);
+            }
+            else {
+                finalFeatures = legacyFeatures;
+            }
+        }
+        // For Material Icons/Symbols, extract style variant
+        else if (finalLibrary === 'material-icons' ||
+            finalLibrary === 'material-symbols') {
+            const styleVariants = finalLibrary === 'material-icons'
+                ? ['filled', 'outlined', 'round', 'sharp']
+                : ['outlined', 'rounded', 'sharp'];
+            const styleVariant = legacyFeatures.find(f => styleVariants.includes(f));
+            if (styleVariant) {
+                finalVariant = styleVariant;
+                finalFeatures = legacyFeatures.filter(f => f !== styleVariant);
+            }
+            else {
+                finalFeatures = legacyFeatures;
+            }
+        }
+        // For others, all features go to finalFeatures
+        else {
+            finalFeatures = legacyFeatures;
+        }
+    }
+    // Handle web components vs CSS-based icons
+    if (finalLibrary === 'ion') {
+        // For Ionicons, handle variant in the name
+        let ionName = finalName;
+        if (finalVariant === 'outline') {
+            ionName = `${finalName}-outline`;
+        }
+        else if (finalVariant === 'sharp') {
+            ionName = `${finalName}-sharp`;
+        }
+        return (jsx("span", { className: iconContainerClasses, ...a11yProps, style: style, ...rest, children: jsx("ion-icon", { name: ionName }) }));
+    }
+    // Legacy CSS-based icons
+    const iClasses = getIconClasses(finalLibrary, finalName, finalVariant, finalFeatures);
+    // Material Icons and Material Symbols use text content, not CSS classes for the icon name
+    if (finalLibrary === 'material-icons' ||
+        finalLibrary === 'material-symbols') {
+        return (jsx("span", { className: iconContainerClasses, ...a11yProps, style: style, ...rest, children: jsx("i", { className: iClasses, children: finalName }) }));
+    }
+    return (jsx("span", { className: iconContainerClasses, ...a11yProps, style: style, ...rest, children: jsx("i", { className: iClasses }) }));
+};
+
+export { Icon };
+//# sourceMappingURL=Icon.js.map

package/dist/esm/elements/Icon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Icon.js","sources":["../../../src/elements/Icon.tsx"],"sourcesContent":["import React from 'react';\nimport { classNames, usePrefixedClassNames } from '../helpers/classNames';\nimport {\n  useBulmaClasses,\n  BulmaClassesProps,\n  validColors,\n} from '../helpers/useBulmaClasses';\nimport { useIconLibrary } from '../helpers/Config';\n\n// TypeScript declaration for Ionicons web component\ninterface IonIconProps extends React.HTMLAttributes<HTMLElement> {\n  name?: string;\n  src?: string;\n  icon?: unknown;\n  size?: string;\n  lazy?: boolean;\n  sanitize?: boolean;\n  color?: string;\n  flipRtl?: boolean;\n  ariaLabel?: string;\n  ariaHidden?: string;\n}\n\n// React 19 moved the global `JSX` namespace under the `react` module, so the\n// `<ion-icon>` web-component augmentation must target `React.JSX` to take effect.\ndeclare module 'react' {\n  // eslint-disable-next-line @typescript-eslint/no-namespace\n  namespace JSX {\n    interface IntrinsicElements {\n      'ion-icon': IonIconProps;\n    }\n  }\n}\n\ntype IconLibrary = 'fa' | 'mdi' | 'ion' | 'material-icons' | 'material-symbols'; // 'fa' = Font Awesome, 'mdi' = Material Design Icons, 'ion' = Ionicons Web Components, 'material-icons' = Google Material Icons, 'material-symbols' = Google Material Symbols\n\n/**\n * Shared props for the Icon component, independent of whether a class-based `name` or a\n * custom `children` node supplies the glyph.\n */\ninterface IconBaseProps\n  extends React.HTMLAttributes<HTMLSpanElement>, BulmaClassesProps {\n  /** Additional CSS classes to apply. */\n  className?: string;\n  /** Text color helper. */\n  textColor?: (typeof validColors)[number] | 'inherit' | 'current';\n  /** Bulma color modifier for the icon. */\n  color?: 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger';\n  /** Background color helper. */\n  bgColor?: (typeof validColors)[number] | 'inherit' | 'current';\n  /**\n   * Legacy icon class string (e.g. `'fas fa-star'`). Only its last segment is read, as the\n   * glyph name; the library still comes from `library` or `ConfigProvider`, so\n   * `'mdi mdi-rocket'` renders an `fa` class unless the effective library is already `mdi` —\n   * set it here or on the provider.\n   *\n   * @deprecated Use `name` instead.\n   */\n  icon?: string;\n  /**\n   * 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`.\n   * @defaultValue 'fa'\n   */\n  library?: IconLibrary; // defaults to ConfigProvider iconLibrary or 'fa'\n  /** Icon style variant (e.g. `'solid'`, `'outlined'`, `'rounded'`). Ignored when `children` supplies the glyph instead of `name`. */\n  variant?: string; // e.g., 'solid', 'outlined', 'rounded', 'sharp'\n  /** Additional modifiers (e.g. `'fa-lg'`, `'fa-spin'`, `'is-size-1'`). Ignored when `children` supplies the glyph instead of `name`. */\n  features?: string | string[]; // e.g., 'fa-lg', 'fa-spin', 'is-size-1'\n  /**\n   * Additional modifiers in the older combined form, parsed into `variant` and `features`.\n   *\n   * @deprecated Use `variant` and `features` instead.\n   */\n  libraryFeatures?: string | string[];\n  /** Size modifier for the icon container. */\n  size?: 'small' | 'medium' | 'large';\n  /**\n   * Accessible name for an icon that means something on its own. Set it and the container\n   * span gets `role=\"img\"` with this `aria-label`, so the name is exactly this text: a\n   * Material ligature such as `rocket_launch` inside stays out of it. Leave it unset (or\n   * empty) and the icon is decorative: the span renders `aria-hidden=\"true\"` and no name,\n   * so it adds nothing to the accessible name of a `Button` or text around it. For an\n   * icon-only control, put the name on the control (e.g. `Button`'s `aria-label`) and leave\n   * this unset. A non-empty native `aria-label` or `aria-labelledby` passed instead also\n   * counts as a name, and an explicit `role` or `aria-hidden` wins over both defaults. An\n   * unnamed icon given a `role` or a `tabIndex` of its own isn't hidden, since hiding\n   * something focusable is a failure of its own.\n   */\n  ariaLabel?: string;\n  /** Inline style object. */\n  style?: React.CSSProperties;\n  /** Override the default `'icon'` container class (e.g., `'panel-icon'`). */\n  containerClassName?: string; // Override the default 'icon' container class (e.g., 'panel-icon')\n}\n\n/**\n * Props for `Icon` rendering a class-based glyph from an icon library.\n */\nexport interface IconNameProps extends IconBaseProps {\n  /** The icon name, with or without its library prefix (e.g. `'star'` or `'fa-star'`). Mutually exclusive with `children`. */\n  name: string; // e.g., 'star', 'account', 'home-outline'\n  /** A custom node (an inline SVG, a `react-icons` component, …) rendered inside the icon container in place of a class-based glyph. Mutually exclusive with `name`. */\n  children?: never;\n}\n\n/**\n * Props for `Icon` rendering a custom node (an inline SVG, a `react-icons` component, a Font\n * Awesome React `<FontAwesomeIcon>`, …) in place of a class-based glyph.\n */\nexport interface IconChildrenProps extends IconBaseProps {\n  /** The icon name, with or without its library prefix (e.g. `'star'` or `'fa-star'`). Mutually exclusive with `children`. */\n  name?: undefined;\n  /** A custom node (an inline SVG, a `react-icons` component, …) rendered inside the icon container in place of a class-based glyph. Mutually exclusive with `name`. */\n  // `undefined` is excluded deliberately: the renderer discriminates on `children !== undefined`,\n  // so `children={undefined}` would satisfy the type but fall through to the `name` path with no\n  // name and render an `fa-undefined` glyph. Excluding it keeps the advertised\n  // exactly-one-of-`name`-or-`children` constraint matching what actually renders.\n  children: Exclude<React.ReactNode, undefined>;\n}\n\n/**\n * Props for `Icon` naming its glyph through the deprecated `icon` prop instead of `name`.\n *\n * The runtime has always accepted `icon` on its own — it strips a leading library prefix off\n * the class string and falls through to the `name` path — but the type offered no member without\n * a `name` or `children`, so every caller still on the deprecated prop got an error the\n * package could not see — until #663 nothing here type-checked a test or a story, so the\n * three `Icon.test.tsx` cases exercising this path proved the runtime and said nothing about\n * the type. Declaring the path is the honest resolution: it is deprecated, not removed, and a\n * deprecation that does not type-check is a removal announced only to whoever tries it.\n *\n * @deprecated Pass `name` instead. This member goes when `icon` does.\n */\nexport interface IconDeprecatedProps extends IconBaseProps {\n  /**\n   * Legacy icon class string (e.g. `'fas fa-star'`). Only its last segment is read, as the\n   * glyph name; the library still comes from `library` or `ConfigProvider`, so\n   * `'mdi mdi-rocket'` renders an `fa` class unless the effective library is already `mdi` —\n   * set it here or on the provider.\n   *\n   * @deprecated Use `name` instead.\n   */\n  // Required here, optional on `IconBaseProps`: the other two members allow it\n  // alongside `name`, and this one is the member where it IS the glyph. Same\n  // prose in both places on purpose — the API-docs extractor reads whichever it\n  // reaches first, and the two must not drift apart.\n  icon: string;\n  /** The icon name. Absent on this path — `icon` supplies the glyph. */\n  name?: undefined;\n  /** A custom node. Mutually exclusive with `icon`. */\n  children?: never;\n}\n\n/**\n * Props for the Icon component — a discriminated union of a class-based `name`, a custom\n * `children` node, and the deprecated `icon` class string.\n */\nexport type IconProps = IconNameProps | IconChildrenProps | IconDeprecatedProps;\n\n/**\n * Strips a redundant leading library prefix from an icon name (e.g. `fa-check` -> `check`\n * for the `fa` library, `mdi-account` -> `account` for `mdi`), so `name` behaves the same\n * whether or not the caller includes the prefix. Font Awesome and Material Design Icons docs\n * conventionally refer to icons with their class prefix (`fa-check`), which otherwise gets\n * doubled by `getIconClasses` (producing `fa-fa-check`, matching no glyph).\n *\n * @param {string} name - The icon name, possibly including a redundant library prefix.\n * @param {IconLibrary} library - The icon library the name will be rendered with.\n * @returns {string} The icon name with any redundant leading library prefix removed.\n */\nfunction stripRedundantLibraryPrefix(\n  name: string,\n  library: IconLibrary\n): string {\n  if (!name) {\n    return name;\n  }\n  if (library === 'fa' && name.startsWith('fa-')) {\n    return name.substring(3);\n  }\n  if (library === 'mdi' && name.startsWith('mdi-')) {\n    return name.substring(4);\n  }\n  return name;\n}\n\n/**\n * Gets the correct classes for the icon element based on the library and features.\n *\n * @param {IconLibrary} library - The icon library.\n * @param {string} name - The icon name.\n * @param {string} [variant] - Icon style variant (e.g., 'solid', 'outlined', 'rounded').\n * @param {string | string[]} [features] - Additional library-specific modifiers.\n * @returns {string} The combined class string for the icon.\n */\nfunction getIconClasses(\n  library: IconLibrary,\n  name: string,\n  variant?: string,\n  features?: string | string[]\n): string {\n  let baseClass: string;\n  let iconClass: string;\n  const featureList = Array.isArray(features)\n    ? features\n    : features\n      ? [features]\n      : [];\n\n  switch (library) {\n    case 'fa': {\n      // Font Awesome: use variant as style ('solid' -> 'fas', 'regular' -> 'far', etc.)\n      const styleMap: Record<string, string> = {\n        solid: 'fas',\n        regular: 'far',\n        brands: 'fab',\n        light: 'fal',\n        duotone: 'fad',\n        thin: 'fat',\n      };\n      const faStyle = variant ? styleMap[variant] || variant : 'fas';\n      baseClass = faStyle;\n      iconClass = `fa-${name}`;\n      return [baseClass, iconClass, ...featureList].join(' ');\n    }\n    case 'mdi':\n      // Material Design Icons: no variants, just features\n      baseClass = 'mdi';\n      iconClass = `mdi-${name}`;\n      return [baseClass, iconClass, ...featureList].join(' ');\n    case 'material-icons': {\n      // Google Material Icons: map variants to full class names\n      const styleVariants: Record<string, string> = {\n        filled: 'material-icons',\n        outlined: 'material-icons-outlined',\n        round: 'material-icons-round',\n        sharp: 'material-icons-sharp',\n      };\n      baseClass = variant\n        ? styleVariants[variant] || `material-icons-${variant}`\n        : 'material-icons';\n      return [baseClass, ...featureList].join(' ');\n    }\n    case 'material-symbols': {\n      // Google Material Symbols: map variants to full class names\n      const styleVariants: Record<string, string> = {\n        outlined: 'material-symbols-outlined',\n        rounded: 'material-symbols-rounded',\n        sharp: 'material-symbols-sharp',\n      };\n      baseClass = variant\n        ? styleVariants[variant] || `material-symbols-${variant}`\n        : 'material-symbols-outlined';\n      return [baseClass, ...featureList].join(' ');\n    }\n    default:\n      // fallback: just icon name and features\n      return [name, ...featureList].join(' ');\n  }\n}\n\n/**\n * 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.).\n *\n * @function\n * @param {IconProps} props - Props for the Icon component.\n * @returns {JSX.Element} The rendered icon element.\n * @see {@link https://bulma.io/documentation/elements/icon/ | Bulma Icon documentation}\n */\nexport const Icon: React.FC<IconProps> = ({\n  className,\n  textColor,\n  bgColor,\n  name,\n  library,\n  variant,\n  features,\n  libraryFeatures, // Deprecated but maintained for backward compatibility\n  size,\n  ariaLabel,\n  style,\n  icon, // Capture and exclude the deprecated 'icon' prop from DOM\n  color: _color, // Exclude 'color' prop if passed directly\n  containerClassName,\n  children,\n  ...restProps\n}) => {\n  // Get the default icon library from context, fallback to 'fa' if not set\n  const defaultLibrary = useIconLibrary();\n\n  /**\n   * Generates Bulma helper classes and separates out remaining props.\n   * Note: variant, features, and libraryFeatures are excluded from props spread\n   */\n  const { bulmaHelperClasses, rest } = useBulmaClasses({\n    color: textColor,\n    backgroundColor: bgColor,\n    ...restProps,\n  });\n\n  // Hoisted unconditionally to respect rules-of-hooks; the branches below\n  // pick which result to consume.\n  const defaultIconClasses = usePrefixedClassNames('icon', {\n    [`is-${size}`]: size,\n  });\n  const sizeModifierClass = usePrefixedClassNames(\n    size ? `is-${size}` : undefined\n  );\n\n  const bulmaClasses = containerClassName\n    ? containerClassName\n    : defaultIconClasses;\n\n  const iconContainerClasses = classNames(\n    bulmaClasses,\n    containerClassName && size ? sizeModifierClass : undefined,\n    bulmaHelperClasses,\n    className\n  );\n\n  // A named icon is an image, whose name is its label alone, so a ligature inside\n  // never leaks into it. An unnamed one is decorative and hidden outright. Spread\n  // before `rest`, so a caller's own `role` or `aria-hidden` still wins.\n  const named =\n    !!ariaLabel || !!restProps['aria-label'] || !!restProps['aria-labelledby'];\n  // A caller's own `role` or `tabIndex` on an unnamed icon means it isn't decoration (an\n  // icon made a button, say), so it isn't hidden either: `aria-hidden` on something\n  // focusable is a failure of its own.\n  const a11yProps = named\n    ? { role: 'img', 'aria-label': ariaLabel || undefined }\n    : restProps.role !== undefined || restProps.tabIndex !== undefined\n      ? {}\n      : { 'aria-hidden': true };\n\n  if (children !== undefined) {\n    // `IconChildrenProps`: render the caller's node (an inline SVG, a `react-icons`\n    // component, …) in place of a class-based glyph. Library/variant/features don't apply.\n    return (\n      <span\n        className={iconContainerClasses}\n        {...a11yProps}\n        style={style}\n        {...rest}\n      >\n        {children}\n      </span>\n    );\n  }\n\n  // `name` is guaranteed once `children` is absent UNLESS the caller is on the deprecated\n  // `icon` path, which `IconDeprecatedProps` declares with `name?: undefined`.\n  // (`IconChildrenProps['children']` excludes `undefined`, so `children={undefined}` can't\n  // slip past into this branch.) The cast covers that third member, and the `!name && icon`\n  // fallback below is what fills it in.\n  let finalName = name as string;\n  if (!name && icon) {\n    // If icon prop is provided instead of name, try to parse it\n    // e.g., \"mdi mdi-rocket-launch\" -> \"rocket-launch\"\n    if (typeof icon === 'string') {\n      const parts = icon.split(' ');\n      const lastPart = parts[parts.length - 1];\n      if (lastPart.startsWith('mdi-')) {\n        finalName = lastPart.substring(4); // Remove \"mdi-\" prefix\n      } else if (lastPart.startsWith('fa-')) {\n        finalName = lastPart.substring(3); // Remove \"fa-\" prefix\n      } else {\n        finalName = lastPart;\n      }\n    }\n  }\n\n  const finalLibrary = library || defaultLibrary || 'fa';\n\n  // Normalize a redundant leading library prefix (e.g. \"fa-check\" -> \"check\" when the\n  // library is 'fa'), so `name` behaves identically with or without the prefix.\n  finalName = stripRedundantLibraryPrefix(finalName, finalLibrary);\n\n  if (!finalName) {\n    // No glyph to name. Reachable through the public type only as `icon=\"\"`, and otherwise\n    // by a plain-JS caller (or one that casts). Building a class off an absent name produced\n    // a bogus `fa-undefined` glyph; render the bare container instead, matching the\n    // `children` branch.\n    return (\n      <span\n        className={iconContainerClasses}\n        {...a11yProps}\n        style={style}\n        {...rest}\n      />\n    );\n  }\n\n  // Backward compatibility: if libraryFeatures is provided, parse it for variant and features\n  let finalVariant = variant;\n  let finalFeatures = features;\n\n  if (libraryFeatures && !variant && !features) {\n    const legacyFeatures = Array.isArray(libraryFeatures)\n      ? libraryFeatures\n      : [libraryFeatures];\n\n    // For Font Awesome, extract style from features\n    if (finalLibrary === 'fa') {\n      const faStyle = legacyFeatures.find(f =>\n        [\n          'fas',\n          'far',\n          'fab',\n          'fal',\n          'fad',\n          'fat',\n          'solid',\n          'regular',\n          'brands',\n          'light',\n          'duotone',\n          'thin',\n        ].includes(f)\n      );\n      if (faStyle) {\n        finalVariant = faStyle;\n        finalFeatures = legacyFeatures.filter(f => f !== faStyle);\n      } else {\n        finalFeatures = legacyFeatures;\n      }\n    }\n    // For Material Icons/Symbols, extract style variant\n    else if (\n      finalLibrary === 'material-icons' ||\n      finalLibrary === 'material-symbols'\n    ) {\n      const styleVariants =\n        finalLibrary === 'material-icons'\n          ? ['filled', 'outlined', 'round', 'sharp']\n          : ['outlined', 'rounded', 'sharp'];\n\n      const styleVariant = legacyFeatures.find(f => styleVariants.includes(f));\n      if (styleVariant) {\n        finalVariant = styleVariant;\n        finalFeatures = legacyFeatures.filter(f => f !== styleVariant);\n      } else {\n        finalFeatures = legacyFeatures;\n      }\n    }\n    // For others, all features go to finalFeatures\n    else {\n      finalFeatures = legacyFeatures;\n    }\n  }\n\n  // Handle web components vs CSS-based icons\n  if (finalLibrary === 'ion') {\n    // For Ionicons, handle variant in the name\n    let ionName = finalName;\n    if (finalVariant === 'outline') {\n      ionName = `${finalName}-outline`;\n    } else if (finalVariant === 'sharp') {\n      ionName = `${finalName}-sharp`;\n    }\n\n    return (\n      <span\n        className={iconContainerClasses}\n        {...a11yProps}\n        style={style}\n        {...rest}\n      >\n        <ion-icon name={ionName} />\n      </span>\n    );\n  }\n\n  // Legacy CSS-based icons\n  const iClasses = getIconClasses(\n    finalLibrary,\n    finalName,\n    finalVariant,\n    finalFeatures\n  );\n\n  // Material Icons and Material Symbols use text content, not CSS classes for the icon name\n  if (\n    finalLibrary === 'material-icons' ||\n    finalLibrary === 'material-symbols'\n  ) {\n    return (\n      <span\n        className={iconContainerClasses}\n        {...a11yProps}\n        style={style}\n        {...rest}\n      >\n        <i className={iClasses}>{finalName}</i>\n      </span>\n    );\n  }\n\n  return (\n    <span\n      className={iconContainerClasses}\n      {...a11yProps}\n      style={style}\n      {...rest}\n    >\n      <i className={iClasses} />\n    </span>\n  );\n};\n"],"names":["_jsx"],"mappings":"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"}

package/dist/esm/elements/IconText.js

@@ -0,0 +1,36 @@
+/* @allxsmith/bestax-bulma — AI agents: see AGENTS.md in the package root, or https://bestax.io/llms.txt */
+import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
+import React from 'react';
+import { usePrefixedClassNames, classNames } from '../helpers/classNames.js';
+import { withSubComponents } from '../helpers/withSubComponents.js';
+import { useBulmaClasses } from '../helpers/useBulmaClasses.js';
+import { Icon } from './Icon.js';
+import { isIconProps } from './iconProps.js';
+
+/**
+ * The `IconText` component provides a Bulma-styled horizontal arrangement of one or more `Icon` components and optional text.
+ *
+ * @function
+ * @param {IconTextProps} props - Props for the IconText component.
+ * @returns {JSX.Element} The rendered icon text element.
+ * @see {@link https://bulma.io/documentation/elements/icon/#icon-text | Bulma IconText documentation}
+ */
+const IconTextComponent = ({ className, textColor, color, bgColor, iconProps, children, items, ...props }) => {
+    /**
+     * Generates Bulma helper classes and separates out remaining props.
+     */
+    const { bulmaHelperClasses, rest } = useBulmaClasses({
+        color: textColor ?? color,
+        backgroundColor: bgColor,
+        ...props,
+    });
+    const bulmaClasses = usePrefixedClassNames('icon-text');
+    const iconTextClasses = classNames(bulmaClasses, bulmaHelperClasses, className);
+    return (jsx("span", { className: iconTextClasses, ...rest, children: items ? (items.map((item, index) => (jsxs(React.Fragment, { children: [item.iconProps &&
+                    (isIconProps(item.iconProps) ? (jsx(Icon, { ...item.iconProps })) : (jsx(Icon, { children: item.iconProps }))), item.text && jsx("span", { children: item.text })] }, index)))) : (jsxs(Fragment, { children: [iconProps &&
+                    (isIconProps(iconProps) ? (jsx(Icon, { ...iconProps })) : (jsx(Icon, { children: iconProps }))), children && jsx("span", { children: children })] })) }));
+};
+const IconText = withSubComponents(IconTextComponent, { Icon }, 'IconText');
+
+export { IconText };
+//# sourceMappingURL=IconText.js.map

package/dist/esm/elements/IconText.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IconText.js","sources":["../../../src/elements/IconText.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 { Icon, IconProps } from './Icon';\nimport { isIconProps } from './iconProps';\n\n/**\n * Represents an item for the IconText component, containing icon props and optional text.\n */\ninterface IconTextItem {\n  /** Props for the Icon component, or a custom node (an inline SVG, a `react-icons` component, …) rendered in place of a class-based glyph. */\n  iconProps: IconProps | React.ReactNode;\n  /** Optional text to display next to the icon. */\n  text?: string;\n}\n\n/**\n * Props for the IconText component.\n */\ninterface IconTextProps\n  extends React.HTMLAttributes<HTMLSpanElement>, BulmaClassesProps {\n  /** Additional CSS classes to apply. */\n  className?: string;\n  /** Text color helper. */\n  textColor?: (typeof validColors)[number] | 'inherit' | 'current';\n  /**\n   * Text color alias: renders `has-text-<color>`, exactly like `textColor`.\n   * Not a filled variant (no `.icon-text.is-<color>` CSS exists). Prefer\n   * `textColor`, which takes precedence when both are set; use `bgColor` for\n   * a colored surface.\n   */\n  color?: 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger';\n  /** Background color helper. */\n  bgColor?: (typeof validColors)[number] | 'inherit' | 'current';\n  /** Props for a single Icon component, or a custom node, for single icon mode. */\n  iconProps?: IconProps | React.ReactNode; // For single icon\n  /** Text for a single icon (for single icon mode). */\n  children?: React.ReactNode; // Text for single icon\n  /** Array of icon/text pairs (for multiple icons mode). */\n  items?: IconTextItem[]; // For multiple icons\n}\n\n/**\n * The `IconText` component provides a Bulma-styled horizontal arrangement of one or more `Icon` components and optional text.\n *\n * @function\n * @param {IconTextProps} props - Props for the IconText component.\n * @returns {JSX.Element} The rendered icon text element.\n * @see {@link https://bulma.io/documentation/elements/icon/#icon-text | Bulma IconText documentation}\n */\nconst IconTextComponent: React.FC<IconTextProps> = ({\n  className,\n  textColor,\n  color,\n  bgColor,\n  iconProps,\n  children,\n  items,\n  ...props\n}) => {\n  /**\n   * Generates Bulma helper classes and separates out remaining props.\n   */\n  const { bulmaHelperClasses, rest } = useBulmaClasses({\n    color: textColor ?? color,\n    backgroundColor: bgColor,\n    ...props,\n  });\n\n  const bulmaClasses = usePrefixedClassNames('icon-text');\n  const iconTextClasses = classNames(\n    bulmaClasses,\n    bulmaHelperClasses,\n    className\n  );\n\n  return (\n    <span className={iconTextClasses} {...rest}>\n      {items ? (\n        items.map((item, index) => (\n          <React.Fragment key={index}>\n            {item.iconProps &&\n              (isIconProps(item.iconProps) ? (\n                <Icon {...item.iconProps} />\n              ) : (\n                <Icon>{item.iconProps}</Icon>\n              ))}\n            {item.text && <span>{item.text}</span>}\n          </React.Fragment>\n        ))\n      ) : (\n        <>\n          {iconProps &&\n            (isIconProps(iconProps) ? (\n              <Icon {...iconProps} />\n            ) : (\n              <Icon>{iconProps}</Icon>\n            ))}\n          {children && <span>{children}</span>}\n        </>\n      )}\n    </span>\n  );\n};\n\nexport const IconText = withSubComponents(\n  IconTextComponent,\n  { Icon },\n  'IconText'\n);\n"],"names":["_jsx","_jsxs","_Fragment"],"mappings":";;;;;;;;;AA+CA;;;;;;;AAOG;AACH,MAAM,iBAAiB,GAA4B,CAAC,EAClD,SAAS,EACT,SAAS,EACT,KAAK,EACL,OAAO,EACP,SAAS,EACT,QAAQ,EACR,KAAK,EACL,GAAG,KAAK,EACT,KAAI;AACH;;AAEG;AACH,IAAA,MAAM,EAAE,kBAAkB,EAAE,IAAI,EAAE,GAAG,eAAe,CAAC;QACnD,KAAK,EAAE,SAAS,IAAI,KAAK;AACzB,QAAA,eAAe,EAAE,OAAO;AACxB,QAAA,GAAG,KAAK;AACT,KAAA,CAAC;AAEF,IAAA,MAAM,YAAY,GAAG,qBAAqB,CAAC,WAAW,CAAC;IACvD,MAAM,eAAe,GAAG,UAAU,CAChC,YAAY,EACZ,kBAAkB,EAClB,SAAS,CACV;AAED,IAAA,QACEA,GAAA,CAAA,MAAA,EAAA,EAAM,SAAS,EAAE,eAAe,EAAA,GAAM,IAAI,EAAA,QAAA,EACvC,KAAK,IACJ,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,MACpBC,IAAA,CAAC,KAAK,CAAC,QAAQ,EAAA,EAAA,QAAA,EAAA,CACZ,IAAI,CAAC,SAAS;qBACZ,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,IAC1BD,GAAA,CAAC,IAAI,OAAK,IAAI,CAAC,SAAS,EAAA,CAAI,KAE5BA,GAAA,CAAC,IAAI,EAAA,EAAA,QAAA,EAAE,IAAI,CAAC,SAAS,EAAA,CAAQ,CAC9B,CAAC,EACH,IAAI,CAAC,IAAI,IAAIA,GAAA,CAAA,MAAA,EAAA,EAAA,QAAA,EAAO,IAAI,CAAC,IAAI,GAAQ,CAAA,EAAA,EAPnB,KAAK,CAQT,CAClB,CAAC,KAEFC,IAAA,CAAAC,QAAA,EAAA,EAAA,QAAA,EAAA,CACG,SAAS;AACR,qBAAC,WAAW,CAAC,SAAS,CAAC,IACrBF,GAAA,CAAC,IAAI,EAAA,EAAA,GAAK,SAAS,EAAA,CAAI,KAEvBA,GAAA,CAAC,IAAI,EAAA,EAAA,QAAA,EAAE,SAAS,EAAA,CAAQ,CACzB,CAAC,EACH,QAAQ,IAAIA,GAAA,CAAA,MAAA,EAAA,EAAA,QAAA,EAAO,QAAQ,EAAA,CAAQ,CAAA,EAAA,CACnC,CACJ,EAAA,CACI;AAEX,CAAC;AAEM,MAAM,QAAQ,GAAG,iBAAiB,CACvC,iBAAiB,EACjB,EAAE,IAAI,EAAE,EACR,UAAU;;"}

package/dist/esm/elements/Image.js

@@ -0,0 +1,46 @@
+/* @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 { useBulmaClasses } from '../helpers/useBulmaClasses.js';
+
+/**
+ * The `Image` component wraps images, iframes, or custom content in a Bulma-styled container, supporting fixed sizes, aspect ratios, rounded corners, retina images, and all Bulma helper props for color and spacing.
+ *
+ * @function
+ * @param {ImageProps} props - Props for the Image component.
+ * @returns {JSX.Element} The rendered image element.
+ * @see {@link https://bulma.io/documentation/elements/image/ | Bulma Image documentation}
+ */
+const Image = ({ as, className, textColor, color, bgColor, size, isRounded, isRetina, src, alt, children, ...props }) => {
+    /**
+     * Generates Bulma helper classes and separates out remaining props.
+     */
+    const { bulmaHelperClasses, rest } = useBulmaClasses({
+        color: textColor ?? color,
+        backgroundColor: bgColor,
+        ...props,
+    });
+    const bulmaClasses = usePrefixedClassNames('image', {
+        [`is-${size}`]: size,
+        'has-ratio': size && typeof size === 'string' && size.includes('by'),
+    });
+    const imageClasses = classNames(bulmaClasses, bulmaHelperClasses, className);
+    // Default tag logic: if "as" is provided, use it.
+    // If not, use <figure> for aspect ratios or children, <div> otherwise.
+    let Tag;
+    if (as) {
+        Tag = as;
+    }
+    else if (size && typeof size === 'string' && size.includes('by')) {
+        Tag = 'figure';
+    }
+    else {
+        Tag = 'div';
+    }
+    const roundedClass = usePrefixedClassNames('is-rounded');
+    const content = children ? (children) : (jsx("img", { className: classNames({ [roundedClass]: isRounded }) || undefined, src: src, alt: alt, ...(isRetina && src ? { srcSet: `${src} 2x` } : {}) }));
+    return (jsx(Tag, { className: imageClasses, ...rest, children: content }));
+};
+
+export { Image };
+//# sourceMappingURL=Image.js.map

package/dist/esm/elements/Image.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Image.js","sources":["../../../src/elements/Image.tsx"],"sourcesContent":["import React from 'react';\nimport { classNames, usePrefixedClassNames } from '../helpers/classNames';\nimport {\n  useBulmaClasses,\n  BulmaClassesProps,\n  validColors,\n} from '../helpers/useBulmaClasses';\n\n/**\n * Props for the Image component.\n */\nexport interface ImageProps\n  extends\n    React.HTMLAttributes<HTMLElement>,\n    Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {\n  /** Additional CSS classes to apply. */\n  className?: string;\n  /** Text color helper for the container. */\n  textColor?: (typeof validColors)[number] | 'inherit' | 'current';\n  /**\n   * Text color alias: renders `has-text-<color>`, exactly like `textColor`.\n   * Not a filled variant (no `.image.is-<color>` CSS exists). Prefer\n   * `textColor`, which takes precedence when both are set; use `bgColor` for\n   * a colored surface.\n   */\n  color?: 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger';\n  /** Background color helper for the container. */\n  bgColor?: (typeof validColors)[number] | 'inherit' | 'current';\n  /** Fixed size or aspect ratio modifier for the image container. */\n  size?:\n    | '16x16'\n    | '24x24'\n    | '32x32'\n    | '48x48'\n    | '64x64'\n    | '96x96'\n    | '128x128'\n    | 'square'\n    | '1by1'\n    | '5by4'\n    | '4by3'\n    | '3by2'\n    | '5by3'\n    | '16by9'\n    | '2by1'\n    | '3by1'\n    | '4by5'\n    | '3by4'\n    | '2by3'\n    | '3by5'\n    | '9by16'\n    | '1by2'\n    | '1by3';\n  /** Renders the image with rounded corners. */\n  isRounded?: boolean;\n  /** Uses retina (2x) image source. */\n  isRetina?: boolean;\n  /** Image source URL. */\n  src?: string;\n  /** Alternate text for the image. */\n  alt?: string;\n  /** Arbitrary content (e.g., iframe, custom HTML) inside the image container. */\n  children?: React.ReactNode;\n  /** Container element tag. Defaults to `'figure'` when using aspect-ratio sizes, `'div'` otherwise. */\n  as?: 'figure' | 'div' | 'p';\n}\n\n/**\n * The `Image` component wraps images, iframes, or custom content in a Bulma-styled container, supporting fixed sizes, aspect ratios, rounded corners, retina images, and all Bulma helper props for color and spacing.\n *\n * @function\n * @param {ImageProps} props - Props for the Image component.\n * @returns {JSX.Element} The rendered image element.\n * @see {@link https://bulma.io/documentation/elements/image/ | Bulma Image documentation}\n */\nexport const Image: React.FC<ImageProps> = ({\n  as,\n  className,\n  textColor,\n  color,\n  bgColor,\n  size,\n  isRounded,\n  isRetina,\n  src,\n  alt,\n  children,\n  ...props\n}) => {\n  /**\n   * Generates Bulma helper classes and separates out remaining props.\n   */\n  const { bulmaHelperClasses, rest } = useBulmaClasses({\n    color: textColor ?? color,\n    backgroundColor: bgColor,\n    ...props,\n  });\n\n  const bulmaClasses = usePrefixedClassNames('image', {\n    [`is-${size}`]: size,\n    'has-ratio': size && typeof size === 'string' && size.includes('by'),\n  });\n\n  const imageClasses = classNames(bulmaClasses, bulmaHelperClasses, className);\n\n  // Default tag logic: if \"as\" is provided, use it.\n  // If not, use <figure> for aspect ratios or children, <div> otherwise.\n  let Tag: 'figure' | 'div' | 'p';\n  if (as) {\n    Tag = as;\n  } else if (size && typeof size === 'string' && size.includes('by')) {\n    Tag = 'figure';\n  } else {\n    Tag = 'div';\n  }\n\n  const roundedClass = usePrefixedClassNames('is-rounded');\n\n  const content = children ? (\n    children\n  ) : (\n    <img\n      className={classNames({ [roundedClass]: isRounded }) || undefined}\n      src={src}\n      alt={alt}\n      {...(isRetina && src ? { srcSet: `${src} 2x` } : {})}\n    />\n  );\n\n  return (\n    <Tag className={imageClasses} {...rest}>\n      {content}\n    </Tag>\n  );\n};\n\nexport default Image;\n"],"names":["_jsx"],"mappings":";;;;;AAmEA;;;;;;;AAOG;AACI,MAAM,KAAK,GAAyB,CAAC,EAC1C,EAAE,EACF,SAAS,EACT,SAAS,EACT,KAAK,EACL,OAAO,EACP,IAAI,EACJ,SAAS,EACT,QAAQ,EACR,GAAG,EACH,GAAG,EACH,QAAQ,EACR,GAAG,KAAK,EACT,KAAI;AACH;;AAEG;AACH,IAAA,MAAM,EAAE,kBAAkB,EAAE,IAAI,EAAE,GAAG,eAAe,CAAC;QACnD,KAAK,EAAE,SAAS,IAAI,KAAK;AACzB,QAAA,eAAe,EAAE,OAAO;AACxB,QAAA,GAAG,KAAK;AACT,KAAA,CAAC;AAEF,IAAA,MAAM,YAAY,GAAG,qBAAqB,CAAC,OAAO,EAAE;AAClD,QAAA,CAAC,CAAA,GAAA,EAAM,IAAI,CAAA,CAAE,GAAG,IAAI;AACpB,QAAA,WAAW,EAAE,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;AACrE,KAAA,CAAC;IAEF,MAAM,YAAY,GAAG,UAAU,CAAC,YAAY,EAAE,kBAAkB,EAAE,SAAS,CAAC;;;AAI5E,IAAA,IAAI,GAA2B;IAC/B,IAAI,EAAE,EAAE;QACN,GAAG,GAAG,EAAE;IACV;AAAO,SAAA,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE;QAClE,GAAG,GAAG,QAAQ;IAChB;SAAO;QACL,GAAG,GAAG,KAAK;IACb;AAEA,IAAA,MAAM,YAAY,GAAG,qBAAqB,CAAC,YAAY,CAAC;IAExD,MAAM,OAAO,GAAG,QAAQ,IACtB,QAAQ,KAERA,GAAA,CAAA,KAAA,EAAA,EACE,SAAS,EAAE,UAAU,CAAC,EAAE,CAAC,YAAY,GAAG,SAAS,EAAE,CAAC,IAAI,SAAS,EACjE,GAAG,EAAE,GAAG,EACR,GAAG,EAAE,GAAG,EAAA,IACH,QAAQ,IAAI,GAAG,GAAG,EAAE,MAAM,EAAE,CAAA,EAAG,GAAG,CAAA,GAAA,CAAK,EAAE,GAAG,EAAE,CAAC,EAAA,CACpD,CACH;AAED,IAAA,QACEA,GAAA,CAAC,GAAG,EAAA,EAAC,SAAS,EAAE,YAAY,EAAA,GAAM,IAAI,EAAA,QAAA,EACnC,OAAO,EAAA,CACJ;AAEV;;"}

package/dist/esm/elements/Link.js

@@ -0,0 +1,36 @@
+/* @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 { forwardRef } from 'react';
+import { usePrefixedClassNames, classNames } from '../helpers/classNames.js';
+import { buttonType } from '../helpers/buttonType.js';
+import { useBulmaClasses } from '../helpers/useBulmaClasses.js';
+
+/**
+ * The `Link` component renders a styled anchor (`<a>`) element with Bulma helper class integration.
+ *
+ * @function
+ * @param {LinkProps} props - Props for the Link component.
+ * @param {React.Ref} ref - Forwarded ref to the element `as` renders.
+ * @returns {JSX.Element} The rendered anchor, or whatever `as` names.
+ * @see {@link https://bulma.io/documentation/elements/content/ | Bulma Content documentation}
+ */
+const Link = forwardRef(function Link(linkProps, ref) {
+    const { className, textColor, bgColor, isActive, as: Component = 'a', children, ...props } = linkProps;
+    /**
+     * Generates Bulma helper classes and separates out remaining props.
+     */
+    const { bulmaHelperClasses, rest } = useBulmaClasses({
+        color: textColor,
+        backgroundColor: bgColor,
+        ...props,
+    });
+    const bulmaClasses = usePrefixedClassNames({
+        'is-active': isActive,
+    });
+    const linkClasses = classNames(bulmaClasses, bulmaHelperClasses, className);
+    return (jsx(Component, { ref: ref, className: linkClasses || undefined, ...rest, ...(Component === 'button' ? { type: buttonType(rest.type) } : {}), children: children }));
+});
+Link.displayName = 'Link';
+
+export { Link };
+//# sourceMappingURL=Link.js.map

package/dist/esm/elements/Link.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Link.js","sources":["../../../src/elements/Link.tsx"],"sourcesContent":["import React, { forwardRef } from 'react';\nimport { classNames, usePrefixedClassNames } from '../helpers/classNames';\nimport type { PolymorphicComponent } from '../helpers/polymorphic';\nimport { buttonType } from '../helpers/buttonType';\nimport {\n  useBulmaClasses,\n  BulmaClassesProps,\n  validColors,\n} from '../helpers/useBulmaClasses';\n\n/**\n * The Link component's own props — everything it adds on top of the attributes\n * of whatever element `as` renders.\n */\nexport interface LinkOwnProps extends Omit<\n  BulmaClassesProps,\n  'color' | 'backgroundColor'\n> {\n  /**\n   * Not accepted. `color` on this component would be the deprecated\n   * presentational HTML attribute, and `useBulmaClasses` consumes any `color`\n   * key as a Bulma helper before the target could see it — so it is declared\n   * unavailable rather than silently eaten. Use `textColor` / `bgColor`.\n   * @internal\n   */\n  color?: never;\n  /**\n   * Not accepted under this name. `useBulmaClasses` consumes any\n   * `backgroundColor` key before `rest` is spread, so a custom `as` target\n   * declaring one would never receive it. Use `bgColor`.\n   * @internal\n   */\n  backgroundColor?: never;\n  /** Additional CSS classes to apply. */\n  className?: string;\n  /** Text color helper. */\n  textColor?: (typeof validColors)[number] | 'inherit' | 'current';\n  /** Background color helper. */\n  bgColor?: (typeof validColors)[number] | 'inherit' | 'current';\n  /** Whether the link appears active. */\n  isActive?: boolean;\n  /** Content to render inside the link. */\n  children?: React.ReactNode;\n}\n\n/**\n * Props for the Link component. The DOM attributes and the `ref` both follow\n * `as`: with the default `'a'` the anchor attributes (`href`, `target`, `rel`)\n * are accepted, with `as=\"span\"` they are not.\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 LinkProps<T extends React.ElementType = 'a'> = LinkOwnProps &\n  Omit<React.ComponentPropsWithoutRef<T>, keyof LinkOwnProps | 'as'> & {\n    /**\n     * Render as another intrinsic element (`'span'`, `'button'`) or a custom component (e.g. a router `Link`) instead of `<a>`. Defaults to `'a'`.\n     *\n     * `'button'` renders `type=\"button\"`, so a link inside a form does not submit it. Pass\n     * `type=\"submit\"` or `type=\"reset\"` and yours is used; any other value, or a spread\n     * carrying `type: undefined`, renders `type=\"button\"`.\n     */\n    as?: T;\n  };\n\n/**\n * The shape the implementation destructures. The public contract is the generic\n * `LinkProps<T>` above — the body cannot see through `T`, so it reads the widest\n * form of the props it actually touches.\n */\ntype LinkImplProps = LinkOwnProps & {\n  as?: React.ElementType;\n  type?: React.ButtonHTMLAttributes<HTMLButtonElement>['type'];\n};\n\n/**\n * The `Link` component renders a styled anchor (`<a>`) element with Bulma helper class integration.\n *\n * @function\n * @param {LinkProps} props - Props for the Link component.\n * @param {React.Ref} ref - Forwarded ref to the element `as` renders.\n * @returns {JSX.Element} The rendered anchor, or whatever `as` names.\n * @see {@link https://bulma.io/documentation/elements/content/ | Bulma Content documentation}\n */\nexport const Link = forwardRef(function Link(\n  linkProps: LinkProps,\n  ref: React.Ref<HTMLElement>\n) {\n  const {\n    className,\n    textColor,\n    bgColor,\n    isActive,\n    as: Component = 'a',\n    children,\n    ...props\n  } = linkProps as LinkImplProps;\n  /**\n   * Generates Bulma helper classes and separates out remaining props.\n   */\n  const { bulmaHelperClasses, rest } = useBulmaClasses({\n    color: textColor,\n    backgroundColor: bgColor,\n    ...props,\n  } as BulmaClassesProps & typeof props);\n\n  const bulmaClasses = usePrefixedClassNames({\n    'is-active': isActive,\n  });\n  const linkClasses = classNames(bulmaClasses, bulmaHelperClasses, className);\n\n  return (\n    <Component\n      ref={ref}\n      className={linkClasses || undefined}\n      {...rest}\n      // A `<button>` defaults to type=\"submit\", and a link-styled button inside\n      // a form must not submit it. After the spread, reading through it, so a\n      // spread carrying `type: undefined` cannot erase the default. A caller's\n      // `submit` or `reset` still wins; `buttonType` says more.\n      {...(Component === 'button' ? { type: buttonType(rest.type) } : {})}\n    >\n      {children}\n    </Component>\n  );\n}) as PolymorphicComponent<LinkOwnProps, 'a'>;\n\nLink.displayName = 'Link';\n"],"names":["_jsx"],"mappings":";;;;;;;AA0EA;;;;;;;;AAQG;AACI,MAAM,IAAI,GAAG,UAAU,CAAC,SAAS,IAAI,CAC1C,SAAoB,EACpB,GAA2B,EAAA;IAE3B,MAAM,EACJ,SAAS,EACT,SAAS,EACT,OAAO,EACP,QAAQ,EACR,EAAE,EAAE,SAAS,GAAG,GAAG,EACnB,QAAQ,EACR,GAAG,KAAK,EACT,GAAG,SAA0B;AAC9B;;AAEG;AACH,IAAA,MAAM,EAAE,kBAAkB,EAAE,IAAI,EAAE,GAAG,eAAe,CAAC;AACnD,QAAA,KAAK,EAAE,SAAS;AAChB,QAAA,eAAe,EAAE,OAAO;AACxB,QAAA,GAAG,KAAK;AAC2B,KAAA,CAAC;IAEtC,MAAM,YAAY,GAAG,qBAAqB,CAAC;AACzC,QAAA,WAAW,EAAE,QAAQ;AACtB,KAAA,CAAC;IACF,MAAM,WAAW,GAAG,UAAU,CAAC,YAAY,EAAE,kBAAkB,EAAE,SAAS,CAAC;AAE3E,IAAA,QACEA,GAAA,CAAC,SAAS,IACR,GAAG,EAAE,GAAG,EACR,SAAS,EAAE,WAAW,IAAI,SAAS,EAAA,GAC/B,IAAI,MAKH,SAAS,KAAK,QAAQ,GAAG,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC,YAElE,QAAQ,EAAA,CACC;AAEhB,CAAC;AAED,IAAI,CAAC,WAAW,GAAG,MAAM;;"}

package/dist/esm/elements/LinkButton.js

@@ -0,0 +1,37 @@
+/* @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 { forwardRef } from 'react';
+import { Button } from './Button.js';
+import { usePrefixedClassNames, classNames } from '../helpers/classNames.js';
+
+/**
+ * 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} ref - Forwarded ref to the element `as` renders.
+ * @returns {JSX.Element} The rendered link-styled button element.
+ *
+ * @example
+ * // Text variant (default)
+ * <LinkButton onClick={handleClick}>Click me</LinkButton>
+ *
+ * @example
+ * // Underline variant with color
+ * <LinkButton variant="underline" color="primary">Learn more</LinkButton>
+ */
+const LinkButton = forwardRef(function LinkButton({ variant = 'text', color, className, ...props }, ref) {
+    const buttonColor = variant === 'underline' ? 'text' : variant;
+    const prefixedClasses = usePrefixedClassNames('link-button', color && `link-button-${color}`, variant === 'underline' && 'link-button-underline');
+    return (jsx(Button
+    // LinkButton is polymorphic through to Button, which resolves the element
+    // from `as`. TS cannot infer that through the spread below.
+    , { 
+        // LinkButton is polymorphic through to Button, which resolves the element
+        // from `as`. TS cannot infer that through the spread below.
+        ref: ref, color: buttonColor, className: classNames(prefixedClasses, className), ...props }));
+});
+LinkButton.displayName = 'LinkButton';
+
+export { LinkButton };
+//# sourceMappingURL=LinkButton.js.map

package/dist/esm/elements/LinkButton.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LinkButton.js","sources":["../../../src/elements/LinkButton.tsx"],"sourcesContent":["import React, { forwardRef } from 'react';\nimport { Button, ButtonOwnProps } from './Button';\nimport { classNames, usePrefixedClassNames } from '../helpers/classNames';\nimport type { PolymorphicComponent } from '../helpers/polymorphic';\n\n/**\n * The LinkButton component's own props — everything it adds on top of the\n * attributes of whatever element `as` renders.\n */\nexport interface LinkButtonOwnProps extends Omit<\n  ButtonOwnProps,\n  'color' | 'isOutlined' | 'isInverted' | 'isLight'\n> {\n  /** 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. */\n  variant?: 'text' | 'ghost' | 'underline';\n  /** Text color override for the button. */\n  color?:\n    | 'primary'\n    | 'link'\n    | 'info'\n    | 'success'\n    | 'warning'\n    | 'danger'\n    | 'white'\n    | 'light'\n    | 'dark'\n    | 'black';\n  /**\n   * Not available on `LinkButton`, and declared so that a custom `as` target\n   * cannot reintroduce it. `Button` consumes these three for styling variants\n   * `LinkButton` does not offer, and strips them before rendering the target —\n   * so without this a component requiring one would type-check and silently\n   * never receive it.\n   * @internal\n   */\n  isOutlined?: never;\n  /** @internal Not available on `LinkButton` — see `isOutlined`. */\n  isInverted?: never;\n  /** @internal Not available on `LinkButton` — see `isOutlined`. */\n  isLight?: never;\n}\n\n/**\n * Props for the LinkButton component. The DOM attributes and the `ref` both\n * follow `as`, exactly as they do on `Button`.\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 LinkButtonProps<T extends React.ElementType = 'button'> =\n  LinkButtonOwnProps &\n    Omit<React.ComponentPropsWithoutRef<T>, keyof LinkButtonOwnProps | 'as'> & {\n      /**\n       * Render as a `<button>`, `<a>`, or a custom component (e.g. a router `Link`).\n       * @defaultValue 'button'\n       */\n      as?: T;\n    };\n\n/**\n * The `LinkButton` component renders a `<button>` that visually looks like text or a link.\n *\n * @function\n * @param {LinkButtonProps} props - Props for the LinkButton component.\n * @param {React.Ref} ref - Forwarded ref to the element `as` renders.\n * @returns {JSX.Element} The rendered link-styled button element.\n *\n * @example\n * // Text variant (default)\n * <LinkButton onClick={handleClick}>Click me</LinkButton>\n *\n * @example\n * // Underline variant with color\n * <LinkButton variant=\"underline\" color=\"primary\">Learn more</LinkButton>\n */\nexport const LinkButton = forwardRef(function LinkButton(\n  { variant = 'text', color, className, ...props }: LinkButtonProps,\n  ref: React.Ref<HTMLElement>\n) {\n  const buttonColor = variant === 'underline' ? 'text' : variant;\n\n  const prefixedClasses = usePrefixedClassNames(\n    'link-button',\n    color && `link-button-${color}`,\n    variant === 'underline' && 'link-button-underline'\n  );\n\n  return (\n    <Button\n      // LinkButton is polymorphic through to Button, which resolves the element\n      // from `as`. TS cannot infer that through the spread below.\n      ref={ref as React.Ref<HTMLButtonElement>}\n      color={buttonColor}\n      className={classNames(prefixedClasses, className)}\n      {...props}\n    />\n  );\n}) as PolymorphicComponent<LinkButtonOwnProps, 'button'>;\n\nLinkButton.displayName = 'LinkButton';\n\nexport default LinkButton;\n"],"names":["_jsx"],"mappings":";;;;;;AA0DA;;;;;;;;;;;;;;;AAeG;MACU,UAAU,GAAG,UAAU,CAAC,SAAS,UAAU,CACtD,EAAE,OAAO,GAAG,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,KAAK,EAAmB,EACjE,GAA2B,EAAA;AAE3B,IAAA,MAAM,WAAW,GAAG,OAAO,KAAK,WAAW,GAAG,MAAM,GAAG,OAAO;AAE9D,IAAA,MAAM,eAAe,GAAG,qBAAqB,CAC3C,aAAa,EACb,KAAK,IAAI,CAAA,YAAA,EAAe,KAAK,CAAA,CAAE,EAC/B,OAAO,KAAK,WAAW,IAAI,uBAAuB,CACnD;IAED,QACEA,IAAC;;;;;;AAGC,QAAA,GAAG,EAAE,GAAmC,EACxC,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,UAAU,CAAC,eAAe,EAAE,SAAS,CAAC,KAC7C,KAAK,EAAA,CACT;AAEN,CAAC;AAED,UAAU,CAAC,WAAW,GAAG,YAAY;;"}

package/dist/esm/elements/ListItem.js

@@ -0,0 +1,28 @@
+/* @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 { useBulmaClasses } from '../helpers/useBulmaClasses.js';
+
+/**
+ * The `ListItem` component renders a styled list item (`<li>`) element with Bulma helper class integration.
+ *
+ * @function
+ * @param {ListItemProps} props - Props for the ListItem component.
+ * @returns {JSX.Element} The rendered li element.
+ */
+const ListItem = ({ className, textColor, bgColor, children, ...props }) => {
+    /**
+     * Generates Bulma helper classes and separates out remaining props.
+     */
+    const { bulmaHelperClasses, rest } = useBulmaClasses({
+        color: textColor,
+        backgroundColor: bgColor,
+        ...props,
+    });
+    const bulmaClasses = usePrefixedClassNames();
+    const itemClasses = classNames(bulmaClasses, bulmaHelperClasses, className);
+    return (jsx("li", { className: itemClasses || undefined, ...rest, children: children }));
+};
+
+export { ListItem };
+//# sourceMappingURL=ListItem.js.map

package/dist/esm/elements/ListItem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ListItem.js","sources":["../../../src/elements/ListItem.tsx"],"sourcesContent":["import React from 'react';\nimport { classNames, usePrefixedClassNames } from '../helpers/classNames';\nimport {\n  useBulmaClasses,\n  BulmaClassesProps,\n  validColors,\n} from '../helpers/useBulmaClasses';\n\n/**\n * Props for the ListItem component.\n * @extraProp {number} [value] - Custom value for ordered list items.\n */\nexport interface ListItemProps\n  extends\n    React.LiHTMLAttributes<HTMLLIElement>,\n    Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {\n  /** Additional CSS classes to apply. */\n  className?: string;\n  /** Text color helper. */\n  textColor?: (typeof validColors)[number] | 'inherit' | 'current';\n  /** Background color helper. */\n  bgColor?: (typeof validColors)[number] | 'inherit' | 'current';\n  /** Content to render inside the list item. */\n  children?: React.ReactNode;\n}\n\n/**\n * The `ListItem` component renders a styled list item (`<li>`) element with Bulma helper class integration.\n *\n * @function\n * @param {ListItemProps} props - Props for the ListItem component.\n * @returns {JSX.Element} The rendered li element.\n */\nexport const ListItem: React.FC<ListItemProps> = ({\n  className,\n  textColor,\n  bgColor,\n  children,\n  ...props\n}) => {\n  /**\n   * Generates Bulma helper classes and separates out remaining props.\n   */\n  const { bulmaHelperClasses, rest } = useBulmaClasses({\n    color: textColor,\n    backgroundColor: bgColor,\n    ...props,\n  } as BulmaClassesProps & typeof props);\n\n  const bulmaClasses = usePrefixedClassNames();\n  const itemClasses = classNames(bulmaClasses, bulmaHelperClasses, className);\n\n  return (\n    <li className={itemClasses || undefined} {...rest}>\n      {children}\n    </li>\n  );\n};\n"],"names":["_jsx"],"mappings":";;;;;AA0BA;;;;;;AAMG;AACI,MAAM,QAAQ,GAA4B,CAAC,EAChD,SAAS,EACT,SAAS,EACT,OAAO,EACP,QAAQ,EACR,GAAG,KAAK,EACT,KAAI;AACH;;AAEG;AACH,IAAA,MAAM,EAAE,kBAAkB,EAAE,IAAI,EAAE,GAAG,eAAe,CAAC;AACnD,QAAA,KAAK,EAAE,SAAS;AAChB,QAAA,eAAe,EAAE,OAAO;AACxB,QAAA,GAAG,KAAK;AAC2B,KAAA,CAAC;AAEtC,IAAA,MAAM,YAAY,GAAG,qBAAqB,EAAE;IAC5C,MAAM,WAAW,GAAG,UAAU,CAAC,YAAY,EAAE,kBAAkB,EAAE,SAAS,CAAC;AAE3E,IAAA,QACEA,GAAA,CAAA,IAAA,EAAA,EAAI,SAAS,EAAE,WAAW,IAAI,SAAS,EAAA,GAAM,IAAI,EAAA,QAAA,EAC9C,QAAQ,EAAA,CACN;AAET;;"}

package/dist/esm/elements/Loader.js

@@ -0,0 +1,37 @@
+/* @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 { forwardRef } from 'react';
+import { usePrefixedClassNames, classNames } from '../helpers/classNames.js';
+import { useBulmaClasses } from '../helpers/useBulmaClasses.js';
+
+/**
+ * The `Loader` component renders Bulma's `.loader`, a small spinning ring for inline loading states.
+ *
+ * The ring is `1em` square, so `textSize` scales it. It is exposed as an
+ * indeterminate `progressbar` named by `ariaLabel`, and it stops spinning
+ * under `prefers-reduced-motion: reduce` while staying drawn.
+ *
+ * @function
+ * @param {LoaderProps} props - Props for the Loader component.
+ * @param {React.Ref<HTMLSpanElement>} ref - Forwarded ref to the loader element.
+ * @returns {JSX.Element} The rendered loader element.
+ *
+ * @example
+ * <Loader />
+ *
+ * @example
+ * <Loader textSize="3" ariaLabel="Saving" />
+ */
+const Loader = forwardRef(({ className, ariaLabel = 'Loading', ...props }, ref) => {
+    const { bulmaHelperClasses, rest } = useBulmaClasses(props);
+    const loaderClass = usePrefixedClassNames('loader');
+    // role="progressbar", not role="status": a status region mounted together
+    // with its text is not reliably announced, so the loader claims only what
+    // it can deliver, a named indicator found by reading the page. No
+    // aria-valuenow, because the progress is indeterminate.
+    return (jsx("span", { ref: ref, className: classNames(loaderClass, bulmaHelperClasses, className), role: "progressbar", "aria-label": ariaLabel, ...rest }));
+});
+Loader.displayName = 'Loader';
+
+export { Loader };
+//# sourceMappingURL=Loader.js.map

package/dist/esm/elements/Loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Loader.js","sources":["../../../src/elements/Loader.tsx"],"sourcesContent":["import React, { forwardRef } from 'react';\nimport { classNames, usePrefixedClassNames } from '../helpers/classNames';\nimport { useBulmaClasses, BulmaClassesProps } from '../helpers/useBulmaClasses';\n\n/**\n * Props for the Loader component.\n *\n * There is no color prop, and the text and background color helpers are left\n * out on purpose: Bulma draws the ring in `--bulma-border`, so a text color\n * never reaches it. For a colored spinner over a region, use `Loading`.\n *\n * @extraProp {React.Ref<HTMLSpanElement>} [ref] - Ref forwarded to the loader element.\n */\nexport interface LoaderProps\n  extends\n    Omit<React.HTMLAttributes<HTMLSpanElement>, 'color' | 'children'>,\n    Omit<\n      BulmaClassesProps,\n      'color' | 'colorShade' | 'backgroundColor' | 'backgroundColorShade'\n    > {\n  /** Additional CSS classes to apply. */\n  className?: string;\n  /**\n   * Accessible name of the progress indicator. Name what is loading\n   * (`\"Saving row\"`) when more than one loader can be on screen at once.\n   */\n  ariaLabel?: string;\n}\n\n/**\n * The `Loader` component renders Bulma's `.loader`, a small spinning ring for inline loading states.\n *\n * The ring is `1em` square, so `textSize` scales it. It is exposed as an\n * indeterminate `progressbar` named by `ariaLabel`, and it stops spinning\n * under `prefers-reduced-motion: reduce` while staying drawn.\n *\n * @function\n * @param {LoaderProps} props - Props for the Loader component.\n * @param {React.Ref<HTMLSpanElement>} ref - Forwarded ref to the loader element.\n * @returns {JSX.Element} The rendered loader element.\n *\n * @example\n * <Loader />\n *\n * @example\n * <Loader textSize=\"3\" ariaLabel=\"Saving\" />\n */\nexport const Loader = forwardRef<HTMLSpanElement, LoaderProps>(\n  ({ className, ariaLabel = 'Loading', ...props }, ref) => {\n    const { bulmaHelperClasses, rest } = useBulmaClasses(props);\n    const loaderClass = usePrefixedClassNames('loader');\n\n    // role=\"progressbar\", not role=\"status\": a status region mounted together\n    // with its text is not reliably announced, so the loader claims only what\n    // it can deliver, a named indicator found by reading the page. No\n    // aria-valuenow, because the progress is indeterminate.\n    return (\n      <span\n        ref={ref}\n        className={classNames(loaderClass, bulmaHelperClasses, className)}\n        role=\"progressbar\"\n        aria-label={ariaLabel}\n        {...rest}\n      />\n    );\n  }\n);\n\nLoader.displayName = 'Loader';\n"],"names":["_jsx"],"mappings":";;;;;;AA6BA;;;;;;;;;;;;;;;;;AAiBG;MACU,MAAM,GAAG,UAAU,CAC9B,CAAC,EAAE,SAAS,EAAE,SAAS,GAAG,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,GAAG,KAAI;IACtD,MAAM,EAAE,kBAAkB,EAAE,IAAI,EAAE,GAAG,eAAe,CAAC,KAAK,CAAC;AAC3D,IAAA,MAAM,WAAW,GAAG,qBAAqB,CAAC,QAAQ,CAAC;;;;;IAMnD,QACEA,GAAA,CAAA,MAAA,EAAA,EACE,GAAG,EAAE,GAAG,EACR,SAAS,EAAE,UAAU,CAAC,WAAW,EAAE,kBAAkB,EAAE,SAAS,CAAC,EACjE,IAAI,EAAC,aAAa,EAAA,YAAA,EACN,SAAS,EAAA,GACjB,IAAI,EAAA,CACR;AAEN,CAAC;AAGH,MAAM,CAAC,WAAW,GAAG,QAAQ;;"}