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

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

@@ -0,0 +1,281 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.thermidor.coveo.com/components/date-facet.schema.json",
+  "title": "DateFacet",
+  "description": "Renders a range-based date commerce facet. Presents date range values with their result counts and selection state, and dispatches actions to select, clear active values, apply a custom date range, and show more or fewer values.",
+  "allOf": [
+    {
+      "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
+    }
+  ],
+  "properties": {
+    "componentType": {
+      "type": "string",
+      "const": "date-facet"
+    },
+    "state": {
+      "$ref": "#/$defs/DateFacetState"
+    },
+    "actions": {
+      "type": "object",
+      "required": [
+        "toggleSelect",
+        "toggleSingleSelect",
+        "clearAllActiveValues",
+        "applyCustomRange",
+        "showMoreValues",
+        "showLessValues"
+      ],
+      "properties": {
+        "toggleSelect": {
+          "$ref": "#/$defs/DateFacetToggleSelectAction"
+        },
+        "toggleSingleSelect": {
+          "$ref": "#/$defs/DateFacetToggleSingleSelectAction"
+        },
+        "clearAllActiveValues": {
+          "$ref": "#/$defs/DateFacetClearAllActiveValuesAction"
+        },
+        "applyCustomRange": {
+          "$ref": "#/$defs/DateFacetApplyCustomRangeAction"
+        },
+        "showMoreValues": {
+          "$ref": "#/$defs/DateFacetShowMoreValuesAction"
+        },
+        "showLessValues": {
+          "$ref": "#/$defs/DateFacetShowLessValuesAction"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "DateFacetState": {
+      "title": "DateFacetState",
+      "description": "The observable state of a date facet. Owned exclusively by the backend.",
+      "type": "object",
+      "required": [
+        "field",
+        "displayName",
+        "values",
+        "customRange",
+        "hasActiveValues",
+        "canShowMoreValues",
+        "canShowLessValues"
+      ],
+      "properties": {
+        "field": {
+          "type": "string",
+          "description": "The commerce index field the facet operates on."
+        },
+        "displayName": {
+          "type": "string",
+          "description": "Human-readable label for the facet."
+        },
+        "values": {
+          "type": "array",
+          "description": "The date range values currently exposed by the facet.",
+          "items": {
+            "$ref": "#/$defs/DateFacetValue"
+          }
+        },
+        "customRange": {
+          "description": "The currently applied custom range, or null when none is active. Mutually exclusive with selected values.",
+          "oneOf": [
+            {
+              "$ref": "#/$defs/DateFacetCustomRange"
+            },
+            {
+              "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 than currently shown are available."
+        },
+        "canShowLessValues": {
+          "type": "boolean",
+          "description": "Whether the number of shown values can be reduced."
+        }
+      },
+      "additionalProperties": false
+    },
+    "DateFacetValue": {
+      "title": "DateFacetValue",
+      "description": "A single selectable date range within a date facet.",
+      "type": "object",
+      "required": [
+        "start",
+        "end",
+        "numberOfResults",
+        "state"
+      ],
+      "properties": {
+        "start": {
+          "type": "string",
+          "description": "The inclusive start of the date range."
+        },
+        "end": {
+          "type": "string",
+          "description": "The end of the date 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
+    },
+    "DateFacetCustomRange": {
+      "title": "DateFacetCustomRange",
+      "description": "A custom date range applied by the user, with its result count.",
+      "type": "object",
+      "required": [
+        "start",
+        "end",
+        "numberOfResults"
+      ],
+      "properties": {
+        "start": {
+          "type": "string",
+          "description": "The inclusive start of the custom date range."
+        },
+        "end": {
+          "type": "string",
+          "description": "The end of the custom date range."
+        },
+        "numberOfResults": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "The number of results matching this custom range."
+        }
+      },
+      "additionalProperties": false
+    },
+    "DateFacetToggleSelectAction": {
+      "title": "dateFacetToggleSelect",
+      "description": "Toggles the selection of a date facet value.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": [
+            "start",
+            "end"
+          ],
+          "properties": {
+            "start": {
+              "type": "string",
+              "description": "The inclusive start of the date range to toggle."
+            },
+            "end": {
+              "type": "string",
+              "description": "The end of the date range to toggle."
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+    "DateFacetToggleSingleSelectAction": {
+      "title": "dateFacetToggleSingleSelect",
+      "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": "string",
+              "description": "The inclusive lower bound of the range to single-select."
+            },
+            "end": {
+              "type": "string",
+              "description": "The upper bound of the range to single-select."
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+    "DateFacetClearAllActiveValuesAction": {
+      "title": "dateFacetClearAllActiveValues",
+      "description": "Resets all date range values to the idle state, clearing every selection.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ]
+    },
+    "DateFacetApplyCustomRangeAction": {
+      "title": "dateFacetApplyCustomRange",
+      "description": "Applies a single custom date 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": "string",
+              "description": "The inclusive start of the custom date range."
+            },
+            "end": {
+              "type": "string",
+              "description": "The end of the custom date range."
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+    "DateFacetShowMoreValuesAction": {
+      "title": "dateFacetShowMoreValues",
+      "description": "Increases the number of date range values shown.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ]
+    },
+    "DateFacetShowLessValuesAction": {
+      "title": "dateFacetShowLessValues",
+      "description": "Decreases the number of date range values shown.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,47 @@
+{
+  "$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.",
+  "allOf": [
+    {
+      "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
+    }
+  ],
+  "properties": {
+    "componentType": {
+      "type": "string",
+      "const": "facet-manager"
+    },
+    "state": {
+      "$ref": "#/$defs/FacetManagerState"
+    },
+    "actions": {
+      "type": "object",
+      "properties": {},
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "FacetManagerState": {
+      "title": "FacetManagerState",
+      "description": "The facet manager state. Holds the ordered list of facet component identifiers. Owned exclusively by the backend.",
+      "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-]*$"
+          }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

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

@@ -0,0 +1,87 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.thermidor.coveo.com/components/next-actions-bar.schema.json",
+  "title": "NextActionsBar",
+  "description": "Renders a set of suggested next actions the user can pick from. The selectAction action is dispatched when the user clicks an action button.",
+  "allOf": [
+    {
+      "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
+    }
+  ],
+  "properties": {
+    "componentType": {
+      "type": "string",
+      "const": "next-actions-bar"
+    },
+    "state": {
+      "$ref": "#/$defs/NextActionsState"
+    },
+    "actions": {
+      "type": "object",
+      "required": [
+        "selectAction"
+      ],
+      "properties": {
+        "selectAction": {
+          "$ref": "#/$defs/SelectActionAction"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "NextActionsState": {
+      "title": "NextActionsState",
+      "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"
+      ],
+      "properties": {
+        "actions": {
+          "type": "array",
+          "description": "Suggested actions the assistant offers the user.",
+          "items": {
+            "$ref": "https://schema.thermidor.coveo.com/definitions/action-item.schema.json"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "SelectActionAction": {
+      "title": "selectAction",
+      "description": "Signals that the user selected one of the suggested actions.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": [
+            "text",
+            "type"
+          ],
+          "properties": {
+            "text": {
+              "type": "string",
+              "description": "The display text of the action the user selected."
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "followup",
+                "search"
+              ],
+              "description": "The kind of action selected: \"followup\" or \"search\"."
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    }
+  }
+}