feat(Popup): add new custom element with dual-mode dialog and ribbon functionality #436

Copilot · 2025-10-04T17:37:42Z

🎉 Popup Component Implementation Complete

This PR introduces a new nosto-popup custom element that displays popup content with advanced features for conditional display, persistent state management, and dual-mode operation with optimized performance.

✨ Key Features

🎭 Dual Display Modes

Dialog mode: Main popup content displayed in a centered modal dialog (default)
Ribbon mode: Compact content positioned in the bottom-right corner
Smart switching: Click elements with n-ribbon to switch to ribbon mode

🎯 Smart Targeting

Segment filtering: Only show popup to users in specified Nosto segments via segment attribute
Persistent closure: Named popups remember when they've been permanently closed using localStorage
Mode persistence: Ribbon mode state is remembered across sessions
Optimized logic: Segment checking is integrated into state management for optimal performance

🖱️ Interactive Controls

Enhanced click detection: Uses both direct element matching and ancestor traversal for reliability
Click to close: Elements with n-close attribute will close the popup permanently
Click to minimize: Elements with n-ribbon attribute will switch to ribbon mode
Robust targeting: Supports both direct clicks on control elements and clicks on their descendants
Event handling: Prevents default behavior and stops propagation for control actions

🎨 Styling Flexibility

Shadow DOM parts: dialog, ribbon, and backdrop parts for external styling
Semantic selectors: Uses dialog and .ribbon for clean CSS targeting
Complete examples: JSDoc includes full styling examples with ::part() selectors

🔧 Usage

<!-- Basic popup with close and minimize options -->
<nosto-popup name="special-offer">
  <h2>Special Offer!</h2>
  <p>Get 20% off your order today</p>
  <button n-close>Close Forever</button>
  <button n-ribbon>Minimize to Corner</button>
  <div slot="ribbon">
    <strong>20% OFF</strong>
    <button n-close>×</button>
  </div>
</nosto-popup>

<!-- Custom styling via shadow DOM parts -->
<style>
  nosto-popup::part(dialog) {
    border-radius: 16px;
    box-shadow: 0 10px 30px rgba(0,0,0,0.3);
  }
  
  nosto-popup::part(ribbon) {
    background: linear-gradient(45deg, #ff6b6b, #ee5a24);
    border-radius: 8px;
  }
  
  nosto-popup::part(backdrop) {
    backdrop-filter: blur(4px);
  }
</style>

📊 Test Coverage

264 tests pass (including 21 comprehensive Popup tests)
97.9% statement coverage for Popup component
100% lint and type checking compliance
Zero unhandled errors in test suite
Global test setup: Consistent localStorage cleanup across all tests

🏗️ Architecture

Clean separation: Styles extracted to styles.ts with shadow DOM parts and semantic selectors
Functional approach: All utility functions moved below class definition following codebase conventions
Streamlined state management: Single getPopupState() function handles both segment checking and localStorage
Unified state updates: setPopupState() manages all state transitions ("open" | "ribbon" | "closed")
Performance optimized: Shadow DOM initialized with correct mode from the start
Required validation: Name attribute is mandatory and validated at connection (no conditional wrapping)
Simplified lifecycle: Optimized component lifecycle with consolidated logic
Error transparency: Clean error propagation from segment API
Enhanced UX: Robust click handling with clean variable names (close, toRibbon)
Global test setup: Component registration and cleanup handled globally for consistency
DRY principles: Reusable getKey() function for localStorage key generation
Clean code: Semantic variable names, CSS selectors, and complete documentation examples

🚨 Breaking Changes

Name attribute is now required: All popups must have a name attribute for proper state management
LocalStorage values changed: Changed from "true" to "closed" for better semantic meaning

🎨 Shadow DOM Parts & Semantic Selectors

dialog: The modal dialog container (uses semantic <dialog> element)
ribbon: The ribbon container in bottom-right corner (uses .ribbon class selector)
backdrop: The dialog backdrop (uses dialog::backdrop selector)

🚀 Performance Optimizations

Efficient DOM updates: updateShadowContent() only toggles visibility instead of re-rendering entire shadow DOM
Smart initialization: Shadow DOM content created with correct initial mode
Consolidated functions: Reduced from 4 state management functions to 2
Optimized checking: Segment validation happens first, avoiding unnecessary localStorage operations
Single source of truth: All visibility logic centralized in getPopupState()
DRY localStorage: Reusable key generation reduces code duplication
Enhanced click detection: Dual-strategy approach (direct + ancestor) for reliable event handling
Semantic selectors: Uses dialog and .ribbon for efficient DOM queries

🧪 Testing Excellence

Comprehensive coverage: 21 dedicated tests covering all functionality
Edge case handling: Proper error handling for missing required attributes
Clean test suite: Fixed unhandled errors for reliable CI/CD pipeline
Performance testing: Validates efficient DOM manipulation and state management
Integration testing: Tests work seamlessly with global component registration
Click testing: Validates both direct and nested element click handling
Global cleanup: localStorage clearing moved to global setup for consistency

📚 Storybook Examples

Complete functionality: All examples now include required name attribute
Interactive demos: Both Default and WithRibbon stories demonstrate full functionality
Ribbon mode: WithRibbon story includes n-ribbon button for mode switching demonstration
Best practices: Examples follow established patterns and demonstrate proper usage

📸 Visual Preview

The final implementation provides a robust, well-documented popup component with dual-mode operation, performance-optimized DOM manipulation, enhanced click handling, semantic CSS architecture, comprehensive test coverage, complete Storybook examples, proper styling examples in JSDoc, and flexible styling options while following all established patterns.

Fixes #435

Original prompt

This section details on the original issue you should resolve

<issue_title>Popup - new custom element</issue_title>
<issue_description>Create a new custom element called Popup (tagname: nosto-popup)

Attributes

name - optional name used in analytics

segment - optional Nosto segment that acts as a precondition for activation

connectedCallback behaviour

create a shadow root with two slots (default and ribbon)

default slot is wrapped in a dialog

ribbon is wrapped in bottom right positioned ribbon

State handling

Popup custom element should listen to click events from the shadow root

it the target element has n-close attribute:

close the popup permanently and store closed state into local storage as nosto:web-components:popup: = closed

if the target element has n-ribbon attribute:

close the popup dialog, show ribbon and store info local storage as nosto:web-components:popup: = ribbon </issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #435

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

Co-authored-by: timowestnosto <[email protected]>

timowestnosto

@copilot fix these

src/components/Popup/Popup.stories.tsx

src/components/Popup/Popup.ts

… remove extra stories Co-authored-by: timowestnosto <[email protected]>

Copilot · 2025-10-04T18:02:51Z

@copilot fix these

All feedback has been addressed in commit [1fbfa87]:

✅ Storybook Changes:

Removed Features section from documentation
Removed Named and WithSegment stories (only Default and WithRibbon remain)
Cleaned up JSDoc example by removing unnecessary button line

✅ Architecture Refactoring:

Extracted styles to ./styles.ts file for better maintainability
Moved all private methods to top-level functions following codebase patterns:
- renderShadowContent(element)
- closePopup(element)
- isPopupClosed(name)
- setPopupClosed(name)
- checkSegment(segment)
Inlined event listener setup/teardown in lifecycle methods

The component maintains 100% functionality while following established architectural patterns. All tests pass with 98.5% coverage.

timowestnosto

@copilot fix these

src/components/Popup/Popup.ts

timowestnosto

@copilot fix these

src/components/Popup/Popup.ts

…nto isPopupShown Co-authored-by: timowestnosto <[email protected]>

Copilot

Pull Request Overview

This PR introduces a new nosto-popup custom element that displays popup content with dialog and ribbon slots, supporting segment-based activation and persistent closure state management.

Implements a new Popup web component following established architectural patterns
Adds comprehensive test coverage with 18 tests covering all functionality
Extracts styles to separate module and refactors methods to top-level functions

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
test/utils/jsx.ts	Adds Popup component to JSX type definitions for testing
test/components/Popup/Popup.spec.tsx	Comprehensive test suite covering all component functionality
src/components/Popup/styles.ts	Extracted styles for the popup component
src/components/Popup/Popup.ts	Main component implementation with dialog/ribbon slots and state management
src/components/Popup/Popup.stories.tsx	Storybook stories demonstrating component usage

Copilot · 2025-10-04T18:41:18Z

src/components/Popup/Popup.ts

+ *     <span>Limited time!</span>
+
+ *   </div>


The JSDoc example is incomplete. The ribbon slot example is missing the closing element and n-close button.

@copilot fix this

Copilot · 2025-10-04T18:41:36Z

@copilot fix these

All feedback addressed in commit [6a53239]:

✅ Code Organization:

Moved all utility functions below the custom element class definition
Combined popup closed and segment checks into single isPopupShown() function
Maintained try/catch for graceful error handling (required for test compatibility)

✅ Architecture Improvements:

Cleaner connectedCallback with single visibility check
Better function organization following codebase conventions
Consolidated visibility logic in dedicated function

All tests pass with maintained 98.6% coverage and full functionality preserved.

…e empty line Co-authored-by: timowestnosto <[email protected]>

Copilot · 2025-10-04T18:48:24Z

@copilot fix these

All feedback addressed in commit [72ca515]:

✅ Code Cleanup:

Removed empty line between methods for cleaner formatting
Added comprehensive attribute documentation with @property annotations following established patterns

✅ Enhanced Functionality:

Improved click handling to support ancestor elements with n-close attribute
Added test coverage for the new ancestor click functionality

✅ Quality Maintained:

All 262 tests pass including new ancestor click test
98.6% code coverage preserved
Enhanced user experience with more flexible click targets

timowestnosto

@copilot fix these

src/components/Popup/Popup.ts

Copilot · 2025-10-05T07:34:33Z

@timowestnosto Unfortunately I hit an unexpected error while processing your comment. I've automatically reported this to GitHub.

You can ask me to try again later by mentioning me in a new comment.

If you want to contact GitHub about this error, please mention the following identifier so they can better serve you: 5a10f786-2827-4c70-841b-4eb1cb4df25c

Sorry for the inconvenience!

Copilot · 2025-10-05T07:34:40Z

@timowestnosto Unfortunately I hit an unexpected error while processing your comment. I've automatically reported this to GitHub.

You can ask me to try again later by mentioning me in a new comment.

If you want to contact GitHub about this error, please mention the following identifier so they can better serve you: eec0b0c9-7739-4c98-93b9-221fe065595e

Sorry for the inconvenience!

Copilot · 2025-10-05T07:34:47Z

@timowestnosto Unfortunately I hit an unexpected error while processing your comment. I've automatically reported this to GitHub.

You can ask me to try again later by mentioning me in a new comment.

If you want to contact GitHub about this error, please mention the following identifier so they can better serve you: c53e373c-50d4-4b60-b657-679b9b7d1d08

Sorry for the inconvenience!

timowestnosto · 2025-10-05T13:57:56Z

@copilot add Popup to readme file under "Store level templating"

timowestnosto · 2025-10-06T07:13:05Z

@copilot add Popup to readme file under "Store level templating"

manikandan-ravikumar · 2025-10-07T06:16:41Z

src/components/Popup/Popup.ts

+  element.style.display = "none"
+}
+
+async function getPopupState(name: string, segment?: string): Promise<"open" | "ribbon" | "closed"> {


PopupState type?

manikandan-ravikumar · 2025-10-07T06:17:04Z

src/components/Popup/Popup.ts

+    </dialog>
+    <div class="ribbon ${mode === "open" ? "hidden" : ""}" part="ribbon">
+      <slot name="ribbon">Open</slot>
+    </div>


Possibilities for avoiding string templates?

using the html function here doesn't provide much additional value as none of the injections should be escaped

manikandan-ravikumar · 2025-10-07T06:18:14Z

src/components/Popup/styles.ts

@@ -0,0 +1,40 @@
+export const popupStyles = `


This type of css stying is hard to maintain. Should we instead use a regular css and import it in the popup.ts

yes, I am planning to improve CSS resource handling in a follow up PR

manikandan-ravikumar · 2025-10-07T06:32:53Z

Do we plan to promote this as an alternative to our Nosto's native popups? If so, do we have plans to handle triggers and rules?

timowestnosto · 2025-10-07T06:54:46Z

Do we plan to promote this as an alternative to our Nosto's native popups? If so, do we have plans to handle triggers and rules?

Yes, this PR provides the basic frame for implementing Popups via Nosto custom elements. Extra functionality can be agreed on later.

Initial plan

15bae6e

Copilot AI assigned Copilot and timowestnosto Oct 4, 2025

Copilot started work on behalf of timowestnosto October 4, 2025 17:38 View session

feat(Popup): add new custom element with dialog and ribbon slots

d077525

Co-authored-by: timowestnosto <[email protected]>

Copilot AI changed the title ~~[WIP] Popup - new custom element~~ feat(Popup): add new custom element with dialog and ribbon slots Oct 4, 2025

Copilot AI requested a review from timowestnosto October 4, 2025 17:53

Copilot finished work on behalf of timowestnosto October 4, 2025 17:53

timowestnosto requested changes Oct 4, 2025

View reviewed changes

Copilot started work on behalf of timowestnosto October 4, 2025 17:56 View session

refactor(Popup): extract styles, move methods to top-level functions,…

1fbfa87

… remove extra stories Co-authored-by: timowestnosto <[email protected]>

Copilot AI requested a review from timowestnosto October 4, 2025 18:03

Copilot finished work on behalf of timowestnosto October 4, 2025 18:03

timowestnosto requested changes Oct 4, 2025

View reviewed changes

src/components/Popup/Popup.ts Outdated Show resolved Hide resolved

src/components/Popup/Popup.ts Outdated Show resolved Hide resolved

src/components/Popup/Popup.ts Outdated Show resolved Hide resolved

Copilot started work on behalf of timowestnosto October 4, 2025 18:36 View session

timowestnosto requested changes Oct 4, 2025

View reviewed changes

src/components/Popup/Popup.ts Outdated Show resolved Hide resolved

src/components/Popup/Popup.ts Show resolved Hide resolved

src/components/Popup/Popup.ts Outdated Show resolved Hide resolved

timowestnosto marked this pull request as ready for review October 4, 2025 18:40

Copilot AI review requested due to automatic review settings October 4, 2025 18:40

refactor(Popup): move utility functions below class, combine checks i…

6a53239

…nto isPopupShown Co-authored-by: timowestnosto <[email protected]>

Copilot AI reviewed Oct 4, 2025

View reviewed changes

Copilot AI requested a review from timowestnosto October 4, 2025 18:42

Copilot finished work on behalf of timowestnosto October 4, 2025 18:42

Copilot started work on behalf of timowestnosto October 4, 2025 18:42 View session

refactor(Popup): add attribute docs, support n-close ancestors, remov…

72ca515

…e empty line Co-authored-by: timowestnosto <[email protected]>

Copilot finished work on behalf of timowestnosto October 4, 2025 18:49

Copilot started work on behalf of timowestnosto October 4, 2025 18:50 View session

timowestnosto requested changes Oct 4, 2025

View reviewed changes

Copilot finished work on behalf of timowestnosto October 5, 2025 07:47

Copilot started work on behalf of timowestnosto October 5, 2025 07:48 View session

chore: add manual fixes

5d01322

timowestnosto force-pushed the copilot/fix-c98b8d45-0181-47c7-b7f2-a21104d2580c branch 6 times, most recently from bc35ab7 to e5b2606 Compare October 5, 2025 11:38

chore: more manual fixes

b869c7a

timowestnosto force-pushed the copilot/fix-c98b8d45-0181-47c7-b7f2-a21104d2580c branch from e5b2606 to b869c7a Compare October 5, 2025 11:44

Copilot started work on behalf of timowestnosto October 5, 2025 13:58 View session

Copilot started work on behalf of timowestnosto October 6, 2025 07:13 View session

manikandan-ravikumar reviewed Oct 7, 2025

View reviewed changes

chore: add PopupState type

d0f1b37

manikandan-ravikumar approved these changes Oct 7, 2025

View reviewed changes

timowestnosto approved these changes Oct 7, 2025

View reviewed changes

timowestnosto merged commit c809919 into main Oct 7, 2025
2 checks passed

feat(Popup): add new custom element with dual-mode dialog and ribbon functionality #436

feat(Popup): add new custom element with dual-mode dialog and ribbon functionality #436

Uh oh!

Conversation

Copilot AI commented Oct 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎉 Popup Component Implementation Complete

✨ Key Features

🔧 Usage

📊 Test Coverage

🏗️ Architecture

🚨 Breaking Changes

🎨 Shadow DOM Parts & Semantic Selectors

🚀 Performance Optimizations

🧪 Testing Excellence

📚 Storybook Examples

📸 Visual Preview

Comments on the Issue (you are @copilot in this section)

Uh oh!

timowestnosto left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI commented Oct 4, 2025

Uh oh!

timowestnosto left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

timowestnosto left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Oct 4, 2025

Choose a reason for hiding this comment

Uh oh!

timowestnosto Oct 4, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Oct 4, 2025

Uh oh!

Copilot AI commented Oct 4, 2025

Uh oh!

timowestnosto left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI commented Oct 5, 2025

Uh oh!

Copilot AI commented Oct 5, 2025

Uh oh!

Copilot AI commented Oct 5, 2025

Uh oh!

timowestnosto commented Oct 5, 2025

Uh oh!

timowestnosto commented Oct 6, 2025

Uh oh!

Copilot AI commented Oct 4, 2025 •

edited

Loading

timowestnosto commented Oct 7, 2025 •

edited

Loading