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

npm install @uxpractice/ruc-lib

Install Individual Component

If you only need the Grid List component:

npm install @ruc-lib/grid-list

Version Compatibility

Please ensure you install the correct version of @ruc-lib/grid-list based on your Angular version.

| Angular Version | Compatible @ruc-lib/grid-list Version | |--------------------|---------------------------------------------| | 15.x.x | npm install @ruc-lib/grid-list@^3.0.0 | | 16.x.x | npm install @ruc-lib/grid-list@^3.0.0 |

Usage

1. Import the Component

In your Angular component file (e.g., app.component.ts), import the RuclibGridListComponent:

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.

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

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.

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

{ 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

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:

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