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

## 🧭 Project Overview

**JTL Platform UI React** is a modern, accessible UI component library built with React 19, TailwindCSS 4, and Radix UI primitives. It provides reusable components following Atomic Design principles for JTL applications.

### Tech Stack

- React 19 (peer dependency requirement)
- TailwindCSS 4 (used internally; consumers do not need to set it up in their app)
- TypeScript 5.6
- Vite 6 (build tool)
- Vitest 3 (testing)
- Storybook 9 (documentation)
- react-hook-form + Zod (form validation)
- shadcn UI (component reference)
- Radix UI primitives

## 📦 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. Import the Stylesheet

The library ships a pre-compiled stylesheet that includes all the utility classes, design tokens, and a minimal element-level reset its components need. You must import it once at your app entry point.

In JavaScript or TypeScript (most common with Vite, Next.js, CRA):

```ts
// In your app entry, e.g. main.tsx, _app.tsx
import '@jtl-software/platform-ui-react/index.css';
```

Or from CSS:

```css
@import '@jtl-software/platform-ui-react/index.css';
```

You do not need to configure TailwindCSS in your app to use the library. The required utility classes are already compiled into the shipped CSS.

### 2. CSS Reset (consumer responsibility)

The library does not ship a full CSS reset. It includes a small targeted reset for form controls (`button`, `input`, `select`, `textarea`) and replaced elements (`img`, `svg`, `video`) so its own components render correctly, but it does not normalize typography, headings, list bullets, or page-level margins.

If your app does not already have a CSS reset in place, we strongly recommend adding one. Common options:

- Full Tailwind preflight (`@import 'tailwindcss'`) if you use Tailwind in your app
- [normalize.css](https://necolas.github.io/normalize.css/)
- [`tailwindcss-scoped-preflight`](https://www.npmjs.com/package/tailwindcss-scoped-preflight) if you want Tailwind's reset scoped to a specific root

Without a reset, native browser styles (default `<h1>` margins, list bullets, etc.) will remain in your app, which is usually what you want for content outside the library's components.

### 3. Styling Variables

The library exposes its design tokens as CSS custom properties. You can use them in your own styles:

- Prefer classes like `w-[var(--spacing-10)]` instead of hard-coded values like `w-40`.
- Override tokens at `:root` to theme the components (e.g. `--base-primary`).
- For dark mode, set `data-color-scheme="dark"` on `<html>` or apply the `.dark` class to a wrapping element.

## 🚀 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`

### Import Aliases (Repository Development)

Use internal path aliases for local source imports:

```typescript
import { Component } from '@/components/component-name';
import { useHook } from '@/hooks';
import { utils } from '@/lib';
```

## 🔌 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.