@magicx-eng/ai-autocomplete-vanilla 0.34.0 → 0.35.0

package/README.md

@@ -202,7 +202,10 @@ Each server item becomes a `Product` with `id` (the item's stable id), `title`,
 currency is yours to add), `vendor`, `imageUrl`, and a `url`: the item's own
 `item_url` when the uploaded catalog named one (absolute or root-relative;
 anything else is ignored), else a **relative** `/products/{handle}` — the right
-link for a Shopify widget running on the storefront itself. An item with
+link for a Shopify widget running on the storefront itself — opened on the
+variant the query chose (`?variant=…`, e.g. the blue one for "blue shoes") when
+there is one, whose price and image the card then shows. `available` is carried
+over when the server reports it. An item with
 neither gets no `url`: its card is still activatable and still emits
 `onProductSelect`, it just has nothing for cmd-click to open. `productFromMatchedItem` / `productsFromCustomFields` are
 exported for a hand-rolled strip that wants the same mapping.
@@ -229,6 +232,17 @@ empty or whitespace-only title shows `?`. The fallback works in both row and
 list layouts. Initial tiles are decorative (`aria-hidden="true"`); the card's
 visible title supplies its text.
 
+**Sold out.** A product with `available: false` shows a "Sold out" badge over
+the top-left of its image (in the list layout, a smaller banner across the
+bottom of the thumbnail) and its image is desaturated; the card stays
+selectable and keeps its link. Absent or `true` shows no
+badge, so leave `available` out when you don't know. The badge is part of the
+card's text, so screen readers announce it. Theme it with
+`--aia-product-badge-bg`, `--aia-product-badge-color`,
+`--aia-product-badge-font-size` and `--aia-product-badge-inset`, and the list
+banner with `--aia-product-badge-list-bg`, `--aia-product-badge-list-color` and
+`--aia-product-badge-list-font-size`.
+
 Set the option at construction or change it through `update()`. Both
 rendered tiers (`"full"` and `"dropdown"`) apply it to the visible cards:
 
@@ -340,7 +354,7 @@ new AIAutocomplete(container, {
 });
 ```
 
-`Product` is exactly six fields; only `id` and `title` are required:
+`Product` is exactly seven fields; only `id` and `title` are required:
 
 ```ts
 type Product = {
@@ -350,6 +364,7 @@ type Product = {
   imageUrl?: string | null;   // null uses the configured productImageFallback
   price?: string;             // pre-formatted by you
   vendor?: string;
+  available?: boolean;        // false shows a "Sold out" badge
 };
 ```
 

package/dist/index.d.mts

@@ -154,6 +154,18 @@ interface MatchedItem {
      * item carries `handle` instead. When both are present the strip links here.
      */
     item_url?: string;
+    /**
+     * The variant a filter in the query chose for this item ("blue", "size 10"),
+     * as the platform's numeric variant id. When set, `price` and `image_url`
+     * are that variant's, and the strip links to `/products/{handle}?variant=…`
+     * so the shopper lands on it.
+     */
+    variant_id?: string;
+    /**
+     * Whether the item can be bought: `false` is sold out. Absent when the
+     * catalog doesn't say, which is not the same as sold out.
+     */
+    available?: boolean;
 }
 /** The items the applied filters left standing. */
 interface MatchedItems {
@@ -352,6 +364,12 @@ interface Product {
     /** Pre-formatted by the integration, which is the side that knows the currency. */
     price?: string;
     vendor?: string;
+    /**
+     * `false` marks the card sold out: a "Sold out" badge over the image, and
+     * the image desaturated. The card stays selectable. Absent or `true` shows no
+     * badge — leave it out when availability is unknown.
+     */
+    available?: boolean;
 }
 /**
  * How the product strip lays its cards out. `"row"` is the horizontally
@@ -2181,9 +2199,10 @@ declare const PRODUCT_PATH_PREFIX = "/products/";
  * `customFields` gets the same cards the built-in one draws.
  *
  * The link is the item's own `item_url` when the catalog named one, else the
- * `/products/{handle}` path a Shopify item implies. An item with neither
- * yields a card without a `url`: still activatable, still emitting
- * `onProductSelect`, just nothing for cmd-click to open.
+ * `/products/{handle}` path a Shopify item implies, opened on the chosen
+ * variant when there is one. An item with neither yields a card without a
+ * `url`: still activatable, still emitting `onProductSelect`, just nothing for
+ * cmd-click to open.
  */
 declare function productFromMatchedItem(item: MatchedItem): Product;
 /**

package/dist/index.d.ts

@@ -154,6 +154,18 @@ interface MatchedItem {
      * item carries `handle` instead. When both are present the strip links here.
      */
     item_url?: string;
+    /**
+     * The variant a filter in the query chose for this item ("blue", "size 10"),
+     * as the platform's numeric variant id. When set, `price` and `image_url`
+     * are that variant's, and the strip links to `/products/{handle}?variant=…`
+     * so the shopper lands on it.
+     */
+    variant_id?: string;
+    /**
+     * Whether the item can be bought: `false` is sold out. Absent when the
+     * catalog doesn't say, which is not the same as sold out.
+     */
+    available?: boolean;
 }
 /** The items the applied filters left standing. */
 interface MatchedItems {
@@ -352,6 +364,12 @@ interface Product {
     /** Pre-formatted by the integration, which is the side that knows the currency. */
     price?: string;
     vendor?: string;
+    /**
+     * `false` marks the card sold out: a "Sold out" badge over the image, and
+     * the image desaturated. The card stays selectable. Absent or `true` shows no
+     * badge — leave it out when availability is unknown.
+     */
+    available?: boolean;
 }
 /**
  * How the product strip lays its cards out. `"row"` is the horizontally
@@ -2181,9 +2199,10 @@ declare const PRODUCT_PATH_PREFIX = "/products/";
  * `customFields` gets the same cards the built-in one draws.
  *
  * The link is the item's own `item_url` when the catalog named one, else the
- * `/products/{handle}` path a Shopify item implies. An item with neither
- * yields a card without a `url`: still activatable, still emitting
- * `onProductSelect`, just nothing for cmd-click to open.
+ * `/products/{handle}` path a Shopify item implies, opened on the chosen
+ * variant when there is one. An item with neither yields a card without a
+ * `url`: still activatable, still emitting `onProductSelect`, just nothing for
+ * cmd-click to open.
  */
 declare function productFromMatchedItem(item: MatchedItem): Product;
 /**