@jmruthers/pace-core 0.5.181 → 0.5.182

package/docs/troubleshooting/styling-issues.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T15:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # Troubleshooting Styling Issues
@@ -268,6 +268,201 @@ npm run build
 
 ## 🆘 Still Not Working?
 
+## 🔍 Tailwind v4 Content Scanning Issues
+
+### The Core Problem
+
+Tailwind v4 needs to scan source files to detect utility classes, but published packages only contain compiled JavaScript. This results in:
+
+- ❌ Only ~292 CSS rules instead of 987+ needed
+- ❌ Missing component styles
+- ❌ Severely compromised UI
+
+### Solution 1: Use Source Files (Recommended)
+
+Pace-core v0.4.15+ includes source files in the published package for Tailwind scanning.
+
+#### Updated Vite Configuration
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss({
+      content: [
+        // Your app's source files
+        './src/**/*.{js,ts,jsx,tsx}',
+        // Pace-core source files (NEW)
+        './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'
+      ]
+    })
+  ],
+})
+```
+
+#### Alternative: PostCSS Configuration
+
+```javascript
+// tailwind.config.js
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: [
+    './src/**/*.{js,ts,jsx,tsx}',
+    './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'
+  ],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+}
+```
+
+### Solution 2: Pre-built CSS (Fallback)
+
+If source file scanning doesn't work, use the pre-built CSS approach:
+
+#### 1. Import Pre-built CSS
+
+```tsx
+// src/main.tsx
+import '@jmruthers/pace-core/src/styles/core.css';
+// Don't import your own Tailwind CSS
+```
+
+#### 2. Disable Tailwind in Your App
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+// Don't include tailwindcss plugin
+
+export default defineConfig({
+  plugins: [react()],
+})
+```
+
+### Solution 3: Hybrid Approach
+
+Use both approaches for maximum compatibility:
+
+#### 1. Vite Configuration
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss({
+      content: [
+        './src/**/*.{js,ts,jsx,tsx}',
+        './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}',
+        // Fallback: also scan dist files
+        './node_modules/@jmruthers/pace-core/dist/**/*.{js,ts,jsx,tsx}'
+      ]
+    })
+  ],
+})
+```
+
+#### 2. CSS Import
+
+```tsx
+// src/main.tsx
+import '@jmruthers/pace-core/src/styles/core.css';
+```
+
+### Verification Steps
+
+#### 1. Check CSS Output Size
+
+After building, your CSS should be:
+- **Expected**: 50-100+ kB (with all utility classes)
+- **Problem**: 20-30 kB (missing classes)
+
+#### 2. Verify Component Styling
+
+Test with a simple component:
+
+```tsx
+import { Button, Card } from '@jmruthers/pace-core';
+
+function TestComponent() {
+  return (
+    <Card className="p-4">
+      <Button variant="primary" className="bg-main-600 text-main-50">
+        Test Button
+      </Button>
+    </Card>
+  );
+}
+```
+
+**Expected Result**: Properly styled components with PACE Core colors and spacing.
+
+#### 3. Check Browser Dev Tools
+
+Inspect elements to verify:
+- ✅ `bg-main-600` class is applied
+- ✅ `text-main-50` class is applied
+- ✅ Component has proper padding and styling
+
+### Troubleshooting Content Scanning
+
+#### Issue: Source files not found
+
+**Error**: `Cannot resolve './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'`
+
+**Solution**: Ensure you're using pace-core v0.4.15+ which includes source files.
+
+#### Issue: Still only 292 rules
+
+**Possible Causes**:
+1. Using old package version
+2. Incorrect content paths
+3. Cached build files
+
+**Solutions**:
+1. Update to latest pace-core: `npm install @jmruthers/pace-core@latest`
+2. Clear node_modules and reinstall: `rm -rf node_modules package-lock.json && npm install`
+3. Clear build cache: `rm -rf dist .vite`
+
+#### Issue: Build errors with source files
+
+**Error**: TypeScript errors when scanning source files
+
+**Solution**: Add TypeScript configuration for node_modules:
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "skipLibCheck": true
+  },
+  "include": [
+    "src/**/*",
+    "node_modules/@jmruthers/pace-core/src/**/*"
+  ]
+}
+```
+
+### Expected Results
+
+With proper configuration, you should see:
+- ✅ 987+ CSS rules generated
+- ✅ All component styles working
+- ✅ Full UI functionality restored
+- ✅ Proper color palette applied
+
 If you've tried everything above and still have issues:
 
 1. **Create a minimal test case** showing the problem
@@ -277,4 +472,51 @@ If you've tried everything above and still have issues:
 
 ---
 
-**Last Updated:** 2025-01-XX | **Version:** v0.5.65+
+**Last Updated:** 2025-01-28 | **Version:** v0.5.181
+
+## ♿ Accessibility
+
+Troubleshooting styling issues should consider accessibility:
+
+- **WCAG 2.1 AA compliance** - Ensure fixes maintain accessibility standards
+- **Screen Reader Support** - Verify styling fixes don't break screen reader functionality
+- **Keyboard Navigation** - Ensure styling changes don't affect keyboard accessibility
+- **Color Contrast** - Verify color fixes meet WCAG contrast requirements
+- **Focus Indicators** - Ensure focus states remain visible after styling fixes
+
+### Accessibility Best Practices
+
+1. **Test with screen readers** - Verify styling fixes work with assistive technologies
+2. **Check color contrast** - Use contrast checkers to verify color fixes
+3. **Maintain focus visibility** - Ensure focus indicators remain visible
+4. **Test keyboard navigation** - Verify all interactive elements remain keyboard accessible
+5. **Preserve semantic structure** - Don't break semantic HTML with styling fixes
+
+## ⚠️ Edge Cases
+
+### Styling Fixes Not Applying
+
+When styling fixes don't apply:
+- Clear browser cache and hard refresh
+- Verify CSS import order is correct
+- Check for CSS specificity conflicts
+- Ensure Tailwind is scanning all necessary files
+- Restart dev server after configuration changes
+
+### Build-Time vs Runtime Styling Issues
+
+When styles work in development but not production:
+- Verify build configuration matches development
+- Check that all CSS files are included in build
+- Ensure Tailwind is configured for production builds
+- Verify content scanning paths are correct
+- Check for CSS minification issues
+
+### Multiple Styling Conflicts
+
+When multiple styling issues occur simultaneously:
+- Address CSS import order first
+- Fix Tailwind configuration before component-specific issues
+- Resolve color palette issues before utility class problems
+- Test each fix independently
+- Use browser DevTools to identify conflicting styles

package/{src/components/DataTable/examples → examples/DataTable}/GroupingAggregationExample.tsx

@@ -10,7 +10,7 @@
  */
 
 import React from 'react';
-import { DataTable, sum, average, count, type DataTableColumn, type DataRecord } from '../index';
+import { DataTable, sum, average, count, type DataTableColumn, type DataRecord } from '@jmruthers/pace-core';
 
 // ============================================================================
 // DATA INTERFACE

package/examples/{components 2/DataTable/HierarchicalActionsExample.tsx → DataTable/HierarchicalActionsExample.tsx}

@@ -9,10 +9,13 @@
  */
 
 import React from 'react';
-import { DataTable } from '../DataTable';
-import type { DataTableColumn, DataTableAction } from '../types';
-import { Button } from '../../Button';
-import { createLogger } from '../../../utils/logger';
+import { 
+  DataTable, 
+  type DataTableColumn, 
+  type DataTableAction,
+  type HierarchicalDataRow,
+  Button
+} from '@jmruthers/pace-core';
 import { 
   PlusIcon, 
   PencilIcon, 
@@ -25,7 +28,6 @@ import {
   InfoIcon,
   StarIcon
 } from 'lucide-react';
-import type { HierarchicalDataRow } from '../types';
 
 // ============================================================================
 // DATA TYPES
@@ -352,7 +354,6 @@ const columns: DataTableColumn<Dish>[] = [
 // ============================================================================
 
 export function HierarchicalActionsExample() {
-  const logger = createLogger('HierarchicalActionsExample');
   return (
     <div className="space-y-6">
       <div>

package/{src/components/DataTable/examples → examples/DataTable}/HierarchicalExample.tsx

@@ -17,10 +17,12 @@
  */
 
 import React from 'react';
-import { DataTable } from '../DataTable';
-import type { DataTableColumn } from '../types';
-import { ExpandButton, ExpandButtonMinimal } from '../components/ExpandButton';
-import type { HierarchicalDataRow, HierarchicalConfig } from '../types';
+import { 
+  DataTable, 
+  type DataTableColumn,
+  type HierarchicalDataRow,
+  type HierarchicalConfig
+} from '@jmruthers/pace-core';
 
 // ============================================================================
 // DATA TYPES
@@ -313,7 +315,7 @@ const hierarchicalConfig: HierarchicalConfig = {
   onExpandedChange: (expandedIds) => {
     // Expanded rows changed
   },
-  expandButton: ExpandButton, // Use default expand button
+  // expandButton is optional - DataTable uses default if not provided
   indentSize: 24, // 24px indentation for child rows
   parentRowClassName: 'bg-main-50 hover:bg-main-100 font-medium border-l-4 border-l-main-500',
   childRowClassName: 'bg-sec-25 hover:bg-sec-50 text-sec-700',
@@ -378,7 +380,7 @@ export function HierarchicalExample() {
 export function HierarchicalExampleMinimal() {
   const minimalConfig: HierarchicalConfig = {
     ...hierarchicalConfig,
-    expandButton: ExpandButtonMinimal,
+    // expandButton is optional - DataTable uses default if not provided
     parentRowClassName: 'bg-acc-50 hover:bg-acc-100 font-semibold',
     childRowClassName: 'bg-acc-25 hover:bg-acc-50',
   };

package/examples/{components 2/DataTable/PerformanceExample.tsx → DataTable/PerformanceExample.tsx}

@@ -7,14 +7,14 @@
 
 import React, { useState, useMemo } from 'react';
 import { 
+  DataTable,
   type DataTableColumn,
   type ServerSideConfig,
   type PerformanceConfig,
   type ServerSideParams,
   type ServerSideResponse,
   type DataTableFeatureConfig
-} from '../types';
-import { DataTable } from '../DataTable';
+} from '@jmruthers/pace-core';
 
 // Sample data interface
 interface User {

package/examples/{components 2/DataTable/index.ts → DataTable/index.ts}

@@ -11,3 +11,4 @@ export { HierarchicalExample } from './HierarchicalExample';
 export { HierarchicalActionsExample } from './HierarchicalActionsExample';
 export { InitialPageSizeExample } from './InitialPageSizeExample';
 export { PerformanceExample } from './PerformanceExample';
+export { GroupingAggregationExample, CustomAggregationExample } from './GroupingAggregationExample';

package/{src/components/Dialog/examples → examples/Dialog}/HtmlDialogExample.tsx

@@ -17,9 +17,9 @@ import {
   DialogTitle, 
   DialogDescription,
   DialogBody,
-  DialogFooter
-} from '../Dialog';
-import { Button } from '../../Button';
+  DialogFooter,
+  Button
+} from '@jmruthers/pace-core';
 
 export function HtmlDialogExample() {
   const importInstructionsHtml = `

package/examples/{components 2/Dialog/ScrollableDialogExample.tsx → Dialog/ScrollableDialogExample.tsx}

@@ -23,7 +23,7 @@ import {
   DialogDescription,
   Button,
   Card,
-} from '../../../index';
+} from '@jmruthers/pace-core';
 
 /**
  * Example demonstrating Dialog with scrolling, height, and width constraints

package/{src/components/Dialog/examples → examples/Dialog}/SmartDialogExample.tsx

@@ -18,7 +18,7 @@ import {
   Button,
   Input,
   Label,
-} from '../../../index';
+} from '@jmruthers/pace-core';
 
 /**
  * Example demonstrating the enhanced Dialog component with all advanced features

package/examples/{components 2/Dialog/index.ts → Dialog/index.ts}

@@ -10,6 +10,3 @@
 export { HtmlDialogExample } from './HtmlDialogExample';
 export { ScrollableDialogExample } from './ScrollableDialogExample';
 export { SmartDialogExample } from './SmartDialogExample';
-export { SimpleHtmlTest } from './SimpleHtmlTest';
-export { BasicHtmlTest } from './BasicHtmlTest';
-export { DebugHtmlExample } from './DebugHtmlExample';

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

@@ -19,11 +19,12 @@ import {
   PublicPageLayout, 
   PublicPageHeader, 
   PublicPageFooter,
-  EventLogo,
+  FileDisplay,
+  FileCategory,
   usePublicEvent,
   usePublicRouteParams,
-  PublicLoadingSpinner
-} from '../../../src';
+  LoadingSpinner
+} from '@jmruthers/pace-core';
 
 /**
  * MAIN APPLICATION - This is your main app with authentication
@@ -97,9 +98,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>
     );
   }
 
@@ -219,12 +223,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>
@@ -244,7 +259,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) return <div>Error: {error.message}</div>;
   if (!event) return <div>Event not found</div>;
 
@@ -259,12 +283,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}/PublicEventPage.tsx

@@ -34,12 +34,12 @@ import {
   PublicPageLayout, 
   PublicPageHeader, 
   PublicPageFooter,
-  EventLogo,
+  FileDisplay,
+  FileCategory,
   usePublicEvent,
   usePublicRouteParams,
-  PublicLoadingSpinner,
-  PublicErrorBoundary
-} from '../../../src';
+  LoadingSpinner
+} from '@jmruthers/pace-core';
 
 /**
  * Complete public event page example
@@ -56,9 +56,12 @@ export function PublicEventPage() {
   // Handle loading state
   if (eventLoading) {
     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>
     );
   }
 
@@ -114,8 +117,7 @@ export function PublicEventPage() {
   }
 
   return (
-    <PublicErrorBoundary>
-      <PublicPageLayout eventCode={eventCode || ''} event={event}>
+    <PublicPageLayout eventCode={eventCode || ''} event={event}>
         <PublicPageHeader 
           event={event}
           eventCode={eventCode || ''}
@@ -170,12 +172,23 @@ export function PublicEventPage() {
             {/* 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>
@@ -205,7 +218,6 @@ export function PublicEventPage() {
 
         <PublicPageFooter event={event} />
       </PublicPageLayout>
-    </PublicErrorBoundary>
   );
 }
 
@@ -216,28 +228,47 @@ export function PublicEventPageCompact() {
   const { eventCode } = usePublicRouteParams();
   const { event, isLoading, error } = usePublicEvent(eventCode || '');
 
-  if (isLoading) return <PublicLoadingSpinner message="Loading..." />;
+  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...</p>
+        </div>
+      </div>
+    );
+  }
   if (error || !event) return <div>Event not found</div>;
 
   return (
-    <PublicErrorBoundary>
-      <PublicPageLayout eventCode={eventCode || ''} event={event}>
-        <PublicPageHeader 
-          event={event}
-          eventCode={eventCode || ''}
-          showEventLogo={true}
-          showAppLogo={true}
-        />
-        
-        <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"
-              className="mx-auto mb-4"
-            />
+    <PublicPageLayout eventCode={eventCode || ''} event={event}>
+      <PublicPageHeader 
+        event={event}
+        eventCode={eventCode || ''}
+        showEventLogo={true}
+        showAppLogo={true}
+      />
+      
+      <main className="max-w-4xl mx-auto px-4 py-6">
+        <div className="text-center mb-6">
+          <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 && (
               <p className="text-sec-600 mt-2">
@@ -267,7 +298,6 @@ export function PublicEventPageCompact() {
 
         <PublicPageFooter event={event} />
       </PublicPageLayout>
-    </PublicErrorBoundary>
   );
 }