@recursica/mui-adapter 0.25.0 → 0.27.0

package/src/components/DatePicker/DatePicker.tsx

@@ -1,47 +1,229 @@
-/* eslint-disable @typescript-eslint/no-unused-vars */
-import React from "react";
-import "./DatePicker.module.css";
-import { type RecursicaDatePickerProps } from "@recursica/adapter-common";
-
-export type DatePickerProps = Omit<
-  React.HTMLAttributes<HTMLDivElement>,
-  "value" | "onChange" | "defaultValue"
-> &
-  RecursicaDatePickerProps & {
-    disabled?: boolean;
-    label?: React.ReactNode;
-    assistiveText?: string;
-    error?: React.ReactNode;
-    required?: boolean;
-    withAsterisk?: boolean;
-    placeholder?: string;
-    value?: Date | null;
-    defaultValue?: Date | null;
-    onChange?: (value: Date | null) => void;
-    readOnly?: boolean;
-    formLayout?: "stacked" | "side-by-side";
-    leftSection?: React.ReactNode;
-    labelWithEditIcon?: boolean;
-    onLabelEditClick?: () => void;
-  };
-
-export const DatePicker: React.FC<DatePickerProps> = ({
-  disabled,
-  label,
-  assistiveText,
-  error,
-  required,
-  withAsterisk,
-  placeholder,
-  value,
-  defaultValue,
-  onChange,
-  readOnly,
-  formLayout,
-  leftSection,
-  labelWithEditIcon,
-  onLabelEditClick,
-  ...props
-}) => {
-  return <div {...props}>DatePicker</div>;
-};
+import React, { forwardRef, useEffect, useState } from "react";
+import { LocalizationProvider } from "@mui/x-date-pickers/LocalizationProvider";
+import { AdapterDayjs } from "@mui/x-date-pickers/AdapterDayjs";
+import {
+  DatePicker as MuiDatePicker,
+  type DatePickerProps as MuiDatePickerProps,
+  type DatePickerSlotProps,
+  type DatePickerSlots,
+} from "@mui/x-date-pickers/DatePicker";
+import dayjs, { type Dayjs } from "dayjs";
+import { type ReadOnlyControlProps } from "@recursica/adapter-common";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/FormControlWrapper";
+import { WithReadOnlyWrapper } from "../ReadOnlyField/WithReadOnlyWrapper";
+import { CalendarIcon } from "./DatePicker.icons";
+import styles from "./DatePicker.module.css";
+
+import { type RecursicaDatePickerProps as BaseRecursicaDatePickerProps } from "@recursica/adapter-common";
+
+// Default display/entry format (dayjs format string), matching the mantine-adapter's DatePicker.
+const DATE_FORMAT = "MM/DD/YY";
+
+function toDayjs(value: Date | null | undefined): Dayjs | null {
+  return value ? dayjs(value) : null;
+}
+
+export interface RecursicaDatePickerProps
+  extends Omit<
+      MuiDatePickerProps,
+      | "value"
+      | "defaultValue"
+      | "onChange"
+      | "minDate"
+      | "maxDate"
+      | "format"
+      | "slots"
+      | "slotProps"
+    >,
+    Pick<
+      RecursicaFormControlWrapperProps,
+      | "label"
+      | "error"
+      | "required"
+      | "id"
+      | "assistiveText"
+      | "assistiveWithIcon"
+      | "formLayout"
+      | "labelSize"
+      | "labelAlignment"
+      | "labelOptionalText"
+      | "labelWithEditIcon"
+      | "onLabelEditClick"
+    >,
+    ReadOnlyControlProps,
+    BaseRecursicaDatePickerProps {
+  /** Selected date, matching the mantine-adapter convention of a plain `Date` value. */
+  value?: Date | null;
+  /** Uncontrolled initial date. */
+  defaultValue?: Date | null;
+  /** Fires with the new date, or `null` if cleared. */
+  onChange?: (value: Date | null) => void;
+  minDate?: Date;
+  maxDate?: Date;
+  /** Overridable component slots — e.g. `slots={{ openPickerIcon: MyIcon }}` to replace the default calendar icon. */
+  slots?: DatePickerSlots;
+  slotProps?: DatePickerSlotProps;
+  /** Caller-provided inline style, passed through to the FormControlWrapper root. */
+  style?: React.CSSProperties;
+}
+
+export type DatePickerProps = RecursicaOverStyled<RecursicaDatePickerProps>;
+
+export const DatePicker = forwardRef<HTMLDivElement, DatePickerProps>(
+  function DatePicker(props, ref) {
+    const {
+      overStyled = false,
+      formLayout = "stacked",
+
+      // Label & Wrapper Maps
+      labelSize,
+      labelAlignment,
+      labelOptionalText,
+      labelWithEditIcon,
+      onLabelEditClick,
+
+      label,
+      assistiveText,
+      assistiveWithIcon,
+      error,
+      required,
+      id,
+      className,
+      style,
+      disabled,
+      readOnly,
+      readOnlyComponent,
+      emptyValueComponent,
+      value,
+      defaultValue,
+      onChange,
+      minDate,
+      maxDate,
+      slots,
+      slotProps,
+      ...rest
+    } = props;
+
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+
+    // Internal Dayjs value: MUI X's DatePicker only speaks Dayjs (via AdapterDayjs); the public
+    // API stays plain `Date` to match the mantine-adapter convention.
+    const [internalValue, setInternalValue] = useState<Dayjs | null>(
+      () => toDayjs(value) ?? toDayjs(defaultValue) ?? null,
+    );
+
+    useEffect(() => {
+      if (value !== undefined) {
+        setInternalValue(toDayjs(value));
+      }
+    }, [value]);
+
+    const wrapperClass = className
+      ? `${styles.layoutOverride} ${className}`
+      : styles.layoutOverride;
+
+    const handleChange = (next: Dayjs | null) => {
+      setInternalValue(next);
+      onChange?.(next ? next.toDate() : null);
+    };
+
+    const readOnlyValue = (() => {
+      const source = value !== undefined ? value : defaultValue;
+      return toDayjs(source)?.format(DATE_FORMAT);
+    })();
+
+    // slotProps.field/desktopPaper are typed to also allow a `(ownerState) => props` function
+    // form; this adapter only ever merges plain objects (same assumption TextField/DatePicker's
+    // mantine counterpart make for consumer-supplied classNames), so narrow to that shape here.
+    const consumerFieldProps =
+      slotProps?.field && typeof slotProps.field === "object"
+        ? (slotProps.field as Record<string, unknown>)
+        : undefined;
+    const consumerDesktopPaperProps =
+      slotProps?.desktopPaper && typeof slotProps.desktopPaper === "object"
+        ? (slotProps.desktopPaper as Record<string, unknown>)
+        : undefined;
+
+    return (
+      <WithReadOnlyWrapper
+        ref={ref}
+        className={wrapperClass}
+        style={style}
+        controlMaxWidth={undefined}
+        controlMinWidth={undefined}
+        overStyled={overStyled as true}
+        formLayout={formLayout}
+        labelSize={labelSize}
+        labelAlignment={labelAlignment}
+        labelOptionalText={labelOptionalText}
+        labelWithEditIcon={labelWithEditIcon}
+        onLabelEditClick={onLabelEditClick}
+        label={label}
+        assistiveText={assistiveText}
+        assistiveWithIcon={assistiveWithIcon}
+        error={error}
+        required={required}
+        id={id}
+        readOnly={readOnly}
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        readOnlyComponent={readOnlyComponent as any}
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        emptyValueComponent={(emptyValueComponent as any) || undefined}
+        readOnlyType="text"
+        readOnlyValue={readOnlyValue}
+        readOnlyNativeProps={props}
+        activeComponent={
+          /* Naked field execution safely decoupled from MUI X's own label/error macro handling,
+             same convention as TimePicker.tsx. Unlike TimePicker, the popup calendar IS used here
+             (and token-styled below) — see DATEPICKER_IMPLEMENTATION_NOTES.md. */
+          <div className={styles.root} data-error={error ? "true" : undefined}>
+            <LocalizationProvider dateAdapter={AdapterDayjs}>
+              <MuiDatePicker
+                {...(sanitizedProps as unknown as Partial<MuiDatePickerProps>)}
+                value={internalValue}
+                onChange={handleChange}
+                disabled={disabled}
+                format={DATE_FORMAT}
+                minDate={toDayjs(minDate) ?? undefined}
+                maxDate={toDayjs(maxDate) ?? undefined}
+                slots={{ openPickerIcon: CalendarIcon, ...slots }}
+                slotProps={
+                  {
+                    ...slotProps,
+                    field: {
+                      // Calendar icon opens the picker from the left side of the field, mirroring
+                      // the mantine-adapter's default `leftSection`; overridable via
+                      // `slots.openPickerIcon`. Only settable per-field, not at the picker's own
+                      // top level (MUI X has no top-level `openPickerButtonPosition` prop).
+                      openPickerButtonPosition: "start",
+                      ...consumerFieldProps,
+                      className: consumerFieldProps?.className
+                        ? `${styles.field} ${consumerFieldProps.className as string}`
+                        : styles.field,
+                    },
+                    // The popup surface is portaled to document.body, outside this component's own
+                    // DOM subtree, so — same constraint mantine-adapter's `popoverProps.classNames`
+                    // documents — it can only be reached by handing it a className directly, not a
+                    // descendant CSS selector.
+                    desktopPaper: {
+                      ...consumerDesktopPaperProps,
+                      className: consumerDesktopPaperProps?.className
+                        ? `${styles.dropdown} ${consumerDesktopPaperProps.className as string}`
+                        : styles.dropdown,
+                    },
+                  } as DatePickerSlotProps
+                }
+              />
+            </LocalizationProvider>
+          </div>
+        }
+      />
+    );
+  },
+);
+
+DatePicker.displayName = "DatePicker";

package/src/components/DatePicker/USAGE.md

@@ -19,7 +19,7 @@ import React from "react";
 import { DatePicker } from "@recursica/mui-adapter";
 
 export default function Demo() {
-  return <DatePicker label="Select Date" placeholder="Pick a date" />;
+  return <DatePicker label="Select Date" />;
 }
 ```
 
@@ -34,3 +34,16 @@ All Recursica components in the `@recursica/mui-adapter` package adhere strictly
 > - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
 > - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
 > - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.
+
+---
+
+## 4. Key Integration Features & Constraints
+
+## Structural Constraints
+
+1. **Value Type**: `value`/`defaultValue`/`onChange` all speak plain `Date` objects (not MUI X's native `Dayjs`), matching the mantine-adapter's DatePicker convention — conversion to/from `Dayjs` happens internally.
+2. **Read-Only Rendering**: When rendered in read-only mode, the selected date is displayed formatted as `MM/DD/YY`. If you need custom date formatting, pass a `readOnlyComponent` prop to control how the value is rendered.
+3. **Calendar Popover Styling**: The UI Kit exports no calendar-specific tokens (surface, selected day, hover, today, in-range), so the calendar reuses the closest existing tokens — see `DATEPICKER_IMPLEMENTATION_NOTES.md` for the exact mapping, mirrored 1:1 from the mantine-adapter. The header's prev/next arrows and month-view toggle are styled as Recursica `text`-variant buttons.
+4. **Typing vs. Popover Entry**: Unlike the mantine-adapter (popover-only selection), MUI X's field supports typing a date directly into its masked `MM/DD/YY` segments, in addition to picking from the popup calendar.
+5. **Default Display/Entry Format**: `MM/DD/YY` (e.g. `08/19/26`), matching the mantine-adapter; pass your own `format` (a `dayjs` format string) via the standard MUI X `DatePicker` props to override.
+6. **Default Leading Icon**: A calendar icon opens the picker from the start of the field by default; pass `slots={{ openPickerIcon: MyIcon }}` to override it.

package/src/components/Dropdown/BareDropdown.tsx

@@ -6,6 +6,7 @@ import {
 } from "@mui/material";
 import {
   filterStylingProps,
+  omitUnsupportedProps,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import styles from "./Dropdown.module.css";
@@ -52,14 +53,19 @@ export const BareDropdown = forwardRef<
     error,
     ...rest
   } = props;
-  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 sizing via design tokens, not MUI's native small/medium size
+    "variant", // Recursica styles the naked select directly; MUI's standard/filled/outlined unused
+    "classes", // Recursica computes its own classes object below; caller's would silently clobber it
+  ] as const satisfies readonly (keyof MuiSelectProps)[];
 
-  delete restRecord["size"];
-  delete restRecord["variant"];
-  // className is merged explicitly below — don't let the spread further down silently overwrite
-  // styles.root with just the caller's own class.
-  delete restRecord["className"];
+  const sanitizedProps = omitUnsupportedProps(
+    filterStylingProps(rest, overStyled),
+    UNSUPPORTED_PROPS,
+  );
+  const restRecord = sanitizedProps as Record<string, unknown>;
 
   const mergedClassName = className
     ? `${styles.root} ${className}`
@@ -100,6 +106,7 @@ export const BareDropdown = forwardRef<
   return (
     <MuiSelect
       ref={ref}
+      {...(sanitizedProps as unknown as MuiSelectProps)}
       disabled={disabled}
       value={value}
       defaultValue={defaultValue}
@@ -125,7 +132,6 @@ export const BareDropdown = forwardRef<
         "data-error": error ? "true" : undefined,
         ...(restRecord.inputProps as Record<string, unknown>),
       }}
-      {...(sanitizedProps as unknown as MuiSelectProps)}
     >
       {renderOptions()}
     </MuiSelect>

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

@@ -1,10 +1,3 @@
-/* EXEMPTIONS:
-   - state-specific border-size variables are ignored because a uniform 1px border is applied globally to prevent
-     unexpected layout shift or flickering during focus, disabled, or error state transitions. */
-/* recursica-ignore: --recursica_ui-kit_components_dropdown_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_dropdown_variants_states_disabled_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_dropdown_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 --dropdown-control-{max,min}-width hooks consumed inline in Dropdown.tsx, since

package/src/components/Dropdown/Dropdown.tsx

@@ -7,6 +7,7 @@ import {
 import { type ReadOnlyControlProps } from "@recursica/adapter-common";
 import {
   filterStylingProps,
+  omitUnsupportedProps,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/FormControlWrapper";
@@ -73,12 +74,18 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
       clearable, // Not natively supported by basic MUI Select, stubbed
       ...rest
     } = props;
-    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 sizing via design tokens, not MUI's native small/medium size
+      "variant", // Recursica styles the naked select directly; MUI's standard/filled/outlined unused
+    ] as const satisfies readonly (keyof MuiSelectProps)[];
 
-    // Delete prohibited sizing hooks
-    delete restRecord["size"];
-    delete restRecord["variant"];
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled),
+      UNSUPPORTED_PROPS,
+    );
+    const restRecord = sanitizedProps as Record<string, unknown>;
 
     const injectedStyles = {
       ...((style as React.CSSProperties) || {}),
@@ -159,6 +166,7 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
         activeComponent={
           <MuiSelect
             ref={ref}
+            {...(sanitizedProps as unknown as MuiSelectProps)}
             disabled={disabled}
             value={value}
             defaultValue={defaultValue}
@@ -185,7 +193,6 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
               "data-error": error ? "true" : undefined,
               ...(restRecord.inputProps as Record<string, unknown>),
             }}
-            {...(sanitizedProps as unknown as MuiSelectProps)}
           >
             {renderOptions()}
           </MuiSelect>

package/src/components/FileInput/FileInput.module.css

@@ -1,24 +1,3 @@
-/* EXEMPTIONS:
-   - The disabled/error states' own border-size variables are ignored so the border never changes
-     thickness across states and shifts the layout — same house policy as TextField/DatePicker.
-     The flat, state-agnostic properties_border-size token below is applied uniformly instead.
-   - There is no forge-defined focus state for file-input (no `states.focus` axis, unlike its
-     disabled/error siblings) — the generic recursica_brand_states_focus_* ring is used instead,
-     same fallback TextField/DatePicker use for the same reason.
-   - properties_icon-text-gap doubles as the gap between chips: file-input has no dedicated
-     chip-gap token (unlike file-upload's properties_item-gap).
-   - The trailing clear-all affordance is now a real shared `Button` (icon-only, "text" variant)
-     rather than a bespoke span, so it gets its own real button semantics/keyboard handling —
-     same pattern as Tree's expand/collapse button. It renders through Button's own tokened
-     color states (including disabled), so file-input's own trailing-icon color tokens — which
-     have no "clear button is disabled/errored" equivalent state of their own anyway — are no
-     longer consumed here. */
-/* recursica-ignore: --recursica_ui-kit_components_file-input_variants_states_disabled_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_file-input_variants_states_error_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_file-input_properties_colors_trailing-icon */
-/* recursica-ignore: --recursica_ui-kit_components_file-input_variants_states_error_properties_colors_trailing-icon */
-/* recursica-ignore: --recursica_ui-kit_components_file-input_variants_states_disabled_properties_colors_trailing-icon */
-
 /* LAYOUT SPACING OVERRIDES:
    - Sets the --form-control-margin-bottom spacing hook to map component-specific layout tokens.
    - Also sets the --file-input-control-{max,min}-width hooks consumed inline in FileInput.tsx,

package/src/components/FileInput/FileInput.tsx

@@ -308,6 +308,7 @@ export const FileInput = forwardRef<HTMLDivElement, FileInputProps>(
       >
         <div
           ref={ref}
+          {...restRecord}
           className={styles.root}
           role="button"
           aria-label={browseLabel}
@@ -323,7 +324,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.module.css

@@ -1,14 +1,3 @@
-/* EXEMPTIONS:
-   - border-style has no usable var(...) form: the Figma-exported token's value is the literal
-     string `"dashed"` (quotes included), which is not a valid CSS <line-style> keyword — the same
-     class of "structural, not tokenized" property the canonical guide already treats border-style
-     as (see .root's own HARDCODED VALUES note below and TimePicker/DatePicker's identical
-     hardcoded `border-style: solid`). Hardcoded to the keyword `dashed` instead.
-   - properties_icon-size has no equivalent: unlike TextField/DatePicker, file-upload has no
-     dedicated icon-size token. Sized to visually match the Figma reference instead (see
-     HARDCODED VALUES below). */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_properties_border-style */
-
 /* HARDCODED VALUES:
    - .root: display: flex; flex-direction: column; width: 100% — structural layout, not a design
      token concern (matches how other block-level components like Layer are laid out).

package/src/components/FileUpload/FileUpload.tsx

@@ -267,10 +267,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/FormControlLayout/FormControlLayout.tsx

@@ -32,6 +32,7 @@ export const FormControlLayout = React.forwardRef<
   return (
     <div
       ref={ref}
+      {...sanitizedProps}
       className={className ? `${styles.root} ${className}` : styles.root}
       data-form-layout={formLayout}
       style={
@@ -45,7 +46,6 @@ export const FormControlLayout = React.forwardRef<
             : {}),
         } as React.CSSProperties
       }
-      {...sanitizedProps}
     >
       {/* 
         The left section strictly enforces the Label boundary sizes 

package/src/components/FormControlWrapper/FormControlWrapper.tsx

@@ -94,6 +94,7 @@ export const FormControlWrapper = React.forwardRef<
   return (
     <FormControl
       ref={ref}
+      {...(sanitizedProps as FormControlProps)}
       error={!!error}
       required={required}
       disabled={disabled}
@@ -103,7 +104,6 @@ export const FormControlWrapper = React.forwardRef<
       data-error={error ? "true" : undefined}
       data-disabled={disabled ? "true" : undefined}
       data-focused={focused ? "true" : undefined}
-      {...(sanitizedProps as FormControlProps)}
     >
       <FormControlLayout
         formLayout={formLayout}

package/src/components/HoverCard/HoverCard.module.css

@@ -5,13 +5,7 @@
      and positioning (-arrowSize/2) calculations that cannot be CSS-driven. The default matches
      the Recursica beak-size token (16px). See COMPONENT_ISSUES.md for details.
    - All structural layout (display, position, overflow) is deferred to Mantine's native
-     behavior. We only override visual design tokens (colors, typography, spacing, borders).
-/* EXEMPTIONS:
-   - beak-size is ignored here because Mantine's popover arrows compute their sizing and positional offsets
-     dynamically within the React rendering engine (requires inline pixel number rather than standard CSS variables).
-     The beak size is checked in JS against a fixed value of 16px. If this variable changes, the TSX components
-     need to be reviewed/re-compiled. */
-/* recursica-ignore: --recursica_ui-kit_components_hover-card-popover_properties_beak-size = 16px */
+     behavior. We only override visual design tokens (colors, typography, spacing, borders). */
 
 /* ======================================
    DROPDOWN CONTAINER

package/src/components/HoverCard/HoverCard.tsx

@@ -5,6 +5,7 @@ import {
 } from "@mui/material";
 import {
   filterStylingProps,
+  mergeClassNames,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import styles from "./HoverCard.module.css";
@@ -35,27 +36,18 @@ const HoverCardBase = function HoverCard({
     overStyled,
   );
 
-  // Bind CSS module classes to Mui's internal classNames API
-  const mergedClassNames: Partial<Record<string, string>> = {
-    tooltip: 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];
-      }
-    });
-  }
+  // Bind CSS module classes to Mui's internal classNames API. Note MUI's actual prop is
+  // "classes", not "classNames" (that's Mantine's naming) — this used to read the wrong key,
+  // silently no-op-ing any caller-supplied classes.
+  const mergedClassNames = mergeClassNames(
+    {
+      tooltip: styles.dropdown,
+      arrow: styles.arrow,
+    },
+    (sanitizedProps as Record<string, unknown>).classes as
+      | Partial<Record<string, string>>
+      | undefined,
+  );
 
   // Find Target and Dropdown children
   let targetNode: React.ReactNode = null;

package/src/components/Label/Label.module.css

@@ -1,9 +1,3 @@
-/* EXEMPTIONS:
-   - layouts_stacked sizes width variables are ignored because stacked labels naturally occupy 100% width block-level
-     real estate in HTML rendering, making explicit width properties redundant. Mirrors the mantine-adapter reference. */
-/* recursica-ignore: --recursica_ui-kit_components_label_variants_layouts_stacked_variants_sizes_default_properties_width */
-/* recursica-ignore: --recursica_ui-kit_components_label_variants_layouts_stacked_variants_sizes_small_properties_width */
-
 .root {
   /* Prevent default MUI absolute positioning logic */
   position: relative;

package/src/components/Link/Link.module.css

@@ -1,8 +1,3 @@
-/* EXEMPTIONS:
-   - text_text-transform is ignored because links naturally inherit casing directly from text
-     children rather than requiring custom CSS transforms. Mirrors the mantine-adapter reference. */
-/* recursica-ignore: --recursica_ui-kit_components_link_properties_text_text-transform */
-
 /*
 HARDCODED VALUES:
 - display: inline-flex; (Base layout to align icon and text correctly)
@@ -79,11 +74,3 @@ HARDCODED VALUES:
   /* HARDCODE: allows text truncation if bounded */
   min-width: 0;
 }
-
-/* EXEMPTIONS:
-   text_text-transform across multiple link states (default, hover, visited, visited-hover) is ignored
-   because links naturally inherit casing directly from text children rather than requiring custom CSS transforms. */
-/* recursica-ignore: --recursica_ui-kit_components_link_variants_states_default_properties_text_text-transform */
-/* recursica-ignore: --recursica_ui-kit_components_link_variants_states_hover_properties_text_text-transform */
-/* recursica-ignore: --recursica_ui-kit_components_link_variants_states_visited_properties_text_text-transform */
-/* recursica-ignore: --recursica_ui-kit_components_link_variants_states_visited-hover_properties_text_text-transform */

package/src/components/Menu/Menu.module.css

@@ -1,8 +1,3 @@
-/* EXEMPTIONS:
-   - colors_supporting-text-color (selected variant) is ignored because selected menu items do not render
-     supporting secondary text, making the selected-state override for supporting text colors obsolete. */
-/* recursica-ignore: --recursica_ui-kit_components_menu-item_variants_selection-states_selected_properties_colors_supporting-text-color */
-
 /* HARDCODED VALUES:
    - border-style: solid. Structural rendering rule for the dropdown border (Mantine uses Paper which may not set border natively).
    - NOTE: overflow is intentionally NOT set on .dropdown. Mantine renders sub-menu dropdowns