Mithra UI

React component library for the Dossier design system

• Documentation
• Bitbucket

Getting started

Set up local development environment:

1. Run npm install
2. Run npm run build-lib to generate the version file.
3. Run npm start to start the dev server.

The local dev server gives you a live-reloaded version of the mithra documentation, that you can use to test components while working on them.

Other useful commands:

• npm run build-lib
• npm run build-doc
• npm run import-icons

Changelog merge driver

A custom git merge driver avoids conflicts when multiple branches add entries under the HEAD section in CHANGELOG. Run this once per clone to register it:

git config merge.changelog.driver "node scripts/changelog-merge-driver.cjs %O %A %B"

Technology stack

• React 19
• Vite
• TypeScript
• SCSS

Development and branches

Development happens in feature branches, for example improvement/PF-1234-description. These are merged by pull request to master.

When making changes that affect users of the library, please add a concise comment about the change at the top of the CHANGELOG file.

To determine which release branch a feature should be merged to, use SemVer (breaking changes → next major, non-breaking changes → next minor or patch).

Code style

We use automatic code formatting with Prettier. You should set this up with your editor when contributing.

VS Code: The project already contains configuration that makes the editor format on save, but you must install the Prettier extension. This will be prompted when you open the project.

IntelliJ: Install the Prettier extension, and choose the node_modules Prettier in its settings.

Releasing packages

Steps to release on npm:

• Checkout the correct release branch.
• Run the appropriate npm version major|minor|patch to update package.json and create a tagged commit.
• Push the commit to bitbucket (git push).
• Push the resulting git tag to bitbucket (git push --tags).
• This triggers the npm publish pipeline, which is irreversible. It also rebuilds and deploys the docs site.

Importing icons from Figma

1. Select the icons in Figma and batch export everything as svg.
2. Create a folder in the project root called ./iconBuildSrc
3. Extract the downloaded zip into the iconBuildSrc
4. Run npm run import-icons
5. ~~Modify src/lib/assets/icons/icons/index.js as needed if the categories have changed~~
6. Voilà. Delicious icons.

Snapshot testing

The image snapshot tests take screenshots of test layouts using Puppeteer and Vitest. The images are then compared with previous snapshots using jest-image-snapshot. This alerts us to unintended visual changes to components. If a test fails, an image file will be created, with a visual diff of the change. These tests also run automatically in a bitbucket pipeline for all pull requests. If they fail, you can download the diff images for the failed tests in an artifact from bitbucket.

To run and/or update the tests locally, you must have Docker on your system. The snapshot tests need Docker in order to render exactly the same, regardless of different developer systems and CI.

Running the tests in the docker container

Before running the tests, be sure you have a dev server running locally. Docker must also be installed.

# Run dev server on your local machine
npm run start

Then you can run the snapshot tests in a container. The following command starts a container and executes all the snapshot tests (against your dev server). The first time you run this command it will spend some time downloading the image and installing node_modules.

# Run tests in the container
npm run test:docker

# Or, run interactively
npm run test:docker:watch

Then if there are any failures, you can see the diffs in __tests__/__image_snapshots__/__diff_output__.

You can update the snapshots by running the following command:

# Run tests in the container
npm run test:docker -u

To shut down the container and Docker resources after testing, run:

npm run test:docker:cleanup

About the Docker test environment

Both the local test environment and the bitbucket pipeline use the official puppeteer image. The local environment is managed by Docker compose (see docker-compose.yml).

Migration notes (v3.x)

This version includes several breaking changes:

React 19 required

• Upgrade react and react-dom to ^19.0.0

Placement type import changed

If you import Placement type for popover/tooltip positioning:

// Before
import { Placement } from "@popperjs/core";

// After  
import { PopoverPlacement } from "@dossier/mithra-ui";

CSS attribute selectors changed

If you have custom CSS targeting popover placements:

/* Before */
[data-popper-placement^="top"] { ... }

/* After */
[data-placement^="top"] { ... }

IE11 no longer supported

IE11 support and polyfills have been removed.