@wix/himalaya-cli 0.1095.0 → 0.1097.0

package/templates/branded-lite/dev/index.ts

@@ -80654,6 +80654,219 @@ const TEMPLATED: { pattern: string; display: string; liveSeed?: LiveSeed; static
                         }
                       }
                     },
+                    {
+                      "id": "himi_product.options_card",
+                      "body": {
+                        "package": "himalaya",
+                        "type": "VStack",
+                        "props": {
+                          "spacing": 12,
+                          "alignment": "leading",
+                          "children": [
+                            {
+                              "id": "himi_product.opt1_row",
+                              "body": {
+                                "package": "himalaya",
+                                "type": "VStack",
+                                "props": {
+                                  "spacing": 8,
+                                  "alignment": "leading",
+                                  "children": [
+                                    {
+                                      "id": "",
+                                      "body": {
+                                        "package": "himalaya",
+                                        "type": "Text",
+                                        "props": {
+                                          "text": "$service:himiStoreProduct.opt1Label",
+                                          "style": "bodyEmphasis",
+                                          "collapseWhenEmpty": true
+                                        }
+                                      }
+                                    },
+                                    {
+                                      "id": "himi_product.opt1",
+                                      "body": {
+                                        "package": "himalaya",
+                                        "type": "FilterChips",
+                                        "props": {
+                                          "chips": [],
+                                          "optionsPath": "$service:himiStoreProduct.opt1Chips",
+                                          "selectedIds": [
+                                            "$service:himiStoreProduct.opt1Selected"
+                                          ],
+                                          "onChange": {
+                                            "actionId": "tier5.himiStoreProduct.selectOption",
+                                            "params": {
+                                              "group": "1"
+                                            }
+                                          }
+                                        }
+                                      },
+                                      "modifiers": {
+                                        "accessibilityLabel": "$service:himiStoreProduct.opt1Label"
+                                      }
+                                    }
+                                  ]
+                                }
+                              },
+                              "modifiers": {
+                                "hiddenPath": "$service:himiStoreProduct.noOpt1"
+                              }
+                            },
+                            {
+                              "id": "himi_product.opt2_row",
+                              "body": {
+                                "package": "himalaya",
+                                "type": "VStack",
+                                "props": {
+                                  "spacing": 8,
+                                  "alignment": "leading",
+                                  "children": [
+                                    {
+                                      "id": "",
+                                      "body": {
+                                        "package": "himalaya",
+                                        "type": "Text",
+                                        "props": {
+                                          "text": "$service:himiStoreProduct.opt2Label",
+                                          "style": "bodyEmphasis",
+                                          "collapseWhenEmpty": true
+                                        }
+                                      }
+                                    },
+                                    {
+                                      "id": "himi_product.opt2",
+                                      "body": {
+                                        "package": "himalaya",
+                                        "type": "FilterChips",
+                                        "props": {
+                                          "chips": [],
+                                          "optionsPath": "$service:himiStoreProduct.opt2Chips",
+                                          "selectedIds": [
+                                            "$service:himiStoreProduct.opt2Selected"
+                                          ],
+                                          "onChange": {
+                                            "actionId": "tier5.himiStoreProduct.selectOption",
+                                            "params": {
+                                              "group": "2"
+                                            }
+                                          }
+                                        }
+                                      },
+                                      "modifiers": {
+                                        "accessibilityLabel": "$service:himiStoreProduct.opt2Label"
+                                      }
+                                    }
+                                  ]
+                                }
+                              },
+                              "modifiers": {
+                                "hiddenPath": "$service:himiStoreProduct.noOpt2"
+                              }
+                            },
+                            {
+                              "id": "himi_product.opt3_row",
+                              "body": {
+                                "package": "himalaya",
+                                "type": "VStack",
+                                "props": {
+                                  "spacing": 8,
+                                  "alignment": "leading",
+                                  "children": [
+                                    {
+                                      "id": "",
+                                      "body": {
+                                        "package": "himalaya",
+                                        "type": "Text",
+                                        "props": {
+                                          "text": "$service:himiStoreProduct.opt3Label",
+                                          "style": "bodyEmphasis",
+                                          "collapseWhenEmpty": true
+                                        }
+                                      }
+                                    },
+                                    {
+                                      "id": "himi_product.opt3",
+                                      "body": {
+                                        "package": "himalaya",
+                                        "type": "FilterChips",
+                                        "props": {
+                                          "chips": [],
+                                          "optionsPath": "$service:himiStoreProduct.opt3Chips",
+                                          "selectedIds": [
+                                            "$service:himiStoreProduct.opt3Selected"
+                                          ],
+                                          "onChange": {
+                                            "actionId": "tier5.himiStoreProduct.selectOption",
+                                            "params": {
+                                              "group": "3"
+                                            }
+                                          }
+                                        }
+                                      },
+                                      "modifiers": {
+                                        "accessibilityLabel": "$service:himiStoreProduct.opt3Label"
+                                      }
+                                    }
+                                  ]
+                                }
+                              },
+                              "modifiers": {
+                                "hiddenPath": "$service:himiStoreProduct.noOpt3"
+                              }
+                            },
+                            {
+                              "id": "himi_product.options_hint",
+                              "body": {
+                                "package": "himalaya",
+                                "type": "Text",
+                                "props": {
+                                  "text": "$service:himiStoreProduct.optionsHint",
+                                  "style": "footnote",
+                                  "color": "textSecondary",
+                                  "collapseWhenEmpty": true
+                                }
+                              }
+                            },
+                            {
+                              "id": "",
+                              "body": {
+                                "package": "himalaya",
+                                "type": "Text",
+                                "props": {
+                                  "text": "This product has more options than this screen can show. Open it on the website to order.",
+                                  "style": "footnote",
+                                  "color": "textSecondary"
+                                }
+                              },
+                              "modifiers": {
+                                "hiddenPath": "$service:himiStoreProduct.noOptionsOverflow"
+                              }
+                            }
+                          ]
+                        }
+                      },
+                      "modifiers": {
+                        "background": {
+                          "token": "surfaceElevated"
+                        },
+                        "border": {
+                          "width": 1,
+                          "color": {
+                            "token": "border"
+                          }
+                        },
+                        "cornerRadius": 8,
+                        "padding": {
+                          "leading": 14,
+                          "trailing": 14,
+                          "top": 14,
+                          "bottom": 14
+                        },
+                        "hiddenPath": "$service:himiStoreProduct.noOptions"
+                      }
+                    },
                     {
                       "id": "himi_product.qty_card",
                       "body": {
@@ -80938,7 +81151,8 @@ const TEMPLATED: { pattern: string; display: string; liveSeed?: LiveSeed; static
                   "fullWidth": true,
                   "action": {
                     "actionId": "tier5.himiStoreProduct.addToCart"
-                  }
+                  },
+                  "disabledPath": "$service:himiStoreProduct.optionsIncomplete"
                 }
               },
               "modifiers": {

package/templates/branded-lite/tier5-src/himi-store-product/index.ts

@@ -3,7 +3,9 @@ import { defineService } from "@himalaya/state";
 import { share as shareSheet } from "@himalaya/share";
 import { addToCurrentCart, getCurrentCart } from "@himalaya/wix-ecom";
 import { get, upsert, enqueue, type DbEntity } from "@himalaya/local-db";
-import { getStoreProduct, plainText, productImage, productPrice, wixMediaUrl, productGallery as sdkProductGallery, WIX_DETAIL_IMAGE, type StoreProduct } from "../_shared/himi-store.js";
+import { getStoreProduct, plainText, productImage, productPrice, wixMediaUrl, productGallery as sdkProductGallery, WIX_DETAIL_IMAGE, type StoreProduct,
+  productOptions, defaultSelection, isSelectionComplete, selectionSummary, cartOptionsPayload,
+  type StoreOption, type StoreOptionChoice, type StoreOptionSelection } from "../_shared/himi-store.js";
 import { cleanTitle } from "../_shared/himi-text.js";
 import { stashCopy, copyParam, copyTemplate } from "../_shared/himi-copy.js";
 import { isBridgeUnavailable } from "../_shared/owner-load-error.js";
@@ -39,6 +41,85 @@ interface GalleryItem {
   url: string;
 }
 
+interface OptionChip {
+  id: string;
+  label: string;
+}
+
+// ---------------------------------------------------------------------------
+// Product options (Colour, Size, …)
+//
+// A product with options is not buyable without them: the cart line goes out with
+// no colour and no size, and the merchant cannot fulfil the order. The reader and
+// the cart payload live in @himalaya/wix-stores (one reader, both catalogs, and a
+// cart payload that is catalog-specific in a way a per-app copy gets wrong) — this
+// worker only holds the shopper's choice and hides the slots it does not need.
+//
+// THREE fixed slots, because a screen descriptor is static: it cannot loop over N
+// groups when N is unknown at authoring time. Catalog V3 allows up to 6. A product
+// with more groups than slots is NOT silently half-configured — the overflow hint
+// renders and Add to cart stays disabled, because a line item for the wrong variant
+// is worse than one the shopper cannot place yet. Give the descriptor a bounded
+// repeater and this cap goes away.
+// ---------------------------------------------------------------------------
+const OPTION_SLOTS = 3;
+
+/** The raw product behind the current screen. NOT in published state: the V3 cart
+ *  payload is resolved from `variantsInfo`, which no renderer needs to see. */
+let lastProduct: StoreProduct | undefined;
+
+/** The product id `lastProduct` was read for. A pooled screen re-appearing calls
+ *  `refreshServices()` → `load()`, so this is what tells a genuine navigation to a
+ *  DIFFERENT product (drop the picks) from the same product coming back (keep them). */
+let lastLoadedId: string | undefined;
+
+interface OptionSlots {
+  opt1Label: string; opt1Chips: OptionChip[]; opt1Selected: string[]; noOpt1: boolean;
+  opt2Label: string; opt2Chips: OptionChip[]; opt2Selected: string[]; noOpt2: boolean;
+  opt3Label: string; opt3Chips: OptionChip[]; opt3Selected: string[]; noOpt3: boolean;
+}
+
+function slotsOf(groups: StoreOption[], selection: StoreOptionSelection): OptionSlots {
+  const out = {} as Record<string, unknown>;
+  for (let i = 0; i < OPTION_SLOTS; i++) {
+    const g = groups[i];
+    const n = i + 1;
+    const chosen = g ? selection[g.id] ?? "" : "";
+    out[`opt${n}Label`] = g?.name ?? "";
+    // Out-of-stock choices stay selectable but say so — hiding them makes a product
+    // look like it has fewer colours than it does, and the stock flag is per-choice
+    // across variants, not a promise about the combination.
+    out[`opt${n}Chips`] = (g?.choices ?? []).map((c) => ({ id: c.id, label: c.inStock ? c.label : `${c.label} · ${copyParam("product.optionOutOfStock", "Out of stock")}` }));
+    out[`opt${n}Selected`] = chosen ? [chosen] : [];
+    out[`noOpt${n}`] = !g;
+  }
+  return out as unknown as OptionSlots;
+}
+
+/** The chosen choice that cannot be bought, if any. A chip stays SELECTABLE when it
+ *  is out of stock — hiding it makes a product look like it has fewer colours than it
+ *  does — but picking it must not reach the cart: the add was accepted and only failed
+ *  at purchase, which is the worst place to learn it. */
+function outOfStockPick(groups: StoreOption[], selection: StoreOptionSelection): StoreOptionChoice | undefined {
+  for (const g of groups) {
+    const chosen = g.choices.find((c) => c.id === selection[g.id]);
+    if (chosen && chosen.inStock === false) return chosen;
+  }
+  return undefined;
+}
+
+/** What to say under the picker: the groups still unchosen, else the choice made. */
+function optionsHint(groups: StoreOption[], selection: StoreOptionSelection): string {
+  const missing = groups.filter((g) => !selection[g.id]).map((g) => g.name);
+  if (!missing.length) {
+    const blocked = outOfStockPick(groups, selection);
+    return blocked
+      ? copyTemplate("product.optionOutOfStockHint", "{choice} is out of stock. Choose another.", { choice: blocked.label })
+      : selectionSummary(groups, selection);
+  }
+  return copyTemplate("product.optionsChoose", "Choose {options}", { options: missing.join(", ") });
+}
+
 interface S {
   status: "loading" | "ready" | "error";
   name: string;
@@ -79,6 +160,26 @@ interface S {
   saved: boolean;
   saveLabel: string;
   saveHint: string;
+  /** The product's option groups, in site order — the source the slots below and
+   *  the cart payload are derived from. */
+  optionGroups: StoreOption[];
+  /** option id → chosen choice id. A group the shopper has not picked is absent. */
+  selection: StoreOptionSelection;
+  hasOptions: boolean;
+  noOptions: boolean;
+  /** More option groups than the descriptor has slots — see OPTION_SLOTS. */
+  optionsOverflow: boolean;
+  noOptionsOverflow: boolean;
+  /** Add to cart is blocked: this product has options and they are not all chosen. */
+  optionsIncomplete: boolean;
+  /** The product was served from the offline cache, which carries no option groups.
+   *  "No groups" here means UNKNOWN, not "none" — so the CTA must stay blocked rather
+   *  than offer a one-tap add for a product that may need a colour and a size. */
+  optionsUnknown: boolean;
+  optionsHint: string;
+  opt1Label: string; opt1Chips: OptionChip[]; opt1Selected: string[]; noOpt1: boolean;
+  opt2Label: string; opt2Chips: OptionChip[]; opt2Selected: string[]; noOpt2: boolean;
+  opt3Label: string; opt3Chips: OptionChip[]; opt3Selected: string[]; noOpt3: boolean;
 }
 
 function inputId(): string {
@@ -148,8 +249,22 @@ function derive(s: S): S {
   const empty = s.status === "ready" && !s.name;
   const hasGallery = s.gallery.length > 1;
   const hasSingleImage = !!s.image && !hasGallery;
+  const groups = s.optionGroups;
+  const overflow = groups.length > OPTION_SLOTS;
   return {
     ...s,
+    ...slotsOf(groups, s.selection),
+    hasOptions: groups.length > 0,
+    noOptions: groups.length === 0,
+    optionsOverflow: overflow,
+    noOptionsOverflow: !overflow,
+    // Overflow counts as incomplete on purpose: the shopper cannot choose a group
+    // the screen never rendered, so the only variant we could send would be a guess.
+    // `optionsUnknown` blocks too: a cached product whose options we never read is
+    // indistinguishable from one with none, and adding it would post the variant-less
+    // line this whole feature exists to prevent.
+    optionsIncomplete: s.optionsUnknown || !!outOfStockPick(groups, s.selection) || (groups.length > 0 && (overflow || !isSelectionComplete(groups, s.selection))),
+    optionsHint: groups.length ? optionsHint(groups, s.selection) : "",
     saveLabel: s.saved ? copyParam("product.saved", "Saved") : copyParam("product.save", "Save product"),
     notAdding: !s.adding,
     notAdded: !s.added,
@@ -170,6 +285,7 @@ function derive(s: S): S {
 const svc = defineService<S, {
   load: (s: S, arg?: unknown) => Promise<S>;
   setQuantity: (s: S, arg?: unknown) => S;
+  selectOption: (s: S, arg?: unknown) => S;
   addToCart: (s: S) => Promise<S>;
   beginAdd: (s: S, arg?: unknown) => S;
   share: (s: S) => Promise<S>;
@@ -206,6 +322,18 @@ const svc = defineService<S, {
     saved: false,
     saveLabel: "",
     saveHint: "",
+    optionGroups: [],
+    selection: {},
+    hasOptions: false,
+    noOptions: true,
+    optionsOverflow: false,
+    noOptionsOverflow: true,
+    optionsIncomplete: false,
+    optionsUnknown: false,
+    optionsHint: "",
+    opt1Label: "", opt1Chips: [], opt1Selected: [], noOpt1: true,
+    opt2Label: "", opt2Chips: [], opt2Selected: [], noOpt2: true,
+    opt3Label: "", opt3Chips: [], opt3Selected: [], noOpt3: true,
   }),
   actions: {
     load: async (s, arg) => {
@@ -217,15 +345,39 @@ const svc = defineService<S, {
       s = { ...s, saved, saveHint: "", adding: false, added: false };
       // A fresh navigation into the product resets any quantity left over
       // from a previous visit to the same worker instance.
-      if (!id) return derive({ ...s, status: "ready", quantity: 1, emptyText: copyParam("product.notFoundText", "Product not found.") });
+      if (!id) {
+        lastProduct = undefined;
+        lastLoadedId = undefined;
+        return derive({ ...s, status: "ready", quantity: 1, optionGroups: [], selection: {}, optionsUnknown: false, emptyText: copyParam("product.notFoundText", "Product not found.") });
+      }
       try {
         const r = await getStoreProduct(id);
         const p = (r.product ?? (r as unknown as StoreProduct)) as StoreProduct;
         const name = cleanTitle(p.name) || "Product";
         const image = productImage(p, WIX_DETAIL_IMAGE);
+        lastProduct = p;
+        // A group with exactly one choice is chosen for the shopper; a real choice
+        // is left blank so the pick is deliberate.
+        const optionGroups = productOptions(p);
+        // A pooled screen re-appearing re-runs `load`. Wiping `selection` there means a
+        // trip to the cart and back silently clears the size the shopper picked and
+        // re-disables the CTA with no explanation. Carry the picks when this is the SAME
+        // product, and only for a choice the product still offers — a stale id would
+        // resolve to no variant and block the cart just as silently.
+        const carried: StoreOptionSelection = {};
+        if (id === lastLoadedId) {
+          for (const g of optionGroups) {
+            const chosen = s.selection[g.id];
+            if (chosen && g.choices.some((c) => c.id === chosen)) carried[g.id] = chosen;
+          }
+        }
+        lastLoadedId = id;
         return derive({
           ...s,
           status: "ready",
+          optionGroups,
+          selection: { ...defaultSelection(optionGroups), ...carried },
+          optionsUnknown: false,
           name,
           price: productPrice(p),
           description: plainText(p.plainDescription || p.description),
@@ -244,21 +396,34 @@ const svc = defineService<S, {
         if (cached) {
           const name = String(cached.name ?? "") || "Product";
           const image = String(cached.image ?? "");
+          // The cached list row carries no options, and guessing "none" would offer
+          // a one-tap Add to cart for a product that needs a colour and a size. So
+          // the offline detail shows no picker AND marks the options UNKNOWN, which
+          // keeps `optionsIncomplete` true: the CTA stays disabled and `addToCart`
+          // refuses. `cartHint` carries the reason, because the options card is hidden
+          // on `noOptions` and would otherwise leave a dead button unexplained.
+          lastProduct = undefined;
+          lastLoadedId = undefined;
           return derive({
             ...s,
             status: "ready",
+            optionGroups: [],
+            selection: {},
+            optionsUnknown: true,
             name,
             price: String(cached.subtitle ?? ""),
             description: "",
             image,
             initial: String(cached.initial ?? "") || (name[0] || "#").toUpperCase(),
-            cartHint: "",
+            cartHint: copyParam("product.cartHintOffline", "Reconnect to choose options and add this to your cart."),
             cartCount: await cartItemCount(),
             emptyText: "",
             quantity: 1,
           });
         }
-        return derive({ ...s, status: "error", emptyText: copyParam("product.errorText", "Product could not load.") });
+        lastProduct = undefined;
+        lastLoadedId = undefined;
+        return derive({ ...s, status: "error", optionGroups: [], selection: {}, optionsUnknown: false, emptyText: copyParam("product.errorText", "Product could not load.") });
       }
     },
     // The stepper fires onChange with { value } on every tap; clamp 1–99 and
@@ -267,6 +432,24 @@ const svc = defineService<S, {
       const quantity = parseQuantity(argValue(arg, "value"));
       return quantity ? derive({ ...s, quantity }) : s;
     },
+    // One chip row per option group. `group` is the descriptor slot ("1".."3");
+    // FilterChips sends back the WHOLE selected set, which for a single-select row
+    // is either one id or none (re-tapping the active chip clears it).
+    selectOption: (s, arg) => {
+      const slot = Math.floor(Number(argValue(arg, "group")));
+      const group = s.optionGroups[slot - 1];
+      if (!group) return s;
+      const raw = (arg as { selectedIds?: unknown } | undefined)?.selectedIds;
+      const picked = Array.isArray(raw) ? String(raw[0] ?? "") : String(raw ?? "");
+      // Only a choice this group actually offers — a stale id from a previous
+      // product would otherwise resolve to no variant and block the cart silently.
+      const choice = group.choices.some((c) => c.id === picked) ? picked : "";
+      const selection = { ...s.selection };
+      if (choice) selection[group.id] = choice; else delete selection[group.id];
+      // A new choice invalidates the last add's confirmation — it was for the
+      // previous variant.
+      return derive({ ...s, selection, added: false, cartHint: "" });
+    },
     // The pending half of addToCart, as its own reducer so it PUBLISHES before the
     // network write starts: the pending line shows and the top-bar badge ticks up in the same
     // interaction, instead of the tap looking dead until the round-trip (and the badge re-read)
@@ -280,20 +463,44 @@ const svc = defineService<S, {
       if (!id) return derive({ ...s, cartHint: copyParam("product.cartHintNoProduct", "No product to add.") });
       // A second tap while the first write is in flight must not add the line twice.
       if (s.adding) return s;
+      // The CTA is already disabled on this state; this is the second gate, because
+      // a voice-control/deep-link dispatch reaches the action without the button.
+      if (s.optionsIncomplete) {
+        // With no groups in hand there is nothing for `optionsHint` to name, so the
+        // offline case needs its own reason rather than an empty string.
+        return derive({ ...s, cartHint: s.optionsUnknown
+          ? copyParam("product.cartHintOffline", "Reconnect to choose options and add this to your cart.")
+          : optionsHint(s.optionGroups, s.selection) || copyParam("product.cartHintNoVariant", "That combination is not available. Try another.") });
+      }
+      // Which variant the choice resolves to is the SDK's job — V3 addresses the
+      // choice by variantId, V1 by a name→choice map, and it throws rather than
+      // hand back a payload that would add a line with no variant.
+      let cartOptions: Record<string, unknown> | undefined;
+      try {
+        cartOptions = cartOptionsPayload(lastProduct, s.optionGroups, s.selection);
+      } catch {
+        return derive({ ...s, cartHint: copyParam("product.cartHintNoVariant", "That combination is not available. Try another.") });
+      }
       const quantity = s.quantity > 0 ? s.quantity : 1;
       const before = s.cartCount;
       await svc.beginAdd({ quantity: String(quantity) });
       s = svc.getState() as S;
       // Optimistic local cart line — the cart repaints from cache immediately (offline or not).
-      const line: DbEntity = { id: `line-${id}`, productId: id, name: s.name || "product", title: s.name || "product", subtitle: `Qty ${quantity}`, quantity: String(quantity) };
+      const chosen = selectionSummary(s.optionGroups, s.selection);
+      // Keyed by product AND variant. `line-${id}` alone collapses two variants of the
+      // same product into one cached row while the badge counts both — the offline cart
+      // then shows one line for two adds. Sorted so the key is stable whatever order the
+      // groups were picked in, and reduced to id-safe characters.
+      const variantKey = Object.keys(s.selection).sort().map((k) => `${k}:${s.selection[k]}`).join("|").replace(/[^A-Za-z0-9]+/g, "_");
+      const line: DbEntity = { id: variantKey ? `line-${id}-${variantKey}` : `line-${id}`, productId: id, name: s.name || "product", title: s.name || "product", subtitle: chosen ? `${chosen} · Qty ${quantity}` : `Qty ${quantity}`, quantity: String(quantity) };
       await cartPut(line);
       try {
-        await addToCurrentCart(id, quantity);
+        await addToCurrentCart(id, quantity, cartOptions);
       } catch (e) {
         if (isBridgeUnavailable(e)) {
           // Offline / no bridge: the optimistic cache line already shows; queue the
           // add to replay (WriteQueue, idempotent) when connectivity returns.
-          await queueWrite("tier5.himiStoreProduct.addToCart", { id });
+          await queueWrite("tier5.himiStoreProduct.addToCart", { id, ...(cartOptions ? { options: JSON.stringify(cartOptions) } : {}) });
           return derive({ ...s, adding: false, added: false, cartHint: copyTemplate("product.cartHintQueued", "Added {name} to cart. Will sync when you reconnect.", { name: s.name || "product" }) });
         }
         // Roll the optimistic badge back — nothing was added.