# Redpanda UI

React Typescript component library for Redpanda UI projects.

[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white)](https://conventionalcommits.org)
![release](https://github.com/redpanda-data/ui/actions/workflows/release-main.yaml/badge.svg)
![tests](https://github.com/redpanda-data/ui/actions/workflows/test.yaml/badge.svg)

## 🏛️ Base library

This library uses [Chakra UI](https://chakra-ui.com/) as the basis for all components.

## 🧱 Custom components

Create a component in the `src/components/` directory, then export it from `src/components/index.ts`.

Component directory structure:

```
src/
  exports.ts
  assets/
  styles/
  components/
    index.ts
    Button/
      Button.tsx
      Button.test.tsx
      Button.stories.tsx
```

Exporting a component in `src/components/index.ts`

```
export { default as Button } from './Button/Button';
```

### Generate

_TODO - add generator for new components with the correct directory, index, component, story, and test files._

### Overrides

To override any default components from the base library. Simply create a new component with the same name, and add it to `src/components/index.ts`.

### Including components from other libraries

Create a custom component, and import the component you need from your package. Ensure that you use the hooks provided in Chakra for theming light and dark modes.

## 🎨 Styles

Custom CSS and SCSS can be used but is mostly not needed as Chakra provides all of the base styles we need. Refer to the Chakra documentation for styles and prop based styles.

### Global CSS

this library will export a global css file with your custom css, make sure you import it from `@redpanda-data/dist/index.css`.

### SASS support

yuor scss or sass files will be transpiled to a single css file when imported on any file, output file will be `index.css`

## 🧪 Storybook

We use storybook to preview components and test them.

Run `npm run build-storybook` for static assets.
Run `npm run storybook` and go to http://localhost:6006

This storybook setup closely follows this approach:

- [Storybook best practices](https://betterprogramming.pub/10-storybooks-best-practices-ad5fec0f145a)
- [Storybook with Typescript intro](https://youtu.be/qSkHRVLcj6U)

### Test coverage

We are using @testing-library/react to write the tests for UI.

Run `npm run test` to see the coverage for the library.

### A few things to remember when writing tests for UI components:

1. The goal is to increase confidence in using the library, not to test every prop.
1. If the component is simple e.g: only has a prop that changes a 'backgroundColor', then using storybook controls is enough confidence, we do not need to write a test for this.
1. Write tests for clear branches in logic, and to test stateful changes to a component. e.g: a date-picker will have internal state and is sufficiently complex that it will need multiple tests.
1. Use your judgement whether visually testing is important.

### Local Development with Cloud/Admin UI

When making changes to the UI library (components, styles, etc.), it's nice to test those changes within the context of your local-running Cloud UI. Using [`yalc`](https://github.com/wclr/yalc), you can link Cloud UI to your local `ui` repo and see those changes reflected with your Cloud UI instance using the following steps:

1. Install `yalc` on your machine: `npm i -g yalc`
2. Within the `ui` repo, run `yalc publish`. This will publish your local `ui` repo to your local `yalc` store (registry).
3. Within the `cloud-ui` (or `admin-ui`) repo, add the newly-added yalc dependency: `yalc add @redpanda-data/ui`
4. Withing the `cloud-ui` (or `admin-ui`) repo, install the new dependency: `npm i`

After making any code changes within your local `ui` repo, run `yalc push` to update the local `yalc` store and have your changes pushed to the `cloud-ui` (or `admin-ui`) repo.

Once you're done testing local changes, it's important to unlink the local `ui` repo from `cloud-ui` (or `admin-ui`) by running: `yalc remove @redpanda-data/ui`.

### Visual testing

When viewing a component in storybook, check that it works with both `light` and `dark` modes.

### Accessibility tests

Ensure that tests pass all critical accessibilty violations. If unsure about visual elements contact the design team for input.

## 🏖️ Playground

Use the files in the directory `playground/` as a scratchpad for trying out components. It uses a standard [CRA](https://github.com/facebook/create-react-app) setup.

Run `npm run playground` to see the playground in the browser at http://localhost:3000

## 🚀 Deployment

We are using [release-please](https://github.com/googleapis/release-please) to hande the release of this library, notice it relies on [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/)
to generate [semver](https://semver.org/), [releases](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases) and [changelog](https://keepachangelog.com/en/1.0.0/).

### build:

We use [rollup](https://rollupjs.org/guide/en/) for building the app, simply run `npm run build` to generate the built files and types.

### how to release for prod:

Every push to main will generate a release pull request, when the PR is approved and merged it will publish the new version of the package to npm.

Note: To ensure a release is auto-created, be sure to rebase/merge back into your branch before merging your PR.

Keep in mind: PRs that use the `docs` or `chore` commit lint prefix will not trigger a new release. It's recommended to prefix your PR title with "feat" or "fix" when releasing a new feature or fix, respectively.

### contribution guideline:

You should use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) for your commits, you can run `npm run commit` it will prompt a helper to generate your commits.
there are some git hooks to validate your commits and some prettier style enforcement.
