npm package: @l3mpire/ui
Description: React component library for the lemDS design system. Built with **CVA** (Class Variance Authority), **Tailwind CSS v4**, and **Radix UI** primitives.
Latest version: 2.13.0

# @l3mpire/ui

React component library for the lemDS design system. Built with **CVA** (Class Variance Authority), **Tailwind CSS v4**, and **Radix UI** primitives.

## Installation

```bash
pnpm add @l3mpire/ui @l3mpire/tokens @l3mpire/icons
```

Peer dependencies:

```bash
pnpm add react react-dom @l3mpire/icons
```

## Setup

### 1. Import the global stylesheet

In your app's root CSS file:

```css
@import "@l3mpire/ui/globals.css";
```

This file:
- Imports all design tokens as CSS custom properties
- Registers tokens with Tailwind CSS v4's `@theme`
- Sets up dark mode via `data-theme="dark"` custom variant
- Defines component animations

### 2. Configure Tailwind (if using Tailwind in your project)

Add the UI package to your content sources so Tailwind can scan component classes:

```css
@source "../node_modules/@l3mpire/ui/dist";
```

## Usage

```tsx
import { Button, Badge, TextInput, Toast } from "@l3mpire/ui";
import { Icon, faCheck } from "@l3mpire/icons";

function Example() {
  return (
    <>
      <Button appearance="solid" intent="brand" size="md" leftIcon={faCheck}>
        Confirm
      </Button>

      <Badge appearance="solid" intent="primary" size="md">
        New
      </Badge>

      <TextInput
        placeholder="Enter your email"
        size="md"
      />

      <Toast type="success" title="Saved!" description="Your changes have been saved." />
    </>
  );
}
```

## Components

### Actions

| Component | Variants | Description |
|-----------|----------|-------------|
| **Button** | `appearance`: solid, outlined, ghost | Primary action element |
| | `intent`: brand, alert | |
| | `size`: sm, md, lg | |
| **Link** | `variant`: brand, neutral | Text link with hover/pressed states |

### Data Display

| Component | Variants | Description |
|-----------|----------|-------------|
| **Avatar** | `size`: sm, md, lg, xl | User profile image with initials fallback |
| | `shape`: rounded, squared | |
| **Badge** | `appearance`: solid, light, outlined | Inline label / status indicator |
| | `intent`: primary, success, critical, warning, neutral | |
| **Tag** | `variant`: brand, neutral | Removable inline tag |
| **Tooltip** | `variant`: default, invert | Contextual hover tooltip |

### Feedback

| Component | Variants | Description |
|-----------|----------|-------------|
| **InfoMessage** | `type`: info, success, alert, warning, empty | Alert / notification banner |
| **Toast** | `type`: info, success, alert, warning | Notification toast |

### Forms

| Component | Description |
|-----------|-------------|
| **Checkbox** | Checkbox with label (Radix UI) |
| **InputLabel** | Form label with optional/mandatory indicator |
| **SearchBar** | Search input with magnifying glass icon |
| **Select** | Custom dropdown select with chevron |
| **Switch** | Toggle switch with label (Radix UI) |
| **TextArea** | Multi-line input with character counter |
| **TextInput** | Single-line input with icon and validation |

### Data

| Component | Description |
|-----------|-------------|
| **Table** | Low-level table primitives (Header, Body, Row, Cell, Caption) |
| **DataTable** | Data-driven table powered by TanStack Table |
| | Features: sorting, filtering, pagination, row selection, column resizing, column drag reorder |
| **DataTablePagination** | Pagination controls with page size selector |
| **EmptyState** | Placeholder with icon, title, description, and optional action |
| **Cell Renderers** | `AvatarCell`, `StatusCell`, `NumberCell`, `DateCell`, `EmailCell`, `LinkCell`, `ButtonCell`, `EditableCell` |
| **RowActions** | Hover-reveal action buttons for table rows |

### Navigation

| Component | Description |
|-----------|-------------|
| **DropdownMenu** | Menu with items, headings, sections, and clear action |
| **ProductLogo** | Product logo with optional text |
| **Sidebar** | Collapsible app sidebar with header, sections, footer |
| **SidebarItem** | Navigation item with icon, badge, avatar support |
| **SidebarHeadingItem** | Section heading label for sidebar |
| **Typography** | Text component with variant presets |
| **UserMenu** | User profile dropdown with info rows and sections |

## Component Patterns

### CVA Variants

All components use CVA for variant management:

```tsx
<Button appearance="solid" intent="brand" size="md">Click me</Button>
<Button appearance="ghost" intent="brand" size="sm">Cancel</Button>
```

### Polymorphic Rendering (`asChild`)

Components support the `asChild` prop via Radix UI's Slot, allowing you to render as any element:

```tsx
<Button asChild>
  <a href="/dashboard">Go to Dashboard</a>
</Button>
```

### Icons in Components

Pass FontAwesome icon definitions directly:

```tsx
import { faPen, faTrash } from "@l3mpire/icons";

<Button leftIcon={faPen} size="md">Edit</Button>
<Button rightIcon={faTrash} intent="alert" size="md">Delete</Button>
<Button leftIcon={faPlus} iconOnly size="sm" />
```

### Dark Mode

Toggle dark mode by setting the `data-theme` attribute:

```html
<html data-theme="dark">
```

All component tokens automatically switch to their dark mode values.

## Utility: `cn()`

A `clsx` + `tailwind-merge` utility is exported for combining classes:

```tsx
import { cn } from "@l3mpire/ui";

<div className={cn("p-md rounded-base", isActive && "bg-blue-500")} />
```

## Exports

Every component exports its React component, CVA variants function (when applicable), and TypeScript props type:

```tsx
import {
  Button,
  buttonVariants,  // CVA variants function
  type ButtonProps, // TypeScript type
} from "@l3mpire/ui";

// Use buttonVariants() to get classes without rendering:
const classes = buttonVariants({ appearance: "solid", intent: "brand", size: "md" });
```

## Storybook

Browse the full component documentation with interactive examples:

```bash
# From the monorepo root
pnpm --filter @l3mpire/storybook dev
```

Opens at `http://localhost:6006`.