@sreedev/my3dui 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sreekanth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,536 @@
+# 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