@recursica/mui-adapter 0.6.0 → 0.7.0

package/src/components/Group/Group.tsx

@@ -4,25 +4,28 @@ import {
   type StackProps as MUIStackProps,
 } from "@mui/material";
 import {
-  type RecursicaSpacing,
   SPACING_MAP,
   type OmitSx,
   filterSxProp,
 } from "../../utils/filterStylingProps";
 
-export interface RecursicaGroupProps {
-  children?: React.ReactNode;
-  gap?: MUIStackProps["spacing"] | RecursicaSpacing;
-  rowGap?: MUIStackProps["spacing"] | RecursicaSpacing;
-  columnGap?: MUIStackProps["spacing"] | RecursicaSpacing;
-}
+import { type RecursicaGroupProps } from "@recursica/adapter-common";
 
 export type GroupProps = OmitSx<
   Omit<MUIStackProps, "spacing" | "direction"> & RecursicaGroupProps
 >;
 
 export const Group = forwardRef<HTMLDivElement, GroupProps>(function Group(
-  { children, gap = "rec-default", rowGap, columnGap, ...rest },
+  {
+    children,
+    gap = "rec-default",
+    rowGap,
+    columnGap,
+    justify,
+    align,
+    wrap,
+    ...rest
+  },
   ref,
 ) {
   const safeProps = filterSxProp(rest as Record<string, unknown>);
@@ -43,7 +46,9 @@ export const Group = forwardRef<HTMLDivElement, GroupProps>(function Group(
     <MUIStack
       ref={ref}
       direction="row"
-      flexWrap="wrap"
+      flexWrap={wrap || "wrap"}
+      justifyContent={justify}
+      alignItems={align}
       spacing={resolvedGap}
       sx={{
         ...(resolvedRowGap ? { rowGap: resolvedRowGap } : {}),

package/src/components/HoverCard/HoverCard.tsx

@@ -1,6 +1,7 @@
+import React, { isValidElement } from "react";
 import {
-  Popover as MuiHoverCard,
-  type PopoverProps as MuiHoverCardProps,
+  Tooltip as MuiTooltip,
+  type TooltipProps as MuiTooltipProps,
 } from "@mui/material";
 import {
   filterStylingProps,
@@ -12,48 +13,31 @@ import styles from "./HoverCard.module.css";
 // HOVERCARD ROOT
 // ============================================================
 
-/**
- * Recursica-specific props for HoverCard.
- */
-export interface RecursicaHoverCardProps {
-  /**
-   * Whether to display a beak (arrow) pointing from the dropdown to the target.
-   * This is the Recursica equivalent of Mui's `withArrow`.
-   * When both `withBeak` and `withArrow` are provided, `withBeak` takes precedence.
-   */
-  withBeak?: boolean;
-}
-
-/**
- * Recursica HoverCard component wrapping Mui's composable HoverCard.
- *
- * Displays a dropdown panel when the user hovers over a target element.
- * Uses the composable dot-notation pattern:
- * ```tsx
- * <HoverCard withBeak>
- *   <HoverCard.Target>
- *     <Button>Hover me</Button>
- *   </HoverCard.Target>
- *   <HoverCard.Dropdown>
- *     Content displayed on hover
- *   </HoverCard.Dropdown>
- * </HoverCard>
- * ```
- */
+import { type RecursicaHoverCardProps } from "@recursica/adapter-common";
+
 export type HoverCardProps = RecursicaOverStyled<
-  MuiHoverCardProps & RecursicaHoverCardProps
+  Omit<MuiTooltipProps, "title" | "children"> & RecursicaHoverCardProps
 >;
 
 const HoverCardBase = function HoverCard({
   overStyled = false,
   withBeak = true,
+  position = "top",
+  openDelay = 0,
+  closeDelay = 150,
+  disabled = false,
+  offset = 5,
+  children,
   ...rest
 }: HoverCardProps) {
-  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const sanitizedProps = filterStylingProps(
+    rest as Record<string, unknown>,
+    overStyled,
+  );
 
   // Bind CSS module classes to Mui's internal classNames API
   const mergedClassNames: Partial<Record<string, string>> = {
-    dropdown: styles.dropdown,
+    tooltip: styles.dropdown,
     arrow: styles.arrow,
   };
 
@@ -73,29 +57,55 @@ const HoverCardBase = function HoverCard({
     });
   }
 
-  // arrowSize must be a JS number prop — Mui uses it for inline width/height
-  // and positioning offset (-arrowSize/2) calculations that cannot be CSS-driven.
-  // Default to 16 to match the Recursica beak-size token (16px).
-  const arrowSize =
-    ((sanitizedProps as Record<string, unknown>).arrowSize as
-      | number
-      | undefined) ?? 16;
-
-  // Resolve withBeak (Recursica) vs withArrow (Mui).
-  // withBeak takes precedence when both are provided.
-  const withArrow = (sanitizedProps as Record<string, unknown>).withArrow as
-    | boolean
-    | undefined;
-  const resolvedWithArrow = withBeak ?? withArrow;
+  // Find Target and Dropdown children
+  let targetNode: React.ReactNode = null;
+  let dropdownNode: React.ReactNode = null;
+
+  React.Children.forEach(children, (child) => {
+    if (isValidElement(child)) {
+      const childElement = child as any;
+      if (childElement.type?.displayName === "HoverCardTarget") {
+        targetNode = childElement.props.children;
+      } else if (childElement.type?.displayName === "HoverCardDropdown") {
+        dropdownNode = childElement.props.children;
+      }
+    }
+  });
+
+  if (!targetNode) {
+    // Fallback if structure is wrong
+    targetNode = <div />;
+  }
+  if (!dropdownNode) {
+    dropdownNode = <div />;
+  }
 
   return (
-    <MuiHoverCard
-      position="top" /* Recursica default; Mui defaults to "bottom" */
-      arrowSize={arrowSize}
-      withArrow={resolvedWithArrow}
-      classes={mergedClassNames}
-      {...(sanitizedProps as unknown as MuiHoverCardProps)}
-    />
+    <MuiTooltip
+      title={dropdownNode}
+      placement={position as any}
+      arrow={withBeak}
+      enterDelay={openDelay}
+      leaveDelay={closeDelay}
+      disableHoverListener={disabled}
+      slotProps={{
+        popper: {
+          modifiers: [
+            {
+              name: "offset",
+              options: {
+                offset: [0, offset],
+              },
+            },
+          ],
+        },
+      }}
+      classes={mergedClassNames as any}
+      {...(sanitizedProps as any)}
+    >
+      {/* Tooltip requires a single valid React element child that accepts a ref */}
+      {isValidElement(targetNode) ? targetNode : <span>{targetNode}</span>}
+    </MuiTooltip>
   );
 };
 HoverCardBase.displayName = "HoverCard";
@@ -104,14 +114,12 @@ HoverCardBase.displayName = "HoverCard";
 // HOVERCARD TARGET
 // ============================================================
 
-/**
- * Wrapper for the element that triggers the hover card.
- * Requires a single child element that supports ref forwarding.
- */
-export type HoverCardTargetProps = any;
+export type HoverCardTargetProps = { children?: React.ReactNode };
 
-const HoverCardTarget = function HoverCardTarget(props: HoverCardTargetProps) {
-  return <div {...props} />;
+const HoverCardTarget = function HoverCardTarget({
+  children,
+}: HoverCardTargetProps) {
+  return <>{children}</>;
 };
 HoverCardTarget.displayName = "HoverCardTarget";
 
@@ -119,23 +127,12 @@ HoverCardTarget.displayName = "HoverCardTarget";
 // HOVERCARD DROPDOWN
 // ============================================================
 
-/** The dropdown panel displayed when hovering over the target. */
-export type HoverCardDropdownProps = RecursicaOverStyled<any>;
+export type HoverCardDropdownProps = { children?: React.ReactNode };
 
 const HoverCardDropdown = function HoverCardDropdown({
-  overStyled = false,
-  ...rest
+  children,
 }: HoverCardDropdownProps) {
-  const sanitizedProps = filterStylingProps(rest, overStyled);
-  const classNameProp = (sanitizedProps as Record<string, unknown>)
-    .className as string | undefined;
-
-  return (
-    <div
-      className={classNameProp}
-      {...(sanitizedProps as unknown as MuiHoverCardDropdownProps)}
-    />
-  );
+  return <>{children}</>;
 };
 HoverCardDropdown.displayName = "HoverCardDropdown";
 

package/src/components/Label/Label.module.css

@@ -62,6 +62,10 @@
   );
 }
 
+.root :global(.MuiFormLabel-asterisk) {
+  display: none !important;
+}
+
 /* MUI propagates .Mui-error to the label automatically on FormControl error. 
    We explicitly override this bleed to prevent the main label text from turning red, 
    while allowing the asterisk to take the error color! */

package/src/components/Label/Label.stories.tsx

@@ -15,19 +15,9 @@ const meta: Meta<LabelStoryProps> = {
     docs: {
       description: {
         component:
-          "The `Label` component is a strict Recursica-styled wrapper around MUI's native `InputLabel`. It serves as the primary compositional primitive for all form fields, preserving MUI's accessibility associations and context while strictly enforcing the Recursica atomic design system.\n\n### Usage with Form Inputs\nWhen working with form structures, render this `Label` component directly above your inputs or supply it to a component's overriding properties. The component automatically maps structural layout dimensions, dynamic alignment (`left` vs `right`), custom indicator gaps, and integrates a customized `optionalText` and `withEditIcon` flow that safely bypasses MUI's native required asterisk mechanisms.",
+          "The `Label` component is a strict Recursica-styled wrapper around Mantine's native `Input.Label`. It serves as the primary compositional primitive for all form fields, preserving Mantine's accessibility associations and context while strictly enforcing the Recursica atomic design system.\n\n### Usage with Form Inputs\nWhen working with form structures, render this `Label` component directly above your inputs or supply it to a component's overriding properties. The component automatically maps structural layout dimensions, dynamic alignment (`left` vs `right`), custom indicator gaps, and integrates a customized `optionalText` and `withEditIcon` flow that safely bypasses Mantine's native required asterisk mechanisms.",
       },
     },
-    controls: {
-      include: [
-        "labelSize",
-        "labelAlignment",
-        "required",
-        "labelOptionalText",
-        "labelWithEditIcon",
-        "children",
-      ],
-    },
   },
   argTypes: {
     ...formControlArgTypes,
@@ -39,7 +29,7 @@ export default meta;
 type Story = StoryObj<LabelStoryProps>;
 
 // Utility mapping to pipe raw Label args structurally into TextField accurately
-const renderWithTextField = ({ children, ...args }: any) => (
+const renderWithTextField = ({ children, ...args }: LabelStoryProps) => (
   <TextField
     label={children as React.ReactNode}
     placeholder="Form Control primitive mapped..."
@@ -50,6 +40,7 @@ const renderWithTextField = ({ children, ...args }: any) => (
 export const Default: Story = {
   args: {
     children: "Dynamic Label (Controls)",
+
     labelSize: "default",
     labelAlignment: "left",
     required: false,
@@ -69,6 +60,7 @@ export const StackedDefault: Story = {
 export const StackedRequired: Story = {
   args: {
     children: "Primary Network Node",
+
     required: true,
   },
   render: renderWithTextField,
@@ -77,6 +69,7 @@ export const StackedRequired: Story = {
 export const StackedWithEditIcon: Story = {
   args: {
     children: "Environment Variables",
+
     labelWithEditIcon: true,
   },
   render: renderWithTextField,
@@ -85,6 +78,7 @@ export const StackedWithEditIcon: Story = {
 export const SideBySideDefault: Story = {
   args: {
     children: "Status",
+
     labelSize: "default",
   },
   render: renderWithTextField,
@@ -93,6 +87,7 @@ export const SideBySideDefault: Story = {
 export const RequiredSuppressesOptionalText: Story = {
   args: {
     children: "Full Name",
+
     required: true,
     labelOptionalText: "This should not render",
   },
@@ -102,6 +97,7 @@ export const RequiredSuppressesOptionalText: Story = {
 export const BooleanOptionalText: Story = {
   args: {
     children: "Middle Initial",
+
     labelOptionalText: true,
   },
   render: renderWithTextField,
@@ -110,6 +106,16 @@ export const BooleanOptionalText: Story = {
 export const WithEditIcon: Story = {
   args: {
     children: "Shipping Address",
+
+    labelWithEditIcon: true,
+  },
+  render: renderWithTextField,
+};
+
+export const LayerOneSideBySide: Story = {
+  args: {
+    children: "Configuration",
+
     labelWithEditIcon: true,
   },
   render: renderWithTextField,

package/src/components/Label/Label.tsx

@@ -3,16 +3,10 @@ import { InputLabel, type InputLabelProps } from "@mui/material";
 import { filterStylingProps } from "../../utils/filterStylingProps";
 import styles from "./Label.module.css";
 
-export interface LabelProps extends InputLabelProps {
+import { type RecursicaLabelProps } from "@recursica/adapter-common";
+
+export interface LabelProps extends InputLabelProps, RecursicaLabelProps {
   overStyled?: boolean;
-  /** Explicit optional text to render safely mapping alongside the label. Hidden natively if 'required' is flagged true. */
-  labelOptionalText?: React.ReactNode | true;
-  /** Triggers the inline edit action icon native layout hook beside the label element. */
-  labelWithEditIcon?: boolean;
-  /** Fires specifically on icon click natively. */
-  onLabelEditClick?: (e: React.MouseEvent<HTMLButtonElement>) => void;
-  /** Replaces the right side optional text block natively with any custom React node (e.g. actions, toggles). */
-  labelActionArea?: React.ReactNode;
 }
 
 export const Label = React.forwardRef<HTMLLabelElement, LabelProps>(

package/src/components/Link/Link.module.css

@@ -8,9 +8,8 @@ HARDCODED VALUES:
 */
 
 .root {
-  /* HARDCODE: base layout to support optional icon gaps */
-  display: inline-flex;
-  align-items: center;
+  /* HARDCODE: base layout */
+  display: inline;
   cursor: pointer;
 
   /* HARDCODE: Reset underline and color so we can explicitly use our tokens */
@@ -45,6 +44,8 @@ HARDCODED VALUES:
 }
 
 .root[data-has-icon] {
+  display: inline-flex;
+  align-items: center;
   gap: var(--recursica_ui-kit_components_link_properties_icon-text-gap);
 }
 

package/src/components/Link/Link.stories.tsx

@@ -2,17 +2,11 @@
 /* eslint-disable @typescript-eslint/no-unused-vars */
 import type { Meta, StoryObj } from "@storybook/react";
 import { Link } from "./Link";
-import { Text } from "../Text/Text";
 
 const meta: Meta<typeof Link> = {
   title: "UI-Kit/Link",
   component: Link,
   tags: ["autodocs"],
-  parameters: {
-    controls: {
-      include: ["children", "href", "icon", "component", "onClick"],
-    },
-  },
   args: {
     children: "Link text",
     href: "#",
@@ -57,8 +51,8 @@ export const Polymorphic: Story = {
 
 export const InlineText: Story = {
   render: () => (
-    <Text>
+    <p>
       Here is some text with an <Link href="#">inline link</Link> inside it.
-    </Text>
+    </p>
   ),
 };

package/src/components/Link/Link.tsx

@@ -6,11 +6,7 @@ import {
 } from "../../utils/filterStylingProps";
 import styles from "./Link.module.css";
 
-export interface RecursicaLinkProps {
-  icon?: React.ReactNode;
-  children?: React.ReactNode;
-  component?: React.ElementType;
-}
+import { type RecursicaLinkProps } from "@recursica/adapter-common";
 
 export type LinkProps = RecursicaOverStyled<
   Omit<MUILinkProps, "underline"> & RecursicaLinkProps

package/src/components/Loader/Loader.module.css

@@ -1,8 +1,7 @@
 .root {
   /* Default inheritance mapped from component variables if not explicitly overridden by variants */
   --loader-color: var(
-    --recursica_ui-kit_components_loader_properties_indicator-color,
-    currentColor
+    --recursica_ui-kit_components_loader_properties_indicator-color
   );
   box-sizing: border-box;
 }

package/src/components/Loader/Loader.tsx

@@ -2,16 +2,10 @@ import React, { forwardRef } from "react";
 import {
   filterStylingProps,
   type RecursicaOverStyled,
-  type RecursicaSize,
 } from "../../utils/filterStylingProps";
 import styles from "./Loader.module.css";
 
-export interface RecursicaLoaderProps {
-  /** Map to the component styles defined in variables */
-  variant?: "oval" | "bars" | "dots";
-  /** Map to Recursica sizes */
-  size?: "sm" | "md" | "lg" | RecursicaSize;
-}
+import { type RecursicaLoaderProps } from "@recursica/adapter-common";
 
 export type LoaderProps = RecursicaOverStyled<
   React.HTMLAttributes<HTMLSpanElement> & RecursicaLoaderProps

package/src/components/Menu/IMPLEMENTATION_NOTES.md

@@ -0,0 +1,4 @@
+# Menu Implementation Notes
+
+- **Compositional API Dropped:** Mantine uses `<Menu.Target>`, `<Menu.Dropdown>`, `<Menu.Item>`, etc., and manages state natively via React context within `<Menu>`. MUI's API is fully monolithic.
+- **Monolithic API Adopted:** Following architectural review, we have abandoned the fabricated context wrappers for `mui-adapter`. We now natively export `Menu`, `MenuItem`, and `MenuDivider` wrapping their `@mui/material` counterparts. Developers are expected to manage `anchorEl` state themselves, just like native MUI. Storybook tests have been updated to simulate this open state so visual regressions still cover the dropdown menu visually.