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

package/schema/components/comparison-table.schema.json

@@ -9,9 +9,28 @@
     }
   ],
   "properties": {
-    "componentType": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
       "type": "string",
-      "const": "comparison-table"
+      "const": "ComparisonTable"
+    },
+    "heading": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The table heading, bound to /state/<id>/heading."
+    },
+    "summary": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The AI summary text, bound to /state/<id>/summary."
+    },
+    "products": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The compared products, bound to /state/<id>/products."
+    },
+    "attributes": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The ordered attribute descriptors, bound to /state/<id>/attributes."
     },
     "state": {
       "$ref": "#/$defs/ComparisonTableState"
@@ -20,17 +39,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/date-facet.schema.json

@@ -9,9 +9,40 @@
     }
   ],
   "properties": {
-    "componentType": {
+    "component": {
       "type": "string",
-      "const": "date-facet"
+      "const": "DateFacet"
+    },
+    "id": {
+      "type": "string"
+    },
+    "field": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The commerce index field the facet operates on, 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 date-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."
     },
     "state": {
       "$ref": "#/$defs/DateFacetState"
@@ -47,17 +78,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,

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

@@ -2,16 +2,25 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://schema.thermidor.coveo.com/components/facet-manager.schema.json",
   "title": "FacetManager",
-  "description": "Manages facet ordering and cross-facet concerns. Holds the backend-determined order of facet components as state. The position of each identifier (indexed from 0) determines the facet's rendering rank. Ready to gain cross-facet actions (e.g., clear all facets, reorder) as needs arise.",
+  "description": "Manages facet ordering and cross-facet concerns. Holds the backend-determined order of facet components as state; each identifier's position (from 0) is its rendering rank.",
+  "$comment": "Ready to gain cross-facet actions (e.g. clear all facets, reorder) as needs arise.",
   "allOf": [
     {
       "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
     }
   ],
   "properties": {
-    "componentType": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
       "type": "string",
-      "const": "facet-manager"
+      "const": "FacetManager"
+    },
+    "children": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/child-list.schema.json",
+      "description": "The backend-determined facet order: a ChildList of ComponentId references whose position (from 0) is each facet's rendering rank.",
+      "$comment": "Homogeneous ordered-list composition: child ids are static (binder passes through unresolved), mounted in order via children(id)."
     },
     "state": {
       "$ref": "#/$defs/FacetManagerState"
@@ -20,17 +29,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/layout-stack.schema.json

@@ -2,16 +2,30 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://schema.thermidor.coveo.com/components/layout-stack.schema.json",
   "title": "LayoutStack",
-  "description": "Generic layout container that stacks its children along a single axis. It carries no business data: its AG-UI state is empty. Layout is a presentation concern and travels as an A2-UI node prop ('direction': 'column' | 'row'), never as AG-UI state. Reused across surfaces (commerce search, knowledge search) to compose columns and rows from the A2-UI composition plane rather than hardcoding layout per parent renderer.",
+  "description": "Generic layout container that stacks its children along a single axis. Carries no business data; its state is empty and the stacking direction travels as a presentation prop.",
+  "$comment": "Reused across surfaces to compose rows/columns from the A2-UI composition plane rather than hardcoding layout per parent renderer.",
   "allOf": [
     {
       "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
     }
   ],
   "properties": {
-    "componentType": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
+      "type": "string",
+      "const": "LayoutStack"
+    },
+    "direction": {
       "type": "string",
-      "const": "layout-stack"
+      "enum": ["column", "row"],
+      "description": "The axis along which children are stacked. A plain presentation value at the node top level, never server state."
+    },
+    "children": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/child-list.schema.json",
+      "description": "The ordered children, a ChildList of ComponentId references mounted in order via children(id).",
+      "$comment": "Homogeneous ordered-list composition: the ordered list is the semantics; child ids are static, passed through unresolved."
     },
     "state": {
       "$ref": "#/$defs/LayoutStackState"
@@ -20,24 +34,13 @@
       "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": {
     "LayoutStackState": {
       "title": "LayoutStackState",
-      "description": "The layout-stack state. A layout container holds no business data, so its state is always the empty object. The stacking direction is presentation and travels as an A2-UI node prop, never as AG-UI state.",
+      "description": "Empty: a layout container holds no business data.",
       "type": "object",
       "required": [],
       "properties": {},

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

@@ -9,9 +9,17 @@
     }
   ],
   "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"
@@ -25,17 +33,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,
@@ -45,9 +42,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": {

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,

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
+        }
+      }
     }
   }
 }