@recursica/mantine-adapter 0.12.0 → 0.13.1

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/Loader/LOADER_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,25 @@
+# Loader Implementation Notes
+
+## Architecture & Integration
+
+The `Loader` component acts as a strictly tokenized wrapper bridging the Recursica UI-Kit `loader` variables to the generic Mantine `@mantine/core` `Loader` primitive.
+
+### Key Decisions:
+
+- **Variant Mapping:** Recursica's `variant` directly proxies to Mantine's `type` prop for `"oval" | "bars" | "dots"`.
+- **Property Overrides Disabled:** Natively overriding specific structural variants directly on the JSX interface like `thickness` and `borderRadius` has been intentionally omitted. Component rendering relies entirely on variables exposed by the underlying UI Kit mappings tied to the size prop.
+
+### Token Mapping:
+
+Sizes are bound through `data-size` attributes (`sm`, `md`, `lg` parsing to target `<div data-size="small">`, etc.).
+
+Mantine natively sets sizing dynamically at the component root and parses thickness/variants differently natively (e.g., `oval` styles its geometry strictly via CSS `border`, while `bars` and `dots` utilize specific DOM inner spans `span.dot` / `span.bar`).
+
+#### Specific CSS Targeting Hacks Used
+
+- `border-width` structurally styles the `thickness` configuration of the `oval` variant by resolving `--recursica_ui-kit_components_loader_variants_sizes_..._properties_thickness`.
+- For non-oval variants, `border-radius` natively maps downwards to targeting component `span` children within the wrapper to capture `<span className="mantine-Loader-dot" />` geometries safely without polluting the flex wrapper natively.
+
+### Unsupported Properties
+
+- **xs and xl Sizing:** These sizes are explicitly unsupported in the Recursica standard logic (as surfaced in `filterStylingProps` and UI Kit mappings). Attempting to use them will safely default back or fallthrough statically unless defined later. See `COMPONENT_ISSUES.md`.

package/src/components/Menu/Menu.tsx

@@ -10,6 +10,7 @@ import {
   type MenuSubProps as MantineMenuSubProps,
   type MenuSubTargetProps as MantineMenuSubTargetProps,
   type MenuSubDropdownProps as MantineMenuSubDropdownProps,
+  createPolymorphicComponent,
 } from "@mantine/core";
 import {
   filterStylingProps,
@@ -131,29 +132,39 @@ export type MenuItemProps = RecursicaOverStyled<
   Omit<MantineMenuItemProps, "color">
 >;
 
-const MenuItem = forwardRef<HTMLButtonElement, MenuItemProps>(function MenuItem(
-  { overStyled = false, ...rest },
-  ref,
-) {
-  const sanitizedProps = filterStylingProps(rest, overStyled);
-  const restRecord = sanitizedProps as Record<string, unknown>;
+const _MenuItem = forwardRef<HTMLButtonElement, MenuItemProps>(
+  function MenuItem({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const restRecord = sanitizedProps as Record<string, unknown>;
 
-  // Strip Mantine's `color` prop to enforce token-driven styling
-  if (!overStyled) {
-    delete restRecord["color"];
-  }
+    // Strip Mantine's `color` prop to enforce token-driven styling
+    if (!overStyled) {
+      delete restRecord["color"];
+    }
 
-  const classNameProp = restRecord.className as string | undefined;
+    const classNameProp = restRecord.className as string | undefined;
 
-  return (
-    <MantineMenu.Item
-      ref={ref}
-      className={classNameProp}
-      {...(sanitizedProps as unknown as MantineMenuItemProps)}
-    />
-  );
-});
-MenuItem.displayName = "MenuItem";
+    return (
+      <MantineMenu.Item
+        ref={ref}
+        className={classNameProp}
+        {...(sanitizedProps as unknown as MantineMenuItemProps)}
+      />
+    );
+  },
+);
+_MenuItem.displayName = "MenuItem";
+
+/**
+ * An individual actionable item within the menu dropdown.
+ *
+ * Supports polymorphism via the `component` prop for link-style items.
+ * @example
+ * ```tsx
+ * <Menu.Item component="a" href="/settings">Settings</Menu.Item>
+ * ```
+ */
+const MenuItem = createPolymorphicComponent<"button", MenuItemProps>(_MenuItem);
 
 // ============================================================
 // MENU DIVIDER
@@ -240,7 +251,7 @@ export type MenuSubItemProps = RecursicaOverStyled<
   Omit<MantineMenuItemProps, "color">
 >;
 
-const MenuSubItem = forwardRef<HTMLButtonElement, MenuSubItemProps>(
+const _MenuSubItem = forwardRef<HTMLButtonElement, MenuSubItemProps>(
   function MenuSubItem({ overStyled = false, ...rest }, ref) {
     const sanitizedProps = filterStylingProps(rest, overStyled);
     const restRecord = sanitizedProps as Record<string, unknown>;
@@ -260,7 +271,16 @@ const MenuSubItem = forwardRef<HTMLButtonElement, MenuSubItemProps>(
     );
   },
 );
-MenuSubItem.displayName = "MenuSubItem";
+_MenuSubItem.displayName = "MenuSubItem";
+
+/**
+ * A menu item that acts as a submenu trigger.
+ *
+ * Supports polymorphism via the `component` prop.
+ */
+const MenuSubItem = createPolymorphicComponent<"button", MenuSubItemProps>(
+  _MenuSubItem,
+);
 
 // ============================================================
 // MENU SUB DROPDOWN

package/src/components/Text/Text.tsx

@@ -2,6 +2,7 @@ import { forwardRef, type ReactNode } from "react";
 import {
   Text as MantineText,
   type TextProps as MantineTextProps,
+  createPolymorphicComponent,
 } from "@mantine/core";
 import {
   filterStylingProps,
@@ -26,11 +27,7 @@ export type RecursicaTextProps = Omit<MantineTextProps, "variant"> & {
 
 export type TextProps = RecursicaOverStyled<RecursicaTextProps>;
 
-/**
- * A generalized typographical wrapper limiting text properties to bounded Recursica UI-kit tokens inherently.
- * Do not use for semantic headings; use the explicit `<Title>` component for `<h1>` - `<h6>`.
- */
-export const Text = forwardRef<HTMLDivElement, TextProps>(function Text(
+const _Text = forwardRef<HTMLDivElement, TextProps>(function Text(
   { overStyled = false, variant = "body", ...rest },
   ref,
 ) {
@@ -51,4 +48,17 @@ export const Text = forwardRef<HTMLDivElement, TextProps>(function Text(
     />
   );
 });
-Text.displayName = "Text";
+_Text.displayName = "Text";
+
+/**
+ * A generalized typographical wrapper limiting text properties to bounded Recursica UI-kit tokens inherently.
+ * Do not use for semantic headings; use the explicit `<Title>` component for `<h1>` - `<h6>`.
+ *
+ * Supports polymorphism via the `component` prop or `renderRoot` for custom element rendering.
+ * @example
+ * ```tsx
+ * <Text component="span">Inline text</Text>
+ * <Text component="label" htmlFor="input-id">Label text</Text>
+ * ```
+ */
+export const Text = createPolymorphicComponent<"p", TextProps>(_Text);