@coveo/thermidor-schema 1.0.0-beta.1 → 1.0.0-beta.13

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"
@@ -26,22 +35,11 @@
   "$defs": {
     "FacetManagerState": {
       "title": "FacetManagerState",
-      "description": "The facet manager state. Holds the ordered list of facet component identifiers. Owned exclusively by the backend.",
+      "description": "The facet manager state. Facet ordering is expressed via the facet-manager A2-UI component node's 'children'; this state carries no facet-ordering data.",
       "type": "object",
-      "required": [
-        "facetIds"
-      ],
-      "properties": {
-        "facetIds": {
-          "type": "array",
-          "description": "Ordered facet component identifiers. Position (indexed from 0) determines the facet's rendering rank. Each identifier is expected to match the 'componentId' of a facet component registered in the catalog; referential integrity is enforced outside JSON Schema.",
-          "items": {
-            "type": "string",
-            "pattern": "^[a-z][a-z0-9-]*$"
-          }
-        }
-      },
+      "required": [],
+      "properties": {},
       "additionalProperties": false
     }
   }
-}
+}

package/schema/components/layout-stack.schema.json

@@ -0,0 +1,50 @@
+{
+  "$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. 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": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
+      "type": "string",
+      "const": "LayoutStack"
+    },
+    "direction": {
+      "type": "string",
+      "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"
+    },
+    "actions": {
+      "type": "object",
+      "properties": {},
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "LayoutStackState": {
+      "title": "LayoutStackState",
+      "description": "Empty: a layout container holds no business data.",
+      "type": "object",
+      "required": [],
+      "properties": {},
+      "additionalProperties": false
+    }
+  }
+}

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

@@ -9,18 +9,24 @@
     }
   ],
   "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"],
       "properties": {
         "selectAction": {
           "$ref": "#/$defs/SelectActionAction"
@@ -36,11 +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": {
@@ -61,10 +65,7 @@
       "properties": {
         "payload": {
           "type": "object",
-          "required": [
-            "text",
-            "type"
-          ],
+          "required": ["text", "type"],
           "properties": {
             "text": {
               "type": "string",
@@ -72,10 +73,7 @@
             },
             "type": {
               "type": "string",
-              "enum": [
-                "followup",
-                "search"
-              ],
+              "enum": ["followup", "search"],
               "description": "The kind of action selected: \"followup\" or \"search\"."
             }
           },
@@ -84,4 +82,4 @@
       }
     }
   }
-}
+}

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"
@@ -116,12 +151,7 @@
       "title": "NumericFacetValue",
       "description": "A single numeric range value within a numeric facet.",
       "type": "object",
-      "required": [
-        "start",
-        "end",
-        "numberOfResults",
-        "state"
-      ],
+      "required": ["start", "end", "numberOfResults", "state"],
       "properties": {
         "start": {
           "type": "number",
@@ -147,11 +177,7 @@
       "title": "NumericFacetCustomRange",
       "description": "A custom numeric range applied by the user, with its result count.",
       "type": "object",
-      "required": [
-        "start",
-        "end",
-        "numberOfResults"
-      ],
+      "required": ["start", "end", "numberOfResults"],
       "properties": {
         "start": {
           "type": "number",
@@ -196,10 +222,7 @@
       "properties": {
         "payload": {
           "type": "object",
-          "required": [
-            "start",
-            "end"
-          ],
+          "required": ["start", "end"],
           "properties": {
             "start": {
               "type": "number",
@@ -225,10 +248,7 @@
       "properties": {
         "payload": {
           "type": "object",
-          "required": [
-            "start",
-            "end"
-          ],
+          "required": ["start", "end"],
           "properties": {
             "start": {
               "type": "number",
@@ -263,10 +283,7 @@
       "properties": {
         "payload": {
           "type": "object",
-          "required": [
-            "start",
-            "end"
-          ],
+          "required": ["start", "end"],
           "properties": {
             "start": {
               "type": "number",
@@ -300,4 +317,4 @@
       ]
     }
   }
-}
+}

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

@@ -0,0 +1,79 @@
+{
+  "$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. 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": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
+      "type": "string",
+      "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"
+    },
+    "actions": {
+      "type": "object",
+      "required": ["setPageSize"],
+      "properties": {
+        "setPageSize": {
+          "$ref": "#/$defs/SetPageSizeAction"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "PageSizeState": {
+      "title": "PageSizeState",
+      "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": {
+        "pageSize": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "The number of items displayed per page."
+        }
+      },
+      "additionalProperties": false
+    },
+    "SetPageSizeAction": {
+      "title": "setPageSize",
+      "description": "Changes the number of items displayed per page.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": ["pageSize"],
+          "properties": {
+            "pageSize": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "The number of items to display per page."
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    }
+  }
+}

package/schema/components/pagination.schema.json

@@ -9,25 +9,44 @@
     }
   ],
   "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
@@ -39,12 +58,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 +94,7 @@
       "properties": {
         "payload": {
           "type": "object",
-          "required": [
-            "page"
-          ],
+          "required": ["page"],
           "properties": {
             "page": {
               "type": "integer",
@@ -105,9 +117,7 @@
       "properties": {
         "payload": {
           "type": "object",
-          "required": [
-            "pageSize"
-          ],
+          "required": ["pageSize"],
           "properties": {
             "pageSize": {
               "type": "integer",
@@ -118,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"
@@ -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

@@ -9,16 +9,31 @@
     }
   ],
   "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": {},
+      "required": ["selectProducts", "productClick"],
+      "properties": {
+        "selectProducts": {
+          "$ref": "#/$defs/SelectProductsAction"
+        },
+        "productClick": {
+          "$ref": "#/$defs/ProductClickAction"
+        }
+      },
       "additionalProperties": false
     }
   },
@@ -28,9 +43,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",
@@ -41,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
+        }
+      }
     }
   }
-}
+}