@runwell/shopify-toolkit 0.21.0 → 0.24.0

package/lib/init.js

@@ -65,7 +65,7 @@ export async function init(flags) {
     store: 'TODO.myshopify.com',
     theme_path: '.',
     baseline,
-    toolkit_version: '^0.9.0',
+    toolkit_version: '^0.21.0',
     brand: {
       name: client.charAt(0).toUpperCase() + client.slice(1),
       primary: '#1A1A1A',
@@ -76,7 +76,18 @@ export async function init(flags) {
       tagline: ''
     },
     modules: {
-      '_shared/css-tokens': { enabled: true, config: {} }
+      '_shared/css-tokens': { enabled: true, config: {} },
+      'runwell-bundle-system': {
+        enabled: false,
+        config: {
+          surface_1_collection_page_enabled: false,
+          surface_2_pdp_pairs_with_enabled: false,
+          surface_3_home_stacks_enabled: false,
+          surface_4_cart_drawer_xsell_enabled: false,
+          surface_5_pdp_banner_enabled: false,
+          surface_6_collection_filter_enabled: false
+        }
+      }
     }
   };
 

package/modules/INDEX.md

@@ -47,7 +47,7 @@ Total modules: 39.
 | `recently-viewed` | pdp | (native build) | sections:1 assets:2 | eyebrow, heading, background_color | (none) | (none) |
 | `reviews` | social-proof | (native build) | sections:1 assets:1 | heading | (none) | (none) |
 | `risk-reversal` | conversion | (native build) | sections:1 | icon, heading, body, link_label, link_url, background_color, text_color | (none) | (none) |
-| `runwell-bundle-system` | catalog | the legacy bundle-builder module | sections:6 snippets:8 assets:2 | surface_1_collection_page_enabled, surface_2_pdp_pairs_with_enabled, surface_3_home_stacks_enabled, surface_4_cart_drawer_xsell_enabled, surface_5_pdp_banner_enabled, surface_6_collection_filter_enabled, surface_2_eyebrow, surface_2_heading, surface_3_eyebrow, surface_3_heading, surface_4_eyebrow, surface_4_cta, surface_5_copy_template, cross_supplier_disclosure, home_strip_position | (none) | install-shopify-bundles + define-bundle-metafields + create-bundle-index-metaobject + create-first-bundle-product + configure-quantity-tier-discount-function + configure-free-gift-discount + create-bundles-collection-page-template + add-home-stacks-section + add-pdp-pairs-with-section + add-pdp-banner-section + verify-cart-drawer-coordination + rebuild-bundle-index |
+| `runwell-bundle-system` | catalog | the legacy bundle-builder module | sections:6 snippets:13 assets:2 | surface_1_collection_page_enabled, surface_2_pdp_pairs_with_enabled, surface_3_home_stacks_enabled, surface_4_cart_drawer_xsell_enabled, surface_5_pdp_banner_enabled, surface_6_collection_filter_enabled, surface_2_eyebrow, surface_2_heading, surface_3_eyebrow, surface_3_heading, surface_4_eyebrow, surface_4_cta, surface_5_copy_template, cross_supplier_disclosure, home_strip_position | (none) | install-shopify-bundles + define-bundle-metafields + create-bundle-index-metaobject + create-first-bundle-product + configure-byob-mode + configure-quantity-tier-discount-function + configure-free-gift-discount + create-bundles-collection-page-template + add-home-stacks-section + add-pdp-pairs-with-section + add-pdp-banner-section + verify-cart-drawer-coordination + rebuild-bundle-index |
 | `scrolling-ticker` | social-proof | announcement-bar / scrolling-text apps | sections:1 assets:1 | (none) | (none) | (none) |
 | `shipping-bar` | conversion | (native build) | sections:1 | threshold_cents, message_below, message_qualified, message_default, background_color, text_color | (none) | (none) |
 | `social-proof-banner` | social-proof | fixed-text social-proof apps | sections:1 assets:1 | (none) | (none) | (none) |
@@ -269,9 +269,9 @@ Total modules: 39.
 - Category: catalog
 - Replaces: the legacy bundle-builder module
 - What: Configurable bundles engine.
-- Files: sections:6 snippets:8 assets:2
+- Files: sections:6 snippets:13 assets:2
 - Config: surface_1_collection_page_enabled, surface_2_pdp_pairs_with_enabled, surface_3_home_stacks_enabled, surface_4_cart_drawer_xsell_enabled, surface_5_pdp_banner_enabled, surface_6_collection_filter_enabled, surface_2_eyebrow, surface_2_heading, surface_3_eyebrow, surface_3_heading, surface_4_eyebrow, surface_4_cta, surface_5_copy_template, cross_supplier_disclosure, home_strip_position
-- Admin steps: install-shopify-bundles + define-bundle-metafields + create-bundle-index-metaobject + create-first-bundle-product + configure-quantity-tier-discount-function + configure-free-gift-discount + create-bundles-collection-page-template + add-home-stacks-section + add-pdp-pairs-with-section + add-pdp-banner-section + verify-cart-drawer-coordination + rebuild-bundle-index
+- Admin steps: install-shopify-bundles + define-bundle-metafields + create-bundle-index-metaobject + create-first-bundle-product + configure-byob-mode + configure-quantity-tier-discount-function + configure-free-gift-discount + create-bundles-collection-page-template + add-home-stacks-section + add-pdp-pairs-with-section + add-pdp-banner-section + verify-cart-drawer-coordination + rebuild-bundle-index
 
 ### scrolling-ticker
 

package/modules/runwell-bundle-system/admin-metafields.json

@@ -5,11 +5,11 @@
     "namespace": "runwell",
     "owner_type": "PRODUCT",
     "definitions": [
-      { "key": "bundle_mode", "name": "Bundle mode", "type": "single_line_text_field", "validations": [{ "name": "choices", "value": "[\"quantity_tiers\",\"multi_product\",\"mix_match\",\"subscription\"]" }] },
-      { "key": "bundle_pricing_model", "name": "Bundle pricing model", "type": "single_line_text_field", "validations": [{ "name": "choices", "value": "[\"tier_quantity\",\"fixed_price\",\"percent_off_subtotal\",\"dollar_off_subtotal\"]" }] },
+      { "key": "bundle_mode", "name": "Bundle mode", "type": "single_line_text_field", "validations": [{ "name": "choices", "value": "[\"quantity_tiers\",\"multi_product\",\"mix_match\",\"byob\",\"subscription\"]" }] },
+      { "key": "bundle_pricing_model", "name": "Bundle pricing model", "type": "single_line_text_field", "validations": [{ "name": "choices", "value": "[\"tier_quantity\",\"fixed_price\",\"fixed_bundle_price\",\"percent_off_subtotal\",\"dollar_off_subtotal\"]" }] },
       { "key": "bundle_pricing_value", "name": "Bundle pricing value (JSON)", "type": "json", "description": "Shape varies by pricing_model. See spec.md section 2.2." },
       { "key": "bundle_components", "name": "Bundle components (JSON)", "type": "json", "description": "Required for multi_product / mix_match. Array of {product_handle, qty}." },
-      { "key": "bundle_quantity_tiers", "name": "Bundle quantity tiers (JSON)", "type": "json", "description": "Required for quantity_tiers. Array of {qty, discount_pct}. Mirrors quantity_breaks schema." },
+      { "key": "bundle_quantity_tiers", "name": "Bundle quantity tiers (JSON)", "type": "json", "description": "Required for quantity_tiers. Array of {qty, discount_pct, label?, popular?, free_shipping?, free_gift?}. label is the visible row label (e.g. '2x Sculpting Brush'); falls back to '{qty}x {product.title}' when absent. popular adds the MOST POPULAR badge. free_shipping shows the FREE SHIPPING tag on that tier. free_gift means buying this tier appends the bundle_free_gift_handle product as a $0 line item via ATC." },
       { "key": "bundle_show_in_catalog", "name": "Show in main catalog", "type": "boolean", "default": true },
       { "key": "bundle_surfaces_enabled", "name": "Surfaces enabled (JSON)", "type": "json", "description": "Per-bundle surface allowlist. Array of 1..6. Absent = all enabled at tenant level." },
       { "key": "bundle_copy", "name": "Per-surface copy (JSON)", "type": "json", "description": "Per-surface eyebrow/heading/cta overrides." },
@@ -21,6 +21,15 @@
       { "key": "bundle_cross_supplier", "name": "Cross-supplier", "type": "boolean", "default": false },
       { "key": "bundle_supplier_count", "name": "Supplier count", "type": "number_integer" },
       { "key": "bundle_savings_pct", "name": "Computed savings percent", "type": "number_decimal", "description": "Precomputed for fast banner / card render. Recomputed by runwell-shopify rebuild-bundle-index." },
+      { "key": "bundle_sale_prefix", "name": "Sale prefix (Mode A)", "type": "single_line_text_field", "description": "Subheading copy displayed under the product title on Mode A quantity-tier surfaces. Example: 'Spring Sculpting Sale: Ends June 5'." },
+      { "key": "bundle_rating_score", "name": "Rating score display", "type": "single_line_text_field", "description": "Rating string shown above the title (e.g. '4.8/5'). Display-only; not wired to a review provider for v1." },
+      { "key": "bundle_rating_count", "name": "Rating count display", "type": "single_line_text_field", "description": "Review count string shown next to the rating score (e.g. '2,400+ Reviews')." },
+      { "key": "bundle_byob_candidates", "name": "BYOB candidates", "type": "list.product_reference", "description": "Mode C only. Pool of candidate products the customer can pick from.", "v1_5": true },
+      { "key": "bundle_byob_min_picks", "name": "BYOB min picks", "type": "number_integer", "description": "Mode C only. Minimum required selections before ATC enables.", "v1_5": true },
+      { "key": "bundle_byob_max_picks", "name": "BYOB max picks", "type": "number_integer", "description": "Mode C only. Maximum allowed selections.", "v1_5": true },
+      { "key": "bundle_byob_layout", "name": "BYOB picker layout", "type": "single_line_text_field", "validations": [{ "name": "choices", "value": "[\"grid\",\"accordion\",\"radio\"]" }], "description": "Mode C only. Default grid.", "v1_5": true },
+      { "key": "bundle_byob_categories", "name": "BYOB categories", "type": "json", "description": "Mode C only. Optional. Array of {label, handles: [product_handle]} to group candidates.", "v1_5": true },
+      { "key": "bundle_byob_required_handles", "name": "BYOB required handles", "type": "list.product_reference", "description": "Mode C only. Pre-selected, not deselectable.", "v1_5": true },
       { "key": "subscription_enabled", "name": "Subscription enabled (v2)", "type": "boolean", "default": false, "v2_only": true },
       { "key": "subscription_interval", "name": "Subscription interval (JSON, v2)", "type": "json", "v2_only": true },
       { "key": "subscription_discount_pct", "name": "Subscription discount percent (v2)", "type": "number_decimal", "v2_only": true },
@@ -40,6 +49,9 @@
   "cross_field_validation": [
     { "rule": "bundle_quantity_tiers required when bundle_mode == 'quantity_tiers'", "enforced_by": "runwell-shopify qa --bundles" },
     { "rule": "bundle_components required when bundle_mode in ['multi_product','mix_match']", "enforced_by": "runwell-shopify qa --bundles" },
+    { "rule": "bundle_byob_candidates + bundle_byob_min_picks + bundle_byob_max_picks required when bundle_mode == 'byob'", "enforced_by": "runwell-shopify qa --bundles" },
+    { "rule": "bundle_byob_min_picks <= bundle_byob_max_picks", "enforced_by": "runwell-shopify qa --bundles" },
+    { "rule": "bundle_byob_layout == 'radio' requires bundle_byob_categories", "enforced_by": "runwell-shopify qa --bundles" },
     { "rule": "bundle_pricing_value shape matches bundle_pricing_model (see spec.md section 2.2)", "enforced_by": "runwell-shopify qa --bundles" },
     { "rule": "bundle_free_gift_handle required when bundle_free_gift_enabled == true", "enforced_by": "runwell-shopify qa --bundles" }
   ]

package/modules/runwell-bundle-system/assets/runwell-bundle-quantity-builder.css

@@ -0,0 +1,383 @@
+.runwell-bundle-quantity-builder__grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 2.4rem;
+  align-items: start;
+}
+
+/* Slideshow Gallery */
+.runwell-bundle-quantity-builder__slideshow {
+  position: relative;
+  border-radius: 12px;
+  overflow: hidden;
+  background: #E8D5C4;
+}
+
+.runwell-bundle-quantity-builder__slide {
+  display: none;
+}
+
+.runwell-bundle-quantity-builder__slide--active {
+  display: block;
+}
+
+.runwell-bundle-quantity-builder__img {
+  width: 100%;
+  height: auto;
+  display: block;
+  aspect-ratio: 1 / 1;
+  object-fit: cover;
+  max-height: calc(100vh - 260px);
+}
+
+/* Thumbnail Strip - ALWAYS visible including mobile */
+.runwell-bundle-quantity-builder__thumbnails {
+  display: flex;
+  gap: 8px;
+  margin-top: 12px;
+  overflow-x: auto;
+  scrollbar-width: thin;
+  scrollbar-color: #EADFD4 transparent;
+  padding-bottom: 4px;
+  -webkit-overflow-scrolling: touch;
+}
+
+.runwell-bundle-quantity-builder__thumbnails::-webkit-scrollbar {
+  height: 4px;
+}
+
+.runwell-bundle-quantity-builder__thumbnails::-webkit-scrollbar-thumb {
+  background: #EADFD4;
+  border-radius: 2px;
+}
+
+.runwell-bundle-quantity-builder__thumb {
+  flex: 0 0 72px;
+  height: 72px;
+  border-radius: 8px;
+  overflow: hidden;
+  border: 2px solid transparent;
+  cursor: pointer;
+  padding: 0;
+  background: #E8D5C4;
+  transition: border-color 0.2s, opacity 0.2s;
+  opacity: 0.7;
+}
+
+.runwell-bundle-quantity-builder__thumb--active {
+  border-color: #3F5B4C;
+  opacity: 1;
+}
+
+.runwell-bundle-quantity-builder__thumb:hover {
+  opacity: 1;
+}
+
+.runwell-bundle-quantity-builder__thumb img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+/* Rating */
+.runwell-bundle-quantity-builder__rating {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin-bottom: 0;
+}
+
+.runwell-bundle-quantity-builder__stars {
+  color: #E8B931;
+  font-size: calc(var(--font-body-scale) * 1.6rem);
+  letter-spacing: 1px;
+}
+
+.runwell-bundle-quantity-builder__rating-text {
+  font-size: calc(var(--font-body-scale) * 1.4rem);
+  font-weight: 600;
+  font-style: italic;
+}
+
+/* Title */
+.runwell-bundle-quantity-builder__title {
+  margin-top: 0.4rem;
+  margin-bottom: 1rem;
+}
+
+/* Sale heading */
+.runwell-bundle-quantity-builder__sale-heading {
+  display: flex;
+  align-items: center;
+  gap: 1.2rem;
+  margin-bottom: 1.2rem;
+}
+
+.runwell-bundle-quantity-builder__sale-line {
+  flex: 1;
+  height: 1px;
+  background: #2A2622;
+}
+
+.runwell-bundle-quantity-builder__sale-text {
+  font-weight: 700;
+  font-size: calc(var(--font-body-scale) * 1.5rem);
+  white-space: nowrap;
+}
+
+/* Scarcity indicator */
+.runwell-bundle-quantity-builder__scarcity {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 6px;
+  font-size: calc(var(--font-body-scale) * 1.3rem);
+  font-weight: 500;
+  color: #b45309;
+  margin-bottom: 1rem;
+}
+
+.runwell-bundle-quantity-builder__scarcity-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: #b45309;
+  animation: scarcity-pulse 2s ease-in-out infinite;
+}
+
+@keyframes scarcity-pulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.4; }
+}
+
+/* Options */
+.runwell-bundle-quantity-builder__options {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  margin-bottom: 1.2rem;
+}
+
+.runwell-bundle-quantity-builder__option {
+  display: flex;
+  align-items: flex-start;
+  gap: 12px;
+  padding: 14px 18px;
+  border: 2px solid #EADFD4;
+  border-radius: 10px;
+  cursor: pointer;
+  transition: border-color 0.2s, box-shadow 0.2s;
+  position: relative;
+}
+
+.runwell-bundle-quantity-builder__option:hover {
+  border-color: #3F5B4C;
+}
+
+.runwell-bundle-quantity-builder__option--selected {
+  border-color: #2A2622;
+  box-shadow: 0 0 0 1px #2A2622;
+}
+
+.runwell-bundle-quantity-builder__option--popular {
+  border-color: #3F5B4C;
+  position: relative;
+}
+
+.runwell-bundle-quantity-builder__popular-badge {
+  position: absolute;
+  top: -10px;
+  right: 16px;
+  background: #3F5B4C;
+  color: #fff;
+  font-size: var(--runwell-body-size);
+  font-weight: 700;
+  padding: 2px 10px;
+  border-radius: 4px;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+}
+
+.runwell-bundle-quantity-builder__option input {
+  position: absolute;
+  opacity: 0;
+  pointer-events: none;
+}
+
+.runwell-bundle-quantity-builder__option-radio {
+  width: 22px;
+  height: 22px;
+  border-radius: 50%;
+  border: 2px solid #EADFD4;
+  flex-shrink: 0;
+  margin-top: 2px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: border-color 0.2s;
+}
+
+.runwell-bundle-quantity-builder__option--selected .runwell-bundle-quantity-builder__option-radio {
+  border-color: #2A2622;
+}
+
+.runwell-bundle-quantity-builder__option--selected .runwell-bundle-quantity-builder__option-radio::after {
+  content: '';
+  width: 12px;
+  height: 12px;
+  border-radius: 50%;
+  background: #2A2622;
+}
+
+.runwell-bundle-quantity-builder__option-content {
+  flex: 1;
+}
+
+.runwell-bundle-quantity-builder__option-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+  gap: 12px;
+}
+
+.runwell-bundle-quantity-builder__option-title {
+  font-weight: 700;
+  font-size: calc(var(--font-heading-scale) * 1.5rem);
+}
+
+.runwell-bundle-quantity-builder__option-pricing {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+  flex-shrink: 0;
+}
+
+.runwell-bundle-quantity-builder__option-price {
+  font-weight: 700;
+  font-size: calc(var(--font-body-scale) * 1.8rem);
+}
+
+.runwell-bundle-quantity-builder__option-compare {
+  font-size: calc(var(--font-body-scale) * 1.3rem);
+  text-decoration: line-through;
+  opacity: 0.5;
+}
+
+.runwell-bundle-quantity-builder__option-badges {
+  display: flex;
+  gap: 6px;
+  margin-top: 6px;
+  flex-wrap: wrap;
+}
+
+.runwell-bundle-quantity-builder__badge {
+  font-size: calc(var(--font-body-scale) * 1.1rem);
+  font-weight: 700;
+  padding: 2px 8px;
+  border-radius: 4px;
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+}
+
+.runwell-bundle-quantity-builder__badge--save {
+  background: #3F5B4C;
+  color: #fff;
+}
+
+.runwell-bundle-quantity-builder__badge--shipping {
+  color: #3F5B4C;
+  font-weight: 600;
+}
+
+.runwell-bundle-quantity-builder__free-gift {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  margin-top: 8px;
+  padding: 8px 12px;
+  background: rgba(63, 91, 76, 0.06);
+  border-radius: 6px;
+  font-size: calc(var(--font-body-scale) * 1.3rem);
+  font-weight: 600;
+}
+
+.runwell-bundle-quantity-builder__gift-icon {
+  font-size: calc(var(--font-body-scale) * 1.6rem);
+}
+
+/* ATC Button */
+.runwell-bundle-quantity-builder__atc {
+  width: 100%;
+  padding: 1.6rem;
+  font-size: calc(var(--font-body-scale) * 1.6rem);
+  font-weight: 700;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  background: #2A2622;
+  color: #fff;
+  border: none;
+  border-radius: 8px;
+  cursor: pointer;
+  transition: background 0.2s;
+  margin-bottom: 1.2rem;
+}
+
+.runwell-bundle-quantity-builder__atc:hover {
+  background: #3F5B4C;
+}
+
+/* Trust badges */
+.runwell-bundle-quantity-builder__trust {
+  display: flex;
+  justify-content: center;
+  gap: 2rem;
+  font-size: calc(var(--font-body-scale) * 1.3rem);
+  opacity: 0.7;
+  flex-wrap: wrap;
+}
+
+/* Sticky ATC on mobile */
+@media screen and (max-width: 989px) {
+  .runwell-bundle-quantity-builder__grid {
+    grid-template-columns: 1fr;
+    gap: 2rem;
+  }
+
+  .runwell-bundle-quantity-builder__atc-wrap {
+    position: sticky;
+    bottom: 0;
+    z-index: 10;
+    background: #fff;
+    padding: 12px 0 max(12px, env(safe-area-inset-bottom));
+    box-shadow: 0 -2px 12px rgba(0, 0, 0, 0.08);
+    margin: 0 -1.5rem;
+    padding-left: 1.5rem;
+    padding-right: 1.5rem;
+  }
+}
+
+@media screen and (max-width: 749px) {
+  .runwell-bundle-quantity-builder__option-header {
+    flex-direction: column;
+    gap: 4px;
+  }
+
+  .runwell-bundle-quantity-builder__trust {
+    flex-direction: column;
+    align-items: center;
+    gap: 0.6rem;
+  }
+}
+
+/* Runwell additions: placeholder states when gallery is empty */
+.runwell-bundle-quantity-builder__img--placeholder,
+.runwell-bundle-quantity-builder__thumb-img--placeholder {
+  width: 100%;
+  height: 100%;
+  min-height: 320px;
+  background: linear-gradient(135deg, var(--runwell-oat, #F5F0EE), var(--runwell-cream, #EDE6D8));
+  display: block;
+}
+.runwell-bundle-quantity-builder__thumb-img--placeholder {
+  min-height: 0;
+}