# Storyfyd Web Component API

## 🚀 Quick Start

The easiest way to integrate Storyfyd into your website using Web Components.

### Installation

```html
<!-- Load the SDK -->
<script src="https://cdn.storyfyd.com/sdk/storyfyd-web.js"></script>
```

### Basic Usage

```html
<!-- Add the widget element -->
<storyfyd-web></storyfyd-web>

<script>
  const storyfydWeb = document.querySelector('storyfyd-web');
  storyfydWeb.init({
    token: 'YOUR_TOKEN_HERE'
  });
</script>
```

That's it! Your stories widget is now live. 🎉

## 📖 API Reference

### Element

```html
<storyfyd-web id="my-stories"></storyfyd-web>
```

The `<storyfyd-web>` custom element automatically creates a container for the story circles.

### Methods

#### `init(config)`

Initialize the widget with configuration options.

**Parameters:**
- `config` (Object) - Configuration object

**Required Config Options:**
- `token` (string) - Your Storyfyd API token

**Optional Config Options:**
- `layout` (Object) - Layout configuration
  - `view` (string) - View style: 'classic' or 'rounded' (default: 'classic')
  - `style` (Object) - Custom styles
    - `width` (string) - Circle width (default: '80px')
    - `height` (string) - Circle height (default: '80px')
    - `titleColor` (string) - Title color

**Callback Options:**
- `onReady` (function) - Called when widget is ready
- `onStoryOpen` (function) - Called when a story opens
- `onStoryClosed` (function) - Called when a story closes
- `onStoryChanged` (function) - Called when story changes
- `onInteraction` (function) - Called on user interaction
- `onError` (function) - Called on error

**Example:**
```javascript
const storyfydWeb = document.querySelector('storyfyd-web');
storyfydWeb.init({
  token: 'YOUR_TOKEN',
  layout: {
    view: 'classic',
    style: {
      width: '100px',
      height: '100px',
      titleColor: '#333'
    }
  },
  onReady: () => console.log('Widget ready!'),
  onStoryOpen: (data) => console.log('Story opened:', data),
  onStoryClosed: () => console.log('Story closed'),
  onStoryChanged: (data) => console.log('Story changed:', data),
  onInteraction: (data) => console.log('User interaction:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### `destroy()`

Destroy the widget and clean up resources.

**Example:**
```javascript
const storyfydWeb = document.querySelector('storyfyd-web');
storyfydWeb.destroy();
```

## 📝 Complete Example

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My Stories</title>
</head>
<body>
    <h1>My Stories Widget</h1>
    
    <!-- Widget container -->
    <storyfyd-web id="my-stories"></storyfyd-web>

    <!-- Load SDK -->
    <script src="https://cdn.storyfyd.com/sdk/storyfyd-web.js"></script>

    <!-- Initialize -->
    <script>
        const storyfydWeb = document.querySelector('#my-stories');
        storyfydWeb.init({
            token: 'YOUR_TOKEN_HERE',
            onReady: () => {
                console.log('Stories loaded successfully!');
            }
        });
    </script>
</body>
</html>
```

## 🎨 Styling

The widget automatically adapts to its container. You can control the layout using the `layout` config option:

```javascript
storyfydWeb.init({
  token: 'YOUR_TOKEN',
  layout: {
    view: 'rounded',        // 'classic' or 'rounded'
    style: {
      width: '120px',       // Circle size
      height: '120px',
      titleColor: '#2c3e50' // Title text color
    }
  }
});
```

## 🔄 Lifecycle

The widget automatically cleans up when the element is removed from the DOM.

```javascript
// Manual cleanup
const storyfydWeb = document.querySelector('storyfyd-web');
storyfydWeb.destroy();

// Or remove from DOM (automatic cleanup)
storyfydWeb.remove();
```

## 🆚 Comparison with Legacy API

### Old Way (Legacy)
```javascript
const loader = new StoryfydLoader();
loader.init({
  token: 'YOUR_TOKEN',
  container: '#storyfyd-widget',
  // ... config
});
```

### New Way (Web Component) ✨
```javascript
// In HTML: <storyfyd-web></storyfyd-web>

const storyfydWeb = document.querySelector('storyfyd-web');
storyfydWeb.init({
  token: 'YOUR_TOKEN'
  // ... config (no container needed!)
});
```

## 💡 Benefits

- ✅ **Simpler** - No need to specify container, the element IS the container
- ✅ **Cleaner HTML** - Custom element instead of generic div
- ✅ **Auto cleanup** - Widget destroys itself when element is removed
- ✅ **Modern** - Uses Web Components standard
- ✅ **Backward compatible** - Legacy API still works

## 📦 Events & Callbacks

### onReady
Fired when the widget is initialized and ready to display stories.

```javascript
onReady: () => {
  console.log('Widget is ready!');
}
```

### onStoryOpen
Fired when a story is opened.

```javascript
onStoryOpen: (data) => {
  console.log('Story opened:', data);
  // data contains: groupIndex, storyIndex, group, story
}
```

### onStoryClosed
Fired when the story viewer is closed.

```javascript
onStoryClosed: () => {
  console.log('Story viewer closed');
}
```

### onStoryChanged
Fired when navigating between stories.

```javascript
onStoryChanged: (data) => {
  console.log('Story changed:', data);
  // data contains: groupIndex, storyIndex, story
}
```

### onInteraction
Fired when user interacts with story elements (buttons, swipe-ups, etc).

```javascript
onInteraction: (data) => {
  console.log('User interaction:', data);
  // data contains interaction details
}
```

### onError
Fired when an error occurs.

```javascript
onError: (error) => {
  console.error('Error occurred:', error);
}
```

## 🔐 Getting Your Token

To get your API token:
1. Log in to your Storyfyd dashboard
2. Go to Settings → API Keys
3. Copy your token
4. Use it in the `init()` method

## 🌐 Browser Support

Works in all modern browsers that support:
- Web Components (Custom Elements)
- ES6+ JavaScript
- postMessage API

## 📞 Support

Need help? Contact us at:
- Email: support@storyfyd.com
- Docs: https://docs.storyfyd.com
- Issues: https://github.com/storyfyd/sdk-js/issues