mirror of
https://github.com/bitwarden/browser
synced 2025-12-16 16:23:44 +00:00
[CL-428] create drawer component (#12812)
* remove private/protected/lifecycle fields from Storybook docs table * move theme override decorator into util method * implement base drawer component * update bit-layout to be drawer container * create drawer helper components * expose new APIs to DS barrel file * write docs * update docs; add role input * use host directive instead of service * clean up logic a tad * add start slot to story * update docs * Apply suggestions from code review Co-authored-by: Victoria League <vleague@bitwarden.com> * update docs * Update libs/components/src/drawer/drawer.mdx Co-authored-by: Victoria League <vleague@bitwarden.com> * update docs / stories * add non text element to drawer --------- Co-authored-by: Victoria League <vleague@bitwarden.com>
This commit is contained in:
Will Martin
GitHub
36
libs/components/src/drawer/drawer-body.component.ts
Normal file
36
libs/components/src/drawer/drawer-body.component.ts
Normal file
@@ -0,0 +1,36 @@
|
||||
import { CdkScrollable } from "@angular/cdk/scrolling";
|
||||
import { ChangeDetectionStrategy, Component, Signal, inject } from "@angular/core";
|
||||
import { toSignal } from "@angular/core/rxjs-interop";
|
||||
import { map } from "rxjs";
|
||||
|
||||
/**
|
||||
* Body container for `bit-drawer`
|
||||
*/
|
||||
@Component({
|
||||
selector: "bit-drawer-body",
|
||||
standalone: true,
|
||||
changeDetection: ChangeDetectionStrategy.OnPush,
|
||||
imports: [],
|
||||
host: {
|
||||
class:
|
||||
"tw-p-4 tw-pt-0 tw-block tw-overflow-auto tw-border-solid tw-border tw-border-transparent tw-transition-colors tw-duration-200",
|
||||
"[class.tw-border-t-secondary-300]": "isScrolled()",
|
||||
},
|
||||
hostDirectives: [
|
||||
{
|
||||
directive: CdkScrollable,
|
||||
},
|
||||
],
|
||||
template: ` <ng-content></ng-content> `,
|
||||
})
|
||||
export class DrawerBodyComponent {
|
||||
private scrollable = inject(CdkScrollable);
|
||||
|
||||
/** TODO: share this utility with browser popup header? */
|
||||
protected isScrolled: Signal<boolean> = toSignal(
|
||||
this.scrollable
|
||||
.elementScrolled()
|
||||
.pipe(map(() => this.scrollable.measureScrollOffset("top") > 0)),
|
||||
{ initialValue: false },
|
||||
);
|
||||
}
|
||||
29
libs/components/src/drawer/drawer-close.directive.ts
Normal file
29
libs/components/src/drawer/drawer-close.directive.ts
Normal file
@@ -0,0 +1,29 @@
|
||||
import { Directive, inject } from "@angular/core";
|
||||
|
||||
import { DrawerComponent } from "./drawer.component";
|
||||
|
||||
/**
|
||||
* Closes the ancestor drawer
|
||||
*
|
||||
* @example
|
||||
*
|
||||
* ```html
|
||||
* <bit-drawer>
|
||||
* <button type="button" bitButton bitDrawerClose>Close</button>
|
||||
* </bit-drawer>
|
||||
* ```
|
||||
**/
|
||||
@Directive({
|
||||
selector: "button[bitDrawerClose]",
|
||||
standalone: true,
|
||||
host: {
|
||||
"(click)": "onClick()",
|
||||
},
|
||||
})
|
||||
export class DrawerCloseDirective {
|
||||
private drawer = inject(DrawerComponent, { optional: true });
|
||||
|
||||
protected onClick() {
|
||||
this.drawer?.open.set(false);
|
||||
}
|
||||
}
|
||||
15
libs/components/src/drawer/drawer-header.component.html
Normal file
15
libs/components/src/drawer/drawer-header.component.html
Normal file
@@ -0,0 +1,15 @@
|
||||
<header class="tw-flex tw-justify-between tw-items-center">
|
||||
<div class="tw-flex tw-items-center tw-gap-1 tw-overflow-auto">
|
||||
<ng-content select="[slot=start]"></ng-content>
|
||||
<h2 bitTypography="h3" noMargin class="tw-text-main tw-mb-0 tw-truncate" [attr.title]="title()">
|
||||
{{ title() }}
|
||||
</h2>
|
||||
</div>
|
||||
<button
|
||||
bitIconButton="bwi-close"
|
||||
type="button"
|
||||
bitDrawerClose
|
||||
[attr.title]="'close' | i18n"
|
||||
[attr.aria-label]="'close' | i18n"
|
||||
></button>
|
||||
</header>
|
||||
34
libs/components/src/drawer/drawer-header.component.ts
Normal file
34
libs/components/src/drawer/drawer-header.component.ts
Normal file
@@ -0,0 +1,34 @@
|
||||
import { CommonModule } from "@angular/common";
|
||||
import { ChangeDetectionStrategy, Component, HostBinding, input } from "@angular/core";
|
||||
|
||||
import { IconButtonModule } from "../icon-button";
|
||||
import { I18nPipe } from "../shared/i18n.pipe";
|
||||
import { TypographyModule } from "../typography";
|
||||
|
||||
import { DrawerCloseDirective } from "./drawer-close.directive";
|
||||
|
||||
/**
|
||||
* Header container for `bit-drawer`
|
||||
**/
|
||||
@Component({
|
||||
selector: "bit-drawer-header",
|
||||
standalone: true,
|
||||
changeDetection: ChangeDetectionStrategy.OnPush,
|
||||
imports: [CommonModule, DrawerCloseDirective, TypographyModule, IconButtonModule, I18nPipe],
|
||||
templateUrl: "drawer-header.component.html",
|
||||
host: {
|
||||
class: "tw-block tw-pl-4 tw-pr-2 tw-py-2",
|
||||
},
|
||||
})
|
||||
export class DrawerHeaderComponent {
|
||||
/**
|
||||
* The title to display
|
||||
*/
|
||||
title = input.required<string>();
|
||||
|
||||
/** We don't want to set the HTML title attribute with `this.title` */
|
||||
@HostBinding("attr.title")
|
||||
protected get getTitle(): null {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
28
libs/components/src/drawer/drawer-host.directive.ts
Normal file
28
libs/components/src/drawer/drawer-host.directive.ts
Normal file
@@ -0,0 +1,28 @@
|
||||
import { Portal } from "@angular/cdk/portal";
|
||||
import { Directive, signal } from "@angular/core";
|
||||
|
||||
/**
|
||||
* Host that renders a drawer
|
||||
*
|
||||
* @internal
|
||||
*/
|
||||
@Directive({
|
||||
selector: "[bitDrawerHost]",
|
||||
standalone: true,
|
||||
})
|
||||
export class DrawerHostDirective {
|
||||
private _portal = signal<Portal<unknown> | undefined>(undefined);
|
||||
|
||||
/** The portal to display */
|
||||
portal = this._portal.asReadonly();
|
||||
|
||||
open(portal: Portal<unknown>) {
|
||||
this._portal.set(portal);
|
||||
}
|
||||
|
||||
close(portal: Portal<unknown>) {
|
||||
if (portal === this.portal()) {
|
||||
this._portal.set(undefined);
|
||||
}
|
||||
}
|
||||
}
|
||||
8
libs/components/src/drawer/drawer.component.html
Normal file
8
libs/components/src/drawer/drawer.component.html
Normal file
@@ -0,0 +1,8 @@
|
||||
<ng-container *cdkPortal>
|
||||
<section
|
||||
[attr.role]="role()"
|
||||
class="tw-w-[23rem] tw-sticky tw-top-0 tw-h-screen tw-flex tw-flex-col tw-overflow-auto tw-border-0 tw-border-l tw-border-solid tw-border-secondary-300 tw-bg-background"
|
||||
>
|
||||
<ng-content></ng-content>
|
||||
</section>
|
||||
</ng-container>
|
||||
76
libs/components/src/drawer/drawer.component.ts
Normal file
76
libs/components/src/drawer/drawer.component.ts
Normal file
@@ -0,0 +1,76 @@
|
||||
import { CdkPortal, PortalModule } from "@angular/cdk/portal";
|
||||
import { CommonModule } from "@angular/common";
|
||||
import {
|
||||
ChangeDetectionStrategy,
|
||||
Component,
|
||||
effect,
|
||||
inject,
|
||||
input,
|
||||
model,
|
||||
viewChild,
|
||||
} from "@angular/core";
|
||||
|
||||
import { DrawerHostDirective } from "./drawer-host.directive";
|
||||
|
||||
/**
|
||||
* A drawer is a panel of supplementary content that is adjacent to the page's main content.
|
||||
*
|
||||
* Drawers render in `bit-layout`. Drawers must be a descendant of `bit-layout`, but they do not need to be a direct descendant.
|
||||
*/
|
||||
@Component({
|
||||
selector: "bit-drawer",
|
||||
standalone: true,
|
||||
changeDetection: ChangeDetectionStrategy.OnPush,
|
||||
imports: [CommonModule, PortalModule],
|
||||
templateUrl: "drawer.component.html",
|
||||
})
|
||||
export class DrawerComponent {
|
||||
private drawerHost = inject(DrawerHostDirective);
|
||||
private portal = viewChild.required(CdkPortal);
|
||||
|
||||
/**
|
||||
* Whether or not the drawer is open.
|
||||
*
|
||||
* Note: Does not support implicit boolean transform due to Angular limitation. Must be bound explicitly `[open]="true"` instead of just `open`.
|
||||
* https://github.com/angular/angular/issues/55166#issuecomment-2032150999
|
||||
**/
|
||||
open = model<boolean>(false);
|
||||
|
||||
/**
|
||||
* The ARIA role of the drawer.
|
||||
*
|
||||
* - [complementary](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/complementary_role)
|
||||
* - For drawers that contain content that is complementary to the page's main content. (default)
|
||||
* - [navigation](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/navigation_role)
|
||||
* - For drawers that primary contain links to other content.
|
||||
*/
|
||||
role = input<"complementary" | "navigation">("complementary");
|
||||
|
||||
constructor() {
|
||||
effect(
|
||||
() => {
|
||||
this.open() ? this.drawerHost.open(this.portal()) : this.drawerHost.close(this.portal());
|
||||
},
|
||||
{
|
||||
allowSignalWrites: true,
|
||||
},
|
||||
);
|
||||
|
||||
// Set `open` to `false` when another drawer is opened.
|
||||
effect(
|
||||
() => {
|
||||
if (this.drawerHost.portal() !== this.portal()) {
|
||||
this.open.set(false);
|
||||
}
|
||||
},
|
||||
{
|
||||
allowSignalWrites: true,
|
||||
},
|
||||
);
|
||||
}
|
||||
|
||||
/** Toggle the drawer between open & closed */
|
||||
toggle() {
|
||||
this.open.update((prev) => !prev);
|
||||
}
|
||||
}
|
||||
120
libs/components/src/drawer/drawer.mdx
Normal file
120
libs/components/src/drawer/drawer.mdx
Normal file
@@ -0,0 +1,120 @@
|
||||
import { Meta, Story, Primary, Controls } from "@storybook/addon-docs";
|
||||
|
||||
import * as stories from "./drawer.stories";
|
||||
|
||||
import { DrawerOpen as KitchenSink } from "../stories/kitchen-sink/kitchen-sink.stories";
|
||||
|
||||
<Meta of={stories} />
|
||||
|
||||
```ts
|
||||
import { DrawerComponent } from "@bitwarden/components";
|
||||
```
|
||||
|
||||
# Drawer
|
||||
|
||||
A drawer is a panel of supplementary content that is adjacent to the page's main content.
|
||||
|
||||
<Primary />
|
||||
|
||||
<Controls />
|
||||
|
||||
## Usage
|
||||
|
||||
A `bit-drawer` in a template will not render inline, but rather will render adjacent to the main
|
||||
page content.
|
||||
|
||||
```html
|
||||
<bit-drawer [open]="true">
|
||||
<bit-drawer-header title="Hello Bitwaaaaaaaaaaaaaaaaaaaaaaaaarden!"></bit-drawer-header>
|
||||
<bit-drawer-body>
|
||||
<p>Lorem ipsum dolor...</p>
|
||||
</bit-drawer-body>
|
||||
</bit-drawer>
|
||||
```
|
||||
|
||||
`bit-drawer` must be a descendant of `bit-layout`, but it does not need to be a direct descendant.
|
||||
|
||||
## Header and body
|
||||
|
||||
Header and body content can be provided with the `bit-drawer-header` and `bit-drawer-body`
|
||||
components, respectively.
|
||||
|
||||
A title can be passed to the header by input:
|
||||
`<bit-drawer-header title="Foobar"></bit-drawer-header>`
|
||||
|
||||
Custom content can be rendered before the title with the header's `start` slot:
|
||||
|
||||
```html
|
||||
<bit-drawer-header title="Foobar">
|
||||
<i slot="start" class="bwi bwi-key" aria-hidden="true"></i>
|
||||
</bit-drawer-header>
|
||||
```
|
||||
|
||||
## Opening and closing
|
||||
|
||||
`bit-drawer` opens when its `open` input is `true`:
|
||||
|
||||
```html
|
||||
<bit-drawer [open]="true">...</bit-drawer>
|
||||
```
|
||||
|
||||
Note: Model inputs do not support implicit boolean transformation (see Angular reasoning
|
||||
[here](https://github.com/angular/angular/issues/55166#issuecomment-2032150999)). `open` must be
|
||||
bound explicitly `<bit-drawer [open]="true">` instead of just `<bit-drawer open>`.
|
||||
|
||||
Buttons can be made to open/toggle drawers by referencing a template variable, or by manipulating
|
||||
state that is bound to `open`:
|
||||
|
||||
```html
|
||||
<button (click)="myDrawer.toggle()"></button> <bit-drawer #myDrawer>...</bit-drawer>
|
||||
```
|
||||
|
||||
For convenience, close buttons can be created _inside_ the drawer with the `bitDrawerClose`
|
||||
directive:
|
||||
|
||||
```html
|
||||
<bit-drawer>
|
||||
<button type="button" bitDrawerClose>Close</button>
|
||||
</bit-drawer>
|
||||
```
|
||||
|
||||
## Multiple Drawers
|
||||
|
||||
Only one drawer can be open at a time, and they do not stack. If a drawer is already open, opening
|
||||
another will close and replace the one already open.
|
||||
|
||||
<Story of={stories.MultipleDrawers} />
|
||||
|
||||
## Headless
|
||||
|
||||
Omitting `bit-drawer-header` and `bit-drawer-body` allows for fully customizable content.
|
||||
|
||||
<Story of={stories.Headless} />
|
||||
|
||||
## Accessibility
|
||||
|
||||
- The drawer should contain an h2 element. If you are using `bit-drawer-header`, this is created for
|
||||
you via the `title` input:
|
||||
|
||||
```html
|
||||
<bit-drawer>
|
||||
<h2 bitTypography="h2">Hello world!</h2>
|
||||
</bit-drawer>
|
||||
|
||||
<!-- or -->
|
||||
|
||||
<bit-drawer>
|
||||
<bit-drawer-header title="Hello world!"></bit-drawer-header>
|
||||
</bit-drawer>
|
||||
```
|
||||
|
||||
- The ARIA role of the drawer can be set with the `role` attribute:
|
||||
- [complementary](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/complementary_role)
|
||||
(default)
|
||||
- For drawers that contain content that is complementary to the page's main content.
|
||||
- [navigation](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/navigation_role)
|
||||
- For drawers that primary contain links to other content.
|
||||
|
||||
## Kitchen Sink
|
||||
|
||||
<Story of={KitchenSink} autoplay />
|
||||
12
libs/components/src/drawer/drawer.module.ts
Normal file
12
libs/components/src/drawer/drawer.module.ts
Normal file
@@ -0,0 +1,12 @@
|
||||
import { NgModule } from "@angular/core";
|
||||
|
||||
import { DrawerBodyComponent } from "./drawer-body.component";
|
||||
import { DrawerCloseDirective } from "./drawer-close.directive";
|
||||
import { DrawerHeaderComponent } from "./drawer-header.component";
|
||||
import { DrawerComponent } from "./drawer.component";
|
||||
|
||||
@NgModule({
|
||||
imports: [DrawerComponent, DrawerHeaderComponent, DrawerBodyComponent, DrawerCloseDirective],
|
||||
exports: [DrawerComponent, DrawerHeaderComponent, DrawerBodyComponent, DrawerCloseDirective],
|
||||
})
|
||||
export class DrawerModule {}
|
||||
124
libs/components/src/drawer/drawer.stories.ts
Normal file
124
libs/components/src/drawer/drawer.stories.ts
Normal file
@@ -0,0 +1,124 @@
|
||||
// FIXME: Update this file to be type safe and remove this and next line
|
||||
// @ts-strict-ignore
|
||||
import { RouterTestingModule } from "@angular/router/testing";
|
||||
import { Meta, StoryObj, moduleMetadata } from "@storybook/angular";
|
||||
|
||||
import { I18nService } from "@bitwarden/common/platform/abstractions/i18n.service";
|
||||
|
||||
import { ButtonModule } from "../button";
|
||||
import { CalloutModule } from "../callout";
|
||||
import { LayoutComponent } from "../layout";
|
||||
import { mockLayoutI18n } from "../layout/mocks";
|
||||
import {
|
||||
disableBothThemeDecorator,
|
||||
positionFixedWrapperDecorator,
|
||||
} from "../stories/storybook-decorators";
|
||||
import { TypographyModule } from "../typography";
|
||||
import { I18nMockService } from "../utils";
|
||||
|
||||
import { DrawerBodyComponent } from "./drawer-body.component";
|
||||
import { DrawerHeaderComponent } from "./drawer-header.component";
|
||||
import { DrawerComponent } from "./drawer.component";
|
||||
import { DrawerModule } from "./drawer.module";
|
||||
|
||||
export default {
|
||||
title: "Component Library/Drawer",
|
||||
component: DrawerComponent,
|
||||
subcomponents: {
|
||||
DrawerHeaderComponent,
|
||||
DrawerBodyComponent,
|
||||
},
|
||||
decorators: [
|
||||
positionFixedWrapperDecorator(),
|
||||
disableBothThemeDecorator,
|
||||
moduleMetadata({
|
||||
imports: [
|
||||
RouterTestingModule,
|
||||
LayoutComponent,
|
||||
DrawerModule,
|
||||
ButtonModule,
|
||||
CalloutModule,
|
||||
TypographyModule,
|
||||
],
|
||||
providers: [
|
||||
{
|
||||
provide: I18nService,
|
||||
useFactory: () => {
|
||||
return new I18nMockService({
|
||||
...mockLayoutI18n,
|
||||
close: "Close",
|
||||
});
|
||||
},
|
||||
},
|
||||
],
|
||||
}),
|
||||
],
|
||||
} as Meta<DrawerComponent>;
|
||||
|
||||
type Story = StoryObj<DrawerComponent>;
|
||||
|
||||
export const Default: Story = {
|
||||
render: (args) => ({
|
||||
props: args,
|
||||
template: /*html*/ `
|
||||
<bit-layout class="tw-text-main">
|
||||
<p>The drawer is {{ open ? "open" : "closed" }}.<p>
|
||||
<button type="button" bitButton (click)="drawer.toggle()">Toggle</button>
|
||||
|
||||
<!-- Note: bit-drawer does *not* need to be a direct descendant of bit-layout. -->
|
||||
<bit-drawer [(open)]="open" #drawer>
|
||||
<bit-drawer-header title="Hello Bitwaaaaaaaaaaaaaaaaaaaaaaaaarden!">
|
||||
<i slot="start" class="bwi bwi-key" aria-hidden="true"></i>
|
||||
</bit-drawer-header>
|
||||
<bit-drawer-body>
|
||||
<p bitTypography="body1">
|
||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
|
||||
</p>
|
||||
</bit-drawer-body>
|
||||
</bit-drawer>
|
||||
</bit-layout>
|
||||
`,
|
||||
}),
|
||||
args: {
|
||||
open: true,
|
||||
},
|
||||
};
|
||||
|
||||
export const Headless: Story = {
|
||||
render: (args) => ({
|
||||
props: args,
|
||||
template: /*html*/ `
|
||||
<bit-layout class="tw-text-main">
|
||||
<p>The drawer is {{ open ? "open" : "closed" }}.<p>
|
||||
<button type="button" bitButton (click)="drawer.toggle()">Toggle</button>
|
||||
<bit-drawer [(open)]="open" #drawer>
|
||||
<h2 bitTypography="h2"></h2>
|
||||
Hello world!
|
||||
</bit-drawer>
|
||||
</bit-layout>
|
||||
`,
|
||||
}),
|
||||
args: {
|
||||
open: true,
|
||||
},
|
||||
};
|
||||
|
||||
export const MultipleDrawers: Story = {
|
||||
render: (args) => ({
|
||||
props: args,
|
||||
template: /*html*/ `
|
||||
<bit-layout class="tw-text-main">
|
||||
<button type="button" bitButton (click)="foo.toggle()">{{ !foo.open() ? "Open" : "Close" }} Foo</button>
|
||||
<button type="button" bitButton (click)="bar.toggle()">{{ !bar.open() ? "Open" : "Close" }} Bar</button>
|
||||
|
||||
<bit-drawer #foo>
|
||||
Foo
|
||||
</bit-drawer>
|
||||
|
||||
<bit-drawer #bar [open]="true">
|
||||
Bar
|
||||
</bit-drawer>
|
||||
</bit-layout>
|
||||
`,
|
||||
}),
|
||||
};
|
||||
5
libs/components/src/drawer/index.ts
Normal file
5
libs/components/src/drawer/index.ts
Normal file
@@ -0,0 +1,5 @@
|
||||
export * from "./drawer.module";
|
||||
export * from "./drawer.component";
|
||||
export * from "./drawer-body.component";
|
||||
export * from "./drawer-close.directive";
|
||||
export * from "./drawer-header.component";
|
||||
Reference in New Issue
Block a user