npm package: @senx/discovery-plot
Description: Discovery Widgets Elements
Author: SenX
Latest version: 0.0.4

# Discovery Plot

## Usage

### In a Web Environment

#### With NPM/Yarn

    $ npm install @senx/discovery-plot

#### With CDN

```html

<script nomodule src="https://unpkg.com/@senx/discovery-plot/dist/discovery-plot/discovery-plot.js"></script>
<script type="module" src="https://unpkg.com/@senx/discovery-plot/dist/discovery-plot/discovery-plot.esm.js"></script>
```

#### Usage

```html

<html>
<head>
  <title>Test</title>
</head>
<body>
<discovery-plot url="https://warp.senx.io/api/v0/exec">
  1 4 <% DROP NEWGTS 'g' STORE
  1 10 <% 'ts' STORE $g $ts RAND + STU * NOW + NaN NaN NaN RAND ADDVALUE DROP %> FOR
  $g %> FOR
</discovery-plot>
<script nomodule src="https://unpkg.com/@senx/discovery-plot/dist/discovery-plot/discovery-plot.js"></script>
<script type="module" src="https://unpkg.com/@senx/discovery-plot/dist/discovery-plot/discovery-plot.esm.js"></script>
</body>
</html>
```

## Configuration

### discovery-tile

This Web component displays a Tile based upon a WarpScript (or FLoWS). The WarpScript is executed when the tile renders.

| Property         | Attribute         |  Type                     | Default       | Description |
| ---------------- | ----------------- | ------------------------ | ------------- |-------------|
| `debug`          | `debug`           | `boolean`                | `false`       | Enable debug messages | 
| `options`        | `options`         | `Param / string`         | `new Param()` | Serialized JSON options (see Params below) | 
| `type`           | `type`            | `line, area, scatter, step-area, spline-area, spline, step, step-after, step-before, annotation, bar, display, image, map, gauge, linear-gauge, circle, pie, plot, doughnut, rose, tabular, svg`  | | Chart type |   
| `url`            | `url`             | `string`                 | `undefined`   | exec url of your Warp 10 endpoint or Mobius WebSocket endpoint |
| `lang`            | `lang`             | `warpscript, flows`                 | `warpscript`   | Language used  |
| `chartTitle`     | `chart-title`     | `string`                 | `undefined`   | Title of the Tile, not mandatory, could be overridden by the dashboard definition (see Dashboard Definition below). | 
| `result`     | `result`      |  `DataModel / string`           |  | Execution result |

````html

<discovery-plot url="https://warp.senx.io/api/v0/exec">
  1 4 <% DROP NEWGTS 'g' STORE
  1 10 <% 'ts' STORE $g $ts RAND + STU * NOW + NaN NaN NaN RAND ADDVALUE DROP %> FOR
  $g %> FOR
</discovery-plot>
````

#### Params / Options

Options inherit from higher level.
![options](./assets/options.png)

| Name | Type | Default | Description |
|------|------|---------|-------------|
| type | `string` | | Chart type  (line, area, scatter, step-area, spline-area, spline, step, step-after, step-before, annotation, bar, display, image, map, gauge, linear-gauge, circle, pie, plot, doughnut, rose, tabular, svg, input:text, input:list, input:secret, input:autocomplete, input:slider, input:date, input:date-range, button) |
| timeMode | `string` | 'date' | date, timestamp or custom |
| timeZone | `string` | 'UTC' | Timezone |
| timeUnit | `string` | 'us' | Warp 10 time unit (us, ms, ns) |
| scheme | `string` | 'WARP10' | Color scheme (COHESIVE, COHESIVE_2, BELIZE, VIRIDIS, MAGMA, INFERNO, PLASMA, YL_OR_RD, YL_GN_BU, BU_GN, WARP10, NINETEEN_EIGHTY_FOUR, ATLANTIS, DO_ANDROIDS_DREAM, DELOREAN, CTHULHU, ECTOPLASM, T_MAX_400_FILM ) |
| showLegend | `boolean` | false | Display the chart legend |
| fullDateDisplay | `boolean` | false | Display full date on the XAxis |
| unit | `string` | | Unit to be displayed |
| bgColor |  `string` | | Background color of tiles |
| datasetColor | `string` | | Only for the `param` field in execution result. Color of the trace |
| fontColor |  `string` | | Font color in tiles |
| borderColor |  `string` | | Border color in tiles |
| showLegend |  `boolean` | false | Display chart legend |
| responsive |  `boolean` | true | Responsive charts |
| showRangeSelector |  `boolean` | false | Display the skyline below line or area charts |
| autoRefresh |  `number` | -1 | if positive value, will refresh with a request each `autoRefresh` second for http requests, milliseconds for WebSocket |
| showErrors |  `boolean` | true | Display errors if any |
| showStatus |  `boolean` | true | Display the Warp 10 execution status |
| expandAnnotation |  `boolean` | false | Expand annotations |
| scheme | `string` | 'WARP10' | Color scheme ( COHESIVE, COHESIVE_2, BELIZE, VIRIDIS, MAGMA, INFERNO, PLASMA, YL_OR_RD, YL_GN_BU, BU_GN, WARP10, NINETEEN_EIGHTY_FOUR, ATLANTIS, DO_ANDROIDS_DREAM, DELOREAN, CTHULHU, ECTOPLASM, T_MAX_400_FILM, MATRIX, CHARTANA) |
| eventHandler | `string` | 'type=Regexp,tag=Regexp' | Only applies on Tiles and Dashboard. See the events chapter below |

### Common CSS vars

| Name | Default |
|------|------|
| --gts-classname-font-color | #004eff |
| --gts-labelname-font-color | #19A979 |
| --gts-attrname-font-color | #ED4A7B |
| --gts-separator-font-color | #a0a0a0 |
| --gts-labelvalue-font-color | #000000 |
| --gts-attrvalue-font-color | #000000 |
| --warp-view-font-color | #000000 |
| --warp-view-bg-color | transparent |

### Specific charts configuration and CSS styles

| Event  | Description | Type                |
| ------ | ----------- | ------------------- |
| `draw` |             | `CustomEvent<void>` |

#### line, area, scatter, spline-area, step-area, spline, step, step-after, step-before

| Name | Default |
|------|------|
| --warp-view-chart-label-color | #8e8e8e |
| --warp-view-chart-grid-color | #8e8e8e |

| Name | Type | Description |
|------|------|-------------|
| data | `GTS`, `GTS[]`, custom data |  Data to display, numeric GTS only |
| globalParams |  `Option` | Global options (see above) concerning this tile, including chat type |
| params | `Option[]` | List of options (see above) concerning each displayed dataset depending of the index of this array |
| events | `Events[]` | List of events to emit (see below) |

Supported option per series are:

- datasetColor: Hex CSS color of the series. ie: '#fff00f'
- type: Chart type (line, area, scatter, step-area, spline-area, spline, step, step-after, step-before)
- xAxis: In case of multi-X axis support, represents the index of related axis.
- yAxis: In case of multi-Y axis support, represents the index of related axis.

````
1 4 <% 
  DROP NEWGTS 'g' STORE
  1 30 <% 
    'ts' STORE 
    $g $ts RAND + STU * NOW + NaN NaN NaN RAND ADDVALUE DROP 
  %> FOR
$g %> FOR STACKTOLIST 'data' STORE
{ 
  'data' $data 
  'params' [ 
    { 'datasetColor' '#dc3545' 'xAxis' 0 }
    { 'datasetColor' '#ff9900' 'xAxis' 0 }
    { 'type' 'area' 'datasetColor' '#90d743' 'xAxis' 1 }
    { 'datasetColor' 'white' 'xAxis' 0 }
  ]
}  
````

Custom data for line and scatter only:

````
<% [ 0 10 <% DROP [ RAND 10 * 5 -   RAND 10 * 5 - ] %> FOR ] %> 'rand' STORE
  {
    'title' 'Test'
    'globalParams' { }
    'data' [
      { 'label' 'A' 'values' @rand }
      { 'label' 'B' 'values' @rand }
    ]
  }
````

#### annotation

| Name | Default |
|------|------|
| --warp-view-chart-label-color | #8e8e8e |
| --warp-view-chart-grid-color | #8e8e8e |

| Name | Type | Description |
|------|------|-------------|
| data | `GTS`, `GTS[]` |  Data to display, non-numeric GTS only |
| globalParams |  `Option` | Global options (see above) concerning this tile |
| params | `Option[]` | List of options (see above) concerning each displayed dataset depending of the index of this array |
| events | `Events[]` | List of events to emit (see below) |

Supported option per series are:

- datasetColor: Hex CSS color of the series. ie: '#fff00f'

#### bar

| Name | Default |
|------|------|
| --warp-view-chart-label-color | #8e8e8e |
| --warp-view-chart-grid-color | #8e8e8e |

| Name | Type | Description |
|------|------|-------------|
| data | `GTS`, `GTS[]`, custom data |  Data to display |
| globalParams |  `Option` | Global options (see above) concerning this tile |
| params | `Option[]` | List of options (see above) concerning each displayed dataset depending of the index of this array |
| events | `Events[]` | List of events to emit (see below) |

Supported option per series are:

- datasetColor: Hex CSS color of the series. ie: '#fff00f'
- bar
    - horizontal: Bar chart orientation
    - stacked

##### Custom data:

````json
{
  "title": "Test",
  "columns":  [ "A", "B", "C", "D" ],
  "rows": [
    [ "label X", 15, 56, 44, 22 ],
    [ "label Y", 1, 5, 4, 2 ],
    [ "label Z", 14, 45, 78, 12 ]
  ]
}
````

#### display


| Name | Type | Description |
|------|------|-------------|
| data | `number`, `string`, custom data |  Data to display |
| globalParams |  `Option` | Global options (see above) concerning this tile |
| params | `Option[]` | List of options (see above) concerning each displayed dataset depending of the index of this array |
| events | `Events[]` | List of events to emit (see below) |

- Option.timeMode:
    - date: convert the value into an ISO date.
    - duration: convert the value to a human-readable duration.
    - custom: display value as is, including HTML.

##### Custom Data Samples:

````
{ 'data' 42 'globalParams' { 'timeMode' 'custom' } }
````

````
{ 'data' NOW 'globalParams' { 'timeMode' 'date' } }
````

````
{ 'data' NOW 5 s - 'globalParams' { 'timeMode' 'duration' } }
````

````
{
  'data' '<a href="https://warp10.io/" target="_blank">Warp 10</a>'
  'globalParams' { 'bgColor' '#f57f17' 'fontColor' '#bc5100' 'timeMode' 'custom' }
}
````

````
{
  'data' { 'text' 'SenX.io' 'url' 'https://senx.io' }
  'globalParams' { 'bgColor' '#f57f17' 'fontColor' '#bc5100' }
}
````

#### map


| Name | Type | Description |
|------|------|-------------|
| data |   `GTS`, `GTS[]`, custom data  |  Data to display |
| globalParams |  `Option` | Global options (see above) concerning this tile |
| params | `Option[]` | List of options (see above) concerning each displayed dataset depending of the index of this array |
| events | `Events[]` | List of events to emit (see below) |

##### Custom data:

- `string[]`: considered as GEOJson
- `GTS[]`: considered as Path

##### Options

| Name | Type | Description |
|------|------|-------------|
| tiles | `string[]` | List of custom tile layers |
| mapType | `string` | Base tile layer (NONE, DEFAULT, HOT, TOPO, TOPO2, STADIA, STADIA_DARK, TONER, TONER_LITE, TERRAIN, ESRI, SATELLITE, OCEANS, GRAY, GRAYSCALE, WATERCOLOR, CARTODB, CARTODB_DARK) |
| startLat | `number` | Initial latitude position |
| startLong | `number` | Initial longitude position |
| startZoom | `number` | Initial zoom level |
| maxNativeZoom | `number` | Maximum zoom number the tile source has available. If it is specified, the tiles on all zoom levels higher than maxNativeZoom will be loaded from maxNativeZoom level and auto-scaled. |
| maxZoom | `number` | The maximum zoom level up to which this layer will be displayed (inclusive). |

##### Params:

Render dots without lines:

````
{
  'key' 'bases'
  'render' 'dots'
  "color" "#f44336"
  "line" false
}
````
Render weighted dots:

````
{
  'key' 'sightings'
  'render' 'weightedDots'
  "color" "#31C0F6cc"
  "borderColor" "#31C0F6"
  "maxValue" 100
  "minValue" 0
}
````

#### Gauge, circle

| Name | Default |
|------|------|
| --warp-view-chart-label-color | #8e8e8e |
| --warp-view-chart-grid-color | #8e8e8e |

| Name | Type | Description |
|------|------|-------------|
| data | `GTS`, `GTS[]`, custom data |  Data to display |
| globalParams |  `Option` | Global options (see above) concerning this tile |
| params | `Option[]` | List of options (see above) concerning each displayed dataset depending of the index of this array |
| events | `Events[]` | List of events to emit (see below) |

##### Params

| Name | Type | Description |
|------|------|-------------|
| maxValue | `number` | Max value for gauge |

#### linear-gauge

| Name | Default |
|------|------|
| --warp-view-chart-label-color | #8e8e8e |
| --warp-view-chart-grid-color | #8e8e8e |

| Name | Type | Description |
|------|------|-------------|
| data | `GTS`, `GTS[]`, custom data |  Data to display |
| globalParams |  `Option` | Global options (see above) concerning this tile |
| params | `Option[]` | List of options (see above) concerning each displayed dataset depending of the index of this array |
| events | `Events[]` | List of events to emit (see below) |

##### Options

| Name | Type | Description |
|------|------|-------------|
| gauge.horizontal | `boolean` | Gauge orientation |

##### Params

| Name | Type | Description |
|------|------|-------------|
| maxValue | `number` | Max value for gauge |

#### pie, doughnut, rose

| Name | Default |
|------|------|
| --warp-view-chart-label-color | #8e8e8e |
| --warp-view-chart-grid-color | #8e8e8e |

| Name | Type | Description |
|------|------|-------------|
| data | `GTS`, `GTS[]`, custom data |  Data to display |
| globalParams |  `Option` | Global options (see above) concerning this tile |
| params | `Option[]` | List of options (see above) concerning each displayed dataset depending of the index of this array |
| events | `Events[]` | List of events to emit (see below) |

##### Custom data:

`{ 'key':string 'value':number }[]`

## Demo

````shell
npm run dev
````