@genesislcap/grid-pro 14.275.3 → 14.276.0

package/README.md

@@ -268,7 +268,7 @@ export class ConnectedGridServerSideExample extends GenesisElement {}
 
 This folder contains implementations of Genesis `datasource` components, responsible for fetching data for Genesis [Grid Pro](../../README.md) components.
 
-This document outlines the available features of our two “Grid Pro” datasources: `<grid-pro-client-side-datasource>` and `<grid-pro-server-side-datasource>`.
+This document outlines the available features of our two "Grid Pro" datasources: `<grid-pro-client-side-datasource>` and `<grid-pro-server-side-datasource>`.
 
 ## \<grid-pro-client-side-datasource\>
 
@@ -276,7 +276,7 @@ This document outlines the available features of our two “Grid Pro” datasour
 
 - **Sorting**: Order by any column, ASC or DESC.
 - **Filtering**:
-  - Filtering options are automatically generated, based on the resource’s metadata.
+  - Filtering options are automatically generated, based on the resource's metadata.
   - String Filters:
     - contains
     - not contains
@@ -308,11 +308,11 @@ This document outlines the available features of our two “Grid Pro” datasour
 ### 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 [Genesis database indexes](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.
+  - Filtering options are automatically generated, based on the resource's metadata.
   - String filters
     - blank
     - contains
@@ -344,21 +344,21 @@ This document outlines the available features of our two “Grid Pro” datasour
 - 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.
+  - 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.
 
 ---
 
 ## Supported Row Models
 
-We support all of the AG’s Row Models.  More on [JavaScript Grid: Row Models | AG Grid (ag-grid.com)](https://www.ag-grid.com/javascript-data-grid/row-models/).
+We support all of the AG's Row Models.  More on [JavaScript Grid: Row Models | AG Grid (ag-grid.com)](https://www.ag-grid.com/javascript-data-grid/row-models/).
 
-In the table below you can find a complete “feature list” of all the possibilities of client/server-side row models (and others too.. that can be manually enabled/integrated but we don’t expose any components for those yet).
+In the table below you can find a complete "feature list" of all the possibilities of client/server-side row models (and others too.. that can be manually enabled/integrated but we don't expose any components for those yet).
 
-It’s important to note that any client app can implement the other Row Models to their own needs. Our Grid Pro component is not tied to the datasource, it’s the opossite.. so datasources can be as specialized/customized as possible.
+It's important to note that any client app can implement the other Row Models to their own needs. Our Grid Pro component is not tied to the datasource, it's the opossite.. so datasources can be as specialized/customized as possible.
 
 `Infinite` and `Viewport` row models are also supported but not offered "out of the box" (devs will have to create their own component).
 
@@ -406,7 +406,7 @@ 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**:
@@ -416,7 +416,7 @@ DOM Virtualisation is a powerful technique that enhances the performance of grid
 
 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))
 
-### Pagination
+### Pagination Performance
 
 Pagination is another effective technique to improve performance in AG Grid by breaking down large datasets into smaller, manageable chunks or pages. This allows the grid to load and render only a subset of data at a time, significantly reducing the load on the client.
 
@@ -428,12 +428,425 @@ Pagination is another effective technique to improve performance in AG Grid by b
 
 ### Combined Approach
 
-By leveraging both DOM Virtualisation and Pagination, our “grid components” can efficiently manage and display larger datasets on the client-side. Here’s how these techniques work together:
+By leveraging both DOM Virtualisation and Pagination, our "grid components" can efficiently manage and display larger datasets on the client-side. Here's how these techniques work together:
 
 - **Initial Load**: Only the data for the first page is loaded, minimizing the initial load time.
 - **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.
 
+## Status Bar and Pagination
+
+The Grid Pro component supports a comprehensive status bar system at the bottom of the grid, along with flexible pagination options. The status bar can be configured with various panels to display information like row counts, custom content, and action buttons.
+
+### Enterprise License Requirement
+
+**Important**: Status bar functionality requires the AG Grid Enterprise module to be available. Status bar components will only be displayed if the Enterprise module is properly licensed and configured.
+
+### Basic Status Bar Usage
+
+The status bar can be enabled using the datasource attributes and configured through the `status-bar-config` attribute:
+
+```html
+<rapid-grid-pro>
+  <grid-pro-client-side-datasource
+    resource-name="ALL_TRADES"
+    with-status-bar="true"
+    status-bar-config='{"rows": true, "reload": true, "loadMore": true}'
+  ></grid-pro-client-side-datasource>
+</rapid-grid-pro>
+```
+
+### Status Bar Configuration Interface
+
+The status bar can be configured using the `GridProStatusBarConfig` interface:
+
+```typescript
+interface GridProStatusBarConfig {
+  rows?: boolean;                                    // Enable row count component (default: true)
+  maxRows?: boolean;                                 // Enable max rows label-value component (default: false)
+  loadMore?: boolean | GridProStatusBarLoadMoreConfig; // Enable/configure load more button
+  reload?: boolean | GridProStatusBarReloadConfig;     // Enable/configure reload button
+}
+
+interface GridProStatusBarLoadMoreConfig {
+  onLoadMore?: () => void;    // Custom callback function
+  appearance?: string;        // Button appearance: 'accent', 'lightweight', 'neutral', 'outline', 'stealth'
+  tooltip?: string;          // Custom tooltip text (default: 'Load More')
+}
+
+interface GridProStatusBarReloadConfig {
+  onReload?: () => void;     // Custom callback function
+  icon?: string;            // Custom icon name (default: 'refresh')
+  tooltip?: string;         // Custom tooltip text (default: 'Reload')
+}
+```
+
+### Status Bar Configuration Examples
+
+#### Basic Configuration
+
+```typescript
+// Simple boolean configuration
+const statusBarConfig = {
+  rows: true,
+  maxRows: true,
+  loadMore: true,
+  reload: true
+};
+```
+
+#### Advanced Configuration with Custom Callbacks
+
+```typescript
+// Advanced configuration with custom callbacks and styling
+const statusBarConfig = {
+  rows: true,
+  maxRows: false,
+  loadMore: {
+    onLoadMore: () => {
+      console.log('Custom load more logic');
+      // Your custom load more implementation
+    },
+    appearance: 'accent',
+    tooltip: 'Load 50 more records from server'
+  },
+  reload: {
+    onReload: () => {
+      console.log('Custom reload logic');
+      // Your custom reload implementation
+    },
+    icon: 'refresh',
+    tooltip: 'Refresh all data from server'
+  }
+};
+```
+
+#### TypeScript Usage in Component
+
+```typescript
+import { GridProStatusBarConfig } from '@genesislcap/grid-pro';
+
+@customElement({
+  name: 'my-grid-component',
+  template: html`
+    <rapid-grid-pro with-status-bar>
+      <grid-pro-client-side-datasource
+        resource-name="ALL_TRADES"
+        :status-bar-config=${(x) => x.statusBarConfig}
+      ></grid-pro-client-side-datasource>
+    </rapid-grid-pro>
+  `
+})
+export class MyGridComponent extends GenesisElement {
+  @observable statusBarConfig: GridProStatusBarConfig = {
+    rows: true,
+    maxRows: true,
+    loadMore: {
+      appearance: 'outline',
+      tooltip: 'Load more trades from server'
+    },
+    reload: {
+      tooltip: 'Refresh trade data'
+    }
+  };
+}
+```
+
+### Client-Side vs Server-Side Datasource Differences
+
+#### Client-Side Datasource (`<grid-pro-client-side-datasource>`)
+
+**Available Status Bar Components:**
+
+- **Row Count**: Shows total and filtered row count (`agTotalAndFilteredRowCountComponent`)
+- **Max Rows**: Shows the maximum rows limit
+- **Load More**: Button to load additional rows from server
+- **Reload**: Button to reload/refresh the datasource
+- **Pagination**: Full pagination controls when pagination is enabled
+
+**Example:**
+
+```html
+<rapid-grid-pro with-status-bar>
+  <grid-pro-client-side-datasource
+    resource-name="ALL_TRADES"
+    status-bar-config='{"rows": true, "maxRows": true, "loadMore": true, "reload": true}'
+  ></grid-pro-client-side-datasource>
+</rapid-grid-pro>
+```
+
+#### Server-Side Datasource (`<grid-pro-server-side-datasource>`)
+
+**Available Status Bar Components:**
+
+- **Row Count**: Shows total row count only (`agTotalRowCountComponent`)
+- **Max Rows**: Shows the maximum rows limit
+- **Load More**: **NOT AVAILABLE** - Server-side uses infinite scroll or pagination instead
+- **Reload**: Button to reload/refresh the datasource
+- **Pagination**: Full pagination controls when pagination is enabled
+
+**Important Notes:**
+
+- Load More button is **automatically disabled** for server-side datasources
+- Server-side row model handles data loading through infinite scroll or pagination
+- Row count component shows total rows (not filtered count due to server limitations)
+
+**Example:**
+
+```html
+<rapid-grid-pro with-status-bar>
+  <grid-pro-server-side-datasource
+    resource-name="ALL_TRADES"
+    status-bar-config='{"rows": true, "maxRows": true, "reload": true}'
+    pagination="true"
+  ></grid-pro-server-side-datasource>
+</rapid-grid-pro>
+```
+
+### Pagination
+
+#### Basic Pagination Setup
+
+```html
+<!-- Client-side pagination -->
+<rapid-grid-pro pagination="true" pagination-page-size="25" with-status-bar="true">
+  <grid-pro-client-side-datasource
+    resource-name="ALL_TRADES"
+  ></grid-pro-client-side-datasource>
+</rapid-grid-pro>
+
+<!-- Server-side pagination -->
+<rapid-grid-pro pagination="true" with-status-bar="true">
+  <grid-pro-server-side-datasource
+    resource-name="ALL_TRADES"
+    max-rows="50"
+  ></grid-pro-server-side-datasource>
+</rapid-grid-pro>
+```
+
+#### Pagination with Custom Status Bar
+
+When pagination is enabled, Grid Pro automatically:
+
+- Adds pagination controls to the status bar
+- Suppresses the default AG Grid pagination panel
+- Positions pagination controls on the right side of the status bar
+
+```html
+<rapid-grid-pro pagination="true" with-status-bar="true">
+  <grid-pro-client-side-datasource
+    resource-name="ALL_TRADES"
+    status-bar-config='{"rows": true, "reload": true}'
+  ></grid-pro-client-side-datasource>
+</rapid-grid-pro>
+```
+
+**Default Status Bar Layout with Pagination:**
+
+- Left: Row count component (`agTotalAndFilteredRowCountComponent` for client-side, `agTotalRowCountComponent` for server-side)
+- Right: Pagination controls with navigation buttons and page information
+
+### Built-in AG Grid Status Bar Panels
+
+Grid Pro supports all standard AG Grid status bar panels:
+
+- `agTotalRowCountComponent`: Displays the total row count
+- `agTotalAndFilteredRowCountComponent`: Displays the total and filtered row count
+- `agFilteredRowCountComponent`: Displays the filtered row count
+- `agSelectedRowCountComponent`: Displays the selected row count
+- `agAggregationComponent`: Displays aggregations for the selected range
+
+### Custom Status Bar Components
+
+Grid Pro provides several custom status bar components accessible through the `GridProStatusBarTypes` enum:
+
+#### LabelValueStatusBarComponent
+
+A flexible component that displays a label and value pair:
+
+```typescript
+import { GridProStatusBarTypes } from '@genesislcap/grid-pro';
+
+// In your grid options:
+statusBar: {
+  statusPanels: [
+    { 
+      statusPanel: GridProStatusBarTypes.labelValue,
+      statusPanelParams: { 
+        label: 'Max Rows', 
+        value: 250,
+        hide: false 
+      },
+      align: 'left',
+    },
+  ],
+},
+```
+
+#### LoadMoreStatusBarComponent
+
+A button component that allows users to load additional rows (client-side only):
+
+```typescript
+import { GridProStatusBarTypes } from '@genesislcap/grid-pro';
+
+// In your grid options:
+statusBar: {
+  statusPanels: [
+    { 
+      statusPanel: GridProStatusBarTypes.loadMore,
+      statusPanelParams: {
+        onLoadMore: () => console.log('Loading more data...'),
+        appearance: 'outline',
+        tooltip: 'Load more rows from server'
+      },
+      align: 'right',
+    },
+  ],
+},
+```
+
+#### ReloadStatusBarComponent
+
+A refresh button component that allows users to reload the grid data:
+
+```typescript
+import { GridProStatusBarTypes } from '@genesislcap/grid-pro';
+
+// In your grid options:
+statusBar: {
+  statusPanels: [
+    { 
+      statusPanel: GridProStatusBarTypes.reload,
+      statusPanelParams: {
+        onReload: () => console.log('Reloading data...'),
+        icon: 'refresh',
+        tooltip: 'Reload the datasource'
+      },
+      align: 'right',
+    },
+  ],
+},
+```
+
+#### PaginationStatusBarComponent
+
+A pagination control component that provides navigation buttons and page information:
+
+```typescript
+import { GridProStatusBarTypes } from '@genesislcap/grid-pro';
+
+// In your grid options:
+statusBar: {
+  statusPanels: [
+    { statusPanel: 'agTotalAndFilteredRowCountComponent', align: 'left' },
+    { statusPanel: GridProStatusBarTypes.pagination, align: 'right' },
+  ],
+},
+```
+
+### Manual Status Bar Configuration
+
+You can also manually configure the status bar using direct grid options:
+
+```typescript
+import { GridProStatusBarTypes } from '@genesislcap/grid-pro';
+
+const gridOptions = {
+  statusBar: {
+    statusPanels: [
+      { statusPanel: 'agTotalAndFilteredRowCountComponent', align: 'left' },
+      { 
+        statusPanel: GridProStatusBarTypes.labelValue,
+        statusPanelParams: { label: 'Active Records', value: 1250 },
+        align: 'center'
+      },
+      { 
+        statusPanel: GridProStatusBarTypes.reload,
+        statusPanelParams: {
+          tooltip: 'Refresh all data'
+        },
+        align: 'right' 
+      },
+    ],
+  },
+};
+```
+
+### Complete Usage Examples
+
+#### Client-Side with Full Status Bar
+
+```html
+<rapid-grid-pro 
+  pagination="true" 
+  pagination-page-size="50" 
+  with-status-bar="true">
+  <grid-pro-client-side-datasource
+    resource-name="ALL_TRADES"
+    max-rows="500"
+    status-bar-config='{
+      "rows": true,
+      "maxRows": true,
+      "loadMore": {
+        "appearance": "accent",
+        "tooltip": "Load 50 more trades"
+      },
+      "reload": {
+        "tooltip": "Refresh trade data"
+      }
+    }'
+  ></grid-pro-client-side-datasource>
+</rapid-grid-pro>
+```
+
+#### Server-Side with Pagination
+
+```html
+<rapid-grid-pro 
+  pagination="true" 
+  with-status-bar="true">
+  <grid-pro-server-side-datasource
+    resource-name="ALL_TRADES"
+    max-rows="100"
+    status-bar-config='{
+      "rows": true,
+      "maxRows": true,
+      "reload": true
+    }'
+  ></grid-pro-server-side-datasource>
+</rapid-grid-pro>
+```
+
+#### Infinite Scroll with Minimal Status Bar
+
+```html
+<rapid-grid-pro with-status-bar="true">
+  <grid-pro-server-side-datasource
+    resource-name="ALL_TRADES"
+    max-rows="50"
+    status-bar-config='{"rows": true, "reload": true}'
+  ></grid-pro-server-side-datasource>
+</rapid-grid-pro>
+```
+
+### Accessibility Features
+
+All status bar components include comprehensive accessibility support:
+
+- **ARIA labels** and **roles** for screen readers
+- **Keyboard navigation** support (Tab, Enter, Space)
+- **Focus management** and visual indicators
+- **Semantic HTML** structure with proper landmarks
+- **Tooltips** and **descriptions** for interactive elements
+
+### Performance Considerations
+
+- Status bar components are lightweight and optimized for performance
+- Components are only rendered when enabled in configuration
+- Event listeners are properly cleaned up when components are destroyed
+- Status updates are debounced to prevent excessive re-renders
+
 ## 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.