npm package: @ruc-lib/timeline
Description: A timeline visualizes a series of chained events. It's a way to display information, like data tables, in a format that's easy to scan, allowing users to identify patterns and insights.
Latest version: 4.0.0

# ruclib-timeline

A timeline visualizes a series of chained events. It's a way to display information, like data tables, in a format that's easy to scan, allowing users to identify patterns and insights.

# Installation guide

To use the timeline 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 Timeline component:

**For Angular 15:**
```bash
npm install @ruc-lib/timeline@3.2.0 @angular/material@^15.0.0 @angular/cdk@^15.0.0
```

**For Angular 16:**
```bash
npm install @ruc-lib/timeline@3.2.0 @angular/material@^16.0.0 @angular/cdk@^16.0.0
```

**For Angular 17:**
```bash
npm install @ruc-lib/timeline@4.0.0 @angular/material@^17.0.0 @angular/cdk@^17.0.0
```

**For Angular 18:**
```bash
npm install @ruc-lib/timeline@4.0.0 @angular/material@^18.0.0 @angular/cdk@^18.0.0
```

**For Angular 19:**
```bash
npm install @ruc-lib/timeline@4.0.0 @angular/material@^19.0.0 @angular/cdk@^19.0.0
```

**For Angular 20:**
```bash
npm install @ruc-lib/timeline@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
 
Please ensure you install the correct version of `@ruc-lib/timeline` based on your Angular version.
 
| Angular Version    | Compatible `@ruc-lib/timeline` Version     |
|--------------------|---------------------------------------------|
| 15.x.x             | `npm install @ruc-lib/timeline@^3.2.0`     |
| 16.x.x             | `npm install @ruc-lib/timeline@^3.2.0`     |
| 17.x.x             | `npm install @ruc-lib/timeline@^4.0.0`     |
| 18.x.x             | `npm install @ruc-lib/timeline@^4.0.0`     |
| 19.x.x             | `npm install @ruc-lib/timeline@^4.0.0`     |
| 20.x.x             | `npm install @ruc-lib/timeline@^4.0.0`     |

## Usage
### 1. Import the Component
In your Angular component file (e.g., `app.component.ts`), import the `RuclibTimelineComponent`:

```typescript
import { Component } from '@angular/core';

// For Complete Library
import { RuclibTimelineComponent } from '@uxpractice/ruc-lib/timeline';

// For Individual Package
import { RuclibTimelineComponent } from '@ruc-lib/timeline';

@Component({
  selector: 'app-root',
  imports: [RuclibTimelineComponent],
  templateUrl: './app.component.html',
})
export class AppComponent {
  // Component code here
}
```

### 2. Use the Component
In your component's template, use the `<uxp-ruclib-timeline>` selector and pass the configuration object to the `rucInputData` input.

```html
<uxp-ruclib-timeline [rucInputData]="timelineDataConfig" [customTheme]="customTheme"></uxp-ruclib-timeline>
```

## API Reference

### Component Inputs

| Input           | Type                 | Description                                        |
|-----------------|----------------------|----------------------------------------------------|
| `rucInputData`  | `timelineDataConfig` | The main configuration object for the timeline.    |
| `customTheme`   | `string`             | An optional CSS class for custom theming.          |

### Component Outputs

| Output          | Type      | Description                                       |
|-----------------|-----------|---------------------------------------------------|
|-----------------|-----------| User can see the UI with timeline data.           |

### `timelineDataConfig`
This is the main configuration object for the timeline component.

| Property                  | Type                                                    | Description                                                           |
|---------------------------|---------------------------------------------------------|-----------------------------------------------------------------------|
| `layout`                  | `'vertical' \| 'horizontal'`                            | Type of timeline (e.g., 'vertical', 'horizontal').                    |
| `position`                | `'top' \| 'bottom' \| 'left' \| 'right' \| 'alternate'` | Position of the timeline (e.g., use top, bottom and horizontal when layout is horizontal and when layout is vertical use left, right and alternate). |
| `titleFontColor`          | `string`                                                | configure color of the title text.                                    |
| `subTitleFontColor`       | `string`                                                | configure color of the subtitle text.                                 |
| `titleFontSize`           | `string`                                                | configure font size of the title text.                                |
| `subTitleFontSize`        | `string`                                                | configure font size of the subtitle text.                             |
| `titleBackgroundColor`    | `string`                                                | configure background color of the title.                              |
| `subTitleBackgroundColor` | `string`                                                | configure background color of the subtitle.                           |
| `highlightColor`          | `string`                                                | configure color used to highlight an active or selected timeline item.|
| `iconColor`               | `'primary' \| 'accent' \| 'warn'`                       | configure the theme color for the timeline item icons.                |
| `maxTitleLength`          | `number`                                                | configure maximum number of characters to display for the title before truncating. |
| `maxSubTitleLength`       | `number`                                                | configure maximum number of characters to display for the subtitle before truncating. |
| `isInfo`                  | `boolean`                                               | A flag to determine if the additional info sections for title and subtitle should be displayed.| 
| `isTemplate`              | `boolean`                                               | A flag to indicate whether a custom template is being used for the timeline items instead of the default structure.|
| `data`                    |  `timelineData`                                         | The array of data objects that represent the items in the timeline.   | 

### `timelineData`
This array of objects defines the content for each step of the tour guide.

| Property            | Type              | Description                                                                                           |
|---------------------|-------------------|-------------------------------------------------------------------------------------------------------|
| `id`                | `number`          | to give the order.                                                                                    |
| `title`             | `string`          | content for main heading.                                                                             |
| `subtitle`          | `string`          | content for sub heading.                                                                              |
| `content`           | `string`          | The main content or description for the timeline item.                                                |
| `icon`              | `string`          | provide material icon for timeline.                                                                   |
| `iconAriaLabel`     | `string`          | Custom width for the popup of the current step.                                                       |
| `imageUrl`          | `string`          | provide url of image when isTemplate is true.                                                         |
| `imageAltText`      | `string`          | provide alternative text of image when isTemplate is true.                                            |
| `titleInfo`         | `string`          | provide content for titile when isInfo is true.                                                       |
| `subTitleInfo`      | `string`          | provide content for subtitile when isInfo is true.                                                    |
| `iconTitle`         | `string`          | The name of the Material icon to be displayed next to the title info text.                            |
| `iconSubTitle`      | `string`          | The name of the Material icon to be displayed next to the subtitle info text.                         |
| `titleInfoIcon`     | `string`          | The name of the Material icon for the title's info section, often used for a tooltip or popover.      |
| `subTitleInfoIcon`  | `string`          | The name of the Material icon for the subtitle's info section, often used for a tooltip or popover.   |

## Example Configuration

Here's an example of how to configure the timeline component in your component's TypeScript file.

```typescript
import { Component } from '@angular/core';

// For Complete Library
import { RucTimelineInput, RucTimelineItemData } from '@uxpractice/ruc-lib/timeline';

// For Individual package
import { RucTimelineInput, RucTimelineItemData } from '@ruc-lib/timeline';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
})
export class AppComponent {
  timelineDataConfig: RucTimelineInput = {
    layout: 'vertical',
    position: 'left',
    data: timelineData,
  };

  timelineData: RucTimelineItemData[] = [
    {
      id: 1,
      title: 'Ordered',
      subtitle: 'sub-title',
    },
    {
      id: 2,
      title: 'Processing',
      subtitle: 'sub-title',
    },
    {
      id: 3,
      title: 'Shipped',
      subtitle: 'sub-title',
    },
    {
      id: 4,
      title: 'Delivered',
      subtitle: 'sub-title',
    },
    {
      id: 5,
      title: 'Introduction',
      subtitle: "Established",
    },
  ];
}
```

> ⚠️ **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 timeline component. If you have any feedback or suggestions, please let us know!