@souldi/try-on 0.2.0 → 0.3.1

package/README.md

@@ -61,13 +61,26 @@ The result surface is the widget's and only the widget's: an accessible
 `<dialog>` inside an isolated Shadow DOM, appended to `<body>`. It reads none of
 your CSS selectors and never touches your product images, so a theme change
 cannot break it — and there is nothing to point it at. It is also where the
-customer decides: beside the render they are told their size (when the garment
-has a size chart), can add that size to your cart (when you supply
-[`onAddToCart`](#onaddtocart)), can open **Body fit** to see how that size sits
-on their body, can open their profile to retake their photo, edit their
-measurements or sign out, can refine the result, and can switch to the
-garment's back view when there is one. The dialog can be reopened after
-closing; the try-on button becomes **View try-on** once a result exists.
+customer decides. It has two screens:
+
+- **Try-on** — the render, beside the customer's size (when the garment has a
+  size chart), an **Add size X to cart** button (when you supply
+  [`onAddToCart`](#onaddtocart)), Refine, and the garment's back view when
+  there is one.
+- **Size** — "How size X sits on you": the same size and cart button beside a
+  mannequin showing how that size fits the customer's body, and a **Try on**
+  button (or **View try-on**, once a result exists).
+
+The dialog can open on **Size** before any try-on has been generated — the
+size comes from the customer's measurements, not from a render — so the size
+shown on the try-on button opens it, before and after a try-on. The ruler
+shown on the button before a size exists is a way into sizing: it signs the
+customer in and takes them to their size, or to their profile when no size is
+ready yet. Neither ever starts a try-on. **Your profile** (retake the photo,
+edit measurements, sign out) opens from inside the dialog. The dialog can be
+reopened after closing; the try-on button becomes **View try-on** once a result
+exists, and the button's size, the dialog's size and the cart button always
+name the same size — a measurement edit updates all of them at once.
 
 Everything optional is simply absent when it does not apply — no size, no
 cart button, no fit detail on a garment without a chart — and nothing is
@@ -102,7 +115,8 @@ Callbacks about a specific try-on receive a trailing `info` object:
 | Field | Type | Present on | Description |
 |-------|------|-----------|-------------|
 | `buttonId` | `string` | most | The `containerId` of the button this callback is about |
-| `operation` | `'generate' \| 'refine'` | `onError`, `onResultShown` | Which operation this is about |
+| `operation` | `'generate' \| 'refine' \| 'view'` | `onError`, `onResultShown` | Which operation this is about |
+| `shownInResult` | `boolean` | `onError` | `true` when the widget has already said this inside its open dialog, under the result it failed to change — so you need not say it again |
 | `view` | `string \| null` | `onGenerationSuccess`, `onResultShown` | The Render View this result is (e.g. `'front'`), when the garment offers more than one |
 | `how` | `'verified' \| 'shared' \| 'restored'` | `onSignedIn` | How this tab's session began. Only `'verified'` is a *new* sign-in — `'shared'` and `'restored'` are this tab catching up with a session that began elsewhere |
 | `resolution` | `string` | `onPhotoReady` | The preprocessing outcome, e.g. `'clean'` or `'soft-issue'` |
@@ -118,8 +132,9 @@ and `onError(message)` keep working unchanged.
 Note that `onError` with `operation: 'refine'` also covers a refine the widget
 *declined* — only the most recently generated result can be refined, so a
 request against an older one is reported here rather than silently dropped.
-Present it wherever you collected the instruction; the previous result is
-untouched either way.
+The previous result is untouched either way. A failed `refine` or `view` with
+the dialog open is already shown in it (`shownInResult: true`); with the dialog
+closed, it is yours to show if you want the customer to see it.
 
 `onResultShown` receives the same `info` `onGenerationSuccess` did for that
 result, minus the image URL — it is about the same render, just reported once
@@ -150,8 +165,8 @@ address, or body measurements.
 #### `onAddToCart`
 
 The widget knows a customer's size; only you know your cart. Supply
-`onAddToCart` and the result dialog (and the size guide) draw an **Add size X
-to cart** button. Leave it out and there is no cart control at all.
+`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.
 
 It is called with one `intent` and must **resolve** (never reject) to an
 outcome:
@@ -192,6 +207,13 @@ Add a try-on button for a specific garment. Call once per product on the page.
 | `garmentUrl` | `string` | Yes | Public URL of the garment image |
 | `internalId` | `string` | No | Your internal/vendor id for this garment; correlated server-side |
 
+It returns a handle for that button. Among its methods:
+
+| Method | Description |
+|--------|-------------|
+| `setGarment(garmentUrl, internalId?)` | Point the button at another garment — a colour switch. The button's previous result is forgotten; a try-on still running for the previous garment is shown when it lands. |
+| `openSize()` | Open the dialog on the customer's size, exactly as the size on the button does — for a "check your size" control of your own. Does nothing while the button has no size to show. |
+
 > **Removed in 0.2.0:** `targetImageId`. It named an `<img>` on your page for the
 > widget to overwrite with the result, and it is gone — the widget shows every
 > result in its own dialog instead (see [How It Works](#how-it-works)). Passing