@machinemetrics/mm-react-components 0.2.3-0 → 0.2.3-10

package/agent-docs/chakra-migration-troubleshooting.md

@@ -0,0 +1,649 @@
+# Troubleshooting Guide: Chakra UI to MachineMetrics Migration
+
+## Common Issues and Solutions
+
+### 1. Import Errors
+
+#### Error: `Module not found: Can't resolve '@machinemetrics/mm-react-components'`
+
+**Cause**: Package not installed or incorrect import path.
+
+**Solution**:
+
+```bash
+npm install @machinemetrics/mm-react-components
+```
+
+**Verification**:
+
+```tsx
+import { Button, Input } from '@machinemetrics/mm-react-components';
+```
+
+#### Error: `Module not found: Can't resolve 'lucide-react'`
+
+**Cause**: Lucide React not installed for icon replacements.
+
+**Solution**:
+
+```bash
+npm install lucide-react
+```
+
+**Verification**:
+
+```tsx
+import { Plus, Trash2 } from 'lucide-react';
+```
+
+#### Error: `Module not found: Can't resolve '@radix-ui/react-*'`
+
+**Cause**: Missing Radix UI dependencies for specific components.
+
+**Solution**:
+
+```bash
+# Install required Radix UI packages
+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
+```
+
+### 2. Theme and Styling Issues
+
+#### Issue: Components don't have expected styling
+
+**Cause**: Carbide theme not imported or applied.
+
+**Solution**:
+
+```tsx
+// Import theme in your main entry file
+import '@machinemetrics/mm-react-components/themes/carbide';
+
+// Apply theme class to your app root
+function App() {
+  return (
+    <div className="carbide">
+      <YourApp />
+    </div>
+  );
+}
+```
+
+#### Issue: Dark mode not working
+
+**Cause**: Dark mode class not applied.
+
+**Solution**:
+
+```tsx
+// Apply both theme and dark mode classes
+<div className="carbide dark">
+  <YourApp />
+</div>
+```
+
+#### Issue: Custom colors not working
+
+**Cause**: Using Chakra color tokens instead of Tailwind classes.
+
+**Solution**:
+
+```tsx
+// Before (Chakra)
+<Box bg="blue.500" color="white">
+
+// After (Tailwind)
+<div className="bg-blue-500 text-white">
+```
+
+### 3. Layout Component Issues
+
+#### Error: `Box is not defined`
+
+**Cause**: Layout components need manual replacement.
+
+**Solution**:
+
+```tsx
+// Before
+<Box p={4} bg="gray.100">
+  Content
+</Box>
+
+// After
+<div className="p-4 bg-gray-100">
+  Content
+</div>
+```
+
+#### Error: `Flex is not defined`
+
+**Cause**: Flex component needs manual replacement.
+
+**Solution**:
+
+```tsx
+// Before
+<Flex direction="column" gap={4}>
+  Content
+</Flex>
+
+// After
+<div className="flex flex-col gap-4">
+  Content
+</div>
+```
+
+#### Error: `VStack is not defined`
+
+**Cause**: VStack component needs manual replacement.
+
+**Solution**:
+
+```tsx
+// Before
+<VStack spacing={4}>
+  Content
+</VStack>
+
+// After
+<div className="flex flex-col gap-4">
+  Content
+</div>
+```
+
+### 4. Component API Issues
+
+#### Error: `Modal is not defined`
+
+**Cause**: Modal component renamed to Dialog.
+
+**Solution**:
+
+```tsx
+// Before
+import { Modal, ModalOverlay, ModalContent } from '@chakra-ui/react';
+
+// After
+import {
+  Dialog,
+  DialogTrigger,
+  DialogContent,
+} from '@machinemetrics/mm-react-components';
+```
+
+#### Error: `Menu is not defined`
+
+**Cause**: Menu component renamed to DropdownMenu.
+
+**Solution**:
+
+```tsx
+// Before
+import { Menu, MenuButton, MenuList, MenuItem } from '@chakra-ui/react';
+
+// After
+import {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+} from '@machinemetrics/mm-react-components';
+```
+
+#### Error: `FormLabel is not defined`
+
+**Cause**: FormLabel component renamed to Label.
+
+**Solution**:
+
+```tsx
+// Before
+import { FormLabel } from '@chakra-ui/react';
+
+// After
+import { Label } from '@machinemetrics/mm-react-components';
+```
+
+### 5. Icon Issues
+
+#### Error: `AddIcon is not defined`
+
+**Cause**: Chakra icons replaced with Lucide React.
+
+**Solution**:
+
+```tsx
+// Before
+import { AddIcon, DeleteIcon } from '@chakra-ui/icons';
+
+// After
+import { Plus, Trash2 } from 'lucide-react';
+```
+
+#### Issue: Icons not displaying
+
+**Cause**: Icon component not properly imported or used.
+
+**Solution**:
+
+```tsx
+// Ensure proper import
+import { Plus } from 'lucide-react';
+
+// Use as JSX element
+<Button>
+  <Plus className="w-4 h-4" />
+  Add Item
+</Button>;
+```
+
+### 6. Form Component Issues
+
+#### Error: Form components not working
+
+**Cause**: Form API changed significantly.
+
+**Solution**:
+
+```tsx
+// Before (Chakra)
+<FormControl>
+  <FormLabel>Name</FormLabel>
+  <Input />
+  <FormErrorMessage>Error</FormErrorMessage>
+</FormControl>
+
+// After (MachineMetrics)
+<FormField>
+  <FormItem>
+    <FormLabel>Name</FormLabel>
+    <FormControl>
+      <Input />
+    </FormControl>
+    <FormMessage>Error</FormMessage>
+  </FormItem>
+</FormField>
+```
+
+#### Issue: Form validation not working
+
+**Cause**: Form validation API changed.
+
+**Solution**:
+
+```tsx
+// Use the new Form component structure
+import {
+  Form,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormControl,
+  FormMessage,
+} from '@machinemetrics/mm-react-components';
+
+// Implement with proper form structure
+<Form>
+  <FormField>
+    <FormItem>
+      <FormLabel>Field Label</FormLabel>
+      <FormControl>
+        <Input />
+      </FormControl>
+      <FormMessage />
+    </FormItem>
+  </FormField>
+</Form>;
+```
+
+### 7. State Management Issues
+
+#### Issue: Modal state not working
+
+**Cause**: Modal state API changed.
+
+**Solution**:
+
+```tsx
+// Before (Chakra)
+const [isOpen, setIsOpen] = useState(false)
+
+<Modal isOpen={isOpen} onClose={() => setIsOpen(false)}>
+  Content
+</Modal>
+
+// After (MachineMetrics)
+const [isOpen, setIsOpen] = useState(false)
+
+<Dialog open={isOpen} onOpenChange={setIsOpen}>
+  <DialogTrigger>Open</DialogTrigger>
+  <DialogContent>
+    Content
+  </DialogContent>
+</Dialog>
+```
+
+#### Issue: Drawer state not working
+
+**Cause**: Drawer state API changed.
+
+**Solution**:
+
+```tsx
+// Before (Chakra)
+const [isOpen, setIsOpen] = useState(false)
+
+<Drawer isOpen={isOpen} onClose={() => setIsOpen(false)}>
+  Content
+</Drawer>
+
+// After (MachineMetrics)
+const [isOpen, setIsOpen] = useState(false)
+
+<Drawer open={isOpen} onOpenChange={setIsOpen}>
+  <DrawerTrigger>Open</DrawerTrigger>
+  <DrawerContent>
+    Content
+  </DrawerContent>
+</Drawer>
+```
+
+### 8. Styling Issues
+
+#### Issue: Spacing not working
+
+**Cause**: Chakra spacing props not converted to Tailwind.
+
+**Solution**:
+
+```tsx
+// Before (Chakra)
+<Box p={4} m={2} gap={4}>
+
+// After (Tailwind)
+<div className="p-4 m-2 gap-4">
+```
+
+#### Issue: Colors not working
+
+**Cause**: Chakra color tokens not converted to Tailwind.
+
+**Solution**:
+
+```tsx
+// Before (Chakra)
+<Box bg="blue.500" color="white">
+
+// After (Tailwind)
+<div className="bg-blue-500 text-white">
+```
+
+#### Issue: Responsive design not working
+
+**Cause**: Chakra responsive props not converted to Tailwind.
+
+**Solution**:
+
+```tsx
+// Before (Chakra)
+<Box display={{ base: 'block', md: 'flex' }}>
+
+// After (Tailwind)
+<div className="block md:flex">
+```
+
+### 9. Animation Issues
+
+#### Issue: Animations not working
+
+**Cause**: Chakra animations not available in MachineMetrics.
+
+**Solution**:
+
+```tsx
+// Use Tailwind animations or CSS transitions
+<div className="transition-all duration-300 ease-in-out">Content</div>
+```
+
+#### Issue: Fade animations not working
+
+**Cause**: Chakra Fade component not available.
+
+**Solution**:
+
+```tsx
+// Use CSS transitions with conditional classes
+<div
+  className={`transition-opacity duration-300 ${isVisible ? 'opacity-100' : 'opacity-0'}`}
+>
+  Content
+</div>
+```
+
+### 10. Build Issues
+
+#### Error: Build fails with missing dependencies
+
+**Cause**: Missing required dependencies.
+
+**Solution**:
+
+```bash
+# Install all required dependencies
+npm install @machinemetrics/mm-react-components
+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
+npm install -D tailwindcss postcss autoprefixer
+```
+
+#### Error: TypeScript errors
+
+**Cause**: Type definitions not found.
+
+**Solution**:
+
+```bash
+# Install TypeScript definitions
+npm install -D @types/react @types/react-dom
+```
+
+#### Error: Tailwind CSS not working
+
+**Cause**: Tailwind CSS not configured.
+
+**Solution**:
+
+```bash
+# Initialize Tailwind CSS
+npx tailwindcss init -p
+```
+
+**Update tailwind.config.js**:
+
+```javascript
+module.exports = {
+  content: ['./src/**/*.{js,ts,jsx,tsx}'],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+};
+```
+
+### 11. Performance Issues
+
+#### Issue: Bundle size increased
+
+**Cause**: Additional dependencies added.
+
+**Solution**:
+
+```bash
+# Analyze bundle size
+npm run build -- --analyze
+
+# Use tree shaking for unused components
+import { Button } from '@machinemetrics/mm-react-components'
+// Instead of
+import * as Components from '@machinemetrics/mm-react-components'
+```
+
+#### Issue: Slow build times
+
+**Cause**: Additional dependencies and processing.
+
+**Solution**:
+
+```bash
+# Use build caching
+npm run build -- --cache
+
+# Optimize imports
+import { Button, Input } from '@machinemetrics/mm-react-components'
+// Instead of importing entire library
+```
+
+### 12. Testing Issues
+
+#### Issue: Tests failing after migration
+
+**Cause**: Component APIs changed.
+
+**Solution**:
+
+```tsx
+// Update test imports
+import { render, screen } from '@testing-library/react';
+import { Button } from '@machinemetrics/mm-react-components';
+
+// Update test selectors
+// Before
+screen.getByRole('button', { name: /add/i });
+
+// After (if API changed)
+screen.getByRole('button', { name: /add/i });
+```
+
+#### Issue: Visual regression tests failing
+
+**Cause**: Component styling changed.
+
+**Solution**:
+
+```bash
+# Update visual test baselines
+npm run test:visual -- --update-snapshots
+
+# Review and approve changes
+npm run test:visual -- --review
+```
+
+## Debugging Tools
+
+### 1. Console Debugging
+
+```tsx
+// Add debug logging
+console.log('Component props:', props);
+console.log('Component state:', state);
+
+// Use React DevTools
+// Install React DevTools browser extension
+```
+
+### 2. Network Debugging
+
+```bash
+# Check network requests
+# Open browser DevTools > Network tab
+# Look for failed requests or missing resources
+```
+
+### 3. Build Debugging
+
+```bash
+# Verbose build output
+npm run build -- --verbose
+
+# Check for specific errors
+npm run build 2>&1 | grep -i error
+```
+
+### 4. Dependency Debugging
+
+```bash
+# Check installed packages
+npm list
+
+# Check for version conflicts
+npm ls --depth=0
+
+# Check for missing dependencies
+npm audit
+```
+
+## Prevention Strategies
+
+### 1. Gradual Migration
+
+```tsx
+// Migrate components one at a time
+// Start with simple components (Button, Input)
+// Then move to complex components (Modal, Form)
+```
+
+### 2. Testing Strategy
+
+```tsx
+// Write tests before migration
+// Test component functionality
+// Test visual appearance
+// Test responsive behavior
+```
+
+### 3. Documentation
+
+```tsx
+// Document migration decisions
+// Keep track of component mappings
+// Note any customizations needed
+```
+
+### 4. Code Review
+
+```tsx
+// Review all migration changes
+// Ensure functionality is preserved
+// Verify styling is correct
+// Check for performance issues
+```
+
+## Getting Help
+
+### 1. Documentation
+
+- [MachineMetrics Components Docs](https://components.machinemetrics.com)
+- [Component API Reference](https://components.machinemetrics.com/api)
+- [Migration Guide](https://components.machinemetrics.com/migration)
+
+### 2. Community Support
+
+- [GitHub Issues](https://github.com/machinemetrics/mm-react-components/issues)
+- [Discord Community](https://discord.gg/machinemetrics)
+- [Stack Overflow](https://stackoverflow.com/questions/tagged/machinemetrics)
+
+### 3. Professional Support
+
+- [MachineMetrics Support](https://support.machinemetrics.com)
+- [Enterprise Support](https://enterprise.machinemetrics.com)
+- [Consulting Services](https://consulting.machinemetrics.com)
+
+## Conclusion
+
+This troubleshooting guide covers the most common issues encountered during Chakra UI to MachineMetrics migration. Follow the solutions provided and use the debugging tools to resolve any issues. For additional help, refer to the documentation or contact support.