feat(settings-row,heading): surface headingType prop on components

surfaces the `headingType` prop on the `SettingsRow` and `Heading` components to provide consumers
with the ability to specify which level of section headings they wish to apply from h1 to h6.

BREAKING CHANGE: default heading level on `SettingsRow` is changed from `h1` to `h4`

fix #5723

src/components/heading/heading.component.tsx

@@ -20,6 +20,7 @@ import {
 } from "./heading.style";
 import useLocale from "../../hooks/__internal__/useLocale";
 
+export type HeadingType = "h1" | "h2" | "h3" | "h4" | "h5";
 export interface HeadingProps extends MarginProps, TagProps {
   /** Child elements */
   children?: React.ReactNode;
@@ -31,6 +32,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. */
@@ -66,6 +69,7 @@ export const Heading = ({
   separator = false,
   subheader,
   subtitleId,
+  headingType = "h1",
   title,
   titleId,
   ...rest
@@ -141,7 +145,7 @@ export const Heading = ({
         <StyledHeaderContent>
           <StyledHeadingTitle
             withMargin={!!pills || !!help}
-            variant="h1"
+            variant={headingType}
             data-element="title"
             id={titleId}
           >

src/components/heading/heading.spec.tsx

@@ -1,6 +1,6 @@
 import React from "react";
 import { shallow, mount, ReactWrapper } from "enzyme";
-import Heading from ".";
+import Heading, { HeadingType } from ".";
 import {
   StyledHeader,
   StyledSubHeader,
@@ -41,6 +41,19 @@ describe("Heading", () => {
     });
   });
 
+  describe("when headingType prop is provided", () => {
+    it.each<HeadingType>(["h1", "h2", "h3", "h4", "h5"])(
+      "HTML heading element is correct when headingType is %s",
+      (headingType) => {
+        const wrapper = mount(
+          <Heading headingType={headingType} title="foo" />
+        );
+
+        expect(wrapper.find(headingType).text()).toBe("foo");
+      }
+    );
+  });
+
   describe("when the help prop is provided", () => {
     it("renders a help component", () => {
       const wrapper = mount(

src/components/heading/heading.stories.mdx

@@ -42,6 +42,17 @@ import Heading from "carbon-react/lib/components/heading";
   </Story>
 </Canvas>
 
+### Heading with headingType
+
+The `headingType` prop sets the HTML heading element which is rendered on the page. It can take values `"h1"` up to `"h5"`.
+
+<Canvas>
+  <Story name="with headingType">
+    <Heading headingType="h4" title="This is a h4 Title" />
+  </Story>
+</Canvas>
+
+
 ### Heading without Divider
 
 <Canvas>

src/components/heading/heading.test.js

@@ -152,6 +152,19 @@ context("Testing Heading component", () => {
       }
     );
 
+    describe("when headingType prop is provided", () => {
+      it.each(["h1", "h2", "h3", "h4", "h5"])(
+        "should check HTML heading element is correct when headingType is %s",
+        (headingType) => {
+          CypressMountWithProviders(
+            <HeadingComponent headingType={headingType} title="foo" />
+          );
+
+          cy.get(headingType).contains("foo");
+        }
+      );
+    });
+
     describe("should render Heading component and check accessibility issues", () => {
       it("should check heading accessibility", () => {
         CypressMountWithProviders(<HeadingComponent />);

src/components/heading/index.ts

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

src/components/settings-row/settings-row.component.js

@@ -17,6 +17,7 @@ const marginPropTypes = filterStyledSystemMarginProps(
 
 const SettingsRow = ({
   title,
+  headingType = "h4",
   description,
   children,
   className,
@@ -28,6 +29,7 @@ const SettingsRow = ({
 
     return (
       <Heading
+        headingType={headingType}
         title={title}
         subheader={description}
         separator={description !== undefined}
@@ -58,6 +60,8 @@ SettingsRow.propTypes = {
   className: PropTypes.string,
   /**  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,
   /** Shows a divider below the component. */

src/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. */

src/components/settings-row/settings-row.spec.js

@@ -20,6 +20,7 @@ describe("SettingsRow", () => {
   describe("render", () => {
     const name = "foobar-row";
     const title = "Some Title";
+    const description = <span>Some descriptive text</span>;
     const childId = "my_child";
     const children = <span id={childId} />;
     let wrapper = shallow(
@@ -58,7 +59,6 @@ describe("SettingsRow", () => {
     });
 
     describe("when description is provided", () => {
-      const description = <span>Some descriptive text</span>;
       let head;
 
       beforeEach(() => {
@@ -77,6 +77,25 @@ describe("SettingsRow", () => {
       });
     });
 
+    describe("when headingType prop is provided", () => {
+      it.each(["h1", "h2", "h3", "h4", "h5"])(
+        "HTML heading element is correct when headingType is %s",
+        (headingType) => {
+          wrapper = mount(
+            <SettingsRow
+              headingType={headingType}
+              title={title}
+              description={description}
+            >
+              Content for settings
+            </SettingsRow>
+          );
+
+          expect(wrapper.find(headingType).text()).toBe(title);
+        }
+      );
+    });
+
     describe("when title is not provided", () => {
       it("does not render a header", () => {
         wrapper = shallow(

src/components/settings-row/settings-row.stories.mdx

@@ -44,6 +44,17 @@ All `children` are rendered in the input column to the right of the header colum
   </Story>
 </Canvas>
 
+### with HeadingType
+
+The `headingType` prop sets the HTML heading element of the  `title` within the component which is rendered on the page. It can take values `"h1"` up to `"h5"`.
+<Canvas>
+  <Story name="headingType">
+    <SettingsRow headingType="h3" description="Description" title="This is a h3 Title">
+      Content for settings
+    </SettingsRow>
+  </Story>
+</Canvas>
+
 ## Props
 
 ### Settings Row

src/components/settings-row/settings-row.test.js

@@ -27,6 +27,21 @@ context("Tests for SettingsRow component", () => {
       }
     );
 
+    it.each(["h1", "h2", "h3", "h4", "h5"])(
+      "should check HTML heading element is correct when headingType is %s",
+      (headingType) => {
+        CypressMountWithProviders(
+          <SettingsRowComponent
+            headingType={headingType}
+            title="foo"
+            description="bar"
+          />
+        );
+
+        cy.get(headingType).contains("foo");
+      }
+    );
+
     it.each(testData)(
       "should check %s as description for SettingsRow component",
       (description) => {