element-web/packages/shared-components

@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 and Compound Web. This is not a design system by itself, but rather a set of big chunks of components.

Installation

yarn add @element-hq/web-shared-components

Peer Dependencies

This package requires compound web to be added as a peer dependency:

yarn add @vector-im/compound-web

Usage

Basic Import

Both JavaScript and CSS can be imported as follows:

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:

@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:

import { Flex } from "@element-hq/web-shared-components";
function MyApp() {
    return <Flex align="center" />;
}

View (MVVM) Components

These components follow the MVVM pattern. A ViewModel instance should be provided as a prop.

Here's a basic example:

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

# Install dependencies
yarn install

# Build the library
yarn prepare

Running Storybook

yarn storybook

Write components

Most the components should be written as MVVM pattern 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.

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.

First run storybook:

yarn storybook

Then, in another terminal, run:

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 and translation dev guide. To generate translation strings for this package, run:

yarn i18n