@jmruthers/pace-core 0.6.6 → 0.6.7

package/dist/eslint-rules/rules/components.cjs

@@ -1,113 +0,0 @@
-/**
- * Component usage rules
- * @package @jmruthers/pace-core
- * @module ESLintRules/rules/components
- */
-
-const { isPaceCoreSourceFile } = require('../utils/helpers.cjs');
-
-module.exports = {
-  rules: {
-    /**
-     * Prefer pace-core Form component over plain form tags and direct react-hook-form usage
-     */
-    'prefer-pace-core-form': {
-      meta: {
-        type: 'problem',
-        docs: {
-          description: 'Disallow plain <form> tags and direct react-hook-form imports. Use pace-core Form component instead.',
-          category: 'Best Practices',
-          recommended: true
-        },
-        messages: {
-          plainFormTag: "Plain <form> tag detected. Use pace-core Form component instead.",
-          reactHookFormImport: "Direct import from 'react-hook-form' detected: {{imports}}. Use pace-core Form component instead. useFormContext is allowed when Form is imported from pace-core."
-        },
-        hasSuggestions: true
-      },
-      create(context) {
-        const filename = context.getFilename();
-        
-        // Exclude pace-core source files - these rules are for consuming apps
-        if (isPaceCoreSourceFile(filename)) {
-          return {};
-        }
-        
-        let hasPaceCoreForm = false;
-        const problematicImports = ['useForm', 'FormProvider', 'Controller', 'useWatch', 'useFieldArray', 'useController'];
-        
-        return {
-          ImportDeclaration(node) {
-            const importSource = node.source.value;
-            
-            // Check if Form is imported from pace-core
-            if (importSource === '@jmruthers/pace-core' || 
-                importSource === '@jmruthers/pace-core/components') {
-              const hasForm = node.specifiers.some(spec => {
-                if (spec.type === 'ImportSpecifier') {
-                  return spec.imported.name === 'Form';
-                }
-                return false;
-              });
-              if (hasForm) {
-                hasPaceCoreForm = true;
-              }
-            }
-            
-            // Check for react-hook-form imports
-            if (importSource === 'react-hook-form') {
-              const importedItems = node.specifiers
-                .filter(spec => spec.type === 'ImportSpecifier')
-                .map(spec => spec.imported.name);
-              
-              const foundProblematic = importedItems.filter(item => problematicImports.includes(item));
-              
-              // Allow useFormContext when Form is imported from pace-core
-              const isAcceptable = hasPaceCoreForm && 
-                                  foundProblematic.length === 1 && 
-                                  foundProblematic[0] === 'useFormContext';
-              
-              if (foundProblematic.length > 0 && !isAcceptable) {
-                context.report({
-                  node: node.source,
-                  messageId: 'reactHookFormImport',
-                  data: {
-                    imports: foundProblematic.join(', ')
-                  },
-                  suggest: [{
-                    desc: 'Use pace-core Form component instead',
-                    fix(fixer) {
-                      return fixer.remove(node);
-                    }
-                  }]
-                });
-              }
-            }
-          },
-          
-          JSXOpeningElement(node) {
-            // Check for plain <form> tags (lowercase, not Form component)
-            if (node.name.type === 'JSXIdentifier') {
-              const elementName = node.name.name;
-              // Check if it's lowercase 'form' (not 'Form' component)
-              if (elementName === 'form') {
-                context.report({
-                  node,
-                  messageId: 'plainFormTag',
-                  suggest: [{
-                    desc: 'Replace with pace-core Form component',
-                    fix(fixer) {
-                      // This is complex to auto-fix, so we'll just report
-                      return null;
-                    }
-                  }]
-                });
-              }
-            }
-          }
-        };
-      }
-    }
-  }
-};
-

package/dist/eslint-rules/rules/imports.cjs

@@ -1,102 +0,0 @@
-/**
- * Import restriction rules
- * @package @jmruthers/pace-core
- * @module ESLintRules/rules/imports
- */
-
-const { getRestrictedImports } = require('../utils/manifest-loader.cjs');
-const { getPaceCoreAlternative, isPaceCoreSourceFile } = require('../utils/helpers.cjs');
-
-module.exports = {
-  rules: {
-    /**
-     * Block direct imports of libraries wrapped by pace-core
-     */
-    'no-restricted-imports': {
-      meta: {
-        type: 'problem',
-        docs: {
-          description: 'Disallow direct imports of libraries that pace-core wraps',
-          category: 'Best Practices',
-          recommended: true
-        },
-        fixable: 'code',
-        hasSuggestions: true,
-        messages: {
-          restrictedImport: '{{message}} Import from {{alternative}} instead.',
-          restrictedImportWithReason: '{{message}} {{reason}}'
-        }
-      },
-      create(context) {
-        const filename = context.getFilename();
-        
-        // Exclude pace-core source files - these rules are for consuming apps
-        if (isPaceCoreSourceFile(filename)) {
-          return {};
-        }
-        
-        const restrictedImports = getRestrictedImports();
-        const restrictedModules = restrictedImports.map(imp => imp.module);
-        
-        // Also catch @radix-ui/* patterns
-        const radixPattern = /^@radix-ui\//;
-        
-        return {
-          ImportDeclaration(node) {
-            const importSource = node.source.value;
-            
-            // Check exact matches
-            const restricted = restrictedImports.find(imp => imp.module === importSource);
-            if (restricted) {
-              context.report({
-                node: node.source,
-                messageId: 'restrictedImportWithReason',
-                data: {
-                  message: `Direct import of '${importSource}' is not allowed.`,
-                  reason: restricted.reason
-                },
-                suggest: [{
-                  desc: `Use pace-core alternative: ${restricted.reason}`,
-                  fix(fixer) {
-                    // Suggest importing from pace-core instead
-                    const paceCoreAlternative = getPaceCoreAlternative(importSource);
-                    if (paceCoreAlternative) {
-                      return fixer.replaceText(
-                        node.source,
-                        `'@jmruthers/pace-core${paceCoreAlternative}'`
-                      );
-                    }
-                    return null;
-                  }
-                }]
-              });
-              return;
-            }
-            
-            // Check @radix-ui/* pattern
-            if (radixPattern.test(importSource) && !restrictedModules.includes(importSource)) {
-              context.report({
-                node: node.source,
-                messageId: 'restrictedImport',
-                data: {
-                  message: `Direct import of '${importSource}' is not allowed.`,
-                  alternative: '@jmruthers/pace-core'
-                },
-                suggest: [{
-                  desc: 'Use pace-core component instead',
-                  fix(fixer) {
-                    return fixer.replaceText(
-                      node.source,
-                      "'@jmruthers/pace-core'"
-                    );
-                  }
-                }]
-              });
-            }
-          }
-        };
-      }
-    }
-  }
-};
-

package/docs/best-practices/README.md

@@ -1,472 +0,0 @@
----
-lastUpdated: 2025-11-18T17:00:00+11:00
-version: 0.5.181
-reviewedBy: documentation-standards-audit
----
-
-# 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)
-
-## Core Topics
-
-### Security
-- [**Security Best Practices**](./security.md) - Security guidelines and secure coding patterns
-
-### Accessibility  
-- [**Accessibility Guide**](./accessibility.md) - WCAG compliance and inclusive design
-
-### Performance
-- [**Performance Optimization**](./performance.md) - Comprehensive performance optimization strategies
-
-### Testing
-- [**Testing Best Practices**](./testing.md) - Testing strategies and patterns
-
-### Deployment
-- [**Deployment Guide**](./deployment.md) - Production deployment guidelines
-
----
-
-## 🔒 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_PUBLISHABLE_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 Organisation
-
-**✅ 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-sec-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.**
-
-## ♿ Accessibility
-
-All best practices should consider accessibility:
-
-- **WCAG 2.1 AA compliance** - Ensure all practices maintain accessibility standards
-- **Screen Reader Support** - Verify practices don't break screen reader functionality
-- **Keyboard Navigation** - Ensure practices don't affect keyboard accessibility
-- **Error Announcements** - Ensure error messages are accessible
-- **Focus Management** - Verify focus handling remains correct
-
-### Accessibility Best Practices
-
-1. **Test with screen readers** - Verify practices work with assistive technologies
-2. **Check error announcements** - Ensure error messages are properly announced
-3. **Maintain keyboard access** - Verify all interactive elements remain keyboard accessible
-4. **Preserve semantic structure** - Don't break semantic HTML with optimizations
-5. **Test focus management** - Ensure focus handling remains correct
-
-## ⚠️ Edge Cases
-
-### Best Practices Conflicts
-
-When best practices conflict:
-- Prioritize security over performance when necessary
-- Balance accessibility with design requirements
-- Consider trade-offs between maintainability and optimization
-- Document decisions when deviating from best practices
-- Test thoroughly when combining multiple practices
-
-### Performance vs Accessibility
-
-When performance optimizations impact accessibility:
-- Ensure lazy loading doesn't break screen reader navigation
-- Verify code splitting maintains keyboard navigation
-- Check that memoization doesn't affect focus management
-- Test with assistive technologies after optimizations
-- Balance performance gains with accessibility requirements
-
-### Security vs Usability
-
-When security practices impact usability:
-- Find balance between security and user experience
-- Provide clear error messages without exposing vulnerabilities
-- Implement security measures transparently
-- Test with real users to ensure usability
-- Document security decisions for future reference