# @argent/x-ui

This package provides a theme and components for use with [Chakra UI](https://chakra-ui.com/)

## Contents

- [Installation](#installation)
- [Usage](#usage)
  - [Set up the global theme](#set-up-the-global-theme)
  - [Theme and utilities](#theme-and-utilities)
  - [Components](#components)
  - [Tailwind theme](#tailwind-theme)
- [Design System tokens](#design-system-tokens)
- [Icons and Logos](#icons-and-logos)
- [Storybook](#storybook)
- [Testing](#testing)
- [Development](#development)
- [Development as a local dependency](#development-as-a-local-dependency)
  - [Recommended](#recommended)
  - [Experimental](#experimental)
- [Versioning](#versioning)
- [Hotfix workflow](#hotfix-workflow)

## Installation

To install the package, use the following command:

```sh
pnpm add @argent/x-ui
```

## Usage

### Set up the global theme

```tsx
import { Button, H1, theme } from "@argent/x-ui"
import { ChakraProvider } from "@chakra-ui/react"
import { FC } from "react"

export const App: FC = () => {
  return (
    <ChakraProvider theme={theme}>
      <H1>Hello world</H1>
      <Button>Click me</Button>
    </ChakraProvider>
  )
}
```

### Theme and utilities

The theme contains standard set of attributes which are accessed using a name or key as decribed by chakra-ui. This allows the system to change the underlying values and units without changing the component markup.

See [chakra style props](https://chakra-ui.com/docs/styled-system/style-props) for examples

### Components

You can use primitives and components from chakra - see [chakra components](https://chakra-ui.com/docs/components) for examples

Some components like `BottomSheet` require you to import styles in your project. You can do it like this:

```typescript
import "@argent/x-ui/styles/style.css"
```

## Design System tokens

The tokens in `*.generated.ts[x]` are generated from data in Supernova. To regenerate these (requires an access key - see `.env`):

You can get that access token from: https://cloud.supernova.io/user-profile/authentication

```sh
pnpm gen:tokens
```

## Icons and Logos

The icons and logos in `/src/components/icons` and `/src/components/logos` are generated from master artwork in Figma. To regenerate these (requires an access key - see `.env`):

You can get that access token from: https://www.figma.com/developers/api#access-tokens

```sh
pnpm gen:icons
```

## Tailwind theme

You will need to add the css varaibles that are reference by the tailwind config to your global styles `global.css`. Thes are set to use `.dark` class for dark mode by default:

```css
/* global.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

@import "@argent/x-ui/styles/tailwind.css";

/* any additional styles here */
```

And them colors and fontSize to your tailwind config `tailwind.config.ts`:

```tsx
// tailwind.config.ts

import type { Config } from "tailwindcss"

import { tailwindThemeConfig } from "@argent/x-ui"

const config: Config = {
  darkMode: "class",
  theme: {
    extend: {
      colors: {
        ...tailwindThemeConfig.colors
        // add any additional colors here
      },
      fontSize: {
        ...tailwindThemeConfig.fontSize
        // add any additional font sizes here
      }
    }
  }
  // add any additional config here
}

export default config
```

## Storybook

Custom components and examples unique to this package are in Storybook

```sh
pnpm storybook
```

Storybook will be published to Chromatic for each PR - see the GitHub Actions output for a link

The permalink for `@argent/x-ui` on `develop` is https://develop--65d8cb036305ac44c7a097eb.chromatic.com/

## Testing

Tests include shapshot testing that requires Playwright browsers to be installed

```sh
pnpm exec playwright install
```

To run the tests, use the following command:

```sh
pnpm test
```

To run tests in watch mode:

```sh
pnpm test:watch
```

To update test snapshots:

```sh
pnpm test:update
```

## Development

To start development, clone the repository and install the dependencies:

```sh
git clone https://github.com/argentlabs/x-ui.git
cd x-ui
pnpm install
# generate TypeScript types for autocomplete
pnpm gen:theme-typings
```

You can start the development server with:

```sh
pnpm dev
```

This builds for development, in watch mode with sourcemaps enabled.

## Development as a local dependency

### Recommended

The recommended way to develop as a local dependency is to use the `file:` protocol, see [What's the difference between pnpm link and using the file: protocol?](https://pnpm.io/cli/link#whats-the-difference-between-pnpm-link-and-using-the-file-protocol)

```json
/** in the project package.json, use a relative path to the local x-ui folder */
"@argent/x-ui": "file:../../../x-ui",
```

The workflow is then;

- Make changes in `x-ui` package
- Run `pnpm build` in the `x-ui` package
- Run `pnpm install` in the project that references the local `x-ui` folder
- Repeat every time you want to install the latest changes

Once you are happy with the changes

- Create and merge a PR into `develop` branch
- Wait for package to publish to npm with [updated `next` version](https://www.npmjs.com/package/@argent/x-ui?activeTab=versions)
- Update the version in the relevant projects

### Experimental

Please also try an experimental way of developing local packages with live reloading and source maps. This is a new feature, please use and share any feedback or issues.

1. In each of the packages you are wroking on, start dev in watch mode with reloading;

   ```sh
   # e.g. in `x-ui` or `x-shared` package
   $ pnpm dev
   ```

2. In `argent-x-private`, modify the root `package.json` to override the packages you want to work on:

   ```json
     /** in the project package.json, use a relative path to the local folder */
     "pnpm": {
       "overrides": {
         "@argent/x-shared": "link:../x-shared",
         "@argent/x-ui": "link:../x-ui"
       }
     }
   ```

3. Install the changes and start the dev server with hot reloading

   ```sh
   $ pnpm install
   $ pnpm dev
   # or just for the extension package
   $ pnpm dev:extension
   ```

4. Make a change in the linked package. This will trigger a series of updates;

   - trigger a re-build in the linked package
   - trigger a re-build in the extension package
   - trigger a reload of the running extension with your changes

## Versioning

The package version will be inferred automatically from each commit message using [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) - see the summary there for how to achieve patch, minor and major version changes.

## Hotfix workflow

- Checkout the tag of the version you want to hotfix
- Create a new branch using the format `hotfix/vx.y.z` and increment the patch version
- Add your changes
- Commit your changes using the format `fix: <commit message>`
