@genesislcap/grid-pro 14.199.1 → 14.199.2-alpha-1ab46f4.0

package/README.md

@@ -2,7 +2,7 @@
 
 The `@genesislcap/grid-pro` package provides a collection of grid-related components and utilities for Genesis applications.
 
-### API Documentation
+## API Documentation
 
 For more detailed information on API and configurations, please refer to the [API documentation](docs/api/index.md) in the `docs/api` directory.
 
@@ -12,13 +12,12 @@ For more detailed information on API and configurations, please refer to the [AP
 - **Customizable**: support for custom headers, mapping values, text formatting, custom cell-renderers and more (more on grid options later).
 - **Flexible**: when it comes to **working with data** grid-pro makes it easy by supporting filtering, editing, sorting, pagination (depending on configuration).
 - **Events** and **callbacks**: There is a large number of events and callbacks provided by the grid, you can find details [here](https://www.ag-grid.com/javascript-data-grid/grid-events/).
-- **Simple** or **connected data**: There are two main use cases for our Grid Pro component
-  - **Simple data**: when you have your own data model and flow (JSON, external/custom REST APIs, etc) but still want to use a rich data grid component with all its features (filtering, sorting, custom cell renderers, etc).
-  - **Connected data**: when you have a Data Server or Request Server available and ready to use, and you don't want to worry about handling data transformations, updates, deletes and cell renderers in the grid.
+- **Simple Data** or **Connected Data**: There are two main use cases for our Grid Pro component
+  - **Simple Data**: when you have your own data model and flow (JSON, external/custom REST APIs, etc) but still want to use a rich data grid component with all its features (filtering, sorting, custom cell renderers, etc).
+  - **Connected Data**: when you have a Data Server or Request Server available and ready to use, and you don't want to worry about handling data transformations, updates, deletes and cell renderers in the grid.
 - **State persistence**: ability to save and restore grid state.
 - **Row models**: support for both client-side and server-side [row models](https://www.ag-grid.com/javascript-data-grid/row-models/).
 
-
 ## Project Structure
 
 - **`src/`**: Source code for the package, including cell-editors, cell-renderers, datasources and utility functions.
@@ -66,9 +65,11 @@ provideDesignSystem().register(baseComponents, rapidGridComponents);
 There are many attributes that can be set on a datasource component.
 
 #### Resource Attributes
+
 Some  **resource** related attributes are `DATASERVER` or `REQUEST_SERVER` specific while others can be used with both.
 
 ##### Attributes that are common between DATASERVER and REQUEST_SERVER
+
 |Name|Type|Default|Description|
 |----|----|-------|-----------|
 | `resource-name` | `string` | - | The name of the target [Data Server](https://learn.genesis.global/docs/server/data-server/introduction/) `query` or [Request Server](https://learn.genesis.global/docs/server/request-server/introduction/) `requestReply`. |
@@ -78,6 +79,7 @@ Some  **resource** related attributes are `DATASERVER` or `REQUEST_SERVER` speci
 | `view-number` | `number` | - | The desired view/page you want data from. |
 
 ##### DATASERVER only attributes
+
 |Name|Type|Default|Description|
 |----|----|-------|-----------|
 | `fields` | `string` | - | This optional parameter allows you to select a subset of fields from the query if the client is not interested in receiving all of them. |
@@ -86,33 +88,37 @@ Some  **resource** related attributes are `DATASERVER` or `REQUEST_SERVER` speci
 | `order-by` | `string` | - | This option can be used to select a [Data Server index](https://learn.genesis.global/docs/database/data-types/index-entities/) (defined in the Data Server `query`), which is especially useful if you want the data to be sorted in a specific way. By default, Data Server rows are returned in order of creation (from oldest database record to newest).|
 | `reverse` | `boolean` | `false` | This option changes the [Data Server index](https://learn.genesis.global/docs/database/data-types/index-entities/) iteration. For example, if you are using the default index, the query will return rows in order from the newest database records to the oldest.|
 
-
 ##### REQUEST_SERVER only attributes
+
 |Name|Type|Default|Description|
 |----|----|-------|-----------|
 | `disable-polling` | `boolean` | `false` | This option disables polling if set to true (data updates for the grid will not be fetched automatically).|
 | `polling-interval` | `number` | - | This option enables you to set a custom polling frequency (in milliseconds) for a [Request Server](https://learn.genesis.global/docs/server/request-server/introduction/) resource. Note that this option only works with Request Server resources; if your resource is a Data Server `query`, your grid is updated in real time. |
 |`request`| `string` | - | Similar to `fields` but for [Request Server](https://learn.genesis.global/docs/server/request-server/introduction/) scenarios. This optional parameter enables you to specify request fields, which can include wildcards.|
+|`request-auto-setup`| `boolean` | `false` | This option, if set to true, will automatically set up the `request` based on the datasources's metadata.|
 
 #### Component Attributes
 
 There are additional attributes that can affect the behavior of a datasource component.
 
 ##### `<grid-pro-client-side-datasource>`
+
 |Name|Type|Default|Description|
 |----|----|-------|-----------|
 | `restart-on-reconnection` | `boolean` | `false` | This option, if set to true, will force the resource data to be reloaded upon a reconnection event.|
 | `keep-col-defs-on-clear-row-data` | `boolean` | `false` | This option, if set to true, will retain column definitions upon a `restart` or `clearRowData` event. |
 
 ##### `<grid-pro-server-side-datasource>`
+
 |Name|Type|Default|Description|
 |----|----|-------|-----------|
 | `pagination` | `boolean` | `false` | This option enables pagination if set to true, otherwise the behavior will be infinite-scroll.|
+| `zero-based-view-number` | `boolean` | `false` | This option, if set to true, will make the starting VIEW_NUMBER zero-based (starting from 0 instead of 1).|
 | `live-updates` | `boolean` | `false` | This option enables live updates for the grid if set to true.|
 
 More details about our datasource implementations [here](#genesis-datasource).
 
-### Usage (simple data example)
+### Usage - Simple Data example
 
 ```typescript
 import { ColDef, GridOptions } from '@ag-grid-community/core';
@@ -221,7 +227,7 @@ export class SimpleGridExample extends GenesisElement {
 }
 ```
 
-### Usage - connected data example (client-side row model)
+### Usage - Connected Data example (client-side datasource)
 
 ```typescript
 @customElement({
@@ -238,7 +244,7 @@ export class SimpleGridExample extends GenesisElement {
 export class ConnectedGridClientSideExample extends GenesisElement {}
 ```
 
-### Usage - connected data example (server-side row model)
+### Usage - connected data example (server-side datasource)
 
 Note: if pagination is set to false the grid will be in infinite scroll mode.
 
@@ -258,7 +264,7 @@ export class ConnectedGridServerSideExample extends GenesisElement {}
 ```
 <!-- page-split -->
 
-# Genesis Datasource
+## Genesis Datasource
 
 This folder contains implementations of Genesis `datasource` components, responsible for fetching data for Genesis [Grid Pro](../../README.md) components.
 
@@ -266,32 +272,32 @@ This document outlines the available features of our two “Grid Pro” datasour
 
 ## \<grid-pro-client-side-datasource\>
 
-### Features
+### Client-Side Features
 
 - **Sorting**: Order by any column, ASC or DESC.
 - **Filtering**:
-    - Filtering options are automatically generated, based on the resource’s metadata.
-    - String Filters:
-        - contains
-        - not contains
-        - equals
-        - not equals
-        - starts with
-        - ends with
-        - blank
-        - not blank
-    - Number/Date Filters:
-        - equals
-        - less than
-        - less than or equal
-        - greater than
-        - greater than or equal
-        - in range
+  - Filtering options are automatically generated, based on the resource’s metadata.
+  - String Filters:
+    - contains
+    - not contains
+    - equals
+    - not equals
+    - starts with
+    - ends with
+    - blank
+    - not blank
+  - Number/Date Filters:
+    - equals
+    - less than
+    - less than or equal
+    - greater than
+    - greater than or equal
+    - in range
 - **Filter Combinations** (Max 2 filters can be combined):
-    - filter1 AND filter2
-    - filter1 OR filter2
+  - filter1 AND filter2
+  - filter1 OR filter2
 
-### Notes
+### Client-Side Notes
 
 - Works with both `DATASERVER` and `REQUEST_SERVER` resources.
 - Operations like sorting and filtering are performed on the client-side.
@@ -299,52 +305,52 @@ This document outlines the available features of our two “Grid Pro” datasour
 
 ## \<grid-pro-server-side-datasource\>
 
-### Features
+### Server-Side Features
 
 - **Sorting**: Order by any INDEX column/field, ASC or DESC.
-    - This is a server limitation. For each column that needs to have “sorting” the developer will need to have an INDEX for it. See more about indexes [here](https://learn.genesis.global/docs/database/data-types/index-entities/).
-    - By default, sorting is disabled on ALL columns… BUT if we detect valid ‘` indexes” from the metadata those column/fields will be setup to have sorting.
-    - If the user attempts to force `sortable` we’ll check if it’s really ok to do that + warn in the logs about it + try to mention other available indexes.. if any at all.
+  - This is a server limitation. For each column that needs to have “sorting” the developer will need to have an INDEX for it. See more about indexes [here](https://learn.genesis.global/docs/database/data-types/index-entities/).
+  - By default, sorting is disabled on ALL columns… BUT if we detect valid ‘` indexes” from the metadata those column/fields will be setup to have sorting.
+  - If the user attempts to force `sortable` we’ll check if it’s really ok to do that + warn in the logs about it + try to mention other available indexes.. if any at all.
 - **Filtering**:
-    - Filtering options are automatically generated, based on the resource’s metadata.
-    - String filters
-      - blank
-      - contains
-      - equals
-      - notBlank
-      - notEqual
-      - wordStartsWith
-    - Number filters
-      - equals
-      - notEqual
-      - greaterThan
-      - greaterThanOrEqual
-      - lessThan
-      - lessThanOrEqual
-      - inRange
-      - blank
-      - notBlank
-    - Date filters
-      - equals
-      - lessThan
-      - greaterThan
-      - inRange
-      - isToday
-      - blank
-      - notBlank
-
-### Notes
+  - Filtering options are automatically generated, based on the resource’s metadata.
+  - String filters
+    - blank
+    - contains
+    - equals
+    - notBlank
+    - notEqual
+    - wordStartsWith
+  - Number filters
+    - equals
+    - notEqual
+    - greaterThan
+    - greaterThanOrEqual
+    - lessThan
+    - lessThanOrEqual
+    - inRange
+    - blank
+    - notBlank
+  - Date filters
+    - equals
+    - lessThan
+    - greaterThan
+    - inRange
+    - isToday
+    - blank
+    - notBlank
+
+### Server-Side Notes
 
 - Operations like sorting and filtering are pushed to the backend.
-    - Filtering uses `CRITERIA_MATCH` param
-    - Sorting uses `ORDERY_BY` param
-    - Both work the same way, once filtering/sorting is applied the datasource component “resets itself”, basically starting a new stream with the updated params.
+  - Filtering uses `CRITERIA_MATCH` param
+  - Sorting uses `ORDERY_BY` param
+  - Both work the same way, once filtering/sorting is applied the datasource component “resets itself”, basically starting a new stream with the updated params.
 - **LIMITATIONS**
-    - Sorting can only be applied to “index” fields/columns. Also mentioned [here](https://www.notion.so/Grid-Pro-Datasource-Inventory-d11ca7570ee94847bbcb3e7362025b0a?pvs=21). More details [here](https://genesisglobal.atlassian.net/jira/polaris/projects/GPR/ideas/view/4721227?selectedIssue=GPR-171&focusedCommentId=143757) and [here](https://genesis-global-talk.slack.com/archives/C0416MFG360/p1696456988606789).
-    - ROWS_COUNT doesn’t reflect the correct amount when a CRITERIA_MATCH (filtering) is applied. Example: X resource has 100 records. A criteria is specified so it returns only 50 records… the rows count sent from the server is still 100. Because of that we have to manually/locally calculate that.
+  - Sorting can only be applied to “index” fields/columns. Also mentioned [here](https://www.notion.so/Grid-Pro-Datasource-Inventory-d11ca7570ee94847bbcb3e7362025b0a?pvs=21). More details [here](https://genesisglobal.atlassian.net/jira/polaris/projects/GPR/ideas/view/4721227?selectedIssue=GPR-171&focusedCommentId=143757) and [here](https://genesis-global-talk.slack.com/archives/C0416MFG360/p1696456988606789).
+  - ROWS_COUNT doesn’t reflect the correct amount when a CRITERIA_MATCH (filtering) is applied. Example: X resource has 100 records. A criteria is specified so it returns only 50 records… the rows count sent from the server is still 100. Because of that we have to manually/locally calculate that.
 - Suitable for large datasets where only a subset of data is loaded into the client based on user interactions.
 
-<hr>
+---
 
 ## Supported Row Models
 
@@ -356,40 +362,40 @@ It’s important to note that any client app can implement the other Row Models
 
 `Infinite` and `Viewport` row models are also supported but not offered "out of the box" (devs will have to create their own component).
 
-| Feature |	Client-Side	| Server-Side	|	Notes |
-| --- |	---	|---	|	--- |
-| All Data in Client | ✓ | ✗ |	Free |
-| Fetch Data as User Scrolls |	✗ |	✓ | Free |
-| Row Sorting	| (client) | (client OR server) our component is server-only |	Free |
-| Row Filtering	| (client) |	(client OR server) our component is server-only |	Free |
-| Quick Filter |	✓ |	✓ | Free |
-| Floating Filters |	✓ |	✓ | Free |
-| Dynamic Row Height |	✓ |	✓ | Free |
-| Row Grouping |	(client) | (server) | Paid (Enterprise) |
-| Row Pivoting |	(client) | (server) | Paid (Enterprise) |
-| Lazy Loading Row Groups	| ✗ |	✓ | Paid (Enterprise) |
-| Value Aggregation	(client)	(server)	✗	✗	| Paid (Enterprise) |
-| Row Selection	| ✓ |	✓ | Free |
-| Specify Selectable Rows	| ✓ |	✓ | Free |
-| Header Checkbox Selection	| ✓ |	✓ | Free |
-| Range Selection	| ✓ |	✓ |	Free |
-| Column Spanning	| ✓ |	✓ |	Free |
-| Column Pinning	| ✓ |	✓ |	Free |
-| Row Pinning	| ✓ |	✓ |	Free |
-| Pagination	| ✓ |	✓ |	Free |
-| Custom Filters	| ✓ |	✓ |	Free |
-| Cell Editors	| ✓ |	✓ |	Free |
-| Cell Renderers	| ✓ |	✓ |	Free |
-| Value Getter	| ✓ |	✓ |	Free |
-| Value Setter	| ✓ |	✓ |	Free |
-| Value Formatter	| ✓ |	✓ |	Free |
-| Value Parser	| ✓ |	✓ |	Free |
-| Full Width Rows	| ✓ |	✓ |	Free |
-| CSV Export	| ✓	| (data on screen) | Free |
-| Excel Export | ✓ | (data on screen)	| Paid (Enterprise) |
-| Clipboard Copy & Paste	| ✓ |	✓ |	Free |
-| Update via Transaction	| ✓ |	✓ |	Free |
-| Update via Async Transactions	| ✓ |	✓ |	Free |
+| Feature | Client-Side | Server-Side | Notes |
+| --- | --- |--- | --- |
+| All Data in Client | ✓ | ✗ | Free |
+| Fetch Data as User Scrolls | ✗ | ✓ | Free |
+| Row Sorting | (client) | (client OR server) our component is server-only | Free |
+| Row Filtering | (client) | (client OR server) our component is server-only | Free |
+| Quick Filter | ✓ | ✓ | Free |
+| Floating Filters | ✓ | ✓ | Free |
+| Dynamic Row Height | ✓ | ✓ | Free |
+| Row Grouping | (client) | (server) | Paid (Enterprise) |
+| Row Pivoting | (client) | (server) | Paid (Enterprise) |
+| Lazy Loading Row Groups | ✗ | ✓ | Paid (Enterprise) |
+| Value Aggregation | (client) | (server) | Paid (Enterprise) |
+| Row Selection | ✓ | ✓ | Free |
+| Specify Selectable Rows | ✓ | ✓ | Free |
+| Header Checkbox Selection | ✓ | ✓ | Free |
+| Range Selection | ✓ | ✓ | Free |
+| Column Spanning | ✓ | ✓ | Free |
+| Column Pinning | ✓ | ✓ | Free |
+| Row Pinning | ✓ | ✓ | Free |
+| Pagination | ✓ | ✓ | Free |
+| Custom Filters | ✓ | ✓ | Free |
+| Cell Editors | ✓ | ✓ | Free |
+| Cell Renderers | ✓ | ✓ | Free |
+| Value Getter | ✓ | ✓ | Free |
+| Value Setter | ✓ | ✓ | Free |
+| Value Formatter | ✓ | ✓ | Free |
+| Value Parser | ✓ | ✓ | Free |
+| Full Width Rows | ✓ | ✓ | Free |
+| CSV Export | ✓ | (data on screen) | Free |
+| Excel Export | ✓ | (data on screen) | Paid (Enterprise) |
+| Clipboard Copy & Paste | ✓ | ✓ | Free |
+| Update via Transaction | ✓ | ✓ | Free |
+| Update via Async Transactions | ✓ | ✓ | Free |
 
 ### Summary
 
@@ -400,13 +406,13 @@ It’s important to note that any client app can implement the other Row Models
 
 ### DOM Virtualisation
 
-DOM Virtualisation is a powerful technique that enhances the performance of grid components by only rendering the rows and columns that are currently visible in the viewport. This approach significantly reduces the memory footprint and improves the rendering speed, enabling all of our “grid components” to handle larger datasets more efficiently. 
+DOM Virtualisation is a powerful technique that enhances the performance of grid components by only rendering the rows and columns that are currently visible in the viewport. This approach significantly reduces the memory footprint and improves the rendering speed, enabling all of our “grid components” to handle larger datasets more efficiently.
 
 - **How It Works**: Instead of rendering all rows and columns, the grid dynamically generates the DOM elements for only the visible part of the dataset. As the user scrolls, rows and columns are created or destroyed on the fly, ensuring a smooth scrolling experience.
 - **Benefits**:
-    - Reduced memory usage since only a subset of rows and columns are in the DOM at any given time.
-    - Faster initial rendering and improved responsiveness, even with large datasets.
-    - Enhanced user experience with seamless scrolling and interaction.
+  - Reduced memory usage since only a subset of rows and columns are in the DOM at any given time.
+  - Faster initial rendering and improved responsiveness, even with large datasets.
+  - Enhanced user experience with seamless scrolling and interaction.
 
 For more details, visit the [AG Grid DOM Virtualisation documentation](https://www.ag-grid.com/javascript-data-grid/dom-virtualisation/) (also available in [Tabulator Virtual DOM](https://tabulator.info/docs/6.2/virtual-dom))
 
@@ -416,9 +422,9 @@ Pagination is another effective technique to improve performance in AG Grid by b
 
 - **How It Works**: Data is divided into pages, and only the data for the current page is loaded and rendered. Users can navigate through pages using pagination controls.
 - **Benefits**:
-    - Minimizes the amount of data loaded into the client at any given time, enhancing performance.
-    - Provides a structured way to navigate large datasets, improving usability.
-    - Reduces the risk of browser crashes and memory overflow issues.
+  - Minimizes the amount of data loaded into the client at any given time, enhancing performance.
+  - Provides a structured way to navigate large datasets, improving usability.
+  - Reduces the risk of browser crashes and memory overflow issues.
 
 ### Combined Approach
 
@@ -428,10 +434,10 @@ By leveraging both DOM Virtualisation and Pagination, our “grid components”
 - **Scrolling**: As users scroll, DOM Virtualisation ensures only the visible rows and columns are rendered, maintaining performance.
 - **Page Navigation**: Users can navigate through pages to access the full dataset without overwhelming the client.
 
-
 ## License
 
 Note: this project provides front-end dependencies and uses licensed components listed in the next section; thus, licenses for those components are required during development. Contact [Genesis Global](https://genesis.global/contact-us/) for more details.
 
 ### Licensed components
+
 Genesis low-code platform