npm package: @gamaroff/ionic-wizard-bubbles
Description: A wizard bubble plugin for Ionic applications
Author: Lorien Gamaroff
Latest version: 2.0.5

# @gamaroff/ionic-wizard-bubbles

A wizard bubble plugin for Ionic applications that helps guide users through your app's features.

## Features

- 🎯 Highlight specific elements on the page
- 💬 Show informative bubbles with custom text
- 🎨 Fully customizable themes
- 📱 Cross-platform support (Web, iOS*, Android WebView)
- 🔄 Step-by-step navigation
- 🎉 Optional icons for each step
- 📱 Smart positioning for mobile screens
- 🔍 Debug mode for troubleshooting

*Note: iOS native implementation is currently a stub. Web implementation works in iOS WebView.

## Installation

```bash
npm install @gamaroff/ionic-wizard-bubbles
```

## Platform Setup

### Web
No additional setup required. The plugin works out of the box.

### Android (WebView)
The plugin works in Android's WebView environment. For optimal performance:

1. Add the viewport meta tag to your `index.html`:
```html
<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover">
```

2. Use `ngAfterViewInit` for initialization in your Angular component:
```typescript
import { Component, AfterViewInit } from '@angular/core';
import { WizardBubble } from '@gamaroff/ionic-wizard-bubbles';

@Component({
  selector: 'app-home',
  template: `
    <ion-content>
      <div id="feature1">Feature 1</div>
      <div id="feature2">Feature 2</div>
    </ion-content>
  `
})
export class HomePage implements AfterViewInit {
  ngAfterViewInit() {
    // Wait for the view to be fully rendered
    setTimeout(() => {
      WizardBubble.show({
        steps: [
          {
            targetId: 'feature1',
            text: 'This is an amazing feature!',
            icon: '🚀'
          },
          {
            targetId: 'feature2',
            text: 'And here is another cool thing!'
          }
        ],
        buttonText: {
          next: 'Continue',
          finish: 'Got it!'
        },
        theme: {
          backgroundColor: '#ffffff',
          textColor: '#333333',
          buttonColor: '#007bff',
          buttonTextColor: '#ffffff',
          highlightColor: '#007bff',
          borderRadius: '12px'
        }
      });
    }, 1000);
  }
}
```

### iOS (WebView)
Same setup as Android - the web implementation works in iOS WebView.

## Debugging in Android WebView

To view debug logs and troubleshoot issues:

1. Connect your Android device to your computer
2. Open Chrome on your computer
3. Navigate to `chrome://inspect/#devices`
4. Find your app in the list and click "inspect"
5. Check the console for detailed logs about element positioning and visibility

## API Reference

### WizardBubbleOptions Interface

```typescript
interface WizardBubbleOptions {
  steps: WizardBubbleStep[];
  buttonText?: {
    next?: string;
    finish?: string;
  };
  theme?: {
    backgroundColor?: string;
    textColor?: string;
    buttonColor?: string;
    buttonTextColor?: string;
    highlightColor?: string;
    borderRadius?: string;
  };
}

interface WizardBubbleStep {
  targetId: string;
  text: string;
  icon?: string;  // Emoji or text icon
}
```

### Methods

#### show(options: WizardBubbleOptions): Promise<void>
Shows the wizard bubble with the specified options. Features include:
- Smart positioning that adjusts based on screen space
- Automatic repositioning for scrolled content
- Touch-optimized for mobile devices
- High z-index to ensure visibility in WebViews

#### next(): Promise<{ isFinished: boolean }>
Advances to the next step. Returns an object with `isFinished` indicating whether the wizard has completed.

#### hide(): Promise<void>
Manually hides the wizard bubble.

## Platform Support

| Feature | Web | iOS WebView | Android WebView | iOS Native | Android Native |
|---------|-----|-------------|----------------|------------|----------------|
| Show Bubble | ✅ | ✅ | ✅ | ⚠️ | ⚠️ |
| Hide Bubble | ✅ | ✅ | ✅ | ⚠️ | ⚠️ |
| Navigation | ✅ | ✅ | ✅ | ⚠️ | ⚠️ |
| Theming | ✅ | ✅ | ✅ | ⚠️ | ⚠️ |
| Element Highlighting | ✅ | ✅ | ✅ | ⚠️ | ⚠️ |
| Smart Positioning | ✅ | ✅ | ✅ | ⚠️ | ⚠️ |

✅ = Fully supported
⚠️ = Stub implementation (no visual elements)

## Troubleshooting

### Bubble Not Visible
1. Check element IDs match exactly
2. Ensure the view is fully rendered (use setTimeout)
3. Verify z-index conflicts with other elements
4. Check Chrome DevTools for error messages
5. Ensure the target element is in the viewport

### Positioning Issues
1. Verify viewport meta tag is present
2. Check if target element is properly positioned
3. Ensure no CSS transforms affecting positioning
4. Check Chrome DevTools console for positioning logs

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT