npm package: @rayvelez/dashboard-ui
Description: A beautiful dashboard design system with animated charts, neumorphic cards, and dark mode support
Latest version: 0.1.5

# @your-org/dashboard-ui

A beautiful dashboard design system featuring animated charts, neumorphic soft-UI cards, skeleton loaders, and dark mode support. Built with React, Tailwind CSS, and Framer Motion.

## Features

- 🎨 **Neumorphic Design** - Soft UI cards with elegant shadows
- 🌙 **Dark Mode** - Full light/dark theme support
- 📊 **Animated Charts** - CircleGraph and HorizontalBarChart with smooth animations
- 💀 **Skeleton Loaders** - Beautiful loading states with shimmer effect
- 🧭 **Navigation** - HeaderNavBar with theme toggle and tooltips
- 🎯 **TypeScript** - Full type safety with exported interfaces

## Installation

```bash
npm install @your-org/dashboard-ui
# or
yarn add @your-org/dashboard-ui
# or
pnpm add @your-org/dashboard-ui
```

### Peer Dependencies

Make sure you have these installed:

```bash
npm install react react-dom tailwindcss framer-motion
# Optional for specific components:
npm install react-router-dom  # For NavLink
npm install next-themes       # For HeaderNavBar theme toggle
```

## Setup

### 1. Import the CSS

Add the theme styles to your app's entry point:

```tsx
// In your main.tsx or App.tsx
import "@your-org/dashboard-ui/styles";
```

Or import in your CSS:

```css
/* In your global CSS file */
@import "@your-org/dashboard-ui/styles";
```

### 2. Configure Tailwind

Extend your `tailwind.config.js` with the preset:

```js
// tailwind.config.js
module.exports = {
  presets: [require("@your-org/dashboard-ui/tailwind-preset")],
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    // Include the package components
    "./node_modules/@your-org/dashboard-ui/dist/**/*.{js,mjs}",
  ],
  // ... your other config
};
```

### 3. Set up Dark Mode (Optional)

For theme switching, wrap your app with a theme provider:

```tsx
import { ThemeProvider } from "next-themes";

function App() {
  return (
    <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
      {/* Your app */}
    </ThemeProvider>
  );
}
```

## Components

### DashboardTemplate

A complete, configurable dashboard page that can be dropped in with one import.

```tsx
import { DashboardTemplate } from "@your-org/dashboard-ui";

// Basic usage with defaults
<DashboardTemplate />

// Fully configured
<DashboardTemplate
  revenue={{
    total: "$2.5M",
    changeText: "+18% vs Last Month",
    chartData: [45, 52, 38, 65, 72, 80, 95],
    chartLabels: ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul"],
  }}
  salesStats={{ closedDeals: 245, activeOpportunities: 520 }}
  customers={[
    { name: "John Doe", company: "Acme Inc", amount: "$50k", avatar: "/avatars/john.jpg" },
  ]}
  tasks={[
    { id: 1, text: "Follow up with client", due: "Today", completed: false },
  ]}
  onTaskToggle={(id) => console.log("Toggle task:", id)}
  onNavigate={(id) => console.log("Navigate to:", id)}
  isLoading={false}
/>
```

#### Props

| Prop | Type | Description |
|------|------|-------------|
| `revenue` | `RevenueData` | Revenue display data |
| `salesStats` | `SalesStats` | Closed deals & opportunities |
| `activityRings` | `ActivityRingData[]` | Circle graph data |
| `leadStatuses` | `LeadStatus[]` | Lead status bar segments |
| `tasks` | `Task[]` | Upcoming tasks list |
| `activities` | `Activity[]` | Recent activities table |
| `customers` | `Customer[]` | Top customers list |
| `navItems` | `NavItem[]` | Header navigation items |
| `isLoading` | `boolean` | Show skeleton loader |
| `showAlternateView` | `boolean` | Toggle alternate charts |
| `onTaskToggle` | `(id) => void` | Task completion callback |
| `onNavigate` | `(id) => void` | Navigation callback |

### CircleGraph

An animated multi-ring circular chart.

```tsx
import { CircleGraph } from "@your-org/dashboard-ui";

const data = [
  { label: "Sales", value: 85, color: "hsl(25 95% 53%)" },
  { label: "Marketing", value: 65, color: "hsl(142 71% 45%)" },
  { label: "Support", value: 45, color: "hsl(215 16% 47%)" },
];

<CircleGraph data={data} size={200} />;
```

#### Props

| Prop   | Type         | Default | Description                        |
| ------ | ------------ | ------- | ---------------------------------- |
| `data` | `RingData[]` | -       | Array of ring data (required)      |
| `size` | `number`     | `200`   | Size of the graph in pixels        |

### HorizontalBarChart

An animated horizontal bar chart with category groupings.

```tsx
import { HorizontalBarChart } from "@your-org/dashboard-ui";

const categories = [
  {
    title: "Products",
    bars: [
      { label: "Electronics", value: 85 },
      { label: "Software", value: 70 },
    ],
  },
  {
    title: "Regions",
    bars: [
      { label: "North America", value: 90 },
      { label: "Europe", value: 65 },
    ],
  },
];

<HorizontalBarChart categories={categories} />;
```

#### Props

| Prop         | Type             | Default          | Description                     |
| ------------ | ---------------- | ---------------- | ------------------------------- |
| `categories` | `CategoryData[]` | Default data     | Array of category data          |

### HeaderNavBar

A navigation bar with icon buttons, tooltips, and theme toggle.

```tsx
import { HeaderNavBar } from "@your-org/dashboard-ui";
import { Home, Settings, Users } from "lucide-react";

const navItems = [
  { id: "home", icon: Home, label: "Home" },
  { id: "users", icon: Users, label: "Users" },
  { id: "settings", icon: Settings, label: "Settings" },
];

<HeaderNavBar
  items={navItems}
  defaultActiveId="home"
  onNavigate={(id) => console.log("Navigated to:", id)}
  showThemeToggle={true}
/>;
```

#### Props

| Prop              | Type                   | Default    | Description                      |
| ----------------- | ---------------------- | ---------- | -------------------------------- |
| `items`           | `NavItem[]`            | Defaults   | Navigation items                 |
| `defaultActiveId` | `string`               | `"home"`   | Initially active item            |
| `onNavigate`      | `(id: string) => void` | -          | Callback on navigation           |
| `showThemeToggle` | `boolean`              | `true`     | Show/hide theme toggle           |

### NavLink

Enhanced router NavLink with simpler className API.

```tsx
import { NavLink } from "@your-org/dashboard-ui";

<NavLink
  to="/dashboard"
  className="px-4 py-2"
  activeClassName="bg-primary text-primary-foreground"
  pendingClassName="opacity-50"
>
  Dashboard
</NavLink>;
```

### Skeleton Components

Loading placeholders with shimmer animation.

```tsx
import {
  Skeleton,
  DashboardSkeleton,
  SalesPerformanceCardSkeleton,
  CustomerActivitySkeleton,
} from "@your-org/dashboard-ui";

// Basic skeleton
<Skeleton className="h-4 w-32" />
<Skeleton variant="circle" className="w-10 h-10" />

// Full dashboard loading state
<DashboardSkeleton />

// Individual card skeletons
<SalesPerformanceCardSkeleton />
<CustomerActivitySkeleton />
```

## CSS Classes

The package includes these utility classes:

| Class             | Description                                    |
| ----------------- | ---------------------------------------------- |
| `.soft-card`      | Neumorphic card with outer shadows             |
| `.inner-well`     | Inset/pressed appearance for inner elements    |
| `.shadow-glow`    | Glowing shadow effect using primary color      |
| `.skeleton-shimmer` | Shimmer animation for loading states         |

```tsx
<div className="soft-card rounded-4xl p-6">
  <div className="inner-well rounded-xl p-4">Content</div>
</div>
```

## Utilities

### cn()

A utility for merging Tailwind classes:

```tsx
import { cn } from "@your-org/dashboard-ui";

<div className={cn("p-4", isActive && "bg-primary", className)} />;
```

## Theme Customization

Override CSS variables in your own CSS:

```css
:root {
  /* Change the primary/accent color */
  --primary: 220 90% 56%; /* Blue instead of orange */
  --accent: 220 90% 56%;
  --ring: 220 90% 56%;

  /* Adjust border radius */
  --radius: 0.75rem;
}
```

## TypeScript

All components export their prop interfaces:

```tsx
import type {
  CircleGraphProps,
  RingData,
  HorizontalBarChartProps,
  CategoryData,
  BarData,
  HeaderNavBarProps,
  NavItem,
  NavLinkCompatProps,
  SkeletonProps,
} from "@your-org/dashboard-ui";
```

## License

MIT