From 97f6ad6647b46fbcb92649ff0d79014a4c9d29f2 Mon Sep 17 00:00:00 2001 From: Kristin Bradley Date: Thu, 12 Sep 2024 08:36:29 -0700 Subject: [PATCH 1/6] HDS-3807 Add AppSideNav docs files --- website/docs/components/app-side-nav/index.md | 38 ++ .../partials/accessibility/accessibility.md | 15 + .../partials/code/component-api.md | 323 +++++++++++ .../app-side-nav/partials/code/how-to-use.md | 507 ++++++++++++++++++ .../partials/guidelines/guidelines.md | 115 ++++ .../partials/guidelines/overview.md | 7 + .../partials/specifications/anatomy.md | 10 + .../partials/version-history/4.10.0.md | 5 + .../components/app-side-nav-test.js | 39 +- 9 files changed, 1038 insertions(+), 21 deletions(-) create mode 100644 website/docs/components/app-side-nav/index.md create mode 100644 website/docs/components/app-side-nav/partials/accessibility/accessibility.md create mode 100644 website/docs/components/app-side-nav/partials/code/component-api.md create mode 100644 website/docs/components/app-side-nav/partials/code/how-to-use.md create mode 100644 website/docs/components/app-side-nav/partials/guidelines/guidelines.md create mode 100644 website/docs/components/app-side-nav/partials/guidelines/overview.md create mode 100644 website/docs/components/app-side-nav/partials/specifications/anatomy.md create mode 100644 website/docs/components/app-side-nav/partials/version-history/4.10.0.md diff --git a/website/docs/components/app-side-nav/index.md b/website/docs/components/app-side-nav/index.md new file mode 100644 index 0000000000..b77ca9065a --- /dev/null +++ b/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 +--- + +
+ @include "partials/guidelines/overview.md" + @include "partials/guidelines/guidelines.md" +
+ +
+ @include "partials/code/how-to-use.md" + @include "partials/code/component-api.md" +
+ +
+ @include "partials/specifications/anatomy.md" +
+ +
+ @include "partials/accessibility/accessibility.md" +
+ +
+ @include "partials/version-history/4.10.0.md" +
+ diff --git a/website/docs/components/app-side-nav/partials/accessibility/accessibility.md b/website/docs/components/app-side-nav/partials/accessibility/accessibility.md new file mode 100644 index 0000000000..ad2705df1b --- /dev/null +++ b/website/docs/components/app-side-nav/partials/accessibility/accessibility.md @@ -0,0 +1,15 @@ +## Conformance rating + +Conformant + +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: + + + +--- + + diff --git a/website/docs/components/app-side-nav/partials/code/component-api.md b/website/docs/components/app-side-nav/partials/code/component-api.md new file mode 100644 index 0000000000..a9ac3c26fa --- /dev/null +++ b/website/docs/components/app-side-nav/partials/code/component-api.md @@ -0,0 +1,323 @@ +## Component API + +### App Side Nav + +This is the full-fledged component (responsive and animated). + + + + A named block where the content for the “header” area of the App Side Nav is rendered. The `AppSideNav::Header` component should be added here. It yields the value of `isMinimized` too. +

+ When the App Side Nav is paired with the [`Hds::AppHeader`](/components/app-header) component, the `<:header>` block normally doesn’t need to be included. + + + A named block where the content for the “body” or main content of the App Side Nav is rendered. The `AppSideNav::List` and `AppSideNav::PortalTarget` components should be added here when used. It yields the value of `isMinimized` too. + + + A named block where the content for the “footer” section of the App Side Nav is rendered. It yields the value of `isMinimized` too. +

+ When the App Side Nav is paired with the [`Hds::AppHeader`](/components/app-header) component, you may not need to include the `<:footer>` block or related content. + + + Controls whether the App Side Nav is responsive to viewport changes. It can be programmatically turned off by passing `false`. +
+ Notice: even if the `@isResponsive` parameter is set to false, some JavaScript is still executed in the background, and event listeners are attached to some DOM elements (even if this functionality is not used). + + + Controls whether the App Side Nav is collapsible on large viewports. When this argument and `isResponsive` are set to `true`, a toggle button will permanently be rendered to collapse and expand the App Side Nav. +
+ Notice: if `@isResponsive` is set to false, this argument has no effect. + + + Controls if the App Side Nav is rendered collapsed or expanded when initialized. This allows an application to preserve the collapsed/expanded state across sessions. After the initial render, this argument is altered based on user interactions (collapse/expand the App Side Nav or resize the window) and it is not a suitable way of controlling the App Side Nav state from outside after render (it’s an internal state). + + + Accepts a localized string; the fallback is set to `Open menu` if the menu is closed, and `Close menu` if the menu is open. + + + Callback function invoked when the `AppSideNav` is collapsed or expanded. The function receives a boolean argument stating if the `AppSideNav` is minimized on not. + + + This component supports use of [`...attributes`](https://guides.emberjs.com/release/in-depth-topics/patterns-for-components/#toc_attribute-ordering). + + + +### AppSideNav::Base + +This is the basic component (layout only). + + + + A named block for rendering content outside of the "header/body/footer" containers of the App Side Nav. + + + A named block where the content for the “header” area of the App Side Nav is rendered. The `AppSideNav::Header` component should be added here. + + + A named block where the content for the “body” or main content of the App Side Nav is rendered. The `AppSideNav::List` and `AppSideNav::PortalTarget` components should be added here when used. + + + A named block where the content for the “footer” section of the App Side Nav is rendered. + + + This component supports use of [`...attributes`](https://guides.emberjs.com/release/in-depth-topics/patterns-for-components/#toc_attribute-ordering). + + + +### AppSideNav::Header + + + + A named block where the main product logo linked to your app’s home page will be rendered. The `AppSideNav::HomeLink` component should be added here. + + + A named block where the header “action” components will be rendered. Typically `Dropdown` components and/or `AppSideNav::IconButton` components will be added here. + + + This component supports use of [`...attributes`](https://guides.emberjs.com/release/in-depth-topics/patterns-for-components/#toc_attribute-ordering). + + + +### AppSideNav::Header::HomeLink + +The `AppSideNav::Header::HomeLink` component. + +It internally uses the [`Hds::Interactive`](/utilities/interactive) utility component. For more details about this component API, please refer to [its documentation page](/utilities/interactive?tab=code#component-api). + + + + Used to show an icon. Any [icon](/icons/library) name is accepted. Typically you would add the icon name for your product. + + + Used to specify an optional custom color provided as any valid CSS color. For more details on acceptable values, see the [how to use the Icon's `color` argument](/components/icon?tab=code#color). If unspecified, it will use the SideNav’s default white text color. + + + URL parameter that’s passed down to the `` element. + + + This controls if the `` link is external. For security reasons, we add the `target="_blank"` and `rel="noopener noreferrer"` attributes to it by default. + + + Parameters that are passed down as arguments to the ``/`` components. + + + This controls if the “LinkTo” is external to the Ember engine, in which case it will use a `` for the `@route`. + + + The value of the aria-label. If no text value is defined an error will be thrown. + + + This component supports use of [`...attributes`](https://guides.emberjs.com/release/in-depth-topics/patterns-for-components/#toc_attribute-ordering). + + + +### SideNav::Header::IconButton + +!!! Warning + +The `AppSideNav::Header::IconButton` subcomponent is now deprecated. Use the `Hds::Button` component with the `isIconOnly` variant instead. + +* [Example usage of an Icon-only Button](/components/app-sidenav?tab=code#actions) within the App Side Nav `:actions` block. +* [Icon-only Button documentation](/components/button?tab=code#icon-only-button) + +!!! + +The `AppSideNav::Header::IconButton` component. + +It internally uses the [`Hds::Interactive`](/utilities/interactive) utility component. For more details about this component API, please refer to [its documentation page](/utilities/interactive?tab=code#component-api). + + + + Used to show an icon. Any [icon](/icons/library) name is accepted. + + + URL parameter that’s passed down to the `` element. + + + This controls if the `` link is external. For security reasons, we add the `target="_blank"` and `rel="noopener noreferrer"` attributes to it by default. + + + Parameters that are passed down as arguments to the ``/`` components. + + + This controls if the “LinkTo” is external to the Ember engine, in which case it will use a `` for the `@route`. + + + The value of the `aria-label`. If no text value is defined an error will be thrown. + + + This component supports use of [`...attributes`](https://guides.emberjs.com/release/in-depth-topics/patterns-for-components/#toc_attribute-ordering). + + + +### AppSideNav::PortalTarget + +The `AppSideNav::PortalTarget` component is used to receive some content "transported" through the portal and inject it into its position in the DOM tree. For details about how portals work refer to the [`ember-stargate` documentation](https://github.com/simonihmig/ember-stargate). + +!!! Info + +The component is implemented to support [multiple portals](https://github.com/simonihmig/ember-stargate#portaltarget). + +!!! + + + + The unique name used by [`ember-stargate`](https://github.com/simonihmig/ember-stargate#usage) to identify the portal. If provided, the same name must be used in the `AppSideNav::Portal` to point to the correct target. + + + This component supports use of [`...attributes`](https://guides.emberjs.com/release/in-depth-topics/patterns-for-components/#toc_attribute-ordering). + + + +### AppSideNav::Portal + +The `AppSideNav::Portal` component is used to "transport" some content through the portal into the target element. For details about how portals work refer to the [`ember-stargate` documentation](https://github.com/simonihmig/ember-stargate). + +The content yielded in the component is injected inside a `Hds::SideNav::List` element (hence all its sub-components available as yielded components). + + + + Sub-components yielded from `Hds::SideNav::List` (see below). + + + The unique name used by [`ember-stargate`](https://github.com/simonihmig/ember-stargate#usage) to identify the target portal. If provided, the same name must be used in the `AppSideNav::PortalTarget` to identify it. + + + The value of the `aria-label` that is applied to the `