Docs update - Heading (#1187)

* docs: updating Heading docs

* chore: fixing default level on demo

docs/src/data/links.ts

@@ -21,7 +21,7 @@ export const baseComponents: ComponentNavItem[] = [
   {
     href: '/components/heading',
     label: 'Heading',
-    body: ``,
+    body: `This is a separate primitive from Text for semantic purposes. The Heading primitive maps to an <h*> tag, and Text maps to a <p> tag.`,
   },
   {
     href: '/components/icon',

docs/src/pages/components/heading/HeadingPropControls.tsx

@@ -0,0 +1,38 @@
+import * as React from 'react';
+import {
+  Flex,
+  HeadingLevel,
+  HeadingProps,
+  SelectField,
+} from '@aws-amplify/ui-react';
+
+interface HeadingPropControlsProps extends HeadingProps {
+  setLevel: (value: React.SetStateAction<HeadingProps['level']>) => void;
+}
+
+interface HeadingPropControlsInterface {
+  (props: HeadingPropControlsProps): JSX.Element;
+}
+
+export const HeadingPropControls: HeadingPropControlsInterface = ({
+  level,
+  setLevel,
+}) => {
+  return (
+    <Flex direction="column">
+      <SelectField
+        name="level"
+        value={String(level)}
+        onChange={(event) => setLevel(+event.target.value as HeadingLevel)}
+        label="level"
+      >
+        <option value="1">1</option>
+        <option value="2">2</option>
+        <option value="3">3</option>
+        <option value="4">4</option>
+        <option value="5">5</option>
+        <option value="6">6</option>
+      </SelectField>
+    </Flex>
+  );
+};

docs/src/pages/components/heading/demo.tsx

@@ -1,36 +1,21 @@
-import React, { useState } from 'react';
-import { Heading, HeadingLevel, Flex, View } from '@aws-amplify/ui-react';
-import { FieldLabeler } from '@/components/FieldLabeler';
-import { Example } from '@/components/Example';
+import * as React from 'react';
+import { Heading, HeadingLevel } from '@aws-amplify/ui-react';
 
+import { HeadingPropControls } from './HeadingPropControls';
+import { Demo } from '@/components/Demo';
+
+const propsToCode = (level: HeadingLevel) => {
+  return `<Heading level={${level}}>Heading</Heading>`;
+};
 export const HeadingDemo = () => {
-  const [level, setLevel] = useState<HeadingLevel>(6);
+  const [level, setLevel] = React.useState<HeadingLevel>(6);
 
   return (
-    <Flex direction="column" gap="1rem">
-      <Flex>
-        <FieldLabeler id="level">
-          <select
-            value={level}
-            placeholder="Select heading level"
-            onChange={(event) => setLevel(+event.target.value as HeadingLevel)}
-            id="level"
-            name="level"
-          >
-            <option value={1}>1</option>
-            <option value={2}>2</option>
-            <option value={3}>3</option>
-            <option value={4}>4</option>
-            <option value={5}>5</option>
-            <option value={6}>6</option>
-          </select>
-        </FieldLabeler>
-      </Flex>
-      <Example>
-        <View>
-          <Heading level={level}>Heading</Heading>
-        </View>
-      </Example>
-    </Flex>
+    <Demo
+      code={propsToCode(level)}
+      propControls={<HeadingPropControls level={level} setLevel={setLevel} />}
+    >
+      <Heading level={level}>Heading</Heading>
+    </Demo>
   );
 };

docs/src/pages/components/heading/examples/DefaultHeadingExample.tsx

@@ -0,0 +1,6 @@
+import * as React from 'react';
+import { Heading } from '@aws-amplify/ui-react';
+
+export const DefaultHeadingExample = () => {
+  return <Heading>Hello world</Heading>;
+};

docs/src/pages/components/heading/examples/HeadingLevelExample.tsx

@@ -0,0 +1,16 @@
+import * as React from 'react';
+import { Heading } from '@aws-amplify/ui-react';
+
+export const HeadingLevelExample = () => {
+  return (
+    <>
+      <Heading level={1}>Heading 1</Heading>
+      <Heading level={2}>Heading 2</Heading>
+      <Heading level={3}>Heading 3</Heading>
+      <Heading level={4}>Heading 4</Heading>
+      <Heading level={5}>Heading 5</Heading>
+      <Heading level={6}>Heading 6</Heading>
+      <Heading>Default (level 6)</Heading>
+    </>
+  );
+};

docs/src/pages/components/heading/examples/HeadingStylePropsExample.tsx

@@ -0,0 +1,15 @@
+import * as React from 'react';
+import { Heading, useTheme } from '@aws-amplify/ui-react';
+
+export const HeadingStylePropsExample = () => {
+  const { tokens } = useTheme();
+  return (
+    <Heading
+      level={3}
+      color={tokens.colors.green[80]}
+      fontWeight={tokens.fontWeights.bold}
+    >
+      Hello world
+    </Heading>
+  );
+};

docs/src/pages/components/heading/examples/index.ts

@@ -0,0 +1,3 @@
+export { DefaultHeadingExample } from './DefaultHeadingExample';
+export { HeadingLevelExample } from './HeadingLevelExample';
+export { HeadingStylePropsExample } from './HeadingStylePropsExample';

docs/src/pages/components/heading/index.page.mdx

@@ -1,5 +1,6 @@
 ---
 title: Heading
+description: This is a separate primitive from Text for semantic purposes. The Heading primitive maps to an <h*> tag, and Text maps to a <p> tag.
 isPrimitive: true
 ---
 

docs/src/pages/components/heading/react.mdx

@@ -1,50 +1,43 @@
 import { Heading } from '@aws-amplify/ui-react';
-import { HeadingDemo } from './demo';
-import { Example } from '@/components/Example';
 
-This is a separate primitive from Text for semantic purposes. The Heading primitive maps to an `<h*>` tag, and Text maps to a `<p>` tag.
+import {
+  DefaultHeadingExample,
+  HeadingLevelExample,
+  HeadingStylePropsExample,
+} from './examples';
+import { HeadingDemo } from './demo';
+import { Example, ExampleCode } from '@/components/Example';
 
 ## Demo
 
 <HeadingDemo />
 
 ## Usage
 
-Import the Heading primitive and styles.
+Import the Heading primitive.
 
-```jsx
-import { Heading } from '@aws-amplify/ui-react';
-import '@aws-amplify/ui-react/styles.css';
+<Example>
+  <DefaultHeadingExample />
+  <ExampleCode>
+    ```jsx file=./examples/DefaultHeadingExample.tsx
 
-<Heading>Hello world</Heading>;
-```
+    ```
 
-<Example>
-  <Heading>Hello world</Heading>
+  </ExampleCode>
 </Example>
 
 ### Heading levels
 
 Use the `level` prop to change the heading level (e.g., `h1 - h6`). Available options are `1`, `2`, `3`, `4`, `5` and `6`.
 
-```jsx
-<Heading level={1}>Heading 1</Heading>
-<Heading level={2}>Heading 2</Heading>
-<Heading level={3}>Heading 3</Heading>
-<Heading level={4}>Heading 4</Heading>
-<Heading level={5}>Heading 5</Heading>
-<Heading level={6}>Heading 6</Heading>
-<Heading>Default (level 6)</Heading>
-```
-
 <Example>
-  <Heading level={1}>Heading 1</Heading>
-  <Heading level={2}>Heading 2</Heading>
-  <Heading level={3}>Heading 3</Heading>
-  <Heading level={4}>Heading 4</Heading>
-  <Heading level={5}>Heading 5</Heading>
-  <Heading level={6}>Heading 6</Heading>
-  <Heading>Default (level 6)</Heading>
+  <HeadingLevelExample />
+  <ExampleCode>
+    ```jsx file=./examples/HeadingLevelExample.tsx
+
+    ```
+
+  </ExampleCode>
 </Example>
 
 ## CSS Styling
@@ -53,55 +46,55 @@ Use the `level` prop to change the heading level (e.g., `h1 - h6`). Available op
 
 To override styling on all Headings, you can set the Amplify CSS variables or use the built-in `.amplify-heading` class.
 
-```css
-/* styles.css */
-:root {
-  --amplify-components-heading-color: gray;
-}
-/* OR */
-.amplify-heading {
-  color: gray;
-}
-```
-
-To replace the Heading styling, unset it:
-
-```css
-.amplify-heading {
-  all: unset;
-  /* Add your styling here*/
-}
-```
+<Example>
+  <Heading class="heading-global-styling" level={3}>Hello world</Heading>
+  <ExampleCode>
+    ```css
+    /* styles.css */
+    :root {
+      --amplify-components-heading-color: gray;
+    }
+    /* OR */
+    .amplify-heading {
+      color: gray;
+    }
+    ```
+  </ExampleCode>
+</Example>
 
 Override styles for any `Heading` component `h1 - h6`
 
-```css
-/* styles.css */
-h1.amplify-heading {
-  font-size: 1rem;
-  font-style: italic;
-}
-
-h6.amplify-heading {
-  font-size: 2rem;
-  font-weight: bold;
-}
-```
-
-```jsx
-import './styles.css';
-
-<Heading level={1}>Small and italic</Heading>
-<Heading>Big and bold</Heading>
-```
-
 <Example>
   <Heading fontSize="1rem" fontStyle="italic">
     Small and italic
   </Heading>
   <Heading fontSize="2rem" fontWeight="bold">
     Big and bold
   </Heading>
+  <ExampleCode>
+    ```css
+    /* styles.css */
+    h1.amplify-heading {
+      font-size: 1rem;
+      font-style: italic;
+    }
+
+    h6.amplify-heading {
+    font-size: 2rem;
+    font-weight: bold;
+    }
+    ```
+
+  </ExampleCode>
+  <ExampleCode>
+    ```jsx
+    import './styles.css';
+
+    <Heading level={1}>Small and italic</Heading>
+    <Heading>Big and bold</Heading>
+    ```
+
+  </ExampleCode>
 </Example>
 
 ### Local styling
@@ -110,18 +103,40 @@ To override styling on a specific Heading, you can use a class selector or style
 
 _Using a class selector:_
 
-(Example needed)
+<Example>
+  <Heading className="heading-blue" level={3}>
+    Hello world
+  </Heading>
+  <ExampleCode>
+  ```css
+  /* styles.css */
+  .heading-blue {
+    color: var(--amplify-colors-blue-80);
+  }
+  ```
+
+  </ExampleCode>
+  <ExampleCode>
+    ```jsx
+    import './styles.css';
+
+    <Heading className="heading-blue" level={3}>
+      Hello world
+    </Heading>;
+    ```
+
+  </ExampleCode>
+</Example>
 
 _Using style props:_
 
-```jsx
-<Heading level={3} color="green" fontWeight="bold">
-  Save the environment
-</Heading>
-```
-
 <Example>
-  <Heading level={3} color="green" fontWeight="bold">
-    Save the environment
-  </Heading>
+  <HeadingStylePropsExample />
+  <ExampleCode>
+    ```jsx
+    <Heading level={3} color="green" fontWeight="bold">
+      Hello world
+    </Heading>
+    ```
+  </ExampleCode>
 </Example>

docs/src/styles/primitives/headingStyles.css

@@ -1,5 +1,7 @@
-#subscribe {
-  color: darkblue;
-  font-style: italic;
-  font-size: 1.5rem;
+.heading-global-styling {
+  color: var(--amplify-colors-neutral-80);
+}
+
+.heading-blue {
+  color: var(--amplify-colors-blue-80);
 }