# Kwant-UI

`kwant-ui` is the official frontend component library for Kwant-App. It provides a set of reusable, accessible, and themeable React components to build beautiful and consistent user interfaces.

## 📋 Table of Contents

- [About The Project](#about-the-project 'null')
- [Installation](#installation 'null')
- [Usage](#usage 'null')
- [Storybook: Visualizing Components](#storybook-visualizing-components 'null')
- [Available Scripts for Development](#available-scripts-for-development 'null')

- [Publishing to NPM](#publishing-to-npm)
- [Folder Structure](#folder-structure 'null')
- [Contributing](#contributing 'null')

## 🚀 About The Project

This library contains all the foundational UI elements required for the Kwant ecosystem. Each component is built with TypeScript for type safety and styled to fit our design system. The components are bundled using Rollup.js for optimized performance.

**Built With:**

- [**React**](https://reactjs.org/ 'null')**:** A JavaScript library for building user interfaces.

- [**Styled Components**](https://styled-components.com/ 'null')**:** For component level styling.

- [**TypeScript**](https://www.typescriptlang.org/ 'null')**:** For robust, type-safe components.
- [**Storybook**](https://storybook.js.org/ 'null')**:** For developing and showcasing components in isolation.
- [**Rollup.js**](https://rollupjs.org/ 'null')**:** For bundling the library into a distributable format.
- [**ESLint**](https://eslint.org/ 'null')**:** For maintaining code quality.

## 📥 Installation

To use kwant-ui in your project, you need to install the library along with its peer dependencies.

Install with npm:

```
npm install kwant-ui react react-dom styled-components react-viewport-list
```

**Note:** `react-dom, styled-components, react-viewport-list` are a peer dependency and must be installed alongside `kwant-ui`.

## 💡 Usage

To use `kwant-ui`, you must wrap your application with the `ThemeProvider` from `styled-components` and provide it with a theme from our library. This is a required step for the components to render correctly.

### 1. Set up the ThemeProvider

In your main application entry point (`main.tsx` or `index.tsx`), set up the provider as follows:

```
import React from 'react';
import ReactDOM from 'react-dom/client';
import { createBrowserRouter, RouterProvider } from 'react-router-dom';
import { ROUTES } from './routes';
import { ThemeProvider } from 'styled-components';
import './assets/styles/index.scss';
import { colors } from 'kwant-ui';

const router = createBrowserRouter(ROUTES);

ReactDOM.createRoot(document.getElementById('root') as HTMLElement).render(
  <React.StrictMode>
    <ThemeProvider theme={colors}>
      <RouterProvider router={router} />
    </ThemeProvider>
  </React.StrictMode>
);

```

### 2. Use Components in Your App

Once the `ThemeProvider` is set up, you can import and use any component from the library throughout your application.

```
import React from 'react';
import { Button, Text } from 'kwant-ui';

function MyComponent() {
  return (
    <>
      <Text category="subtitle2" weight="semiBold">Welcome</Text>
      <Button onClick={() => alert('Button Clicked!')} label="Click Me"/>
    </>
  );
}

export default MyComponent;

```

## 📖 Storybook: Visualizing Components

We use Storybook for interactive development and documentation. It allows you to browse the component library, view the different states of each component, and interact with them in a live environment.

#### Live Playground

_Explore the live Storybook playground at:_ [_https://ui.kwant.ai/_](https://ui.kwant.ai/ 'null')

#### Local Development

To run Storybook locally, clone this repository and run:

```
npm run storybook
```

This will start the Storybook development server on [http://localhost:6006](https://www.google.com/search?q=http://localhost:6006 'null').

## 📜 Available Scripts for Development

These scripts are for the development and maintenance of this library.

### `npm run storybook` or `npm run dev`

Starts the Storybook development server. This is the primary command for developing and testing components in isolation.

### `npm run build`

```
rm -rf ./dist && rollup -c --bundleConfigAsCjs
```

Builds the library for production. It first cleans the `dist` directory and then uses Rollup to bundle the components into an optimized format suitable for publishing to NPM.

### `npm run prebuild`

This script runs automatically before the `build` script.

- `npm run generate-icon-types`: Executes a utility script to automatically generate TypeScript type definitions for the icons used in the library.

### `npm run build-storybook`

Builds a static version of the Storybook documentation site, which can be deployed and hosted online.

### `npm run lint`

```
eslint "**/*.ts*"
```

Lints all TypeScript files (`.ts` and `.tsx`) in the project to enforce code quality and style consistency.

## 📦 Publishing to NPM

For instructions on how to publish a new version of `kwant-ui` to the NPM repository, please refer to our internal documentation on Confluence.

[**Publishing Guide: Publishing a version of ui-components(npm package)**](https://ontargetapp.atlassian.net/wiki/x/AwDcfg 'null')

## 📂 Folder Structure

The library is organized as follows:

```
kwant-ui/
├── .storybook/         # Storybook configuration files
├── components/         # The source code for all React components
├── GlobalStyles/       # Global CSS styles and resets
├── HOC/                # Higher-Order Components
├── hooks/              # Custom React hooks
├── stories/            # Storybook stories for each component
├── themes/             # Design tokens (colors, spacing, typography)
├── types/              # Global TypeScript type definitions
├── utils/              # Utility scripts, like the icon type generator
├── .eslintrc.cjs       # ESLint configuration
├── .prettierrc         # Prettier configuration
├── package.json        # Project dependencies and scripts
├── rollup.config.js    # Rollup configuration for building the library
└── tsconfig.json       # TypeScript configuration

```

## 🤝 Contributing

1.  Fork the Project
2.  Create your Feature Branch (`git checkout -b PR-JIRA-TICKET-ID`)
3.  Commit your Changes (`git commit -m 'Add NewComponent'`)
4.  Push to the Branch (`git push origin PR-JIRA-TICKET-ID`)
5.  Open a Pull Request