@souldi/try-on 0.5.1 → 0.5.2

package/CHANGELOG.md

@@ -8,6 +8,8 @@
 - **Removed: the size screen.** "How size X sits on you" and its 3D mannequin are gone from the dialog, and the size in the dialog is no longer a button. The mannequin's standalone build is still published, for older bundles that load it.
 - **Removed: Refine.** The dialog has no Refine control, and the button handle's `refine()` is gone. `onError` no longer reports `operation: 'refine'`, and `onGenerationSuccess` / `onResultShown` no longer carry `refinable`. Refine stays in the Souldi API; the widget never sends a `refinement_prompt`.
 - `openSize()` on the button handle still opens the dialog on the customer's size. Before a try-on it now shows the garment and **Try on** there.
+- **New: between two sizes, the customer picks.** When the customer is between two neighbouring sizes, the dialog shows "Your size: between M and L" with two options, M for a closer fit and L for a looser one, the recommended one preselected, and "Both will fit you." under them. **Add size X to cart** follows the choice; a new recommendation (edited measurements, another colour) resets it. Shown only where there is a cart button; otherwise the dialog names one size and gives the same advice in words. A customer whose second size is not a neighbour still sees one size, now captioned "This one is harder to call." alone (it used to follow "From your measurements.").
+- **`onAddToCart` gains `recommendedSize` and `recommendationId`** beside `size`, which is the size the customer chose. Additive: a handler that reads `size` alone keeps working. See [`onAddToCart`](README.md#onaddtocart).
 
 ## 0.5.0
 

package/README.md

@@ -165,17 +165,29 @@ address, or body measurements.
 #### `onAddToCart`
 
 The widget knows a customer's size; only you know your cart. Supply
-`onAddToCart` and the dialog draws an **Add size X to cart** button on both its
-screens. Leave it out and there is no cart control at all.
+`onAddToCart` and the dialog draws an **Add size X to cart** button under the
+customer's size. Leave it out and there is no cart control at all.
+
+When the customer is between two neighbouring sizes, the dialog says so ("Your
+size: between M and L") and lets them pick which one goes in the cart: the
+smaller for a closer fit, the larger for a looser one, with the recommended size
+preselected. The button follows their choice, and any new recommendation (edited
+measurements, another colour) resets it. Without `onAddToCart` there is nothing
+to pick for, so the dialog shows the one recommended size and says the same
+advice in words.
 
 It is called with one `intent` and must **resolve** (never reject) to an
 outcome:
 
 ```js
-onAddToCart: async ({ buttonId, size, sizeRun }) => {
-  // buttonId — the containerId of the button this is about
-  // size     — the size the customer chose, e.g. "M"
-  // sizeRun  — every size the garment's chart offers, e.g. ["S", "M", "L"]
+onAddToCart: async ({ buttonId, size, sizeRun, recommendedSize, recommendationId }) => {
+  // buttonId         — the containerId of the button this is about
+  // size             — the size to add: the customer's choice, e.g. "L"
+  // sizeRun          — every size the garment's chart offers, e.g. ["S", "M", "L"]
+  // recommendedSize  — the size the widget recommended, e.g. "M". It differs
+  //                    from `size` only when the customer picked the other of
+  //                    two neighbouring sizes
+  // recommendationId — the id of the recommendation on screen, or null
   const variant = resolveVariant(buttonId, size);
   if (!variant) return { ok: false, message: 'That size is not available in this colour.' };
   await addLineToCart(variant.id);
@@ -191,6 +203,13 @@ onAddToCart: async ({ buttonId, size, sizeRun }) => {
 | `quantity` | `ok: true` | Optional. How many of this line the cart now holds, for a repeat add |
 | `notice` | `ok: true` | Optional. A caveat when the add was adjusted on the way in (short stock, a cart limit) |
 
+`recommendedSize` and `recommendationId` are new in this release, and only
+added beside the fields you already read. A handler that reads `size` alone
+keeps working and adds what the customer chose. Keep `recommendationId` with the
+line item if you want to match a purchase to the recommendation behind it. The
+widget records each recommendation in the background and nothing waits for
+that record, so it may arrive after the add or not at all.
+
 Two rules the widget keeps for you: nothing is stated in the past tense until
 you have resolved `{ ok: true }`, and nothing reaches your handler without a
 click on the button — opening the dialog, a new result landing, and changing