@machinemetrics/mm-react-components 0.2.3-2 → 0.2.3-21

package/agent-docs/component-mapping-reference.md

@@ -0,0 +1,466 @@
+# Component Mapping Reference for AI Agents
+
+## Overview
+
+This reference provides detailed mappings between Chakra UI components and MachineMetrics React Components for AI agents performing automated migrations.
+
+## Direct Component Mappings
+
+### Basic UI Components
+
+| Chakra UI   | MachineMetrics | Import                                | Notes              |
+| ----------- | -------------- | ------------------------------------- | ------------------ |
+| `Badge`     | `Badge`        | `@machinemetrics/mm-react-components` | Direct replacement |
+| `Button`    | `Button`       | `@machinemetrics/mm-react-components` | API compatible     |
+| `Input`     | `Input`        | `@machinemetrics/mm-react-components` | Direct replacement |
+| `Label`     | `Label`        | `@machinemetrics/mm-react-components` | Direct replacement |
+| `Checkbox`  | `Checkbox`     | `@machinemetrics/mm-react-components` | Direct replacement |
+| `Switch`    | `Switch`       | `@machinemetrics/mm-react-components` | Direct replacement |
+| `Slider`    | `Slider`       | `@machinemetrics/mm-react-components` | Direct replacement |
+| `Toggle`    | `Toggle`       | `@machinemetrics/mm-react-components` | Direct replacement |
+| `Skeleton`  | `Skeleton`     | `@machinemetrics/mm-react-components` | Direct replacement |
+| `Progress`  | `Progress`     | `@machinemetrics/mm-react-components` | Direct replacement |
+| `Separator` | `Separator`    | `@machinemetrics/mm-react-components` | Direct replacement |
+| `Textarea`  | `Textarea`     | `@machinemetrics/mm-react-components` | Direct replacement |
+
+### Form Components
+
+| Chakra UI         | MachineMetrics    | Import                                | Notes              |
+| ----------------- | ----------------- | ------------------------------------- | ------------------ |
+| `FormLabel`       | `Label`           | `@machinemetrics/mm-react-components` | Renamed component  |
+| `Radio`           | `RadioGroupItem`  | `@machinemetrics/mm-react-components` | Different API      |
+| `RadioGroup`      | `RadioGroup`      | `@machinemetrics/mm-react-components` | Direct replacement |
+| `Form`            | `Form`            | `@machinemetrics/mm-react-components` | New component      |
+| `FormField`       | `FormField`       | `@machinemetrics/mm-react-components` | New component      |
+| `FormItem`        | `FormItem`        | `@machinemetrics/mm-react-components` | New component      |
+| `FormControl`     | `FormControl`     | `@machinemetrics/mm-react-components` | New component      |
+| `FormDescription` | `FormDescription` | `@machinemetrics/mm-react-components` | New component      |
+| `FormMessage`     | `FormMessage`     | `@machinemetrics/mm-react-components` | New component      |
+
+### Layout Components (Manual Replacement Required)
+
+| Chakra UI    | Replacement | Tailwind Classes                                       | Notes                            |
+| ------------ | ----------- | ------------------------------------------------------ | -------------------------------- |
+| `Box`        | `<div>`     | Custom classes                                         | Add appropriate Tailwind classes |
+| `Flex`       | `<div>`     | `flex`                                                 | Add flex-related classes         |
+| `VStack`     | `<div>`     | `flex flex-col gap-4`                                  | Adjust spacing as needed         |
+| `HStack`     | `<div>`     | `flex flex-row gap-4`                                  | Adjust spacing as needed         |
+| `Stack`      | `<div>`     | `flex flex-col gap-4`                                  | Adjust direction/spacing         |
+| `Container`  | `<div>`     | `container mx-auto px-4`                               | Adjust max-width                 |
+| `Center`     | `<div>`     | `flex items-center justify-center`                     | Direct replacement               |
+| `SimpleGrid` | `<div>`     | `grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4` | Adjust columns                   |
+
+### Typography Components (Manual Replacement Required)
+
+| Chakra UI | Replacement           | Tailwind Classes                 | Notes             |
+| --------- | --------------------- | -------------------------------- | ----------------- |
+| `Heading` | `<h1>`, `<h2>`, etc.  | `font-semibold`, `text-lg`, etc. | Use semantic HTML |
+| `Text`    | `<p>`, `<span>`, etc. | Custom classes                   | Use semantic HTML |
+
+### Modal/Dialog Components
+
+| Chakra UI      | MachineMetrics  | Import                                | Notes               |
+| -------------- | --------------- | ------------------------------------- | ------------------- |
+| `Modal`        | `Dialog`        | `@machinemetrics/mm-react-components` | Renamed component   |
+| `ModalOverlay` | `DialogOverlay` | `@machinemetrics/mm-react-components` | Renamed component   |
+| `ModalContent` | `DialogContent` | `@machinemetrics/mm-react-components` | Renamed component   |
+| `ModalHeader`  | `DialogHeader`  | `@machinemetrics/mm-react-components` | Renamed component   |
+| `ModalFooter`  | `DialogFooter`  | `@machinemetrics/mm-react-components` | Renamed component   |
+| `ModalBody`    | `DialogContent` | `@machinemetrics/mm-react-components` | Merged with content |
+| `AlertDialog`  | `AlertDialog`   | `@machinemetrics/mm-react-components` | New component       |
+
+### Navigation Components
+
+| Chakra UI    | MachineMetrics | Import                                | Notes              |
+| ------------ | -------------- | ------------------------------------- | ------------------ |
+| `Menu`       | `DropdownMenu` | `@machinemetrics/mm-react-components` | Renamed component  |
+| `Tabs`       | `Tabs`         | `@machinemetrics/mm-react-components` | Direct replacement |
+| `Breadcrumb` | `Breadcrumb`   | `@machinemetrics/mm-react-components` | New component      |
+
+### Data Display Components
+
+| Chakra UI | MachineMetrics | Import                                | Notes              |
+| --------- | -------------- | ------------------------------------- | ------------------ |
+| `Table`   | `Table`        | `@machinemetrics/mm-react-components` | Direct replacement |
+| `Card`    | `Card`         | `@machinemetrics/mm-react-components` | New component      |
+| `Avatar`  | `Avatar`       | `@machinemetrics/mm-react-components` | New component      |
+| `Tooltip` | `Tooltip`      | `@machinemetrics/mm-react-components` | Direct replacement |
+| `Popover` | `Popover`      | `@machinemetrics/mm-react-components` | Direct replacement |
+
+### Feedback Components
+
+| Chakra UI | MachineMetrics | Import                                | Notes                |
+| --------- | -------------- | ------------------------------------- | -------------------- |
+| `Alert`   | `Alert`        | `@machinemetrics/mm-react-components` | New component        |
+| `Toast`   | `Toaster`      | `@machinemetrics/mm-react-components` | New component        |
+| `Spinner` | Custom         | Tailwind classes                      | Use Tailwind spinner |
+
+### Overlay Components
+
+| Chakra UI | MachineMetrics | Import                                | Notes                     |
+| --------- | -------------- | ------------------------------------- | ------------------------- |
+| `Drawer`  | `Drawer`       | `@machinemetrics/mm-react-components` | Direct replacement        |
+| `Sheet`   | `Sheet`        | `@machinemetrics/mm-react-components` | Direct replacement        |
+| `Portal`  | Custom         | React Portal                          | Use React Portal directly |
+
+### Disclosure Components
+
+| Chakra UI   | MachineMetrics | Import                                | Notes              |
+| ----------- | -------------- | ------------------------------------- | ------------------ |
+| `Collapse`  | `Collapsible`  | `@machinemetrics/mm-react-components` | Renamed component  |
+| `Accordion` | `Accordion`    | `@machinemetrics/mm-react-components` | Direct replacement |
+
+### New Components (Recently Added)
+
+| Chakra UI         | MachineMetrics                         | Import                                | Notes         |
+| ----------------- | -------------------------------------- | ------------------------------------- | ------------- |
+| `Calendar`        | `Calendar`                             | `@machinemetrics/mm-react-components` | New component |
+| `DateRangePicker` | `DateRangePicker`                      | `@machinemetrics/mm-react-components` | New component |
+| `Chart`           | `ChartContainer`, `ChartTooltip`, etc. | `@machinemetrics/mm-react-components` | New component |
+| `Dropzone`        | `Dropzone`                             | `@machinemetrics/mm-react-components` | New component |
+| `SearchInput`     | `SearchInput`                          | `@machinemetrics/mm-react-components` | New component |
+
+## Compound Component Mappings
+
+### Modal/Dialog Structure
+
+```tsx
+// Chakra UI Structure
+<Modal>
+  <ModalOverlay />
+  <ModalContent>
+    <ModalHeader>
+      <ModalTitle>Title</ModalTitle>
+      <ModalDescription>Description</ModalDescription>
+    </ModalHeader>
+    <ModalBody>Content</ModalBody>
+    <ModalFooter>
+      <ModalCloseButton />
+      <Button>Action</Button>
+    </ModalFooter>
+  </ModalContent>
+</Modal>
+
+// MachineMetrics Structure
+<Dialog>
+  <DialogTrigger>Open</DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Title</DialogTitle>
+      <DialogDescription>Description</DialogDescription>
+    </DialogHeader>
+    Content
+    <DialogFooter>
+      <DialogClose>Close</DialogClose>
+      <Button>Action</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+### Drawer Structure
+
+```tsx
+// Chakra UI Structure
+<Drawer>
+  <DrawerOverlay />
+  <DrawerContent>
+    <DrawerHeader>
+      <DrawerTitle>Title</DrawerTitle>
+      <DrawerDescription>Description</DrawerDescription>
+    </DrawerHeader>
+    <DrawerBody>Content</DrawerBody>
+    <DrawerFooter>
+      <DrawerCloseButton />
+      <Button>Action</Button>
+    </DrawerFooter>
+  </DrawerContent>
+</Drawer>
+
+// MachineMetrics Structure
+<Drawer>
+  <DrawerTrigger>Open</DrawerTrigger>
+  <DrawerContent>
+    <DrawerHeader>
+      <DrawerTitle>Title</DrawerTitle>
+      <DrawerDescription>Description</DrawerDescription>
+    </DrawerHeader>
+    Content
+    <DrawerFooter>
+      <DrawerClose>Close</DrawerClose>
+      <Button>Action</Button>
+    </DrawerFooter>
+  </DrawerContent>
+</Drawer>
+```
+
+### Accordion Structure
+
+```tsx
+// Chakra UI Structure
+<Accordion>
+  <AccordionItem>
+    <AccordionButton>Header</AccordionButton>
+    <AccordionPanel>Content</AccordionPanel>
+  </AccordionItem>
+</Accordion>
+
+// MachineMetrics Structure
+<Accordion>
+  <AccordionItem>
+    <AccordionTrigger>Header</AccordionTrigger>
+    <AccordionContent>Content</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+### Card Structure
+
+```tsx
+// Chakra UI Structure
+<Card>
+  <CardHeader>Header</CardHeader>
+  <CardBody>Content</CardBody>
+  <CardFooter>Footer</CardFooter>
+</Card>
+
+// MachineMetrics Structure
+<Card>
+  <CardHeader>
+    <CardTitle>Title</CardTitle>
+    <CardDescription>Description</CardDescription>
+  </CardHeader>
+  <CardContent>Content</CardContent>
+  <CardFooter>Footer</CardFooter>
+</Card>
+```
+
+### Form Structure
+
+```tsx
+// Chakra UI Structure
+<Form>
+  <FormControl>
+    <FormLabel>Label</FormLabel>
+    <Input />
+    <FormErrorMessage>Error</FormErrorMessage>
+  </FormControl>
+</Form>
+
+// MachineMetrics Structure
+<Form>
+  <FormField>
+    <FormItem>
+      <FormLabel>Label</FormLabel>
+      <FormControl>
+        <Input />
+      </FormControl>
+      <FormMessage>Error</FormMessage>
+    </FormItem>
+  </FormField>
+</Form>
+```
+
+## Icon Mappings
+
+### Common Icons
+
+| Chakra UI          | Lucide React     | Notes                  |
+| ------------------ | ---------------- | ---------------------- |
+| `AddIcon`          | `Plus`           | Add/create actions     |
+| `DeleteIcon`       | `Trash2`         | Delete actions         |
+| `EditIcon`         | `Edit`           | Edit actions           |
+| `SearchIcon`       | `Search`         | Search actions         |
+| `CloseIcon`        | `X`              | Close actions          |
+| `ChevronDownIcon`  | `ChevronDown`    | Dropdown indicators    |
+| `ChevronUpIcon`    | `ChevronUp`      | Dropdown indicators    |
+| `ChevronLeftIcon`  | `ChevronLeft`    | Navigation             |
+| `ChevronRightIcon` | `ChevronRight`   | Navigation             |
+| `ArrowBackIcon`    | `ArrowLeft`      | Back navigation        |
+| `ArrowForwardIcon` | `ArrowRight`     | Forward navigation     |
+| `ExternalLinkIcon` | `ExternalLink`   | External links         |
+| `DownloadIcon`     | `Download`       | Download actions       |
+| `UploadIcon`       | `Upload`         | Upload actions         |
+| `CopyIcon`         | `Copy`           | Copy actions           |
+| `CheckIcon`        | `Check`          | Success/check actions  |
+| `WarningIcon`      | `AlertTriangle`  | Warning indicators     |
+| `InfoIcon`         | `Info`           | Information indicators |
+| `StarIcon`         | `Star`           | Rating/favorites       |
+| `HeartIcon`        | `Heart`          | Favorites/likes        |
+| `SettingsIcon`     | `Settings`       | Settings/configuration |
+| `MenuIcon`         | `Menu`           | Menu/hamburger         |
+| `MoreIcon`         | `MoreHorizontal` | More options           |
+
+## Prop Mappings
+
+### Common Props
+
+| Chakra UI     | MachineMetrics | Notes            |
+| ------------- | -------------- | ---------------- |
+| `size`        | `size`         | Same API         |
+| `variant`     | `variant`      | Same API         |
+| `colorScheme` | `variant`      | Different naming |
+| `isDisabled`  | `disabled`     | Different naming |
+| `isLoading`   | `loading`      | Different naming |
+| `isOpen`      | `open`         | Different naming |
+| `onClose`     | `onOpenChange` | Different naming |
+| `placement`   | `side`         | Different naming |
+| `spacing`     | `gap`          | Different naming |
+| `direction`   | `orientation`  | Different naming |
+
+### Size Mappings
+
+| Chakra UI | MachineMetrics | Notes            |
+| --------- | -------------- | ---------------- |
+| `xs`      | `sm`           | Extra small      |
+| `sm`      | `sm`           | Small            |
+| `md`      | `default`      | Medium (default) |
+| `lg`      | `lg`           | Large            |
+| `xl`      | `lg`           | Extra large      |
+
+### Variant Mappings
+
+| Chakra UI | MachineMetrics | Notes             |
+| --------- | -------------- | ----------------- |
+| `solid`   | `default`      | Primary variant   |
+| `outline` | `outline`      | Outline variant   |
+| `ghost`   | `ghost`        | Ghost variant     |
+| `link`    | `link`         | Link variant      |
+| `subtle`  | `secondary`    | Secondary variant |
+
+## Styling Mappings
+
+### Spacing
+
+| Chakra UI | Tailwind CSS | Notes              |
+| --------- | ------------ | ------------------ |
+| `p={4}`   | `p-4`        | Padding            |
+| `m={4}`   | `m-4`        | Margin             |
+| `px={4}`  | `px-4`       | Horizontal padding |
+| `py={4}`  | `py-4`       | Vertical padding   |
+| `gap={4}` | `gap-4`      | Gap                |
+
+### Colors
+
+| Chakra UI                | Tailwind CSS      | Notes            |
+| ------------------------ | ----------------- | ---------------- |
+| `bg="blue.500"`          | `bg-blue-500`     | Background color |
+| `color="white"`          | `text-white`      | Text color       |
+| `borderColor="gray.300"` | `border-gray-300` | Border color     |
+
+### Layout
+
+| Chakra UI            | Tailwind CSS     | Notes           |
+| -------------------- | ---------------- | --------------- |
+| `display="flex"`     | `flex`           | Display flex    |
+| `direction="column"` | `flex-col`       | Flex direction  |
+| `align="center"`     | `items-center`   | Align items     |
+| `justify="center"`   | `justify-center` | Justify content |
+| `wrap="wrap"`        | `flex-wrap`      | Flex wrap       |
+
+### Responsive
+
+| Chakra UI                                 | Tailwind CSS    | Notes              |
+| ----------------------------------------- | --------------- | ------------------ |
+| `display={{ base: 'block', md: 'flex' }}` | `block md:flex` | Responsive display |
+| `p={{ base: 2, md: 4 }}`                  | `p-2 md:p-4`    | Responsive padding |
+
+## Migration Patterns
+
+### 1. Import Updates
+
+```tsx
+// Before
+import { Button, Input, Modal, Box, Flex } from '@chakra-ui/react';
+import { AddIcon } from '@chakra-ui/icons';
+
+// After
+import { Button, Input, Dialog } from '@machinemetrics/mm-react-components';
+import { Plus } from 'lucide-react';
+// Layout components become generic HTML elements
+```
+
+### 2. Component Updates
+
+```tsx
+// Before
+<Modal isOpen={isOpen} onClose={onClose}>
+  <ModalOverlay />
+  <ModalContent>
+    <ModalHeader>Title</ModalHeader>
+    <ModalBody>Content</ModalBody>
+  </ModalContent>
+</Modal>
+
+// After
+<Dialog open={isOpen} onOpenChange={setIsOpen}>
+  <DialogTrigger>Open</DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Title</DialogTitle>
+    </DialogHeader>
+    Content
+  </DialogContent>
+</Dialog>
+```
+
+### 3. Layout Updates
+
+```tsx
+// Before
+<Box p={4} bg="gray.100">
+  <Flex direction="column" gap={4}>
+    <VStack spacing={4}>
+      Content
+    </VStack>
+  </Flex>
+</Box>
+
+// After
+<div className="p-4 bg-gray-100">
+  <div className="flex flex-col gap-4">
+    <div className="flex flex-col gap-4">
+      Content
+    </div>
+  </div>
+</div>
+```
+
+### 4. Icon Updates
+
+```tsx
+// Before
+<Button>
+  <AddIcon />
+  Add Item
+</Button>
+
+// After
+<Button>
+  <Plus />
+  Add Item
+</Button>
+```
+
+## Error Handling
+
+### Common Migration Errors
+
+1. **Missing Imports**: Ensure all MachineMetrics components are imported
+2. **Layout Issues**: Replace layout components with HTML + Tailwind
+3. **Icon Issues**: Update icon imports to Lucide React
+4. **Prop Issues**: Update prop names according to mapping table
+5. **Styling Issues**: Convert Chakra props to Tailwind classes
+
+### Validation Steps
+
+1. Check all imports are updated
+2. Verify layout components are replaced
+3. Confirm icons are updated
+4. Test component functionality
+5. Verify styling is preserved
+6. Check for console errors
+
+## Conclusion
+
+This reference provides comprehensive mappings for migrating from Chakra UI to MachineMetrics React Components. Use this as a guide for automated migration tools and manual conversion processes.