npm package: @lukeyreyno/bubble-display
Description: Interactive Three.js bubble display with configurable content
Author: Lucas Reyna
Latest version: 1.0.0

# Bubble Display

Interactive Three.js bubble display with configurable content - perfect for creating engaging portfolio sections, feature showcases, or interactive content displays.

## Features

- 🫧 **Liquid-like bubbles** with smooth physics simulation
- 📱 **Interactive content** - click to expand bubbles and show detailed information
- 🎨 **Fully customizable** - colors, sizes, content, and positioning
- 📝 **Optional titles** - bubbles can have text labels or be plain spheres
- 🖼️ **Rich content** - support for images, descriptions, and custom styling
- ⚡ **Physics-based** - bubbles push each other around naturally
- 🎯 **TypeScript** - full type safety and excellent developer experience

## Installation

```bash
npm install @lukeyreyno/bubble-display three
```

Note: `three` is a peer dependency, so you need to install it separately.

## Quick Start

```typescript
import { BubbleDisplay, BubbleConfig } from '@lukeyreyno/bubble-display';

// Define your bubble content
const bubbles: BubbleConfig[] = [
  {
    content: {
      title: "My Project",
      description: "An awesome project I built with React and TypeScript",
      color: "#4A90E2",
      images: [
        { url: "/project-screenshot.jpg", alt: "Project Screenshot" }
      ]
    },
    position: { x: 0, y: 0, z: 0 },
    initialRadius: 1,
    expandedRadius: 2.5
  },
  {
    content: {
      title: "Another Project", 
      description: "A different project with cool features",
      color: "#50C878"
    },
    position: { x: 3, y: 1, z: 0 }
  }
];

// Get your container element
const container = document.getElementById('bubble-container');

// Create the display
const display = new BubbleDisplay(container, bubbles);
```

## Configuration

### BubbleConfig

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `content` | `BubbleContent` | ✅ | The content and styling for the bubble |
| `position` | `{x, y, z}` | ❌ | Initial 3D position (random if not provided) |
| `initialRadius` | `number` | ❌ | Starting size (default: 1) |
| `expandedRadius` | `number` | ❌ | Size when expanded (default: 2.5) |

### BubbleContent

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `title` | `string` | ❌ | Text shown on bubble surface |
| `description` | `string` | ✅ | Detailed content shown when expanded |
| `color` | `string` | ❌ | Bubble color (hex, rgb, etc.) |
| `textColor` | `string` | ❌ | Title text color (default: white) |
| `images` | `BubbleContentImage[]` | ❌ | Images to show in expanded view |

### BubbleContentImage

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `url` | `string` | ✅ | Image URL |
| `alt` | `string` | ✅ | Alt text for accessibility |
| `width` | `number` | ❌ | Image width |
| `height` | `number` | ❌ | Image height |

## API Reference

### BubbleDisplay

```typescript
class BubbleDisplay {
  constructor(
    container: HTMLElement, 
    bubbles?: BubbleConfig[],
    bounds?: { min: {x, y, z}, max: {x, y, z} }
  )
  
  addBubble(config: BubbleConfig): Bubble
  addBubbles(configs: BubbleConfig[]): Bubble[]
  getCamera(): THREE.Camera
  getScene(): THREE.Scene  
  getRenderer(): THREE.WebGLRenderer
  dispose(): void
}
```

## Examples

### Simple Usage
```typescript
const display = new BubbleDisplay(container, [
  {
    content: {
      title: "Hello World",
      description: "My first bubble!",
      color: "#ff6b6b"
    }
  }
]);
```

### Without Titles (Plain Spheres)
```typescript
const display = new BubbleDisplay(container, [
  {
    content: {
      description: "This bubble has no title text",
      color: "#4ecdc4"
    }
  }
]);
```

### With Custom Bounds
```typescript
const display = new BubbleDisplay(
  container, 
  bubbles,
  {
    min: { x: -5, y: -5, z: -5 },
    max: { x: 5, y: 5, z: 5 }
  }
);
```

### Dynamic Content
```typescript
const display = new BubbleDisplay(container);

// Add bubbles dynamically
display.addBubble({
  content: {
    title: "Dynamic Bubble",
    description: "Added after initialization"
  }
});
```

## Development

```bash
# Install dependencies
npm install

# Run demo
npm run dev

# Build library
npm run build:lib

# Type check
npm run type-check
```

## Browser Support

- Modern browsers with WebGL support
- Chrome 51+
- Firefox 51+
- Safari 12+
- Edge 79+

## License

MIT

## Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.