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

package/agent-docs/init-readme.md

@@ -0,0 +1,283 @@
+# MachineMetrics React Components - Initialization Setup
+
+## Overview
+
+This directory contains comprehensive documentation and tools for setting up the MachineMetrics React Components library. It includes automated scripts, manual setup guides, and troubleshooting resources for AI agents and developers.
+
+## Files in This Directory
+
+### Documentation Files
+
+- **`ai-agent-init-guide.md`** - Comprehensive guide for AI agents on how to set up and use the init script
+- **`setup-reference.md`** - Detailed reference for dependencies, configuration files, and setup procedures
+- **`init-troubleshooting.md`** - Common issues and solutions for init script problems
+- **`README.md`** - This overview file
+
+### Scripts and Tools
+
+- **`init.cjs`** - Main initialization script (in `scripts/` directory)
+- **`npx-init.cjs`** - NPX-specific initialization script (in `scripts/` directory)
+
+## Quick Start
+
+### 1. Automated Setup (Preferred)
+
+```bash
+# Run the main init script
+npx @machinemetrics/mm-react-components init
+
+# Or use the direct script
+npx mm-init
+```
+
+### 2. Manual Setup (Complete Control)
+
+Follow the detailed instructions in `ai-agent-init-guide.md` for step-by-step manual setup.
+
+## What Gets Set Up
+
+### Dependencies Installed
+
+- **Core Library**: `@machinemetrics/mm-react-components`
+- **Peer Dependencies**: `class-variance-authority`, `clsx`, `tailwind-merge`, `@radix-ui/react-slot`, `lucide-react`
+- **Build Dependencies**: `tailwindcss`, `autoprefixer`, `postcss`
+- **TypeScript Dependencies**: `@types/react`, `@types/react-dom`, `typescript` (if enabled)
+
+### Configuration Files Created
+
+- **`tailwind.config.js`** - Tailwind CSS configuration with component library paths
+- **`postcss.config.js`** - PostCSS configuration for CSS processing
+- **`src/index.css`** - CSS file with Carbide theme import
+
+### Project Structure
+
+```
+your-project/
+├── src/
+│   ├── index.css (with Carbide theme import)
+│   ├── App.tsx (with carbide class)
+│   └── Example.tsx (example component)
+├── tailwind.config.js
+├── postcss.config.js
+├── package.json
+└── node_modules/
+    └── @machinemetrics/mm-react-components/
+```
+
+## Framework Support
+
+### Supported Frameworks
+
+- **React** - Standard React applications
+- **Next.js** - Next.js applications with TypeScript support
+- **Vite** - Vite-based React applications
+- **Create React App** - CRA applications with CRACO support
+
+### Framework-Specific Setup
+
+Each framework has specific configuration requirements:
+
+- **Next.js**: Requires `transpilePackages` configuration
+- **Vite**: Requires CSS processing configuration
+- **CRA**: Requires CRACO for Tailwind support
+
+## Usage Examples
+
+### Basic Setup
+
+```bash
+# Create new React 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
+```
+
+### Next.js Setup
+
+```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
+```
+
+### Vite Setup
+
+```bash
+# Create new Vite 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
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Script fails with "command not found"**
+   - Solution: Install NPX or use npm directly
+
+2. **Dependencies not installed**
+   - Solution: Clear cache and reinstall
+
+3. **CSS not loading**
+   - Solution: Ensure Carbide theme is imported and applied
+
+4. **Build errors**
+   - Solution: Check configuration files and dependencies
+
+### Debugging Steps
+
+1. **Check dependencies**: `npm list @machinemetrics/mm-react-components`
+2. **Verify configuration**: Check `tailwind.config.js` and `postcss.config.js`
+3. **Test imports**: Try importing a component
+4. **Check CSS**: Ensure theme is imported and applied
+
+## AI Agent Usage
+
+### For AI Agents
+
+AI agents can use these files to:
+
+1. **Automated Setup**: Use the main init script for standard setups
+2. **Fallback Setup**: Use the fallback script when main script fails
+3. **Manual Setup**: Follow the detailed guides for complex scenarios
+4. **Troubleshooting**: Use the troubleshooting guide to resolve issues
+
+### AI Agent Commands
+
+```bash
+# Automated setup
+node scripts/init.cjs
+
+# Or with npx
+npx @machinemetrics/mm-react-components init
+
+# Manual setup (follow ai-agent-init-guide.md)
+# 1. Install dependencies
+# 2. Import CSS in your app
+# 3. Add 'carbide' class to root element
+# 4. Test setup
+```
+
+## Validation
+
+### Setup Validation
+
+After setup, verify:
+
+- [ ] `@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
+- [ ] Build process works without errors
+
+### Test Component
+
+```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;
+```
+
+## Advanced Configuration
+
+### Custom Tailwind Configuration
+
+```javascript
+// tailwind.config.js
+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
+    },
+  },
+  plugins: [
+    // Additional Tailwind plugins
+  ],
+};
+```
+
+### Custom CSS Setup
+
+```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 */
+}
+```
+
+## Support and Resources
+
+### Documentation
+
+- [Component Library Docs](https://components.machinemetrics.com)
+- [Setup Guide](https://components.machinemetrics.com/setup)
+- [API Reference](https://components.machinemetrics.com/api)
+
+### 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 initialization setup provides comprehensive tools and documentation for setting up the MachineMetrics React Components library. Whether using automated scripts or manual setup, the goal is to provide a smooth development experience with industrial-grade components.
+
+For AI agents, these files provide everything needed to automate the setup process and handle edge cases when the main scripts fail. The fallback script ensures that setup can always be completed, even in complex scenarios.