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

package/schema/components/comparison-table.schema.json

@@ -0,0 +1,78 @@
+{
+  "$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. A leaf component that owns its framing (heading and AI summary), the compared products, and the ordered attribute descriptors defining the comparison rows. Read-only: the product set, attributes, and framing are owned by the backend.",
+  "allOf": [
+    {
+      "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
+    }
+  ],
+  "properties": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
+      "type": "string",
+      "const": "ComparisonTable"
+    },
+    "heading": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The table heading, bound to /state/<id>/heading."
+    },
+    "summary": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The AI summary text, bound to /state/<id>/summary."
+    },
+    "products": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The compared products, bound to /state/<id>/products."
+    },
+    "attributes": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The ordered attribute descriptors, bound to /state/<id>/attributes."
+    },
+    "state": {
+      "$ref": "#/$defs/ComparisonTableState"
+    },
+    "actions": {
+      "type": "object",
+      "properties": {},
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "ComparisonTableState": {
+      "title": "ComparisonTableState",
+      "description": "The comparison content owned by the backend: the table heading, the AI summary text, the compared products, and the ordered attribute descriptors defining the comparison rows.",
+      "type": "object",
+      "required": ["products", "attributes", "heading", "summary"],
+      "properties": {
+        "heading": {
+          "type": "string",
+          "description": "Title displayed above the comparison table."
+        },
+        "summary": {
+          "type": "string",
+          "description": "AI-generated summary text displayed below the comparison table."
+        },
+        "products": {
+          "type": "array",
+          "description": "The compared products shown as columns of the comparison table.",
+          "items": {
+            "$ref": "https://schema.thermidor.coveo.com/definitions/comparison-product.schema.json"
+          }
+        },
+        "attributes": {
+          "type": "array",
+          "description": "Attribute descriptors defining the comparison rows.",
+          "items": {
+            "$ref": "https://schema.thermidor.coveo.com/definitions/comparison-attribute.schema.json"
+          }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

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

@@ -0,0 +1,294 @@
+{
+  "$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": {
+    "component": {
+      "type": "string",
+      "const": "DateFacet"
+    },
+    "id": {
+      "type": "string"
+    },
+    "field": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The commerce 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 date-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."
+    },
+    "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,45 @@
+{
+  "$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; 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": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
+      "type": "string",
+      "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"
+    },
+    "actions": {
+      "type": "object",
+      "properties": {},
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "FacetManagerState": {
+      "title": "FacetManagerState",
+      "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": [],
+      "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

@@ -0,0 +1,85 @@
+{
+  "$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": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
+      "type": "string",
+      "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"],
+      "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": ["suggestedActions"],
+      "properties": {
+        "suggestedActions": {
+          "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
+        }
+      }
+    }
+  }
+}