npm package: @rorycombe/toaster
Description: A toaster web component
Author: Rory Combe
Latest version: 0.0.4

# Toaster

A beautiful, animated toast notification web component inspired by Sonner. Features a card-stacking effect with depth, smooth animations, and intelligent hover interactions.

## Features

- 🎨 **Beautiful animations** - Smooth slide-in animations and card stacking effects
- 📚 **Card stacking** - Toasts stack on top of each other with a depth effect
- 🎯 **Hover interactions** - Hover to pause timers and expand the full stack
- ⏱️ **Auto-hide** - Toasts automatically hide after 5 seconds
- 🎭 **Multiple types** - Support for success, error, warning, and info toasts
- 🎪 **Depth effect** - Cards at the back are narrower and centered for a 3D effect
- 📱 **Web Component** - Works with any framework or vanilla JavaScript

## Installation

```bash
npm install @rorycombe/toaster
```

## Quick Start

### HTML

```html
<!DOCTYPE html>
<html>
<head>
  <script type="module" src="node_modules/@rorycombe/toaster/dist/index.mjs"></script>
</head>
<body>
  <rc-toaster></rc-toaster>
  
  <script>
    const toaster = document.querySelector('rc-toaster');
    toaster.toast('Hello, world!', 'success');
  </script>
</body>
</html>
```

### JavaScript/TypeScript

```javascript
import '@rorycombe/toaster';

const toaster = document.querySelector('rc-toaster');
toaster.toast('Operation completed successfully!', 'success');
```

### React

```jsx
import { useEffect } from 'react';
import '@rorycombe/toaster';

function App() {
  useEffect(() => {
    const toaster = document.querySelector('rc-toaster');
    if (!toaster) {
      const element = document.createElement('rc-toaster');
      document.body.appendChild(element);
    }
  }, []);

  const showToast = (message, type) => {
    const toaster = document.querySelector('rc-toaster');
    toaster.toast(message, type);
  };

  return (
    <div>
      <button onClick={() => showToast('Success!', 'success')}>
        Show Success
      </button>
    </div>
  );
}
```

## API

### Methods

#### `toast(message: string, type?: 'success' | 'error' | 'warning' | 'info'): void`

Displays a toast notification.

**Parameters:**
- `message` (string, required) - The message to display
- `type` (string, optional) - The toast type. Defaults to `'success'`

**Toast Types:**
- `'success'` - Green background (default)
- `'error'` - Red background
- `'warning'` - Yellow background
- `'info'` - Blue background

**Example:**
```javascript
const toaster = document.querySelector('rc-toaster');

// Success toast (default)
toaster.toast('Operation completed!');

// Error toast
toaster.toast('Something went wrong!', 'error');

// Warning toast
toaster.toast('Please check your input', 'warning');

// Info toast
toaster.toast('Here is some information', 'info');
```

## Behavior

### Card Stacking

- New toasts appear at the front of the stack
- Up to 3 toasts are visible when not hovered
- Cards further back are narrower and slightly scaled down for depth
- Cards are centered relative to the front card for a 3D effect

### Auto-Hide

- Toasts automatically hide after 5 seconds
- Timers pause when hovering over the toast area
- Timers resume when you stop hovering
- Hidden toasts can still be viewed when hovering over the stack

### Hover Interactions

- **Hovering** over any toast or the container:
  - Pauses all hide timers
  - Expands the stack to show all toasts
  - Cards space out evenly for readability
  
- **Moving away** from the toast area:
  - Resumes timers with remaining time
  - Collapses the stack back to stacked view

### Animations

- **Slide-in**: New toasts slide in from the right
- **Slide-down**: Toasts slide down when hiding
- **Stack shuffle**: Existing toasts smoothly move back when new ones appear
- **Expand/Collapse**: Smooth transitions when hovering

## Styling

The toaster is positioned fixed at the bottom-right of the viewport. You can customize the position using CSS:

```css
rc-toaster {
  bottom: 20px;
  right: 20px;
}
```

Toast colors can be customized by targeting the shadow DOM:

```css
rc-toaster::part(toast-success) {
  background-color: your-color;
}
```

## Examples

### Multiple Toasts

```javascript
const toaster = document.querySelector('rc-toaster');

// Show multiple toasts in sequence
['First', 'Second', 'Third'].forEach((msg, i) => {
  setTimeout(() => {
    toaster.toast(msg, ['success', 'error', 'warning'][i]);
  }, i * 500);
});
```

### Error Handling

```javascript
try {
  await someAsyncOperation();
  toaster.toast('Operation successful!', 'success');
} catch (error) {
  toaster.toast(`Error: ${error.message}`, 'error');
}
```

## Browser Support

- Chrome/Edge (latest)
- Firefox (latest)
- Safari (latest)
- Any browser that supports Web Components and Shadow DOM

## License

MIT

## Author

Rory Combe