@recursica/mantine-adapter 0.42.0 → 0.43.0

package/package.json

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

package/src/GlobalExemptions.modules.css

@@ -5,9 +5,3 @@
  * recursica_variables_scoped.css but are not used by any specific component.
  * Isolating them here keeps individual component stylesheets clean and focused.
  */
-
-/* ==== GLOBAL ICON STYLE ====
-   Global layout option specifying the overall SVG rendering style (solid/outline).
-   Note to Forge Devs: style is not a CSS property or variable type and cannot be applied in standard CSS stylesheets.
-   This variable is ignored in the UI adapters and should be reviewed by the Forge team. */
-/* recursica-ignore: --recursica_ui-kit_globals_icon_style */

package/src/components/Accordion/Accordion.module.css

@@ -1,11 +1,3 @@
-/* EXEMPTIONS:
-   - accordion-header open-appearance background-color/border-color are ignored because Forge does
-     not apply a visual swap on expand, even though the token schema defines "open" appearance
-     colors distinct from "closed" (see .control below, which intentionally keeps a constant
-     background/border across collapsed/expanded). */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-header_variants_appearance_open_properties_colors_background-color */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-header_variants_appearance_open_properties_colors_border-color */
-
 /* ==== ACCORDION CONTAINER ==== */
 .root {
   box-sizing: border-box;

package/src/components/Accordion/Accordion.tsx

@@ -8,6 +8,8 @@ import {
 } from "@mantine/core";
 import {
   filterStylingProps,
+  omitUnsupportedProps,
+  mergeClassNames,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import styles from "./Accordion.module.css";
@@ -47,44 +49,31 @@ const AccordionBase = function Accordion({
       : variant;
 
   const sanitizedProps = filterStylingProps(rest, overStyled);
+  const restRecord = sanitizedProps as Record<string, unknown>;
 
   // Bind all deep CSS module references natively into the global class mapping schema
-  const mergedClassNames: Partial<Record<string, string>> = {
-    root: styles.root,
-    item: styles.item,
-    control: styles.control,
-    label: styles.label,
-    chevron: styles.chevron,
-    icon: styles.icon,
-    panel: styles.panel,
-    content: styles.content,
-  };
-
-  const classNamesProp = (sanitizedProps as Record<string, unknown>).classNames;
-  if (
-    classNamesProp &&
-    typeof classNamesProp === "object" &&
-    !Array.isArray(classNamesProp)
-  ) {
-    const o = classNamesProp as Record<string, string>;
-    Object.keys(o).forEach((key) => {
-      if (mergedClassNames[key]) {
-        mergedClassNames[key] = `${mergedClassNames[key]} ${o[key]}`;
-      } else {
-        mergedClassNames[key] = o[key];
-      }
-    });
-  }
+  const mergedClassNames = mergeClassNames(
+    {
+      root: styles.root,
+      item: styles.item,
+      control: styles.control,
+      label: styles.label,
+      chevron: styles.chevron,
+      icon: styles.icon,
+      panel: styles.panel,
+      content: styles.content,
+    },
+    restRecord.classNames as Partial<Record<string, string>> | undefined,
+  );
 
-  const classNameProp = (sanitizedProps as Record<string, unknown>)
-    .className as string | undefined;
+  const classNameProp = restRecord.className as string | undefined;
 
   return (
     <MantineAccordion
+      {...(sanitizedProps as unknown as MantineAccordionProps)}
       variant={resolvedVariant as MantineAccordionProps["variant"]}
       className={classNameProp}
       classNames={mergedClassNames}
-      {...(sanitizedProps as unknown as MantineAccordionProps)}
     />
   );
 };
@@ -128,9 +117,9 @@ export const AccordionItem = forwardRef<
   return (
     <MantineAccordion.Item
       ref={ref}
+      {...(sanitizedProps as unknown as AccordionItemProps)}
       className={finalClass}
       data-disabled={disabled || undefined}
-      {...(sanitizedProps as unknown as AccordionItemProps)}
     >
       {title ? (
         <>
@@ -155,6 +144,13 @@ export type AccordionControlWrapperProps = RecursicaOverStyled<
   Omit<AccordionControlProps, "icon"> & RecursicaAccordionControlProps
 >;
 
+// Props this component intentionally doesn't support — deleted at runtime so they can't leak
+// through even if a caller forces them via plain JavaScript, bypassing the `Omit<>` above.
+const UNSUPPORTED_PROPS = [
+  "icon", // Mantine's native icon slot is fully computed here from `leftIcon`; the `Omit<>` on
+  // AccordionControlWrapperProps only stops a well-typed caller, this is the runtime backstop.
+] as const satisfies readonly (keyof AccordionControlProps)[];
+
 export const AccordionControl = forwardRef<
   HTMLButtonElement,
   AccordionControlWrapperProps
@@ -162,13 +158,17 @@ export const AccordionControl = forwardRef<
   { leftIcon, children, overStyled = false, ...rest },
   ref,
 ) {
-  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const sanitizedProps = omitUnsupportedProps(
+    filterStylingProps(rest, overStyled),
+    UNSUPPORTED_PROPS,
+  );
   const classNameProp = (sanitizedProps as Record<string, unknown>)
     .className as string | undefined;
 
   return (
     <MantineAccordion.Control
       ref={ref}
+      {...(sanitizedProps as unknown as AccordionControlProps)}
       className={classNameProp}
       icon={
         leftIcon ? (
@@ -177,7 +177,6 @@ export const AccordionControl = forwardRef<
           </span>
         ) : undefined
       }
-      {...(sanitizedProps as unknown as AccordionControlProps)}
     >
       {children}
     </MantineAccordion.Control>
@@ -201,8 +200,8 @@ export const AccordionPanel = forwardRef<
   return (
     <MantineAccordion.Panel
       ref={ref}
-      className={classNameProp}
       {...(sanitizedProps as unknown as AccordionPanelProps)}
+      className={classNameProp}
     />
   );
 });

package/src/components/AssistiveElement/AssistiveElement.tsx

@@ -74,11 +74,11 @@ export const AssistiveElement = forwardRef<
   return (
     <div
       ref={ref}
+      {...restRecord} // Spread standard HTML attributes (like id, aria-*) natively.
       className={finalClass}
       data-variant={assistiveVariant}
       role={resolvedRole}
       style={restRecord.style as React.CSSProperties}
-      {...restRecord} // Spread standard HTML attributes (like id, aria-*) natively.
     >
       {assistiveWithIcon && (
         <span className={styles.iconWrapper}>

package/src/components/AutoComplete/AutoComplete.module.css

@@ -1,10 +1,3 @@
-/* EXEMPTIONS:
-   - border-size variables are ignored because the input box uses a uniform static boundary to prevent
-     unexpected layout shifts or flickering when switching between focused, disabled, or error states. */
-/* recursica-ignore: --recursica_ui-kit_components_autocomplete_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_autocomplete_variants_states_disabled_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_autocomplete_variants_states_error_properties_border-size */
-
 /* LAYOUT SPACING OVERRIDES:
    - Sets the --form-control-margin-bottom spacing hook to map component-specific layout tokens.
    - Also sets the --autocomplete-control-{max,min}-width hooks consumed inline in AutoComplete.tsx,

package/src/components/AutoComplete/AutoComplete.tsx

@@ -7,6 +7,8 @@ import {
 import { type ReadOnlyControlProps } from "@recursica/adapter-common";
 import {
   filterStylingProps,
+  omitUnsupportedProps,
+  mergeClassNames,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/FormControlWrapper";
@@ -42,6 +44,14 @@ export interface RecursicaAutoCompleteProps
 
 export type AutoCompleteProps = RecursicaOverStyled<RecursicaAutoCompleteProps>;
 
+// Props this component intentionally doesn't support — deleted at runtime so they can't leak
+// through even if a caller forces them via plain JavaScript, bypassing the `Omit<>` above.
+const UNSUPPORTED_PROPS = [
+  "size", // Recursica controls sizing via the `size` variant + design tokens, not raw dimensions.
+  "variant", // Colors/variants are token-driven; the library's native palette isn't exposed.
+  "radius", // Recursica does not expose the library's native corner-radius system.
+] as const satisfies readonly (keyof MantineAutocompleteProps)[];
+
 export const AutoComplete = forwardRef<HTMLInputElement, AutoCompleteProps>(
   function AutoComplete(props, ref) {
     const {
@@ -72,46 +82,24 @@ export const AutoComplete = forwardRef<HTMLInputElement, AutoCompleteProps>(
       defaultValue,
       ...rest
     } = props;
-    const sanitizedProps = filterStylingProps(rest, overStyled);
-    const restRecord = sanitizedProps as Record<string, unknown>;
 
-    // Delete prohibited sizing hooks from bypassing variables natively
-    delete restRecord["size"];
-    delete restRecord["variant"];
-    delete restRecord["radius"];
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled) as Record<string, unknown>,
+      UNSUPPORTED_PROPS,
+    );
+    const restRecord = sanitizedProps as Record<string, unknown>;
 
     // Securely map core native blocks down ensuring nested CSS modules map precisely
-    const mergedClassNames: Partial<Record<string, string>> = {
-      wrapper: styles.root, // The nested Input internal relative wrapper bounding box
-      input: styles.input,
-      section: styles.section,
-      dropdown: styles.dropdown,
-      option: styles.option,
-    };
-
-    const classNamesProp = restRecord.classNames;
-    if (
-      classNamesProp &&
-      typeof classNamesProp === "object" &&
-      !Array.isArray(classNamesProp)
-    ) {
-      const o = classNamesProp as Partial<Record<string, string>>;
-      mergedClassNames.wrapper = o.wrapper
-        ? `${styles.root} ${o.wrapper}`
-        : styles.root;
-      mergedClassNames.input = o.input
-        ? `${styles.input} ${o.input}`
-        : styles.input;
-      mergedClassNames.section = o.section
-        ? `${styles.section} ${o.section}`
-        : styles.section;
-      mergedClassNames.dropdown = o.dropdown
-        ? `${styles.dropdown} ${o.dropdown}`
-        : styles.dropdown;
-      mergedClassNames.option = o.option
-        ? `${styles.option} ${o.option}`
-        : styles.option;
-    }
+    const mergedClassNames = mergeClassNames(
+      {
+        wrapper: styles.root, // The nested Input internal relative wrapper bounding box
+        input: styles.input,
+        section: styles.section,
+        dropdown: styles.dropdown,
+        option: styles.option,
+      },
+      restRecord.classNames as Partial<Record<string, string>> | undefined,
+    );
 
     const wrapperClass = className
       ? `${styles.layoutOverride} ${className}`
@@ -147,12 +135,12 @@ export const AutoComplete = forwardRef<HTMLInputElement, AutoCompleteProps>(
           /* Naked Input execution safely decoupled from Mantine's macro Input.Wrapper DOM hooks */
           <MantineAutocomplete
             ref={ref}
+            {...(sanitizedProps as unknown as MantineAutocompleteProps)}
             classNames={mergedClassNames}
             disabled={disabled}
             value={value as string | undefined}
             defaultValue={defaultValue as string | undefined}
             error={!!error}
-            {...(sanitizedProps as unknown as MantineAutocompleteProps)}
           />
         }
       />

package/src/components/Avatar/Avatar.module.css

@@ -7,14 +7,6 @@ HARDCODED VALUES:
 - Image has no explicit size tokens other than root size, assume it scales 100%
 */
 
-/* EXEMPTIONS:
-   The generic size variables below are defined in Figma but unused.
-   We explicitly style the avatar's dimensions using the dedicated width and height tokens
-   (e.g., small_properties_width and small_properties_height) for precise component layout. */
-/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_default_properties_size */
-/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_large_properties_size */
-/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_small_properties_size */
-
 .root {
   box-sizing: border-box;
   margin: 0;

package/src/components/Avatar/Avatar.tsx

@@ -6,6 +6,8 @@ import {
 } from "@mantine/core";
 import {
   filterStylingProps,
+  omitUnsupportedProps,
+  mergeClassNames,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import styles from "./Avatar.module.css";
@@ -41,7 +43,17 @@ const _Avatar = forwardRef<HTMLDivElement, AvatarProps>(function Avatar(
     large: "lg",
   } as const;
 
-  const sanitizedProps = filterStylingProps(rest, overStyled);
+  // Props this component intentionally doesn't support — deleted at runtime so they can't leak
+  // through even if a caller forces them via plain JavaScript, bypassing the `Omit<>` above.
+  const UNSUPPORTED_PROPS = [
+    "color", // Colors are token-driven via `data-variant`; Mantine's native palette isn't exposed.
+    "radius", // Avatar corner radius is controlled by design tokens, not a raw radius prop.
+  ] as const satisfies readonly (keyof MantineAvatarProps)[];
+
+  const sanitizedProps = omitUnsupportedProps(
+    filterStylingProps(rest, overStyled),
+    UNSUPPORTED_PROPS,
+  );
   const restRecord = sanitizedProps as Record<string, unknown>;
 
   // Determine semantic style based on provided props
@@ -52,33 +64,21 @@ const _Avatar = forwardRef<HTMLDivElement, AvatarProps>(function Avatar(
     computedStyle = "icon";
   }
 
-  const mergedClassNames: Partial<Record<string, string>> = {
-    root: styles.root,
-    image: styles.image,
-    placeholder: styles.placeholder,
-  };
-
-  const classNamesProp = restRecord.classNames;
-  if (
-    classNamesProp &&
-    typeof classNamesProp === "object" &&
-    !Array.isArray(classNamesProp)
-  ) {
-    const o = classNamesProp as Partial<Record<string, string>>;
-    mergedClassNames.root = o.root ? `${styles.root} ${o.root}` : styles.root;
-    mergedClassNames.image = o.image
-      ? `${styles.image} ${o.image}`
-      : styles.image;
-    mergedClassNames.placeholder = o.placeholder
-      ? `${styles.placeholder} ${o.placeholder}`
-      : styles.placeholder;
-  }
+  const mergedClassNames = mergeClassNames(
+    {
+      root: styles.root,
+      image: styles.image,
+      placeholder: styles.placeholder,
+    },
+    restRecord.classNames as Partial<Record<string, string>> | undefined,
+  );
 
   const classNameProp = restRecord.className as string | undefined;
 
   return (
     <MantineAvatar
       ref={ref}
+      {...sanitizedProps}
       className={classNameProp}
       classNames={mergedClassNames}
       variant={mapVariant[variant]}
@@ -87,7 +87,6 @@ const _Avatar = forwardRef<HTMLDivElement, AvatarProps>(function Avatar(
       data-variant={variant}
       data-size={size}
       data-style={computedStyle}
-      {...sanitizedProps}
     >
       {icon != null ? (
         <span className={styles.iconWrapper} aria-hidden>

package/src/components/Badge/Badge.tsx

@@ -6,6 +6,7 @@ import {
 } from "@mantine/core";
 import {
   filterStylingProps,
+  mergeClassNames,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import styles from "./Badge.module.css";
@@ -25,23 +26,16 @@ const _Badge = forwardRef<HTMLDivElement, BadgeProps>(function Badge(
   // External layout props like margins are safely preserved.
   const sanitizedProps = filterStylingProps(rest, overStyled);
 
-  const mergedClassNames: Partial<Record<string, string>> = {
-    root: styles.root,
-    section: styles.section,
-    label: styles.label,
-  };
-
-  const classNamesProp = (sanitizedProps as Record<string, unknown>).classNames;
-  if (
-    classNamesProp &&
-    typeof classNamesProp === "object" &&
-    !Array.isArray(classNamesProp)
-  ) {
-    const o = classNamesProp as Partial<Record<string, string>>;
-    mergedClassNames.root = o.root ? `${styles.root} ${o.root}` : styles.root;
-    mergedClassNames.section = o.section ?? styles.section;
-    mergedClassNames.label = o.label ?? styles.label;
-  }
+  const mergedClassNames = mergeClassNames(
+    {
+      root: styles.root,
+      section: styles.section,
+      label: styles.label,
+    },
+    (sanitizedProps as Record<string, unknown>).classNames as
+      | Partial<Record<string, string>>
+      | undefined,
+  );
 
   const classNameProp = (sanitizedProps as Record<string, unknown>)
     .className as string | undefined;
@@ -52,9 +46,9 @@ const _Badge = forwardRef<HTMLDivElement, BadgeProps>(function Badge(
   return (
     <MantineBadge
       ref={ref}
+      {...sanitizedProps}
       variant="filled" // We manage visual style purely through our CSS variables mapping
       data-variant={variant}
-      {...sanitizedProps}
       className={finalClass}
       classNames={mergedClassNames}
     />

package/src/components/Breadcrumb/Breadcrumb.tsx

@@ -5,6 +5,7 @@ import {
 } from "@mantine/core";
 import {
   filterStylingProps,
+  mergeClassNames,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import styles from "./Breadcrumb.module.css";
@@ -24,24 +25,15 @@ export const Breadcrumb = forwardRef<HTMLDivElement, BreadcrumbProps>(
       overStyled,
     );
 
-    const mergedClassNames: Partial<Record<string, string>> = {
-      root: styles.root,
-      separator: styles.separator,
-    };
-
-    const classNamesProp = (sanitizedProps as Record<string, unknown>)
-      .classNames;
-    if (
-      classNamesProp &&
-      typeof classNamesProp === "object" &&
-      !Array.isArray(classNamesProp)
-    ) {
-      const o = classNamesProp as Partial<Record<string, string>>;
-      mergedClassNames.root = o.root ? `${styles.root} ${o.root}` : styles.root;
-      mergedClassNames.separator = o.separator
-        ? `${styles.separator} ${o.separator}`
-        : styles.separator;
-    }
+    const mergedClassNames = mergeClassNames(
+      {
+        root: styles.root,
+        separator: styles.separator,
+      },
+      (sanitizedProps as Record<string, unknown>).classNames as
+        | Partial<Record<string, string>>
+        | undefined,
+    );
 
     const classNameProp = (sanitizedProps as Record<string, unknown>)
       .className as string | undefined;

package/src/components/Button/Button.tsx

@@ -7,6 +7,9 @@ import {
 } from "@mantine/core";
 import {
   filterStylingProps,
+  omitUnsupportedProps,
+  withCallerOverride,
+  mergeClassNames,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import styles from "./Button.module.css";
@@ -49,11 +52,17 @@ const _Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
     small: "sm",
   } as const;
 
-  const sanitizedProps = filterStylingProps(rest, overStyled);
-  const restRecord = sanitizedProps as Record<string, unknown>;
+  // Props this component intentionally doesn't support — deleted at runtime so they can't leak
+  // through even if a caller forces them via plain JavaScript, bypassing the `Omit<>` above.
+  const UNSUPPORTED_PROPS = [
+    "fullWidth", // Recursica Button width comes from layout/token constraints, not Mantine's boolean fullWidth toggle.
+  ] as const satisfies readonly (keyof MantineButtonProps)[];
 
-  // Explicitly delete blocked semantic expansion dimension props
-  delete restRecord["fullWidth"];
+  const sanitizedProps = omitUnsupportedProps(
+    filterStylingProps(rest, overStyled) as Record<string, unknown>,
+    UNSUPPORTED_PROPS,
+  ) as Partial<typeof rest>;
+  const restRecord = sanitizedProps as Record<string, unknown>;
 
   const hasLeftSection = !!icon || !!restRecord["leftSection"];
   const hasRightSection = !!restRecord["rightSection"];
@@ -78,41 +87,33 @@ const _Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
     );
   }
 
-  const mergedClassNames: Partial<Record<string, string>> = {
-    root: styles.root,
-    section: styles.section,
-    label: styles.label,
-    loader: styles.loader,
-  };
-
-  const classNamesProp = restRecord.classNames;
-  if (
-    classNamesProp &&
-    typeof classNamesProp === "object" &&
-    !Array.isArray(classNamesProp)
-  ) {
-    const o = classNamesProp as Partial<Record<string, string>>;
-    mergedClassNames.root = o.root ? `${styles.root} ${o.root}` : styles.root;
-    mergedClassNames.section = o.section ?? styles.section;
-    mergedClassNames.label = o.label ?? styles.label;
-  }
+  const mergedClassNames = mergeClassNames(
+    {
+      root: styles.root,
+      section: styles.section,
+      label: styles.label,
+      loader: styles.loader,
+    },
+    restRecord.classNames as Partial<Record<string, string>> | undefined,
+  );
 
   const classNameProp = restRecord.className as string | undefined;
   const finalClass = classNameProp
     ? `${styles.root} ${classNameProp}`
     : styles.root;
-  // className is merged explicitly above — don't let the {...sanitizedProps} spread below
-  // silently overwrite finalClass with just the caller's own class (same bug class as
-  // mantine-adapter's Dropdown/BareDropdown.tsx had). Masked here today since `classNames.root`
-  // (a separate prop, unaffected) also carries styles.root — but a real latent bug regardless.
-  delete restRecord["className"];
+  // Note: `finalClass` is safe from being clobbered by `{...sanitizedProps}` below purely
+  // because of spread order — `className` (like `classNames`, `variant`, `size`, `leftSection`,
+  // and the `data-*` attributes) is spread first, then re-asserted after, so our computed value
+  // always wins. See the canonical guide's §3.3 for why ordering (not deletion) is the fix here.
 
   const userLoaderProps = restRecord.loaderProps as
     | Record<string, unknown>
     | undefined;
 
-  const resolvedLoaderSize =
-    loaderSize ?? (size === "small" ? "small" : "default");
+  const resolvedLoaderSize = withCallerOverride(
+    size === "small" ? "small" : "default",
+    loaderSize,
+  );
 
   let mergedLoaderProps = userLoaderProps;
   if (useRecursicaLoader) {
@@ -125,6 +126,7 @@ const _Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
   return (
     <MantineButton
       ref={ref}
+      {...sanitizedProps}
       className={finalClass}
       classNames={mergedClassNames}
       variant={mapVariant[variant]}
@@ -140,7 +142,6 @@ const _Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
       data-variant={variant}
       data-size={size}
       data-content={contentType}
-      {...sanitizedProps}
       disabled={!!restRecord.disabled || !!restRecord.loading}
     >
       <span className={styles.labelText}>{children}</span>