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

package/agent-docs/ai-agent-guide.md

@@ -0,0 +1,558 @@
+# AI Agent Guide: Chakra UI to MachineMetrics React Components Migration
+
+## Overview
+
+This guide provides AI agents with comprehensive instructions for migrating Chakra UI components to the MachineMetrics React Components library.
+
+**Important:** MachineMetrics React Components is built on **[shadcn/ui](https://ui.shadcn.com/)**, which uses Radix UI primitives and Tailwind CSS. This means you're migrating from Chakra UI → shadcn/ui-based components with the Carbide industrial theme.
+
+This guide includes automated script usage, manual conversion procedures, and troubleshooting guidance.
+
+## Quick Start
+
+### 1. Automated Migration (Preferred)
+
+```bash
+# Run the migration script
+node scripts/chakra-to-shadcn-migrator/chakra-to-shadcn.js --apply
+```
+
+### 2. Manual Migration (When Script Fails)
+
+If the automated script fails, follow the manual conversion guide below.
+
+## Configuration File Reference
+
+The migration configuration is located at `scripts/chakra-to-shadcn-migrator/chakra-to-shadcn.config.json` and contains:
+
+- **Dependencies to Remove**: Chakra UI packages to uninstall
+- **Dependencies to Add**: New packages required for MachineMetrics components
+- **Component Mappings**: Direct component replacements
+- **Compound Components**: Complex component structure mappings
+- **Manual Migration Instructions**: Fallback conversion steps
+
+## Component Migration Mappings
+
+### Layout Components (Manual Replacement Required)
+
+| Chakra Component | Replacement                                                              | Notes                              |
+| ---------------- | ------------------------------------------------------------------------ | ---------------------------------- |
+| `Box`            | `<div>`                                                                  | Add appropriate Tailwind classes   |
+| `Flex`           | `<div className="flex">`                                                 | Add flex-related Tailwind classes  |
+| `VStack`         | `<div className="flex flex-col gap-4">`                                  | Adjust spacing as needed           |
+| `HStack`         | `<div className="flex flex-row gap-4">`                                  | Adjust spacing as needed           |
+| `Stack`          | `<div className="flex flex-col gap-4">`                                  | Adjust direction/spacing as needed |
+| `Container`      | `<div className="container mx-auto px-4">`                               | Adjust max-width as needed         |
+| `Center`         | `<div className="flex items-center justify-center">`                     | -                                  |
+| `SimpleGrid`     | `<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">` | Adjust columns as needed           |
+
+### Typography Components (Manual Replacement Required)
+
+| Chakra Component | Replacement                  | Notes                                              |
+| ---------------- | ---------------------------- | -------------------------------------------------- |
+| `Heading`        | `<h1>`, `<h2>`, `<h3>`, etc. | Use semantic HTML with Tailwind typography classes |
+| `Text`           | `<p>`, `<span>`, etc.        | Use semantic HTML with Tailwind typography classes |
+
+### Form Components (Manual Replacement Required)
+
+| Chakra Component | Replacement             | Notes                                         |
+| ---------------- | ----------------------- | --------------------------------------------- |
+| `Field`          | `<div>` wrapper         | Use shadcn/ui form components for inputs      |
+| `NumberInput`    | `<input type="number">` | Add Tailwind classes, or use shadcn/ui Input  |
+| `Slider`         | `<input type="range">`  | Add Tailwind classes, or use shadcn/ui Slider |
+| `NativeSelect`   | `<select>`              | Add Tailwind classes, or use shadcn/ui Select |
+
+### UI Components (Direct Mappings Available)
+
+| Chakra Component | MachineMetrics Component | Import Path                           |
+| ---------------- | ------------------------ | ------------------------------------- |
+| `Badge`          | `Badge`                  | `@machinemetrics/mm-react-components` |
+| `Button`         | `Button`                 | `@machinemetrics/mm-react-components` |
+| `Modal`          | `Dialog`                 | `@machinemetrics/mm-react-components` |
+| `Input`          | `Input`                  | `@machinemetrics/mm-react-components` |
+| `Menu`           | `DropdownMenu`           | `@machinemetrics/mm-react-components` |
+| `Select`         | `Select`                 | `@machinemetrics/mm-react-components` |
+| `Table`          | `Table`                  | `@machinemetrics/mm-react-components` |
+| `Tabs`           | `Tabs`                   | `@machinemetrics/mm-react-components` |
+| `Tooltip`        | `Tooltip`                | `@machinemetrics/mm-react-components` |
+| `Drawer`         | `Drawer`                 | `@machinemetrics/mm-react-components` |
+| `Switch`         | `Switch`                 | `@machinemetrics/mm-react-components` |
+| `Checkbox`       | `Checkbox`               | `@machinemetrics/mm-react-components` |
+| `Radio`          | `RadioGroupItem`         | `@machinemetrics/mm-react-components` |
+| `RadioGroup`     | `RadioGroup`             | `@machinemetrics/mm-react-components` |
+| `Label`          | `Label`                  | `@machinemetrics/mm-react-components` |
+| `FormLabel`      | `Label`                  | `@machinemetrics/mm-react-components` |
+| `Sheet`          | `Sheet`                  | `@machinemetrics/mm-react-components` |
+| `Skeleton`       | `Skeleton`               | `@machinemetrics/mm-react-components` |
+| `Collapse`       | `Collapsible`            | `@machinemetrics/mm-react-components` |
+| `Accordion`      | `Accordion`              | `@machinemetrics/mm-react-components` |
+| `Progress`       | `Progress`               | `@machinemetrics/mm-react-components` |
+| `Slider`         | `Slider`                 | `@machinemetrics/mm-react-components` |
+| `Popover`        | `Popover`                | `@machinemetrics/mm-react-components` |
+
+### New Components (Recently Added)
+
+| Chakra Component  | MachineMetrics Component               | Import Path                           |
+| ----------------- | -------------------------------------- | ------------------------------------- |
+| `Alert`           | `Alert`                                | `@machinemetrics/mm-react-components` |
+| `AlertDialog`     | `AlertDialog`                          | `@machinemetrics/mm-react-components` |
+| `Avatar`          | `Avatar`                               | `@machinemetrics/mm-react-components` |
+| `Breadcrumb`      | `Breadcrumb`                           | `@machinemetrics/mm-react-components` |
+| `Calendar`        | `Calendar`                             | `@machinemetrics/mm-react-components` |
+| `DateRangePicker` | `DateRangePicker`                      | `@machinemetrics/mm-react-components` |
+| `Form`            | `Form`                                 | `@machinemetrics/mm-react-components` |
+| `Separator`       | `Separator`                            | `@machinemetrics/mm-react-components` |
+| `Textarea`        | `Textarea`                             | `@machinemetrics/mm-react-components` |
+| `Toaster`         | `Toaster`                              | `@machinemetrics/mm-react-components` |
+| `Chart`           | `ChartContainer`, `ChartTooltip`, etc. | `@machinemetrics/mm-react-components` |
+| `Dropzone`        | `Dropzone`                             | `@machinemetrics/mm-react-components` |
+| `SearchInput`     | `SearchInput`                          | `@machinemetrics/mm-react-components` |
+
+## Compound Component Mappings
+
+### Modal/Dialog Components
+
+```tsx
+// Chakra UI
+<Modal>
+  <ModalOverlay />
+  <ModalContent>
+    <ModalHeader>Title</ModalHeader>
+    <ModalBody>Content</ModalBody>
+    <ModalFooter>Footer</ModalFooter>
+  </ModalContent>
+</Modal>
+
+// MachineMetrics Components
+<Dialog>
+  <DialogTrigger>Open</DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Title</DialogTitle>
+    </DialogHeader>
+    Content
+    <DialogFooter>Footer</DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+### Drawer Components
+
+```tsx
+// Chakra UI
+<Drawer>
+  <DrawerOverlay />
+  <DrawerContent>
+    <DrawerHeader>Title</DrawerHeader>
+    <DrawerBody>Content</DrawerBody>
+    <DrawerFooter>Footer</DrawerFooter>
+  </DrawerContent>
+</Drawer>
+
+// MachineMetrics Components
+<Drawer>
+  <DrawerTrigger>Open</DrawerTrigger>
+  <DrawerContent>
+    <DrawerHeader>
+      <DrawerTitle>Title</DrawerTitle>
+    </DrawerHeader>
+    Content
+    <DrawerFooter>Footer</DrawerFooter>
+  </DrawerContent>
+</Drawer>
+```
+
+### Accordion Components
+
+```tsx
+// Chakra UI
+<Accordion>
+  <AccordionItem>
+    <AccordionButton>Header</AccordionButton>
+    <AccordionPanel>Content</AccordionPanel>
+  </AccordionItem>
+</Accordion>
+
+// MachineMetrics Components
+<Accordion>
+  <AccordionItem>
+    <AccordionTrigger>Header</AccordionTrigger>
+    <AccordionContent>Content</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+### Card Components
+
+```tsx
+// Chakra UI
+<Card>
+  <CardHeader>Header</CardHeader>
+  <CardBody>Content</CardBody>
+  <CardFooter>Footer</CardFooter>
+</Card>
+
+// MachineMetrics Components
+<Card>
+  <CardHeader>
+    <CardTitle>Title</CardTitle>
+    <CardDescription>Description</CardDescription>
+  </CardHeader>
+  <CardContent>Content</CardContent>
+  <CardFooter>Footer</CardFooter>
+</Card>
+```
+
+## Manual Conversion Process
+
+### Step 1: Update Dependencies
+
+```bash
+# Remove Chakra UI packages
+npm uninstall @chakra-ui/react @chakra-ui/icons @chakra-ui/system @emotion/react @emotion/styled
+
+# Install MachineMetrics components
+npm install @machinemetrics/mm-react-components
+
+# Install additional dependencies
+npm install class-variance-authority tailwind-merge lucide-react
+npm install react-day-picker date-fns recharts react-dropzone sonner vaul
+npm install @radix-ui/react-avatar @radix-ui/react-breadcrumb @radix-ui/react-calendar
+npm install @radix-ui/react-alert-dialog @radix-ui/react-separator @radix-ui/react-form
+npm install @radix-ui/react-textarea @radix-ui/react-toast
+
+# Install dev dependencies
+npm install -D tailwindcss postcss autoprefixer
+```
+
+### Step 2: Update Theme Configuration
+
+```tsx
+// Remove ChakraProvider from your app root
+// Before
+import { ChakraProvider } from '@chakra-ui/react';
+
+function App() {
+  return (
+    <ChakraProvider>
+      <YourApp />
+    </ChakraProvider>
+  );
+}
+
+// After
+import '@machinemetrics/mm-react-components/themes/carbide';
+
+function App() {
+  return (
+    <div className="carbide">
+      <YourApp />
+    </div>
+  );
+}
+```
+
+### Step 3: Update Component Imports
+
+```tsx
+// Before
+import { Button, Input, Modal, Box, Flex } from '@chakra-ui/react';
+
+// After
+import { Button, Input, Dialog } from '@machinemetrics/mm-react-components';
+// Layout components become generic HTML elements with Tailwind classes
+```
+
+### Step 4: Convert Layout Components
+
+```tsx
+// Before
+<Box p={4} bg="gray.100">
+  <Flex direction="column" gap={4}>
+    <VStack spacing={4}>
+      <HStack spacing={2}>
+        Content
+      </HStack>
+    </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">
+      <div className="flex flex-row gap-2">
+        Content
+      </div>
+    </div>
+  </div>
+</div>
+```
+
+### Step 5: Convert Typography Components
+
+```tsx
+// Before
+<Heading size="lg" color="blue.500">
+  Title
+</Heading>
+<Text fontSize="sm" color="gray.600">
+  Description
+</Text>
+
+// After
+<h2 className="text-lg font-semibold text-blue-500">
+  Title
+</h2>
+<p className="text-sm text-gray-600">
+  Description
+</p>
+```
+
+### Step 6: Convert Form Components
+
+```tsx
+// Before
+<Field>
+  <FormLabel>Name</FormLabel>
+  <Input placeholder="Enter name" />
+</Field>
+
+// After
+<div>
+  <Label>Name</Label>
+  <Input placeholder="Enter name" />
+</div>
+```
+
+### Step 7: Convert UI Components
+
+```tsx
+// Before
+<Modal isOpen={isOpen} onClose={onClose}>
+  <ModalOverlay />
+  <ModalContent>
+    <ModalHeader>Title</ModalHeader>
+    <ModalBody>Content</ModalBody>
+    <ModalFooter>
+      <Button onClick={onClose}>Close</Button>
+    </ModalFooter>
+  </ModalContent>
+</Modal>
+
+// After
+<Dialog open={isOpen} onOpenChange={setIsOpen}>
+  <DialogTrigger>Open</DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Title</DialogTitle>
+    </DialogHeader>
+    Content
+    <DialogFooter>
+      <Button onClick={() => setIsOpen(false)}>Close</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+## Icon Migration
+
+### Replace Chakra Icons with Lucide React
+
+```tsx
+// Before
+import { AddIcon, DeleteIcon } from '@chakra-ui/icons'
+
+// After
+import { Plus, Trash2 } from 'lucide-react'
+
+// Usage remains the same
+<Button>
+  <AddIcon />
+  Add Item
+</Button>
+
+<Button>
+  <Plus />
+  Add Item
+</Button>
+```
+
+## Common Migration Patterns
+
+### 1. Spacing and Layout
+
+```tsx
+// Chakra UI spacing
+<Box p={4} m={2} gap={4}>
+
+// Tailwind CSS spacing
+<div className="p-4 m-2 gap-4">
+```
+
+### 2. Colors
+
+```tsx
+// Chakra UI colors
+<Box bg="blue.500" color="white">
+
+// Tailwind CSS colors
+<div className="bg-blue-500 text-white">
+```
+
+### 3. Responsive Design
+
+```tsx
+// Chakra UI responsive
+<Box display={{ base: 'block', md: 'flex' }}>
+
+// Tailwind CSS responsive
+<div className="block md:flex">
+```
+
+### 4. State Management
+
+```tsx
+// Chakra UI state
+const [isOpen, setIsOpen] = useState(false);
+
+// MachineMetrics state (same pattern)
+const [isOpen, setIsOpen] = useState(false);
+```
+
+## Troubleshooting Common Issues
+
+### 1. Missing Dependencies
+
+**Error**: `Module not found: Can't resolve '@machinemetrics/mm-react-components'`
+
+**Solution**: Install the package
+
+```bash
+npm install @machinemetrics/mm-react-components
+```
+
+### 2. Theme Not Applied
+
+**Error**: Components don't have the expected styling
+
+**Solution**: Ensure theme is imported and applied
+
+```tsx
+import '@machinemetrics/mm-react-components/themes/carbide';
+
+// Add to your app root
+<div className="carbide">
+  <YourApp />
+</div>;
+```
+
+### 3. Layout Components Not Working
+
+**Error**: Layout components like `Box`, `Flex` not found
+
+**Solution**: Replace with generic HTML elements and Tailwind classes
+
+```tsx
+// Instead of <Box>, use <div>
+// Instead of <Flex>, use <div className="flex">
+```
+
+### 4. Icons Not Displaying
+
+**Error**: Icons not showing after migration
+
+**Solution**: Update icon imports to Lucide React
+
+```tsx
+// Before
+import { AddIcon } from '@chakra-ui/icons';
+
+// After
+import { Plus } from 'lucide-react';
+```
+
+### 5. Form Components Not Working
+
+**Error**: Form components not functioning properly
+
+**Solution**: Use the new Form components from MachineMetrics
+
+```tsx
+import {
+  Form,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormControl,
+} from '@machinemetrics/mm-react-components';
+```
+
+## Validation Checklist
+
+After migration, verify:
+
+- [ ] All Chakra UI imports removed
+- [ ] MachineMetrics components imported correctly
+- [ ] Theme applied with `carbide` class
+- [ ] Layout components converted to HTML + Tailwind
+- [ ] Icons updated to Lucide React
+- [ ] Form components working correctly
+- [ ] Modal/Dialog components functioning
+- [ ] Styling matches original design
+- [ ] No console errors
+- [ ] All functionality preserved
+
+## Advanced Migration Scenarios
+
+### Custom Chakra Components
+
+If you have custom components built on Chakra UI:
+
+1. Identify the base Chakra component used
+2. Replace with equivalent MachineMetrics component
+3. Update styling to use Tailwind classes
+4. Test functionality thoroughly
+
+### Complex Layout Migrations
+
+For complex layouts:
+
+1. Break down into smaller components
+2. Convert each part individually
+3. Use Tailwind's flexbox and grid utilities
+4. Test responsive behavior
+
+### Animation Migrations
+
+For animations:
+
+1. Replace Chakra's `Fade`, `Slide` with CSS transitions
+2. Use Tailwind's animation utilities
+3. Consider Framer Motion for complex animations
+
+## Support and Resources
+
+- **Documentation**: [MachineMetrics Components Docs](https://components.machinemetrics.com)
+- **GitHub**: [Component Library Repository](https://github.com/machinemetrics/mm-react-components)
+- **Issues**: Report migration issues on GitHub
+- **Community**: Join the MachineMetrics developer community
+
+## Migration Script Usage
+
+The automated migration script can be run with:
+
+```bash
+# Preview changes (dry run)
+node scripts/chakra-to-shadcn-migrator/chakra-to-shadcn.js
+
+# Apply changes
+node scripts/chakra-to-shadcn-migrator/chakra-to-shadcn.js --apply
+
+# With verbose output
+node scripts/chakra-to-shadcn-migrator/chakra-to-shadcn.js --apply --verbose
+```
+
+## Conclusion
+
+This guide provides comprehensive instructions for migrating from Chakra UI to MachineMetrics React Components. The automated script handles most cases, but manual conversion may be necessary for complex scenarios. Always test thoroughly after migration to ensure functionality is preserved.