@magic-spells/gift-with-purchase 0.2.0 → 1.0.0

package/README.md

@@ -8,7 +8,7 @@ A powerful, e-commerce web component for automatic gift-with-purchase threshold
 
 - 🎁 **Automatic Gift Management** - Adds/removes gifts based on cart thresholds using smart pricing logic
 - 🛒 **Shopify Integration** - Built-in Cart API support with proper line item properties
-- 📱 **Cart Panel Sync** - Automatically syncs with cart-dialog components using `calculated_subtotal`
+- 📱 **Cart Panel Sync** - Automatically syncs with cart-panel components using `calculated_subtotal`
 - 🎨 **Highly Customizable** - CSS custom properties and swappable content elements
 - ⚡ **Event-Driven** - Custom events for gift addition, removal, and errors
 - 🔧 **Flexible Content** - Data attributes for dynamic image, title, and variant updates
@@ -27,8 +27,9 @@ npm install @magic-spells/gift-with-purchase
 	threshold="75.00"
 	current="45.00"
 	variant-id="12345678"
+	money-format="${{amount}}"
 	message-above="🎉 Congratulations! You've qualified for your FREE gift!"
-	message-below="Add ${ amount } more to unlock your free gift! 🎁">
+	message-below="Add [amount] more to unlock your free gift! 🎁">
 	<div class="gwp-product">
 		<img src="gift-image.jpg" alt="Free Gift" />
 		<div class="gwp-content">
@@ -46,21 +47,22 @@ npm install @magic-spells/gift-with-purchase
 
 ## Cart Integration
 
-The component automatically listens for cart data changes when placed inside a `<cart-dialog>` component from the `@magic-spells/cart-panel` package:
+The component automatically listens for cart data changes when placed inside a `<cart-panel>` component from the `@magic-spells/cart-panel` package:
 
-```html
-<cart-dialog>
+```liquid
+<cart-panel>
 	<gift-with-purchase
 		threshold="75.00"
 		variant-id="12345678"
+		money-format={{ shop.money_format | json }}
 		message-above="🎉 Congratulations! You've qualified for your FREE gift!"
-		message-below="Add ${ amount } more to unlock your free gift! 🎁">
+		message-below="Add [amount] more to unlock your free gift! 🎁">
 		<!-- Gift content -->
 	</gift-with-purchase>
-</cart-dialog>
+</cart-panel>
 ```
 
-When the cart-dialog emits a `cart-dialog:data-changed` event (typically from Shopify cart updates), the gift component will automatically:
+When the cart-panel emits a `cart-panel:data-changed` event (typically from Shopify cart updates), the gift component will automatically:
 
 - Update the current cart amount using `calculated_subtotal` for accurate threshold calculation
 - Check if the threshold is met (excludes other gifts and honors pricing exclusions)
@@ -73,42 +75,74 @@ The component uses intelligent threshold calculation:
 - **Uses `calculated_subtotal`** from cart-panel which properly handles item exclusions
 - **Excludes gifts**: Other gifts with purchase won't count toward this threshold
 - **Includes bundle items**: Hidden bundle components that should count are included
-- **Backwards compatible**: Falls back to `total_price` if `calculated_subtotal` unavailable
+- **Multi-currency support**: Automatically converts threshold using `Shopify.currency.rate` for stores with multiple currencies
+- **Requires cart-panel**: The component requires `calculated_subtotal` in cart events to function
 
 ## JavaScript API
 
 ```javascript
 const gwp = document.querySelector('gift-with-purchase');
 
-// Update cart amount
+// Setters - update state programmatically
 gwp.setCurrentAmount(85.5);
-
-// Change threshold
 gwp.setThreshold(100.0);
-
-// Update variant ID
 gwp.setVariantId('87654321');
 
-// Get current state
+// Get full state object
 const state = gwp.getState();
 console.log(state.isActive, state.isAdded, state.remainingAmount);
 
-// Manual message updates (component handles this automatically)
-const messageEl = gwp.querySelector('[data-content-gwp-message]');
-if (messageEl) {
-	messageEl.textContent = 'Custom message';
-}
+// Readonly getters - access individual properties
+console.log(gwp.currentAmount);     // number - current cart amount
+console.log(gwp.threshold);         // number - threshold amount
+console.log(gwp.variantId);         // string - gift variant ID
+console.log(gwp.isActive);          // boolean - threshold met
+console.log(gwp.isAdded);           // boolean - gift in cart
+console.log(gwp.promoEnded);        // boolean - promo has ended
+console.log(gwp.productAvailable);  // boolean - gift product available
+console.log(gwp.isDisabled);        // boolean - promo ended OR product unavailable
 ```
 
 ## Attributes
 
 | Attribute       | Description                                                          | Example                                                      |
 | --------------- | -------------------------------------------------------------------- | ------------------------------------------------------------ |
-| `threshold`     | Spending threshold to unlock the gift                                | `"75.00"`                                                    |
-| `current`       | Current cart amount                                                  | `"45.00"`                                                    |
+| `threshold`     | Spending threshold to unlock the gift (auto-converts for multi-currency) | `"75.00"`                                                    |
+| `current`       | Current cart amount (typically set automatically via cart-panel)     | `"45.00"`                                                    |
 | `variant-id`    | Shopify variant ID for the gift product                              | `"12345678"`                                                 |
+| `promo-ended`   | Disables the promo and hides the component                           | `"true"`                                                     |
+| `product-available` | Whether the gift product is available (disables if false)        | `"true"`                                                     |
 | `message-above` | Message shown when threshold is met                                  | `"🎉 Congratulations! You've qualified for your FREE gift!"` |
-| `message-below` | Message shown when below threshold (uses `{ amount }` placeholder) | `"Add ${ amount } more to unlock your free gift! 🎁"`      |
+| `message-below` | Message shown below threshold; use `[amount]` for remaining amount   | `"Add [amount] more to unlock your free gift! 🎁"`           |
+| `money-format`  | Shopify-style money format for currency display                      | `"${{amount}}"`                                              |
+
+### The `[amount]` Placeholder
+
+In the `message-below` attribute, use `[amount]` (with square brackets) to insert the remaining amount needed to reach the threshold. The component automatically:
+
+- Calculates the remaining amount (`threshold - currentAmount`)
+- Converts to the customer's currency using `Shopify.currency.rate`
+- Formats using your `money-format` attribute
+
+```html
+<!-- Example: If threshold is $75 and cart is $45, displays "Add $30 more..." -->
+<gift-with-purchase
+	threshold="75.00"
+	money-format="${{amount}}"
+	message-below="Add [amount] more to unlock your free gift!">
+</gift-with-purchase>
+```
+
+**Why square brackets?** We use `[amount]` instead of `{{amount}}` to avoid conflicts with Shopify Liquid templates and JavaScript template literals.
+
+### Multi-Currency Support
+
+The component automatically handles currency conversion for multi-currency Shopify stores:
+
+- Set `threshold` in your store's **base currency** (e.g., USD)
+- The component reads `Shopify.currency.rate` from the browser
+- Threshold is automatically converted to the customer's selected currency
+- The `[amount]` placeholder displays in the converted currency
 
 ## Message Element
 
@@ -127,6 +161,62 @@ The component requires a message element to display threshold messages:
 </gift-with-purchase>
 ```
 
+## Currency Formatting
+
+Use the `money-format` attribute to format amounts with the correct currency symbol and formatting:
+
+```html
+<gift-with-purchase
+	threshold="75.00"
+	variant-id="12345678"
+	money-format="${{amount}}"
+	message-below="Add [amount] more to unlock your free gift!">
+	<!-- Gift content -->
+</gift-with-purchase>
+```
+
+In Shopify themes, you can pass the shop's money format using the `json` filter:
+
+```liquid
+<gift-with-purchase
+	threshold="75.00"
+	variant-id="12345678"
+	money-format={{ shop.money_format | json }}
+	message-below="Add [amount] more to unlock your free gift!">
+	<!-- Gift content -->
+</gift-with-purchase>
+```
+
+Available Shopify money formats:
+- `shop.money_format` - Basic format (e.g., `${{amount}}`)
+- `shop.money_with_currency_format` - With currency code (e.g., `${{amount}} USD`)
+
+### Supported Format Placeholders
+
+| Placeholder | Output | Example |
+| ----------- | ------ | ------- |
+| `{{amount}}` | Amount with decimals | `19.99` |
+| `{{amount_no_decimals}}` | Rounded whole number | `20` |
+| `{{amount_with_comma_separator}}` | Comma as decimal | `19,99` |
+| `{{amount_no_decimals_with_comma_separator}}` | Whole with comma thousands | `1,000` |
+
+### Examples by Currency
+
+```html
+<!-- USD -->
+money-format="${{amount}}"         <!-- $30.00 -->
+
+<!-- EUR -->
+money-format="€{{amount}}"         <!-- €30.00 -->
+money-format="{{amount}} €"        <!-- 30.00 € -->
+
+<!-- GBP -->
+money-format="£{{amount}}"         <!-- £30.00 -->
+
+<!-- JPY (no decimals) -->
+money-format="¥{{amount_no_decimals}}"  <!-- ¥3000 -->
+```
+
 ## Events
 
 The component emits custom events for integration:
@@ -184,9 +274,11 @@ The component automatically applies a `state` attribute based on its current con
 
 - `state="active"` - Threshold met, gift available to add
 - `state="added"` - Gift successfully added to cart
+- `state="inactive"` - Below threshold (component idle)
 - `state="ended"` - Promo ended (component hidden)
+- `state="disabled"` - Gift unavailable (component hidden)
 
-Note: There is no `inactive` state since the component would typically not be loaded at all when below threshold in most Shopify implementations.
+Note: `ended` and `disabled` both hide the component while still removing any existing gift items.
 
 ## Shopify Integration Details
 
@@ -248,7 +340,7 @@ In your Shopify cart template, you can identify and handle gift items:
 	threshold="50.00"
 	variant-id="111111"
 	message-above="🎉 You've unlocked a free tote bag!"
-	message-below="Add ${ amount } more for a free tote bag! 👜">
+	message-below="Add [amount] more for a free tote bag! 👜">
 	<div class="gwp-product">
 		<img src="tote-bag.jpg" alt="Free Tote Bag" />
 		<h4 class="gwp-title">Free Tote Bag</h4>
@@ -261,7 +353,7 @@ In your Shopify cart template, you can identify and handle gift items:
 	threshold="100.00"
 	variant-id="222222"
 	message-above="✨ Amazing! You've earned our premium gift set!"
-	message-below="Spend ${ amount } more for our exclusive premium gift set! ✨">
+	message-below="Spend [amount] more for our exclusive premium gift set! ✨">
 	<div class="gwp-product">
 		<img src="gift-set.jpg" alt="Premium Gift Set" />
 		<h4 class="gwp-title">Premium Gift Set</h4>
@@ -313,10 +405,15 @@ Type definitions are included in the package:
 interface GiftWithPurchaseState {
 	currentAmount: number;
 	threshold: number;
+	convertedThreshold: number;
 	variantId: string | null;
 	isActive: boolean;
 	isAdded: boolean;
+	promoEnded: boolean;
+	productAvailable: boolean;
+	isDisabled: boolean;
 	remainingAmount: number;
+	currencyRate: number;
 }
 
 // Component automatically handles message injection

package/dist/gift-with-purchase.cjs.css

@@ -40,4 +40,7 @@ gift-with-purchase[state=added] {
 gift-with-purchase[state=ended] {
   display: none;
 }
+gift-with-purchase[state=disabled] {
+  display: none;
+}
 /*# sourceMappingURL=gift-with-purchase.cjs.css.map */

package/dist/gift-with-purchase.cjs.css.map

@@ -1 +1 @@
-{"version":3,"sources":["gift-with-purchase.scss"],"names":[],"mappings":"AAAA;EACE,wBAAwB;EACxB,mBAAmB;EACnB,eAAe;EACf,wBAAwB;EACxB,uBAAuB;EACvB,4BAA4B;EAC5B,2BAA2B;EAC3B,0BAA0B;EAC1B,yBAAyB;EACzB,cAAc;EACd,0CAA0C;EAC1C,uCAAuC;EACvC,2BAA2B;EAC3B,sCAAsC;EACtC,6BAA6B;AAC/B;AACA;EACE,aAAa;EACb,uBAAuB;EACvB,mBAAmB;AACrB;AACA;EACE,cAAc;AAChB;AACA;EACE,OAAO;EACP,YAAY;AACd;AACA;EACE,sCAAsC;EACtC,sCAAsC;EACtC,6BAA6B;AAC/B;AACA;EACE,qCAAqC;EACrC,qCAAqC;EACrC,4BAA4B;AAC9B;AACA;EACE,aAAa;AACf","file":"gift-with-purchase.cjs.css","sourcesContent":["gift-with-purchase {\n  --gwp-border-radius: 8px;\n  --gwp-padding: 1rem;\n  --gwp-gap: 1rem;\n  --gwp-bg-active: #e8f5e8;\n  --gwp-bg-added: #d4edda;\n  --gwp-border-active: #28a745;\n  --gwp-border-added: #155724;\n  --gwp-text-active: #155724;\n  --gwp-text-added: #155724;\n  display: block;\n  border: 2px solid var(--gwp-border-active);\n  border-radius: var(--gwp-border-radius);\n  padding: var(--gwp-padding);\n  background-color: var(--gwp-bg-active);\n  color: var(--gwp-text-active);\n}\ngift-with-purchase .gwp-product {\n  display: flex;\n  align-items: flex-start;\n  gap: var(--gwp-gap);\n}\ngift-with-purchase [data-gwp-image] {\n  flex-shrink: 0;\n}\ngift-with-purchase .gwp-content {\n  flex: 1;\n  min-width: 0;\n}\ngift-with-purchase[state=active] {\n  background-color: var(--gwp-bg-active);\n  border-color: var(--gwp-border-active);\n  color: var(--gwp-text-active);\n}\ngift-with-purchase[state=added] {\n  background-color: var(--gwp-bg-added);\n  border-color: var(--gwp-border-added);\n  color: var(--gwp-text-added);\n}\ngift-with-purchase[state=ended] {\n  display: none;\n}"]}
+{"version":3,"sources":["gift-with-purchase.scss"],"names":[],"mappings":"AAAA;EACE,wBAAwB;EACxB,mBAAmB;EACnB,eAAe;EACf,wBAAwB;EACxB,uBAAuB;EACvB,4BAA4B;EAC5B,2BAA2B;EAC3B,0BAA0B;EAC1B,yBAAyB;EACzB,cAAc;EACd,0CAA0C;EAC1C,uCAAuC;EACvC,2BAA2B;EAC3B,sCAAsC;EACtC,6BAA6B;AAC/B;AACA;EACE,aAAa;EACb,uBAAuB;EACvB,mBAAmB;AACrB;AACA;EACE,cAAc;AAChB;AACA;EACE,OAAO;EACP,YAAY;AACd;AACA;EACE,sCAAsC;EACtC,sCAAsC;EACtC,6BAA6B;AAC/B;AACA;EACE,qCAAqC;EACrC,qCAAqC;EACrC,4BAA4B;AAC9B;AACA;EACE,aAAa;AACf;AACA;EACE,aAAa;AACf","file":"gift-with-purchase.cjs.css","sourcesContent":["gift-with-purchase {\n  --gwp-border-radius: 8px;\n  --gwp-padding: 1rem;\n  --gwp-gap: 1rem;\n  --gwp-bg-active: #e8f5e8;\n  --gwp-bg-added: #d4edda;\n  --gwp-border-active: #28a745;\n  --gwp-border-added: #155724;\n  --gwp-text-active: #155724;\n  --gwp-text-added: #155724;\n  display: block;\n  border: 2px solid var(--gwp-border-active);\n  border-radius: var(--gwp-border-radius);\n  padding: var(--gwp-padding);\n  background-color: var(--gwp-bg-active);\n  color: var(--gwp-text-active);\n}\ngift-with-purchase .gwp-product {\n  display: flex;\n  align-items: flex-start;\n  gap: var(--gwp-gap);\n}\ngift-with-purchase [data-gwp-image] {\n  flex-shrink: 0;\n}\ngift-with-purchase .gwp-content {\n  flex: 1;\n  min-width: 0;\n}\ngift-with-purchase[state=active] {\n  background-color: var(--gwp-bg-active);\n  border-color: var(--gwp-border-active);\n  color: var(--gwp-text-active);\n}\ngift-with-purchase[state=added] {\n  background-color: var(--gwp-bg-added);\n  border-color: var(--gwp-border-added);\n  color: var(--gwp-text-added);\n}\ngift-with-purchase[state=ended] {\n  display: none;\n}\ngift-with-purchase[state=disabled] {\n  display: none;\n}"]}