@recursica/mantine-adapter 0.11.0 → 0.13.0

package/src/components/Button/Button.tsx

@@ -2,6 +2,7 @@ import React, { forwardRef } from "react";
 import {
   Button as MantineButton,
   type ButtonProps as MantineButtonProps,
+  createPolymorphicComponent,
 } from "@mantine/core";
 import {
   filterStylingProps,
@@ -26,97 +27,108 @@ function hasVisibleChildren(children: React.ReactNode): boolean {
   return true;
 }
 
-export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
-  function Button(
-    {
-      variant = "solid",
-      size = "default",
-      icon,
-      children,
-      overStyled = false,
-      ...rest
-    },
-    ref,
-  ) {
-    const mapVariant = {
-      solid: "filled",
-      outline: "outline",
-      text: "subtle",
-    } as const;
+const _Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
+  {
+    variant = "solid",
+    size = "default",
+    icon,
+    children,
+    overStyled = false,
+    ...rest
+  },
+  ref,
+) {
+  const mapVariant = {
+    solid: "filled",
+    outline: "outline",
+    text: "subtle",
+  } as const;
 
-    const mapSize = {
-      default: "md",
-      small: "sm",
-    } as const;
+  const mapSize = {
+    default: "md",
+    small: "sm",
+  } as const;
 
-    const sanitizedProps = filterStylingProps(rest, overStyled);
-    const restRecord = sanitizedProps as Record<string, unknown>;
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const restRecord = sanitizedProps as Record<string, unknown>;
 
-    // Explicitly delete blocked semantic expansion dimension props
-    delete restRecord["fullWidth"];
+  // Explicitly delete blocked semantic expansion dimension props
+  delete restRecord["fullWidth"];
 
-    const hasLeftSection = !!icon || !!restRecord["leftSection"];
-    const hasRightSection = !!restRecord["rightSection"];
-    const isIconOnly =
-      (hasLeftSection || hasRightSection) && !hasVisibleChildren(children);
+  const hasLeftSection = !!icon || !!restRecord["leftSection"];
+  const hasRightSection = !!restRecord["rightSection"];
+  const isIconOnly =
+    (hasLeftSection || hasRightSection) && !hasVisibleChildren(children);
 
-    if (
-      typeof process !== "undefined" &&
-      process.env.NODE_ENV !== "production" &&
-      isIconOnly &&
-      !restRecord["aria-label"]
-    ) {
-      console.warn(
-        '[Recursica Button] Icon-only buttons must provide an accessible name. Pass aria-label (e.g. aria-label="Submit").',
-      );
-    }
+  if (
+    typeof process !== "undefined" &&
+    process.env.NODE_ENV !== "production" &&
+    isIconOnly &&
+    !restRecord["aria-label"]
+  ) {
+    console.warn(
+      '[Recursica Button] Icon-only buttons must provide an accessible name. Pass aria-label (e.g. aria-label="Submit").',
+    );
+  }
 
-    const mergedClassNames: Partial<Record<string, string>> = {
-      root: styles.root,
-      section: styles.section,
-      label: styles.label,
-    };
+  const mergedClassNames: Partial<Record<string, string>> = {
+    root: styles.root,
+    section: styles.section,
+    label: styles.label,
+  };
 
-    const classNamesProp = restRecord.classNames;
-    if (
-      classNamesProp &&
-      typeof classNamesProp === "object" &&
-      !Array.isArray(classNamesProp)
-    ) {
-      const o = classNamesProp as Partial<Record<string, string>>;
-      mergedClassNames.root = o.root ? `${styles.root} ${o.root}` : styles.root;
-      mergedClassNames.section = o.section ?? styles.section;
-      mergedClassNames.label = o.label ?? styles.label;
-    }
+  const classNamesProp = restRecord.classNames;
+  if (
+    classNamesProp &&
+    typeof classNamesProp === "object" &&
+    !Array.isArray(classNamesProp)
+  ) {
+    const o = classNamesProp as Partial<Record<string, string>>;
+    mergedClassNames.root = o.root ? `${styles.root} ${o.root}` : styles.root;
+    mergedClassNames.section = o.section ?? styles.section;
+    mergedClassNames.label = o.label ?? styles.label;
+  }
 
-    const classNameProp = restRecord.className as string | undefined;
-    const finalClass = classNameProp
-      ? `${styles.root} ${classNameProp}`
-      : styles.root;
+  const classNameProp = restRecord.className as string | undefined;
+  const finalClass = classNameProp
+    ? `${styles.root} ${classNameProp}`
+    : styles.root;
 
-    return (
-      <MantineButton
-        ref={ref}
-        className={finalClass}
-        classNames={mergedClassNames}
-        variant={mapVariant[variant]}
-        size={mapSize[size]}
-        leftSection={
-          icon != null ? (
-            <span className={styles.iconWrapper} aria-hidden>
-              {icon}
-            </span>
-          ) : undefined
-        }
-        data-variant={variant}
-        data-size={size}
-        {...(isIconOnly ? { "data-icon-only": "" } : {})}
-        {...sanitizedProps}
-      >
-        <span className={styles.labelText}>{children}</span>
-      </MantineButton>
-    );
-  },
-);
+  return (
+    <MantineButton
+      ref={ref}
+      className={finalClass}
+      classNames={mergedClassNames}
+      variant={mapVariant[variant]}
+      size={mapSize[size]}
+      leftSection={
+        icon != null ? (
+          <span className={styles.iconWrapper} aria-hidden>
+            {icon}
+          </span>
+        ) : undefined
+      }
+      data-variant={variant}
+      data-size={size}
+      {...(isIconOnly ? { "data-icon-only": "" } : {})}
+      {...sanitizedProps}
+    >
+      <span className={styles.labelText}>{children}</span>
+    </MantineButton>
+  );
+});
+_Button.displayName = "Button";
 
-Button.displayName = "Button";
+/**
+ * Recursica Button component wrapping Mantine's Button.
+ *
+ * Supports polymorphism via the `component` prop or `renderRoot` for custom element rendering.
+ * @example
+ * ```tsx
+ * <Button component="a" href="/dashboard">Navigate</Button>
+ * <Button renderRoot={(props) => <Link to="/home" {...props} />}>Home</Button>
+ * ```
+ */
+export const Button = createPolymorphicComponent<"button", ButtonProps>(
+  _Button,
+);

package/src/components/Card/Card.tsx

@@ -3,6 +3,7 @@ import {
   Card as MantineCard,
   type CardProps as MantineCardProps,
   type CardSectionProps as MantineCardSectionProps,
+  createPolymorphicComponent,
 } from "@mantine/core";
 import {
   filterStylingProps,
@@ -162,15 +163,34 @@ export const CardContent = forwardRef<HTMLDivElement, CardContentProps>(
 CardContent.displayName = "CardContent";
 
 // ==== DOT NOTATION EXPORT ====
-type CardComponent = typeof CardBase & {
+
+/**
+ * Recursica Card component wrapping Mantine's Card (Paper).
+ *
+ * Supports polymorphism via the `component` prop or `renderRoot` for custom element rendering.
+ * Use dot-notation sub-components for structured card layouts.
+ */
+const PolymorphicCard = createPolymorphicComponent<
+  "div",
+  CardProps,
+  {
+    Section: typeof CardSection;
+    Header: typeof CardHeader;
+    Footer: typeof CardFooter;
+    Content: typeof CardContent;
+  }
+>(CardBase);
+
+// Attach static components for dot-notation access
+const _card = PolymorphicCard as Record<string, unknown>;
+_card.Section = CardSection;
+_card.Header = CardHeader;
+_card.Footer = CardFooter;
+_card.Content = CardContent;
+
+export const Card = PolymorphicCard as typeof PolymorphicCard & {
   Section: typeof CardSection;
   Header: typeof CardHeader;
   Footer: typeof CardFooter;
   Content: typeof CardContent;
 };
-
-export const Card = CardBase as CardComponent;
-Card.Section = CardSection;
-Card.Header = CardHeader;
-Card.Footer = CardFooter;
-Card.Content = CardContent;

package/src/components/Flex/Flex.tsx

@@ -2,6 +2,7 @@ import React, { forwardRef } from "react";
 import {
   Flex as MantineFlex,
   type FlexProps as MantineFlexProps,
+  createPolymorphicComponent,
 } from "@mantine/core";
 import {
   filterStylingProps,
@@ -27,7 +28,7 @@ export type FlexProps = RecursicaOverStyled<
   MantineFlexProps & RecursicaFlexProps
 >;
 
-export const Flex = forwardRef<HTMLDivElement, FlexProps>(function Flex(
+const _Flex = forwardRef<HTMLDivElement, FlexProps>(function Flex(
   { children, overStyled = false, gap = "rec-default", ...rest },
   ref,
 ) {
@@ -64,5 +65,16 @@ export const Flex = forwardRef<HTMLDivElement, FlexProps>(function Flex(
     </MantineFlex>
   );
 });
+_Flex.displayName = "Flex";
 
-Flex.displayName = "Flex";
+/**
+ * Recursica Flex layout wrapper.
+ *
+ * Supports polymorphism via the `component` prop or `renderRoot` for custom element rendering.
+ * @example
+ * ```tsx
+ * <Flex component="nav">...</Flex>
+ * <Flex component="section">...</Flex>
+ * ```
+ */
+export const Flex = createPolymorphicComponent<"div", FlexProps>(_Flex);

package/src/components/Menu/MENU_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,78 @@
+# Menu – Implementation Notes
+
+Decisions and design tweaks strictly tailored for the UI Kit's Menu wrapped against `@mantine/core`. This is a living document that tracks _why_ specific logic decisions exist.
+
+---
+
+## 1. Composable API Preservation (1:1 Mapping)
+
+**Decision:** We maintain the exact library composition API structure (`<Menu>`, `<Menu.Target>`, `<Menu.Dropdown>`, `<Menu.Item>`, `<Menu.Divider>`, `<Menu.Label>`, `<Menu.Sub>`, `<Menu.Sub.Target>`, `<Menu.Sub.Item>`, `<Menu.Sub.Dropdown>`) as a 1:1 React component mapping.
+
+**Implementation:** Mantine's Menu internally manages WAI-ARIA role assignments (`role="menu"`, `role="menuitem"`, `aria-haspopup`, `aria-expanded`, `aria-controls`), keyboard navigation (arrow keys, Enter, Escape), and focus trapping natively across its composable hierarchy. By preserving the exact sub-component tree, Recursica safely adopts all of these accessibility behaviors without reimplementation.
+
+---
+
+## 2. Hover State Overlay Technique
+
+**Decision:** We nullify Mantine's native hover background on `Menu.Item` and exclusively utilize Recursica's hover structure via a `::after` pseudo-element overlay.
+
+**Implementation:** The `.item::after` pseudo-object dynamically pulls `hover-color` & `hover-opacity` bindings from the Recursica token system. Mantine natively changes `background-color` on item hover which would override our token-driven colors. We enforce `background-color` to remain the unselected-item background on hover, then layer our pseudo-overlay on top. This is the same technique used in the Accordion component.
+
+---
+
+## 3. Selected vs Unselected Item States
+
+**Decision:** Menu items map to Recursica's `selected-item` and `unselected-item` color token groups.
+
+**Implementation:** The CSS module defaults all items to `unselected-item_*` tokens (background, text, opacity). Items with `[data-selected]` switch to `selected-item_*` tokens. This mapping is natively driven by Mantine's internal state tracking without React state hooks.
+
+---
+
+## 4. `color` Prop Stripping
+
+**Decision:** Mantine's `color` prop on `Menu.Item` (used for semantics like "danger/red") is explicitly stripped in strict mode.
+
+**Implementation:** The `color` prop is deleted from the sanitized props when `overStyled` is `false`. This enforces strict design token adherence — all item colors come from the CSS module referencing Recursica variables. Developers requiring custom color semantics must either:
+
+1. Use `overStyled={true}` as an explicit escape hatch
+2. Contribute a proper Recursica variant to the token system
+
+**Rationale:** The Recursica token set does not currently include danger-specific or semantic-color variants for menu items. Allowing arbitrary `color` values would break design system consistency.
+
+---
+
+## 5. Menu.Target Pass-Through
+
+**Decision:** `Menu.Target` is a transparent pass-through with no styling applied.
+
+**Implementation:** The target wrapper exists solely to manage Mantine's ref forwarding and event binding for the trigger element. No `filterStylingProps` or CSS module classes are applied — the trigger's appearance is entirely controlled by whatever component the integrator places inside it (e.g., `<Button>`).
+
+---
+
+## 6. Sub-Menu Support
+
+**Decision:** We wrap the full Mantine sub-menu hierarchy (`Menu.Sub`, `Menu.Sub.Target`, `Menu.Sub.Item`, `Menu.Sub.Dropdown`).
+
+**Implementation:** Sub-menu components inherit the same CSS module classes as their top-level counterparts since the Recursica token set does not distinguish sub-menu-specific styling. `Menu.Sub.Item` also strips the `color` prop in strict mode, consistent with `Menu.Item`. The sub-menu dropdown portal inherits the same `classNames` from the root Menu's `classNames` mapping.
+
+---
+
+## 7. Dropdown Container Padding
+
+**Decision:** The dropdown container uses `divider-item-gap` as its internal padding.
+
+**Implementation:** This ensures consistent spacing between the dropdown border and its content items. The gap token (`4px` by default) creates a subtle inset that visually separates items from the container edge, matching the Figma design specifications.
+
+---
+
+## 8. Minimal CSS Override Philosophy
+
+**Decision:** The CSS module only overrides visual design tokens (colors, typography, spacing, borders, shadows). All structural layout properties (flex, cursor, pointer-events, box-sizing, etc.) are deferred to Mantine's native behavior.
+
+**Implementation:** Unlike form-field components (e.g., Dropdown/TextField) which require deep structural overrides to strip Mantine's macro wrappers, the Menu is an overlay component where Mantine's native layout is already correct. We avoid setting:
+
+- `overflow` on the dropdown (Mantine renders sub-menu dropdowns inside the parent DOM tree using Floating UI absolute positioning — setting overflow clips them)
+- `display`, `align-items`, `width`, `cursor` on items (Mantine's button-based items already handle this)
+- `pointer-events` on disabled items (Mantine handles disabled natively)
+
+**Rationale:** Early iterations included aggressive structural resets (like `overflow: hidden`, `box-sizing: border-box`, `margin: 0`) cargo-culted from the Dropdown component. These caused sub-menus to render clipped inside the parent dropdown with scrollbars. The lesson: default to Mantine's native behavior and only override what the Recursica token system explicitly needs to control.

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

@@ -0,0 +1,244 @@
+/* HARDCODED VALUES:
+   - border-style: solid. Structural rendering rule for the dropdown border (Mantine uses Paper which may not set border natively).
+   - opacity: 0.5 on disabled items. Recursica has no dedicated disabled-opacity token for menu items.
+   - NOTE: overflow is intentionally NOT set on .dropdown. Mantine renders sub-menu dropdowns
+     inside the parent dropdown DOM tree using Floating UI absolute positioning. Setting
+     overflow: hidden clips sub-menus; overflow-y: auto causes unwanted scrollbars.
+   - All structural layout (flex, cursor, pointer-events on disabled) is deferred to Mantine's
+     native behavior. We only override visual design tokens (colors, typography, spacing, borders).
+*/
+
+/* ======================================
+   DROPDOWN CONTAINER
+   ====================================== */
+
+.dropdown {
+  background-color: var(
+    --recursica_ui-kit_components_menu_properties_colors_background
+  );
+  border-style: solid; /* HARDCODE: Mantine Paper does not set border-style natively */
+  border-width: var(--recursica_ui-kit_components_menu_properties_border-size);
+  border-color: var(
+    --recursica_ui-kit_components_menu_properties_colors_border-color
+  );
+  border-radius: var(
+    --recursica_ui-kit_components_menu_properties_border-radius
+  );
+  box-shadow: var(--recursica_ui-kit_components_menu_properties_elevation);
+
+  min-width: var(--recursica_ui-kit_components_menu_properties_min-width);
+  max-width: var(--recursica_ui-kit_components_menu_properties_max-width);
+
+  padding: var(
+    --recursica_ui-kit_components_menu-item_properties_divider-item-gap
+  );
+}
+
+/* ======================================
+   MENU ITEM
+   ====================================== */
+
+.item {
+  position: relative;
+
+  /* Geometry */
+  padding: var(
+      --recursica_ui-kit_components_menu-item_properties_vertical-padding
+    )
+    var(--recursica_ui-kit_components_menu-item_properties_horizontal-padding);
+  border-radius: var(
+    --recursica_ui-kit_components_menu-item_properties_border-radius
+  );
+
+  /* Typography */
+  font-family: var(
+    --recursica_ui-kit_components_menu-item_properties_text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_menu-item_properties_text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_menu-item_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_menu-item_properties_text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_menu-item_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_menu-item_properties_text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_menu-item_properties_text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_menu-item_properties_text_text-transform
+  );
+
+  /* Default State: Unselected */
+  background-color: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_background
+  );
+  color: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_text
+  );
+  opacity: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_opacity
+  );
+}
+
+/* Override Mantine's native hover background to use our overlay technique */
+.item:hover {
+  background-color: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_background
+  );
+}
+
+/* Hover overlay using ::after pseudo-element (same technique as Accordion) */
+.item::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  z-index: 0;
+  pointer-events: none;
+  background-color: var(
+    --recursica_ui-kit_components_menu-item_properties_hover-color
+  );
+  opacity: 0;
+  transition: opacity 150ms ease;
+}
+
+.item:hover:not([data-disabled])::after {
+  opacity: var(
+    --recursica_ui-kit_components_menu-item_properties_hover-opacity,
+    0.1
+  );
+}
+
+/* Selected item state */
+.item[data-selected] {
+  background-color: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_selected-item_background
+  );
+  color: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_selected-item_text
+  );
+  opacity: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_selected-item_opacity
+  );
+}
+
+/* Hovered item state (keyboard navigation) */
+.item[data-hovered] {
+  background-color: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_background
+  );
+}
+.item[data-hovered]::after {
+  opacity: var(
+    --recursica_ui-kit_components_menu-item_properties_hover-opacity,
+    0.1
+  );
+}
+
+/* Disabled item */
+.item[data-disabled] {
+  /* HARDCODE: 0.5 opacity fallback; no dedicated disabled-opacity token for menu items */
+  opacity: 0.5;
+}
+
+/* ======================================
+   ITEM LABEL
+   ====================================== */
+
+.itemLabel {
+  position: relative;
+  z-index: 1;
+  color: inherit;
+}
+
+/* ======================================
+   ITEM SECTION (LEFT / RIGHT ICONS)
+   ====================================== */
+
+.itemSection {
+  position: relative;
+  z-index: 1;
+  color: inherit;
+}
+
+/* ======================================
+   DIVIDER
+   ====================================== */
+
+.divider {
+  height: var(
+    --recursica_ui-kit_components_menu-item_properties_divider-height
+  );
+  background-color: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_divider-color
+  );
+  opacity: var(
+    --recursica_ui-kit_components_menu-item_properties_divider-opacity
+  );
+  margin: var(
+      --recursica_ui-kit_components_menu-item_properties_divider-item-gap
+    )
+    0;
+}
+
+/* ======================================
+   SECTION LABEL
+   ====================================== */
+
+.label {
+  padding: var(
+      --recursica_ui-kit_components_menu-item_properties_vertical-padding
+    )
+    var(--recursica_ui-kit_components_menu-item_properties_horizontal-padding);
+
+  /* Supporting Text Typography */
+  font-family: var(
+    --recursica_ui-kit_components_menu-item_properties_supporting-text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_menu-item_properties_supporting-text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_menu-item_properties_supporting-text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_menu-item_properties_supporting-text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_menu-item_properties_supporting-text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_menu-item_properties_supporting-text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_menu-item_properties_supporting-text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_menu-item_properties_supporting-text_text-transform
+  );
+
+  color: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_supporting-text-color
+  );
+  opacity: var(
+    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_supporting-text-opacity
+  );
+}
+
+/* ======================================
+   SUB-MENU CHEVRON
+   ====================================== */
+
+.chevron {
+  position: relative;
+  z-index: 1;
+  color: inherit;
+}