@carbon/react 1.89.0 → 1.90.0-rc.0

package/es/components/Toggletip/index.js

@@ -8,7 +8,7 @@
 import { extends as _extends } from '../../_virtual/_rollupPluginBabelHelpers.js';
 import cx from 'classnames';
 import PropTypes from 'prop-types';
-import React, { useContext, useRef, useState } from 'react';
+import React, { useContext, useRef, useState, useEffect } from 'react';
 import { Popover, PopoverContent } from '../Popover/index.js';
 import { Escape } from '../../internal/keyboard/keys.js';
 import { match } from '../../internal/keyboard/match.js';
@@ -127,13 +127,24 @@ function Toggletip({
       actions.close();
     }
   });
-  useWindowEvent('click', ({
-    target
-  }) => {
-    if (open && target instanceof Node && !ref.current?.contains(target)) {
-      actions.close();
-    }
-  });
+  useEffect(() => {
+    if (!ref.current) return;
+    const targetDocument = ref.current.ownerDocument || document;
+    const eventType = 'PointerEvent' in window ? 'pointerdown' : 'mousedown';
+    const handleOutsideClick = event => {
+      const node = event.target;
+      if (open && node && !ref.current.contains(node)) {
+        setOpen(false);
+      }
+    };
+    const options = {
+      capture: true
+    };
+    targetDocument.addEventListener(eventType, handleOutsideClick, options);
+    return () => {
+      targetDocument.removeEventListener(eventType, handleOutsideClick, options);
+    };
+  }, [open]);
   return /*#__PURE__*/React.createElement(ToggletipContext.Provider, {
     value: value
   }, /*#__PURE__*/React.createElement(Popover, _extends({

package/es/components/TreeView/TreeNode.d.ts

@@ -11,6 +11,9 @@ export type TreeNodeProps = {
     /**
      * **Note:** this is controlled by the parent TreeView component, do not set manually.
      * The ID of the active node in the tree
+     *
+     * @deprecated The `active` prop for `TreeNode` has
+     * been deprecated after the introduction of context. It will be removed in the next major release.
      */
     active?: string | number;
     /**
@@ -29,6 +32,9 @@ export type TreeNodeProps = {
     /**
      * **Note:** this is controlled by the parent TreeView component, do not set manually.
      * TreeNode depth to determine spacing
+     *
+     * @deprecated The `depth` prop for `TreeNode` has
+     * been deprecated after the introduction of context. It will be removed in the next major release.
      */
     depth?: number;
     /**
@@ -49,6 +55,9 @@ export type TreeNodeProps = {
     label: React.ReactNode;
     /**
      * Callback function for when the node receives or loses focus
+     *
+     * @deprecated The `onNodeFocusEvent` prop for `TreeNode` has
+     * been deprecated after the introduction of context. It will be removed in the next major release.
      */
     onNodeFocusEvent?: (event: React.FocusEvent<HTMLElement>) => void;
     /**
@@ -61,6 +70,9 @@ export type TreeNodeProps = {
     onToggle?: UncontrolledOnToggle | ControlledOnToggle;
     /**
      * Callback function for when any node in the tree is selected
+     *
+     * @deprecated The `onTreeSelect` prop for `TreeNode` has
+     * been deprecated after the introduction of context. It will be removed in the next major release.
      */
     onTreeSelect?: (event: React.MouseEvent | React.KeyboardEvent, node: Pick<TreeNodeProps, 'id' | 'label' | 'value'>) => void;
     /**
@@ -70,6 +82,8 @@ export type TreeNodeProps = {
     /**
      * **Note:** this is controlled by the parent TreeView component, do not set manually.
      * Array containing all selected node IDs in the tree
+     * @deprecated The `selected` prop for `TreeNode` has
+     * been deprecated after the introduction of context. It will be removed in the next major release.
      */
     selected?: Array<string | number>;
     /**
@@ -97,6 +111,9 @@ declare const TreeNode: React.ForwardRefExoticComponent<{
     /**
      * **Note:** this is controlled by the parent TreeView component, do not set manually.
      * The ID of the active node in the tree
+     *
+     * @deprecated The `active` prop for `TreeNode` has
+     * been deprecated after the introduction of context. It will be removed in the next major release.
      */
     active?: string | number;
     /**
@@ -115,6 +132,9 @@ declare const TreeNode: React.ForwardRefExoticComponent<{
     /**
      * **Note:** this is controlled by the parent TreeView component, do not set manually.
      * TreeNode depth to determine spacing
+     *
+     * @deprecated The `depth` prop for `TreeNode` has
+     * been deprecated after the introduction of context. It will be removed in the next major release.
      */
     depth?: number;
     /**
@@ -135,6 +155,9 @@ declare const TreeNode: React.ForwardRefExoticComponent<{
     label: React.ReactNode;
     /**
      * Callback function for when the node receives or loses focus
+     *
+     * @deprecated The `onNodeFocusEvent` prop for `TreeNode` has
+     * been deprecated after the introduction of context. It will be removed in the next major release.
      */
     onNodeFocusEvent?: (event: React.FocusEvent<HTMLElement>) => void;
     /**
@@ -147,6 +170,9 @@ declare const TreeNode: React.ForwardRefExoticComponent<{
     onToggle?: UncontrolledOnToggle | ControlledOnToggle;
     /**
      * Callback function for when any node in the tree is selected
+     *
+     * @deprecated The `onTreeSelect` prop for `TreeNode` has
+     * been deprecated after the introduction of context. It will be removed in the next major release.
      */
     onTreeSelect?: (event: React.MouseEvent | React.KeyboardEvent, node: Pick<TreeNodeProps, "id" | "label" | "value">) => void;
     /**
@@ -156,6 +182,8 @@ declare const TreeNode: React.ForwardRefExoticComponent<{
     /**
      * **Note:** this is controlled by the parent TreeView component, do not set manually.
      * Array containing all selected node IDs in the tree
+     * @deprecated The `selected` prop for `TreeNode` has
+     * been deprecated after the introduction of context. It will be removed in the next major release.
      */
     selected?: Array<string | number>;
     /**

package/es/components/TreeView/TreeNode.js

@@ -12,6 +12,7 @@ import PropTypes from 'prop-types';
 import React, { useContext, useRef, useState, useEffect, useCallback } from 'react';
 import { ArrowLeft, ArrowRight, Enter, Space } from '../../internal/keyboard/keys.js';
 import { matches, match } from '../../internal/keyboard/match.js';
+import { deprecate } from '../../prop-types/deprecate.js';
 import { useControllableState } from '../../internal/useControllableState.js';
 import { usePrefix } from '../../internal/usePrefix.js';
 import { useId } from '../../internal/useId.js';
@@ -413,7 +414,7 @@ TreeNode.propTypes = {
    * **Note:** this is controlled by the parent TreeView component, do not set manually.
    * The ID of the active node in the tree
    */
-  active: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
+  active: deprecate(PropTypes.oneOfType([PropTypes.string, PropTypes.number]), 'The `active` prop for `TreeNode` is no longer needed and has ' + 'been deprecated. It will be removed in the next major release.'),
   /**
    * Specify the children of the TreeNode
    */
@@ -431,7 +432,7 @@ TreeNode.propTypes = {
    * **Note:** this is controlled by the parent TreeView component, do not set manually.
    * TreeNode depth to determine spacing
    */
-  depth: PropTypes.number,
+  depth: deprecate(PropTypes.number, 'The `depth` prop for `TreeNode` is no longer needed and has ' + 'been deprecated. It will be removed in the next major release.'),
   /**
    * Specify if the TreeNode is disabled
    */
@@ -451,7 +452,7 @@ TreeNode.propTypes = {
   /**
    * Callback function for when the node receives or loses focus
    */
-  onNodeFocusEvent: PropTypes.func,
+  onNodeFocusEvent: deprecate(PropTypes.func, 'The `onNodeFocusEvent` prop for `TreeNode` is no longer needed and has ' + 'been deprecated. It will be removed in the next major release.'),
   /**
    * Callback function for when the node is selected
    */
@@ -463,7 +464,7 @@ TreeNode.propTypes = {
   /**
    * Callback function for when any node in the tree is selected
    */
-  onTreeSelect: PropTypes.func,
+  onTreeSelect: deprecate(PropTypes.func, 'The `onTreeSelect` prop for `TreeNode` is no longer needed and has ' + 'been deprecated. It will be removed in the next major release.'),
   /**
    * A component used to render an icon.
    */
@@ -474,7 +475,7 @@ TreeNode.propTypes = {
    * Array containing all selected node IDs in the tree
    */
   // @ts-ignore
-  selected: PropTypes.arrayOf(PropTypes.oneOfType([PropTypes.string, PropTypes.number])),
+  selected: deprecate(PropTypes.arrayOf(PropTypes.oneOfType([PropTypes.string, PropTypes.number])), 'The `selected` prop for `TreeNode` is no longer needed and has ' + 'been deprecated. It will be removed in the next major release.'),
   /**
    * Specify the value of the TreeNode
    */

package/lib/components/ComposedModal/ComposedModal.js

@@ -170,9 +170,14 @@ const ComposedModal = /*#__PURE__*/React.forwardRef(function ComposedModal({
     } = evt;
     const mouseDownTarget = onMouseDownTarget.current;
     evt.stopPropagation();
-    const containsModalFooter = React.Children.toArray(childrenWithProps).some(child => utils.isComponentElement(child, ModalFooter.ModalFooter));
-    const isPassive = !containsModalFooter;
-    const shouldCloseOnOutsideClick = isPassive ? preventCloseOnClickOutside !== false : preventCloseOnClickOutside === true;
+    const shouldCloseOnOutsideClick =
+    // Passive modals can close on clicks outside the modal when
+    // preventCloseOnClickOutside is undefined or explicitly set to false.
+    isPassive && !preventCloseOnClickOutside ||
+    // Non-passive modals have to explicitly opt-in for close on outside
+    // behavior by explicitly setting preventCloseOnClickOutside to false,
+    // rather than just leaving it undefined.
+    !isPassive && preventCloseOnClickOutside === false;
     if (shouldCloseOnOutsideClick && target instanceof Node && !wrapFocus.elementOrParentIsFloatingMenu(target, selectorsFloatingMenus) && innerModal.current && !innerModal.current.contains(target) && !innerModal.current.contains(mouseDownTarget)) {
       closeModal(evt);
     }
@@ -256,6 +261,12 @@ const ComposedModal = /*#__PURE__*/React.forwardRef(function ComposedModal({
         return child;
     }
   });
+
+  // Modals without a footer are considered passive and carry limitations as
+  // outlined in the design spec.
+  const containsModalFooter = React.Children.toArray(childrenWithProps).some(child => utils.isComponentElement(child, ModalFooter.ModalFooter));
+  const isPassive = !containsModalFooter;
+  process.env.NODE_ENV !== "production" ? warning.warning(!(!isPassive && preventCloseOnClickOutside === false), '`<ComposedModal>` prop `preventCloseOnClickOutside` should not be ' + '`false` when `<ModalFooter>` is present. Transactional, non-passive ' + 'Modals should not be dissmissable by clicking outside. ' + 'See: https://carbondesignsystem.com/components/modal/usage/#transactional-modal') : void 0;
   React.useEffect(() => {
     if (!open) return;
     const handleEscapeKey = event => {

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

@@ -6,6 +6,7 @@
  */
 import PropTypes from 'prop-types';
 import React, { type ChangeEvent, type MouseEvent, type ReactElement, type ReactNode } from 'react';
+import { type SortRowFn } from './state/sorting';
 import type { DataTableSortState } from './state/sortStates';
 import { TranslateWithId } from '../../types/common';
 declare const translationKeys: {
@@ -181,13 +182,7 @@ export interface DataTableProps<RowType, ColTypes extends any[]> extends Transla
     render?: (renderProps: DataTableRenderProps<RowType, ColTypes>) => ReactElement;
     rows: Omit<DataTableRow<ColTypes>, 'cells'>[];
     size?: DataTableSize;
-    sortRow?: (cellA: any, cellB: any, options: {
-        sortDirection: DataTableSortState;
-        sortStates: Record<DataTableSortState, DataTableSortState>;
-        locale: string;
-        key: string;
-        compare: (a: number | string, b: number | string, locale?: string) => number;
-    }) => number;
+    sortRow?: SortRowFn;
     stickyHeader?: boolean;
     useStaticWidth?: boolean;
     useZebraStyles?: boolean;
@@ -286,7 +281,7 @@ export declare const DataTable: {
     };
     TableHead: (props: React.HTMLAttributes<"thead">) => React.ReactElement<any>;
     TableHeader: React.ForwardRefExoticComponent<import("./TableHeader").TableHeaderProps & React.RefAttributes<HTMLTableCellElement>>;
-    TableRow: React.ForwardRefExoticComponent<import("./TableRow").TableRowProps & React.RefAttributes<HTMLTableCellElement>>;
+    TableRow: React.ForwardRefExoticComponent<import("./TableRow").TableRowProps & React.RefAttributes<HTMLTableRowElement>>;
     TableSelectAll: {
         ({ ariaLabel: deprecatedAriaLabel, ["aria-label"]: ariaLabel, checked, id, indeterminate, name, onSelect, disabled, className, }: import("./TableSelectAll").TableSelectAllProps): import("react/jsx-runtime").JSX.Element;
         propTypes: {

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

@@ -4,13 +4,41 @@
  * 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 React, { type MouseEventHandler, type PropsWithChildren } from 'react';
-import { TableRowProps } from './TableRow';
-export interface TableExpandRowProps extends PropsWithChildren<TableRowProps> {
+import React, { type HTMLAttributes, type MouseEventHandler, type PropsWithChildren } from 'react';
+/** Props shared between `TableRow` and `TableExpandRow`. */
+export interface TableRowExpandInteropProps {
+    /**
+     * @deprecated Use `aria-label` instead.
+     */
+    ariaLabel?: string;
+    /**
+     * Specify the string read by a voice reader when the expand trigger is
+     * focused
+     */
+    'aria-label'?: string;
+    /**
+     * Space separated list of one or more ID values referencing the TableExpandedRow(s) being controlled by the TableExpandRow
+     */
+    'aria-controls'?: string;
+    /**
+     * Specify whether this row is expanded or not. This helps coordinate data
+     * attributes so that `TableExpandRow` and `TableExpandedRow` work together
+     */
+    isExpanded?: boolean;
+    /**
+     * Hook for when a listener initiates a request to expand the given row
+     */
+    onExpand?: MouseEventHandler<HTMLButtonElement>;
+    /**
+     * Specify if the row is selected.
+     */
+    isSelected?: boolean;
+}
+export interface TableExpandRowProps extends PropsWithChildren<Omit<HTMLAttributes<HTMLTableRowElement>, 'onClick'>>, Omit<TableRowExpandInteropProps, 'aria-label' | 'onExpand'> {
     /**
      * Space separated list of one or more ID values referencing the TableExpandedRow(s) being controlled by the TableExpandRow
      */
-    ['aria-controls']?: string;
+    'aria-controls'?: string;
     /**
      * @deprecated This prop has been deprecated and will be
      * removed in the next major release of Carbon. Use the
@@ -21,7 +49,7 @@ export interface TableExpandRowProps extends PropsWithChildren<TableRowProps> {
      * Specify the string read by a voice reader when the expand trigger is
      * focused
      */
-    ['aria-label']: string;
+    'aria-label': string;
     /**
      * The id of the matching th node in the table head. Addresses a11y concerns outlined here: https://www.ibm.com/able/guidelines/ci162/info_and_relationships.html and https://www.w3.org/TR/WCAG20-TECHS/H43
      */

package/lib/components/DataTable/TableExpandRow.js

@@ -21,6 +21,8 @@ var TableDecoratorRow = require('./TableDecoratorRow.js');
 var index = require('../AILabel/index.js');
 var utils = require('../../internal/utils.js');
 
+/** Props shared between `TableRow` and `TableExpandRow`. */
+
 const TableExpandRow = /*#__PURE__*/React.forwardRef(({
   ['aria-controls']: ariaControls,
   ['aria-label']: ariaLabel,
@@ -89,13 +91,13 @@ TableExpandRow.propTypes = {
    * Space separated list of one or more ID values referencing the TableExpandedRow(s) being controlled by the TableExpandRow
    * TODO: make this required in v12
    */
-  ['aria-controls']: PropTypes.string,
+  'aria-controls': PropTypes.string,
   /**
    * Specify the string read by a voice reader when the expand trigger is
    * focused
    */
   /**@ts-ignore*/
-  ['aria-label']: PropTypes.string,
+  'aria-label': PropTypes.string,
   /**
    * Deprecated, please use `aria-label` instead.
    * Specify the string read by a voice reader when the expand trigger is

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

@@ -5,9 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 import React, { type HTMLAttributes, type MouseEventHandler, type ReactNode } from 'react';
-import { sortStates } from './state/sorting';
 import { TranslateWithId } from '../../types/common';
-import { DataTableSortState } from './state/sortStates';
+import { sortStates, type DataTableSortState } from './state/sortStates';
 export type TableHeaderTranslationKey = 'carbon.table.header.icon.description';
 export interface TableHeaderTranslationArgs {
     header: ReactNode;

package/lib/components/DataTable/TableHeader.js

@@ -14,12 +14,11 @@ var cx = require('classnames');
 var PropTypes = require('prop-types');
 var React = require('react');
 var iconsReact = require('@carbon/icons-react');
-require('./state/sorting.js');
 var useId = require('../../internal/useId.js');
 var usePrefix = require('../../internal/usePrefix.js');
+var sortStates = require('./state/sortStates.js');
 var index = require('../AILabel/index.js');
 var utils = require('../../internal/utils.js');
-var sortStates = require('./state/sortStates.js');
 
 const defaultScope = 'col';
 const translationKeys = {

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

@@ -5,15 +5,12 @@
  * LICENSE file in the root directory of this source tree.
  */
 import React, { type HTMLAttributes } from 'react';
-export interface TableRowProps extends HTMLAttributes<HTMLTableRowElement> {
+import type { TableRowExpandInteropProps } from './TableExpandRow';
+export interface TableRowProps extends HTMLAttributes<HTMLTableRowElement>, TableRowExpandInteropProps {
     /**
      * Specify an optional className to be applied to the container node
      */
     className?: string;
-    /**
-     * Specify if the row is selected
-     */
-    isSelected?: boolean;
 }
-declare const TableRow: React.ForwardRefExoticComponent<TableRowProps & React.RefAttributes<HTMLTableCellElement>>;
+declare const TableRow: React.ForwardRefExoticComponent<TableRowProps & React.RefAttributes<HTMLTableRowElement>>;
 export default TableRow;

package/lib/components/DataTable/TableRow.js

@@ -19,28 +19,10 @@ var TableDecoratorRow = require('./TableDecoratorRow.js');
 var index = require('../AILabel/index.js');
 var utils = require('../../internal/utils.js');
 
-const TableRow = /*#__PURE__*/React.forwardRef((props, ref) => {
-  const prefix = usePrefix.usePrefix();
-  let rowHasAILabel;
-  if (props?.children) {
-    // TODO: Why is this loop a `map`? It's not returning anything. Ideally,
-    // it seems that it should be a `some`. Maybe I'm missing something?
-    React.Children.toArray(props.children).map(child => {
-      if (utils.isComponentElement(child, TableSlugRow.default)) {
-        if (child.props.slug) {
-          rowHasAILabel = true;
-        }
-      } else if (utils.isComponentElement(child, TableDecoratorRow.default) && utils.isComponentElement(child.props.decorator, index.AILabel)) {
-        rowHasAILabel = true;
-      }
-    });
-  }
+const frFn = React.forwardRef;
+const TableRow = frFn((props, ref) => {
   // Remove unnecessary props if provided to this component, these are
   // only useful in `TableExpandRow`
-  const className = cx(props.className, {
-    [`${prefix}--data-table--selected`]: props.isSelected,
-    [`${prefix}--data-table--slug-row ${prefix}--data-table--ai-label-row`]: rowHasAILabel
-  });
   const {
     ariaLabel,
     'aria-label': ariaLabelAlt,
@@ -50,6 +32,17 @@ const TableRow = /*#__PURE__*/React.forwardRef((props, ref) => {
     isSelected,
     ...cleanProps
   } = props;
+  const prefix = usePrefix.usePrefix();
+  const rowHasAILabel = React.Children.toArray(props.children).some(child => {
+    if (utils.isComponentElement(child, TableSlugRow.default)) {
+      return !!child.props.slug;
+    }
+    return utils.isComponentElement(child, TableDecoratorRow.default) && utils.isComponentElement(child.props.decorator, index.AILabel);
+  });
+  const className = cx(props.className, {
+    [`${prefix}--data-table--selected`]: isSelected,
+    [`${prefix}--data-table--slug-row ${prefix}--data-table--ai-label-row`]: rowHasAILabel
+  });
   if (className) {
     cleanProps.className = className;
   }
@@ -65,7 +58,27 @@ TableRow.propTypes = {
   /**
    * Specify if the row is selected
    */
-  isSelected: PropTypes.bool
+  isSelected: PropTypes.bool,
+  /**
+   * Non-standard alias for `aria-label`.
+   */
+  ariaLabel: PropTypes.string,
+  /**
+   * Accessible label for the row element.
+   */
+  'aria-label': PropTypes.string,
+  /**
+   * Associates this row with the id of the corresponding expanded row content.
+   */
+  'aria-controls': PropTypes.string,
+  /**
+   * Handler called when the row’s expand toggle is clicked.
+   */
+  onExpand: PropTypes.func,
+  /**
+   * Flag indicating whether the row is currently expanded.
+   */
+  isExpanded: PropTypes.bool
 };
 
 exports.default = TableRow;

package/lib/components/DataTable/state/sorting.d.ts

@@ -1,15 +1,56 @@
-export { sortStates };
-export const initialSortState: import("./sortStates").DataTableSortState;
-export function getNextSortDirection(prevHeader: string, header: string, prevState: string): string;
-export function getNextSortState(props: any, state: any, { key }: {
-    key: any;
-}): any;
-export function getSortedState(props: {
+/**
+ * Copyright IBM Corp. 2016, 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 DataTableSortState } from './sortStates';
+import type { DataTableCell } from '../DataTable';
+export interface SortRowParams {
+    key: string;
+    sortDirection: DataTableSortState;
+    sortStates: Record<DataTableSortState, DataTableSortState>;
     locale: string;
-    sortRows: Function;
-}, state: {
-    rowIds: Array<string>;
-    cellsById: object;
-    initialRowOrder: Array<string>;
-}, key: string, sortDirection: string): object;
-import { sortStates } from './sortStates';
+    compare: (a: string | number, b: string | number, locale?: string) => number;
+}
+export type SortRowFn = (cellA: any, cellB: any, options: SortRowParams) => number;
+interface Props {
+    locale?: string;
+    sortRow?: SortRowFn;
+}
+interface State<ColTypes extends any[]> {
+    rowIds: string[];
+    cellsById: Record<string, DataTableCell<ColTypes[number]>>;
+    initialRowOrder: string[];
+    sortHeaderKey: string | null;
+    sortDirection: DataTableSortState;
+}
+export declare const initialSortState: DataTableSortState;
+/**
+ * Gets the next sort direction for a header.
+ *
+ * @param prevHeader - Key of the previously sorted header.
+ * @param currentHeader - Key of the currently selected header.
+ * @param prevState - Previous sort direction.
+ */
+export declare const getNextSortDirection: (prevHeader: string, currentHeader: string, prevState: DataTableSortState) => DataTableSortState;
+/**
+ * Gets the next sort state.
+ *
+ * @param props - Component props.
+ * @param state - Current table state.
+ * @param key - Header key to sort by.
+ */
+export declare const getNextSortState: <ColTypes extends any[]>(props: Props, state: State<ColTypes>, { key }: {
+    key: string;
+}) => Pick<State<ColTypes>, "sortHeaderKey" | "sortDirection" | "rowIds">;
+/**
+ * Gets a sort state update.
+ *
+ * @param props - Component props.
+ * @param state - Current state of the table.
+ * @param key - Header key to sort by.
+ * @param sortDirection - Sort direction to apply.
+ */
+export declare const getSortedState: <ColTypes extends any[]>({ locale, sortRow }: Props, { rowIds, cellsById, initialRowOrder }: State<ColTypes>, key: string, sortDirection: DataTableSortState) => Pick<State<ColTypes>, "rowIds" | "sortDirection" | "sortHeaderKey">;
+export {};

package/lib/components/DataTable/state/sorting.js

@@ -10,37 +10,39 @@
 var sortStates = require('./sortStates.js');
 var sorting = require('../tools/sorting.js');
 
-// Our initialSortState should be `NONE`, unless a consumer has specified a
-// different initialSortState
 const initialSortState = sortStates.sortStates.NONE;
 
 /**
- * Utility used to get the next sort state given the following pieces of
- * information:
+ * Gets the next sort direction for a header.
  *
- * @param {string} prevHeader the value of the previous header
- * @param {string} header the value of the currently selected header
- * @param {string} prevState the previous sort state of the table
- * @returns {string}
+ * @param prevHeader - Key of the previously sorted header.
+ * @param currentHeader - Key of the currently selected header.
+ * @param prevState - Previous sort direction.
  */
-const getNextSortDirection = (prevHeader, header, prevState) => {
-  // If the previous header is equivalent to the current header, we know that we
-  // have to derive the next sort state from the previous sort state
-  if (prevHeader === header) {
-    // When transitioning, we know that the sequence of states is as follows:
-    // NONE -> ASC -> DESC -> NONE
-    if (prevState === 'NONE') {
-      return sortStates.sortStates.ASC;
+const getNextSortDirection = (prevHeader, currentHeader, prevState) => {
+  // Cycle for sorting the same header: NONE -> ASC -> DESC -> NONE.
+  if (prevHeader === currentHeader) {
+    switch (prevState) {
+      case sortStates.sortStates.NONE:
+        return sortStates.sortStates.ASC;
+      case sortStates.sortStates.ASC:
+        return sortStates.sortStates.DESC;
+      case sortStates.sortStates.DESC:
+        return sortStates.sortStates.NONE;
     }
-    if (prevState === 'ASC') {
-      return sortStates.sortStates.DESC;
-    }
-    return sortStates.sortStates.NONE;
   }
-  // Otherwise, we have selected a new header and need to start off by sorting
-  // in descending order by default
+
+  // Sorting a new header starts at ascending order.
   return sortStates.sortStates.ASC;
 };
+
+/**
+ * Gets the next sort state.
+ *
+ * @param props - Component props.
+ * @param state - Current table state.
+ * @param key - Header key to sort by.
+ */
 const getNextSortState = (props, state, {
   key
 }) => {
@@ -48,38 +50,26 @@ const getNextSortState = (props, state, {
     sortDirection,
     sortHeaderKey
   } = state;
-  const nextSortDirection = getNextSortDirection(key, sortHeaderKey, sortDirection);
+  const nextSortDirection = getNextSortDirection(key, sortHeaderKey ?? '', sortDirection);
   return getSortedState(props, state, key, nextSortDirection);
 };
 
 /**
- * Derive the set of sorted state fields from props and state for the given
- * header key and sortDirection
+ * Gets a sort state update.
  *
- * @param {object} props
- * @param {string} props.locale The current locale
- * @param {Function} props.sortRows Method to handle sorting a collection of
- * rows
- * @param {object} state
- * @param {Array<string>} state.rowIds Array of row ids
- * @param {object} state.cellsById Lookup object for cells by id
- * @param {Array<string>} state.initialRowOrder Initial row order for the
- * current set of rows
- * @param {string} key The key for the given header we are serving the
- * sorted state for
- * @param {string} sortDirection The sortState that we want to order by
- * @returns {object}
+ * @param props - Component props.
+ * @param state - Current state of the table.
+ * @param key - Header key to sort by.
+ * @param sortDirection - Sort direction to apply.
  */
-const getSortedState = (props, state, key, sortDirection) => {
-  const {
-    rowIds,
-    cellsById,
-    initialRowOrder
-  } = state;
-  const {
-    locale,
-    sortRow
-  } = props;
+const getSortedState = ({
+  locale,
+  sortRow
+}, {
+  rowIds,
+  cellsById,
+  initialRowOrder
+}, key, sortDirection) => {
   const nextRowIds = sortDirection !== sortStates.sortStates.NONE ? sorting.sortRows({
     rowIds,
     cellsById,
@@ -90,12 +80,11 @@ const getSortedState = (props, state, key, sortDirection) => {
   }) : initialRowOrder;
   return {
     sortHeaderKey: key,
-    sortDirection: sortDirection,
+    sortDirection,
     rowIds: nextRowIds
   };
 };
 
-exports.sortStates = sortStates.sortStates;
 exports.getNextSortDirection = getNextSortDirection;
 exports.getNextSortState = getNextSortState;
 exports.getSortedState = getSortedState;