@recursica/mui-adapter 0.19.0 → 0.21.0

package/dist/src/components/Dropdown/BareDropdown.d.ts

@@ -0,0 +1,41 @@
+import { default as React } from 'react';
+import { SelectProps as MuiSelectProps } from '@mui/material';
+import { RecursicaOverStyled } from '../../utils/filterStylingProps';
+/**
+ * Bare, unwrapped Select — no `FormControlWrapper`/`WithReadOnlyWrapper`, no label/assistiveText/
+ * error/required. Tied to the same `Dropdown.module.css` variables/classes as the public
+ * `Dropdown` component, so it looks identical, but is meant to be embedded inside another
+ * component that already owns its own `FormControlWrapper` (e.g. `TimePicker`'s AM/PM control) —
+ * nesting the full `Dropdown` there would double up `FormControl`/`FormControlLayout` wrapping.
+ *
+ * Not exported from this folder's `index.ts` — internal use only. Import it directly:
+ * `import { BareDropdown } from "../Dropdown/BareDropdown"`.
+ */
+export interface BareDropdownProps extends Omit<MuiSelectProps, "size" | "variant" | "classes" | "error" | "onChange"> {
+    data: (string | {
+        value: string;
+        label: React.ReactNode;
+        disabled?: boolean;
+    })[];
+    /** Normalized to just the selected value, unlike MUI's raw (event, child) Select onChange. */
+    onChange?: (value: string | null) => void;
+    /** Applies the error visual state (via `data-error`) — no error message is rendered here. */
+    error?: boolean;
+}
+export type BareDropdownComponentProps = RecursicaOverStyled<BareDropdownProps>;
+export declare const BareDropdown: React.ForwardRefExoticComponent<(Omit<Omit<import('@recursica/adapter-common').WithRecursicaSpacing<BareDropdownProps>, import('@recursica/adapter-common').BlockedStylingKeys> & import('@recursica/adapter-common').ForbiddenStyles & {
+    overStyled?: false | undefined;
+}, "ref"> | Omit<Omit<BareDropdownProps, "m" | "my" | "mx" | "mt" | "mb" | "ml" | "mr" | "gap" | "rowGap" | "columnGap"> & {
+    m?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    mx?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    my?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    mt?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    mb?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    ml?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    mr?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    gap?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    rowGap?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    columnGap?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+} & {
+    overStyled: true;
+}, "ref">) & React.RefAttributes<HTMLInputElement>>;

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

@@ -1,4 +1,17 @@
 import { default as React } from 'react';
-import { RecursicaTimePickerProps } from '@recursica/adapter-common';
-export type TimePickerProps = React.HTMLAttributes<HTMLDivElement> & RecursicaTimePickerProps;
-export declare const TimePicker: React.FC<TimePickerProps>;
+import { TimePickerProps as MuiTimePickerProps } from '@mui/x-date-pickers/TimePicker';
+import { ReadOnlyControlProps, RecursicaTimePickerProps as BaseRecursicaTimePickerProps } from '@recursica/adapter-common';
+import { RecursicaOverStyled } from '../../utils/filterStylingProps';
+import { RecursicaFormControlWrapperProps } from '../FormControlWrapper/FormControlWrapper';
+export interface RecursicaTimePickerProps extends Omit<MuiTimePickerProps, "value" | "defaultValue" | "onChange" | "minTime" | "maxTime" | "views" | "format" | "style">, Pick<RecursicaFormControlWrapperProps, "label" | "error" | "required" | "id" | "assistiveText" | "assistiveWithIcon" | "formLayout" | "labelSize" | "labelAlignment" | "labelOptionalText" | "labelWithEditIcon" | "onLabelEditClick">, ReadOnlyControlProps, BaseRecursicaTimePickerProps {
+    /** Selected time as an "HH:mm" (or "HH:mm:ss" with `withSeconds`) string, matching the mantine-adapter convention. */
+    value?: string;
+    /** Uncontrolled initial time as an "HH:mm" (or "HH:mm:ss" with `withSeconds`) string. */
+    defaultValue?: string;
+    /** Fires with the new time as an "HH:mm" (or "HH:mm:ss" with `withSeconds`) string, or `null` if cleared. */
+    onChange?: (value: string | null) => void;
+    /** Caller-provided inline style, passed through to the FormControlWrapper root. */
+    style?: React.CSSProperties;
+}
+export type TimePickerProps = RecursicaOverStyled<RecursicaTimePickerProps>;
+export declare const TimePicker: React.ForwardRefExoticComponent<TimePickerProps & React.RefAttributes<HTMLDivElement>>;

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

@@ -9,5 +9,10 @@ export type TreeProps = RecursicaOverStyled<RecursicaTreeProps & Omit<React.Comp
  * Wraps `@mui/x-tree-view`'s `RichTreeView` with a fully custom item renderer so every visual
  * aspect (row box model, selected/unselected colors and typography, indent, item spacing)
  * comes from Recursica's `tree` design tokens rather than MUI's defaults.
+ *
+ * **Interaction pattern (fixed, not prop-configurable):** expand/collapse and select are
+ * independent — the chevron button toggles a node's subtree only, clicking the rest of a row
+ * (or pressing `Enter`/`Space`) selects it only, and `ArrowLeft`/`ArrowRight` toggle expansion
+ * only. See `RecursicaTreeProps` for the full breakdown.
  */
 export declare const Tree: React.ForwardRefExoticComponent<TreeProps & React.RefAttributes<HTMLUListElement>>;

package/dist/src/index.d.ts

@@ -88,4 +88,4 @@ export declare const Toast: typeof rawComponents.Toast;
 export declare const Tooltip: typeof rawComponents.Tooltip;
 export declare const TransferList: typeof rawComponents.TransferList;
 export declare const Tree: typeof rawComponents.Tree;
-export type { RecursicaAutocompleteProps, RecursicaDropdownProps, RecursicaFormControlWrapperProps, RecursicaNumberInputProps, RecursicaSliderProps, RecursicaTextAreaProps, RecursicaTextFieldProps, RecursicaToastProps, } from './components';
+export type { RecursicaAutocompleteProps, RecursicaDropdownProps, RecursicaFormControlWrapperProps, RecursicaNumberInputProps, RecursicaSliderProps, RecursicaTextAreaProps, RecursicaTextFieldProps, RecursicaTimePickerProps, RecursicaToastProps, } from './components';

package/docs/PHILOSOPHY.md

@@ -0,0 +1,39 @@
+# Recursica MUI Adapter: Core Philosophy
+
+Recursica's component architecture isn't just a wrapper; it's a strict enforcing layer over MUI's massive API surface. Our primary goal is to ensure consistency, eliminate "design system rot," and provide clear boundaries for application developers using the UI Kit.
+
+This document serves as the governing framework for why the `mui-adapter` components are built the way they are.
+
+## 1. Strict Separation of Props (The Unified Recursica Prop Layer)
+
+Recursica has a **single universal API surface** internally regardless of whether we use MUI or another underlying UI library.
+
+- We decouple our visual properties natively. Instead of mapping perfectly to MUI's native variants `(contained, outlined, text)`, we intentionally use Recursica's semantic and behavioral structures (e.g., `<Badge variant="alert" />`).
+- We intentionally omit and strip complex underlying parameters if they collide with or circumvent our UI tokens (like stripping `--size` or raw MUI size properties when Recursica enforces a universal scale).
+
+## 2. Component Wrappers (Leaving MUI Alone)
+
+We actively avoid mutating or patching MUI source code or deeply hooking into the MUI `createTheme` Theme object to apply our token system.
+
+- We rely on standard DOM `module.css` bridging with strictly targeted `className`/`classes` overrides whenever possible, instead of heavy Emotion/CSS-in-JS logic.
+- This creates total decoupled isolation: updating MUI natively will not fracture our styles, and we avoid dealing with deep CSS-in-JS theme clashing logic.
+
+## 3. The `overStyled` Property
+
+MUI encourages deep styling access by injecting the `sx` prop, system props like `bgcolor`, `color`, `typography`, or nested `classes` directly into component tags.
+
+- By default, **Recursica components block all arbitrary styling vectors**. `sx` maps, `classes` overrides, system styles, and inline logic are proactively stripped before they hit MUI using central utility functions.
+- **Why?** To prevent the design system from deteriorating over time as developers write one-off hotfixes into their TSX rendering blocks.
+- **The Caveat:** We allow _external DOM layout positioning props_ (e.g., margin `m`, `mt`, `p`, `px`, etc.) to pass through and natively intercept Recursica Spacing Tokens (`rec-sm`, `rec-default`) so developers can structure components organically within their parent layouts.
+
+### Escape Hatches
+
+If a developer _strictly must_ heavily alter a component, they are required to explicitly declare `<Component overStyled={true} />`. This immediately raises a visible red flag during code reviews.
+
+## 4. Expectations for External Developers (Modifying Recursica)
+
+If a developer finds that a component does not fit their needs and styling must be modified, their path of execution should follow these principles sequentially:
+
+1. **Leverage Native MUI First:** If a Recursica component lacks the functionality or styling variant needed for a highly custom edge case (e.g., a massive marketing hero button), do not try to forcibly hack the Recursica component. Instead, import the raw underlying `Button` component directly from `@mui/material` and style it manually. Use Recursica for standard systematic needs, and native libraries for isolated custom one-offs.
+2. **Accept `overStyled` as Technical Debt:** If you must override the Recursica component immediately but intend to roll it back, use `overStyled={true}`. The expectation is that `overStyled` uses will eventually be replaced once the actual Recursica Figma variants are natively updated to accommodate your usecase, at which point `overStyled={true}` can be safely removed.
+3. **Contribute to the Kit:** Avoid building private custom wrappers around Recursica components. If the system is missing a variant, that is a shared project deficit—raise a concern and have the variant integrated directly into the universal token libraries!

package/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/borderux/recursica.git",
     "directory": "packages/mui-adapter"
   },
-  "version": "0.19.0",
+  "version": "0.21.0",
   "publishConfig": {
     "access": "public"
   },
@@ -38,7 +38,8 @@
     "USAGE.md",
     "ARCHITECTURE.md",
     "SETUP.md",
-    "OVERSTYLING.md"
+    "OVERSTYLING.md",
+    "docs/PHILOSOPHY.md"
   ],
   "keywords": [
     "react",
@@ -64,6 +65,7 @@
     "@chromatic-com/storybook": "^5.1.1",
     "@eslint/js": "^9.25.0",
     "@mui/lab": "^7.0.1-beta.25",
+    "@mui/x-date-pickers": "^9.11.0",
     "@mui/x-tree-view": "^9.11.0",
     "@recursica/recursica-postcss-vars": "*",
     "@recursica/storybook-template": "*",
@@ -101,13 +103,15 @@
   },
   "dependencies": {
     "@recursica/adapter-common": "*",
-    "@recursica/official-release": "*"
+    "@recursica/official-release": "*",
+    "dayjs": "^1.11.21"
   },
   "peerDependencies": {
     "@emotion/react": "^11.14.0",
     "@emotion/styled": "^11.14.0",
     "@mui/lab": "^7.0.1-beta.25",
     "@mui/material": "^7.3.0",
+    "@mui/x-date-pickers": "^9.11.0",
     "@mui/x-tree-view": "^9.11.0",
     "react": ">=16.8.0",
     "react-dom": ">=16.8.0"
@@ -116,6 +120,9 @@
     "@mui/lab": {
       "optional": true
     },
+    "@mui/x-date-pickers": {
+      "optional": true
+    },
     "@mui/x-tree-view": {
       "optional": true
     }

package/src/components/Box/USAGE.md

@@ -45,4 +45,4 @@ All Recursica components in the `@recursica/mui-adapter` package adhere strictly
 
 ## `sx` Prop Exemption
 
-By design, the `Box` component is the most permissive primitive in the UI kit. It explicitly allows the `sx` prop to pass through to the underlying MUI `Box`. It does not use any strict styling gatekeepers (`RecursicaOverStyled`, `filterSxProp`). It is intended to be used as a final escape hatch when the standard layout primitives or design system tokens cannot fulfill a unique layout requirement.
+By design, the `Box` component is the most permissive primitive in the UI kit: it always allows the `sx` prop to pass through, without requiring `overStyled`. It is intended to be used as a final escape hatch when the standard layout primitives or design system tokens cannot fulfill a unique layout requirement.

package/src/components/Button/BUTTON_IMPLEMENTATION_NOTES.md

@@ -31,3 +31,25 @@ We explicitly pass `disableRipple` and `disableElevation` to block MUI's dynamic
 **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 MUI's internal loading opacity adjustments.
+
+---
+
+## `className` overwrite bug (Matt Massey, 2026-08-08)
+
+**Bug:** with `overStyled` and a custom `className` (e.g. Tree embedding a `Button` for its expand chevron), the component's own `styles.root` class silently disappeared from the rendered `<button>` — every `[data-variant]`/`[data-size]` CSS rule stopped applying, and MUI's own default styling (including its default blue "primary" color) showed through instead.
+
+**Root cause:** `className={finalClass}` (`` `${styles.root} ${classNameProp}` ``) was set explicitly on `<MuiButton>`, but `{...sanitizedProps}` was spread _after_ it — and `sanitizedProps` still contained the original, unmodified `className` key, since it had only been _read_ to compute `finalClass`, never deleted. The later spread silently overwrote the merged class with just the caller's own class. Same bug class as `Dropdown.tsx`/`BareDropdown.tsx` had.
+
+**Fix:** delete `className` from the sanitized props record right after reading it, before it reaches the JSX spread. mantine-adapter's `Button.tsx` had the identical mistake — masked there by a separate `classNames={{root: ...}}` object prop unaffected by the bug, but fixed there too for correctness.
+
+---
+
+## `.MuiButton-startIcon`/`.MuiButton-endIcon` selectors never matched anything (Matt Massey, 2026-08-10)
+
+**Bug:** icon-only buttons rendered with the icon visibly off-center — shifted left, with extra empty space on the right. Not a regression from any recent change; `Button.module.css` itself was untouched, and the same unwrapped selectors already existed at `HEAD`. It had just gone unnoticed until the Tree work put an icon-only Button (the chevron) under closer visual scrutiny next to Mantine's (correctly centered) version.
+
+**Root cause:** `.MuiButton-startIcon`/`.MuiButton-endIcon` are real global class names MUI's `Button` applies directly in the DOM — not local CSS Modules classes generated from this file. Referencing them as plain `.MuiButton-startIcon` (rather than `:global(.MuiButton-startIcon)`, the pattern already used correctly for `.Mui-disabled` elsewhere in this same file) meant Vite's CSS Modules silently hashed them into scoped names — `.Button-module__MuiButton-startIcon___<hash>` — that never matched anything real in the DOM. Every rule targeting them (the icon↔label gap margin, and the icon-only margin reset) was a total no-op; icon-only buttons were left with MUI's own unreset default `margin-right` on the icon, which is what visibly pushed the icon off-center.
+
+**Fix:** wrapped every `.MuiButton-startIcon`/`.MuiButton-endIcon` reference in `:global(...)`.
+
+**Not otherwise fixed, flagged separately:** the same unwrapped-global-class pattern shows up in at least `Stepper.module.css` (`.Mui-active`/`.Mui-completed`/`.MuiStepLabel-root`, fully unwrapped) and `SegmentedControl.module.css`, and partially in `Label.module.css`/`Accordion.module.css` — meaning some of those components' MUI-state-driven styling may also be silently no-op'ing. Out of scope for this fix (Button only, per what was asked); worth a dedicated sweep.

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

@@ -202,26 +202,29 @@
   );
 }
 
-/* MUI uses .MuiButton-startIcon and .MuiButton-endIcon */
-.root[data-size="default"] .MuiButton-startIcon {
+/* MUI uses .MuiButton-startIcon and .MuiButton-endIcon — real global classes MUI applies
+   directly, not local CSS Modules classes, so they must be wrapped in :global() (same as
+   .Mui-disabled below) or Vite's CSS Modules hashes them into scoped names that never match
+   anything in the actual DOM, silently no-op'ing every rule below. */
+.root[data-size="default"] :global(.MuiButton-startIcon) {
   margin-left: 0;
   margin-right: var(
     --recursica_ui-kit_components_button_variants_sizes_default_properties_icon-text-gap
   );
 }
-.root[data-size="default"] .MuiButton-endIcon {
+.root[data-size="default"] :global(.MuiButton-endIcon) {
   margin-right: 0;
   margin-left: var(
     --recursica_ui-kit_components_button_variants_sizes_default_properties_icon-text-gap
   );
 }
-.root[data-size="small"] .MuiButton-startIcon {
+.root[data-size="small"] :global(.MuiButton-startIcon) {
   margin-left: 0;
   margin-right: var(
     --recursica_ui-kit_components_button_variants_sizes_small_properties_icon-text-gap
   );
 }
-.root[data-size="small"] .MuiButton-endIcon {
+.root[data-size="small"] :global(.MuiButton-endIcon) {
   margin-right: 0;
   margin-left: var(
     --recursica_ui-kit_components_button_variants_sizes_small_properties_icon-text-gap
@@ -232,8 +235,8 @@
 .root[data-content="icon-only"] .labelText {
   display: none;
 }
-.root[data-content="icon-only"] .MuiButton-startIcon,
-.root[data-content="icon-only"] .MuiButton-endIcon {
+.root[data-content="icon-only"] :global(.MuiButton-startIcon),
+.root[data-content="icon-only"] :global(.MuiButton-endIcon) {
   margin-right: 0;
   margin-left: 0;
 }

package/src/components/Button/Button.tsx

@@ -87,6 +87,10 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
     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
+    // mui-adapter's Dropdown/BareDropdown.tsx had).
+    delete restRecord["className"];
 
     // We don't map Recursica variant/size to MUI's because we want to completely disable MUI's native
     // variant logic (e.g., elevation, shadows) and style everything strictly through our CSS Modules.

package/src/components/Button/USAGE.md

@@ -43,16 +43,4 @@ All Recursica components in the `@recursica/mui-adapter` package adhere strictly
 
 ## 4. Key Integration Features & Constraints
 
-## Loader color contrast
-
-**Decision:** When a Button is in a loading state, the `Recursica Loader` component is injected via the `loadingIndicator` prop. The `Loader` component strictly defines its own colors and styles per variant, meaning it does not automatically 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 MUI's internal loading opacity adjustments.
+When `loading={true}` is passed to the Button, the button is also automatically disabled, and its loading indicator's color may not always match the button's text color, which can affect contrast in some variants.

package/src/components/Card/USAGE.md

@@ -54,16 +54,4 @@ All Recursica components in the `@recursica/mui-adapter` package adhere strictly
 
 ## 4. Key Integration Features & Constraints
 
-## Architecture Overrides
-
-Because MUI natively constructs `Card` bounding boxes using `<Paper>` components (which lack the precise edge-to-edge layouts native to Mantine's sections), we implemented custom margins for edge-to-edge section components:
-
-- `<Card.Header>` explicitly hooks `--recursica_ui-kit_components_card_properties_header-background` and corresponding padding variables, stretching edge-to-edge via negative margin resets.
-- `<Card.Footer>` explicitly hooks `--recursica_ui-kit_components_card_properties_footer-background` and corresponding padding variables.
-
-## Layout Alignment Exceptions
-
-To allow Cards to fit cleanly inside dynamic/flex layouts (like dashboard panels, grid tracks, or sidebar layout segments), the Card wrapper implements a custom gatekeeper bypass for outer styling properties:
-
-- Exposes a safe subset of flexbox/dimensions styling properties (`flex`, `flexGrow`, `flexShrink`, `flexBasis`, `grow`, `h`, `height`) on the root `<Card>` component to allow proper sizing alongside layout siblings.
-- Sets `<Card.Content>` to `flex-grow: 1;` by default via CSS modules. Since the root `<Card>` has `display: flex; flex-direction: column;`, this makes the content area expand to fill all vertical space, pushing `<Card.Footer>` to align at the absolute bottom of the bounding box.
+`Card.Header` and `Card.Footer` stretch edge-to-edge within the card. The root `Card` component also accepts a safe subset of flexbox/dimension props (`flex`, `flexGrow`, `flexShrink`, `flexBasis`, `grow`, `h`, `height`) so it can be sized properly alongside other elements in dynamic/flex layouts (such as dashboard panels, grid tracks, or sidebar layout segments). `Card.Content` grows to fill the available vertical space, keeping `Card.Footer` aligned to the bottom of the card.

package/src/components/Container/USAGE.md

@@ -45,4 +45,4 @@ All Recursica components in the `@recursica/mui-adapter` package adhere strictly
 
 ## `sx` Prop Exemption
 
-By design, the `Container` component explicitly allows the `sx` prop to pass through to the underlying MUI `Container`. Unlike standard UI kit components (which use the `RecursicaOverStyled` gatekeeper) or flex layout primitives (which strip `sx` via `OmitSx` and `filterSxProp`), `Container` acts as a structural boundary where advanced, one-off positioning adjustments may be required by the consuming application.
+By design, the `Container` component always allows the `sx` prop to pass through, without requiring `overStyled`. This makes it useful as a structural boundary where advanced, one-off positioning adjustments may be required by the consuming application.

package/src/components/Dropdown/BareDropdown.tsx

@@ -0,0 +1,135 @@
+import React, { forwardRef } from "react";
+import {
+  Select as MuiSelect,
+  type SelectProps as MuiSelectProps,
+  MenuItem,
+} from "@mui/material";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Dropdown.module.css";
+
+/**
+ * Bare, unwrapped Select — no `FormControlWrapper`/`WithReadOnlyWrapper`, no label/assistiveText/
+ * error/required. Tied to the same `Dropdown.module.css` variables/classes as the public
+ * `Dropdown` component, so it looks identical, but is meant to be embedded inside another
+ * component that already owns its own `FormControlWrapper` (e.g. `TimePicker`'s AM/PM control) —
+ * nesting the full `Dropdown` there would double up `FormControl`/`FormControlLayout` wrapping.
+ *
+ * Not exported from this folder's `index.ts` — internal use only. Import it directly:
+ * `import { BareDropdown } from "../Dropdown/BareDropdown"`.
+ */
+export interface BareDropdownProps
+  extends Omit<
+    MuiSelectProps,
+    "size" | "variant" | "classes" | "error" | "onChange"
+  > {
+  data: (
+    | string
+    | { value: string; label: React.ReactNode; disabled?: boolean }
+  )[];
+  /** Normalized to just the selected value, unlike MUI's raw (event, child) Select onChange. */
+  onChange?: (value: string | null) => void;
+  /** Applies the error visual state (via `data-error`) — no error message is rendered here. */
+  error?: boolean;
+}
+
+export type BareDropdownComponentProps = RecursicaOverStyled<BareDropdownProps>;
+
+export const BareDropdown = forwardRef<
+  HTMLInputElement,
+  BareDropdownComponentProps
+>(function BareDropdown(props, ref) {
+  const {
+    overStyled = false,
+    disabled,
+    data,
+    onChange,
+    className,
+    value,
+    defaultValue,
+    error,
+    ...rest
+  } = props;
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const restRecord = sanitizedProps as Record<string, unknown>;
+
+  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 mergedClassName = className
+    ? `${styles.root} ${className}`
+    : styles.root;
+
+  const selectedValue = value ?? defaultValue;
+
+  const renderOptions = () =>
+    data.map((item, index) => {
+      if (typeof item === "string") {
+        return (
+          <MenuItem
+            key={`${item}-${index}`}
+            value={item}
+            className={styles.option}
+            // Dropdown.module.css's own selected-state tint (`.option[data-selected="true"]`) needs
+            // this explicitly — MUI's own `Mui-selected` class carries its default primary-color
+            // tint instead, which is what shows through without it.
+            data-selected={item === selectedValue ? "true" : undefined}
+          >
+            {item}
+          </MenuItem>
+        );
+      }
+      return (
+        <MenuItem
+          key={`${item.value}-${index}`}
+          value={item.value}
+          disabled={item.disabled}
+          className={styles.option}
+          data-selected={item.value === selectedValue ? "true" : undefined}
+        >
+          {item.label}
+        </MenuItem>
+      );
+    });
+
+  return (
+    <MuiSelect
+      ref={ref}
+      disabled={disabled}
+      value={value}
+      defaultValue={defaultValue}
+      onChange={(event) => onChange?.((event.target.value as string) ?? null)}
+      displayEmpty
+      error={!!error}
+      className={mergedClassName}
+      classes={{
+        select: styles.input,
+        icon: styles.icon,
+      }}
+      MenuProps={{
+        classes: { paper: styles.dropdown },
+      }}
+      // Dropdown.module.css's error/disabled state rules key off `.root[data-error]`/
+      // `[data-disabled]` (the outer Select element, matching mergedClassName above) —
+      // `inputProps` only reaches the nested accessibility <input>, which that selector never
+      // matches, so these need to be set here too (mirrors the same fix in Dropdown.tsx).
+      data-disabled={disabled ? "true" : undefined}
+      data-error={error ? "true" : undefined}
+      inputProps={{
+        "data-disabled": disabled ? "true" : undefined,
+        "data-error": error ? "true" : undefined,
+        ...(restRecord.inputProps as Record<string, unknown>),
+      }}
+      {...(sanitizedProps as unknown as MuiSelectProps)}
+    >
+      {renderOptions()}
+    </MuiSelect>
+  );
+});
+
+BareDropdown.displayName = "BareDropdown";

package/src/components/Dropdown/Dropdown.tsx

@@ -98,6 +98,12 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
               key={`${item}-${index}`}
               value={item}
               className={styles.option}
+              // Dropdown.module.css's own selected-state tint (`.option[data-selected="true"]`)
+              // needs this explicitly — MUI's own `Mui-selected` class carries its default primary-
+              // color tint instead, which is what shows through without it.
+              data-selected={
+                item === (value ?? defaultValue) ? "true" : undefined
+              }
             >
               {item}
             </MenuItem>
@@ -109,6 +115,9 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
             value={item.value}
             disabled={item.disabled}
             className={styles.option}
+            data-selected={
+              item.value === (value ?? defaultValue) ? "true" : undefined
+            }
           >
             {item.label}
           </MenuItem>
@@ -164,6 +173,13 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
             MenuProps={{
               classes: { paper: styles.dropdown },
             }}
+            // Dropdown.module.css's error/disabled state rules key off `.root[data-error]`/
+            // `[data-disabled]` (the outer Select element, matching the `className={styles.root}`
+            // above) — `inputProps` below only reaches the nested accessibility <input>, which that
+            // selector never matches, so these need to be set here too. (Previously only set via
+            // inputProps, which meant the error border never actually appeared on the Dropdown.)
+            data-disabled={disabled ? "true" : undefined}
+            data-error={error ? "true" : undefined}
             inputProps={{
               "data-disabled": disabled ? "true" : undefined,
               "data-error": error ? "true" : undefined,

package/src/components/Grid/USAGE.md

@@ -36,7 +36,7 @@ All Recursica components in the `@recursica/mui-adapter` package adhere strictly
 
 > [!IMPORTANT]
 >
-> - **Anti-override protection**: `Grid` is a primitive layout component (see [OVERSTYLING.md](../../../OVERSTYLING.md)) and is exempt from the `RecursicaOverStyled` gatekeeper — only the `sx` prop is stripped, everything else passes through freely.
+> - **Anti-override protection**: `Grid` is a primitive layout component (see [OVERSTYLING.md](../../../OVERSTYLING.md)) — only the `sx` prop is stripped, everything else passes through freely without needing `overStyled`.
 > - **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**: Spacing is entirely determined by the `rec-*` token scale, mapped transparently to MUI's `spacing` value.
 
@@ -44,12 +44,8 @@ All Recursica components in the `@recursica/mui-adapter` package adhere strictly
 
 ## 4. Key Integration Features & Constraints
 
-`Grid` and `Grid.Col` expose the same public API as the mantine-adapter's `Grid`/`Grid.Col` (same prop names and shapes), so code written against one adapter ports to the other without changes. Internally, MUI has no native `AppShell`-style Grid/Col split — MUI merges "container" and "item" into a single `Grid` component — so this adapter hand-composes `Grid` (always `container`) and `Grid.Col` (always item mode) from that single underlying component.
-
-Notable mapping details:
-
-- `gap` maps to MUI's own `spacing` prop (same concept as `gutter` on the mantine side).
-- `span`'s `"auto"`/`"content"` keywords are the inverse of MUI's own `"grow"`/`"auto"` keywords — this adapter translates between them internally, so the public `span` values match Mantine's semantics exactly regardless of adapter.
-- `offset` maps directly to MUI's own `offset` prop (same name, same shape).
-- `order` is applied directly for a fixed number. A responsive object (`{ base, sm, md, ... }`) is **not** fully supported yet — the smallest specified breakpoint's value is applied as a single static order, since MUI's Grid has no native per-breakpoint `order` mechanism. See `IMPLEMENTATION_NOTES.md`.
-- `visibleFrom`/`hiddenFrom` are implemented via a small CSS module using MUI's own default breakpoint pixel values (600/900/1200/1536), since MUI's Grid has no built-in breakpoint-visibility mechanism.
+- `gap` controls the spacing between grid items.
+- `span` accepts a column count, `"auto"`, `"content"`, or a responsive object (`{ base, sm, md, ... }`).
+- `offset` shifts a column by a number of columns.
+- `order` accepts a fixed number to control a column's visual order. A responsive object (`{ base, sm, md, ... }`) is **not** fully supported yet — only the smallest specified breakpoint's value is applied.
+- `visibleFrom`/`hiddenFrom` show or hide a column at the standard breakpoints (600/900/1200/1536px).

package/src/components/Loader/USAGE.md

@@ -39,26 +39,4 @@ All Recursica components in the `@recursica/mui-adapter` package adhere strictly
 
 ## 4. Key Integration Features & Constraints
 
-## Architecture & Integration
-
-The `Loader` component for the MUI adapter has been completely hand-coded from scratch using pure CSS and basic HTML `<span>` elements. It explicitly **does not** use MUI's native `<CircularProgress>` component.
-
-This was a deliberate architectural decision to ensure 100% feature and visual parity with the `mantine-adapter`.
-
-### Key Decisions:
-
-- **Bypassing Native Components:** MUI's native loaders (like `<CircularProgress>`) are built using complex animated SVGs and only support a circular "oval" shape. Since the Recursica design system mandates `oval`, `bars`, and `dots` variants, relying on MUI's primitives would have forced a fragmented architecture where `oval` used MUI but `bars` and `dots` were hand-coded.
-- **Parity with Mantine:** To guarantee identical animation timing, easing curves, and DOM structures across frameworks, the CSS keyframes and layout strategies used internally by Mantine's `<Loader>` were extracted and directly replicated in this adapter's `Loader.module.css`.
-
-### Token Mapping:
-
-Sizes are bound through `data-size` attributes (`sm`, `md`, `lg` parsing to target `<div data-size="small">`, etc.).
-
-- **Oval Variant:** Uses a CSS spinning `::after` pseudo-element. To avoid CSS border inheritance bugs when computing tokenized border-widths, a custom `--loader-thickness` CSS variable is used to bridge the token into the spinning element.
-- **Bars & Dots Variants:** Render three internal `<span />` elements sequentially, styled via `Loader.module.css` to handle individual keyframe delays for bouncing or fading animations.
-
-### Color Contrast Rules:
-
-Loaders are hardcoded to map to their explicitly defined design tokens (e.g., `--recursica_ui-kit_components_loader_properties_indicator-color`). By default, they do **not** inherit `currentColor`.
-
-When injected into components like the `Button` (where contrast issues may arise against solid backgrounds), it is the responsibility of the parent component (e.g., `Button.module.css`) to use contextual CSS overrides to force `--loader-color: currentColor !important` if necessary.
+Loader colors are determined by their own design tokens by default and do not automatically inherit `currentColor` from a parent component, which can occasionally affect contrast when a loader is placed on a colored background.

package/src/components/Menu/USAGE.md

@@ -45,10 +45,3 @@ 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
-
-- **Compositional API Dropped:** Mantine uses `<Menu.Target>`, `<Menu.Dropdown>`, `<Menu.Item>`, etc., and manages state natively via React context within `<Menu>`. MUI's API is fully monolithic.
-- **Monolithic API Adopted:** Following architectural review, we have abandoned the fabricated context wrappers for `mui-adapter`. We now natively export `Menu`, `MenuItem`, and `MenuDivider` wrapping their `@mui/material` counterparts. Developers are expected to manage `anchorEl` state themselves, just like native MUI. Storybook tests have been updated to simulate this open state so visual regressions still cover the dropdown menu visually.

package/src/components/Pagination/USAGE.md

@@ -34,9 +34,3 @@ 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
-
-- **Compositional API Dropped:** Mantine's original `Pagination` component relies heavily on dot-notation sub-components (`Pagination.Root`, `Pagination.Items`, `Pagination.Control`, etc.). MUI's `<Pagination>` is fundamentally monolithic. Following architectural review, we have decided to drop the dot-notation wrappers for `mui-adapter` and rely strictly on MUI's monolithic API. Storybook and visual regression tests have been updated to reflect this divergence while retaining core property mapping compatibility.