@machinemetrics/mm-react-components 0.2.3-3 → 0.2.3-30

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

@@ -0,0 +1,465 @@
+# AI Agent Guide: MachineMetrics React Components Initialization
+
+## 🚨 CRITICAL FOR AI AGENTS
+
+**The library uses ZERO-CONFIG setup** - no build tools required.
+
+- ✅ Use `/styles` import (pre-compiled CSS)
+- ✅ No Tailwind/PostCSS needed
+- ✅ 2 simple steps: install + CSS import
+- ✅ Works immediately
+
+## Overview
+
+This guide provides AI agents with comprehensive instructions for setting up the MachineMetrics React Components library.
+
+**Library Foundation:** Built on **[shadcn/ui](https://ui.shadcn.com/)** - re-usable components using Radix UI and Tailwind CSS, enhanced with the Carbide industrial theme.
+
+The library uses a **ZERO-CONFIG** approach - no build tools, no configuration files, just install and use.
+
+## Quick Start
+
+### 1. Automated Initialization (Recommended)
+
+```bash
+# Run the init script via npx
+npx @machinemetrics/mm-react-components init
+
+# This installs the library and sets up the CSS import
+```
+
+### 2. Manual Setup (If Script Fails)
+
+If the automated script fails, follow the manual setup guide below.
+
+## What the Init Script Does
+
+The init script performs minimal automated setup:
+
+1. **Installs the component library** - `@machinemetrics/mm-react-components`
+2. **Creates/updates CSS import** - Adds `/styles` import with pre-compiled CSS
+3. **Done!** - No build tools, no configuration files needed
+
+### What's Included
+
+The `/styles` import provides everything you need:
+
+- ✅ All Tailwind utilities (pre-compiled)
+- ✅ Carbide industrial theme
+- ✅ Dark mode support
+- ✅ All component styles (focus, hover, etc.)
+- ✅ Google Fonts
+- ✅ 118 KB CSS (18 KB gzipped)
+
+## Dependencies
+
+### Required
+
+- `@machinemetrics/mm-react-components` - Component library
+- `react` (^19.1.1) - React library
+- `react-dom` (^19.1.1) - React DOM renderer
+
+**That's it!** No build tools required.
+
+## Manual Setup
+
+### Step 1: Install the Library
+
+```bash
+# Install the component library
+npm install @machinemetrics/mm-react-components
+```
+
+### Step 2: Add CSS Import
+
+Create or update your main CSS file (usually `src/index.css` or `src/main.css`):
+
+```css
+/* MM React Components - Pre-compiled CSS */
+@import '@machinemetrics/mm-react-components/styles';
+
+/* Your existing CSS here */
+```
+
+**That's it for setup!**
+
+### Step 3: Activate Carbide Theme
+
+Add the Carbide theme class to your app root element:
+
+```tsx
+// Option 1: Add to root component
+function App() {
+  return (
+    <div className="carbide">
+      <YourApp />
+    </div>
+  );
+}
+
+// Option 2: Add via JavaScript (in your main entry file)
+document.documentElement.classList.add('carbide');
+```
+
+### Step 4: Import and Use Components
+
+```tsx
+import {
+  Button,
+  Input,
+  Card,
+  CardHeader,
+  CardTitle,
+  CardContent,
+} from '@machinemetrics/mm-react-components';
+
+function MyComponent() {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Welcome to MachineMetrics Components</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <Input placeholder="Enter your data" />
+        <Button>Submit</Button>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+**Done!** Components are ready to use.
+
+## Project Structure After Setup
+
+```
+your-project/
+├── src/
+│   ├── index.css (or main.css)
+│   └── App.tsx (or App.jsx)
+├── tailwind.config.js
+├── postcss.config.js
+├── package.json
+└── node_modules/
+    └── @machinemetrics/mm-react-components/
+```
+
+## Framework-Specific Setup
+
+### React with Vite
+
+```bash
+# Create new Vite React project
+npm create vite@latest my-app -- --template react-ts
+cd my-app
+
+# Run init script
+npx @machinemetrics/mm-react-components init
+
+# Start development server
+npm run dev
+```
+
+### Next.js
+
+```bash
+# Create new Next.js project
+npx create-next-app@latest my-app --typescript --tailwind --eslint
+cd my-app
+
+# Run init script
+npx @machinemetrics/mm-react-components init
+
+# Start development server
+npm run dev
+```
+
+### Create React App
+
+```bash
+# Create new CRA project
+npx create-react-app my-app --template typescript
+cd my-app
+
+# Run init script
+npx @machinemetrics/mm-react-components init
+
+# Start development server
+npm start
+```
+
+## Advanced Configuration
+
+### Custom Tailwind Configuration
+
+If you need to extend the Tailwind configuration:
+
+```javascript
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: [
+    './src/**/*.{js,ts,jsx,tsx}',
+    './node_modules/@machinemetrics/mm-react-components/dist/**/*.{js,ts,jsx,tsx}',
+  ],
+  theme: {
+    extend: {
+      // Your custom theme extensions
+      colors: {
+        // Custom colors
+      },
+      fontFamily: {
+        // Custom fonts
+      },
+    },
+  },
+  plugins: [
+    // Additional Tailwind plugins
+  ],
+};
+```
+
+### Custom CSS Setup
+
+For more control over CSS imports:
+
+```css
+/* src/index.css */
+@import '@machinemetrics/mm-react-components/themes/carbide';
+
+/* Custom CSS variables */
+:root {
+  --custom-primary: #your-color;
+}
+
+/* Custom component styles */
+.my-custom-component {
+  /* Your styles */
+}
+```
+
+### TypeScript Configuration
+
+If using TypeScript, ensure your `tsconfig.json` includes the component library types:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["@machinemetrics/mm-react-components"]
+  }
+}
+```
+
+## Troubleshooting Common Issues
+
+### Issue: Script Fails with "Command not found"
+
+**Cause**: NPX not installed or network issues.
+
+**Solution**:
+
+```bash
+# Install npx globally
+npm install -g npx
+
+# Or use npm directly
+npm init @machinemetrics/mm-react-components
+```
+
+### Issue: "Cannot find module" errors
+
+**Cause**: Dependencies not installed correctly.
+
+**Solution**:
+
+```bash
+# Clear npm cache
+npm cache clean --force
+
+# Delete node_modules and package-lock.json
+rm -rf node_modules package-lock.json
+
+# Reinstall dependencies
+npm install
+
+# Run init script again
+npx @machinemetrics/mm-react-components init
+```
+
+### Issue: Tailwind CSS not working
+
+**Cause**: Tailwind configuration not set up correctly.
+
+**Solution**:
+
+```bash
+# Initialize Tailwind manually
+npx tailwindcss init -p
+
+# Update tailwind.config.js with correct content paths
+# Ensure PostCSS is configured
+```
+
+### Issue: Components not styling correctly
+
+**Cause**: Carbide theme not applied or CSS not imported.
+
+**Solution**:
+
+```tsx
+// Ensure CSS is imported in your main file
+import '@machinemetrics/mm-react-components/themes/carbide';
+
+// Ensure carbide class is applied to root element
+<div className="carbide">
+  <YourApp />
+</div>;
+```
+
+### Issue: Build errors with TypeScript
+
+**Cause**: Type definitions not found.
+
+**Solution**:
+
+```bash
+# Install TypeScript definitions
+npm install -D @types/react @types/react-dom
+
+# Update tsconfig.json
+{
+  "compilerOptions": {
+    "types": ["@machinemetrics/mm-react-components"]
+  }
+}
+```
+
+### Issue: Icons not displaying
+
+**Cause**: Lucide React not installed or imported incorrectly.
+
+**Solution**:
+
+```bash
+# Install Lucide React
+npm install lucide-react
+
+# Import icons correctly
+import { Plus, Trash2 } from 'lucide-react';
+```
+
+## Validation Checklist
+
+After setup, verify the following:
+
+- [ ] `@machinemetrics/mm-react-components` is installed
+- [ ] All peer dependencies are installed
+- [ ] CSS file imports the Carbide theme
+- [ ] Tailwind CSS is configured
+- [ ] PostCSS is configured
+- [ ] Root element has `carbide` class
+- [ ] Components can be imported and used
+- [ ] Icons are displaying correctly
+- [ ] Build process works without errors
+- [ ] Development server starts successfully
+
+## Testing the Setup
+
+### Basic Component Test
+
+```tsx
+import {
+  Button,
+  Card,
+  CardContent,
+  CardHeader,
+  CardTitle,
+} from '@machinemetrics/mm-react-components';
+
+function TestComponent() {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Setup Test</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <Button>Test Button</Button>
+      </CardContent>
+    </Card>
+  );
+}
+
+export default TestComponent;
+```
+
+### Theme Test
+
+```tsx
+// Test that the Carbide theme is working
+function ThemeTest() {
+  return (
+    <div className="carbide">
+      <div className="bg-primary text-primary-foreground p-4 rounded">
+        This should have industrial styling
+      </div>
+    </div>
+  );
+}
+```
+
+## Advanced Usage
+
+### Custom Component Integration
+
+```tsx
+import { Button } from '@machinemetrics/mm-react-components';
+import { cn } from '@machinemetrics/mm-react-components';
+
+function CustomButton({ className, ...props }) {
+  return <Button className={cn('custom-styles', className)} {...props} />;
+}
+```
+
+### Theme Customization
+
+```css
+/* Override Carbide theme variables */
+.carbide {
+  --primary: #your-custom-color;
+  --secondary: #your-custom-color;
+}
+```
+
+### Build Optimization
+
+```javascript
+// vite.config.js for Vite projects
+export default {
+  optimizeDeps: {
+    include: ['@machinemetrics/mm-react-components'],
+  },
+};
+```
+
+## Support and Resources
+
+### Documentation
+
+- [Component Library Docs](https://components.machinemetrics.com)
+- [API Reference](https://components.machinemetrics.com/api)
+- [Getting Started Guide](https://components.machinemetrics.com/getting-started)
+
+### 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)
+
+### Professional Support
+
+- [MachineMetrics Support](https://support.machinemetrics.com)
+- [Enterprise Support](https://enterprise.machinemetrics.com)
+- [Consulting Services](https://consulting.machinemetrics.com)
+
+## Conclusion
+
+This guide provides comprehensive instructions for setting up the MachineMetrics React Components library. The automated init script handles most cases, but manual setup may be necessary for complex scenarios or when the script fails. Always test your setup thoroughly to ensure everything is working correctly.

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

@@ -0,0 +1,265 @@
+# Chakra UI to MachineMetrics React Components Migration
+
+This directory contains comprehensive tools and documentation for migrating from Chakra UI to the MachineMetrics React Components library.
+
+## Files Overview
+
+### Core Files
+
+- **`chakra-to-shadcn.config.json`** - Main migration configuration with component mappings
+- **`ai-agent-guide.md`** - Comprehensive guide for AI agents performing migrations
+- **`component-mapping-reference.md`** - Detailed component mapping reference
+- **`chakra-migration-troubleshooting.md`** - Common issues and solutions
+- **`README.md`** - This file
+
+## Quick Start for AI Agents
+
+### 1. Automated Migration (Preferred)
+
+```bash
+# Use the migration tool
+node scripts/chakra-to-shadcn-migrator/chakra-to-shadcn.js --apply
+```
+
+### 2. Manual Migration (When Scripts Fail)
+
+Follow the comprehensive guide in `ai-agent-guide.md` for step-by-step manual conversion.
+
+## Configuration File
+
+The `chakra-to-shadcn.config.json` file 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 Mappings
+
+### Direct Replacements (Automated)
+
+These components can be automatically migrated:
+
+- `Badge` → `Badge`
+- `Button` → `Button`
+- `Input` → `Input`
+- `Modal` → `Dialog`
+- `Menu` → `DropdownMenu`
+- `Select` → `Select`
+- `Table` → `Table`
+- `Tabs` → `Tabs`
+- `Tooltip` → `Tooltip`
+- `Drawer` → `Drawer`
+- `Switch` → `Switch`
+- `Checkbox` → `Checkbox`
+- `Radio` → `RadioGroupItem`
+- `RadioGroup` → `RadioGroup`
+- `Label` → `Label`
+- `Sheet` → `Sheet`
+- `Skeleton` → `Skeleton`
+- `Collapse` → `Collapsible`
+- `Accordion` → `Accordion`
+- `Progress` → `Progress`
+- `Slider` → `Slider`
+- `Popover` → `Popover`
+
+### New Components (Recently Added)
+
+- `Alert` → `Alert`
+- `AlertDialog` → `AlertDialog`
+- `Avatar` → `Avatar`
+- `Breadcrumb` → `Breadcrumb`
+- `Calendar` → `Calendar`
+- `DateRangePicker` → `DateRangePicker`
+- `Form` → `Form`
+- `Separator` → `Separator`
+- `Textarea` → `Textarea`
+- `Toaster` → `Toaster`
+- `Chart` → `ChartContainer`, `ChartTooltip`, etc.
+- `Dropzone` → `Dropzone`
+- `SearchInput` → `SearchInput`
+
+### Manual Replacements Required
+
+These components need manual conversion to HTML + Tailwind:
+
+- `Box` → `<div>` with Tailwind classes
+- `Flex` → `<div className="flex">` with flex classes
+- `VStack` → `<div className="flex flex-col gap-4">`
+- `HStack` → `<div className="flex flex-row gap-4">`
+- `Stack` → `<div className="flex flex-col gap-4">`
+- `Container` → `<div className="container mx-auto px-4">`
+- `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">`
+- `Heading` → `<h1>`, `<h2>`, etc. with Tailwind typography
+- `Text` → `<p>`, `<span>`, etc. with Tailwind typography
+
+## Migration 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';
+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 with Tailwind classes
+```
+
+### Step 4: Convert Components
+
+```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>
+```
+
+## Usage Examples
+
+### Basic Migration
+
+```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
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Missing Dependencies**: Install all required packages
+2. **Theme Not Applied**: Ensure Carbide theme is imported and applied
+3. **Layout Components**: Replace with HTML + Tailwind classes
+4. **Icons Not Working**: Update to Lucide React icons
+5. **Form Components**: Use new Form component structure
+
+### Debugging
+
+```bash
+# Check for errors
+npm run lint
+
+# Test components
+npm run test
+
+# Build project
+npm run build
+```
+
+## 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
+
+## 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
+
+## File Descriptions
+
+### `chakra-to-shadcn.config.json`
+
+Main configuration file containing all component mappings, dependencies, and migration instructions.
+
+
+### `ai-agent-guide.md`
+
+Comprehensive guide for AI agents performing migrations. Includes step-by-step instructions, examples, and best practices.
+
+### `component-mapping-reference.md`
+
+Detailed reference for all component mappings, including props, styling, and usage examples.
+
+### `chakra-migration-troubleshooting.md`
+
+Common issues and solutions encountered during migration, with debugging tips and prevention strategies.
+
+## Conclusion
+
+This migration toolkit provides everything needed to migrate from Chakra UI to MachineMetrics React Components. The automated tools handle most cases, but manual conversion may be necessary for complex scenarios. Always test thoroughly after migration to ensure functionality is preserved.