@recursica/mantine-adapter 0.42.1 → 0.44.0

package/src/components/Dropdown/Dropdown.module.css

@@ -169,6 +169,39 @@
   );
 }
 
+/* Mantine's own clear button (rendered via `clearButtonProps`, see Dropdown.tsx) is a bare
+   `CloseButton` by default — its own module CSS hardcodes a gray icon color and a circular gray
+   hover background, neither of which is Recursica-token-driven. The double class selector (same
+   specificity-boosting trick as Chip.module.css's `.root.root`) beats that default without
+   needing `!important`. Same icon-size/trailing-icon tokens as the rest of this section, same
+   focus-visible ring technique as Chip's own `.removeIcon` — the established inline icon-button
+   pattern elsewhere in this adapter. */
+.clearButton.clearButton {
+  width: var(--recursica_ui-kit_components_dropdown_properties_icon-size);
+  height: var(--recursica_ui-kit_components_dropdown_properties_icon-size);
+  min-width: var(--recursica_ui-kit_components_dropdown_properties_icon-size);
+  min-height: var(--recursica_ui-kit_components_dropdown_properties_icon-size);
+  border-radius: 50%;
+  background: transparent;
+  color: var(
+    --recursica_ui-kit_components_dropdown_properties_colors_trailing-icon
+  );
+  outline: none;
+}
+
+.clearButton.clearButton:hover {
+  background: transparent;
+}
+
+.clearButton.clearButton:focus-visible {
+  box-shadow:
+    0 0 0 var(--recursica_brand_states_focus_border-size)
+      var(--recursica_brand_states_focus_color),
+    0 0 var(--recursica_brand_states_focus_blur)
+      var(--recursica_brand_states_focus_margin)
+      var(--recursica_brand_states_focus_color);
+}
+
 /* -------------------------------------
    STATE CASCADE ARCHITECTURE
 -------------------------------------- */
@@ -254,6 +287,17 @@
     --recursica_ui-kit_components_dropdown_properties_border-radius
   );
   overflow: hidden;
+
+  /* The visible top/bottom gap before/after the option list was previously left to Mantine's own
+     untokenized `--combobox-padding` default (4px) — wire it to the same dropdown vertical-padding
+     token the closed control itself uses instead (mirrors the mui-adapter fix to the equivalent
+     gap there, which came from MUI's own untokenized 8px `.MuiList-padding` default). */
+  padding-top: var(
+    --recursica_ui-kit_components_dropdown_properties_vertical-padding
+  );
+  padding-bottom: var(
+    --recursica_ui-kit_components_dropdown_properties_vertical-padding
+  );
 }
 
 .option {
@@ -277,10 +321,8 @@
   cursor: pointer;
 }
 
-/* No per-option selected/hovered tokens exist in the schema; use the generic overlay tint
-   (same technique as Table's row hover) to highlight the active option. */
-.option[data-selected="true"],
-.option[data-combobox-selected="true"],
+/* No per-option hovered token exists in the schema; use the generic overlay tint (same technique
+   as Table's row hover) to highlight a hovered-but-not-selected option. */
 .option[data-hovered="true"],
 .option:hover {
   background-color: color-mix(
@@ -290,3 +332,18 @@
     transparent
   );
 }
+
+/* No dedicated dropdown-option "selected" token exists in the schema either, but the menu-item
+   component's selected-state colors are the closest real token family for the same concept (a
+   selected row in a list) — reused here rather than the neutral hover tint above, which is what
+   previously made the selected option read as grey instead of Recursica's brand color. Matches
+   the mui-adapter fix for the same gap. */
+.option[data-selected="true"],
+.option[data-combobox-selected="true"] {
+  background-color: var(
+    --recursica_ui-kit_components_menu-item_variants_selection-states_selected_properties_colors_background-color
+  );
+  color: var(
+    --recursica_ui-kit_components_menu-item_variants_selection-states_selected_properties_colors_text-color
+  );
+}

package/src/components/Dropdown/Dropdown.stories.tsx

@@ -65,6 +65,27 @@ export const SearchableClearable: Story = {
   },
 };
 
+export const WithLeadingIcon: Story = {
+  args: {
+    label: "Destination",
+    leftSection: (
+      <svg
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <path d="M21 10c0 7-9 13-9 13s-9-6-9-13a9 9 0 0 1 18 0z"></path>
+        <circle cx="12" cy="10" r="3"></circle>
+      </svg>
+    ),
+  },
+};
+
 export const StaticError: Story = {
   args: {
     error: "You must choose a valid destination.",

package/src/components/Dropdown/Dropdown.tsx

@@ -6,6 +6,8 @@ import {
 import { type ReadOnlyControlProps } from "@recursica/adapter-common";
 import {
   filterStylingProps,
+  omitUnsupportedProps,
+  mergeClassNames,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/FormControlWrapper";
@@ -28,6 +30,14 @@ export interface RecursicaDropdownProps
 
 export type DropdownProps = RecursicaOverStyled<RecursicaDropdownProps>;
 
+// 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 MantineSelectProps)[];
+
 export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
   function Dropdown(props, ref) {
     const {
@@ -58,48 +68,41 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
       value,
       defaultValue,
       data,
+      clearButtonProps,
       ...rest
     } = props;
-    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled) as Record<string, unknown>,
+      UNSUPPORTED_PROPS,
+    );
     const restRecord = sanitizedProps as Record<string, unknown>;
 
-    // Delete prohibited sizing hooks from bypassing variables natively
-    delete restRecord["size"];
-    delete restRecord["variant"];
-    delete restRecord["radius"];
-
-    // 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,
+    // Mantine's own clear button (rendered when `clearable` + a value are both present) otherwise
+    // renders unstyled — bare `CloseButton` defaults, no Recursica icon-button treatment. Merge in
+    // our own class (see `.clearButton` in Dropdown.module.css) alongside anything the caller
+    // already passed, same merge shape as `mergeClassNames` but for a single `className` string
+    // rather than a per-slot classNames map.
+    const consumerClearButtonProps = clearButtonProps as
+      | Record<string, unknown>
+      | undefined;
+    const mergedClearButtonProps = {
+      ...consumerClearButtonProps,
+      className: consumerClearButtonProps?.className
+        ? `${styles.clearButton} ${consumerClearButtonProps.className as string}`
+        : styles.clearButton,
     };
 
-    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;
-    }
+    // Securely map core native blocks down ensuring nested CSS modules map precisely
+    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 injectedStyles = {
       ...((style as React.CSSProperties) || {}),
@@ -146,11 +149,13 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
           /* Naked Select execution safely decoupled from Mantine's macro Input.Wrapper DOM hooks */
           <MantineSelect
             ref={ref}
+            {...(sanitizedProps as unknown as MantineSelectProps)}
             classNames={mergedClassNames}
             disabled={disabled}
             value={value}
             defaultValue={defaultValue}
             data={(data as unknown as MantineSelectProps["data"]) || []}
+            clearButtonProps={mergedClearButtonProps}
             label={undefined}
             description={undefined}
             error={undefined}
@@ -169,7 +174,6 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
                 "data-error": error ? "true" : undefined,
               },
             }}
-            {...(sanitizedProps as unknown as MantineSelectProps)}
           />
         }
       />

package/src/components/Dropdown/USAGE.md

@@ -45,3 +45,4 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 ## 4. Notes
 
 - `Dropdown` is styled independently from `TextField`; even though they look similar, they are themed using separate design tokens.
+- Pass `leftSection` for a leading icon, and `clearable` (with a value present) to show a clear button — both render using the dropdown's own icon-color tokens.

package/src/components/FileInput/FileInput.tsx

@@ -309,6 +309,7 @@ export const FileInput = forwardRef<HTMLDivElement, FileInputProps>(
       >
         <div
           ref={ref}
+          {...restRecord}
           className={styles.root}
           role="button"
           aria-label={browseLabel}
@@ -324,7 +325,6 @@ export const FileInput = forwardRef<HTMLDivElement, FileInputProps>(
           onDragLeave={interactive ? handleDragLeave : undefined}
           onDragOver={interactive ? handleDragOver : undefined}
           onDrop={interactive ? handleDrop : undefined}
-          {...restRecord}
         >
           <span className={styles.leadingIcon} aria-hidden>
             {icon ?? <UploadIcon />}

package/src/components/FileUpload/FileUpload.tsx

@@ -268,10 +268,10 @@ export const FileUpload = forwardRef<HTMLDivElement, FileUploadProps>(
       >
         <div
           ref={ref}
+          {...restRecord}
           className={styles.root}
           data-disabled={disabled ? "true" : undefined}
           data-error={effectiveError ? "true" : undefined}
-          {...restRecord}
         >
           {!readOnly && (
             <div

package/src/components/HoverCard/HoverCard.tsx

@@ -6,6 +6,7 @@ import {
 } from "@mantine/core";
 import {
   filterStylingProps,
+  mergeClassNames,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import styles from "./HoverCard.module.css";
@@ -42,54 +43,37 @@ export type HoverCardProps = RecursicaOverStyled<
 const HoverCardBase = function HoverCard({
   overStyled = false,
   withBeak = true,
+  position = "top", // Recursica default; Mantine defaults to "bottom". Consumers can still override.
+  // arrowSize must be a JS number prop — Mantine uses it for inline width/height
+  // and positioning offset (-arrowSize/2) calculations that cannot be CSS-driven.
+  // Default to 16 to match the Recursica beak-size token (16px). Consumers can still override.
+  arrowSize = 16,
+  withArrow,
   ...rest
 }: HoverCardProps) {
   const sanitizedProps = filterStylingProps(rest, overStyled);
+  const restRecord = sanitizedProps as Record<string, unknown>;
 
   // Bind CSS module classes to Mantine's internal classNames API
-  const mergedClassNames: Partial<Record<string, string>> = {
-    dropdown: styles.dropdown,
-    arrow: styles.arrow,
-  };
-
-  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];
-      }
-    });
-  }
-
-  // arrowSize must be a JS number prop — Mantine uses it for inline width/height
-  // and positioning offset (-arrowSize/2) calculations that cannot be CSS-driven.
-  // Default to 16 to match the Recursica beak-size token (16px).
-  const arrowSize =
-    ((sanitizedProps as Record<string, unknown>).arrowSize as
-      | number
-      | undefined) ?? 16;
+  const mergedClassNames = mergeClassNames(
+    {
+      dropdown: styles.dropdown,
+      arrow: styles.arrow,
+    },
+    restRecord.classNames as Partial<Record<string, string>> | undefined,
+  );
 
   // Resolve withBeak (Recursica) vs withArrow (Mantine).
   // withBeak takes precedence when both are provided.
-  const withArrow = (sanitizedProps as Record<string, unknown>).withArrow as
-    | boolean
-    | undefined;
   const resolvedWithArrow = withBeak ?? withArrow;
 
   return (
     <MantineHoverCard
-      position="top" /* Recursica default; Mantine defaults to "bottom" */
+      {...(sanitizedProps as unknown as MantineHoverCardProps)}
+      position={position}
       arrowSize={arrowSize}
       withArrow={resolvedWithArrow}
       classNames={mergedClassNames}
-      {...(sanitizedProps as unknown as MantineHoverCardProps)}
     />
   );
 };
@@ -128,8 +112,8 @@ const HoverCardDropdown = function HoverCardDropdown({
 
   return (
     <MantineHoverCard.Dropdown
-      className={classNameProp}
       {...(sanitizedProps as unknown as MantineHoverCardDropdownProps)}
+      className={classNameProp}
     />
   );
 };

package/src/components/Label/Label.tsx

@@ -2,6 +2,8 @@ import React, { forwardRef } from "react";
 import { Input, type InputLabelProps } from "@mantine/core";
 import {
   filterStylingProps,
+  omitUnsupportedProps,
+  mergeClassNames,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import styles from "./Label.module.css";
@@ -35,28 +37,25 @@ export const Label = forwardRef<HTMLLabelElement, LabelProps>(function Label(
     else if (labelOptionalText) resolvedOptionalText = labelOptionalText;
   }
 
-  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 = [
+    "size", // Recursica controls label sizing via `labelSize` + design tokens, not Mantine's native `size`.
+  ] as const satisfies readonly (keyof InputLabelProps)[];
 
-  const mergedClassNames: Partial<Record<string, string>> = {
-    label: styles.root,
-    required: styles.required,
-  };
+  const sanitizedProps = omitUnsupportedProps(
+    filterStylingProps(rest, overStyled),
+    UNSUPPORTED_PROPS,
+  );
+  const restRecord = sanitizedProps as Record<string, unknown>;
 
-  const classNamesProp = restRecord.classNames;
-  if (
-    classNamesProp &&
-    typeof classNamesProp === "object" &&
-    !Array.isArray(classNamesProp)
-  ) {
-    const o = classNamesProp as Partial<Record<string, string>>;
-    mergedClassNames.label = o.label
-      ? `${styles.root} ${o.label}`
-      : styles.root;
-    mergedClassNames.required = o.required
-      ? `${styles.required} ${o.required}`
-      : styles.required;
-  }
+  const mergedClassNames = mergeClassNames(
+    {
+      label: styles.root,
+      required: styles.required,
+    },
+    restRecord.classNames as Partial<Record<string, string>> | undefined,
+  );
 
   const classNameProp = restRecord.className as string | undefined;
   const finalClass = classNameProp
@@ -66,12 +65,12 @@ export const Label = forwardRef<HTMLLabelElement, LabelProps>(function Label(
   return (
     <Input.Label
       ref={ref}
+      {...sanitizedProps}
       className={finalClass}
       classNames={mergedClassNames}
       data-size={labelSize}
       data-alignment={resolvedAlignment}
       required={required && !labelWithEditIcon}
-      {...sanitizedProps}
     >
       <span className={styles.labelText}>{children}</span>
       {resolvedOptionalText && (

package/src/components/Link/Link.tsx

@@ -6,6 +6,7 @@ import {
 } from "@mantine/core";
 import {
   filterStylingProps,
+  mergeClassNames,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import styles from "./Link.module.css";
@@ -23,19 +24,10 @@ const _Link = forwardRef<HTMLAnchorElement, LinkProps>(function Link(
   const sanitizedProps = filterStylingProps(rest, overStyled);
   const restRecord = sanitizedProps as Record<string, unknown>;
 
-  const mergedClassNames: Partial<Record<string, string>> = {
-    root: styles.root,
-  };
-
-  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;
-  }
+  const mergedClassNames = mergeClassNames(
+    { root: styles.root },
+    restRecord.classNames as Partial<Record<string, string>> | undefined,
+  );
 
   const classNameProp = restRecord.className as string | undefined;
   const finalClass = classNameProp
@@ -45,11 +37,11 @@ const _Link = forwardRef<HTMLAnchorElement, LinkProps>(function Link(
   return (
     <MantineAnchor
       ref={ref}
+      {...(sanitizedProps as Record<string, unknown>)}
       className={finalClass}
       classNames={mergedClassNames}
       underline="never"
       {...(icon ? { "data-has-icon": "" } : {})}
-      {...(sanitizedProps as Record<string, unknown>)}
     >
       {icon && (
         <span className={styles.iconWrapper} aria-hidden>

package/src/components/Loader/Loader.tsx

@@ -5,6 +5,7 @@ import {
 } from "@mantine/core";
 import {
   filterStylingProps,
+  mergeClassNames,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import styles from "./Loader.module.css";
@@ -33,23 +34,14 @@ export const Loader = forwardRef<HTMLSpanElement, LoaderProps>(function Loader(
   // Strip all visual override injections unless developer has specifically opted into overStyling.
   // External layout props like margins are safely preserved.
   const sanitizedProps = filterStylingProps(rest, overStyled);
+  const restRecord = sanitizedProps as Record<string, unknown>;
 
-  const mergedClassNames: Partial<Record<string, string>> = {
-    root: styles.root,
-  };
-
-  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;
-  }
+  const mergedClassNames = mergeClassNames(
+    { root: styles.root },
+    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;
   const finalClass = classNameProp
     ? `${styles.root} ${classNameProp}`
     : styles.root;
@@ -57,10 +49,10 @@ export const Loader = forwardRef<HTMLSpanElement, LoaderProps>(function Loader(
   return (
     <MantineLoader
       ref={ref}
+      {...sanitizedProps}
       type={variant}
       data-variant={variant}
       data-size={resolvedSize}
-      {...sanitizedProps}
       className={finalClass}
       classNames={mergedClassNames}
     />

package/src/components/Menu/Menu.stories.tsx

@@ -199,7 +199,9 @@ export const Default: Story = {
     position: "bottom-start",
     withArrow: false,
     offset: 5,
-    opened: undefined,
+    // Rendered open by default so this story is diffable against the MUI adapter
+    // without an interaction step.
+    opened: true,
   },
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   render: ({ withLayer, layer, ...args }: MenuStoryArgs) => {
@@ -230,6 +232,9 @@ export const Default: Story = {
 export const WithDisabledItems: Story = {
   args: {
     position: "bottom-start",
+    // Rendered open by default so this story is diffable against the MUI adapter
+    // without an interaction step.
+    opened: true,
   },
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   render: ({ withLayer, layer, ...args }: MenuStoryArgs) => {
@@ -258,6 +263,9 @@ export const WithSubmenus: Story = {
   args: {
     position: "bottom-start",
     width: 200,
+    // Rendered open by default so this story is diffable against the MUI adapter
+    // without an interaction step.
+    opened: true,
   },
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   render: ({ withLayer, layer, ...args }: MenuStoryArgs) => {