npm package: @ruc-lib/org-chart
Description: A component for creating a org chart. There are various features like Downloading, Collapseing and Expanding available in it.
Latest version: 4.0.0

# ruclib-org-chart

A component for creating a org chart. There are various features like Downloading, Collapseing and Expanding available in it.

# Features

- User is allowed to input the data source in the correct JSON format (specific to organizational structure); otherwise, print console for that specific missing properties.
- User is allowed to select different templates for displaying the organizational chart, including various node shapes such as Portrait, Landscape, and Triangle.
- User is allowed to search by title or subtitle in the organizational chart, with the ability to toggle the visibility of the search bar based on configuration.
- User is allowed to see the searched node highlighted, while other nodes will be faded when a search is performed.
- User is allowed to access a hamburger menu (three horizontal lines) that displays a list of options such as Expand All, Collapse All, Download PNG, Download SVG, and Download PDF.
- User is allowed to expand all nodes by clicking the "Expand All" button and collapse all nodes by clicking the "Collapse All" button.
- User is allowed to download the organizational chart in PNG format by clicking the "Download PNG" button, in SVG format with the "Download SVG" option, and in PDF format using the "Download PDF" button.
- User is allowed to hover over any node in the chart, which will highlight the parent and child nodes while fading other nodes, along with displaying a tooltip containing the node's description.
- User is allowed to click the expand icon on any node to toggle between expanding or collapsing the node, provided it has child data.
- User is allowed to configure custom CSS for the organizational chart, including styling options like node color, background color.


# Installation guide

# Install complete library

`npm install @uxpractice/ruc-lib`

## Install Individual Component

If you only need the OrgChart component:

**For Angular 15:**
```bash
npm install @ruc-lib/org-chart@3.2.0 @angular/material@^15.0.0 @angular/cdk@^15.0.0
```

**For Angular 16:**
```bash
npm install @ruc-lib/org-chart@3.2.0 @angular/material@^16.0.0 @angular/cdk@^16.0.0
```

**For Angular 17:**
```bash
npm install @ruc-lib/org-chart@4.0.0 @angular/material@^17.0.0 @angular/cdk@^17.0.0
```

**For Angular 18:**
```bash
npm install @ruc-lib/org-chart@4.0.0 @angular/material@^18.0.0 @angular/cdk@^18.0.0
```

**For Angular 19:**
```bash
npm install @ruc-lib/org-chart@4.0.0 @angular/material@^19.0.0 @angular/cdk@^19.0.0
```

**For Angular 20:**
```bash
npm install @ruc-lib/org-chart@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/org-chart` based on your Angular version.
 
| Angular Version    | Compatible `@ruc-lib/org-chart` Version     |
|--------------------|---------------------------------------------|
| 15.x.x             | `npm install @ruc-lib/org-chart@^3.2.0`     |
| 16.x.x             | `npm install @ruc-lib/org-chart@^3.2.0`     |
| 17.x.x             | `npm install @ruc-lib/org-chart@^4.0.0`     |
| 18.x.x             | `npm install @ruc-lib/org-chart@^4.0.0`     |
| 19.x.x             | `npm install @ruc-lib/org-chart@^4.0.0`     |
| 20.x.x             | `npm install @ruc-lib/org-chart@^4.0.0`     |

**Note:** If you are facing any build/compile issue related to "primeng", then install "primeng" explicitly according to angular version.

# Usage

After installing the the required package successfully, we have to import the CSS in our style.scss file in following way.

`@import "../../../node_modules/primeng/resources/themes/lara-light-indigo/theme.css";`
`@import "../../../node_modules/primeng/resources/primeng.min.css";`

here path of the scss file is subject to change as per choice of the installation

for library
`@import "../node_modules/primeng/resources/themes/lara-light-indigo/theme.css";`
`@import "../node_modules/primeng/resources/primeng.min.css";`

for seperate package
`@import "../node_modules/primeng/resources/themes/lara-light-indigo/theme.css";`
`@import "../node_modules/primeng/resources/primeng.min.css";`


# import required modules

for library
`import { RuclibOrgChartModule } from '@uxpractice/ruc-lib/org-chart';`

for seperate package
`import { RuclibOrgChartModule } from '@ruc-lib/org-chart';`

# use component selector

```
<uxp-ruclib-org-chart [rucInputData]="inputOrgData" [customTheme]="customTheme"></uxp-ruclib-org-chart>
```


# Input and Output

# Inputs
rucInputData -> It is the configuration input to configure the org chart

customTheme -> It is the name of the theme.
# Output

# rucInputData (sample object)

# Detail definition of the each property can be found in type definition file.

 ```
const inputOrgData = {
    isDisplayHambergerMenu: true,
    isDisplaySearchBar : true,
    nodeTemplate: 'triangle', // portrait , triangle, landscape
    hambergerMenuList : [
      { label: 'Download pdf', 
        id: 1 
      },
      { label: 'Download png',
        id: 2 
      },
      { label: 'Download jpeg', 
        id: 3 
      },
      {
        label: 'Expand All',
        id: 4,
      },
      {
        label: 'Collapse All',
        id: 5,
      }
    ],
    greyNodeStyle : {
      backgroundColor: '#d3d3d3',
      color: '#808080',
    },
    orgData: [
      {
        label: 'ceo',
        expanded: false,
        description: 'ceo description',
        customNodeStyle: {
          backgroundColor: '#3498db',
          color: 'white',
          padding: '1.5em',
          borderRadius: '0px',
        },     
  
        data: {
          image:'https://primefaces.org/cdn/primeng/images/demo/avatar/amyelsner.png',
          name: 'Amy Elsner',
          title: 'CEO',
        },
        children: [
          {
            expanded: false,
            label: 'cmo',
            description: 'cmo description',
            customNodeStyle: {
              backgroundColor: 'rgb(152, 1, 4)',
              color: 'white',
              padding: '1.5em',
              borderRadius: '0px',
            },
            data: {
              image:
                'https://primefaces.org/cdn/primeng/images/demo/avatar/annafali.png',
              name: 'Ahaanna Fali',
              title: 'CMO',
            }
          },
          {
            expanded: false,
            label: 'CTO',
            description: 'CTO description',
            customNodeStyle: {
              backgroundColor: 'rgb(152, 1, 4)',
              color: 'white',
              padding: '1.5em',
              borderRadius: '0px',
            },
            data: {
              image:
                'https://primefaces.org/cdn/primeng/images/demo/avatar/stephenshaw.png',
              name: 'Stephen Shaw',
              title: 'CTO',
            },
            children:  [
              {
              expanded: false,
              label: 'Architect',
              description: 'CTO description',
              customNodeStyle: {
                backgroundColor:  'rgb(137, 152, 1)',
                color: 'white',
                padding: '1.5em',
                borderRadius: '0px',
              },
              data: {
                image:
                  'https://primefaces.org/cdn/primeng/images/demo/avatar/stephenshaw.png',
                name: 'Thomas Shaw',
                title: 'Architect',
              }
            },
            {
              expanded: false,
              label: 'Manager',
              description: 'CTO description',
              customNodeStyle: {
                backgroundColor:  'rgb(137, 152, 1)',
                color: 'white',
                padding: '1.5em',
                borderRadius: '0px',
              },
              data: {
                image:
                  'https://primefaces.org/cdn/primeng/images/demo/avatar/stephenshaw.png',
                name: 'Steve Shaw',
                title: 'Manager',
              }
            }],
          },
        ],
      },
    ]
  } 

```

> ⚠️ **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 Data flow Component Library. If you have any feedback or suggestions, please let us know!