@jmruthers/pace-core 0.6.1 → 0.6.2

package/src/components/ErrorBoundary/ErrorBoundaryContext.tsx

@@ -0,0 +1,129 @@
+/**
+ * @file Error Boundary Context
+ * @package @jmruthers/pace-core
+ * @module Components/ErrorBoundary
+ * @since 0.6.2
+ *
+ * Context provider for global error handler configuration in ErrorBoundary components.
+ * Allows applications to register a default error handler once, which is then used by
+ * all ErrorBoundary instances unless overridden.
+ *
+ * @example
+ * ```tsx
+ * // Setup once in main.tsx
+ * <ErrorBoundaryProvider
+ *   defaultErrorHandler={(error, errorInfo, errorId, componentName) => {
+ *     if (import.meta.env.DEV) {
+ *       console.error(`[${componentName}] ErrorBoundary caught error:`, error, errorInfo);
+ *     }
+ *     errorTracking.captureException(error, {
+ *       componentStack: errorInfo.componentStack,
+ *       errorBoundary: true,
+ *       errorId,
+ *       componentName,
+ *     });
+ *   }}
+ * >
+ *   <App />
+ * </ErrorBoundaryProvider>
+ *
+ * // Usage - no onError needed, uses global handler
+ * <ErrorBoundary componentName="AppRoot">
+ *   <AppContent />
+ * </ErrorBoundary>
+ * ```
+ */
+
+import React, { createContext, useContext, ReactNode } from 'react';
+
+/**
+ * Type definition for the global error handler function
+ * @public
+ */
+export type GlobalErrorHandler = (
+  error: Error,
+  errorInfo: React.ErrorInfo,
+  errorId: string,
+  componentName: string
+) => void;
+
+/**
+ * Context value type for ErrorBoundary configuration
+ * @internal
+ */
+interface ErrorBoundaryContextType {
+  /** Global error handler that will be used by all ErrorBoundary instances */
+  defaultErrorHandler?: GlobalErrorHandler;
+}
+
+/**
+ * Context for ErrorBoundary global configuration
+ * @internal
+ */
+const ErrorBoundaryContext = createContext<ErrorBoundaryContextType | undefined>(undefined);
+
+/**
+ * Props for ErrorBoundaryProvider component
+ * @public
+ */
+export interface ErrorBoundaryProviderProps {
+  /** Children to wrap with the provider */
+  children: ReactNode;
+  /** Global error handler that will be used by all ErrorBoundary instances unless overridden */
+  defaultErrorHandler?: GlobalErrorHandler;
+}
+
+/**
+ * Provider component for ErrorBoundary global error handler configuration
+ * 
+ * Wrap your application with this provider to set a default error handler that will
+ * be used by all ErrorBoundary instances unless they provide their own onError prop.
+ * 
+ * @example
+ * ```tsx
+ * <ErrorBoundaryProvider
+ *   defaultErrorHandler={(error, errorInfo, errorId, componentName) => {
+ *     errorTracking.captureException(error, {
+ *       componentStack: errorInfo.componentStack,
+ *       errorBoundary: true,
+ *       errorId,
+ *       componentName,
+ *     });
+ *   }}
+ * >
+ *   <App />
+ * </ErrorBoundaryProvider>
+ * ```
+ * 
+ * @public
+ */
+/**
+ * Error boundary provider component.
+ * Provides global error handling configuration to child ErrorBoundary components.
+ * 
+ * @param props - Error boundary provider configuration
+ * @returns The error boundary provider
+ */
+export function ErrorBoundaryProvider({
+  children,
+  defaultErrorHandler,
+}: ErrorBoundaryProviderProps) {
+  const contextValue: ErrorBoundaryContextType = {
+    defaultErrorHandler,
+  };
+
+  return (
+    <ErrorBoundaryContext.Provider value={contextValue}>
+      {children}
+    </ErrorBoundaryContext.Provider>
+  );
+}
+
+/**
+ * Hook to access ErrorBoundary context
+ * @internal
+ */
+export function useErrorBoundaryContext(): ErrorBoundaryContextType | undefined {
+  return useContext(ErrorBoundaryContext);
+}
+

package/src/components/ErrorBoundary/index.ts

@@ -2,7 +2,32 @@
  * @file Error Boundary exports
  */
 
-export { ErrorBoundary } from './ErrorBoundary';
+// Re-export ErrorBoundary with automatic context support
+import { ErrorBoundary as ErrorBoundaryClass } from './ErrorBoundary';
+import { useErrorBoundaryContext } from './ErrorBoundaryContext';
+import React from 'react';
+import type { ErrorBoundaryProps } from './ErrorBoundary';
+
+// Export types and provider
 export type { ErrorBoundaryProps, ErrorBoundaryState } from './ErrorBoundary';
-import { ErrorBoundary } from './ErrorBoundary';
+export { ErrorBoundaryProvider } from './ErrorBoundaryContext';
+export type { ErrorBoundaryProviderProps, GlobalErrorHandler } from './ErrorBoundaryContext';
+
+/**
+ * ErrorBoundary component with automatic context support
+ * This wrapper automatically uses the global error handler from ErrorBoundaryProvider
+ * if no onError prop is provided.
+ */
+export const ErrorBoundary = React.forwardRef<
+  ErrorBoundaryClass,
+  Omit<ErrorBoundaryProps, '_globalErrorHandler'>
+>((props, ref) => {
+  const context = useErrorBoundaryContext();
+  const globalErrorHandler = context?.defaultErrorHandler;
+  
+  return React.createElement(ErrorBoundaryClass, { ...props, ref, _globalErrorHandler: globalErrorHandler });
+});
+
+ErrorBoundary.displayName = 'ErrorBoundary';
+
 export default ErrorBoundary;

package/src/components/EventSelector/EventSelector.tsx

@@ -95,6 +95,9 @@ import { useEffect, useMemo, useRef } from 'react';
 import { cn } from '../../utils/core/cn';
 import { logger } from '../../utils/core/logger';
 
+/**
+ * Props for the EventSelector component.
+ */
 export interface EventSelectorProps {
   /** Placeholder text for the dropdown */
   placeholder?: string;

package/src/components/FileDisplay/FileDisplay.tsx

@@ -192,10 +192,15 @@ function FileDisplayContent({
 
   const handleDeleteConfirm = async () => {
     setDeleteDialogOpen(false);
-    if (onDelete) {
-      await onDelete();
+    try {
+      if (onDelete) {
+        await onDelete();
+      }
+      setImageError(false);
+    } catch (error) {
+      // Error handling is delegated to onDelete callback
+      setImageError(false);
     }
-    setImageError(false);
   };
 
   const handleImageError = () => {
@@ -773,16 +778,10 @@ function FileDisplayAuthenticated({
 }: FileDisplayProps) {
   const { supabase } = useUnifiedAuth();
 
-  if (!supabase) {
-    return (
-      <figure className={className} title="Error">
-        <p className={getFallbackClasses(fallbackSize || 'md')}>
-          Supabase client not available in authenticated context
-        </p>
-      </figure>
-    );
-  }
+  // Consolidated state for displayOnly mode - must be before early return
+  const [displayOnlyFileReference, setDisplayOnlyFileReference] = useState<FileReference | null>(null);
 
+  // Call hooks before any early returns - hooks must handle null supabase gracefully
   const {
     fileUrl,
     fileReference,
@@ -797,20 +796,17 @@ function FileDisplayAuthenticated({
     record_id,
     organisation_id,
     category,
-    { supabase }
+    { supabase: supabase || null }
   );
-
-  // Consolidated state for displayOnly mode
-  const [displayOnlyFileReference, setDisplayOnlyFileReference] = useState<FileReference | null>(null);
   
   // Use fileUrls map if available, otherwise use useFileUrl hook
   const displayOnlyFileUrlFromMap = displayOnlyFileReference ? fileUrls.get(displayOnlyFileReference.id) : null;
   const displayOnlyFileUrlHook = useFileUrl(
     displayOnlyFileReference && !displayOnlyFileUrlFromMap ? displayOnlyFileReference : null,
     {
-      supabase,
+      supabase: supabase || null,
       organisation_id,
-      autoLoad: !displayOnlyFileUrlFromMap && !!displayOnlyFileReference
+      autoLoad: !displayOnlyFileUrlFromMap && !!displayOnlyFileReference && !!supabase
     }
   );
   const displayOnlyFileUrl = displayOnlyFileUrlFromMap || displayOnlyFileUrlHook.url;
@@ -831,6 +827,17 @@ function FileDisplayAuthenticated({
     }
   }, [displayOnly, category, fileReferences, fileUrls]);
 
+  // Early return check after all hooks are called
+  if (!supabase) {
+    return (
+      <figure className={className} title="Error">
+        <p className={getFallbackClasses(fallbackSize || 'md')}>
+          Supabase client not available in authenticated context
+        </p>
+      </figure>
+    );
+  }
+
   // Delete operation - implementation pending
   const handleDelete = async () => {
     // TODO: Implement delete via FileReferenceService when delete functionality is needed
@@ -906,6 +913,13 @@ function FileDisplayAuthenticated({
  * @param props.category - Optional category filter. When specified, only displays files matching this category and uses single file display variant.
  * @returns React element with file display
  */
+/**
+ * File display component.
+ * Renders files from the file reference system with support for previews, downloads, and public/private access.
+ * 
+ * @param props - File display configuration
+ * @returns The rendered file display
+ */
 export function FileDisplay({
   table_name,
   record_id,

package/src/components/FileUpload/FileUpload.tsx

@@ -15,6 +15,10 @@ import { getCurrentAppName } from '../../utils/app/appNameResolver';
 import { getAppId } from '../../utils/app/appIdResolver';
 import { assertAppId } from '../../types/core';
 
+/**
+ * Props for the FileUpload component.
+ * Configures file upload behavior including storage location, validation, and callbacks.
+ */
 export interface FileUploadProps {
   supabase: SupabaseClient;
   table_name: string;
@@ -71,6 +75,15 @@ export function FileUpload({
   onProgress,
   children
 }: FileUploadProps) {
+  // Validate pageContext early - required prop
+  if (!pageContext) {
+    const errorMsg = 'pageContext is required for FileUpload component. This is used for permission checks.';
+    if (import.meta.env.MODE === 'development') {
+      console.error('[FileUpload]', errorMsg);
+    }
+    throw new Error(errorMsg);
+  }
+
   const [isDragging, setIsDragging] = useState(false);
   const [uploadStates, setUploadStates] = useState<Map<string, FileUploadState>>(new Map());
   const [resolvedAppId, setResolvedAppId] = useState<string | null>(app_id || null);
@@ -286,6 +299,12 @@ export function FileUpload({
           throw new Error(errorMsg);
         }
 
+        // Validate pageContext before upload
+        if (!pageContext) {
+          const errorMsg = 'pageContext is required for file upload. This is used for permission checks.';
+          throw new Error(errorMsg);
+        }
+
         const result = await uploadFile({
           table_name,
           record_id,
@@ -294,7 +313,7 @@ export function FileUpload({
           app_id: resolvedAppId ? assertAppId(resolvedAppId) : assertAppId(''),
           category,
           folder,
-          pageContext,
+          pageContext: pageContext,
           event_id,
           is_public: isPublic
         }, file);
@@ -393,7 +412,7 @@ export function FileUpload({
         onUploadError?.(errorMessage, file);
       }
     }
-  }, [uploadFile, table_name, record_id, organisation_id, resolvedAppId, category, folder, isPublic, maxSize, onUploadSuccess, onUploadError, onProgress, validateFile, generatePreview, showPreview, appIdError]);
+  }, [uploadFile, table_name, record_id, organisation_id, resolvedAppId, category, folder, isPublic, maxSize, onUploadSuccess, onUploadError, onProgress, validateFile, generatePreview, showPreview, appIdError, pageContext]);
 
   const handleDragOver = useCallback((e: React.DragEvent) => {
     e.preventDefault();
@@ -475,6 +494,7 @@ export function FileUpload({
               className="hidden"
               disabled={isDisabled}
               data-testid="file-input"
+              aria-label={accept ? `Upload file${multiple ? 's' : ''} (${accept})` : `Upload file${multiple ? 's' : ''}`}
             />
             <div className="text-sec-600">
               {isResolvingAppId ? (

package/src/components/Footer/Footer.test.tsx

@@ -82,7 +82,7 @@ describe('Footer Component', () => {
     it('renders with children content', () => {
       renderWithProviders(
         <Footer>
-          <div data-testid="custom-content">Custom footer content</div>
+          <section data-testid="custom-content">Custom footer content</section>
         </Footer>
       );
       
@@ -163,7 +163,7 @@ describe('Footer Component', () => {
     it('renders content in proper semantic structure', () => {
       renderWithProviders(
         <Footer>
-          <div>Custom content</div>
+          <section>Custom content</section>
         </Footer>
       );
       
@@ -175,7 +175,7 @@ describe('Footer Component', () => {
     it('renders logo before children content', () => {
       renderWithProviders(
         <Footer logo="/logo.png">
-          <div data-testid="children">Children content</div>
+          <section data-testid="children">Children content</section>
         </Footer>
       );
       
@@ -189,7 +189,7 @@ describe('Footer Component', () => {
     it('renders copyright text after children content', () => {
       renderWithProviders(
         <Footer>
-          <div data-testid="children">Children content</div>
+          <section data-testid="children">Children content</section>
         </Footer>
       );
       
@@ -380,7 +380,7 @@ describe('Footer Component', () => {
           logo="/test-logo.png"
           copyright="Custom copyright text"
         >
-          <div>Test children</div>
+          <section>Test children</section>
         </Footer>
       );
       
@@ -398,27 +398,27 @@ describe('Footer Component', () => {
     it('works with complex children content', () => {
       renderWithProviders(
         <Footer>
-          <div className="grid grid-cols-1 md:grid-cols-3 gap-8 mb-8">
-            <div>
+          <section className="grid grid-cols-1 md:grid-cols-3 gap-8 mb-8">
+            <section>
               <h3 className="font-semibold mb-2">About Us</h3>
               <p className="text-sm text-muted-foreground">
                 We provide innovative solutions for modern businesses.
               </p>
-            </div>
-            <div>
+            </section>
+            <section>
               <h3 className="font-semibold mb-2">Contact</h3>
               <p className="text-sm text-muted-foreground">
                 Email: info@company.com
               </p>
-            </div>
-            <div>
+            </section>
+            <section>
               <h3 className="font-semibold mb-2">Follow Us</h3>
-              <div className="flex gap-2">
+              <nav className="flex gap-2">
                 <a href="#" className="text-muted-foreground hover:text-foreground">Twitter</a>
                 <a href="#" className="text-muted-foreground hover:text-foreground">LinkedIn</a>
-              </div>
-            </div>
-          </div>
+              </nav>
+            </section>
+          </section>
         </Footer>
       );
       
@@ -463,7 +463,7 @@ describe('Footer Component', () => {
           logo="/logo.png"
           className="custom-footer"
         >
-          <div data-testid="custom-content">Custom footer content</div>
+          <section data-testid="custom-content">Custom footer content</section>
         </Footer>
       );
       

package/src/components/Footer/Footer.tsx

@@ -47,28 +47,28 @@
  * 
  * // Footer with custom content
  * <Footer companyName="My Company">
- *   <div className="grid grid-cols-1 md:grid-cols-3 gap-8 mb-8">
- *     <div>
+ *   <section className="grid grid-cols-1 md:grid-cols-3 gap-8 mb-8">
+ *     <section>
  *       <h3 className="font-semibold mb-2">About Us</h3>
  *       <p className="text-sm text-muted-foreground">
  *         We provide innovative solutions for modern businesses.
  *       </p>
- *     </div>
- *     <div>
+ *     </section>
+ *     <section>
  *       <h3 className="font-semibold mb-2">Contact</h3>
  *       <p className="text-sm text-muted-foreground">
  *         Email: info@mycompany.com<br />
  *         Phone: (555) 123-4567
  *       </p>
- *     </div>
- *     <div>
+ *     </section>
+ *     <section>
  *       <h3 className="font-semibold mb-2">Follow Us</h3>
- *       <div className="flex gap-2">
+ *       <nav className="flex gap-2">
  *         <a href="#" className="text-muted-foreground hover:text-foreground">Twitter</a>
  *         <a href="#" className="text-muted-foreground hover:text-foreground">LinkedIn</a>
- *       </div>
- *     </div>
- *   </div>
+ *       </nav>
+ *     </section>
+ *   </section>
  * </Footer>
  * ```
  *
@@ -87,6 +87,9 @@
 import React from 'react';
 import { cn } from '../../utils/core/cn';
 
+/**
+ * Props for the Footer component.
+ */
 export interface FooterProps {
   /**
    * Company or organization name
@@ -138,7 +141,7 @@ export interface FooterProps {
  * 
  * // With children
  * <Footer>
- *   <div>Custom footer content</div>
+ *   <section>Custom footer content</section>
  * </Footer>
  * 
  * // With logo and copyright

package/src/components/Form/Form.tsx

@@ -359,6 +359,7 @@ export function FormField<
                 type={type}
                 placeholder={placeholder}
                 data-testid={testId}
+                aria-label={label || placeholder || name}
                 className={cn(
                   "flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50",
                   fieldError && "border-destructive focus-visible:ring-destructive"

package/src/components/Header/Header.tsx

@@ -42,10 +42,10 @@
  *   ]}
  *   currentPath="/dashboard"
  *   actions={
- *     <div className="flex gap-2">
+ *     <>
  *       <Button variant="outline">Export</Button>
  *       <Button>New Item</Button>
- *     </div>
+ *     </>
  *   }
  *   user={currentUser}
  *   onSignOut={handleSignOut}
@@ -199,10 +199,10 @@ export interface HeaderProps {
  * 
  * function HeaderWithActions() {
  *   const customActions = (
- *     <div className="flex items-center gap-2">
+ *     <>
  *       <Button variant="outline" size="sm">Export</Button>
  *       <Button size="sm">New Item</Button>
- *     </div>
+ *     </>
  *   );
  * 
  *   return (
@@ -238,6 +238,13 @@ export interface HeaderProps {
  * 
  * @since 0.1.0
  */
+/**
+ * Header component for application layouts.
+ * Provides navigation, user menu, organisation/event selectors, and customizable branding.
+ * 
+ * @param props - Header configuration
+ * @returns The rendered header
+ */
 export function Header({
   logoUrl,
   logoAlt = 'Logo',
@@ -278,7 +285,7 @@ export function Header({
       "w-full border-b border-main-200 h-16 shadow-sm bg-main-100 ",
       className
     )} role="banner">
-      <nav className="px-4 w-[min(var(--app-width),100%)] mx-auto flex items-center gap-4 h-full">
+      <nav className="px-4 w-[min(var(--app-width),100%)] mx-auto grid grid-cols-[auto_1fr_auto_auto_auto_auto] items-center gap-4 h-full">
           {/* Logo */}
           {logo ? (
             logoHref ? (
@@ -333,10 +340,7 @@ export function Header({
               itemsPreFiltered={true}
             />
           )}
-        
 
-        {/* Right side: Organisation Selector, Event Selector, Actions, and User Menu */}
-        <div className="flex items-center gap-4 ml-auto">
           {/* Organisation Selector - Only show if user has organisations */}
           {showOrgSelector ? (
             <OrganisationSelectorConditional />
@@ -346,7 +350,15 @@ export function Header({
           {showEventSelector ? (
             <EventSelector 
               placeholder="Select event" 
-              className="w-96" 
+              className={cn(
+                "w-96",
+                // If both org selector and actions exist, EventSelector uses 1 column
+                // If only one exists, EventSelector spans 2 columns
+                // If neither exists, EventSelector spans 3 columns
+                showOrgSelector && actions ? "col-span-1" :
+                showOrgSelector || actions ? "col-span-2" :
+                "col-span-3"
+              )}
               data-testid="event-selector" 
             />
           ) : null}
@@ -367,7 +379,6 @@ export function Header({
               />
             )
           )}
-        </div>
 
       </nav>
     </header>

package/src/components/Input/Input.test.tsx

@@ -420,14 +420,14 @@ describe('InputGroup Component', () => {
   // Accessibility tests
   describe('Accessibility', () => {
     it('forwards ref correctly', () => {
-      const ref = React.createRef<HTMLDivElement>();
+      const ref = React.createRef<HTMLFieldSetElement>();
       renderWithProviders(
         <InputGroup ref={ref}>
           <Input placeholder="Input 1" />
         </InputGroup>
       );
       
-      expect(ref.current).toBeInstanceOf(HTMLDivElement);
+      expect(ref.current).toBeInstanceOf(HTMLFieldSetElement);
     });
 
     it('maintains proper focus order', async () => {

package/src/components/Input/Input.tsx

@@ -55,6 +55,10 @@ import { cn } from '../../utils/core/cn';
 // BASE INPUT COMPONENT
 // ============================================================================
 
+/**
+ * Props for the Input component.
+ * Extends standard input HTML attributes.
+ */
 export interface InputProps
   extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size'> {
   /**
@@ -136,7 +140,7 @@ Input.displayName = 'Input';
 // INPUT GROUP COMPONENT
 // ============================================================================
 
-export interface InputGroupProps extends React.HTMLAttributes<HTMLDivElement> {
+export interface InputGroupProps extends React.HTMLAttributes<HTMLFieldSetElement> {
   /** Child elements to be rendered in the group */
   children: React.ReactNode;
   /** Layout orientation of the input group */
@@ -165,7 +169,7 @@ export interface InputGroupProps extends React.HTMLAttributes<HTMLDivElement> {
  * </InputGroup>
  * ```
  */
-export const InputGroup = React.forwardRef<HTMLDivElement, InputGroupProps>(
+export const InputGroup = React.forwardRef<HTMLFieldSetElement, InputGroupProps>(
   ({ className, children, orientation = 'vertical', spacing = 'md', ...props }, ref) => {
     const spacingClasses = {
       sm: orientation === 'horizontal' ? 'space-x-2' : 'space-y-2',
@@ -174,7 +178,7 @@ export const InputGroup = React.forwardRef<HTMLDivElement, InputGroupProps>(
     };
 
     return (
-      <div
+      <fieldset
         ref={ref}
         className={cn(
           'flex',
@@ -185,7 +189,7 @@ export const InputGroup = React.forwardRef<HTMLDivElement, InputGroupProps>(
         {...props}
       >
         {children}
-      </div>
+      </fieldset>
     );
   }
 );

package/src/components/LoadingSpinner/LoadingSpinner.test.tsx

@@ -382,10 +382,10 @@ describe('LoadingSpinner Component', () => {
 
     it('works within a card or container', () => {
       renderWithProviders(
-        <div className="card">
+        <section className="card">
           <h2>Loading Content</h2>
           <LoadingSpinner size="lg" />
-        </div>
+        </section>
       );
       
       const spinner = screen.getByRole('status');
@@ -397,11 +397,11 @@ describe('LoadingSpinner Component', () => {
 
     it('works with multiple instances', () => {
       renderWithProviders(
-        <div>
+        <>
           <LoadingSpinner size="sm" />
           <LoadingSpinner size="md" />
           <LoadingSpinner size="lg" />
-        </div>
+        </>
       );
       
       const spinners = screen.getAllByRole('status');

package/src/components/LoginForm/LoginForm.tsx

@@ -106,6 +106,10 @@ import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle }
 import { Alert, AlertDescription } from '../Alert/Alert';
 import { cn } from '../../utils/core/cn';
 
+/**
+ * Props for the LoginForm component.
+ * Configures login form behavior, validation, and callbacks.
+ */
 export interface LoginFormProps {
   /** Callback invoked when the form is submitted */
   onSignIn: (data: { email: string; password: string }) => Promise<void>;