bitwarden-clients/libs/components/src/anon-layout/anon-layout.mdx

import { Meta, Story, Controls } from "@storybook/addon-docs/blocks";

import * as stories from "./anon-layout.stories";

<Meta of={stories} />

# AnonLayout Component

The AnonLayoutComponent is to be used primarily for unauthenticated pages\*, where we don't know who
the user is.

\*There will be a few exceptions to this&mdash;that is, AnonLayout will also be used for the Unlock
and View Send pages.

---

### Incorrect Usage ❌

The AnonLayoutComponent is **not** to be implemented by every component that uses it in that
component's template directly. For example, if you have a component template called
`example.component.html`, and you want it to use the AnonLayoutComponent, you will **not** be
writing:

```html
<!-- File: example.component.html -->

<auth-anon-layout>
  <div>Example component content</div>
</auth-anon-layout>
```

### Correct Usage ✅

Instead the AnonLayoutComponent is implemented solely in the router via routable composition, which
gives us the advantages of nested routes in Angular.

To allow for routable composition, Auth also provides an AnonLayout**Wrapper**Component which embeds
the AnonLayoutComponent.

For clarity:

- AnonLayoutComponent = the base, Auth-owned library component - `<auth-anon-layout>`
- AnonLayout**Wrapper**Component = the wrapper to be used in client routing modules

The AnonLayout**Wrapper**Component embeds the AnonLayoutComponent along with the router outlets:

```html
<!-- File: anon-layout-wrapper.component.html -->

<auth-anon-layout
  [title]="pageTitle"
  [subtitle]="pageSubtitle"
  [icon]="pageIcon"
  [showReadonlyHostname]="showReadonlyHostname"
>
  <router-outlet></router-outlet>
  <router-outlet slot="secondary" name="secondary"></router-outlet>
  <router-outlet slot="environment-selector" name="environment-selector"></router-outlet>
</auth-anon-layout>
```

To implement, the developer does not need to work with the base AnonLayoutComponent directly. The
devoloper simply uses the AnonLayout**Wrapper**Component in `oss-routing.module.ts` (for Web, for
example) to construct the page via routable composition:

```typescript
// File: oss-routing.module.ts
import { AnonLayoutWrapperComponent, AnonLayoutWrapperData } from "@bitwarden/auth/angular";
import { LockIcon } from "@bitwarden/assets/svg";

{
  path: "",
  component: AnonLayoutWrapperComponent, // Wrapper component
  children: [
    {
      path: "sample-route", // replace with your route
      children: [
        {
          path: "",
          component: MyPrimaryComponent, // replace with your component
        },
        {
          path: "",
          component: MySecondaryComponent, // replace with your component (or remove this secondary outlet object entirely if not needed)
          outlet: "secondary",
        },
      ],
      data: {
        pageTitle: "logIn", // example of a translation key from messages.json
        pageSubtitle: "loginWithMasterPassword", // example of a translation key from messages.json
        pageIcon: LockIcon, // example of an icon to pass in
      } satisfies AnonLayoutWrapperData,
    },
  ],
},
```

(Notice that you can optionally add an `outlet: "secondary"` if you want to project secondary
content below the primary content).

If the AnonLayout**Wrapper**Component is already being used in your client's routing module, then
your work will be as simple as just adding another child route under the `children` array.

<br />

### Data Properties

Routes that use the AnonLayou**tWrapper**Component can take several unique data properties defined
in the `AnonLayoutWrapperData` interface:

- For the `pageTitle` and `pageSubtitle` - pass in a translation key from `messages.json`.
- For the `pageIcon` - import an icon (of type `Icon`) into the router file and use the icon
  directly.
- `showReadonlyHostname` - set to `true` if you want to show the hostname in the footer (ex:
  "Accessing bitwarden.com")

All of these properties are optional.

```typescript
import { AnonLayoutWrapperComponent, AnonLayoutWrapperData } from "@bitwarden/auth/angular";
import { LockIcon } from "@bitwarden/assets/svg";

{
  // ...
  data: {
    pageTitle: "logIn",
    pageSubtitle: "loginWithMasterPassword",
    pageIcon: LockIcon,
    showReadonlyHostname: true,
  } satisfies AnonLayoutWrapperData,
}
```

### Environment Selector

For some routes, you may want to display the environment selector in the footer of the
AnonLayoutComponent. To do so, add the relevant environment selector (Web or Libs version, depending
on your client) as a component with `outlet: "environment-selector"`.

```javascript
// File: oss-routing.module.ts
import { AnonLayoutWrapperComponent, AnonLayoutWrapperData } from "@bitwarden/auth/angular";

import { EnvironmentSelectorComponent } from "./components/environment-selector/environment-selector.component";

{
  path: "",
  component: AnonLayoutWrapperComponent,
  children: [
    {
      path: "sample-route",
      children: [
        {
          path: "",
          component: MyPrimaryComponent,
        },
        {
          path: "",
          component: EnvironmentSelectorComponent, // use Web or Libs component depending on your client
          outlet: "environment-selector",
        },
      ],
      // ...
    },
  ],
},
```

---

<Story of={stories.SecondaryContent} />