@jmruthers/pace-core 0.6.1 → 0.6.3

package/src/components/Button/Button.tsx

@@ -53,6 +53,16 @@ import { Tooltip } from '../Tooltip';
 // BASE BUTTON COMPONENT
 // ============================================================================
 
+/**
+ * Button component props
+ * Extends standard HTML button attributes with button-specific styling and behavior options.
+ * 
+ * @interface ButtonProps
+ */
+/**
+ * Props for the Button component.
+ * Extends standard button HTML attributes.
+ */
 export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
   /** Visual variant of the button */
   variant?: 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link';
@@ -127,6 +137,12 @@ Button.displayName = 'Button';
 // BUTTON GROUP COMPONENT
 // ============================================================================
 
+/**
+ * ButtonGroup component props
+ * Configuration for grouping multiple buttons with consistent styling and spacing.
+ * 
+ * @interface ButtonGroupProps
+ */
 export type ButtonGroupProps = {
   /** Child elements to be rendered in the group */
   children: React.ReactNode;
@@ -216,6 +232,12 @@ export function ButtonGroup({
 // ICON BUTTON COMPONENT
 // ============================================================================
 
+/**
+ * IconButton component props
+ * Extends ButtonProps but requires an icon and aria-label instead of children.
+ * 
+ * @interface IconButtonProps
+ */
 export type IconButtonProps = Omit<ButtonProps, 'children'> & {
   /** The icon element to display in the button */
   icon: React.ReactNode;

package/src/components/Calendar/Calendar.tsx

@@ -89,6 +89,10 @@ type RootProps = {
 // CALENDAR COMPONENT
 // ============================================================================
 
+/**
+ * Props for the Calendar component.
+ * Extends DayPickerProps with pace-core specific customizations.
+ */
 export interface CalendarProps extends Omit<DayPickerProps, 'className' | 'classNames' | 'styles' | 'onSelect'> {
   /**
    * Additional CSS classes to apply to the calendar table
@@ -416,8 +420,10 @@ const Calendar = React.forwardRef<HTMLTableElement, CalendarProps>(
                 </>
               );
             }
-            
-            return child;
+
+            return React.isValidElement(child) 
+              ? React.cloneElement(child, { key: child.key ?? `calendar-child-${index}` })
+              : child;
           })}
         </>
       );

package/src/components/Card/Card.tsx

@@ -65,6 +65,10 @@ import * as React from "react"
 import { useNavigate } from "react-router-dom"
 import { cn } from "../../utils/core/cn"
 
+/**
+ * Props for the Card component.
+ * Extends standard HTML attributes for semantic HTML elements.
+ */
 export interface CardProps extends React.HTMLAttributes<HTMLElement> {
   /** Visual variant of the card */
   variant?: 'default' | 'outline' | 'ghost';

package/src/components/Checkbox/Checkbox.test.tsx

@@ -235,10 +235,10 @@ describe('Checkbox Component', () => {
 
     it('supports aria-labelledby', () => {
       renderWithProviders(
-        <div>
+        <>
           <label id="terms-label">Accept terms and conditions</label>
           <Checkbox aria-labelledby="terms-label" />
-        </div>
+        </>
       );
       const checkbox = screen.getByRole('checkbox', { name: 'Accept terms and conditions' });
       expect(checkbox).toBeInTheDocument();
@@ -246,10 +246,10 @@ describe('Checkbox Component', () => {
 
     it('supports aria-describedby', () => {
       renderWithProviders(
-        <div>
+        <>
           <Checkbox aria-describedby="terms-help" />
-          <div id="terms-help">Please read the terms carefully</div>
-        </div>
+          <span id="terms-help">Please read the terms carefully</span>
+        </>
       );
       const checkbox = screen.getByRole('checkbox');
       expect(checkbox).toHaveAttribute('aria-describedby', 'terms-help');
@@ -319,10 +319,10 @@ describe('Checkbox Component', () => {
   describe('Form Integration', () => {
     it('works with form labels', () => {
       renderWithProviders(
-        <div>
+        <>
           <label htmlFor="terms-checkbox">Accept terms and conditions</label>
           <Checkbox id="terms-checkbox" />
-        </div>
+        </>
       );
       
       const checkbox = screen.getByRole('checkbox');
@@ -388,11 +388,11 @@ describe('Checkbox Component', () => {
   describe('Integration', () => {
     it('works with multiple checkboxes', () => {
       renderWithProviders(
-        <div>
+        <>
           <Checkbox id="option1" />
           <Checkbox id="option2" />
           <Checkbox id="option3" />
-        </div>
+        </>
       );
       
       expect(screen.getAllByRole('checkbox')).toHaveLength(3);
@@ -420,13 +420,13 @@ describe('Checkbox Component', () => {
       const TestComponent = () => {
         const [checked, setChecked] = React.useState(false);
         return (
-          <div>
+          <>
             <Checkbox 
               checked={checked} 
               onCheckedChange={setChecked}
             />
             <span data-testid="status">{checked ? 'checked' : 'unchecked'}</span>
-          </div>
+          </>
         );
       };
       
@@ -470,7 +470,7 @@ describe('Checkbox Component', () => {
       ));
       
       const startTime = performance.now();
-      renderWithProviders(<div>{checkboxes}</div>);
+      renderWithProviders(<>{checkboxes}</>);
       const endTime = performance.now();
       
       // Performance test: verify rendering completes in reasonable time

package/src/components/Checkbox/Checkbox.tsx

@@ -21,10 +21,10 @@
  * <Checkbox />
  *
  * // With label
- * <div className="flex items-center space-x-2">
+ * <>
  *   <Checkbox id="terms" />
  *   <label htmlFor="terms">Accept terms and conditions</label>
- * </div>
+ * </>
  *
  * // Disabled state
  * <Checkbox disabled />

package/src/components/ContextSelector/ContextSelector.tsx

@@ -0,0 +1,384 @@
+/**
+ * @file Context Selector Component
+ * @package @jmruthers/pace-core
+ * @module Components/ContextSelector
+ * @since 0.6.4
+ *
+ * A unified intelligent selector component that shows all organisations and events
+ * a user can access based on their roles and permissions. This is the single
+ * selector for all apps - it intelligently determines what to show based on:
+ * - User's organisation roles
+ * - User's event-app roles
+ * - Super admin status (shows all)
+ *
+ * Features:
+ * - Intelligent display of accessible organisations and events
+ * - Grouped display (Organisations / Events sections)
+ * - Visual distinction between orgs and events
+ * - Super admin support (shows all orgs and events)
+ * - Loading states and error handling
+ * - Accessible interface design
+ * - Integration with OrganisationProvider and EventService
+ * - Automatically shows superset of what user can access
+ *
+ * @example
+ * ```tsx
+ * <ContextSelector
+ *   onOrganisationSelect={(org) => {
+ *     switchOrganisation(org.id);
+ *   }}
+ *   onEventSelect={(event) => {
+ *     setSelectedEvent(event);
+ *   }}
+ * />
+ * ```
+ *
+ * @accessibility
+ * - WCAG 2.1 AA compliant
+ * - Keyboard navigation support
+ * - Screen reader friendly
+ * - Focus management
+ * - ARIA labels and descriptions
+ * - High contrast support
+ *
+ * @security
+ * - Only shows organisations/events user has access to
+ * - Super admins see all items
+ * - Validates access before selection
+ */
+
+import React, { useMemo } from 'react';
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue, SelectGroup, SelectLabel, SelectSeparator } from '../Select';
+import { Alert, AlertDescription } from '../Alert/Alert';
+import { Button } from '../Button/Button';
+import { LoadingSpinner } from '../LoadingSpinner/LoadingSpinner';
+import { RefreshCw, AlertCircle, Building2, Calendar } from 'lucide-react';
+import { useOrganisations } from '../../hooks/useOrganisations';
+import { useEvents } from '../../hooks/useEvents';
+import { useRBAC } from '../../rbac/hooks/useRBAC';
+import type { Organisation } from '../../types/organisation';
+import type { Event } from '../../types/event';
+import { logger } from '../../utils/core/logger';
+
+/**
+ * Props for the ContextSelector component.
+ */
+export interface ContextSelectorProps {
+  /** Placeholder text for the dropdown */
+  placeholder?: string;
+  /** Additional CSS classes */
+  className?: string;
+  /** Callback fired when an organisation is selected */
+  onOrganisationSelect?: (org: Organisation) => void;
+  /** Callback fired when an event is selected */
+  onEventSelect?: (event: Event) => void;
+  /** Show friendly message when no items available */
+  showNoItemsMessage?: boolean;
+  /** Show retry button on errors */
+  showRetryButton?: boolean;
+  /** Compact display mode */
+  compact?: boolean;
+  /** Disabled state */
+  disabled?: boolean;
+  /** Show organisations section (default: true) */
+  showOrganisations?: boolean;
+  /** Show events section (default: true) */
+  showEvents?: boolean;
+}
+
+/**
+ * ContextSelector component for selecting organisations or events
+ * 
+ * This is the unified intelligent selector that shows all organisations and events
+ * a user can access. It automatically determines what to show based on the user's
+ * roles and permissions - no need to configure separate org/event selectors.
+ * 
+ * The selector intelligently shows:
+ * - All organisations the user has access to (via organisation roles)
+ * - All events the user has access to (via event-app roles or organisation membership)
+ * - Everything for super admins
+ * 
+ * @component
+ * @example
+ * <ContextSelector
+ *   onOrganisationSelect={(org) => switchOrganisation(org)}
+ *   onEventSelect={(event) => setSelectedEvent(event)}
+ * />
+ */
+export function ContextSelector({
+  placeholder = "Select organisation or event",
+  className,
+  onOrganisationSelect,
+  onEventSelect,
+  showNoItemsMessage = true,
+  showRetryButton = true,
+  compact = false,
+  disabled = false,
+  showOrganisations = true,
+  showEvents = true
+}: ContextSelectorProps) {
+  const { 
+    organisations, 
+    selectedOrganisation,
+    isLoading: orgLoading,
+    error: orgError,
+    refreshOrganisations
+  } = useOrganisations();
+  
+  const { 
+    events, 
+    selectedEvent, 
+    isLoading: eventLoading, 
+    error: eventError, 
+    refreshEvents
+  } = useEvents();
+  
+  const { isSuperAdmin } = useRBAC();
+  
+  const isLoading = (showOrganisations && orgLoading) || (showEvents && eventLoading);
+  const hasError = (showOrganisations && orgError) || (showEvents && eventError);
+  const hasItems = 
+    (showOrganisations && (organisations?.length || 0) > 0) || 
+    (showEvents && (events?.length || 0) > 0);
+  
+  // Determine current selection value
+  // Priority: Event selection takes precedence over organisation selection
+  // When an event is selected, show the event (even if an org is also selected)
+  // The organisation remains in context (derived from event) but selector shows the active selection
+  const currentValue = useMemo(() => {
+    if (showEvents && selectedEvent) {
+      return `event:${selectedEvent.event_id || selectedEvent.id}`;
+    }
+    if (showOrganisations && selectedOrganisation) {
+      return `org:${selectedOrganisation.id}`;
+    }
+    return '';
+  }, [showOrganisations, showEvents, selectedOrganisation?.id, selectedEvent]);
+  
+  const handleValueChange = (value: string) => {
+    if (disabled || isLoading) return;
+    
+    if (value.startsWith('org:') && showOrganisations) {
+      const orgId = value.replace('org:', '');
+      const org = organisations?.find(o => o.id === orgId);
+      if (org && onOrganisationSelect) {
+        onOrganisationSelect(org);
+      }
+    } else if (value.startsWith('event:') && showEvents) {
+      const eventId = value.replace('event:', '');
+      const event = events?.find(e => (e.event_id || e.id) === eventId);
+      if (event && onEventSelect) {
+        onEventSelect(event);
+      }
+    }
+  };
+  
+  const handleRetry = async () => {
+    try {
+      if (showOrganisations && orgError) {
+        await refreshOrganisations();
+      }
+      if (showEvents && eventError) {
+        await refreshEvents();
+      }
+    } catch (error) {
+      logger.error('ContextSelector', 'Failed to refresh:', error);
+    }
+  };
+  
+  // Loading state - only show loading if we don't have any items yet
+  // This prevents the selector from being stuck in loading when data exists
+  if (isLoading && !hasItems) {
+    const loadingText = compact ? "Loading..." : 
+      showOrganisations && showEvents ? "Loading organisations and events..." :
+      showOrganisations ? "Loading organisations..." :
+      "Loading events...";
+    return (
+      <div className={`flex items-center gap-2 ${className}`}>
+        <LoadingSpinner size="sm" />
+        <span className="text-sm text-muted-foreground">
+          {loadingText}
+        </span>
+      </div>
+    );
+  }
+  
+  // Error state
+  if (hasError) {
+    const errorMessages = [];
+    if (showOrganisations && orgError) {
+      errorMessages.push(`Failed to load organisations: ${orgError.message}`);
+    }
+    if (showEvents && eventError) {
+      errorMessages.push(`Failed to load events: ${eventError.message}`);
+    }
+    return (
+      <div className={`space-y-2 ${className}`}>
+        <Alert variant="destructive">
+          <AlertCircle className="size-4" />
+          <AlertDescription>
+            {errorMessages.join(' ')}
+          </AlertDescription>
+        </Alert>
+        {showRetryButton && (
+          <Button 
+            variant="outline" 
+            size="sm" 
+            onClick={handleRetry}
+            disabled={isLoading}
+            className="w-full"
+          >
+            <RefreshCw className={`size-4 mr-2 ${isLoading ? 'animate-spin' : ''}`} />
+            Retry
+          </Button>
+        )}
+      </div>
+    );
+  }
+  
+  // No items available
+  if (!hasItems) {
+    if (showNoItemsMessage) {
+      const noItemsText = 
+        showOrganisations && showEvents ? "No organisations or events available. Please contact your administrator." :
+        showOrganisations ? "No organisations available. Please contact your administrator." :
+        "No events available. Please contact your administrator.";
+      return (
+        <div className={`space-y-2 ${className}`}>
+          <Alert>
+            <AlertCircle className="size-4" />
+            <AlertDescription>
+              {noItemsText}
+            </AlertDescription>
+          </Alert>
+          {showRetryButton && (
+            <Button 
+              variant="outline" 
+              size="sm" 
+              onClick={handleRetry}
+              disabled={isLoading}
+              className="w-full"
+            >
+              <RefreshCw className={`size-4 mr-2 ${isLoading ? 'animate-spin' : ''}`} />
+              Check Again
+            </Button>
+          )}
+        </div>
+      );
+    }
+    return null;
+  }
+  
+  // Format display value
+  // Priority: Event selection takes precedence over organisation selection (matches currentValue)
+  const displayValue = useMemo(() => {
+    if (showEvents && selectedEvent) {
+      return (
+        <div className="flex items-center gap-2">
+          <Calendar className="size-4 flex-shrink-0" />
+          <span className="truncate">{selectedEvent.event_name}</span>
+        </div>
+      );
+    }
+    if (showOrganisations && selectedOrganisation) {
+      return (
+        <div className="flex items-center gap-2">
+          <Building2 className="size-4 flex-shrink-0" />
+          <span className="truncate">{selectedOrganisation.display_name}</span>
+        </div>
+      );
+    }
+    return null;
+  }, [showOrganisations, showEvents, selectedOrganisation, selectedEvent]);
+  
+  // Determine placeholder text based on what's shown
+  const effectivePlaceholder = useMemo(() => {
+    if (placeholder !== "Select organisation or event") {
+      return placeholder;
+    }
+    if (showOrganisations && showEvents) {
+      return "Select organisation or event";
+    }
+    if (showOrganisations) {
+      return "Select organisation";
+    }
+    if (showEvents) {
+      return "Select event";
+    }
+    return placeholder;
+  }, [placeholder, showOrganisations, showEvents]);
+  
+  return (
+    <div className={className} data-testid="context-selector">
+      <Select 
+        value={currentValue}
+        onValueChange={handleValueChange}
+        disabled={disabled || isLoading}
+      >
+        <SelectTrigger 
+          className="text-left"
+          variant="outline"
+        >
+          <SelectValue placeholder={effectivePlaceholder}>
+            {displayValue}
+          </SelectValue>
+        </SelectTrigger>
+        <SelectContent>
+          {/* Organisations Section */}
+          {showOrganisations && organisations && organisations.length > 0 && (
+            <>
+              <SelectGroup>
+                <SelectLabel>Organisations</SelectLabel>
+                {organisations.map((org) => (
+                  <SelectItem 
+                    key={org.id} 
+                    value={`org:${org.id}`}
+                  >
+                    <div className="flex items-center gap-2">
+                      <Building2 className="size-4" />
+                      <div className="flex flex-col">
+                        <span className="font-medium">{org.display_name}</span>
+                        {!compact && org.description && (
+                          <span className="text-xs text-muted-foreground truncate max-w-40">
+                            {org.description}
+                          </span>
+                        )}
+                      </div>
+                    </div>
+                  </SelectItem>
+                ))}
+              </SelectGroup>
+              {showEvents && events && events.length > 0 && <SelectSeparator />}
+            </>
+          )}
+          
+          {/* Events Section */}
+          {showEvents && events && events.length > 0 && (
+            <SelectGroup>
+              <SelectLabel>Events</SelectLabel>
+              {events.map((event) => (
+                <SelectItem 
+                  key={event.event_id || event.id} 
+                  value={`event:${event.event_id || event.id}`}
+                >
+                  <div className="flex items-center gap-2">
+                    <Calendar className="size-4" />
+                    <div className="flex flex-col">
+                      <span className="font-medium">{event.event_name}</span>
+                      {!compact && event.event_date && (
+                        <span className="text-xs text-muted-foreground">
+                          {new Date(event.event_date).toLocaleDateString()}
+                        </span>
+                      )}
+                    </div>
+                  </div>
+                </SelectItem>
+              ))}
+            </SelectGroup>
+          )}
+        </SelectContent>
+      </Select>
+    </div>
+  );
+}
+

package/src/components/ContextSelector/index.ts

@@ -0,0 +1,3 @@
+export { ContextSelector } from './ContextSelector';
+export type { ContextSelectorProps } from './ContextSelector';
+

package/src/components/DataTable/DataTable.tsx

@@ -462,6 +462,38 @@ export interface DataTableProps<TData extends DataRecord> {
  * 
  * Features are configured through the unified `features` prop for maximum flexibility.
  */
+/**
+ * Enhanced DataTable component with performance optimizations and comprehensive features.
+ * 
+ * This is the main entry point for the DataTable component. It wraps DataTableCore
+ * and provides feature normalization and validation.
+ * 
+ * @template TData - The type of data records in the table
+ * @param props - DataTable configuration including data, columns, features, and RBAC
+ * @returns The rendered DataTable component
+ * 
+ * @example
+ * ```tsx
+ * <DataTable
+ *   data={users}
+ *   columns={userColumns}
+ *   rbac={{ pageId: 'user-management' }}
+ *   features={{
+ *     search: true,
+ *     pagination: true,
+ *     sorting: true
+ *   }}
+ * />
+ * ```
+ */
+/**
+ * Comprehensive, feature-rich data table component built on top of TanStack Table.
+ * Provides advanced data management capabilities with a clean, accessible interface.
+ * 
+ * @template TData - The type of data records in the table
+ * @param props - DataTable configuration and props
+ * @returns The rendered DataTable component
+ */
 export function DataTable<TData extends DataRecord>(props: DataTableProps<TData>) {
   const logger = createLogger('DataTable');
   const { features, ...rest } = props;
@@ -485,11 +517,13 @@ export function DataTable<TData extends DataRecord>(props: DataTableProps<TData>
 // ============================================================================
 
 /**
- * DataTable component with React.memo for performance optimization
+ * DataTable component export
+ * 
+ * Note: React.memo removed for React 19 compatibility. React 19's automatic
+ * memoization (React Compiler) handles optimization automatically, and manual
+ * memoization can interfere with prop updates in React 19.
  */
-const DataTableComponent = React.memo(DataTable) as typeof DataTable;
-
-export { DataTableComponent as default };
+export { DataTable as default };
 
 // Re-export for convenience
 export { DataTable as EnhancedDataTable };

package/src/components/DataTable/__tests__/DataTableCore.test-setup.ts

@@ -1,3 +1,4 @@
+/// <reference types="vitest/globals" />
 /**
  * @file DataTableCore Test Setup
  * @package @jmruthers/pace-core
@@ -7,8 +8,6 @@
  * Shared test setup and mocks for DataTableCore component tests.
  * This file is imported by all DataTableCore test files to ensure consistent mocking.
  */
-
-import { vi } from 'vitest';
 import React from 'react';
 
 // Mock the RBAC hooks
@@ -132,7 +131,7 @@ vi.mock('../hooks/useColumnOrderPersistence', () => ({
 // Mock the column factory
 vi.mock('../core/ColumnFactory', () => ({
   ColumnFactory: {
-    createColumns: vi.fn((columns) => columns),
+    createColumns: vi.fn((columns: unknown) => columns),
     createActionColumn: vi.fn(() => ({
       id: 'actions',
       header: 'Actions',
@@ -144,11 +143,11 @@ vi.mock('../core/ColumnFactory', () => ({
 // Mock the hierarchical utilities
 vi.mock('../utils/hierarchicalUtils', () => ({
   validateHierarchicalData: vi.fn(() => true),
-  sortHierarchicalData: vi.fn((data) => data),
+  sortHierarchicalData: vi.fn((data: unknown) => data),
 }));
 
 vi.mock('../utils/hierarchicalSorting', () => ({
-  sortHierarchicalData: vi.fn((data) => data),
+  sortHierarchicalData: vi.fn((data: unknown) => data),
 }));
 
 // Create a mock implementation that can be overridden
@@ -184,7 +183,7 @@ vi.mock('../hooks/useDataTablePermissions', () => ({
 }));
 
 vi.mock('../hooks/useTableColumns', () => ({
-  useTableColumns: vi.fn(({ columns }) => ({
+  useTableColumns: vi.fn(({ columns }: { columns?: unknown[] }) => ({
     enhancedColumns: columns || []
   }))
 }));