npm package: @ruc-lib/grid-list
Description: The Grid List component is a powerful and versatile tool for displaying data in either a traditional table (list) format or a card-based (grid) format. It comes packed with features like sorting, filtering, pagination, row selection, expandable rows for d
Latest version: 4.0.0

# ruclib-grid-list

The Grid List component is a powerful and versatile tool for displaying data in either a traditional table (list) format or a card-based (grid) format. It comes packed with features like sorting, filtering, pagination, row selection, expandable rows for detailed views, and customizable action columns.

## Installation Guide

To use the Grid List 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 GridList component:

**For Angular 15:**
```bash
npm install @ruc-lib/grid-list@3.2.0 @angular/material@^15.0.0 @angular/cdk@^15.0.0
```

**For Angular 16:**
```bash
npm install @ruc-lib/grid-list@3.2.0 @angular/material@^16.0.0 @angular/cdk@^16.0.0
```

**For Angular 17:**
```bash
npm install @ruc-lib/grid-list@4.0.0 @angular/material@^17.0.0 @angular/cdk@^17.0.0
```

**For Angular 18:**
```bash
npm install @ruc-lib/grid-list@4.0.0 @angular/material@^18.0.0 @angular/cdk@^18.0.0
```

**For Angular 19:**
```bash
npm install @ruc-lib/grid-list@4.0.0 @angular/material@^19.0.0 @angular/cdk@^19.0.0
```

**For Angular 20:**
```bash
npm install @ruc-lib/grid-list@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 `@ruc-lib/grid-list` Version     |
|--------------------|---------------------------------------------|
| 15.x.x             | `npm install @ruc-lib/grid-list@^3.2.0`     |
| 16.x.x             | `npm install @ruc-lib/grid-list@^3.2.0`     |
| 17.x.x             | `npm install @ruc-lib/grid-list@^4.0.0`     |
| 18.x.x             | `npm install @ruc-lib/grid-list@^4.0.0`     |
| 19.x.x             | `npm install @ruc-lib/grid-list@^4.0.0`     |
| 20.x.x             | `npm install @ruc-lib/grid-list@^4.0.0`     |


## Usage

### 1. Import the Component
In your Angular component file (e.g., `app.component.ts`), import the `RuclibGridListComponent`:

```typescript
import { Component } from '@angular/core';

// For Complete Library
import { RuclibGridListComponent } from '@uxpractice/ruc-lib/grid-list';

// For Individual Package
import { RuclibGridListComponent } from '@ruc-lib/grid-list';

@Component({
  selector: 'app-root',
  imports: [RuclibGridListComponent],
  templateUrl: './app.component.html',
})
export class AppComponent {
  // Component code here
}
```

### 2. Use the Component

In your component's template, use the `<uxp-ruclib-grid-list>` selector.

```html
<uxp-ruclib-grid-list [rucInputData]="gridListConfig" [dataSource]="gridListData" (rucEvent)="handleGridEvent($event)"> </uxp-ruclib-grid-list>
```

## API Reference

### Component Inputs

| Input          | Type     | Description                                                    |
| -------------- | -------- | -------------------------------------------------------------- |
| `rucInputData` | `object` | The main configuration object for the grid. See details below. |
| `dataSource`   | `any[]`  | The array of data to be displayed in the grid.                 |
| `customTheme`  | `string` | An optional CSS class for custom theming.                      |
| `chartConfig`  | `any`    | Configuration for charts displayed in expandable rows.         |

### Component Outputs

| Output | Type | Description -
| `rucEvent` | `EventEmitter<any>` | Emits various events from the grid. The event object has an `eventName` and `eventOutput`. Possible `eventName` values are: `sortByColumn`, `paginatorChange`, `currentStateObjChange`. |
| `rowExpanded` | `EventEmitter<any>` | Emits when a row is expanded or collapsed, providing the row data and an `isExpanded` flag. -
| `infoClicked` | `EventEmitter<any>` | Emits when an info icon in an action column is clicked, providing the row data. -

### `rucInputData`

This is the main configuration object for the Grid List component.

```typescript
interface RucInputData {
  gridConfig: GridConfig;
  columnConfig: GridColumnConfig[];
}
```

#### `gridConfig`

| Property            | Type                         | Description                                                                         |
| ------------------- | ---------------------------- | ----------------------------------------------------------------------------------- |
| `showFilter`        | `boolean`                    | If `true`, a search filter input is displayed. Default is `true`.                   |
| `showGridView`      | `boolean`                    | If `true`, icons to toggle between list and grid view are shown. Default is `true`. |
| `pagination`        | `boolean`                    | If `true`, pagination is enabled. Default is `true`.                                |
| `isPaginatedApi`    | `boolean`                    | Set to `true` if pagination is handled by a backend API. Default is `false`.        |
| `isExpandable`      | `boolean`                    | If `true`, rows can be expanded to show more details. Default is `false`.           |
| `isSelectable`      | `boolean`                    | If `true`, a checkbox column for row selection is shown. Default is `true`.         |
| `stickyTableHeader` | `boolean`                    | If `true`, the table header remains visible while scrolling. Default is `true`.     |
| `cardStyle`         | `any`                        | Custom CSS styles for the cards in grid view.                                       |
| `showListView`      | `boolean`                    | If `true`, the list view is shown by default. Default is `false`.                   |
| `loadData`          | `(event?: PageEvent) => any` | A function to load data, typically used with API-driven pagination.                 |
| `loadChartData`     | `() => any`                  | A function to load data for charts in expandable rows.                              |

#### `columnConfig`

This is an array of objects, where each object configures a column in the grid.

| Property         | Type                           | Description                                                                       |
| ---------------- | ------------------------------ | --------------------------------------------------------------------------------- |
| `name`           | `string`                       | A unique identifier for the column. Must match a key in the `dataSource` objects. |
| `header`         | `string`                       | The text to display in the column header.                                         |
| `headerStyle`    | `any` (optional)               | Custom CSS styles for the column header.                                          |
| `isCustom`       | `boolean` (optional)           | Set to `true` if you are providing a custom cell template for this column.        |
| `sticky`         | `boolean` (optional)           | If `true`, the column will be sticky.                                             |
| `isSort`         | `boolean` (optional)           | If `true`, enables sorting for this column.                                       |
| `actionColumn`   | `boolean` (optional)           | Set to `true` if this column contains action icons.                               |
| `action`         | `GridListActions[]` (optional) | An array of action configurations for an action column.                           |
| `showInCardView` | `boolean`                      | If `true`, this column's data will be shown on the cards in grid view.            |

#### `GridListActions`

| Property  | Type                                  | Description                                    |
| --------- | ------------------------------------- | ---------------------------------------------- |
| `icon`    | `string`                              | The name of the Material Icon to display.      |
| `title`   | `string`                              | Tooltip text for the icon.                     |
| `handler` | `(event, rowData) => void` (optional) | The function to call when the icon is clicked. |

## Custom Column Templates

To provide a custom template for a cell, set `isCustom: true` in its `columnConfig`. Then, nest a `<ruc-grid-column>` component inside `<uxp-ruclib-grid-list>` and define the template.

```html
<uxp-ruclib-grid-list [rucInputData]="gridListConfig" [dataSource]="gridListData">
  <!-- Custom template for the 'name' column -->
  <ruc-grid-column name="name">
    <ng-template #cellTemplate let-element>
      <strong style="color: cornflowerblue;">{{element.name}}</strong>
    </ng-template>
  </ruc-grid-column>
</uxp-ruclib-grid-list>
```

Make sure the corresponding `columnConfig` entry is updated:

```typescript
{ name: 'name', header: 'Name', showInCardView: true, isCustom: true }
```

## Example Configuration

Here's a comprehensive example of how to configure the Grid List component.

**your-component.ts**

```typescript
import { Component } from '@angular/core';
import { GridConfig, GridColumnConfig } from '@ruc-lib/grid-list'; // Adjust path if needed

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
})
export class AppComponent {
  gridListData = [
    { position: 1, name: 'Hydrogen', weight: 1.0079, symbol: 'H' },
    { position: 2, name: 'Helium', weight: 4.0026, symbol: 'He' },
    { position: 3, name: 'Lithium', weight: 6.941, symbol: 'Li' },
  ];

  gridListConfig: {
    gridConfig: GridConfig<any>;
    columnConfig: GridColumnConfig[];
  };

  constructor() {
    this.gridListConfig = {
      gridConfig: {
        showFilter: true,
        showGridView: true,
        pagination: true,
        isPaginatedApi: false,
        isExpandable: true,
        isSelectable: true,
        stickyTableHeader: true,
        showListView: true,
      },
      columnConfig: [
        { name: 'position', header: 'No.', showInCardView: true },
        { name: 'name', header: 'Name', showInCardView: true },
        { name: 'weight', header: 'Weight', showInCardView: true },
        { name: 'symbol', header: 'Symbol', showInCardView: false },
        {
          name: 'actions',
          header: 'Actions',
          actionColumn: true,
          showInCardView: false,
          action: [
            {
              icon: 'edit',
              title: 'Edit',
              handler: (event, rowData) => {
                console.log('Edit clicked', rowData);
              },
            },
            {
              icon: 'delete',
              title: 'Delete',
              handler: (event, rowData) => {
                console.log('Delete clicked', rowData);
              },
            },
          ],
        },
      ],
    };
  }

  handleGridEvent(event: any) {
    console.log('Grid Event:', event.eventName, event.eventOutput);
  }
}
```

> ⚠️ **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 Grid List component. If you have any feedback or suggestions, please let us know!