npm package: @ragdalion/ui
Description: Ragdalion React UI Kit — fully typed, tree-shakeable component library built with Tailwind CSS, Radix UI, and CVA.
Author: Ragdalion
Latest version: 0.0.1

# @ragdalion/ui

A professional, headless-friendly React UI component library built with **Tailwind CSS**, **Radix UI**, and **Class Variance Authority (CVA)**.

Fully typed. Tree-shakeable. Dark mode ready.

---

## Installation

```bash
# npm
npm install @ragdalion/ui

# pnpm
pnpm add @ragdalion/ui

# bun
bun add @ragdalion/ui
```

### Peer Dependencies

Make sure your project has these installed:

```bash
npm install react react-dom tailwindcss
```

---

## Quick Start

```tsx
import { Button, Badge, Modal, Tabs } from "@ragdalion/ui";

export default function App() {
  return (
    <div className="p-8 space-y-4">
      <Button variant="primary" size="md">
        Get Started
      </Button>

      <Badge color="green" style="soft">
        Active
      </Badge>

      <Modal
        triggerLabel="Open Modal"
        title="Confirm Action"
        description="Are you sure you want to proceed?"
        variant="confirm"
      />
    </div>
  );
}
```

---

## Components

### Core UI

| Component | Description |
| --- | --- |
| `Button` | Multi-variant button with loading state, icons, and `asChild` |
| `ButtonSocial` | Google / Facebook / Twitter sign-in buttons |
| `Badge` | Color badges with dot, icon, and removable variants |
| `Alert` | Info / success / warning / error alerts (default, filled, outline, toast) |
| `Accordion` | Radix-based accordion with single/multiple + 4 visual variants |
| `Breadcrumb` | Breadcrumb navigation with 4 styles and 5 separator options |
| `Dialog` | Full Radix Dialog primitives (Dialog, Content, Header, Footer, etc.) |
| `Modal` | Pre-composed modal with confirm/danger/success/form variants |
| `Progress` | Animated progress bar |
| `Tooltip` | Radix tooltip with 6 color variants |
| `Tabs` | Pure React tabs with 5 variants + vertical orientation |
| `Pagination` | 5-variant pagination with controlled & uncontrolled modes |
| `PaginationDefault` | Table-style pagination with rows-per-page selector |
| `Select` | Full Radix Select wrapper |
| `SelectCustom` | Select with label integration |
| `Table` | Composable table primitives (`Table`, `THead`, `TBody`, `Th`, `Td`, etc.) |
| `SortIcon` | Sort direction indicator for table headers |
| `Label` | Form label component |

### File Upload

| Component | Description |
| --- | --- |
| `AvatarUpload` | Circular avatar upload with progress overlay |
| `DocumentUpload` | Document file upload with file-type icons |
| `DragDropGeneral` | General drag & drop zone for any file type |
| `FileInputRow` | Inline file input with preview and remove actions |
| `ImageGalleryUpload` | Image-only upload with grid gallery preview |
| `InlineUpload` | Compact file attachment for chat/message forms |
| `MultiFileInputRow` | Multi-file input with preview chips |
| `VideoUpload` | Video/media upload with drag & drop and progress |

### Utilities

| Export | Description |
| --- | --- |
| `cn()` | `clsx` + `tailwind-merge` utility |
| `formatBytes()` | Human-readable file size formatter |
| `addFiles()` | Simulated file upload hook with progress tracking |
| `getFileIcon()` | SVG icon based on MIME type |
| `DeleteBtn` | Small icon-only delete button |
| `PreviewModal` | File preview modal (images, videos) |

---

## Variants & Customization

All components accept a `className` prop for Tailwind overrides:

```tsx
<Button variant="outline" className="rounded-full px-8">
  Custom Style
</Button>

<Badge color="purple" style="solid" size="lg">
  Premium
</Badge>
```

### Button Variants

`default` · `destructive` · `outline` · `secondary` · `ghost` · `link` · `primary` · `newPrimary` · `gradient` · `blue` · `icon` · and more

### Badge Colors

`gray` · `blue` · `green` · `red` · `amber` · `purple` · `pink` · `cyan`

### Alert Styles

`default` · `filled` · `outline` · `toast`

---

## TypeScript

Every component is fully typed. Import types directly:

```tsx
import type {
  ButtonProps,
  BadgeColor,
  BadgeStyle,
  TabItem,
  TabsProps,
  UploadedFile,
  SelectedFile,
  SortDir,
} from "@ragdalion/ui";
```

---

## Dark Mode

All components support dark mode via Tailwind's `dark:` prefix. Just enable dark mode in your Tailwind config:

```js
// tailwind.config.js
module.exports = {
  darkMode: "class", // or 'media'
  // ...
};
```

---

## Charts

Chart components are available via a separate sub-path import to keep the main bundle lean:

```tsx
import { SimpleBar, DonutChart, AreaLine, SimpleRadar } from "@ragdalion/ui/charts";
```

All 30+ chart variants are available: Bar, Line, Pie, Radar, and Scatter charts.

---

## Development

```bash
# Install dependencies
bun install

# Watch mode (rebuilds on change)
bun run dev

# Build for production
bun run build

# Type check
bun run typecheck

# Publish
npm publish
```

---

## License

MIT © [Ragdalion](https://github.com/ragdalion)