@recursica/mantine-adapter 0.20.0 → 0.21.0

package/dist/src/components/Button/Button.d.ts

@@ -1,10 +1,20 @@
 import { default as React } from 'react';
+import { RecursicaLoaderProps } from '../Loader/Loader';
 import { ButtonProps as MantineButtonProps } from '@mantine/core';
 import { RecursicaOverStyled } from '../../utils/filterStylingProps';
 export interface RecursicaButtonProps {
+    /** The visual style variant of the button */
     variant?: "solid" | "outline" | "text";
+    /** The size of the button */
     size?: "default" | "small";
+    /** An optional icon element to display to the left of the button text. Replaces Mantine's leftSection. */
     icon?: React.ReactNode;
+    /** Which Recursica Loader variant to use */
+    loaderVariant?: RecursicaLoaderProps["variant"];
+    /** The size variant for the loader */
+    loaderSize?: RecursicaLoaderProps["size"];
+    /** Whether to use the Recursica loader or fallback to the Mantine loader */
+    useRecursicaLoader?: boolean;
 }
 export type ButtonProps = RecursicaOverStyled<Omit<MantineButtonProps, "variant" | "size" | "leftSection" | "fullWidth"> & RecursicaButtonProps>;
 /**
@@ -25,7 +35,7 @@ export type ButtonProps = RecursicaOverStyled<Omit<MantineButtonProps, "variant"
  */
 export declare const Button: (<C = "button">(props: import('@mantine/core').PolymorphicComponentProps<C, ButtonProps>) => React.ReactElement) & Omit<React.FunctionComponent<((ButtonProps & {
     component?: any;
-}) & Omit<Omit<any, "ref">, "className" | "classNames" | "style" | "styles" | "vars" | "p" | "px" | "py" | "pt" | "pb" | "pl" | "pr" | "bg" | "c" | "opacity" | "ff" | "fz" | "fw" | "lts" | "ta" | "lh" | "fs" | "tt" | "td" | "bd" | "w" | "miw" | "maw" | "h" | "mih" | "mah" | "m" | "my" | "mx" | "mt" | "mb" | "ml" | "mr" | "top" | "left" | "bottom" | "right" | "color" | "children" | "radius" | "__vars" | "__size" | "hiddenFrom" | "visibleFrom" | "lightHidden" | "darkHidden" | "mod" | "ms" | "me" | "ps" | "pe" | "bdrs" | "bgsz" | "bgp" | "bgr" | "bga" | "pos" | "inset" | "display" | "flex" | "unstyled" | "variant" | "attributes" | "overStyled" | "disabled" | "icon" | "justify" | "size" | "gradient" | "autoContrast" | "component" | "loading" | "rightSection" | "data-disabled" | "loaderProps"> & {
+}) & Omit<Omit<any, "ref">, "className" | "classNames" | "style" | "styles" | "vars" | "p" | "px" | "py" | "pt" | "pb" | "pl" | "pr" | "bg" | "c" | "opacity" | "ff" | "fz" | "fw" | "lts" | "ta" | "lh" | "fs" | "tt" | "td" | "bd" | "w" | "miw" | "maw" | "h" | "mih" | "mah" | "m" | "my" | "mx" | "mt" | "mb" | "ml" | "mr" | "top" | "left" | "bottom" | "right" | "color" | "children" | "radius" | "__vars" | "__size" | "hiddenFrom" | "visibleFrom" | "lightHidden" | "darkHidden" | "mod" | "ms" | "me" | "ps" | "pe" | "bdrs" | "bgsz" | "bgp" | "bgr" | "bga" | "pos" | "inset" | "display" | "flex" | "unstyled" | "variant" | "attributes" | "overStyled" | "disabled" | "icon" | "justify" | "size" | "gradient" | "autoContrast" | "component" | "loading" | "rightSection" | "data-disabled" | "loaderProps" | "loaderVariant" | "loaderSize" | "useRecursicaLoader"> & {
     ref?: any;
     renderRoot?: (props: any) => any;
 }) | (ButtonProps & {

package/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/borderux/recursica.git",
     "directory": "packages/mantine-adapter"
   },
-  "version": "0.20.0",
+  "version": "0.21.0",
   "type": "module",
   "main": "./dist/mantine-adapter.cjs",
   "module": "./dist/mantine-adapter.js",

package/src/components/Button/Button.module.css

@@ -36,12 +36,16 @@
 }
 
 /* Internal Mantine reset & layout logic for Truncation */
-.root > * {
+.root > *:not(.loader) {
   min-width: 0;
   position: relative;
   z-index: 1;
 }
 
+.loader {
+  /* Mantine absolutely positions this; we just need a hook to exclude it from the child reset */
+}
+
 .label {
   display: flex;
   align-items: center;

package/src/components/Button/Button.stories.tsx

@@ -20,6 +20,30 @@ const meta: Meta<ButtonStoryProps> = {
       options: ["default", "small"],
       description: "The size of the button",
     },
+    loading: {
+      control: "boolean",
+      description: "Sets the button to a loading state",
+    },
+    useRecursicaLoader: {
+      control: "boolean",
+      description:
+        "Use the Recursica Loader component instead of the default Mantine loader",
+    },
+    loaderVariant: {
+      control: "select",
+      options: ["oval", "bars", "dots"],
+      description: "The visual variant of the Recursica Loader",
+    },
+    loaderSize: {
+      control: "select",
+      options: [undefined, "sm", "md", "lg", "small", "default", "large"],
+      description: "The size variant for the loader",
+    },
+  },
+  args: {
+    useRecursicaLoader: true,
+    loaderVariant: "oval",
+    loaderSize: undefined,
   },
 };
 
@@ -126,3 +150,20 @@ export const TruncatedLabel: Story = {
     </div>
   ),
 };
+
+export const Loading: Story = {
+  args: {
+    children: "Saving Changes",
+    variant: "solid",
+    size: "default",
+    loading: true,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "When `loading={true}` is applied, the Button injects the Recursica `<Loader />` component. Per Recursica design rules, placing a Button in a loading state automatically forces the `disabled={true}` state on the underlying element. This ensures the button immediately receives the brand theme disabled opacities without relying solely on semantic logic.",
+      },
+    },
+  },
+};

package/src/components/Button/Button.tsx

@@ -1,4 +1,6 @@
 import React, { forwardRef } from "react";
+import { Loader } from "../Loader/Loader";
+import type { RecursicaLoaderProps } from "../Loader/Loader";
 import {
   Button as MantineButton,
   type ButtonProps as MantineButtonProps,
@@ -11,9 +13,18 @@ import {
 import styles from "./Button.module.css";
 
 export interface RecursicaButtonProps {
+  /** The visual style variant of the button */
   variant?: "solid" | "outline" | "text";
+  /** The size of the button */
   size?: "default" | "small";
+  /** An optional icon element to display to the left of the button text. Replaces Mantine's leftSection. */
   icon?: React.ReactNode;
+  /** Which Recursica Loader variant to use */
+  loaderVariant?: RecursicaLoaderProps["variant"];
+  /** The size variant for the loader */
+  loaderSize?: RecursicaLoaderProps["size"];
+  /** Whether to use the Recursica loader or fallback to the Mantine loader */
+  useRecursicaLoader?: boolean;
 }
 
 export type ButtonProps = RecursicaOverStyled<
@@ -34,6 +45,9 @@ const _Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
     icon,
     children,
     overStyled = false,
+    loaderVariant = "oval",
+    loaderSize,
+    useRecursicaLoader = true,
     ...rest
   },
   ref,
@@ -75,6 +89,7 @@ const _Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
     root: styles.root,
     section: styles.section,
     label: styles.label,
+    loader: styles.loader,
   };
 
   const classNamesProp = restRecord.classNames;
@@ -94,6 +109,21 @@ const _Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
     ? `${styles.root} ${classNameProp}`
     : styles.root;
 
+  const userLoaderProps = restRecord.loaderProps as
+    | Record<string, any>
+    | undefined;
+
+  const resolvedLoaderSize =
+    loaderSize ?? (size === "small" ? "small" : "default");
+
+  let mergedLoaderProps = userLoaderProps;
+  if (useRecursicaLoader) {
+    mergedLoaderProps = {
+      children: <Loader variant={loaderVariant} size={resolvedLoaderSize} />,
+      ...userLoaderProps,
+    };
+  }
+
   return (
     <MantineButton
       ref={ref}
@@ -101,6 +131,7 @@ const _Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
       classNames={mergedClassNames}
       variant={mapVariant[variant]}
       size={mapSize[size]}
+      loaderProps={mergedLoaderProps}
       leftSection={
         icon != null ? (
           <span className={styles.iconWrapper} aria-hidden>
@@ -112,6 +143,7 @@ const _Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
       data-size={size}
       {...(isIconOnly ? { "data-icon-only": "" } : {})}
       {...sanitizedProps}
+      disabled={!!restRecord.disabled || !!restRecord.loading}
     >
       <span className={styles.labelText}>{children}</span>
     </MantineButton>

package/src/components/Button/IMPLEMENTATION_NOTES.md

@@ -43,3 +43,19 @@ Mantine's `.mantine-Button-label` flex centering breaks primitive truncation log
 ## Disabled state: brand theme opacity (implicit)
 
 **Decision:** The UI kit enforces global brand theme disabled opacities. The `.root:disabled` logic implicitly overrides visibility locally via `var(--recursica_brand_states_disabled)`.
+
+---
+
+## Loader color contrast
+
+**Decision:** When a Button is in a loading state, the `Recursica Loader` component is injected. The `Loader` component strictly defines its own colors and styles per variant, meaning it does not inherit the text color (`currentColor`) from the Button.
+
+**Constraint:** This can lead to contrast issues (e.g., a blue dots loader inside a solid blue button). Design has explicitly decided not to address this at the moment. As such, developers using the `loading` prop must be aware that the loader's color is fixed by its internal tokens, not by the button's context.
+
+---
+
+## Loading state enforces disabled state
+
+**Decision:** When `loading={true}` is passed to the Button, the component explicitly forces `disabled={true}` natively on the underlying element.
+
+**Implementation:** This ensures that loading buttons automatically inherit the brand theme disabled opacities (via the `:disabled` CSS pseudo-class) rather than relying solely on Mantine's native `data-disabled` dataset logic, which may not trigger the strict visual fade required by the Recursica design system.

package/src/components/Toast/Toast.module.css

@@ -23,6 +23,12 @@
   );
   gap: var(--recursica_ui-kit_components_toast_properties_spacing);
 
+  /* Hide Mantine's native colored vertical line */
+  &::before {
+    display: none;
+    content: none;
+  }
+
   & .icon {
     width: var(--recursica_ui-kit_components_toast_properties_icon) !important;
     height: var(--recursica_ui-kit_components_toast_properties_icon) !important;