@magic-spells/cart-progress-bar 0.1.0

package/package.json

@@ -0,0 +1,75 @@
+{
+	"name": "@magic-spells/cart-progress-bar",
+	"version": "0.1.0",
+	"description": "Cart progress bar web component for free shipping thresholds.",
+	"author": "Cory Schulz",
+	"license": "MIT",
+	"type": "module",
+	"main": "dist/cart-progress-bar.cjs.js",
+	"module": "dist/cart-progress-bar.esm.js",
+	"unpkg": "dist/cart-progress-bar.min.js",
+	"style": "dist/cart-progress-bar.min.css",
+	"sass": "dist/cart-progress-bar.scss",
+	"exports": {
+		".": {
+			"import": "./dist/cart-progress-bar.esm.js",
+			"require": "./dist/cart-progress-bar.cjs.js",
+			"default": "./dist/cart-progress-bar.esm.js"
+		},
+		"./css": "./dist/cart-progress-bar.css",
+		"./css/min": "./dist/cart-progress-bar.min.css",
+		"./scss": "./dist/cart-progress-bar.scss"
+	},
+	"sideEffects": true,
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/magic-spells/cart-progress-bar"
+	},
+	"homepage": "https://github.com/magic-spells/cart-progress-bar#readme",
+	"bugs": {
+		"url": "https://github.com/magic-spells/cart-progress-bar/issues"
+	},
+	"keywords": [
+		"cart-progress-bar",
+		"progress-bar",
+		"web-components",
+		"free-shipping",
+		"e-commerce",
+		"custom-elements",
+		"cart-threshold"
+	],
+	"files": [
+		"dist/",
+		"src/"
+	],
+	"scripts": {
+		"build": "rollup -c",
+		"lint": "eslint src/ rollup.config.mjs",
+		"format": "prettier --write .",
+		"prepublishOnly": "npm run build",
+		"serve": "rollup -c --watch",
+		"dev": "rollup -c --watch"
+	},
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	},
+	"browserslist": [
+		"last 2 versions",
+		"not dead",
+		"not ie <= 11"
+	],
+	"devDependencies": {
+		"@eslint/js": "^8.57.0",
+		"@rollup/plugin-node-resolve": "^15.2.3",
+		"@rollup/plugin-terser": "^0.4.4",
+		"eslint": "^8.0.0",
+		"globals": "^13.24.0",
+		"prettier": "^3.3.3",
+		"rollup": "^3.0.0",
+		"rollup-plugin-copy": "^3.5.0",
+		"rollup-plugin-postcss": "^4.0.2",
+		"rollup-plugin-serve": "^1.1.1",
+		"sass": "^1.86.3"
+	}
+}

package/src/cart-progress-bar.js

@@ -0,0 +1,348 @@
+import './cart-progress-bar.scss';
+
+/**
+ * ProgressBar helper class for the visual progress bar element
+ */
+class ProgressBar extends HTMLElement {
+	constructor() {
+		super();
+		this.#setupProgressBar();
+	}
+
+	#setupProgressBar() {
+		this.setAttribute('role', 'progressbar');
+		this.setAttribute('aria-valuemin', '0');
+		this.setAttribute('aria-valuemax', '100');
+		this.setAttribute('aria-valuenow', '0');
+
+		// Create the visual progress bar
+		this.innerHTML = '<div class="progress-bar-fill"></div>';
+	}
+
+	setPercent(percent) {
+		const clampedPercent = Math.max(0, Math.min(100, percent));
+		this.style.setProperty('--cart-progress-percent', `${clampedPercent}%`);
+		this.setAttribute('aria-valuenow', clampedPercent);
+	}
+}
+
+// Define ProgressBar custom element immediately so it's available for CartProgressBar
+customElements.define('progress-bar', ProgressBar);
+
+/**
+ * CartProgressBar main component
+ */
+class CartProgressBar extends HTMLElement {
+	// Private fields
+	#minAmount = 0;
+	#currentAmount = 0;
+	#progressPercent = 0;
+	#originalAboveMessage = '';
+	#originalBelowMessage = '';
+	#progressBar = null;
+	#messageElement = null;
+
+	/**
+	 * Define which attributes should be observed for changes
+	 */
+	static get observedAttributes() {
+		return ['threshold', 'current', 'message-above', 'message-below'];
+	}
+
+	constructor() {
+		super();
+		this.#init();
+	}
+
+	#init() {
+		// Read initial attributes
+		this.#minAmount = parseFloat(this.getAttribute('threshold')) || 0;
+		this.#currentAmount = parseFloat(this.getAttribute('current')) || 0;
+
+		// Store original message templates
+		this.#originalAboveMessage = this.getAttribute('message-above') || '';
+		this.#originalBelowMessage = this.getAttribute('message-below') || '';
+	}
+
+	async connectedCallback() {
+		// ensure the child custom element has been registered
+		await customElements.whenDefined('progress-bar');
+
+		if (!customElements.get('progress-bar')) {
+			throw new Error('<progress-bar> must be registered before <cart-progress-bar> runs');
+		}
+
+		this.#render();
+		this.#updateProgress();
+		this.#attachListeners();
+	}
+
+	attributeChangedCallback(name, oldValue, newValue) {
+		if (oldValue === newValue) return;
+
+		switch (name) {
+			case 'threshold':
+				this.#minAmount = parseFloat(newValue) || 0;
+				this.#updateProgress();
+				break;
+			case 'current':
+				this.#currentAmount = parseFloat(newValue) || 0;
+				this.#updateProgress();
+				break;
+			case 'message-above':
+				this.#originalAboveMessage = newValue || '';
+				this.#updateMessages();
+				break;
+			case 'message-below':
+				this.#originalBelowMessage = newValue || '';
+				this.#updateMessages();
+				break;
+		}
+	}
+
+	#render() {
+		// Find or create the message element
+		this.#messageElement =
+			this.querySelector('[data-content-cart-progress-message]') ||
+			this.querySelector('p[data-content-cart-progress-message]');
+
+		// Find existing progress bar (user can add their own)
+		this.#progressBar = this.querySelector('progress-bar');
+
+		// Create message element if it doesn't exist but we have message templates
+		if (!this.#messageElement && (this.#originalAboveMessage || this.#originalBelowMessage)) {
+			this.#messageElement = document.createElement('p');
+			this.#messageElement.setAttribute('data-content-cart-progress-message', '');
+			this.appendChild(this.#messageElement);
+		}
+
+		// Create progress bar if it doesn't exist - add it at the end (below text message)
+		if (!this.#progressBar) {
+			// Ensure progress-bar is defined before creating
+			if (customElements.get('progress-bar')) {
+				this.#progressBar = document.createElement('progress-bar');
+				this.appendChild(this.#progressBar);
+			} else {
+				// Fallback: wait for definition
+				customElements.whenDefined('progress-bar').then(() => {
+					if (!this.#progressBar) {
+						this.#progressBar = document.createElement('progress-bar');
+						this.appendChild(this.#progressBar);
+						this.#updateProgress(); // Update progress after creating
+					}
+				});
+			}
+		}
+	}
+
+	#updateProgress() {
+		if (this.#minAmount === 0) {
+			this.#progressPercent = 100;
+		} else {
+			this.#progressPercent = Math.min(100, (this.#currentAmount / this.#minAmount) * 100);
+		}
+
+		// Update progress bar
+		if (this.#progressBar) {
+			this.#progressBar.setPercent(this.#progressPercent);
+		}
+
+		// Update messages
+		this.#updateMessages();
+
+		// Update component state
+		this.#updateComponentState();
+	}
+
+	#attachListeners() {
+		// Find the nearest cart-panel component
+		const cartPanel = this.closest('cart-panel');
+
+		if (cartPanel) {
+			// Listen for cart data changes
+			cartPanel.addEventListener('cart-dialog:data-changed', (event) => {
+				this.#handleCartDataChange(event);
+			});
+		}
+	}
+
+	#handleCartDataChange(event) {
+		const updatedCart = event.detail;
+
+		if (updatedCart && typeof updatedCart.total_price !== 'undefined') {
+			// Convert from cents to dollars if needed (Shopify typically returns cents)
+			const currentAmount = updatedCart.total_price / 100;
+			this.setCurrentAmount(currentAmount);
+		}
+	}
+
+	#updateMessages() {
+		const isComplete = this.#currentAmount >= this.#minAmount;
+		const remainingAmount = Math.max(0, this.#minAmount - this.#currentAmount);
+
+		// Format remaining amount as currency (assuming USD for now)
+		const formattedAmount = this.#formatCurrency(remainingAmount);
+
+		// Update the single message element
+		if (this.#messageElement) {
+			let messageTemplate;
+
+			if (isComplete && this.#originalAboveMessage) {
+				// Show success message when complete
+				messageTemplate = this.#originalAboveMessage;
+			} else if (!isComplete) {
+				// Show progress message when incomplete
+				messageTemplate = this.#originalBelowMessage || this.#originalAboveMessage;
+			}
+
+			if (messageTemplate) {
+				const message = messageTemplate.replace(/\$\{left\}/g, formattedAmount);
+				this.#messageElement.textContent = message;
+				this.#messageElement.style.display = 'block';
+			} else {
+				// Hide message if no template available for current state
+				this.#messageElement.style.display = 'none';
+			}
+		}
+	}
+
+	#updateComponentState() {
+		const isComplete = this.#currentAmount >= this.#minAmount;
+
+		if (isComplete) {
+			this.setAttribute('data-complete', 'true');
+			this.removeAttribute('data-incomplete');
+		} else {
+			this.setAttribute('data-incomplete', 'true');
+			this.removeAttribute('data-complete');
+		}
+
+		// Set progress level classes for styling
+		this.classList.remove('progress-low', 'progress-medium', 'progress-high', 'progress-complete');
+
+		if (isComplete) {
+			this.classList.add('progress-complete');
+		} else if (this.#progressPercent >= 75) {
+			this.classList.add('progress-high');
+		} else if (this.#progressPercent >= 50) {
+			this.classList.add('progress-medium');
+		} else {
+			this.classList.add('progress-low');
+		}
+	}
+
+	#formatCurrency(amount) {
+		// Basic currency formatting - could be enhanced with locale/currency options
+		return new Intl.NumberFormat('en-US', {
+			style: 'currency',
+			currency: 'USD',
+			minimumFractionDigits: 2,
+			maximumFractionDigits: 2,
+		}).format(amount);
+	}
+
+	/**
+	 * Public API: Set the progress percentage directly
+	 * @param {number} percent - Progress percentage (0-100)
+	 */
+	setPercent(percent) {
+		const clampedPercent = Math.max(0, Math.min(100, percent));
+		this.#progressPercent = clampedPercent;
+
+		if (this.#progressBar) {
+			this.#progressBar.setPercent(clampedPercent);
+		}
+
+		// Calculate current amount based on percentage
+		this.#currentAmount = (clampedPercent / 100) * this.#minAmount;
+		this.setAttribute('current', this.#currentAmount.toString());
+
+		this.#updateMessages();
+		this.#updateComponentState();
+	}
+
+	/**
+	 * Public API: Set the current cart amount
+	 * @param {number} amount - Current cart amount
+	 */
+	setCurrentAmount(amount) {
+		this.#currentAmount = parseFloat(amount) || 0;
+		this.setAttribute('current', this.#currentAmount.toString());
+		this.#updateProgress();
+	}
+
+	/**
+	 * Public API: Set the threshold amount for free shipping
+	 * @param {number} amount - Threshold amount for free shipping
+	 */
+	setThresholdAmount(amount) {
+		this.#minAmount = parseFloat(amount) || 0;
+		this.setAttribute('threshold', this.#minAmount.toString());
+		this.#updateProgress();
+	}
+
+	/**
+	 * Public API: Set the minimum amount for free shipping (deprecated - use setThresholdAmount)
+	 * @param {number} amount - Minimum amount threshold
+	 * @deprecated Use setThresholdAmount instead
+	 */
+	setMinAmount(amount) {
+		this.setThresholdAmount(amount);
+	}
+
+	/**
+	 * Public API: Get current progress information
+	 */
+	getProgress() {
+		return {
+			currentAmount: this.#currentAmount,
+			thresholdAmount: this.#minAmount,
+			minAmount: this.#minAmount, // backwards compatibility
+			remainingAmount: Math.max(0, this.#minAmount - this.#currentAmount),
+			percent: this.#progressPercent,
+			isComplete: this.#currentAmount >= this.#minAmount,
+		};
+	}
+
+	/**
+	 * Public API: Update message templates
+	 * @param {string} aboveMessage - Message template for above the bar
+	 * @param {string} belowMessage - Message template for below the bar
+	 */
+	setMessages(aboveMessage = null, belowMessage = null) {
+		if (aboveMessage !== null) {
+			this.#originalAboveMessage = aboveMessage;
+			this.setAttribute('message-above', aboveMessage);
+		}
+
+		if (belowMessage !== null) {
+			this.#originalBelowMessage = belowMessage;
+			this.setAttribute('message-below', belowMessage);
+		}
+
+		this.#updateMessages();
+	}
+
+	// Getters
+	get currentAmount() {
+		return this.#currentAmount;
+	}
+	get thresholdAmount() {
+		return this.#minAmount;
+	}
+	get minAmount() {
+		return this.#minAmount;
+	} // backwards compatibility
+	get percent() {
+		return this.#progressPercent;
+	}
+	get isComplete() {
+		return this.#currentAmount >= this.#minAmount;
+	}
+}
+
+// Define CartProgressBar custom element
+customElements.define('cart-progress-bar', CartProgressBar);
+
+// Export components for external use
+export { CartProgressBar, ProgressBar };

package/src/cart-progress-bar.scss

@@ -0,0 +1,202 @@
+// SCSS Variables (can be overridden before import)
+$cart-progress-bar-height: 12px !default;
+$cart-progress-bar-border-radius: 6px !default;
+$cart-progress-bar-bg: #e9ecef !default;
+$cart-progress-bar-fill-bg: #28a745 !default;
+$cart-progress-bar-complete-bg: #007bff !default;
+$cart-progress-bar-shadow: inset 0 1px 2px rgba(0, 0, 0, 0.1) !default;
+$cart-progress-bar-transition-duration: 0.3s !default;
+
+// Message styling
+$cart-progress-message-font-size: 0.875rem !default;
+$cart-progress-message-line-height: 1.4 !default;
+$cart-progress-message-color: #495057 !default;
+$cart-progress-message-complete-color: #155724 !default;
+$cart-progress-message-margin: 0.5rem !default;
+
+// Responsive breakpoints
+$cart-progress-mobile-breakpoint: 768px !default;
+
+// Cart progress bar component styles
+cart-progress-bar {
+	// CSS Custom Properties for customization (mapped from SCSS variables)
+	--cart-progress-bar-height: #{$cart-progress-bar-height};
+	--cart-progress-bar-border-radius: #{$cart-progress-bar-border-radius};
+	--cart-progress-bar-bg: #{$cart-progress-bar-bg};
+	--cart-progress-bar-fill-bg: #{$cart-progress-bar-fill-bg};
+	--cart-progress-bar-complete-bg: #{$cart-progress-bar-complete-bg};
+	--cart-progress-bar-shadow: #{$cart-progress-bar-shadow};
+	--cart-progress-bar-transition-duration: #{$cart-progress-bar-transition-duration};
+	--cart-progress-message-font-size: #{$cart-progress-message-font-size};
+	--cart-progress-message-line-height: #{$cart-progress-message-line-height};
+	--cart-progress-message-color: #{$cart-progress-message-color};
+	--cart-progress-message-complete-color: #{$cart-progress-message-complete-color};
+	--cart-progress-message-margin: #{$cart-progress-message-margin};
+
+	// Dynamic progress percentage (set by JavaScript)
+	--cart-progress-percent: 0%;
+
+	display: block;
+	width: 100%;
+	max-width: 100%;
+
+	// Message styling
+	p[data-content-cart-progress-message] {
+		font-size: var(--cart-progress-message-font-size);
+		line-height: var(--cart-progress-message-line-height);
+		color: var(--cart-progress-message-color);
+		margin: var(--cart-progress-message-margin) 0;
+		text-align: center;
+		transition: color var(--cart-progress-bar-transition-duration) ease;
+
+		@media (max-width: $cart-progress-mobile-breakpoint) {
+			font-size: calc(var(--cart-progress-message-font-size) * 0.9);
+			margin: calc(var(--cart-progress-message-margin) * 0.75) 0;
+		}
+	}
+
+	// State-based styling
+	&[data-complete='true'] {
+		p[data-content-cart-progress-message] {
+			color: var(--cart-progress-message-complete-color);
+			font-weight: 600;
+		}
+	}
+
+	// Progress level classes for additional styling hooks
+	&.progress-low {
+		--cart-progress-bar-fill-bg: #dc3545; // red for low progress
+	}
+
+	&.progress-medium {
+		--cart-progress-bar-fill-bg: #ffc107; // yellow for medium progress
+	}
+
+	&.progress-high {
+		--cart-progress-bar-fill-bg: #fd7e14; // orange for high progress
+	}
+
+	&.progress-complete {
+		--cart-progress-bar-fill-bg: var(--cart-progress-bar-complete-bg);
+
+		p[data-content-cart-progress-message] {
+			color: var(--cart-progress-message-complete-color);
+		}
+	}
+}
+
+// Progress bar component styles
+progress-bar {
+	display: block;
+	width: 100%;
+	height: var(--cart-progress-bar-height);
+	background-color: var(--cart-progress-bar-bg);
+	border-radius: var(--cart-progress-bar-border-radius);
+	box-shadow: var(--cart-progress-bar-shadow);
+	overflow: hidden;
+	position: relative;
+
+	.progress-bar-fill {
+		height: 100%;
+		width: var(--cart-progress-percent);
+		background-color: var(--cart-progress-bar-fill-bg);
+		border-radius: var(--cart-progress-bar-border-radius);
+		transition:
+			width var(--cart-progress-bar-transition-duration) ease,
+			background-color var(--cart-progress-bar-transition-duration) ease;
+		position: relative;
+
+		// Subtle gradient effect
+		background-image: linear-gradient(
+			45deg,
+			rgba(255, 255, 255, 0.1) 25%,
+			transparent 25%,
+			transparent 50%,
+			rgba(255, 255, 255, 0.1) 50%,
+			rgba(255, 255, 255, 0.1) 75%,
+			transparent 75%,
+			transparent
+		);
+		background-size: 12px 12px;
+
+		// Shine effect for completed state
+		&::after {
+			content: '';
+			position: absolute;
+			top: 0;
+			left: -100%;
+			width: 100%;
+			height: 100%;
+			background: linear-gradient(90deg, transparent, rgba(255, 255, 255, 0.4), transparent);
+			transition: left 0.5s ease;
+		}
+	}
+
+	// Animate shine effect when complete
+	cart-progress-bar[data-complete='true'] &,
+	cart-progress-bar.progress-complete & {
+		.progress-bar-fill::after {
+			left: 100%;
+		}
+	}
+
+	// Accessibility improvements
+	&:focus-visible {
+		outline: 2px solid #007bff;
+		outline-offset: 2px;
+	}
+
+	// High contrast mode support
+	@media (prefers-contrast: high) {
+		--cart-progress-bar-bg: #000000;
+		--cart-progress-bar-fill-bg: #ffffff;
+		border: 1px solid #ffffff;
+	}
+
+	// Reduced motion support
+	@media (prefers-reduced-motion: reduce) {
+		.progress-bar-fill {
+			transition: none;
+		}
+
+		.progress-bar-fill::after {
+			transition: none;
+		}
+	}
+}
+
+// Responsive adjustments
+@media (max-width: $cart-progress-mobile-breakpoint) {
+	cart-progress-bar {
+		--cart-progress-bar-height: 10px;
+		--cart-progress-message-margin: 0.375rem;
+	}
+}
+
+// Dark mode support
+@media (prefers-color-scheme: dark) {
+	cart-progress-bar {
+		--cart-progress-bar-bg: #343a40;
+		--cart-progress-message-color: #e9ecef;
+		--cart-progress-message-complete-color: #28a745;
+	}
+}
+
+// Print styles
+@media print {
+	cart-progress-bar {
+		.above-message,
+		.below-message {
+			color: #000000 !important;
+		}
+
+		progress-bar {
+			border: 1px solid #000000;
+
+			.progress-bar-fill {
+				background-color: #000000 !important;
+				background-image: none !important;
+			}
+		}
+	}
+}