From 78e4908242b77624614135b81a8b9b6d0bc2f6dc Mon Sep 17 00:00:00 2001 From: Josh Romero Date: Fri, 18 Nov 2022 10:53:19 -0800 Subject: [PATCH] [Doc] Document `charts` plugin (#2695) - Update README with full capabilities - Add `current_usage` to track current usage Signed-off-by: Josh Romero Signed-off-by: Arpit Bandejiya --- CHANGELOG.md | 1 + docs/charts/current_usage.md | 184 +++++++++++++++++++++++++++++++++++ src/plugins/charts/README.md | 81 ++++++++++++--- 3 files changed, 255 insertions(+), 11 deletions(-) create mode 100644 docs/charts/current_usage.md diff --git a/CHANGELOG.md b/CHANGELOG.md index e0691372f424..5ed0d65e7560 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -77,6 +77,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) - Add the release runbook to RELEASING.md ([#2533](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/2533)) - [MD] Add design documents of multiple data source feature [#2538](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/2538) - [MD] Tweak multiple data source design doc [#2724](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/2724) +- Add `current-usage.md` and more details to `README.md` of `charts` plugin ([#2695](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/2695)) ### 🛠 Maintenance diff --git a/docs/charts/current_usage.md b/docs/charts/current_usage.md new file mode 100644 index 000000000000..f3e7db435955 --- /dev/null +++ b/docs/charts/current_usage.md @@ -0,0 +1,184 @@ +# Usage + +The purpose of this doc is to keep track of the current (as of 2022-11-14) usage of the [charts plugin](../../src/plugins/charts/), as well as other packages and tools with similar purposes. See https://github.com/opensearch-project/OpenSearch-Dashboards/issues/2830 for more information on future plans. + +## Lifecycle methods/services + +### `ChartsPluginStart` + +1. `ChartsPluginStart['theme']` used by `discover` plugin to fetch `chartsTheme` and `chartsBaseTheme` for use in styling the histogram. + +### `ChartsPluginSetup` + +1. `ChartsPluginSetup` declared as one of `MetricVisPluginSetupDependencies` in the `vis_type_metric` plugin, but isn't actually used. +2. `ChartsPluginSetup['colors']` used by `vis_type_tagcloud` plugin. Only the seed colors are used via `d3.scale.ordinal().range(colors.seedColors)` +3. `ChartsPluginSetup.colors` and `ChartsPluginSetup.theme` used by the `vis_type_timeseries` plugin. + 1. `themeService.useChartsBaseTheme()` is used only as a fallback; otherwise theme (dark or light) is calculated from the user-specified background color + 2. `colors.mappedColors` used to fetch mapped colors only if user has not specified a color for a particular series label (and there's no color specified from the server). +4. `ChartsPluginSetup.colors.createColorLookupFunction()` is used by the `vis_type_vislib` plugin, ultimately, as part of `getColorFunc()` and `getPieColorFunc()`; the former also uses fallback for default and overwritten colors from `uiState`. +5. Set as a dependency in stub plugin `vis_type_xy`, but not actually used. + +## `uiSettings` in advanced settings `visualization:colorMapping` + +Appears to only be used by the telemetry plugin: https://github.com/opensearch-project/OpenSearch-Dashboards/blob/95f4fd5c6a6cd59bd555bf0ec120843ef6a93566/src/plugins/telemetry/schema/oss_plugins.json#L1363 + +## Static functions and components + +### Color Maps + +#### `ColorMap` interface + +1. `region_map` plugin +2. `tile_map` plugin +3. `timeline` plugin +4. `vis_type_metric` plugin +5. `vis_type_timeline` plugin + +#### `ColorSchema` interface + +1. `maps_legacy` plugin +2. `region_map` plugin +3. `tile_map` plugin +4. `vis_type_metric` plugin +5. `vis_type_vislib` plugin +6. `visualizations` plugin +7. `visualize` plugin +8. `vis_builder` plugin + +#### `ColorSchemas` enum + +1. `region_map` plugin +2. `tile_map` plugin +3. `vis_type_metric` plugin +4. `vis_type_vislib` plugin +5. `vis_builder` plugin + +#### `RawColorSchema` interface + +Not used by any core plugins + +#### `colorSchemas` array of objects + +1. `region_map` plugin +2. `tile_map` plugin +3. `vis_type_metric` plugin +4. `vis_type_vislib` plugin +5. `vis_builder` plugin + +#### `getHeatmapColors` function + +1. `vis_type_metric` plugin +2. `vis_type_vislib` plugin + +#### `truncatedColorMaps` object + +1. `region_map` plugin +2. `tile_map` plugin + +#### `truncatedColorSchemas` array of objects + +1. `region_map` plugin +2. `tile_map` plugin + +#### `vislibColorMaps` object + +1. `vis_type_metric` plugin + +### React components + +These components may eventually make more sense elsewhere. See https://github.com/opensearch-project/OpenSearch-Dashboards/issues/2832 for one such proposal. + +#### `ColorModes` object + +1. `vis_type_metric` plugin +2. `vis_type_vislib` plugin +3. `vis_builder` plugin + +#### `Rotates` object + +1. `vis_type_vislib` plugin + +#### `BasicOptions` component + +1. `tile_map` plugin +2. `vis_type_vislib` plugin +3. `vis_builder` plugin + +#### `ColorRanges` component + +1. `vis_type_metric` plugin +2. `vis_type_vislib` plugin +3. `vis_builder` plugin + +#### `ColorSchemaOptions` component + +Accounts for customized `vis.colors` in the `uiState`. Supports setting custom colors via legend, and resetting. + +1. `vis_type_metric` plugin. Doesn't actually support custom colors +2. `vis_type_vislib` plugin +3. `vis_builder` plugin (metric visualization). Doesn't support custom colors + +#### `NumberInputOption` component + +1. `region_map` plugin +2. `vis_type_table` plugin +3. `vis_type_vislib` plugin + +#### `RangeOption` component + +1. `tile_map` plugin +2. `vis_type_markdown` plugin +3. `vis_type_metric` plugin +4. `vis_type_timeseries` plugin +5. `vis_builder` plugin + +#### `RequiredNumberInputOption` component + +1. `vis_type_vislib` plugin + +#### `SelectOption` component + +1. `index_pattern_management` plugin +2. `maps_legacy` plugin +3. `region_map` plugin +4. `tile_map` plugin +5. `vis_type_table` plugin +6. `vis_type_tagcloud` plugin +7. `vis_type_timeseries` plugin +8. `vis_type_vislib` plugin +9. `vis_builder` plugin + +#### `SwitchOption` component + +1. `maps_legacy` plugin +2. `region_map` plugin +3. `tile_map` plugin +4. `vis_type_markdown` plugin +5. `vis_type_metric` plugin +6. `vis_type_table` plugin +7. `vis_type_tagcloud` plugin +8. `vis_type_vislib` plugin +9. `vis_builder` plugin + +#### `TextInputOption` component + +1. `maps_legacy` plugin +2. `vis_type_vislib` plugin + +# OUI chart colors + +An alternative to using color schemas and maps provided by the `charts` plugin is to use [color palettes from OUI](https://github.com/opensearch-project/oui/blob/main/src/services/color/oui_palettes.ts). + +## `ouiPaletteColorBlind()` + +1. `index_pattern_management` plugin +2. `vis_type_vega` plugin +3. `vis_type_vislib` plugin + +## Other quantitative palettes + +Not currently used + +## `colorPalette` + +Not currently used diff --git a/src/plugins/charts/README.md b/src/plugins/charts/README.md index f7ff405c74f2..1afd049ea284 100644 --- a/src/plugins/charts/README.md +++ b/src/plugins/charts/README.md @@ -1,29 +1,88 @@ # Charts -The Charts plugin is a way to create easier integration of shared colors, themes, types and other utilities across all OpenSearch Dashboards charts and visualizations. +The Charts plugin provides utility services for accessing shared colors and themes for visual consistency across all OpenSearch Dashboards charts and visualizations. It also provides a number of static utility functions and standard components for user-specified chart configuration. -## Static methods +## Services -### `vislibColorMaps` +### Theme service -Color mappings related to vislib visualizations +A utility service for fetching `chartsTheme` and `chartsBaseTheme`. -### `truncatedColorMaps` +For more, see Theme service [docs](public/services/theme/README.md) -Color mappings subset of `vislibColorMaps` +### Color service +#### Static properties +##### `seedColors` + +A list of colors chosen for visual appeal. + +#### Static methods +##### `mappedColors` -### `colorSchemas` +Get a value-based mapping of colors. + +##### `createColorLookupFunction` + +Factory for color mapping function. + +## Static functions and components +### Color maps +#### `colorSchemas` Color mappings in `value`/`text` form -### `getHeatmapColors` +#### `getHeatmapColors` Function to retrieve heatmap related colors based on `value` and `colorSchemaName` -### `truncatedColorSchemas` +#### `truncatedColorMaps` + +Color mappings subset of `vislibColorMaps` + +#### `truncatedColorSchemas` Truncated color mappings in `value`/`text` form -## Theme +#### `vislibColorMaps` + +Color mappings related to vislib visualizations + +### Components + +Standardized React input UI components which can be used by visualization editors to specify various visualization options. + +#### `BasicOptions` + +Components for specifying legend and tooltip + +#### `ColorRanges` + +Component for specifying color range thresholds + +#### `ColorSchemaOptions` + +Component for specifying color schemas (palettes) + +#### `NumberInputOption` + +Deprecated in favor of `RequiredNumberInputOption` + +#### `RangeOption` + +Component for specifying a numerical value with a slider + +#### `RequiredNumberInputOption` + +Component for specifying numerical values, such as a threshold. + +#### `SelectOption` + +Basic select component + +#### `SwitchOption` + +Basic toggle component + +#### `TextInputOption` -See Theme service [docs](public/services/theme/README.md) +Basic text input component