@jmruthers/pace-core 0.2.7 → 0.4.1

package/docs/implementation-guides/forms.md

@@ -350,7 +350,7 @@ function CustomFormField({ name, label, ...props }) {
       </label>
       <FormField name={name} {...props} />
       {fieldError && (
-        <p className="text-sm text-acc-600">
+        <p className="text-sm text-red-600">
           {fieldError.message}
         </p>
       )}
@@ -471,7 +471,7 @@ function FormWithState() {
   required
   aria-describedby="email-help"
 />
-<p id="email-help" className="text-sm text-sec-600">
+<p id="email-help" className="text-sm text-gray-600">
   We'll never share your email address
 </p>
 ```
@@ -568,7 +568,7 @@ function FormDebugger() {
   const { formState } = useFormContext();
   
   return (
-    <pre className="text-xs bg-sec-100 p-2 rounded">
+    <pre className="text-xs bg-gray-100 p-2 rounded">
       {JSON.stringify(formState, null, 2)}
     </pre>
   );

package/docs/implementation-guides/large-datasets.md

@@ -137,8 +137,8 @@ const columns = [
     cell: ({ getValue }) => {
       const value = getValue();
       // Handle zero values explicitly
-      if (value === 0) return <span className="text-sec-500">0</span>;
-      if (value == null) return <span className="text-sec-400">—</span>;
+      if (value === 0) return <span className="text-app-sec-500">0</span>;
+      if (value == null) return <span className="text-app-sec-400">—</span>;
       return value.toLocaleString();
     }
   }

package/docs/implementation-guides/navigation.md

@@ -492,7 +492,7 @@ import { NavigationMenu, Card } from '@jmruthers/pace-core';
 
 function SidebarNavigation() {
   return (
-    <aside className="w-64 bg-sec-50 border-r">
+    <aside className="w-64 bg-gray-50 border-r">
       <Card className="h-full rounded-none border-0">
         <div className="p-4">
           <h2 className="text-lg font-semibold mb-4">Navigation</h2>

package/docs/implementation-guides/permission-enforcement.md

@@ -135,15 +135,15 @@ Provide custom fallback components for better UX:
 ```tsx
 function AccessDeniedPage() {
   return (
-    <div className="flex items-center justify-center min-h-screen bg-sec-50">
+    <div className="flex items-center justify-center min-h-screen bg-gray-50">
       <div className="text-center max-w-md mx-auto p-6">
         <div className="mb-4">
-          <svg className="mx-auto h-12 w-12 text-acc-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+          <svg className="mx-auto h-12 w-12 text-red-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
             <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-2.5L13.732 4c-.77-.833-1.964-.833-2.732 0L3.732 16.5c-.77.833.192 2.5 1.732 2.5z" />
           </svg>
         </div>
-        <h2 className="text-2xl font-bold text-sec-900 mb-2">Access Denied</h2>
-        <p className="text-sec-600 mb-6">
+        <h2 className="text-2xl font-bold text-gray-900 mb-2">Access Denied</h2>
+        <p className="text-gray-600 mb-6">
           You don't have permission to access this page. Please contact your administrator for access.
         </p>
         <div className="space-x-4">

package/docs/migration/README.md

@@ -68,7 +68,7 @@ npm install @jmruthers/pace-core@latest
 **CRITICAL**: Fixed Tailwind v4 theme file with missing semantic colors and circular @apply references.
 
 **Impact**:
-- Build failures when importing `@jmruthers/pace-core/styles/core.css`
+- Build failures when importing `@jmruthers/pace-core/styles/tailwind-v4-theme`
 - Missing semantic colors (ring, border, background, foreground, etc.)
 - Component classes not working due to circular references
 
@@ -90,9 +90,9 @@ npm install @jmruthers/pace-core@latest
 ```
 
 **Usage** (now works out-of-the-box):
-```tsx
-/* main.tsx */
-import '@jmruthers/pace-core/styles/core.css';
+```css
+/* index.css */
+@import '@jmruthers/pace-core/styles/tailwind-v4-theme';
 ```
 
 ```ts
@@ -143,7 +143,7 @@ PACE Core now supports Tailwind CSS v4 with modern CSS-first configuration.
    @tailwind utilities;
 
    /* After (v4) */
-   @import '@jmruthers/pace-core/styles/core.css';
+   @import '@jmruthers/pace-core/styles/tailwind-v4-theme';
    ```
 
 For complete Tailwind v4 setup instructions, see the [Styling Guide](../styles/README.md#tailwind-css-v4-setup).
@@ -270,10 +270,7 @@ function App() {
 **After (PACE Core)**
 ```tsx
 import { UnifiedAuthProvider } from '@jmruthers/pace-core';
-
-// Import the core CSS file - app.css must come first for proper @theme processing
-import './app.css'; // Your app's color palette
-import '@jmruthers/pace-core/styles/core.css';
+import '@jmruthers/pace-core/styles/tokens';
 
 function App() {
   return (
@@ -340,10 +337,7 @@ function MyComponent() {
 **After (PACE Core Components)**
 ```tsx
 import { Button, Modal } from '@jmruthers/pace-core';
-
-// Import the core CSS file (in your app's entry point)
-import './app.css'; // Your app's color palette (must come first)
-import '@jmruthers/pace-core/styles/core.css';
+import '@jmruthers/pace-core/styles/tokens';
 
 function MyComponent() {
   return (
@@ -440,11 +434,7 @@ echo "Migration complete! Please review changes and test thoroughly."
 
 ### Issue 3: Styling Not Applied
 **Problem**: Components look unstyled
-**Solution**: Import the CSS files in your app's entry point:
-```tsx
-import './app.css'; // Your app's color palette (must come first)
-import '@jmruthers/pace-core/styles/core.css';
-```
+**Solution**: Import the design tokens: `import '@jmruthers/pace-core/styles/tokens'`
 
 ### Issue 4: TypeScript Errors
 **Problem**: TypeScript errors after migration

package/docs/migration/rbac-migration.md

@@ -20,16 +20,6 @@ import { useRBAC } from '@jmruthers/pace-core';
 import { useCan, usePermissions } from '@jmruthers/pace-core/rbac';
 ```
 
-### 2. New Security Features
-
-The new RBAC system includes enhanced security features that are automatically enabled:
-
-- **Input Validation**: All UUIDs, permissions, and scopes are validated
-- **Security Monitoring**: Comprehensive logging of security events
-- **Rate Limiting**: Built-in protection against abuse
-- **Input Sanitization**: Automatic sanitization of potentially dangerous inputs
-- **Audit Trail**: Complete audit logging for all permission operations
-
 ### 2. Hook API Changes
 
 **Old (Legacy)**:
@@ -223,9 +213,6 @@ export async function POST(request: Request) {
 - [ ] Verify performance improvements
 - [ ] Check error handling
 - [ ] Validate security enforcement
-- [ ] Test security context features
-- [ ] Verify input validation is working
-- [ ] Check audit logging functionality
 
 ## Common Migration Patterns
 
@@ -514,41 +501,6 @@ If you encounter issues during migration:
 - Performance validation
 - Security verification
 
-## Security Context Migration
-
-### Using Security Context (Optional but Recommended)
-
-The new RBAC system supports optional security context for enhanced security monitoring:
-
-```typescript
-// Basic usage (backward compatible)
-const hasPermission = await isPermitted({
-  userId: 'user-123',
-  scope: { organisationId: 'org-456' },
-  permission: 'read:users'
-});
-
-// Enhanced usage with security context
-const hasPermissionSecure = await isPermitted({
-  userId: 'user-123',
-  scope: { organisationId: 'org-456' },
-  permission: 'read:users'
-}, {
-  userId: 'user-123',
-  organisationId: 'org-456',
-  ipAddress: '192.168.1.1',
-  userAgent: 'Mozilla/5.0...',
-  timestamp: new Date()
-});
-```
-
-### Security Context Benefits
-
-- **Enhanced Audit Logging**: More detailed security event logging
-- **Rate Limiting**: Built-in protection against abuse
-- **Input Validation**: Automatic validation of all inputs
-- **Security Monitoring**: Comprehensive security event tracking
-
 ## Benefits of Migration
 
 ### Performance
@@ -565,7 +517,5 @@ const hasPermissionSecure = await isPermitted({
 - **Organisation context enforcement** prevents data leakage
 - **Row Level Security** integration
 - **Complete audit trail** for all permission checks
-- **Enhanced security monitoring** with input validation and rate limiting
-- **Automatic input sanitization** prevents injection attacks
 
 The new RBAC system provides a more robust, performant, and secure foundation for your application's permission management.

package/docs/migration-guide.md

@@ -1,15 +1,14 @@
-# Migration Guide: Simplified Single-File CSS Architecture
+# Migration Guide: Clean 3-File CSS Architecture
 
-This guide explains how to migrate your consuming app to use the new simplified single-file CSS architecture with Tailwind v4 and native utilities.
+This guide explains how to migrate your consuming app to use the new clean 3-file CSS architecture with Tailwind v4 and native utilities.
 
 ## Overview
 
 The new architecture uses:
-- **1 CSS file**: core.css from pace-core (includes everything)
-- **Built-in palettes**: Complete color palettes are included in core.css
+- **3 CSS files**: base.css, theme.css, dark.css from pace-core
+- **App-owned palettes**: Your app defines main/sec/acc colors in app.css
 - **Native utilities**: Use standard Tailwind classes (bg-main-600, text-sec-700)
 - **No CVA**: Components use native Tailwind utilities, not class-variance-authority
-- **Automatic scanning**: Uses Tailwind v4's built-in file scanning through build tool configuration
 
 This provides maximum flexibility while maintaining consistency across all consuming applications.
 
@@ -17,30 +16,71 @@ This provides maximum flexibility while maintaining consistency across all consu
 
 ### 1. Update Your Imports
 
-Replace old style imports with the new single-file system:
+Replace old style imports with the new 3-file system:
 
 ```tsx
 // OLD - Remove these imports
 // import '@jmruthers/pace-core/styles';
 // import '@jmruthers/pace-core/styles/tokens';
 // import '@jmruthers/pace-core/styles/components';
-// import '@jmruthers/pace-core/styles/base.css';
-// import '@jmruthers/pace-core/styles/theme.css';
-// import './app.css'; // No longer needed
 
-// NEW - Import the single CSS file (includes everything)
-import '@jmruthers/pace-core/styles/core.css';
+// NEW - Import the 3 CSS files
+import '@jmruthers/pace-core/styles/base.css';
+import '@jmruthers/pace-core/styles/theme.css';
+import '@jmruthers/pace-core/styles/dark.css';
+import './app.css'; // Your app's color palette
 ```
 
-### 2. Remove Your App's Color Palette
-
-**No longer needed!** The core.css file includes complete color palettes:
-
-- **Main palette**: Silver tones (50-950 shades)
-- **Secondary palette**: Violet tones (50-950 shades)  
-- **Accent palette**: Blood orange tones (50-950 shades)
-
-All utilities like `bg-main-600`, `text-sec-700`, `border-acc-500` work out of the box.
+### 2. Create Your App's Color Palette
+
+Create `app.css` with your brand colors:
+
+```css
+/* app.css - Your app's specific palette */
+@theme static {
+  /* MAIN palette - your primary brand color */
+  --color-main-raw: oklch(0.7 0.057 252.02); /* Update to your brand color */
+  --color-main-50: oklch(0.98 0.001 252.02);
+  --color-main-100: oklch(0.96 0.005 252.02);
+  --color-main-200: oklch(0.927 0.012 252.02);
+  --color-main-300: oklch(0.881 0.021 252.02);
+  --color-main-400: oklch(0.822 0.032 252.02);
+  --color-main-500: oklch(0.75 0.047 252.02);
+  --color-main-600: oklch(0.7 0.057 252.02);
+  --color-main-700: oklch(0.567 0.044 252.02);
+  --color-main-800: oklch(0.456 0.034 252.02);
+  --color-main-900: oklch(0.332 0.024 252.02);
+  --color-main-950: oklch(0.195 0.014 252.02);
+
+  /* SEC palette - your secondary brand color */
+  --color-sec-raw: oklch(0.58 0.23 280.75); /* Update to your secondary color */
+  --color-sec-50: oklch(0.98 0.003 280.75);
+  --color-sec-100: oklch(0.96 0.014 280.75);
+  --color-sec-200: oklch(0.927 0.033 280.75);
+  --color-sec-300: oklch(0.881 0.059 280.75);
+  --color-sec-400: oklch(0.822 0.093 280.75);
+  --color-sec-500: oklch(0.75 0.133 280.75);
+  --color-sec-600: oklch(0.665 0.182 280.75);
+  --color-sec-700: oklch(0.58 0.23 280.75);
+  --color-sec-800: oklch(0.456 0.158 280.75);
+  --color-sec-900: oklch(0.332 0.099 280.75);
+  --color-sec-950: oklch(0.195 0.047 280.75);
+
+  /* ACC palette - your accent brand color */
+  --color-acc-raw: oklch(0.64 0.21 37.76); /* Update to your accent color */
+  --color-acc-50: oklch(0.98 0.003 37.76);
+  --color-acc-100: oklch(0.96 0.015 37.76);
+  --color-acc-200: oklch(0.927 0.035 37.76);
+  --color-acc-300: oklch(0.881 0.063 37.76);
+  --color-acc-400: oklch(0.822 0.099 37.76);
+  --color-acc-500: oklch(0.75 0.143 37.76);
+  --color-acc-600: oklch(0.64 0.21 37.76);
+  --color-acc-700: oklch(0.567 0.177 37.76);
+  --color-acc-800: oklch(0.456 0.13 37.76);
+  --color-acc-900: oklch(0.332 0.085 37.76);
+  --color-acc-950: oklch(0.195 0.044 37.76);
+}
+```
 
 ### 3. Update Your Component Classes
 
@@ -48,8 +88,8 @@ Replace old app-* classes with new native utilities:
 
 ```tsx
 // OLD - Remove these classes
-// <div className="bg-main-500 text-main-50">
-//   <Button className="bg-sec-600 hover:bg-sec-700">
+// <div className="bg-app-main-500 text-app-main-50">
+//   <Button className="bg-app-sec-600 hover:bg-app-sec-700">
 
 // NEW - Use native utilities
 <div className="bg-main-500 text-main-50">
@@ -59,48 +99,65 @@ Replace old app-* classes with new native utilities:
 </div>
 ```
 
-### 4. Configure Tailwind v4
+### 4. Update Dynamic Theming
 
-Update your build configuration:
+Replace old theming with new runtime API:
 
 ```tsx
-// vite.config.ts
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
-import tailwindcss from '@tailwindcss/vite'
+// OLD - Remove these imports
+// import { EventColorManager } from '@jmruthers/pace-core';
 
-export default defineConfig({
-  plugins: [react(), tailwindcss()],
-})
+// NEW - Use runtime theming
+import { applyPalette, clearPalette } from '@jmruthers/pace-core/theming/runtime';
+
+// Apply organisation colors
+applyPalette({
+  main: orgData.colors.main,
+  sec: orgData.colors.sec,
+  acc: orgData.colors.acc
+});
+
+// Clear dynamic theming
+clearPalette();
+```
+
+### 5. Remove Old Dependencies
+
+Remove any old theming dependencies:
+
+```bash
+# Remove old theming packages if you have them
+npm uninstall class-variance-authority
 ```
 
-### 5. Test Your Migration
+### 6. Test Your Migration
 
-1. **Verify imports**: Ensure the core CSS file is imported
-2. **Check colors**: Verify the built-in color palettes work correctly
-3. **Test components**: Ensure all components render correctly
-4. **Check scanning**: Verify Tailwind automatically detects utility classes
+1. **Verify imports**: Ensure all 3 CSS files are imported
+2. **Check colors**: Verify your brand colors appear correctly
+3. **Test dark mode**: Toggle dark mode and verify shade reversal
+4. **Test dynamic theming**: Apply organisation colors and verify they work
+5. **Check components**: Ensure all components render correctly
 
 ## What Changed
 
 ### Before (Old System)
 - Complex CSS structure with multiple files
-- App-specific color palette files
-- Manual Tailwind configuration
+- App-specific classes (`bg-app-main-500`)
+- CVA-based component styling
 - Complex theming system
 
 ### After (New System)
-- Clean single-file CSS structure
-- Built-in color palettes
-- Automatic file scanning with @source directives
-- Native Tailwind utilities
+- Clean 3-file CSS structure
+- Native Tailwind utilities (`bg-main-500`)
+- Direct Tailwind classes in components
+- Simple runtime theming API
 
 ## Benefits
 
-1. **Simpler**: Only 1 CSS file to import
+1. **Simpler**: Only 3 CSS files to import
 2. **Faster**: Native Tailwind utilities are optimized
-3. **Cleaner**: No additional configuration needed
-4. **Automatic**: Tailwind scans all source files through build tool configuration
+3. **Cleaner**: No CVA dependency
+4. **More flexible**: Apps own their color palettes
 5. **Future-proof**: Easy to maintain and extend
 
 ## Support
@@ -145,7 +202,7 @@ export default defineConfig({
 
 ## Color Customization
 
-To customize your app's colors, simply update the `--color-main-*`, `--color-sec-*`, and `--color-acc-*` variables in your `src/app.css` file. The semantic color mappings will automatically use your new colors throughout the application.
+To customize your app's colors, simply update the `--color-app-main-*`, `--color-app-sec-*`, and `--color-app-acc-*` variables in your `src/app.css` file. The semantic color mappings will automatically use your new colors throughout the application.
 
 ## Troubleshooting
 
@@ -155,11 +212,7 @@ To customize your app's colors, simply update the `--color-main-*`, `--color-sec
 - Verify that the semantic mappings in `@theme inline` are referencing your color variables
 
 ### Styles Not Loading
-- Make sure you're importing the core CSS file in your app's entry point:
-  ```tsx
-  import './app.css'; // Your app's color palette (must come first)
-  import '@jmruthers/pace-core/styles/core.css';
-  ```
+- Make sure you're importing `@jmruthers/pace-core/styles` in your CSS file
 - Check that Tailwind CSS v4 is properly configured
 - Ensure your Vite configuration includes the `@tailwindcss/vite` plugin
 

package/docs/performance/README.md

@@ -262,7 +262,10 @@ function App() {
 function App() {
   return (
     <UserProvider>
-      <UserProfile />
+      <ThemeProvider>
+        <UserProfile />
+        <ThemeToggle />
+      </ThemeProvider>
     </UserProvider>
   );
 }

package/docs/quick-reference.md

@@ -33,48 +33,28 @@ npm install @jmruthers/pace-core
 ### Basic App Setup
 ```tsx
 import React from 'react';
-import { UnifiedAuthProvider, PaceAppLayout } from '@jmruthers/pace-core';
-import { BrowserRouter as Router, Routes, Route } from 'react-router-dom';
-
-// Import the core CSS file - app.css must come first for proper @theme processing
-import './app.css'; // Your app's color palette
-import '@jmruthers/pace-core/styles/core.css';
+import { UnifiedAuthProvider } from '@jmruthers/pace-core';
+import '@jmruthers/pace-core/styles/tokens';
 
 function App() {
   return (
-    <UnifiedAuthProvider supabaseClient={supabase} appName="My App">
-      <Router>
-        <Routes>
-          <Route path="/" element={
-            <PaceAppLayout appName="My Application">
-              <div className="container mx-auto px-4 py-6">
-                <h1>Welcome to My App</h1>
-                <p>Your content goes here</p>
-              </div>
-            </PaceAppLayout>
-          } />
-        </Routes>
-      </Router>
+    <UnifiedAuthProvider>
+      <YourApp />
     </UnifiedAuthProvider>
   );
 }
 ```
 
 ### Tailwind Configuration
-```ts
-// vite.config.ts
-import tailwindcss from '@tailwindcss/vite'
-export default defineConfig({
-  plugins: [
-    react(),
-    tailwindcss({
-      content: [
-        './src/**/*.{js,ts,jsx,tsx}',
-        './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}'
-      ]
-    })
+```js
+// tailwind.config.js
+module.exports = {
+  content: [
+    './src/**/*.{js,ts,jsx,tsx}',
+    './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}',
   ],
-})
+  // ... rest of config
+};
 ```
 
 ## 🔐 Authentication
@@ -359,18 +339,12 @@ import tailwindcss from '@tailwindcss/vite';
 
 export default defineConfig({
   plugins: [
-    tailwindcss({
-      // CRITICAL: Include pace-core components for scanning
-      content: [
-        './src/**/*.{js,ts,jsx,tsx}',
-        './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}'
-      ]
-    })
+    tailwindcss() // ✅ Simple - theme is included in CSS
   ],
 });
 
-// main.tsx
-import '@jmruthers/pace-core/styles/core.css';
+// index.css
+@import '@jmruthers/pace-core/styles/tailwind-v4-theme';
 ```
 
 **What's included automatically**:
@@ -390,16 +364,13 @@ module.exports = {
   content: ["./src/**/*.{js,jsx,ts,tsx}"],
 };
 
-// index.css or main.tsx
-import './app.css'; // Your app's color palette (must come first)
-import '@jmruthers/pace-core/styles/core.css';
+// index.css
+@import '@jmruthers/pace-core/styles/tokens';
 ```
 
 ### Using Design Tokens
 ```tsx
-// Import the core CSS file
-import './app.css'; // Your app's color palette (must come first)
-import '@jmruthers/pace-core/styles/core.css';
+import '@jmruthers/pace-core/styles/tokens';
 
 // Use in your CSS
 .my-component {
@@ -411,11 +382,22 @@ import '@jmruthers/pace-core/styles/core.css';
 
 ### Custom Themes
 ```tsx
-// Define your custom colors in app.css
-// @theme static {
-//   --color-primary: #your-primary-color;
-//   --color-secondary: #your-secondary-color;
-// }
+import { ThemeProvider } from '@jmruthers/pace-core';
+
+function App() {
+  return (
+    <ThemeProvider
+      theme={{
+        colors: {
+          primary: '#your-primary-color',
+          secondary: '#your-secondary-color',
+        },
+      }}
+    >
+      <YourApp />
+    </ThemeProvider>
+  );
+}
 ```
 
 ## 🔧 Utilities
@@ -424,7 +406,8 @@ import '@jmruthers/pace-core/styles/core.css';
 ```tsx
 import { 
   useDebounce, 
-  useToast
+  useToast, 
+  useTheme 
 } from '@jmruthers/pace-core';
 
 function SearchComponent() {