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

package/README.md

@@ -17,39 +17,89 @@ A comprehensive React component library designed specifically for MachineMetrics
 npm install @machinemetrics/mm-react-components
 ```
 
+**Required Dependencies:**
+
+- React 19+
+- React DOM 19+
+
+**Optional Dependencies (only if using `/themes/carbide`):**
+
+- Tailwind CSS 4.0+
+- PostCSS 8.5+
+- Autoprefixer 10+
+
+> 💡 **Note:** When using `/styles` (recommended), no build tools are required! The CSS is fully compiled.
+
 ## Quick Start
 
-### 1. Install Dependencies
+### 🚀 Automated Setup (Recommended)
+
+The fastest way to get started:
 
 ```bash
-npm install @machinemetrics/mm-react-components tailwindcss postcss autoprefixer
+# Install the package
+npm install @machinemetrics/mm-react-components
+
+# Run the automated setup
+npx @machinemetrics/mm-react-components/setup
 ```
 
-### 2. Configure Tailwind CSS
+This will automatically:
+
+- ✅ Copy Tailwind configuration
+- ✅ Create PostCSS configuration
+- ✅ Set up the complete theme
+- ✅ Create an example component
+- ✅ Generate all necessary files
+
+### 📋 Manual Setup
 
-Copy the Tailwind configuration to your project:
+If you prefer manual setup:
+
+#### 1. Install the Library
+
+```bash
+npm install @machinemetrics/mm-react-components
+```
+
+**Optional:** Only install Tailwind if you want to use `/themes/carbide` instead of `/styles`:
+
+```bash
+npm install -D tailwindcss postcss autoprefixer
+```
+
+#### 2. (Optional) Configure Tailwind CSS
+
+> 💡 Skip this step if using `/styles` - Tailwind configuration is not needed!
+
+**Only if using `/themes/carbide`:**
 
 ```bash
 cp node_modules/@machinemetrics/mm-react-components/tailwind.config.export.js tailwind.config.js
 ```
 
-### 3. Import Complete Theme (Recommended)
+Note: The exported config is the main config (no preview-only utilities). The preview app in this repo uses a separate `tailwind.preview.config.js` that imports the main config and adds preview utilities.
 
-```css
-/* In your main CSS file - one import gets everything! */
-@import '@machinemetrics/mm-react-components/themes/complete';
+#### 3. Import Styles
+
+Import the complete styles including Tailwind CSS, base styles, and Carbide theme:
+
+```ts
+// In your main entry (e.g., src/main.tsx)
+import '@machinemetrics/mm-react-components/styles';
+document.documentElement.classList.add('carbide');
 ```
 
-**That's it!** This single import includes:
+**What's included in `/styles` (118 KB, 18 KB gzipped):**
 
-- ✅ Tailwind CSS reset
+- ✅ Tailwind CSS reset and utilities (compiled)
 - ✅ Base theme variables (OKLCH color system)
 - ✅ Carbide industrial theme
-- ✅ All component styles
+- ✅ All component styles (focus states, rings, borders, etc.)
 - ✅ Dark mode support
 - ✅ Animations and utilities
 
-### 4. Use Components
+#### 4. Use Components
 
 ```tsx
 import { Button, Input } from '@machinemetrics/mm-react-components';
@@ -64,9 +114,11 @@ function App() {
 }
 ```
 
-### 5. Complete Setup Guide
+### 📚 Documentation
 
-For detailed setup instructions and alternative import methods, see the [Tailwind Setup Guide](./docs/TAILWIND_SETUP.md).
+- [Getting Started Guide](./docs/GETTING_STARTED.md) - Complete setup guide
+- [Tailwind Setup Guide](./docs/TAILWIND_SETUP.md) - Detailed configuration
+- [Quick Start Template](./templates/quick-start.html) - Live demo
 
 ## Theme System
 
@@ -86,23 +138,40 @@ The component library includes a comprehensive theme system with two main themes
 - Enhanced component styling for industrial applications
 - Complete dark mode support
 
-### Using Themes
+### Import Options
 
-#### Option 1: Complete Theme (Recommended)
+#### Option 1: Complete Styles (Recommended - 118 KB gzipped)
 
-```css
-/* One import gets everything - easiest setup */
-@import '@machinemetrics/mm-react-components/themes/complete';
+Import everything including Tailwind utilities, theme, and animations:
+
+```ts
+import '@machinemetrics/mm-react-components/styles';
+document.documentElement.classList.add('carbide');
 ```
 
-#### Option 2: Manual Theme Import
+**Includes:**
 
-```css
-/* Import themes separately for more control */
-@import '@machinemetrics/mm-react-components/themes/base';
-@import '@machinemetrics/mm-react-components/themes/carbide';
+- ✅ All Tailwind utilities (compiled)
+- ✅ Carbide theme variables
+- ✅ Component styles with focus states
+- ✅ Dark mode support
+- ✅ Animations
+
+#### Option 2: Theme Only (41 KB - if you already have Tailwind)
+
+Import just the Carbide theme variables and component overrides:
+
+```ts
+import '@machinemetrics/mm-react-components/themes/carbide';
+document.documentElement.classList.add('carbide');
 ```
 
+**Use this if:**
+
+- You already have Tailwind CSS in your project
+- You want to minimize bundle size
+- You're using our components with your own Tailwind config
+
 #### Option 3: Use Theme Utilities
 
 ```tsx
@@ -213,16 +282,13 @@ This includes:
 ### Alternative Import Methods
 
 ```css
-/* Import base theme only */
-@import '@machinemetrics/mm-react-components/themes/base';
-
-/* Import Carbide theme for industrial styling */
-@import '@machinemetrics/mm-react-components/themes/carbide';
+/* Import complete styles including Carbide theme */
+@import '@machinemetrics/mm-react-components/styles';
 ```
 
 ```tsx
 // Import in JavaScript/TypeScript
-import '@machinemetrics/mm-react-components/themes/complete';
+import '@machinemetrics/mm-react-components/styles';
 ```
 
 ## TypeScript Support

package/agent-docs/agent-documentation-reference.md

@@ -0,0 +1,247 @@
+# AI Agent Documentation Reference
+
+## Overview
+
+This directory contains comprehensive documentation and tools for AI agents working with the MachineMetrics React Components library. The documentation is organized into two main categories: **Initialization Setup** and **Chakra UI Migration**.
+
+## Directory Structure
+
+```
+agent-docs/
+├── agent-documentation-reference.md    # This reference file
+├── ai-agent-init-guide.md              # Main init setup guide
+├── setup-reference.md                  # Detailed setup reference
+├── init-troubleshooting.md             # Init setup troubleshooting
+├── init-readme.md                      # Init setup overview
+├── ai-agent-guide.md                   # Chakra migration guide
+├── component-mapping-reference.md      # Chakra migration reference
+├── chakra-migration-troubleshooting.md # Chakra migration troubleshooting
+└── chakra-migration-readme.md          # Chakra migration overview
+```
+
+## Documentation Categories
+
+### 1. Initialization Setup Documentation
+
+#### **ai-agent-init-guide.md**
+
+- **Purpose**: Comprehensive guide for AI agents on library setup
+- **Use Case**: When AI agents need to initialize the MachineMetrics React Components library
+- **Key Features**:
+  - Zero-config setup (no build tools required)
+  - Automated setup procedures
+  - Framework-specific instructions (React, Next.js, Vite)
+  - Troubleshooting guidance
+  - Validation checklists
+- **Target Audience**: AI agents performing automated setup
+- **When to Use**: Primary resource for init script setup
+
+#### **setup-reference.md**
+
+- **Purpose**: Detailed reference for setup procedures
+- **Use Case**: When AI agents need specific technical details about setup
+- **Key Features**:
+  - Complete dependency list
+  - Configuration file templates
+  - Framework-specific setup instructions
+  - Component usage patterns
+  - Performance optimization
+- **Target Audience**: AI agents needing technical reference
+- **When to Use**: Technical reference during setup or troubleshooting
+
+#### **init-troubleshooting.md**
+
+- **Purpose**: Common issues and solutions for init script problems
+- **Use Case**: When the init script fails or encounters issues
+- **Key Features**:
+  - Script execution issues
+  - Dependency installation problems
+  - Configuration issues
+  - Build and runtime problems
+  - Framework-specific troubleshooting
+- **Target Audience**: AI agents debugging setup issues
+- **When to Use**: When automated setup fails or encounters errors
+
+#### **init-readme.md**
+
+- **Purpose**: Overview and usage instructions for init setup
+- **Use Case**: Quick reference for init setup process
+- **Key Features**:
+  - Quick start instructions
+  - File descriptions
+  - Usage examples
+  - Validation steps
+- **Target Audience**: AI agents needing quick overview
+- **When to Use**: Initial understanding of init setup process
+
+### 2. Chakra UI Migration Documentation
+
+#### **ai-agent-guide.md**
+
+- **Purpose**: Comprehensive guide for AI agents on Chakra UI to MachineMetrics migration
+- **Use Case**: When AI agents need to migrate existing Chakra UI components
+- **Key Features**:
+  - Automated migration procedures
+  - Manual conversion steps
+  - Component mapping instructions
+  - Icon migration guidance
+  - Validation checklists
+- **Target Audience**: AI agents performing Chakra UI migration
+- **When to Use**: Primary resource for Chakra UI migration
+
+#### **component-mapping-reference.md**
+
+- **Purpose**: Detailed reference of component mappings for Chakra UI migration
+- **Use Case**: When AI agents need specific component mapping information
+- **Key Features**:
+  - Complete component mapping tables
+  - Prop mapping references
+  - Styling conversion guides
+  - Icon mapping tables
+  - Migration patterns
+- **Target Audience**: AI agents needing component mapping details
+- **When to Use**: Technical reference during Chakra UI migration
+
+#### **chakra-migration-troubleshooting.md**
+
+- **Purpose**: Common issues and solutions for Chakra UI migration problems
+- **Use Case**: When Chakra UI migration encounters issues
+- **Key Features**:
+  - Import errors and solutions
+  - Theme and styling issues
+  - Layout problems
+  - API changes
+  - Icon issues
+  - Form component problems
+- **Target Audience**: AI agents debugging migration issues
+- **When to Use**: When Chakra UI migration fails or encounters errors
+
+#### **chakra-migration-readme.md**
+
+- **Purpose**: Overview and usage instructions for Chakra UI migration
+- **Use Case**: Quick reference for Chakra UI migration process
+- **Key Features**:
+  - Migration overview
+  - File descriptions
+  - Usage examples
+  - Troubleshooting tips
+- **Target Audience**: AI agents needing quick migration overview
+- **When to Use**: Initial understanding of Chakra UI migration process
+
+## Usage Patterns
+
+### For AI Agents
+
+#### **Initialization Setup Workflow**
+
+1. **Start with**: `ai-agent-init-guide.md` for comprehensive setup instructions
+2. **Reference**: `setup-reference.md` for technical details
+3. **Troubleshoot**: `init-troubleshooting.md` if issues arise
+4. **Overview**: `init-readme.md` for quick reference
+
+#### **Chakra UI Migration Workflow**
+
+1. **Start with**: `ai-agent-guide.md` for comprehensive migration instructions
+2. **Reference**: `component-mapping-reference.md` for component details
+3. **Troubleshoot**: `chakra-migration-troubleshooting.md` if issues arise
+4. **Overview**: `chakra-migration-readme.md` for quick reference
+
+### For Developers
+
+#### **Quick Start**
+
+- Use `init-readme.md` for setup overview
+- Use `chakra-migration-readme.md` for migration overview
+
+#### **Detailed Implementation**
+
+- Use `ai-agent-init-guide.md` for setup implementation
+- Use `ai-agent-guide.md` for migration implementation
+
+#### **Troubleshooting**
+
+- Use `init-troubleshooting.md` for setup issues
+- Use `chakra-migration-troubleshooting.md` for migration issues
+
+## File Relationships
+
+### **Init Setup Files**
+
+```
+ai-agent-init-guide.md (main guide)
+├── setup-reference.md (technical reference)
+├── init-troubleshooting.md (issue resolution)
+└── init-readme.md (overview)
+```
+
+### **Chakra Migration Files**
+
+```
+ai-agent-guide.md (main guide)
+├── component-mapping-reference.md (technical reference)
+├── chakra-migration-troubleshooting.md (issue resolution)
+└── chakra-migration-readme.md (overview)
+```
+
+## Package.json Exports
+
+The following files are exported via package.json for AI agent access:
+
+### **Init Setup Exports**
+
+- `./init/guide` → `ai-agent-init-guide.md`
+- `./init/reference` → `setup-reference.md`
+- `./init/troubleshooting` → `init-troubleshooting.md`
+- `./init/readme` → `init-readme.md`
+
+### **Chakra Migration Exports**
+
+- `./migration/config` → `chakra-to-shadcn.config.json`
+- `./migration/guide` → `ai-agent-guide.md`
+- `./migration/reference` → `component-mapping-reference.md`
+- `./migration/troubleshooting` → `chakra-migration-troubleshooting.md`
+- `./migration/readme` → `chakra-migration-readme.md`
+
+## Best Practices
+
+### **For AI Agents**
+
+1. **Always start with the main guide** for comprehensive instructions
+2. **Use reference files** for technical details and specific information
+3. **Check troubleshooting guides** when issues arise
+4. **Use fallback scripts** when automated tools fail
+5. **Validate setup** using provided checklists
+
+### **For Documentation Maintenance**
+
+1. **Keep guides updated** with new components and features
+2. **Update troubleshooting guides** with new issues and solutions
+3. **Maintain reference files** with current dependency versions
+4. **Test fallback scripts** regularly to ensure they work
+5. **Update package.json exports** when adding new files
+
+## 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 documentation reference provides a comprehensive overview of all AI agent documentation and tools available for the MachineMetrics React Components library. Use this as a guide to understand which files to use for specific tasks and how they relate to each other.
+
+For AI agents, this reference ensures you have access to all necessary documentation and tools to successfully set up and migrate components. For developers, this reference provides a clear understanding of the available resources and how to use them effectively.