@nebula.js/sn-gauge 0.8.9 → 0.8.10

package/README.md

@@ -1,19 +1,185 @@
 # sn-gauge
 
-## !Experimental
+## A gauge for nebula.js
 
-A nebula.js supernova picasso gauge chart
+The gauge is often used to present KPIs, that is a single measure value, in the form of
+a radial gauge or a bar gauge.
 
-# Rendering tests
+![Gauge example](./assets/sn-gauge.png)
 
-Rendering tests are running playwright. Execute rendering tests with `pnpm test:e2e --headed`.
+## Requirements
 
-Rendering test compares a baseline snapshot with a current version of the same object. The output is then stored under `baselines`. It is important to take the baseline from the build in your PR and not your local baselines which is stored under `baselines-local`. The report with baselines can be found under summary under a link called test report.
+Requires `@nebula.js/stardust` version `1.2.0` or later.
 
-You can use the action called update snapshot to trigger a commit into your branch that automatically updates the snapshots.
+## Installing
 
-1. Go to actions tab.
-2. Click on Build, validate, (release) workflow.
-3. Open the Run workflow dropdown menu to the right.
-4. Choose your branch and tick the update_snapshot.
-5. Click Run workflow - now a commit will be done to your branch with updated snapshots.
+If you use npm: `npm install @nebula.js/sn-gauge`.
+You can also load through the script tag directly from
+[https://unpkg.com](https://unpkg.com/@nebula.js/sn-gauge).
+
+## Usage
+
+```js
+const nebula = embed(app, {
+  context: { theme: "light" },
+  types: [
+    {
+      name: "gauge",
+      load: () => Promise.resolve(gauge),
+    },
+  ],
+});
+
+nebula.render({
+  type: "gauge",
+  element: document.querySelector(".object"),
+  fields: ["=[A Sales $  with measure color]"],
+  options: { direction: "ltr", freeResize: true },
+  properties: {
+    measureAxis: {
+      min: 0,
+      max: 150000000,
+    },
+    useSegments: true,
+    color: { useBaseColors: "off" },
+    segmentInfo: {
+      limits: [
+        {
+          value: { qValueExpression: { qExpr: "Sum ([Sales Amount])*0.8" } },
+          gradient: false,
+        },
+        {
+          value: { qValueExpression: { qExpr: "Sum ([Sales Amount])*1.2" } },
+          gradient: false,
+        },
+      ],
+      paletteColors: [{ color: "#EE4266" }, { color: "#FFD23F" }, { color: "#337357" }],
+    },
+  },
+});
+```
+
+## Options
+
+- direction - ltr/rtl
+- freeResize - in conjunction with snapshotData on layout,
+  lets the chart ignore size set on snapshotData
+
+## More examples
+
+### Radial gauge with label styles, right-to-left direction, and narrow axis spacing
+
+You can decorate the labels of the radial gauge in
+the previous example with more styles (font family and color),
+by adding styling `"components"` into the `"properties"` of the gauge.
+
+Also, for the sake of demonstration
+the direction of the chart is changed from `"ltr"` to `"rtl"`,
+and the axis spacing is made narrow (that is more ticks along the curved axis).
+
+![gauge style](assets/sn-gauge-label-styles-and-rtl.png)
+
+```js
+nebula.render({
+  type: "gauge",
+  element: document.querySelector(".object"),
+  fields: ["=[A Sales $  with measure color]"],
+  options: { direction: "rtl" },
+  properties: {
+    measureAxis: {
+      min: 0,
+      max: 150000000,
+      spacing: 0.5,
+    },
+    useSegments: true,
+    color: { useBaseColors: "off" },
+    segmentInfo: {
+      limits: [
+        {
+          value: { qValueExpression: { qExpr: "Sum ([Sales Amount])*0.8" } },
+          gradient: false,
+        },
+        {
+          value: { qValueExpression: { qExpr: "Sum ([Sales Amount])*1.2" } },
+          gradient: false,
+        },
+      ],
+      paletteColors: [{ color: "#EE4266" }, { color: "#FFD23F" }, { color: "#337357" }],
+    },
+    components: [
+      {
+        key: "axis",
+        axis: {
+          title: {
+            fontFamily: "Montserrat, sans-serif",
+            color: { color: "#bb3e00" },
+          },
+          label: {
+            name: {
+              color: { color: "#657c6a" },
+              fontFamily: "Open Sans, sans-serif",
+            },
+          },
+        },
+      },
+      {
+        key: "value",
+        label: {
+          value: {
+            color: { color: "#f7ad45" },
+            fontFamily: "Roboto, sans-serif",
+          },
+        },
+      },
+    ],
+  },
+});
+```
+
+### Horizontal bar gauge with segments and reference lines
+
+You can combine segments and reference lines to clearly
+put the measured value in context.
+
+In the example below, you can compare the current sales value with
+the value of last year and with the expected value.
+The segments colors indicate which range the current value
+falls into, and the reference lines and labels provide
+information about the referenced values.
+
+![gauge segments and ref lines](assets/sn-gauge-ref-lines-and-segments.png)
+
+```js
+nebula.render({
+  type: "gauge",
+  element: document.querySelector(".object"),
+  fields: ["=[A Sales $  with measure color]"],
+  properties: {
+    gaugetype: "bar",
+    measureAxis: { min: 0, max: 150000000 },
+    useSegments: true,
+    color: { useBaseColors: "off" },
+    segmentInfo: {
+      limits: [
+        { value: 91000000, gradient: false },
+        { value: 101000000, gradient: false },
+      ],
+      paletteColors: [{ color: "#EE4266" }, { color: "#FFD23F" }, { color: "#337357" }],
+    },
+    refLine: {
+      refLines: [
+        {
+          label: "Last year sales",
+          refLineExpr: { value: 91000000, label: "91000000" },
+          paletteColor: { color: "#cc3c5b" },
+        },
+        {
+          label: "Expectation",
+          refLineExpr: { value: 101000000, label: "101000000" },
+          paletteColor: { color: "#49bd2b" },
+        },
+      ],
+    },
+  },
+});
+```

package/api-specifications/properties.json

@@ -3,7 +3,7 @@
   "info": {
     "name": "@nebula.js/sn-gauge:properties",
     "description": "Gauge generic object definition",
-    "version": "0.8.9",
+    "version": "0.8.10",
     "license": "MIT",
     "stability": "stable",
     "x-qlik-visibility": "public"