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

package/README.md

@@ -2,16 +2,16 @@
 
 A powerful, e-commerce web component for automatic gift-with-purchase threshold promotions. Seamlessly integrates with Shopify and automatically manages gift items in the cart based on spending thresholds.
 
-[**Live Demo**](https://magic-spells.github.io/gift-with-purchase/demo/)
+[**Live Demo**](https://magic-spells.github.io/cart/)
 
 ## Features
 
 - 🎁 **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
+- 🔧 **Flexible Content** - Your own markup inside the element; the component only writes the `[data-content-gwp-message]` element
 - 📱 **Responsive** - Mobile-optimized with responsive design
 
 ## Installation
@@ -20,15 +20,40 @@ A powerful, e-commerce web component for automatic gift-with-purchase threshold
 npm install @magic-spells/gift-with-purchase
 ```
 
+The package is ESM-only. Import it once, anywhere in your bundle, to register the custom element:
+
+```javascript
+import '@magic-spells/gift-with-purchase';
+```
+
+The CSS is shipped as a separate file rather than injected, so load it too:
+
+```css
+/* unminified */
+@import '@magic-spells/gift-with-purchase/css';
+
+/* or minified */
+@import '@magic-spells/gift-with-purchase/css/min';
+```
+
+Without a bundler, use the UMD build (exposes the `GiftWithPurchase` global):
+
+```html
+<link
+	rel="stylesheet"
+	href="https://unpkg.com/@magic-spells/gift-with-purchase/dist/gift-with-purchase.min.css" />
+<script src="https://unpkg.com/@magic-spells/gift-with-purchase/dist/gift-with-purchase.min.js"></script>
+```
+
 ## Basic Usage
 
 ```html
 <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">
@@ -40,27 +65,24 @@ npm install @magic-spells/gift-with-purchase
 </gift-with-purchase>
 ```
 
-```css
-@import '@magic-spells/gift-with-purchase/css';
-```
-
 ## 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 +95,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`       | Optional starting amount. The component tracks the live cart total internally from `cart-panel:data-changed` and never writes this attribute back, so don't template it from Liquid | `"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 +181,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:
@@ -145,7 +255,7 @@ gwp.addEventListener('gwp:removed', (event) => {
 // Error occurred during add/remove
 gwp.addEventListener('gwp:error', (event) => {
 	console.error('Error:', event.detail.error);
-	console.log('Action:', event.detail.action); // 'add' or 'remove'
+	console.log('Action:', event.detail.action); // 'add', 'remove', or 'trim'
 });
 ```
 
@@ -160,7 +270,7 @@ gift-with-purchase {
 	--gwp-bg-active: #e8f5e8;
 	--gwp-border-active: #28a745;
 	--gwp-text-active: #155724;
-	--gwp-image-size: 80px;
+	--gwp-gap: 1.5rem;
 }
 ```
 
@@ -184,9 +294,13 @@ 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 the gift line for **this**
+component's `variant-id`. Another tier's gift is left alone, so disabling one tier never clears
+another's.
 
 ## Shopify Integration Details
 
@@ -195,8 +309,8 @@ Note: There is no `inactive` state since the component would typically not be lo
 The component uses Shopify's Cart API endpoints:
 
 - `POST /cart/add.js` - Adds the gift to cart
-- `GET /cart.js` - Gets current cart state
-- `POST /cart/change.js` - Removes gift from cart
+- `GET /cart.js` - Gets current cart state (only when the parent cart-panel cannot supply it)
+- `POST /cart/change.js` - Removes the gift line, and trims a doubled gift line back to `quantity: 1`
 
 ### Line Item Properties
 
@@ -248,7 +362,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 +375,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>
@@ -291,9 +405,9 @@ In your Shopify cart template, you can identify and handle gift items:
 /* Compact mobile style */
 @media (max-width: 768px) {
 	gift-with-purchase {
-		--gwp-image-size: 40px;
 		--gwp-padding: 0.5rem;
 		--gwp-gap: 0.5rem;
+		--gwp-border-radius: 4px;
 	}
 }
 ```
@@ -305,24 +419,47 @@ In your Shopify cart template, you can identify and handle gift items:
 - Safari 14+
 - All modern browsers with Custom Elements support
 
-## TypeScript Support
+## State Shape
 
-Type definitions are included in the package:
+`getState()` returns:
 
 ```typescript
 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
 // Style your content and message elements with any CSS classes
 ```
 
+## Development
+
+```bash
+npm run dev    # build to demo/dist/ in watch mode and serve demo/ on http://localhost:3000
+npm run build  # build the published dist/ (ESM, minified UMD, CSS, minified CSS)
+npm run lint   # ESLint over src/ and scripts/
+```
+
+The build is a plain Node script (`scripts/build.mjs`) driving Vite's JS API — there is no
+`vite.config.js`. It emits exactly four files into `dist/`:
+
+| File                          | Format                                  |
+| ----------------------------- | --------------------------------------- |
+| `gift-with-purchase.esm.js`   | ES module (unminified)                  |
+| `gift-with-purchase.min.js`   | UMD, minified, global `GiftWithPurchase` |
+| `gift-with-purchase.css`      | Stylesheet                              |
+| `gift-with-purchase.min.css`  | Stylesheet, minified                    |
+
 ## Contributing
 
 Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

package/dist/{gift-with-purchase.cjs.css → gift-with-purchase.css}

@@ -8,36 +8,42 @@ gift-with-purchase {
   --gwp-border-added: #155724;
   --gwp-text-active: #155724;
   --gwp-text-added: #155724;
-  display: block;
   border: 2px solid var(--gwp-border-active);
   border-radius: var(--gwp-border-radius);
   padding: var(--gwp-padding);
   background-color: var(--gwp-bg-active);
   color: var(--gwp-text-active);
+  display: block;
 }
+
 gift-with-purchase .gwp-product {
-  display: flex;
   align-items: flex-start;
   gap: var(--gwp-gap);
+  display: flex;
 }
+
 gift-with-purchase [data-gwp-image] {
   flex-shrink: 0;
 }
+
 gift-with-purchase .gwp-content {
   flex: 1;
   min-width: 0;
 }
-gift-with-purchase[state=active] {
+
+gift-with-purchase[state="active"] {
   background-color: var(--gwp-bg-active);
   border-color: var(--gwp-border-active);
   color: var(--gwp-text-active);
 }
-gift-with-purchase[state=added] {
+
+gift-with-purchase[state="added"] {
   background-color: var(--gwp-bg-added);
   border-color: var(--gwp-border-added);
   color: var(--gwp-text-added);
 }
-gift-with-purchase[state=ended] {
+
+gift-with-purchase[state="ended"], gift-with-purchase[state="disabled"] {
   display: none;
 }
-/*# sourceMappingURL=gift-with-purchase.cjs.css.map */
+/*$vite$:1*/