mirror of
https://github.com/bitwarden/browser
synced 2026-02-16 16:59:30 +00:00
226 lines
6.8 KiB
Plaintext
226 lines
6.8 KiB
Plaintext
import { Meta } from "@storybook/addon-docs/blocks";
|
|
|
|
<Meta title="Documentation/Migration" />
|
|
|
|
# Migrating to the Component Library
|
|
|
|
## Background
|
|
|
|
Bitwarden is in the process of migrating client code to fully use the Component Library.
|
|
|
|
Previously, the clients used a mix of multiple UI frameworks: Bootstrap, custom "box" styles, and
|
|
this component library, which is built on top of Tailwind.
|
|
|
|
Bootstrap is now removed from the clients repo in favor of using Tailwind Preflight for global reset
|
|
styles.
|
|
|
|
Tailwind is used in client code where layout-level html is written in conjunction with Component
|
|
Library components.
|
|
|
|
Some custom css still lingers in all the clients and is planned to be removed. Do not write more
|
|
custom css.
|
|
|
|
## Performing a migration
|
|
|
|
You have been tasked with migrating a component to use the CL. What does that entail?
|
|
|
|
### Getting Started
|
|
|
|
Before progressing here, please ensure that...
|
|
|
|
- You have fully setup your dev environment as described in the
|
|
[contributing docs](https://contributing.bitwarden.com/).
|
|
- You are familiar with [Angular reactive forms](https://angular.io/guide/reactive-forms).
|
|
- You are familiar with [Tailwind](https://tailwindcss.com/docs/utility-first).
|
|
|
|
This is very important work. Centralizing around a shared design system will:
|
|
|
|
- improve user experience by utilizing consistent patterns
|
|
- improve developer experience by reducing custom complex UI code
|
|
- improve dev & design velocity by having a central location to make UI/UX changes that impact the
|
|
entire project
|
|
|
|
### Success Criteria
|
|
|
|
Follow these steps to fully migrate a component.
|
|
|
|
#### Use Storybook
|
|
|
|
Don't recreate the wheel.
|
|
|
|
After reviewing a design, consult this Storybook to determine if there is a component built for your
|
|
usecase. Don't waste effort styling a button or building a popover menu from scratch--we already
|
|
have those. If a component isn't flexible enough or doesn't exist for your usecase, contact the
|
|
Component Library team.
|
|
|
|
#### Use Tailwind
|
|
|
|
Only use Tailwind for styling. No Bootstrap or other custom CSS is allowed.
|
|
|
|
This is easy to verify. Bitwarden prefixes all Tailwind classes with `tw-`. If you see a class
|
|
without this prefix, it probably shouldn't be there.
|
|
|
|
<div class="tw-bg-danger-600/10 tw-p-4">
|
|
<span class="tw-font-medium tw-text-danger">Bad (Bootstrap)</span>
|
|
```html
|
|
<div class="mb-2"></div>
|
|
```
|
|
</div>
|
|
|
|
<div class="tw-bg-success-600/10 tw-p-4">
|
|
<span class="tw-font-medium tw-text-success">Good (Tailwind)</span>
|
|
```html
|
|
<div class="tw-mb-2"></div>
|
|
```
|
|
</div>
|
|
|
|
**Exception:** Icon font classes, prefixed with `bwi`, are allowed.
|
|
|
|
<div class="tw-bg-success-600/10 tw-p-4">
|
|
<span class="tw-font-medium tw-text-success">Good (Icons)</span>
|
|
```html
|
|
<i class="bwi bwi-spinner bwi-lg bwi-spin" aria-hidden="true"></i>
|
|
```
|
|
</div>
|
|
|
|
#### Use Reactive Forms
|
|
|
|
The CL has form components that integrate with Angular's reactive forms: `bit-form-field`,
|
|
`bitSubmit`, `bit-form-control`, etc. All forms should be migrated from template-drive forms to
|
|
reactive forms to make use of these components. Review the
|
|
[form component docs](?path=/docs/component-library-form--docs).
|
|
|
|
<div class="tw-bg-danger-600/10 tw-p-4">
|
|
<span class="tw-text-danger tw-font-medium">Bad</span>
|
|
```html
|
|
<form #form (ngSubmit)="submit()">
|
|
...
|
|
</form>
|
|
```
|
|
</div>
|
|
|
|
<div class="tw-bg-success-600/10 tw-p-4">
|
|
<span class="tw-text-success tw-font-medium">Good</span>
|
|
```html
|
|
<form [formGroup]="formGroup" [bitSubmit]="submit">
|
|
...
|
|
</form>
|
|
```
|
|
</div>
|
|
|
|
#### Dialogs
|
|
|
|
Legacy Bootstrap modals use the `ModalService`. These should be converted to use the `DialogService`
|
|
and it's [related CL components](?path=/docs/component-library-dialogs--docs). Components that are
|
|
fully migrated should have no reference to the `ModalService`.
|
|
|
|
1. Update the template to use CL components:
|
|
|
|
<div class="tw-bg-danger-600/10 tw-p-4">
|
|
```html
|
|
<!-- FooDialogComponent -->
|
|
<div class="modal fade" role="dialog" aria-modal="true">...</div>
|
|
```
|
|
</div>
|
|
|
|
<div class="tw-bg-success-600/10 tw-p-4">
|
|
```html
|
|
<!-- FooDialogComponent -->
|
|
<bit-dialog>...</bit-dialog>
|
|
```
|
|
</div>
|
|
|
|
2. Create a static `open` method on the component, that calls `DialogService.open`:
|
|
|
|
<div class="tw-bg-success-600/10 tw-p-4">
|
|
```ts
|
|
export class FooDialogComponent {
|
|
//...
|
|
|
|
static open(dialogService: DialogService) {
|
|
return dialogService.open(DeleteAccountComponent);
|
|
}
|
|
}
|
|
```
|
|
|
|
</div>
|
|
|
|
3. If you need to pass data into the dialog, pass it to `open` as a parameter and inject
|
|
`DIALOG_DATA` into the component's constructor.
|
|
|
|
<div class="tw-bg-success-600/10 tw-p-4">
|
|
```ts
|
|
export type FooDialogParams = {
|
|
bar: string;
|
|
}
|
|
|
|
export class FooDialogComponent {
|
|
constructor(@Inject(DIALOG_DATA) protected params: FooDialogParams) {}
|
|
|
|
static open(dialogService: DialogService, data: FooDialogParams) {
|
|
return dialogService.open(DeleteAccountComponent, { data });
|
|
}
|
|
}
|
|
```
|
|
|
|
</div>
|
|
|
|
4. Replace calls to `ModalService.open` or `ModalService.openViewRef` with the newly created static
|
|
`open` method:
|
|
|
|
<div class="tw-bg-danger-600/10 tw-p-4">`this.modalService.open(FooDialogComponent);`</div>
|
|
|
|
<div class="tw-bg-success-600/10 tw-p-4">`FooDialogComponent.open(this.dialogService);`</div>
|
|
|
|
### Examples
|
|
|
|
The following examples come from accross the Bitwarden codebase.
|
|
|
|
#### 1.) AboutComponent
|
|
|
|
Codeowner: Platform
|
|
|
|
https://github.com/bitwarden/clients/pull/6301/files
|
|
|
|
This migration updates a `ModalService` component to the `DialogService`.
|
|
|
|
**Note:** Most of the internal markup of this component was unchanged, aside from the removal of
|
|
defunct Bootstrap classes.
|
|
|
|
#### 2.) Auth
|
|
|
|
Codeowner: Auth
|
|
|
|
https://github.com/bitwarden/clients/pull/5377
|
|
|
|
This PR also does some general refactoring, the main relevant change can be seen here:
|
|
|
|
[Old template](https://github.com/bitwarden/clients/pull/5377/files#diff-4fcab9ffa4ed26904c53da3bd130e346986576f2372e90b0f66188c809f9284d)
|
|
-->
|
|
[New template](https://github.com/bitwarden/clients/pull/5377/files#diff-cb93c74c828b9b49dc7869cc0324f5f7d6609da6f72e38ac6baba6d5b6384327)
|
|
|
|
Updates a dialog, similar to example 1, but also adds CL form components and Angular Reactive Forms.
|
|
|
|
#### 3.) AC
|
|
|
|
Codeowner: Admin Console
|
|
|
|
https://github.com/bitwarden/clients/pull/5417
|
|
|
|
Migrates dialog, form, buttons, and a table.
|
|
|
|
#### 4.) Vault
|
|
|
|
Codeowner: Vault
|
|
|
|
https://github.com/bitwarden/clients/pull/5648
|
|
|
|
Some of our components are shared between multiple clients (web, desktop, and the browser extension)
|
|
through the use of inheritance. This PR updates the _web_ template of a cross-client component to
|
|
use Tailwind and the CL, and updates the base component implementation to use reactive forms,
|
|
without updating the desktop or browser templates.
|
|
|
|
### Questions
|
|
|
|
Please direct any development questions to the Component Library team. Thank you!
|