@coveo/thermidor-schema 1.0.0-beta.3 → 1.0.0-beta.30

package/schema/components/next-actions-bar.schema.json

@@ -2,40 +2,40 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://schema.thermidor.coveo.com/components/next-actions-bar.schema.json",
   "title": "NextActionsBar",
-  "description": "Renders a set of suggested next actions the user can pick from. The selectAction action is dispatched when the user clicks an action button.",
+  "description": "Renders a set of suggested next actions the user can pick from. The selectAction action is dispatched when the user clicks a \"followup\" or \"search\" action button, and selectSearchOption when they click a \"searchOption\" one.",
   "allOf": [
     {
       "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
     }
   ],
   "properties": {
-    "componentType": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
       "type": "string",
-      "const": "next-actions-bar"
+      "const": "NextActionsBar"
+    },
+    "suggestedActions": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "Bound list of selectable next-action descriptors (bound to /state/<id>/suggestedActions). Presentation data, not the dispatchable actions map.",
+      "$comment": "Named `suggestedActions` (not `actions`) so it does not collide with the reserved dispatchable `actions` map."
     },
     "state": {
       "$ref": "#/$defs/NextActionsState"
     },
     "actions": {
       "type": "object",
-      "required": ["selectAction"],
+      "required": ["selectAction", "selectSearchOption"],
       "properties": {
         "selectAction": {
           "$ref": "#/$defs/SelectActionAction"
+        },
+        "selectSearchOption": {
+          "$ref": "#/$defs/SelectSearchOptionAction"
         }
       },
       "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,
@@ -45,9 +45,9 @@
       "description": "The list of suggested actions 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": ["actions"],
+      "required": ["suggestedActions"],
       "properties": {
-        "actions": {
+        "suggestedActions": {
           "type": "array",
           "description": "Suggested actions the assistant offers the user.",
           "items": {
@@ -83,6 +83,29 @@
           "additionalProperties": false
         }
       }
+    },
+    "SelectSearchOptionAction": {
+      "title": "selectSearchOption",
+      "description": "Signals that the user selected a \"searchOption\" action. The backend runs the search it saved under optionId.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": ["optionId"],
+          "properties": {
+            "optionId": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The optionId of the selected action, echoed unchanged."
+            }
+          },
+          "additionalProperties": false
+        }
+      }
     }
   }
 }

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

@@ -9,9 +9,44 @@
     }
   ],
   "properties": {
-    "componentType": {
+    "component": {
       "type": "string",
-      "const": "numeric-facet"
+      "const": "NumericFacet"
+    },
+    "id": {
+      "type": "string"
+    },
+    "field": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The index field the facet queries, bound to /state/<id>/field."
+    },
+    "displayName": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The facet's human-readable label, bound to /state/<id>/displayName."
+    },
+    "values": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The numeric-range facet values, bound to /state/<id>/values."
+    },
+    "customRange": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The custom range, bound to /state/<id>/customRange."
+    },
+    "hasActiveValues": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "Whether at least one facet value is active, bound to /state/<id>/hasActiveValues."
+    },
+    "canShowMoreValues": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "Whether more facet values can be shown, bound to /state/<id>/canShowMoreValues."
+    },
+    "canShowLessValues": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "Whether fewer facet values can be shown, bound to /state/<id>/canShowLessValues."
+    },
+    "domain": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The numeric domain (min/max) of the facet, bound to /state/<id>/domain."
     },
     "state": {
       "$ref": "#/$defs/NumericFacetState"
@@ -47,17 +82,6 @@
         }
       },
       "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,
@@ -87,8 +111,6 @@
         "values": {
           "type": "array",
           "description": "The numeric range values available for this facet.",
-          "minItems": 0,
-          "maxItems": 500,
           "items": {
             "$ref": "#/$defs/NumericFacetValue"
           }

package/schema/components/page-size.schema.json

@@ -2,16 +2,24 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://schema.thermidor.coveo.com/components/page-size.schema.json",
   "title": "PageSize",
-  "description": "A 'Products per page' selector for a search surface. Its own componentType lets it be mounted through the A2-UI tree (one renderer per componentType). It owns the current pageSize in its state and dispatches setPageSize; the backend applies the change to the surface's paging so the pagination component re-renders from the shared view.",
+  "description": "A 'Products per page' selector for a search surface. Owns the current pageSize in its state and dispatches setPageSize.",
+  "$comment": "Its own component discriminant lets it mount through the A2-UI tree. The backend applies the change so the pagination component re-renders from the shared view.",
   "allOf": [
     {
       "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
     }
   ],
   "properties": {
-    "componentType": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
       "type": "string",
-      "const": "page-size"
+      "const": "PageSize"
+    },
+    "pageSize": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The current page size, bound to /state/<id>/pageSize via a { \"path\": ... } Data_Binding."
     },
     "state": {
       "$ref": "#/$defs/PageSizeState"
@@ -25,24 +33,14 @@
         }
       },
       "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": {
     "PageSizeState": {
       "title": "PageSizeState",
-      "description": "The current page size. Owned exclusively by the backend. Kept as its own entry (keyed by this component's id) so the selector reads exactly the field it needs without depending on the pagination component's state shape.",
+      "description": "The current page size. Owned exclusively by the backend.",
+      "$comment": "Kept as its own entry (keyed by this component's id) so the selector reads only the field it needs, independent of the pagination component's state shape.",
       "type": "object",
       "required": ["pageSize"],
       "properties": {

package/schema/components/pagination.schema.json

@@ -9,36 +9,47 @@
     }
   ],
   "properties": {
-    "componentType": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
       "type": "string",
-      "const": "pagination"
+      "const": "Pagination"
+    },
+    "page": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The current page number, bound to /state/<id>/page via a { \"path\": ... } Data_Binding."
+    },
+    "pageSize": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The number of items per page, bound to /state/<id>/pageSize."
+    },
+    "totalEntries": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The total number of items, bound to /state/<id>/totalEntries."
+    },
+    "totalPages": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The total number of pages, bound to /state/<id>/totalPages."
     },
     "state": {
       "$ref": "#/$defs/PaginationState"
     },
     "actions": {
       "type": "object",
-      "required": ["selectPage", "setPageSize"],
+      "required": ["selectPage", "setPageSize", "showMore"],
       "properties": {
         "selectPage": {
           "$ref": "#/$defs/SelectPageAction"
         },
         "setPageSize": {
           "$ref": "#/$defs/SetPageSizeAction"
+        },
+        "showMore": {
+          "$ref": "#/$defs/ShowMoreAction"
         }
       },
       "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,
@@ -117,6 +128,22 @@
           "additionalProperties": false
         }
       }
+    },
+    "ShowMoreAction": {
+      "title": "showMore",
+      "description": "Advances to the next page while preserving backend ownership of pagination state.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "properties": {},
+          "additionalProperties": false
+        }
+      }
     }
   }
 }

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

@@ -9,9 +9,20 @@
     }
   ],
   "properties": {
-    "componentType": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
       "type": "string",
-      "const": "product-carousel"
+      "const": "ProductCarousel"
+    },
+    "heading": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The carousel heading, bound to /state/<id>/heading."
+    },
+    "products": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The ordered list of products, bound to /state/<id>/products."
     },
     "state": {
       "$ref": "#/$defs/ProductCarouselState"
@@ -20,17 +31,6 @@
       "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,

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

@@ -9,28 +9,32 @@
     }
   ],
   "properties": {
-    "componentType": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
       "type": "string",
-      "const": "product-list"
+      "const": "ProductList"
+    },
+    "products": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The ordered list of products, bound to /state/<id>/products via a { \"path\": ... } Data_Binding."
     },
     "state": {
       "$ref": "#/$defs/ProductListState"
     },
     "actions": {
       "type": "object",
-      "properties": {},
-      "additionalProperties": false
-    },
-    "children": {
-      "type": "array",
-      "items": {
-        "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
+      "required": ["selectProducts", "productClick"],
+      "properties": {
+        "selectProducts": {
+          "$ref": "#/$defs/SelectProductsAction"
+        },
+        "productClick": {
+          "$ref": "#/$defs/ProductClickAction"
+        }
       },
-      "maxItems": 1000,
-      "default": []
-    },
-    "child": {
-      "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
+      "additionalProperties": false
     }
   },
   "additionalProperties": false,
@@ -50,6 +54,63 @@
         }
       },
       "additionalProperties": false
+    },
+    "SelectProductsAction": {
+      "title": "selectProducts",
+      "description": "Persists the set of products selected by the shopper.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": ["productIds"],
+          "properties": {
+            "productIds": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+    "ProductClickAction": {
+      "title": "productClick",
+      "description": "Records a shopper clicking a product result.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": ["productId", "position"],
+          "properties": {
+            "productId": {
+              "type": "string",
+              "minLength": 1
+            },
+            "name": {
+              "type": "string"
+            },
+            "price": {
+              "type": ["number", "null"]
+            },
+            "position": {
+              "type": "integer",
+              "minimum": 0
+            }
+          },
+          "additionalProperties": false
+        }
+      }
     }
   }
 }

package/schema/components/product-research-card.schema.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.thermidor.coveo.com/components/product-research-card.schema.json",
+  "title": "ProductResearchCard",
+  "description": "Renders a research card for a single known product: the product details alongside a short research summary and a list of concise product-education bullets. Read-only from the frontend: the backend is the sole source of truth for the product and the research content.",
+  "allOf": [
+    {
+      "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
+    }
+  ],
+  "properties": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
+      "type": "string",
+      "const": "ProductResearchCard"
+    },
+    "product": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The researched product, bound to /state/<id>/product."
+    },
+    "summary": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The research summary, bound to /state/<id>/summary."
+    },
+    "bullets": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The product-education bullets, bound to /state/<id>/bullets."
+    },
+    "relatedDocuments": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The related documents, bound to /state/<id>/relatedDocuments."
+    },
+    "state": {
+      "$ref": "#/$defs/ProductResearchCardState"
+    },
+    "actions": {
+      "type": "object",
+      "properties": {},
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "ProductResearchCardState": {
+      "title": "ProductResearchCardState",
+      "description": "The researched product, its research content, and related documents. 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": ["product", "summary", "bullets"],
+      "properties": {
+        "product": {
+          "$ref": "https://schema.thermidor.coveo.com/definitions/product.schema.json"
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Short research paragraph about the product."
+        },
+        "bullets": {
+          "type": "array",
+          "minItems": 1,
+          "description": "Concise product-education bullets, in display order. Producers currently emit at most 5 bullets.",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "relatedDocuments": {
+          "type": "array",
+          "description": "Documents related to the researched product, in display order.",
+          "items": {
+            "$ref": "#/$defs/ProductResearchRelatedDocument"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "ProductResearchRelatedDocument": {
+      "title": "ProductResearchRelatedDocument",
+      "description": "A document related to the researched product.",
+      "type": "object",
+      "required": ["title"],
+      "properties": {
+        "title": {
+          "type": "string",
+          "description": "The display title of the document."
+        },
+        "clickUri": {
+          "type": "string",
+          "description": "The URI used to open the document."
+        },
+        "size": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "The document size in bytes."
+        },
+        "filetype": {
+          "type": "string",
+          "description": "The document file type."
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

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

@@ -2,16 +2,28 @@
   "$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.",
+  "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.",
+  "$comment": "Compact-row presentation 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": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
       "type": "string",
-      "const": "product-summary"
+      "const": "ProductSummary"
+    },
+    "categoryLabel": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The product category label, bound to /state/<id>/categoryLabel."
+    },
+    "product": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The single summarized product, bound to /state/<id>/product."
     },
     "state": {
       "$ref": "#/$defs/ProductSummaryState"
@@ -20,17 +32,6 @@
       "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,