feat(api): support number-tile color in the external dashboards API

.changeset/number-tile-color-external-api.md

@@ -0,0 +1,5 @@
+---
+"@hyperdx/api": minor
+---
+
+Support number-tile color authoring through the external dashboards API. The v2 REST API and OpenAPI spec now accept `color` (a palette token) and `colorRules` (ordered conditional color rules, last match wins) on builder number tiles, and `color` on raw SQL number tiles, matching what the in-product number-tile editor persists. Color rules accept the numeric and equality operators the editor offers (`gt`, `gte`, `lt`, `lte`, `between`, `eq`, `neq`). Existing dashboards keep working: tiles saved before the palette was renamed to hue names are normalized to the current token names on read.

packages/api/openapi.json

@@ -779,6 +779,174 @@
           }
         }
       },
+      "ChartPaletteToken": {
+        "type": "string",
+        "enum": [
+          "chart-blue",
+          "chart-orange",
+          "chart-red",
+          "chart-cyan",
+          "chart-green",
+          "chart-pink",
+          "chart-purple",
+          "chart-light-blue",
+          "chart-brown",
+          "chart-gray",
+          "chart-success",
+          "chart-warning",
+          "chart-error"
+        ],
+        "description": "Palette token used to color a number tile. Tokens reflow across light and dark themes, so raw hex values are not accepted.\n",
+        "example": "chart-red"
+      },
+      "NumericColorCondition": {
+        "type": "object",
+        "required": [
+          "operator",
+          "value",
+          "color"
+        ],
+        "description": "Color rule comparing the displayed value against a single numeric bound.",
+        "properties": {
+          "operator": {
+            "type": "string",
+            "enum": [
+              "gt",
+              "gte",
+              "lt",
+              "lte"
+            ],
+            "description": "Numeric comparison operator.",
+            "example": "gt"
+          },
+          "value": {
+            "type": "number",
+            "description": "Numeric bound the displayed value is compared against. Only finite numbers are accepted (Infinity and NaN are rejected).\n",
+            "example": 100
+          },
+          "color": {
+            "$ref": "#/components/schemas/ChartPaletteToken",
+            "description": "Color applied when the rule matches."
+          },
+          "label": {
+            "type": "string",
+            "maxLength": 40,
+            "description": "Optional label describing the rule.",
+            "example": "High"
+          }
+        }
+      },
+      "BetweenColorCondition": {
+        "type": "object",
+        "required": [
+          "operator",
+          "value",
+          "color"
+        ],
+        "description": "Color rule matching when the displayed value falls within an inclusive range.",
+        "properties": {
+          "operator": {
+            "type": "string",
+            "enum": [
+              "between"
+            ],
+            "description": "Range comparison operator.",
+            "example": "between"
+          },
+          "value": {
+            "type": "array",
+            "minItems": 2,
+            "maxItems": 2,
+            "items": {
+              "type": "number"
+            },
+            "description": "Inclusive [min, max] range. Both bounds must be finite numbers.\n",
+            "example": [
+              100,
+              500
+            ]
+          },
+          "color": {
+            "$ref": "#/components/schemas/ChartPaletteToken",
+            "description": "Color applied when the rule matches."
+          },
+          "label": {
+            "type": "string",
+            "maxLength": 40,
+            "description": "Optional label describing the rule.",
+            "example": "Warning"
+          }
+        }
+      },
+      "EqualityColorCondition": {
+        "type": "object",
+        "required": [
+          "operator",
+          "value",
+          "color"
+        ],
+        "description": "Color rule matching when the displayed value equals (eq) or does not equal (neq) a number or string.",
+        "properties": {
+          "operator": {
+            "type": "string",
+            "enum": [
+              "eq",
+              "neq"
+            ],
+            "description": "Equality comparison operator.",
+            "example": "eq"
+          },
+          "value": {
+            "oneOf": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "string",
+                "maxLength": 200
+              }
+            ],
+            "description": "A finite number, or a string up to 200 characters, to compare for equality.\n",
+            "example": "OK"
+          },
+          "color": {
+            "$ref": "#/components/schemas/ChartPaletteToken",
+            "description": "Color applied when the rule matches."
+          },
+          "label": {
+            "type": "string",
+            "maxLength": 40,
+            "description": "Optional label describing the rule.",
+            "example": "Healthy"
+          }
+        }
+      },
+      "NumberTileColorCondition": {
+        "description": "A single conditional color rule for a number tile. Rules are evaluated in order and the last matching rule wins. When no rule matches, the static color applies, then the default text color. The number-tile editor surfaces numeric and equality operators only.\n",
+        "oneOf": [
+          {
+            "$ref": "#/components/schemas/NumericColorCondition"
+          },
+          {
+            "$ref": "#/components/schemas/BetweenColorCondition"
+          },
+          {
+            "$ref": "#/components/schemas/EqualityColorCondition"
+          }
+        ],
+        "discriminator": {
+          "propertyName": "operator",
+          "mapping": {
+            "gt": "#/components/schemas/NumericColorCondition",
+            "gte": "#/components/schemas/NumericColorCondition",
+            "lt": "#/components/schemas/NumericColorCondition",
+            "lte": "#/components/schemas/NumericColorCondition",
+            "between": "#/components/schemas/BetweenColorCondition",
+            "eq": "#/components/schemas/EqualityColorCondition",
+            "neq": "#/components/schemas/EqualityColorCondition"
+          }
+        }
+      },
       "TimeChartSeries": {
         "type": "object",
         "required": [
@@ -1417,6 +1585,18 @@
           "numberFormat": {
             "$ref": "#/components/schemas/NumberFormat",
             "description": "Number formatting options for displayed values."
+          },
+          "color": {
+            "$ref": "#/components/schemas/ChartPaletteToken",
+            "description": "Optional static color applied to the displayed number."
+          },
+          "colorRules": {
+            "type": "array",
+            "maxItems": 10,
+            "description": "Ordered conditional color rules evaluated against the displayed value (last match wins). Falls back to color, then the default text color when no rule matches.\n",
+            "items": {
+              "$ref": "#/components/schemas/NumberTileColorCondition"
+            }
           }
         }
       },
@@ -1772,6 +1952,10 @@
                 ],
                 "description": "Display as a single big-number chart.",
                 "example": "number"
+              },
+              "color": {
+                "$ref": "#/components/schemas/ChartPaletteToken",
+                "description": "Optional static color applied to the displayed number. Raw SQL number tiles do not support conditional colorRules.\n"
               }
             }
           }