mirror of
https://github.com/bitwarden/browser
synced 2025-12-15 15:53:27 +00:00
Update CL documentation (#5379)
This commit is contained in:
Oscar Hinton
GitHub
@@ -81,13 +81,13 @@ import { Meta } from "@storybook/addon-docs";
|
||||
|
||||
# Bitwarden Component Library
|
||||
|
||||
The Bitwarden Component Library is a collection of reusable low level components which empowers designers and
|
||||
developers to work more efficiently. The primary goal is to ensure a consistent design and behavior across the
|
||||
different clients and platforms. Currently the primary focus is the web based clients, namely _web_, _browser_ and
|
||||
_desktop_.
|
||||
The Bitwarden Component Library is a collection of reusable low level components which empowers
|
||||
designers and developers to work more efficiently. The primary goal is to ensure a consistent design
|
||||
and behavior across the different clients and platforms. Currently the primary focus is the web
|
||||
based clients, namely _web_, _browser_ and _desktop_.
|
||||
|
||||
**Roll out status:** we are currently in the process of transitioning the Web Vault to utilize the component library
|
||||
and the other clients will follow once this work is completed.
|
||||
**Roll out status:** we are currently in the process of transitioning the Web Vault to utilize the
|
||||
component library and the other clients will follow once this work is completed.
|
||||
|
||||
<div className="subheading">Configure</div>
|
||||
|
||||
|
||||
@@ -4,20 +4,21 @@ import { Meta, Story } from "@storybook/addon-docs";
|
||||
|
||||
# Banner
|
||||
|
||||
Banners are used for important communication with the user that needs to be seen right away, but has little effect on
|
||||
the experience. Banners appear at the top of the user's screen on page load and persist across all pages a user
|
||||
navigates to.
|
||||
Banners are used for important communication with the user that needs to be seen right away, but has
|
||||
little effect on the experience. Banners appear at the top of the user's screen on page load and
|
||||
persist across all pages a user navigates to.
|
||||
|
||||
- They should always be dismissable and never use a timeout. If a user dismisses a banner, it should not reappear
|
||||
during that same active session.
|
||||
- Use banners sparingly, as they can feel intrusive to the user if they appear unexpectedly. Their effectiveness may
|
||||
decrease if too many are used.
|
||||
- They should always be dismissable and never use a timeout. If a user dismisses a banner, it should
|
||||
not reappear during that same active session.
|
||||
- Use banners sparingly, as they can feel intrusive to the user if they appear unexpectedly. Their
|
||||
effectiveness may decrease if too many are used.
|
||||
- Avoid stacking multiple banners.
|
||||
- Banners supports buttons and anchors using [bitLink](?path=/story/component-library-link--anchors).
|
||||
- Banners support a button link (text button).
|
||||
|
||||
## Types
|
||||
|
||||
Icons should remain consistent across these types. Do not change the icon without consulting designers.
|
||||
Icons should remain consistent across these types. Do not change the icon without consulting
|
||||
designers.
|
||||
|
||||
Use the following guidelines to help choose the correct type of banner.
|
||||
|
||||
@@ -47,5 +48,6 @@ Rarely used, but may be used to alert users over critical messages or very outda
|
||||
|
||||
## Accessibility
|
||||
|
||||
Dialogs sets the `role="status"` and `aria-live="polite"` attributes to ensure screen readers announce the content
|
||||
prior to the test of the page. This behaviour can be disabled by setting `[useAlertRole]="false"`.
|
||||
Banners sets the `role="status"` and `aria-live="polite"` attributes to ensure screen readers
|
||||
announce the content prior to the test of the page. This behaviour can be disabled by setting
|
||||
`[useAlertRole]="false"`.
|
||||
|
||||
@@ -4,30 +4,54 @@ import { Meta, Story } from "@storybook/addon-docs";
|
||||
|
||||
# Button
|
||||
|
||||
Use buttons for actions in forms, dialogs, and more with support for style, block, icon, and state.
|
||||
Buttons are interactive elements that can be triggered using a mouse, keyboard, or touch. They are
|
||||
used to indicate actions that can be performed by a user such as submitting a form.
|
||||
|
||||
For pairings in the bottom left corner of a page or component, the `primary` call to action will go on the left side of a button group with the `secondary` call to action option on the left.
|
||||
## Guidelines
|
||||
|
||||
Pairings in the top right corner of a page, should have the `primary` call to action on the right.
|
||||
### Choosing the `<a>` or `<button>`
|
||||
|
||||
Groups of buttons should have 1rem of spacing between them.
|
||||
|
||||
## Choosing the `<a>` or `<button>`
|
||||
|
||||
Buttons can use either the `<a>` or `<button>` tags. Choose which based on the action the button takes:
|
||||
Buttons can use either the `<a>` or `<button>` tags. Choose which based on the action the button
|
||||
takes:
|
||||
|
||||
- If navigating to a new page, use `<a>`
|
||||
- If taking an action on the current page use `<button>`
|
||||
- If the button launches a dialog, use `<button>`
|
||||
|
||||
## Submit and async actions
|
||||
### Groups
|
||||
|
||||
Both submit and async action buttons use a loading button state while an action is taken.
|
||||
Groups of buttons should be seperated by a `0.5` rem gap. Usually acomplished by using the
|
||||
`tw-gap-2` class in the button group container.
|
||||
|
||||
Groups within page content, dialog footers or forms should have the `primary` call to action placed
|
||||
to left. Groups in headers and navigational areas should have the `primary` call to action on the
|
||||
right.
|
||||
|
||||
## Accessibility
|
||||
|
||||
Please follow these guidelines to ensure that buttons are accessible to all users.
|
||||
|
||||
### Color contrast
|
||||
|
||||
All button styles are WCAG compliant when displayed on `background` and `background-alt` colors. To
|
||||
use a button on a different background, double check that the color contrast is sufficient in both
|
||||
the light and dark themes.
|
||||
|
||||
### Loading Buttons
|
||||
|
||||
Include an `aria-label` attribute that defaults to “loading” but can be configurable per
|
||||
implementation. On click, the screen reader should announce the `aria-label`. Once the action is
|
||||
compelted, use another messaging pattern to alert the user that the action is complete (example:
|
||||
success toast).
|
||||
|
||||
### Submit and async actions
|
||||
|
||||
Both submit and async action buttons use a loading button state while an action is taken. If your
|
||||
button is preforming a long running task in the background like a server API call, be sure to review
|
||||
the [Async Actions Directive](?path=/story/component-library-async-actions-overview--page).
|
||||
|
||||
<Story id="component-library-button--loading" />
|
||||
|
||||
If your button is preforming a long running task in the background like a server API call, be sure to review the [Async Actions Directive](https://components.bitwarden.com/?path=/story/component-library-async-actions-overview--page).
|
||||
|
||||
## Styles
|
||||
|
||||
There are 3 main styles for the button: Primary, Secondary, and Danger.
|
||||
@@ -36,13 +60,16 @@ There are 3 main styles for the button: Primary, Secondary, and Danger.
|
||||
|
||||
<Story id="component-library-button--primary" />
|
||||
|
||||
Use the primary button styling for all Primary call to actions. An action is "primary" if it relates to the main purpose of a page. There should never be 2 primary styled buttons next to each other.
|
||||
Use the primary button styling for all Primary call to actions. An action is "primary" if it relates
|
||||
to the main purpose of a page. There should never be 2 primary styled buttons next to each other.
|
||||
|
||||
### Secondary
|
||||
|
||||
<Story id="component-library-button--secondary" />
|
||||
|
||||
The secondary styling should be used for secondary calls to action. An action is "secondary" if it relates indirectly to the purpose of a page. There may be multiple secondary buttons next to each other; however, generally there should only be 1 or 2 calls to action per page.
|
||||
The secondary styling should be used for secondary calls to action. An action is "secondary" if it
|
||||
relates indirectly to the purpose of a page. There may be multiple secondary buttons next to each
|
||||
other; however, generally there should only be 1 or 2 calls to action per page.
|
||||
|
||||
### Danger
|
||||
|
||||
@@ -52,22 +79,14 @@ Use the danger styling only in settings when the user may preform a permanent ac
|
||||
|
||||
## Disabled UI
|
||||
|
||||
Both the disabled and loading states use the default state’s color with a 60% opacity or `tw-opacity-60`.
|
||||
Both the disabled and loading states use the default state’s color with a 60% opacity or
|
||||
`tw-opacity-60`.
|
||||
|
||||
<Story id="component-library-button--disabled" />
|
||||
|
||||
## Block
|
||||
|
||||
Typically button widths expand with their text. In some causes though buttons may need to be block where the width is fixed and the text wraps to 2 lines if exceeding the button’s width.
|
||||
Typically button widths expand with their text. In some causes though buttons may need to be block
|
||||
where the width is fixed and the text wraps to 2 lines if exceeding the button’s width.
|
||||
|
||||
<Story id="component-library-button--block" />
|
||||
|
||||
## Accessibility
|
||||
|
||||
### Color contrast
|
||||
|
||||
All button styles are WCAG compliant when displayed on `background` and `background-alt` colors. To use a button on a different background, double check that the color contrast is sufficient in both the light and dark themes.
|
||||
|
||||
### Loading Buttons
|
||||
|
||||
Include an `aria-label` attribute that defaults to “loading” but can be configurable per implementation. On click, the screen reader should announce the `aria-label`. Once the action is compelted, use another messaging pattern to alert the user that the action is complete (example: success toast).
|
||||
|
||||
@@ -89,6 +89,17 @@ th {
|
||||
|
||||
# Colors
|
||||
|
||||
Tailwind traditionally has a very large color palette. Bitwarden has their own more limited color
|
||||
palette instead.
|
||||
|
||||
This has a couple of advantages:
|
||||
|
||||
- Promotes consistency across the application.
|
||||
- Easier to maintain and make adjustments.
|
||||
- Allows us to support more than two themes light & dark, should it be needed.
|
||||
|
||||
Below are all the permited colors. Please consult design before considering adding a new color.
|
||||
|
||||
<div class="tw-flex tw-space-x-4">
|
||||
<Table />
|
||||
<Table class="theme_dark tw-bg-background" />
|
||||
|
||||
51
libs/components/src/stories/forms-docs.stories.mdx
Normal file
51
libs/components/src/stories/forms-docs.stories.mdx
Normal file
@@ -0,0 +1,51 @@
|
||||
import { Meta, Story, Source } from "@storybook/addon-docs";
|
||||
|
||||
<Meta title="Documentation/Forms" />
|
||||
|
||||
# Forms
|
||||
|
||||
Examples and usage guidelines for form control styles, layout options, and custom components for
|
||||
creating a wide variety of forms.
|
||||
|
||||
## Overview
|
||||
|
||||
Component Library forms should always be built using [Angular Reactive Forms][reactive]. Please read
|
||||
[ADR-0001][adr-0001] for a background to this decision. In practice this means that forms should
|
||||
always use the native `form` element and bind a `formGroup`.
|
||||
|
||||
Forms consists of one or multiple sections, and ends with one or multiple buttons.
|
||||
|
||||
### Form Field
|
||||
|
||||
A form field is the most common section in a form. It consists of a label, control and a optional
|
||||
hint.
|
||||
|
||||
<Story id="component-library-form-field--default" />
|
||||
|
||||
<Source id="component-library-form-field--default" />
|
||||
|
||||
### Radio group
|
||||
|
||||
A radio group is a form field that consists of a main label and multiple radio groups. Each group
|
||||
consists of a label and a radio input.
|
||||
|
||||
#### Block
|
||||
|
||||
<Story id="component-library-form-radio-button--block" />
|
||||
|
||||
<Source id="component-library-form-radio-button--block" />
|
||||
|
||||
#### Inline
|
||||
|
||||
<Story id="component-library-form-radio-button--inline" />
|
||||
|
||||
<Source id="component-library-form-radio-button--inline" />
|
||||
|
||||
## Full Example
|
||||
|
||||
<Story id="component-library-form--full-example" />
|
||||
|
||||
<Source id="component-library-form--full-example" />
|
||||
|
||||
[reactive]: https://angular.io/guide/reactive-forms
|
||||
[adr-0001]: https://contributing.bitwarden.com/architecture/adr/reactive-forms
|
||||
@@ -6,7 +6,11 @@ import { Meta } from "@storybook/addon-docs/";
|
||||
|
||||
# Iconography
|
||||
|
||||
Avoid using icons to convey information unless paired with meaningful, clear text. If an icon must be used and text cannot be displayed visually along with the icon, use an `aria-label` to provide the text to screen readers, and a `title` attribute to provide the text visually through a tool tip. Note: this pattern should only be followed for very common iconography such as, a settings cog icon or an options menu icon.
|
||||
Avoid using icons to convey information unless paired with meaningful, clear text. If an icon must
|
||||
be used and text cannot be displayed visually along with the icon, use an `aria-label` to provide
|
||||
the text to screen readers, and a `title` attribute to provide the text visually through a tool tip.
|
||||
Note: this pattern should only be followed for very common iconography such as, a settings cog icon
|
||||
or an options menu icon.
|
||||
|
||||
## Status Indicators
|
||||
|
||||
|
||||
@@ -4,9 +4,9 @@ import { Meta } from "@storybook/addon-docs";
|
||||
|
||||
# `bitInput`
|
||||
|
||||
`bitInput` is an Angular directive to be used on `<input>`, `<select>`, and `<textarea>`
|
||||
tags in order to provide standardized TailwindCss styling, error handling, and more.
|
||||
It is meant to be used within a `<bit-form-field>` custom component.
|
||||
`bitInput` is an Angular directive to be used on `<input>`, `<select>`, and `<textarea>` tags in
|
||||
order to provide standardized TailwindCss styling, error handling, and more. It is meant to be used
|
||||
within a `<bit-form-field>` custom component.
|
||||
|
||||
## Basic Usage Example
|
||||
|
||||
@@ -20,8 +20,8 @@ It is meant to be used within a `<bit-form-field>` custom component.
|
||||
|
||||
## Disabled `bitInput` and Error Handling
|
||||
|
||||
If you would like to be able to still show errors when an input is disabled for
|
||||
specific validation scenarios, then set `[showErrorsWhenDisabled]="true"`
|
||||
If you would like to be able to still show errors when an input is disabled for specific validation
|
||||
scenarios, then set `[showErrorsWhenDisabled]="true"`
|
||||
|
||||
```html
|
||||
<bit-form-field>
|
||||
@@ -31,7 +31,8 @@ specific validation scenarios, then set `[showErrorsWhenDisabled]="true"`
|
||||
</bit-form-field>
|
||||
```
|
||||
|
||||
**NOTE:** Disabling a FormControl removes validation errors so you must manually set the errors after disabling:
|
||||
**NOTE:** Disabling a FormControl removes validation errors so you must manually set the errors
|
||||
after disabling:
|
||||
|
||||
```ts
|
||||
get exampleFormCtrl(): FormControl {
|
||||
|
||||
@@ -6,13 +6,37 @@ import { Meta, Story, Source } from "@storybook/addon-docs";
|
||||
|
||||
## Overview
|
||||
|
||||
All tables should have a visible horizontal header and label for each column.
|
||||
The table component provides a comprehensive way to display, sort and filter data. It consists of
|
||||
two portions, a UI component called `bit-table` and the underlying data source `TableDataSource`.
|
||||
This documentation will initially focus on the UI portion before covering the data source.
|
||||
|
||||
## UI Component
|
||||
|
||||
The UI component consists of a couple of elements.
|
||||
|
||||
- `bit-table`: The main component that creates a native table element and applies the table styling.
|
||||
- `header`: A container for the table header.
|
||||
- `body`: A container for the table body.
|
||||
- `bitCell`: A cell within the table. Used for both headers and content.
|
||||
|
||||
### Guidelines
|
||||
|
||||
- Always include a row or column header with your table; this allows screen readers to better
|
||||
contextualize the data
|
||||
- Avoid spanning data across cells.
|
||||
- Be sure to make repeating actions unique by associating them with the object they relate to.
|
||||
Example: if there are multiple “Edit” buttons on a table, a screen reader should read “Edit,
|
||||
Netflix” for an edit option for a Netflix item.
|
||||
- Use [Virtual Scrolling](#virtual-scrolling) for large data sets.
|
||||
|
||||
### Example
|
||||
|
||||
<Story id="component-library-table--default" />
|
||||
|
||||
The below code is the absolute minimum required to create a table. However we strongly advise you to
|
||||
use the `dataSource` input to provide a data source for your table. This allows you to easily sort
|
||||
data.
|
||||
### Usage
|
||||
|
||||
The below code is the minimum required to create a table. However we strongly advise you to use the
|
||||
`dataSource` input to provide a data source for your table. This allows you to easily sort data.
|
||||
|
||||
```html
|
||||
<bit-table>
|
||||
@@ -36,9 +60,8 @@ data.
|
||||
## Data Source
|
||||
|
||||
Bitwarden provides a data source for tables that can be used in place of a traditional data array.
|
||||
The `TableDataSource` implements sorting and will in the future also support filtering. This allows
|
||||
the `bitTable` component to focus on rendering while offloading the data management to the data
|
||||
source.
|
||||
The `TableDataSource` implements sorting and filtering capabilities. This allows the `bitTable`
|
||||
component to focus on rendering while offloading the data management to the data source.
|
||||
|
||||
```ts
|
||||
// External data source
|
||||
@@ -51,14 +74,31 @@ dataSource.data = data;
|
||||
We use the `dataSource` as an input to the `bit-table` component, and access the rows to render
|
||||
within the `ng-template`which provides access to the rows using `let-rows$`.
|
||||
|
||||
<Source id="component-library-table--data-source" />
|
||||
```html
|
||||
<bit-table [dataSource]="dataSource">
|
||||
<ng-container header>
|
||||
<tr>
|
||||
<th bitCell bitSortable="id" default>Id</th>
|
||||
<th bitCell bitSortable="name">Name</th>
|
||||
<th bitCell bitSortable="other" [fn]="sortFn">Other</th>
|
||||
</tr>
|
||||
</ng-container>
|
||||
<ng-template body let-rows$>
|
||||
<tr bitRow *ngFor="let r of rows$ | async">
|
||||
<td bitCell>{{ r.id }}</td>
|
||||
<td bitCell>{{ r.name }}</td>
|
||||
<td bitCell>{{ r.other }}</td>
|
||||
</tr>
|
||||
</ng-template>
|
||||
</bit-table>
|
||||
```
|
||||
|
||||
### Sortable
|
||||
### Sorting
|
||||
|
||||
We provide a simple component for displaying sortable column headers. The `bitSortable` component
|
||||
wires up to the `TableDataSource` and will automatically sort the data when clicked and display
|
||||
an indicator for which column is currently sorted. The dafault sorting can be specified by setting
|
||||
the `default`.
|
||||
wires up to the `TableDataSource` and will automatically sort the data when clicked and display an
|
||||
indicator for which column is currently sorted. The dafault sorting can be specified by setting the
|
||||
`default`.
|
||||
|
||||
```html
|
||||
<th bitCell bitSortable="id" default>Id</th>
|
||||
@@ -71,6 +111,16 @@ It's also possible to define a custom sorting function by setting the `fn` input
|
||||
const sortFn = (a: T, b: T) => (a.id > b.id ? 1 : -1);
|
||||
```
|
||||
|
||||
### Filtering
|
||||
|
||||
The `TableDataSource` supports a rudimentary filtering capability most commonly used to implement a
|
||||
search function. It works by converting each entry into a string of it's properties. The string is
|
||||
then compared against the filter value using a simple `indexOf`check.
|
||||
|
||||
```ts
|
||||
dataSource.filter = "search value";
|
||||
```
|
||||
|
||||
### Virtual Scrolling
|
||||
|
||||
It's heavily adviced to use virtual scrolling if you expect the table to have any significant amount
|
||||
@@ -97,8 +147,3 @@ specify a `itemSize`, set `scrollWindow` to `true` and replace `*ngFor` with `*c
|
||||
</bit-table>
|
||||
</cdk-virtual-scroll-viewport>
|
||||
```
|
||||
|
||||
## Accessibility
|
||||
|
||||
- Always incude a row or column header with your table; this allows screen readers to better contextualize the data
|
||||
- Avoid spanning data across cells
|
||||
|
||||
Reference in New Issue
Block a user