@recursica/mantine-adapter 0.36.1 → 0.38.1

package/package.json

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

package/src/components/Accordion/USAGE.md

@@ -46,45 +46,6 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ## 4. Key Integration Features & Constraints
 
-## 1. Hybrid Composition API (Smart Rendering Flow)
+### Composition Patterns
 
-**Decision:** We fundamentally maintain the exact library composition API structure (`<Accordion>`, `<Accordion.Item>`, `<Accordion.Control>`, `<Accordion.Panel>`) while actively supporting an auto-completing flattened prop schema matching the unified Recursica API (`title`, `leftIcon`, `divider`).
-**Implementation:** Avoid rigid raw parameter dumps. Mantine dynamically injects explicit `id` logic, keyboard ARIA mapping, and focus tracking correctly across `Control` to `Panel` DOM connections natively. By exposing the hierarchical mapping 1:1, Recursica safely adopts these capabilities. However, to strictly support Recursica's unified prop mapping interface:
-
-- **Auto-Construction:** If integrators natively pass `title` and/or `leftIcon` props into `<AccordionItem>`, the component structurally auto-generates the internal `AccordionControl` sub-wrappers mapping the text and SVG natively, whilst treating `children` implicitly as the Panel contents.
-- **Graceful Falldown:** If `title` is heavily omitted, the node immediately falls backward into raw Mantine composability expecting integrators mapped `<Accordion.Control>` entirely manually.
-
----
-
-## 2. Default Configuration Reset (`unstyled`)
-
-**Decision:** We strip Mantine's inner styles away completely from Accordion mappings by leveraging React's default `variant="unstyled"`.
-**Implementation:** In `Accordion.tsx`, `<MantineAccordion>` binds `variant="unstyled"`. This effectively deletes Mantine's precomputed padding, borders, and shadow mappings allowing our targeted `classNames` inside `Accordion.module.css` to become the exact source of foundational truth without "fighting" `!important` tags or unpredictable flex-layouts inherited globally.
-
----
-
-## 3. Strict SVG Icons Wrapper (`.iconLeftWrapper`)
-
-**Decision:** Identical logic enforced as seen within Buttons: SVG scales dynamically inside `.mantine-leftSection` based on SVGs internal definition boundaries potentially corrupting header gaps.
-**Implementation:** `AccordionControl` captures `<span className={styles.iconLeftWrapper} aria-hidden>` forcing `object-fit: contain` mapped exactly to the `properties_icon-left-size` Recursica dimension token forcing integrator SVG overrides inline perfectly.
-
----
-
-## 4. Transparent Global Hover Fixes
-
-**Decision:** We nullify internal Mantine button hover actions and exclusively utilize Recursica's hover structure natively.
-**Implementation:** We construct `.control::after` pseudo-objects dynamically pulling our `hover-color` & `hover-opacity` bindings. Mantine's native action sets `.control:hover { background-color: var(...) }` dynamically causing internal layer overlaps. We enforce `background-color: transparent` strictly overriding it, preserving our pseudo-overlay layer-cascade cleanly.
-
----
-
-## 5. Active Target Hooks (`[data-active]`)
-
-**Decision:** Collapsed and expanded state tracking requires separate background maps across `AccordionItem`.
-**Implementation:** Rather than syncing React `useState` hooks matching `Accordion.value`, we defer to Mantine's inherent DOM mapping: `.item[data-active]` implicitly triggers exactly when Mantine registers an expansion state swap changing values down dynamically on the element layer, perfectly binding to `--recursica_..._background-expanded`.
-
----
-
-## 6. Nullifying Isolated State Bounds (`open` boolean)
-
-**Decision:** We do not bind isolated `open={true}` state properties natively on individual `<AccordionItem>` configurations.
-**Implementation:** Recursica natively dictates an item-level `open` tracking mapping. However, internally mapping boolean flags structurally across specific tree nodes heavily corrupts Mantine's DOM layout algorithms mapping parent-driven transition listeners. Mantine forces all expanded-height logic to run symmetrically off the `<Accordion value="...">` string matching array to accurately bind ARIA transitions. We explicitly ignore isolated item `<AccordionItem open={...}>` booleans to shield the rendering sequence cleanly.
+`Accordion.Item` supports two ways of providing content: pass `title` (and optionally `leftIcon`) directly on `Accordion.Item` for a simple control/panel pair, with `children` treated as the panel content; or omit `title` and compose manually with `Accordion.Control` and `Accordion.Panel` for full control over the control's contents.

package/src/components/AutoComplete/USAGE.md

@@ -45,22 +45,6 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ## 4. Key Integration Features & Constraints
 
-## Form Control Wrapping
+### Known Limitation: Active Option Highlight
 
-The `AutoComplete` component is wrapped using the `WithReadOnlyWrapper` to seamlessly bridge standard `InputWrapperProps` attributes (like `label`, `error`, `assistiveText`) directly onto the macro Recursica `<FormControlWrapper>`.
-
-## CSS Layout Execution
-
-The baseline structure maps identical `HARDCODED VALUES` as standard text inputs (`border-width: 1px`, `display: flex`). The `.root` dynamically overrides the `--input-left-section-size` and `--input-right-section-size` to accurately allocate whitespace for prepended or appended icons natively matching the underlying UI token layout system securely.
-
-## Dropdown Styling
-
-The Mantine `<Autocomplete>` dropdown menu and options are styled strictly using native UI-Kit variables mapping border radii, shadows, and base colors (`.dropdown` and `.option`).
-
-## State Cascade Architecture
-
-Focus, errors, and disabled visual states are enforced explicitly via the outer `<FormControlWrapper>` boundary emitting context down structurally (`[data-error]`, `[data-disabled]`) and evaluated efficiently against scoped nested selectors natively inside `AutoComplete.module.css`.
-
-## Missing Active Option Color
-
-Currently, there is no explicit JSON token for the background color of an active/hovered option in the AutoComplete dropdown. We temporarily map `.option:hover` and `.option[data-combobox-active]` to the `--recursica_ui-kit_components_autocomplete_variants_states_focus_properties_colors_background` variable. Because this variable maps to the base field background, the highlight is currently invisible. This will be updated once the correct token is added to the UI kit.
+The background highlight for a hovered or active option in the dropdown is not currently visible. This will be addressed in a future update.

package/src/components/Avatar/USAGE.md

@@ -36,30 +36,3 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 > - **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
-
-## Architecture Decisions
-
-The `Avatar` component is an adapter over Mantine's `Avatar`. To ensure adherence to the `COMPONENT_GUIDE_WALKTHROUGH.md`:
-
-- We do not wrap `MantineAvatar` in any custom standard `div` elements, preserving DOM structure.
-- All styles strictly pull from explicit `--recursica_ui-kit_components_avatar_*` CSS tokens.
-
-## Structural Workarounds
-
-### Implicit `data-style`
-
-Mantine's Avatar implicitly renders an image, an icon, or a text node based on the properties passed (`src`, `var`, `children`).
-Recursica Tokens split Avatar styling distinctly across three separate categories: `image`, `icon`, and `text`.
-To correctly map these variables, our React component observes standard prop states and manually injects a `data-style="image|icon|text"` onto the root. The `Avatar.module.css` explicitly gates padding and generic sizing modifiers under these `data-style` attributes.
-
-### Flex Layout & Internal Spans
-
-Since Avatar children (icons or initials) require robust centering that might differ heavily across Recursica size mappings, all child content defaults to being wrapped in `span` elements (either `.textWrapper` or `.iconWrapper`). These spans enforce 100% height and flex formatting independent of the Mantine container constraints.
-
-### CSS Reset Hacks
-
-Noticeable `/* HARDCODE: ... */` hacks are deployed within `.root` to completely zero-out Mantine's `--avatar-bg` and internal variables statically since Recursica handles background-colors inherently via the CSS variants cascade.

package/src/components/Badge/USAGE.md

@@ -43,16 +43,13 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ## 4. Key Integration Features & Constraints
 
-## 1. Stripped Size Properties
+## 1. Sizing
 
-As logged in `COMPONENT_ISSUES.md`, there are currently no Figma variables mapped for different `size` variants (`small`, `default`, etc.). The component explicitly `Omit`s the Mantine `size` property from its signature to prevent integrators from attempting to drive sizes that do not exist in the tokens.
+Badge does not currently support a `size` prop; badges render at a single fixed size.
 
 ## 2. Intent-Based Variants
 
-Mantine supports multiple visual variants (`outline`, `filled`, `light`). However, the existing variable schema for `Badge` only defines "Styles" which act as intents (`alert`, `primary-color`, `success`, `warning`).
-
-- Default is arbitrarily mapped to `primary-color` as we lack a pure `neutral` schema right now.
-- `variant` mapped to underlying Mantine prop has been hardcoded to `filled`, since the Recursica coloring fully replaces the Mantine DOM.
+Badge exposes a `variant` prop with intent-based values (`alert`, `primary-color`, `success`, `warning`) rather than Mantine's `outline`/`filled`/`light` style options. The default variant is `primary-color`.
 
 ## 3. The `overStyled` Prop
 

package/src/components/Breadcrumb/USAGE.md

@@ -47,11 +47,7 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ## Missing Variants and Sizes
 
-The `Breadcrumb` currently does not establish any size (`xs`, `sm`, etc.) or variant variables in the underlying design tokens (`recursica_ui-kit.json`). Only basic structural definitions for `padding` and `item-gap` exist. Because of this, the `size` and `variant` properties have been explicitly omitted from the passed mantine props.
-
-## Gap Styling
-
-We attach `gap` to `.root` directly within `.module.css`. Mantine's inner `separator` divs can natively accept our CSS variables for structural layout.
+Breadcrumb does not currently support `size` or `variant` props.
 
 ## Composition and Separators
 

package/src/components/Button/Button.tsx

@@ -101,6 +101,11 @@ const _Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
   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"];
 
   const userLoaderProps = restRecord.loaderProps as
     | Record<string, unknown>

package/src/components/Button/IMPLEMENTATION_NOTES.md

@@ -59,3 +59,11 @@ Mantine's `.mantine-Button-label` flex centering breaks primitive truncation log
 **Decision:** When `loading={true}` is passed to the Button, the component explicitly forces `disabled={true}` natively on the underlying element.
 
 **Implementation:** This ensures that loading buttons automatically inherit the brand theme disabled opacities (via the `:disabled` CSS pseudo-class) rather than relying solely on Mantine's native `data-disabled` dataset logic, which may not trigger the strict visual fade required by the Recursica design system.
+
+---
+
+## `className` overwrite bug (Matt Massey, 2026-08-08)
+
+**Bug:** with `overStyled` and a custom `className` (surfaced by Tree embedding a `Button` for its expand chevron — see `Tree/IMPLEMENTATION_NOTES.md`), `finalClass` (`` `${styles.root} ${classNameProp}` ``) was set explicitly on `<MantineButton>`, but `{...sanitizedProps}` was spread _after_ it — and `sanitizedProps` still contained the original, unmodified `className` key, since it had only been _read_, never deleted. The later spread would silently overwrite `finalClass` with just the caller's own class. Same bug class as `Dropdown.tsx`/`BareDropdown.tsx` had.
+
+**Why it wasn't visible here:** `classNames={{root: mergedClassNames.root, ...}}` is a _separate_ Mantine prop from the plain `className` string, unaffected by the overwrite, and `mergedClassNames.root` always includes `styles.root` independently — so the root element kept its Recursica styling regardless of the bug. mui-adapter's equivalent `Button.tsx` has no such secondary path (`@mui/material` only has a plain `className`), so the identical mistake there was fully visible (chevron rendered in MUI's own default color). Fixed in both regardless, since this is a real latent bug independent of whether it happens to be masked today.

package/src/components/Button/USAGE.md

@@ -45,37 +45,19 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ## Icon size: Recursica defines it
 
-**Decision:** Icon size is **not** left to the developer. Recursica defines it via the design tokens; the Button enforces it so callers cannot pass an arbitrarily sized icon.
-
-**Implementation:**
-
-- When `icon` is provided, the Button wraps it in a single element with class `iconWrapper` before passing it to Mantine’s `leftSection`.
-- In `Button.module.css`, `.iconWrapper` has explicit `width` and `height` from the Recursica tokens mapping natively based on `data-size`.
-- The rule `.iconWrapper > *` sets `width: 100%`, `height: 100%`, and `object-fit: contain` so whatever the caller passes scales cleanly with the token constraints.
+Icon size is **not** left to the developer. Recursica defines it via the design tokens, so callers cannot pass an arbitrarily sized icon — whatever is passed in `icon` is scaled to fit the token-defined dimensions for the button's size.
 
 ---
 
-## Icon-only buttons: accessibility and width
-
-**Decision:** When the button has an icon and no visible label (icon-only), callers must provide an accessible name, and the button must not show extra space to the right of the icon.
-
-**Accessibility:** We document that icon-only buttons must pass `aria-label` (e.g. `aria-label="Submit"`). In development we log a console warning if `icon` is set, `children` is empty, and `aria-label` is missing.
+## Icon-only buttons: accessibility
 
-**Width:** Mantine’s layout natively applies structural section gaps. We detect icon-only and set a `data-icon-only` hook so that `Button.module.css` zeros out the sections spacing allowing the button to precisely hit `min-width` perfectly centered.
+When the button has an icon and no visible label (icon-only), callers must provide an accessible name via `aria-label` (e.g. `aria-label="Submit"`). In development, a console warning is logged if `icon` is set, `children` is empty, and `aria-label` is missing.
 
 ---
 
 ## Label truncation at max-width
 
-**Decision:** When the button hits its Recursica max-width (500px), the label truncates with an ellipsis instead of wrapping.
-
-**Implementation:**
-Mantine's `.mantine-Button-label` flex centering breaks primitive truncation logic. To combat this:
-
-- **`.root`** has `overflow: hidden`.
-- **`.root > *`** forces `min-width: 0`.
-- The structural children wrap into `<span className={styles.labelText}>`.
-- **`.labelText`** binds `overflow: hidden; text-overflow: ellipsis; white-space: nowrap;` creating flawless string cutoffs strictly at exact UI constraints.
+When the button hits its Recursica max-width (500px), the label truncates with an ellipsis instead of wrapping.
 
 ---
 
@@ -95,6 +77,4 @@ Mantine's `.mantine-Button-label` flex centering breaks primitive truncation log
 
 ## Loading state enforces disabled state
 
-**Decision:** When `loading={true}` is passed to the Button, the component explicitly forces `disabled={true}` natively on the underlying element.
-
-**Implementation:** This ensures that loading buttons automatically inherit the brand theme disabled opacities (via the `:disabled` CSS pseudo-class) rather than relying solely on Mantine's native `data-disabled` dataset logic, which may not trigger the strict visual fade required by the Recursica design system.
+When `loading={true}` is passed to the Button, it is also treated as disabled — the button cannot be interacted with while loading.

package/src/components/Card/USAGE.md

@@ -54,18 +54,10 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ## 4. Key Integration Features & Constraints
 
-## Architecture Overrides
+## Header & Footer Styling
 
-Because Mantine natively constructs `Card` bounding boxes with generic inner `<Card.Section>` elements that depend on explicit user styling (and lack implicit native designations for "Header" vs "Footer"), we implemented an explicit component wrapper departure:
+`Card.Header` and `Card.Footer` automatically receive their background color and padding from the design system; no manual styling is needed.
 
-- `<Card.Header>` explicitly hooks `--recursica_ui-kit_components_card_properties_header-background` and corresponding padding variables.
-- `<Card.Footer>` explicitly hooks `--recursica_ui-kit_components_card_properties_footer-background` and corresponding padding variables.
+## Layout Alignment
 
-Mantine's generic `<Card.Section>` calculates negative margins implicitly. Because of this, it is crucial that our local CSS module declares `--card-padding: var(--recursica_ui-kit_components_card_properties_padding)` directly on `.root` so that all generic or explicit section wrappers natively stretch across the bounding box properly.
-
-## 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` accepts a safe subset of flexbox/sizing props (`flex`, `flexGrow`, `flexShrink`, `flexBasis`, `grow`, `h`, `height`) so it can participate cleanly in flex or grid layouts (dashboard panels, grid tracks, sidebar segments, etc.). `Card.Content` grows to fill available vertical space, which keeps `Card.Footer` pinned to the bottom of the card.

package/src/components/Checkbox/USAGE.md

@@ -39,26 +39,10 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ## 4. Key Integration Features & Constraints
 
-## Architectural Philosophy
+### Checkbox Alignment with Multi-line Labels
 
-The `Checkbox` primitive requires aggressive structural modifications to decouple Mantine's built-in arrays (`<Checkbox.Group>`) tying the raw DOM nodes seamlessly back into Recursica's unified form definitions flawlessly.
+Checkbox visually aligns to the first line of a wrapping, multi-line label.
 
-### Checkbox Alignment Anchoring (gap overflow hack)
+### Checkbox.Group
 
-By default, placing a Checkbox alongside a deeply wrapping multi-line label causes native geometric drifts natively. Because Mantine aligns the Checkbox graphic to the top of standard `display: flex` boxes, its optical center will appear natively skewed slightly _too high_ against the very first typographic text-line.
-
-We mathematically fix this alignment within `Checkbox.module.css` using explicit design variable arithmetic natively.
-\`\`\`css
-margin-top: calc(
-(
-var(--recursica_ui-kit_components_checkbox-item_properties_text_line-height) \*
-var(--recursica_ui-kit_components_checkbox-item_properties_text_font-size) -
-var(--recursica_ui-kit_components_checkbox_properties_size)
-) / 2
-) !important;
-\`\`\`
-This calculation ensures that the optical center of the `.inner` checkmark vector perfectly snaps onto the relative center of the text's line-height, permanently solving pixel-drifts natively!
-
-### Checkbox.Group Overrides
-
-To decouple `<CheckboxGroup>` away from `<Input.Wrapper>`, we explicitly extract the raw array execution mapped correctly against our identical `RecursicaFormControlWrapperProps` schema structurally!
+`Checkbox.Group` integrates with the same label, description, and error props as other Recursica form components.

package/src/components/Chip/USAGE.md

@@ -39,39 +39,10 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ## 4. Key Integration Features & Constraints
 
-## Architecture decisions
-
-### Mantine DOM Structure & Label Overrides
-
-Mantine's `<Chip>` behaves like an input element (`radio` or `checkbox`). Under the hood, it renders:
-
-1. `.mantine-Chip-root` (wrapper)
-2. `input` (hidden visual structure)
-3. `.mantine-Chip-label` (The actual visible button-like pill)
-
-Because the `.label` is the primary visual surface and handles Mantine's built-in `:hover` and active states, we direct our Recursica styling natively to `.label`.
-
-### Icon and Remove Implementations
-
-To achieve this without breaking Mantine's `Chip` input architecture, we wrapped the internal `children` using a standard `span` DOM strategy:
-
-```tsx
-<span className={styles.innerWrapper}>
-  {icon}
-  <span className={styles.children}>{children}</span>
-  {onRemove}
-</span>
-```
-
-#### Intermediate Children Wrapper Span display fix:
-
-Mantine internally wraps the children passed to `Chip` in a default `<span>` which has `display: inline`. This intermediate `span` inherits the `line-height` of the `.label` container, causing the computed height of the Chip to be ~2px taller than expected. To address this, `.label > span:not(.mantineIconWrapper)` is targeted to force `display: inline-flex; align-items: center;` on that intermediate wrapper `span`, allowing it to collapse perfectly to the `16px` height of the `innerWrapper`.
-
 ### Accessibility of Remove Action
 
-Because the Chip fundamentally functions as a `<label>` linked to an `<input>`, placing a raw interactive element like `<button>` directly inside the standard Chip sub-tree violates nested interactive element ARIA constraints in strict validators.
-To accommodate this, the visual "close" icon uses a `<span>` element configured with `role="button"` and `tabIndex={0}` to hook into standard keyboard activations without triggering generic nested `<form>` conflicts native to Mantine's baseline constraints.
+The remove/close action is keyboard accessible — it can be activated via keyboard as well as mouse click.
 
-### Removing Sizing Properties
+### Sizing
 
-During implementation, the parsed Figma design tokens natively exported specific height/padding vectors dynamically (e.g., `--recursica_ui-kit_components_chip_properties_icon-size`) rather than explicit string variants (`sm`, `md`, `lg`). Therefore, we omitted `size` conceptually from the `RecursicaChipProps` wrapper to lock down size evaluation natively against the active layer variables.
+Chip does not support a `size` prop; chips render at a fixed size.

package/src/components/DatePicker/USAGE.md

@@ -39,17 +39,7 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ## 4. Key Integration Features & Constraints
 
-## Architecture Overview
-
-The `DatePicker` component is a wrapper around the `@mantine/dates` `DatePickerInput` component, implementing the `FormControlWrapper` macro structure for Recursica. This ensures that the component visually and structurally aligns with standard Recursica input primitives.
-
 ## Structural Constraints
 
-1. **Naked Input Usage**: We intentionally pass `label={undefined}`, `description={undefined}`, and `error={undefined}` to the Mantine `DatePickerInput` component. This suppresses Mantine's internal macro form wrapping and ensures that only our `WithReadOnlyWrapper` > `FormControlWrapper` orchestrates labels, description text, and ARIA state error boundaries.
-2. **Read-Only Implementation**: Since the value type for `DatePickerInput` can be a date object, string, or array, the `WithReadOnlyWrapper` attempts to safely cast the output value using standard `String(value)`. For production apps utilizing heavy date formatting logic, developers can pass a custom `readOnlyComponent` explicitly to bypass this default cast.
-3. **Calendar Portal/Dropdown (Figma Token Issue)**: The Recursica UI Kit's `date-picker` component in Figma fails to export any explicit structural or color properties for the calendar popover itself (e.g. elevation, surface background, selected day colors). To solve this organically within the framework without breaking strict token adherence, we manually override the Mantine `.dropdown` and `.day[data-selected]` classes using `--recursica_ui-kit_components_hover-card-popover` tokens for elevation/padding/surfaces, and `--recursica_ui-kit_components_button_variants_styles_solid` tokens for the selected primary blue day. This guarantees strict visual adherence to the system until explicitly mapped tokens are provided in the UI Kit.
-
-## Styling Quirks
-
-- The `DatePickerInput` mimics Mantine's `Input` structure natively (`.input`, `.wrapper`, `.section`). We attach our `styles.input` and `styles.root` classes exactly like `TextField`.
-- The global layout margin override (`.layoutOverride`) utilizes `--form-control-margin-bottom` driven by specific stacked/side-by-side design tokens.
+1. **Read-Only Rendering**: When rendered in read-only mode, the selected date is displayed via a plain string conversion of the value. If you need custom date formatting, pass a `readOnlyComponent` prop to control how the value is rendered.
+2. **Calendar Popover Styling**: The calendar popover is not yet fully styled by design tokens.

package/src/components/Dropdown/BareDropdown.tsx

@@ -0,0 +1,85 @@
+import { forwardRef } from "react";
+import {
+  Select as MantineSelect,
+  type SelectProps as MantineSelectProps,
+} from "@mantine/core";
+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<
+    MantineSelectProps,
+    | "size"
+    | "variant"
+    | "radius"
+    | "wrapperProps"
+    | "label"
+    | "description"
+    | "error"
+  > {
+  data: MantineSelectProps["data"];
+  /** 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, className, disabled, error, ...rest } = props;
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const restRecord = sanitizedProps as Record<string, unknown>;
+
+  delete restRecord["size"];
+  delete restRecord["variant"];
+  delete restRecord["radius"];
+
+  const mergedClassNames: Partial<Record<string, string>> = {
+    wrapper: className ? `${styles.root} ${className}` : styles.root,
+    input: styles.input,
+    section: styles.section,
+    dropdown: styles.dropdown,
+    option: styles.option,
+  };
+
+  return (
+    <MantineSelect
+      ref={ref}
+      classNames={mergedClassNames}
+      disabled={disabled}
+      label={undefined}
+      description={undefined}
+      error={undefined}
+      // `wrapperProps` targets Mantine's *outer* `Input.Wrapper` (the label/description/error
+      // stacking element) — a different, ancestor element from the "wrapper" styles-api slot that
+      // actually carries `styles.root`'s border/background. Dropdown.module.css's error/disabled
+      // rules (`.root[data-error]`/`[data-disabled]`) need the attribute on that inner element, so
+      // `attributes.wrapper` (which targets the same slot as `classNames.wrapper`/`styles.wrapper`)
+      // is the correct hook here, not `wrapperProps`. See TIMEPICKER_IMPLEMENTATION_NOTES.md.
+      attributes={{
+        wrapper: {
+          "data-disabled": disabled ? "true" : undefined,
+          "data-error": error ? "true" : undefined,
+        },
+      }}
+      {...(sanitizedProps as unknown as MantineSelectProps)}
+    />
+  );
+});
+
+BareDropdown.displayName = "BareDropdown";

package/src/components/Dropdown/Dropdown.tsx

@@ -156,9 +156,18 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
             error={undefined}
             required={undefined}
             withAsterisk={undefined}
-            wrapperProps={{
-              "data-disabled": disabled ? "true" : undefined,
-              "data-error": error ? "true" : undefined,
+            // `wrapperProps` targets Mantine's *outer* `Input.Wrapper` (the label/description/error
+            // stacking element) — a different, ancestor element from the "wrapper" styles-api slot
+            // that actually carries `styles.root`'s border/background. Dropdown.module.css's error/
+            // disabled rules (`.root[data-error]`/`[data-disabled]`) need the attribute on that
+            // inner element, so `attributes.wrapper` (which targets the same slot as
+            // `classNames.wrapper`) is the correct hook — `wrapperProps` here meant the error state
+            // never actually applied a border color.
+            attributes={{
+              wrapper: {
+                "data-disabled": disabled ? "true" : undefined,
+                "data-error": error ? "true" : undefined,
+              },
             }}
             {...(sanitizedProps as unknown as MantineSelectProps)}
           />

package/src/components/Dropdown/USAGE.md

@@ -42,10 +42,6 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ---
 
-## 4. Key Integration Features & Constraints
+## 4. Notes
 
-The `Dropdown` component is mapped explicitly to Mantine's `<Select>` following the exact same strict encapsulation rules as `TextField`.
-
-1. **Naked Primitive Mapping:** Mantine's `Select` natively executes macro-label generation. To decouple it, we explicitly disable internal labels (`label={undefined}`) and inject it purely inside our generic `FormControlWrapper`.
-2. **Strict Dropdown Design Tokens:** The adapter implements strictly sandboxed styling utilizing only `--recursica_ui-kit_components_dropdown_...` variables. It explicitly does NOT inherit general `text-field` tokens despite geometric similarities, ensuring dropdown menus can be themed independently.
-3. **Dropdown Appendages:** To correctly map Mantine's detached Popover `.dropdown` and list `.option` items, we targeted focus and geometric bindings appending standard padding structures matched to the dropdown height overrides dynamically into our `Dropdown.module.css`.
+- `Dropdown` is styled independently from `TextField`; even though they look similar, they are themed using separate design tokens.

package/src/components/Flex/USAGE.md

@@ -45,4 +45,4 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 ## 4. Key Integration Features & Constraints
 
 The `Flex` component is a generic unopinionated flex layout wrapper mapped directly to Mantine's `Flex`.
-It currently does not require any custom logical layouts or CSS workarounds since it serves only to provide absolute, raw manipulation of standard CSS flex properties. All spacing props (gap, align, justify, direction, wrap) pass safely through via the `filterStylingProps` layout-property allowance, with `rec-` dimension tokens scaling transparently mapped to standard gap limits.
+All spacing props (`gap`, `align`, `justify`, `direction`, `wrap`) pass through as normal, with `rec-` dimension tokens mapped transparently to standard gap values.

package/src/components/FormControlWrapper/USAGE.md

@@ -41,35 +41,7 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ---
 
-## 4. Key Integration Features & Constraints
+## 4. Notes
 
-## Architectural Philosophy
-
-The `FormControlWrapper` is the ultimate structural replacement for Mantine's built-in `Input.Wrapper`. By abandoning Mantine's opinionated wrappers entirely across the design system, we centralize all label tracking, error rendering, ARIA generation, and grid layouts natively inside this single component.
-
-### 1. Bypassing `Input.Wrapper`
-
-Under the hood of Mantine, elements like `TextInput` heavily rely on `Input.Wrapper`. We actively discourage their use. The central tenet of Recursica Forms is to strip the UI primitive back to its "naked" form (e.g. `<Input />`, `<Checkbox />`) and encapsulate it manually inside `<FormControlWrapper>`.
-
-- **Why?** It enforces complete layout mastery. It natively enables `formLayout="side-by-side"` and completely disables Mantine's margin collisions without requiring messy CSS hacks.
-
-### 2. The `cloneElement` ARIA Map
-
-Because we tore out Mantine's `InputContext` provider (which natively glued error strings to `<input>` tags using React Context), we explicitly utilize `React.cloneElement` on the nested children inside this wrapper.
-
-- `aria-describedby` and `aria-errormessage` are dynamically generated using `React.useId()` and physically injected back onto the provided child node. Screen readers rely strictly on this mapping to announce the assistive fields correctly.
-
-### 3. Strict `AssistiveElement` Coupling
-
-We completely abandoned generic `<Input.Description>` tags. The `FormControlWrapper` directly renders `<AssistiveElement>` primitives, parsing them seamlessly mapping them to `"error"` or `"help"` variants automatically depending on the component's internal state machine.
-
-### 4. Dynamic Geometric Variable Payloads
-
-Because `FormControlWrapper` acts as an agnostic grid box encompassing raw primitives (like `TextField`, `Select`), it initially stretches `100%` across horizontal bounds.
-
-- **The Bug:** If a child `TextField` carries its own hardcoded `max-width` token, it stops expanding early, but the wrapper and `<Label>` keep expanding, causing right-aligned labels to aggressively float past the field to the screen's edge dynamically.
-- **The Variable Payload Resolution:** Instead of destroying grids with `width: fit-content` arrays, primitive components are required to pass their local `max-width` tokens UP to the wrapper explicitly via React `style`:
-  ```tsx
-  <FormControlWrapper style={{ "--form-control-max-width": "var(--...)" }}>
-  ```
-  The wrapper natively respects `max-width: var(--form-control-max-width, 100%)`. This structurally unifies the bounding caps so right-aligned labels flawlessly snap tightly to the explicit boundary edge of the specific primitive it is wrapping.
+- `FormControlWrapper` renders the label, error, and help text around the child input; screen-reader associations between the input and its assistive text are handled automatically.
+- The wrapper stretches to fill its container by default. If the wrapped input has its own maximum width, pass a matching `--form-control-max-width` CSS variable via the `style` prop so the label and assistive text align to the same width as the input.

package/src/components/Grid/USAGE.md

@@ -36,7 +36,7 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 > [!IMPORTANT]
 >
-> - **Anti-override protection**: `Grid` is a primitive layout component (see [OVERSTYLING.md](../../../OVERSTYLING.md)) and is exempt from the `RecursicaOverStyled` gatekeeper, so standard Mantine layout props pass through freely.
+> - **Anti-override protection**: `Grid` is a primitive layout component (see [OVERSTYLING.md](../../../OVERSTYLING.md)), so standard Mantine layout props pass 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 standard Mantine gutter values.
 

package/src/components/Group/USAGE.md

@@ -45,4 +45,4 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 ## 4. Key Integration Features & Constraints
 
 The `Group` component is a generic flex layout wrapper mapped directly to Mantine's `Group`.
-It currently does not require any custom logical layouts or CSS workarounds since it serves only to organize layout structure, and doesn't enforce any strict design-system token styling itself. All gap, align, wrap, and justify properties pass safely through via the `filterStylingProps` layout-property allowance.
+`gap`, `align`, `wrap`, and `justify` all pass through as normal.