# Particle

A CSS framework and React component library for building dscout user interfaces. Visit the [documentation site] to learn more.

## Usage

Install particle using [yarn] or [npm]:

```bash
$ yarn add @dscout/particle
$ npm install --save @dscout/particle
```

### React Version Support

Particle supports both React 18.x and React 19.x applications. No code changes are required when upgrading between React versions. Note that Particle is built using React 18.x, so usage with React 19.x should be done with this in mind and developers should validate components behave as expected.

```bash
# React 18 applications
yarn add @dscout/particle react@^18.0.0 react-dom@^18.0.0

# React 19 applications
yarn add @dscout/particle react@^19.0.0 react-dom@^19.0.0
```

### Peer dependencies

Particle requires the implementing application install React and React Router. Optionally the implementing application can also install `lodash` and `@floating-ui/dom`. These optional peer dependencies are **required** when using the tooltip or dropdown components from Particle, but can be omitted if those are not used.

### Importing

Everything is a named export on the namespace "@dscout/particle," for example:

```javascript
import React from 'react';
import { Container, Heading } from '@dscout/particle';

export default function Announcement() {
  return (
    <Container>
      <Heading level="2">Important!</Heading>
      <p>Make sure to eat your vegetables.</p>
    </Container>
  );
}
```

## Stylesheets

Stylesheets are included in two formats: `css` and `scss`.

Pre-compiled stylesheets are located in the `lib` directory of the build output.
To import into a plain CSS file:

```css
@import 'node_modules/@dscout/particle/lib/stylesheets/particle.css';
@import 'node_modules/@dscout/particle/lib/stylesheets/particle.min.css';
```

The source `scss` file is located in the `styles` directory.
You can import it into your own `scss` file like so:

```scss
@import '@dscout/particle/styles/particle.scss';
```

## Developing with Storybook

Storybook provides an isolated development environment for Particle components as well as a published static site that serves as a playground and documentation.

### Install dependencies

Particle uses asdf to manage the node dependencies. To develop locally first
install asdf with:

```bash
brew install asdf
```

Then install nodejs. If you don't already have nodejs set up on your machine you may first need install its dependencies and OpenPGP keys:

```bash
brew install coreutils
brew install gpg
bash ~/.asdf/plugins/nodejs/bin/import-release-team-keyring
```

Install asdf dependencies

```bash
asdf install
```

Install NPM dependencies with [yarn]:

```bash
yarn install
```

### Start Storybook

Run Storybook locally:

```bash
yarn start
```

## Scripts

A variety of scripts are provided for running common tasks.

Lint with ESLint and run typechecker:

```bash
yarn lint
```

Start the Vitest test runner in watch mode:

Note: Before testing, you will need to run `yarn playwright install` to ensure the local test runner can properly spin up the necessary browser environment.

```bash
yarn test
```

## Contributing

[See the wiki](https://github.com/dscout/particle/wiki/Development-and-QA-workflow) for details on how to contribute to Particle.

## Releasing a new version

Instructions for preparing a new release and submitting it to npm can be found [here](https://github.com/dscout/particle/wiki/Versioning-&-Releases).

[documentation site]: https://dscout.github.io/particle/
[npm]: https://www.npmjs.com/
[Storybook]: https://getstorybook.io/
[yarn]: https://yarnpkg.com/en/docs/install