[Docs] Templates - Ascending navigation update

aries-site/src/data/structures/templates/templates.js

@@ -15,9 +15,9 @@ export const templates = [
     name: 'Ascending navigation',
     available: true,
     cardOrder: 101,
-    description: `The Ascending Button for Navigation allows
-    the user to navigate to a parent page from a child page
-    by moving upward in the application or website hierarchy.`,
+    description: `Ascending navigation enables users 
+    to move up one level in an application’s hierarchy, 
+    from a child page back to its parent.`,
     preview: {
       image: {
         src: {

aries-site/src/examples/templates/ascending-navigation/AscendingNavigationExample.js

@@ -0,0 +1,103 @@
+/* eslint-disable react/prop-types */
+import React, { useState } from 'react';
+import {
+  Anchor,
+  Box,
+  Button,
+  Grommet,
+  Header,
+  Markdown,
+  PageContent,
+  PageHeader,
+  Paragraph,
+  Text,
+} from 'grommet';
+import { hpe } from 'grommet-theme-hpe';
+import { Left, Home } from '@hpe-design/icons-grommet';
+
+import { components } from '../../../components/content/MarkdownComponents';
+import { HomeContent } from './components/HomeContent';
+import { sectionConfig } from './data/sections';
+
+export const AscendingNavigationExample = () => {
+  const [activeSection, setActiveSection] = useState('overview');
+
+  const config = sectionConfig[activeSection];
+
+  const sectionContent = {
+    home: <HomeContent onNavigate={setActiveSection} />,
+    overview: (
+      <Paragraph>
+        This overview page can describe the purpose of your app or design
+        system. It's a child of the Home page.
+      </Paragraph>
+    ),
+    components: (
+      <>
+        <Text weight="bold">Components in use in this example:</Text>
+        <Markdown components={components}>
+          {`- \`Page\`, \`PageContent\`, \`PageHeader\`
+- \`Box\`, \`Header\`, \`Nav\`, \`Button\`  
+- \`Text\`, \`Paragraph\`, \`Anchor\``}
+        </Markdown>
+      </>
+    ),
+    help: (
+      <>
+        <Text weight="bold">To create this demo application:</Text>
+        <Markdown components={components}>
+          {
+          `1. Create a React sandbox
+2. Install \`grommet\`, \`grommet-theme-hpe\`, \`@hpe-design/icons-grommet\`
+3. Replace your App.js with this template`
+}
+        </Markdown>
+      </>
+    ),
+  };
+
+  return (
+    <Grommet theme={hpe}>
+      <Box
+        background="background-back"
+        width="full"
+        border={{ color: 'border-weak', size: 'xsmall' }}
+        pad={{ bottom: 'xlarge' }}
+      >
+      <Header
+        pad={{ horizontal: 'medium', vertical: 'small' }}
+        background="background-front"
+      >
+        <Button
+          default
+          icon={<Home />}
+          onClick={() => setActiveSection('home')}
+          hoverIndicator="background"
+          a11yTitle="Go to Home page"
+        />
+      </Header>
+      <Box>
+        <PageContent gap="small">
+          <PageHeader
+            title={config.label}
+            subtitle={config.subtitle}
+            parent={
+              activeSection !== 'home' ? (
+                <Anchor
+                  label="Home"
+                  icon={<Left />}
+                  onClick={() => setActiveSection('home')}
+                />
+              ) : undefined
+            }
+            actions={
+              activeSection !== 'home' && <Button label="Primary" primary />
+            }
+          />
+          <Box gap="small">{sectionContent[activeSection]}</Box>
+        </PageContent>
+      </Box>
+    </Box>
+    </Grommet>
+  );
+};

aries-site/src/examples/templates/ascending-navigation/components/HomeContent.js

@@ -0,0 +1,19 @@
+/* eslint-disable react/prop-types */
+import { Paragraph, Grid } from 'grommet';
+import { SectionCard } from './SectionCard';
+import { sections } from '../data/sections';
+
+export const HomeContent = ({ onNavigate }) => (
+  <>
+    <Paragraph>
+      Use the navigation in the header or the cards below to explore different
+      sections of this demo app. While on any nested page the{' '}
+      <strong>Ascending navigation</strong> will bring you home.
+    </Paragraph>
+    <Grid columns="small" gap="small">
+      {sections.map(section => (
+        <SectionCard key={section.id} section={section} onClick={onNavigate} />
+      ))}
+    </Grid>
+  </>
+);

aries-site/src/examples/templates/ascending-navigation/components/NavigationButton.js

@@ -0,0 +1,12 @@
+/* eslint-disable react/prop-types */
+import { Button } from 'grommet';
+
+export const NavigationButton = ({ section, isActive, onClick }) => (
+  <Button
+    default
+    icon={section.icon}
+    label={section.label}
+    active={isActive}
+    onClick={() => onClick(section.id)}
+  />
+);

aries-site/src/examples/templates/ascending-navigation/components/SectionCard.js

@@ -0,0 +1,24 @@
+/* eslint-disable react/prop-types */
+import { Card, Box, Heading, Paragraph } from 'grommet';
+import { LinkNext } from '@hpe-design/icons-grommet';
+
+export const SectionCard = ({ section, onClick }) => (
+  <Card default onClick={() => onClick(section.id)} pad="xsmall">
+    <Box direction="row" fill justify="between">
+      <Heading
+        level="2"
+        margin={{
+          horizontal: 'none',
+          vertical: '3xsmall',
+        }}
+      >
+        {section.label}
+      </Heading>
+      <LinkNext height="xxlarge" />
+    </Box>
+
+    <Paragraph>
+      This leads to the {section.label} page of your HPE Design System demo app.
+    </Paragraph>
+  </Card>
+);

aries-site/src/examples/templates/ascending-navigation/data/sections.js

@@ -0,0 +1,17 @@
+import { Announce, Help, Template } from '@hpe-design/icons-grommet';
+
+export const sections = [
+  { id: 'overview', label: 'Overview', icon: <Announce size="small" /> },
+  { id: 'components', label: 'Components', icon: <Template size="small" /> },
+  { id: 'help', label: 'Help', icon: <Help size="small" /> },
+];
+
+export const sectionConfig = {
+  home: { label: 'Home', subtitle: 'HPE Design System demo.' },
+  overview: { label: 'Overview', subtitle: 'This is the overview section.' },
+  components: {
+    label: 'Components',
+    subtitle: 'This is the components section.',
+  },
+  help: { label: 'Help', subtitle: 'This is the help section.' },
+};

aries-site/src/examples/templates/ascending-navigation/index.js

@@ -1 +1 @@
-export * from './AscendingNavigationAnatomy';
+export * from './AscendingNavigationExample';

aries-site/src/pages/templates/ascending-navigation.mdx

@@ -1,59 +1,55 @@
-import { DiagramPreview, Example } from '../../layouts';
-import { AscendingNavigationAnatomy } from '../../examples';
+import { Example } from '../../layouts';
+import { 
+  AscendingNavigationExample 
+  } from '../../examples';
 import { Text } from 'grommet';
 
-When an application’s hierarchy is well designed, the ascending button will typically take the user
-back to the previous page they came from.
+The `parent` property on [PageHeader](https://design-system.hpe.design/components/PageHeader) generates a link to the immediate upstream page in the hierarchy.
 
-<Example
-  caption="Example of an ascending button."
-  plain
-  pad="xsmall"
-  previewWidth="medium"
-  height={{ min: 'xsmall' }}
->
-  <DiagramPreview
-    src={{
-      dark: '/templateImages/ascending-button-preview-invert.svg',
-      light: '/templateImages/ascending-button-preview.svg',
-    }}
-    alt="ascending button in an application"
-  />
-</Example>
-
-## Guidance
-
-- Follows the [default button styling](https://design-system.hpe.design/components/button#default-button) with a "FormPrevious" icon.
-- Displayed below the Header and aligned to the left with the pages content.
-
-## When to use
-
-- To allow users to return to the parent (hub) screen when on a details (child/spoke) page.
-- To visually communicate the parent page for the user’s current page.
-
-## Example
-
-Ascending Navigation provides an easy way for a user to move from a child page up to a parent page.
 
 <Example
   caption={
     <>
       <Text margin={{ top: 'xsmall' }} size="small">
         {' '}
-        1. A preview of Users detail view (child page).
+        1. Page loads on <strong>Overview</strong> child page
       </Text>
       <br></br>
       <Text margin={{ top: 'xsmall' }} size="small">
         {' '}
-        2. A preview of Ascending Navigation to the parent page utilizing the ascending
-        button.
+        2. Interacting with the <strong>Ascending Navigation</strong> link brings the user to the home page.
       </Text>
     </>
   }
   plain
-  pad="xsmall"
-  previewWidth="xlarge"
-  height={{ min: 'xsmall' }}
+  pad={{
+    bottom: "xlarge"
+  }}
+  previewWidth="full"  
 >
-  <AscendingNavigationAnatomy />
+  <AscendingNavigationExample />
 </Example>
+
+```txt
+<PageHeader 
+  parent={ <Anchor label="Home" icon={<Left />} a11yTitle="Link to the home page" />} 
+  title="Example page title" 
+  subtitle="I'm a direct child of the homepage"
+/>
+```
+
+## Guidance
+- Renders as a standard anchor link using [default anchor styling](https://design-system.hpe.design/components/anchor).
+- Should be paired with a [**Left**](https://hpe-design-icons-grommet.netlify.app/?path=/story/icons-hpe-icons-for-grommet--default&args=iconName:Left) icon to clearly communicate backward navigation.
+- Keep the label short and contextual, match the parent name to set navigation expectaions.
+- Use only one ascending link per page.
+
+## When to use
+
+Use ascending navigation when your product has a parent/child or hub/spoke page structure and users may need to return to the parent context.
+
+- Detail pages that roll up into an overview page.
+- Spoke pages that sit under a central hub.
+- Nested workflows where returning to previous context is important.
+
+