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

package/README.md

@@ -2,7 +2,7 @@
 
 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
 
@@ -11,7 +11,7 @@ A powerful, e-commerce web component for automatic gift-with-purchase threshold
 - 📱 **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,12 +20,36 @@ 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!"
@@ -41,10 +65,6 @@ 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-panel>` component from the `@magic-spells/cart-panel` package:
@@ -108,7 +128,7 @@ console.log(gwp.isDisabled);        // boolean - promo ended OR product unavaila
 | Attribute       | Description                                                          | Example                                                      |
 | --------------- | -------------------------------------------------------------------- | ------------------------------------------------------------ |
 | `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"`                                                    |
+| `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"`                                                     |
@@ -235,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'
 });
 ```
 
@@ -250,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;
 }
 ```
 
@@ -278,7 +298,9 @@ The component automatically applies a `state` attribute based on its current con
 - `state="ended"` - Promo ended (component hidden)
 - `state="disabled"` - Gift unavailable (component hidden)
 
-Note: `ended` and `disabled` both hide the component while still removing any existing gift items.
+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
 
@@ -287,8 +309,8 @@ Note: `ended` and `disabled` both hide the component while still removing any ex
 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
 
@@ -383,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;
 	}
 }
 ```
@@ -397,9 +419,9 @@ 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 {
@@ -420,6 +442,24 @@ interface GiftWithPurchaseState {
 // 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,39 +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] {
-  display: none;
-}
-gift-with-purchase[state=disabled] {
+
+gift-with-purchase[state="ended"], gift-with-purchase[state="disabled"] {
   display: none;
 }
-/*# sourceMappingURL=gift-with-purchase.cjs.css.map */
+/*$vite$:1*/