Skip to content

Commit

Permalink
HDS-3807 Remove references to old header child components and named b…
Browse files Browse the repository at this point in the history 
…locks
  • Loading branch information
@KristinLBradley
KristinLBradley committed Sep 16, 2024
1 parent d1a365d commit f5a98ed
Show file tree
Hide file tree
Showing 2 changed files with 7 additions and 215 deletions.
94 changes: 3 additions & 91 deletions website/docs/components/app-side-nav/partials/code/component-api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,7 @@ This is the full-fledged component (responsive and animated).

<Doc::ComponentApi as |C|>
<C.Property @name="<:header>" @type="named block">
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.
<br><br>
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.
</C.Property>
<C.Property @name="<:body>" @type="named block">
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.
Expand Down Expand Up @@ -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.
</C.Property>
<C.Property @name="<:header>" @type="named block">
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.
</C.Property>
<C.Property @name="<:body>" @type="named block">
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.
</C.Property>
<C.Property @name="<:footer>" @type="named block">
A named block where the content for the “footer” section of the App Side Nav is rendered.
</C.Property>
<C.Property @name="...attributes">
This component supports use of [`...attributes`](https://guides.emberjs.com/release/in-depth-topics/patterns-for-components/#toc_attribute-ordering).
</C.Property>
</Doc::ComponentApi>

### AppSideNav::Header

<Doc::ComponentApi as |C|>
<C.Property @name="<:logo>" @type="named block">
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.
</C.Property>
<C.Property @name="<:actions>" @type="named block">
A named block where the header “action” components will be rendered. Typically `Dropdown` components and/or `AppSideNav::IconButton` components will be added here.
</C.Property>
<C.Property @name="...attributes">
This component supports use of [`...attributes`](https://guides.emberjs.com/release/in-depth-topics/patterns-for-components/#toc_attribute-ordering).
</C.Property>
</Doc::ComponentApi>

### 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).

<Doc::ComponentApi as |C|>
<C.Property @name="icon" @type="string">
Used to show an icon. Any [icon](/icons/library) name is accepted. Typically you would add the icon name for your product.
</C.Property>
<C.Property @name="color" @type="string">
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.
</C.Property>
<C.Property @name="href">
URL parameter that’s passed down to the `<a>` element.
</C.Property>
<C.Property @name="isHrefExternal" @type="boolean" @default="false">
This controls if the `<a>` link is external. For security reasons, we add the `target="_blank"` and `rel="noopener noreferrer"` attributes to it by default.
</C.Property>
<C.Property @name="route/models/model/query/current-when/replace">
Parameters that are passed down as arguments to the `<LinkTo>`/`<LinkToExternal>` components.
</C.Property>
<C.Property @name="isRouteExternal" @type="boolean" @default="false">
This controls if the “LinkTo” is external to the Ember engine, in which case it will use a `<LinkToExternal>` for the `@route`.
</C.Property>
<C.Property @name="ariaLabel" @type="string" @required={{true}}>
The value of the aria-label. If no text value is defined an error will be thrown.
</C.Property>
<C.Property @name="...attributes">
This component supports use of [`...attributes`](https://guides.emberjs.com/release/in-depth-topics/patterns-for-components/#toc_attribute-ordering).
</C.Property>
</Doc::ComponentApi>

### 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).

<Doc::ComponentApi as |C|>
<C.Property @name="icon" @type="string" @required={{true}}>
Used to show an icon. Any [icon](/icons/library) name is accepted.
</C.Property>
<C.Property @name="href">
URL parameter that’s passed down to the `<a>` element.
</C.Property>
<C.Property @name="isHrefExternal" @type="boolean" @default="false">
This controls if the `<a>` link is external. For security reasons, we add the `target="_blank"` and `rel="noopener noreferrer"` attributes to it by default.
</C.Property>
<C.Property @name="route/models/model/query/current-when/replace">
Parameters that are passed down as arguments to the `<LinkTo>`/`<LinkToExternal>` components.
</C.Property>
<C.Property @name="isRouteExternal" @type="boolean" @default="false">
This controls if the “LinkTo” is external to the Ember engine, in which case it will use a `<LinkToExternal>` for the `@route`.
</C.Property>
<C.Property @name="ariaLabel" @type="string" @required={{true}}>
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.
</C.Property>
<C.Property @name="...attributes">
This component supports use of [`...attributes`](https://guides.emberjs.com/release/in-depth-topics/patterns-for-components/#toc_attribute-ordering).
Expand Down
128 changes: 4 additions & 124 deletions website/docs/components/app-side-nav/partials/code/how-to-use.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ It exposes three “slots” (named blocks) where the consumers can yield the na
<div class="doc-app-sidenav-demo">
<Hds::AppSideNav>
<:header>
<Doc::Placeholder @height="72px" @text="&lt;:header /&gt;" @background="#e4e4e4" />
<Doc::Placeholder @height="36px" @text="&lt;:header /&gt;" @background="#e4e4e4" />
</:header>
<:body>
<Doc::Placeholder @height="500px" @text="&lt;:body /&gt;" @background="#e4e4e4" />
Expand All @@ -47,140 +47,23 @@ It also comes with a set of CSS properties that automatically set the App Side N

### Content

#### Header (`<:header>`)

<mark>TODO: Should :header block be simplified or removed entirely?</mark>

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 `<Hds::AppSideNav::Header::HomeLink>` (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.

```handlebars
<div class="doc-app-sidenav-demo--short">
<Hds::AppSideNav>
<:header>
<Hds::AppSideNav::Header>
<:logo>
<Doc::Placeholder @width="100%" @height="100%" @text="logo" @background="#e4e4e4" />
</:logo>
<:actions>
<Doc::Placeholder @width="150px" @height="36px" @text="actions" @background="#e4e4e4" />
</:actions>
</Hds::AppSideNav::Header>
<Doc::Placeholder @width="100%" @height="100%" @text="custom header content" @background="#e4e4e4" />
</:header>
{{! ... }}
</Hds::AppSideNav>
</div>
```

##### Logo

To add a logo to the "header" of the App Side Nav use the `<Hds::AppSideNav::Header::HomeLink>` sub-component.

It requires a value for the `@icon` and `@ariaLabel` arguments:

```handlebars
<div class="doc-app-sidenav-demo--short">
<Hds::AppSideNav>
<:header>
<Hds::AppSideNav::Header>
<:logo>
<Hds::AppSideNav::Header::HomeLink @icon="hashicorp" @ariaLabel="HashiCorp home menu" @href="#" />
</:logo>
<:actions>
<Doc::Placeholder @width="150px" @height="36px" @text="actions" @background="#e4e4e4" />
</:actions>
</Hds::AppSideNav::Header>
</:header>
{{! ... }}
</Hds::AppSideNav>
</div>
```

It also accepts optional arguments, for example it’s possible to provide a custom color for the icon if needed:

```handlebars
<div class="doc-app-sidenav-demo--short">
<Hds::AppSideNav>
<:header>
<Hds::AppSideNav::Header>
<:logo>
<Hds::AppSideNav::Header::HomeLink
@icon="boundary"
{{! you can provide a custom color for the icon }}
@color="var(--token-color-boundary-brand)"
@ariaLabel="Boundary home menu"
@href="#"
/>
</:logo>
<:actions>
<Doc::Placeholder @width="150px" @height="36px" @text="actions" @background="#e4e4e4" />
</:actions>
</Hds::AppSideNav::Header>
</:header>
{{!-- ... --}}
</Hds::AppSideNav>
</div>
```

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
<div class="doc-app-sidenav-demo--short">
<Hds::AppSideNav>
<:header>
<Hds::AppSideNav::Header>
<:logo>
<Hds::AppSideNav::Header::HomeLink @icon="hashicorp" @ariaLabel="HashiCorp home menu" @href="#" />
</:logo>
<:actions>
<Hds::Button @icon="search" @isIconOnly={{true}} @text="Search" />
<Hds::Dropdown @enableCollisionDetection={{true}} as |dd|>
<dd.ToggleIcon @icon="help" @text="settings menu" />
<dd.Title @text="Help & Support" />
<dd.Interactive @text="Documentation" @href="#" />
<dd.Interactive @text="Tutorials" @href="#" />
<dd.Interactive @text="Terraform Provider" @href="#" />
<dd.Interactive @text="Changelog" @href="#" />
<dd.Separator />
<dd.Interactive @text="Create support ticket" @href="#" />
<dd.Interactive @text="Give feedback" @href="#" />
</Hds::Dropdown>
<Hds::Dropdown @enableCollisionDetection={{true}} as |dd|>
<dd.ToggleIcon @icon="user" @text="user menu" />
<dd.Title @text="Signed In" />
<dd.Description @text="email@domain.com" />
<dd.Interactive @href="#" @text="Account Settings" />
</Hds::Dropdown>
</:actions>
</Hds::AppSideNav::Header>
</:header>
{{! ... }}
</Hds::AppSideNav>
</div>
```

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.
Expand Down Expand Up @@ -465,15 +348,12 @@ Here is an example of how the component could be used:
</div>
```

In this example we’re using the `<Hds::AppSideNav::Header>` and `<Hds::AppSideNav::Header::HomeLink>` 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.
Expand Down

0 comments on commit f5a98ed

Please sign in to comment.