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

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

@@ -0,0 +1,320 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.thermidor.coveo.com/components/numeric-facet.schema.json",
+  "title": "NumericFacet",
+  "description": "A numeric range facet for a commerce search surface. Renders numeric range values and dispatches toggleSelect, clearAllActiveValues, applyCustomRange, showMoreValues, and showLessValues to refine results.",
+  "allOf": [
+    {
+      "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
+    }
+  ],
+  "properties": {
+    "component": {
+      "type": "string",
+      "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"
+    },
+    "actions": {
+      "type": "object",
+      "required": [
+        "toggleSelect",
+        "toggleSingleSelect",
+        "clearAllActiveValues",
+        "applyCustomRange",
+        "showMoreValues",
+        "showLessValues"
+      ],
+      "properties": {
+        "toggleSelect": {
+          "$ref": "#/$defs/NumericFacetToggleSelectAction"
+        },
+        "toggleSingleSelect": {
+          "$ref": "#/$defs/NumericFacetToggleSingleSelectAction"
+        },
+        "clearAllActiveValues": {
+          "$ref": "#/$defs/NumericFacetClearAllActiveValuesAction"
+        },
+        "applyCustomRange": {
+          "$ref": "#/$defs/NumericFacetApplyCustomRangeAction"
+        },
+        "showMoreValues": {
+          "$ref": "#/$defs/NumericFacetShowMoreValuesAction"
+        },
+        "showLessValues": {
+          "$ref": "#/$defs/NumericFacetShowLessValuesAction"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "NumericFacetState": {
+      "title": "NumericFacetState",
+      "description": "The current numeric facet state. Owned exclusively by the backend.",
+      "type": "object",
+      "required": [
+        "field",
+        "displayName",
+        "values",
+        "customRange",
+        "hasActiveValues",
+        "canShowMoreValues",
+        "canShowLessValues"
+      ],
+      "properties": {
+        "field": {
+          "type": "string",
+          "description": "The index field this facet queries."
+        },
+        "displayName": {
+          "type": "string",
+          "description": "Human-readable name for this facet."
+        },
+        "values": {
+          "type": "array",
+          "description": "The numeric range values available for this facet.",
+          "minItems": 0,
+          "maxItems": 500,
+          "items": {
+            "$ref": "#/$defs/NumericFacetValue"
+          }
+        },
+        "customRange": {
+          "description": "The currently applied custom range, or null when none is active. Mutually exclusive with selected values.",
+          "oneOf": [
+            {
+              "$ref": "#/$defs/NumericFacetCustomRange"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "hasActiveValues": {
+          "type": "boolean",
+          "description": "Whether at least one range value is not in the idle state."
+        },
+        "canShowMoreValues": {
+          "type": "boolean",
+          "description": "Whether more values can be shown."
+        },
+        "canShowLessValues": {
+          "type": "boolean",
+          "description": "Whether fewer values can be shown."
+        },
+        "domain": {
+          "$ref": "#/$defs/NumericFacetDomain",
+          "description": "The optional numeric domain (min/max) of the facet."
+        }
+      },
+      "additionalProperties": false
+    },
+    "NumericFacetValue": {
+      "title": "NumericFacetValue",
+      "description": "A single numeric range value within a numeric facet.",
+      "type": "object",
+      "required": ["start", "end", "numberOfResults", "state"],
+      "properties": {
+        "start": {
+          "type": "number",
+          "description": "The inclusive lower bound of the range."
+        },
+        "end": {
+          "type": "number",
+          "description": "The upper bound of the range."
+        },
+        "numberOfResults": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "The number of results matching this range."
+        },
+        "state": {
+          "$ref": "https://schema.thermidor.coveo.com/definitions/selectable-facet-value-state.schema.json",
+          "description": "The selection state of this facet value (idle or selected; exclusion is not supported)."
+        }
+      },
+      "additionalProperties": false
+    },
+    "NumericFacetCustomRange": {
+      "title": "NumericFacetCustomRange",
+      "description": "A custom numeric range applied by the user, with its result count.",
+      "type": "object",
+      "required": ["start", "end", "numberOfResults"],
+      "properties": {
+        "start": {
+          "type": "number",
+          "description": "The inclusive lower bound of the custom range."
+        },
+        "end": {
+          "type": "number",
+          "description": "The upper bound of the custom range."
+        },
+        "numberOfResults": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "The number of results matching this custom range."
+        }
+      },
+      "additionalProperties": false
+    },
+    "NumericFacetDomain": {
+      "title": "NumericFacetDomain",
+      "description": "The numeric domain bounds of a numeric facet.",
+      "type": "object",
+      "properties": {
+        "min": {
+          "type": "number",
+          "description": "The minimum value of the domain."
+        },
+        "max": {
+          "type": "number",
+          "description": "The maximum value of the domain."
+        }
+      },
+      "additionalProperties": false
+    },
+    "NumericFacetToggleSelectAction": {
+      "title": "numericFacetToggleSelect",
+      "description": "Toggles the selection of a numeric range value.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": ["start", "end"],
+          "properties": {
+            "start": {
+              "type": "number",
+              "description": "The inclusive lower bound of the range to toggle."
+            },
+            "end": {
+              "type": "number",
+              "description": "The upper bound of the range to toggle."
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+    "NumericFacetToggleSingleSelectAction": {
+      "title": "numericFacetToggleSingleSelect",
+      "description": "Toggles the selection of a range value, deselecting all other values (single-select behavior).",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": ["start", "end"],
+          "properties": {
+            "start": {
+              "type": "number",
+              "description": "The inclusive lower bound of the range to single-select."
+            },
+            "end": {
+              "type": "number",
+              "description": "The upper bound of the range to single-select."
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+    "NumericFacetClearAllActiveValuesAction": {
+      "title": "numericFacetClearAllActiveValues",
+      "description": "Resets all numeric range values to the idle state, clearing every selection.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ]
+    },
+    "NumericFacetApplyCustomRangeAction": {
+      "title": "numericFacetApplyCustomRange",
+      "description": "Applies a single custom numeric range, clearing any selected displayed ranges.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": ["start", "end"],
+          "properties": {
+            "start": {
+              "type": "number",
+              "description": "The inclusive lower bound of the custom range."
+            },
+            "end": {
+              "type": "number",
+              "description": "The upper bound of the custom range."
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+    "NumericFacetShowMoreValuesAction": {
+      "title": "numericFacetShowMoreValues",
+      "description": "Increases the number of numeric range values shown.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ]
+    },
+    "NumericFacetShowLessValuesAction": {
+      "title": "numericFacetShowLessValues",
+      "description": "Decreases the number of numeric range values shown.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,149 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.thermidor.coveo.com/components/pagination.schema.json",
+  "title": "Pagination",
+  "description": "Controls page navigation for a commerce search surface. Manages current page, page size, and total counts; dispatches selectPage to navigate.",
+  "allOf": [
+    {
+      "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
+    }
+  ],
+  "properties": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
+      "type": "string",
+      "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", "showMore"],
+      "properties": {
+        "selectPage": {
+          "$ref": "#/$defs/SelectPageAction"
+        },
+        "setPageSize": {
+          "$ref": "#/$defs/SetPageSizeAction"
+        },
+        "showMore": {
+          "$ref": "#/$defs/ShowMoreAction"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "PaginationState": {
+      "title": "PaginationState",
+      "description": "The current pagination state. Owned exclusively by the backend.",
+      "type": "object",
+      "required": ["page", "pageSize", "totalEntries", "totalPages"],
+      "properties": {
+        "page": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "The current zero-indexed page number."
+        },
+        "pageSize": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "The number of items per page."
+        },
+        "totalEntries": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "The total number of items across all pages."
+        },
+        "totalPages": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "The total number of pages."
+        }
+      },
+      "additionalProperties": false
+    },
+    "SelectPageAction": {
+      "title": "selectPage",
+      "description": "Navigates to a specific page.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": ["page"],
+          "properties": {
+            "page": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "The zero-indexed page number to navigate to."
+            }
+          },
+          "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
+        }
+      }
+    },
+    "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

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.thermidor.coveo.com/components/product-carousel.schema.json",
+  "title": "ProductCarousel",
+  "description": "Renders an ordered list of commerce products for a single category or intent bucket. Read-only from the frontend: the backend is the sole source of truth for which products are displayed and in what order.",
+  "allOf": [
+    {
+      "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
+    }
+  ],
+  "properties": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
+      "type": "string",
+      "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"
+    },
+    "actions": {
+      "type": "object",
+      "properties": {},
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "ProductCarouselState": {
+      "title": "ProductCarouselState",
+      "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"],
+      "properties": {
+        "heading": {
+          "type": "string",
+          "description": "Display heading for this product list (e.g. 'Life Jackets'). An empty string is a valid transient value while the list is still loading."
+        },
+        "products": {
+          "type": "array",
+          "description": "Ordered list of products to render.",
+          "items": {
+            "$ref": "https://schema.thermidor.coveo.com/definitions/product.schema.json"
+          }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}