Releases: prosdevlab/experience-sdk
Releases · prosdevlab/experience-sdk
@prosdevlab/[email protected]
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:submitevent - 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 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 ChangesNone. 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
instanceIdtracking
Migration Guide: No migration needed. Simply upgrade and start using the new plugins!
Full Changelog: See Phase 2 Spec
Patch Changes
- Updated dependencies [2fc279c]
- @prosdevlab/[email protected]
@prosdevlab/[email protected]
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:submitevent - 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 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 ChangesNone. 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
instanceIdtracking
Migration Guide: No migration needed. Simply upgrade and start using the new plugins!
Full Changelog: See Phase 2 Spec
@prosdevlab/[email protected]
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.
Patch Changes
- Updated dependencies [02de640]
- @prosdevlab/[email protected]
@prosdevlab/[email protected]
Patch Changes
- Updated dependencies [df2c286]
- @prosdevlab/[email protected]
@prosdevlab/[email protected]
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.
@prosdevlab/[email protected]
Patch Changes
-
df2c286: feat(banner): add pushDown option to push content down instead of overlay
Add optional
pushDownconfig to banner plugin that allows top banners to smoothly push page content down (add margin-top) instead of overlaying it.Usage:
init({ banner: { position: "top", pushDown: "header", // CSS selector of element to push down }, });
Benefits:
- Opt-in feature (default behavior unchanged)
- Smooth transition with CSS animations
- Improves UX for sticky navigation
- Automatically removes margin when banner is dismissed
v0.1.0 - Initial Release
🎉 Initial Release
Experience SDK is now available on npm!
Features
- Multiple buttons with variants - Primary, secondary, and link button styles
- Responsive layout - Automatically adapts to mobile and desktop
- Frequency capping - Control impressions per session/day/week
- Explainability-first - Every decision includes structured reasons
- Lightweight - Only 6.9 KB gzipped
- TypeScript - Full type safety
Installation
npm install @prosdevlab/experience-sdkQuick Start
import { createInstance } from '@prosdevlab/experience-sdk';
const experiences = createInstance({ debug: true });
experiences.register('welcome', {
type: 'banner',
content: {
message: 'Welcome!',
buttons: [{ text: 'Get Started', variant: 'primary' }]
}
});
experiences.evaluate();Documentation
Known Issues
@prosdevlab/[email protected]
Patch Changes
- Updated dependencies [41c0aa5]
- @prosdevlab/[email protected]
@prosdevlab/[email protected]
Patch Changes
-
fdad132: Fix npm install error from v0.1.0. Add README and improve workflows.
v0.1.0 was published with
workspace:*dependency which doesn't work outside the monorepo. This release fixes that by letting changesets automatically convert it to the proper version range during publish.- Add: README with installation instructions and examples
- Add: READMEs for plugins package
- Fix: pnpm version conflicts in GitHub workflows
- Add: Release banner to docs homepage
@prosdevlab/[email protected]
Patch Changes
-
41c0aa5: Fix npm publishing error by adding repository field to package.json
- Add repository field required for npm provenance verification