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:

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

• yarn:

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

• pnpm:

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.

2. Import Styles

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

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

🚀 Usage

Basic Component Usage

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

Running Storybook Locally

After cloning and installing dependencies:

# Install dependencies
pnpm install

# Start Storybook
pnpm storybook

Storybook will be available at: 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.

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

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