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.

$3

``bash
npm install @uxpractice/ruc-lib
`

$3

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.

$3

| 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

$3

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
}
`

$3

In your component's template, use the selector.

`html

`

API Reference

$3

| 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. |

$3

| Output | Type | Description -
| rucEvent | EventEmitter | Emits various events from the grid. The event object has an eventName and eventOutput. Possible eventName values are: sortByColumn, paginatorChange, currentStateObjChange. |
| rowExpanded | EventEmitter | Emits when a row is expanded or collapsed, providing the row data and an isExpanded flag. -
| infoClicked | EventEmitter | Emits when an info icon in an action column is clicked, providing the row data. -

$3

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 component inside and define the template.

`html




{{element.name}}



`

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;
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!