npm package: @ravja/custom-react-components
Description: A collection of custom React components built on top of shadcn/ui with Tailwind CSS, including Scheduler, AnimatedModal, and more
Author: ravja
Latest version: 1.0.0-129

# @ravja/custom-react-components

A collection of custom React components built on top of shadcn/ui with Tailwind CSS, including Scheduler, AnimatedModal, and more.

📦 **Published on npm**: [https://www.npmjs.com/package/@ravja/custom-react-components](https://www.npmjs.com/package/@ravja/custom-react-components)

🌐 **Sample Page & Documentation**: [http://react.ryanlam.net/scheduler](http://react.ryanlam.net/scheduler)

[![npm version](https://img.shields.io/npm/v/@ravja/custom-react-components)](https://www.npmjs.com/package/@ravja/custom-react-components)
[![npm](https://img.shields.io/npm/dm/@ravja/custom-react-components)](https://www.npmjs.com/package/@ravja/custom-react-components)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 📦 Installation

Install the package using npm:

```bash
npm install @ravja/custom-react-components
```

Or using yarn:

```bash
yarn add @ravja/custom-react-components
```

Or using pnpm:

```bash
pnpm add @ravja/custom-react-components
```

## 📋 Package Information

- **Package Name**: `@ravja/custom-react-components`
- **Version**: `0.0.1`
- **NPM**: [https://www.npmjs.com/package/@ravja/custom-react-components](https://www.npmjs.com/package/@ravja/custom-react-components)
- **Author**: [ravja](https://www.npmjs.com/~ravja)
- **License**: MIT

## 🚀 Quick Start

### Installation

```bash
npm install @ravja/custom-react-components
# or
yarn add @ravja/custom-react-components
# or
pnpm add @ravja/custom-react-components
```

### Prerequisites

- React 18+ or React 19+
- TypeScript (recommended)
- Tailwind CSS configured in your project (for styling)
- Node.js 18+

### Basic Usage

#### Scheduler Component

```tsx
import { Scheduler, type SchedulerEvent, type SchedulerResource } from '@ravja/custom-react-components';
import '@ravja/custom-react-components/ravja.scheduler.css';

function App() {
  const resources: SchedulerResource[] = [
    { id: "1", name: "John Doe", color: "#3b82f6" },
    { id: "2", name: "Jane Smith", color: "#10b981" },
  ];

  const events: SchedulerEvent[] = [
    {
      id: "e1",
      title: "Team Meeting",
      resourceId: "1",
      start: new Date(2024, 0, 15, 10, 0),
      end: new Date(2024, 0, 15, 11, 30),
      description: "Weekly team sync",
    },
  ];

  return (
    <Scheduler
      resources={resources}
      events={events}
      onEventClick={(event) => console.log('Event clicked:', event)}
      onEventDrop={(event, newStart, newResourceId) => {
        console.log('Event dropped:', { event, newStart, newResourceId });
      }}
      onEventResize={(event, newEnd) => {
        console.log('Event resized:', { event, newEnd });
      }}
      startHour={8}
      endHour={20}
    />
  );
}
```

#### AnimatedModal Component

```tsx
import { AnimatedModal } from '@ravja/custom-react-components';

function App() {
  return (
    <AnimatedModal
      title="Confirm Action"
      description="Are you sure you want to proceed?"
      triggerText="Open Modal"
      maxWidth="lg"
      footerActions={
        <>
          <button onClick={() => console.log('Canceled')}>Cancel</button>
          <button onClick={() => console.log('Confirmed')}>Confirm</button>
        </>
      }
    >
      <p>Your modal content goes here.</p>
    </AnimatedModal>
  );
}
```

#### ImageUploaderCropper Component

```tsx
import { ImageUploaderCropper, type ImageUploaderCropperProps } from '@ravja/custom-react-components';
import { useState } from 'react';

function App() {
  const [croppedImage, setCroppedImage] = useState<string | null>(null);

  return (
    <div>
      <ImageUploaderCropper
        onChange={(image) => {
          // image can be Blob or string (base64)
          if (typeof image === 'string') {
            setCroppedImage(image);
          } else {
            const reader = new FileReader();
            reader.onloadend = () => {
              setCroppedImage(reader.result as string);
            };
            reader.readAsDataURL(image);
          }
        }}
        aspectRatios={[
          { label: 'Square (1:1)', value: 1 },
          { label: '4:3', value: 4 / 3 },
          { label: '16:9', value: 16 / 9 },
          { label: 'Custom', value: null },
        ]}
        outputFormat="base64"
      />
      
      {croppedImage && (
        <img src={croppedImage} alt="Cropped" className="mt-4 rounded-lg" />
      )}
    </div>
  );
}
```

### Import CSS Styles

**Important**: Don't forget to import the CSS file for the Scheduler component:

```tsx
import '@ravja/custom-react-components/ravja.scheduler.css';
// or
import '@ravja/custom-react-components/scheduler.css';
```

The CSS file includes all necessary Tailwind styles including dialog/modal animations - no additional Tailwind configuration needed!

## ✨ Features

- 🎨 **Beautiful UI** - Built with shadcn/ui and Tailwind CSS
- 📱 **Responsive Layout** - Resizable panels for optimal viewing experience
- 🔍 **Component Browser** - Easy navigation through component categories
- 📖 **Documentation** - Each component includes detailed documentation
- 📋 **Copy to Clipboard** - One-click code copying for easy integration
- 🌓 **Dark Mode** - Built-in theme switcher
- 🎯 **Modern Scrollers** - Custom styled scrollbars throughout
- 📅 **Scheduler Component** - Full-featured calendar/scheduler with drag & drop and event resizing
- 🎭 **Animated Modal** - Smooth animated modal dialogs with header and footer

## 🛠️ Development Setup

### Building the Library

To build the library for production:

```bash
npm run build
```

This will generate:
- `dist/index.js` - ESM build (for modern bundlers)
- `dist/index.cjs` - CommonJS build (for Node.js and older bundlers)
- `dist/index.d.ts` - TypeScript declarations
- `dist/ravja.scheduler.css` - Component styles

The library supports both ESM and CommonJS formats, making it compatible with:
- ✅ Create React App (CRA)
- ✅ Vite
- ✅ Next.js
- ✅ Webpack
- ✅ Rollup
- ✅ Any modern React application

### Publishing

```bash
npm run build
npm publish --access public
```

### Local Development

If you want to contribute or run the showcase locally:

1. Clone the repository:
```bash
# Clone the repository (if available)
cd Custom-React-Components
```

2. Install dependencies:
```bash
npm install
```

3. Start the development server:
```bash
npm run dev
```

4. Open [http://localhost:5173](http://localhost:5173) in your browser

### Demo/Testing

See the `demo/` folder for example usage of the components.

## Project Structure

```
src/
├── components/
│   ├── custom/          # Custom component implementations
│   │   ├── Scheduler.tsx      # Calendar/scheduler component
│   │   ├── AnimatedModal.tsx # Modal with bounce animations
│   │   └── ...               # Other custom components
│   ├── layout/          # Layout components (Sidebar, TopNav)
│   └── ui/              # shadcn/ui base components
├── data/
│   └── components.ts    # Component data and metadata
├── documents/           # Component documentation guides
│   ├── SCHEDULER-COMPONENT-GUIDE.md
│   └── MODAL-COMPONENT-GUIDE.md
├── lib/
│   └── utils.ts         # Utility functions
└── App.tsx              # Main application component
```

## Documentation

Detailed component guides are available in the `documents/` folder:

- **[Scheduler Component Guide](./documents/SCHEDULER-COMPONENT-GUIDE.md)** - Complete guide for the calendar/scheduler component with drag & drop, event resizing, and multiple views
- **[Modal Component Guide](./documents/MODAL-COMPONENT-GUIDE.md)** - Guide for creating animated modal dialogs with bounce effects

## Adding New Components

To add a new component to the showcase:

1. Create your component in `src/components/custom/`
2. Add component data to `src/data/components.ts`:

```typescript
{
  id: "my-component",
  name: "My Component",
  description: "A brief description",
  category: "Category Name",
  component: () => <MyComponent />,
  code: `// Your component code here`,
  documentation: `# My Component\n\nDocumentation in markdown...`
}
```

## 📚 Components

### Scheduler

A full-featured calendar/scheduler component with:
- Multiple views (Day, Week, Month)
- Drag & drop events
- Event resizing
- Multiple resources support
- Time slot highlighting
- Event details modal

**Example:**
```tsx
import { Scheduler, type SchedulerEvent, type SchedulerResource } from '@ravja/custom-react-components';

const resources: SchedulerResource[] = [
  { id: "1", name: "John Doe", color: "#3b82f6" },
  { id: "2", name: "Jane Smith", color: "#10b981" },
];

const events: SchedulerEvent[] = [
  {
    id: "e1",
    title: "Meeting",
    resourceId: "1",
    start: new Date(),
    end: new Date(),
  },
];

<Scheduler
  resources={resources}
  events={events}
  onEventClick={(event) => console.log(event)}
/>
```

### AnimatedModal

A modal dialog component with smooth animations:
- Fixed header and footer
- Scrollable content area
- Customizable width
- Smooth animations

**Example:**
```tsx
import { AnimatedModal } from '@ravja/custom-react-components';

<AnimatedModal
  title="Confirm Action"
  description="Are you sure you want to proceed?"
  triggerText="Open Modal"
  maxWidth="lg"
>
  <p>Your content here</p>
</AnimatedModal>
```

## 📖 Documentation

Detailed component guides are available:

- **[Scheduler Component Guide](./documents/SCHEDULER-COMPONENT-GUIDE.md)** - Complete guide for the calendar/scheduler component with drag & drop, event resizing, and multiple views
- **[Modal Component Guide](./documents/MODAL-COMPONENT-GUIDE.md)** - Guide for creating animated modal dialogs with bounce effects

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🔗 Links

- **NPM Package**: [https://www.npmjs.com/package/@ravja/custom-react-components](https://www.npmjs.com/package/@ravja/custom-react-components)
- **Author**: [ravja on npm](https://www.npmjs.com/~ravja)
- **Live Demo**: [http://react.ryanlam.net/scheduler](http://react.ryanlam.net/scheduler)

## 🛠️ Built With

- [React](https://react.dev/)
- [TypeScript](https://www.typescriptlang.org/)
- [Vite](https://vitejs.dev/)
- [Tailwind CSS](https://tailwindcss.com/)
- [shadcn/ui](https://ui.shadcn.com/)
- [react-resizable-panels](https://github.com/bvaughn/react-resizable-panels)
- [react-markdown](https://github.com/remarkjs/react-markdown)
- [date-fns](https://date-fns.org/)
- [Radix UI](https://www.radix-ui.com/)