@splunk/visualizations 25.6.0 → 25.7.0

package/TRELLIS.md

@@ -0,0 +1,296 @@
+# Trellis layout
+
+> Trellis is only available for single value visualizations.
+
+Organize your search results with the trellis layout for a holistic view of your data. Trellis layout visualizes your search results by separating each value field or aggregation.
+
+The search in the following example returns customer purchases by product category. Applying a trellis layout creates a view of each product category as its own single value visualization.
+
+`index="sample-data" | stats count by productName`
+
+![](./src/common/docs/images/trellis-intro.png)
+
+## Create a trellis layout
+
+Configure your visualization for the trellis layout by adding the `splitByLayout:trellis` option in the `options` stanza. You might need to adjust the sizing of your trellis layout to fit your page.
+
+### Trellis layout configuration UI
+
+Customers with access to a Unified Dashboard Framework (UDF) **Edit** mode can create the trellis layout using the following steps. If you’re not using UDF, skip to step 4.
+
+1. Select a single value visualization using the visual editor by clicking the **Add Chart** dropdown menu in the editing toolbar.
+2. Select the single value on your dashboard so that it's highlighted with the blue editing outline.
+3. Set up a new data source by adding selecting **+ Create Search** and adding a search to the **Search query** window. Or, select an existing data source under the **Search**, **Saved Search**, or **Chain Search** dropdown lists.
+4. Activate the trellis layout by toggling on **Trellis Layout** in the **Data display** section of the Configuration panel.
+
+## Configurations for trellis layout
+
+Additionally, you can add the following trellis configurations to the `options` stanza for further customization.
+
+```markup
+| Option                 | Type   | Default                         | Description                                                                                                                                                                                                                                                                                                                        |
+| ---------------------- | ------ | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| splitByLayout          | string | off                             | Specify the layout method to display the visualization, which splits the data into individual visualizations based on a specific category. The available values are off and trellis.                                                                                                                                               |
+| trellisBackgroundColor | string | > themes.defaultBackgroundColor | Specify the background color of the whole panel in the trellis layout display. For example, “#FF0000”. You can use a hexadecimal code to apply the color. The default for Enterprise light is #ffffff. The default for Enterprise dark is #000000. The default for Prisma dark is #0b0c0e.                                         |
+| trellisColumns         | number | n/a                             | Specify the number of columns in a trellis layout container. For example, six columns allow six visualizations per row. Rows populate to accommodate the total number of visualizations. If no column number is specified, the number of columns is automatically set based on the value specified for trellisMinColumnWidth.      |
+| trellisMinColumnWidth  | number | 100                             | Specify the minimum width, in pixels, of each visualization in the trellis container. If you resize the window or panel, you can view the remaining visualizations by scrolling.                                                                                                                                                   |
+| trellisPageCount       | number | 20                              | Specify the maximum number of visualizations to display on a single page in the trellis container. The remaining visualizations paginate accordingly.                                                                                                                                                                              |
+| trellisRowHeight       | number | 70                              | Specify each visualization's height, in pixels, in the trellis container. If you resize the window or panel, you can view the remaining visualizations by scrolling.                                                                                                                                                               |
+| trellisSplitBy         | string | n/a                             | If applicable, specify the column's field name with categories used or aggregations to split the data into individual visualizations for trellis display. If you use an SPL `timechart` command, this might default to the SPL `by` clause field. If you use an SPL `chart` command, this might default to the first string field. |
+```
+
+## Overview of data-splitting logic
+
+The trellis layout splits data visualizations based on the SPL commands and associated metadata or configurations provided. The data-splitting logic defaults to SPL commands and associated metadata first, then option configurations. If you apply configuration options, any of those options could impact how the logic behaves with SPL commands or data field types. The following examples show different scenarios of data-splitting logic.
+
+If your application has SPL support, the following are examples of how SPL searches impact the trellis layout data-splitting logic. If your application doesn’t have SPL, you might need to restructure your data and use the `trellisSplitBy` option to achieve similar results to the following examples.
+
+### Split data with the timechart command
+
+When using the SPL `timechart` command, the trellis layout defaults to an associated `by` clause. The following example shows how the trellis layout categorizes each single value visualization by product name as a result of the SPL search `index="sample-data" | timechart count by productName`.
+
+![](./src/common/docs/images/trellis-timechart.png)
+
+![](./src/common/docs/images/trellis-timechart-table.png)
+
+#### Source code
+
+```
+import React from 'react';
+import { FeatureFlagContextProvider } from '@splunk/visualization-context/FeatureFlagContext';
+import SingleValue from '@splunk/visualizations/SingleValue';
+
+export default () => (
+    <FeatureFlagContextProvider value={{ visualizations_enableTrellis: true }}>
+      <SingleValue
+         options={{
+            splitByLayout: 'trellis',
+         }}
+         dataSources={{
+            primary: {
+               data: {
+                  columns: [
+                     [
+                        '2023-03-21T00:00:00.000+00:00',
+                        '2023-03-22T00:00:00.000+00:00',
+                        '2023-03-23T00:00:00.000+00:00',
+                        '2023-03-24T00:00:00.000+00:00',
+                        '2023-03-25T00:00:00.000+00:00',
+                        '2023-03-26T00:00:00.000+00:00',
+                        '2023-03-27T00:00:00.000+00:00',
+                        '2023-03-28T00:00:00.000+00:00',
+                     ],
+                     ['80', '271', '263', '289', '263', '304', '268', '236'],
+                     ['62', '265', '263', '289', '263', '304', '261', '205'],
+                     ['51', '291', '263', '289', '263', '304', '268', '211'],
+                     ['77', '334', '263', '289', '263', '304', '301', '230'],
+                  ],
+                  fields: [
+                     {
+                        name: '_time',
+                     },
+                     {
+                        name: 'Dream Crusher',
+                     },
+                     {
+                        name: 'Final Sequel',
+                     },
+                     {
+                        name: 'Fire Resistance Suit of Provolone',
+                     },
+                     {
+                        name: 'Grand Theft Scooter',
+                     },
+                  ],
+               },
+               meta: {},
+            },
+         }}
+      />
+    </FeatureFlagContextProvider>
+);
+
+```
+
+### Split data with the chart or stats commands
+
+The trellis layout defaults to the first string field when using the SPL `chart` or `stats` command with one `by` clause. The following example shows how the trellis layout categorizes each single value visualization by the `productName` column as a result of the SPL search `index="sample-data" | chart count by productName`.
+
+![](./src/common/docs/images/trellis-chart-stats.png)
+
+![](./src/common/docs/images/trellis-chart-stats-table.png)
+
+#### Source code
+
+```
+import React from 'react';
+import { FeatureFlagContextProvider } from '@splunk/visualization-context/FeatureFlagContext';
+import SingleValue from '@splunk/visualizations/SingleValue';
+
+export default () => (
+    <FeatureFlagContextProvider value={{ visualizations_enableTrellis: true }}>
+      <SingleValue
+         options={{
+            splitByLayout: 'trellis',
+            trellisSplitBy: 'productName',
+         }}
+         dataSources={{
+            primary: {
+               data: {
+                  columns: [
+                     ['Benign Space Debris', 'Curling 2014', 'Dream Crusher', 'Final Sequel'],
+                     ['1309', '1346', '1974', '1766'],
+                  ],
+                  fields: [
+                     {
+                        name: 'productName',
+                     },
+                     {
+                        name: 'count',
+                     },
+                  ],
+               },
+               meta: {},
+            },
+         }}
+      />
+    </FeatureFlagContextProvider>
+);
+
+```
+
+### Split specific data with the trellisSplitBy option
+
+If you don't want to rely on the default data-splitting logic, you can split your data by a specific field name using the 'trellisSplitBy' option. For example, you can split the data by price if you have multiple products with different price points. Using `trellisSplitBy` overrides the logic to split the data by product name.
+
+The following example sets `trellisSplitBy: price` with the SPL search `index="sample-data" | chart count by productName, price`. `"sample-data"` is a lookup file available for upload in the [Search Tutorial](https://docs.splunk.com/Documentation/Splunk/latest/SearchTutorial/WelcometotheSearchTutorial) of the _Search Tutorial_ manual.
+
+![](./src/common/docs/images/trellis-split-by.png)
+
+![](./src/common/docs/images/trellis-split-by-table.png)
+
+#### Source code
+
+```
+import React from 'react';
+import { FeatureFlagContextProvider } from '@splunk/visualization-context/FeatureFlagContext';
+import SingleValue from '@splunk/visualizations/SingleValue';
+
+export default () => (
+    <FeatureFlagContextProvider value={{ visualizations_enableTrellis: true }}>
+      <SingleValue
+         options={{
+            backgroundColor: '#BDBDBD',
+            splitByLayout: 'trellis',
+            trellisSplitBy: 'price',
+         }}
+         dataSources={{
+            primary: {
+               data: {
+                  columns: [
+                     ['Benign Space Debris', 'Curling 2014', 'Dream Crusher', 'Final Sequel'],
+                     ['0', '1346', '0', '0', '0', '0'],
+                     ['1309', '0', '0', '1766', '0', '0'],
+                     ['0', '0', '0', '0', '0', '0'],
+                  ],
+                  fields: [
+                     {
+                        name: 'productName',
+                     },
+                     {
+                        name: '19.99',
+                     },
+                     {
+                        name: '24.99',
+                     },
+                     {
+                        name: '26.99',
+                     },
+                  ],
+               },
+               meta: {},
+            },
+         }}
+      />
+    </FeatureFlagContextProvider>
+);
+
+```
+
+### Configure trellisSplitBy with aggregations
+
+Aggregations are categories specified by field name prefixes. For example, avg(price) is an aggregation of the average price, and max(price) is an aggregation of the maximum price. You can split your data by aggregations using the `trellisSplitBy` option.
+
+The following example sets `trellisSplitBy` aggregations with the SPL search `index="sample-data" | timechart avg(price), max(price)`.
+
+![](./src/common/docs/images/trellis-aggregations.png)
+
+![](./src/common/docs/images/trellis-aggregations-table.png)
+
+#### Source code
+
+```
+import React from 'react';
+import { FeatureFlagContextProvider } from '@splunk/visualization-context/FeatureFlagContext';
+import SingleValue from '@splunk/visualizations/SingleValue';
+
+export default () => (
+    <FeatureFlagContextProvider value={{ visualizations_enableTrellis: true }}>
+      <SingleValue
+         options={{
+            splitByLayout: 'trellis',
+            trellisSplitBy: 'aggregations',
+         }}
+         dataSources={{
+            primary: {
+               data: {
+                  columns: [
+                     [
+                        '2023-03-21T00:00:00.000+00:00',
+                        '2023-03-22T00:00:00.000+00:00',
+                        '2023-03-23T00:00:00.000+00:00',
+                        '2023-03-24T00:00:00.000+00:00',
+                        '2023-03-25T00:00:00.000+00:00',
+                        '2023-03-26T00:00:00.000+00:00',
+                        '2023-03-27T00:00:00.000+00:00',
+                        '2023-03-28T00:00:00.000+00:00',
+                     ],
+                     ['22.64029940119746', '21.768596847991684', '21.885890410958826', '21.936683354193125'],
+                     ['49.99', '49.99', '49.99', '49.99'],
+                  ],
+                  fields: [
+                     {
+                        name: '_time',
+                     },
+                     {
+                        name: 'avg(price)',
+                     },
+                     {
+                        name: 'max(price)',
+                     },
+                  ],
+               },
+               meta: {},
+            },
+         }}
+      />
+    </FeatureFlagContextProvider>
+);
+
+```
+
+## Customize trellis columns with trellisMinColumnWidth and trellisColumns
+
+You can customize the width of each visualization in the trellis layout with the `trellisMinColumnWidth` option. By default, `trellisMinColumnWidth` adjusts based on the configuration of the `config.ts` file and the parent panel width.
+
+The following example shows how the trellis layout changes when the default `trellisMinColumnWidth` is updated to `trellisMinColumnWidth: 150`.
+
+![](./src/common/docs/images/trellis-col-1.png)
+
+![](./src/common/docs/images/trellis-col-2.png)
+
+You can customize the number of visualizations to display in a single row of the trellis panel with `trellisColumns`. Visualizations with an undefined `trellisColumns` fill and wrap within the set width of the trellis panel.
+
+The following example shows how visualizations might extend beyond the trellis panel with a `trellisMinColumnWidth: 150` and `trellisColumns: 6`.
+
+![](./src/common/docs/images/trellis-col-3.png)

package/Table.config.js

@@ -87,7 +87,7 @@ module.exports =
 /******/
 /******/
 /******/ 	// Load entry module and return exports
-/******/ 	return __webpack_require__(__webpack_require__.s = 76);
+/******/ 	return __webpack_require__(__webpack_require__.s = 80);
 /******/ })
 /************************************************************************/
 /******/ ({
@@ -161,11 +161,12 @@ var VizBehavior;
 
   VizBehavior["PLACEHOLDER"] = "placeholder";
   VizBehavior["PAGE_AND_SORT"] = "page-and-sort";
+  VizBehavior["TRELLIS"] = "trellis";
 })(VizBehavior = exports.VizBehavior || (exports.VizBehavior = {}));
 
 /***/ }),
 
-/***/ 25:
+/***/ 26:
 /***/ (function(module, exports) {
 
 module.exports = require("@splunk/visualizations-shared/colorConstants");
@@ -430,7 +431,36 @@ module.exports = require("@babel/runtime/helpers/defineProperty");
 
 /***/ }),
 
-/***/ 76:
+/***/ 8:
+/***/ (function(module, exports, __webpack_require__) {
+
+"use strict";
+
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.VizCategory = void 0;
+var VizCategory;
+
+(function (VizCategory) {
+  VizCategory["SINGLE_VALUE"] = "Single Value";
+  VizCategory["TRENDS"] = "Trends";
+  VizCategory["COMPARISONS"] = "Comparisons";
+  VizCategory["TABLE"] = "Table";
+  VizCategory["GAUGE"] = "Gauge";
+  VizCategory["DISTRIBUTIONS"] = "Distributions";
+  VizCategory["CHOROPLETH"] = "Choropleth Maps";
+  VizCategory["SHAPES"] = "Shapes";
+  VizCategory["MISC"] = "misc";
+  VizCategory["FLOW"] = "Flow";
+  VizCategory["CORRELATION"] = "Correlation";
+  VizCategory["SPATIAL"] = "Spatial";
+})(VizCategory = exports.VizCategory || (exports.VizCategory = {}));
+
+/***/ }),
+
+/***/ 80:
 /***/ (function(module, exports, __webpack_require__) {
 
 "use strict";
@@ -448,7 +478,7 @@ var lodash_1 = __webpack_require__(6);
 
 var schemaUtils_1 = __webpack_require__(3);
 
-var colorConstants_1 = __webpack_require__(25);
+var colorConstants_1 = __webpack_require__(26);
 
 var visualization_icons_1 = __webpack_require__(12);
 
@@ -462,7 +492,7 @@ var configUtils_1 = __webpack_require__(4);
 
 var VizBehavior_1 = __webpack_require__(2);
 
-var consts_1 = __webpack_require__(77);
+var consts_1 = __webpack_require__(81);
 
 var VizCategory_1 = __webpack_require__(8);
 
@@ -959,24 +989,21 @@ var editorConfig = [{
     option: 'count',
     editor: 'editor.number',
     editorProps: {
-      labelPosition: 'left',
       min: 0,
       labelWidth: EDITOR_LABEL_WIDTH
     }
   }], [{
     label: i18n_1._('Row numbers'),
     option: 'showRowNumbers',
-    editor: 'editor.toggle',
+    editor: 'editor.checkbox',
     editorProps: {
-      labelPosition: 'left',
       labelWidth: EDITOR_LABEL_WIDTH
     }
   }], [{
     label: i18n_1._('Internal fields'),
     option: 'showInternalFields',
-    editor: 'editor.toggle',
+    editor: 'editor.checkbox',
     editorProps: {
-      labelPosition: 'left',
       labelWidth: EDITOR_LABEL_WIDTH
     }
   }], [{
@@ -1004,7 +1031,7 @@ var editorConfig = [{
     editor: 'editor.tableBackgroundColor',
     editorProps: {
       themes: themes,
-      labelPosition: 'left',
+      labelPosition: 'top',
       labelWidth: EDITOR_LABEL_WIDTH,
       palette: _toConsumableArray(backgroundColorPaletteSet)
     }
@@ -1162,7 +1189,7 @@ exports.default = configUtils_1.enhanceConfig(config);
 
 /***/ }),
 
-/***/ 77:
+/***/ 81:
 /***/ (function(module, exports, __webpack_require__) {
 
 "use strict";
@@ -1181,35 +1208,6 @@ exports.validFontSizes = ['extraSmall', 'small', 'default', 'large'];
 
 /***/ }),
 
-/***/ 8:
-/***/ (function(module, exports, __webpack_require__) {
-
-"use strict";
-
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.VizCategory = void 0;
-var VizCategory;
-
-(function (VizCategory) {
-  VizCategory["SINGLE_VALUE"] = "Single Value";
-  VizCategory["TRENDS"] = "Trends";
-  VizCategory["COMPARISONS"] = "Comparisons";
-  VizCategory["TABLE"] = "Table";
-  VizCategory["GAUGE"] = "Gauge";
-  VizCategory["DISTRIBUTIONS"] = "Distributions";
-  VizCategory["CHOROPLETH"] = "Choropleth Maps";
-  VizCategory["SHAPES"] = "Shapes";
-  VizCategory["MISC"] = "misc";
-  VizCategory["FLOW"] = "Flow";
-  VizCategory["CORRELATION"] = "Correlation";
-  VizCategory["SPATIAL"] = "Spatial";
-})(VizCategory = exports.VizCategory || (exports.VizCategory = {}));
-
-/***/ }),
-
 /***/ 9:
 /***/ (function(module, exports) {