@carbon/react 1.90.0 → 1.91.0-rc.0

package/lib/components/DataTable/DataTable.js

@@ -39,6 +39,7 @@ var TableToolbarAction = require('./TableToolbarAction.js');
 var TableToolbarContent = require('./TableToolbarContent.js');
 var TableToolbarSearch = require('./TableToolbarSearch.js');
 var TableToolbarMenu = require('./TableToolbarMenu.js');
+var deprecate = require('../../prop-types/deprecate.js');
 
 const getInstanceId = setupGetInstanceId.setupGetInstanceId();
 const translationKeys = {
@@ -52,11 +53,8 @@ const translationKeys = {
   unselectRow: 'carbon.table.row.unselect'
 };
 
-// TODO: All code comments in this file should be revisited for accuracy and
-// clarity.
-
 /**
- * Message ids that will be passed to translateWithId().
+ * Message IDs that will be passed to translateWithId().
  */
 
 const defaultTranslations = {
@@ -82,14 +80,12 @@ const translateWithId = id => defaultTranslations[id];
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- https://github.com/carbon-design-system/carbon/issues/20071
 
 /**
- * Data Tables are used to represent a collection of resources, displaying a
- * subset of their fields in columns, or headers. We prioritize direct updates
- * to the state of what we're rendering, so internally we end up normalizing the
- * given data and then denormalizing it when rendering.
- *
- * As a result, each part of the DataTable is accessible through look-up by id,
- * and updating the state of the single entity will cascade updates to the
- * consumer.
+ * DataTable components are used to represent a collection of resources,
+ * displaying a subset of their fields in columns, or headers. We prioritize
+ * direct updates to the state of what we're rendering, so internally we
+ * normalize the given data and then denormalize it at render time. Each part of
+ * the DataTable is accessible through look-up by ID, and updating the state of
+ * a single entity cascades updates to the consumer.
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- https://github.com/carbon-design-system/carbon/issues/20071
 const DataTable = props => {
@@ -112,24 +108,18 @@ const DataTable = props => {
   const instanceId = React.useMemo(() => getInstanceId(), []);
   const [state, setState] = React.useState(() => ({
     ...getDerivedStateFromProps.default(props, {}),
-    isExpandedAll: false // Start with collapsed state, treat `undefined` as neutral state
+    // Initialize to collapsed. A value of `undefined` is treated as neutral.
+    isExpandedAll: false
   }));
   React.useEffect(() => {
     const nextRowIds = rows.map(row => row.id);
     const nextHeaders = headers.map(header => header.key);
     const hasRowIdsChanged = !isEqual(nextRowIds, state.rowIds);
-    const currentHeaders = Object.keys(state.cellsById).reduce((acc, cellId) => {
-      const headerKey = cellId.split(':')[1];
-      if (headerKey && !acc.includes(headerKey)) {
-        acc.push(headerKey);
-      }
-      return acc;
-    }, []);
+    const currentHeaders = Array.from(new Set(Object.keys(state.cellsById).map(id => id.split(':')[1])));
     const hasHeadersChanged = !isEqual(nextHeaders, currentHeaders);
     const currentRows = state.rowIds.map(id => {
       const row = state.rowsById[id];
       return {
-        // TODO: Investigate whether it be okay to just return `row`.
         id: row.id,
         disabled: row.disabled,
         isExpanded: row.isExpanded,
@@ -142,11 +132,6 @@ const DataTable = props => {
     }
     // eslint-disable-next-line  react-hooks/exhaustive-deps -- https://github.com/carbon-design-system/carbon/issues/20071
   }, [headers, rows]);
-
-  /**
-   * Get the props associated with the given header. Mostly used for adding in
-   * sorting behavior.
-   */
   const getHeaderProps = ({
     header,
     onClick,
@@ -157,34 +142,36 @@ const DataTable = props => {
       sortDirection,
       sortHeaderKey
     } = state;
+    const {
+      key,
+      slug,
+      decorator
+    } = header;
     return {
       ...rest,
-      key: header.key,
+      key,
       sortDirection,
       isSortable,
-      isSortHeader: sortHeaderKey === header.key,
-      slug: header.slug,
-      decorator: header.decorator,
+      isSortHeader: sortHeaderKey === key,
+      slug,
+      decorator,
       onClick: event => {
         const nextSortState = sorting.getNextSortState(props, state, {
-          key: header.key
+          key
         });
         setState(prev => ({
           ...prev,
           ...nextSortState
         }));
-        // eslint-disable-next-line  @typescript-eslint/no-unused-expressions -- https://github.com/carbon-design-system/carbon/issues/20071
-        onClick && handleOnHeaderClick(onClick, {
-          sortHeaderKey: header.key,
-          sortDirection: nextSortState.sortDirection
-        })(event);
+        if (onClick) {
+          handleOnHeaderClick(onClick, {
+            sortHeaderKey: key,
+            sortDirection: nextSortState.sortDirection
+          })(event);
+        }
       }
     };
   };
-
-  /**
-   * Get the props associated with the given expand header.
-   */
   const getExpandHeaderProps = ({
     onClick,
     onExpand,
@@ -197,39 +184,35 @@ const DataTable = props => {
     } = state;
     const isExpanded = isExpandedAll || rowIds.every(id => rowsById[id].isExpanded);
     const translationKey = isExpanded ? translationKeys.collapseAll : translationKeys.expandAll;
+    const handlers = [handleOnExpandAll, onExpand];
+    if (onClick) {
+      handlers.push(handleOnExpandHeaderClick(onClick, {
+        isExpanded
+      }));
+    }
     return {
       ...rest,
       'aria-label': t(translationKey),
-      // Provide a string of all the expanded row id's, separated by a space.
+      // Provide a string of all expanded row IDs, separated by a space.
       'aria-controls': rowIds.map(id => `expanded-row-${id}`).join(' '),
       isExpanded,
-      // Compose the event handlers so we don't overwrite a consumer's `onClick`
-      // handler
-      onExpand: events.composeEventHandlers([handleOnExpandAll, onExpand,
-      // TODO: Avoid passing `false` to this function.
-      onClick && handleOnExpandHeaderClick(onClick, {
-        isExpanded
-      })])
+      onExpand: events.composeEventHandlers(handlers)
     };
   };
 
   /**
-   * Decorate consumer's `onClick` event handler with sort parameters
+   * Wraps the consumer's `onClick` with sorting metadata.
    */
   const handleOnHeaderClick = (onClick, sortParams) => {
     return event => onClick(event, sortParams);
   };
 
   /**
-   * Decorate consumer's `onClick` event handler with expand parameters
+   * Wraps the consumer's `onClick` with sorting metadata.
    */
   const handleOnExpandHeaderClick = (onClick, expandParams) => {
     return event => onClick(event, expandParams);
   };
-
-  /**
-   * Get the props associated with the given row. Mostly used for expansion.
-   */
   const getRowProps = ({
     row,
     onClick,
@@ -250,10 +233,6 @@ const DataTable = props => {
       disabled: row.disabled
     };
   };
-
-  /**
-   * Get the props associated with an expanded row
-   */
   const getExpandedRowProps = ({
     row,
     ...rest
@@ -265,9 +244,7 @@ const DataTable = props => {
   };
 
   /**
-   * Gets the props associated with selection for a header or a row, where
-   * applicable. Most often used to indicate selection status of the table or
-   * for a specific row.
+   * Gets the props associated with selection for a header or a row.
    */
   const getSelectionProps = ({
     onClick,
@@ -292,7 +269,7 @@ const DataTable = props => {
     // Otherwise, we're working on `TableSelectAll` which handles toggling the
     // selection state of all rows.
     const rowCount = state.rowIds.length;
-    const selectedRowCount = getSelectedRows().length;
+    const selectedRowCount = selectedRows.length;
     const checked = rowCount > 0 && selectedRowCount === rowCount;
     const indeterminate = rowCount > 0 && selectedRowCount > 0 && selectedRowCount !== rowCount;
     const translationKey = checked || indeterminate ? translationKeys.unselectAll : translationKeys.selectAll;
@@ -317,13 +294,13 @@ const DataTable = props => {
     const {
       shouldShowBatchActions
     } = state;
-    const totalSelected = getSelectedRows().length;
+    const selectedRowCount = selectedRows.length;
     return {
       onSelectAll: undefined,
-      totalCount: state.rowIds.length || 0,
+      totalCount: state.rowIds.length,
       ...props,
-      shouldShowBatchActions: shouldShowBatchActions && totalSelected > 0,
-      totalSelected,
+      shouldShowBatchActions: shouldShowBatchActions && selectedRowCount > 0,
+      totalSelected: selectedRowCount,
       onCancel: handleOnCancel
     };
   };
@@ -344,77 +321,49 @@ const DataTable = props => {
       useStaticWidth
     };
   };
-
-  // TODO: `getHeaderProps` and `getRowProps` return `key` props. Would it be
-  // beneficial for this function to also return a `key` prop?
-  /**
-   * Get the props associated with the given table cell.
-   */
   const getCellProps = ({
     cell: {
       hasAILabelHeader,
-      hasDecoratorHeader
+      id
     },
     ...rest
   }) => {
     return {
       ...rest,
       hasAILabelHeader,
-      hasDecoratorHeader
+      key: id
     };
   };
 
   /**
-   * Helper utility to get all the currently selected rows
-   *
-   * @returns the array of rowIds that are currently selected
+   * Selected row IDs, excluding disabled rows.
    */
-  const getSelectedRows = () => state.rowIds.filter(id => {
+  const selectedRows = state.rowIds.filter(id => {
     const row = state.rowsById[id];
     return row.isSelected && !row.disabled;
   });
+  const filteredRowIds = typeof state.filterInputValue === 'string' ? filterRows({
+    cellsById: state.cellsById,
+    getCellId: cells.getCellId,
+    headers,
+    inputValue: state.filterInputValue,
+    rowIds: state.rowIds
+  }) : state.rowIds;
 
   /**
-   * Helper utility to get all of the available rows after applying the filter
-   *
-   * @returns the array of rowIds that are currently included through the filter
-   */
-  const getFilteredRowIds = () => {
-    const filteredRowIds = typeof state.filterInputValue === 'string' ? filterRows({
-      rowIds: state.rowIds,
-      headers: headers,
-      cellsById: state.cellsById,
-      inputValue: state.filterInputValue,
-      getCellId: cells.getCellId
-    }) : state.rowIds;
-    // TODO: Use strict equality check.
-    if (filteredRowIds.length == 0) {
-      return [];
-    }
-    return filteredRowIds;
-  };
-
-  /**
-   * Helper for getting the table prefix for elements that require an
-   * `id` attribute that is unique.
+   * Generates a prefix for table related IDs.
    */
   const getTablePrefix = () => `data-table-${instanceId}`;
 
   /**
-   * Helper for toggling all selected items in a state. Does not call
-   * setState, so use it when setting state.
-   *
-   * @returns object to put into this.setState (use spread operator)
+   * Generates a new `rowsById` object with updated selection state.
    */
-  const setAllSelectedState = (initialState, isSelected, filteredRowIds) => {
+  const getUpdatedSelectionState = (initialState, isSelected) => {
     const {
       rowIds
     } = initialState;
-    // TODO: Use strict inequality check.
-    const isFiltered = rowIds.length != filteredRowIds.length;
+    const isFiltered = rowIds.length !== filteredRowIds.length;
     return {
-      // TODO: Should the `reduce` be typed with `<Record<string,
-      // DataTableRow<ColTypes>>>`?
       rowsById: rowIds.reduce((acc, id) => {
         const row = {
           ...initialState.rowsById[id]
@@ -422,62 +371,59 @@ const DataTable = props => {
         if (!row.disabled && (!isFiltered || filteredRowIds.includes(id))) {
           row.isSelected = isSelected;
         }
-        acc[id] = row; // Local mutation for performance with large tables
+
+        // Local mutation for performance with large tables
+        acc[id] = row;
         return acc;
       }, {})
     };
   };
 
   /**
-   * Handler for the `onCancel` event to hide the batch action bar and
-   * deselect all selected rows
+   * Handler for `onCancel` to hide the batch action toolbar and deselect all
+   * rows.
    */
   const handleOnCancel = () => {
     setState(prev => {
       return {
         ...prev,
         shouldShowBatchActions: false,
-        ...setAllSelectedState(prev, false, getFilteredRowIds())
+        ...getUpdatedSelectionState(prev, false)
       };
     });
   };
 
   /**
-   * Handler for toggling the selection state of all rows in the database
+   * Handler for toggling the selection state of all rows.
    */
   const handleSelectAll = () => {
     setState(prev => {
-      const filteredRowIds = getFilteredRowIds();
       const {
         rowsById
       } = prev;
-      const isSelected = !(Object.values(rowsById).filter(row => row.isSelected && !row.disabled).length > 0);
+      const isSelected = !Object.values(rowsById).filter(row => row.isSelected && !row.disabled).length;
       return {
         ...prev,
         shouldShowBatchActions: isSelected,
-        ...setAllSelectedState(prev, isSelected, filteredRowIds)
+        ...getUpdatedSelectionState(prev, isSelected)
       };
     });
   };
 
   /**
-   * Handler for toggling the selection state of a given row.
+   * Handler for toggling selection state of a given row.
    */
   const handleOnSelectRow = rowId => () => {
     setState(prev => {
       const row = prev.rowsById[rowId];
       if (radio) {
-        // TODO:
-        // 1. Should the `reduce` be typed with `<Record<string,
-        // DataTableRow<ColTypes>>>`?
-        // 2. Add better parameter names. Use `acc` and `row`.
-        //
-        // deselect all radio buttons
-        const rowsById = Object.entries(prev.rowsById).reduce((p, c) => {
-          const [key, val] = c;
-          val.isSelected = false;
-          p[key] = val;
-          return p;
+        // Deselect all radio buttons, then toggle the target row
+        const rowsById = Object.entries(prev.rowsById).reduce((acc, [id, row]) => {
+          acc[id] = {
+            ...row,
+            isSelected: false
+          };
+          return acc;
         }, {});
         return {
           ...prev,
@@ -485,8 +431,8 @@ const DataTable = props => {
           rowsById: {
             ...rowsById,
             [rowId]: {
-              ...row,
-              isSelected: !row.isSelected
+              ...rowsById[rowId],
+              isSelected: !rowsById[rowId].isSelected
             }
           }
         };
@@ -496,10 +442,8 @@ const DataTable = props => {
       const selectedRowsCount = !row.isSelected ? selectedRows + 1 : selectedRows - 1;
       return {
         ...prev,
-        // Basic assumption here is that we want to show the batch action bar if
-        // the row is being selected. If it's being unselected, then see if we
-        // have a non-zero number of selected rows that batch actions could
-        // still apply to
+        // Show batch action toolbar if selecting, or if there are other
+        // selected rows remaining.
         shouldShowBatchActions: !row.isSelected || selectedRowsCount > 0,
         rowsById: {
           ...prev.rowsById,
@@ -511,10 +455,6 @@ const DataTable = props => {
       };
     });
   };
-
-  /**
-   * Handler for toggling the expansion state of a given row.
-   */
   const handleOnExpandRow = rowId => () => {
     setState(prev => {
       const row = prev.rowsById[rowId];
@@ -534,10 +474,6 @@ const DataTable = props => {
       };
     });
   };
-
-  /**
-   * Handler for changing the expansion state of all rows.
-   */
   const handleOnExpandAll = () => {
     setState(prev => {
       const {
@@ -547,22 +483,19 @@ const DataTable = props => {
       return {
         ...prev,
         isExpandedAll: !isExpandedAll,
-        // TODO: Add generic to `reduce`.
-        rowsById: rowIds.reduce((acc, id) => ({
-          ...acc,
-          [id]: {
+        rowsById: rowIds.reduce((acc, id) => {
+          acc[id] = {
             ...prev.rowsById[id],
             isExpanded: !isExpandedAll
-          }
-        }), {})
+          };
+          return acc;
+        }, {})
       };
     });
   };
 
   /**
-   * Handler for transitioning to the next sort state of the table
-   *
-   * @param headerKey - The field for the header that we are sorting by.
+   * Transitions to the next sort state of the table.
    */
   const handleSortBy = headerKey => () => {
     setState(prev => {
@@ -578,37 +511,20 @@ const DataTable = props => {
   };
 
   /**
-   * Event handler for transitioning input value state changes for the table
-   * filter component.
+   * Event handler for table filter input changes.
    */
   const handleOnInputValueChange = (event, defaultValue) => {
-    if (event.target) {
-      setState(prev => ({
-        ...prev,
-        filterInputValue: event.target.value
-      }));
-    }
-    if (defaultValue) {
-      setState(prev => ({
-        ...prev,
-        filterInputValue: defaultValue
-      }));
-    }
+    const value = defaultValue || event.target?.value;
+    setState(prev => ({
+      ...prev,
+      filterInputValue: value
+    }));
   };
-
-  // TODO: Could getFilteredRowIds be used here?
-  const filteredRowIds = typeof state.filterInputValue === 'string' ? filterRows({
-    rowIds: state.rowIds,
-    headers,
-    cellsById: state.cellsById,
-    inputValue: state.filterInputValue,
-    getCellId: cells.getCellId
-  }) : state.rowIds;
   const renderProps = {
     // Data derived from state
     rows: denormalize.default(filteredRowIds, state.rowsById, state.cellsById),
     headers: headers,
-    selectedRows: denormalize.default(getSelectedRows(), state.rowsById, state.cellsById),
+    selectedRows: denormalize.default(selectedRows, state.rowsById, state.cellsById),
     // Prop accessors/getters
     getHeaderProps,
     getExpandHeaderProps,
@@ -662,6 +578,10 @@ DataTable.TableToolbarContent = TableToolbarContent.default;
 DataTable.TableToolbarSearch = TableToolbarSearch.default;
 DataTable.TableToolbarMenu = TableToolbarMenu.default;
 DataTable.propTypes = {
+  /**
+   * Pass in the children that will be rendered within the Table
+   */
+  children: PropTypes.node,
   /**
    * Experimental property. Allows table to align cell contents to the top if there is text wrapping in the content. Might have performance issues, intended for smaller tables
    */
@@ -697,6 +617,13 @@ DataTable.propTypes = {
    * Specify whether the control should be a radio button or inline checkbox
    */
   radio: PropTypes.bool,
+  /**
+   * @deprecated Use `children` instead. This prop will be removed in
+   * the next major version.
+   *
+   * https://www.patterns.dev/react/render-props-pattern/#children-as-a-function
+   */
+  render: deprecate.deprecate(PropTypes.func),
   /**
    * The `rows` prop is where you provide us with a list of all the rows that
    * you want to render in the table. The only hard requirement is that this
@@ -723,13 +650,13 @@ DataTable.propTypes = {
    */
   stickyHeader: PropTypes.bool,
   /**
-   * Optional method that takes in a message id and returns an
+   * Optional method that takes in a message ID and returns an
    * internationalized string. See `DataTable.translationKeys` for all
-   * available message ids.
+   * available message IDs.
    */
   translateWithId: PropTypes.func,
   /**
-   * `false` If true, will use a width of 'auto' instead of 100%
+   * If `true`, sets the table width to `auto` instead of `100%`.
    */
   useStaticWidth: PropTypes.bool,
   /**

package/lib/components/DataTable/Table.d.ts

@@ -26,7 +26,7 @@ export interface TableProps {
      */
     stickyHeader?: boolean;
     /**
-     * `false` If true, will use a width of 'auto' instead of 100%
+     * If `true`, sets the table width to `auto` instead of `100%`.
      */
     useStaticWidth?: boolean;
     /**
@@ -67,7 +67,7 @@ export declare const Table: {
          */
         stickyHeader: PropTypes.Requireable<boolean>;
         /**
-         * `false` If true, will use a width of 'auto' instead of 100%
+         * If `true`, sets the table width to `auto` instead of `100%`.
          */
         useStaticWidth: PropTypes.Requireable<boolean>;
         /**

package/lib/components/DataTable/Table.js

@@ -170,7 +170,7 @@ Table.propTypes = {
    */
   stickyHeader: PropTypes.bool,
   /**
-   * `false` If true, will use a width of 'auto' instead of 100%
+   * If `true`, sets the table width to `auto` instead of `100%`.
    */
   useStaticWidth: PropTypes.bool,
   /**

package/lib/components/DataTable/TableExpandHeader.d.ts

@@ -98,7 +98,7 @@ declare const TableExpandHeader: {
          * Specify whether this row is expanded or not. This helps coordinate data
          * attributes so that `TableExpandRow` and `TableExpandedRow` work together
          */
-        isExpanded: React.Validator;
+        isExpanded: PropTypes.Validator<boolean | null | undefined>;
         /**
          * Hook for when a listener initiates a request to expand the given row
          */

package/lib/components/DataTable/TableExpandHeader.js

@@ -91,13 +91,13 @@ TableExpandHeader.propTypes = {
    * Specify whether this row is expanded or not. This helps coordinate data
    * attributes so that `TableExpandRow` and `TableExpandedRow` work together
    */
-  isExpanded: requiredIfGivenPropIsTruthy.default('enableToggle', PropTypes.bool),
+  isExpanded: requiredIfGivenPropIsTruthy.requiredIfGivenPropIsTruthy('enableToggle', PropTypes.bool),
   /**
    * Hook for when a listener initiates a request to expand the given row
    */
-  onExpand: PropTypes.oneOfType([requiredIfGivenPropIsTruthy.default('enableExpando', PropTypes.func
+  onExpand: PropTypes.oneOfType([requiredIfGivenPropIsTruthy.requiredIfGivenPropIsTruthy('enableExpando', PropTypes.func
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- https://github.com/carbon-design-system/carbon/issues/20071
-  ), requiredIfGivenPropIsTruthy.default('enableToggle', PropTypes.func
+  ), requiredIfGivenPropIsTruthy.requiredIfGivenPropIsTruthy('enableToggle', PropTypes.func
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- https://github.com/carbon-design-system/carbon/issues/20071
   )])
 };

package/lib/components/DatePicker/DatePicker.d.ts

@@ -8,18 +8,6 @@ import React, { ReactNode } from 'react';
 import flatpickr from 'flatpickr';
 import { DateLimit, DateOption } from 'flatpickr/dist/types/options';
 export type DatePickerTypes = 'simple' | 'single' | 'range';
-export type CalRef = {
-    inline: boolean;
-    disableMobile: boolean;
-    defaultDate: Date;
-    closeOnSelect: (evt: React.ChangeEvent<HTMLTextAreaElement>) => void;
-    mode: 'simple' | 'single' | 'range';
-    allowInput: boolean;
-    dateFormat: string;
-    locale: string;
-    plugins: [];
-    clickOpens: any;
-};
 export interface DatePickerProps {
     /**
      * Flatpickr prop passthrough enables direct date input, and when set to false,

package/lib/components/DatePicker/DatePicker.js

@@ -358,8 +358,8 @@ const DatePicker = /*#__PURE__*/React.forwardRef(function DatePicker({
       minDate: minDate,
       maxDate: maxDate,
       parseDate: parseDate,
-      plugins: [datePickerType === 'range' ? rangePlugin.default({
-        input: endInputField.current
+      plugins: [datePickerType === 'range' ? rangePlugin.rangePlugin({
+        input: endInputField.current ?? undefined
       }) : () => {}, appendTo ? appendToPlugin.appendToPlugin({
         appendTo
       }) : () => {}, carbonFlatpickrMonthSelectPlugin({

package/lib/components/DatePicker/plugins/rangePlugin.d.ts

@@ -1,2 +1,19 @@
-declare function _default(config: object): Plugin;
-export default _default;
+/**
+ * Copyright IBM Corp. 2019, 2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { type Config } from 'flatpickr/dist/plugins/rangePlugin';
+import { Instance } from 'flatpickr/dist/types/instance';
+/**
+ * @param config Plugin configuration.
+ * @returns An extension of Flatpickr `rangePlugin` that does the following:
+ *   * Better ensures the calendar dropdown is always aligned to the `<input>` for the starting date.
+ *     Workaround for: https://github.com/flatpickr/flatpickr/issues/1944
+ *   * A logic to ensure `fp.setDate()` call won't end up with "startDate to endDate" set to the first `<input>`
+ */
+export declare const rangePlugin: (config?: Config) => (fp: Instance) => Partial<import("flatpickr/dist/types/options").BaseOptions> & {
+    onReady: (import("flatpickr/dist/types/options").Hook | import("flatpickr/dist/types/options").Hook[] | undefined)[];
+    onPreCalendarPosition: () => void;
+};