@ruc-lib/grid-list 2.0.0 → 3.0.0

package/README.md

@@ -1,7 +1,257 @@
 # ruclib-grid-list
 
-This library was generated with [Nx](https://nx.dev).
+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.
 
-## Running unit tests
+## Installation Guide
 
-Run `nx test ruclib-grid-list` to execute the unit tests.
+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 Grid List component:
+
+```bash
+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 Module
+
+In your Angular module file (e.g., `app.module.ts`), import the `RuclibGridListModule`:
+
+```typescript
+// For Complete Library
+import { RuclibGridListModule } from '@uxpractice/ruc-lib/grid-list';
+
+// For Individual Package
+import { RuclibGridListModule } from '@ruc-lib/grid-list';
+
+import { AppComponent } from './app.component';
+import { NgModule } from '@angular/core';
+import { BrowserModule } from '@angular/platform-browser';
+import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
+
+@NgModule({
+  declarations: [AppComponent],
+  imports: [BrowserModule, BrowserAnimationsModule, RuclibGridListModule],
+  providers: [],
+  bootstrap: [AppComponent],
+})
+export class AppModule {}
+```
+
+### 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!