@coveo/thermidor-schema 1.0.0-beta.2 → 1.0.0-beta.4

package/schema/components/pagination.schema.json

@@ -18,10 +18,7 @@
     },
     "actions": {
       "type": "object",
-      "required": [
-        "selectPage",
-        "setPageSize"
-      ],
+      "required": ["selectPage", "setPageSize"],
       "properties": {
         "selectPage": {
           "$ref": "#/$defs/SelectPageAction"
@@ -31,6 +28,17 @@
         }
       },
       "additionalProperties": false
+    },
+    "children": {
+      "type": "array",
+      "items": {
+        "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
+      },
+      "maxItems": 1000,
+      "default": []
+    },
+    "child": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
     }
   },
   "additionalProperties": false,
@@ -39,12 +47,7 @@
       "title": "PaginationState",
       "description": "The current pagination state. Owned exclusively by the backend.",
       "type": "object",
-      "required": [
-        "page",
-        "pageSize",
-        "totalEntries",
-        "totalPages"
-      ],
+      "required": ["page", "pageSize", "totalEntries", "totalPages"],
       "properties": {
         "page": {
           "type": "integer",
@@ -80,9 +83,7 @@
       "properties": {
         "payload": {
           "type": "object",
-          "required": [
-            "page"
-          ],
+          "required": ["page"],
           "properties": {
             "page": {
               "type": "integer",
@@ -105,9 +106,7 @@
       "properties": {
         "payload": {
           "type": "object",
-          "required": [
-            "pageSize"
-          ],
+          "required": ["pageSize"],
           "properties": {
             "pageSize": {
               "type": "integer",
@@ -120,4 +119,4 @@
       }
     }
   }
-}
+}

package/schema/components/product-carousel.schema.json

@@ -20,6 +20,17 @@
       "type": "object",
       "properties": {},
       "additionalProperties": false
+    },
+    "children": {
+      "type": "array",
+      "items": {
+        "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
+      },
+      "maxItems": 1000,
+      "default": []
+    },
+    "child": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
     }
   },
   "additionalProperties": false,
@@ -29,10 +40,7 @@
       "description": "The ordered list of products to render. Owned exclusively by the backend; the frontend must not mutate this directly.",
       "$comment": "This schema validates the runtime state value the backend pushes to the frontend.",
       "type": "object",
-      "required": [
-        "heading",
-        "products"
-      ],
+      "required": ["heading", "products"],
       "properties": {
         "heading": {
           "type": "string",
@@ -49,4 +57,4 @@
       "additionalProperties": false
     }
   }
-}
+}

package/schema/components/product-list.schema.json

@@ -20,6 +20,17 @@
       "type": "object",
       "properties": {},
       "additionalProperties": false
+    },
+    "children": {
+      "type": "array",
+      "items": {
+        "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
+      },
+      "maxItems": 1000,
+      "default": []
+    },
+    "child": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
     }
   },
   "additionalProperties": false,
@@ -28,9 +39,7 @@
       "title": "ProductListState",
       "description": "The ordered list of products to render. Owned exclusively by the backend; the frontend must not mutate this directly.",
       "type": "object",
-      "required": [
-        "products"
-      ],
+      "required": ["products"],
       "properties": {
         "products": {
           "type": "array",
@@ -43,4 +52,4 @@
       "additionalProperties": false
     }
   }
-}
+}

package/schema/components/product-summary.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.thermidor.coveo.com/components/product-summary.schema.json",
+  "title": "ProductSummary",
+  "description": "Renders a single commerce product as a compact summary row (thumbnail, name, short description, price) for a category slot. Read-only from the frontend: the backend is the sole source of truth for the summarized product. Presentation as a compact row is expressed by this component type on the A2-UI plane, never as data in AG-UI state.",
+  "allOf": [
+    {
+      "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
+    }
+  ],
+  "properties": {
+    "componentType": {
+      "type": "string",
+      "const": "product-summary"
+    },
+    "state": {
+      "$ref": "#/$defs/ProductSummaryState"
+    },
+    "actions": {
+      "type": "object",
+      "properties": {},
+      "additionalProperties": false
+    },
+    "children": {
+      "type": "array",
+      "items": {
+        "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
+      },
+      "maxItems": 1000,
+      "default": []
+    },
+    "child": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "ProductSummaryState": {
+      "title": "ProductSummaryState",
+      "description": "The single product to summarize for a category slot. Owned exclusively by the backend; the frontend must not mutate this directly.",
+      "type": "object",
+      "required": ["categoryLabel", "product"],
+      "properties": {
+        "categoryLabel": {
+          "type": "string",
+          "description": "Display label of the product category this summary represents (e.g. 'Surfboard')."
+        },
+        "product": {
+          "description": "The single product to summarize, or null when no product is available for this slot.",
+          "oneOf": [
+            {
+              "$ref": "https://schema.thermidor.coveo.com/definitions/product.schema.json"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schema/components/query-summary.schema.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.thermidor.coveo.com/components/query-summary.schema.json",
+  "title": "QuerySummary",
+  "description": "Summarizes the current result window for a search surface (e.g. 'Products 1-12 of 43 for Water Sports'). Read-only from the frontend. Rather than reading three sibling components' state (search-box query, pagination page/pageSize/totalEntries, product-list count), it carries its own backend-computed aggregate so it has no cross-component coupling.",
+  "allOf": [
+    {
+      "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
+    }
+  ],
+  "properties": {
+    "componentType": {
+      "type": "string",
+      "const": "query-summary"
+    },
+    "state": {
+      "$ref": "#/$defs/QuerySummaryState"
+    },
+    "actions": {
+      "type": "object",
+      "properties": {},
+      "additionalProperties": false
+    },
+    "children": {
+      "type": "array",
+      "items": {
+        "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
+      },
+      "maxItems": 1000,
+      "default": []
+    },
+    "child": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "QuerySummaryState": {
+      "title": "QuerySummaryState",
+      "description": "The backend-computed aggregate for the current result window. Owned exclusively by the backend; the frontend must not mutate this directly.",
+      "type": "object",
+      "required": ["query", "firstIndex", "lastIndex", "totalEntries"],
+      "properties": {
+        "query": {
+          "type": "string",
+          "description": "The current query string. May be empty when the surface has no active query."
+        },
+        "firstIndex": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "The 1-based index of the first result on the current page."
+        },
+        "lastIndex": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "The 1-based index of the last result on the current page."
+        },
+        "totalEntries": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "The total number of results across all pages."
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schema/components/regular-facet.schema.json

@@ -63,6 +63,17 @@
         }
       },
       "additionalProperties": false
+    },
+    "children": {
+      "type": "array",
+      "items": {
+        "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
+      },
+      "maxItems": 1000,
+      "default": []
+    },
+    "child": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
     }
   },
   "additionalProperties": false,
@@ -125,11 +136,7 @@
       "title": "RegularFacetValue",
       "description": "A single selectable value within a regular facet.",
       "type": "object",
-      "required": [
-        "value",
-        "numberOfResults",
-        "state"
-      ],
+      "required": ["value", "numberOfResults", "state"],
       "properties": {
         "value": {
           "type": "string",
@@ -154,11 +161,7 @@
       "title": "RegularFacetSearch",
       "description": "The facet search state for a regular facet.",
       "type": "object",
-      "required": [
-        "query",
-        "canShowMoreResults",
-        "results"
-      ],
+      "required": ["query", "canShowMoreResults", "results"],
       "properties": {
         "query": {
           "type": "string",
@@ -186,10 +189,7 @@
       "title": "RegularFacetSearchResult",
       "description": "A single result returned by a regular facet search. Facet search only returns idle (unselected) values, so it carries no selection state.",
       "type": "object",
-      "required": [
-        "value",
-        "numberOfResults"
-      ],
+      "required": ["value", "numberOfResults"],
       "properties": {
         "value": {
           "type": "string",
@@ -217,9 +217,7 @@
       "properties": {
         "payload": {
           "type": "object",
-          "required": [
-            "value"
-          ],
+          "required": ["value"],
           "properties": {
             "value": {
               "type": "string",
@@ -243,9 +241,7 @@
       "properties": {
         "payload": {
           "type": "object",
-          "required": [
-            "value"
-          ],
+          "required": ["value"],
           "properties": {
             "value": {
               "type": "string",
@@ -269,9 +265,7 @@
       "properties": {
         "payload": {
           "type": "object",
-          "required": [
-            "value"
-          ],
+          "required": ["value"],
           "properties": {
             "value": {
               "type": "string",
@@ -295,9 +289,7 @@
       "properties": {
         "payload": {
           "type": "object",
-          "required": [
-            "value"
-          ],
+          "required": ["value"],
           "properties": {
             "value": {
               "type": "string",
@@ -330,9 +322,7 @@
       "properties": {
         "payload": {
           "type": "object",
-          "required": [
-            "query"
-          ],
+          "required": ["query"],
           "properties": {
             "query": {
               "type": "string",
@@ -382,4 +372,4 @@
       ]
     }
   }
-}
+}

package/schema/components/sort.schema.json

@@ -18,15 +18,24 @@
     },
     "actions": {
       "type": "object",
-      "required": [
-        "selectSort"
-      ],
+      "required": ["selectSort"],
       "properties": {
         "selectSort": {
           "$ref": "#/$defs/SelectSortAction"
         }
       },
       "additionalProperties": false
+    },
+    "children": {
+      "type": "array",
+      "items": {
+        "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
+      },
+      "maxItems": 1000,
+      "default": []
+    },
+    "child": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
     }
   },
   "additionalProperties": false,
@@ -35,10 +44,7 @@
       "title": "SortState",
       "description": "The current sort state. Owned exclusively by the backend.",
       "type": "object",
-      "required": [
-        "appliedSort",
-        "availableSorts"
-      ],
+      "required": ["appliedSort", "availableSorts"],
       "properties": {
         "appliedSort": {
           "$ref": "#/$defs/SortCriterion",
@@ -58,10 +64,7 @@
       "title": "SortCriterion",
       "description": "A sort criterion consisting of a named criteria and field definitions.",
       "type": "object",
-      "required": [
-        "sortCriteria",
-        "fields"
-      ],
+      "required": ["sortCriteria", "fields"],
       "properties": {
         "sortCriteria": {
           "type": "string",
@@ -85,10 +88,7 @@
       "properties": {
         "payload": {
           "type": "object",
-          "required": [
-            "sortCriteria",
-            "fields"
-          ],
+          "required": ["sortCriteria", "fields"],
           "properties": {
             "sortCriteria": {
               "type": "string",
@@ -104,4 +104,4 @@
       }
     }
   }
-}
+}

package/schema/definitions/bundle-tier.schema.json

@@ -27,15 +27,15 @@
     "BundleSlot": {
       "title": "BundleSlot",
       "type": "object",
-      "required": ["categoryLabel", "surfaceRef"],
+      "required": ["categoryLabel", "childId"],
       "properties": {
         "categoryLabel": {
           "type": "string",
           "description": "Display name of the product category for this slot."
         },
-        "surfaceRef": {
+        "childId": {
           "type": "string",
-          "description": "Surface ID where this slot's products are rendered via a ProductCarousel."
+          "description": "Id of the bundle-display child product-list node that renders this slot's products. Associates the slot with its child on the A2-UI composition plane; the renderer mounts the child via children(id)."
         }
       },
       "additionalProperties": false

package/schema/definitions/child-ref.schema.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json",
+  "title": "ChildRef",
+  "type": "string",
+  "pattern": "^[a-z][a-z0-9-]*$",
+  "description": "A reference to another component in the same flat map, by componentId."
+}

package/schema/definitions/comparison-attribute.schema.json

@@ -2,13 +2,13 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://schema.thermidor.coveo.com/definitions/comparison-attribute.schema.json",
   "title": "ComparisonAttribute",
-  "description": "Defines an attribute (column) used in a ComparisonTable. The key is the programmatic identifier that maps to values in ComparisonProduct.values, and label is the human-readable column heading.",
+  "description": "Defines an attribute (row) used in a ComparisonTable. The key is the programmatic identifier that maps to values in each compared product's values record, and label is the human-readable row heading.",
   "type": "object",
   "required": ["key", "label"],
   "properties": {
     "key": {
       "type": "string",
-      "description": "The programmatic identifier for this attribute, used as a key in ComparisonProduct.values."
+      "description": "The programmatic identifier for this attribute, used as a key in each compared product's values record."
     },
     "label": {
       "type": "string",

package/schema/definitions/comparison-product.schema.json

@@ -2,9 +2,9 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://schema.thermidor.coveo.com/definitions/comparison-product.schema.json",
   "title": "ComparisonProduct",
-  "description": "A product entry in a comparison table, containing required identifiers and a values record mapping attribute keys to display strings.",
+  "description": "A product entry (column) in a ComparisonTable, containing required identifiers and a values record mapping attribute keys to display strings.",
   "type": "object",
-  "required": ["productId", "name", "values"],
+  "required": ["productId", "name"],
   "properties": {
     "productId": {
       "type": "string",

package/schema/components/cart.schema.json

@@ -1,108 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://schema.thermidor.coveo.com/components/cart.schema.json",
-  "title": "Cart",
-  "description": "Renders the current cart contents and exposes actions for the frontend to manage line items.",
-  "allOf": [
-    {
-      "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
-    }
-  ],
-  "properties": {
-    "componentType": {
-      "type": "string",
-      "const": "cart"
-    },
-    "state": {
-      "$ref": "#/$defs/CartState"
-    },
-    "actions": {
-      "type": "object",
-      "required": [
-        "setItems",
-        "updateItemQuantity"
-      ],
-      "properties": {
-        "setItems": {
-          "$ref": "#/$defs/SetItemsAction"
-        },
-        "updateItemQuantity": {
-          "$ref": "#/$defs/UpdateItemQuantityAction"
-        }
-      },
-      "additionalProperties": false
-    }
-  },
-  "additionalProperties": false,
-  "$defs": {
-    "CartState": {
-      "title": "CartState",
-      "description": "The current contents of the cart. Owned exclusively by the backend; the frontend must not mutate this directly.",
-      "$comment": "This schema validates the runtime state value the backend pushes to the frontend.",
-      "type": "object",
-      "required": [
-        "items"
-      ],
-      "properties": {
-        "items": {
-          "type": "array",
-          "description": "The current line items in the cart.",
-          "items": {
-            "$ref": "https://schema.thermidor.coveo.com/definitions/cart-item.schema.json"
-          }
-        }
-      },
-      "additionalProperties": false
-    },
-    "SetItemsAction": {
-      "title": "setItems",
-      "description": "Replaces the entire cart contents with the provided list of items.",
-      "allOf": [
-        {
-          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
-        }
-      ],
-      "properties": {
-        "payload": {
-          "type": "object",
-          "required": [
-            "items"
-          ],
-          "properties": {
-            "items": {
-              "type": "array",
-              "description": "The new complete list of cart items. An empty array clears the cart.",
-              "items": {
-                "$ref": "https://schema.thermidor.coveo.com/definitions/cart-item.schema.json"
-              }
-            }
-          },
-          "additionalProperties": false
-        }
-      }
-    },
-    "UpdateItemQuantityAction": {
-      "title": "updateItemQuantity",
-      "description": "Updates the quantity of a single existing cart line item identified by productId.",
-      "allOf": [
-        {
-          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
-        }
-      ],
-      "properties": {
-        "payload": {
-          "type": "object",
-          "required": [
-            "item"
-          ],
-          "properties": {
-            "item": {
-              "$ref": "https://schema.thermidor.coveo.com/definitions/cart-item.schema.json"
-            }
-          },
-          "additionalProperties": false
-        }
-      }
-    }
-  }
-}

package/schema/definitions/cart-item.schema.json

@@ -1,29 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://schema.thermidor.coveo.com/definitions/cart-item.schema.json",
-  "title": "CartItem",
-  "description": "A single line item in the cart, as exposed by the CartController state and used in cart action payloads.",
-  "type": "object",
-  "required": ["productId", "name", "price", "quantity"],
-  "properties": {
-    "productId": {
-      "type": "string",
-      "description": "The unique product identifier. Corresponds to the Product's permanentid field."
-    },
-    "name": {
-      "type": "string",
-      "description": "The display name of the product at the time it was added to the cart."
-    },
-    "price": {
-      "type": "number",
-      "minimum": 0,
-      "description": "The non-negative unit price at the time the item was added, in the session currency."
-    },
-    "quantity": {
-      "type": "integer",
-      "minimum": 1,
-      "description": "The number of units of this product in the cart."
-    }
-  },
-  "additionalProperties": false
-}