@jmruthers/pace-core 0.5.181 → 0.5.182

package/docs/rbac/README-rbac-rls-integration.md

@@ -1,374 +0,0 @@
----
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
----
-
-# RBAC-RLS Integration: Dynamic Permission Enforcement
-
-> **🚨 Critical Architecture Fix** - This integration solves the fundamental disconnect between configurable RBAC permissions and hardcoded RLS policies that was breaking core functionality.
-
-## Overview
-
-The RBAC-RLS integration provides dynamic permission enforcement that automatically respects RBAC configuration changes. This solves the critical issue where:
-
-- **RBAC permissions are configurable** - Organisations can set which roles have which CRUD permissions for each page ✅
-- **RLS policies were hardcoded** - Database-level security policies were static and didn't respect the dynamic RBAC configuration ❌
-- **Result:** Users with valid RBAC permissions were blocked by RLS policies, breaking core functionality
-
-## Quick Start
-
-### 1. Apply the Migration
-
-```bash
-# Apply the complete RBAC-RLS integration
-supabase migration up
-```
-
-### 2. Register Your Tables
-
-```sql
--- Register tables for RBAC policy management
-SELECT register_rbac_table('cake_meal', 'meals', 'CAKE', 'organisation_id', 'meal_event_id');
-SELECT register_rbac_table('cake_delivery', 'deliveries', 'CAKE', 'organisation_id', 'delivery_event_id');
-```
-
-### 3. Update Policies
-
-```sql
--- Update all policies to use RBAC-aware permission checking
-SELECT update_all_rbac_policies();
-```
-
-### 4. Verify the Integration
-
-```sql
--- Check policy health
-SELECT * FROM check_rbac_policy_health();
-
--- Test permission checking
-SELECT check_rbac_permission_with_context('delete', 'meals', 'org-uuid', 'event-123', 'CAKE');
-```
-
-## Key Features
-
-### 🔄 Dynamic Permission Checking
-- **Real-time RBAC respect** - Policies automatically adapt to permission changes
-- **Context-aware security** - Checks both organisation and event context
-- **Performance optimized** - Efficient database functions with proper indexing
-
-### 🛠️ Automatic Policy Management
-- **Change detection** - Policies update automatically when RBAC permissions change
-- **Audit logging** - Complete trail of all policy changes
-- **Health monitoring** - Continuous validation of policy consistency
-
-### 🎯 Developer Tools
-- **SQL function management** - Direct database functions for policy management
-- **Comprehensive testing** - Built-in test suite for validation
-- **Debug utilities** - Easy troubleshooting and monitoring
-
-## Architecture
-
-### Before (Problematic)
-```
-Frontend RBAC Check → ✅ User has permission
-Database RLS Policy → ❌ Hardcoded role check fails
-Result → Operation appears to succeed but fails silently
-```
-
-### After (Fixed)
-```
-Frontend RBAC Check → ✅ User has permission
-Database RLS Policy → ✅ Dynamic RBAC check passes
-Result → Operation succeeds as expected
-```
-
-## Core Functions
-
-### Permission Checking
-```sql
--- Basic permission check
-SELECT check_rbac_permission('delete', 'meals', 'event-123', 'org-uuid', 'CAKE');
-
--- Context-aware permission check
-SELECT check_rbac_permission_with_context('delete', 'meals', resource.organisation_id, resource.meal_event_id, 'CAKE');
-```
-
-### Policy Management
-```sql
--- Create RBAC-aware policy
-SELECT create_rbac_rls_policy('cake_meal', 'DELETE', 'meals', 'rbac_delete_meals');
-
--- Update all policies
-SELECT update_all_rbac_policies();
-
--- Register new table
-SELECT register_rbac_table('your_table', 'your_page', 'YOUR_APP');
-```
-
-## Policy Management
-
-All policy management is done through SQL functions. Connect to your Supabase database and use these commands:
-
-### Usage
-
-```sql
--- List registered tables
-SELECT * FROM rbac_policy_configs WHERE is_active = true;
-
--- Register a new table
-SELECT register_rbac_table('cake_meal', 'meals', 'CAKE', 'organisation_id', 'meal_event_id');
-
--- Update policies for a specific table
-SELECT update_rbac_policies_for_table('cake_meal', 'meals', 'CAKE');
-
--- Update all policies
-SELECT * FROM update_all_rbac_policies();
-
--- Check policy health
-SELECT * FROM check_rbac_policy_health();
-
--- View audit log
-SELECT * FROM rbac_policy_audit 
-ORDER BY changed_at DESC 
-LIMIT 50;
-
--- Test permission check
-SELECT check_rbac_permission_with_context(
-  'delete', 
-  'meals', 
-  'org-uuid-here', 
-  'event-123'::uuid, 
-  'CAKE'
-);
-```
-
-## Migration Guide
-
-### From Hardcoded to Dynamic
-
-#### Before (Hardcoded)
-```sql
-CREATE POLICY "Users can delete meals for their events" ON cake_meal
-FOR DELETE TO public
-USING (EXISTS (SELECT 1 FROM rbac_event_app_roles r 
-  WHERE r.user_id = auth.uid() 
-    AND r.event_id::text = cake_meal.meal_event_id::text 
-    AND r.role = 'event_admin'::rbac_event_app_role));
-```
-
-#### After (Dynamic)
-```sql
-CREATE POLICY "rbac_delete_meals" ON cake_meal
-FOR DELETE
-USING (
-  check_rbac_permission_with_context(
-    'delete',
-    'meals',
-    organisation_id,
-    meal_event_id,
-    'CAKE'
-  )
-);
-```
-
-### Migration Steps
-
-1. **Apply the migration** - Run the complete RBAC-RLS integration migration
-2. **Register tables** - Use `register_rbac_table()` for each table you want to manage
-3. **Update policies** - Use `update_all_rbac_policies()` to create RBAC-aware policies
-4. **Test thoroughly** - Use the SQL test functions to verify everything works
-5. **Monitor changes** - Use the audit log and health checks for ongoing monitoring
-
-## Examples
-
-### React Component Usage
-```tsx
-import { PagePermissionGuard } from '@jmruthers/pace-core/rbac';
-
-function MealsPage() {
-  return (
-    <div>
-      <PagePermissionGuard
-        pageName="meals"
-        operation="delete"
-        fallback={<div>You don't have permission to delete meals</div>}
-      >
-        <button onClick={handleDeleteMeal}>
-          Delete Selected Meal
-        </button>
-      </PagePermissionGuard>
-    </div>
-  );
-}
-```
-
-### Database Permission Testing
-```sql
--- Test different permission scenarios
-SELECT 
-  'planner delete meals' as test_case,
-  check_rbac_permission_with_context('delete', 'meals', 'org-uuid', 'event-123', 'CAKE') as result
-UNION ALL
-SELECT 
-  'planner delete deliveries',
-  check_rbac_permission_with_context('delete', 'deliveries', 'org-uuid', 'event-123', 'CAKE');
-```
-
-### Dynamic Permission Changes
-```sql
--- Change permissions in real-time
-UPDATE rbac_page_permissions 
-SET allowed = false 
-WHERE app_page_id = 'page-meals-id' 
-  AND role_name = 'planner' 
-  AND operation = 'delete';
-
--- Policies automatically update to reflect the change!
-```
-
-## Monitoring and Maintenance
-
-### Health Checks
-```sql
--- Regular health monitoring
-SELECT * FROM check_rbac_policy_health();
-
--- Policy status overview
-SELECT * FROM rbac_policy_status;
-
--- Recent changes
-SELECT * FROM rbac_recent_changes;
-```
-
-### Audit Logging
-```sql
--- View all policy changes
-SELECT * FROM rbac_policy_audit 
-ORDER BY changed_at DESC;
-
--- Filter by success/failure
-SELECT * FROM rbac_policy_audit 
-WHERE success = false
-ORDER BY changed_at DESC;
-```
-
-## Troubleshooting
-
-### Common Issues
-
-#### 1. Policies Not Created
-**Problem:** `create_rbac_rls_policy()` returns false
-**Solution:** 
-- Check that the table exists and you have proper permissions
-- Verify the page and app are properly configured
-- Check the audit log for error details
-
-#### 2. Permission Checks Fail
-**Problem:** `check_rbac_permission()` returns false when it should return true
-**Solution:**
-- Verify the user has the correct role in `rbac_event_app_roles`
-- Check that the page permissions exist in `rbac_page_permissions`
-- Ensure the app and page are properly configured
-- Test with SQL: `SELECT check_rbac_permission('delete', 'meals', 'event-123', 'org-uuid', 'CAKE');`
-
-#### 3. Policies Not Updating
-**Problem:** Changes to RBAC permissions don't reflect in RLS policies
-**Solution:**
-- Check that the table is registered in `rbac_policy_configs`
-- Verify the trigger is working: `SELECT * FROM rbac_policy_audit ORDER BY changed_at DESC LIMIT 10;`
-- Manually update: `SELECT update_rbac_policies_for_table('table_name', 'page_name');`
-
-### Debug Commands
-
-```sql
--- Check policy health
-SELECT * FROM check_rbac_policy_health();
-
--- View recent changes
-SELECT * FROM rbac_policy_audit 
-ORDER BY changed_at DESC 
-LIMIT 20;
-
--- Test specific permission
-SELECT check_rbac_permission_with_context(
-  'delete', 
-  'meals', 
-  'org-uuid-here', 
-  'event-123'::uuid, 
-  'CAKE'
-);
-
--- Update all policies
-SELECT * FROM update_all_rbac_policies();
-```
-
-## Performance Considerations
-
-### Optimization
-- RBAC functions are optimized for performance with proper indexing
-- Permission checks are cached at the application level
-- Database queries are optimized for minimal overhead
-
-### Monitoring
-```sql
--- Check for slow permission checks
-SELECT 
-  query,
-  calls,
-  total_time,
-  mean_time
-FROM pg_stat_statements
-WHERE query LIKE '%check_rbac_permission%'
-ORDER BY mean_time DESC;
-```
-
-## Security
-
-### Best Practices
-- Always use `check_rbac_permission_with_context()` for resource-specific operations
-- Validate organisation and event context
-- Test permission changes thoroughly
-- Monitor the audit log for suspicious activity
-
-### Principle of Least Privilege
-- Default to deny, only allow explicitly granted permissions
-- Regular security audits using health checks
-- Complete audit trail of all permission changes
-
-## Documentation
-
-- **[Complete Integration Guide](./rbac-rls-integration.md)** - Detailed technical documentation
-- **[Examples](./examples/rbac-rls-integration-example.md)** - Practical usage examples
-- **[API Reference](./api-reference.md)** - Complete function reference
-- **[Troubleshooting](./troubleshooting.md)** - Common issues and solutions
-
-## Support
-
-### Getting Help
-1. Check the troubleshooting section above
-2. Review the audit log for error details
-3. Use the SQL functions for debugging
-4. Check the health monitoring views
-
-### Reporting Issues
-When reporting issues, please include:
-- The specific error message
-- Relevant audit log entries
-- Health check results
-- Steps to reproduce the issue
-
-## Conclusion
-
-The RBAC-RLS integration provides a robust, scalable solution for dynamic permission enforcement. It solves the critical architectural issue where RBAC configuration and RLS policies were disconnected, ensuring that:
-
-1. **Organisations have true control** over their permission systems
-2. **Developers can rely on consistent behavior** across all operations
-3. **Users get the functionality they expect** based on their assigned roles
-4. **The system is maintainable and auditable** with clear change tracking
-
-This integration is not just a bug fix - it's a fundamental improvement to the pace-core architecture that will benefit all current and future applications in the suite.
-
----
-
-**🎉 Your pace-core system now has true dynamic permission enforcement!**

package/docs/styles/usage.md

@@ -1,227 +0,0 @@
----
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
----
-
-# PACE Core Styling Usage Guide
-
-This guide explains how to integrate PACE Core's new styling system into your application.
-
-## Quick Start
-
-### 1. Install PACE Core
-
-```bash
-npm install @jmruthers/pace-core
-```
-
-### 2. Create Your App CSS File
-
-Create `src/app.css` in your consuming app with your brand colors and source directives:
-
-```css
-@import "tailwindcss";
-
-/* @source directives for Tailwind v4 content scanning */
-@source "./src/**/*.{js,ts,jsx,tsx}";
-@source "./node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}";
-@source "./node_modules/@jmruthers/pace-core/src/components/**/*.{js,ts,jsx,tsx}";
-@source "./node_modules/@jmruthers/pace-core/src/providers/**/*.{js,ts,jsx,tsx}";
-@source "./node_modules/@jmruthers/pace-core/src/hooks/**/*.{js,ts,jsx,tsx}";
-@source "./node_modules/@jmruthers/pace-core/src/utils/**/*.{js,ts,jsx,tsx}";
-@source "./node_modules/@jmruthers/pace-core/src/types/**/*.{js,ts,jsx,tsx}";
-@source "./node_modules/@jmruthers/pace-core/src/validation/**/*.{js,ts,jsx,tsx}";
-@source "./node_modules/@jmruthers/pace-core/src/rbac/**/*.{js,ts,jsx,tsx}";
-
-/* Define your brand color palettes */
-@theme static {
-  /* Your main, secondary, and accent color palettes here */
-  /* See the styling guide for the complete structure */
-}
-```
-
-### 3. Import Both CSS Files
-
-In your app's entry point (e.g., `main.tsx` or root layout):
-
-```tsx
-// Import the core CSS file first
-import '@jmruthers/pace-core/src/styles/core.css';
-
-// Import your app-specific colors second
-import './app.css';
-```
-
-### 4. Use Your Brand Colors
-
-Your app now uses your custom color palette defined in `app.css`. All pace-core components will automatically use your brand colors through the semantic token system.
-
-### 5. Use Components
-
-Now you can use PACE Core components with native Tailwind utilities:
-
-```tsx
-import { Button, Card, DataTable } from '@jmruthers/pace-core';
-
-function MyComponent() {
-  return (
-    <Card className="bg-main-50 border-main-200">
-      <h2 className="text-main-900">Welcome</h2>
-      <p className="text-sec-700">This uses your brand colors!</p>
-      <Button className="bg-main-600 hover:bg-main-700">
-        Click me
-      </Button>
-    </Card>
-  );
-}
-```
-
-## Dynamic Theming
-
-### Automatic Event Theming (Recommended)
-
-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';
-
-// Apply organisation colors
-function applyOrganisationColors(orgData: any) {
-  applyPalette({
-    main: orgData.colors.main,
-    sec: orgData.colors.sec,
-    acc: orgData.colors.acc
-  });
-}
-
-// Clear dynamic theming (return to app defaults)
-function resetToAppColors() {
-  clearPalette();
-}
-```
-
-### SSR Support
-
-For server-side rendering, generate the theme CSS:
-
-```tsx
-import { generateSSRThemeCSS } from '@jmruthers/pace-core/theming/runtime';
-
-// In your SSR setup
-const themeCSS = generateSSRThemeCSS(paletteData);
-// Inject into your HTML head
-```
-
-## Available Utilities
-
-### Color Utilities
-
-- `bg-main-50` through `bg-main-950`
-- `text-main-50` through `text-main-950`
-- `border-main-200`, `border-main-300`
-- `ring-main-500`, `ring-sec-500`, `ring-acc-500`
-
-Same patterns for `sec-*` and `acc-*` palettes.
-
-### Semantic Color Utilities
-
-PACE Core also provides semantic color utilities that automatically map to your palettes:
-
-- `bg-background`, `text-foreground` - Main background and text
-- `bg-primary`, `text-primary-foreground` - Primary actions
-- `bg-secondary`, `text-secondary-foreground` - Secondary elements
-- `bg-destructive`, `text-destructive-foreground` - Destructive actions
-- `bg-muted`, `text-muted-foreground` - Muted content
-- `bg-accent`, `text-accent-foreground` - Accent elements
-- `bg-card`, `text-card-foreground` - Card backgrounds
-- `bg-popover`, `text-popover-foreground` - Popover backgrounds
-
-### Typography
-
-- `font-sans` - Open Sans
-- `font-serif` - Open Sans (serif fallback)
-- `font-mono` - Reddit Mono
-
-### Other Utilities
-
-- `rounded-sm` through `rounded-2xl`
-- `shadow-sm` through `shadow-2xl`
-- Custom utilities: `.pace-text-balance`, `.pace-scrollbar-hide`
-
-## Migration from Old System
-
-### Before (Old System)
-```tsx
-// Old app-* classes
-<div className="bg-main-500 text-main-50">
-  <Button className="bg-sec-600 hover:bg-sec-700">
-    Click me
-  </Button>
-</div>
-```
-
-### After (New System)
-```tsx
-// New native utilities
-<div className="bg-main-500 text-main-50">
-  <Button className="bg-sec-600 hover:bg-sec-700">
-    Click me
-  </Button>
-</div>
-```
-
-## Constraints
-
-- **No arbitrary values**: Use only standard utilities like `bg-main-600`, not `bg-[oklch(...)]`
-- **No CVA**: Components use native Tailwind utilities, not class-variance-authority
-- **No utility aliases**: Use standard Tailwind class names
-- **Default palettes included**: pace-core provides sensible defaults, but you can override with `app.css`
-- **Tailwind v4 only**: Uses CSS-first approach with `@theme` blocks, no `tailwind.config.js`
-
-## Troubleshooting
-
-### Colors Not Appearing
-- Ensure you've imported `@jmruthers/pace-core/src/styles/core.css`
-- If using custom palettes, check that your `app.css` defines the complete palette
-- Verify Tailwind v4 is installed
-- Check that font files are available in your `/fonts` directory
-
-
-### Dynamic Theming Issues
-- Verify palette data has correct structure (main/sec/acc with 50-950 shades)
-- Check browser console for errors
-- Use `isDynamicThemingActive()` to debug
-
-## Visual Testing
-
-For visual regression testing and component verification, see the [Visual Testing Guide](./visual-testing.md).
-
-## Support
-
-For issues or questions:
-- Check the [GitHub repository](https://github.com/jmruthers/pace-core)
-- Review component documentation
-- See [Visual Testing Guide](./visual-testing.md) for visual regression testing
-- Open an issue with reproduction steps

package/docs/testing/visual-testing.md

@@ -1,120 +0,0 @@
----
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
----
-
-# Visual Testing Guide
-
-This document outlines the visual testing approach for pace-core components to ensure visual parity after the styling refactor.
-
-## Before/After Visual Testing
-
-### Testing Approach
-
-1. **Component Snapshots**: Each component should be tested with visual snapshots
-2. **Color Variations**: Test with different palette combinations
-4. **Responsive**: Test at different screen sizes
-
-### Key Components to Test
-
-#### Button Component
-- **Variants**: default, destructive, outline, secondary, ghost, link
-- **Sizes**: sm, default, lg, icon
-- **States**: normal, hover, active, disabled, focus
-
-#### Card Component  
-- **Variants**: default, outline, ghost
-- **Sizes**: default, sm, lg
-- **Content**: with/without header, footer, actions
-
-#### DataTable Component
-- **States**: empty, loading, with data
-- **Features**: sorting, filtering, pagination
-- **Responsive**: mobile, tablet, desktop
-
-### Visual Regression Testing
-
-#### Setup
-```bash
-# Install visual testing tools
-npm install --save-dev @storybook/react @storybook/addon-storyshots
-
-# Run visual tests
-npm run test:visual
-```
-
-#### Test Cases
-
-1. **Light Mode Default Palette**
-   - Use default main/sec/acc colors
-   - Verify all components render correctly
-   - Check color contrast ratios
-
-   - Check no hue shifts occur
-
-3. **Dynamic Palette Replacement**
-   - Apply different organisation palettes
-   - Verify all components update correctly
-   - Test palette switching
-
-4. **Custom App Palettes**
-   - Test with different brand colors
-   - Verify OKLCH format works correctly
-   - Check all shade variations (50-950)
-
-### Visual Parity Checklist
-
-- [ ] Button variants maintain same visual appearance
-- [ ] Card shadows and borders unchanged
-- [ ] DataTable styling consistent
-- [ ] Typography hierarchy preserved
-- [ ] Focus states work correctly
-- [ ] Hover effects unchanged
-- [ ] Spacing and layout identical
-- [ ] Color contrast maintained
-- [ ] Dynamic theming works
-
-### Screenshot Comparison
-
-#### Before (Legacy System)
-- Components using `app-*` classes
-- CVA-based styling
-- Complex theming system
-
-#### After (New System)
-- Components using native utilities (`main-*`, `sec-*`, `acc-*`)
-- No CVA dependency
-- Simple runtime theming
-
-### Testing Tools
-
-1. **Chromatic** - Visual regression testing
-2. **Percy** - Cross-browser visual testing  
-3. **Storybook** - Component isolation and testing
-4. **Playwright** - Automated visual testing
-
-### Manual Testing Checklist
-
-- [ ] All components render without errors
-- [ ] Colors display correctly in light mode
-- [ ] Dynamic palette switching works
-- [ ] No visual regressions detected
-- [ ] Performance is maintained or improved
-- [ ] Accessibility features work correctly
-
-### Reporting Issues
-
-If visual regressions are found:
-
-1. Document the specific component and variant
-2. Note the expected vs actual appearance
-3. Check if it's a color mapping issue
-4. Verify the palette values are correct
-5. Test with different color combinations
-
-### Maintenance
-
-- Update visual tests when adding new components
-- Re-run tests after palette changes
-- Test dynamic theming with new palettes