@jmruthers/pace-core 0.5.181 → 0.5.182

package/examples/{features/public-pages → PublicPages}/PublicPageApp.tsx

@@ -38,12 +38,12 @@ import {
   PublicPageLayout, 
   PublicPageHeader, 
   PublicPageFooter,
-  EventLogo,
+  FileDisplay,
+  FileCategory,
   usePublicEvent,
   usePublicRouteParams,
-  PublicLoadingSpinner,
-  PublicErrorBoundary
-} from '../../../src';
+  LoadingSpinner
+} from '@jmruthers/pace-core';
 
 /**
  * Complete public page application that works independently
@@ -87,9 +87,12 @@ function PublicRecipeGridReportPage() {
   // Step 3: Handle loading state
   if (isLoading) {
     return (
-      <PublicLoadingSpinner 
-        message="Loading recipe grid report..."
-      />
+      <div className="min-h-screen bg-background flex items-center justify-center">
+        <div className="max-w-md mx-auto text-center px-4">
+          <LoadingSpinner size="lg" className="mx-auto mb-4" />
+          <p className="text-sec-600">Loading recipe grid report...</p>
+        </div>
+      </div>
     );
   }
 
@@ -209,12 +212,23 @@ function PublicRecipeGridReportPage() {
           {/* Event Logo */}
           <div className="flex justify-center lg:justify-start">
             <div className="text-center">
-              <EventLogo
-                eventId={event.event_id}
-                eventName={event.event_name}
-                organisationId={event.organisation_id}
-                size="2xl"
+              <FileDisplay
+                table_name="event"
+                record_id={event.event_id}
+                organisation_id={event.organisation_id}
+                category={FileCategory.EVENT_LOGOS}
+                displayOnly={true}
+                showFallback={true}
+                fallbackSize="2xl"
                 className="rounded-lg shadow-lg"
+                generateFallbackText={() => {
+                  if (!event.event_name) return 'EV';
+                  return event.event_name
+                    .split(/[\s\-_]+/)
+                    .map(word => word.charAt(0).toUpperCase())
+                    .join('')
+                    .substring(0, 3);
+                }}
               />
               <p className="mt-4 text-sm text-sec-600">Event Logo</p>
             </div>
@@ -234,7 +248,16 @@ function PublicEventPage() {
   const { eventCode } = usePublicRouteParams({ fetchEventData: false });
   const { event, isLoading, error, refetch } = usePublicEvent(eventCode || '');
 
-  if (isLoading) return <PublicLoadingSpinner message="Loading event..." />;
+  if (isLoading) {
+    return (
+      <div className="min-h-screen bg-background flex items-center justify-center">
+        <div className="max-w-md mx-auto text-center px-4">
+          <LoadingSpinner size="lg" className="mx-auto mb-4" />
+          <p className="text-sec-600">Loading event...</p>
+        </div>
+      </div>
+    );
+  }
   if (error || !event) return <div>Event not found</div>;
 
   return (
@@ -248,12 +271,23 @@ function PublicEventPage() {
       
       <main className="max-w-4xl mx-auto px-4 py-6">
         <div className="text-center mb-6">
-          <EventLogo
-            eventId={event.event_id}
-            eventName={event.event_name}
-            organisationId={event.organisation_id}
-            size="xl"
+          <FileDisplay
+            table_name="event"
+            record_id={event.event_id}
+            organisation_id={event.organisation_id}
+            category={FileCategory.EVENT_LOGOS}
+            displayOnly={true}
+            showFallback={true}
+            fallbackSize="xl"
             className="mx-auto mb-4"
+            generateFallbackText={() => {
+              if (!event.event_name) return 'EV';
+              return event.event_name
+                .split(/[\s\-_]+/)
+                .map(word => word.charAt(0).toUpperCase())
+                .join('')
+                .substring(0, 3);
+            }}
           />
           <h1 className="text-2xl font-bold text-sec-900">{event.event_name}</h1>
           {event.event_date && (

package/examples/{features/public-pages → PublicPages}/PublicPageUsageExample.tsx

@@ -29,12 +29,12 @@ import {
   PublicPageLayout, 
   PublicPageHeader, 
   PublicPageFooter,
-  EventLogo,
+  FileDisplay,
+  FileCategory,
   usePublicEvent,
   usePublicRouteParams,
-  PublicLoadingSpinner,
-  PublicErrorBoundary
-} from '../../../src';
+  LoadingSpinner
+} from '@jmruthers/pace-core';
 
 /**
  * Correct usage pattern for public pages
@@ -55,9 +55,12 @@ export function PublicPageUsageExample() {
   // Step 3: Handle loading state
   if (isLoading) {
     return (
-      <PublicLoadingSpinner 
-        message="Loading event details..."
-      />
+      <div className="min-h-screen bg-background flex items-center justify-center">
+        <div className="max-w-md mx-auto text-center px-4">
+          <LoadingSpinner size="lg" className="mx-auto mb-4" />
+          <p className="text-sec-600">Loading event details...</p>
+        </div>
+      </div>
     );
   }
 
@@ -113,9 +116,9 @@ export function PublicPageUsageExample() {
   }
 
   // Step 6: Render the public page with event data
+  // Note: PublicPageLayout now includes ErrorBoundary internally
   return (
-    <PublicErrorBoundary>
-      <PublicPageLayout eventCode={eventCode || ''} event={event}>
+    <PublicPageLayout eventCode={eventCode || ''} event={event}>
         <PublicPageHeader 
           event={event}
           eventCode={eventCode || ''}
@@ -170,12 +173,23 @@ export function PublicPageUsageExample() {
             {/* Event Logo */}
             <div className="flex justify-center lg:justify-start">
               <div className="text-center">
-                <EventLogo
-                  eventId={event.event_id}
-                  eventName={event.event_name}
-                  organisationId={event.organisation_id}
-                  size="2xl"
+                <FileDisplay
+                  table_name="event"
+                  record_id={event.event_id}
+                  organisation_id={event.organisation_id}
+                  category={FileCategory.EVENT_LOGOS}
+                  displayOnly={true}
+                  showFallback={true}
+                  fallbackSize="2xl"
                   className="rounded-lg shadow-lg"
+                  generateFallbackText={() => {
+                    if (!event.event_name) return 'EV';
+                    return event.event_name
+                      .split(/[\s\-_]+/)
+                      .map(word => word.charAt(0).toUpperCase())
+                      .join('')
+                      .substring(0, 3);
+                  }}
                 />
                 <p className="mt-4 text-sm text-sec-600">Event Logo</p>
               </div>
@@ -209,7 +223,6 @@ export function PublicPageUsageExample() {
 
         <PublicPageFooter event={event} />
       </PublicPageLayout>
-    </PublicErrorBoundary>
   );
 }
 

package/examples/README.md

@@ -1,53 +1,101 @@
 # PACE Core Examples
 
-This directory contains runnable examples demonstrating how to use various features of the pace-core library.
+This directory contains **runnable TypeScript/React component examples** demonstrating how to use various features of the pace-core library.
 
-## Structure
+> **Note:** For complete application tutorials and starter projects, see the [Getting Started Examples](../../docs/getting-started/examples/) documentation.
 
-Examples are organized into two main categories:
+## Structure
 
-### Features (`features/`)
-Cross-component workflow examples that demonstrate how to use multiple components together:
-- **`features/rbac/`** - RBAC and permission system examples
-- **`features/public-pages/`** - Public page workflow examples
-- **`features/authentication/`** - Authentication examples (coming soon)
+Examples are organized in a flat structure by component or feature:
 
-### Components (`components/`)
-Component-specific examples that demonstrate individual component features:
-- **`components/DataTable/`** - DataTable component examples
-- **`components/Dialog/`** - Dialog component examples
+```
+examples/
+├── README.md                    # This file
+├── index.ts                     # Central export point
+│
+├── DataTable/                   # DataTable component examples
+│   ├── index.ts
+│   ├── HierarchicalExample.tsx
+│   ├── HierarchicalActionsExample.tsx
+│   ├── InitialPageSizeExample.tsx
+│   ├── PerformanceExample.tsx
+│   └── GroupingAggregationExample.tsx
+│
+├── Dialog/                      # Dialog component examples
+│   ├── index.ts
+│   ├── HtmlDialogExample.tsx
+│   ├── ScrollableDialogExample.tsx
+│   └── SmartDialogExample.tsx
+│
+├── rbac/                        # RBAC and permission examples
+│   ├── index.ts
+│   ├── EventBasedApp.tsx
+│   ├── CompleteRBACExample.tsx
+│   └── PermissionExample.tsx
+│
+└── PublicPages/                # Public page workflow examples
+    ├── index.ts
+    ├── PublicPageUsageExample.tsx
+    ├── PublicEventPage.tsx
+    ├── PublicPageApp.tsx
+    └── CorrectPublicPageImplementation.tsx
+```
 
 ## Usage
 
-### Import Feature Examples
+### Import from Main Export (Recommended)
 
 ```tsx
-// Import from main examples export (recommended)
-import { PublicPageUsageExample, EventBasedApp } from '@jmruthers/pace-core/examples';
+// Import all examples from main export
+import { 
+  PublicPageUsageExample, 
+  EventBasedApp,
+  HierarchicalExample,
+  HtmlDialogExample
+} from '@jmruthers/pace-core/examples';
+```
 
-// Or import from specific feature category
-import { PublicPageUsageExample } from '@jmruthers/pace-core/examples/features/public-pages';
-import { EventBasedApp } from '@jmruthers/pace-core/examples/features/rbac';
+### Import from Specific Directories
 
-// Or import all features
-import * as Features from '@jmruthers/pace-core/examples/features';
+```tsx
+// Import from specific directories
+import { HierarchicalExample } from '@jmruthers/pace-core/examples/DataTable';
+import { HtmlDialogExample } from '@jmruthers/pace-core/examples/Dialog';
+import { EventBasedApp } from '@jmruthers/pace-core/examples/rbac';
+import { PublicPageUsageExample } from '@jmruthers/pace-core/examples/PublicPages';
 ```
 
-### Import Component Examples
+## Package Exports
 
-```tsx
-// Import from specific component
-import { HierarchicalExample } from '@jmruthers/pace-core/examples/components/DataTable';
-import { HtmlDialogExample } from '@jmruthers/pace-core/examples/components/Dialog';
+The following export paths are available:
 
-// Or import all component examples
-import * as Components from '@jmruthers/pace-core/examples/components';
-```
+- `@jmruthers/pace-core/examples` - Main export (all examples)
+- `@jmruthers/pace-core/examples/DataTable` - DataTable examples
+- `@jmruthers/pace-core/examples/Dialog` - Dialog examples
+- `@jmruthers/pace-core/examples/rbac` - RBAC examples
+- `@jmruthers/pace-core/examples/PublicPages` - Public pages examples
+
+## Adding New Examples
+
+1. Create a new directory under `examples/[ExampleName]/`
+2. Add your example files
+3. Create an `index.ts` file exporting your examples
+4. Update `examples/index.ts` to export from your new directory
+5. Update `package.json` exports if you want a dedicated import path
+
+## Documentation vs Runnable Examples
 
-## Documentation
+**This directory (`/examples/`)** contains:
+- ✅ Runnable TypeScript/React components you can import and use
+- ✅ Component-level examples (DataTable, Dialog, RBAC, PublicPages)
+- ✅ Importable code: `import { HierarchicalExample } from '@jmruthers/pace-core/examples'`
 
-For more detailed tutorials and guides, see the documentation:
-- [Getting Started Examples](../../docs/getting-started/examples/)
-- [RBAC Examples](../../docs/rbac/examples/)
-- [Implementation Guides](../../docs/implementation-guides/)
+**Documentation examples (`/docs/getting-started/examples/`)** contain:
+- 📚 Tutorial-style guides with embedded code snippets
+- 📚 Complete application examples (basic-auth-app, full-featured meal app)
+- 📚 Step-by-step setup instructions and explanations
 
+For more detailed tutorials and guides, see:
+- [Getting Started Examples](../../docs/getting-started/examples/) - Complete app tutorials
+- [RBAC Examples](../../docs/rbac/examples/) - RBAC implementation guides
+- [Implementation Guides](../../docs/implementation-guides/) - Advanced patterns

package/examples/index.ts

@@ -11,20 +11,22 @@
  *
  * @example
  * ```tsx
- * // Import feature examples
- * import { PublicPageUsageExample } from '@jmruthers/pace-core/examples';
- * import { EventBasedApp } from '@jmruthers/pace-core/examples';
+ * // Import all examples
+ * import { PublicPageUsageExample, EventBasedApp } from '@jmruthers/pace-core/examples';
+ * import { HierarchicalExample } from '@jmruthers/pace-core/examples';
+ * import { HtmlDialogExample } from '@jmruthers/pace-core/examples';
  * 
- * // Import component examples
- * import { HierarchicalExample } from '@jmruthers/pace-core/examples/components/DataTable';
- * import { HtmlDialogExample } from '@jmruthers/pace-core/examples/components/Dialog';
+ * // Or import from specific directories
+ * import { HierarchicalExample } from '@jmruthers/pace-core/examples/DataTable';
+ * import { HtmlDialogExample } from '@jmruthers/pace-core/examples/Dialog';
+ * import { EventBasedApp } from '@jmruthers/pace-core/examples/rbac';
+ * import { PublicPageUsageExample } from '@jmruthers/pace-core/examples/PublicPages';
  * ```
  */
 
-// Export all feature examples
-export * from './features/rbac';
-export * from './features/public-pages';
-
-// Export all component examples
-export * from './components';
+// Export all examples
+export * from './DataTable';
+export * from './Dialog';
+export * from './rbac';
+export * from './PublicPages';
 

package/examples/{RBAC → rbac}/CompleteRBACExample.tsx

@@ -30,7 +30,7 @@ import {
   EnhancedNavigationMenu,
   type NavigationItem,
   type RouteConfig
-} from '../../src/rbac/components';
+} from '@jmruthers/pace-core';
 
 // Example navigation items
 const navigationItems: NavigationItem[] = [

package/examples/{features/rbac → rbac}/EventBasedApp.tsx

@@ -12,10 +12,10 @@ import {
   PermissionEnforcer, 
   PagePermissionGuard, 
   NavigationGuard,
-  useCan 
-} from '../../src/rbac';
-import { useUnifiedAuth } from '../../src/providers';
-import type { Permission } from '../../src/rbac/types';
+  useCan,
+  useUnifiedAuth,
+  type Permission
+} from '@jmruthers/pace-core';
 
 // Example navigation items for an event-based app
 const navigationItems = [

package/examples/{features/rbac → rbac}/PermissionExample.tsx

@@ -9,9 +9,11 @@
  */
 
 import React from 'react';
-import { useUnifiedAuth } from '../../src/providers';
-import { useAppConfig } from '../../src/hooks';
-import { AccessLevel } from '../../src/types';
+import { 
+  useUnifiedAuth, 
+  useAppConfig,
+  type AccessLevel 
+} from '@jmruthers/pace-core';
 
 export function PermissionExample() {
   const { 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmruthers/pace-core",
-  "version": "0.5.181",
+  "version": "0.5.182",
   "description": "Clean, modern React component library with Tailwind v4 styling and native utilities",
   "private": false,
   "publishConfig": {
@@ -97,35 +97,25 @@
       "import": "./dist/examples/index.js",
       "default": "./dist/examples/index.js"
     },
-    "./examples/features": {
-      "types": "./dist/examples/features/index.d.ts",
-      "import": "./dist/examples/features/index.js",
-      "default": "./dist/examples/features/index.js"
+    "./examples/DataTable": {
+      "types": "./dist/examples/DataTable/index.d.ts",
+      "import": "./dist/examples/DataTable/index.js",
+      "default": "./dist/examples/DataTable/index.js"
     },
-    "./examples/features/rbac": {
-      "types": "./dist/examples/features/rbac/index.d.ts",
-      "import": "./dist/examples/features/rbac/index.js",
-      "default": "./dist/examples/features/rbac/index.js"
+    "./examples/Dialog": {
+      "types": "./dist/examples/Dialog/index.d.ts",
+      "import": "./dist/examples/Dialog/index.js",
+      "default": "./dist/examples/Dialog/index.js"
     },
-    "./examples/features/public-pages": {
-      "types": "./dist/examples/features/public-pages/index.d.ts",
-      "import": "./dist/examples/features/public-pages/index.js",
-      "default": "./dist/examples/features/public-pages/index.js"
+    "./examples/rbac": {
+      "types": "./dist/examples/rbac/index.d.ts",
+      "import": "./dist/examples/rbac/index.js",
+      "default": "./dist/examples/rbac/index.js"
     },
-    "./examples/components": {
-      "types": "./dist/examples/components/index.d.ts",
-      "import": "./dist/examples/components/index.js",
-      "default": "./dist/examples/components/index.js"
-    },
-    "./examples/components/DataTable": {
-      "types": "./dist/examples/components/DataTable/index.d.ts",
-      "import": "./dist/examples/components/DataTable/index.js",
-      "default": "./dist/examples/components/DataTable/index.js"
-    },
-    "./examples/components/Dialog": {
-      "types": "./dist/examples/components/Dialog/index.d.ts",
-      "import": "./dist/examples/components/Dialog/index.js",
-      "default": "./dist/examples/components/Dialog/index.js"
+    "./examples/PublicPages": {
+      "types": "./dist/examples/PublicPages/index.d.ts",
+      "import": "./dist/examples/PublicPages/index.js",
+      "default": "./dist/examples/PublicPages/index.js"
     },
     "./source/examples": {
       "import": "./examples/index.ts",
@@ -143,9 +133,13 @@
   "scripts": {
     "_comment_build": "Build package and documentation",
     "build": "tsup && node scripts/build-css.js",
+    "build:watch": "tsup --watch",
     "build:docs": "node scripts/build-docs-incremental.js",
     "build:docs:force": "node scripts/build-docs-incremental.js --force",
     "build:all": "npm run build && npm run build:docs",
+    "_comment_local_dev": "Local development utilities",
+    "link": "npm run build && npm link",
+    "unlink": "npm unlink",
     "validate:theme": "node scripts/validate-theme.js",
     "prepublishOnly": "npm run build",
     "clean": "rimraf dist",

package/src/__tests__/helpers/test-utils.tsx

@@ -9,6 +9,15 @@ import userEvent from '@testing-library/user-event';
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 import { vi } from 'vitest';
 
+// Try to import MemoryRouter, but handle cases where react-router-dom is mocked
+let MemoryRouter: React.ComponentType<any> | null = null;
+try {
+  const routerModule = require('react-router-dom');
+  MemoryRouter = routerModule.MemoryRouter || null;
+} catch {
+  // react-router-dom may be mocked, MemoryRouter will be null
+}
+
 // Mock providers for testing - optimized for performance
 let sharedQueryClient: QueryClient | null = null;
 
@@ -34,6 +43,8 @@ const createTestQueryClient = () => {
 interface CustomRenderOptions extends Omit<RenderOptions, 'wrapper'> {
   queryClient?: QueryClient;
   withQueryClient?: boolean;
+  withRouter?: boolean;
+  initialEntries?: string[];
 }
 
 export function renderWithProviders(
@@ -43,18 +54,33 @@ export function renderWithProviders(
   const {
     queryClient = createTestQueryClient(),
     withQueryClient = true,
+    withRouter = true,
+    initialEntries = ['/'],
     ...renderOptions
   } = options;
 
   const Wrapper = ({ children }: { children: React.ReactNode }) => {
+    let content = <>{children}</>;
+    
     if (withQueryClient) {
-      return (
+      content = (
         <QueryClientProvider client={queryClient}>
-          {children}
+          {content}
         </QueryClientProvider>
       );
     }
-    return <>{children}</>;
+    
+    // Only wrap with Router if MemoryRouter is available and withRouter is true
+    // Some tests may already have a Router or mock react-router-dom
+    if (withRouter && MemoryRouter) {
+      content = (
+        <MemoryRouter initialEntries={initialEntries}>
+          {content}
+        </MemoryRouter>
+      );
+    }
+    
+    return content;
   };
 
   return render(ui, { wrapper: Wrapper, ...renderOptions });

package/src/__tests__/rbac/PagePermissionGuard.test.tsx

@@ -19,8 +19,9 @@ import { useUnifiedAuth } from '../../providers';
 import { useCan } from '../../rbac/hooks';
 
 // Mock the hooks
-vi.mock('../../providers', () => ({
-  useUnifiedAuth: vi.fn(),
+const mockUseUnifiedAuthFn = vi.fn();
+vi.mock('../../providers/services/UnifiedAuthProvider', () => ({
+  useUnifiedAuth: () => mockUseUnifiedAuthFn(),
   UnifiedAuthProvider: ({ children }: { children: React.ReactNode }) => <>{children}</>,
 }));
 vi.mock('../../rbac/hooks', () => ({
@@ -28,7 +29,6 @@ vi.mock('../../rbac/hooks', () => ({
 }));
 vi.mock('../../utils/appNameResolver');
 
-const mockUseUnifiedAuth = vi.mocked(useUnifiedAuth);
 const mockUseCan = vi.mocked(useCan);
 
 describe('PagePermissionGuard', () => {
@@ -48,8 +48,10 @@ describe('PagePermissionGuard', () => {
     vi.clearAllMocks();
     
     // Default mock implementations
-    vi.mocked(useUnifiedAuth).mockReturnValue({
+    mockUseUnifiedAuthFn.mockReturnValue({
       user: mockUser,
+      selectedOrganisation: { id: 'org-123' },
+      selectedEvent: { event_id: 'event-123' },
       selectedOrganisationId: 'org-123',
       selectedEventId: 'event-123',
       supabase: {} as any,
@@ -188,7 +190,7 @@ describe('PagePermissionGuard', () => {
 
   describe('Scope Resolution', () => {
     it('should work with organisation context', async () => {
-      mockUseUnifiedAuth.mockReturnValue({
+      mockUseUnifiedAuthFn.mockReturnValue({
         user: mockUser,
         selectedOrganisationId: 'org-123',
         selectedEventId: null,

package/src/components/Alert/Alert.test.tsx

@@ -110,7 +110,7 @@ describe('Alert Component', () => {
     });
 
     it('forwards ref correctly', () => {
-      const ref = React.createRef<HTMLParagraphElement>();
+      const ref = React.createRef<HTMLHeadingElement>();
       
       renderWithProviders(
         <Alert>
@@ -387,7 +387,7 @@ describe('Alert Component', () => {
     });
 
     it('handles invalid variant gracefully', () => {
-      // @ts-expect-error Testing invalid variant
+      // @ts-expect-error - Testing invalid variant type for runtime behavior
       renderWithProviders(
         <Alert variant="invalid">
           <AlertTitle>Test</AlertTitle>

package/src/components/Alert/Alert.tsx

@@ -50,7 +50,7 @@ import * as React from "react"
 import { cn } from "../../utils/core/cn"
 
 // Context to share variant with child components
-const AlertContext = React.createContext<{ variant?: "default" | "destructive" | "inline" | null }>({ variant: "default" })
+const AlertContext = React.createContext<{ variant?: "default" | "destructive" | "inline" }>({ variant: "default" })
 
 const getAlertClasses = (variant: "default" | "destructive" | "inline" = "default"): string => {
   const baseClasses = "relative w-full rounded-lg border p-4";
@@ -92,7 +92,7 @@ const Alert = React.forwardRef<
 Alert.displayName = "Alert"
 
 const AlertTitle = React.forwardRef<
-  HTMLParagraphElement,
+  HTMLHeadingElement,
   React.HTMLAttributes<HTMLHeadingElement>
 >(({ className, ...props }, ref) => {
   const { variant } = React.useContext(AlertContext)
@@ -104,7 +104,7 @@ const AlertTitle = React.forwardRef<
   return (
     <h5
       ref={ref}
-      className={cn("", className)}
+      className={cn(className)}
       {...props}
     />
   )
@@ -124,7 +124,7 @@ const AlertDescription = React.forwardRef<
   return (
     <p
       ref={ref}
-      className={cn("", className)}
+      className={cn(className)}
       {...props}
     />
   )