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

package/schema/base/component.schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.thermidor.coveo.com/base/component.schema.json",
+  "title": "Component",
+  "description": "A Component is a discrete, renderable UI element. Components describe what can be rendered, not how it is rendered. Each component has a type, an observable state, and a set of available actions.",
+  "type": "object",
+  "required": ["componentId", "displayName", "componentType", "state", "actions"],
+  "properties": {
+    "componentId": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Stable kebab-case identifier for this component (e.g. 'product-carousel'). Must be unique within a Catalog."
+    },
+    "displayName": {
+      "type": "string",
+      "description": "Human-readable name for this component (e.g. 'Product Carousel')."
+    },
+    "description": {
+      "type": "string",
+      "description": "Human-readable description of this component's purpose and rendering intent."
+    },
+    "componentType": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$",
+      "maxLength": 128,
+      "description": "Stable kebab-case type identifier (e.g. 'cart'). Used as discriminant for contract resolution."
+    },
+    "state": {
+      "type": "object",
+      "description": "The observable state owned by the backend. An empty object {} is valid for components with no observable state."
+    },
+    "actions": {
+      "type": "object",
+      "description": "Map of available actions. Each value conforms to base/action.schema.json. An empty object {} is valid for read-only components.",
+      "additionalProperties": {
+        "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schema/components/bundle-display.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.thermidor.coveo.com/components/bundle-display.schema.json",
+  "title": "BundleDisplay",
+  "description": "Renders a tiered product bundle layout with budget, mid-range, and premium options. Each tier contains slots that reference product surfaces.",
+  "allOf": [
+    {
+      "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
+    }
+  ],
+  "properties": {
+    "componentType": {
+      "type": "string",
+      "const": "bundle-display"
+    },
+    "state": {
+      "$ref": "#/$defs/BundleDisplayState"
+    },
+    "actions": {
+      "type": "object",
+      "properties": {},
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "BundleDisplayState": {
+      "title": "BundleDisplayState",
+      "description": "The tiered product bundle layout. 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": [
+        "tiers"
+      ],
+      "properties": {
+        "tiers": {
+          "type": "array",
+          "description": "Ordered list of bundle tiers to render.",
+          "items": {
+            "$ref": "https://schema.thermidor.coveo.com/definitions/bundle-tier.schema.json"
+          }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schema/components/cart.schema.json

@@ -0,0 +1,108 @@
+{
+  "$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/components/category-facet.schema.json

@@ -0,0 +1,292 @@
+{
+  "$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": {
+    "componentType": {
+      "type": "string",
+      "const": "category-facet"
+    },
+    "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/comparison-table.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.thermidor.coveo.com/components/comparison-table.schema.json",
+  "title": "ComparisonTable",
+  "description": "Renders a tabular product comparison with attribute columns. Read-only: the product set and attributes are owned by the backend.",
+  "allOf": [
+    {
+      "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
+    }
+  ],
+  "properties": {
+    "componentType": {
+      "type": "string",
+      "const": "comparison-table"
+    },
+    "state": {
+      "$ref": "#/$defs/ComparisonTableState"
+    },
+    "actions": {
+      "type": "object",
+      "properties": {},
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "ComparisonTableState": {
+      "title": "ComparisonTableState",
+      "description": "The comparison data to render. Contains a list of products with their attribute values and the attribute descriptors defining the columns.",
+      "type": "object",
+      "required": [
+        "products",
+        "attributes"
+      ],
+      "properties": {
+        "products": {
+          "type": "array",
+          "description": "Products to compare, each with attribute values keyed by attribute key.",
+          "items": {
+            "$ref": "https://schema.thermidor.coveo.com/definitions/comparison-product.schema.json"
+          }
+        },
+        "attributes": {
+          "type": "array",
+          "description": "Attribute descriptors defining the comparison columns.",
+          "items": {
+            "$ref": "https://schema.thermidor.coveo.com/definitions/comparison-attribute.schema.json"
+          }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schema/components/component-contracts.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.thermidor.coveo.com/components/component-contracts.schema.json",
+  "title": "Component Contracts",
+  "description": "Discriminated index of component runtime contracts. componentType is the stable discriminant; componentId identifies a particular instance outside this static contract.",
+  "$defs": {
+    "ComponentContracts": {
+      "title": "ComponentContracts",
+      "oneOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/components/product-carousel.schema.json"
+        },
+        {
+          "$ref": "https://schema.thermidor.coveo.com/components/cart.schema.json"
+        },
+        {
+          "$ref": "https://schema.thermidor.coveo.com/components/next-actions-bar.schema.json"
+        },
+        {
+          "$ref": "https://schema.thermidor.coveo.com/components/bundle-display.schema.json"
+        },
+        {
+          "$ref": "https://schema.thermidor.coveo.com/components/comparison-table.schema.json"
+        },
+        {
+          "$ref": "https://schema.thermidor.coveo.com/components/product-list.schema.json"
+        },
+        {
+          "$ref": "https://schema.thermidor.coveo.com/components/pagination.schema.json"
+        },
+        {
+          "$ref": "https://schema.thermidor.coveo.com/components/sort.schema.json"
+        },
+        {
+          "$ref": "https://schema.thermidor.coveo.com/components/search-box.schema.json"
+        },
+        {
+          "$ref": "https://schema.thermidor.coveo.com/components/regular-facet.schema.json"
+        },
+        {
+          "$ref": "https://schema.thermidor.coveo.com/components/numeric-facet.schema.json"
+        },
+        {
+          "$ref": "https://schema.thermidor.coveo.com/components/date-facet.schema.json"
+        },
+        {
+          "$ref": "https://schema.thermidor.coveo.com/components/category-facet.schema.json"
+        },
+        {
+          "$ref": "https://schema.thermidor.coveo.com/components/facet-manager.schema.json"
+        }
+      ]
+    }
+  }
+}