weloop-shadcn-ui/README.md

WeLoop UI component library with Radix UI and Recharts

# WeLoop ShadCN UI

A beautiful and accessible UI component library built with React, TypeScript, and SCSS.

[![npm version](https://img.shields.io/npm/v/weloop-shadcn-ui.svg)](https://www.npmjs.com/package/weloop-shadcn-ui)
[![license](https://img.shields.io/npm/l/weloop-shadcn-ui.svg)](https://github.com/your-username/weloop-shadcn-ui/blob/main/LICENSE)

## 🚀 Quick Start

### 1. Install

```bash
# React 18
npm install weloop-shadcn-ui@^1.1.8 react@^18 react-dom@^18
# (Only if you use forms)
npm install react-hook-form@^7 @hookform/resolvers@^3

# React 19
npm install weloop-shadcn-ui@^1.1.8 react@^19 react-dom@^19
# (Only if you use forms)
npm install react-hook-form@^8 @hookform/resolvers@^4
```

### 2. Import Styles

Add this to your main CSS file (e.g., `src/index.css` or `src/App.css`):

```css
@import "weloop-shadcn-ui/styles";
```

### 3. Import Components

```tsx
import {
  Button,
  Card,
  CardContent,
  CardHeader,
  CardTitle,
} from "weloop-shadcn-ui";
```

### 4. Use Components

```tsx
import {
  Button,
  Card,
  CardContent,
  CardHeader,
  CardTitle,
} from "weloop-shadcn-ui";

function App() {
  return (
    <div className="wl-container">
      <Card>
        <CardHeader>
          <CardTitle>Welcome to WeLoop ShadCN UI</CardTitle>
        </CardHeader>
        <CardContent>
          <Button>Click me</Button>
        </CardContent>
      </Card>
    </div>
  );
}
```

## ⚠️ Notes on React 19

- The core library builds and installs on React 19.
- Some form-related components rely on `react-hook-form`. It is not a peer; install it only if you use forms.
- Install `react-hook-form` and `@hookform/resolvers` with versions compatible to your React version (see commands above).

## 🎯 Features

- ⚛️ **React 18–19** - Tested install on React 18 and 19
- 🎨 **Beautiful Design** - Modern, accessible components
- 🌙 **Dark Mode** - Built-in dark mode support
- 📱 **Responsive** - Mobile-first design approach
- ♿ **Accessible** - WCAG compliant components
- 🎯 **TypeScript** - Full type safety
- 🎨 **Customizable** - Easy theming with CSS variables
- 📦 **Zero Setup** - No additional dependencies required
- 🚀 **Optimized** - Tree-shaking friendly with clean exports
- 🎨 **SCSS-based Styling** - Consistent design with SCSS classes
- 🔧 **Pure SCSS** - No external styling dependencies
- 📊 **Chart Components** - Built-in Recharts integration
- 🎯 **Form Handling** - React Hook Form integration
- 🎨 **Icon Support** - Lucide React icons included

## 🧩 Available Components

### Layout & Structure

- `Accordion` - Collapsible content sections
- `AppBar` - Application header with navigation
- `AspectRatio` - Maintain aspect ratio for content
- `Badge` - Status indicators and labels
- `Banner` - Prominent notification banners
- `Breadcrumb` - Navigation breadcrumbs
- `Button` - Interactive buttons with variants
- `ButtonGroup` - Grouped button components
- `Card` - Container components
- `Chip` - Compact information chips
- `Collapsible` - Collapsible content areas
- `EmptyState` - Empty state placeholders
- `Separator` - Visual dividers
- `Sheet` - Slide-out panels
- `Skeleton` - Loading placeholders

### Navigation

- `Menubar` - Horizontal menu bars
- `NavigationMenu` - Main navigation
- `Pagination` - Page navigation
- `Sidebar` - Side navigation with advanced features
- `Tabs` - Tabbed interfaces

### Forms & Inputs

- `Checkbox` - Checkbox inputs
- `Command` - Command palette
- `Form` - Form handling with validation
- `Input` - Text inputs with variants
- `InputOTP` - One-time password inputs
- `Label` - Form labels
- `RadioGroup` - Radio button groups
- `Select` - Dropdown selects
- `Slider` - Range sliders
- `Switch` - Toggle switches
- `TagInput` - Tag input component
- `Textarea` - Multi-line text inputs
- `Toggle` - Toggle buttons
- `ToggleGroup` - Grouped toggle buttons

### Overlays & Modals

- `AlertDialog` - Confirmation dialogs
- `ContextMenu` - Right-click menus
- `Dialog` - Modal dialogs
- `Drawer` - Slide-out panels
- `DropdownMenu` - Dropdown menus
- `HoverCard` - Hover-triggered cards
- `Popover` - Floating content
- `Tooltip` - Information tooltips

### Data Display

- `Alert` - Status messages
- `Avatar` - User avatars
- `Calendar` - Date picker
- `Carousel` - Image carousels
- `Chart` - Data visualization container
- `AreaChart` - Area chart visualization
- `BarChart` - Bar chart visualization
- `LineChart` - Line chart visualization
- `PieChart` - Pie chart visualization
- `RadarChart` - Radar chart visualization
- `RadialChart` - Radial bar chart visualization
- `FileUpload` - File upload component
- `Progress` - Progress indicators
- `ResizablePanel` - Resizable panel groups
- `ScrollArea` - Custom scrollbars
- `Table` - Data tables

### Utilities

- `useToast` - Toast notifications
- `Toaster` - Toast container
- `Snackbar` - Snackbar notifications
- `useMobile` - Mobile detection hook

## 🎨 Styling Approach

### SCSS-based Styling System

WeLoop ShadCN UI uses a pure SCSS styling approach:

- **SCSS-based Components**: All components are styled with SCSS for consistent design
- **Pre-built Classes**: Components come with ready-to-use SCSS classes
- **No External Dependencies**: Pure SCSS without Tailwind or other styling frameworks

### Using SCSS Classes

Components come with pre-built SCSS classes that you can use directly:

```tsx
<Button className="wl-button wl-button-primary">Click me</Button>
<Card className="wl-card wl-card-elevated">Content</Card>
```

### Responsive Design

All components include responsive SCSS classes:

```tsx
<Button className="wl-button wl-button-responsive">Responsive Button</Button>
```

## 📱 Responsive Design

All components are built with a mobile-first approach and include responsive SCSS classes:

```tsx
<Button className="wl-button wl-button-responsive">Responsive Button</Button>
```

## ♿ Accessibility

Components follow WCAG guidelines and include:

- Proper ARIA attributes
- Keyboard navigation support
- Screen reader compatibility
- Focus management
- Color contrast compliance

## 🔧 Development

### Building the Library

```bash
npm run build
```

This command builds both the TypeScript/JavaScript code and SCSS styles together.

For individual builds:

```bash
npm run build:js    # Build only JavaScript/TypeScript
npm run build:styles # Build only SCSS styles
```

### Running the Demo

```bash
npm run dev
# or
npm run demo
```

The demo will be available at `http://localhost:5173/`

### Building the Demo

```bash
npm run preview
```

## 📦 Package Structure

```
weloop-shadcn-ui/
├── dist/                  # Built library files
│   ├── index.js          # Main library bundle
│   ├── index.d.ts        # TypeScript definitions
│   └── styles.css        # Compiled styles
├── src/
│   ├── components/ui/    # UI components
│   ├── hooks/           # Custom hooks
│   └── lib/             # Utilities and variants
└── demo/                 # Demo application (not included in package)
```

## 📚 Resources

- [React Documentation](https://react.dev/)
- [SCSS Documentation](https://sass-lang.com/)
- [Radix UI Documentation](https://www.radix-ui.com/)
- [Recharts Documentation](https://recharts.org/)
- [React Hook Form Documentation](https://react-hook-form.com/)
- [Changelog](./CHANGELOG.md)

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

Built with ❤️ by the WeLoop Team