@prosdevlab/experience-sdk-plugins 0.1.4 → 0.3.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @prosdevlab/experience-sdk-plugins@0.1.4 build /home/runner/work/experience-sdk/experience-sdk/packages/plugins
+> @prosdevlab/experience-sdk-plugins@0.3.0 build /home/runner/work/experience-sdk/experience-sdk/packages/plugins
 > tsup
 
 CLI Building entry: src/index.ts
@@ -9,9 +9,9 @@
 CLI Target: es2024
 CLI Cleaning output folder
 ESM Build start
-ESM dist/index.js     19.53 KB
-ESM dist/index.js.map 48.09 KB
-ESM ⚡️ Build success in 140ms
+ESM dist/index.js     79.10 KB
+ESM dist/index.js.map 191.96 KB
+ESM ⚡️ Build success in 304ms
 DTS Build start
-DTS ⚡️ Build success in 857ms
-DTS dist/index.d.ts 5.46 KB
+DTS ⚡️ Build success in 1228ms
+DTS dist/index.d.ts 28.79 KB

package/CHANGELOG.md

@@ -1,5 +1,155 @@
 # @prosdevlab/experience-sdk-plugins
 
+## 0.3.0
+
+### Minor Changes
+
+- 2fc279c: **Phase 2: Presentation Layer - Modal & Inline Plugins**
+
+  This release introduces two powerful new rendering plugins with built-in form support, completing the presentation layer for the Experience SDK.
+
+  ## 🎉 New Features
+
+  ### Modal Plugin
+
+  - **Rich Content Modals**: Display announcements, promotions, and interactive content
+  - **Built-in Forms**: Email capture, surveys, and feedback forms with validation
+  - **Size Variants**: Small, medium, large, and extra-large sizes
+  - **Hero Images**: Full-width images for visual impact
+  - **Responsive Design**: Mobile fullscreen mode for optimal UX
+  - **Keyboard Navigation**: Focus trap, Escape key, Tab navigation
+  - **Animations**: Smooth fade-in/fade-out transitions
+  - **Form States**: Success, error, and loading states
+  - **API Methods**: `show()`, `remove()`, `isShowing()`, `showFormState()`, `resetForm()`, `getFormData()`
+
+  ### Inline Plugin
+
+  - **DOM Insertion**: Embed content anywhere in your page
+  - **5 Insertion Methods**: `replace`, `append`, `prepend`, `before`, `after`
+  - **CSS Selector Targeting**: Use any valid selector to target elements
+  - **Dismissal with Persistence**: Users can dismiss and it persists in localStorage
+  - **No Layout Disruption**: Seamlessly integrates with existing page structure
+  - **API Methods**: `show()`, `remove()`, `isShowing()`
+
+  ### Forms (Built into Modal)
+
+  - **Field Types**: text, email, url, tel, number, textarea, select, checkbox, radio
+  - **Validation**: Required, email, URL, pattern, custom validation, min/max length
+  - **Real-time Feedback**: Validates on blur, shows errors inline
+  - **Submission Handling**: Emits `experiences:modal:form:submit` event
+  - **Success/Error States**: Built-in UI for post-submission states
+  - **Pure Functions**: Validation and rendering logic easily extractable
+
+  ## 🎨 Theming & Customization
+
+  ### CSS Variables
+
+  All plugins now support CSS variable theming:
+
+  - **Modal**: `--xp-modal-*` variables for backdrop, dialog, title, content, buttons
+  - **Forms**: `--xp-form-*` variables for inputs, labels, errors, submit button
+  - **Banner**: `--xp-banner-*` variables (refactored from inline styles)
+  - **Inline**: `--xp-inline-*` variables for custom styling
+
+  See the [Theming Guide](https://prosdevlab.github.io/experience-sdk/guides/theming) for full reference.
+
+  ## 🔧 API Improvements
+
+  ### Runtime
+
+  - **Auto-registration**: Modal and inline plugins are automatically registered
+  - **Plugin API Access**: Expose plugin APIs via singleton (`experiences.modal.show()`)
+  - **Trigger Event Handling**: Explicit listeners for each trigger type (exit intent, scroll depth, time delay)
+
+  ### Display Conditions
+
+  Seamless integration with existing display condition plugins:
+
+  - **Exit Intent + Modal**: Capture emails before users leave
+  - **Scroll Depth + Inline**: Progressive feature discovery
+  - **Time Delay + Modal**: Time-sensitive promotions
+  - **Page Visits + Banner**: Returning user messages
+
+  ## 📦 Bundle Size
+
+  - **Core SDK**: 13.4 KB gzipped (under 15 KB target ✅)
+  - **All Plugins**: ~26 KB gzipped total (smaller than competitors like Pathfora at ~47 KB)
+  - **Excellent Compression**: CSS-in-JS with CSS variables maintains small footprint
+
+  ## 🧪 Testing
+
+  - **432 tests passing** (unit, integration, browser tests)
+  - **Modal Plugin**: 56 tests for core functionality, forms, keyboard nav, accessibility
+  - **Inline Plugin**: 24 tests for DOM insertion, dismissal, persistence
+  - **Form Validation**: 35 tests for all field types and edge cases
+  - **Integration Tests**: 10 tests for plugin interactions
+  - **Exit Intent**: 21 tests with timing and sensitivity validation
+
+  ## 📚 Documentation
+
+  - **Modal Plugin Reference**: Complete API docs with examples
+  - **Inline Plugin Reference**: Full insertion method documentation
+  - **Theming Guide**: CSS variable reference with examples
+  - **Use Case Examples**: 4 complete implementation guides in playground
+
+  ## 🚀 Playground Enhancements
+
+  - **Layout Gallery Hub**: Visual directory for banner, modal, and inline layouts
+  - **Navigation System**: Breadcrumbs and sub-navigation tabs
+  - **Use Case Examples**:
+    - Exit Intent Email Capture (exit intent + modal forms)
+    - Feature Discovery Journey (scroll depth + inline + modal)
+    - Time-Delayed Promotions (time delay + hero image modal)
+    - Promotions & Announcements (banner examples)
+  - **Interactive Demos**: Live examples with SDK integration
+
+  ## ⚠️ Breaking Changes
+
+  None. This is a **minor** release with backward compatibility.
+
+  ## 🔜 Next Steps (Phase 3+)
+
+  - Browser tests for form focus management
+  - Composable form plugin (separate from modal)
+  - Additional layout plugins (tooltip, slideout, sticky bar)
+  - Multi-instance support with `instanceId` tracking
+
+  ***
+
+  **Migration Guide**: No migration needed. Simply upgrade and start using the new plugins!
+
+  **Full Changelog**: See [Phase 2 Spec](https://github.com/prosdevlab/experience-sdk/blob/main/specs/phase-2-presentation-layer/spec.md)
+
+## 0.2.0
+
+### Minor Changes
+
+- 02de640: feat: add display condition plugins with event-driven architecture
+
+  Add 4 new display condition plugins with comprehensive testing and documentation:
+
+  **New Plugins:**
+
+  - Exit Intent: Velocity-based mouse tracking with session awareness
+  - Scroll Depth: Multiple thresholds with advanced engagement metrics
+  - Page Visits: Session and lifetime counters with first-visit detection
+  - Time Delay: Millisecond-precision delays with visibility API integration
+
+  **Core Enhancements:**
+
+  - Event-driven trigger architecture (`trigger:*` events)
+  - Composable display conditions (AND/OR/NOT logic)
+  - TriggerState interface for type-safe context updates
+
+  **Developer Experience:**
+
+  - 101 new tests across 4 plugins (314 total)
+  - 12 integration tests for plugin composition
+  - Complete API documentation with examples
+  - Pure functions for easier testing
+
+  All plugins are backward compatible and work independently or together.
+
 ## 0.1.4
 
 ### Patch Changes

package/README.md

@@ -2,100 +2,90 @@
 
 Official plugins for [Experience SDK](https://github.com/prosdevlab/experience-sdk).
 
-**Size:** 13.4 KB (ESM)
+**Size:** 12.7 KB gzipped (all plugins)
 
 ## Included Plugins
 
-### Banner Plugin
+### Layout Plugins
 
-Renders banner experiences in the DOM with automatic positioning, theming, and responsive layout.
+**Banner Plugin** - Top/bottom notification bars with push-down support
 
 **Features:**
 - Multiple buttons with variants (primary, secondary, link)
 - Responsive layout (desktop inline, mobile stack)
-- Automatic theme detection (light/dark mode)
-- Top/bottom positioning
-- Dismissable with close button
-- **CSS customization** via `className` and `style` props
-- Stable `.xp-*` CSS classes for styling
+- Top/bottom positioning with optional push-down
+- HTML sanitization for XSS protection
+- CSS variables for full theming
 
-```typescript
-import { createInstance, bannerPlugin } from '@prosdevlab/experience-sdk-plugins';
-
-const sdk = createInstance();
-sdk.use(bannerPlugin);
+**Modal Plugin** - Overlay dialogs with forms and rich content
 
-sdk.banner.show({
-  id: 'welcome',
-  type: 'banner',
-  content: {
-    title: 'Welcome!',
-    message: 'Thanks for visiting.',
-    buttons: [
-      { text: 'Get Started', url: '/start', variant: 'primary' }
-    ],
-    position: 'top',
-    dismissable: true
-  }
-});
-```
+**Features:**
+- Multiple sizes (sm, md, lg, fullscreen, auto)
+- Mobile fullscreen for large modals
+- Hero images with max height
+- Animations (fade, slide-up, none)
+- Built-in form support with validation
+- Focus trap and keyboard support (Escape)
+- CSS variables for full theming
 
-**Customization:**
+**Inline Plugin** - In-content experiences using CSS selectors
 
-The banner plugin uses `.xp-*` CSS classes and supports custom styling:
+**Features:**
+- 5 insertion methods (replace, append, prepend, before, after)
+- Dismissal with persistence
+- Multi-instance support
+- HTML sanitization
+- Custom styling (className, style props)
+- CSS variables for theming
 
-```typescript
-// With Tailwind
-content: {
-  message: 'Flash Sale!',
-  className: 'bg-gradient-to-r from-blue-600 to-purple-600 text-white',
-  buttons: [{
-    text: 'Shop Now',
-    className: 'bg-white text-blue-600 hover:bg-gray-100'
-  }]
-}
-
-// With inline styles
-content: {
-  message: 'Flash Sale!',
-  style: {
-    background: 'linear-gradient(90deg, #667eea 0%, #764ba2 100%)',
-    color: 'white'
-  }
-}
-```
+### Display Condition Plugins
 
-See the [Plugins documentation](https://prosdevlab.github.io/experience-sdk/reference/plugins#customization) for more customization examples.
+**Exit Intent Plugin** - Detect when users are leaving
 
-### Frequency Plugin
+**Features:**
+- Mouse movement tracking
+- Configurable sensitivity
+- Min time on page
+- Delay before triggering
+- Session persistence
 
-Manages impression tracking and frequency capping with persistent storage.
+**Scroll Depth Plugin** - Track scroll engagement
 
 **Features:**
-- Session/day/week impression tracking
-- Automatic storage management
-- Manual impression recording
-- Reset capabilities
+- Multiple thresholds (25%, 50%, 75%, 100%)
+- Max scroll tracking
+- Velocity and direction tracking
+- Time-to-threshold metrics
+- Throttling and resize handling
 
-```typescript
-import { createInstance, frequencyPlugin } from '@prosdevlab/experience-sdk-plugins';
+**Page Visits Plugin** - Session and lifetime counters
 
-const sdk = createInstance();
-sdk.use(frequencyPlugin);
+**Features:**
+- Session-scoped visits (sessionStorage)
+- Lifetime visits (localStorage)
+- First-visit detection
+- DNT (Do Not Track) support
+- Expiration and cross-tab safety
 
-// Check impression count
-const count = sdk.frequency.getImpressionCount('welcome', 'session');
+**Time Delay Plugin** - Show after time elapsed
 
-// Record impression
-sdk.frequency.recordImpression('welcome');
+**Features:**
+- Configurable show delay
+- Auto-hide after duration
+- Pause when page hidden (Page Visibility API)
+- Timer management
 
-// Reset counts
-sdk.frequency.reset('welcome');
-```
+### Utility Plugins
 
-### Debug Plugin
+**Frequency Plugin** - Impression tracking and capping
 
-Provides console logging and window event emission for debugging and Chrome extension integration.
+**Features:**
+- Session/day/week impression tracking
+- Automatic storage management
+- Manual impression recording
+- Reset capabilities
+
+**Debug Plugin** - Logging and window events
 
 **Features:**
 - Console logging with prefix
@@ -103,18 +93,87 @@ Provides console logging and window event emission for debugging and Chrome exte
 - Automatic decision logging
 - Configurable logging levels
 
+## Quick Examples
+
+### Banner
+
 ```typescript
-import { createInstance, debugPlugin } from '@prosdevlab/experience-sdk-plugins';
+import { createInstance, bannerPlugin } from '@prosdevlab/experience-sdk-plugins';
 
-const sdk = createInstance({ debug: true });
-sdk.use(debugPlugin);
+const sdk = createInstance();
+sdk.use(bannerPlugin);
 
-// Manual logging
-sdk.debug.log('Custom message', { foo: 'bar' });
+sdk.banner.show({
+  id: 'welcome',
+  type: 'banner',
+  content: {
+    message: 'Welcome! Get 20% off today.',
+    buttons: [
+      { text: 'Shop Now', url: '/shop', variant: 'primary' }
+    ],
+    position: 'top'
+  }
+});
+```
 
-// Listen to debug events
-window.addEventListener('experiences:debug', (event) => {
-  console.log(event.detail);
+### Modal with Form
+
+```typescript
+sdk.modal.show({
+  id: 'newsletter',
+  type: 'modal',
+  content: {
+    title: 'Stay Updated',
+    message: 'Subscribe for exclusive offers.',
+    size: 'sm',
+    form: {
+      fields: [
+        { name: 'email', type: 'email', required: true }
+      ],
+      submitButton: { text: 'Subscribe', variant: 'primary' },
+      successState: { 
+        title: '✓ Subscribed!',
+        message: 'Check your inbox.'
+      }
+    }
+  }
+});
+```
+
+### Inline Experience
+
+```typescript
+sdk.inline.show({
+  id: 'promo',
+  type: 'inline',
+  content: {
+    selector: '#sidebar',
+    position: 'prepend',
+    message: '<p><strong>Special Offer!</strong> Get 20% off with SAVE20.</p>',
+    buttons: [
+      { text: 'Shop Now', url: '/shop', variant: 'primary' }
+    ],
+    dismissable: true,
+    persist: true
+  }
+});
+```
+
+### Exit Intent
+
+```typescript
+// Trigger modal on exit intent
+sdk.on('trigger:exitIntent', () => {
+  sdk.modal.show({
+    id: 'exit-offer',
+    content: {
+      title: 'Wait! Before You Go...',
+      message: 'Get 15% off your first order.',
+      buttons: [
+        { text: 'Claim Discount', variant: 'primary', url: '/checkout?code=EXIT15' }
+      ]
+    }
+  });
 });
 ```
 
@@ -145,8 +204,11 @@ experiences.register('banner', { ... });
 ## Documentation
 
 - [Full Documentation](https://prosdevlab.github.io/experience-sdk)
-- [Plugins Guide](https://prosdevlab.github.io/experience-sdk/reference/plugins)
-- [Banner Examples](https://prosdevlab.github.io/experience-sdk/demo/banner)
+- [Banner Plugin](https://prosdevlab.github.io/experience-sdk/reference/plugins/banner)
+- [Modal Plugin](https://prosdevlab.github.io/experience-sdk/reference/plugins/modal)
+- [Inline Plugin](https://prosdevlab.github.io/experience-sdk/reference/plugins/inline)
+- [Display Conditions](https://prosdevlab.github.io/experience-sdk/reference/plugins/exit-intent)
+- [All Plugins](https://prosdevlab.github.io/experience-sdk/reference/plugins)
 
 ## License