# ![JTL logo](https://avatars.githubusercontent.com/u/31404730?s=25&v=4) JTL-Platform UI React

A modern, accessible UI component library for JTL applications built with React and TailwindCSS.

## 📦 Installation

Install the package using the package manager of your choice:

- npm:

```bash
npm install @jtl-software/platform-ui-react
```

- yarn:

```bash
yarn add @jtl-software/platform-ui-react
```

- pnpm:

```bash
pnpm add @jtl-software/platform-ui-react
```

## 🔨 Setup

### 1. TailwindCSS Configuration

This library requires TailwindCSS 4. If you haven't set up TailwindCSS in your project yet, follow the [official Tailwind CSS installation guide](https://tailwindcss.com/docs/installation).

### 2. Import Styles

In your main CSS file (e.g., `globals.css` or `index.css`), import the library styles:

```css
@import '@jtl-software/platform-ui-react/dist/main.css';
@import 'tailwindcss';
@source 'node_modules/@jtl-software/platform-ui-react/dist';
```

## 🚀 Usage

### Basic Component Usage

```jsx
import { Button, Text, Card } from '@jtl-software/platform-ui-react';
```

## 🧩 Component Categories

This library includes the following component categories:

### Layout Components

- `Box`, `Grid`, `Stack`, `Layout`, `LayoutSection`, `Card`

### Form Components

- `Button`, `Checkbox`, `Input`, `InputOTP`, `Radio`, `Select`, `Textarea`, `Switch`, `Toggle`, `ToggleGroup`, `FormGroup`, `Form`

### Data Display

- `Text`, `Badge`, `Avatar`, `Table`, `DataTable`, `Progress`

### Navigation

- `Link`, `Breadcrumb`, `Tab`, `Dropdown`

### Feedback

- `Alert`, `Dialog`, `AlertDialog`, `Tooltip`, `Skeleton`

### Utility

- `Icon`, `Separator`, `ScrollArea`, `Collapsible`, `Popover`, `Sheet`

### ⚠️ **Usage Guidelines**

- Avoid invalid HTML nesting (e.g., `<div>` inside `<p>`, `<button>` containing `<a>`).
- Do not wrap library components with arbitrary elements unless semantically correct.
- Fix any console warnings like `Warning: validateDOMNesting(...)`.

## 📚 Storybook

The best way to explore all available components and their usage is through [Storybook](https://storybook.jtl-cloud.com/release/)

### Running Storybook Locally

After cloning and installing dependencies:

```bash
# Install dependencies
pnpm install

# Start Storybook
pnpm storybook
```

Storybook will be available at: [http://localhost:50170](http://localhost:50170)

### Using Storybook for Documentation

Our Storybook includes:

- Component demonstrations with various prop combinations
- Interactive controls to experiment with component properties
- Documentation on component APIs, props, and examples
- Accessibility information
- Source code examples

## ⚡️ Development

### Prerequisites

- For local development, ensure you are using the Node.js version specified in `package.json`.
  - **Mise**: run `mise install` to install the correct versions of node and pnpm
- Run `pnpm install` on repository root to install dependencies

### Common Commands

- Start Storybook: `pnpm storybook`
- Build the library: `pnpm build`
- Run tests: `pnpm test`
- Run linting: `pnpm lint`

## 🔌 Ports

To prevent conflicts with other services during development, we have a reserved port range for this project: `50170-50179`. Please use a port within this range when adding a new service.

| Port  | Protocol | Service   |
| ----- | -------- | --------- |
| 50170 | HTTP     | Storybook |

## 📦 Dependencies

This project uses React 19 for both development and as a peer dependency.

```json
"peerDependencies": {
  "react": "^19.0.0",
  "react-dom": "^19.0.0",
}
```

Projects using this library should use React 19 for optimal compatibility.