# Reusable Carousel Component Documentation

## Overview

The `ReusableCarousel` component provides a consistent, sophisticated carousel design that can be used across different sections of the website. It maintains the same design pattern as the "Our Services" section but allows for customizable content, styling, and functionality.

## Key Features

- **Consistent Design Language**: Maintains the same layout, spacing, and visual hierarchy
- **Flexible Content**: Accepts any data structure with customizable card rendering
- **Responsive Navigation**: Built-in carousel controls with proper accessibility
- **Customizable Styling**: Adjustable card dimensions, spacing, and layout
- **CTA Integration**: Built-in call-to-action button with custom configuration
- **Pre-built Variants**: Ready-to-use components for common use cases

## Basic Usage

### 1. Import the Component

```tsx
import { ReusableCarousel, CarouselItem, CarouselConfig } from '../ReusableCarousel';
```

### 2. Prepare Your Data

```tsx
const myItems: CarouselItem[] = [
  {
    title: "Item Title",
    description: "Item description text",
    icon: MyIcon, // Lucide React icon component
    features: ["Feature 1", "Feature 2", "Feature 3"],
    outcome: "Expected outcome description"
  },
  // ... more items
];
```

### 3. Configure the Carousel

```tsx
const config: CarouselConfig = {
  eyebrowText: "SECTION CATEGORY",
  title: "Section Title",
  description: "Section description that appears below the title",
  ctaText: "Call to Action Text",
  ctaAction: () => navigateTo('/target-page'),
  ctaAriaLabel: "Accessible description for the CTA button"
};
```

### 4. Render the Carousel

```tsx
<ReusableCarousel 
  items={myItems}
  config={config}
/>
```

## Advanced Configuration

### Custom Card Rendering

For specialized card layouts, provide a custom renderer:

```tsx
const customRenderer = (item: CarouselItem, index: number) => (
  <Card className="custom-card-styles">
    <CardContent className="p-6">
      {/* Your custom card content */}
      <h3>{item.title}</h3>
      <p>{item.description}</p>
      {/* Add any custom fields from your CarouselItem */}
    </CardContent>
  </Card>
);

<ReusableCarousel 
  items={myItems}
  config={config}
  customCardRenderer={customRenderer}
/>
```

### Styling Customization

```tsx
<ReusableCarousel 
  items={myItems}
  config={config}
  className="my-custom-section" // Additional CSS classes
  cardWidth="80%" // Adjust card width (default: "70%")
  cardSpacing="mr-8" // Adjust spacing between cards (default: "mr-7")
  featuresTitle="Custom Features Title:" // Override features section title
  outcomesTitle="Custom Outcomes Title:" // Override outcomes section title
/>
```

## Pre-built Variants

For common use cases, use the pre-configured variants:

### Consulting Services Carousel

```tsx
import { ConsultingServicesCarousel } from '../ReusableCarousel';

<ConsultingServicesCarousel consultingServices={consultingData} />
```

### Leadership Programs Carousel

```tsx
import { LeadershipProgramsCarousel } from '../ReusableCarousel';

<LeadershipProgramsCarousel leadershipPrograms={programsData} />
```

### Expert Services Carousel

```tsx
import { ExpertServicesCarousel } from '../ReusableCarousel';

<ExpertServicesCarousel expertServices={servicesData} />
```

### Platform Features Carousel

```tsx
import { PlatformFeaturesCarousel } from '../ReusableCarousel';

<PlatformFeaturesCarousel platformFeatures={featuresData} />
```

## Data Structure Requirements

### CarouselItem Interface

```tsx
interface CarouselItem {
  title: string;           // Required: Item title
  description: string;     // Required: Item description
  icon: React.ComponentType<any>; // Required: Lucide React icon
  features?: string[];     // Optional: Array of feature bullets
  outcome?: string;        // Optional: Expected outcome text
  [key: string]: any;      // Additional custom properties
}
```

### CarouselConfig Interface

```tsx
interface CarouselConfig {
  eyebrowText: string;     // Branded tag text (e.g., "CONSULTING SERVICES")
  title: string;           // Main section title
  description: string;     // Section description
  ctaText: string;         // CTA button text
  ctaAction: () => void;   // CTA button click handler
  ctaAriaLabel: string;    // Accessibility label for CTA
}
```

## Real-World Examples

### Creating a Training Programs Carousel

```tsx
// 1. Define your data
const trainingPrograms: CarouselItem[] = [
  {
    title: "Executive Leadership Program",
    description: "Comprehensive leadership development for senior executives",
    icon: Crown,
    features: [
      "Strategic thinking development",
      "Executive presence coaching",
      "Board governance training",
      "Crisis leadership skills"
    ],
    outcome: "Enhanced executive effectiveness and organizational impact within 6 months"
  },
  // ... more programs
];

// 2. Configure the carousel
const trainingConfig: CarouselConfig = {
  eyebrowText: "TRAINING PROGRAMS",
  title: "Leadership Training Excellence",
  description: "Comprehensive training programs designed to develop leadership capabilities at every organizational level.",
  ctaText: "Explore Training Programs",
  ctaAction: () => navigateTo('/training'),
  ctaAriaLabel: "Explore our leadership training programs"
};

// 3. Use in your component
export function TrainingSection() {
  return (
    <section className="py-24" style={{ backgroundColor: '#FFFFFF' }}>
      <div className="container mx-auto section-margin-x">
        <ReusableCarousel 
          items={trainingPrograms}
          config={trainingConfig}
          featuresTitle="Program Highlights:"
          outcomesTitle="Program Results:"
        />
      </div>
    </section>
  );
}
```

### Creating a Technology Solutions Carousel

```tsx
const techSolutions: CarouselItem[] = [
  {
    title: "Learning Management System",
    description: "Advanced LMS platform for enterprise learning",
    icon: Monitor,
    features: [
      "Cloud-based infrastructure",
      "Mobile-responsive design",
      "Advanced analytics",
      "Integration capabilities"
    ],
    outcome: "Improved learning engagement and completion rates",
    // Custom properties for this use case
    deployment: "Cloud or On-premise",
    integration: "API-first architecture"
  },
  // ... more solutions
];

// Custom renderer for technology-specific cards
const techRenderer = (item: CarouselItem, index: number) => (
  <Card className="border border-gray-200 h-full overflow-hidden">
    <CardContent className="p-6">
      <div className="flex items-center gap-4 mb-4">
        <div className="w-14 h-14 rounded-xl bg-blue-100 flex items-center justify-center">
          {React.createElement(item.icon, { className: "w-7 h-7 text-blue-600" })}
        </div>
        <h3 className="text-h4 text-black">{item.title}</h3>
      </div>
      
      <p className="text-body text-muted mb-6">{item.description}</p>
      
      {/* Custom technology info */}
      <div className="bg-gray-50 rounded-lg p-4 mb-6">
        <div className="grid grid-cols-2 gap-4">
          <div>
            <span className="text-small font-medium text-black">Deployment:</span>
            <span className="text-small text-muted ml-2">{item.deployment}</span>
          </div>
          <div>
            <span className="text-small font-medium text-black">Integration:</span>
            <span className="text-small text-muted ml-2">{item.integration}</span>
          </div>
        </div>
      </div>
      
      {/* Standard features section */}
      {item.features && (
        <div className="mb-6">
          <h4 className="text-subhead text-black mb-4">Key Features:</h4>
          <div className="space-y-2">
            {item.features.map((feature: string, idx: number) => (
              <div key={idx} className="flex items-center gap-2">
                <CheckCircle className="w-4 h-4 text-blue-600" />
                <span className="text-small text-muted">{feature}</span>
              </div>
            ))}
          </div>
        </div>
      )}
    </CardContent>
  </Card>
);

// Usage with custom renderer
<ReusableCarousel 
  items={techSolutions}
  config={techConfig}
  customCardRenderer={techRenderer}
  cardWidth="75%"
  cardSpacing="mr-6"
/>
```

## Design Guidelines

### When to Use

- **Multiple Related Items**: When you have 3+ related items to showcase
- **Detailed Information**: When each item needs substantial description and features
- **Call-to-Action Flow**: When the section should lead to a specific action
- **Consistent Branding**: When you want to maintain the established design language

### When NOT to Use

- **Simple Lists**: For basic lists without detailed descriptions
- **Static Content**: For content that doesn't benefit from carousel navigation
- **Single Items**: For individual content pieces
- **Grid Layouts**: When users need to see all items simultaneously

### Best Practices

1. **Content Length**: Keep titles concise (2-6 words), descriptions to 1-2 sentences
2. **Feature Lists**: Limit to 4-6 features per item for optimal readability
3. **Icons**: Use consistent icon style from Lucide React library
4. **Outcomes**: Make outcomes specific and measurable when possible
5. **CTA Alignment**: Ensure CTA leads to relevant, valuable content

## Accessibility Features

- **Keyboard Navigation**: Full keyboard support for carousel controls
- **ARIA Labels**: Proper accessibility labels for all interactive elements
- **Focus Management**: Clear focus indicators and logical tab order
- **Screen Readers**: Semantic HTML structure for assistive technologies

## Browser Support

- **Modern Browsers**: Full support in Chrome, Firefox, Safari, Edge
- **Responsive Design**: Optimized for all device sizes
- **Performance**: Optimized animations and minimal re-renders
- **Fallbacks**: Graceful degradation for older browsers

## Contributing

When extending the reusable carousel:

1. **Maintain Consistency**: Keep the established design patterns
2. **Test Accessibility**: Ensure all new features are accessible
3. **Document Changes**: Update this documentation for new features
4. **Performance**: Consider performance impact of customizations

This reusable carousel system allows you to quickly implement consistent, professional carousels across any section while maintaining design cohesion and user experience standards.