@jmruthers/pace-core 0.2.7 → 0.4.1

package/docs/best-practices/README.md

@@ -1,400 +0,0 @@
-# Best Practices
-
-> **🎯 Build Better Apps** | [Security](#security) | [Performance](#performance) | [Testing](#testing) | [Deployment](#deployment)
-
-[← Back to Documentation](../README.md) | [↑ Table of Contents](#table-of-contents)
-
-Comprehensive best practices for building secure, performant, and maintainable applications with PACE Core.
-
-## 📋 Table of Contents
-
-- [Security Best Practices](#-security-best-practices)
-- [Performance Optimization](#-performance-optimization)
-- [Testing Strategies](#-testing-strategies)
-- [Deployment Guidelines](#-deployment-guidelines)
-- [Code Quality](#-code-quality)
-- [Accessibility](#-accessibility)
-- [Maintenance](#-maintenance)
-
-## 🔒 Security Best Practices
-
-### Authentication & Authorization
-
-**✅ Do:**
-- Always validate permissions server-side
-- Use the built-in RBAC system for access control
-- Implement proper session management
-- Enable MFA where possible
-
-```tsx
-// ✅ Good - Server-side validation
-const { data, error } = await supabase
-  .from('users')
-  .select('*')
-  .eq('organisation_id', user.organisation_id); // RLS handles security
-
-// ❌ Bad - Client-side only validation
-if (user.role === 'admin') {
-  // This can be bypassed!
-}
-```
-
-**✅ Do:**
-- Use permission guards for UI elements
-- Implement proper error boundaries
-- Sanitize all user inputs
-
-```tsx
-// ✅ Good - Permission-based rendering
-<PermissionGuard
-  operation="read"
-  resource="sensitive_data"
-  fallback={<div>Access denied</div>}
->
-  <SensitiveDataComponent />
-</PermissionGuard>
-```
-
-### Data Protection
-
-**✅ Do:**
-- Use Row Level Security (RLS) policies
-- Encrypt sensitive data at rest
-- Implement proper audit logging
-- Validate all inputs with Zod schemas
-
-```tsx
-// ✅ Good - Input validation
-const userSchema = z.object({
-  email: z.string().email(),
-  password: z.string().min(8).regex(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)/),
-});
-
-const result = userSchema.safeParse(formData);
-if (!result.success) {
-  // Handle validation errors
-}
-```
-
-For detailed security guidelines, see [Security Best Practices](./security.md).
-
-## ⚡ Performance Optimization
-
-### Bundle Optimization
-
-**✅ Do:**
-- Use tree shaking for smaller bundles
-- Implement code splitting
-- Lazy load heavy components
-- Optimize images and assets
-
-```tsx
-// ✅ Good - Lazy loading
-const HeavyComponent = React.lazy(() => import('./HeavyComponent'));
-
-function App() {
-  return (
-    <Suspense fallback={<LoadingSpinner />}>
-      <HeavyComponent />
-    </Suspense>
-  );
-}
-```
-
-### Runtime Performance
-
-**✅ Do:**
-- Use React.memo for expensive components
-- Optimize callbacks with useCallback
-- Implement proper memoization
-- Use virtualization for large lists
-
-```tsx
-// ✅ Good - Memoized component
-const ExpensiveTable = React.memo(({ data, columns }) => {
-  return <DataTable data={data} columns={columns} />;
-});
-
-// ✅ Good - Memoized callback
-const handleDataChange = useCallback((newData) => {
-  setData(newData);
-}, []);
-```
-
-### Data Management
-
-**✅ Do:**
-- Implement proper caching strategies
-- Use pagination for large datasets
-- Optimize database queries
-- Implement proper loading states
-
-```tsx
-// ✅ Good - Paginated data
-<DataTable
-  data={paginatedData}
-  columns={columns}
-  pagination={{
-    currentPage,
-    pageSize,
-    totalItems: data.length,
-    onPageChange: setCurrentPage,
-  }}
-/>
-```
-
-For detailed performance guidelines, see [Performance Best Practices](./performance.md).
-
-## 🧪 Testing Strategies
-
-### Unit Testing
-
-**✅ Do:**
-- Test component behavior, not implementation
-- Use proper mocking for external dependencies
-- Test error states and edge cases
-- Maintain good test coverage
-
-```tsx
-// ✅ Good - Component testing
-test('renders user data correctly', () => {
-  const mockUser = { id: '1', name: 'John Doe', email: 'john@example.com' };
-  
-  render(<UserProfile user={mockUser} />);
-  
-  expect(screen.getByText('John Doe')).toBeInTheDocument();
-  expect(screen.getByText('john@example.com')).toBeInTheDocument();
-});
-```
-
-### Integration Testing
-
-**✅ Do:**
-- Test component interactions
-- Test authentication flows
-- Test permission enforcement
-- Test form submissions
-
-```tsx
-// ✅ Good - Integration testing
-test('user can submit form with valid data', async () => {
-  const mockSubmit = jest.fn();
-  
-  render(<UserForm onSubmit={mockSubmit} />);
-  
-  await user.type(screen.getByLabelText('Name'), 'John Doe');
-  await user.type(screen.getByLabelText('Email'), 'john@example.com');
-  await user.click(screen.getByRole('button', { name: 'Submit' }));
-  
-  expect(mockSubmit).toHaveBeenCalledWith({
-    name: 'John Doe',
-    email: 'john@example.com'
-  });
-});
-```
-
-### E2E Testing
-
-**✅ Do:**
-- Test critical user journeys
-- Test across different browsers
-- Test responsive behavior
-- Test accessibility features
-
-For detailed testing guidelines, see [Testing Best Practices](./testing.md).
-
-## 🚀 Deployment Guidelines
-
-### Environment Configuration
-
-**✅ Do:**
-- Use environment variables for configuration
-- Implement proper secrets management
-- Use different configs for different environments
-- Validate environment variables at startup
-
-```tsx
-// ✅ Good - Environment validation
-const config = {
-  supabaseUrl: process.env.VITE_SUPABASE_URL,
-  supabaseKey: process.env.VITE_SUPABASE_ANON_KEY,
-  appName: process.env.VITE_APP_NAME,
-};
-
-if (!config.supabaseUrl || !config.supabaseKey) {
-  throw new Error('Missing required environment variables');
-}
-```
-
-### Build Optimization
-
-**✅ Do:**
-- Optimize bundle size
-- Enable compression
-- Use CDN for static assets
-- Implement proper caching headers
-
-### Monitoring
-
-**✅ Do:**
-- Set up error tracking
-- Monitor performance metrics
-- Implement health checks
-- Set up alerts for critical issues
-
-For detailed deployment guidelines, see [Deployment Best Practices](./deployment.md).
-
-## 📝 Code Quality
-
-### TypeScript
-
-**✅ Do:**
-- Use strict TypeScript configuration
-- Define proper interfaces and types
-- Use type guards for runtime safety
-- Avoid `any` types
-
-```tsx
-// ✅ Good - Proper typing
-interface User {
-  id: string;
-  name: string;
-  email: string;
-  role: 'admin' | 'user' | 'guest';
-}
-
-const UserCard: React.FC<{ user: User }> = ({ user }) => {
-  return <div>{user.name}</div>;
-};
-```
-
-### Code Organization
-
-**✅ Do:**
-- Use consistent file naming
-- Organize components logically
-- Separate concerns properly
-- Use proper imports and exports
-
-```tsx
-// ✅ Good - Clean imports
-import { Button, Card, DataTable } from '@jmruthers/pace-core';
-import { useUnifiedAuth, useCan } from '@jmruthers/pace-core';
-import { z } from 'zod';
-```
-
-### Error Handling
-
-**✅ Do:**
-- Implement proper error boundaries
-- Use consistent error handling patterns
-- Provide meaningful error messages
-- Log errors appropriately
-
-```tsx
-// ✅ Good - Error boundary
-<ErrorBoundary
-  fallback={<ErrorFallback />}
-  onError={(error, errorInfo) => {
-    console.error('Error caught by boundary:', error, errorInfo);
-  }}
->
-  <MyComponent />
-</ErrorBoundary>
-```
-
-## ♿ Accessibility
-
-### WCAG Compliance
-
-**✅ Do:**
-- Use semantic HTML elements
-- Provide proper ARIA labels
-- Ensure keyboard navigation
-- Maintain color contrast ratios
-
-```tsx
-// ✅ Good - Accessible component
-<button
-  aria-label="Close dialog"
-  onClick={onClose}
-  className="p-2 rounded-md hover:bg-gray-100"
->
-  <XIcon className="h-4 w-4" />
-</button>
-```
-
-### Screen Reader Support
-
-**✅ Do:**
-- Use proper heading hierarchy
-- Provide alternative text for images
-- Use live regions for dynamic content
-- Test with screen readers
-
-```tsx
-// ✅ Good - Live region for updates
-<div aria-live="polite" aria-atomic="true">
-  {isLoading && 'Loading...'}
-  {error && `Error: ${error.message}`}
-  {data && `Loaded ${data.length} items`}
-</div>
-```
-
-## 🔧 Maintenance
-
-### Documentation
-
-**✅ Do:**
-- Keep documentation up to date
-- Document breaking changes
-- Provide migration guides
-- Include code examples
-
-### Dependencies
-
-**✅ Do:**
-- Keep dependencies updated
-- Use security scanning tools
-- Test updates in development
-- Pin critical dependency versions
-
-### Monitoring
-
-**✅ Do:**
-- Monitor application performance
-- Track user behavior
-- Set up error alerts
-- Regular security audits
-
-## 🎯 Quick Checklist
-
-### Before Going to Production
-
-- [ ] Security audit completed
-- [ ] Performance testing done
-- [ ] Accessibility testing passed
-- [ ] Error handling implemented
-- [ ] Monitoring set up
-- [ ] Documentation updated
-- [ ] Dependencies updated
-- [ ] Environment variables configured
-- [ ] Backup strategy in place
-- [ ] Rollback plan ready
-
-### Regular Maintenance
-
-- [ ] Weekly dependency updates
-- [ ] Monthly security reviews
-- [ ] Quarterly performance audits
-- [ ] Annual architecture reviews
-
-## 📚 Additional Resources
-
-- [Security Best Practices](./security.md) - Detailed security guidelines
-- [Performance Best Practices](./performance.md) - Performance optimization
-- [Testing Best Practices](./testing.md) - Testing strategies
-- [Deployment Best Practices](./deployment.md) - Deployment guidelines
-- [Troubleshooting Guide](../troubleshooting/) - Common issues and solutions
-
-Remember: **Best practices are guidelines, not rules. Adapt them to your specific needs and constraints.**

package/docs/consuming-app-vite-config.md

@@ -1,233 +0,0 @@
-# Consuming App Vite Configuration
-
-This document shows the **CRITICAL** Vite configuration for consuming apps using pace-core with Tailwind v4. Proper configuration is essential to ensure pace-core components are styled correctly.
-
-## ⚠️ Critical: Why This Configuration Matters
-
-Pace-core components contain Tailwind classes that **MUST** be scanned during the build process. Without proper configuration:
-
-- ❌ Component styles will be missing or broken
-- ❌ Colors, spacing, and typography won't work  
-- ❌ The UI will be severely compromised
-- ❌ The entire point of using this UI library is undermined
-
-## ✅ Solution: CSS-First Approach (v0.4.16+)
-
-**NEW**: Pace-core v0.4.16+ uses Tailwind v4's CSS-first approach with `@source` directives in `core.css`. This automatically scans the published source files without requiring complex Vite configuration.
-
-### Method 1: CSS-First Configuration (Recommended)
-
-```ts
-// vite.config.ts
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
-import tailwindcss from '@tailwindcss/vite'
-import path from 'path'
-
-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}'
-      ]
-    })
-  ],
-  resolve: {
-    alias: {
-      "@": path.resolve(__dirname, "./src"),
-    },
-  },
-  server: {
-    port: 3000,
-    open: true,
-  },
-  build: {
-    outDir: 'dist',
-    sourcemap: true,
-  },
-})
-```
-
-### Method 2: Explicit Source File Scanning (Fallback)
-
-If the CSS-first approach doesn't work, you can explicitly include pace-core source files:
-
-```ts
-// vite.config.ts
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
-import tailwindcss from '@tailwindcss/vite'
-import path from 'path'
-
-export default defineConfig({
-  plugins: [
-    react(),
-    tailwindcss({
-      // Explicitly include pace-core source files for scanning
-      content: [
-        './src/**/*.{js,ts,jsx,tsx}',
-        './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'
-      ]
-    })
-  ],
-  resolve: {
-    alias: {
-      "@": path.resolve(__dirname, "./src"),
-    },
-  },
-  server: {
-    port: 3000,
-    open: true,
-  },
-  build: {
-    outDir: 'dist',
-    sourcemap: true,
-  },
-})
-```
-
-### Alternative: PostCSS Configuration
-
-If you prefer PostCSS over 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: [],
-}
-```
-
-## 🔄 Fallback: Hybrid Approach
-
-If source file scanning doesn't work, try this hybrid approach:
-
-```ts
-// vite.config.ts
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
-import tailwindcss from '@tailwindcss/vite'
-
-export default defineConfig({
-  plugins: [
-    react(),
-    tailwindcss({
-      content: [
-        './src/**/*.{js,ts,jsx,tsx}',
-        // Try source files first
-        './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}',
-        // Fallback: also scan dist files
-        './node_modules/@jmruthers/pace-core/dist/**/*.{js,ts,jsx,tsx}'
-      ]
-    })
-  ],
-})
-```
-
-## 🚨 Legacy Configuration (v0.4.14 and below)
-
-If you're using an older version, use this configuration:
-
-```ts
-// vite.config.ts
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
-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}'
-      ]
-    })
-  ],
-})
-```
-
-## What This Configuration Does
-
-1. **Scans Your Source Files**: Detects Tailwind classes in your app's source code
-2. **Scans Pace-Core Source Files**: Ensures all Tailwind classes used in pace-core components are included
-3. **Generates Complete CSS**: Creates a CSS file with all necessary utility classes
-4. **Enables Proper Styling**: Allows pace-core components to render with correct styles
-
-## Verification Steps
-
-After configuration, verify everything works:
-
-1. **Import the CSS file** in your main entry point:
-   ```tsx
-   import '@jmruthers/pace-core/styles/core.css';
-   ```
-
-2. **Create a test component**:
-   ```tsx
-   import { Button, Card } from '@jmruthers/pace-core';
-   
-   function TestComponent() {
-     return (
-       <Card className="p-4">
-         <Button variant="primary" className="bg-main-600 text-main-50">
-           Test Button
-         </Button>
-       </Card>
-     );
-   }
-   ```
-
-3. **Check the result**: The component should render with proper PACE Core styling
-
-4. **Verify CSS size**: Your CSS file should be 50-100+ kB (not 20-30 kB)
-
-## Common Issues and Solutions
-
-### Issue: Components appear unstyled
-**Solution**: Ensure pace-core source files are included in content scanning
-
-### Issue: Colors don't work (text-main-900, bg-sec-500, etc.)
-**Solution**: Verify the CSS file is imported and content scanning includes pace-core source files
-
-### Issue: Build errors about missing classes
-**Solution**: Check that your content paths are correct and include both source files and pace-core source files
-
-### Issue: Still only 292 CSS rules instead of 800+
-**Solution**: 
-1. Update to pace-core v0.4.15+
-2. Use source file paths: `./node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}`
-3. Clear build cache and rebuild
-
-### Issue: Source files not found
-**Solution**: Ensure you're using pace-core v0.4.15+ which includes source files in the published package
-
-## Key Points
-
-- ✅ **Required**: Must include pace-core source files in content scanning
-- ✅ **Critical**: Without this, components won't be styled
-- ✅ **Simple**: Just add the source file paths to your content array
-- ✅ **Reliable**: Works with any project structure when configured correctly
-
-## What NOT to Do
-
-- ❌ **Don't skip content configuration** - pace-core won't be scanned
-- ❌ **Don't rely on automatic scanning only** - it may not catch node_modules
-- ❌ **Don't forget to import the CSS file** - styles won't be available
-- ❌ **Don't assume it works without testing** - always verify with a test component
-
-## Next Steps
-
-- [Installation Guide](./getting-started/installation.md) - Complete setup instructions
-- [Tailwind Content Scanning Guide](./troubleshooting/tailwind-content-scanning.md) - Detailed troubleshooting
-- [Troubleshooting Guide](./troubleshooting/styling-issues.md) - Fix common problems