@splunk/visualizations 28.6.0 → 28.7.0

package/docs-llm/dsl/formatters/prepend-examples-json.md

@@ -0,0 +1,51 @@
+# Prepend Formatter Examples
+
+## Example 1
+
+```json
+{
+  "context": {
+    "staticUser": "All users",
+    "staticId": "*",
+    "additionalUsers": [
+      "Andrew",
+      "Chanelle"
+    ],
+    "idsAsNumbers": [
+      1,
+      2
+    ],
+    "users": "> primary | seriesByName(\"users\") | prepend(staticUser)",
+    "ids": "> primary | seriesByName(\"ids\") | prepend(staticId)",
+    "pathologicalIds": "> primary | seriesByName(\"idsAsNumbers\") | prepend(staticId)"
+  },
+  "options": {
+    "consolidatedUsers": "> primary | seriesByName(\"users\") | prepend(additionalUsers)",
+    "prependingFrames": "> primary | prepend(primary)"
+  },
+  "dataSources": {
+    "primary": {
+      "data": {
+        "columns": [
+          [
+            "Maurine",
+            "Jennings"
+          ],
+          [
+            "1",
+            "2"
+          ]
+        ],
+        "fields": [
+          {
+            "name": "users"
+          },
+          {
+            "name": "ids"
+          }
+        ]
+      }
+    }
+  }
+}
+```

package/docs-llm/dsl/formatters/prepend-examples-react.md

@@ -0,0 +1,33 @@
+# Prepend Formatter Examples
+
+## Example 1
+
+```jsx
+<SampleViz
+    context={{
+        staticUser: 'All users',
+        staticId: '*',
+        additionalUsers: ['Andrew', 'Chanelle'],
+        idsAsNumbers: [1, 2],
+        users: '> primary | seriesByName("users") | prepend(staticUser)', // returns ['All users', 'Maurine', 'Jennings']
+        ids: '> primary | seriesByName("ids") | prepend(staticId)' // returns ['*', '1', '2', '3']
+        pathologicalIds: '> primary | seriesByName("idsAsNumbers") | prepend(staticId)' // throws an error, since `staticId` is a string, while the pre-existing series is composed of numbers
+    }}
+    options={{
+        consolidatedUsers: '> primary | seriesByName("users") | prepend(additionalUsers)', // returns ['Andrew', 'Chanelle', 'Maurine', 'Jennings']
+        // returns {
+        //     columns: [['Maurine', 'Jennings', 'Maurine', 'Jennings'], ['1', '2', '1', '2']]
+        //     fields: [{ name: 'users' }, { name: 'ids' }]
+        // }
+        prependingFrames: '> primary | prepend(primary)'
+    }}
+    dataSources={{
+        primary: {
+            data: {
+                columns: [['Maurine', 'Jennings'], ['1', '2']],
+                fields: [{ name: 'users' }, { name: 'ids' }]
+            }
+        }
+    }}
+/>
+```

package/docs-llm/dsl/formatters/prepend.md

@@ -0,0 +1,9 @@
+# Prepend Formatter
+
+Formatter that prepends a DataFrame, DataSeries, or DataPoint to a pre-existing DataFrame or DataSeries with compatible types.
+
+If prepending a DataFrame to another DataFrame, the DataFrames must have the same number of DataSeries.
+For example, a DataFrame with 3 series such as `[[1, 2], [3, 4], [5, 6]]` cannot be prepended to a DataFrame with 2 series such as `[[7, 8], [9, 10]]`.
+
+Only the same DataPrimitive type or a DataPrimitive's composite DataPrimitives
+(e.g. DataSeries or DataPoint for DataFrame, or a DataPoint for a DataSeries) can be prepended to the pre-existing DataPrimitive.

package/docs-llm/dsl/formatters/range-value-examples-json.md

@@ -0,0 +1,48 @@
+# RangeValue Formatter Examples
+
+## Example 1
+
+```json
+{
+  "context": {
+    "colorThresholds": [
+      {
+        "from": 1321,
+        "value": "#00FFFF"
+      },
+      {
+        "to": 1321,
+        "value": "#FF00FF"
+      }
+    ]
+  },
+  "options": {
+    "valueOption": "> primary | seriesByIndex(0) | lastPoint()",
+    "colorOption": "> deltaValue | rangeValue(colorThresholds)"
+  },
+  "dataSources": {
+    "primary": {
+      "data": {
+        "columns": [
+          [
+            "1",
+            "103"
+          ],
+          [
+            "2018-08-19T00:00:00.000+00:00",
+            "2018-08-20T00:00:00.000+00:00"
+          ]
+        ],
+        "fields": [
+          {
+            "name": "foo"
+          },
+          {
+            "name": "_time"
+          }
+        ]
+      }
+    }
+  }
+}
+```

package/docs-llm/dsl/formatters/range-value-examples-react.md

@@ -0,0 +1,34 @@
+# RangeValue Formatter Examples
+
+## Example 1
+
+```jsx
+<SampleViz
+     context={{
+         colorThresholds: [
+             {
+                 from: 1321,
+                 value: '#00FFFF',
+             },
+             {
+                 to: 1321,
+                 value: '#FF00FF',
+             },
+         ],
+     }}
+     options={{
+         valueOption: '> primary | seriesByIndex(0) | lastPoint()', // returns 103
+         colorOption: '> deltaValue | rangeValue(colorThresholds)', // returns '#FF00FF'
+     }}
+     dataSources={{
+         primary: {
+             data: {
+                 columns: [
+                     ['1', '103'], ['2018-08-19T00:00:00.000+00:00', '2018-08-20T00:00:00.000+00:00'],
+                 ],
+                 fields: [{ name: 'foo', }, { name: '_time' }],
+             }
+         },
+     }}
+ />
+```

package/docs-llm/dsl/formatters/range-value.md

@@ -0,0 +1,15 @@
+# RangeValue Formatter
+
+Formatter function that takes the list of ranges and a defaultValue (if no range is found)
+and returns a function that takes a value and returns the range value if found, or the defaultValue if present.
+
+If neither are present, it returns the original value.
+
+The range fitting follows this criteria: `range.from <= value < range.to`
+
+A range can be defined as either a closed bound range: `{ from: 10, to: 20, value: 'foo' }`
+or an open bound range:
+`{ to: 20, value: 'bar' }` (open lower bound)
+`{ from: 100, value: 'oof' }` (open upper bound)
+
+@extends AbstractFormatter<DataType, DataType>

package/docs-llm/dsl/formatters/set-color-channel-examples-json.md

@@ -0,0 +1,40 @@
+# SetColorChannel Formatter Examples
+
+## Example 1
+
+```json
+{
+  "context": {
+    "rowBGConfig": {
+      "channel": "hsl.l",
+      "value": "*0.2"
+    },
+    "headerBackgroundColor": {
+      "channel": "hsv.v",
+      "value": "*0.66"
+    }
+  },
+  "options": {
+    "backgroundColor": "orangered",
+    "rowBackgroundColor": "> backgroundColor | setColorChannel(rowBGConfig)",
+    "headerColor": "> backgroundColor | setColorChannel(headerColorConfig)"
+  },
+  "dataSources": {
+    "primary": {
+      "data": {
+        "fields": [
+          {
+            "name": "foo"
+          }
+        ],
+        "columns": [
+          [
+            100,
+            200
+          ]
+        ]
+      }
+    }
+  }
+}
+```

package/docs-llm/dsl/formatters/set-color-channel-examples-react.md

@@ -0,0 +1,31 @@
+# SetColorChannel Formatter Examples
+
+## Example 1
+
+```jsx
+<SampleViz
+    context={{
+         rowBGConfig: {
+             channel: 'hsl.l',
+             value: '*0.2'
+         },
+         headerBackgroundColor: {
+             channel: 'hsv.v',
+             value: '*0.66'
+         }
+    }}
+    options={{
+        backgroundColor: 'orangered',
+        rowBackgroundColor: '> backgroundColor | setColorChannel(rowBGConfig)',   // #330e00
+        headerColor: '> backgroundColor | setColorChannel(headerColorConfig)',    // #a82e00
+    }}
+    dataSources={{
+        primary: {
+            data: {
+                fields: [{ name: 'foo' }]
+                columns: [[100, 200]]
+            }
+        }
+    }}
+/>
+```

package/docs-llm/dsl/formatters/set-color-channel.md

@@ -0,0 +1,9 @@
+# SetColorChannel Formatter
+
+SetColorChannel can be used to modify a given color.
+
+Leverages [Chromajs.set](https://gka.github.io/chroma.js/#color-set) to change the color
+
+## Config Object
+ * **channel**: 'string' refers to channel of the color. For ex: 'hsl.l' or 'hsl.s' or 'rgb.b'
+ * **value**: 'string' or 'number'. Can be used to set absolute. For ex: setColorChannel({channel: 'hsl.h', value: 0}). Can be used as relative. For ex: setColorChannel({channel: 'lab.l', value: '*0.5'})

package/docs-llm/dsl/formatters/suffix-examples-json.md

@@ -0,0 +1,29 @@
+# Suffix Formatter Examples
+
+## Example 1
+
+```json
+{
+  "context": {},
+  "options": {
+    "textOption": "> primary | seriesByName(\"foo\") | lastPoint() | suffix(\" %\")"
+  },
+  "dataSources": {
+    "primary": {
+      "data": {
+        "fields": [
+          {
+            "name": "foo"
+          }
+        ],
+        "columns": [
+          [
+            100,
+            200
+          ]
+        ]
+      }
+    }
+  }
+}
+```

package/docs-llm/dsl/formatters/suffix-examples-react.md

@@ -0,0 +1,19 @@
+# Suffix Formatter Examples
+
+## Example 1
+
+```jsx
+<SampleViz
+    options={{
+        textOption: '> primary | seriesByName("foo") | lastPoint() | suffix(" %")' // returns "100 %"
+    }}
+    dataSources={{
+        primary: {
+            data: {
+                fields: [{ name: 'foo' }]
+                columns: [[100, 200]]
+            }
+        }
+    }}
+/>
+```

package/docs-llm/dsl/formatters/suffix.md

@@ -0,0 +1,3 @@
+# Suffix Formatter
+
+Appends the given suffix (passed as a parameter) to the DataPoint.

package/docs-llm/dsl/formatters/type-examples-json.md

@@ -0,0 +1,37 @@
+# Type Formatter Examples
+
+## Example 1
+
+```json
+{
+  "context": {},
+  "options": {
+    "option1": "> primary | seriesByIndex(0) | type()",
+    "option2": "> primary | seriesByIndex(1) | type()"
+  },
+  "dataSources": {
+    "primary": {
+      "columns": [
+        [
+          100,
+          200,
+          300
+        ],
+        [
+          "string1",
+          "string2",
+          "string3"
+        ]
+      ],
+      "fields": [
+        {
+          "name": "foo"
+        },
+        {
+          "name": "bar"
+        }
+      ]
+    }
+  }
+}
+```

package/docs-llm/dsl/formatters/type-examples-react.md

@@ -0,0 +1,20 @@
+# Type Formatter Examples
+
+## Example 1
+
+```jsx
+<SampleViz
+    options={{
+        option1: '> primary | seriesByIndex(0) | type()' // returns ['number', 'number', 'number']
+        option2: '> primary | seriesByIndex(1) | type()' // returns ['string', 'string', 'string']
+    }}
+    dataSources={{
+        data: {
+            primary: {
+                columns: [[100, 200, 300], ['string1', 'string2', 'string3']]
+                fields: [{ name: 'foo' }, { name: 'bar' }]
+            }
+        }
+    }}
+/>
+```

package/docs-llm/dsl/formatters/type.md

@@ -0,0 +1,3 @@
+# Type Formatter
+
+Formatter that returns the DataType for each element within the given DataSeries.

package/docs-llm/dsl/overview.md

@@ -0,0 +1,41 @@
+# Fundamentals of DSL
+
+The consolidated visualizations package introduces a DSL to bind options to data and provide a rich data-driven visualization configuration experience. While options for a visualization still accept static values, DSL allows for dynamically configuring option values at runtime based on received data. The DSL allows the user to read data from a specified identifier, apply formatting and transformations to the selected data, specify a formatting/transformation pipeline to process the data, and to use the resultant output as the value for a given option.
+
+## Data Primitives
+
+The structure of the data the DSL receives can be categorized within three main Data Primitive structures: `DataFrame`, `DataSeries`, and `DataPoint`. Within the DSL, the data that is piped from one selector/formatter to another conforms to one of these given Data Primitive structures (or their raw equivalents).
+
+A `DataFrame` is comprised of a list of `DataSeries`, a `DataSeries` is a list of `DataPoints`, and a `DataPoint` holds an individual primitive value (e.g. a string, number, boolean).
+
+## DSL Selectors
+
+To select the data of interest when configuring a dynamic option, the DSL exposes a list of selectors to reduce the data from its original structure. These selectors are defined at the `DataFrame`, `DataSeries`, and `DataPoint` levels.
+
+## DSL Formatters
+
+DSL formatters allow you to transform and map the data you receive into the desired format. Some formatters replace the original functions of encoding v1 (e.g. specifying gradients, thresholding, and match values), while others provide additional data formatting capabilities that were not possible in encoding v1 (e.g. formatting string data values via units, prepending text to data, etc.).
+
+## DSL Scopes
+
+The main global scopes that the DSL can read identifiers from are `context`, `datasources`, `options`, and `themes`. The contents of `context`, `datasources`, and `options` and scopes are directly defined by the user and passed into the visualization, while values from `themes` are taken from the theme variables that the given visualization exposes. In addition to identifiers found in global scopes, DSL can resolve identifiers at the local scope as shown in the example below.
+
+### Qualified (global) vs. Unqualified Identifiers
+
+Qualified identifiers are references to DSL-scoped variables which denote the full path to the DSL-scoped variable value (e.g. `context.foo.bar`). However, the DSL can also infer the value of local identifiers. For example, if a deeply nested identifier is defined within `context` and is referenced at the local scope (such as `context={{ foo: { bar: 'val1', d: '> bar' } }}`), the DSL defined in `context.foo.d` will be resolved as `val1`.
+
+If an identifier is not prefixed with one of the aforementioned global scopes, the DSL will first look at the local level (i.e. other identifiers defined at the same level relative to where the original identifier was defined) to resolve the value. If this does not return a match, the DSL will look through the list of identifiers defined at the first level of the global scope objects to find the identifier (i.e. `context.identifier`, `datasources.identifier`, `options.identifier`, `themes.identifier`).
+
+The following shows an example of how DSL variable name resolution is performed.
+
+## Use
+
+The example below shows a SingleValue visualization configured to use DSL for dynamically defining certain options.
+
+In this example, DSL is configured for the `sparklineValues`, `trendValue`, and `trendColor` options.
+
+The `sparklineValues` DSL reads data from the `primary` identifier (which is defined within the `datasources` global scope) and reads data of a `DataFrame`-type structure from the `primary` identifier. This data is then reduced to a `DataSeries` structure by applying the `seriesByIndex` DSL selector, and the `sparklineValues` option receives this resolved output as its dynamic value.
+
+The `trendValues` DSL takes the resolved data of the `sparklineValues` (which now exists at the local scope) and applies the `delta` selector to reduce this even further to a `DataPoint` data structure.
+
+The `trendColor` DSL applies formatting to the DataPoint by mapping the target range that the `DataPoint` falls into. The corresponding `DataPoint` value for the target range is then returned.

package/docs-llm/dsl/selectors/abs.md

@@ -0,0 +1,7 @@
+# abs
+
+Returns the absolute value of the current data point as a new DataPoint.
+Numeric types and numeric strings are both supported.
+
+@public
+@returns {DataPoint<'number'>} DataPoint with absolute value, or undefined for non-numeric input

package/docs-llm/dsl/selectors/ceil.md

@@ -0,0 +1,7 @@
+# ceil
+
+Ceils the current data point value to the nearest higher integer and returns a new DataPoint.
+Numeric types and numeric strings are both supported.
+
+@public
+@returns {DataPoint<'number'>} DataPoint with ceiled value, or undefined for non-numeric input

package/docs-llm/dsl/selectors/data-frame-average-examples-json.md

@@ -0,0 +1,41 @@
+# DataFrame#average Examples
+
+## Example 1
+
+```json
+{
+  "context": {},
+  "options": {
+    "majorValue": "> primary | average()",
+    "trendDisplay": "off",
+    "sparklineDisplay": "off"
+  },
+  "dataSources": {
+    "primary": {
+      "data": {
+        "fields": [
+          {
+            "name": "_time"
+          },
+          {
+            "name": "count"
+          }
+        ],
+        "columns": [
+          [
+            "2018-08-19T00:00:00.000+00:00",
+            "2018-08-20T00:00:00.000+00:00",
+            "2018-08-21T00:00:00.000+00:00"
+          ],
+          [
+            "10",
+            "20",
+            "30"
+          ]
+        ]
+      },
+      "meta": {}
+    }
+  }
+}
+```

package/docs-llm/dsl/selectors/data-frame-average-examples-react.md

@@ -0,0 +1,36 @@
+# DataFrame#average Examples
+
+## Example 1
+
+```jsx
+<SingleValue
+    options={{
+        majorValue: '> primary | average()',
+        trendDisplay: 'off',
+        sparklineDisplay: 'off'
+    }}
+    dataSources={{
+        primary: {
+            data: {
+                fields: [
+                    {
+                        name: '_time',
+                    },
+                    {
+                        name: 'count',
+                    },
+                ],
+                columns: [
+                    [
+                        '2018-08-19T00:00:00.000+00:00',
+                        '2018-08-20T00:00:00.000+00:00',
+                        '2018-08-21T00:00:00.000+00:00',
+                    ],
+                    [ '10', '20', '30' ],
+                ],
+            },
+            meta: {},
+        },
+    }}
+/>
+```

package/docs-llm/dsl/selectors/data-frame-average.md

@@ -0,0 +1,7 @@
+# DataFrame#average
+
+Get the average of all numeric values from all numeric DataSeries in the DataFrame.
+@public
+@returns {DataPoint<DataType>}
+
+The following code sample shows how to use average to display the mean of all data points in a data source as a single value.

package/docs-llm/dsl/selectors/data-frame-count-examples-json.md

@@ -0,0 +1,41 @@
+# DataFrame#count Examples
+
+## Example 1
+
+```json
+{
+  "context": {},
+  "options": {
+    "majorValue": "> primary | count()",
+    "trendDisplay": "off",
+    "sparklineDisplay": "off"
+  },
+  "dataSources": {
+    "primary": {
+      "data": {
+        "fields": [
+          {
+            "name": "_time"
+          },
+          {
+            "name": "count"
+          }
+        ],
+        "columns": [
+          [
+            "2018-08-19T00:00:00.000+00:00",
+            "2018-08-20T00:00:00.000+00:00",
+            "2018-08-21T00:00:00.000+00:00"
+          ],
+          [
+            "10",
+            "20",
+            "30"
+          ]
+        ]
+      },
+      "meta": {}
+    }
+  }
+}
+```

package/docs-llm/dsl/selectors/data-frame-count-examples-react.md

@@ -0,0 +1,36 @@
+# DataFrame#count Examples
+
+## Example 1
+
+```jsx
+<SingleValue
+    options={{
+        majorValue: '> primary | count()',
+        trendDisplay: 'off',
+        sparklineDisplay: 'off'
+    }}
+    dataSources={{
+        primary: {
+            data: {
+                fields: [
+                    {
+                        name: '_time',
+                    },
+                    {
+                        name: 'count',
+                    },
+                ],
+                columns: [
+                    [
+                        '2018-08-19T00:00:00.000+00:00',
+                        '2018-08-20T00:00:00.000+00:00',
+                        '2018-08-21T00:00:00.000+00:00',
+                    ],
+                    [ '10', '20', '30' ],
+                ],
+            },
+            meta: {},
+        },
+    }}
+/>
+```

package/docs-llm/dsl/selectors/data-frame-count.md

@@ -0,0 +1,7 @@
+# DataFrame#count
+
+Get the count of all values from all DataSeries in the DataFrame.
+@public
+@returns {DataPoint<DataType>}
+
+The following code sample shows how to use count to display the total number of data points in a data source as a single value.