npm package: @ruc-lib/data-grid
Description: Data tables display information in a grid-like format of rows and columns. They organize information in a way that's easy to scan so that users can look for patterns and insights. User can also configure below add on functionalities except for basic data 
Latest version: 4.0.0

# ruclib-data-grid

Data tables display information in a grid-like format of rows and columns. They organize information in a way that's easy to scan so that users can look for patterns and insights. User can also configure below add on functionalities except for basic data grid.

# Installation guide

To use the Data Grid 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 DataGrid component:

**For Angular 15:**
```bash
npm install @ruc-lib/data-grid@3.2.0 @angular/material@^15.0.0 @angular/cdk@^15.0.0
```

**For Angular 16:**
```bash
npm install @ruc-lib/data-grid@3.2.0 @angular/material@^16.0.0 @angular/cdk@^16.0.0
```

**For Angular 17:**
```bash
npm install @ruc-lib/data-grid@4.0.0 @angular/material@^17.0.0 @angular/cdk@^17.0.0
```

**For Angular 18:**
```bash
npm install @ruc-lib/data-grid@4.0.0 @angular/material@^18.0.0 @angular/cdk@^18.0.0
```

**For Angular 19:**
```bash
npm install @ruc-lib/data-grid@4.0.0 @angular/material@^19.0.0 @angular/cdk@^19.0.0
```

**For Angular 20:**
```bash
npm install @ruc-lib/data-grid@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/data-grid` based on your Angular version.

| Angular Version | Compatible Version | Installation Command                                                                      |
|-----------------|--------------------|-------------------------------------------------------------------------------------------|
| 15.x.x          | 3.2.0              | `npm install @ruc-lib/data-grid@^3.2.0 @angular/material@^15.0.0 @angular/cdk@^15.0.0`    |
| 16.x.x          | 3.2.0              | `npm install @ruc-lib/data-grid@^3.2.0 @angular/material@^16.0.0 @angular/cdk@^16.0.0`    |
| 17.x.x          | 4.0.0              | `npm install @ruc-lib/data-grid@^4.0.0 @angular/material@^17.0.0 @angular/cdk@^17.0.0`    |
| 18.x.x          | 4.0.0              | `npm install @ruc-lib/data-grid@^4.0.0 @angular/material@^18.0.0 @angular/cdk@^18.0.0`    |
| 19.x.x          | 4.0.0              | `npm install @ruc-lib/data-grid@^4.0.0 @angular/material@^19.0.0 @angular/cdk@^19.0.0`    |
| 20.x.x          | 4.0.0              | `npm install @ruc-lib/data-grid@^4.0.0`                                                   |



## Usage

### 1. Import the Component
In your Angular component file (e.g., `app.component.ts`), import the `RuclibDataGridComponent`:

```typescript
import { Component } from '@angular/core';

// For Complete Library
import { RuclibDataGridComponent } from '@uxpractice/ruc-lib/data-grid';

// For Individual Package
import { RuclibDataGridComponent } from '@ruc-lib/data-grid';

@Component({
  selector: 'app-root',
  imports: [RuclibDataGridComponent],
  templateUrl: './app.component.html',
})
export class AppComponent {
  // Component code here
}
```

### 2. Use the Component
In your component's template, use the `<uxp-ruclib-data-grid>` selector and pass the configuration object to the `rucInputData` input and the data to the `dataSource` input.

```html
<uxp-ruclib-data-grid [dataSource]="datagridDataSource" [rucInputData]="inputObjectDataGrid"
  (rucEvent)="passEvent($event)" [customTheme]="customTheme"> </uxp-ruclib-data-grid>
```

## API Reference

### Component Inputs

| Input          | Type               | Description                                       |
|----------------|--------------------|---------------------------------------------------|
| `rucInputData` | `DataGridConfig`   | The main configuration object for the data grid.  |
| `customTheme`  | `string`           | An optional CSS class for custom theming.         |
| `dataSource`   | `DataGridData`     | Data for the data grid.                           |

### Component Outputs

| Output        | Type          | Description                                 |
|---------------|---------------|---------------------------------------------|
| `rucEvent`    | `any`         | Emits events related to data grid actions.  |

### `DataGridConfig`
This is the main configuration object for the Data Grid component.

> *Detail definition of the each property can be found in type definition file.*

| Property                 | Type                         | Description                                                  |
|--------------------------|------------------------------|--------------------------------------------------------------|
| columnDefs               | Array<columnDefs>            | Array of column definitions.                                 |
| sortConfig               | SortDefaults                 | Configuration for sorting.                                   |
| filterConfig             | FilterDefaults               | Configuration for filtering.                                 |
| paginationConfig         | PaginationDefaults           | Configuration for pagination.                                |
| defaultColConfig         | DefaultColConfig             | Configuration for default column properties.                 |
| highlightText            | string                       | Text to highlight in the table.                              |
| hasSelectionBox          | boolean                      | Whether to show a selection box in the table.                |
| hasStickyHeader          | boolean                      | Whether to show a sticky header in the table.                |
| hasStickyDisclaimer      | boolean                      | Whether to show a sticky disclaimer in the table.            |
| disclaimer               | string                       | Text to display in the disclaimer.                           |
| height                   | string                       | Height of the table.                                         |
| hasRowContextMenu        | boolean                      | Whether to show a context menu for each row.                 |
| hasHighLightedRowOnSelect| boolean                      | Whether to highlight a row when it is selected.              |
| rowHighlightColor        | string                       | Color of the highlighted row.                                |
| rowHeight                | string                       | Height of each row.                                          |
| contextMenuStyle         | any                          | Styles for the context menu.                                 |
| headerRowStyle           | any                          | Styles for the header row.  ex: { position: 'sticky' }       |
| noRowOverlayMsg          | string                       | Message to display when there are no rows to show.           |
| hasSuppressNoRowsOverlay | boolean                      | Whether to suppress the no rows overlay.                     |
| tableStyle               | any                          | Styles for the table.                                        |
| uniqueCol                | string                       | Unique column to identify rows.                              |
| searchBoxStyle           | any                          | Styles for the search box.                                   |
| contextMenuData          | Array<ContextMenuDefaults>   | Data for the context menu.                                   |


## Example Configuration

Here's an example of how to configure the Data Grid component in your component's TypeScript file.

```typescript
import { Component } from '@angular/core';

// For Complete Library
import { DataGridConfig, DataGridData } from '@uxpractice/ruc-lib/data-grid';

// For Individual package
import { DataGridConfig, DataGridData } from '@ruc-lib/data-grid';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
})
export class AppComponent {
  rucInputData = {
    columnDefs: [
      {
        headerName: 'Actions',
        field: 'Actions',
      },
      {
        headerName: 'Position Name',
        field: 'Position',
        type: 'number',
      },
      {
        headerName: 'Name',
        field: 'Name',
        type: 'string',
      },
      {
        headerName: 'Weight',
        field: 'Weight',
        type: 'number',
      },
      {
        headerName: 'Symbol',
        field: 'Symbol',
        type: 'string',
      },
    ],
    sortConfig: {
      hasSort: true,
      sortedAt: 'Position',
      sortOrder: 'desc',
      sortMode: 'auto',
    },
    filterConfig: {
      hasFilter: true,
      filterMode: 'auto',
    },
    paginationConfig: {
      hasPagination: true,
      paginationMode: 'auto',
      defaultRowSet: 5,
      paginationStyle: { float: 'right' },
    },
    defaultColConfig: {
      hasTooltip: false,
      tooltipVal: '',
      sortArrowPos: 'after',
      headerStyle: {
        'border-bottom': '3px solid grey',
        'background-color': 'lightgray',
      },
      cellStyle: {
        'border-bottom': '1.5px solid grey ',
      },
    },
    highlightText: '',
    hasSelectionBox: true,
    hasStickyHeader: true,
    hasStickyDisclaimer: true,
    disclaimer: 'This is disclaimer text. Please ignore.',
    height: '400px',
    hasRowContextMenu: true,
    hasHighLightedRowOnSelect: true,
    rowHighlightColor: '#d3d3d3',
    rowHeight: '40px',
    contextMenuStyle: {},
    headerRowStyle: { position: 'sticky' },
    noRowOverlayMsg: 'No Rows To Show',
    hasSuppressNoRowsOverlay: false,
    tableStyle: {},
    uniqueCol: 'Symbol',
    searchBoxStyle: { float: 'right' },
    contextMenuData: [
      { label: 'Delete', value: 'Delete', disable: false },
      {
        label: 'Select',
        value: 'Select',
        icon: '',
        disable: false,
        style: {},
      },
      { label: 'Add', value: 'Add', icon: '', disable: false, style: {} },
      {
        label: 'Update',
        value: 'Update',
        icon: '',
        disable: false,
        style: {},
      },
    ],
  };

  passEvent(event: any) {
    console.log('Data Grid 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 Data grid Component Library. If you have any feedback or suggestions, please let us know!