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 index a9ac3c26fa..f0b9d1b53b 100644 --- a/website/docs/components/app-side-nav/partials/code/component-api.md +++ b/website/docs/components/app-side-nav/partials/code/component-api.md @@ -6,9 +6,7 @@ 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 optional content for the “header” area of the App Side Nav is rendered. It yields the value of `isMinimized` too. 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. @@ -51,99 +49,13 @@ 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 optional content for the “header” area of the App Side Nav is rendered. 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. + A named block where optional 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). diff --git a/website/docs/components/app-side-nav/partials/code/how-to-use.md b/website/docs/components/app-side-nav/partials/code/how-to-use.md index 627c516dee..b6ebbfa506 100644 --- a/website/docs/components/app-side-nav/partials/code/how-to-use.md +++ b/website/docs/components/app-side-nav/partials/code/how-to-use.md @@ -31,7 +31,7 @@ It exposes three “slots” (named blocks) where the consumers can yield the na
<:header> - + <:body> @@ -47,14 +47,9 @@ It also comes with a set of CSS properties that automatically set the App Side N ### Content -#### Header (`<:header>`) - -TODO: Should :header block be simplified or removed entirely? - -Typically the `Hds::AppSideNav::Header` sub-component should be added here if used. It provides two slots (named blocks): +Standard HDS [`Button`](/components/button) and [`Dropdown`](/components/dropdown) components can be used within the App Side Nav where needed. We recommend setting `enableCollisionDetection` to `true` for each Dropdown component used within the App Side Nav. -- the `<:logo>` block should contain the `` (but it could contain also custom content, if necessary) -- the `<:actions>` block should contain optional top-level actions (eg. global search, user menu, help menu, etc.) +#### Header (`<:header>`) Note: When the App Side Nav is paired with the [`Hds::AppHeader`](/components/app-header) component, the `<:header>` slot normally is not used. @@ -62,125 +57,13 @@ Note: When the App Side Nav is paired with the [`Hds::AppHeader`](/components/ap
<:header> - - <:logo> - - - <:actions> - - - + {{! ... }}
``` -##### Logo - -To add a logo to the "header" of the App Side Nav use the `` sub-component. - -It requires a value for the `@icon` and `@ariaLabel` arguments: - -```handlebars -
- - <:header> - - <:logo> - - - <:actions> - - - - - {{! ... }} - -
-``` - -It also accepts optional arguments, for example it’s possible to provide a custom color for the icon if needed: - -```handlebars -
- - <:header> - - <:logo> - - - <:actions> - - - - - {{!-- ... --}} - -
-``` - -The HomeLink is built on top of the [`Hds::Interactive` component](/utilities/interactive), so it accepts all its routing arguments (eg. `@href`, `@route`, `@query`, `@model(s)`, etc.). - -Refer to the [Component API section](/components/app-sidenav?tab=code#sidenavheaderhomelink) for details. - -##### Actions - -This block is intended to contain top-level actionable elements like dropdowns and buttons. - -Here is an example of some possible actions: - -```handlebars -
- - <:header> - - <:logo> - - - <:actions> - - - - - - - - - - - - - - - - - - - - - - {{! ... }} - -
-``` - -Standard HDS [`Button`](/components/button) and [`Dropdown`](/components/dropdown) components can be used within the App Side Nav where needed. We recommend setting `enableCollisionDetection` to `true` for each Dropdown component used within the App Side Nav. - -You can also add custom elements to the `<:actions>` block, if these don’t cover your specific needs. - -!!! Info - -The “actions” block is automatically faded in/out whenever the App Side Nav transition between minimized/maximized states (see [Responsiveness](#responsiveness) below for details). - -!!! - #### Body (`<:body>`) The `<:body>` block is where the actual navigation lives. It’s an agnostic container, in which consumers _in principle_ can add anything they want, in the order they want. @@ -465,15 +348,12 @@ Here is an example of how the component could be used:
``` -In this example we’re using the `` and `` but _in theory_ you could use your own content for the `<:header>` block (same for the `<:footer>`). - A special “slot” called `<:root>` is also available: it can be used to add content that needs to live within the App Side Nav, but can’t be added to the “header/body/footer” containers. For details about these slots, see the [“Component API”](/components/app-sidenav?tab=code#component-api) section. In theory, one could also use portals to inject the content, but this somehow defeats the purpose of the `Hds::AppSideNav::Base` component: its simplicity of use. So if you find yourself in need of using portals, consider adopting the full-featured variant of the App Side Nav component instead. - ### Responsiveness This base component is **not** responsive: this means its width is fixed, at any viewport size.