@recursica/mantine-adapter 0.20.0 → 0.22.0

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

@@ -1,3 +1,10 @@
+/**
+ * IMPLEMENTATION NOTES:
+ * 
+ * - Icon-Only Flexbox Hack: Mantine renders a hidden `.label` span even if `children` is empty. 
+ *   Because we apply `flex: 1` to `.label`, this empty span grows and pushes the `leftSection` (the icon) 
+ *   off-center. To fix this, we apply `display: none` to the label when `data-content="icon-only"`.
+ */
 /* Baseline and Reset */
 .root {
   box-sizing: border-box;
@@ -36,15 +43,20 @@
 }
 
 /* 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;
+  justify-content: center;
   min-width: 0;
   flex: 1 1 0;
 }
@@ -61,39 +73,114 @@
 
 /* ==== SIZES ==== */
 .root[data-size="default"] {
-  border-radius: var(
-    --recursica_ui-kit_components_button_variants_sizes_default_properties_border-radius
-  );
-  height: var(
-    --recursica_ui-kit_components_button_variants_sizes_default_properties_height
-  );
-  min-width: var(
-    --recursica_ui-kit_components_button_variants_sizes_default_properties_min-width
-  );
+  /* Set baseline paddings and min-width using generic tokens as baseline defaults */
   padding: 0
     var(
       --recursica_ui-kit_components_button_variants_sizes_default_properties_horizontal-padding
     );
-}
-.root[data-size="default"] .labelText {
-  max-width: var(
-    --recursica_ui-kit_components_button_variants_sizes_default_properties_max-label-width
+  min-width: var(
+    --recursica_ui-kit_components_button_variants_sizes_default_properties_min-width
   );
+
+  height: var(
+    --recursica_ui-kit_components_button_variants_sizes_default_properties_height
+  );
+
+  .labelText {
+    max-width: var(
+      --recursica_ui-kit_components_button_variants_sizes_default_properties_max-label-width
+    );
+  }
+
+  .iconWrapper {
+    width: var(
+      --recursica_ui-kit_components_button_variants_sizes_default_properties_icon
+    );
+    height: var(
+      --recursica_ui-kit_components_button_variants_sizes_default_properties_icon
+    );
+  }
+
+  .section {
+    gap: var(
+      --recursica_ui-kit_components_button_variants_sizes_default_properties_icon-text-gap
+    );
+  }
+
+  &[data-content="label"] {
+    border-radius: var(
+      --recursica_ui-kit_components_button_variants_content_label_variants_sizes_default_properties_border-radius
+    );
+    min-width: var(
+      --recursica_ui-kit_components_button_variants_content_label_variants_sizes_default_properties_min-width
+    );
+    padding: 0
+      var(
+        --recursica_ui-kit_components_button_variants_content_label_variants_sizes_default_properties_horizontal-padding
+      );
+  }
+
+  &[data-content="icon-label"] {
+    border-radius: var(
+      --recursica_ui-kit_components_button_variants_content_icon-label_variants_sizes_default_properties_border-radius
+    );
+    min-width: var(
+      --recursica_ui-kit_components_button_variants_content_icon-label_variants_sizes_default_properties_min-width
+    );
+    padding: 0
+      var(
+        --recursica_ui-kit_components_button_variants_content_icon-label_variants_sizes_default_properties_horizontal-padding
+      );
+  }
+
+  &[data-content="icon-only"] {
+    border-radius: var(
+      --recursica_ui-kit_components_button_variants_content_icon-only_variants_sizes_default_properties_border-radius
+    );
+    min-width: var(
+      --recursica_ui-kit_components_button_variants_content_icon-only_variants_sizes_default_properties_min-width
+    );
+    padding: 0
+      var(
+        --recursica_ui-kit_components_button_variants_content_icon-only_variants_sizes_default_properties_horizontal-padding
+      );
+  }
 }
+
 .root[data-size="small"] {
-  border-radius: var(
-    --recursica_ui-kit_components_button_variants_sizes_small_properties_border-radius
+  /* Set baseline paddings and min-width using generic tokens as baseline defaults */
+  padding: 0
+    var(
+      --recursica_ui-kit_components_button_variants_sizes_small_properties_horizontal-padding
+    );
+  min-width: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_min-width
   );
+
   height: var(
     --recursica_ui-kit_components_button_variants_sizes_small_properties_height
   );
-  min-width: var(
-    --recursica_ui-kit_components_button_variants_sizes_small_properties_min-width
-  );
-  padding: 0
-    var(
-      --recursica_ui-kit_components_button_variants_sizes_small_properties_horizontal-padding
+
+  .labelText {
+    max-width: var(
+      --recursica_ui-kit_components_button_variants_sizes_small_properties_max-label-width
+    );
+  }
+
+  .iconWrapper {
+    width: var(
+      --recursica_ui-kit_components_button_variants_sizes_small_properties_icon
     );
+    height: var(
+      --recursica_ui-kit_components_button_variants_sizes_small_properties_icon
+    );
+  }
+
+  .section {
+    gap: var(
+      --recursica_ui-kit_components_button_variants_sizes_small_properties_icon-text-gap
+    );
+  }
 
   /* Override specific typography for small */
   font-family: var(
@@ -114,11 +201,75 @@
       --recursica_ui-kit_components_button_variants_sizes_default_properties_text_font-weight
     )
   );
-}
-.root[data-size="small"] .labelText {
-  max-width: var(
-    --recursica_ui-kit_components_button_variants_sizes_small_properties_max-label-width
+  font-style: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_text_font-style,
+    var(
+      --recursica_ui-kit_components_button_variants_sizes_default_properties_text_font-style
+    )
   );
+  letter-spacing: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_text_letter-spacing,
+    var(
+      --recursica_ui-kit_components_button_variants_sizes_default_properties_text_letter-spacing
+    )
+  );
+  line-height: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_text_line-height,
+    var(
+      --recursica_ui-kit_components_button_variants_sizes_default_properties_text_line-height
+    )
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_text_text-decoration,
+    var(
+      --recursica_ui-kit_components_button_variants_sizes_default_properties_text_text-decoration
+    )
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_text_text-transform,
+    var(
+      --recursica_ui-kit_components_button_variants_sizes_default_properties_text_text-transform
+    )
+  );
+
+  &[data-content="label"] {
+    border-radius: var(
+      --recursica_ui-kit_components_button_variants_content_label_variants_sizes_small_properties_border-radius
+    );
+    min-width: var(
+      --recursica_ui-kit_components_button_variants_content_label_variants_sizes_small_properties_min-width
+    );
+    padding: 0
+      var(
+        --recursica_ui-kit_components_button_variants_content_label_variants_sizes_small_properties_horizontal-padding
+      );
+  }
+
+  &[data-content="icon-label"] {
+    border-radius: var(
+      --recursica_ui-kit_components_button_variants_content_icon-label_variants_sizes_small_properties_border-radius
+    );
+    min-width: var(
+      --recursica_ui-kit_components_button_variants_content_icon-label_variants_sizes_small_properties_min-width
+    );
+    padding: 0
+      var(
+        --recursica_ui-kit_components_button_variants_content_icon-label_variants_sizes_small_properties_horizontal-padding
+      );
+  }
+
+  &[data-content="icon-only"] {
+    border-radius: var(
+      --recursica_ui-kit_components_button_variants_content_icon-only_variants_sizes_small_properties_border-radius
+    );
+    min-width: var(
+      --recursica_ui-kit_components_button_variants_content_icon-only_variants_sizes_small_properties_min-width
+    );
+    padding: 0
+      var(
+        --recursica_ui-kit_components_button_variants_content_icon-only_variants_sizes_small_properties_horizontal-padding
+      );
+  }
 }
 
 /* Icon Resets */
@@ -133,45 +284,22 @@
   height: 100%;
   object-fit: contain;
 }
-.root[data-size="default"] .iconWrapper {
-  width: var(
-    --recursica_ui-kit_components_button_variants_sizes_default_properties_icon
-  );
-  height: var(
-    --recursica_ui-kit_components_button_variants_sizes_default_properties_icon
-  );
-}
-.root[data-size="small"] .iconWrapper {
-  width: var(
-    --recursica_ui-kit_components_button_variants_sizes_small_properties_icon
-  );
-  height: var(
-    --recursica_ui-kit_components_button_variants_sizes_small_properties_icon
-  );
-}
 
 .section {
   min-width: 0;
 }
-.root[data-size="default"] .section {
-  gap: var(
-    --recursica_ui-kit_components_button_variants_sizes_default_properties_icon-text-gap
-  );
-}
-.root[data-size="small"] .section {
-  gap: var(
-    --recursica_ui-kit_components_button_variants_sizes_small_properties_icon-text-gap
-  );
-}
 
 /* Icon-only logic overrides */
-.root[data-icon-only] .section {
+.root[data-content="icon-only"] .label {
+  display: none;
+}
+.root[data-content="icon-only"] .section {
   gap: 0;
 }
-.root[data-icon-only] .section[data-position="left"] {
+.root[data-content="icon-only"] .section[data-position="left"] {
   margin-inline-end: 0;
 }
-.root[data-icon-only] .section[data-position="right"] {
+.root[data-content="icon-only"] .section[data-position="right"] {
   margin-inline-start: 0;
 }
 
@@ -210,13 +338,21 @@
     --recursica_ui-kit_components_button_variants_sizes_small_properties_hover-color
   );
 }
-.root:hover:not(:disabled)::after {
+.root[data-size="default"]:hover:not(:disabled)::after {
   opacity: var(
     --recursica_ui-kit_components_button_variants_sizes_default_properties_hover-opacity,
     0.1
   );
 }
-
+.root[data-size="small"]:hover:not(:disabled)::after {
+  opacity: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_hover-opacity,
+    var(
+      --recursica_ui-kit_components_button_variants_sizes_default_properties_hover-opacity,
+      0.1
+    )
+  );
+}
 /* ==== VARIANTS ==== */
 
 /* SOLID */
@@ -236,11 +372,20 @@
   color: var(
     --recursica_ui-kit_components_button_variants_styles_solid_properties_colors_text
   );
+
+  .iconWrapper {
+    color: var(
+      --recursica_ui-kit_components_button_variants_styles_solid_properties_colors_icon-color
+    );
+  }
 }
 .root[data-variant="solid"]:hover:not(:disabled) {
   color: var(
     --recursica_ui-kit_components_button_variants_styles_solid_properties_colors_text-hover
   );
+  box-shadow: var(
+    --recursica_ui-kit_components_button_variants_styles_solid_properties_hover-elevation
+  );
 }
 
 /* OUTLINE */
@@ -260,11 +405,20 @@
   color: var(
     --recursica_ui-kit_components_button_variants_styles_outline_properties_colors_text
   );
+
+  .iconWrapper {
+    color: var(
+      --recursica_ui-kit_components_button_variants_styles_outline_properties_colors_icon-color
+    );
+  }
 }
 .root[data-variant="outline"]:hover:not(:disabled) {
   color: var(
     --recursica_ui-kit_components_button_variants_styles_outline_properties_colors_text-hover
   );
+  box-shadow: var(
+    --recursica_ui-kit_components_button_variants_styles_outline_properties_hover-elevation
+  );
 }
 
 /* TEXT */
@@ -284,9 +438,18 @@
   color: var(
     --recursica_ui-kit_components_button_variants_styles_text_properties_colors_text
   );
+
+  .iconWrapper {
+    color: var(
+      --recursica_ui-kit_components_button_variants_styles_text_properties_colors_icon-color
+    );
+  }
 }
 .root[data-variant="text"]:hover:not(:disabled) {
   color: var(
     --recursica_ui-kit_components_button_variants_styles_text_properties_colors_text-hover
   );
+  box-shadow: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_hover-elevation
+  );
 }

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

@@ -10,6 +10,9 @@ const meta: Meta<ButtonStoryProps> = {
   component: Button,
   tags: ["autodocs"],
   argTypes: {
+    disabled: {
+      control: "boolean",
+    },
     variant: {
       control: "select",
       options: ["solid", "outline", "text"],
@@ -20,6 +23,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,
   },
 };
 
@@ -80,6 +107,30 @@ export const TextWithIcon: Story = {
   },
 };
 
+export const IconOnly: Story = {
+  args: {
+    variant: "solid",
+    size: "default",
+    "aria-label": "Search",
+    icon: (
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <circle cx="11" cy="11" r="8"></circle>
+        <line x1="21" y1="21" x2="16.65" y2="16.65"></line>
+      </svg>
+    ),
+  },
+};
+
 export const LayerOneSolid: Story = {
   args: {
     children: "Layer 1 Solid",
@@ -126,3 +177,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,
@@ -57,8 +71,15 @@ const _Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
 
   const hasLeftSection = !!icon || !!restRecord["leftSection"];
   const hasRightSection = !!restRecord["rightSection"];
-  const isIconOnly =
-    (hasLeftSection || hasRightSection) && !hasVisibleChildren(children);
+  const hasVisibleText = hasVisibleChildren(children);
+  const isIconOnly = (hasLeftSection || hasRightSection) && !hasVisibleText;
+
+  let contentType = "label";
+  if (isIconOnly) {
+    contentType = "icon-only";
+  } else if (hasLeftSection || hasRightSection) {
+    contentType = "icon-label";
+  }
 
   if (
     typeof process !== "undefined" &&
@@ -75,6 +96,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 +116,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 +138,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>
@@ -110,8 +148,9 @@ const _Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
       }
       data-variant={variant}
       data-size={size}
-      {...(isIconOnly ? { "data-icon-only": "" } : {})}
+      data-content={contentType}
       {...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/Card/Card.module.css

@@ -1,3 +1,9 @@
+/* HARDCODED VALUES:
+   - display: flex on root
+   - flex-direction: column
+   - gap: section-gap
+ */
+
 .root {
   /* HARDCODE: Map Recursica explicitly into Mantine's variable format so internal components know the margins */
   --card-padding: var(--recursica_ui-kit_components_card_properties_padding);
@@ -33,7 +39,32 @@
   border-bottom: var(--recursica_ui-kit_components_card_properties_divider-size)
     solid
     var(--recursica_ui-kit_components_card_properties_colors_divider-color);
-  composes: recursica_brand_typography_h3 from global;
+
+  /* Direct Figma Typography Mapping */
+  font-family: var(
+    --recursica_ui-kit_components_card_properties_header-style_fontFamily
+  );
+  font-size: var(
+    --recursica_ui-kit_components_card_properties_header-style_fontSize
+  );
+  font-style: var(
+    --recursica_ui-kit_components_card_properties_header-style_fontStyle
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_card_properties_header-style_fontWeight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_card_properties_header-style_letterSpacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_card_properties_header-style_lineHeight
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_card_properties_header-style_textCase
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_card_properties_header-style_textDecoration
+  );
 }
 
 .footer {
@@ -58,4 +89,30 @@
   flex-direction: column;
   gap: var(--recursica_ui-kit_components_card_properties_vertical-gutter);
   padding: 0;
+
+  /* Direct Figma Typography Mapping */
+  font-family: var(
+    --recursica_ui-kit_components_card_properties_content-style_fontFamily
+  );
+  font-size: var(
+    --recursica_ui-kit_components_card_properties_content-style_fontSize
+  );
+  font-style: var(
+    --recursica_ui-kit_components_card_properties_content-style_fontStyle
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_card_properties_content-style_fontWeight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_card_properties_content-style_letterSpacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_card_properties_content-style_lineHeight
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_card_properties_content-style_textCase
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_card_properties_content-style_textDecoration
+  );
 }

package/src/components/Card/Card.stories.tsx

@@ -37,7 +37,8 @@ export const Default: Story = {
       <div
         style={{
           padding: "48px",
-          backgroundColor: "var(--recursica_brand_palettes_neutral_050)",
+          backgroundColor:
+            "var(--recursica_brand_palettes_neutral_050_color_tone)",
         }}
       >
         <Layer layer={0}>
@@ -72,7 +73,8 @@ export const HeaderlessAndFooterless: Story = {
       <div
         style={{
           padding: "48px",
-          backgroundColor: "var(--recursica_brand_palettes_neutral_050)",
+          backgroundColor:
+            "var(--recursica_brand_palettes_neutral_050_color_tone)",
         }}
       >
         <Layer layer={0}>