@runwell/shopify-toolkit 0.1.0 → 0.3.0

package/modules/quick-view/snippets/runwell-quickview-modal.liquid

@@ -0,0 +1,14 @@
+{%- comment -%}
+  Runwell quick-view modal shell. Render once at end of layout/theme.liquid:
+  {% render 'runwell-quickview-modal' %}
+{%- endcomment -%}
+
+<div class="runwell-quickview" data-runwell-quickview-modal aria-hidden="true" role="dialog" aria-labelledby="runwell-qv-title">
+  <div class="runwell-quickview__backdrop" data-runwell-quickview-close></div>
+  <div class="runwell-quickview__panel">
+    <button class="runwell-quickview__close" type="button" data-runwell-quickview-close aria-label="Close">&times;</button>
+    <div class="runwell-quickview__body" data-runwell-quickview-body></div>
+  </div>
+</div>
+
+<script src="{{ 'runwell-quickview.js' | asset_url }}" defer="defer"></script>

package/modules/quick-view/snippets/runwell-quickview-trigger.liquid

@@ -0,0 +1,19 @@
+{%- comment -%}
+  Runwell quick-view trigger button. Render inside card-product.liquid
+  near the product image:
+
+  {% render 'runwell-quickview-trigger', handle: card_product.handle %}
+{%- endcomment -%}
+
+<button
+  type="button"
+  class="runwell-quickview-trigger"
+  data-runwell-quickview
+  data-handle="{{ handle }}"
+  aria-label="Quick view"
+>
+  <svg viewBox="0 0 24 24" width="18" height="18" aria-hidden="true">
+    <path d="M12 5C7 5 3 12 3 12s4 7 9 7 9-7 9-7-4-7-9-7zm0 11a4 4 0 110-8 4 4 0 010 8z" fill="currentColor"/>
+    <circle cx="12" cy="12" r="2" fill="#FFFFFF"/>
+  </svg>
+</button>

package/modules/subscriptions/README.md

@@ -0,0 +1,37 @@
+# subscriptions
+
+Brand-styled subscribe-and-save picker on top of Shopify's native Selling Plan API. Replaces Recharge / Bold Subscriptions / Appstle / Loop for the storefront display layer. Customer subscription management uses Shopify's native customer account.
+
+## Files
+
+- `snippets/runwell-subscription-picker.liquid`. Radio picker between one-time and subscribe-and-save.
+
+## How to use
+
+1. Run the merchant admin steps in `module.json` (install Shopify's free Subscriptions app, create a Selling Plan Group)
+2. Render the picker in `sections/main-product.liquid` BEFORE the `buy_buttons` block:
+   ```liquid
+   {% render 'runwell-subscription-picker', product: product %}
+   ```
+3. The picker emits a `selling_plan` form input that Dawn's buy-buttons snippet picks up automatically when present
+4. Style `.runwell-sub` selectors in your brand stylesheet
+
+## Config
+
+| Key | Default | Notes |
+|---|---|---|
+| `one_time_label` | `One-time purchase` | Label for the no-subscription option |
+| `subscribe_label` | `Subscribe and save` | Label for the subscription option |
+| `fineprint` | `Cancel anytime. Skip a delivery from your account.` | Microcopy under the picker |
+
+## Why no app
+
+Shopify ships native subscription primitives (Selling Plan API, native customer-account subscription tab) since 2021. The free Shopify Subscriptions app is the canonical UI for managing Selling Plan Groups. We use that for management; this module handles the storefront PDP picker.
+
+## Replaces
+
+Recharge, Bold Subscriptions, Appstle, Loop (display layer only; the management UX is Shopify's native account tab).
+
+## Plan requirement
+
+Works on **Shopify Basic and up**. The free Shopify Subscriptions app is required.

package/modules/subscriptions/module.json

@@ -0,0 +1,36 @@
+{
+  "name": "subscriptions",
+  "version": "0.1.0",
+  "category": "catalog",
+  "description": "Brand-styled subscribe-and-save picker that wraps Shopify's native Selling Plan API. Replaces Recharge / Bold Subscriptions / Appstle for the storefront display layer; subscription management still uses Shopify's native customer account.",
+  "files": {
+    "snippets": ["snippets/runwell-subscription-picker.liquid"]
+  },
+  "config": {
+    "schema": {
+      "one_time_label": { "type": "string", "default": "One-time purchase" },
+      "subscribe_label": { "type": "string", "default": "Subscribe and save" },
+      "fineprint": { "type": "string", "default": "Cancel anytime. Skip a delivery from your account." }
+    }
+  },
+  "admin_steps": [
+    {
+      "id": "install-shopify-subscriptions",
+      "label": "Install Shopify's free Subscriptions app",
+      "url": "https://apps.shopify.com/shopify-subscriptions",
+      "summary": "Install the Subscriptions app made by Shopify (free, first-party). Required to expose Selling Plan Groups."
+    },
+    {
+      "id": "create-selling-plan-group",
+      "label": "Create a Selling Plan Group",
+      "url": "https://admin.shopify.com/store/{store_handle}/apps",
+      "summary": "Apps > Subscriptions > Create plan. Name 'Subscribe and save'. Add delivery options every 30/60/90 days. Apply 15% discount on subscription orders. Apply to selected products."
+    },
+    {
+      "id": "enable-customer-account-tab",
+      "label": "Verify Subscriptions tab on customer account",
+      "url": "https://admin.shopify.com/store/{store_handle}/settings/customer_accounts",
+      "summary": "Settings > Customer accounts > Customize. Confirm the Subscriptions section is enabled. Customers will see skip/cancel/change frequency from /account."
+    }
+  ]
+}

package/modules/subscriptions/snippets/runwell-subscription-picker.liquid

@@ -0,0 +1,35 @@
+{%- comment -%}
+  Runwell subscription picker. Brand-styled radio between one-time and
+  subscribe-and-save when a product has selling_plan_groups configured.
+  Render inside main-product.liquid where the buy buttons live, BEFORE
+  the buy_buttons block:
+
+  {% render 'runwell-subscription-picker', product: product %}
+
+  Requires:
+  - Shopify Subscriptions app installed (free, made by Shopify)
+  - At least one Selling Plan Group attached to the product
+{%- endcomment -%}
+
+{%- if product != blank and product.selling_plan_groups.size > 0 -%}
+  {%- assign group = product.selling_plan_groups[0] -%}
+  <fieldset class="runwell-sub" data-runwell-subscription-picker>
+    <legend class="visually-hidden">Purchase type</legend>
+    <label class="runwell-sub__option">
+      <input type="radio" name="selling_plan" value="" checked>
+      <span class="runwell-sub__title">{{config.one_time_label}}</span>
+      <span class="runwell-sub__price">{{ product.price | money }}</span>
+    </label>
+    {%- for plan in group.selling_plans -%}
+      <label class="runwell-sub__option runwell-sub__option--featured">
+        <input type="radio" name="selling_plan" value="{{ plan.id }}">
+        <span class="runwell-sub__title">
+          {{config.subscribe_label}}
+          <span class="runwell-sub__discount">{{ plan.price_adjustments[0].value }}% off</span>
+        </span>
+        <span class="runwell-sub__detail">{{ plan.name }}</span>
+      </label>
+    {%- endfor -%}
+    <p class="runwell-sub__fineprint">{{config.fineprint}}</p>
+  </fieldset>
+{%- endif -%}

package/modules/wishlist/README.md

@@ -0,0 +1,48 @@
+# wishlist
+
+Native wishlist using localStorage. Replaces Wishlist Plus, Wishlist King, Globo Wishlist. App-free.
+
+## Files
+
+- `assets/runwell-wishlist.js`. Core storage + UI logic. ~120 LOC, no dependencies.
+- `snippets/runwell-wishlist-icon.liquid`. Heart button to drop into card-product or main-product.
+- `sections/runwell-wishlist-page.liquid`. Section that hydrates the dedicated wishlist page.
+- `templates/page.wishlist.json`. Page template wiring the section to the `/pages/wishlist` URL.
+
+## How to use
+
+1. Sync the module: `runwell-shopify sync`
+2. Add the heart icon wherever a product is listed:
+   ```liquid
+   {% render 'runwell-wishlist-icon', handle: card_product.handle %}
+   ```
+3. Create the Wishlist page in admin (see admin_steps in module.json):
+   - Pages > Add page > Title "Wishlist" > Visible > Theme template "page.wishlist" > Save
+4. Visit `/pages/wishlist` to see the saved items hydrate from localStorage.
+
+## Config
+
+| Key | Default | Notes |
+|---|---|---|
+| `max_items` | `100` | Max items kept in localStorage. Excess trimmed FIFO. |
+
+## Storage
+
+| Surface | Mechanism |
+|---|---|
+| Guest user | `localStorage["runwell_wishlist"] = ["handle-1", ...]` |
+| Logged-in customer | localStorage only in v0.1; metafield sync is v0.2 (requires App Proxy) |
+
+## Events
+
+The module dispatches `runwell:wishlist:change` on `document` whenever an item is added or removed. Useful if you want to update a header counter:
+
+```js
+document.addEventListener('runwell:wishlist:change', function (e) {
+  console.log('count:', e.detail.count);
+});
+```
+
+## Replaces
+
+Wishlist Plus, Wishlist King, Globo Wishlist (display layer; the metafield sync option in those apps is the only feature not yet built).

package/modules/wishlist/assets/runwell-wishlist.js

@@ -0,0 +1,112 @@
+/* Runwell wishlist. localStorage-backed for guests; reads/writes
+   customer metafield lushi.wishlist when logged in (writes require an
+   App Proxy; v1 ships localStorage only, sync to metafield is v0.2).
+   Replaces Wishlist Plus, Wishlist King, Globo Wishlist. */
+(function () {
+  if (typeof window === 'undefined') return;
+  var KEY = 'runwell_wishlist';
+  var MAX = 100;
+
+  function read() {
+    try { return JSON.parse(localStorage.getItem(KEY) || '[]'); } catch (e) { return []; }
+  }
+  function write(list) {
+    try { localStorage.setItem(KEY, JSON.stringify(list.slice(0, MAX))); } catch (e) {}
+  }
+  function has(handle) { return read().indexOf(handle) !== -1; }
+  function add(handle) {
+    var list = read().filter(function (h) { return h !== handle; });
+    list.unshift(handle);
+    write(list);
+    fire('add', handle);
+  }
+  function remove(handle) {
+    var list = read().filter(function (h) { return h !== handle; });
+    write(list);
+    fire('remove', handle);
+  }
+  function toggle(handle) {
+    if (has(handle)) { remove(handle); return false; }
+    add(handle); return true;
+  }
+  function fire(action, handle) {
+    var event = new CustomEvent('runwell:wishlist:change', { detail: { action: action, handle: handle, count: read().length } });
+    document.dispatchEvent(event);
+  }
+
+  function bindButtons() {
+    document.querySelectorAll('[data-runwell-wishlist]').forEach(function (btn) {
+      if (btn.dataset.runwellWishlistBound === '1') return;
+      btn.dataset.runwellWishlistBound = '1';
+      var handle = btn.getAttribute('data-handle');
+      if (!handle) return;
+      function refresh() {
+        if (has(handle)) {
+          btn.setAttribute('aria-pressed', 'true');
+          btn.classList.add('is-saved');
+        } else {
+          btn.setAttribute('aria-pressed', 'false');
+          btn.classList.remove('is-saved');
+        }
+      }
+      btn.addEventListener('click', function (e) {
+        e.preventDefault();
+        toggle(handle);
+        refresh();
+      });
+      refresh();
+    });
+  }
+
+  function renderPage() {
+    var host = document.querySelector('[data-runwell-wishlist-page]');
+    if (!host) return;
+    var handles = read();
+    var grid = host.querySelector('[data-runwell-wishlist-grid]');
+    var emptyState = host.querySelector('[data-runwell-wishlist-empty]');
+    if (!handles.length) {
+      if (emptyState) emptyState.style.display = '';
+      if (grid) grid.style.display = 'none';
+      return;
+    }
+    if (emptyState) emptyState.style.display = 'none';
+    if (grid) grid.style.display = '';
+
+    Promise.all(handles.map(function (h) {
+      return fetch('/products/' + h + '.js').then(function (r) { return r.ok ? r.json() : null; }).catch(function () { return null; });
+    })).then(function (products) {
+      if (!grid) return;
+      grid.innerHTML = products.filter(Boolean).map(function (p) {
+        var img = p.featured_image ? '<img src="' + p.featured_image + '" alt="' + p.title + '" loading="lazy">' : '';
+        var price = (p.price / 100).toFixed(2);
+        return '<a class="runwell-wishlist__card" href="/products/' + p.handle + '">' +
+                 '<div class="runwell-wishlist__media">' + img + '</div>' +
+                 '<div class="runwell-wishlist__title">' + p.title + '</div>' +
+                 '<div class="runwell-wishlist__price">$' + price + '</div>' +
+                 '<button type="button" class="runwell-wishlist__remove" data-handle="' + p.handle + '" aria-label="Remove from wishlist">Remove</button>' +
+               '</a>';
+      }).join('');
+
+      grid.querySelectorAll('.runwell-wishlist__remove').forEach(function (btn) {
+        btn.addEventListener('click', function (e) {
+          e.preventDefault();
+          remove(btn.getAttribute('data-handle'));
+          renderPage();
+        });
+      });
+    });
+  }
+
+  window.runwellWishlist = { has: has, add: add, remove: remove, toggle: toggle, list: read };
+
+  function init() {
+    bindButtons();
+    renderPage();
+  }
+  document.addEventListener('runwell:wishlist:change', bindButtons);
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', init);
+  } else {
+    init();
+  }
+})();

package/modules/wishlist/module.json

@@ -0,0 +1,25 @@
+{
+  "name": "wishlist",
+  "version": "0.1.0",
+  "category": "customer",
+  "description": "Native wishlist using localStorage. Heart icon on cards + dedicated /pages/wishlist page. v1 ships localStorage; metafield sync via App Proxy is v0.2. Replaces Wishlist Plus, Wishlist King, Globo Wishlist.",
+  "files": {
+    "assets": ["assets/runwell-wishlist.js"],
+    "snippets": ["snippets/runwell-wishlist-icon.liquid"],
+    "sections": ["sections/runwell-wishlist-page.liquid"],
+    "templates": ["templates/page.wishlist.json"]
+  },
+  "config": {
+    "schema": {
+      "max_items": { "type": "number", "default": 100 }
+    }
+  },
+  "admin_steps": [
+    {
+      "id": "create-wishlist-page",
+      "label": "Create the wishlist page in Shopify admin",
+      "url": "https://admin.shopify.com/store/{store_handle}/pages/new",
+      "summary": "Create a Page with title 'Wishlist'. Set visibility Visible. In the Theme template dropdown, select 'page.wishlist'. Save."
+    }
+  ]
+}

package/modules/wishlist/sections/runwell-wishlist-page.liquid

@@ -0,0 +1,35 @@
+{%- comment -%}
+  Runwell wishlist page section. Drop into a Shopify Page template
+  (e.g. templates/page.wishlist.json).
+{%- endcomment -%}
+
+<section class="runwell-wishlist" data-runwell-wishlist-page>
+  <div class="runwell-wishlist__inner">
+    {%- if section.settings.heading != blank -%}
+      <h1 class="runwell-wishlist__heading">{{ section.settings.heading }}</h1>
+    {%- endif -%}
+    <div class="runwell-wishlist__empty" data-runwell-wishlist-empty>
+      <p>{{ section.settings.empty_text }}</p>
+      <a href="{{ routes.collections_url }}/all" class="runwell-wishlist__cta">{{ section.settings.empty_cta }}</a>
+    </div>
+    <div class="runwell-wishlist__grid" data-runwell-wishlist-grid></div>
+  </div>
+</section>
+
+<script src="{{ 'runwell-wishlist.js' | asset_url }}" defer="defer"></script>
+
+{% schema %}
+{
+  "name": "Runwell wishlist page",
+  "tag": "section",
+  "class": "section-runwell-wishlist",
+  "settings": [
+    { "type": "text", "id": "heading", "label": "Heading", "default": "Saved for later" },
+    { "type": "text", "id": "empty_text", "label": "Empty state text", "default": "Save items as you browse and they will show up here." },
+    { "type": "text", "id": "empty_cta", "label": "Empty state CTA", "default": "Start browsing" }
+  ],
+  "presets": [
+    { "name": "Runwell wishlist page" }
+  ]
+}
+{% endschema %}

package/modules/wishlist/snippets/runwell-wishlist-icon.liquid

@@ -0,0 +1,17 @@
+{%- comment -%}
+  Runwell wishlist heart button. Drop into card-product or main-product.
+  Caller sets handle via {% render 'runwell-wishlist-icon', handle: card_product.handle %}
+{%- endcomment -%}
+
+<button
+  type="button"
+  class="runwell-wishlist-icon"
+  data-runwell-wishlist
+  data-handle="{{ handle }}"
+  aria-pressed="false"
+  aria-label="Save for later"
+>
+  <svg viewBox="0 0 24 24" width="20" height="20" aria-hidden="true">
+    <path d="M12 21s-7-4.35-9.5-9C.5 7 4 3 7.5 3c2 0 3.5 1 4.5 2.5C13 4 14.5 3 16.5 3 20 3 23.5 7 21.5 12 19 16.65 12 21 12 21z" fill="none" stroke="currentColor" stroke-width="1.5"/>
+  </svg>
+</button>

package/modules/wishlist/templates/page.wishlist.json

@@ -0,0 +1,13 @@
+{
+  "sections": {
+    "wishlist": {
+      "type": "runwell-wishlist-page",
+      "settings": {
+        "heading": "Saved for later",
+        "empty_text": "Save items as you browse and they will show up here.",
+        "empty_cta": "Start browsing"
+      }
+    }
+  },
+  "order": ["wishlist"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runwell/shopify-toolkit",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Reusable Shopify theme modules from Runwell. Replaces typically app-driven features (reviews, wishlist, urgency, FAQ, post-purchase upsell, exit popups, free-ship progress, sticky ATC, testimonials, badges, bundles) with native Liquid + JS + CSS that ship across multiple client themes via a config-driven sync CLI.",
   "type": "module",
   "main": "lib/index.js",