@jmruthers/pace-core 0.4.1 → 0.5.3

package/docs/migration/v0.4.15-tailwind-scanning.md

@@ -0,0 +1,272 @@
+# Migration Guide: v0.4.15 Tailwind Content Scanning
+
+This guide helps you migrate to pace-core v0.4.15+ which includes source files for proper Tailwind v4 content scanning.
+
+## 🎯 What's New in v0.4.15
+
+- ✅ **Source files included** in published package
+- ✅ **New source exports** for Tailwind scanning
+- ✅ **Improved content scanning** with 800+ CSS rules
+- ✅ **Better component styling** with complete design system
+
+## 🚀 Migration Steps
+
+### 1. Update pace-core
+
+```bash
+npm install @jmruthers/pace-core@latest
+```
+
+### 2. Update Vite Configuration
+
+**Before (v0.4.14 and below):**
+```typescript
+// vite.config.ts
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss({
+      content: [
+        './src/**/*.{js,ts,jsx,tsx}',
+        './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}'
+      ]
+    })
+  ],
+})
+```
+
+**After (v0.4.15+):**
+```typescript
+// vite.config.ts
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss({
+      content: [
+        './src/**/*.{js,ts,jsx,tsx}',
+        './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'
+      ]
+    })
+  ],
+})
+```
+
+### 3. Alternative: PostCSS Configuration
+
+If you're using PostCSS instead of Vite plugin:
+
+```javascript
+// tailwind.config.js
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: [
+    './src/**/*.{js,ts,jsx,tsx}',
+    './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'
+  ],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+}
+```
+
+### 4. Clear Build Cache
+
+```bash
+# Clear all caches
+rm -rf dist .vite node_modules package-lock.json
+
+# Reinstall dependencies
+npm install
+
+# Rebuild
+npm run build
+```
+
+## 🔍 Verification Steps
+
+### 1. Check CSS Output Size
+
+After building, verify your CSS file size:
+
+```bash
+# Check CSS file size
+ls -la dist/assets/*.css
+```
+
+**Expected Results:**
+- ✅ **50-100+ kB** (with all utility classes)
+- ❌ **20-30 kB** (missing classes - indicates scanning issue)
+
+### 2. Test Component Styling
+
+Create a test component to verify styling:
+
+```tsx
+// src/TestComponent.tsx
+import { Button, Card } from '@jmruthers/pace-core';
+
+export function TestComponent() {
+  return (
+    <div className="p-8 space-y-4">
+      <h1 className="text-2xl font-bold text-main-900">Migration Test</h1>
+      
+      <Card className="p-4 border border-main-300">
+        <h2 className="text-lg font-semibold text-sec-800 mb-2">
+          Component Styling Test
+        </h2>
+        <div className="space-y-2">
+          <Button 
+            variant="primary" 
+            className="bg-main-600 text-main-50 hover:bg-main-700"
+          >
+            Primary Button
+          </Button>
+          <Button 
+            variant="secondary" 
+            className="bg-sec-500 text-main-50 hover:bg-sec-600"
+          >
+            Secondary Button
+          </Button>
+          <div className="p-2 bg-acc-100 text-acc-800 rounded">
+            Accent colored div
+          </div>
+        </div>
+      </Card>
+    </div>
+  );
+}
+```
+
+**Expected Result:**
+- ✅ Proper PACE Core colors (main, sec, acc palettes)
+- ✅ Correct spacing and typography
+- ✅ Hover effects working
+- ✅ Component styling complete
+
+### 3. Check Browser Dev Tools
+
+Inspect elements to verify:
+
+1. **Open browser dev tools**
+2. **Inspect the test component**
+3. **Check computed styles** for:
+   - `background-color` values (should show PACE Core colors)
+   - `color` values (should show proper text colors)
+   - `padding`, `margin` values (should show proper spacing)
+
+### 4. Verify CSS Rules Count
+
+Check the generated CSS for utility classes:
+
+```bash
+# Count CSS rules (approximate)
+grep -c "\.bg-\|\.text-\|\.p-\|\.m-\|\.w-\|\.h-\|\.flex\|\.grid" dist/assets/*.css
+```
+
+**Expected Results:**
+- ✅ **800+ rules** (complete utility set)
+- ❌ **<300 rules** (incomplete - scanning issue)
+
+## 🛠️ Troubleshooting
+
+### Issue: Still only 292 CSS rules
+
+**Possible Causes:**
+1. Using old package version
+2. Incorrect content paths
+3. Cached build files
+
+**Solutions:**
+1. **Verify package version:**
+   ```bash
+   npm list @jmruthers/pace-core
+   # Should show v0.4.15+
+   ```
+
+2. **Check content paths:**
+   ```typescript
+   // Ensure you're using source paths
+   content: [
+     './src/**/*.{js,ts,jsx,tsx}',
+     './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'
+   ]
+   ```
+
+3. **Clear all caches:**
+   ```bash
+   rm -rf dist .vite node_modules package-lock.json
+   npm install
+   npm run build
+   ```
+
+### Issue: Source files not found
+
+**Error:** `Cannot resolve './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'`
+
+**Solution:**
+1. Ensure you're using pace-core v0.4.15+
+2. Check if source files exist:
+   ```bash
+   ls -la node_modules/@jmruthers/pace-core/src/
+   ```
+
+### Issue: Build errors with source files
+
+**Error:** TypeScript errors when scanning source files
+
+**Solution:** Add TypeScript configuration:
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "skipLibCheck": true
+  }
+}
+```
+
+### Issue: Components still unstyled
+
+**Solution:**
+1. Verify CSS import: `import '@jmruthers/pace-core/styles/core.css'`
+2. Check Vite configuration includes source files
+3. Restart dev server after changes
+
+## 📊 Before vs After
+
+| Aspect | v0.4.14 and below | v0.4.15+ |
+|--------|-------------------|-----------|
+| **CSS Rules** | ~292 rules | 800+ rules |
+| **File Size** | 20-30 kB | 50-100+ kB |
+| **Component Styling** | Incomplete | Complete |
+| **Colors** | Missing | Full palette |
+| **Spacing** | Limited | Complete |
+| **Content Scanning** | Compiled JS only | Source files |
+
+## 🎉 Success Indicators
+
+You'll know the migration was successful when:
+
+- ✅ **CSS file is 50-100+ kB**
+- ✅ **Components render with proper styling**
+- ✅ **PACE Core colors work** (`bg-main-600`, `text-sec-700`, etc.)
+- ✅ **Spacing and typography are correct**
+- ✅ **Hover effects and transitions work**
+- ✅ **No console errors about missing classes**
+
+## 📚 Additional Resources
+
+- [Tailwind Content Scanning Guide](../troubleshooting/tailwind-content-scanning.md)
+- [Vite Configuration Guide](../consuming-app-vite-config.md)
+- [Troubleshooting Guide](../troubleshooting/styling-issues.md)
+- [Installation Guide](../getting-started/installation.md)
+
+## 🆘 Need Help?
+
+If you're still experiencing issues after following this guide:
+
+1. **Check the troubleshooting guides** above
+2. **Verify your configuration** matches the examples
+3. **Test with a minimal example** to isolate the issue
+4. **Contact support** with specific error messages and configuration details

package/docs/migration/v0.4.16-css-first-approach.md

@@ -0,0 +1,306 @@
+# Migration Guide: v0.4.16 CSS-First Approach
+
+This guide helps you migrate to pace-core v0.4.16+ which uses Tailwind v4's CSS-first approach with `@source` directives for automatic content scanning.
+
+## 🎯 What's New in v0.4.16
+
+- ✅ **CSS-first approach** with `@source` directives in `core.css`
+- ✅ **Automatic content scanning** of published source files
+- ✅ **Simplified Vite configuration** - no complex content paths needed
+- ✅ **Better reliability** - follows Tailwind v4 best practices
+- ✅ **Same styling results** with less configuration
+
+## 🚀 Migration Steps
+
+### 1. Update pace-core
+
+```bash
+npm install @jmruthers/pace-core@latest
+```
+
+### 2. Simplify Vite Configuration
+
+**Before (v0.4.15 and below):**
+```typescript
+// vite.config.ts
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss({
+      content: [
+        './src/**/*.{js,ts,jsx,tsx}',
+        './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'
+      ]
+    })
+  ],
+})
+```
+
+**After (v0.4.16+):**
+```typescript
+// vite.config.ts
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss({
+      // Only need to scan your app's source files
+      // pace-core source files are automatically scanned via @source directives
+      content: [
+        './src/**/*.{js,ts,jsx,tsx}'
+      ]
+    })
+  ],
+})
+```
+
+### 3. Alternative: PostCSS Configuration
+
+If you're using PostCSS instead of Vite plugin:
+
+```javascript
+// tailwind.config.js
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: [
+    './src/**/*.{js,ts,jsx,tsx}'
+    // pace-core source files are automatically scanned via @source directives
+  ],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+}
+```
+
+### 4. Clear Build Cache
+
+```bash
+# Clear all caches
+rm -rf dist .vite node_modules package-lock.json
+
+# Reinstall dependencies
+npm install
+
+# Rebuild
+npm run build
+```
+
+## 🔍 How It Works
+
+### CSS-First Approach
+
+Pace-core v0.4.16+ includes `@source` directives in `core.css`:
+
+```css
+@import "tailwindcss";
+
+/* @source directives for Tailwind v4 content scanning */
+@source "./src/**/*.{js,ts,jsx,tsx}";
+@source "./src/components/**/*.{js,ts,jsx,tsx}";
+@source "./src/providers/**/*.{js,ts,jsx,tsx}";
+@source "./src/hooks/**/*.{js,ts,jsx,tsx}";
+@source "./src/utils/**/*.{js,ts,jsx,tsx}";
+@source "./src/types/**/*.{js,ts,jsx,tsx}";
+@source "./src/validation/**/*.{js,ts,jsx,tsx}";
+@source "./src/rbac/**/*.{js,ts,jsx,tsx}";
+
+@theme {
+  /* ... theme configuration ... */
+}
+```
+
+These directives tell Tailwind v4 to automatically scan the pace-core source files for utility classes, eliminating the need for complex Vite configuration.
+
+## 🔍 Verification Steps
+
+### 1. Check CSS Output Size
+
+After building, verify your CSS file size:
+
+```bash
+# Check CSS file size
+ls -la dist/assets/*.css
+```
+
+**Expected Results:**
+- ✅ **50-100+ kB** (with all utility classes)
+- ❌ **20-30 kB** (missing classes - indicates scanning issue)
+
+### 2. Test Component Styling
+
+Create a test component to verify styling:
+
+```tsx
+// src/TestComponent.tsx
+import { Button, Card } from '@jmruthers/pace-core';
+
+export function TestComponent() {
+  return (
+    <div className="p-8 space-y-4">
+      <h1 className="text-2xl font-bold text-main-900">CSS-First Test</h1>
+      
+      <Card className="p-4 border border-main-300">
+        <h2 className="text-lg font-semibold text-sec-800 mb-2">
+          Component Styling Test
+        </h2>
+        <div className="space-y-2">
+          <Button 
+            variant="primary" 
+            className="bg-main-600 text-main-50 hover:bg-main-700"
+          >
+            Primary Button
+          </Button>
+          <Button 
+            variant="secondary" 
+            className="bg-sec-500 text-main-50 hover:bg-sec-600"
+          >
+            Secondary Button
+          </Button>
+          <div className="p-2 bg-acc-100 text-acc-800 rounded">
+            Accent colored div
+          </div>
+        </div>
+      </Card>
+    </div>
+  );
+}
+```
+
+**Expected Result:**
+- ✅ Proper PACE Core colors (main, sec, acc palettes)
+- ✅ Correct spacing and typography
+- ✅ Hover effects working
+- ✅ Component styling complete
+
+### 3. Check Browser Dev Tools
+
+Inspect elements to verify:
+
+1. **Open browser dev tools**
+2. **Inspect the test component**
+3. **Check computed styles** for:
+   - `background-color` values (should show PACE Core colors)
+   - `color` values (should show proper text colors)
+   - `padding`, `margin` values (should show proper spacing)
+
+### 4. Verify CSS Rules Count
+
+Check the generated CSS for utility classes:
+
+```bash
+# Count CSS rules (approximate)
+grep -c "\.bg-\|\.text-\|\.p-\|\.m-\|\.w-\|\.h-\|\.flex\|\.grid" dist/assets/*.css
+```
+
+**Expected Results:**
+- ✅ **800+ rules** (complete utility set)
+- ❌ **<300 rules** (incomplete - scanning issue)
+
+## 🛠️ Troubleshooting
+
+### Issue: Still only 292 CSS rules
+
+**Possible Causes:**
+1. Using old package version
+2. CSS-first approach not working
+3. Cached build files
+
+**Solutions:**
+1. **Verify package version:**
+   ```bash
+   npm list @jmruthers/pace-core
+   # Should show v0.4.16+
+   ```
+
+2. **Check @source directives:**
+   ```bash
+   # Check if core.css contains @source directives
+   grep -n "@source" node_modules/@jmruthers/pace-core/src/styles/core.css
+   ```
+
+3. **Fallback to explicit content scanning:**
+   ```typescript
+   // vite.config.ts - Fallback configuration
+   export default defineConfig({
+     plugins: [
+       react(),
+       tailwindcss({
+         content: [
+           './src/**/*.{js,ts,jsx,tsx}',
+           './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'
+         ]
+       })
+     ],
+   })
+   ```
+
+4. **Clear all caches:**
+   ```bash
+   rm -rf dist .vite node_modules package-lock.json
+   npm install
+   npm run build
+   ```
+
+### Issue: @source directives not working
+
+**Error:** CSS-first approach not scanning pace-core files
+
+**Solution:** Use the fallback configuration with explicit content paths (see above).
+
+### Issue: Build errors with @source directives
+
+**Error:** Tailwind v4 doesn't recognize @source directives
+
+**Solution:** 
+1. Ensure you're using Tailwind v4
+2. Use the fallback configuration with explicit content paths
+3. Check Tailwind v4 documentation for @source directive support
+
+### Issue: Components still unstyled
+
+**Solution:**
+1. Verify CSS import: `import '@jmruthers/pace-core/styles/core.css'`
+2. Check Vite configuration includes source files
+3. Restart dev server after changes
+4. Use fallback configuration if CSS-first approach fails
+
+## 📊 Before vs After
+
+| Aspect | v0.4.15 and below | v0.4.16+ |
+|--------|-------------------|-----------|
+| **Configuration** | Complex content paths | Simple content paths |
+| **Content Scanning** | Explicit source file paths | Automatic via @source directives |
+| **CSS Rules** | 800+ rules | 800+ rules |
+| **File Size** | 50-100+ kB | 50-100+ kB |
+| **Component Styling** | Complete | Complete |
+| **Reliability** | Good | Better |
+| **Maintenance** | Manual path updates | Automatic |
+
+## 🎉 Success Indicators
+
+You'll know the migration was successful when:
+
+- ✅ **CSS file is 50-100+ kB**
+- ✅ **Components render with proper styling**
+- ✅ **PACE Core colors work** (`bg-main-600`, `text-sec-700`, etc.)
+- ✅ **Spacing and typography are correct**
+- ✅ **Hover effects and transitions work**
+- ✅ **No console errors about missing classes**
+- ✅ **Simplified Vite configuration works**
+
+## 📚 Additional Resources
+
+- [CSS-First Approach Guide](../troubleshooting/tailwind-content-scanning.md)
+- [Vite Configuration Guide](../consuming-app-vite-config.md)
+- [Troubleshooting Guide](../troubleshooting/styling-issues.md)
+- [Installation Guide](../getting-started/installation.md)
+
+## 🆘 Need Help?
+
+If you're still experiencing issues after following this guide:
+
+1. **Check the troubleshooting guides** above
+2. **Verify your configuration** matches the examples
+3. **Test with a minimal example** to isolate the issue
+4. **Use the fallback configuration** if CSS-first approach fails
+5. **Contact support** with specific error messages and configuration details