HDS-3807 Add AppSideNav docs files

website/docs/components/app-side-nav/index.md

@@ -0,0 +1,38 @@
+---
+title: App Side Nav
+description: Used as a contextual navigation for subpages within an application.
+caption: A side navigation menu that provides access to subpages within a product or application.
+links:
+  figma: 
+  github: https://github.com/hashicorp/design-system/tree/main/packages/components/src/components/hds/app-side-nav
+related: ['components/side-nav', 'components/breadcrumb','components/tabs','layouts/app-frame','components/app-header']
+previewImage: assets/illustrations/components/app-side-nav.jpg
+navigation:
+  hidden: false
+  keywords: ['navigation', 'side navigation', 'sidenav', 'sidebar']
+status:
+  added: 4.10.0
+---
+
+<section data-tab="Guidelines">
+  @include "partials/guidelines/overview.md"
+  @include "partials/guidelines/guidelines.md"
+</section>
+
+<section data-tab="Code">
+  @include "partials/code/how-to-use.md"
+  @include "partials/code/component-api.md"
+</section>
+
+<section data-tab="Specifications">
+  @include "partials/specifications/anatomy.md"
+</section>
+
+<section data-tab="Accessibility">
+  @include "partials/accessibility/accessibility.md"
+</section>
+
+<section data-tab="Version history">
+  @include "partials/version-history/4.10.0.md"
+</section>
+

website/docs/components/app-side-nav/partials/accessibility/accessibility.md

@@ -0,0 +1,15 @@
+## Conformance rating
+
+<Doc::Badge @type="success">Conformant</Doc::Badge>
+
+When used as recommended, there should not be any WCAG conformance issues with this component.
+
+## Applicable WCAG Success Criteria
+
+This section is for reference only. This component intends to conform to the following WCAG Success Criteria:
+
+<Doc::WcagList @criteriaList={{array "1.1.1" "1.3.1" "1.3.2" "1.3.3" "1.3.4" "1.4.1" "1.4.3" "1.4.4" "1.4.10" "1.4.11" "1.4.12" "1.4.13" "2.1.1" "2.1.2" "2.1.4" "2.4.3" "2.4.7" "3.2.1" "3.2.3" "3.2.4" "4.1.2" }} />
+
+---
+
+<Doc::A11ySupport />

website/docs/components/app-side-nav/partials/guidelines/guidelines.md

@@ -0,0 +1,115 @@
+## Usage
+
+### When to use
+
+- When navigating between subpages and nested pages within the application.
+
+### When not to use
+
+- For global navigation across an application, use the [App Header](/components/app-header) instead.
+- To move between views within the same context or page, consider [Tabs](/components/tabs).
+
+## Body
+
+The body consists of a group of sections with vertical lists of links, typically to the most important parts of the application. Any generic content or component is also supported by an additional generic container.
+
+### List
+
+#### With title
+
+![App Side Nav section with a title](/assets/components/app-side-nav/section-with-title.png)
+
+#### Without title
+
+![App Side Nav section without a title](/assets/components/app-side-nav/section-without-title.png)
+
+- A title can help users scan the sections and provide context about the links inside each section.
+- Titles should be meaningful and related to the content within the section.
+
+### List items
+
+#### Without icon
+
+![List items without icons](/assets/components/app-side-nav/list-item-without-icon.png)
+
+#### With icon
+
+![List items with icons](/assets/components/app-side-nav/list-item-with-icon.png)
+
+- Use icons to help users recognize and scan the links they are paired with.
+- We recommend only using icons in the main or top level navigation.
+- Avoid overwriting color styles in icons.
+
+!!! Do
+
+![List items with correct use of icons](/assets/components/app-side-nav/list-item-with-icon-do.png)
+
+!!!
+
+!!! Dont
+
+![List items with incorrect use of icons](/assets/components/app-side-nav/list-item-with-icon-dont.png)
+
+!!!
+
+#### With badge
+
+![List item with a badge](/assets/components/app-side-nav/list-item-with-badge.png)
+
+#### With count
+
+![List item with badge-count](/assets/components/app-side-nav/list-item-with-count.png)
+
+#### With nested items
+
+Use `hasSubItems` to show or signify that a link has a nested level of navigation.
+
+![List item with sub-items](/assets/components/app-side-nav/list-item-with-nested-items.png)
+
+#### External links
+
+Use `isLinkExternal` to show that the list item is a hyperlink pointing to a page outside the product or platform.
+
+![List item with a external link](/assets/components/app-side-nav/list-item-with-external-link.png)
+
+!!! Warning
+
+Use external links sparingly. Avoid using this property to link pages that are unrelated to the product's navigation.
+!!!
+
+### Generic content
+
+The topGenericInstance and bottomGenericInstance properties support any additional generic content, local components, or Helios components within the body container via instance swap properties (`topGenericInstance`, `bottomGenericInstance`) in Figma.
+
+![Generic container within the side-nav body](/assets/components/app-side-nav/custom-content-body.png)
+
+## Positioning, and responsive behaviour
+
+The App Side Nav should always be positioned on the left side of the viewport, occupying 100% of the viewport height to ensure that the navigation is always visible and accessible to the user..
+
+On smaller viewports, the App Side Nav should collapse to maximize the available real estate on tablet and mobile devices. By tapping the menu icon, users can expand and access the full menu when needed.
+
+![Responsive side-nav](/assets/components/app-side-nav/sidenav-position-and-responsive.png)
+
+## Collapse functionality
+
+If the `isCollapsible` property is set to `true`, a collapse toggle button will be exposed to the end-user allowing them to manually expand and collapse the component.
+
+![App Side Nav collapse function](/assets/components/app-side-nav/sidenav-collapse-interaction.png)
+
+On smaller viewports, the App Side Nav will be rendered in its collapsed state **by default** and will overlay the main page content in its expanded state.
+
+![App Side Nav overlay on smaller viewports](/assets/components/app-side-nav/sidenav-overlay-small-viewport.png)
+
+### Collapsed reflow
+
+The collapse functionality of the App Side Nav gives control to the end-user to unlock more horizontal space in the main page. Thus, the main page content should reflow or reposition to occupy this space if the App Side Nav is in its collapsed state. If the main page content has a predetermined maximum width that is reached when the App Side Nav collapses, the content should transition smoothly to the new center of the main page area.
+
+This is handled out of the box by the [AppFrame](/layouts/app-frame) component, but may need to be accounted for in custom implementations of the application/page layout.
+
+<video width="100%" controls loop>
+  <source
+    src="/assets/components/app-side-nav/app-side-nav-expand-collapse.mp4"
+    type="video/mp4"
+  />
+</video>

website/docs/components/app-side-nav/partials/guidelines/overview.md

@@ -0,0 +1,7 @@
+The App Side Nav provides users with access to contextual navigation within areas of the application and generally includes subpages and nested pages within projects and organizations.
+
+!!! Info
+
+The App Side Nav replaces the former Side Nav component. It is designed to always be used together with the App Header component unlike the former Side Nav which was originally created as a standalone navigation component before the introduction of the App Header.
+
+!!!

website/docs/components/app-side-nav/partials/specifications/anatomy.md

@@ -0,0 +1,10 @@
+## Anatomy
+
+![Anatomy of sideNav](/assets/components/side-nav/side-nav-anatomy.png =580x*)
+
+| Element         | Usage                  |
+| --------------- | ---------------------- |
+| Collapse Toggle | Optional               |
+| Back button     | Required in sub-pages  |
+| List title      | Optional               |
+| List item       | Required; at least one |

website/docs/components/app-side-nav/partials/version-history/4.10.0.md

@@ -0,0 +1,5 @@
+## 4.10.0
+
+### Added
+
+`Hds::AppSideNav` - Added the component. It replaces the standalone `SideNav` component and is meant to be used together with the `AppHeader` component which should both be contained within the `AppFrame` layout component.

website/tests/acceptance/components/app-side-nav-test.js

@@ -3,35 +3,32 @@
  * SPDX-License-Identifier: MPL-2.0
  */
 
-import { module } from 'qunit';
-// import { module, test } from 'qunit';
-// import { visit, currentURL } from '@ember/test-helpers';
+import { module, test } from 'qunit';
+import { visit, currentURL } from '@ember/test-helpers';
 import { setupApplicationTest } from 'website/tests/helpers';
-// import { a11yAudit, setRunOptions } from 'ember-a11y-testing/test-support';
+import { a11yAudit, setRunOptions } from 'ember-a11y-testing/test-support';
 
 module('Acceptance | components/app-side-nav', function (hooks) {
   setupApplicationTest(hooks);
 
-  // TODO: Add AppSideNav Web docs then reenable tests
+  test('visiting /components/app-side-nav', async function (assert) {
+    await visit('/components/app-side-nav');
 
-  // DISABLEtest('visiting /components/app-side-nav', async function (assert) {
-  //   await visit('/components/app-side-nav');
+    assert.strictEqual(currentURL(), '/components/app-side-nav');
+  });
 
-  //   assert.strictEqual(currentURL(), '/components/app-side-nav');
-  // });
+  test('Components/app-side-nav page passes automated a11y checks', async function (assert) {
+    setRunOptions({
+      rules: {
+        'duplicate-id-aria': { enabled: false },
+        'duplicate-id-active': { enabled: false },
+      },
+    });
 
-  // DISABLEtest('Components/app-side-nav page passes automated a11y checks', async function (assert) {
-  //   setRunOptions({
-  //     rules: {
-  //       'duplicate-id-aria': { enabled: false },
-  //       'duplicate-id-active': { enabled: false },
-  //     },
-  //   });
+    await visit('/components/app-side-nav');
 
-  //   await visit('/components/app-side-nav');
+    await a11yAudit();
 
-  //   await a11yAudit();
-
-  //   assert.ok(true, 'a11y automation audit passed');
-  // });
+    assert.ok(true, 'a11y automation audit passed');
+  });
 });