Florian Duros
154 lines
3.4 KiB
Markdown
154 lines
3.4 KiB
Markdown
# @element-hq/web-shared-components
|
|
|
|
Shared React components library for Element Web, Aurora, Element modules... This package provides opinionated UI components built on top of the [Compound Design System](https://compound.element.io) and [Compound Web](https://github.com/element-hq/compound-web). This is not a design system by itself, but rather a set of big chunks of components.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
yarn add @element-hq/web-shared-components
|
|
```
|
|
|
|
### Peer Dependencies
|
|
|
|
This package requires compound web to be added as a peer dependency:
|
|
|
|
```bash
|
|
yarn add @vector-im/compound-web
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Basic Import
|
|
|
|
Both JavaScript and CSS can be imported as follows:
|
|
|
|
```javascript
|
|
import { RoomListHeaderView, useViewModel } from "@element-hq/web-shared-components";
|
|
import "@element-hq/web-shared-components/dist/element-web-shared-components.css";
|
|
```
|
|
|
|
or in CSS file:
|
|
|
|
```css
|
|
@import url("@element-hq/web-shared-components");
|
|
```
|
|
|
|
### Using Components
|
|
|
|
There is two kinds of components in this library:
|
|
|
|
- _regular_ react component which doesn't follow specific pattern.
|
|
- _view_ component(MVVM pattern).
|
|
|
|
> [!TIP]
|
|
> Theses components are available in the project storybook.
|
|
|
|
#### Regular Components
|
|
|
|
These components can be used directly by passing props. Example:
|
|
|
|
```tsx
|
|
import { Flex } from "@element-hq/web-shared-components";
|
|
function MyApp() {
|
|
return <Flex align="center" />;
|
|
}
|
|
```
|
|
|
|
#### View (MVVM) Components
|
|
|
|
These components follow the [MVVM pattern](../../docs/MVVM.md). A ViewModel instance should be provided as a prop.
|
|
|
|
Here's a basic example:
|
|
|
|
```jsx
|
|
import { ViewExample } from "@element-hq/web-shared-components";
|
|
|
|
function MyApp() {
|
|
const viewModel = new ViewModelExample();
|
|
return <ViewExample vm={viewModel} />;
|
|
}
|
|
```
|
|
|
|
### Utilities
|
|
|
|
#### Internationalization
|
|
|
|
- `useI18n()` - Hook for translations
|
|
- `I18nApi` - Internationalization API utilities
|
|
|
|
#### Date & Time
|
|
|
|
- `DateUtils` - Date formatting and manipulation
|
|
- `humanize` - Human-readable time formatting
|
|
|
|
#### Formatting
|
|
|
|
- `FormattingUtils` - Text and data formatting utilities
|
|
- `numbers` - Number formatting utilities
|
|
|
|
## Development
|
|
|
|
### Prerequisites
|
|
|
|
- Node.js >= 20.0.0
|
|
- Yarn 1.22.22+
|
|
|
|
### Setup
|
|
|
|
```bash
|
|
# Install dependencies
|
|
yarn install
|
|
|
|
# Build the library
|
|
yarn prepare
|
|
```
|
|
|
|
### Running Storybook
|
|
|
|
```bash
|
|
yarn storybook
|
|
```
|
|
|
|
### Write components
|
|
|
|
Most the components should be written as [MVVM pattern](../../docs/MVVM.md) view components. See existing components for examples. The exception are low level components that don't need a view model.
|
|
|
|
### Tests
|
|
|
|
Two types of tests are available: unit tests and visual regression tests.
|
|
|
|
### Unit Tests
|
|
|
|
These tests cover the logic of the components and utilities. Built with Jest and React Testing Library.
|
|
|
|
```bash
|
|
yarn test
|
|
```
|
|
|
|
### Visual Regression Tests
|
|
|
|
These tests ensure the UI components render correctly. They need Storybook to be running and they will run in docker using [Playwright](../../playwright.md).
|
|
|
|
First run storybook:
|
|
|
|
```bash
|
|
yarn storybook
|
|
```
|
|
|
|
Then, in another terminal, run:
|
|
|
|
```bash
|
|
yarn test:storybook:update
|
|
```
|
|
|
|
Each story will be rendered and a screenshot will be taken and compared to the existing baseline. If there are visual changes or AXE violation, the test will fail.
|
|
|
|
### Translations
|
|
|
|
First see our [translation guide](../../docs/translation.md) and [translation dev guide](../../docs/translation-dev.md).
|
|
To generate translation strings for this package, run:
|
|
|
|
```bash
|
|
yarn i18n
|
|
```
|