@openedx/paragon 22.16.0 → 22.16.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openedx/paragon",
-  "version": "22.16.0",
+  "version": "22.16.2",
   "description": "Accessible, responsive UI component library based on Bootstrap.",
   "main": "dist/index.js",
   "module": "dist/index.js",

package/src/DataTable/README.md

@@ -167,76 +167,104 @@ To enable proper selection behavior with backend pagination (i.e., when ``isSele
 
 ```jsx live
 () => {
-  const PAGINATED_DATA = [
-    [
-      {
-        id: '2baf70d1-42bb-4437-b551-e5fed5a87abe',
-        title: 'Castle in the Sky',
-        director: 'Hayao Miyazaki',
-        producer: 'Isao Takahata',
-        release_date: 1986,
-        rt_score: 95,
-      }, {
-        id: '12cfb892-aac0-4c5b-94af-521852e46d6a',
-        title: 'Grave of the Fireflies',
-        director: 'Isao Takahata',
-        producer: 'Toru Hara',
-        release_date: 1988,
-        rt_score: 97,
-      },
-      {
-        id: '58611129-2dbc-4a81-a72f-77ddfc1b1b49',
-        title: 'My Neighbor Totoro',
-        director: 'Hayao Miyazaki',
-        producer: 'Hayao Miyazaki',
-        release_date: 1988,
-        rt_score: 93,
-      },
-    ],
-    [
-      {
-        id: 'ea660b10-85c4-4ae3-8a5f-41cea3648e3e',
-        title: 'Kiki\'s Delivery Service',
-        director: 'Hayao Miyazaki',
-        producer: 'Hayao Miyazaki',
-        release_date: 1989,
-        rt_score: 96,
-      },
-      {
-        id: '4e236f34-b981-41c3-8c65-f8c9000b94e7',
-        title: 'Only Yesterday',
-        director: 'Isao Takahata',
-        producer: 'Toshio Suzuki',
-        release_date: 1991,
-        rt_score: 100,
-      },
-      {
-        id: 'ebbb6b7c-945c-41ee-a792-de0e43191bd8',
-        title: 'Porco Rosso',
-        director: 'Hayao Miyazaki',
-        producer: 'Toshio Suzuki',
-        release_date: 1992,
-        rt_score: 94,
-      },
-    ],
-    [
-      {
-        id: '1b67aa9a-2e4a-45af-ac98-64d6ad15b16c',
-        title: 'Pom Poko',
-        director: 'Isao Takahata',
-        producer: 'Toshio Suzuki',
-        release_date: 1994,
-        rt_score: 78,
-      },
-    ],
+  const DEFAULT_PAGE_SIZE = 3;
+  const DATA = [
+    {
+      id: '2baf70d1-42bb-4437-b551-e5fed5a87abe',
+      title: 'Castle in the Sky',
+      director: 'Hayao Miyazaki',
+      producer: 'Isao Takahata',
+      release_date: 1986,
+      rt_score: 95,
+    }, 
+    {
+      id: '12cfb892-aac0-4c5b-94af-521852e46d6a',
+      title: 'Grave of the Fireflies',
+      director: 'Isao Takahata',
+      producer: 'Toru Hara',
+      release_date: 1988,
+      rt_score: 97,
+    },
+    {
+      id: '58611129-2dbc-4a81-a72f-77ddfc1b1b49',
+      title: 'My Neighbor Totoro',
+      director: 'Hayao Miyazaki',
+      producer: 'Hayao Miyazaki',
+      release_date: 1988,
+      rt_score: 93,
+    },
+    {
+      id: 'ea660b10-85c4-4ae3-8a5f-41cea3648e3e',
+      title: 'Kiki\'s Delivery Service',
+      director: 'Hayao Miyazaki',
+      producer: 'Hayao Miyazaki',
+      release_date: 1989,
+      rt_score: 96,
+    },
+    {
+      id: '4e236f34-b981-41c3-8c65-f8c9000b94e7',
+      title: 'Only Yesterday',
+      director: 'Isao Takahata',
+      producer: 'Toshio Suzuki',
+      release_date: 1991,
+      rt_score: 100,
+    },
+    {
+      id: 'ebbb6b7c-945c-41ee-a792-de0e43191bd8',
+      title: 'Porco Rosso',
+      director: 'Hayao Miyazaki',
+      producer: 'Toshio Suzuki',
+      release_date: 1992,
+      rt_score: 94,
+    },
+    {
+      id: '1b67aa9a-2e4a-45af-ac98-64d6ad15b16c',
+      title: 'Pom Poko',
+      director: 'Isao Takahata',
+      producer: 'Toshio Suzuki',
+      release_date: 1994,
+      rt_score: 78,
+    },
   ];
-  const [data, setData] = useState(PAGINATED_DATA[0]);
-  const fetchData = useCallback(
-    (args) => {
+
+  function paginateData(data, pageSize = DEFAULT_PAGE_SIZE) {
+    if (pageSize <= 0) {
+      throw new Error('Invalid page size');
+    }
+    const pages = [];
+    for (let i = 0; i < data.length; i += pageSize) {
+        pages.push(data.slice(i, i + pageSize));
+    }
+    return pages;
+  }
+
+  function filterData(data, filters) {
+    return data.filter((item) => filters.every(filter => (
+      String(item[filter.id]).toLowerCase().includes(String(filter.value).toLowerCase())
+    )));
+  }
+
+  const useDebouncedFetchData = (setData, setTotalItems, setTotalPages, setIsLoading) => useCallback(
+    debounce((args) => {
+      if (!args) { return; }
+      setIsLoading(true);
+
       setTimeout(() => {
-        setData(PAGINATED_DATA[args.pageIndex]);
+        // Filter the data based on the current filters
+        const filteredData = filterData(DATA, args.filters);
+
+        // Paginate the filtered data
+        const paginatedData = paginateData(filteredData, args.pageSize);
+        const currentPageData = paginatedData[args.pageIndex] || [];
+
+        // Update the state with the paginated data, total items, and total pages
+        setData(currentPageData);
+        setTotalItems(filteredData.length);
+        setTotalPages(paginatedData.length);
+
+        setIsLoading(false);
       }, 1000);
-    },
+    }, 300),
     [],
   );
 
@@ -247,12 +275,18 @@ To enable proper selection behavior with backend pagination (i.e., when ``isSele
     disableSortBy: true,
   };
 
+  const [isLoading, setIsLoading] = useState(true);
+  const [data, setData] = useState([]);
+  const [totalItems, setTotalItems] = useState(0);
+  const [totalPages, setTotalPages] = useState(1);
+
+  const fetchData = useDebouncedFetchData(setData, setTotalItems, setTotalPages, setIsLoading);
+
   const DownloadCSVAction = ({ as: Component, selectedFlatRows, ...rest }) => (
     <Component onClick={() => console.log('Download CSV', selectedFlatRows, rest)}>
       Download CSV
     </Component>
   );
-
   const ClearAction = ({ as: Component, tableInstance }) => (
     <Component
       variant="danger"
@@ -264,9 +298,14 @@ To enable proper selection behavior with backend pagination (i.e., when ``isSele
       Clear Selection
     </Component>
   );
-  
+
   return (
     <DataTable
+      isLoading={isLoading}
+      bulkActions={[
+        <DownloadCSVAction />,
+        <ClearAction />,
+      ]}
       isSelectable
       manualSelectColumn={selectColumn}
       SelectionStatusComponent={DataTable.ControlledSelectionStatus}
@@ -275,17 +314,15 @@ To enable proper selection behavior with backend pagination (i.e., when ``isSele
       defaultColumnValues={{ Filter: TextFilter }}
       isPaginated
       manualPagination
-      isSortable
-      manualSortBy
       initialState={{
         pageSize: 3,
-        pageIndex: 0
+        pageIndex: 0,
       }}
       initialTableOptions={{
         getRowId: row => row.id,
       }}
-      itemCount={7}
-      pageCount={3}
+      itemCount={totalItems}
+      pageCount={totalPages}
       fetchData={fetchData}
       data={data}
       columns={[
@@ -302,10 +339,6 @@ To enable proper selection behavior with backend pagination (i.e., when ``isSele
           accessor: 'release_date',
         },
       ]}
-      bulkActions={[
-        <DownloadCSVAction />,
-        <ClearAction />,
-      ]}
     />
   );
 }

package/src/DataTable/hooks.jsx

@@ -1,6 +1,7 @@
-import { useContext } from 'react';
+import { useContext, useEffect } from 'react';
 import DataTableContext from './DataTableContext';
-import { clearSelectionAction } from './selection/data/actions';
+import { clearSelectionAction, setSelectedRowsAction, toggleIsEntireTableSelected } from './selection/data/actions';
+import { getRowIds, getUnselectedPageRows } from './selection/data/helpers';
 
 export const useRows = () => {
   const {
@@ -39,3 +40,55 @@ export const useSelectionActions = (
     clearSelection,
   };
 };
+
+/**
+ * Provides business logic around managing selection state, notably for controlled
+ * selections with API-driven data.
+ *
+ */
+export const useDataTableSelections = ({
+  selections,
+  selectionsDispatch,
+  itemCount,
+  selectedRows,
+  page,
+  isAllPageRowsSelected,
+}) => {
+  // If "Select all" is explicitly opted in by the user, ensure that all unselected rows are selected
+  // when the user navigates to a new page.
+  useEffect(
+    () => {
+      if (selections.isSelectAllEnabled && (itemCount > selectedRows.length || !isAllPageRowsSelected)) {
+        const selectedRowIds = getRowIds(selectedRows);
+        const unselectedPageRows = getUnselectedPageRows(selectedRowIds, page);
+        if (unselectedPageRows.length) {
+          selectionsDispatch(setSelectedRowsAction(unselectedPageRows, itemCount));
+        }
+      }
+    },
+    [selectedRows, itemCount, page, selectionsDispatch, selections.isSelectAllEnabled, isAllPageRowsSelected],
+  );
+
+  // When `selections.isSelectAllEnabled` is true, ensure `selections.isEntireTableSelected` is true.
+  useEffect(() => {
+    if (selections.isSelectAllEnabled && !selections.isEntireTableSelected) {
+      selectionsDispatch(toggleIsEntireTableSelected());
+    }
+  }, [selectionsDispatch, selections.isEntireTableSelected, selections.isSelectAllEnabled]);
+
+  // When `selections.isSelectAllEnabled` differs from `selections.isEntireTableSelected` and
+  // `isAllPageRowsSelected` matches `selections.isSelectAllEnabled`, toggle `selections.isEntireTableSelected`.
+  useEffect(() => {
+    if (!selections.isSelectAllEnabled && selections.isEntireTableSelected && !isAllPageRowsSelected) {
+      selectionsDispatch(toggleIsEntireTableSelected());
+    }
+    if (selections.isSelectAllEnabled && !selections.isEntireTableSelected && isAllPageRowsSelected) {
+      selectionsDispatch(toggleIsEntireTableSelected());
+    }
+  }, [
+    selectionsDispatch,
+    isAllPageRowsSelected,
+    selections.isEntireTableSelected,
+    selections.isSelectAllEnabled,
+  ]);
+};

package/src/DataTable/index.jsx

@@ -33,8 +33,10 @@ import DataTableLayout from './DataTableLayout';
 import ExpandAll from './ExpandAll';
 import ExpandRow from './ExpandRow';
 
-import { useSelectionActions } from './hooks';
-import selectionsReducer, { initialState as initialSelectionsState } from './selection/data/reducer';
+import { useDataTableSelections, useSelectionActions } from './hooks';
+import selectionsReducer, {
+  initialState as initialSelectionsState,
+} from './selection/data/reducer';
 
 function DataTable({
   columns, data, defaultColumnValues, additionalColumns, isSelectable,
@@ -79,12 +81,13 @@ function DataTable({
               selectedRowIds: {},
             };
           }
-          /*  Note: We override the `toggleRowSelected` action from react-table
-              because we need to preserve the order of the selected rows.
-              While `selectedRowIds` is an object that contains the selected rows as key-value pairs,
-              it does not maintain the order of selection. Therefore, we have added the `selectedRowsOrdered` property
-              to keep track of the order in which the rows were selected.
-          */
+          /**
+           * Note: We override the `toggleRowSelected` action from react-table
+           * because we need to preserve the order of the selected rows.
+           * while `selectedRowIds` is an object that contains the selected rows as key-value pairs,
+           * it does not maintain the order of selection. Therefore, we have added the `selectedRowsOrdered` property
+           * to keep track of the order in which the rows were selected.
+           */
           case 'toggleRowSelected': {
             const rowIndex = parseInt(action.id, 10);
             const { selectedRowsOrdered = [] } = previousState;
@@ -185,6 +188,15 @@ function DataTable({
 
   const selectionActions = useSelectionActions(instance, controlledTableSelections);
 
+  useDataTableSelections({
+    selections,
+    selectionsDispatch,
+    itemCount,
+    selectedRows,
+    page: instance.page,
+    isAllPageRowsSelected: instance.isAllPageRowsSelected,
+  });
+
   const enhancedInstance = {
     ...instance,
     manualFilters,
@@ -216,12 +228,12 @@ function DataTable({
         })}
         >
           {children || (
-          <>
-            <TableControlBar />
-            <Table />
-            <EmptyTableComponent content="No results found" />
-            <TableFooter />
-          </>
+            <>
+              <TableControlBar />
+              <Table />
+              <EmptyTableComponent content="No results found" />
+              <TableFooter />
+            </>
           )}
         </div>
       </DataTableLayout>
@@ -328,7 +340,7 @@ DataTable.propTypes = {
     Cell: PropTypes.oneOfType([PropTypes.elementType, PropTypes.node]),
   })),
   /** Function that will fetch table data. Called when page size, page index or filters change.
-    * Meant to be used with manual filters and pagination */
+   * Meant to be used with manual filters and pagination */
   fetchData: PropTypes.func,
   /** Initial state passed to react-table's documentation https://github.com/TanStack/table/blob/v7/docs/src/pages/docs/api/useTable.md */
   initialState: PropTypes.shape({
@@ -340,7 +352,7 @@ DataTable.propTypes = {
     selectedRowsOrdered: PropTypes.arrayOf(PropTypes.number),
   }),
   /** Table options passed to react-table's useTable hook. Will override some options passed in to DataTable, such
-     as: data, columns, defaultColumn, manualFilters, manualPagination, manualSortBy, and initialState */
+   as: data, columns, defaultColumn, manualFilters, manualPagination, manualSortBy, and initialState */
   initialTableOptions: PropTypes.shape({}),
   /** Actions to be performed on the table. Called with the table instance. Not displayed if rows are selected. */
   itemCount: PropTypes.number.isRequired,

package/src/DataTable/selection/ControlledSelectionStatus.jsx

@@ -1,4 +1,4 @@
-import React, { useContext, useEffect } from 'react';
+import React, { useContext } from 'react';
 import PropTypes from 'prop-types';
 
 import DataTableContext from '../DataTableContext';
@@ -7,34 +7,19 @@ import BaseSelectionStatus from './BaseSelectionStatus';
 import {
   clearSelectionAction,
   setSelectAllRowsAllPagesAction,
-  setSelectedRowsAction,
 } from './data/actions';
-import {
-  getUnselectedPageRows,
-  getRowIds,
-} from './data/helpers';
 
 function ControlledSelectionStatus({ className, clearSelectionText }) {
   const {
     itemCount,
     page,
-    controlledTableSelections: [{ selectedRows, isEntireTableSelected }, dispatch],
+    controlledTableSelections: [
+      { selectedRows, isSelectAllEnabled },
+      selectionsDispatch,
+    ],
   } = useContext(DataTableContext);
 
-  useEffect(
-    () => {
-      if (isEntireTableSelected) {
-        const selectedRowIds = getRowIds(selectedRows);
-        const unselectedPageRows = getUnselectedPageRows(selectedRowIds, page);
-        if (unselectedPageRows.length) {
-          dispatch(setSelectedRowsAction(unselectedPageRows, itemCount));
-        }
-      }
-    },
-    [isEntireTableSelected, selectedRows, itemCount, page, dispatch],
-  );
-
-  const numSelectedRows = isEntireTableSelected ? itemCount : selectedRows.length;
+  const numSelectedRows = itemCount === selectedRows.length || isSelectAllEnabled ? itemCount : selectedRows.length;
   const numSelectedRowsOnPage = (page || []).filter(r => r.isSelected).length;
 
   const selectionStatusProps = {
@@ -42,8 +27,8 @@ function ControlledSelectionStatus({ className, clearSelectionText }) {
     numSelectedRows,
     numSelectedRowsOnPage,
     clearSelectionText,
-    onSelectAll: () => dispatch(setSelectAllRowsAllPagesAction()),
-    onClear: () => dispatch(clearSelectionAction()),
+    onSelectAll: () => selectionsDispatch(setSelectAllRowsAllPagesAction()),
+    onClear: () => selectionsDispatch(clearSelectionAction()),
   };
   return <BaseSelectionStatus {...selectionStatusProps} />;
 }

package/src/DataTable/selection/data/actions.js

@@ -33,3 +33,8 @@ export const clearPageSelectionAction = (rowIds) => ({
   type: CLEAR_PAGE_SELECTION,
   rowIds,
 });
+
+export const TOGGLE_IS_ENTIRE_TABLE_SELECTED = 'TOGGLE IS ENTIRE TABLE SELECTED';
+export const toggleIsEntireTableSelected = () => ({
+  type: TOGGLE_IS_ENTIRE_TABLE_SELECTED,
+});

package/src/DataTable/selection/data/reducer.js

@@ -6,11 +6,13 @@ import {
   CLEAR_SELECTION,
   CLEAR_PAGE_SELECTION,
   SET_SELECT_ALL_ROWS_ALL_PAGES,
+  TOGGLE_IS_ENTIRE_TABLE_SELECTED,
 } from './actions';
 
 export const initialState = {
   selectedRows: [],
   isEntireTableSelected: false,
+  isSelectAllEnabled: false,
 };
 
 const selectionsReducer = (state = initialState, action = {}) => {
@@ -21,7 +23,7 @@ const selectionsReducer = (state = initialState, action = {}) => {
         ...state,
         selectedRows,
       };
-      if (selectedRows.length === action.itemCount) {
+      if (state.isSelectAllEnabled || selectedRows.length === action.itemCount) {
         updatedState.isEntireTableSelected = true;
       }
       return updatedState;
@@ -30,16 +32,19 @@ const selectionsReducer = (state = initialState, action = {}) => {
       return {
         ...state,
         isEntireTableSelected: true,
+        isSelectAllEnabled: true,
       };
     case DELETE_ROW:
       return {
         selectedRows: state.selectedRows.filter((row) => row.id !== action.rowId),
         isEntireTableSelected: false,
+        isSelectAllEnabled: false,
       };
     case ADD_ROW: {
       const selectedRows = uniqBy([...state.selectedRows, action.row], row => row.id);
       const isEntireTableSelected = selectedRows.length === action.itemCount;
       return {
+        ...state,
         selectedRows,
         isEntireTableSelected,
       };
@@ -50,6 +55,12 @@ const selectionsReducer = (state = initialState, action = {}) => {
       return {
         isEntireTableSelected: false,
         selectedRows: state.selectedRows.filter(row => !action.rowIds.includes(row.id)),
+        isSelectAllEnabled: false,
+      };
+    case TOGGLE_IS_ENTIRE_TABLE_SELECTED:
+      return {
+        ...state,
+        isEntireTableSelected: !state.isEntireTableSelected,
       };
     default:
       return state;

package/src/DataTable/selection/tests/ControlledSelectionStatus.test.jsx

@@ -4,7 +4,10 @@ import { IntlProvider } from 'react-intl';
 import userEvent from '@testing-library/user-event';
 
 import ControlledSelectionStatus from '../ControlledSelectionStatus';
-import { clearSelectionAction, setSelectAllRowsAllPagesAction, setSelectedRowsAction } from '../data/actions';
+import {
+  clearSelectionAction,
+  setSelectAllRowsAllPagesAction,
+} from '../data/actions';
 import DataTableContext from '../../DataTableContext';
 import {
   SELECT_ALL_TEST_ID,
@@ -88,28 +91,6 @@ describe('<ControlledSelectionStatus />', () => {
       const selectAllButton = screen.queryByTestId(SELECT_ALL_TEST_ID);
       expect(selectAllButton).not.toBeInTheDocument();
     });
-
-    it('selects any unselected page rows', () => {
-      const selectedRows = Array(instance.itemCount).map((item, index) => ({ id: index + 1 }));
-      const dispatchSpy = jest.fn();
-      render(
-        <ControlledSelectionStatusWrapper
-          value={{
-            ...instance,
-            controlledTableSelections: [
-              {
-                selectedRows,
-                isEntireTableSelected: true,
-              },
-              dispatchSpy,
-            ],
-          }}
-        />,
-      );
-      expect(dispatchSpy).toHaveBeenCalledTimes(1);
-      const action = setSelectedRowsAction(instance.page, instance.itemCount);
-      expect(dispatchSpy).toHaveBeenCalledWith(action);
-    });
   });
 
   describe('individual rows selected', () => {

package/src/DataTable/selection/tests/reducer.test.js

@@ -25,6 +25,7 @@ describe('DataTable selections reducer', () => {
     const action = setSelectedRowsAction(rows, itemCount);
     const updatedState = selectionsReducer(defaultInitialState, action);
     expect(updatedState).toEqual({
+      ...defaultInitialState,
       isEntireTableSelected: true,
       selectedRows: rows,
     });
@@ -38,6 +39,7 @@ describe('DataTable selections reducer', () => {
     const updatedState = selectionsReducer(initialState, action);
     expect(updatedState).toEqual({
       isEntireTableSelected: true,
+      isSelectAllEnabled: true,
       selectedRows: initialState.selectedRows,
     });
   });
@@ -70,6 +72,7 @@ describe('DataTable selections reducer', () => {
     const action = addSelectedRowAction(row, itemCount);
     const updatedState = selectionsReducer(defaultInitialState, action);
     expect(updatedState).toEqual({
+      ...defaultInitialState,
       selectedRows: [row],
       isEntireTableSelected: true,
     });
@@ -88,6 +91,7 @@ describe('DataTable selections reducer', () => {
     const rows = [{ id: 1 }, { id: 2 }, { id: 3 }];
     const initialState = {
       ...defaultInitialState,
+      isSelectAllEnabled: false,
       selectedRows: rows,
     };
     const action = clearPageSelectionAction([1, 2]);