@jmruthers/pace-core 0.5.68 → 0.5.69

package/docs/troubleshooting/styling-issues.md

@@ -1,32 +1,81 @@
-# Styling Issues Troubleshooting
+# Troubleshooting Styling Issues
 
-This guide helps you diagnose and fix common styling issues when using pace-core components.
+> **🎨 Styling Problems?** | [← Back to Troubleshooting](../README.md) | [Troubleshooting Overview](./common-issues.md)
 
-## 🚨 Most Common Issue: Unstyled Components
+Quick fixes and solutions for common styling issues with PACE Core components.
 
-### Symptoms
-- Components render but appear unstyled (no colors, spacing, or typography)
-- Buttons look like plain HTML buttons
-- Cards appear as plain divs
-- Colors like `text-main-900`, `bg-sec-500` don't work
+## 🚨 Most Common Issues
 
-### Root Cause
-**Pace-core components are not being scanned for Tailwind classes during the build process.**
+### Components Appear Unstyled
 
-### Solution
-Update your `vite.config.ts` to include pace-core in content scanning:
+**Symptoms:**
+- Components render without styles
+- Default browser styling appears
+- No colors, spacing, or fonts
+
+**Immediate Fix:**
+```tsx
+// ✅ In your entry point (main.tsx or App.tsx)
+import '@jmruthers/pace-core/src/styles/core.css'; // MUST be first
+import './app.css'; // Your app's color palette
+```
+
+**Checklist:**
+- [ ] CSS files imported in correct order (core.css first, then app.css)
+- [ ] Tailwind v4 installed (`npm list tailwindcss`)
+- [ ] Vite configured with pace-core content scanning
+- [ ] Dev server restarted after config changes
+
+### Colors Don't Work
+
+**Symptoms:**
+- `bg-main-600` shows as gray or doesn't work
+- Tailwind utilities return default colors
+- Theme colors not applied
+
+**Fix:**
+```css
+/* src/app.css - MUST contain color palettes */
+@import "tailwindcss";
+
+/* Source directives */
+@source "./src/**/*.{js,ts,jsx,tsx}";
+@source "./node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}";
+
+/* Color palettes - REQUIRED */
+@theme static {
+  --color-main-50: oklch(0.98 0.003 300);
+  --color-main-100: oklch(0.96 0.014 300);
+  /* ... continue through 950 for main, sec, acc */
+}
+```
+
+### Tailwind v4 Not Working
+
+**Symptoms:**
+- Build errors about Tailwind configuration
+- Styles not generated
+- "Cannot find module '@tailwindcss/vite'"
+
+**Fix:**
+```bash
+# Install Tailwind v4 (correct version)
+npm uninstall tailwindcss@^3.0.0
+npm install -D @tailwindcss/vite tailwindcss@^4.0.0
+
+# Verify installation
+npm list tailwindcss
+# Should show: tailwindcss@^4.0.0
+```
 
 ```ts
-// vite.config.ts
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
+// vite.config.ts - Required configuration
 import tailwindcss from '@tailwindcss/vite'
 
 export default defineConfig({
   plugins: [
     react(),
     tailwindcss({
-      // CRITICAL: Include pace-core components for scanning
       content: [
         './src/**/*.{js,ts,jsx,tsx}',
         './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}'
@@ -36,184 +85,190 @@ export default defineConfig({
 })
 ```
 
-### Verification Steps
-1. **Check your Vite config** - Ensure pace-core is included in content array
-2. **Restart dev server** - Configuration changes require a restart
-3. **Test with a simple component**:
-   ```tsx
-   import { Button } from '@jmruthers/pace-core';
-   
-   function Test() {
-     return <Button variant="primary">Test</Button>;
-   }
-   ```
-4. **Check browser dev tools** - Look for missing CSS classes in the computed styles
+### Fonts Not Loading
 
-## 🔍 Other Common Issues
+**Symptoms:**
+- Text appears in system default font
+- Font files not found in network tab
 
-### Issue: CSS file not imported
-
-**Symptoms**: No styles at all, components look completely unstyled
-
-**Solution**: Import the CSS file in your main entry point:
+**Fix:**
 ```tsx
-// src/main.tsx or src/index.tsx
+// Fonts are included in core.css
+import '@jmruthers/pace-core/src/styles/core.css';
+
+// Verify fonts are loading
 import '@jmruthers/pace-core/src/styles/core.css';
+// Check browser DevTools > Network > Font for Georama, Open Sans, Reddit Mono
 ```
 
-### Issue: Colors not working
+### CSS Conflicts with Existing Styles
 
-**Symptoms**: Components render but colors like `text-main-900`, `bg-sec-500` don't apply
+**Symptoms:**
+- PACE Core styles override your custom styles
+- Unexpected styling conflicts
+- Specificity issues
 
-**Possible Causes**:
-1. CSS file not imported
-2. Pace-core not included in content scanning
-3. Tailwind v3 instead of v4
+**Fix:**
+```css
+/* Use CSS layers to control specificity */
+@layer pace-core, your-app;
 
-**Solution**:
-1. Ensure CSS file is imported
-2. Check Vite configuration includes pace-core
-3. Verify you're using Tailwind v4: `npm list tailwindcss`
+/* Your app styles will take precedence when needed */
+@layer your-app {
+  .my-custom-button {
+    /* Your styles here */
+  }
+}
+```
 
-### Issue: Styles work in dev but not production
+## 🔧 Detailed Solutions
 
-**Symptoms**: Components look good in development but unstyled in production build
+### Vite Configuration Issues
 
-**Solution**: Ensure your build configuration also includes content scanning:
+**Problem:** Tailwind not scanning pace-core source files
+
+**Solution:**
 ```ts
-// vite.config.ts
+// vite.config.ts - REQUIRED
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
 export default defineConfig({
   plugins: [
     react(),
     tailwindcss({
+      // CRITICAL: Must include pace-core source files
       content: [
         './src/**/*.{js,ts,jsx,tsx}',
-        './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}'
+        './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}',
+        './node_modules/@jmruthers/pace-core/src/components/**/*.{js,ts,jsx,tsx}',
+        './node_modules/@jmruthers/pace-core/src/providers/**/*.{js,ts,jsx,tsx}'
       ]
     })
   ],
-  build: {
-    // Your build config
-  }
 })
 ```
 
-### Issue: Build errors about missing classes
+### Import Order Issues
 
-**Symptoms**: Build fails with errors about missing Tailwind classes
+**Problem:** Styles not applied due to import order
 
-**Solution**: Check that your content paths are correct and include both source files and pace-core:
-```ts
-content: [
-  './src/**/*.{js,ts,jsx,tsx}',
-  './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}'
-]
-```
+**Solution:**
+```tsx
+// ✅ CORRECT ORDER
+// 1. Import core.css first
+import '@jmruthers/pace-core/src/styles/core.css';
 
-### Issue: Some components work, others don't
+// 2. Import your app.css second
+import './app.css';
 
-**Symptoms**: Some pace-core components are styled, others are not
+// 3. Import your other styles
+import './index.css';
 
-**Possible Causes**:
-1. Partial content scanning
-2. Different import paths
-3. Component-specific issues
+// ❌ WRONG ORDER
+import './app.css';
+import '@jmruthers/pace-core/src/styles/core.css'; // Too late!
+```
 
-**Solution**:
-1. Check that all pace-core paths are included in content scanning
-2. Try the alternative configuration:
-   ```ts
-   tailwindcss({
-     content: {
-       files: [
-         './src/**/*.{js,ts,jsx,tsx}',
-         './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}',
-         './node_modules/@jmruthers/pace-core/dist/**/*.{js,ts,jsx,tsx}'
-       ]
-     }
-   })
-   ```
+### Missing Color Palette
+
+**Problem:** Error or gray colors because color palette not defined
+
+**Complete app.css Template:**
+```css
+/* src/app.css */
+@import "tailwindcss";
+
+/* Source directives for scanning */
+@source "./src/**/*.{js,ts,jsx,tsx}";
+@source "./node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}";
+
+/* Main palette - Primary brand color */
+@theme static {
+  --color-main-50: oklch(0.98 0.003 300);
+  --color-main-100: oklch(0.96 0.014 300);
+  --color-main-200: oklch(0.927 0.033 300);
+  --color-main-300: oklch(0.881 0.059 300);
+  --color-main-400: oklch(0.822 0.093 300);
+  --color-main-500: oklch(0.75 0.133 300);
+  --color-main-600: oklch(0.665 0.182 300);
+  --color-main-700: oklch(0.58 0.23 300);
+  --color-main-800: oklch(0.456 0.158 300);
+  --color-main-900: oklch(0.332 0.099 300);
+  --color-main-950: oklch(0.195 0.047 300);
+
+  /* Secondary palette */
+  --color-sec-50: oklch(0.98 0.003 244.75);
+  /* ... continue through 950 */
+
+  /* Accent palette */
+  --color-acc-50: oklch(0.98 0.003 7.385);
+  /* ... continue through 950 */
+}
+```
 
-## 🔧 Advanced Troubleshooting
+## 🧪 Verification Steps
 
-### Check if Tailwind is scanning pace-core
+### 1. Check Imports
 
-1. **Enable Tailwind debug mode**:
-   ```ts
-   // vite.config.ts
-   tailwindcss({
-     content: [
-       './src/**/*.{js,ts,jsx,tsx}',
-       './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}'
-     ],
-     debug: true // Add this for debugging
-   })
-   ```
+```tsx
+// Add to your entry file to verify
+console.log('✅ CSS imports working');
+```
 
-2. **Check the generated CSS** - Look for pace-core specific classes in your build output
+### 2. Inspect Generated CSS
 
-3. **Use browser dev tools** - Inspect elements to see which classes are missing
+Open browser DevTools > Elements > Styles tab
+- Should see Tailwind utility classes
+- Colors should show oklch() values
+- Component styles should be present
 
-### Verify Tailwind v4 installation
+### 3. Test Basic Component
 
-```bash
-# Check Tailwind version
-npm list tailwindcss
+```tsx
+import { Button } from '@jmruthers/pace-core';
+
+function Test() {
+  return <Button>Test Button</Button>;
+}
 
-# Should show version 4.x.x, not 3.x.x
+// Should render with proper PACE Core styling
+// Not unstyled or default browser styling
 ```
 
-### Check file paths
+## 🐛 Debug Commands
 
-Ensure your content paths are correct:
-- `./src/**/*.{js,ts,jsx,tsx}` - Your source files
-- `./node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}` - Pace-core components
+```bash
+# Check Tailwind version
+npm list tailwindcss
 
-### Alternative content configuration
+# Check if pace-core installed
+npm list @jmruthers/pace-core
 
-If the standard configuration doesn't work, try this more explicit approach:
+# Verify Vite configuration
+npx vite --config vite.config.ts --debug
 
-```ts
-// vite.config.ts
-export default defineConfig({
-  plugins: [
-    react(),
-    tailwindcss({
-      content: {
-        files: [
-          './src/**/*.{js,ts,jsx,tsx}',
-          './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}',
-          './node_modules/@jmruthers/pace-core/dist/**/*.{js,ts,jsx,tsx}'
-        ]
-      }
-    })
-  ],
-})
+# Build and check for errors
+npm run build
 ```
 
-## ✅ Quick Checklist
-
-Before asking for help, verify:
+## 📚 Related Documentation
 
-- [ ] CSS file is imported: `import '@jmruthers/pace-core/src/styles/core.css'`
-- [ ] Vite config includes pace-core in content scanning
-- [ ] Using Tailwind v4 (not v3)
-- [ ] Dev server restarted after config changes
-- [ ] All required peer dependencies installed
-- [ ] Test component renders with proper styling
+- [Styling Overview](../styles/README.md) - Complete styling guide
+- [Installation Guide](../getting-started/installation-guide.md) - Setup instructions
+- [Vite Configuration](../consuming-app-vite-config.md) - Critical setup
+- [Common Issues](./common-issues.md) - Other troubleshooting
 
-## 🆘 Still Having Issues?
+## 🆘 Still Not Working?
 
-If you've tried all the above and still have problems:
+If you've tried everything above and still have issues:
 
-1. **Check the console** for any error messages
-2. **Verify your setup** matches the [installation guide](../getting-started/installation.md)
-3. **Test with a minimal example** to isolate the issue
-4. **Check your package versions** for compatibility issues
+1. **Create a minimal test case** showing the problem
+2. **Gather debug info** using the commands above
+3. **Check browser console** for error messages
+4. **File an issue** with your findings
 
-## 📚 Related Documentation
+---
 
-- [Installation Guide](../getting-started/installation.md) - Complete setup instructions
-- [Vite Configuration](../consuming-app-vite-config.md) - Detailed Vite setup
-- [Quick Start Guide](../getting-started/quick-start.md) - Step-by-step tutorial
-- [Styles Guide](../styles/README.md) - Understanding the styling system
+**Last Updated:** 2025-01-XX | **Version:** v0.5.65+

package/docs/usage.md

@@ -73,9 +73,30 @@ function MyComponent() {
 
 ## Dynamic Theming
 
-### Organisation/Event Colors
+### Automatic Event Theming (Recommended)
 
-Apply dynamic colors from your database:
+If your app uses the `EventProvider`, simply call `useEventTheme()`:
+
+```tsx
+import { useEventTheme } from '@jmruthers/pace-core';
+
+function MyApp() {
+  // Automatically applies event colors when an event is selected
+  useEventTheme();
+  
+  return <div>Your app</div>;
+}
+```
+
+This hook automatically:
+- Applies event colors when an event is selected
+- Clears theming when no event is selected
+- Handles cleanup and error cases
+- Works consistently across all apps
+
+### Manual Organisation/Event Colors
+
+For custom logic or organisation-based theming:
 
 ```tsx
 import { applyPalette, clearPalette } from '@jmruthers/pace-core/theming/runtime';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmruthers/pace-core",
-  "version": "0.5.68",
+  "version": "0.5.69",
   "description": "Clean, modern React component library with Tailwind v4 styling and native utilities",
   "private": false,
   "publishConfig": {

package/src/__tests__/{TESTING_GUIDELINES.md → TEST_GUIDE_CURSOR.md}

@@ -293,6 +293,26 @@ screen.getByLabelText('Email address');
 - ❌ Configuration files
 - ❌ Type definitions
 
+## 🧩 Test Expansion Workflow
+
+When expanding test coverage:
+
+1. **Start with the coverage report** (`npm test -- --coverage`)
+2. Identify high-priority or under-tested modules
+3. Choose the appropriate test type (unit, component, integration)
+4. Use our standard structure and semantic queries
+5. Assert observable behaviour (not internal state or styles)
+6. Use test tags (`[unit]`, `[integration]`, etc.) for discoverability
+
+## ✅ Pre-Merge Test Checklist
+
+- [ ] Are all tests passing (no `it.only` or `test.skip`)?
+- [ ] Are coverage thresholds still met?
+- [ ] Are tests colocated with the source?
+- [ ] Are semantic queries used (no test IDs)?
+- [ ] Is global state cleaned up properly?
+- [ ] Are new utilities or hooks covered with tests?
+
 ## 🚀 Running Tests
 
 ### Commands

package/src/__tests__/TEST_GUIDE_HUMAN.md

@@ -0,0 +1,103 @@
+
+# 🎯 Cursor-Friendly Testing Guide (pace-core)
+
+This is a simplified version of our full `TESTING_GUIDELINES.md`, designed for use by Cursor or other automated tools.
+
+---
+
+## ✅ Testing Principles (Keep It Simple)
+
+- Test observable behaviour, not internal state or styling
+- Prefer unit/component tests; use integration tests only where needed
+- Avoid brittle selectors and over-mocking
+
+---
+
+## 🧪 Preferred Patterns
+
+### Semantic Queries
+Use these in place of test IDs or class names:
+```ts
+getByRole, getByText, getByLabelText, findByText
+```
+
+### Hook Testing
+```ts
+const { result } = renderHook(() => useCustomHook());
+expect(result.current.value).toBe('expected');
+```
+
+### Component Testing
+```ts
+describe('MyComponent', () => {
+  it('renders correctly', () => {
+    render(<MyComponent />);
+    expect(screen.getByRole('heading')).toHaveTextContent('Title');
+  });
+});
+```
+
+### Async Behaviour
+```ts
+const button = await screen.findByRole('button');
+await user.click(button);
+expect(await screen.findByText('Submitted')).toBeInTheDocument();
+```
+
+---
+
+## ♻️ Structure & Naming
+
+- Test files should be colocated: `MyComponent.test.tsx`, `useThing.test.ts`
+- Use structured `describe` blocks for clarity:
+```ts
+describe('ComponentName', () => {
+  describe('Rendering', () => {});
+  describe('User Interactions', () => {});
+  describe('Error Handling', () => {});
+});
+```
+
+---
+
+## 🔧 Mocking & Cleanup
+
+### Mocks
+```ts
+vi.mock('module', () => ({
+  myFn: vi.fn(),
+}));
+```
+
+### Cleanup
+```ts
+afterEach(() => {
+  cleanup();
+  vi.clearAllMocks();
+  vi.useRealTimers();
+});
+```
+
+---
+
+## 📊 Coverage Targets
+
+- Utils/Hooks: ≥ 95%
+- UI Components: ≥ 90%
+- Feature Modules: ≥ 85%
+- Overall Project: ≥ 82%
+
+---
+
+## 🚫 Avoid
+
+- `getByTestId`, `getByClassName`, DOM structure assertions
+- Snapshot tests (unless explicitly stable)
+- Global state leaks (unreset between tests)
+- Asserting internal state or props
+
+---
+
+## 🧠 Remember
+
+Tests should be readable, behavioural, isolated, and maintainable.

package/src/__tests__/fixtures/test-data.ts

@@ -0,0 +1,90 @@
+/**
+ * @file Test Data Fixtures
+ * @description Shared test data to reduce generation overhead
+ */
+
+import { vi } from 'vitest';
+
+// Pre-generated test data to avoid repeated object creation
+export const TEST_FIXTURES = {
+  users: {
+    basic: {
+      id: 'test-user-id',
+      email: 'test@example.com',
+      name: 'Test User',
+      created_at: '2023-01-01T00:00:00Z',
+    },
+    admin: {
+      id: 'admin-user-id',
+      email: 'admin@example.com',
+      name: 'Admin User',
+      role: 'admin',
+      created_at: '2023-01-01T00:00:00Z',
+    },
+    superAdmin: {
+      id: 'super-admin-id',
+      email: 'superadmin@example.com',
+      name: 'Super Admin',
+      role: 'super_admin',
+      created_at: '2023-01-01T00:00:00Z',
+    },
+  },
+  
+  organisations: {
+    basic: {
+      id: 'org-123',
+      name: 'Test Organisation',
+      slug: 'test-org',
+      created_at: '2023-01-01T00:00:00Z',
+    },
+  },
+  
+  events: {
+    basic: {
+      id: 'event-123',
+      name: 'Test Event',
+      code: 'TEST123',
+      organisation_id: 'org-123',
+      created_at: '2023-01-01T00:00:00Z',
+    },
+  },
+  
+  permissions: {
+    read: 'read:users',
+    write: 'write:users',
+    delete: 'delete:users',
+    admin: 'admin:organisation',
+  },
+  
+  mockFunctions: {
+    onClick: vi.fn(),
+    onSubmit: vi.fn(),
+    onError: vi.fn(),
+    onSuccess: vi.fn(),
+  },
+} as const;
+
+// Helper to create variations of fixtures
+export const createFixture = <T extends Record<string, any>>(
+  base: T,
+  overrides: Partial<T> = {}
+): T => ({ ...base, ...overrides });
+
+// Pre-generated arrays for bulk testing
+export const BULK_FIXTURES = {
+  users: Array.from({ length: 10 }, (_, i) => ({
+    ...TEST_FIXTURES.users.basic,
+    id: `user-${i}`,
+    email: `user${i}@example.com`,
+    name: `User ${i}`,
+  })),
+  
+  permissions: [
+    'read:users',
+    'write:users',
+    'delete:users',
+    'read:events',
+    'write:events',
+    'admin:organisation',
+  ],
+} as const;