npm package: @ruc-lib/accordion
Description: This library provides a flexible and customizable accordion component for your Angular applications, allowing users to efficiently organize and display content in collapsible panels.
Latest version: 4.0.0

# ruclib-accordion

This library provides a flexible and customizable accordion component for your Angular applications, allowing users to efficiently organize and display content in collapsible panels.

## Features

- **Dynamic Panels**: Create any number of accordion panels, each with its own header and content.
- **Multiple Expansion**: Configure the accordion to allow multiple panels to be expanded simultaneously.
- **Customizable Appearance**:
  - Apply custom colors to panel titles, headers, and borders.
  - Use text, an icon, or an image for the panel title.
  - Customize the toggle icon and its position (before or after the title).
- **Flexible Content**: Panel content can be simple text, HTML, or even other Angular components like forms and data grids.
- **Expansion Direction**: Control the direction in which panels expand (vertically or horizontally).
- **Lazy Loading**: Lazily load panel content to improve performance.
- **Accessibility**: Panels can be enabled, disabled, and their initial expanded state can be configured.

## Installation Guide

### Install the Entire Library
```bash
npm install @uxpractice/ruc-lib
```

### Install Individual Component

If you only need the Accordion component:

**For Angular 15:**
```bash
npm install @ruc-lib/accordion@3.2.0 @angular/material@^15.0.0 @angular/cdk@^15.0.0
```

**For Angular 16:**
```bash
npm install @ruc-lib/accordion@3.2.0 @angular/material@^16.0.0 @angular/cdk@^16.0.0
```

**For Angular 17:**
```bash
npm install @ruc-lib/accordion@4.0.0 @angular/material@^17.0.0 @angular/cdk@^17.0.0
```

**For Angular 18:**
```bash
npm install @ruc-lib/accordion@4.0.0 @angular/material@^18.0.0 @angular/cdk@^18.0.0
```

**For Angular 19:**
```bash
npm install @ruc-lib/accordion@4.0.0 @angular/material@^19.0.0 @angular/cdk@^19.0.0
```

**For Angular 20:**
```bash
npm install @ruc-lib/accordion@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/accordion@^3.2.0 @angular/material@^15.0.0 @angular/cdk@^15.0.0` |
| 16.x.x          | 3.2.0              | `npm install @ruc-lib/accordion@^3.2.0 @angular/material@^16.0.0 @angular/cdk@^16.0.0` |
| 17.x.x          | 4.0.0              | `npm install @ruc-lib/accordion@^4.0.0 @angular/material@^17.0.0 @angular/cdk@^17.0.0` |
| 18.x.x          | 4.0.0              | `npm install @ruc-lib/accordion@^4.0.0 @angular/material@^18.0.0 @angular/cdk@^18.0.0` |
| 19.x.x          | 4.0.0              | `npm install @ruc-lib/accordion@^4.0.0 @angular/material@^19.0.0 @angular/cdk@^19.0.0` |
| 20.x.x          | 4.0.0              | `npm install @ruc-lib/accordion@^4.0.0`                                                |


## Usage

### 1. Import the Component
In your Angular component file (e.g., `app.component.ts`), import the `RuclibAccordionComponent`:

```typescript
import { Component } from '@angular/core';

// For Complete Library
import { RuclibAccordionComponent } from '@uxpractice/ruc-lib/accordion';

// For Individual Package
import { RuclibAccordionComponent } from '@ruc-lib/accordion';

@Component({
  selector: 'app-root',
  imports: [RuclibAccordionComponent],
  templateUrl: './app.component.html',
})
export class AppComponent {
  // Component code here
}
```

### 2. Use the Component
In your component's template, use the `<uxp-ruclib-accordion>` selector:

```html
<uxp-ruclib-accordion
    [rucInputData]="inputObjectAccordion"
    (rucEvent)="passEvent($event)"
    [customTheme]="customTheme">
</uxp-ruclib-accordion>
```

## API Reference

### Component Inputs

| Input          | Type                     | Description                                         |
|----------------|--------------------------|-----------------------------------------------------|
| `rucInputData` | `AccordionInterface` | The main configuration object for the accordion.    |
| `customTheme`  | `string`                 | An optional CSS class for custom theming.           |

### Component Outputs

| Output     | Type  | Description                                  |
|------------|-------|----------------------------------------------|
| `rucEvent` | `any` | Emits events from the accordion panels.      |

### `rucInputData` (`AccordionInterface`)
This is the main configuration object for the Accordion component.

| Property             | Type                        | Description                                                                                             |
|----------------------|-----------------------------|---------------------------------------------------------------------------------------------------------|
| `isExpandMultiPanel` | `boolean`                   | If `true`, multiple panels can be expanded at the same time. Default is `true`.                         |
| `displayMode`        | `MatAccordionDisplayMode`   | The display mode of the accordion. Can be `'default'` or `'flat'`. Default is `'default'`.              |
| `enableExpandAllBtn` | `boolean`                   | If `true`, shows a button to expand all panels. Default is `false`.                                     |
| `expandAllBtnName`   | `string`                    | Custom text for the "Expand All" button.                                                                |
| `enableCollapseAllBtn`| `boolean`                  | If `true`, shows a button to collapse all panels. Default is `false`.                                   |
| `collapseAllBtnName` | `string`                    | Custom text for the "Collapse All" button.                                                              |
| `allBtnPosition`     | `string`                    | Position of the "Expand/Collapse All" buttons. Can be `'start'`, `'center'`, or `'end'`.                |
| `panelContent`       | `PanelContentInterface[]`          | An array of panel configuration objects.                                                                |

### `panelContent` Item
This object defines the configuration for each panel in the accordion.

| Property                       | Type                               | Description                                                                                             |
|--------------------------------|------------------------------------|---------------------------------------------------------------------------------------------------------|
| `panelId`                      | `number`                           | A unique identifier for the panel.                                                                      |
| `panelTitle`                   | `string`                           | The title text displayed in the panel header.                                                           |
| `isPanelTitleImage`            | `boolean`                          | If `true`, an image is used as the panel title.                                                         |
| `panelTitleImagePath`          | `string`                           | The path to the image for the panel title.                                                              |
| `isPanelTitleIcon`             | `boolean`                          | If `true`, an icon is used as the panel title.                                                          |
| `panelTitleIconName`           | `string`                           | The name of the Material Icon for the panel title.                                                      |
| `panelDescription`             | `string`                           | A description displayed below the panel title.                                                          |
| `panelContentType`             | `string`                           | The type of content in the panel. Can be `'text'`, `'html'`, `'datagrid'`, etc. Default is `'text'`.     |
| `panelContentData`             | `object`                           | An object containing the data for the panel content.                                                    |
| `isDisabled`                   | `boolean`                          | If `true`, the panel is disabled and cannot be interacted with.                                         |
| `isExpanded`                   | `boolean`                          | The initial expanded state of the panel.                                                                |
| `isCustomToggleIcon`           | `boolean`                          | If `true`, a custom toggle icon is used.                                                                |
| `toggleIconName`               | `string`                           | The name of the custom Material Icon for the toggle indicator.                                          |
| `isHideToggleIcon`             | `boolean`                          | If `true`, the toggle indicator icon is hidden.                                                         |
| `toggleIconPosition`           | `MatAccordionTogglePosition`       | The position of the toggle icon. Can be `'before'` or `'after'`. Default is `'after'`.                  |
| `panelExpandDirection`         | `string`                           | The direction in which the panel expands. Can be `'vertical'` or `'horizontal'`.                        |
| `headerButtonColor`            | `string`                           | Custom color for the panel header.                                                                      |
| `panelHeaderButtonColor`       | `string`                           | Custom color for the panel header button.                                                               |
| `isToggleHeaderButtonColor`    | `boolean`                          | If `true`, enables a different color for the header when the panel is expanded.                         |
| `togglePanelHeaderButtonColor` | `string`                           | The color of the header when the panel is expanded.                                                     |
| `panelHeaderButtonBorder`      | `string`                           | Custom border for the panel header button.                                                              |
| `isToggleHeaderButtonBorder`   | `boolean`                          | If `true`, enables a different border for the header when the panel is expanded.                        |
| `headerButtonBorder`           | `string`                           | Custom border for the header.                                                                           |
| `togglePanelHeaderButtonBorder`| `string`                           | The border of the header when the panel is expanded.                                                    |

## Example Configuration

Here's an example of how to configure the Accordion component in your component's TypeScript file.

```typescript
import { Component } from '@angular/core';

// For Complete Library
import { RuclibAccordionModule, AccordionInterface, PanelContentInterface } from '@uxpractice/ruc-lib/accordion';

// For Individual package
import { RuclibAccordionModule, AccordionInterface, PanelContentInterface } from '@ruc-lib/accordion';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
})
export class AppComponent {
  customTheme = 'ruc-custom-theme';

  inputObjectAccordion: AccordionInterface = {
    isExpandMultiPanel: true,
    displayMode: 'default',
    panelContent: [
        {
            panelId: 1,
            panelTitle: 'Personal Information',
            isPanelTitleImage: false,
            panelTitleImagePath: '',
            isPanelTitleIcon: true,
            panelTitleIconName: 'account_circle',
            panelDescription: 'View and edit your personal details',
            panelContentType: 'text',
            panelContentData: {
                dataSource: 'Here you can add a form or other components to manage personal information.',
                inputObjectDataGrid: ''
            },
            isDisabled: false,
            isExpanded: true,
            isCustomToggleIcon: false,
            toggleIconName: '',
            isHideToggleIcon: false,
            toggleIconPosition: 'after',
            panelExpandDirection: 'vertical',
            headerButtonColor: '',
            panelHeaderButtonColor: '',
            isToggleHeaderButtonColor: false,
            togglePanelHeaderButtonColor: '',
            panelHeaderButtonBorder: '',
            isToggleHeaderButtonBorder: false,
            headerButtonBorder: '',
            togglePanelHeaderButtonBorder: '',
        }
    ]
  };

    passEvent(event: any) {
    console.log('Accordion Event:', event);
  }
}
```

> ⚠️ **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 Accordion component. If you have any feedback or suggestions, please let us know!