npm package: @ruc-lib/carousel
Description: This library provides a flexible and customizable carousel component for your Angular applications. Users can integrate the carousel component using Angular services or selectors with ease. Below are the features, usage instructions, and integration detai
Latest version: 4.0.0

# ruclib-carousel

This library provides a flexible and customizable carousel component for your Angular applications. Users can integrate the carousel component using Angular services or selectors with ease. Below are the features, usage instructions, and integration details

## Installation Guide

To use the Carousel component, you can install the entire RUC library or just this specific component.

### Install the Entire Library
```bash
npm install @uxpractice/ruc-lib
```

### Install Individual Component

If you only need the Carousel component:

**For Angular 15:**
```bash
npm install @ruc-lib/carousel@3.2.0 @angular/material@^15.0.0 @angular/cdk@^15.0.0
```

**For Angular 16:**
```bash
npm install @ruc-lib/carousel@3.2.0 @angular/material@^16.0.0 @angular/cdk@^16.0.0
```

**For Angular 17:**
```bash
npm install @ruc-lib/carousel@4.0.0 @angular/material@^17.0.0 @angular/cdk@^17.0.0
```

**For Angular 18:**
```bash
npm install @ruc-lib/carousel@4.0.0 @angular/material@^18.0.0 @angular/cdk@^18.0.0
```

**For Angular 19:**
```bash
npm install @ruc-lib/carousel@4.0.0 @angular/material@^19.0.0 @angular/cdk@^19.0.0
```

**For Angular 20:**
```bash
npm install @ruc-lib/carousel@4.0.0
```

> **Note:** When installing in Angular 15-19 apps, you must specify the matching `@angular/material` and `@angular/cdk` versions to avoid peer dependency conflicts. Angular 20 will automatically use the correct versions.

### 📦 Version Compatibility

| Angular Version | Compatible Version | Installation Command                                                                   |
|-----------------|--------------------|----------------------------------------------------------------------------------------|
| 15.x.x          | 3.2.0              | `npm install @ruc-lib/carousel@^3.2.0 @angular/material@^15.0.0 @angular/cdk@^15.0.0` |
| 16.x.x          | 3.2.0              | `npm install @ruc-lib/carousel@^3.2.0 @angular/material@^16.0.0 @angular/cdk@^16.0.0` |
| 17.x.x          | 4.0.0              | `npm install @ruc-lib/carousel@^4.0.0 @angular/material@^17.0.0 @angular/cdk@^17.0.0` |
| 18.x.x          | 4.0.0              | `npm install @ruc-lib/carousel@^4.0.0 @angular/material@^18.0.0 @angular/cdk@^18.0.0` |
| 19.x.x          | 4.0.0              | `npm install @ruc-lib/carousel@^4.0.0 @angular/material@^19.0.0 @angular/cdk@^19.0.0` |
| 20.x.x          | 4.0.0              | `npm install @ruc-lib/carousel@^4.0.0`                                                |



## Usage

### 1. Import the Component
In your Angular component file (e.g., `app.component.ts`), import the `RuclibCarouselComponent`:

```typescript
import { Component } from '@angular/core';

// For Complete Library
import { RuclibCarouselComponent } from '@uxpractice/ruc-lib/carousel';

// For Individual Package
import { RuclibCarouselComponent } from '@ruc-lib/carousel';

@Component({
  selector: 'app-root',
  imports: [RuclibCarouselComponent],
  templateUrl: './app.component.html',
})
export class AppComponent {
  // Component code here
}
```
### 2. Use the Component
In your component's template, use the `<uxp-ruclib-carousel>` selector and pass the configuration object to the `rucInputData` input.

```html
<uxp-ruclib-carousel [customTheme]="customTheme" [rucInputData]="inputObjectDataCarousel"></uxp-ruclib-carousel>
```

## API Reference

### Component Inputs


| Input          | Type               | Description                                  |
|----------------|--------------------|----------------------------------------------|
| `rucInputData` | `CarouselConfig` | The main configuration object for the component. |
| `customTheme`  | `string`           | An optional CSS class for custom theming.    |

### `CarouselConfig`
This is the main configuration object for the Carousel.

| Property                    | Type                                             | Description                                                                                             |
|-----------------------------|--------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| `items`                       | `CarouselItem[]`                                         | Items to display in the carousel                                                        |
| `direction`                       | `'horizontal' \| 'vertical'`                                         |  Direction of the carousel scroll                                                      |
| `autoScroll`               | `boolean`                     | Auto Scroll of the Carousel                                                                    |
| `autoScrollInterval`                 | `number`                                        | Interval for Auto Scroll                                                       |
| `prevIcon`                  | `string'` | Previous Icon                                     |
| `nextIcon` | `string'` | Next Icon                                                 |
| `templateStyle`        | `'rectangle' \| 'circle'`                            | Template of the Carousel                                                                  |
| `fontSizes`        | `string`                                        | User can provide font sizes of header, body and  footer                                                               |
| `imageDimensions`                | `string`                               | User can provide image dimesnions- width, height and radius                                   |

### `CarouselItem`
This object defines the configuration for each  carousel item within the Carousel Component.

| Property  | Type                               | Description                                                              |
|-----------|------------------------------------|--------------------------------------------------------------------------|
| `image`   | `string`                           | The image to be displayed on the carousel        |
| `header`   | `string`                           | Header title of the Carousel Item |
| `body`   | `string`                           | The content body of the Carousel Item                                               |
| `footer`    | `string`                | The footer content |

## Example Configuration

Here's an example of how to configure the Carousel in your component's TypeScript file.

```typescript
import { Component } from '@angular/core';

// For Complete Library
import { CarouselConfig } from '@uxpractice/ruc-lib/carousel';

// For Individual Package
import { CarouselConfig } from '@ruc-lib/carousel';


@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
})
export class AppComponent {
  caraouselConfig: CarouselConfig = {
  items: [
  {
    image: 'https://images.unsplash.com/photo-1746184564778-87d9a18ca114?q=80&w=1472&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D',
    header: 'First Slide',
    body: 'This is the first slide body',
    footer: 'Footer 1'
  },
  {
    image: 'https://images.unsplash.com/photo-1746286891817-bde8cce15a7c?q=80&w=1374&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D',
    header: 'Second Slide',
    body: 'This is the second slide body', 
    footer: 'Footer 2'
  },
  {
    image: 'https://images.unsplash.com/photo-1746286891817-bde8cce15a7c?q=80&w=1374&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D',
    header: 'Third Slide',
    body: 'This is the third slide body',
    footer: 'Footer 3'
  },
  {
    image: 'https://images.unsplash.com/photo-1746286891817-bde8cce15a7c?q=80&w=1374&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D',
    header: 'Fourth Slide',
    body: 'This is the fourth slide body',
    footer: 'Footer 4'
  }
],
    direction: 'vertical',
    autoScroll: false,
    autoScrollInterval: 2000,
    prevIcon: 'keyboard_arrow_up',
    nextIcon: 'keyboard_arrow_down',
    templateStyle: 'rectangle',
  };
}
```

> ⚠️ **IMPORTANT: Custom Theme Usage in Angular Material**

When implementing **custom themes**, such as:

```scss
.custom-theme-1 {
  @include angular-material-theme($custom-theme);
}

// You must also include the typography mixin to ensure text styles are applied correctly as shown below:
.custom-theme-1 {
  @include angular-material-theme($custom-theme);
  @include mat.typography-level($theme-custom-typography-name, body-1);
}
```

# Contribution
Contributions are welcome! Feel free to open issues or pull requests for any enhancements or fixes.

# Acknowledgements
Thank you for choosing the Carousel Component Library. If you have any feedback or suggestions, please let us know!