@jmruthers/pace-core 0.5.115 → 0.5.117

package/docs/architecture/rpc-function-standards.md

@@ -714,6 +714,9 @@ rbac_check_permission_simplified(
    - ❌ **WRONG**: `SELECT mealtype_name FROM cake_mealtype`
    - ✅ **CORRECT**: `SELECT cake_mealtype.mealtype_name FROM cake_mealtype`
    - Always fully qualify table names when there might be ambiguity
+   - **MANDATORY**: When using JOINs, always use table aliases and prefix ALL column references
+   - Common ambiguous columns: `organisation_id`, `created_by`, `updated_by`, `created_at`, `updated_at`
+   - See "Avoiding Ambiguous Column References" section below for detailed guidance
 
 5. **Not checking existing migrations**: Before creating a new migration, check if a similar one already exists to avoid duplicates
 
@@ -736,6 +739,190 @@ rbac_check_permission_simplified(
 
 3. **Update references** - Update all callers before removing
 
+## Avoiding Ambiguous Column References
+
+### Overview
+
+Ambiguous column reference errors occur when PostgreSQL cannot determine which table a column belongs to in a query with JOINs. This is a common source of silent failures in RPC functions.
+
+### Mandatory Rules
+
+1. **Always use table aliases in JOINs**: Never write JOINs without table aliases
+2. **Fully qualify ALL column references**: Every column in SELECT, WHERE, ORDER BY, GROUP BY, and HAVING clauses must be prefixed with its table alias
+3. **Common ambiguous columns**: The following columns exist in multiple tables and MUST always be prefixed:
+   - `organisation_id`
+   - `created_by`, `updated_by`
+   - `created_at`, `updated_at`
+   - `event_id` and its variations (e.g., `dish_event_id`, `meal_event_id`)
+
+### Correct Patterns
+
+```sql
+-- ✅ CORRECT: All columns properly prefixed with table aliases
+SELECT 
+  d.dish_id,
+  d.dish_name,
+  d.organisation_id,
+  d.created_at,
+  mt.mealtype_name,
+  e.event_name,
+  e.organisation_id AS event_organisation_id
+FROM cake_dish d
+LEFT JOIN cake_mealtype mt ON d.dish_mealtype_id = mt.mealtype_id
+LEFT JOIN event e ON d.dish_event_id = e.event_id
+WHERE d.dish_event_id = p_event_id
+  AND d.organisation_id = p_organisation_id
+ORDER BY d.dish_code, mt.mealtype_name;
+
+-- ✅ CORRECT: CTEs with proper aliases
+WITH distribution_items AS (
+  SELECT
+    d.item_id,
+    d.collection_date,
+    SUM(d.required_quantity) as total_quantity
+  FROM data_cake_distribution_list(p_event_id, p_user_id, p_organisation_id) d
+  GROUP BY d.item_id, d.collection_date
+)
+SELECT 
+  di.item_id,
+  di.collection_date,
+  di.total_quantity
+FROM distribution_items di
+WHERE di.item_id = p_item_id;
+```
+
+### Incorrect Patterns
+
+```sql
+-- ❌ WRONG: Missing table prefixes in SELECT
+SELECT 
+  dish_id,
+  dish_name,
+  organisation_id,  -- AMBIGUOUS: Could be from cake_dish or event
+  mealtype_name
+FROM cake_dish d
+LEFT JOIN cake_mealtype mt ON d.dish_mealtype_id = mt.mealtype_id
+LEFT JOIN event e ON d.dish_event_id = e.event_id;
+
+-- ❌ WRONG: Missing table prefix in WHERE clause
+SELECT d.dish_id, d.dish_name
+FROM cake_dish d
+LEFT JOIN event e ON d.dish_event_id = e.event_id
+WHERE organisation_id = p_organisation_id;  -- AMBIGUOUS: Which table?
+
+-- ❌ WRONG: Missing table prefix in ORDER BY
+SELECT d.dish_id, d.dish_name, e.event_name
+FROM cake_dish d
+LEFT JOIN event e ON d.dish_event_id = e.event_id
+ORDER BY created_at;  -- AMBIGUOUS: Which table's created_at?
+
+-- ❌ WRONG: SELECT INTO with multiple columns but wrong variable count
+SELECT d.dish_code, d.dish_name, mt.mealtype_name
+INTO v_mealtype_name  -- WRONG: Only one variable for three columns
+FROM cake_dish d
+LEFT JOIN cake_mealtype mt ON d.dish_mealtype_id = mt.mealtype_id;
+```
+
+### SELECT INTO Statements
+
+When using `SELECT ... INTO`, ensure:
+1. The number of columns matches the number of variables
+2. All columns are properly prefixed with table aliases
+3. Use separate variables for each column
+
+```sql
+-- ✅ CORRECT: Proper SELECT INTO with multiple variables
+DECLARE
+  v_dish_code TEXT;
+  v_dish_name TEXT;
+  v_mealtype_name TEXT;
+  v_updated_at TIMESTAMPTZ;
+BEGIN
+  SELECT 
+    d.dish_code,
+    d.dish_name,
+    mt.mealtype_name,
+    d.updated_at
+  INTO 
+    v_dish_code,
+    v_dish_name,
+    v_mealtype_name,
+    v_updated_at
+  FROM cake_dish d
+  LEFT JOIN cake_mealtype mt ON d.dish_mealtype_id = mt.mealtype_id
+  WHERE d.dish_id = p_dish_id;
+END;
+```
+
+### CTEs and Subqueries
+
+When using CTEs (Common Table Expressions) or subqueries:
+1. Use descriptive aliases for CTEs
+2. Fully qualify all column references within CTEs
+3. When referencing CTEs in the main query, use the CTE alias
+
+```sql
+-- ✅ CORRECT: CTE with proper aliases
+WITH unit_diners AS (
+  SELECT 
+    d.diner_unit_id,
+    d.diner_diettype_id,
+    SUM(COALESCE(d.diner_adult, 0)) as adults,
+    SUM(COALESCE(d.diner_youth, 0)) as youth
+  FROM cake_diner d
+  INNER JOIN event_units eu ON d.diner_unit_id = eu.unit_id
+  WHERE (d.diner_adult > 0 OR d.diner_youth > 0)
+  GROUP BY d.diner_unit_id, d.diner_diettype_id
+)
+SELECT 
+  ud.diner_unit_id,
+  ud.adults,
+  ud.youth
+FROM unit_diners ud
+WHERE ud.diner_unit_id = p_unit_id;
+```
+
+### Table Alias Naming Conventions
+
+Use short, descriptive aliases:
+- `d` for `cake_dish`
+- `r` for `cake_recipe`
+- `m` for `cake_meal`
+- `mt` for `cake_mealtype`
+- `i` for `cake_item`
+- `dt` for `cake_diettype`
+- `e` for `event`
+- `u` for `cake_unit`
+- `mp` for `cake_mealplan`
+
+### UPDATE Statements
+
+For UPDATE statements, the WHERE clause should reference the table being updated:
+
+```sql
+-- ✅ CORRECT: WHERE clause uses table name or alias
+UPDATE cake_dish
+SET dish_name = p_dish_name,
+    updated_by = p_user_id,
+    updated_at = now()
+WHERE dish_id = p_dish_id;  -- dish_id is unambiguous (primary key)
+
+-- ✅ CORRECT: When updating with JOIN, qualify all columns
+UPDATE cake_dish d
+SET d.dish_name = p_dish_name
+FROM cake_mealtype mt
+WHERE d.dish_mealtype_id = mt.mealtype_id
+  AND d.dish_id = p_dish_id;
+```
+
+### Testing for Ambiguous References
+
+Before deploying, test your function:
+1. Call the function with valid parameters
+2. Check PostgreSQL logs for "ambiguous column reference" errors
+3. Verify all column references are prefixed in JOINs
+4. Test with multiple tables that share column names
+
 ## Common Patterns
 
 ### Pattern 1: Simple Data Retrieval
@@ -871,6 +1058,12 @@ When creating or reviewing an RPC function, ensure:
 - ✅ **File naming**: `YYYYMMDDHHMMSS_descriptive_name.sql`
 - ✅ **No ambiguous column references**: Fully qualify table names (e.g., `cake_mealtype.mealtype_name`)
 
+### ⚠️ Column Reference Requirements
+- ✅ **All column references in JOINs are fully qualified with table aliases**: Every column in SELECT, WHERE, ORDER BY, GROUP BY, HAVING must have table prefix
+- ✅ **No ambiguous column references in WHERE, ORDER BY, GROUP BY, HAVING clauses**: All columns must be prefixed with table alias
+- ✅ **Table aliases used consistently and meaningfully**: Use short, descriptive aliases (e.g., `d` for dish, `r` for recipe)
+- ✅ **SELECT INTO statements match variable count**: Number of columns must match number of variables
+
 ## References
 
 - [RBAC System Documentation](../core-concepts/rbac-system.md)

package/package.json

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

package/src/__tests__/TEST_STANDARD.md

@@ -329,6 +329,19 @@ expect(screen.getByText('Visible content')).toBeInTheDocument();
 expect(screen.queryByText('Hidden content')).not.toBeInTheDocument();
 ```
 
+### 2. Skipped Tests Without Documentation
+
+```typescript
+// ❌ Bad - Skipped test without explanation
+it.skip('should navigate with keyboard', () => {});
+
+// ✅ Good - Skipped test with clear documentation
+// TODO: Enable when keyboard navigation is implemented
+// See: https://github.com/org/repo/issues/123
+// Expected: Q2 2025
+it.skip('should navigate with keyboard', () => {});
+```
+
 ### 2. Brittle Selectors
 
 ```typescript
@@ -530,9 +543,24 @@ await waitFor(() => {
 
 await waitFor(() => {
   expect(result.current.data).toBeDefined();
-}, { timeout: 5000 }); // Slow operations only
+}, { timeout: 2000 }); // Most async operations (2-3 seconds)
+
+// ⚠️ Only use 5+ seconds for truly slow operations
+await waitFor(() => {
+  expect(result.current.data).toBeDefined();
+}, { timeout: 5000 }); // Network calls, complex computations only
 ```
 
+**Timeout Guidelines**:
+- **Fast operations** (< 100ms): `timeout: 100-500`
+- **Standard async** (100ms-2s): `timeout: 2000-3000`
+- **Slow operations** (2s+): `timeout: 5000+` (with documentation)
+
+**Avoid**:
+- ❌ Using 5-6 second timeouts for mock operations that resolve immediately
+- ❌ Using `waitFor` for synchronous operations
+- ❌ Unnecessary delays in mock implementations
+
 ## 🔧 Test Configuration
 
 ### Vitest Configuration
@@ -618,7 +646,7 @@ screen.logTestingPlaygroundURL();
 
 ## 📋 Pre-Merge Checklist
 
-- [ ] All tests pass without `it.only` or `test.skip`
+- [ ] All tests pass without `it.only` or `test.skip` (see Skipped Test Policy below)
 - [ ] Coverage thresholds are met
 - [ ] Tests use semantic queries (avoid test IDs)
 - [ ] Async operations use proper waiting patterns
@@ -626,6 +654,7 @@ screen.logTestingPlaygroundURL();
 - [ ] Tests focus on behavior, not implementation
 - [ ] Error scenarios are covered
 - [ ] Tests are colocated with source files
+- [ ] Timeout values are appropriate (see Performance Guidelines below)
 
 ## 🎯 Test Categories & Tags
 
@@ -672,3 +701,216 @@ A world-class test suite demonstrates:
 - **Accessibility Awareness** - Tests include a11y considerations
 
 Remember: **Tests are not just about catching bugs—they're about building confidence, enabling refactoring, and documenting expected behavior for future developers.**
+
+---
+
+## 🔄 Skipped Test Policy
+
+### When to Skip Tests
+
+**✅ Appropriate Reasons**:
+- Feature is planned but not yet implemented
+- Test documents future feature requirements
+- Feature is blocked by dependencies
+- Test is for experimental/optional feature
+
+**❌ Inappropriate Reasons**:
+- Test is flaky (fix the test instead)
+- Test is slow (optimize instead)
+- Feature is deprecated (remove test)
+- Test is temporarily broken (fix immediately)
+
+### Requirements for Skipped Tests
+
+1. **Clear Documentation**: Add comment explaining why test is skipped
+2. **Reference Tracking**: Link to feature issue or ticket
+3. **Expected Timeline**: Include expected implementation date (if known)
+4. **Quarterly Review**: Review skipped tests quarterly to determine if still relevant
+
+### Example
+
+```typescript
+// TODO: Enable when keyboard navigation is implemented
+// See: https://github.com/org/repo/issues/123
+// Expected: Q2 2025
+it.skip('should navigate between headers with arrow keys', async () => {
+  // Test implementation
+});
+```
+
+### Skipped Test Review Process
+
+1. **Quarterly Audit**: Review all skipped tests
+2. **Decision Matrix**:
+   - Feature implemented → Enable test
+   - Feature cancelled → Remove test
+   - Feature deferred → Update timeline
+   - Still relevant → Keep skipped with updated timeline
+3. **Documentation**: Update test comments with current status
+
+---
+
+## 📊 Coverage Gap Remediation
+
+### Coverage Thresholds
+
+| Category | Target | CI Blocking | Rationale |
+|----------|--------|-------------|-----------|
+| **Utils/Hooks** | 95% | Yes | Core business logic, high reuse |
+| **UI Components** | 90% | Yes | User-facing, must be reliable |
+| **Services** | 85% | Yes | API interactions, critical paths |
+| **Validation** | 95% | Yes | Security and data integrity |
+| **Overall Project** | 80% | Yes | Quality baseline |
+
+### Identifying Coverage Gaps
+
+1. **Run Coverage Report**:
+   ```bash
+   npm test -- --coverage
+   ```
+
+2. **Review Coverage Report**:
+   - Check per-file coverage percentages
+   - Identify files below thresholds
+   - Review uncovered lines/branches
+
+3. **Prioritize Gaps**:
+   - **Critical**: RBAC, auth, services
+   - **High**: Business logic, hooks
+   - **Medium**: UI components, utilities
+   - **Low**: Type definitions, simple utilities
+
+### Remediation Process
+
+1. **Analyze Gap**: Understand what's not covered
+2. **Create Test Plan**: Determine test type (unit, integration)
+3. **Write Tests**: Follow TEST_STANDARD.md patterns
+4. **Verify Coverage**: Run coverage report to confirm improvement
+5. **Document**: Add comments for complex test scenarios
+
+### Coverage Improvement Checklist
+
+- [ ] Identify files below thresholds
+- [ ] Prioritize critical paths
+- [ ] Create test plan for each file
+- [ ] Write tests following TEST_STANDARD.md
+- [ ] Verify coverage improvement
+- [ ] Document complex test scenarios
+
+---
+
+## ⚡ Performance Test Guidelines
+
+### Test Execution Time Targets
+
+- **Unit Tests**: < 50ms average
+- **Component Tests**: < 100ms average
+- **Integration Tests**: < 500ms average
+- **E2E Tests**: < 2s average
+
+### Timeout Best Practices
+
+**Standard Timeouts**:
+- Fast operations: `timeout: 100-500`
+- Standard async: `timeout: 2000-3000`
+- Slow operations: `timeout: 5000+` (with documentation)
+
+**Optimization Tips**:
+1. Use immediate mock resolution when possible
+2. Avoid unnecessary `setTimeout` in mocks
+3. Use `findBy` queries instead of `waitFor` + `getBy`
+4. Reduce timeout values for fast operations
+
+### Memory Management
+
+```typescript
+describe('Component with Resources', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    // Prevent memory leaks
+    vi.clearAllTimers();
+    vi.useRealTimers();
+    cleanup();
+    vi.clearAllMocks();
+    localStorage.clear();
+    sessionStorage.clear();
+  });
+});
+```
+
+### Performance Monitoring
+
+- Monitor test execution times in CI
+- Track slow tests (> 100ms)
+- Alert on tests exceeding thresholds
+- Review and optimize slow tests regularly
+
+---
+
+## 📁 Large Test File Management
+
+### When to Split Test Files
+
+**Consider Splitting When**:
+- File exceeds 800 lines
+- File contains multiple distinct feature areas
+- File has slow execution times
+- File is difficult to navigate
+
+### Splitting Strategy
+
+**By Feature Area**:
+```
+Component.test.tsx          → Component.rendering.test.tsx
+                            → Component.interactions.test.tsx
+                            → Component.state.test.tsx
+```
+
+**By Test Type**:
+```
+Component.test.tsx          → Component.unit.test.tsx
+                            → Component.integration.test.tsx
+                            → Component.accessibility.test.tsx
+```
+
+### Splitting Guidelines
+
+1. **Keep Related Tests Together**: Don't split if tests are tightly coupled
+2. **Maintain Test Organization**: Use describe blocks for organization
+3. **Share Test Utilities**: Extract shared setup to test utilities
+4. **Document Structure**: Add README explaining test organization
+
+### File Size Recommendations
+
+- **< 500 lines**: No splitting needed
+- **500-800 lines**: Consider if organization improves
+- **> 800 lines**: Strongly consider splitting
+- **> 1000 lines**: Should be split
+
+---
+
+## 📈 Continuous Improvement
+
+### Regular Reviews
+
+1. **Quarterly**: Review skipped tests, coverage gaps, slow tests
+2. **Monthly**: Review test execution times and patterns
+3. **Per PR**: Ensure new tests follow TEST_STANDARD.md
+
+### Metrics to Track
+
+- Test execution time trends
+- Coverage percentage trends
+- Number of skipped tests
+- Test helper usage patterns
+- Test file sizes
+
+### Resources
+
+- [Coverage Gap Analysis](../../docs/testing/coverage-gap-analysis.md)
+- [Test Quality Audit](../../docs/testing/test-quality-audit.md)
+- [Test Helpers Audit](../../docs/testing/test-helpers-audit.md)
+- [Skipped Tests Analysis](../../docs/testing/skipped-tests-analysis.md)

package/src/components/DataTable/__tests__/a11y.basic.test.tsx

@@ -9,7 +9,7 @@
  */
 
 import React from 'react';
-import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import { render, screen, fireEvent, waitFor, within } from '@testing-library/react';
 import { axe, toHaveNoViolations } from 'jest-axe';
 import userEvent from '@testing-library/user-event';
 import { vi, beforeEach, afterEach } from 'vitest';
@@ -252,7 +252,10 @@ describe('DataTable Accessibility', () => {
       }
     });
 
-    it.skip('should have proper aria-selected on selectable rows', () => {
+    it('should have proper aria-selected on selectable rows', async () => {
+      const user = userEvent.setup({ delay: 0 });
+
+
       render(
         <TestWrapper>
           <DataTable
@@ -264,20 +267,41 @@ describe('DataTable Accessibility', () => {
         </TestWrapper>
       );
 
+      // Wait for table to render with selection enabled
+      await waitFor(() => {
+        const rows = screen.getAllByRole('row');
+        expect(rows.length).toBeGreaterThan(1); // Header + data rows
+        
+        // Verify selection is enabled by checking for selection column header
+        const selectHeader = screen.queryByRole('columnheader', { name: /select all/i });
+        if (defaultFeatures.selection) {
+          expect(selectHeader).toBeInTheDocument();
+        }
+      });
+
       // Find data rows (exclude header row)
       const rows = screen.getAllByRole('row');
       const dataRows = rows.slice(1); // Skip header row
 
-      // Check that we have data rows and they have aria-selected
-      expect(dataRows.length).toBeGreaterThan(0);
-      
-      dataRows.forEach((row, index) => {
-        // Initially, rows should not be selected
+      // Check that selectable data rows expose aria-selected state
+      const selectableRows = dataRows.filter(row => within(row).queryByRole('checkbox'));
+      expect(selectableRows.length).toBeGreaterThan(0);
+
+      selectableRows.forEach(row => {
         const ariaSelected = row.getAttribute('aria-selected');
-        console.log(`Row ${index}:`, ariaSelected);
         expect(row).toHaveAttribute('aria-selected');
-        expect(ariaSelected).toBe('false'); // Should be false initially
+        expect(ariaSelected).toBe('false');
+      });
+
+      const firstRowCheckbox = within(selectableRows[0]).getByRole('checkbox');
+      await user.click(firstRowCheckbox);
+
+      const updatedCheckbox = within(selectableRows[0]).getByRole('checkbox');
+
+      await waitFor(() => {
+        expect(updatedCheckbox).toHaveAttribute('aria-checked', 'true');
       });
+
     });
 
     it('should have aria-busy when loading', () => {
@@ -416,7 +440,8 @@ describe('DataTable Accessibility', () => {
       });
     });
 
-    it.skip('should have proper tab order', () => {
+    it('should expose sortable headers in the tab order', () => {
+
       render(
         <TestWrapper>
           <DataTable
@@ -428,12 +453,17 @@ describe('DataTable Accessibility', () => {
         </TestWrapper>
       );
 
-      // Check that sortable headers are focusable
-      const sortableHeaders = screen.getAllByRole('columnheader').filter(header => 
-        header.hasAttribute('tabindex') && header.getAttribute('tabindex') === '0'
-      );
-      
-      expect(sortableHeaders.length).toBeGreaterThan(0);
+      const sortableHeaderButtons = screen
+        .getAllByRole('columnheader')
+        .map(header => header.querySelector<HTMLButtonElement>('button'))
+        .filter((button): button is HTMLButtonElement => Boolean(button));
+
+      expect(sortableHeaderButtons.length).toBeGreaterThan(0);
+
+      sortableHeaderButtons.forEach(button => {
+        expect(button.tabIndex).toBeGreaterThanOrEqual(0);
+        expect(button).not.toHaveAttribute('aria-hidden', 'true');
+      });
     });
   });