@redpanda-data/ui

Redpanda UI

React Typescript component library for Redpanda UI projects.

🏛️ Base library

This library uses Chakra UI 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
• Storybook with Typescript intro

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.
2. 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.
3. 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.
4. 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, 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 setup.

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

🚀 Deployment

We are using release-please to hande the release of this library, notice it relies on conventional commits to generate semver, releases and changelog.

build:

We use rollup 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 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.