# @onbeam/ui

A collection of all UI components styled using the Beam design system. For an overview of all UI components click [here](https://packages.onbeam.com/).

For an example project, check out the [starter template repository](https://github.com/BuildOnBeam/beam-next-app-router-starter). This project already has everything set up in a minimal way. If it suits your use-case, use that repository as a template for your new project. This will save you some time implementing the required packages.

## Table of Contents

- [@onbeam/ui](#onbeamui)
  - [Table of Contents](#table-of-contents)
  - [Installation](#installation)
  - [Tailwind](#tailwind)
  - [Tree-Shaking Support](#tree-shaking-support)
  - [PandaCSS](#pandacss)
    - [Config](#config)
    - [PostCSS](#postcss)
    - [CSS](#css)
    - [Scripts](#scripts)
  - [All `@onbeam` packages](#all-onbeam-packages)

## Installation

In order to use the UI library, you have to install a few packages:

```bash
pnpm add @onbeam/ui@latest @onbeam/styled-system@latest
pnpm add @pandacss/dev@latest --save-dev
```

> Note: It's also possible to only use the styled-system without the UI library.

Icons are optional. If you need them, you can install them with the following command:

```bash
pnpm add @onbeam/icons@latest
```

To keep all `@onbeam` packages updated, you can use the CLI:

```bash
npx @onbeam/cli update -d [directory]
```

## Tailwind

If you're using TailwindCSS alongside Beam UI (PandaCSS) within your application, check out [this example repository](https://github.com/BuildOnBeam/beam-tailwind-example) for the documentation on how to combine these two packages.

## Tree-Shaking Support

This package is fully tree-shakable, ensuring that only the UI components you import are included in your final bundle, optimizing your app's performance.

## PandaCSS

Due to the component styles building just-in-time, you need to install and configure PandaCSS. This means that only the styles for the components you use will be generated, nothing more. When you decide to utilize PandaCSS in your own project, you will be able to use all design tokens and PandaCSS will combine the UI styles with your project styles before compiling the output.

### Config

Create a `panda.config.ts` file in the root of your application and paste this snippet in there:

```ts
import { defineBeamUiConfig } from "@onbeam/styled-system/config";

export default defineBeamUiConfig({
  include: [
    "./node_modules/@onbeam/ui/dist/panda.buildinfo.json",
    // TODO: Configure this line to target your own files that utilize the component library and PandaCSS
    "./src/**/*.{ts,tsx}",
  ],
});
```

### PostCSS

Run `npx panda init --postcss`. This will create a `postcss.config.cjs` file in the root of your application with the following code:

```ts
module.exports = {
  plugins: {
    "@pandacss/dev/postcss": {},
  },
};
```

### CSS

To enable the styles, create a global CSS file, for example named "`globals.css`" and paste the following snippet in there:

```css
/* When adding libraries that could overwrite our styles, make sure to use css layers: */
/* https://panda-css.com/docs/overview/faq#how-can-i-prevent-other-libraries-from-overriding-my-styles */
@layer reset, base, tokens, recipes, utilities;

body {
  font-family: var(--beam-fonts-main);
  color: var(--beam-colors-mono-100);
}

/* TODO: These are all fonts used in the @onbeam/ui components. Add all your used fonts here */
@font-face {
  font-family: "Suisse Intl";
  font-style: normal;
  font-display: swap;
  font-weight: 400;
  src: url("../node_modules/@onbeam/ui/dist/fonts/SuisseIntl-Regular.otf");
}

@font-face {
  font-family: "Suisse Intl";
  font-style: normal;
  font-display: swap;
  font-weight: 500;
  src: url("../node_modules/@onbeam/ui/dist/fonts/SuisseIntl-Book.otf");
}

/* TODO: Remove this if you're not using the `ObjectTree` component */
@font-face {
  font-family: "JetBrains Mono";
  font-style: normal;
  font-display: swap;
  font-weight: 400;
  src: url("../node_modules/@onbeam/ui/dist/fonts/JetBrainsMono-Regular.ttf");
}
```

In the root of your project code, for example `layout.tsx` or `_app.tsx`, import your created css file:

```ts
import "./globals.css";
```

### Scripts

To build the PandaCSS code, add the `panda codegen` command to your `package.json`'s build script. For example:

```json
"scripts": {
  "build": "panda codegen && next build",
},
```

## All `@onbeam` packages

- [@onbeam/automation-api-client](https://www.npmjs.com/package/@onbeam/automation-api-client)
- [@onbeam/biome-config](https://www.npmjs.com/package/@onbeam/biome-config)
- [@onbeam/cli](https://www.npmjs.com/package/@onbeam/cli)
- [@onbeam/errors](https://www.npmjs.com/package/@onbeam/errors)
- [@onbeam/features](https://www.npmjs.com/package/@onbeam/features)
- [@onbeam/icons](https://www.npmjs.com/package/@onbeam/icons)
- [@onbeam/player-api-client](https://www.npmjs.com/package/@onbeam/player-api-client)
- [@onbeam/sdk](https://www.npmjs.com/package/@onbeam/sdk)
- [@onbeam/styled-system](https://www.npmjs.com/package/@onbeam/styled-system)
- [@onbeam/ui](https://www.npmjs.com/package/@onbeam/ui)
- [@onbeam/utils](https://www.npmjs.com/package/@onbeam/utils)

---

**That's it! Happy coding! 🌈**
