@grafana/viz-contract 1.1.0

package/fixtures/type-mismatch/result.json

@@ -0,0 +1,9 @@
+{
+  "isError": true,
+  "content": [
+    {
+      "type": "text",
+      "text": "type-mismatch: sankey needs source, target and value fields. Charts that fit: timeseries, barchart, histogram, piechart, funnel, heatmap, state-timeline, status-history, streamgraph, bubble."
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@grafana/viz-contract",
+  "version": "1.1.0",
+  "description": "Contract between a Grafana query source, the host that shows the chart, and the Renderer",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/grafana/viz-contract.git"
+  },
+  "type": "module",
+  "files": [
+    "schemas/bundled/",
+    "registry/",
+    "fixtures/",
+    "renderer-api.d.ts",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "exports": {
+    "./renderer-api": {
+      "types": "./renderer-api.d.ts"
+    },
+    "./schemas/*": "./schemas/bundled/*",
+    "./registry/*": "./registry/*",
+    "./fixtures/*": "./fixtures/*",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/registry/chart-types.json

@@ -0,0 +1,170 @@
+{
+  "charts": [
+    {
+      "name": "timeseries",
+      "panel": "grafana-echartscartesian-panel",
+      "options": { "seriesType": "line" },
+      "fits": [{ "hasFieldType.time": true, "hasFieldType.number": true }],
+      "description": "Lines of values over time",
+      "dataShape": "a time field and number fields"
+    },
+    {
+      "name": "barchart",
+      "panel": "grafana-echartscartesian-panel",
+      "options": { "seriesType": "bar" },
+      "fits": [{ "hasFieldType.number": true }],
+      "description": "Bars of values by category or time",
+      "dataShape": "number fields, with a string or time field for the categories"
+    },
+    {
+      "name": "histogram",
+      "panel": "grafana-echartscartesian-panel",
+      "options": { "histogram": true },
+      "fits": [{ "hasFieldType.number": true }],
+      "description": "Bucket counts of the values",
+      "dataShape": "number fields"
+    },
+    {
+      "name": "candlestick",
+      "panel": "grafana-echartscartesian-panel",
+      "options": { "seriesType": "candlestick" },
+      "fits": [{ "hasFieldName.open": true, "hasFieldName.high": true, "hasFieldName.low": true, "hasFieldName.close": true }],
+      "description": "Open, high, low and close values for each time or category",
+      "dataShape": "number fields named open, high, low and close"
+    },
+    {
+      "name": "boxplot",
+      "panel": "grafana-echartscartesian-panel",
+      "options": { "seriesType": "boxplot" },
+      "fits": [{ "hasFieldName.min": true, "hasFieldName.q1": true, "hasFieldName.median": true, "hasFieldName.q3": true, "hasFieldName.max": true }],
+      "description": "Five-number summary for each category",
+      "dataShape": "number fields named min, q1, median, q3 and max"
+    },
+    {
+      "name": "piechart",
+      "panel": "grafana-echartsparttowhole-panel",
+      "options": { "seriesType": "pie" },
+      "fits": [{ "hasFieldType.number": true }],
+      "description": "Parts of a whole as slices",
+      "dataShape": "a number field, with a string field for the names of the parts"
+    },
+    {
+      "name": "funnel",
+      "panel": "grafana-echartsparttowhole-panel",
+      "options": { "seriesType": "funnel" },
+      "fits": [{ "hasFieldType.number": true }],
+      "description": "Values of the stages of a process, from largest to smallest",
+      "dataShape": "a number field, with a string field for the names of the stages"
+    },
+    {
+      "name": "heatmap",
+      "panel": "grafana-echartsheatmap-panel",
+      "options": {},
+      "fits": [{ "hasDataFrameType.heatmap-cells": true }, { "hasFieldType.time": true, "hasFieldType.number": true }],
+      "description": "Colored cells of values over time and buckets",
+      "dataShape": "heatmap cells, or a time field and number fields for the buckets"
+    },
+    {
+      "name": "geomap",
+      "panel": "grafana-echartsgeo-panel",
+      "options": {},
+      "fits": [
+        { "hasFieldType.geo": true },
+        { "hasFieldName.geohash": true },
+        { "hasFieldName.latitude": true, "hasFieldName.longitude": true },
+        { "hasFieldName.lat": true, "hasFieldName.lon": true },
+        { "hasFieldName.lat": true, "hasFieldName.lng": true }
+      ],
+      "description": "Points on a map",
+      "dataShape": "a geo field, a geohash field, or latitude and longitude fields"
+    },
+    {
+      "name": "state-timeline",
+      "panel": "grafana-echartsstatetimeline-panel",
+      "options": {},
+      "fits": [{ "hasFieldType.time": true, "fieldCount": { "min": 2 } }],
+      "description": "Changes of state over time, as bands",
+      "dataShape": "a time field and string, boolean or number fields"
+    },
+    {
+      "name": "status-history",
+      "panel": "grafana-echartsstatushistory-panel",
+      "options": {},
+      "fits": [{ "hasFieldType.time": true, "fieldCount": { "min": 2 } }],
+      "description": "Status at each time, as cells",
+      "dataShape": "a time field and string, boolean or number fields"
+    },
+    {
+      "name": "nodeGraph",
+      "panel": "grafana-relations-panel",
+      "options": { "seriesType": "graph" },
+      "fits": [{ "hasPreferredVisualisationType.nodeGraph": true }, { "hasFieldName.source": true, "hasFieldName.target": true }],
+      "description": "Nodes and the links between them",
+      "dataShape": "node graph frames, or source and target fields"
+    },
+    {
+      "name": "sankey",
+      "panel": "grafana-relations-panel",
+      "options": { "seriesType": "sankey" },
+      "fits": [{ "hasFieldName.source": true, "hasFieldName.target": true, "hasFieldType.number": true }],
+      "description": "Flows between nodes, with a width for each value",
+      "dataShape": "source, target and value fields"
+    },
+    {
+      "name": "chord",
+      "panel": "grafana-relations-panel",
+      "options": { "seriesType": "chord" },
+      "fits": [{ "hasFieldName.source": true, "hasFieldName.target": true, "hasFieldType.number": true }],
+      "description": "Flows between nodes on a circle",
+      "dataShape": "source, target and value fields"
+    },
+    {
+      "name": "treemap",
+      "panel": "grafana-echartshierarchy-panel",
+      "options": { "seriesType": "treemap" },
+      "fits": [{ "hasFieldType.string": true, "hasFieldType.number": true }],
+      "description": "Nested rectangles of a hierarchy, with an area for each value",
+      "dataShape": "string fields for the levels and a number field"
+    },
+    {
+      "name": "sunburst",
+      "panel": "grafana-echartshierarchy-panel",
+      "options": { "seriesType": "sunburst" },
+      "fits": [{ "hasFieldType.string": true, "hasFieldType.number": true }],
+      "description": "Rings of a hierarchy, with an angle for each value",
+      "dataShape": "string fields for the levels and a number field"
+    },
+    {
+      "name": "radar",
+      "panel": "grafana-echartsmultivariate-panel",
+      "options": { "seriesType": "radar" },
+      "fits": [{ "hasFieldType.time": false, "fieldCountByType.number": { "min": 3 } }],
+      "description": "Several values of each item on axes around a center",
+      "dataShape": "three or more number fields"
+    },
+    {
+      "name": "parallel",
+      "panel": "grafana-echartsmultivariate-panel",
+      "options": { "seriesType": "parallel" },
+      "fits": [{ "hasFieldType.time": false, "fieldCountByType.number": { "min": 2 } }],
+      "description": "Several values of each item as lines across parallel axes",
+      "dataShape": "two or more number fields"
+    },
+    {
+      "name": "streamgraph",
+      "panel": "grafana-echartsstream-panel",
+      "options": { "streamChartType": "river" },
+      "fits": [{ "hasFieldType.time": true, "hasFieldType.number": true }],
+      "description": "Stacked flows of values over time",
+      "dataShape": "a time field and number fields"
+    },
+    {
+      "name": "bubble",
+      "panel": "grafana-echartsstream-panel",
+      "options": { "streamChartType": "bubble" },
+      "fits": [{ "hasFieldType.time": true, "hasFieldType.number": true }],
+      "description": "Bubbles of values over time, with a size for each value",
+      "dataShape": "a time field and number fields"
+    }
+  ]
+}

package/registry/constants.json

@@ -0,0 +1,14 @@
+{
+  "maxResultBytes":       { "value": 1048576, "unit": "bytes", "meaning": "Largest structuredContent of the tool result", "changeable": true },
+  "refreshTimeoutMs":     { "value": 60000, "unit": "ms", "meaning": "Time before a refresh with no result fails" },
+  "defaultHeightPx":      { "value": 400, "unit": "px", "meaning": "Chart height when the element height is 0" },
+  "defaultFrom":          { "value": "now-1h", "unit": "time", "meaning": "from when the tool arguments have none" },
+  "defaultTo":            { "value": "now", "unit": "time", "meaning": "to when the tool arguments have none" },
+  "defaultMaxDataPoints": { "value": 1000, "unit": "points", "meaning": "maxDataPoints of a query that has none. intervalMs is the range divided by it" },
+  "maxSeries":            { "value": 50, "unit": "series", "meaning": "Most series that the Renderer draws", "changeable": true },
+  "maxBundleGzipBytes":   { "value": null, "unit": "bytes", "meaning": "Largest gzip size of the Renderer bundle. Not set until the host size research is done", "changeable": true },
+  "maxAppNotes":          { "value": 5, "unit": "notes", "meaning": "Most notes of the Source that render_grafana_app adds to its text line", "changeable": true },
+  "maxAppNoteChars":      { "value": 200, "unit": "characters", "meaning": "Longest note in the text line of render_grafana_app", "changeable": true },
+  "deprecationDays":      { "value": 30, "unit": "days", "meaning": "Shortest deprecation period of a change to a frozen interface", "changeable": true },
+  "specVersion":          { "value": 1, "unit": "version", "meaning": "The viz spec version that this contract gives" }
+}

package/registry/notices.json

@@ -0,0 +1,40 @@
+{
+  "notices": [
+    {
+      "code": "query-failed",
+      "raisedBy": "renderer",
+      "when": "An entry of data.results has an error, and another entry has no error",
+      "message": "Query <refId> failed: <error>"
+    },
+    {
+      "code": "unit-unknown",
+      "raisedBy": "renderer",
+      "when": "panel.fieldConfig.defaults.unit is not a unit ID of @grafana/data",
+      "message": "Unit <unit> is not a Grafana unit. The values show with no unit."
+    },
+    {
+      "code": "series-truncated",
+      "raisedBy": "renderer",
+      "when": "The frames have more series than maxSeries",
+      "message": "<omitted> series with the smallest peak values are not shown."
+    },
+    {
+      "code": "chart-changed",
+      "raisedBy": "app",
+      "when": "A refresh got the type-mismatch error, and the App drew the picked chart in its place",
+      "message": "The <old> chart does not fit the new data. The chart is now a <new>."
+    },
+    {
+      "code": "geo-map-tiles",
+      "raisedBy": "renderer",
+      "when": "A map layer of the geo panel needs map tiles from the network",
+      "message": "Map layer <name> (<type>) needs map tiles from the network. The vector basemap is drawn in its place."
+    },
+    {
+      "code": "geo-offline-file",
+      "raisedBy": "renderer",
+      "when": "A map layer of the geo panel needs a file that is not in the Renderer",
+      "message": "Map layer <name>: <url> is not available offline."
+    }
+  ]
+}

package/registry/panel-types.json

@@ -0,0 +1,14 @@
+{
+  "panels": [
+    { "id": "grafana-echartscartesian-panel", "family": "cartesian", "name": "XY chart" },
+    { "id": "grafana-echartsgeo-panel", "family": "geo", "name": "geo map" },
+    { "id": "grafana-echartsheatmap-panel", "family": "heatmap", "name": "heatmap" },
+    { "id": "grafana-echartshierarchy-panel", "family": "hierarchy", "name": "hierarchy chart" },
+    { "id": "grafana-echartsmultivariate-panel", "family": "multivariate", "name": "multivariate chart" },
+    { "id": "grafana-echartsparttowhole-panel", "family": "partToWhole", "name": "part-to-whole chart" },
+    { "id": "grafana-relations-panel", "family": "relations", "name": "relations chart" },
+    { "id": "grafana-echartsstatetimeline-panel", "family": "stateTimeline", "name": "state timeline" },
+    { "id": "grafana-echartsstatushistory-panel", "family": "statusHistory", "name": "status history" },
+    { "id": "grafana-echartsstream-panel", "family": "stream", "name": "stream chart" }
+  ]
+}

package/registry/pick.json

@@ -0,0 +1,46 @@
+{
+  "pickVersion": 1,
+  "rules": [
+    {
+      "id": "node-graph",
+      "reason": "A frame has the preferred visualization type nodeGraph.",
+      "when": { "hasPreferredVisualisationType.nodeGraph": true },
+      "chart": "nodeGraph"
+    },
+    {
+      "id": "heatmap-cells",
+      "reason": "A frame has the data frame type heatmap-cells.",
+      "when": { "hasDataFrameType.heatmap-cells": true },
+      "chart": "heatmap"
+    },
+    {
+      "id": "time-series",
+      "reason": "The frames have a time field with more than one instant and a number field.",
+      "when": { "hasFieldType.time": true, "hasFieldType.number": true, "isInstant": false },
+      "chart": "timeseries"
+    },
+    {
+      "id": "few-parts",
+      "reason": "The frames have one string field, one number field and 2 to 10 rows.",
+      "when": {
+        "hasFieldType.time": false,
+        "fieldCountByType.string": 1,
+        "fieldCountByType.number": 1,
+        "rowCountTotal": { "min": 2, "max": 10 }
+      },
+      "chart": "piechart"
+    },
+    {
+      "id": "categories",
+      "reason": "The frames have a string field and a number field, and no time field.",
+      "when": { "hasFieldType.time": false, "hasFieldType.string": true, "hasFieldType.number": true },
+      "chart": "barchart"
+    },
+    {
+      "id": "default",
+      "reason": "No other rule matches.",
+      "when": {},
+      "chart": "barchart"
+    }
+  ]
+}

package/registry/states.json

@@ -0,0 +1,85 @@
+{
+  "states": [
+    {
+      "state": "rendering",
+      "final": false,
+      "meaning": "The render is not complete. The Renderer shows nothing"
+    },
+    {
+      "state": "ready",
+      "final": true,
+      "meaning": "The Renderer shows the chart"
+    },
+    {
+      "state": "no-data",
+      "final": true,
+      "meaning": "The frames have no rows. The Renderer shows No data, as Grafana does"
+    },
+    {
+      "state": "error",
+      "final": true,
+      "meaning": "The Renderer shows an error message in place of the chart"
+    }
+  ],
+  "errors": [
+    {
+      "code": "invalid-spec",
+      "when": "The viz spec is not an object, or a required field is missing",
+      "message": "The viz spec is not correct: <field> is missing."
+    },
+    {
+      "code": "unsupported-spec-version",
+      "when": "specVersion is not a version that the Renderer supports",
+      "message": "This viz spec version (<n>) is not supported. Supported versions: <list>."
+    },
+    {
+      "code": "unsupported-panel-type",
+      "when": "panel.type is not a panel ID of panel-types.json",
+      "message": "Panel type <type> is not supported. Supported types: <list>."
+    },
+    {
+      "code": "all-queries-failed",
+      "when": "Each entry of data.results has an error",
+      "message": "Query <refId> failed: <error>"
+    },
+    {
+      "code": "panel-error",
+      "when": "The panel shows its own error view in place of the chart",
+      "message": "<panel message>"
+    },
+    {
+      "code": "render-error",
+      "when": "An error occurs in the Renderer after the checks of the viz spec",
+      "message": "This data cannot be shown as a <panelName>."
+    }
+  ],
+  "toolErrors": [
+    {
+      "code": "type-mismatch",
+      "when": "The frames have data, and they do not meet the fits condition of the type from the model",
+      "message": "<chart> needs <dataShape>. Charts that fit: <charts>."
+    },
+    {
+      "code": "too-large",
+      "when": "The structured content of the tool result is larger than maxResultBytes",
+      "message": "The result is larger than <maxResultBytes> bytes. Use a shorter range, a larger intervalMs or fewer series."
+    }
+  ],
+  "refresh": [
+    {
+      "code": "refresh-failed",
+      "when": "The App calls setRefreshed(false, error) with an error text, or onRefresh throws",
+      "message": "Refresh failed: <error>"
+    },
+    {
+      "code": "refresh-failed-no-detail",
+      "when": "The App calls setRefreshed(false) with no error text",
+      "message": "Refresh failed."
+    },
+    {
+      "code": "refresh-timeout",
+      "when": "refreshTimeoutMs passes with no result",
+      "message": "Refresh failed: no result in time."
+    }
+  ]
+}

package/renderer-api.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The Renderer API. The App imports the Renderer as an ES module. 3-renderer.md, 4-states-and-notices.md and
+ * 5-refresh.md give the rules.
+ *
+ * This file has types only. The package has no JavaScript. Import it with `import type`. The values that it
+ * declares, for example render, come from the Renderer.
+ *
+ * The Renderer takes React and the Grafana packages from the App. The peerDependencies of the Renderer give
+ * them.
+ */
+
+/** Semver of the Renderer. */
+export declare const version: string;
+
+/** The specVersion values that the Renderer supports. */
+export declare const specVersions: readonly number[];
+
+/**
+ * Draws a viz spec into el, and returns at once. A spec that is not correct gives the error state. It does not
+ * throw. render throws only if el is not an HTMLElement.
+ */
+export declare function render(el: HTMLElement, spec: unknown, options?: RenderOptions): RenderHandle;
+
+export interface RenderOptions {
+  /** Called when the Renderer shows a new final state or new notices. */
+  onState?: (state: RenderState) => void;
+  /**
+   * Called when the user clicks Refresh or picks a time range. The Renderer shows Refresh and the time picker
+   * only when the App gives this option.
+   */
+  onRefresh?: (request: RefreshRequest) => void;
+}
+
+export interface RenderHandle {
+  /** Draws a new viz spec in the same element. */
+  update(spec: unknown): void;
+  /** Gives the result of the last refresh. With ok false, error is the text that the Renderer shows. */
+  setRefreshed(ok: boolean, error?: string): void;
+  /** Removes the chart and its listeners. */
+  destroy(): void;
+}
+
+/** A final state. The value is the same as the data-viz-state attribute of el. */
+export interface RenderState {
+  state: 'ready' | 'no-data' | 'error';
+  /** Present only when state is error. */
+  error?: RenderError;
+  /** The notices that the chart shows, in the same order. Can be empty. */
+  notices: Notice[];
+}
+
+export interface RenderError {
+  /** A code of errors in registry/states.json. */
+  code: string;
+  /** The message, made from the pattern of the code. */
+  message: string;
+}
+
+export interface Notice {
+  /** A code of registry/notices.json. */
+  code: string;
+  /** The message, made from the pattern of the code. */
+  message: string;
+}
+
+/**
+ * The cause of a refresh. For timeRange, from and to are the range that the user picked. A relative range, for
+ * example now-6h to now, stays relative. An absolute range is in epoch milliseconds.
+ */
+export type RefreshRequest = { cause: 'refresh' } | { cause: 'timeRange'; from: string; to: string };

package/schemas/bundled/query-datasource-args.schema.json

@@ -0,0 +1,86 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "query_datasource arguments",
+  "description": "Query a Grafana data source through /api/ds/query and draw the result as a chart.",
+  "type": "object",
+  "required": [
+    "datasourceUid",
+    "queries"
+  ],
+  "properties": {
+    "datasourceUid": {
+      "type": "string",
+      "minLength": 1,
+      "description": "UID of the data source. All queries use this data source."
+    },
+    "queries": {
+      "type": "array",
+      "minItems": 1,
+      "description": "The queries of /api/ds/query: a unique refId and the fields of the data source, for example expr and legendFormat for Prometheus.",
+      "items": {
+        "type": "object",
+        "required": [
+          "refId"
+        ],
+        "properties": {
+          "refId": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "from": {
+      "type": [
+        "string",
+        "integer"
+      ],
+      "default": "now-1h",
+      "$comment": "Generated from registry/constants.json (defaultFrom). Do not edit.",
+      "description": "Start of the time range, in a format that /api/ds/query accepts, for example now-6h or epoch milliseconds (a string or an integer)."
+    },
+    "to": {
+      "type": [
+        "string",
+        "integer"
+      ],
+      "default": "now",
+      "$comment": "Generated from registry/constants.json (defaultTo). Do not edit.",
+      "description": "End of the time range, in a format that /api/ds/query accepts, for example now or epoch milliseconds."
+    },
+    "type": {
+      "type": "string",
+      "$comment": "Generated from registry/chart-types.json. Do not edit.",
+      "enum": [
+        "timeseries",
+        "barchart",
+        "histogram",
+        "candlestick",
+        "boxplot",
+        "piechart",
+        "funnel",
+        "heatmap",
+        "geomap",
+        "state-timeline",
+        "status-history",
+        "nodeGraph",
+        "sankey",
+        "chord",
+        "treemap",
+        "sunburst",
+        "radar",
+        "parallel",
+        "streamgraph",
+        "bubble"
+      ],
+      "description": "Optional chart to draw. With no type, the chart comes from the data. Each chart needs: timeseries (a time field and number fields), barchart (number fields, with a string or time field for the categories), histogram (number fields), candlestick (number fields named open, high, low and close), boxplot (number fields named min, q1, median, q3 and max), piechart (a number field, with a string field for the names of the parts), funnel (a number field, with a string field for the names of the stages), heatmap (heatmap cells, or a time field and number fields for the buckets), geomap (a geo field, a geohash field, or latitude and longitude fields), state-timeline (a time field and string, boolean or number fields), status-history (a time field and string, boolean or number fields), nodeGraph (node graph frames, or source and target fields), sankey (source, target and value fields), chord (source, target and value fields), treemap (string fields for the levels and a number field), sunburst (string fields for the levels and a number field), radar (three or more number fields), parallel (two or more number fields), streamgraph (a time field and number fields), bubble (a time field and number fields)."
+    },
+    "unit": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Optional Grafana unit ID for all values, for example bytes, percent or reqps."
+    }
+  },
+  "additionalProperties": false,
+  "$comment": "Generated from schemas/query-datasource-args.schema.json. Do not edit."
+}