@jmruthers/pace-core 0.5.76 → 0.5.78

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

@@ -1,320 +0,0 @@
-# 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/src/styles/core.css';
-
-// After
-import '@jmruthers/pace-core/src/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/src/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-guide.md

@@ -1,193 +0,0 @@
-# Migration Guide: Two-File CSS Architecture
-
-This guide explains how to migrate your consuming app to use the new two-file CSS architecture with Tailwind v4 and native utilities.
-
-## Overview
-
-The new architecture uses:
-- **2 CSS files**: core.css from pace-core + app.css in each consuming app
-- **App-specific palettes**: Each app defines its own main/sec/acc color palettes
-- **Native utilities**: Use standard Tailwind classes (bg-main-600, text-sec-700)
-- **No CVA**: Components use native Tailwind utilities, not class-variance-authority
-- **App-controlled scanning**: Each app handles its own Tailwind content scanning
-
-This provides maximum flexibility while maintaining consistency through the semantic token system.
-
-## Migration Steps
-
-### 1. Create Your App CSS File
-
-Create `src/app.css` in your consuming app with your brand colors and source directives:
-
-```css
-@import "tailwindcss";
-
-/* @source directives for Tailwind v4 content scanning */
-@source "./src/**/*.{js,ts,jsx,tsx}";
-@source "./node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}";
-@source "./node_modules/@jmruthers/pace-core/src/components/**/*.{js,ts,jsx,tsx}";
-@source "./node_modules/@jmruthers/pace-core/src/providers/**/*.{js,ts,jsx,tsx}";
-@source "./node_modules/@jmruthers/pace-core/src/hooks/**/*.{js,ts,jsx,tsx}";
-@source "./node_modules/@jmruthers/pace-core/src/utils/**/*.{js,ts,jsx,tsx}";
-@source "./node_modules/@jmruthers/pace-core/src/types/**/*.{js,ts,jsx,tsx}";
-@source "./node_modules/@jmruthers/pace-core/src/validation/**/*.{js,ts,jsx,tsx}";
-@source "./node_modules/@jmruthers/pace-core/src/rbac/**/*.{js,ts,jsx,tsx}";
-
-/* Define your brand color palettes */
-@theme static {
-  /* Your main, secondary, and accent color palettes here */
-  /* See the styling guide for the complete structure */
-}
-```
-
-### 2. Update Your Imports
-
-Replace old style imports with the new two-file system:
-
-```tsx
-// OLD - Remove these imports
-// import '@jmruthers/pace-core/styles';
-// import '@jmruthers/pace-core/styles/tokens';
-// import '@jmruthers/pace-core/styles/components';
-// import '@jmruthers/pace-core/styles/base.css';
-// import '@jmruthers/pace-core/styles/theme.css';
-
-// NEW - Import both CSS files in the correct order
-import '@jmruthers/pace-core/src/styles/core.css'; // Import core first
-import './app.css'; // Import app-specific colors second
-```
-
-### 3. Define Your Color Palettes
-
-**Required!** Each app must define its own color palettes in `app.css`:
-
-- **Main palette**: Your primary brand color (50-950 shades)
-- **Secondary palette**: Your supporting color (50-950 shades)  
-- **Accent palette**: Your highlight color (50-950 shades)
-
-All utilities like `bg-main-600`, `text-sec-700`, `border-acc-500` will use your brand colors.
-
-### 4. Update Your Component Classes
-
-Replace old app-* classes with new native utilities:
-
-```tsx
-// OLD - Remove these classes
-// <div className="bg-main-500 text-main-50">
-//   <Button className="bg-sec-600 hover:bg-sec-700">
-
-// NEW - Use native utilities
-<div className="bg-main-500 text-main-50">
-  <Button className="bg-sec-600 hover:bg-sec-700">
-    Click me
-  </Button>
-</div>
-```
-
-### 4. Configure Tailwind v4
-
-Update your build configuration:
-
-```tsx
-// vite.config.ts
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
-import tailwindcss from '@tailwindcss/vite'
-
-export default defineConfig({
-  plugins: [react(), tailwindcss()],
-})
-```
-
-### 5. Test Your Migration
-
-1. **Verify imports**: Ensure the core CSS file is imported
-2. **Check colors**: Verify the built-in color palettes work correctly
-3. **Test components**: Ensure all components render correctly
-4. **Check scanning**: Verify Tailwind automatically detects utility classes
-
-## What Changed
-
-### Before (Old System)
-- Complex CSS structure with multiple files
-- App-specific color palette files
-- Manual Tailwind configuration
-- Complex theming system
-
-### After (New System)
-- Clean single-file CSS structure
-- Built-in color palettes
-- Automatic file scanning with @source directives
-- Native Tailwind utilities
-
-## Benefits
-
-1. **Simpler**: Only 1 CSS file to import
-2. **Faster**: Native Tailwind utilities are optimized
-3. **Cleaner**: No additional configuration needed
-4. **Automatic**: Tailwind scans all source files through build tool configuration
-5. **Future-proof**: Easy to maintain and extend
-
-## Support
-
-If you encounter issues during migration:
-
-1. Check the [troubleshooting guide](../styles/README.md#troubleshooting)
-2. Review the [usage guide](../usage.md) for complete examples
-3. Open an issue on our GitHub repository
-import tailwindcss from '@tailwindcss/vite'
-
-export default defineConfig({
-  plugins: [
-    react(),
-    tailwindcss() // No theme configuration needed - it's in your CSS
-  ],
-})
-```
-
-## What You Get
-
-### From Your App (`src/app.css`)
-- ✅ Your specific brand colors
-- ✅ App-specific gradients and custom styles
-- ✅ Control over your visual identity
-
-### From PACE Core Package
-- ✅ All component styles (DataTable, buttons, etc.)
-- ✅ Base element styles (h1-h6, p, a, etc.)
-- ✅ Font definitions and loading
-- ✅ Utility classes
-- ✅ Semantic color mappings
-- ✅ Automatic updates when the package is updated
-
-## Benefits
-
-1. **Brand Consistency**: Each app maintains its own visual identity
-2. **Easy Updates**: Package updates automatically improve your components
-3. **No Conflicts**: App colors can't accidentally override component styles
-4. **Maintainable**: Color changes only need to be made in one file
-5. **Future-Proof**: New features and improvements come automatically
-
-## Color Customization
-
-To customize your app's colors, simply update the `--color-main-*`, `--color-sec-*`, and `--color-acc-*` variables in your `src/app.css` file. The semantic color mappings will automatically use your new colors throughout the application.
-
-## Troubleshooting
-
-### Colors Not Updating
-- Ensure your `src/app.css` is imported in your main entry point
-- Check that the color variables are defined in the `@theme static` block
-- Verify that the semantic mappings in `@theme inline` are referencing your color variables
-
-### Styles Not Loading
-- Make sure you're importing the core CSS file in your app's entry point:
-  ```tsx
-  import './app.css'; // Your app's color palette (must come first)
-  import '@jmruthers/pace-core/src/styles/core.css';
-  ```
-- Check that Tailwind CSS v4 is properly configured
-- Ensure your Vite configuration includes the `@tailwindcss/vite` plugin
-
-### Font Issues
-- The package includes embedded fonts, so no additional font loading is needed
-- If you want to use different fonts, update the `--font-*` variables in your `@theme` block