@recursica/mantine-adapter 0.12.0 → 0.13.0

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

@@ -1,9 +1,23 @@
 import { default as React } from 'react';
 import { AvatarProps as MantineAvatarProps } from '@mantine/core';
+import { RecursicaOverStyled } from '../../utils/filterStylingProps';
 export interface RecursicaAvatarProps {
     size?: "small" | "default" | "large";
     variant?: "solid" | "outline" | "ghost";
     icon?: React.ReactNode;
 }
-export type AvatarProps = Omit<MantineAvatarProps, "variant" | "size" | "color" | "radius"> & RecursicaAvatarProps;
-export declare const Avatar: React.ForwardRefExoticComponent<Omit<MantineAvatarProps, "color" | "radius" | "variant" | "size"> & RecursicaAvatarProps & React.RefAttributes<HTMLDivElement>>;
+export type AvatarProps = RecursicaOverStyled<Omit<MantineAvatarProps, "variant" | "size" | "color" | "radius"> & RecursicaAvatarProps>;
+/**
+ * Recursica Avatar component wrapping Mantine's Avatar.
+ *
+ * Supports polymorphism via the `component` prop or `renderRoot` for custom element rendering.
+ */
+export declare const Avatar: (<C = "div">(props: import('@mantine/core').PolymorphicComponentProps<C, AvatarProps>) => React.ReactElement) & Omit<React.FunctionComponent<((AvatarProps & {
+    component?: any;
+}) & Omit<Omit<any, "ref">, "className" | "classNames" | "style" | "styles" | "vars" | "p" | "px" | "py" | "pt" | "pb" | "pl" | "pr" | "bg" | "c" | "opacity" | "ff" | "fz" | "fw" | "lts" | "ta" | "lh" | "fs" | "tt" | "td" | "bd" | "w" | "miw" | "maw" | "h" | "mih" | "mah" | "m" | "my" | "mx" | "mt" | "mb" | "ml" | "mr" | "top" | "left" | "bottom" | "right" | "children" | "__vars" | "__size" | "hiddenFrom" | "visibleFrom" | "lightHidden" | "darkHidden" | "mod" | "ms" | "me" | "ps" | "pe" | "bdrs" | "bgsz" | "bgp" | "bgr" | "bga" | "pos" | "inset" | "display" | "flex" | "unstyled" | "variant" | "attributes" | "overStyled" | "name" | "icon" | "size" | "gradient" | "src" | "alt" | "imageProps" | "autoContrast" | "allowedInitialsColors" | "component"> & {
+    ref?: any;
+    renderRoot?: (props: any) => any;
+}) | (AvatarProps & {
+    component: React.ElementType;
+    renderRoot?: (props: Record<string, any>) => any;
+})>, never> & Record<string, never>;

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

@@ -5,4 +5,17 @@ export interface RecursicaBadgeProps {
     variant?: "alert" | "primary-color" | "success" | "warning";
 }
 export type BadgeProps = RecursicaOverStyled<Omit<MantineBadgeProps, "variant" | "size" | "color" | "radius"> & RecursicaBadgeProps>;
-export declare const Badge: import('react').ForwardRefExoticComponent<BadgeProps & import('react').RefAttributes<HTMLDivElement>>;
+/**
+ * Recursica Badge component wrapping Mantine's Badge.
+ *
+ * Supports polymorphism via the `component` prop or `renderRoot` for custom element rendering.
+ */
+export declare const Badge: (<C = "div">(props: import('@mantine/core').PolymorphicComponentProps<C, BadgeProps>) => React.ReactElement) & Omit<import('react').FunctionComponent<((BadgeProps & {
+    component?: any;
+}) & Omit<Omit<any, "ref">, "className" | "classNames" | "style" | "styles" | "vars" | "p" | "px" | "py" | "pt" | "pb" | "pl" | "pr" | "bg" | "c" | "opacity" | "ff" | "fz" | "fw" | "lts" | "ta" | "lh" | "fs" | "tt" | "td" | "bd" | "w" | "miw" | "maw" | "h" | "mih" | "mah" | "m" | "my" | "mx" | "mt" | "mb" | "ml" | "mr" | "top" | "left" | "bottom" | "right" | "circle" | "children" | "__vars" | "__size" | "hiddenFrom" | "visibleFrom" | "lightHidden" | "darkHidden" | "mod" | "ms" | "me" | "ps" | "pe" | "bdrs" | "bgsz" | "bgp" | "bgr" | "bga" | "pos" | "inset" | "display" | "flex" | "unstyled" | "variant" | "attributes" | "overStyled" | "gradient" | "autoContrast" | "component" | "leftSection" | "rightSection" | "fullWidth"> & {
+    ref?: any;
+    renderRoot?: (props: any) => any;
+}) | (BadgeProps & {
+    component: React.ElementType;
+    renderRoot?: (props: Record<string, any>) => any;
+})>, never> & Record<string, never>;

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

@@ -7,4 +7,22 @@ export interface RecursicaButtonProps {
     icon?: React.ReactNode;
 }
 export type ButtonProps = RecursicaOverStyled<Omit<MantineButtonProps, "variant" | "size" | "leftSection" | "fullWidth"> & RecursicaButtonProps>;
-export declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement>>;
+/**
+ * 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 declare const Button: (<C = "button">(props: import('@mantine/core').PolymorphicComponentProps<C, ButtonProps>) => React.ReactElement) & Omit<React.FunctionComponent<((ButtonProps & {
+    component?: any;
+}) & Omit<Omit<any, "ref">, "className" | "classNames" | "style" | "styles" | "vars" | "p" | "px" | "py" | "pt" | "pb" | "pl" | "pr" | "bg" | "c" | "opacity" | "ff" | "fz" | "fw" | "lts" | "ta" | "lh" | "fs" | "tt" | "td" | "bd" | "w" | "miw" | "maw" | "h" | "mih" | "mah" | "m" | "my" | "mx" | "mt" | "mb" | "ml" | "mr" | "top" | "left" | "bottom" | "right" | "color" | "children" | "radius" | "__vars" | "__size" | "hiddenFrom" | "visibleFrom" | "lightHidden" | "darkHidden" | "mod" | "ms" | "me" | "ps" | "pe" | "bdrs" | "bgsz" | "bgp" | "bgr" | "bga" | "pos" | "inset" | "display" | "flex" | "unstyled" | "variant" | "attributes" | "overStyled" | "disabled" | "icon" | "justify" | "size" | "gradient" | "autoContrast" | "component" | "loading" | "rightSection" | "data-disabled" | "loaderProps"> & {
+    ref?: any;
+    renderRoot?: (props: any) => any;
+}) | (ButtonProps & {
+    component: React.ElementType;
+    renderRoot?: (props: Record<string, any>) => any;
+})>, never> & Record<string, never>;

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

@@ -1,10 +1,6 @@
 import { CardProps as MantineCardProps, CardSectionProps as MantineCardSectionProps } from '@mantine/core';
 import { RecursicaOverStyled } from '../../utils/filterStylingProps';
 export type CardProps = RecursicaOverStyled<MantineCardProps>;
-/**
- * The root Card elevation box. It establishes the global background color, border radius, nested component gap, and outer shadow governed by the current `Layer` context.
- */
-declare const CardBase: import('react').ForwardRefExoticComponent<CardProps & import('react').RefAttributes<HTMLDivElement>>;
 export type RecursicaCardSectionProps = MantineCardSectionProps & {
     children?: React.ReactNode;
 };
@@ -28,11 +24,30 @@ export type CardContentProps = RecursicaOverStyled<React.HTMLAttributes<HTMLDivE
  * Internal container that safely binds typography and structural flex gaps driven by the active UI kit tokens natively, preserving correct padding blocks compared to rigid `Card.Section` edges.
  */
 export declare const CardContent: import('react').ForwardRefExoticComponent<CardContentProps & import('react').RefAttributes<HTMLDivElement>>;
-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.
+ */
+declare const PolymorphicCard: (<C = "div">(props: import('@mantine/core').PolymorphicComponentProps<C, CardProps>) => React.ReactElement) & Omit<import('react').FunctionComponent<((CardProps & {
+    component?: any;
+}) & Omit<Omit<any, "ref">, "className" | "classNames" | "style" | "styles" | "vars" | "p" | "px" | "py" | "pt" | "pb" | "pl" | "pr" | "bg" | "c" | "opacity" | "ff" | "fz" | "fw" | "lts" | "ta" | "lh" | "fs" | "tt" | "td" | "bd" | "shadow" | "w" | "miw" | "maw" | "h" | "mih" | "mah" | "m" | "my" | "mx" | "mt" | "mb" | "ml" | "mr" | "top" | "left" | "bottom" | "right" | "children" | "radius" | "__vars" | "__size" | "hiddenFrom" | "visibleFrom" | "lightHidden" | "darkHidden" | "mod" | "ms" | "me" | "ps" | "pe" | "bdrs" | "bgsz" | "bgp" | "bgr" | "bga" | "pos" | "inset" | "display" | "flex" | "unstyled" | "variant" | "attributes" | "overStyled" | "component" | "withBorder" | "padding"> & {
+    ref?: any;
+    renderRoot?: (props: any) => any;
+}) | (CardProps & {
+    component: React.ElementType;
+    renderRoot?: (props: Record<string, any>) => any;
+})>, never> & {
+    Section: typeof CardSection;
+    Header: typeof CardHeader;
+    Footer: typeof CardFooter;
+    Content: typeof CardContent;
+};
+export declare const Card: typeof PolymorphicCard & {
     Section: typeof CardSection;
     Header: typeof CardHeader;
     Footer: typeof CardFooter;
     Content: typeof CardContent;
 };
-export declare const Card: CardComponent;
 export {};

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

@@ -14,4 +14,22 @@ export interface RecursicaFlexProps {
  * Flex layout wrapper
  */
 export type FlexProps = RecursicaOverStyled<MantineFlexProps & RecursicaFlexProps>;
-export declare const Flex: React.ForwardRefExoticComponent<FlexProps & React.RefAttributes<HTMLDivElement>>;
+/**
+ * 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 declare const Flex: (<C = "div">(props: import('@mantine/core').PolymorphicComponentProps<C, FlexProps>) => React.ReactElement) & Omit<React.FunctionComponent<((FlexProps & {
+    component?: any;
+}) & Omit<Omit<any, "ref">, "className" | "classNames" | "style" | "styles" | "vars" | "p" | "px" | "py" | "pt" | "pb" | "pl" | "pr" | "bg" | "c" | "opacity" | "ff" | "fz" | "fw" | "lts" | "ta" | "lh" | "fs" | "tt" | "td" | "bd" | "w" | "miw" | "maw" | "h" | "mih" | "mah" | "m" | "my" | "mx" | "mt" | "mb" | "ml" | "mr" | "gap" | "rowGap" | "columnGap" | "top" | "left" | "bottom" | "right" | "key" | "defaultValue" | "onChange" | "slot" | "title" | "defaultChecked" | "suppressContentEditableWarning" | "suppressHydrationWarning" | "accessKey" | "autoCapitalize" | "autoFocus" | "contentEditable" | "contextMenu" | "dir" | "draggable" | "enterKeyHint" | "hidden" | "id" | "lang" | "nonce" | "spellCheck" | "tabIndex" | "translate" | "radioGroup" | "role" | "about" | "content" | "datatype" | "inlist" | "prefix" | "property" | "rel" | "resource" | "rev" | "typeof" | "vocab" | "autoCorrect" | "autoSave" | "color" | "itemProp" | "itemScope" | "itemType" | "itemID" | "itemRef" | "results" | "security" | "unselectable" | "popover" | "popoverTargetAction" | "popoverTarget" | "inert" | "inputMode" | "is" | "exportparts" | "part" | "aria-activedescendant" | "aria-atomic" | "aria-autocomplete" | "aria-braillelabel" | "aria-brailleroledescription" | "aria-busy" | "aria-checked" | "aria-colcount" | "aria-colindex" | "aria-colindextext" | "aria-colspan" | "aria-controls" | "aria-current" | "aria-describedby" | "aria-description" | "aria-details" | "aria-disabled" | "aria-dropeffect" | "aria-errormessage" | "aria-expanded" | "aria-flowto" | "aria-grabbed" | "aria-haspopup" | "aria-hidden" | "aria-invalid" | "aria-keyshortcuts" | "aria-label" | "aria-labelledby" | "aria-level" | "aria-live" | "aria-modal" | "aria-multiline" | "aria-multiselectable" | "aria-orientation" | "aria-owns" | "aria-placeholder" | "aria-posinset" | "aria-pressed" | "aria-readonly" | "aria-relevant" | "aria-required" | "aria-roledescription" | "aria-rowcount" | "aria-rowindex" | "aria-rowindextext" | "aria-rowspan" | "aria-selected" | "aria-setsize" | "aria-sort" | "aria-valuemax" | "aria-valuemin" | "aria-valuenow" | "aria-valuetext" | "children" | "dangerouslySetInnerHTML" | "onCopy" | "onCopyCapture" | "onCut" | "onCutCapture" | "onPaste" | "onPasteCapture" | "onCompositionEnd" | "onCompositionEndCapture" | "onCompositionStart" | "onCompositionStartCapture" | "onCompositionUpdate" | "onCompositionUpdateCapture" | "onFocus" | "onFocusCapture" | "onBlur" | "onBlurCapture" | "onChangeCapture" | "onBeforeInput" | "onBeforeInputCapture" | "onInput" | "onInputCapture" | "onReset" | "onResetCapture" | "onSubmit" | "onSubmitCapture" | "onInvalid" | "onInvalidCapture" | "onLoad" | "onLoadCapture" | "onError" | "onErrorCapture" | "onKeyDown" | "onKeyDownCapture" | "onKeyPress" | "onKeyPressCapture" | "onKeyUp" | "onKeyUpCapture" | "onAbort" | "onAbortCapture" | "onCanPlay" | "onCanPlayCapture" | "onCanPlayThrough" | "onCanPlayThroughCapture" | "onDurationChange" | "onDurationChangeCapture" | "onEmptied" | "onEmptiedCapture" | "onEncrypted" | "onEncryptedCapture" | "onEnded" | "onEndedCapture" | "onLoadedData" | "onLoadedDataCapture" | "onLoadedMetadata" | "onLoadedMetadataCapture" | "onLoadStart" | "onLoadStartCapture" | "onPause" | "onPauseCapture" | "onPlay" | "onPlayCapture" | "onPlaying" | "onPlayingCapture" | "onProgress" | "onProgressCapture" | "onRateChange" | "onRateChangeCapture" | "onSeeked" | "onSeekedCapture" | "onSeeking" | "onSeekingCapture" | "onStalled" | "onStalledCapture" | "onSuspend" | "onSuspendCapture" | "onTimeUpdate" | "onTimeUpdateCapture" | "onVolumeChange" | "onVolumeChangeCapture" | "onWaiting" | "onWaitingCapture" | "onAuxClick" | "onAuxClickCapture" | "onClick" | "onClickCapture" | "onContextMenu" | "onContextMenuCapture" | "onDoubleClick" | "onDoubleClickCapture" | "onDrag" | "onDragCapture" | "onDragEnd" | "onDragEndCapture" | "onDragEnter" | "onDragEnterCapture" | "onDragExit" | "onDragExitCapture" | "onDragLeave" | "onDragLeaveCapture" | "onDragOver" | "onDragOverCapture" | "onDragStart" | "onDragStartCapture" | "onDrop" | "onDropCapture" | "onMouseDown" | "onMouseDownCapture" | "onMouseEnter" | "onMouseLeave" | "onMouseMove" | "onMouseMoveCapture" | "onMouseOut" | "onMouseOutCapture" | "onMouseOver" | "onMouseOverCapture" | "onMouseUp" | "onMouseUpCapture" | "onSelect" | "onSelectCapture" | "onTouchCancel" | "onTouchCancelCapture" | "onTouchEnd" | "onTouchEndCapture" | "onTouchMove" | "onTouchMoveCapture" | "onTouchStart" | "onTouchStartCapture" | "onPointerDown" | "onPointerDownCapture" | "onPointerMove" | "onPointerMoveCapture" | "onPointerUp" | "onPointerUpCapture" | "onPointerCancel" | "onPointerCancelCapture" | "onPointerEnter" | "onPointerLeave" | "onPointerOver" | "onPointerOverCapture" | "onPointerOut" | "onPointerOutCapture" | "onGotPointerCapture" | "onGotPointerCaptureCapture" | "onLostPointerCapture" | "onLostPointerCaptureCapture" | "onScroll" | "onScrollCapture" | "onScrollEnd" | "onScrollEndCapture" | "onWheel" | "onWheelCapture" | "onAnimationStart" | "onAnimationStartCapture" | "onAnimationEnd" | "onAnimationEndCapture" | "onAnimationIteration" | "onAnimationIterationCapture" | "onToggle" | "onBeforeToggle" | "onTransitionCancel" | "onTransitionCancelCapture" | "onTransitionEnd" | "onTransitionEndCapture" | "onTransitionRun" | "onTransitionRunCapture" | "onTransitionStart" | "onTransitionStartCapture" | "__vars" | "__size" | "hiddenFrom" | "visibleFrom" | "lightHidden" | "darkHidden" | "mod" | "ms" | "me" | "ps" | "pe" | "bdrs" | "bgsz" | "bgp" | "bgr" | "bga" | "pos" | "inset" | "display" | "flex" | "unstyled" | "variant" | "attributes" | "overStyled" | "justify" | "component" | "direction" | "wrap" | "align"> & {
+    ref?: any;
+    renderRoot?: (props: any) => any;
+}) | (FlexProps & {
+    component: React.ElementType;
+    renderRoot?: (props: Record<string, any>) => any;
+})>, never> & Record<string, never>;

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

@@ -40,7 +40,24 @@ declare const MenuDropdown: import('react').ForwardRefExoticComponent<MenuDropdo
  * design token adherence. Use `overStyled={true}` if you need to bypass.
  */
 export type MenuItemProps = RecursicaOverStyled<Omit<MantineMenuItemProps, "color">>;
-declare const MenuItem: import('react').ForwardRefExoticComponent<MenuItemProps & import('react').RefAttributes<HTMLButtonElement>>;
+/**
+ * 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>
+ * ```
+ */
+declare const MenuItem: (<C = "button">(props: import('@mantine/core').PolymorphicComponentProps<C, MenuItemProps>) => React.ReactElement) & Omit<import('react').FunctionComponent<((MenuItemProps & {
+    component?: any;
+}) & Omit<Omit<any, "ref">, "className" | "classNames" | "style" | "styles" | "vars" | "p" | "px" | "py" | "pt" | "pb" | "pl" | "pr" | "bg" | "c" | "opacity" | "ff" | "fz" | "fw" | "lts" | "ta" | "lh" | "fs" | "tt" | "td" | "bd" | "w" | "miw" | "maw" | "h" | "mih" | "mah" | "m" | "my" | "mx" | "mt" | "mb" | "ml" | "mr" | "top" | "left" | "bottom" | "right" | "children" | "__vars" | "__size" | "hiddenFrom" | "visibleFrom" | "lightHidden" | "darkHidden" | "mod" | "ms" | "me" | "ps" | "pe" | "bdrs" | "bgsz" | "bgp" | "bgr" | "bga" | "pos" | "inset" | "display" | "flex" | "variant" | "overStyled" | "disabled" | "component" | "leftSection" | "rightSection" | "data-disabled" | "closeMenuOnClick"> & {
+    ref?: any;
+    renderRoot?: (props: any) => any;
+}) | (MenuItemProps & {
+    component: React.ElementType;
+    renderRoot?: (props: Record<string, any>) => any;
+})>, never> & Record<string, never>;
 /** A visual separator between groups of menu items. */
 export type MenuDividerProps = RecursicaOverStyled<MantineMenuDividerProps>;
 declare const MenuDivider: import('react').ForwardRefExoticComponent<MenuDividerProps & import('react').RefAttributes<HTMLHRElement>>;
@@ -64,7 +81,20 @@ declare const MenuSubTarget: {
  * Renders within Menu.Sub.Target and displays a chevron indicator.
  */
 export type MenuSubItemProps = RecursicaOverStyled<Omit<MantineMenuItemProps, "color">>;
-declare const MenuSubItem: import('react').ForwardRefExoticComponent<MenuSubItemProps & import('react').RefAttributes<HTMLButtonElement>>;
+/**
+ * A menu item that acts as a submenu trigger.
+ *
+ * Supports polymorphism via the `component` prop.
+ */
+declare const MenuSubItem: (<C = "button">(props: import('@mantine/core').PolymorphicComponentProps<C, MenuSubItemProps>) => React.ReactElement) & Omit<import('react').FunctionComponent<((MenuSubItemProps & {
+    component?: any;
+}) & Omit<Omit<any, "ref">, "className" | "classNames" | "style" | "styles" | "vars" | "p" | "px" | "py" | "pt" | "pb" | "pl" | "pr" | "bg" | "c" | "opacity" | "ff" | "fz" | "fw" | "lts" | "ta" | "lh" | "fs" | "tt" | "td" | "bd" | "w" | "miw" | "maw" | "h" | "mih" | "mah" | "m" | "my" | "mx" | "mt" | "mb" | "ml" | "mr" | "top" | "left" | "bottom" | "right" | "children" | "__vars" | "__size" | "hiddenFrom" | "visibleFrom" | "lightHidden" | "darkHidden" | "mod" | "ms" | "me" | "ps" | "pe" | "bdrs" | "bgsz" | "bgp" | "bgr" | "bga" | "pos" | "inset" | "display" | "flex" | "variant" | "overStyled" | "disabled" | "component" | "leftSection" | "rightSection" | "data-disabled" | "closeMenuOnClick"> & {
+    ref?: any;
+    renderRoot?: (props: any) => any;
+}) | (MenuSubItemProps & {
+    component: React.ElementType;
+    renderRoot?: (props: Record<string, any>) => any;
+})>, never> & Record<string, never>;
 /** The dropdown panel for a submenu. */
 export type MenuSubDropdownProps = RecursicaOverStyled<MantineMenuSubDropdownProps>;
 declare const MenuSubDropdown: import('react').ForwardRefExoticComponent<MenuSubDropdownProps & import('react').RefAttributes<HTMLDivElement>>;

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

@@ -13,5 +13,20 @@ 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>`.
+ *
+ * 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 declare const Text: import('react').ForwardRefExoticComponent<TextProps & import('react').RefAttributes<HTMLDivElement>>;
+export declare const Text: (<C = "p">(props: import('@mantine/core').PolymorphicComponentProps<C, TextProps>) => React.ReactElement) & Omit<import('react').FunctionComponent<((TextProps & {
+    component?: any;
+}) & Omit<Omit<any, "ref">, "className" | "classNames" | "style" | "styles" | "vars" | "p" | "px" | "py" | "pt" | "pb" | "pl" | "pr" | "bg" | "c" | "opacity" | "ff" | "fz" | "fw" | "lts" | "ta" | "lh" | "fs" | "tt" | "td" | "bd" | "w" | "miw" | "maw" | "h" | "mih" | "mah" | "m" | "my" | "mx" | "mt" | "mb" | "ml" | "mr" | "top" | "left" | "bottom" | "right" | "span" | "color" | "children" | "__vars" | "__size" | "hiddenFrom" | "visibleFrom" | "lightHidden" | "darkHidden" | "mod" | "ms" | "me" | "ps" | "pe" | "bdrs" | "bgsz" | "bgp" | "bgr" | "bga" | "pos" | "inset" | "display" | "flex" | "unstyled" | "variant" | "attributes" | "overStyled" | "inherit" | "inline" | "size" | "gradient" | "component" | "__staticSelector" | "lineClamp" | "truncate"> & {
+    ref?: any;
+    renderRoot?: (props: any) => any;
+}) | (TextProps & {
+    component: React.ElementType;
+    renderRoot?: (props: Record<string, any>) => any;
+})>, never> & Record<string, never>;

package/package.json

@@ -11,7 +11,7 @@
     "type": "git",
     "url": "git+https://github.com/borderux/recursica.git"
   },
-  "version": "0.12.0",
+  "version": "0.13.0",
   "type": "module",
   "main": "./dist/mantine-adapter.cjs",
   "module": "./dist/mantine-adapter.js",

package/src/components/Avatar/Avatar.tsx

@@ -2,7 +2,12 @@ import React, { forwardRef } from "react";
 import {
   Avatar as MantineAvatar,
   type AvatarProps as MantineAvatarProps,
+  createPolymorphicComponent,
 } from "@mantine/core";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
 import styles from "./Avatar.module.css";
 
 export interface RecursicaAvatarProps {
@@ -11,22 +16,19 @@ export interface RecursicaAvatarProps {
   icon?: React.ReactNode;
 }
 
-export type AvatarProps = Omit<
-  MantineAvatarProps,
-  "variant" | "size" | "color" | "radius"
-> &
-  RecursicaAvatarProps;
+export type AvatarProps = RecursicaOverStyled<
+  Omit<MantineAvatarProps, "variant" | "size" | "color" | "radius"> &
+    RecursicaAvatarProps
+>;
 
-export const Avatar = forwardRef<HTMLDivElement, AvatarProps>(function Avatar(
+const _Avatar = forwardRef<HTMLDivElement, AvatarProps>(function Avatar(
   {
     size = "default",
     variant = "solid",
     icon,
-    className,
-    classNames,
     children,
-    style,
     src,
+    overStyled = false,
     ...rest
   },
   ref,
@@ -43,6 +45,9 @@ export const Avatar = forwardRef<HTMLDivElement, AvatarProps>(function Avatar(
     large: "lg",
   } as const;
 
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const restRecord = sanitizedProps as Record<string, unknown>;
+
   // Determine semantic style based on provided props
   let computedStyle = "text";
   if (src) {
@@ -57,12 +62,13 @@ export const Avatar = forwardRef<HTMLDivElement, AvatarProps>(function Avatar(
     placeholder: styles.placeholder,
   };
 
+  const classNamesProp = restRecord.classNames;
   if (
-    classNames &&
-    typeof classNames === "object" &&
-    !Array.isArray(classNames)
+    classNamesProp &&
+    typeof classNamesProp === "object" &&
+    !Array.isArray(classNamesProp)
   ) {
-    const o = classNames as Partial<Record<string, string>>;
+    const o = classNamesProp as Partial<Record<string, string>>;
     mergedClassNames.root = o.root ? `${styles.root} ${o.root}` : styles.root;
     mergedClassNames.image = o.image
       ? `${styles.image} ${o.image}`
@@ -72,19 +78,20 @@ export const Avatar = forwardRef<HTMLDivElement, AvatarProps>(function Avatar(
       : styles.placeholder;
   }
 
+  const classNameProp = restRecord.className as string | undefined;
+
   return (
     <MantineAvatar
       ref={ref}
-      className={className}
+      className={classNameProp}
       classNames={mergedClassNames}
       variant={mapVariant[variant]}
       size={mapSize[size]}
-      style={style}
       src={src}
       data-variant={variant}
       data-size={size}
       data-style={computedStyle}
-      {...rest}
+      {...sanitizedProps}
     >
       {icon != null ? (
         <span className={styles.iconWrapper} aria-hidden>
@@ -96,5 +103,11 @@ export const Avatar = forwardRef<HTMLDivElement, AvatarProps>(function Avatar(
     </MantineAvatar>
   );
 });
+_Avatar.displayName = "Avatar";
 
-Avatar.displayName = "Avatar";
+/**
+ * Recursica Avatar component wrapping Mantine's Avatar.
+ *
+ * Supports polymorphism via the `component` prop or `renderRoot` for custom element rendering.
+ */
+export const Avatar = createPolymorphicComponent<"div", AvatarProps>(_Avatar);

package/src/components/Badge/Badge.tsx

@@ -2,6 +2,7 @@ import { forwardRef } from "react";
 import {
   Badge as MantineBadge,
   type BadgeProps as MantineBadgeProps,
+  createPolymorphicComponent,
 } from "@mantine/core";
 import {
   filterStylingProps,
@@ -19,7 +20,7 @@ export type BadgeProps = RecursicaOverStyled<
     RecursicaBadgeProps
 >;
 
-export const Badge = forwardRef<HTMLDivElement, BadgeProps>(function Badge(
+const _Badge = forwardRef<HTMLDivElement, BadgeProps>(function Badge(
   { variant = "primary-color", overStyled = false, ...rest },
   ref,
 ) {
@@ -62,5 +63,11 @@ export const Badge = forwardRef<HTMLDivElement, BadgeProps>(function Badge(
     />
   );
 });
+_Badge.displayName = "Badge";
 
-Badge.displayName = "Badge";
+/**
+ * Recursica Badge component wrapping Mantine's Badge.
+ *
+ * Supports polymorphism via the `component` prop or `renderRoot` for custom element rendering.
+ */
+export const Badge = createPolymorphicComponent<"div", BadgeProps>(_Badge);

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;