@recursica/mui-adapter 0.24.0 → 0.26.0

package/llms.txt

@@ -52,6 +52,7 @@ Each component has its own `USAGE.md` documenting its props, adapter-specific be
 - [NumberInput](src/components/NumberInput/USAGE.md)
 - [Pagination](src/components/Pagination/USAGE.md)
 - [Panel](src/components/Panel/USAGE.md)
+- [Popover](src/components/Popover/USAGE.md)
 - [Radio](src/components/Radio/USAGE.md)
 - [ReadOnlyField](src/components/ReadOnlyField/USAGE.md)
 - [RecursicaThemeProvider](src/components/RecursicaThemeProvider/USAGE.md)

package/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/borderux/recursica.git",
     "directory": "packages/mui-adapter"
   },
-  "version": "0.24.0",
+  "version": "0.26.0",
   "publishConfig": {
     "access": "public"
   },

package/src/GlobalExemptions.modules.css

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

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

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

package/src/components/AssistiveElement/AssistiveElement.tsx

@@ -86,7 +86,7 @@ export const AssistiveElement = React.forwardRef<
           {assistiveVariant === "error" ? <ErrorIcon /> : <HelpIcon />}
         </div>
       )}
-      <div className={styles.text}>{children}</div>
+      <span className={styles.text}>{children}</span>
     </FormHelperText>
   );
 });

package/src/components/Autocomplete/Autocomplete.module.css

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

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

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

package/src/components/Button/BUTTON_IMPLEMENTATION_NOTES.md

@@ -53,3 +53,15 @@ We explicitly pass `disableRipple` and `disableElevation` to block MUI's dynamic
 **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.
+
+---
+
+## `line-height` wiring gap vs Mantine (Matt Massey, 2026-08-19)
+
+**Reported symptom:** descenders on letters like "p"/"g" clipped in the Default story.
+
+**Investigation:** live-verified both adapters in Storybook (Playwright) at the `Default` and `OutlineSmall` stories, including a direct canvas `measureText` check of the `gpqjy` glyph set in Lexend at 14px (`--recursica_tokens_font_line-heights_default: 1.05em` → 14.7px line box vs ~14.0px actual glyph ink) — no visible clipping reproduced in Chromium; both adapters rendered pixel-identical crops. The line-height token itself is objectively tight (near-zero headroom), but that's shared by both adapters and isn't itself mui-specific.
+
+**Real discrepancy found:** `.root`'s "Shared Defaults" set `line-height` once, unconditionally, from the _default_-size token, and `.labelText` merely did `line-height: inherit` — so the small-size line-height token was never actually referenced (it was `recursica-ignore`d as "redundant"). Mantine's `Button.module.css`, by contrast, sets `line-height` directly on `.labelText` per size, from each size's own token. They currently resolve to the same literal value, so this wasn't visually observable, but it's a latent divergence from the source of truth — a future token change to the small-size line-height would silently not apply in mui-adapter.
+
+**Fix:** moved `line-height` off `.root` and onto `.labelText` (default token), added `.root[data-size="small"] .labelText { line-height: ... }` (small token), and removed the now-inaccurate `recursica-ignore` for that token — matching Mantine's structure exactly.

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

@@ -24,9 +24,6 @@
   letter-spacing: var(
     --recursica_ui-kit_components_button_variants_sizes_default_properties_text_letter-spacing
   );
-  line-height: var(
-    --recursica_ui-kit_components_button_variants_sizes_default_properties_text_line-height
-  );
   text-decoration: var(
     --recursica_ui-kit_components_button_variants_sizes_default_properties_text_text-decoration
   );
@@ -64,7 +61,9 @@
   text-overflow: ellipsis;
   white-space: nowrap;
   font-size: inherit;
-  line-height: inherit;
+  line-height: var(
+    --recursica_ui-kit_components_button_variants_sizes_default_properties_text_line-height
+  );
 }
 /* Removed data-loading background override to rely on native disabled opacities like Mantine */
 
@@ -171,6 +170,9 @@
   max-width: var(
     --recursica_ui-kit_components_button_variants_sizes_small_properties_max-label-width
   );
+  line-height: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_text_line-height
+  );
 }
 
 /* Icon Resets */
@@ -376,17 +378,3 @@
       var(--recursica_brand_states_focus_margin)
       var(--recursica_brand_states_focus_color);
 }
-
-/* EXEMPTIONS:
-   These general button properties are redundant because visual mapping has been refactored
-   to content-specific variables (_content_label_sizes_... etc.) or are handled by design defaults. */
-/* recursica-ignore: --recursica_ui-kit_components_button_variants_sizes_default_properties_horizontal-padding */
-/* recursica-ignore: --recursica_ui-kit_components_button_variants_sizes_default_properties_min-width */
-/* recursica-ignore: --recursica_ui-kit_components_button_variants_sizes_small_properties_horizontal-padding */
-/* recursica-ignore: --recursica_ui-kit_components_button_variants_sizes_small_properties_hover-opacity */
-/* recursica-ignore: --recursica_ui-kit_components_button_variants_sizes_small_properties_min-width */
-/* recursica-ignore: --recursica_ui-kit_components_button_variants_sizes_small_properties_text_font-style */
-/* recursica-ignore: --recursica_ui-kit_components_button_variants_sizes_small_properties_text_letter-spacing */
-/* recursica-ignore: --recursica_ui-kit_components_button_variants_sizes_small_properties_text_line-height */
-/* recursica-ignore: --recursica_ui-kit_components_button_variants_sizes_small_properties_text_text-decoration */
-/* recursica-ignore: --recursica_ui-kit_components_button_variants_sizes_small_properties_text_text-transform */

package/src/components/Checkbox/Checkbox.tsx

@@ -92,7 +92,10 @@ export const Checkbox = forwardRef<HTMLButtonElement, CheckboxProps>(
       : styles.root;
 
     const groupContext = React.useContext(CheckboxGroupContext);
-    const isGrouped = groupContext !== null;
+    // A Checkbox with its own explicit `checked` prop owns its source of truth even when
+    // nested inside a CheckboxGroup used purely for layout (e.g. TransferList's ungrouped
+    // rows) — only defer to the group's value array when the caller hasn't already told us.
+    const isGrouped = groupContext !== null && restRecord.checked === undefined;
     const isGroupReadOnly = isGrouped ? groupContext.readOnly : false;
     const isChecked = isGrouped
       ? (groupContext.value || []).includes(restRecord.value)

package/src/components/Chip/Chip.module.css

@@ -1,30 +1,3 @@
-/* EXEMPTIONS:
-   - close-icon-color, leading-icon-color, and select-specific state icon variables are ignored because 
-     Chip uses explicit state color definitions (e.g. unselected, selected, error, error-selected variant colors) 
-     to drive pixel-perfect hover and click transitions, rather than generic single-color overrides.
-   - text-size is ignored since actual chip sizing is dynamically driven by precise vertical padding and line-heights. */
-/* recursica-ignore: --recursica_ui-kit_components_chip_properties_close-icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_chip_properties_leading-icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_chip_properties_text-size */
-/* recursica-ignore: --recursica_ui-kit_components_chip_variants_styles_error_properties_colors_leading-icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_chip_variants_styles_error_properties_colors_selected-icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_chip_variants_styles_error-selected_properties_colors_icon */
-/* recursica-ignore: --recursica_ui-kit_components_chip_variants_styles_error-selected_properties_colors_leading-icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_chip_variants_styles_selected_properties_colors_leading-icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_chip_variants_styles_unselected_properties_colors_selected-icon-color */
-
-/* Additional exemptions matching the reference mantine-adapter's Chip.module.css: per selection/error
-   state, Figma defines multiple icon-color slots (leading-icon-color, selected-icon-color, and for
-   error states also a generic icon-color), but each state only ever consumes ONE of them (leading
-   when unselected, selected when selected). The remaining "off" slots per state are intentionally
-   unused, same as in the mantine reference. */
-/* recursica-ignore: --recursica_ui-kit_components_chip_variants_selection-states_selected_properties_colors_leading-icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_chip_variants_selection-states_selected_variants_states_error_properties_colors_icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_chip_variants_selection-states_selected_variants_states_error_properties_colors_leading-icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_chip_variants_selection-states_unselected_properties_colors_selected-icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_chip_variants_selection-states_unselected_variants_states_error_properties_colors_icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_chip_variants_selection-states_unselected_variants_states_error_properties_colors_selected-icon-color */
-
 /* HARDCODED VALUES
    border-style: solid;  (Baseline reset)
    box-sizing: border-box; (Baseline reset)

package/src/components/DatePicker/DATEPICKER_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,29 @@
+# DatePicker Implementation Notes
+
+## Architecture Overview
+
+The `DatePicker` component is a wrapper around MUI X's `@mui/x-date-pickers` `DatePicker`, implementing the `FormControlWrapper` macro structure for Recursica. This ensures that the component visually and structurally aligns with standard Recursica input primitives, and mirrors the mantine-adapter's own `DatePicker` behavior and token mapping wherever the two libraries' APIs allow it.
+
+## Structural Constraints
+
+1. **Naked Field Usage**: We intentionally pass `label={undefined}`/`description`/`error` through `WithReadOnlyWrapper` rather than MUI X's own field label/helper-text props, so only our `WithReadOnlyWrapper` > `FormControlWrapper` orchestrates labels, description text, and ARIA state error boundaries — same convention as TimePicker.tsx.
+2. **Value Type**: MUI X's `DatePicker` only speaks `Dayjs` (via `AdapterDayjs`); the public API converts to/from plain `Date` internally so `value`/`defaultValue`/`onChange` match the mantine-adapter's convention exactly.
+3. **Read-Only Rendering**: The selected date is displayed formatted as `MM/DD/YY` (via `dayjs(...).format(...)`), not a raw `String(value)` cast (unlike the mantine-adapter, which has no reason to reach for `dayjs` outside read-only formatting). Pass `readOnlyComponent` to override.
+4. **Typing vs. Popover Entry**: Unlike the mantine-adapter (`DatePickerInput`, popover-only), MUI X's field natively supports typing directly into masked date segments in addition to the popup calendar — no adapter code needed to enable this, it's the library default.
+5. **Calendar Popover (Figma Token Issue)**: Same root cause as the mantine-adapter — the UI Kit's `date-picker` component exports no calendar-specific tokens (surface, selected day, hover, today, in-range) — so the calendar reuses the closest existing tokens, mapped 1:1 to the mantine-adapter's choices:
+   - **Surface** (`.dropdown`, applied to `slotProps.desktopPaper`) & **selected day** (`.MuiPickerDay-root.Mui-selected`): `--recursica_ui-kit_components_hover-card-popover` tokens for elevation/padding/surface, `--recursica_ui-kit_components_button_variants_styles_solid` tokens for the selected day fill.
+   - **Header content, weekday row** (`.MuiPickersCalendarHeader-root`, `.MuiDayCalendar-weekDayLabel`): the hover-card-popover content-color token.
+   - **Header nav controls** (`.MuiPickersArrowSwitcher-button`, `.MuiPickersCalendarHeader-switchViewButton`) **& month/year label** (`.MuiPickersCalendarHeader-label`): styled with `--recursica_ui-kit_components_button_variants_styles_text` tokens (border/background/color/elevation) plus small-size `Button` sizing tokens — the same tokens the mantine-adapter's `.calendarHeaderControl`/`.calendarHeaderLevel` use. Note the DOM shape differs from mantine: MUI splits the month/year control into a plain, non-interactive `.label` text node (`role="none"` on its `labelContainer` parent) plus a separate small `.switchViewButton` that's the actual clickable control — only the label's _color/typography_ is recolored to match (no border/background chrome on a non-interactive element), while the switchViewButton gets the full button treatment.
+   - **Hover** (day cells, header nav, header level button): the generic `--recursica_brand_states_hover_color`/`_hover_opacity` pair via the same `::after`-overlay technique the mantine-adapter and `Button`/`Menu` use — a plain `background-color`+`opacity` change on the element itself would dim its icon/text along with the fill, not just tint the surface.
+   - **Disabled / outside-month days** (`.Mui-disabled`, `.MuiPickerDay-dayOutsideMonth`): the generic `--recursica_brand_states_disabled` opacity token, same convention used repo-wide. Disabled header nav/label controls use `Button`'s own text-variant disabled opacity/elevation tokens instead.
+   - **Today marker** (`.MuiPickerDay-today`): reuses the hover-card-popover border-size/color tokens already used for the dropdown surface's own border — same reasoning as mantine-adapter (no dedicated "today" token exists). MUI ships its own default light-primary-color background tint on this class, which is explicitly reset to `transparent` since the design system has no equivalent.
+   - **Range selection / weekend styling**: not mapped. MUI X's default `DatePicker` doesn't render range selection or weekend-specific styling at all (unlike Mantine, which colors weekends red by default and needed an explicit override), so neither state needed a Recursica mapping.
+
+## Styling Quirks
+
+- **Native field decoration suppression**: MUI X's field variant can't be forced to a bare/unstyled mode from this component's public API (same constraint TimePicker.module.css documents) — whichever native outline/underline decoration it renders by default is suppressed via `:global(...)` overrides, and `.field` draws the Recursica border/background/color instead.
+- **Popover `slotProps` gotcha, same shape as mantine-adapter's `popoverProps` bug**: the calendar popup is portaled to `document.body`, entirely outside this component's own DOM subtree, so it can only be reached by handing MUI X's `slotProps.desktopPaper` a `className` directly — a descendant CSS selector from `.root` would never match it. `DatePicker.tsx` merges any consumer-supplied `slotProps.field`/`slotProps.desktopPaper` (and their `className`s) with our own defaults instead of overwriting them.
+- **`.dropdown`'s `!important`s**: unlike the mantine-adapter's equivalent rule (plain CSS-module specificity, no `!important` needed — `@mantine/dates`' own stylesheet reliably loads first), MUI X injects its own `Paper`/`Popper` styles at runtime via emotion, with no guaranteed load-order relative to this CSS module. `!important` here just re-asserts token values against a same-specificity emotion rule that could otherwise win on source order alone.
+- **Default display/entry format**: `format="MM/DD/YY"` (a `dayjs` format string, MUI X's own default is `"MM/DD/YYYY"`), matching the mantine-adapter's `valueFormat` default.
+- **Default leading icon**: the calendar icon is MUI X's own built-in "open picker" button (`slots.openPickerIcon`, positioned via `openPickerButtonPosition="start"` on the field slot) rather than a separate decorative `InputAdornment` — clicking it opens the calendar, unlike the mantine-adapter's purely decorative `leftSection` icon (there, the whole field is the click target). Overridable via `slots={{ openPickerIcon: MyIcon }}`, following the same override-prop convention as `leftSection` elsewhere in this adapter.
+- **No native `::placeholder`**: empty date segments ("MM", "DD", "YYYY") render via MUI X's own internal placeholder styling, not a native `::placeholder` pseudo-element — there's no selector to hook the `placeholder-opacity` token onto, same constraint TimePicker.module.css documents for its own empty sections.

package/src/components/DatePicker/DatePicker.icons.tsx

@@ -0,0 +1,35 @@
+import React from "react";
+
+/**
+ * Default calendar icon rendered in the field's open-picker button (start position, see
+ * DatePicker.tsx). Consumers can override it by passing their own `slots.openPickerIcon`.
+ * Rendered by MUI X as an `SvgIcon`-like component and handed `className`/`style` only — sized/
+ * colored entirely via the generic `.section :global(svg)` rule in DatePicker.module.css, same
+ * convention as the mantine-adapter's CalendarIcon.
+ */
+export function CalendarIcon({
+  className,
+  style,
+}: {
+  className?: string;
+  style?: React.CSSProperties;
+}) {
+  return (
+    <svg
+      className={className}
+      style={style}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden
+    >
+      <rect x="3" y="4" width="18" height="18" rx="2" ry="2" />
+      <line x1="16" y1="2" x2="16" y2="6" />
+      <line x1="8" y1="2" x2="8" y2="6" />
+      <line x1="3" y1="10" x2="21" y2="10" />
+    </svg>
+  );
+}