@runwell/shopify-toolkit 0.17.4 → 0.21.0

package/modules/product-trio-medvi/sections/runwell-product-trio-medvi.liquid

@@ -0,0 +1,188 @@
+{%- comment -%}
+  Runwell product-trio-medvi.
+
+  3-product showcase: 3 product images in a fan layout with the center
+  product foregrounded; single soft-corner copy panel beside, holding
+  one short headline. Hero anchor for a product line.
+
+  Lineage: extracted from home.medvi.org (Framer label "3 Cards / Pill
+  Image Group"), generalised to Runwell brand tokens.
+{%- endcomment -%}
+
+{{ 'runwell-product-trio-medvi.css' | asset_url | stylesheet_tag }}
+
+{%- liquid
+  assign layout = section.settings.layout | default: 'products-left'
+  assign bg_band = section.settings.bg_band | default: 'white'
+  assign panel_bg = section.settings.panel_bg | default: 'var(--runwell-oat)'
+-%}
+
+<section
+  class="runwell-product-trio-medvi runwell-product-trio-medvi--{{ layout }} runwell-product-trio-medvi--bg-{{ bg_band }}"
+>
+  <div class="runwell-product-trio-medvi__inner">
+
+    <div class="runwell-product-trio-medvi__products">
+      <div class="runwell-product-trio-medvi__product runwell-product-trio-medvi__product--left">
+        {%- if section.settings.product_image_left != blank -%}
+          <img
+            src="{{ section.settings.product_image_left | image_url: width: 600 }}"
+            alt="{{ section.settings.product_image_left.alt | default: '' | escape }}"
+            width="{{ section.settings.product_image_left.width }}"
+            height="{{ section.settings.product_image_left.height }}"
+            loading="lazy"
+          >
+        {%- elsif section.settings.product_image_left_asset != blank -%}
+          <img
+            src="{{ section.settings.product_image_left_asset | asset_url }}"
+            alt=""
+            width="600"
+            height="800"
+            loading="lazy"
+          >
+        {%- endif -%}
+      </div>
+
+      <div class="runwell-product-trio-medvi__product runwell-product-trio-medvi__product--center">
+        {%- if section.settings.product_image_center != blank -%}
+          <img
+            src="{{ section.settings.product_image_center | image_url: width: 800 }}"
+            alt="{{ section.settings.product_image_center.alt | default: '' | escape }}"
+            width="{{ section.settings.product_image_center.width }}"
+            height="{{ section.settings.product_image_center.height }}"
+            loading="lazy"
+          >
+        {%- elsif section.settings.product_image_center_asset != blank -%}
+          <img
+            src="{{ section.settings.product_image_center_asset | asset_url }}"
+            alt=""
+            width="800"
+            height="1000"
+            loading="lazy"
+          >
+        {%- endif -%}
+      </div>
+
+      <div class="runwell-product-trio-medvi__product runwell-product-trio-medvi__product--right">
+        {%- if section.settings.product_image_right != blank -%}
+          <img
+            src="{{ section.settings.product_image_right | image_url: width: 600 }}"
+            alt="{{ section.settings.product_image_right.alt | default: '' | escape }}"
+            width="{{ section.settings.product_image_right.width }}"
+            height="{{ section.settings.product_image_right.height }}"
+            loading="lazy"
+          >
+        {%- elsif section.settings.product_image_right_asset != blank -%}
+          <img
+            src="{{ section.settings.product_image_right_asset | asset_url }}"
+            alt=""
+            width="600"
+            height="800"
+            loading="lazy"
+          >
+        {%- endif -%}
+      </div>
+    </div>
+
+    {%- if section.settings.panel_heading != blank -%}
+      <div
+        class="runwell-product-trio-medvi__panel"
+        style="background: {{ panel_bg }};"
+      >
+        <p class="runwell-product-trio-medvi__panel-heading">{{ section.settings.panel_heading }}</p>
+      </div>
+    {%- endif -%}
+
+  </div>
+</section>
+
+{% schema %}
+{
+  "name": "Product trio (medvi)",
+  "tag": "section",
+  "class": "section-runwell-product-trio-medvi",
+  "settings": [
+    {
+      "type": "header",
+      "content": "Products (3 images)"
+    },
+    {
+      "type": "image_picker",
+      "id": "product_image_left",
+      "label": "Left product image",
+      "info": "PNG with transparent background recommended."
+    },
+    {
+      "type": "text",
+      "id": "product_image_left_asset",
+      "label": "Left product image (asset filename)"
+    },
+    {
+      "type": "image_picker",
+      "id": "product_image_center",
+      "label": "Center product image (foregrounded)"
+    },
+    {
+      "type": "text",
+      "id": "product_image_center_asset",
+      "label": "Center product image (asset filename)"
+    },
+    {
+      "type": "image_picker",
+      "id": "product_image_right",
+      "label": "Right product image"
+    },
+    {
+      "type": "text",
+      "id": "product_image_right_asset",
+      "label": "Right product image (asset filename)"
+    },
+    {
+      "type": "header",
+      "content": "Copy panel"
+    },
+    {
+      "type": "text",
+      "id": "panel_heading",
+      "label": "Panel headline",
+      "default": "Doctor-formulated blends designed to support how your body works best."
+    },
+    {
+      "type": "color",
+      "id": "panel_bg",
+      "label": "Panel background tint",
+      "default": "#F5F0EE"
+    },
+    {
+      "type": "header",
+      "content": "Layout"
+    },
+    {
+      "type": "select",
+      "id": "layout",
+      "label": "Layout",
+      "options": [
+        { "value": "products-left", "label": "Products on left" },
+        { "value": "products-right", "label": "Products on right" }
+      ],
+      "default": "products-left"
+    },
+    {
+      "type": "select",
+      "id": "bg_band",
+      "label": "Background band",
+      "options": [
+        { "value": "white", "label": "White" },
+        { "value": "oat", "label": "Oat" },
+        { "value": "celadon-tint", "label": "Celadon tint" }
+      ],
+      "default": "white"
+    }
+  ],
+  "presets": [
+    {
+      "name": "Product trio (medvi)"
+    }
+  ]
+}
+{% endschema %}

package/modules/runwell-bundle-system/README.md

@@ -0,0 +1,35 @@
+# runwell-bundle-system
+
+Configurable bundles engine for Runwell Shopify tenants.
+
+## Modes
+- Mode A: single-product quantity tiers (Lusha pattern).
+- Mode B: curated multi-product bundles (Lushi pattern).
+- Mode C: mix-and-match / build-your-own (v1.5).
+- Mode D: subscription bundles (v2).
+
+## Display surfaces
+1. Dedicated /bundles collection page.
+2. PDP "Pairs well with" widget.
+3. Home page curated stacks.
+4. Cart drawer bundle cross-sell.
+5. PDP bundle banner.
+6. Collection page bundles filter.
+
+## Architecture
+Sits on top of Shopify's free first-party Bundles app. Reads per-bundle config from product metafields (namespace: runwell). See spec.md for the data model.
+
+## Replaces
+- bundle-builder (deprecated; Lusha migrates in v1.1).
+
+## Lineage
+Net-new Runwell module. Spec: `_clients/capital-v/lushi/specs/bundle-system/spec.md`.
+
+## Files in this module
+
+- `module.json`: module manifest, config schema, admin_steps array.
+- `admin-metafields.json`: source of truth for the 19 product metafields and the `bundle_index` shop metaobject. Source for `runwell-shopify provision-metafields` and merchant manual setup.
+- `settings.json`: theme customizer settings patch. Appended to tenant `config/settings_schema.json` by `runwell-shopify sync`.
+- `sections/`: one Liquid section per display surface (placeholders until BS-2 onwards).
+- `snippets/`: shared bundle UI partials (placeholders until BS-2 onwards).
+- `assets/`: module CSS and JS (placeholders until BS-2 onwards).

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

@@ -0,0 +1,46 @@
+{
+  "$comment": "Source of truth for runwell.bundle_* product metafield definitions. Mirrors spec.md section 2.1. Read by runwell-shopify provision-metafields (when implemented) and by admin-guide.md for manual setup.",
+  "spec_ref": "_clients/capital-v/lushi/specs/bundle-system/spec.md#21-per-bundle-product-metafields",
+  "product_metafields": {
+    "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_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_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." },
+      { "key": "bundle_free_gift_enabled", "name": "Free gift enabled", "type": "boolean", "default": false },
+      { "key": "bundle_free_gift_handle", "name": "Free gift product handle", "type": "single_line_text_field" },
+      { "key": "bundle_fomo_mode", "name": "FOMO mode", "type": "single_line_text_field", "validations": [{ "name": "choices", "value": "[\"none\",\"discount\",\"scarcity\",\"both\"]" }] },
+      { "key": "bundle_fomo_cycle_days", "name": "FOMO cycle (days)", "type": "number_integer" },
+      { "key": "bundle_fomo_stock_count", "name": "FOMO stock count", "type": "number_integer" },
+      { "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": "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 },
+      { "key": "subscription_badge_copy", "name": "Subscription badge copy (v2)", "type": "single_line_text_field", "v2_only": true }
+    ]
+  },
+  "shop_metaobjects": [
+    {
+      "type": "bundle_index",
+      "name": "Bundle index",
+      "description": "Forward map (bundles -> components) and reverse map (products -> bundles) used by surfaces 2/4 to avoid N+1 reads. Single instance per shop. Rebuilt by runwell-shopify rebuild-bundle-index or by Shopify Flow on bundle product create/update.",
+      "field_definitions": [
+        { "key": "entries", "name": "Entries", "type": "json", "description": "{products: {handle: [bundle_handles]}, bundles: {handle: {components: {handle: qty}}}}" }
+      ]
+    }
+  ],
+  "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_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" }
+  ]
+}