npm package: @sreedev/m3dui
Description: A modern 3D-inspired UI component library for React with Three.js integration
Author: Sreekanth
Latest version: 0.1.1

# M3DUI - Modern 3D-Inspired UI Component Library

A TypeScript React component library combining beautiful 2D UI components with cutting-edge 3D visual effects using Three.js. Built on top of shadcn/ui, Radix UI, Framer Motion, and @react-three/fiber for maximum flexibility and extensibility.

## Features

🎨 **Rich Component Library**
- 50+ pre-built UI components
- 3D-enhanced variants of common components
- Fully TypeScript support
- Dark mode support via next-themes
- Fully customizable with Tailwind CSS

🎬 **3D Visual Effects**
- Three.js integration via @react-three/fiber
- Bloom effects and post-processing
- Particle systems and animations
- 3D model viewers and galleries
- Custom WebGL effects

🎭 **Animation & Motion**
- Framer Motion integration
- Smooth transitions and interactions
- Spring animations
- Gesture controls

📦 **Developer Experience**
- ESM, CJS, and type declarations included
- Tree-shakeable exports
- Full TypeScript support
- No peer dependency conflicts
- Modular imports for code-splitting

## Installation

```bash
npm install m3dui react react-dom
# or
yarn add m3dui react react-dom
# or
pnpm add m3dui react react-dom
```

### Optional Dependencies

For 3D component support, install the following packages:

```bash
npm install three @react-three/fiber @react-three/drei
```

## Quick Start

### Basic Button3D Component

```tsx
import React from 'react';
import { Button3D } from 'm3dui';

export function MyComponent() {
  return (
    <Button3D 
      variant="primary" 
      size="lg"
      onClick={() => console.log('Clicked!')}
    >
      Click Me
    </Button3D>
  );
}
```

### Card3D Component

```tsx
import { Card3D } from 'm3dui';

export function MyCard() {
  return (
    <Card3D className="w-96">
      <div className="p-6">
        <h2 className="text-2xl font-bold">Card Title</h2>
        <p className="text-gray-600">Card content goes here</p>
      </div>
    </Card3D>
  );
}
```

### Using Standard Components

```tsx
import { 
  Button, 
  Input, 
  Select, 
  Badge,
  Card 
} from 'm3dui';

export function StandardUI() {
  return (
    <Card>
      <div className="space-y-4">
        <Input placeholder="Enter text..." />
        <Select>
          <option>Option 1</option>
          <option>Option 2</option>
        </Select>
        <Button>Submit</Button>
      </div>
    </Card>
  );
}
```

## 3D Components Guide

### Using 3D Effects with Canvas

m3dui 3D components require a `<Canvas>` from @react-three/fiber:

```tsx
import { Canvas } from '@react-three/fiber';
import { Bloom } from 'm3dui';

export function MyScene() {
  return (
    <Canvas>
      <Bloom intensity={1.5} radius={0.8} threshold={0.5} />
      {/* Your 3D content */}
    </Canvas>
  );
}
```

### Bloom Effect

```tsx
import { Canvas } from '@react-three/fiber';
import { Bloom } from 'm3dui';

export function BloomExample() {
  return (
    <Canvas>
      <Bloom 
        intensity={1.2}    // Effect intensity
        radius={0.5}       // Blur radius
        threshold={0.2}    // Light threshold
      />
      <mesh>
        <boxGeometry args={[1, 1, 1]} />
        <meshBasicMaterial color="white" emissive="#00ff00" />
      </mesh>
    </Canvas>
  );
}
```

### 3D Image/Video Planes

```tsx
import { Canvas } from '@react-three/fiber';
import { ImagePlane, VideoPlane } from 'm3dui';

export function MediaPlanes() {
  return (
    <Canvas>
      <ImagePlane 
        src="/path/to/image.jpg" 
        width={4}
        height={3}
      />
    </Canvas>
  );
}
```

### Gallery3D Component

```tsx
import { Canvas } from '@react-three/fiber';
import { Gallery3D } from 'm3dui';

export function MyGallery() {
  const images = [
    '/image1.jpg',
    '/image2.jpg',
    '/image3.jpg',
  ];

  return (
    <Canvas>
      <Gallery3D images={images} />
    </Canvas>
  );
}
```

### Map3D Component

```tsx
import { Canvas } from '@react-three/fiber';
import { Map3D } from 'm3dui';

export function InteractiveMap() {
  return (
    <Canvas>
      <Map3D 
        latitude={40.7128}
        longitude={-74.0060}
        zoom={12}
      />
    </Canvas>
  );
}
```

### Particle System

```tsx
import { Canvas } from '@react-three/fiber';
import { Particles } from 'm3dui';

export function ParticleEffect() {
  return (
    <Canvas>
      <Particles 
        count={1000}
        color="0x00ff00"
        speed={0.5}
      />
    </Canvas>
  );
}
```

## Component API Reference

### Button3D

```tsx
interface Button3DProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'secondary' | 'accent' | 'destructive' | 'outline' | 'ghost' | 'glass';
  size?: 'sm' | 'md' | 'lg' | 'icon' | 'default';
  loading?: boolean;
  asChild?: boolean;
  shadowColor?: string;
}
```

### Card3D

```tsx
interface Card3DProps extends React.HTMLAttributes<HTMLDivElement> {
  elevation?: number;
  glow?: boolean;
  glowColor?: string;
}
```

### Input3D

```tsx
interface Input3DProps extends React.InputHTMLAttributes<HTMLInputElement> {
  variant?: 'default' | 'gradient' | 'glass';
  icon?: React.ReactNode;
}
```

### Bloom

```tsx
interface BloomProps {
  intensity?: number;    // Default: 1.0
  radius?: number;       // Default: 0.4
  threshold?: number;    // Default: 0
}
```

### Particles

```tsx
interface ParticlesProps {
  count?: number;        // Default: 100
  color?: string;        // Hex color
  speed?: number;        // Default: 1
  size?: number;         // Default: 1
}
```

## Theming

### Using next-themes

m3dui supports dark mode seamlessly via next-themes:

```tsx
import { ThemeProvider } from 'next-themes';
import MyApp from './App';

export function App() {
  return (
    <ThemeProvider attribute="class">
      <MyApp />
    </ThemeProvider>
  );
}
```

### Custom Tailwind Config

```js
// tailwind.config.js
module.exports = {
  content: [
    './node_modules/m3dui/**/*.{js,ts,jsx,tsx}',
  ],
  theme: {
    extend: {
      colors: {
        'primary': '#your-color',
      }
    }
  }
}
```

## Peer Dependencies

The following peer dependencies are required:

```json
{
  "react": ">=18.0.0",
  "react-dom": ">=18.0.0",
  "three": ">=0.150.0"
}
```

Optional peer dependencies for 3D features:
- `@react-three/fiber` (^8.0.0)
- `@react-three/drei` (^9.0.0)

## Building from Source

```bash
# Install dependencies
npm install

# Type checking
npm run lint

# Build library
npm run build

# Watch mode (development)
npm run dev
```

## Project Structure

```
src/
├── components/
│   ├── layouts/          # Layout components (Container, Stack, Grid, etc.)
│   └── ui/               # UI components (Button3D, Card3D, etc.)
├── hooks/                # Custom React hooks
├── lib/                  # Utility functions
├── index.ts              # Main entry point
└── three-elements.d.ts   # Three.js type declarations
```

## Supported Components

### Layouts
- `Container` - Responsive container wrapper
- `Grid` - CSS Grid layout component
- `Stack` - Flexbox stack layout
- `Section` - Semantic section component
- `PageLayout` - Full-page layout template
- `Stage` - 3D stage container
- `Scene3D` - 3D scene wrapper
- `ViewPort` - Custom viewport handler

### 3D Components
- `Button3D` - 3D-styled button
- `Card3D` - 3D-enhanced card
- `Accordion3D` - 3D accordion menu
- `Badge3D` - 3D badge component
- `Input3D` - 3D input field
- `Slider3D` - 3D slider control
- `Tabs3D` - 3D tab navigation
- `Toggle3D` - 3D toggle switch
- `Modal3D` - 3D modal dialog
- `Menu3D` - 3D context menu
- `Tooltip3D` - 3D tooltip
- `Progress3D` - 3D progress bar
- `Select3D` - 3D select dropdown
- `Spinner3D` - 3D loading spinner
- `Stepper3D` - 3D step navigator
- `NavBar3D` - 3D navigation bar
- `Timeline3D` - 3D timeline
- `Bloom` - Bloom post-processing effect
- `Particles` - Particle system
- `ImagePlane` - 3D image plane
- `VideoPlane` - 3D video plane
- `Gallery3D` - 3D image gallery
- `Map3D` - 3D interactive map
- `ModelViewer` - 3D model viewer
- `Reflection` - Reflection effect
- `WaveEffect` - Wave animation
- `GlowEffect` - Glow animation
- `AudioVisualizer` - Audio-reactive visualizer

### Standard UI Components (from shadcn/ui)
- `Button` - Standard button
- `Input` - Text input field
- `Select` - Dropdown select
- `Badge` - Badge label
- `Card` - Card container
- `Dialog` - Modal dialog
- `Drawer` - Sliding drawer
- `Dropdown` - Dropdown menu
- `Form` - Form wrapper
- `Tabs` - Tab navigation
- `Tooltip` - Tooltip overlay
- `Slider` - Slider control
- `Toggle` - Toggle switch
- `Popover` - Popover component
- `Table` - Data table
- `Checkbox` - Checkbox input
- `RadioGroup` - Radio button group
- `Switch` - Toggle switch
- `Separator` - Visual divider
- `Skeleton` - Loading skeleton
- `Pagination` - Page selector
- `Calendar` - Date picker
- `Carousel` - Image carousel
- `Breadcrumb` - Breadcrumb navigation
- `Sheet` - Side sheet
- `Sidebar` - Sidebar navigation
- `Menubar` - Menu bar
- `Command Palette` - Command search
- `Context Menu` - Right-click menu
- `Alert` - Alert box
- And more!

## Migration Guide

### From shadcn/ui

All m3dui components maintain compatibility with shadcn/ui styling:

```tsx
// Before
import { Button } from '@/components/ui/button';

// After - with enhanced features
import { Button3D } from 'm3dui';
```

### Variant Changes

Button variants are consistent:

```tsx
// Works the same
<Button3D variant="outline">Click</Button3D>
<Button3D variant="ghost">Click</Button3D>
<Button3D variant="primary">Click</Button3D>
```

## Browser Support

- Chrome/Edge (latest)
- Firefox (latest)
- Safari (latest)
- Opera (latest)

For 3D features, WebGL support is required.

## Performance Tips

1. **Code Splitting**: Import components individually
   ```tsx
   import { Button3D } from 'm3dui';  // Better
   // vs
   import * as M3DUI from 'm3dui';    // Avoids this
   ```

2. **Lazy Load 3D Components**: Use React.lazy for 3D canvas
   ```tsx
   const Scene = React.lazy(() => import('./MyScene'));
   ```

3. **Memoization**: Wrap expensive components
   ```tsx
   const MemoizedGallery = React.memo(Gallery3D);
   ```

4. **SSR Compatibility**: Only render 3D on client
   ```tsx
   if (typeof window === 'undefined') return null;
   ```

## Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Write tests
5. Submit a pull request

## License

MIT License - see LICENSE file for details

## Support

- 📖 [Documentation](https://github.com/yourusername/m3dui)
- 🐛 [Issue Tracker](https://github.com/yourusername/m3dui/issues)
- 💬 [Discussions](https://github.com/yourusername/m3dui/discussions)

## Changelog

### v0.1.0 (Initial Release)
- Initial component library release
- 50+ components included
- Full TypeScript support
- 3D component suite
- Framer Motion integration
- Tailwind CSS styling
- shadcn/ui component compatibility