@l3mpire/ui 2.5.1

package/README.md

@@ -0,0 +1,211 @@
+# @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`.