carbon-react 114.14.1 → 114.16.0

package/esm/components/heading/heading.component.d.ts

@@ -1,6 +1,7 @@
 import React from "react";
 import { MarginProps } from "styled-system";
 import { TagProps } from "../../__internal__/utils/helpers/tags/tags";
+export declare type HeadingType = "h1" | "h2" | "h3" | "h4" | "h5";
 export interface HeadingProps extends MarginProps, TagProps {
     /** Child elements */
     children?: React.ReactNode;
@@ -12,6 +13,8 @@ export interface HeadingProps extends MarginProps, TagProps {
     subheader?: React.ReactNode;
     /** Defines the subtitle id for the heading. */
     subtitleId?: string;
+    /** Defines the HTML heading element of the title. */
+    headingType?: HeadingType;
     /** Defines the help text for the heading. */
     help?: string;
     /** Defines the help link for the heading. */
@@ -27,5 +30,5 @@ export interface HeadingProps extends MarginProps, TagProps {
     /** Aria label for rendered help component */
     helpAriaLabel?: string;
 }
-export declare const Heading: ({ children, backLink, divider, help, helpAriaLabel, helpLink, pills, separator, subheader, subtitleId, title, titleId, ...rest }: HeadingProps) => JSX.Element | null;
+export declare const Heading: ({ children, backLink, divider, help, helpAriaLabel, helpLink, pills, separator, subheader, subtitleId, headingType, title, titleId, ...rest }: HeadingProps) => JSX.Element | null;
 export default Heading;

package/esm/components/heading/heading.component.js

@@ -18,6 +18,7 @@ const Heading = ({
   separator = false,
   subheader,
   subtitleId,
+  headingType = "h1",
   title,
   titleId,
   ...rest
@@ -76,7 +77,7 @@ const Heading = ({
     hasBackLink: !!backLink
   }, backLink && getBackButton(), /*#__PURE__*/React.createElement(StyledHeaderContent, null, /*#__PURE__*/React.createElement(StyledHeadingTitle, {
     withMargin: !!pills || !!help,
-    variant: "h1",
+    variant: headingType,
     "data-element": "title",
     id: titleId
   }, title), (help || helpLink) && getHelp(), pills && getPills()), separator && /*#__PURE__*/React.createElement(StyledSeparator, null), subheader && getSubheader()), divider && /*#__PURE__*/React.createElement(StyledDivider, {
@@ -91,6 +92,7 @@ Heading.propTypes = {
   "data-element": PropTypes.string,
   "data-role": PropTypes.string,
   "divider": PropTypes.bool,
+  "headingType": PropTypes.oneOf(["h1", "h2", "h3", "h4", "h5"]),
   "help": PropTypes.string,
   "helpAriaLabel": PropTypes.string,
   "helpLink": PropTypes.string,

package/esm/components/heading/index.d.ts

@@ -1,2 +1,2 @@
 export { default } from "./heading.component";
-export type { HeadingProps } from "./heading.component";
+export type { HeadingProps, HeadingType } from "./heading.component";

package/esm/components/select/filterable-select/filterable-select.component.js

@@ -12,6 +12,7 @@ import SelectList from "../select-list/select-list.component";
 import isExpectedOption from "../utils/is-expected-option";
 import isNavigationKey from "../utils/is-navigation-key";
 import Logger from "../../../__internal__/utils/logger";
+import useStableCallback from "../../../hooks/__internal__/useStableCallback";
 let deprecateInputRefWarnTriggered = false;
 const FilterableSelectList = withFilter(SelectList);
 const FilterableSelect = /*#__PURE__*/React.forwardRef(({
@@ -21,9 +22,9 @@ const FilterableSelect = /*#__PURE__*/React.forwardRef(({
   name,
   label,
   children,
-  onOpen,
+  onOpen: onOpenProp,
   onChange,
-  onFilterChange,
+  onFilterChange: onFilterChangeProp,
   onClick,
   onKeyDown,
   onFocus,
@@ -206,13 +207,14 @@ const FilterableSelect = /*#__PURE__*/React.forwardRef(({
     // eslint-disable-next-line react-hooks/exhaustive-deps
 
   }, [value, onChange, children]);
+  const onOpen = useStableCallback(onOpenProp);
   useEffect(() => {
     if (!isOpen) {
       setFilterText("");
     } else if (onOpen) {
       onOpen();
     }
-  }, [isOpen, onOpen]);
+  }, [onOpen, isOpen]);
   useEffect(() => {
     const hasListActionButton = listActionButton !== undefined;
     const onListActionMissingMessage = "onListAction prop required when using listActionButton prop";
@@ -225,11 +227,16 @@ const FilterableSelect = /*#__PURE__*/React.forwardRef(({
     // eslint-disable-next-line react-hooks/exhaustive-deps
 
   }, [value, children]);
+  const onFilterChange = useStableCallback(onFilterChangeProp);
+  const isFirstRender = useRef(true);
   useEffect(() => {
-    if (onFilterChange) {
+    if (onFilterChange && !isFirstRender.current) {
       onFilterChange(filterText);
     }
-  }, [filterText, onFilterChange]);
+  }, [onFilterChange, filterText]);
+  useEffect(() => {
+    isFirstRender.current = false;
+  }, []);
   useEffect(() => {
     const clickEvent = "click";
     window.addEventListener(clickEvent, handleGlobalClick);
@@ -308,10 +315,6 @@ const FilterableSelect = /*#__PURE__*/React.forwardRef(({
           return true;
         }
 
-        if (onOpen) {
-          onOpen();
-        }
-
         if (onFocus && !isInputFocused.current) {
           triggerFocus();
           isInputFocused.current = true;

package/esm/components/select/multi-select/multi-select.component.js

@@ -14,6 +14,7 @@ import isExpectedOption from "../utils/is-expected-option";
 import isExpectedValue from "../utils/is-expected-value";
 import isNavigationKey from "../utils/is-navigation-key";
 import Logger from "../../../__internal__/utils/logger";
+import useStableCallback from "../../../hooks/__internal__/useStableCallback";
 let deprecateInputRefWarnTriggered = false;
 const FilterableSelectList = withFilter(SelectList);
 const MultiSelect = /*#__PURE__*/React.forwardRef(({
@@ -25,7 +26,7 @@ const MultiSelect = /*#__PURE__*/React.forwardRef(({
   readOnly,
   children,
   onOpen,
-  onFilterChange,
+  onFilterChange: onFilterChangeProp,
   onChange,
   onClick,
   onFocus,
@@ -245,11 +246,16 @@ const MultiSelect = /*#__PURE__*/React.forwardRef(({
       window.removeEventListener(clickEvent, handleGlobalClick);
     };
   }, [handleGlobalClick]);
+  const onFilterChange = useStableCallback(onFilterChangeProp);
+  const isFirstRender = useRef(true);
   useEffect(() => {
-    if (onFilterChange) {
+    if (onFilterChange && !isFirstRender.current) {
       onFilterChange(filterText);
     }
-  }, [filterText, onFilterChange]);
+  }, [onFilterChange, filterText]);
+  useEffect(() => {
+    isFirstRender.current = false;
+  }, []);
 
   function handleTextboxClick(event) {
     isMouseDownReported.current = false;

package/esm/components/settings-row/settings-row.component.js

@@ -11,6 +11,7 @@ const marginPropTypes = filterStyledSystemMarginProps(styledSystemPropTypes.spac
 
 const SettingsRow = ({
   title,
+  headingType = "h3",
   description,
   children,
   className,
@@ -20,6 +21,7 @@ const SettingsRow = ({
   const heading = () => {
     if (!title) return null;
     return /*#__PURE__*/React.createElement(Heading, {
+      headingType: headingType,
       title: title,
       subheader: description,
       separator: description !== undefined,
@@ -46,6 +48,9 @@ SettingsRow.propTypes = { ...marginPropTypes,
   /**  A title for this group of settings. */
   title: PropTypes.string,
 
+  /** Defines the HTML heading element of the `title` within the component. */
+  headingType: PropTypes.oneOf(["h1", "h2", "h3", "h4", "h5"]),
+
   /**  A string or JSX object that provides a short description about the group of settings. */
   description: PropTypes.node,
 

package/esm/components/settings-row/settings-row.d.ts

@@ -1,10 +1,13 @@
 import * as React from "react";
+import { HeadingType } from "../heading";
 
 export interface SettingsRowProps {
   /**  The CSS classes to apply to the component. */
   className?: string;
   /**  A title for this group of settings. */
   title?: string;
+  /** Defines the HTML heading element of the `title` within the component. */
+  headingType?: HeadingType;
   /**  A string or JSX object that provides a short description about the group of settings. */
   description?: React.ReactNode;
   /** Shows a divider below the component. */

package/esm/components/settings-row/settings-row.style.js

@@ -1,7 +1,7 @@
 import styled, { css } from "styled-components";
 import { margin } from "styled-system";
 import baseTheme from "../../style/themes/base";
-import { StyledHeader, StyledHeadingTitle, StyledSeparator } from "../heading/heading.style";
+import { StyledHeader, StyledSeparator } from "../heading/heading.style";
 export const StyledSettingsRow = styled.div`
   ${margin}
 
@@ -24,15 +24,6 @@ export const StyledSettingsRow = styled.div`
     margin-bottom: 0;
   }
 
-  ${StyledHeadingTitle} {
-    color: var(--colorsUtilityYin090);
-    font-size: 15px;
-    font-weight: bold;
-    line-height: 18px;
-    margin-bottom: 10px;
-    text-transform: uppercase;
-  }
-
   ${StyledSeparator} {
     margin-bottom: 17px;
   }

package/esm/hooks/__internal__/useStableCallback/index.d.ts

@@ -0,0 +1 @@
+export { default } from "./useStableCallback";

package/esm/hooks/__internal__/useStableCallback/index.js

@@ -0,0 +1 @@
+export { default } from "./useStableCallback";

package/esm/hooks/__internal__/useStableCallback/useStableCallback.d.ts

@@ -0,0 +1,2 @@
+export declare function useStableCallback(callback?: (...args: unknown[]) => unknown): ((...args: any[]) => unknown) | undefined;
+export default useStableCallback;

package/esm/hooks/__internal__/useStableCallback/useStableCallback.js

@@ -0,0 +1,14 @@
+import { useRef, useCallback } from "react"; // This is a hook that returns a memoized callback that is guaranteed to be the same reference between renders.
+// This is useful when a stable reference is required to prevent unnecessary re-renders.
+
+export function useStableCallback(callback) {
+  const ref = useRef(callback);
+  ref.current = callback;
+  const stableCallback = useCallback((...args) => {
+    var _ref$current;
+
+    return (_ref$current = ref.current) === null || _ref$current === void 0 ? void 0 : _ref$current.call(ref, ...args);
+  }, []);
+  return callback ? stableCallback : undefined;
+}
+export default useStableCallback;

package/lib/components/heading/heading.component.d.ts

@@ -1,6 +1,7 @@
 import React from "react";
 import { MarginProps } from "styled-system";
 import { TagProps } from "../../__internal__/utils/helpers/tags/tags";
+export declare type HeadingType = "h1" | "h2" | "h3" | "h4" | "h5";
 export interface HeadingProps extends MarginProps, TagProps {
     /** Child elements */
     children?: React.ReactNode;
@@ -12,6 +13,8 @@ export interface HeadingProps extends MarginProps, TagProps {
     subheader?: React.ReactNode;
     /** Defines the subtitle id for the heading. */
     subtitleId?: string;
+    /** Defines the HTML heading element of the title. */
+    headingType?: HeadingType;
     /** Defines the help text for the heading. */
     help?: string;
     /** Defines the help link for the heading. */
@@ -27,5 +30,5 @@ export interface HeadingProps extends MarginProps, TagProps {
     /** Aria label for rendered help component */
     helpAriaLabel?: string;
 }
-export declare const Heading: ({ children, backLink, divider, help, helpAriaLabel, helpLink, pills, separator, subheader, subtitleId, title, titleId, ...rest }: HeadingProps) => JSX.Element | null;
+export declare const Heading: ({ children, backLink, divider, help, helpAriaLabel, helpLink, pills, separator, subheader, subtitleId, headingType, title, titleId, ...rest }: HeadingProps) => JSX.Element | null;
 export default Heading;

package/lib/components/heading/heading.component.js

@@ -32,6 +32,7 @@ const Heading = ({
   separator = false,
   subheader,
   subtitleId,
+  headingType = "h1",
   title,
   titleId,
   ...rest
@@ -90,7 +91,7 @@ const Heading = ({
     hasBackLink: !!backLink
   }, backLink && getBackButton(), /*#__PURE__*/_react.default.createElement(_heading.StyledHeaderContent, null, /*#__PURE__*/_react.default.createElement(_heading.StyledHeadingTitle, {
     withMargin: !!pills || !!help,
-    variant: "h1",
+    variant: headingType,
     "data-element": "title",
     id: titleId
   }, title), (help || helpLink) && getHelp(), pills && getPills()), separator && /*#__PURE__*/_react.default.createElement(_heading.StyledSeparator, null), subheader && getSubheader()), divider && /*#__PURE__*/_react.default.createElement(_heading.StyledDivider, {
@@ -106,6 +107,7 @@ Heading.propTypes = {
   "data-element": _propTypes.default.string,
   "data-role": _propTypes.default.string,
   "divider": _propTypes.default.bool,
+  "headingType": _propTypes.default.oneOf(["h1", "h2", "h3", "h4", "h5"]),
   "help": _propTypes.default.string,
   "helpAriaLabel": _propTypes.default.string,
   "helpLink": _propTypes.default.string,

package/lib/components/heading/index.d.ts

@@ -1,2 +1,2 @@
 export { default } from "./heading.component";
-export type { HeadingProps } from "./heading.component";
+export type { HeadingProps, HeadingType } from "./heading.component";

package/lib/components/select/filterable-select/filterable-select.component.js

@@ -29,6 +29,8 @@ var _isNavigationKey = _interopRequireDefault(require("../utils/is-navigation-ke
 
 var _logger = _interopRequireDefault(require("../../../__internal__/utils/logger"));
 
+var _useStableCallback = _interopRequireDefault(require("../../../hooks/__internal__/useStableCallback"));
+
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 
 function _getRequireWildcardCache() { if (typeof WeakMap !== "function") return null; var cache = new WeakMap(); _getRequireWildcardCache = function () { return cache; }; return cache; }
@@ -47,9 +49,9 @@ const FilterableSelect = /*#__PURE__*/_react.default.forwardRef(({
   name,
   label,
   children,
-  onOpen,
+  onOpen: onOpenProp,
   onChange,
-  onFilterChange,
+  onFilterChange: onFilterChangeProp,
   onClick,
   onKeyDown,
   onFocus,
@@ -233,13 +235,14 @@ const FilterableSelect = /*#__PURE__*/_react.default.forwardRef(({
     // eslint-disable-next-line react-hooks/exhaustive-deps
 
   }, [value, onChange, children]);
+  const onOpen = (0, _useStableCallback.default)(onOpenProp);
   (0, _react.useEffect)(() => {
     if (!isOpen) {
       setFilterText("");
     } else if (onOpen) {
       onOpen();
     }
-  }, [isOpen, onOpen]);
+  }, [onOpen, isOpen]);
   (0, _react.useEffect)(() => {
     const hasListActionButton = listActionButton !== undefined;
     const onListActionMissingMessage = "onListAction prop required when using listActionButton prop";
@@ -252,11 +255,16 @@ const FilterableSelect = /*#__PURE__*/_react.default.forwardRef(({
     // eslint-disable-next-line react-hooks/exhaustive-deps
 
   }, [value, children]);
+  const onFilterChange = (0, _useStableCallback.default)(onFilterChangeProp);
+  const isFirstRender = (0, _react.useRef)(true);
   (0, _react.useEffect)(() => {
-    if (onFilterChange) {
+    if (onFilterChange && !isFirstRender.current) {
       onFilterChange(filterText);
     }
-  }, [filterText, onFilterChange]);
+  }, [onFilterChange, filterText]);
+  (0, _react.useEffect)(() => {
+    isFirstRender.current = false;
+  }, []);
   (0, _react.useEffect)(() => {
     const clickEvent = "click";
     window.addEventListener(clickEvent, handleGlobalClick);
@@ -335,10 +343,6 @@ const FilterableSelect = /*#__PURE__*/_react.default.forwardRef(({
           return true;
         }
 
-        if (onOpen) {
-          onOpen();
-        }
-
         if (onFocus && !isInputFocused.current) {
           triggerFocus();
           isInputFocused.current = true;

package/lib/components/select/multi-select/multi-select.component.js

@@ -33,6 +33,8 @@ var _isNavigationKey = _interopRequireDefault(require("../utils/is-navigation-ke
 
 var _logger = _interopRequireDefault(require("../../../__internal__/utils/logger"));
 
+var _useStableCallback = _interopRequireDefault(require("../../../hooks/__internal__/useStableCallback"));
+
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 
 function _getRequireWildcardCache() { if (typeof WeakMap !== "function") return null; var cache = new WeakMap(); _getRequireWildcardCache = function () { return cache; }; return cache; }
@@ -53,7 +55,7 @@ const MultiSelect = /*#__PURE__*/_react.default.forwardRef(({
   readOnly,
   children,
   onOpen,
-  onFilterChange,
+  onFilterChange: onFilterChangeProp,
   onChange,
   onClick,
   onFocus,
@@ -275,11 +277,16 @@ const MultiSelect = /*#__PURE__*/_react.default.forwardRef(({
       window.removeEventListener(clickEvent, handleGlobalClick);
     };
   }, [handleGlobalClick]);
+  const onFilterChange = (0, _useStableCallback.default)(onFilterChangeProp);
+  const isFirstRender = (0, _react.useRef)(true);
   (0, _react.useEffect)(() => {
-    if (onFilterChange) {
+    if (onFilterChange && !isFirstRender.current) {
       onFilterChange(filterText);
     }
-  }, [filterText, onFilterChange]);
+  }, [onFilterChange, filterText]);
+  (0, _react.useEffect)(() => {
+    isFirstRender.current = false;
+  }, []);
 
   function handleTextboxClick(event) {
     isMouseDownReported.current = false;

package/lib/components/settings-row/settings-row.component.js

@@ -27,6 +27,7 @@ const marginPropTypes = (0, _utils.filterStyledSystemMarginProps)(_propTypes2.de
 
 const SettingsRow = ({
   title,
+  headingType = "h3",
   description,
   children,
   className,
@@ -36,6 +37,7 @@ const SettingsRow = ({
   const heading = () => {
     if (!title) return null;
     return /*#__PURE__*/_react.default.createElement(_heading.default, {
+      headingType: headingType,
       title: title,
       subheader: description,
       separator: description !== undefined,
@@ -62,6 +64,9 @@ SettingsRow.propTypes = { ...marginPropTypes,
   /**  A title for this group of settings. */
   title: _propTypes.default.string,
 
+  /** Defines the HTML heading element of the `title` within the component. */
+  headingType: _propTypes.default.oneOf(["h1", "h2", "h3", "h4", "h5"]),
+
   /**  A string or JSX object that provides a short description about the group of settings. */
   description: _propTypes.default.node,
 

package/lib/components/settings-row/settings-row.d.ts

@@ -1,10 +1,13 @@
 import * as React from "react";
+import { HeadingType } from "../heading";
 
 export interface SettingsRowProps {
   /**  The CSS classes to apply to the component. */
   className?: string;
   /**  A title for this group of settings. */
   title?: string;
+  /** Defines the HTML heading element of the `title` within the component. */
+  headingType?: HeadingType;
   /**  A string or JSX object that provides a short description about the group of settings. */
   description?: React.ReactNode;
   /** Shows a divider below the component. */

package/lib/components/settings-row/settings-row.style.js

@@ -41,15 +41,6 @@ const StyledSettingsRow = _styledComponents.default.div`
     margin-bottom: 0;
   }
 
-  ${_heading.StyledHeadingTitle} {
-    color: var(--colorsUtilityYin090);
-    font-size: 15px;
-    font-weight: bold;
-    line-height: 18px;
-    margin-bottom: 10px;
-    text-transform: uppercase;
-  }
-
   ${_heading.StyledSeparator} {
     margin-bottom: 17px;
   }

package/lib/hooks/__internal__/useStableCallback/index.d.ts

@@ -0,0 +1 @@
+export { default } from "./useStableCallback";

package/lib/hooks/__internal__/useStableCallback/index.js

@@ -0,0 +1,15 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "default", {
+  enumerable: true,
+  get: function () {
+    return _useStableCallback.default;
+  }
+});
+
+var _useStableCallback = _interopRequireDefault(require("./useStableCallback"));
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }

package/lib/hooks/__internal__/useStableCallback/package.json

@@ -0,0 +1,6 @@
+{
+  "sideEffects": false,
+  "module": "../../../../esm/hooks/__internal__/useStableCallback/index.js",
+  "main": "./index.js",
+  "types": "./index.d.ts"
+}

package/lib/hooks/__internal__/useStableCallback/useStableCallback.d.ts

@@ -0,0 +1,2 @@
+export declare function useStableCallback(callback?: (...args: unknown[]) => unknown): ((...args: any[]) => unknown) | undefined;
+export default useStableCallback;

package/lib/hooks/__internal__/useStableCallback/useStableCallback.js

@@ -0,0 +1,25 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useStableCallback = useStableCallback;
+exports.default = void 0;
+
+var _react = require("react");
+
+// This is a hook that returns a memoized callback that is guaranteed to be the same reference between renders.
+// This is useful when a stable reference is required to prevent unnecessary re-renders.
+function useStableCallback(callback) {
+  const ref = (0, _react.useRef)(callback);
+  ref.current = callback;
+  const stableCallback = (0, _react.useCallback)((...args) => {
+    var _ref$current;
+
+    return (_ref$current = ref.current) === null || _ref$current === void 0 ? void 0 : _ref$current.call(ref, ...args);
+  }, []);
+  return callback ? stableCallback : undefined;
+}
+
+var _default = useStableCallback;
+exports.default = _default;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carbon-react",
-  "version": "114.14.1",
+  "version": "114.16.0",
   "description": "A library of reusable React components for easily building user interfaces.",
   "files": [
     "lib",
@@ -80,6 +80,7 @@
     "@storybook/theming": "^6.4.18",
     "@testing-library/jest-dom": "^5.16.2",
     "@testing-library/react": "^12.1.3",
+    "@testing-library/react-hooks": "^8.0.1",
     "@testing-library/user-event": "^14.4.3",
     "@types/crypto-js": "^4.1.1",
     "@types/draft-js": "^0.11.7",