@jmruthers/pace-core 0.2.4

package/src/components/OrganisationSelector/OrganisationSelector.tsx

@@ -0,0 +1,304 @@
+/**
+ * @file Organisation Selector Component
+ * @package @jmruthers/pace-core
+ * @module Components/OrganisationSelector
+ * @since 0.4.0
+ *
+ * A secure organisation selector component that allows users to switch between organisations
+ * they have access to. Includes role display and security validation.
+ *
+ * Features:
+ * - Secure organisation switching with validation
+ * - Role display for each organisation
+ * - Real-time organisation validation
+ * - Accessible dropdown interface
+ * - Error handling for security violations
+ * - Loading states and feedback
+ * - Integration with OrganisationProvider
+ *
+ * @example
+ * ```tsx
+ * // Basic organisation selector
+ * <OrganisationSelector 
+ *   onOrganisationChange={(org) => console.log('Switched to:', org.display_name)}
+ * />
+ * 
+ * // Compact version for header
+ * <OrganisationSelector 
+ *   className="w-48" 
+ *   compact={true}
+ *   showRole={true}
+ * />
+ * 
+ * // With custom placeholder
+ * <OrganisationSelector 
+ *   placeholder="Choose organisation..."
+ *   showNoOrganisationsMessage={true}
+ * />
+ * ```
+ *
+ * @accessibility
+ * - WCAG 2.1 AA compliant
+ * - Keyboard navigation support
+ * - Screen reader friendly
+ * - Focus management
+ * - ARIA labels and descriptions
+ * - High contrast support
+ *
+ * @security
+ * - Validates user access to organisations
+ * - Prevents switching to unauthorised organisations
+ * - Error handling for security violations
+ * - Real-time access validation
+ * - Secure organisation data handling
+ */
+
+import React, { useState, useCallback } from 'react';
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../Select';
+import { Alert, AlertDescription } from '../Alert/Alert';
+import { Button } from '../Button/Button';
+import { LoadingSpinner } from '../LoadingSpinner/LoadingSpinner';
+import { RefreshCw, AlertCircle, Building2, Shield } from 'lucide-react';
+import { useOrganisations } from '../../providers/OrganisationProvider';
+import type { Organisation } from '../../types/organisation';
+
+export interface OrganisationSelectorProps {
+  /** Placeholder text for the dropdown */
+  placeholder?: string;
+  /** Additional CSS classes */
+  className?: string;
+  /** Callback fired when organisation changes, providing full organisation object */
+  onOrganisationChange?: (org: Organisation) => void;
+  /** Show friendly message when no organisations available */
+  showNoOrganisationsMessage?: boolean;
+  /** Show retry button on errors */
+  showRetryButton?: boolean;
+  /** Show user's role in each organisation */
+  showRole?: boolean;
+  /** Compact display mode */
+  compact?: boolean;
+  /** Disabled state */
+  disabled?: boolean;
+}
+
+/**
+ * OrganisationSelector component for secure organisation switching
+ * 
+ * This component provides secure organisation selection with:
+ * - User membership validation
+ * - Role-based access display
+ * - Security error handling
+ * - Real-time organisation switching
+ * - Accessible interface design
+ * 
+ * Security: Only shows organisations the user has valid access to
+ */
+export function OrganisationSelector({
+  placeholder = "Select organisation",
+  className,
+  onOrganisationChange,
+  showNoOrganisationsMessage = true,
+  showRetryButton = true,
+  showRole = false,
+  compact = false,
+  disabled = false
+}: OrganisationSelectorProps) {
+  const [isLoading, setIsLoading] = useState(false);
+  const [switchError, setSwitchError] = useState<string | null>(null);
+  
+  const { 
+    organisations, 
+    selectedOrganisation, 
+    isLoading: orgLoading,
+    error: orgError,
+    switchOrganisation,
+    getUserRole,
+    validateOrganisationAccess,
+    refreshOrganisations
+  } = useOrganisations();
+
+
+  const handleOrganisationChange = useCallback(async (orgId: string) => {
+    if (disabled || isLoading) return;
+    
+    setSwitchError(null);
+    setIsLoading(true);
+    
+    try {
+      // Validate access before attempting switch
+      if (!validateOrganisationAccess(orgId)) {
+        throw new Error('You do not have access to this organisation');
+      }
+      
+      await switchOrganisation(orgId);
+      
+      const newOrganisation = organisations.find(org => org.id === orgId);
+      if (newOrganisation && onOrganisationChange) {
+        onOrganisationChange(newOrganisation);
+      }
+      
+      console.log("[OrganisationSelector] Successfully switched to organisation:", orgId);
+    } catch (error) {
+      console.error("[OrganisationSelector] Failed to switch organisation:", error);
+      setSwitchError(error instanceof Error ? error.message : 'Failed to switch organisation');
+    } finally {
+      setIsLoading(false);
+    }
+  }, [
+    disabled, 
+    isLoading, 
+    validateOrganisationAccess, 
+    switchOrganisation, 
+    organisations, 
+    onOrganisationChange
+  ]);
+
+  const handleRetry = useCallback(async () => {
+    setIsLoading(true);
+    setSwitchError(null);
+    try {
+      await refreshOrganisations();
+    } catch (error) {
+      console.error("[OrganisationSelector] Failed to refresh organisations:", error);
+      setSwitchError('Failed to refresh organisations');
+    } finally {
+      setIsLoading(false);
+    }
+  }, [refreshOrganisations]);
+
+  // Loading state
+  if (orgLoading) {
+    return (
+      <div className={`flex items-center gap-2 ${className}`}>
+        <LoadingSpinner size="sm" />
+        <span className="text-sm text-muted-foreground">
+          {compact ? "Loading..." : "Loading organisations..."}
+        </span>
+      </div>
+    );
+  }
+
+  // Error state
+  if (orgError) {
+    return (
+      <div className={`space-y-2 ${className}`}>
+        <Alert variant="destructive">
+          <AlertCircle className="h-4 w-4" />
+          <AlertDescription>
+            Failed to load organisations: {orgError.message}
+          </AlertDescription>
+        </Alert>
+        {showRetryButton && (
+          <Button 
+            variant="outline" 
+            size="sm" 
+            onClick={handleRetry}
+            disabled={isLoading}
+            className="w-full"
+          >
+            <RefreshCw className={`h-4 w-4 mr-2 ${isLoading ? 'animate-spin' : ''}`} />
+            Retry
+          </Button>
+        )}
+      </div>
+    );
+  }
+
+  // No organisations available
+  if (organisations.length === 0) {
+    if (showNoOrganisationsMessage) {
+      return (
+        <div className={`space-y-2 ${className}`}>
+          <Alert>
+            <Building2 className="h-4 w-4" />
+            <AlertDescription>
+              No organisations available. Please contact your administrator to be added to an organisation.
+            </AlertDescription>
+          </Alert>
+          {showRetryButton && (
+            <Button 
+              variant="outline" 
+              size="sm" 
+              onClick={handleRetry}
+              disabled={isLoading}
+              className="w-full"
+            >
+              <RefreshCw className={`h-4 w-4 mr-2 ${isLoading ? 'animate-spin' : ''}`} />
+              Check Again
+            </Button>
+          )}
+        </div>
+      );
+    }
+    return null;
+  }
+
+  // Switch error display
+  const switchErrorDisplay = switchError && (
+    <Alert variant="destructive" className="mt-2">
+      <AlertCircle className="h-4 w-4" />
+      <AlertDescription>{switchError}</AlertDescription>
+    </Alert>
+  );
+
+  // Normal selector state
+  return (
+    <div className={`space-y-2 ${className}`}>
+      <Select 
+        value={selectedOrganisation.id}
+        onValueChange={handleOrganisationChange}
+        disabled={disabled || isLoading}
+      >
+        <SelectTrigger className={`${isLoading ? 'opacity-50' : ''}`}>
+          <div className="flex items-center gap-2">
+            {isLoading ? (
+              <LoadingSpinner size="sm" />
+            ) : (
+              <Building2 className="h-4 w-4 text-muted-foreground" />
+            )}
+            <SelectValue placeholder={placeholder} />
+          </div>
+        </SelectTrigger>
+        <SelectContent>
+          {organisations.map((org) => {
+            const userRole = getUserRole(org.id);
+            const hasAccess = validateOrganisationAccess(org.id);
+            
+            return (
+              <SelectItem 
+                key={org.id} 
+                value={org.id}
+                disabled={!hasAccess}
+                className={!hasAccess ? 'opacity-50' : ''}
+              >
+                <div className="flex items-center justify-between w-full">
+                  <div className="flex items-center gap-2">
+                    <Building2 className="h-4 w-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>
+                  {showRole && (
+                    <div className="flex items-center gap-1 ml-4">
+                      <Shield className="h-3 w-3 text-muted-foreground" />
+                      <span className="text-xs text-muted-foreground capitalize">
+                        {userRole.replace('_', ' ')}
+                      </span>
+                    </div>
+                  )}
+                </div>
+              </SelectItem>
+            );
+          })}
+        </SelectContent>
+      </Select>
+      
+      {switchErrorDisplay}
+    </div>
+  );
+}