@jmruthers/pace-core 0.5.188 → 0.5.190

package/docs/api-reference/components.md

@@ -889,12 +889,12 @@ import {
 
 ## Alert
 
-A flexible and accessible alert component for displaying important messages.
+A flexible and accessible alert component for displaying important messages. Uses semantic HTML (`<aside>`) for better accessibility and semantic meaning.
 
 ### Props
 
 ```typescript
-interface AlertProps extends React.HTMLAttributes<HTMLDivElement> {
+interface AlertProps extends React.HTMLAttributes<HTMLElement> {
   variant?: 'default' | 'destructive' | 'inline';
   className?: string;
 }
@@ -903,7 +903,7 @@ interface AlertTitleProps extends React.HTMLAttributes<HTMLHeadingElement> {
   className?: string;
 }
 
-interface AlertDescriptionProps extends React.HTMLAttributes<HTMLDivElement> {
+interface AlertDescriptionProps extends React.HTMLAttributes<HTMLParagraphElement> {
   className?: string;
 }
 ```
@@ -913,7 +913,7 @@ interface AlertDescriptionProps extends React.HTMLAttributes<HTMLDivElement> {
 ```tsx
 import { Alert, AlertTitle, AlertDescription } from '@jmruthers/pace-core';
 
-// Basic alert
+// Basic alert (renders as <aside> element)
 <Alert>
   <AlertTitle>Success</AlertTitle>
   <AlertDescription>Your changes have been saved.</AlertDescription>
@@ -934,9 +934,17 @@ import { Alert, AlertTitle, AlertDescription } from '@jmruthers/pace-core';
 
 ### Variants
 
-- **default**: Standard alert with background and border
-- **destructive**: Red alert for errors and warnings
-- **inline**: Lightweight text formatting without background
+- **default**: Standard alert with background and border (renders as `<aside>`)
+- **destructive**: Red alert for errors and warnings (renders as `<aside>`)
+- **inline**: Lightweight text formatting without background (renders as fragment)
+
+### Semantic HTML
+
+The Alert component uses semantic HTML for better accessibility:
+- **Default and destructive variants**: Render as `<aside>` elements with `role="alert"`
+- **Inline variant**: Renders as a React Fragment (no wrapper element)
+- **AlertTitle**: Renders as `<h5>` (default/destructive) or `<strong>` (inline)
+- **AlertDescription**: Renders as `<p>` (default/destructive) or `<span>` (inline)
 
 ## Card
 
@@ -1997,49 +2005,84 @@ For more information about testing components, see the [Testing Guide](../testin
 
 ## Avatar
 
-Display user profile pictures with fallback initials or icons.
+Display user profile pictures with fallback initials or icons. Supports three approaches for image display: direct URLs, file reference props, or file ID.
 
 ### Props
 
 ```typescript
 interface AvatarProps extends React.HTMLAttributes<HTMLDivElement> {
-  className?: string;
-}
-
-interface AvatarImageProps extends React.ImgHTMLAttributes<HTMLImageElement> {
+  // File reference approach (uses FileDisplay for Supabase storage)
+  table_name?: string;
+  record_id?: string;
+  organisation_id?: string;
+  category?: FileCategory;
+  
+  // OR file ID approach (uses file reference lookup)
+  fileId?: string;
+  
+  // OR direct URL approach (simple <img> tag for public images)
   src?: string;
   alt?: string;
+  
+  // Fallback (always required)
+  fallback: string;
+  
+  // Styling
   className?: string;
-}
-
-interface AvatarFallbackProps extends React.HTMLAttributes<HTMLDivElement> {
-  className?: string;
+  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
 }
 ```
 
 ### Usage
 
 ```tsx
-import { Avatar, AvatarImage, AvatarFallback } from '@jmruthers/pace-core';
+import { Avatar } from '@jmruthers/pace-core';
+import { FileCategory } from '@jmruthers/pace-core/types';
+
+// Avatar with direct URL
+<Avatar 
+  src="/user.jpg" 
+  alt="User" 
+  fallback="JD"
+/>
 
-// User avatar
-<Avatar>
-  <AvatarImage src="/user.jpg" alt="User" />
-  <AvatarFallback>JD</AvatarFallback>
-</Avatar>
+// Avatar with file reference props (Supabase storage)
+<Avatar
+  table_name="user_profiles"
+  record_id={userId}
+  organisation_id={orgId}
+  category={FileCategory.PROFILE_PHOTOS}
+  fallback="JD"
+/>
 
-// Avatar without image
-<Avatar>
-  <AvatarFallback>AB</AvatarFallback>
-</Avatar>
+// Avatar with file ID
+<Avatar
+  fileId={fileReferenceId}
+  organisation_id={orgId}
+  fallback="JD"
+/>
+
+// Avatar with fallback only
+<Avatar fallback="AB" />
+
+// Avatar with custom size
+<Avatar 
+  src="/user.jpg" 
+  alt="User" 
+  fallback="JD"
+  size="lg"
+  className="custom-class"
+/>
 ```
 
 ### Features
 
-- Automatic fallback to initials or icon
-- Responsive sizing
+- Three image source approaches: direct URL, file reference props, or file ID
+- Automatic fallback to initials when image fails or not provided
+- Responsive sizing with size prop or custom className
 - Accessible ARIA attributes
-- Integration with user profiles
+- Integration with Supabase storage via FileDisplay
+- Circular avatar display with customizable styling
 
 ---
 

package/docs/api-reference/providers.md

@@ -91,8 +91,8 @@ The `UnifiedAuthProvider` includes built-in inactivity tracking that automatical
 
 #### Features
 
-- **Automatic logout** after 30 minutes of inactivity (configurable)
-- **Warning modal** appears 60 seconds before logout (configurable)
+- **Automatic logout** after configured period of inactivity (must be configured)
+- **Warning modal** appears before logout (must be configured)
 - **Cross-tab synchronization** - activity in any tab resets the timer
 - **Persistence** - survives page reloads and browser restarts
 - **Production-safe** - cannot be disabled in production builds

package/docs/api-reference/rpc-functions.md

@@ -146,6 +146,7 @@ Documented in [RBAC API Reference](../rbac/api-reference.md):
 **Data Access (RBAC-protected):**
 - `data_user_organisations_get` - Get all organisations for a user
 - `data_user_organisation_roles_get` - Get user roles in organisations
+- `get_organisation_members` - (exception to naming standard) Returns distinct active organisation role assignments for dashboard statistics. Enforces `check_user_organisation_access` so only super admins or organisation members can call it.
 - `data_user_events_get` - Get events accessible to a user
 - `data_cake_meals_get` - Get cake meals for an event (application-specific, RBAC-protected)
 

package/docs/best-practices/README.md

@@ -242,7 +242,7 @@ For detailed testing guidelines, see [Testing Best Practices](./testing.md).
 // ✅ Good - Environment validation
 const config = {
   supabaseUrl: process.env.VITE_SUPABASE_URL,
-  supabaseKey: process.env.VITE_SUPABASE_ANON_KEY,
+  supabaseKey: process.env.VITE_SUPABASE_PUBLISHABLE_KEY,
   appName: process.env.VITE_APP_NAME,
 };
 

package/docs/best-practices/deployment.md

@@ -25,21 +25,21 @@ Deployment in `@jmruthers/pace-core` covers multiple environments:
 // .env.local (development)
 VITE_SUPABASE_URL=http://localhost:54321
 // Accepts both legacy anon keys and modern publishable keys (sb_publishable_...)
-VITE_SUPABASE_ANON_KEY=your-local-publishable-key-or-anon-key
+VITE_SUPABASE_PUBLISHABLE_KEY=your-local-publishable-key
 VITE_APP_ENV=development
 VITE_DEBUG=true
 
 // .env.staging
 VITE_SUPABASE_URL=https://your-project.supabase.co
 // Accepts both legacy anon keys and modern publishable keys (sb_publishable_...)
-VITE_SUPABASE_ANON_KEY=your-staging-publishable-key-or-anon-key
+VITE_SUPABASE_PUBLISHABLE_KEY=your-staging-publishable-key
 VITE_APP_ENV=staging
 VITE_DEBUG=false
 
 // .env.production
 VITE_SUPABASE_URL=https://your-project.supabase.co
 // Accepts both legacy anon keys and modern publishable keys (sb_publishable_...)
-VITE_SUPABASE_ANON_KEY=your-production-publishable-key-or-anon-key
+VITE_SUPABASE_PUBLISHABLE_KEY=your-production-publishable-key
 VITE_APP_ENV=production
 VITE_DEBUG=false
 ```
@@ -274,7 +274,7 @@ jobs:
         run: npm run build
         env:
           VITE_SUPABASE_URL: ${{ secrets.SUPABASE_URL }}
-          VITE_SUPABASE_ANON_KEY: ${{ secrets.SUPABASE_ANON_KEY }}
+          VITE_SUPABASE_PUBLISHABLE_KEY: ${{ secrets.SUPABASE_PUBLISHABLE_KEY }}
           VITE_APP_ENV: production
       
       - name: Upload build artifacts
@@ -354,7 +354,7 @@ jobs:
         run: npm run build:staging
         env:
           VITE_SUPABASE_URL: ${{ secrets.STAGING_SUPABASE_URL }}
-          VITE_SUPABASE_ANON_KEY: ${{ secrets.STAGING_SUPABASE_ANON_KEY }}
+          VITE_SUPABASE_PUBLISHABLE_KEY: ${{ secrets.STAGING_SUPABASE_PUBLISHABLE_KEY }}
           VITE_APP_ENV: staging
       
       - name: Deploy to Vercel (Staging)
@@ -441,7 +441,7 @@ jobs:
   ],
   "env": {
     "VITE_SUPABASE_URL": "@supabase-url",
-    "VITE_SUPABASE_ANON_KEY": "@supabase-anon-key"
+    "VITE_SUPABASE_PUBLISHABLE_KEY": "@supabase-publishable-key"
   }
 }
 ```
@@ -566,13 +566,13 @@ export const securityHeaders = {
 ```bash
 # .env.example (template for required variables)
 VITE_SUPABASE_URL=
-VITE_SUPABASE_ANON_KEY=
+VITE_SUPABASE_PUBLISHABLE_KEY=
 VITE_APP_ENV=development
 VITE_DEBUG=false
 
 # .env.production (actual production values - never commit)
 VITE_SUPABASE_URL=https://your-project.supabase.co
-VITE_SUPABASE_ANON_KEY=your-production-anon-key
+VITE_SUPABASE_PUBLISHABLE_KEY=your-production-publishable-key
 VITE_APP_ENV=production
 VITE_DEBUG=false
 ```

package/docs/getting-started/examples/README.md

@@ -53,7 +53,7 @@ npm install @supabase/supabase-js react-router-dom
 Create `.env.local`:
 ```env
 VITE_SUPABASE_URL=your_supabase_url
-VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
+VITE_SUPABASE_PUBLISHABLE_KEY=your_supabase_publishable_key
 VITE_APP_NAME=Basic Auth App
 ```
 
@@ -103,7 +103,7 @@ src/
 import { createClient } from '@supabase/supabase-js';
 
 const supabaseUrl = import.meta.env.VITE_SUPABASE_URL;
-const supabaseKey = import.meta.env.VITE_SUPABASE_ANON_KEY;
+const supabaseKey = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY;
 
 export const supabase = createClient(supabaseUrl, supabaseKey);
 ```

package/docs/getting-started/installation-guide.md

@@ -17,7 +17,7 @@ reviewedBy: documentation-standards-audit
 npm install @jmruthers/pace-core
 
 # 2. Install peer dependencies
-npm install react react-dom @tanstack/react-table @radix-ui/react-avatar @radix-ui/react-checkbox @radix-ui/react-dialog @radix-ui/react-label @radix-ui/react-progress @radix-ui/react-slot @radix-ui/react-switch @radix-ui/react-tabs @radix-ui/react-toast @radix-ui/react-tooltip lucide-react react-day-picker react-hook-form react-router-dom clsx tailwind-merge zod
+npm install react react-dom @tanstack/react-table @radix-ui/react-avatar @radix-ui/react-checkbox @radix-ui/react-dialog @radix-ui/react-label @radix-ui/react-slot @radix-ui/react-switch @radix-ui/react-tabs @radix-ui/react-toast @radix-ui/react-tooltip lucide-react react-day-picker react-hook-form react-router-dom clsx tailwind-merge zod
 
 # 3. Install Tailwind v4
 npm install -D @tailwindcss/vite tailwindcss@^4.0.0
@@ -36,7 +36,7 @@ npm install @jmruthers/pace-core
 
 **Required Peer Dependencies:**
 ```bash
-npm install react react-dom @tanstack/react-table @radix-ui/react-avatar @radix-ui/react-checkbox @radix-ui/react-dialog @radix-ui/react-label @radix-ui/react-progress @radix-ui/react-slot @radix-ui/react-switch @radix-ui/react-tabs @radix-ui/react-toast @radix-ui/react-tooltip lucide-react react-day-picker react-hook-form react-router-dom clsx tailwind-merge zod
+npm install react react-dom @tanstack/react-table @radix-ui/react-avatar @radix-ui/react-checkbox @radix-ui/react-dialog @radix-ui/react-label @radix-ui/react-slot @radix-ui/react-switch @radix-ui/react-tabs @radix-ui/react-toast @radix-ui/react-tooltip lucide-react react-day-picker react-hook-form react-router-dom clsx tailwind-merge zod
 ```
 
 **Note**: `@supabase/supabase-js` and `@tanstack/react-query` are included as dependencies and do not need to be installed separately.
@@ -291,7 +291,7 @@ Create `src/lib/supabase.ts`:
 import { createClient } from '@supabase/supabase-js'
 
 const supabaseUrl = process.env.VITE_SUPABASE_URL!
-const supabaseAnonKey = process.env.VITE_SUPABASE_ANON_KEY!
+const supabasePublishableKey = process.env.VITE_SUPABASE_PUBLISHABLE_KEY!
 
 export const supabase = createClient(supabaseUrl, supabaseAnonKey)
 ```
@@ -301,7 +301,7 @@ Set environment variables in `.env.local`:
 ```bash
 VITE_SUPABASE_URL=https://your-project.supabase.co
 # Accepts both legacy anon keys and modern publishable keys (sb_publishable_...)
-VITE_SUPABASE_ANON_KEY=your-publishable-key-or-anon-key-here
+VITE_SUPABASE_PUBLISHABLE_KEY=your-publishable-key-here
 ```
 
 Wrap your app with providers in the correct nesting order:

package/docs/getting-started/quick-start.md

@@ -35,7 +35,7 @@ npm install @jmruthers/pace-core \
   @supabase/supabase-js \
   @tanstack/react-query @tanstack/react-table \
   @radix-ui/react-avatar @radix-ui/react-checkbox @radix-ui/react-dialog \
-  @radix-ui/react-label @radix-ui/react-progress @radix-ui/react-slot \
+  @radix-ui/react-label @radix-ui/react-slot \
   @radix-ui/react-switch @radix-ui/react-tabs @radix-ui/react-toast @radix-ui/react-tooltip \
   clsx lucide-react react-day-picker react-hook-form react-router-dom tailwind-merge zod
 
@@ -104,7 +104,7 @@ Create `.env.local`:
 
 ```env
 VITE_SUPABASE_URL=your_supabase_project_url
-VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
+VITE_SUPABASE_PUBLISHABLE_KEY=your_supabase_publishable_key
 ```
 
 Create `src/lib/supabase.ts`:
@@ -113,7 +113,7 @@ Create `src/lib/supabase.ts`:
 import { createClient } from '@supabase/supabase-js';
 
 const supabaseUrl = import.meta.env.VITE_SUPABASE_URL!;
-const supabaseAnonKey = import.meta.env.VITE_SUPABASE_ANON_KEY!;
+const supabasePublishableKey = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY!;
 
 export const supabase = createClient(supabaseUrl, supabaseAnonKey);
 ```

package/docs/migration/MIGRATION_GUIDE.md

@@ -830,7 +830,7 @@ VITE_DEBUG_MODE=true
 
 # New environment variables
 VITE_SUPABASE_URL=https://your-project.supabase.co
-VITE_SUPABASE_ANON_KEY=your-anon-key
+VITE_SUPABASE_PUBLISHABLE_KEY=your-publishable-key
 VITE_APP_ENV=development
 VITE_DEBUG=false
 
@@ -847,7 +847,7 @@ cp .env .env.backup
 cat > .env << EOF
 # Supabase Configuration
 VITE_SUPABASE_URL=${VITE_SUPABASE_URL:-https://your-project.supabase.co}
-VITE_SUPABASE_ANON_KEY=${VITE_SUPABASE_ANON_KEY:-your-anon-key}
+VITE_SUPABASE_PUBLISHABLE_KEY=${VITE_SUPABASE_PUBLISHABLE_KEY:-your-publishable-key}
 
 # Application Configuration
 VITE_APP_ENV=${VITE_APP_ENV:-development}
@@ -1133,7 +1133,7 @@ export class MigrationValidation {
   static validateConfiguration(config: any) {
     const required = [
       'VITE_SUPABASE_URL',
-      'VITE_SUPABASE_ANON_KEY',
+      'VITE_SUPABASE_PUBLISHABLE_KEY',
     ];
     
     const warnings = [];

package/docs/rbac/compliance/compliance-guide.md

@@ -152,7 +152,7 @@ import { createClient } from '@supabase/supabase-js';
 
 const supabase = createClient(
   import.meta.env.VITE_SUPABASE_URL,
-  import.meta.env.VITE_SUPABASE_ANON_KEY
+  import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY
 );
 
 // ⚠️ REQUIRED: Call setupRBAC before rendering
@@ -266,7 +266,7 @@ import { createClient } from '@supabase/supabase-js';
 
 export const supabase = createClient(
   import.meta.env.VITE_SUPABASE_URL,
-  import.meta.env.VITE_SUPABASE_ANON_KEY
+  import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY
 );
 ```
 

package/docs/rbac/event-based-apps.md

@@ -89,7 +89,7 @@ Create `.env.local`:
 ```bash
 # .env.local
 VITE_SUPABASE_URL=https://your-project.supabase.co
-VITE_SUPABASE_ANON_KEY=your-anon-key-here
+VITE_SUPABASE_PUBLISHABLE_KEY=your-publishable-key-here
 VITE_APP_NAME=pace-trac
 ```
 
@@ -225,7 +225,7 @@ Create `src/lib/supabase.ts`:
 import { createClient } from '@supabase/supabase-js'
 
 const supabaseUrl = import.meta.env.VITE_SUPABASE_URL
-const supabaseAnonKey = import.meta.env.VITE_SUPABASE_ANON_KEY
+const supabasePublishableKey = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY
 
 if (!supabaseUrl || !supabaseAnonKey) {
   throw new Error('Missing Supabase environment variables')

package/docs/rbac/getting-started.md

@@ -99,7 +99,7 @@ import '@jmruthers/pace-core/src/styles/core.css';
 // Initialize Supabase
 const supabase = createClient(
   import.meta.env.VITE_SUPABASE_URL!,
-  import.meta.env.VITE_SUPABASE_ANON_KEY!
+  import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY!
 );
 
 // ⚠️ REQUIRED: Setup RBAC before rendering
@@ -258,7 +258,7 @@ import App from './App';
 // Initialize Supabase
 const supabase = createClient(
   import.meta.env.VITE_SUPABASE_URL!,
-  import.meta.env.VITE_SUPABASE_ANON_KEY!
+  import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY!
 );
 
 // ⚠️ REQUIRED: Setup RBAC before rendering

package/docs/rbac/quick-start.md

@@ -88,7 +88,7 @@ Create `.env.local`:
 # .env.local
 VITE_SUPABASE_URL=https://your-project.supabase.co
 # Accepts both legacy anon keys and modern publishable keys (sb_publishable_...)
-VITE_SUPABASE_ANON_KEY=your-publishable-key-or-anon-key-here
+VITE_SUPABASE_PUBLISHABLE_KEY=your-publishable-key-here
 VITE_APP_NAME=user-manager
 ```
 
@@ -213,7 +213,7 @@ Create `src/lib/supabase.ts`:
 import { createClient } from '@supabase/supabase-js'
 
 const supabaseUrl = import.meta.env.VITE_SUPABASE_URL
-const supabaseAnonKey = import.meta.env.VITE_SUPABASE_ANON_KEY
+const supabasePublishableKey = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY
 
 if (!supabaseUrl || !supabaseAnonKey) {
   throw new Error('Missing Supabase environment variables')

package/docs/security/README.md

@@ -139,10 +139,10 @@ function ProtectedComponent() {
 
 ### 3. Inactivity Auto-Logout
 
-PACE Core includes built-in inactivity tracking for enhanced security:
+PACE Core includes built-in inactivity tracking for enhanced security. **All inactivity timeout props are mandatory** - apps must explicitly configure them:
 
-- **Automatic logout** after 30 minutes of inactivity (configurable)
-- **Warning modal** appears 60 seconds before logout
+- **Automatic logout** after configured period of inactivity (must be configured)
+- **Warning modal** appears before logout (must be configured)
 - **Cross-tab synchronization** - activity in any tab resets the timer
 - **Persistence** - survives page reloads and browser restarts
 - **Production-safe** - cannot be disabled in production builds
@@ -597,7 +597,7 @@ Secure configuration using environment variables:
 ```bash
 # Authentication
 VITE_SUPABASE_URL=your_supabase_url
-VITE_SUPABASE_ANON_KEY=your_anon_key
+VITE_SUPABASE_PUBLISHABLE_KEY=your_publishable_key
 VITE_SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
 
 # Security