@jmruthers/pace-core 0.4.1 → 0.5.3

package/docs/migration/README.md

@@ -68,7 +68,7 @@ npm install @jmruthers/pace-core@latest
 **CRITICAL**: Fixed Tailwind v4 theme file with missing semantic colors and circular @apply references.
 
 **Impact**:
-- Build failures when importing `@jmruthers/pace-core/styles/tailwind-v4-theme`
+- Build failures when importing `@jmruthers/pace-core/styles/core.css`
 - Missing semantic colors (ring, border, background, foreground, etc.)
 - Component classes not working due to circular references
 
@@ -90,9 +90,9 @@ npm install @jmruthers/pace-core@latest
 ```
 
 **Usage** (now works out-of-the-box):
-```css
-/* index.css */
-@import '@jmruthers/pace-core/styles/tailwind-v4-theme';
+```tsx
+/* main.tsx */
+import '@jmruthers/pace-core/styles/core.css';
 ```
 
 ```ts
@@ -143,7 +143,7 @@ PACE Core now supports Tailwind CSS v4 with modern CSS-first configuration.
    @tailwind utilities;
 
    /* After (v4) */
-   @import '@jmruthers/pace-core/styles/tailwind-v4-theme';
+   @import '@jmruthers/pace-core/styles/core.css';
    ```
 
 For complete Tailwind v4 setup instructions, see the [Styling Guide](../styles/README.md#tailwind-css-v4-setup).
@@ -270,7 +270,10 @@ function App() {
 **After (PACE Core)**
 ```tsx
 import { UnifiedAuthProvider } from '@jmruthers/pace-core';
-import '@jmruthers/pace-core/styles/tokens';
+
+// Import the core CSS file - app.css must come first for proper @theme processing
+import './app.css'; // Your app's color palette
+import '@jmruthers/pace-core/styles/core.css';
 
 function App() {
   return (
@@ -337,7 +340,10 @@ function MyComponent() {
 **After (PACE Core Components)**
 ```tsx
 import { Button, Modal } from '@jmruthers/pace-core';
-import '@jmruthers/pace-core/styles/tokens';
+
+// Import the core CSS file (in your app's entry point)
+import './app.css'; // Your app's color palette (must come first)
+import '@jmruthers/pace-core/styles/core.css';
 
 function MyComponent() {
   return (
@@ -434,7 +440,11 @@ echo "Migration complete! Please review changes and test thoroughly."
 
 ### Issue 3: Styling Not Applied
 **Problem**: Components look unstyled
-**Solution**: Import the design tokens: `import '@jmruthers/pace-core/styles/tokens'`
+**Solution**: Import the CSS files in your app's entry point:
+```tsx
+import './app.css'; // Your app's color palette (must come first)
+import '@jmruthers/pace-core/styles/core.css';
+```
 
 ### Issue 4: TypeScript Errors
 **Problem**: TypeScript errors after migration

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

@@ -0,0 +1,320 @@
+# Quick Migration Guide
+
+> **🚀 Fast Track Migration** | [Full Migration Guide](./README.md) | [Breaking Changes](./breaking-changes.md)
+
+Quick migration guide for common PACE Core upgrade scenarios. For detailed migration instructions, see the [Full Migration Guide](./README.md).
+
+## 🎯 Quick Migration Checklist
+
+### Before You Start
+- [ ] **Backup your project** - Always backup before major updates
+- [ ] **Check current version** - `npm list @jmruthers/pace-core`
+- [ ] **Review changelog** - Check for breaking changes
+- [ ] **Test in development** - Never migrate directly in production
+
+### Common Migration Scenarios
+
+## 📦 Package Updates
+
+### Minor Version Updates (e.g., v0.4.16 → v0.4.17)
+
+**Usually safe, but check for:**
+- New features
+- Bug fixes
+- Performance improvements
+
+```bash
+# Update to latest
+npm update @jmruthers/pace-core
+
+# Or specific version
+npm install @jmruthers/pace-core@0.4.17
+```
+
+**What to check:**
+- [ ] App still builds successfully
+- [ ] No console errors
+- [ ] Components render correctly
+- [ ] Authentication still works
+
+### Major Version Updates (e.g., v0.x → v1.x)
+
+**Requires more attention:**
+- Breaking API changes
+- New required props
+- Deprecated features
+- Configuration changes
+
+```bash
+# Check what's new
+npm info @jmruthers/pace-core versions --json
+
+# Update to latest
+npm install @jmruthers/pace-core@latest
+```
+
+**What to check:**
+- [ ] Review [Breaking Changes](./breaking-changes.md)
+- [ ] Update import statements
+- [ ] Fix deprecated API usage
+- [ ] Update configuration files
+- [ ] Test all functionality
+
+## 🔧 Configuration Updates
+
+### Tailwind v4 Migration
+
+**From v0.4.15 to v0.4.16+ (CSS-First Approach):**
+
+```bash
+# Remove old dependencies
+npm uninstall tailwindcss postcss autoprefixer
+
+# Install new dependencies
+npm install @tailwindcss/vite tailwindcss@^4.0.0
+```
+
+**Update vite.config.ts:**
+```ts
+// Before (v0.4.15)
+import tailwindcss from '@tailwindcss/vite'
+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+)
+import tailwindcss from '@tailwindcss/vite'
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss({
+      content: [
+        './src/**/*.{js,ts,jsx,tsx}' // Only app files, pace-core scanned via @source
+      ]
+    })
+  ],
+})
+```
+
+**Update CSS imports:**
+```tsx
+// Before
+import '@jmruthers/pace-core/styles/core.css';
+
+// After
+import '@jmruthers/pace-core/styles/core.css';
+```
+
+### Source Path Fix (v0.4.17+)
+
+**Critical fix for @source directive paths:**
+
+```ts
+// vite.config.ts
+import tailwindcss from '@tailwindcss/vite'
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss({
+      content: [
+        './src/**/*.{js,ts,jsx,tsx}',
+        './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}'
+      ]
+    })
+  ],
+})
+```
+
+## 🔄 API Changes
+
+### Component Props
+
+**Common prop changes:**
+
+```tsx
+// Before (v0.x)
+<DataTable
+  data={data}
+  columns={columns}
+  enableSearch={true}
+  enablePagination={true}
+/>
+
+// After (v1.x)
+<DataTable
+  data={data}
+  columns={columns}
+  features={{
+    search: true,
+    pagination: true,
+    sorting: true,
+    filtering: true
+  }}
+/>
+```
+
+### Hook Changes
+
+**RBAC hooks moved to separate module:**
+
+```tsx
+// Before
+import { useCan, usePermissions } from '@jmruthers/pace-core';
+
+// After
+import { useCan, usePermissions } from '@jmruthers/pace-core/rbac';
+```
+
+### Import Changes
+
+**Consolidated imports:**
+
+```tsx
+// Before
+import { Button } from '@jmruthers/pace-core/components';
+import { useUnifiedAuth } from '@jmruthers/pace-core/hooks';
+
+// After
+import { Button, useUnifiedAuth } from '@jmruthers/pace-core';
+```
+
+## 🐛 Common Migration Issues
+
+### Styling Issues
+
+**Problem**: Components appear unstyled after update
+
+**Solution**:
+```tsx
+// Ensure CSS import is first
+import '@jmruthers/pace-core/styles/core.css';
+import { Button } from '@jmruthers/pace-core';
+```
+
+### Build Errors
+
+**Problem**: Build fails with Tailwind errors
+
+**Solution**:
+```bash
+# Clear all caches
+rm -rf node_modules package-lock.json
+npm install
+
+# Check Tailwind config
+npm run build -- --debug
+```
+
+### TypeScript Errors
+
+**Problem**: Type errors after update
+
+**Solution**:
+```bash
+# Update TypeScript types
+npm install @types/react@latest @types/react-dom@latest
+
+# Regenerate types
+npm run type-check
+```
+
+### Authentication Issues
+
+**Problem**: Login not working after update
+
+**Solution**:
+```tsx
+// Check provider hierarchy
+<UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
+  <OrganisationProvider>
+    <EventProvider>
+      <YourApp />
+    </EventProvider>
+  </OrganisationProvider>
+</UnifiedAuthProvider>
+```
+
+## ✅ Post-Migration Testing
+
+### Essential Tests
+- [ ] **Build succeeds** - `npm run build`
+- [ ] **App starts** - `npm run dev`
+- [ ] **Authentication works** - Login/logout
+- [ ] **Components render** - All UI components display
+- [ ] **Permissions work** - RBAC functions correctly
+- [ ] **Forms work** - Form validation and submission
+- [ ] **Data tables work** - CRUD operations
+- [ ] **Styling correct** - No visual regressions
+
+### Performance Tests
+- [ ] **Bundle size** - Check for size increases
+- [ ] **Load time** - Measure initial load
+- [ ] **Runtime performance** - Check for slowdowns
+- [ ] **Memory usage** - Monitor for leaks
+
+### Browser Tests
+- [ ] **Chrome** - Latest version
+- [ ] **Firefox** - Latest version
+- [ ] **Safari** - Latest version
+- [ ] **Mobile browsers** - iOS Safari, Chrome Mobile
+
+## 🆘 Getting Help
+
+### If Migration Fails
+
+1. **Check the logs** - Look for specific error messages
+2. **Revert changes** - Go back to working version
+3. **Check documentation** - Look for migration guides
+4. **Search issues** - Check GitHub issues
+5. **Ask for help** - Create detailed issue report
+
+### Debug Information
+
+When asking for help, include:
+
+```bash
+# Version information
+npm list @jmruthers/pace-core
+node --version
+npm --version
+
+# Build output
+npm run build 2>&1 | tee build.log
+
+# Error details
+# Include full error messages and stack traces
+```
+
+### Emergency Rollback
+
+```bash
+# Rollback to previous version
+npm install @jmruthers/pace-core@0.4.16
+
+# Or specific working version
+npm install @jmruthers/pace-core@0.4.15
+
+# Clear caches
+rm -rf node_modules package-lock.json
+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
+- **[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!

package/docs/migration/rbac-migration.md

@@ -20,6 +20,16 @@ import { useRBAC } from '@jmruthers/pace-core';
 import { useCan, usePermissions } from '@jmruthers/pace-core/rbac';
 ```
 
+### 2. New Security Features
+
+The new RBAC system includes enhanced security features that are automatically enabled:
+
+- **Input Validation**: All UUIDs, permissions, and scopes are validated
+- **Security Monitoring**: Comprehensive logging of security events
+- **Rate Limiting**: Built-in protection against abuse
+- **Input Sanitization**: Automatic sanitization of potentially dangerous inputs
+- **Audit Trail**: Complete audit logging for all permission operations
+
 ### 2. Hook API Changes
 
 **Old (Legacy)**:
@@ -213,6 +223,9 @@ export async function POST(request: Request) {
 - [ ] Verify performance improvements
 - [ ] Check error handling
 - [ ] Validate security enforcement
+- [ ] Test security context features
+- [ ] Verify input validation is working
+- [ ] Check audit logging functionality
 
 ## Common Migration Patterns
 
@@ -501,6 +514,41 @@ If you encounter issues during migration:
 - Performance validation
 - Security verification
 
+## Security Context Migration
+
+### Using Security Context (Optional but Recommended)
+
+The new RBAC system supports optional security context for enhanced security monitoring:
+
+```typescript
+// Basic usage (backward compatible)
+const hasPermission = await isPermitted({
+  userId: 'user-123',
+  scope: { organisationId: 'org-456' },
+  permission: 'read:users'
+});
+
+// Enhanced usage with security context
+const hasPermissionSecure = await isPermitted({
+  userId: 'user-123',
+  scope: { organisationId: 'org-456' },
+  permission: 'read:users'
+}, {
+  userId: 'user-123',
+  organisationId: 'org-456',
+  ipAddress: '192.168.1.1',
+  userAgent: 'Mozilla/5.0...',
+  timestamp: new Date()
+});
+```
+
+### Security Context Benefits
+
+- **Enhanced Audit Logging**: More detailed security event logging
+- **Rate Limiting**: Built-in protection against abuse
+- **Input Validation**: Automatic validation of all inputs
+- **Security Monitoring**: Comprehensive security event tracking
+
 ## Benefits of Migration
 
 ### Performance
@@ -517,5 +565,7 @@ If you encounter issues during migration:
 - **Organisation context enforcement** prevents data leakage
 - **Row Level Security** integration
 - **Complete audit trail** for all permission checks
+- **Enhanced security monitoring** with input validation and rate limiting
+- **Automatic input sanitization** prevents injection attacks
 
 The new RBAC system provides a more robust, performant, and secure foundation for your application's permission management.