@carbon/react 1.90.0 → 1.91.0

package/es/components/DataTable/DataTable.js

@@ -37,6 +37,7 @@ import TableToolbarAction from './TableToolbarAction.js';
 import TableToolbarContent from './TableToolbarContent.js';
 import TableToolbarSearch from './TableToolbarSearch.js';
 import TableToolbarMenu from './TableToolbarMenu.js';
+import { deprecate } from '../../prop-types/deprecate.js';
 
 const getInstanceId = setupGetInstanceId();
 const translationKeys = {
@@ -50,11 +51,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 = {
@@ -80,14 +78,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 => {
@@ -110,24 +106,18 @@ const DataTable = props => {
   const instanceId = useMemo(() => getInstanceId(), []);
   const [state, setState] = useState(() => ({
     ...getDerivedStateFromProps(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
   }));
   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,
@@ -140,11 +130,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,
@@ -155,34 +140,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 = 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,
@@ -195,39 +182,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: composeEventHandlers([handleOnExpandAll, onExpand,
-      // TODO: Avoid passing `false` to this function.
-      onClick && handleOnExpandHeaderClick(onClick, {
-        isExpanded
-      })])
+      onExpand: 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,
@@ -248,10 +231,6 @@ const DataTable = props => {
       disabled: row.disabled
     };
   };
-
-  /**
-   * Get the props associated with an expanded row
-   */
   const getExpandedRowProps = ({
     row,
     ...rest
@@ -263,9 +242,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,
@@ -290,7 +267,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;
@@ -315,13 +292,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
     };
   };
@@ -342,77 +319,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,
+    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
-    }) : 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]
@@ -420,62 +369,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,
@@ -483,8 +429,8 @@ const DataTable = props => {
           rowsById: {
             ...rowsById,
             [rowId]: {
-              ...row,
-              isSelected: !row.isSelected
+              ...rowsById[rowId],
+              isSelected: !rowsById[rowId].isSelected
             }
           }
         };
@@ -494,10 +440,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,
@@ -509,10 +453,6 @@ const DataTable = props => {
       };
     });
   };
-
-  /**
-   * Handler for toggling the expansion state of a given row.
-   */
   const handleOnExpandRow = rowId => () => {
     setState(prev => {
       const row = prev.rowsById[rowId];
@@ -532,10 +472,6 @@ const DataTable = props => {
       };
     });
   };
-
-  /**
-   * Handler for changing the expansion state of all rows.
-   */
   const handleOnExpandAll = () => {
     setState(prev => {
       const {
@@ -545,22 +481,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 => {
@@ -576,37 +509,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
-  }) : state.rowIds;
   const renderProps = {
     // Data derived from state
     rows: denormalize(filteredRowIds, state.rowsById, state.cellsById),
     headers: headers,
-    selectedRows: denormalize(getSelectedRows(), state.rowsById, state.cellsById),
+    selectedRows: denormalize(selectedRows, state.rowsById, state.cellsById),
     // Prop accessors/getters
     getHeaderProps,
     getExpandHeaderProps,
@@ -660,6 +576,10 @@ DataTable.TableToolbarContent = TableToolbarContent;
 DataTable.TableToolbarSearch = TableToolbarSearch;
 DataTable.TableToolbarMenu = TableToolbarMenu;
 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
    */
@@ -695,6 +615,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(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
@@ -721,13 +648,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/es/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/es/components/DataTable/Table.js

@@ -166,7 +166,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/es/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/es/components/DataTable/TableExpandHeader.js

@@ -12,7 +12,7 @@ import PropTypes from 'prop-types';
 import React from 'react';
 import { usePrefix } from '../../internal/usePrefix.js';
 import { deprecate } from '../../prop-types/deprecate.js';
-import requiredIfGivenPropIsTruthy from '../../prop-types/requiredIfGivenPropIsTruthy.js';
+import { requiredIfGivenPropIsTruthy } from '../../prop-types/requiredIfGivenPropIsTruthy.js';
 
 const TableExpandHeader = ({
   ['aria-controls']: ariaControls,

package/es/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/es/components/DatePicker/DatePicker.js

@@ -14,7 +14,7 @@ import l10n from 'flatpickr/dist/l10n/index';
 import DatePickerInput from '../DatePickerInput/DatePickerInput.js';
 import { appendToPlugin } from './plugins/appendToPlugin.js';
 import carbonFlatpickrFixEventsPlugin from './plugins/fixEventsPlugin.js';
-import carbonFlatpickrRangePlugin from './plugins/rangePlugin.js';
+import { rangePlugin } from './plugins/rangePlugin.js';
 import { deprecate } from '../../prop-types/deprecate.js';
 import { Escape, Tab, Enter } from '../../internal/keyboard/keys.js';
 import { match } from '../../internal/keyboard/match.js';
@@ -354,8 +354,8 @@ const DatePicker = /*#__PURE__*/React.forwardRef(function DatePicker({
       minDate: minDate,
       maxDate: maxDate,
       parseDate: parseDate,
-      plugins: [datePickerType === 'range' ? carbonFlatpickrRangePlugin({
-        input: endInputField.current
+      plugins: [datePickerType === 'range' ? rangePlugin({
+        input: endInputField.current ?? undefined
       }) : () => {}, appendTo ? appendToPlugin({
         appendTo
       }) : () => {}, carbonFlatpickrMonthSelectPlugin({

package/es/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;
+};