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

# My3DUI - 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 @sreedev/my3dui react react-dom
# or
yarn add @sreedev/my3dui react react-dom
# or
pnpm add @sreedev/my3dui react react-dom
```

### Styles (zero-config)

**Styles load automatically** when you import any component from `@sreedev/my3dui`. You do **not** need to import CSS manually.

```tsx
import { Button3D, ThemeProvider } from "@sreedev/my3dui";
// That's it — design tokens and Tailwind utilities are already loaded
```

The built CSS (Tailwind base/components/utilities and theme tokens for `:root`, `.dark`, `.neon`, `.glass`, `.corporate`, `.vibrant`) is bundled with the library and injected when your bundler resolves the package. You do **not** need to install Tailwind in your app. Optional: if you need to load styles without importing a component (e.g. for SSR or a custom entry), you can still do `import "@sreedev/my3dui/styles.css"`.

### Premium API (recommended)

Use the same import path with **simple names** and **optional** 3D-style depth—**no `<Canvas>` required** for buttons, cards, or inputs. Optional WebGL scenes use `SceneViewport`, which lazy-loads `@react-three/fiber` and falls back when WebGL is unavailable.

```tsx
import {
  ThemeProvider,
  Button,
  Card,
  CardHeader,
  CardTitle,
  CardDescription,
  CardContent,
  CardFooter,
  Input,
  SceneViewport,
  useWebGLSupport,
} from "@sreedev/my3dui";

function Demo() {
  const webgl = useWebGLSupport();
  return (
    <ThemeProvider defaultTheme="light">
      <Card variant="glass" size="md" enable3D intensity={0.55} glow>
        <CardHeader>
          <CardTitle>Billing</CardTitle>
          <CardDescription>Subscription overview</CardDescription>
        </CardHeader>
        <CardContent className="space-y-3">
          <Input placeholder="Search…" variant="glass" enable3D />
          <Button variant="primary" size="md" loading={false} enable3D glow>
            Continue
          </Button>
        </CardContent>
        <CardFooter>
          <span className="text-xs text-muted-foreground">
            WebGL: {webgl ? "available" : "unavailable"}
          </span>
        </CardFooter>
      </Card>

      {/* True 3D: only when you pass R3F nodes as children */}
      <SceneViewport enable3D className="h-64" fallback={<p>3D unavailable</p>}>
        {/* e.g. <Scene3D><Container3D>...</Container3D></Scene3D> */}
      </SceneViewport>
    </ThemeProvider>
  );
}
```

**Standard props** across primitives:

| Prop        | Values                                      | Notes                                      |
|------------|---------------------------------------------|--------------------------------------------|
| `size`     | `sm` · `md` · `lg`                          | Padding / control height                     |
| `variant`  | `primary` · `secondary` · `outline` · `ghost` · `glass` | Surface / control style              |
| `loading`  | boolean                                     | Spinner + `aria-busy`                        |
| `disabled` | boolean                                     | Non-interactive                              |
| `error`    | boolean                                     | Destructive ring where applicable           |
| `enable3D` | boolean                                     | CSS depth / tilt / glow (no Canvas needed)   |
| `intensity`| 0–1                                         | Strength for glow / tilt                     |
| `glow`     | boolean                                     | Extra primary-tinted shadow                  |

### Optional Dependencies

For 3D component support, install the following packages:

```bash
npm install three @react-three/fiber @react-three/drei
```

## Exported Components

All components are exported from the main entry. Use tree-shaking for optimal bundle size.

**Layout:** `Container`, `Grid`, `Stack`, `Section`, `PageLayout`, `Stage`, `Viewport`, `SceneViewport`, `Container3D`, `Grid3D`, `CameraController`, `Scene3D`

**3D UI:** `Button` (alias of `Button3D`), `Button3D`, `Card3D`, `Accordion3D`, `Badge3D`, `Input3D`, `Slider3D`, `Tabs3D`, `Toggle3D`, `Modal3D`, `Menu3D`, `Menu3DItem`, `Menu3DLabel`, `Menu3DSeparator`, `Tooltip3D`, `Progress3D`, `ResizablePanelGroup`, `ResizablePanel`, `ResizableHandle`, `Select3D`, `Spinner3D`, `Stepper3D`, `NavBar3D`, `Timeline3D`

**Standard UI:** `Tooltip`, `TooltipProvider`, `Slider`, `Toggle`, `Badge`, `Input`, `Select`, `Table`, `Pagination`, `Progress`, `Skeleton`, `Toast`, `Toaster`, `SonnerToaster`, `sonnerToast`, `Popover`, `Sheet`, `Dialog`, `Breadcrumb`, `Label`, `Checkbox`, `Switch`, `Textarea`, `Separator`, `ScrollArea`, `ScrollBar`, `RadioGroup`, `ToggleGroup`, `Alert`, `Avatar`, `Card`, `Collapsible`, `AspectRatio`, `HoverCard`, `AlertDialog`, `Command`, `Form`, `DropdownMenu`, `ContextMenu`, `Drawer`, `Menubar`, `NavigationMenu`, `Calendar`, `Sidebar`, `Carousel`, `InputOTP`, and subcomponents.

**Data viz:** `BarChart3D`, `LineChart3D`, `PieChart3D`, `ScatterPlot3D`, `Graph3D`, `Map3D`

**Media:** `Gallery3D`, `ModelViewer`, `VideoPlane`, `ImagePlane`, `AudioVisualizer`

**Effects:** `Particles`, `Bloom`, `Reflection`, `Fog`, `ShadowSystem`, `GlowEffect`, `WaveEffect`, `NoiseField`

**Theme:** `ThemeProvider`, `useTheme`, `useThemeOptional`, `ThemeName`

**System:** `useWebGLSupport`, `getWebGLSupport`, types `UISize`, `UIVariant`, `UIStateProps`, `UIEnhance3DProps`, and `buttonVariants` for custom compositions.

## Multi-theme system

My3DUI ships with six themes controlled by a class on `document.documentElement`. Use `ThemeProvider` to switch themes and persist the choice.

**Themes:** `light` (default), `dark`, `neon`, `glass`, `corporate`, `vibrant`

```tsx
import { ThemeProvider, useTheme } from "@sreedev/my3dui";
import "@sreedev/my3dui/styles.css";

function App() {
  return (
    <ThemeProvider defaultTheme="light" storageKey="my3dui-theme">
      <Demo />
    </ThemeProvider>
  );
}

function Demo() {
  const { theme, setTheme } = useTheme();
  return (
    <select value={theme} onChange={(e) => setTheme(e.target.value)}>
      <option value="light">Light</option>
      <option value="dark">Dark</option>
      <option value="neon">Neon</option>
      <option value="glass">Glass</option>
      <option value="corporate">Corporate</option>
      <option value="vibrant">Vibrant</option>
    </select>
  );
}
```

All components use CSS variables for colors, so they automatically adapt to the active theme. No extra Tailwind setup is required in the consumer app when using the built CSS.

## Design system

### Design tokens

The library uses two layers of tokens:

**1. CSS variables (in `styles.css`)** — Drive theming; values are RGB triplets so Tailwind can apply opacity:

- **Colors:** `--color-primary`, `--color-primary-foreground`, `--color-secondary`, `--color-accent`, `--color-danger`, `--color-success`, `--color-warning`, `--color-background`, `--color-foreground`, `--color-surface`, `--color-border`, `--color-text-primary`, `--color-text-secondary`, `--color-ring`, `--color-muted`, `--color-muted-foreground`
- **Shadows:** `--shadow-soft`, `--shadow-glow`
- **Radius:** `--radius-sm`, `--radius-md`, `--radius-lg`, `--radius-xl`, `--radius-2xl`, `--radius-full`

Each theme (`:root`, `.dark`, `.neon`, `.glass`, `.corporate`, `.vibrant`) sets these variables.

**2. JS tokens (in `lib/tokens.ts`)** — Spacing scale, z-index scale, duration, breakpoints for layout and animation. Used by layout components and shared utilities.

### Variants (CVA)

Components use **class-variance-authority** for consistent variant APIs:

- **Size:** `xs`, `sm`, `md`, `lg`, `xl`, `icon` (and `icon-sm`, `icon-lg` where applicable).
- **Color:** `primary`, `secondary`, `accent`, `danger`, `success`, `warning`, `info`, `muted`.
- **Style:** `solid`, `outline`, `ghost`, `soft`, `glass`.
- **State:** `loading`, `disabled`, `error` (where applicable).
- **Shape:** `rounded-sm` through `rounded-full`.
- **Elevation:** `flat`, `low`, `medium`, `high`, `glow` (Card, surfaces).

Shared variant helpers live in `lib/variants.ts` for internal use; component APIs expose the props that make sense (e.g. `Button3D`: `variant`, `size`, `rounded`; `Badge`: `variant`, `size`, `shape`; `Input`: `size`, `error`; `Card`: `elevation`).

### Layout components

- **Container:** `size`, `padding`, `fluid`; responsive horizontal padding by default.
- **Stack:** `direction`, `gap`, `align`, `justify`, `wrap`, `inline`; `gap` uses spacing scale.
- **Grid:** `cols` (number or responsive `{ sm, md, lg, xl, 2xl }`), `gap`, `minColWidth`; Tailwind-safe responsive classes.
- **Section:** `fullWidth`, `background`, `containerSize`, `noPadding`, `paddingY`, `as` (section | div | article).
- **PageLayout:** `header`, `footer`, `sidebar`, `sidebarPosition`, `sidebarWidth`, `minHeight`.

### Accessibility

Components follow common a11y patterns: focus rings (`focus-visible:ring-2`), `aria-invalid` on inputs when `error`, `disabled`/`loading` with reduced opacity and pointer-events, and semantic HTML. Radix-based components inherit Radix’s keyboard and screen reader behavior.

## Quick Start

### Basic Button3D Component

```tsx
import React from 'react';
import { Button3D } from '@sreedev/my3dui';

export function MyComponent() {
  return (
    <Button3D 
      variant="primary" 
      size="lg"
      onClick={() => console.log('Clicked!')}
    >
      Click Me
    </Button3D>
  );
}
```

### Card3D Component

```tsx
import { Card3D } from '@sreedev/my3dui';

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 { 
  Button3D, 
  Input, 
  Select, 
  Badge,
  Card 
} from '@sreedev/my3dui';

export function StandardUI() {
  return (
    <Card>
      <div className="space-y-4">
        <Input placeholder="Enter text..." />
        <Select>
          <option>Option 1</option>
          <option>Option 2</option>
        </Select>
        <Button3D>Submit</Button3D>
      </div>
    </Card>
  );
}
```

## 3D Components Guide

### Using 3D Effects with Canvas

My3DUI 3D components require a `<Canvas>` from @react-three/fiber:

```tsx
import { Canvas } from '@react-three/fiber';
import { Bloom } from '@sreedev/my3dui';

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 '@sreedev/my3dui';

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 '@sreedev/my3dui';

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 '@sreedev/my3dui';

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 '@sreedev/my3dui';

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 '@sreedev/my3dui';

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

My3DUI 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/@sreedev/my3dui/**/*.{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 My3DUI components maintain compatibility with shadcn/ui styling:

```tsx
// Before
import { Button } from '@/components/ui/button';

// After - with enhanced features
import { Button3D } from '@sreedev/my3dui';
```

### 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 '@sreedev/my3dui';  // Better
   // vs
   import * as My3DUI from '@sreedev/my3dui';    // 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/my3dui)
- 🐛 [Issue Tracker](https://github.com/yourusername/my3dui/issues)
- 💬 [Discussions](https://github.com/yourusername/my3dui/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