@jmruthers/pace-core 0.6.4 → 0.6.6

package/docs/standards/06-testing-and-docs-standard.md

@@ -1,29 +0,0 @@
-# Testing & Documentation Standard
-
-## Testing Strategy
-- Unit tests for utils & hooks
-- Integration tests for components
-- Few meaningful E2E tests (in consuming apps)
-- Coverage: ≥90% utils, ≥70% components
-
-## Test Structure
-- Colocated tests (*.test.ts/tsx)
-- Use RTL + userEvent
-- Avoid unnecessary mocks
-
-## Documentation Requirements
-- Component READMEs
-- API docs
-- Standards directory
-
-## Required Sections
-- Overview
-- API/Props
-- Examples
-- A11y notes
-- Edge cases
-
-## Cursor Checklist
-- Update docs after API changes
-- Ensure tests cover critical paths
-- Use RTL patterns only

package/docs/standards/pace-core-compliance.md

@@ -1,432 +0,0 @@
-# pace-core Compliance Enforcement
-
-This guide explains how to enforce pace-core usage patterns in consuming apps to ensure consistent design, reduce duplication, and maintain high code quality.
-
-## Overview
-
-pace-core provides a comprehensive enforcement system that includes:
-
-1. **ESLint Rules** - Real-time linting during development
-2. **Static Analysis Script** - Comprehensive codebase scanning
-3. **ESLint Config Preset** - Easy setup for consuming apps
-
-## Quick Start
-
-### Option 1: ESLint Config Preset (Recommended)
-
-The easiest way to enable compliance checking is to use the shareable ESLint config. The config is CommonJS but works with both ES module and CommonJS ESLint configs:
-
-**For ES Module ESLint Config (eslint.config.js):**
-```javascript
-// eslint.config.js (ES modules)
-import paceCoreConfig from '@jmruthers/pace-core/eslint-config';
-
-export default [
-  ...paceCoreConfig,
-  // your other config
-];
-```
-
-**For CommonJS ESLint Config (.eslintrc.js or eslint.config.cjs):**
-```javascript
-// eslint.config.cjs (CommonJS)
-const paceCoreConfig = require('@jmruthers/pace-core/eslint-config');
-
-module.exports = [
-  ...paceCoreConfig,
-  // your other config
-];
-```
-
-### Option 2: Manual ESLint Rules Setup
-
-If you prefer more control, you can import the rules directly. Note: The rules are CommonJS, so use `createRequire` in ES modules:
-
-**For ES Module ESLint Config:**
-```javascript
-// eslint.config.js
-import { createRequire } from 'module';
-const require = createRequire(import.meta.url);
-const paceCoreRules = require('@jmruthers/pace-core/eslint-rules').rules;
-
-export default [
-  {
-    plugins: {
-      'pace-core-compliance': {
-        rules: paceCoreRules
-      }
-    },
-    rules: {
-      'pace-core-compliance/no-restricted-imports': 'error',
-      'pace-core-compliance/prefer-pace-core-components': 'warn',
-      'pace-core-compliance/prefer-pace-core-hooks': 'warn',
-      'pace-core-compliance/prefer-pace-core-utils': 'warn',
-      'pace-core-compliance/no-local-component-duplication': 'error'
-    }
-  }
-];
-```
-
-**For CommonJS ESLint Config:**
-```javascript
-// eslint.config.cjs
-const paceCoreRules = require('@jmruthers/pace-core/eslint-rules').rules;
-
-module.exports = [
-  {
-    plugins: {
-      'pace-core-compliance': {
-        rules: paceCoreRules
-      }
-    },
-    rules: {
-      'pace-core-compliance/no-restricted-imports': 'error',
-      'pace-core-compliance/prefer-pace-core-components': 'warn',
-      'pace-core-compliance/prefer-pace-core-hooks': 'warn',
-      'pace-core-compliance/prefer-pace-core-utils': 'warn',
-      'pace-core-compliance/no-local-component-duplication': 'error'
-    }
-  }
-];
-```
-
-## ESLint Rules
-
-### no-restricted-imports
-
-**Severity**: Error
-
-Blocks direct imports of libraries that pace-core wraps and standardizes.
-
-**Restricted Libraries**:
-- `@radix-ui/*` - All Radix UI packages (use pace-core components instead)
-- `lucide-react` - Icons (use pace-core components that include icons)
-- `react-day-picker` - Use `Calendar` from pace-core
-- `@tanstack/react-table` - Use `DataTable` from pace-core
-- `react-hook-form` - Use `Form` and `useZodForm` from pace-core
-- `zod` - Use validation utilities from pace-core
-
-**Example Violation**:
-```typescript
-// ❌ Bad
-import { Dialog } from '@radix-ui/react-dialog';
-import { Button } from 'lucide-react';
-
-// ✅ Good
-import { Dialog } from '@jmruthers/pace-core';
-import { Button } from '@jmruthers/pace-core';
-```
-
-### prefer-pace-core-components
-
-**Severity**: Warning
-
-Suggests using pace-core components instead of native HTML elements.
-
-**Detected Patterns**:
-- `<button>` → Use `Button` from pace-core
-- `<input>` → Use `Input` from pace-core
-- `<textarea>` → Use `Textarea` from pace-core
-- `<label>` → Use `Label` from pace-core
-
-**Example**:
-```tsx
-// ⚠️ Warning
-<button onClick={handleClick}>Click me</button>
-
-// ✅ Recommended
-import { Button } from '@jmruthers/pace-core';
-<Button onClick={handleClick}>Click me</Button>
-```
-
-### prefer-pace-core-hooks
-
-**Severity**: Warning
-
-Detects custom hooks that duplicate pace-core functionality.
-
-**Common Patterns Detected**:
-- `useToast`, `useNotification` → Use `useToast` from pace-core
-- `useDebounce`, `useDebounced` → Use `useDebounce` from pace-core
-- `useAuth`, `useAuthentication` → Use `useUnifiedAuth` from pace-core
-- `useForm`, `useZodForm` → Use `useZodForm` from pace-core
-
-**Example**:
-```typescript
-// ⚠️ Warning
-function useToast() {
-  // custom implementation
-}
-
-// ✅ Recommended
-import { useToast } from '@jmruthers/pace-core';
-```
-
-### prefer-pace-core-utils
-
-**Severity**: Warning
-
-Detects utility functions that duplicate pace-core functionality.
-
-**Common Patterns Detected**:
-- `formatDate`, `dateFormat` → Use `formatDate` from pace-core
-- `formatCurrency`, `formatMoney` → Use `formatCurrency` from pace-core
-- `cn`, `classNames`, `clsx` → Use `cn` from pace-core
-- `validate`, `validateInput` → Use `validateUserInput` from pace-core
-
-**Example**:
-```typescript
-// ⚠️ Warning
-function formatDate(date: Date): string {
-  // custom implementation
-}
-
-// ✅ Recommended
-import { formatDate } from '@jmruthers/pace-core';
-```
-
-### no-local-component-duplication
-
-**Severity**: Error
-
-Prevents creating local components with names matching pace-core components.
-
-**Example Violation**:
-```
-// ❌ Error: components/Button.tsx
-export function Button() { ... }
-
-// pace-core already provides Button component
-```
-
-**Fix**: Remove the local component and import from pace-core:
-```typescript
-import { Button } from '@jmruthers/pace-core';
-```
-
-## Static Analysis Script
-
-The static analysis script provides a comprehensive scan of your codebase and generates a detailed compliance report.
-
-### Running the Script
-
-```bash
-# From your consuming app root
-node node_modules/@jmruthers/pace-core/scripts/check-pace-core-compliance.cjs
-```
-
-Or add it to your `package.json`:
-
-```json
-{
-  "scripts": {
-    "check:pace-core": "node node_modules/@jmruthers/pace-core/scripts/check-pace-core-compliance.cjs"
-  }
-}
-```
-
-### What It Checks
-
-1. **Restricted Imports** - Scans for direct imports of wrapped libraries
-2. **Duplicate Components** - Finds local components matching pace-core names
-3. **Duplicate Hooks** - Finds local hooks matching pace-core hooks
-4. **Duplicate Utils** - Finds local utils matching pace-core utils
-5. **Suggestions** - Recommends pace-core alternatives for native HTML elements
-
-### Report Output
-
-The script generates a color-coded terminal report showing:
-
-- ❌ **Errors** - Critical violations that must be fixed
-- ⚠️ **Warnings** - Issues that should be addressed
-- 💡 **Suggestions** - Recommendations for improvement
-- ✅ **Summary** - Overall compliance status
-
-Example output:
-```
-═══════════════════════════════════════════════════════════
-  pace-core Compliance Report
-═══════════════════════════════════════════════════════════
-
-❌ Restricted Imports Found: 3
-
-  • src/components/CustomDialog.tsx:5
-    Import: @radix-ui/react-dialog
-    Reason: Use Dialog component from pace-core instead
-
-Summary:
-  Total Issues: 3
-  - Restricted Imports: 3
-  - Duplicate Components/Hooks/Utils: 0
-  - Suggestions: 0
-```
-
-## Best Practices
-
-### 1. Always Import from pace-core
-
-```typescript
-// ✅ Good
-import { Button, Card, Dialog } from '@jmruthers/pace-core';
-import { useToast, useDebounce } from '@jmruthers/pace-core';
-import { formatDate, formatCurrency } from '@jmruthers/pace-core';
-```
-
-### 2. Use pace-core Components for UI
-
-Avoid native HTML elements when pace-core provides a component:
-
-```tsx
-// ❌ Avoid
-<button className="btn">Click</button>
-
-// ✅ Use pace-core
-<Button>Click</Button>
-```
-
-### 3. Leverage pace-core Hooks
-
-Don't recreate hooks that pace-core already provides:
-
-```typescript
-// ❌ Avoid
-const [debouncedValue, setDebouncedValue] = useState(value);
-useEffect(() => {
-  const timer = setTimeout(() => setDebouncedValue(value), 500);
-  return () => clearTimeout(timer);
-}, [value]);
-
-// ✅ Use pace-core
-import { useDebounce } from '@jmruthers/pace-core';
-const debouncedValue = useDebounce(value, 500);
-```
-
-### 4. Use pace-core Utilities
-
-Leverage formatting, validation, and other utilities from pace-core:
-
-```typescript
-// ❌ Avoid
-const formatted = new Intl.DateTimeFormat('en-US').format(date);
-
-// ✅ Use pace-core
-import { formatDate } from '@jmruthers/pace-core';
-const formatted = formatDate(date);
-```
-
-### 5. Check Before Creating New Components
-
-Before creating a new component, check if pace-core already provides it:
-
-1. Review the [pace-core documentation](https://github.com/your-org/pace-core)
-2. Check `core-usage-manifest.json` for available components
-3. Search pace-core exports
-
-## Troubleshooting
-
-### ESLint Rules Not Working
-
-1. **Verify plugin is loaded**: Check that the config is imported correctly:
-   ```javascript
-   // In your eslint.config.js, add temporarily:
-   import paceCoreConfig from '@jmruthers/pace-core/eslint-config';
-   console.log('Config:', paceCoreConfig);
-   console.log('Has plugins:', paceCoreConfig[0]?.plugins);
-   ```
-
-2. **Check rule names**: Rules must be prefixed with `pace-core-compliance/`
-
-3. **Verify manifest exists**: Rules load from `core-usage-manifest.json` in the pace-core package
-
-4. **CommonJS/ES Module issues**: If you're using ES modules and rules aren't loading:
-   - Ensure you're using the config preset (Option 1) which handles this automatically
-   - Or use `createRequire` when importing rules directly (Option 2)
-
-5. **Verify rules are available**: Check that the rules file exists:
-   ```bash
-   ls node_modules/@jmruthers/pace-core/dist/eslint-rules/pace-core-compliance.cjs
-   ```
-
-### Static Analysis Script Errors
-
-1. **Manifest not found**: Ensure `core-usage-manifest.json` exists in pace-core package
-2. **No files scanned**: Check that you're running from the project root
-3. **Permission errors**: Ensure script has read access to source files
-
-### False Positives
-
-If you encounter false positives:
-
-1. **Component name conflicts**: If you have a legitimate reason to create a local component with a pace-core name, consider:
-   - Renaming your component
-   - Using a namespace/prefix
-   - Documenting why pace-core doesn't meet your needs
-
-2. **Hook/Util patterns**: The pattern matching may flag similar names. Review the suggestion and decide if migration makes sense.
-
-## Integration with CI/CD
-
-While CI/CD integration is not included in the initial release, you can easily add it:
-
-```yaml
-# .github/workflows/pace-core-compliance.yml
-name: pace-core Compliance
-
-on: [push, pull_request]
-
-jobs:
-  compliance:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-node@v3
-      - run: npm ci
-      - run: npm run check:pace-core
-      - run: npm run lint
-```
-
-## Verification
-
-After setting up the ESLint config, verify it's working:
-
-1. **Check ESLint can load the config**:
-   ```bash
-   npx eslint --print-config src/App.tsx
-   ```
-   Look for `pace-core-compliance` in the plugins section.
-
-2. **Test with a violation**: Create a test file that imports a restricted library:
-   ```typescript
-   // test-violation.ts
-   import { Dialog } from '@radix-ui/react-dialog'; // Should trigger error
-   ```
-   Run ESLint and verify it reports the violation.
-
-3. **Run static analysis**: Use the compliance script to get a full report:
-   ```bash
-   npm run check:pace-core
-   ```
-
-## Getting Help
-
-- **Documentation**: See [pace-core docs](../README.md)
-- **Issues**: Report false positives or rule issues
-- **Manifest**: Check `core-usage-manifest.json` for available exports
-- **ESLint Config**: The config file is at `@jmruthers/pace-core/eslint-config` (CommonJS)
-- **ESLint Rules**: The rules are at `@jmruthers/pace-core/eslint-rules` (CommonJS)
-
-## File Locations
-
-When installed in a consuming app, the compliance tools are available at:
-
-- **ESLint Config**: `node_modules/@jmruthers/pace-core/eslint-config-pace-core.cjs`
-- **ESLint Rules**: `node_modules/@jmruthers/pace-core/dist/eslint-rules/pace-core-compliance.cjs`
-- **Static Analysis Script**: `node_modules/@jmruthers/pace-core/scripts/check-pace-core-compliance.cjs`
-- **Manifest**: `node_modules/@jmruthers/pace-core/core-usage-manifest.json`
-
-## Related Documentation
-
-- [Component Standards](./03-component-standard.md)
-- [API & RPC Standards](./02-api-and-rpc-standard.md)
-- [Getting Started Guide](../getting-started/README.md)
-

package/scripts/audit/core/checks/accessibility.cjs

@@ -1,197 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Accessibility Check Module
- * @package @jmruthers/pace-core
- * @module Audit/Checks/Accessibility
- * 
- * Checks for:
- * - Missing aria-* attributes
- * - Missing keyboard navigation
- * - Missing focus management
- * - Missing alt text on images
- */
-
-const fs = require('fs');
-const { getRelativePath, getLineNumber } = require('../utils.cjs');
-
-const accessibilityCheck = {
-  name: 'accessibility',
-  description: 'Accessibility checks (aria attributes, keyboard navigation, alt text)',
-  severity: 'warning',
-  
-  async run(context) {
-    const { projectRoot, files } = context;
-    const issues = [];
-    const warnings = [];
-    const suggestions = [];
-    
-    if (!files || files.length === 0) {
-      return { issues, warnings, suggestions };
-    }
-    
-    for (const filePath of files) {
-      try {
-        // Only check React component files
-        if (!filePath.match(/\.(tsx|jsx)$/)) {
-          continue;
-        }
-        
-        const content = fs.readFileSync(filePath, 'utf8');
-        const relativePath = getRelativePath(filePath, projectRoot);
-        const normalizedPath = relativePath.replace(/\\/g, '/');
-        
-        // Skip root-level src directory - in pace-core repository, this is a demo/showcase app
-        // Note: We DO check packages/core/ files because accessibility issues (missing alt attributes, missing form labels) are real issues that should be fixed
-        const isRootSrc = normalizedPath.startsWith('src/') && !normalizedPath.includes('packages/');
-        if (isRootSrc) {
-          continue; // Skip demo app files
-        }
-        
-        // Skip scripts directory - utility scripts don't need accessibility validation
-        const isScript = normalizedPath.startsWith('scripts/') || normalizedPath.includes('/scripts/');
-        if (isScript) {
-          continue; // Skip script files
-        }
-        
-        // Skip pace-core library components and examples - these are designed to accept accessibility props
-        // Library components accept id, aria-label, etc. via props spread
-        // Examples are demonstration code, not production code
-        const isPaceCorePackage = normalizedPath.includes('packages/core/') || normalizedPath.startsWith('packages/core/');
-        const isExample = normalizedPath.includes('/examples/');
-        const isLibraryComponent = isPaceCorePackage && !isExample;
-        
-        // Check for images without alt text
-        // Skip library components - they accept alt as a prop
-        if (!isLibraryComponent) {
-          const imgPattern = /<img[^>]*>/g;
-          let imgMatch;
-          while ((imgMatch = imgPattern.exec(content)) !== null) {
-            const imgTag = imgMatch[0];
-            // Check for alt attribute, including React props (alt=, alt =, alt={)
-            const hasAlt = imgTag.includes('alt=') || imgTag.includes('alt =') || imgTag.includes('alt={');
-            if (!hasAlt) {
-              warnings.push({
-                type: 'missing-alt-text',
-                file: relativePath,
-                line: getLineNumber(content, imgMatch.index),
-                message: 'Image element missing alt attribute',
-                recommendation: 'Add alt text to all images for accessibility: <img alt="description" ... />'
-              });
-            }
-          }
-        }
-        
-        // Check for buttons/clickable elements without aria-label or accessible text
-        const buttonPattern = /<(button|a|div)\s+[^>]*(onClick|role=["']button["'])[^>]*>/g;
-        let buttonMatch;
-        while ((buttonMatch = buttonPattern.exec(content)) !== null) {
-          const buttonTag = buttonMatch[0];
-          const hasAriaLabel = buttonTag.includes('aria-label=') || buttonTag.includes('ariaLabel=');
-          const hasAccessibleText = buttonTag.includes('>') && content.substring(buttonMatch.index).match(/<[^>]*>([^<]+)</);
-          
-          if (!hasAriaLabel && !hasAccessibleText) {
-            warnings.push({
-              type: 'missing-aria-label',
-              file: relativePath,
-              line: getLineNumber(content, buttonMatch.index),
-              message: 'Interactive element missing accessible label',
-              recommendation: 'Add aria-label or ensure element contains accessible text content'
-            });
-          }
-        }
-        
-        // Check for form inputs without labels
-        // Skip library components - they accept id, aria-label, etc. via props spread
-        // Skip examples - they're demonstration code
-        if (!isLibraryComponent && !isExample) {
-          const inputPattern = /<input[^>]*>/g;
-          let inputMatch;
-          while ((inputMatch = inputPattern.exec(content)) !== null) {
-            // Get the full input tag including multi-line attributes
-            const inputStart = inputMatch.index;
-            const afterInput = content.substring(inputStart, Math.min(content.length, inputStart + 500));
-            const inputTagEnd = afterInput.indexOf('>');
-            const fullInputTag = inputTagEnd !== -1 ? afterInput.substring(0, inputTagEnd + 1) : inputMatch[0];
-            
-            // Check for id (including React props)
-            const hasId = /id=["']([^"']+)["']|id=\{/.test(fullInputTag);
-            // Check for aria-label (including React props)
-            const hasAriaLabel = /aria-label=["']|ariaLabel=|aria-label=\{/.test(fullInputTag);
-            
-            if (hasId) {
-              const idMatch = fullInputTag.match(/id=["']([^"']+)["']/);
-              if (idMatch) {
-                const id = idMatch[1];
-                // Check if there's a corresponding label
-                const beforeInput = content.substring(Math.max(0, inputMatch.index - 200), inputMatch.index);
-                const hasLabel = new RegExp(`<label[^>]*for=["']${id}["']`, 'i').test(beforeInput);
-                
-                if (!hasLabel && !hasAriaLabel) {
-                  warnings.push({
-                    type: 'missing-input-label',
-                    file: relativePath,
-                    line: getLineNumber(content, inputMatch.index),
-                    message: 'Form input missing associated label',
-                    recommendation: 'Add a <label> element with for attribute matching input id, or use aria-label'
-                  });
-                }
-              }
-            } else if (!hasAriaLabel) {
-              warnings.push({
-                type: 'missing-input-label',
-                file: relativePath,
-                line: getLineNumber(content, inputMatch.index),
-                message: 'Form input missing id and label',
-                recommendation: 'Add id to input and corresponding label, or use aria-label'
-              });
-            }
-          }
-        }
-        
-        // Check for missing focus management in modals/dialogs
-        const dialogPattern = /<Dialog|<dialog/gi;
-        if (dialogPattern.test(content)) {
-          // Skip Dialog.tsx itself - it IS the Dialog component
-          if (normalizedPath.includes('/Dialog/Dialog.tsx') || normalizedPath.includes('/Dialog/Dialog.jsx')) {
-            continue; // Skip the Dialog component file itself
-          }
-          
-          // Check if Dialog from pace-core is used (which handles focus automatically)
-          // Check for both published package import and relative imports (within pace-core repo)
-          const usesPaceCoreDialog = content.includes('from \'@jmruthers/pace-core\'') ||
-                                    content.includes('from "@jmruthers/pace-core"') ||
-                                    content.includes('from \'../Dialog') ||
-                                    content.includes('from "../Dialog') ||
-                                    content.includes('from \'../../Dialog') ||
-                                    content.includes('from "../../Dialog') ||
-                                    content.includes('from \'../../../Dialog') ||
-                                    content.includes('from "../../../Dialog') ||
-                                    content.includes('from \'./Dialog') ||
-                                    content.includes('from "./Dialog');
-          
-          if (!usesPaceCoreDialog) {
-            suggestions.push({
-              type: 'dialog-focus-management',
-              file: relativePath,
-              message: 'Custom dialog implementation detected',
-              recommendation: 'Use Dialog component from @jmruthers/pace-core which handles focus management automatically'
-            });
-          }
-        }
-        
-        // Check for color contrast issues (heuristic - check for color props without sufficient contrast)
-        const colorPattern = /(?:color|bg-|text-)=["']([^"']+)["']/g;
-        // This is a simplified check - full implementation would need color contrast calculation
-        // For now, just suggest using pace-core components which handle contrast
-        
-      } catch (error) {
-        // Skip files with errors
-      }
-    }
-    
-    return { issues, warnings, suggestions };
-  }
-};
-
-module.exports = accessibilityCheck;