fix(ui-heading): fix Heading rendering as H2 in most cases

Previously it was rendering h2 in lots of cases when it should not. Make the order more clear, add
documentation to it

To test: Check if Heading's DOM levels correspond to the logic stated in the documentation.

Fixes INSTUI-4657

Author: matyasf

packages/ui-heading/src/Heading/README.md

@@ -4,33 +4,39 @@ describes: Heading
 
 Heading is a component for creating typographic headings.
 
-## Variant
+### Variant
 
 Variant covers almost all use cases for headings on pages. Their name reflects the places they meant to be used. It takes care of the style of the heading
 
-NOTE 1: for legacy reasons, each `variant` has a default `level` set. This is not the recommended way and will be removed in a later major release. Please specify the `level` directly!
-
-NOTE 2: when `variant` is set the `as` prop is ignored
-
-IMPORTANT A11Y NOTE 1: there can be only one `h1` tag in a page
-
-IMPORTANT A11Y NOTE 2: `h` tags can not skip a level, so for example an `h1` followed by an `h3` not allowed
+```js
+---
+type: embed
+---
+<Alert variant="info">
+  <List margin="0 0 medium">
+    <List.Item>For legacy reasons, each <code>variant</code> has a default <code>level</code> set. This is not the recommended way and will be removed in a later major release. Please always specify the <code>level</code>!</List.Item>
+    <List.Item>When <code>variant</code> is set the <code>as</code> prop is ignored</List.Item>
+    <List.Item>A11Y GUIDELINE: There can be only one <code>h1</code> tag in a page</List.Item>
+    <List.Item>A11Y GUIDELINE: <code>h</code> tags can not skip a level, so for example an <code>h1</code> followed by an <code>h3</code> not allowed</List.Item>
+  </List>
+</Alert>
+```
 
 ```js
 ---
 type: example
 ---
   <div>
-    <Heading variant="titlePageDesktop"> titlePageDesktop </Heading><br/>
-    <Heading variant="titlePageMobile"> titlePageMobile </Heading><br/>
-    <Heading variant="titleSection"> titleSection </Heading><br/>
-    <Heading variant="titleCardSection"> titleCardSection </Heading><br/>
-    <Heading variant="titleModule"> titleModule </Heading><br/>
-    <Heading variant="titleCardLarge"> titleCardLarge </Heading><br/>
-    <Heading variant="titleCardRegular"> titleCardRegular </Heading><br/>
-    <Heading variant="titleCardMini"> titleCardMini </Heading><br/>
-    <Heading variant="label"> label </Heading><br/>
-    <Heading variant="labelInline"> labelInline </Heading><br/>
+    <Heading variant="titlePageDesktop" level="h1"> titlePageDesktop </Heading><br/>
+    <Heading variant="titlePageMobile" level="h1"> titlePageMobile </Heading><br/>
+    <Heading variant="titleSection" level="h2"> titleSection </Heading><br/>
+    <Heading variant="titleCardSection" level="h2"> titleCardSection </Heading><br/>
+    <Heading variant="titleModule" level="h2"> titleModule </Heading><br/>
+    <Heading variant="titleCardLarge" level="h3"> titleCardLarge </Heading><br/>
+    <Heading variant="titleCardRegular" level="h3"> titleCardRegular </Heading><br/>
+    <Heading variant="titleCardMini" level="h4"> titleCardMini </Heading><br/>
+    <Heading variant="label" level="h5"> label </Heading><br/>
+    <Heading variant="labelInline" level="h6"> labelInline </Heading><br/>
   </div>
 ```
 
@@ -51,18 +57,21 @@ type: example
 
 ### Heading level
 
-Generate content headings, from h1 to h5. Use the `margin` prop to add margin.
+What DOM element is output is determined in the following order:
 
-- The `as` prop controls what html element is output. _(if not defined it will default to level)._
-- The `level` prop sets its appearance.
+1. (deprecated) If the variant prop is set, then the value of level prop. If variant is set but level is not, <h1>-<h6> based on the variant prop's value.
+2. The value of the `as` prop
+3. The value of the `level` prop
+4. `<h2>`
+
+The `variant` and `level` props sets its appearance in this order.
 
 ```js
 ---
 type: example
 ---
 <div>
-  <Heading level="h1" as="h2" margin="0 0 x-small">Heading level One</Heading>
-
+  <Heading level="h1" as="h3" margin="0 0 x-small">This renders as <code>&lt;h3&gt;</code></Heading>
 </div>
 ```
 

packages/ui-heading/src/Heading/index.tsx

@@ -25,11 +25,7 @@
 import { Component } from 'react'
 
 import { View } from '@instructure/ui-view'
-import {
-  getElementType,
-  passthroughProps,
-  callRenderProp
-} from '@instructure/ui-react-utils'
+import { passthroughProps, callRenderProp } from '@instructure/ui-react-utils'
 import { testable } from '@instructure/ui-testable'
 import { IconAiColoredSolid } from '@instructure/ui-icons'
 
@@ -40,6 +36,7 @@ import generateComponentTheme from './theme'
 
 import { propTypes, allowedProps } from './props'
 import type { HeadingProps } from './props'
+import { AsElementType } from '@instructure/shared-types'
 
 const variantLevels: Record<
   NonNullable<HeadingProps['variant']>,
@@ -72,8 +69,7 @@ class Heading extends Component<HeadingProps> {
   static defaultProps = {
     children: null,
     border: 'none',
-    color: 'inherit',
-    level: 'h2'
+    color: 'inherit'
   } as const
 
   ref: Element | null = null
@@ -201,22 +197,27 @@ class Heading extends Component<HeadingProps> {
       ...props
     } = this.props
 
-    const propsForGetElementType = variant ? {} : this.props
-
-    const ElementType = getElementType(Heading, propsForGetElementType, () => {
-      if (level === 'reset') {
-        return 'span'
-      } else if (level) {
-        return level
+    let ElementType: AsElementType = 'h2'
+    if (variant) {
+      // TODO deprecated, remove. `variant` should not set DOM level
+      if (level) {
+        if (level === 'reset') {
+          ElementType = 'span'
+        } else {
+          ElementType = level
+        }
+      } else {
+        ElementType = variantLevels[variant]
       }
-
-      if (variant) {
-        return variantLevels[variant]
+    } else if (props.as) {
+      ElementType = props.as
+    } else if (level) {
+      if (level === 'reset') {
+        ElementType = 'span'
       } else {
-        return 'span'
+        ElementType = level
       }
-    })
-
+    }
     return (
       <View
         aria-label={this.getAriaLabel()}

packages/ui-heading/src/Heading/props.ts

@@ -43,7 +43,7 @@ type HeadingLevel<U extends keyof JSX.IntrinsicElements> = U
 
 type HeadingOwnProps = {
   /**
-   * transforms heading into an ai variant
+   * transforms heading into an `ai` variant
    */
   aiVariant?: 'stacked' | 'horizontal' | 'iconOnly'
   /**
@@ -58,19 +58,23 @@ type HeadingOwnProps = {
    * The font color to render, NOTE: `ai` color is deprecated. Use the `aiVariant` prop instead
    */
   color?:
-  | 'primary'
-  | 'secondary'
-  | 'primary-inverse'
-  | 'secondary-inverse'
-  | 'inherit'
-  | 'ai'
+    | 'primary'
+    | 'secondary'
+    | 'primary-inverse'
+    | 'secondary-inverse'
+    | 'inherit'
+    | 'ai'
   /**
-   * The *visual* appearance of the Heading: h1 is largest; h5 is smallest.
+   * The level of the heading in the DOM: h1 is largest; h5 is smallest.
    */
   level?: HeadingLevel<'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'> | 'reset'
   /**
-   * Choose the element Heading should render as. Will default to the `level` prop
-   * if not specified.
+   * What DOM element is output is determined in the following order:
+   * 1. (deprecated) If `variant` is set, then use the `level` prop, if that's
+   * not set use `<h1>`-`<h6>` based on the `variant` prop's value
+   * 2. The value of the `as` prop
+   * 3. The value of the `level` prop
+   * 4. `<h2>`
    */
   as?: AsElementType
   /**
@@ -88,19 +92,20 @@ type HeadingOwnProps = {
    */
   renderIcon?: Renderable
   /**
-   * Sets appearance of the heading.
+   * Sets appearance of the heading. Will also set its heading level, if not
+   * specified by the `level` prop (deprecated, not recommended!)
    */
   variant?:
-  | 'titlePageDesktop'
-  | 'titlePageMobile'
-  | 'titleSection'
-  | 'titleCardSection'
-  | 'titleModule'
-  | 'titleCardLarge'
-  | 'titleCardRegular'
-  | 'titleCardMini'
-  | 'label'
-  | 'labelInline'
+    | 'titlePageDesktop'
+    | 'titlePageMobile'
+    | 'titleSection'
+    | 'titleCardSection'
+    | 'titleModule'
+    | 'titleCardLarge'
+    | 'titleCardRegular'
+    | 'titleCardMini'
+    | 'label'
+    | 'labelInline'
 }
 
 type PropKeys = keyof HeadingOwnProps