@magic-spells/cart-panel 0.3.1 → 1.0.0

package/src/cart-panel.js

@@ -1,159 +1,213 @@
-import './cart-panel.scss';
-
-import '@magic-spells/focus-trap';
+import './cart-panel.css';
 import EventEmitter from '@magic-spells/event-emitter';
-import { CartItem } from '@magic-spells/cart-item';
+import { CartItem, CartItemContent, CartItemProcessing } from './cart-item.js';
+
+// =============================================================================
+// CartPanel Component
+// =============================================================================
 
 /**
- * Custom element that creates an accessible modal cart dialog with focus management
+ * Shopping cart panel web component for Shopify.
+ * Manages cart data and AJAX requests, delegates modal behavior to dialog-panel.
  * @extends HTMLElement
  */
-class CartDialog extends HTMLElement {
-	#handleTransitionEnd;
+class CartPanel extends HTMLElement {
 	#currentCart = null;
 	#eventEmitter;
 	#isInitialRender = true;
 
-	/**
-	 * Clean up event listeners when component is removed from DOM
-	 */
-	disconnectedCallback() {
-		const _ = this;
-		if (_.contentPanel) {
-			_.contentPanel.removeEventListener('transitionend', _.#handleTransitionEnd);
-		}
+	constructor() {
+		super();
+		this.#eventEmitter = new EventEmitter();
+	}
 
-		// Ensure body scroll is restored if component is removed while open
-		document.body.classList.remove('overflow-hidden');
-		this.#restoreScroll();
+	connectedCallback() {
+		this.#attachListeners();
+
+		// Load cart data immediately unless manual mode is enabled
+		if (!this.hasAttribute('manual')) {
+			this.refreshCart();
+		}
+	}
 
-		// Detach event listeners
-		this.#detachListeners();
+	disconnectedCallback() {
+		// Clean up handled by garbage collection
 	}
 
+	// =========================================================================
+	// Public API - Event Emitter
+	// =========================================================================
+
 	/**
-	 * Locks body scrolling
-	 * @private
+	 * Add an event listener
+	 * @param {string} eventName - Name of the event
+	 * @param {Function} callback - Callback function
+	 * @returns {CartPanel} Returns this for method chaining
 	 */
-	#lockScroll() {
-		// Apply overflow hidden to body
-		document.body.classList.add('overflow-hidden');
+	on(eventName, callback) {
+		this.#eventEmitter.on(eventName, callback);
+		return this;
 	}
 
 	/**
-	 * Restores body scrolling when cart dialog is closed
-	 * @private
+	 * Remove an event listener
+	 * @param {string} eventName - Name of the event
+	 * @param {Function} callback - Callback function
+	 * @returns {CartPanel} Returns this for method chaining
 	 */
-	#restoreScroll() {
-		// Remove overflow hidden from body
-		document.body.classList.remove('overflow-hidden');
+	off(eventName, callback) {
+		this.#eventEmitter.off(eventName, callback);
+		return this;
 	}
 
+	// =========================================================================
+	// Public API - Dialog Control
+	// =========================================================================
+
 	/**
-	 * Initializes the cart dialog, sets up focus trap and overlay
+	 * Show the cart by finding and opening the nearest dialog-panel ancestor
+	 * @param {HTMLElement} [triggerEl=null] - The element that triggered the open
+	 * @param {Object} [cartObj=null] - Optional cart object to use instead of fetching
 	 */
-	constructor() {
-		super();
+	show(triggerEl = null, cartObj = null) {
 		const _ = this;
-		_.id = _.getAttribute('id');
-		_.setAttribute('role', 'dialog');
-		_.setAttribute('aria-modal', 'true');
-		_.setAttribute('aria-hidden', 'true');
+		const dialogPanel = _.#findDialogPanel();
 
-		_.triggerEl = null;
+		if (dialogPanel) {
+			dialogPanel.show(triggerEl);
+			_.refreshCart(cartObj);
+			_.#emit('cart-panel:show', { triggerElement: triggerEl });
+		} else {
+			console.warn('cart-panel: No dialog-panel ancestor found. Cart panel is visible but not in a modal.');
+		}
+	}
 
-		// Initialize event emitter
-		_.#eventEmitter = new EventEmitter();
+	/**
+	 * Hide the cart by finding and closing the nearest dialog-panel ancestor
+	 */
+	hide() {
+		const dialogPanel = this.#findDialogPanel();
+		if (dialogPanel) {
+			dialogPanel.hide();
+			this.#emit('cart-panel:hide', {});
+		}
+	}
 
-		// Create a handler for transition end events
-		_.#handleTransitionEnd = (e) => {
-			if (e.propertyName === 'opacity' && _.getAttribute('aria-hidden') === 'true') {
-				_.contentPanel.classList.add('hidden');
+	// =========================================================================
+	// Public API - Cart Data
+	// =========================================================================
 
-				// Emit afterHide event - cart dialog has completed its transition
-				_.#emit('cart-dialog:afterHide', { triggerElement: _.triggerEl });
-			}
-		};
+	/**
+	 * Fetch current cart data from Shopify
+	 * @returns {Promise<Object>} Cart data object
+	 */
+	getCart() {
+		return fetch('/cart.json', {
+			credentials: 'same-origin',
+		})
+			.then((response) => {
+				if (!response.ok) {
+					throw Error(response.statusText);
+				}
+				return response.json();
+			})
+			.catch((error) => {
+				console.error('Error fetching cart:', error);
+				return { error: true, message: error.message };
+			});
 	}
 
-	connectedCallback() {
-		const _ = this;
+	/**
+	 * Update cart item quantity on Shopify
+	 * @param {string|number} key - Cart item key/ID
+	 * @param {number} quantity - New quantity (0 to remove)
+	 * @returns {Promise<Object>} Updated cart data object
+	 */
+	updateCartItem(key, quantity) {
+		return fetch('/cart/change.json', {
+			method: 'POST',
+			credentials: 'same-origin',
+			body: JSON.stringify({ id: key, quantity: quantity }),
+			headers: { 'Content-Type': 'application/json' },
+		})
+			.then((response) => {
+				if (!response.ok) {
+					throw Error(response.statusText);
+				}
+				return response.json();
+			})
+			.catch((error) => {
+				console.error('Error updating cart item:', error);
+				return { error: true, message: error.message };
+			});
+	}
 
-		// Now that we're in the DOM, find the content panel and set up focus trap
-		_.contentPanel = _.querySelector('cart-panel');
+	/**
+	 * Refresh cart display - fetches from server if no cart object provided
+	 * @param {Object} [cartObj=null] - Cart data object to render, or null to fetch
+	 * @returns {Promise<Object>} Cart data object
+	 */
+	async refreshCart(cartObj = null) {
+		const _ = this;
 
-		if (!_.contentPanel) {
-			console.error('cart-panel element not found inside cart-dialog');
-			return;
+		// Fetch from server if no cart object provided
+		cartObj = cartObj || (await _.getCart());
+		if (!cartObj || cartObj.error) {
+			console.warn('Cart data has error or is null:', cartObj);
+			return cartObj;
 		}
 
-		// Check if focus-trap already exists, if not create one
-		_.focusTrap = _.contentPanel.querySelector('focus-trap');
-		if (!_.focusTrap) {
-			_.focusTrap = document.createElement('focus-trap');
+		_.#currentCart = cartObj;
+		_.#renderCartItems(cartObj);
+		_.#renderCartPanel(cartObj);
 
-			// Move all existing cart-panel content into the focus trap
-			const existingContent = Array.from(_.contentPanel.childNodes);
-			existingContent.forEach((child) => _.focusTrap.appendChild(child));
+		const cartWithCalculatedFields = _.#addCalculatedFields(cartObj);
+		_.#emit('cart-panel:refreshed', { cart: cartWithCalculatedFields });
+		_.#emit('cart-panel:data-changed', cartWithCalculatedFields);
 
-			// Insert focus trap inside the cart-panel
-			_.contentPanel.appendChild(_.focusTrap);
-		}
-
-		// Ensure we have labelledby and describedby references
-		if (!_.getAttribute('aria-labelledby')) {
-			const heading = _.querySelector('h1, h2, h3');
-			if (heading && !heading.id) {
-				heading.id = `${_.id}-title`;
-			}
-			if (heading?.id) {
-				_.setAttribute('aria-labelledby', heading.id);
-			}
-		}
+		return cartObj;
+	}
 
-		// Add modal overlay if it doesn't already exist
-		if (!_.querySelector('cart-overlay')) {
-			_.prepend(document.createElement('cart-overlay'));
-		}
-		_.#attachListeners();
-		_.#bindKeyboard();
+	// =========================================================================
+	// Public API - Templates
+	// =========================================================================
 
-		// Load cart data immediately after component initialization
-		_.refreshCart();
+	/**
+	 * Set the template function for cart items
+	 * @param {string} templateName - Name of the template
+	 * @param {Function} templateFn - Function that takes (itemData, cartData) and returns HTML string
+	 */
+	setCartItemTemplate(templateName, templateFn) {
+		CartItem.setTemplate(templateName, templateFn);
 	}
 
 	/**
-	 * Event emitter method - Add an event listener with a cleaner API
-	 * @param {string} eventName - Name of the event to listen for
-	 * @param {Function} callback - Callback function to execute when event is fired
-	 * @returns {CartDialog} Returns this for method chaining
+	 * Set the processing template function for cart items
+	 * @param {Function} templateFn - Function that returns HTML string for processing state
 	 */
-	on(eventName, callback) {
-		this.#eventEmitter.on(eventName, callback);
-		return this;
+	setCartItemProcessingTemplate(templateFn) {
+		CartItem.setProcessingTemplate(templateFn);
 	}
 
+	// =========================================================================
+	// Private Methods - Core
+	// =========================================================================
+
 	/**
-	 * Event emitter method - Remove an event listener
-	 * @param {string} eventName - Name of the event to stop listening for
-	 * @param {Function} callback - Callback function to remove
-	 * @returns {CartDialog} Returns this for method chaining
+	 * Find the nearest dialog-panel ancestor
+	 * @private
 	 */
-	off(eventName, callback) {
-		this.#eventEmitter.off(eventName, callback);
-		return this;
+	#findDialogPanel() {
+		return this.closest('dialog-panel');
 	}
 
 	/**
-	 * Internal method to emit events via the event emitter
-	 * @param {string} eventName - Name of the event to emit
-	 * @param {*} [data] - Optional data to include with the event
+	 * Emit an event via EventEmitter and native CustomEvent
 	 * @private
 	 */
 	#emit(eventName, data = null) {
 		this.#eventEmitter.emit(eventName, data);
 
-		// Also emit as native DOM events for better compatibility
 		this.dispatchEvent(
 			new CustomEvent(eventName, {
 				detail: data,
@@ -163,98 +217,57 @@ class CartDialog extends HTMLElement {
 	}
 
 	/**
-	 * Attach event listeners for cart dialog functionality
+	 * Attach event listeners
 	 * @private
 	 */
 	#attachListeners() {
-		const _ = this;
-
-		// Handle trigger buttons
-		document.addEventListener('click', (e) => {
-			const trigger = e.target.closest(`[aria-controls="${_.id}"]`);
-			if (!trigger) return;
-
-			if (trigger.getAttribute('data-prevent-default') === 'true') {
-				e.preventDefault();
-			}
-
-			_.show(trigger);
-		});
-
 		// Handle close buttons
-		_.addEventListener('click', (e) => {
+		this.addEventListener('click', (e) => {
 			if (!e.target.closest('[data-action-hide-cart]')) return;
-			_.hide();
+			this.hide();
 		});
 
 		// Handle cart item remove events
-		_.addEventListener('cart-item:remove', (e) => {
-			_.#handleCartItemRemove(e);
+		this.addEventListener('cart-item:remove', (e) => {
+			this.#handleCartItemRemove(e);
 		});
 
 		// Handle cart item quantity change events
-		_.addEventListener('cart-item:quantity-change', (e) => {
-			_.#handleCartItemQuantityChange(e);
+		this.addEventListener('cart-item:quantity-change', (e) => {
+			this.#handleCartItemQuantityChange(e);
 		});
-
-		// Add transition end listener
-		_.contentPanel.addEventListener('transitionend', _.#handleTransitionEnd);
-	}
-
-	/**
-	 * Detach event listeners
-	 * @private
-	 */
-	#detachListeners() {
-		const _ = this;
-		if (_.contentPanel) {
-			_.contentPanel.removeEventListener('transitionend', _.#handleTransitionEnd);
-		}
 	}
 
-	/**
-	 * Binds keyboard events for accessibility
-	 * @private
-	 */
-	#bindKeyboard() {
-		this.addEventListener('keydown', (e) => {
-			if (e.key === 'Escape') {
-				this.hide();
-			}
-		});
-	}
+	// =========================================================================
+	// Private Methods - Cart Item Event Handlers
+	// =========================================================================
 
 	/**
 	 * Handle cart item removal
 	 * @private
 	 */
 	#handleCartItemRemove(e) {
+		const _ = this;
 		const { cartKey, element } = e.detail;
 
-		// Set item to processing state
 		element.setState('processing');
 
-		// Remove item by setting quantity to 0
-		this.updateCartItem(cartKey, 0)
+		_.updateCartItem(cartKey, 0)
 			.then((updatedCart) => {
 				if (updatedCart && !updatedCart.error) {
-					// Success - let smart comparison handle the removal animation
-					this.#currentCart = updatedCart;
-					this.#renderCartItems(updatedCart);
-					this.#renderCartPanel(updatedCart);
-
-					// Emit cart updated and data changed events
-					const cartWithCalculatedFields = this.#addCalculatedFields(updatedCart);
-					this.#emit('cart-dialog:updated', { cart: cartWithCalculatedFields });
-					this.#emit('cart-dialog:data-changed', cartWithCalculatedFields);
+					_.#currentCart = updatedCart;
+					_.#renderCartItems(updatedCart);
+					_.#renderCartPanel(updatedCart);
+
+					const cartWithCalculatedFields = _.#addCalculatedFields(updatedCart);
+					_.#emit('cart-panel:updated', { cart: cartWithCalculatedFields });
+					_.#emit('cart-panel:data-changed', cartWithCalculatedFields);
 				} else {
-					// Error - reset to ready state
 					element.setState('ready');
 					console.error('Failed to remove cart item:', cartKey);
 				}
 			})
 			.catch((error) => {
-				// Error - reset to ready state
 				element.setState('ready');
 				console.error('Error removing cart item:', error);
 			});
@@ -265,49 +278,46 @@ class CartDialog extends HTMLElement {
 	 * @private
 	 */
 	#handleCartItemQuantityChange(e) {
+		const _ = this;
 		const { cartKey, quantity, element } = e.detail;
 
-		// Set item to processing state
 		element.setState('processing');
 
-		// Update item quantity
-		this.updateCartItem(cartKey, quantity)
+		_.updateCartItem(cartKey, quantity)
 			.then((updatedCart) => {
 				if (updatedCart && !updatedCart.error) {
-					// Success - update cart data and refresh items
-					this.#currentCart = updatedCart;
-					this.#renderCartItems(updatedCart);
-					this.#renderCartPanel(updatedCart);
-
-					// Emit cart updated and data changed events
-					const cartWithCalculatedFields = this.#addCalculatedFields(updatedCart);
-					this.#emit('cart-dialog:updated', { cart: cartWithCalculatedFields });
-					this.#emit('cart-dialog:data-changed', cartWithCalculatedFields);
+					_.#currentCart = updatedCart;
+					_.#renderCartItems(updatedCart);
+					_.#renderCartPanel(updatedCart);
+
+					const cartWithCalculatedFields = _.#addCalculatedFields(updatedCart);
+					_.#emit('cart-panel:updated', { cart: cartWithCalculatedFields });
+					_.#emit('cart-panel:data-changed', cartWithCalculatedFields);
 				} else {
-					// Error - reset to ready state
 					element.setState('ready');
 					console.error('Failed to update cart item quantity:', cartKey, quantity);
 				}
 			})
 			.catch((error) => {
-				// Error - reset to ready state
 				element.setState('ready');
 				console.error('Error updating cart item quantity:', error);
 			});
 	}
 
+	// =========================================================================
+	// Private Methods - Rendering
+	// =========================================================================
+
 	/**
-	 * Update cart count elements across the site
+	 * Update cart count elements across the page
 	 * @private
 	 */
 	#renderCartCount(cartData) {
 		if (!cartData) return;
 
-		// Calculate visible item count (excluding _hide_in_cart items)
 		const visibleItems = this.#getVisibleCartItems(cartData);
 		const visibleItemCount = visibleItems.reduce((total, item) => total + item.quantity, 0);
 
-		// Update all cart count elements across the site
 		const cartCountElements = document.querySelectorAll('[data-content-cart-count]');
 		cartCountElements.forEach((element) => {
 			element.textContent = visibleItemCount;
@@ -315,170 +325,110 @@ class CartDialog extends HTMLElement {
 	}
 
 	/**
-	 * Update cart subtotal elements across the site
+	 * Update cart subtotal elements across the page
 	 * @private
 	 */
 	#renderCartSubtotal(cartData) {
 		if (!cartData) return;
 
-		// Calculate subtotal from all items except those marked to ignore pricing
 		const pricedItems = cartData.items.filter((item) => {
 			const ignorePrice = item.properties?._ignore_price_in_subtotal;
 			return !ignorePrice;
 		});
 		const subtotal = pricedItems.reduce((total, item) => total + (item.line_price || 0), 0);
 
-		// Update all cart subtotal elements across the site
 		const cartSubtotalElements = document.querySelectorAll('[data-content-cart-subtotal]');
 		cartSubtotalElements.forEach((element) => {
-			// Format as currency (assuming cents, convert to dollars)
 			const formatted = (subtotal / 100).toFixed(2);
 			element.textContent = `$${formatted}`;
 		});
 	}
 
 	/**
-	 * Update cart items display based on cart data
+	 * Update cart panel sections (has-items/empty)
 	 * @private
 	 */
 	#renderCartPanel(cart = null) {
-		const cartData = cart || this.#currentCart;
+		const _ = this;
+		const cartData = cart || _.#currentCart;
 		if (!cartData) return;
 
-		// Get cart sections
-		const hasItemsSection = this.querySelector('[data-cart-has-items]');
-		const emptySection = this.querySelector('[data-cart-is-empty]');
-		const itemsContainer = this.querySelector('[data-content-cart-items]');
+		const visibleItems = _.#getVisibleCartItems(cartData);
+		const hasVisibleItems = visibleItems.length > 0;
 
-		if (!hasItemsSection || !emptySection || !itemsContainer) {
-			console.warn(
-				'Cart sections not found. Expected [data-cart-has-items], [data-cart-is-empty], and [data-content-cart-items]'
-			);
-			return;
-		}
+		// Set state attribute for CSS styling (e.g., Tailwind variants)
+		_.setAttribute('state', hasVisibleItems ? 'has-items' : 'empty');
 
-		// Check visible item count for showing/hiding sections
-		const visibleItems = this.#getVisibleCartItems(cartData);
-		const hasVisibleItems = visibleItems.length > 0;
+		const hasItemsSection = _.querySelector('[data-cart-has-items]');
+		const emptySection = _.querySelector('[data-cart-is-empty]');
 
-		// Show/hide sections based on visible item count
-		if (hasVisibleItems) {
-			hasItemsSection.style.display = '';
-			emptySection.style.display = 'none';
-		} else {
-			hasItemsSection.style.display = 'none';
-			emptySection.style.display = '';
+		if (hasItemsSection && emptySection) {
+			hasItemsSection.style.display = hasVisibleItems ? '' : 'none';
+			emptySection.style.display = hasVisibleItems ? 'none' : '';
 		}
 
-		// Update cart count and subtotal across the site
-		this.#renderCartCount(cartData);
-		this.#renderCartSubtotal(cartData);
+		_.#renderCartCount(cartData);
+		_.#renderCartSubtotal(cartData);
 	}
 
 	/**
-	 * Fetch current cart data from server
-	 * @returns {Promise<Object>} Cart data object
+	 * Render cart items with smart add/update/remove
+	 * @private
 	 */
-	getCart() {
-		return fetch('/cart.json', {
-			crossDomain: true,
-			credentials: 'same-origin',
-		})
-			.then((response) => {
-				if (!response.ok) {
-					throw Error(response.statusText);
-				}
-				return response.json();
-			})
-			.catch((error) => {
-				console.error('Error fetching cart:', error);
-				return { error: true, message: error.message };
-			});
-	}
+	#renderCartItems(cartData) {
+		const _ = this;
+		const itemsContainer = _.querySelector('[data-content-cart-items]');
 
-	/**
-	 * Update cart item quantity on server
-	 * @param {string|number} key - Cart item key/ID
-	 * @param {number} quantity - New quantity (0 to remove)
-	 * @returns {Promise<Object>} Updated cart data object
-	 */
-	updateCartItem(key, quantity) {
-		return fetch('/cart/change.json', {
-			crossDomain: true,
-			method: 'POST',
-			credentials: 'same-origin',
-			body: JSON.stringify({ id: key, quantity: quantity }),
-			headers: { 'Content-Type': 'application/json' },
-		})
-			.then((response) => {
-				if (!response.ok) {
-					throw Error(response.statusText);
-				}
-				return response.json();
-			})
-			.catch((error) => {
-				console.error('Error updating cart item:', error);
-				return { error: true, message: error.message };
-			});
-	}
+		if (!itemsContainer || !cartData || !cartData.items) return;
 
-	/**
-	 * Refresh cart data from server and update components
-	 * @param {Object} [cartObj=null] - Optional cart object to use instead of fetching
-	 * @returns {Promise<Object>} Cart data object
-	 */
-	refreshCart(cartObj = null) {
-		// If cart object is provided, use it directly
-		if (cartObj && !cartObj.error) {
-			// console.log('Using provided cart data:', cartObj);
-			this.#currentCart = cartObj;
-			this.#renderCartItems(cartObj);
-			this.#renderCartPanel(cartObj);
-
-			// Emit cart refreshed and data changed events
-			const cartWithCalculatedFields = this.#addCalculatedFields(cartObj);
-			this.#emit('cart-dialog:refreshed', { cart: cartWithCalculatedFields });
-			this.#emit('cart-dialog:data-changed', cartWithCalculatedFields);
-
-			return Promise.resolve(cartObj);
+		const visibleItems = _.#getVisibleCartItems(cartData);
+
+		// Initial render - load all items without animation
+		if (_.#isInitialRender) {
+			itemsContainer.innerHTML = '';
+			visibleItems.forEach((itemData) => {
+				itemsContainer.appendChild(new CartItem(itemData, cartData));
+			});
+			_.#isInitialRender = false;
+			return;
 		}
 
-		// Otherwise fetch from server
-		return this.getCart().then((cartData) => {
-			// console.log('Cart data received:', cartData);
-			if (cartData && !cartData.error) {
-				this.#currentCart = cartData;
-				this.#renderCartItems(cartData);
-				this.#renderCartPanel(cartData);
-
-				// Emit cart refreshed and data changed events
-				const cartWithCalculatedFields = this.#addCalculatedFields(cartData);
-				this.#emit('cart-dialog:refreshed', { cart: cartWithCalculatedFields });
-				this.#emit('cart-dialog:data-changed', cartWithCalculatedFields);
-			} else {
-				console.warn('Cart data has error or is null:', cartData);
-			}
-			return cartData;
-		});
+		// Get current DOM items
+		const currentItems = Array.from(itemsContainer.querySelectorAll('cart-item'));
+		const currentKeys = new Set(currentItems.map((item) => item.getAttribute('key')));
+
+		// Get new cart data keys
+		const newKeys = visibleItems.map((item) => item.key || item.id);
+		const newKeysSet = new Set(newKeys);
+
+		// Step 1: Remove items no longer in cart
+		_.#removeItemsFromDOM(itemsContainer, newKeysSet);
+
+		// Step 2: Update existing items
+		_.#updateItemsInDOM(itemsContainer, cartData);
+
+		// Step 3: Add new items with animation
+		const itemsToAdd = visibleItems.filter(
+			(itemData) => !currentKeys.has(itemData.key || itemData.id)
+		);
+		_.#addItemsToDOM(itemsContainer, itemsToAdd, newKeys, cartData);
 	}
 
 	/**
-	 * Remove items from DOM that are no longer in cart data
+	 * Remove items from DOM that are no longer in cart
 	 * @private
 	 */
 	#removeItemsFromDOM(itemsContainer, newKeysSet) {
 		const currentItems = Array.from(itemsContainer.querySelectorAll('cart-item'));
-
 		const itemsToRemove = currentItems.filter((item) => !newKeysSet.has(item.getAttribute('key')));
 
 		itemsToRemove.forEach((item) => {
-			console.log('destroy yourself', item);
 			item.destroyYourself();
 		});
 	}
 
 	/**
-	 * Update existing cart-item elements with fresh cart data
+	 * Update existing cart-item elements with fresh data
 	 * @private
 	 */
 	#updateItemsInDOM(itemsContainer, cartData) {
@@ -488,12 +438,7 @@ class CartDialog extends HTMLElement {
 		existingItems.forEach((cartItemEl) => {
 			const key = cartItemEl.getAttribute('key');
 			const updatedItemData = visibleItems.find((item) => (item.key || item.id) === key);
-
-			if (updatedItemData) {
-				// Update cart-item with fresh data and full cart context
-				// The cart-item will handle HTML comparison and only re-render if needed
-				cartItemEl.setData(updatedItemData, cartData);
-			}
+			if (updatedItemData) cartItemEl.setData(updatedItemData, cartData);
 		});
 	}
 
@@ -501,19 +446,15 @@ class CartDialog extends HTMLElement {
 	 * Add new items to DOM with animation delay
 	 * @private
 	 */
-	#addItemsToDOM(itemsContainer, itemsToAdd, newKeys) {
-		// Delay adding new items by 300ms to let cart slide open first
+	#addItemsToDOM(itemsContainer, itemsToAdd, newKeys, cartData) {
 		setTimeout(() => {
 			itemsToAdd.forEach((itemData) => {
-				const cartItem = CartItem.createAnimated(itemData);
+				const cartItem = CartItem.createAnimated(itemData, cartData);
 				const targetIndex = newKeys.indexOf(itemData.key || itemData.id);
 
-				// Find the correct position to insert the new item
 				if (targetIndex === 0) {
-					// Insert at the beginning
 					itemsContainer.insertBefore(cartItem, itemsContainer.firstChild);
 				} else {
-					// Find the item that should come before this one
 					let insertAfter = null;
 					for (let i = targetIndex - 1; i >= 0; i--) {
 						const prevKey = newKeys[i];
@@ -534,246 +475,46 @@ class CartDialog extends HTMLElement {
 		}, 100);
 	}
 
+	// =========================================================================
+	// Private Methods - Helpers
+	// =========================================================================
+
 	/**
-	 * Filter cart items to exclude those with _hide_in_cart property
+	 * Filter cart items to exclude hidden items
 	 * @private
 	 */
 	#getVisibleCartItems(cartData) {
 		if (!cartData || !cartData.items) return [];
 		return cartData.items.filter((item) => {
-			// Check for _hide_in_cart in various possible locations
 			const hidden = item.properties?._hide_in_cart;
-
 			return !hidden;
 		});
 	}
 
 	/**
-	 * Add calculated fields to cart object for events
+	 * Add calculated fields to cart object
 	 * @private
 	 */
 	#addCalculatedFields(cartData) {
 		if (!cartData) return cartData;
 
-		// For display counts: use visible items (excludes _hide_in_cart)
 		const visibleItems = this.#getVisibleCartItems(cartData);
 		const calculated_count = visibleItems.reduce((total, item) => total + item.quantity, 0);
 
-		// For pricing: use all items except those marked to ignore pricing
-		const pricedItems = cartData.items.filter((item) => {
-			const ignorePrice = item.properties?._ignore_price_in_subtotal;
-			return !ignorePrice;
-		});
-		const calculated_subtotal = pricedItems.reduce(
-			(total, item) => total + (item.line_price || 0),
-			0
-		);
-
-		return {
-			...cartData,
-			calculated_count,
-			calculated_subtotal,
-		};
-	}
-
-	/**
-	 * Render cart items from Shopify cart data with smart comparison
-	 * @private
-	 */
-	#renderCartItems(cartData) {
-		const itemsContainer = this.querySelector('[data-content-cart-items]');
-
-		if (!itemsContainer || !cartData || !cartData.items) {
-			console.warn('Cannot render cart items:', {
-				itemsContainer: !!itemsContainer,
-				cartData: !!cartData,
-				items: cartData?.items?.length,
-			});
-			return;
-		}
-
-		// Filter out items with _hide_in_cart property
-		const visibleItems = this.#getVisibleCartItems(cartData);
-
-		// Handle initial render - load all items without animation
-		if (this.#isInitialRender) {
-			// console.log('Initial cart render:', visibleItems.length, 'visible items');
-
-			// Clear existing items
-			itemsContainer.innerHTML = '';
-
-			// Create cart-item elements without animation
-			visibleItems.forEach((itemData) => {
-				const cartItem = new CartItem(itemData); // No animation
-				itemsContainer.appendChild(cartItem);
-			});
-
-			this.#isInitialRender = false;
-
-			return;
-		}
-
-		// Get current DOM items and their keys
-		const currentItems = Array.from(itemsContainer.querySelectorAll('cart-item'));
-		const currentKeys = new Set(currentItems.map((item) => item.getAttribute('key')));
-
-		// Get new cart data keys in order (only visible items)
-		const newKeys = visibleItems.map((item) => item.key || item.id);
-		const newKeysSet = new Set(newKeys);
-
-		// Step 1: Remove items that are no longer in cart data
-		this.#removeItemsFromDOM(itemsContainer, newKeysSet);
-
-		// Step 2: Update existing items with fresh data (handles templates, bundles, etc.)
-		this.#updateItemsInDOM(itemsContainer, cartData);
-
-		// Step 3: Add new items that weren't in DOM (with animation delay)
-		const itemsToAdd = visibleItems.filter(
-			(itemData) => !currentKeys.has(itemData.key || itemData.id)
-		);
-		this.#addItemsToDOM(itemsContainer, itemsToAdd, newKeys);
-	}
-
-	/**
-	 * Set the template function for cart items
-	 * @param {Function} templateFn - Function that takes item data and returns HTML string
-	 */
-	setCartItemTemplate(templateName, templateFn) {
-		CartItem.setTemplate(templateName, templateFn);
-	}
-
-	/**
-	 * Set the processing template function for cart items
-	 * @param {Function} templateFn - Function that returns HTML string for processing state
-	 */
-	setCartItemProcessingTemplate(templateFn) {
-		CartItem.setProcessingTemplate(templateFn);
-	}
-
-	/**
-	 * Shows the cart dialog and traps focus within it
-	 * @param {HTMLElement} [triggerEl=null] - The element that triggered the cart dialog
-	 * @fires CartDialog#show - Fired when the cart dialog has been shown
-	 */
-	show(triggerEl = null, cartObj) {
-		const _ = this;
-		_.triggerEl = triggerEl || false;
-
-		// Lock body scrolling
-		_.#lockScroll();
-
-		// Remove the hidden class first to ensure content is rendered
-		_.contentPanel.classList.remove('hidden');
-
-		// Give the browser a moment to process before starting animation
-		requestAnimationFrame(() => {
-			// Update ARIA states
-			_.setAttribute('aria-hidden', 'false');
-
-			if (_.triggerEl) {
-				_.triggerEl.setAttribute('aria-expanded', 'true');
-			}
-
-			// Focus management
-			const firstFocusable = _.querySelector(
-				'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
-			);
-
-			if (firstFocusable) {
-				requestAnimationFrame(() => {
-					firstFocusable.focus();
-				});
-			}
-
-			// Refresh cart data when showing
-			_.refreshCart(cartObj);
+		const pricedItems = cartData.items.filter((item) => !item.properties?._ignore_price_in_subtotal);
+		const calculated_subtotal = pricedItems.reduce((total, item) => total + (item.line_price || 0), 0);
 
-			// Emit show event - cart dialog is now visible
-			_.#emit('cart-dialog:show', { triggerElement: _.triggerEl });
-		});
-	}
-
-	/**
-	 * Hides the cart dialog and restores focus
-	 * @fires CartDialog#hide - Fired when the cart dialog has started hiding (transition begins)
-	 * @fires CartDialog#afterHide - Fired when the cart dialog has completed its hide transition
-	 */
-	hide() {
-		const _ = this;
-
-		// Update ARIA states
-		if (_.triggerEl) {
-			// remove focus from modal panel first
-			_.triggerEl.focus();
-			// mark trigger as no longer expanded
-			_.triggerEl.setAttribute('aria-expanded', 'false');
-		} else {
-			// If no trigger element, blur any focused element inside the panel
-			const activeElement = document.activeElement;
-			if (activeElement && _.contains(activeElement)) {
-				activeElement.blur();
-			}
-		}
-
-		requestAnimationFrame(() => {
-			// Set aria-hidden to start transition
-			// The transitionend event handler will add display:none when complete
-			_.setAttribute('aria-hidden', 'true');
-
-			// Emit hide event - cart dialog is now starting to hide
-			_.#emit('cart-dialog:hide', { triggerElement: _.triggerEl });
-
-			// Restore body scroll
-			_.#restoreScroll();
-		});
+		return { ...cartData, calculated_count, calculated_subtotal };
 	}
 }
 
-/**
- * Custom element that creates a clickable overlay for the cart dialog
- * @extends HTMLElement
- */
-class CartOverlay extends HTMLElement {
-	constructor() {
-		super();
-		this.setAttribute('tabindex', '-1');
-		this.setAttribute('aria-hidden', 'true');
-		this.cartDialog = this.closest('cart-dialog');
-		this.#attachListeners();
-	}
-
-	#attachListeners() {
-		this.addEventListener('click', () => {
-			this.cartDialog.hide();
-		});
-	}
-}
+// =============================================================================
+// Register Custom Elements
+// =============================================================================
 
-/**
- * Custom element that wraps the content of the cart dialog
- * @extends HTMLElement
- */
-class CartPanel extends HTMLElement {
-	constructor() {
-		super();
-		this.setAttribute('role', 'document');
-	}
-}
-
-if (!customElements.get('cart-dialog')) {
-	customElements.define('cart-dialog', CartDialog);
-}
-if (!customElements.get('cart-overlay')) {
-	customElements.define('cart-overlay', CartOverlay);
-}
 if (!customElements.get('cart-panel')) {
 	customElements.define('cart-panel', CartPanel);
 }
 
-export { CartDialog, CartOverlay, CartPanel, CartItem };
-export default CartDialog;
-
-// Make CartItem available globally for Shopify themes
-if (typeof window !== 'undefined') {
-	window.CartItem = CartItem;
-}
+export { CartPanel, CartItem, CartItemContent, CartItemProcessing };
+export default CartPanel;