@visns-studio/visns-components 5.6.10 → 5.6.12

package/README.md

@@ -191,12 +191,28 @@ A powerful data table component with sorting, filtering, and pagination.
         params: {},
     }}
     columns={[
-        { field: 'id', headerName: 'ID', width: 90 },
-        { field: 'name', headerName: 'Name', width: 150 },
+        { name: 'id', headerName: 'ID', width: 90 },
+        { name: 'name', headerName: 'Name', width: 150 },
+        {
+            name: 'department',
+            headerName: 'Department',
+            width: 180,
+            groupSummaryReducer: 'count',
+            groupSummaryRenderer: (count) => `${count} employees`,
+        },
+        {
+            name: 'salary',
+            headerName: 'Salary',
+            width: 120,
+            type: 'number',
+            groupSummaryReducer: 'sum',
+            groupSummaryRenderer: (sum) => `$${sum.toLocaleString()}`,
+        },
         // More columns...
     ]}
     form={formConfig}
     gridHeight={500}
+    defaultGroupBy={[{ name: 'department' }]}
     settings={{
         pagination: true,
         pageSize: 25,
@@ -214,16 +230,26 @@ A powerful data table component with sorting, filtering, and pagination.
 
 #### DataGrid Props
 
-| Prop          | Description                        | Type     | Default |
-| ------------- | ---------------------------------- | -------- | ------- |
-| ajaxSetting   | Configuration for data fetching    | Object   | -       |
-| columns       | Column definitions                 | Array    | -       |
-| form          | Form configuration for editing     | Object   | -       |
-| gridHeight    | Height of the grid                 | Number   | 500     |
-| settings      | Grid settings (pagination, etc.)   | Object   | -       |
-| setFilterData | Callback for filter changes        | Function | -       |
-| setConfig     | Callback for configuration changes | Function | -       |
-| style         | Custom styles                      | Object   | -       |
+| Prop                  | Description                                | Type     | Default |
+| --------------------- | ------------------------------------------ | -------- | ------- |
+| ajaxSetting           | Configuration for data fetching            | Object   | -       |
+| columns               | Column definitions                         | Array    | -       |
+| defaultExpandedNodes  | Initial expanded nodes for TreeGrid        | Object   | -       |
+| defaultGroupBy        | Initial grouping configuration             | Array    | -       |
+| expandedNodes         | Current expanded nodes for TreeGrid        | Object   | -       |
+| form                  | Form configuration for editing             | Object   | -       |
+| gridHeight            | Height of the grid                         | Number   | 500     |
+| groupBy               | Current grouping configuration             | Array    | -       |
+| loadNode              | Function to load TreeGrid nodes on demand  | Function | -       |
+| onExpandedNodesChange | Callback for TreeGrid node expand/collapse | Function | -       |
+| onGroupByChange       | Callback for grouping changes              | Function | -       |
+| renderGroupTitle      | Custom renderer for group headers          | Function | -       |
+| settings              | Grid settings (pagination, etc.)           | Object   | -       |
+| setFilterData         | Callback for filter changes                | Function | -       |
+| setConfig             | Callback for configuration changes         | Function | -       |
+| style                 | Custom styles                              | Object   | -       |
+| treeColumn            | Column name to display TreeGrid hierarchy  | String   | -       |
+| treeNestingSize       | Indentation size for TreeGrid levels       | Number   | 20      |
 
 #### Auto-Refresh Functionality
 
@@ -253,6 +279,444 @@ When auto-refresh is configured:
 -   Setting `autoRefresh: true` uses the default 30-second interval
 -   The component silently refreshes data without showing notifications
 
+#### Group By Functionality
+
+The DataGrid component supports grouping data by one or more columns, allowing you to organize and visualize data in hierarchical structures.
+
+##### Using defaultGroupBy
+
+The `defaultGroupBy` property allows you to specify initial grouping when the DataGrid loads:
+
+```jsx
+<DataGrid
+    // Other props...
+    defaultGroupBy={[
+        { name: 'category' }, // Group by a single column
+    ]}
+/>
+```
+
+For more complex grouping with multiple levels:
+
+```jsx
+<DataGrid
+    // Other props...
+    defaultGroupBy={[
+        { name: 'department' }, // First level grouping
+        { name: 'role' }, // Second level grouping
+    ]}
+/>
+```
+
+##### Dynamic Grouping
+
+You can also control grouping programmatically:
+
+```jsx
+const [groupBy, setGroupBy] = useState([{ name: 'category' }]);
+
+// Later in your component
+<DataGrid
+    // Other props...
+    groupBy={groupBy}
+    onGroupByChange={setGroupBy}
+/>;
+```
+
+##### Server-Side Grouping
+
+For server-side grouping, the DataGrid sends the groupBy information to your API endpoint:
+
+```jsx
+<DataGrid
+    ajaxSetting={{
+        url: '/api/data',
+        method: 'POST',
+        // Other settings...
+    }}
+    defaultGroupBy={[{ name: 'category' }]}
+    // Other props...
+/>
+```
+
+Your server will receive a request with groupBy information:
+
+```json
+{
+    "page": 1,
+    "take": 25,
+    "groupBy": [{ "name": "category" }]
+    // Other parameters...
+}
+```
+
+##### Group Summaries
+
+You can add summary calculations to grouped data:
+
+```jsx
+<DataGrid
+    // Other props...
+    columns={[
+        {
+            name: 'amount',
+            headerName: 'Amount',
+            type: 'number',
+            groupSummaryReducer: 'sum', // Options: 'sum', 'avg', 'min', 'max', 'count'
+            groupSummaryRenderer: (summary) => `Total: $${summary.toFixed(2)}`,
+        },
+        // Other columns...
+    ]}
+    defaultGroupBy={[{ name: 'category' }]}
+/>
+```
+
+##### Customizing Group Rendering
+
+You can customize how groups are displayed:
+
+```jsx
+<DataGrid
+    // Other props...
+    renderGroupTitle={(groupData) => (
+        <div style={{ fontWeight: 'bold', color: 'var(--primary-color)' }}>
+            {groupData.name}: {groupData.value} ({groupData.count} items)
+        </div>
+    )}
+    defaultGroupBy={[{ name: 'category' }]}
+/>
+```
+
+##### Complete Example with Dynamic Grouping
+
+Here's a complete example of a component that uses DataGrid with dynamic grouping controls:
+
+```jsx
+import React, { useState, useEffect } from 'react';
+import { DataGrid } from 'visns-components';
+
+const EmployeeDataGrid = () => {
+    // State for grouping
+    const [groupBy, setGroupBy] = useState([]);
+
+    // Sample data for the grid
+    const [employees, setEmployees] = useState([]);
+
+    // Fetch data on component mount
+    useEffect(() => {
+        const fetchEmployees = async () => {
+            try {
+                const response = await fetch('/api/employees');
+                const data = await response.json();
+                setEmployees(data);
+            } catch (error) {
+                console.error('Error fetching employees:', error);
+            }
+        };
+
+        fetchEmployees();
+    }, []);
+
+    // Column definitions
+    const columns = [
+        {
+            name: 'id',
+            headerName: 'ID',
+            width: 80,
+        },
+        {
+            name: 'name',
+            headerName: 'Name',
+            width: 180,
+        },
+        {
+            name: 'department',
+            headerName: 'Department',
+            width: 150,
+            groupSummaryReducer: 'count',
+            groupSummaryRenderer: (count) => `${count} employees`,
+        },
+        {
+            name: 'role',
+            headerName: 'Role',
+            width: 150,
+        },
+        {
+            name: 'salary',
+            headerName: 'Salary',
+            width: 120,
+            type: 'number',
+            groupSummaryReducer: 'sum',
+            groupSummaryRenderer: (sum) => `$${sum.toLocaleString()}`,
+        },
+        {
+            name: 'hireDate',
+            headerName: 'Hire Date',
+            width: 120,
+            type: 'date',
+        },
+    ];
+
+    // Group by options for the dropdown
+    const groupByOptions = [
+        { label: 'No Grouping', value: 'none' },
+        { label: 'Department', value: 'department' },
+        { label: 'Role', value: 'role' },
+        { label: 'Department & Role', value: 'department-role' },
+    ];
+
+    // Handle group by change
+    const handleGroupByChange = (e) => {
+        const value = e.target.value;
+
+        switch (value) {
+            case 'department':
+                setGroupBy([{ name: 'department' }]);
+                break;
+            case 'role':
+                setGroupBy([{ name: 'role' }]);
+                break;
+            case 'department-role':
+                setGroupBy([{ name: 'department' }, { name: 'role' }]);
+                break;
+            default:
+                setGroupBy([]);
+                break;
+        }
+    };
+
+    return (
+        <div>
+            <div style={{ marginBottom: '1rem' }}>
+                <label htmlFor="groupBy">Group By: </label>
+                <select
+                    id="groupBy"
+                    onChange={handleGroupByChange}
+                    style={{ padding: '0.5rem', borderRadius: '4px' }}
+                >
+                    {groupByOptions.map((option) => (
+                        <option key={option.value} value={option.value}>
+                            {option.label}
+                        </option>
+                    ))}
+                </select>
+            </div>
+
+            <DataGrid
+                columns={columns}
+                dataSource={employees}
+                groupBy={groupBy}
+                onGroupByChange={setGroupBy}
+                gridHeight={600}
+                settings={{
+                    pagination: true,
+                    pageSize: 25,
+                }}
+                renderGroupTitle={(groupData) => (
+                    <div
+                        style={{
+                            fontWeight: 'bold',
+                            color: 'var(--primary-color)',
+                            padding: '0.25rem 0',
+                        }}
+                    >
+                        {groupData.name === 'department'
+                            ? 'Department'
+                            : 'Role'}
+                        :<span style={{ marginLeft: '0.5rem' }}>
+                            {groupData.value} ({groupData.count} employees)
+                        </span>
+                    </div>
+                )}
+            />
+        </div>
+    );
+};
+
+export default EmployeeDataGrid;
+```
+
+#### TreeGrid Functionality
+
+The DataGrid component also supports hierarchical data display through its TreeGrid functionality. This allows you to represent parent-child relationships in your data with expandable/collapsible nodes.
+
+##### Basic TreeGrid Configuration
+
+To use the TreeGrid functionality:
+
+```jsx
+<DataGrid
+    // Other props...
+    treeColumn="name" // Specify which column will display the expand/collapse icons
+    dataSource={hierarchicalData} // Data with parent-child relationships
+/>
+```
+
+Your data should have a structure where parent nodes contain child nodes:
+
+```jsx
+const hierarchicalData = [
+    {
+        id: 1,
+        name: 'Parent 1',
+        nodes: [
+            // Child nodes
+            { id: 11, name: 'Child 1.1' },
+            {
+                id: 12,
+                name: 'Child 1.2',
+                nodes: [
+                    // Nested children
+                    { id: 121, name: 'Grandchild 1.2.1' },
+                ],
+            },
+        ],
+    },
+    {
+        id: 2,
+        name: 'Parent 2',
+        nodes: [{ id: 21, name: 'Child 2.1' }],
+    },
+];
+```
+
+##### Controlling Expanded Nodes
+
+You can control which nodes are expanded:
+
+```jsx
+const [expandedNodes, setExpandedNodes] = useState({
+    1: true, // Node with ID 1 is expanded
+    '1/12': true, // Node with path 1/12 is expanded
+});
+
+<DataGrid
+    // Other props...
+    treeColumn="name"
+    dataSource={hierarchicalData}
+    expandedNodes={expandedNodes}
+    onExpandedNodesChange={setExpandedNodes}
+/>;
+```
+
+##### Asynchronous Node Loading
+
+For large datasets, you can load child nodes on demand:
+
+```jsx
+<DataGrid
+    // Other props...
+    treeColumn="name"
+    dataSource={asyncHierarchicalData}
+    loadNode={({ node }) => {
+        // Return a Promise that resolves to the child nodes
+        return fetchChildNodes(node.id);
+    }}
+/>
+```
+
+For asynchronous loading, parent nodes should have `nodes: null` to indicate they have children that need to be loaded.
+
+##### Complete TreeGrid Example
+
+Here's a complete example of a component that uses DataGrid with TreeGrid functionality:
+
+```jsx
+import React, { useState } from 'react';
+import { DataGrid } from 'visns-components';
+
+const OrganizationTreeGrid = () => {
+    // Sample hierarchical data
+    const departments = [
+        {
+            id: 1,
+            name: 'Executive',
+            budget: 1500000,
+            nodes: [
+                {
+                    id: 11,
+                    name: 'Finance',
+                    budget: 850000,
+                    nodes: [
+                        { id: 111, name: 'Accounting', budget: 350000 },
+                        { id: 112, name: 'Investment', budget: 500000 },
+                    ],
+                },
+                {
+                    id: 12,
+                    name: 'Operations',
+                    budget: 650000,
+                    nodes: [
+                        { id: 121, name: 'HR', budget: 200000 },
+                        { id: 122, name: 'Facilities', budget: 450000 },
+                    ],
+                },
+            ],
+        },
+        {
+            id: 2,
+            name: 'Sales & Marketing',
+            budget: 1200000,
+            nodes: [
+                { id: 21, name: 'Sales', budget: 700000 },
+                { id: 22, name: 'Marketing', budget: 500000 },
+            ],
+        },
+        {
+            id: 3,
+            name: 'Technology',
+            budget: 2000000,
+            nodes: [
+                { id: 31, name: 'Development', budget: 1200000 },
+                { id: 32, name: 'IT Support', budget: 800000 },
+            ],
+        },
+    ];
+
+    // State for expanded nodes
+    const [expandedNodes, setExpandedNodes] = useState({
+        1: true, // Executive department is expanded by default
+        3: true, // Technology department is expanded by default
+    });
+
+    // Column definitions
+    const columns = [
+        {
+            name: 'name',
+            headerName: 'Department',
+            width: 250,
+            // This column will display the tree expand/collapse icons
+        },
+        {
+            name: 'budget',
+            headerName: 'Budget',
+            width: 150,
+            type: 'number',
+            render: ({ value }) => `$${value.toLocaleString()}`,
+        },
+    ];
+
+    return (
+        <div>
+            <h2>Organization Structure</h2>
+
+            <DataGrid
+                columns={columns}
+                dataSource={departments}
+                treeColumn="name"
+                expandedNodes={expandedNodes}
+                onExpandedNodesChange={setExpandedNodes}
+                treeNestingSize={30} // Indentation size for nested levels
+                gridHeight={500}
+                idProperty="id"
+            />
+        </div>
+    );
+};
+
+export default OrganizationTreeGrid;
+```
+
 ### Form Components
 
 #### Form

package/package.json

@@ -84,7 +84,7 @@
         "react-dom": "^17.0.0 || ^18.0.0"
     },
     "name": "@visns-studio/visns-components",
-    "version": "5.6.10",
+    "version": "5.6.12",
     "description": "Various packages to assist in the development of our Custom Applications.",
     "main": "src/index.js",
     "files": [

package/src/components/crm/DataGrid.jsx

@@ -935,6 +935,12 @@ const DataGrid = forwardRef(
             const cellElement = event.target.closest(
                 '.InovuaReactDataGrid__cell'
             );
+
+            // Add null check to prevent errors when cellElement is null
+            if (!cellElement) {
+                return; // Exit early if no cell element was found
+            }
+
             const columnIndex = Array.from(
                 cellElement.parentNode.children
             ).indexOf(cellElement);
@@ -1042,6 +1048,12 @@ const DataGrid = forwardRef(
                 const cellElement = event.target.closest(
                     '.InovuaReactDataGrid__cell'
                 );
+
+                // Add null check to prevent errors when cellElement is null
+                if (!cellElement) {
+                    return; // Exit early if no cell element was found
+                }
+
                 const columnIndex = Array.from(
                     cellElement.parentNode.children
                 ).indexOf(cellElement);
@@ -2773,13 +2785,68 @@ const DataGrid = forwardRef(
                                                             e.preventDefault();
 
                                                             // Check if every required field in column.validate exists and is truthy in data
-                                                            const isValid =
-                                                                column.validate?.every(
-                                                                    (v) =>
-                                                                        data[v]
-                                                                ) ?? true;
+                                                            if (
+                                                                column.validate &&
+                                                                column.validate
+                                                                    .length > 0
+                                                            ) {
+                                                                const missingFields =
+                                                                    column.validate.filter(
+                                                                        (v) =>
+                                                                            !data[
+                                                                                v
+                                                                            ]
+                                                                    );
 
-                                                            if (isValid) {
+                                                                if (
+                                                                    missingFields.length ===
+                                                                    0
+                                                                ) {
+                                                                    handleTimer(
+                                                                        data[
+                                                                            form
+                                                                                .primaryKey
+                                                                        ],
+                                                                        column.id
+                                                                    );
+                                                                } else {
+                                                                    // Format field names to be more readable
+                                                                    const formattedFields =
+                                                                        missingFields.map(
+                                                                            (
+                                                                                field
+                                                                            ) => {
+                                                                                // Try to find the column with this field ID to get its label
+                                                                                const fieldColumn =
+                                                                                    columns.find(
+                                                                                        (
+                                                                                            col
+                                                                                        ) =>
+                                                                                            col.id ===
+                                                                                            field
+                                                                                    );
+                                                                                // Use the label if found, otherwise use the field ID
+                                                                                return (
+                                                                                    fieldColumn?.label ||
+                                                                                    field
+                                                                                );
+                                                                            }
+                                                                        );
+
+                                                                    const fieldList =
+                                                                        formattedFields.join(
+                                                                            ', '
+                                                                        );
+                                                                    toast.error(
+                                                                        `Please complete the following required field${
+                                                                            missingFields.length >
+                                                                            1
+                                                                                ? 's'
+                                                                                : ''
+                                                                        } before starting the timer: ${fieldList}`
+                                                                    );
+                                                                }
+                                                            } else {
                                                                 handleTimer(
                                                                     data[
                                                                         form
@@ -2787,10 +2854,6 @@ const DataGrid = forwardRef(
                                                                     ],
                                                                     column.id
                                                                 );
-                                                            } else {
-                                                                toast.error(
-                                                                    'Please complete the required fields before starting the timer.'
-                                                                );
                                                             }
                                                         }}
                                                     >
@@ -3206,6 +3269,22 @@ const DataGrid = forwardRef(
             };
         }, []);
 
+        // Reset state when ajaxSetting changes (e.g., when navigating to a new page)
+        useEffect(() => {
+            // Reset selected state
+            setSelected({});
+
+            // Reset filter value if needed
+            if (setFilterData) {
+                setFilterData([]);
+            }
+
+            // Force reload of data
+            if (gridRef.current && gridRef.current.paginationProps) {
+                gridRef.current.paginationProps.reload();
+            }
+        }, [ajaxSetting?.url]);
+
         // Auto-refresh effect
         useEffect(() => {
             // Clear any existing timer
@@ -3258,9 +3337,15 @@ const DataGrid = forwardRef(
                 <div className={styles.dataGridContainer}>
                     {limit && limit > 0 ? (
                         <ReactDataGrid
+                            key={`datagrid-${ajaxSetting?.url || ''}-${
+                                ajaxSetting?.groupBy ? 'grouped' : 'ungrouped'
+                            }`}
                             {...tableSetting}
                             columns={gridColumns}
                             dataSource={dataSource}
+                            {...(ajaxSetting && ajaxSetting.groupBy
+                                ? { defaultGroupBy: ajaxSetting.groupBy }
+                                : {})}
                             filterValue={filterValue}
                             limit={limit}
                             enableColumnAutosize={false}