@jmruthers/pace-core 0.5.181 → 0.5.182

package/docs/migration/MIGRATION_GUIDE.md

@@ -192,52 +192,207 @@ import { UnifiedAuthProvider } from '@jmruthers/pace-core';
 
 **Issue Fixed:** @source directive paths in core.css were incorrect, preventing Tailwind v4 from scanning pace-core source files.
 
-**Before (v0.4.16):**
+**Root Cause:** Since `core.css` is located in `src/styles/core.css`, the relative paths `./src/**/*.{js,ts,jsx,tsx}` were looking for `dist/src/` which doesn't exist.
+
+**The Fix:**
+
+**Before (v0.4.16 - Incorrect):**
 ```css
+/* @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}";
 ```
 
-**After (v0.4.17):**
+**After (v0.4.17 - Correct):**
 ```css
+/* @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}";
+```
+
+**File Structure Explanation:**
+
+```
+node_modules/@jmruthers/pace-core/
+├── dist/
+│   └── styles/
+│       └── core.css          ← @source directives are here
+├── src/                      ← Source files are here
+│   ├── components/
+│   ├── providers/
+│   ├── hooks/
+│   └── ...
+└── package.json
 ```
 
+**Path Resolution:**
+- From `src/styles/core.css` to `src/` requires `../src/`
+- The `../` goes up one directory from `src/styles/` to `src/`
+- Then `src/` goes into the source directory
+
 **Migration Steps:**
 
 1. **Update pace-core:**
 ```bash
-npm install @jmruthers/pace-core@^0.4.17
+npm install @jmruthers/pace-core@latest
 ```
 
-2. **Verify CSS file size:**
+2. **Verify the Fix:**
+
+Check that your CSS file size increases significantly:
+
 ```bash
-# Should be 50-100+ KB (not 20-30 KB)
+# Before (v0.4.16) - ~21KB
+# After (v0.4.17) - 50-100+ KB
 ls -la dist/assets/*.css
 ```
 
-3. **Test component styling:**
+3. **Test Component Styling:**
+
+Create a test component to verify styling:
+
 ```tsx
+// src/TestComponent.tsx
 import { Button, Card } from '@jmruthers/pace-core';
 
-function TestComponent() {
+export function TestComponent() {
   return (
     <div className="p-8 space-y-4">
       <h1 className="text-2xl font-bold text-main-900">Path Fix Test</h1>
+      
       <Card className="p-4 border border-main-300">
-        <Button variant="primary" className="bg-main-600 text-main-50">
-          Primary Button
-        </Button>
+        <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:** Components should render with proper PACE Core styling.
+**Expected Result:**
+- ✅ Proper PACE Core colors (main, sec, acc palettes)
+- ✅ Correct spacing and typography
+- ✅ Hover effects working
+- ✅ Component styling complete
+
+**Verification Steps:**
+
+1. **Check CSS Output 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. **Count CSS Rules:**
+```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)
+
+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)
+
+**Troubleshooting:**
+
+**Issue: Still only 292 CSS rules**
+
+**Possible Causes:**
+1. Using old package version
+2. Cached build files
+3. @source directives still not working
+
+**Solutions:**
+1. **Verify package version:**
+   ```bash
+   npm list @jmruthers/pace-core
+   # Should show v0.4.17+
+   ```
+
+2. **Clear all caches:**
+   ```bash
+   rm -rf dist .vite node_modules package-lock.json
+   npm install
+   npm run build
+   ```
+
+3. **Check @source directives:**
+   ```bash
+   # Verify correct paths in core.css
+   grep -n "@source" node_modules/@jmruthers/pace-core/src/styles/core.css
+   ```
+
+**Issue: Components still unstyled**
+
+**Solution:**
+1. Verify CSS import: `import '@jmruthers/pace-core/src/styles/core.css'`
+2. Restart dev server after changes
+3. Check browser dev tools for missing classes
+
+**Before vs After:**
+
+| Aspect | v0.4.16 (Broken) | v0.4.17 (Fixed) |
+|--------|------------------|-----------------|
+| **@source paths** | `./src/**/*.{js,ts,jsx,tsx}` | `../src/**/*.{js,ts,jsx,tsx}` |
+| **Path resolution** | Looks for `dist/src/` (doesn't exist) | Looks for `src/` (correct) |
+| **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 |
 
 ### v0.4.16 - CSS-First Approach
 
-**Change:** Simplified Tailwind v4 configuration using CSS-first approach with @source directives.
+**Change:** Simplified Tailwind v4 configuration using CSS-first approach with `@source` directives for automatic content scanning.
+
+**What's New:**
+- ✅ **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
 
 **Before (v0.4.15):**
 ```typescript
@@ -275,7 +430,7 @@ export default defineConfig({
 
 1. **Update pace-core:**
 ```bash
-npm install @jmruthers/pace-core@^0.4.16
+npm install @jmruthers/pace-core@latest
 ```
 
 2. **Simplify Vite configuration:**
@@ -297,56 +452,195 @@ export default defineConfig({
 })
 ```
 
-3. **Remove old Tailwind dependencies:**
+**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: [],
+}
+```
+
+3. **Remove old Tailwind dependencies (if upgrading from v3):**
 ```bash
 npm uninstall tailwindcss postcss autoprefixer
 npm install @tailwindcss/vite tailwindcss@^4.0.0
 ```
 
-4. **Test styling:**
-```tsx
-import { Button } from '@jmruthers/pace-core';
+4. **Clear build cache:**
+```bash
+# Clear all caches
+rm -rf dist .vite node_modules package-lock.json
 
-function TestComponent() {
-  return (
-    <Button variant="primary" className="bg-main-600 text-main-50">
-      Test Button
-    </Button>
-  );
-}
+# Reinstall dependencies
+npm install
+
+# Rebuild
+npm run build
 ```
 
-### v0.4.15 - Tailwind Content Scanning
+**How It Works:**
 
-**Change:** Required explicit content scanning for pace-core components.
+Pace-core v0.4.16+ includes `@source` directives in `core.css`:
 
-**Migration Steps:**
+```css
+@import "tailwindcss";
 
-1. **Update Vite configuration:**
-```typescript
-// vite.config.ts
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
-import tailwindcss from '@tailwindcss/vite'
+/* @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 ... */
+}
+```
 
-export default defineConfig({
-  plugins: [
-    react(),
-    tailwindcss({
-      content: [
-        './src/**/*.{js,ts,jsx,tsx}',
-        './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'
-      ]
-    })
-  ],
-})
+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:**
+```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. **Verify CSS import:**
+2. **Test Component Styling:**
 ```tsx
-// Ensure this import is first
-import '@jmruthers/pace-core/src/styles/core.css';
+// 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>
+  );
+}
+```
+
+3. **Verify CSS Rules Count:**
+```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
+
+**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 |
 
 ## API Changes Migration
 
@@ -1155,6 +1449,71 @@ To stay informed about breaking changes:
 
 **Remember**: Always test breaking changes in a development environment before deploying to production.
 
-**Last Updated**: January 2025  
-**Current Stable Version**: v0.5.65+  
-**Next Major Version**: v1.0.0 (TBD)
+**Last Updated**: 2025-11-18  
+**Current Stable Version**: v0.5.181  
+**Next Major Version**: v1.0.0 (TBD)
+
+## ♿ Accessibility
+
+Migration processes should maintain accessibility:
+
+- **Accessibility testing after migration** - Verify all components remain accessible after migration
+- **Screen reader compatibility** - Test with assistive technologies after migration
+- **Keyboard navigation** - Ensure keyboard navigation still works after migration
+- **Focus management** - Verify focus management is correct after migration
+- **ARIA attributes** - Check ARIA attributes are preserved after migration
+
+### Accessibility Best Practices
+
+1. **Test accessibility after migration** - Run accessibility tests after each migration step
+2. **Verify keyboard navigation** - Ensure all interactive elements remain keyboard accessible
+3. **Test with screen readers** - Verify components work with assistive technologies
+4. **Check focus indicators** - Ensure focus indicators are visible and correct
+5. **Review ARIA attributes** - Verify ARIA attributes are properly maintained
+
+## ⚠️ Edge Cases
+
+### Migration Failures
+
+When migrations fail:
+- Review error messages carefully
+- Check version compatibility
+- Verify all dependencies are updated
+- Test with minimal configuration
+- Review migration guide for specific version
+
+### Partial Migrations
+
+When only partial migration is possible:
+- Document what was migrated and what wasn't
+- Create remediation plan for remaining items
+- Test partially migrated code thoroughly
+- Set timeline for completing migration
+- Monitor for issues in partially migrated code
+
+### Version Compatibility Issues
+
+When version compatibility issues occur:
+- Verify all peer dependencies are compatible
+- Check for breaking changes in dependencies
+- Review migration guide for dependency updates
+- Test with different dependency versions
+- Consider gradual migration approach
+
+### Rollback Scenarios
+
+When rollback is needed:
+- Document current state before rollback
+- Verify rollback process is tested
+- Check for data migration issues
+- Ensure rollback doesn't lose data
+- Test rollback in development first
+
+### Multi-Environment Migrations
+
+When migrating across multiple environments:
+- Migrate development first
+- Test thoroughly in staging
+- Verify production migration plan
+- Have rollback plan ready
+- Monitor all environments during migration

package/docs/migration/README.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T21:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # Migration Guide
@@ -508,3 +508,37 @@ If you encounter issues during migration:
 - [ ] Production deployment
 
 Remember: **Always test thoroughly before deploying to production!**
+
+## ♿ Accessibility
+
+Migration processes should maintain accessibility:
+
+- **Accessibility testing after migration** - Verify all components remain accessible after migration
+- **Screen reader compatibility** - Test with assistive technologies after migration
+- **Keyboard navigation** - Ensure keyboard navigation still works after migration
+- **Focus management** - Verify focus management is correct after migration
+
+### Accessibility Best Practices
+
+1. **Test accessibility after migration** - Run accessibility tests after each migration step
+2. **Verify keyboard navigation** - Ensure all interactive elements remain keyboard accessible
+3. **Test with screen readers** - Verify components work with assistive technologies
+4. **Check focus indicators** - Ensure focus indicators are visible and correct
+
+## ⚠️ Edge Cases
+
+### Migration Failures
+
+When migrations fail:
+- Review error messages carefully
+- Check version compatibility
+- Verify all dependencies are updated
+- Test with minimal configuration
+
+### Partial Migrations
+
+When only partial migration is possible:
+- Document what was migrated and what wasn't
+- Create remediation plan for remaining items
+- Test partially migrated code thoroughly
+- Set timeline for completing migration

package/docs/migration/organisation-context-timing-fix.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T21:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # Organisation Context Timing Fix Migration
@@ -220,4 +220,39 @@ If you're still experiencing issues after following this migration guide:
 - [OrganisationProvider API Reference](../api-reference/providers.md#organisationprovider)
 - [Organisations Core Concepts](../core-concepts/organisations.md)
 - [Troubleshooting Common Issues](../troubleshooting/common-issues.md)
-- [RLS Policy Guide](../troubleshooting/database-view-compatibility.md)
+
+## ♿ Accessibility
+
+Migration processes should maintain accessibility:
+
+- **Accessibility testing after migration** - Verify all components remain accessible after migration
+- **Screen reader compatibility** - Test with assistive technologies after migration
+- **Keyboard navigation** - Ensure keyboard navigation still works after migration
+- **Focus management** - Verify focus management is correct after migration
+
+### Accessibility Best Practices
+
+1. **Test accessibility after migration** - Run accessibility tests after each migration step
+2. **Verify keyboard navigation** - Ensure all interactive elements remain keyboard accessible
+3. **Test with screen readers** - Verify components work with assistive technologies
+4. **Check focus indicators** - Ensure focus indicators are visible and correct
+
+## ⚠️ Edge Cases
+
+### Migration Failures
+
+When migrations fail:
+- Review error messages carefully
+- Check version compatibility
+- Verify all dependencies are updated
+- Test with minimal configuration
+- Review migration guide for specific version
+
+### Provider Hierarchy Issues
+
+When provider hierarchy is incorrect:
+- Verify provider order (UnifiedAuthProvider → OrganisationProvider → EventProvider)
+- Check for missing providers
+- Review provider composition examples
+- Test with minimal provider setup
+- Verify context is available before use

package/docs/migration/quick-migration-guide.md

@@ -1,8 +1,14 @@
+---
+lastUpdated: 2025-11-18T21:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
+---
+
 # Quick Migration Guide
 
-> **🚀 Fast Track Migration** | [Full Migration Guide](./README.md) | [Breaking Changes](./breaking-changes.md)
+> **🚀 Fast Track Migration** | [Full Migration Guide](./MIGRATION_GUIDE.md) | [Complete Migration Reference](./README.md)
 
-Quick migration guide for common PACE Core upgrade scenarios. For detailed migration instructions, see the [Full Migration Guide](./README.md).
+Quick migration guide for common PACE Core upgrade scenarios. For detailed migration instructions, see the [Complete Migration Guide](./MIGRATION_GUIDE.md).
 
 ## 🎯 Quick Migration Checklist
 
@@ -309,12 +315,42 @@ npm install
 
 ## 📚 Additional Resources
 
-- **[Full Migration Guide](./README.md)** - Detailed migration instructions
-- **[Breaking Changes](./breaking-changes.md)** - Complete list of breaking changes
-- **[Changelog](../CHANGELOG.md)** - Version history and changes
+- **[Complete Migration Guide](./MIGRATION_GUIDE.md)** - Detailed migration instructions
+- **[Migration Overview](./README.md)** - Migration guide index
 - **[Troubleshooting](../troubleshooting/README.md)** - Common issues and solutions
 - **[GitHub Issues](https://github.com/jmruthers/pace-core/issues)** - Report bugs and get help
 
 ---
 
 **Remember**: Always test migrations in a development environment first!
+
+## ♿ Accessibility
+
+Migration processes should maintain accessibility:
+
+- **Accessibility testing after migration** - Verify all components remain accessible after migration
+- **Screen reader compatibility** - Test with assistive technologies after migration
+- **Keyboard navigation** - Ensure keyboard navigation still works after migration
+
+### Accessibility Best Practices
+
+1. **Test accessibility after migration** - Run accessibility tests after each migration step
+2. **Verify keyboard navigation** - Ensure all interactive elements remain keyboard accessible
+3. **Test with screen readers** - Verify components work with assistive technologies
+
+## ⚠️ Edge Cases
+
+### Migration Failures
+
+When migrations fail:
+- Review error messages carefully
+- Check version compatibility
+- Verify all dependencies are updated
+- Test with minimal configuration
+
+### Partial Migrations
+
+When only partial migration is possible:
+- Document what was migrated and what wasn't
+- Create remediation plan for remaining items
+- Test partially migrated code thoroughly