@coveo/thermidor-schema 0.0.0 → 1.0.0-beta.10

package/schema/components/cart.schema.json

@@ -0,0 +1,147 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.thermidor.coveo.com/components/cart.schema.json",
+  "title": "Cart",
+  "description": "Represents a commerce cart or checkout surface. The backend owns cart state; semantic cart mutations and purchase completion are dispatched through this component.",
+  "allOf": [
+    {
+      "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
+    }
+  ],
+  "properties": {
+    "component": {
+      "type": "string",
+      "const": "Cart"
+    },
+    "id": {
+      "type": "string"
+    },
+    "state": {
+      "$ref": "#/$defs/CartState"
+    },
+    "actions": {
+      "type": "object",
+      "required": ["updateCart", "purchase"],
+      "properties": {
+        "updateCart": {
+          "$ref": "#/$defs/UpdateCartAction"
+        },
+        "purchase": {
+          "$ref": "#/$defs/PurchaseAction"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "CartState": {
+      "title": "CartState",
+      "description": "Cart state is backend-owned. This initial contract intentionally carries no presentation fields; it provides the canonical action anchor for cart mutations and checkout completion.",
+      "type": "object",
+      "properties": {},
+      "additionalProperties": false
+    },
+    "UpdateCartAction": {
+      "title": "updateCart",
+      "description": "Applies a semantic item update to the cart and records the corresponding commerce cart event.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": ["productId", "quantity", "operation"],
+          "properties": {
+            "productId": {
+              "type": "string",
+              "minLength": 1
+            },
+            "name": {
+              "type": "string"
+            },
+            "price": {
+              "type": ["number", "null"]
+            },
+            "quantity": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "operation": {
+              "title": "CartUpdateOperation",
+              "type": "string",
+              "enum": ["add", "remove", "setQuantity"]
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+    "PurchaseAction": {
+      "title": "purchase",
+      "description": "Records a completed commerce transaction.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": ["products", "transaction"],
+          "properties": {
+            "products": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/PurchaseProduct"
+              }
+            },
+            "transaction": {
+              "$ref": "#/$defs/Transaction"
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+    "PurchaseProduct": {
+      "title": "PurchaseProduct",
+      "type": "object",
+      "required": ["productId", "quantity"],
+      "properties": {
+        "productId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "name": {
+          "type": "string"
+        },
+        "price": {
+          "type": ["number", "null"]
+        },
+        "quantity": {
+          "type": "integer",
+          "minimum": 1
+        }
+      },
+      "additionalProperties": false
+    },
+    "Transaction": {
+      "title": "Transaction",
+      "type": "object",
+      "required": ["id", "revenue"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "revenue": {
+          "type": "number"
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

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

@@ -0,0 +1,303 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.thermidor.coveo.com/components/category-facet.schema.json",
+  "title": "CategoryFacet",
+  "description": "A hierarchical category facet for a commerce surface. Renders a flat representation of the category tree (ancestry, selected value, and available children) with facet search. Dispatches selectPath, clearSelectedPath, search, and show-more/less actions.",
+  "allOf": [
+    {
+      "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
+    }
+  ],
+  "properties": {
+    "component": {
+      "type": "string",
+      "const": "CategoryFacet"
+    },
+    "id": {
+      "type": "string"
+    },
+    "field": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The 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 category facet values, bound to /state/<id>/values."
+    },
+    "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."
+    },
+    "facetSearch": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The facet search state, bound to /state/<id>/facetSearch."
+    },
+    "state": {
+      "$ref": "#/$defs/CategoryFacetState"
+    },
+    "actions": {
+      "type": "object",
+      "required": [
+        "selectPath",
+        "clearSelectedPath",
+        "search",
+        "showMoreSearchResults",
+        "clearSearch",
+        "showMoreValues",
+        "showLessValues"
+      ],
+      "properties": {
+        "selectPath": {
+          "$ref": "#/$defs/CategoryFacetSelectPathAction"
+        },
+        "clearSelectedPath": {
+          "$ref": "#/$defs/CategoryFacetClearSelectedPathAction"
+        },
+        "search": {
+          "$ref": "#/$defs/CategoryFacetSearchAction"
+        },
+        "showMoreSearchResults": {
+          "$ref": "#/$defs/CategoryFacetShowMoreSearchResultsAction"
+        },
+        "clearSearch": {
+          "$ref": "#/$defs/CategoryFacetClearSearchAction"
+        },
+        "showMoreValues": {
+          "$ref": "#/$defs/CategoryFacetShowMoreValuesAction"
+        },
+        "showLessValues": {
+          "$ref": "#/$defs/CategoryFacetShowLessValuesAction"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "CategoryFacetState": {
+      "title": "CategoryFacetState",
+      "description": "The current category facet state. Owned exclusively by the backend. Presents a flat view of the category hierarchy: the ancestry path, the currently selected value, and the children available for further navigation.",
+      "type": "object",
+      "required": [
+        "field",
+        "displayName",
+        "values",
+        "canShowMoreValues",
+        "canShowLessValues",
+        "facetSearch"
+      ],
+      "properties": {
+        "field": {
+          "type": "string",
+          "description": "The index field this facet operates on."
+        },
+        "displayName": {
+          "type": "string",
+          "description": "The human-readable label for this facet."
+        },
+        "values": {
+          "$ref": "#/$defs/CategoryFacetValues",
+          "description": "The flat representation of the category hierarchy."
+        },
+        "canShowMoreValues": {
+          "type": "boolean",
+          "description": "Whether more child values can be shown at the current level."
+        },
+        "canShowLessValues": {
+          "type": "boolean",
+          "description": "Whether the number of shown child values can be reduced."
+        },
+        "facetSearch": {
+          "$ref": "#/$defs/CategoryFacetSearch",
+          "description": "The current category facet search state."
+        }
+      },
+      "additionalProperties": false
+    },
+    "CategoryFacetValues": {
+      "title": "CategoryFacetValues",
+      "description": "Flat representation of the category hierarchy. When no category is selected, ancestry and selected are null and children contains the top-level categories.",
+      "type": "object",
+      "required": ["ancestry", "selected", "children"],
+      "properties": {
+        "ancestry": {
+          "type": "array",
+          "description": "The ordered list of ancestor categories leading to the selected value, from the root down. Empty when no category is selected.",
+          "items": {
+            "$ref": "#/$defs/CategoryFacetValue"
+          }
+        },
+        "selected": {
+          "description": "The currently selected category value. Null when no category is selected.",
+          "oneOf": [
+            {
+              "$ref": "#/$defs/CategoryFacetValue"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "children": {
+          "type": "array",
+          "description": "The child categories available for navigation. When no category is selected, these are the top-level categories. When a category is selected, these are its direct children.",
+          "items": {
+            "$ref": "#/$defs/CategoryFacetValue"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "CategoryFacetSearch": {
+      "title": "CategoryFacetSearch",
+      "description": "The current category facet search state.",
+      "type": "object",
+      "required": ["query", "canShowMoreResults", "results"],
+      "properties": {
+        "query": {
+          "type": "string",
+          "maxLength": 256,
+          "description": "The current facet search query."
+        },
+        "canShowMoreResults": {
+          "type": "boolean",
+          "description": "Whether more facet search results can be shown for the current query."
+        },
+        "results": {
+          "type": "array",
+          "description": "The current facet search results.",
+          "items": {
+            "$ref": "#/$defs/CategoryFacetValue"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "CategoryFacetSelectPathAction": {
+      "title": "categoryFacetSelectPath",
+      "description": "Navigates to a category by selecting its path.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": ["path"],
+          "properties": {
+            "path": {
+              "type": "array",
+              "description": "The path of the category to select.",
+              "items": {
+                "type": "string"
+              }
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+    "CategoryFacetClearSelectedPathAction": {
+      "title": "categoryFacetClearSelectedPath",
+      "description": "Clears the current category selection, navigating back to the root.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ]
+    },
+    "CategoryFacetSearchAction": {
+      "title": "categoryFacetSearch",
+      "description": "Runs a category facet search for the given query.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": ["query"],
+          "properties": {
+            "query": {
+              "type": "string",
+              "maxLength": 256,
+              "description": "The facet search query string."
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+    "CategoryFacetShowMoreSearchResultsAction": {
+      "title": "categoryFacetShowMoreSearchResults",
+      "description": "Requests the next page of category facet search results.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ]
+    },
+    "CategoryFacetClearSearchAction": {
+      "title": "categoryFacetClearSearch",
+      "description": "Clears the category facet search query and results.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ]
+    },
+    "CategoryFacetShowMoreValuesAction": {
+      "title": "categoryFacetShowMoreValues",
+      "description": "Increases the number of child category values shown.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ]
+    },
+    "CategoryFacetShowLessValuesAction": {
+      "title": "categoryFacetShowLessValues",
+      "description": "Decreases the number of child category values shown.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ]
+    },
+    "CategoryFacetValue": {
+      "title": "CategoryFacetValue",
+      "description": "A single category value. Used throughout the category facet state (ancestry, selected value, children) and as facet search results.",
+      "type": "object",
+      "required": ["path", "value", "numberOfResults"],
+      "properties": {
+        "path": {
+          "type": "array",
+          "description": "The ordered path of category segments from the root to this value.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "value": {
+          "type": "string",
+          "description": "The display label of this category."
+        },
+        "numberOfResults": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "The number of results matching this category."
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schema/components/commerce-search.schema.json

@@ -0,0 +1,186 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.thermidor.coveo.com/components/commerce-search.schema.json",
+  "title": "CommerceSearch",
+  "description": "Surface-root component for a commerce search surface. Its component discriminant carries the surface intent; it owns the surface's top-level components via named child slots and dispatches search lifecycle actions (submitQuery, restoreState, overrideCorrection).",
+  "allOf": [
+    {
+      "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
+    }
+  ],
+  "properties": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
+      "type": "string",
+      "const": "CommerceSearch"
+    },
+    "sidebarChild": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/component-id.schema.json",
+      "description": "The sidebar named slot: a static ComponentId the renderer mounts by name via children(sidebarChild).",
+      "$comment": "Heterogeneous named-slot composition: CommerceSearch uses named ComponentId slots (sidebar, main) rather than a positional children[] array."
+    },
+    "mainChild": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/component-id.schema.json",
+      "description": "The main-area named slot: a static ComponentId the renderer mounts by name via children(mainChild)."
+    },
+    "state": {
+      "$ref": "#/$defs/CommerceSearchState"
+    },
+    "actions": {
+      "type": "object",
+      "required": ["submitQuery", "restoreState", "overrideCorrection"],
+      "properties": {
+        "submitQuery": {
+          "$ref": "#/$defs/SubmitQueryAction"
+        },
+        "restoreState": {
+          "$ref": "#/$defs/RestoreStateAction"
+        },
+        "overrideCorrection": {
+          "$ref": "#/$defs/OverrideCorrectionAction"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "CommerceSearchState": {
+      "title": "CommerceSearchState",
+      "description": "The commerce search surface state. Owned exclusively by the backend.",
+      "type": "object",
+      "additionalProperties": false
+    },
+    "SubmitQueryAction": {
+      "title": "submitQuery",
+      "description": "Submits a new search query.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": ["query"],
+          "properties": {
+            "query": {
+              "type": "string",
+              "description": "The query string to submit."
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+    "RestoreStateAction": {
+      "title": "restoreState",
+      "description": "Restores a commerce-search surface from externally persisted search state.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": ["query", "page", "pageSize"],
+          "properties": {
+            "query": {
+              "type": "string"
+            },
+            "page": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "pageSize": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "sortCriteria": {
+              "type": "string"
+            },
+            "facets": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/FacetRestore"
+              }
+            },
+            "pinnedProducts": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+    "OverrideCorrectionAction": {
+      "title": "overrideCorrection",
+      "description": "Re-runs a search with the shopper's original query instead of an automatic correction.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": ["originalQuery"],
+          "properties": {
+            "originalQuery": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+    "FacetRestore": {
+      "title": "FacetRestore",
+      "type": "object",
+      "required": ["facetId"],
+      "properties": {
+        "facetId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "values": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "numericRanges": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/NumericRangeRestore"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "NumericRangeRestore": {
+      "title": "NumericRangeRestore",
+      "type": "object",
+      "required": ["start", "end"],
+      "properties": {
+        "start": {
+          "type": "number"
+        },
+        "end": {
+          "type": "number"
+        },
+        "endInclusive": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}