@jmruthers/pace-core 0.5.181 → 0.5.182

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

@@ -1,278 +0,0 @@
----
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
----
-
-# 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/src/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

@@ -1,312 +0,0 @@
----
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
----
-
-# 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/src/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