[Lens] Color mapping for categorical dimensions

packages/kbn-coloring/src/shared_components/color_mapping/README.md

@@ -0,0 +1,87 @@
+# Color Mapping
+
+This shared component can be used to define a color mapping as an association of one or multiple string values to a color definition.
+
+This package provides:
+- a React component, called `CategoricalColorMapping` that provides a simplified UI (that in general can be hosted in a flyout), that helps the user generate a `ColorMapping.Config` object that descibes the mappings configuration
+- a function `getColorFactory` that given a color mapping configuration returns a function that maps a passed category to the corresponding color
+- a definition scheme for the color mapping, based on the type `ColorMapping.Config`, that provides an extensible way of describing the link between colors and rules. Collects the minimal information required apply colors based on categories. Together with the `ColorMappingInputData` can be used to get colors in a deterministic way.
+
+
+An example of the configuration is the following:
+```ts
+const DEFAULT_COLOR_MAPPING_CONFIG: ColorMapping.Config = {
+  assignmentMode: 'auto',
+  assignments: [
+    {
+        rule: {
+            type: 'matchExactly',
+            values: [''];
+        },
+        color: {
+            type: 'categorical',
+            paletteId: 'eui',
+            colorIndex: 2,
+        }
+    }
+  ],
+  specialAssignments: [
+    {
+      rule: {
+        type: 'other',
+      },
+      color: {
+        type: 'categorical',
+        paletteId: 'neutral',
+        colorIndex: 2
+      },
+      touched: false,
+    },
+  ],
+  paletteId: EUIPalette.id,
+  colorMode: {
+    type: 'categorical',
+  },
+};
+```
+
+The function `getColorFactory` is a curry function where, given the model, a palette getter, the theme mode (dark/light) and a list of categories, returns a function that can be used to pick the right color based on a given category.
+
+```ts
+function getColorFactory(
+  model: ColorMapping.Config,
+  getPaletteFn: (paletteId: string) => ColorMapping.CategoricalPalette,
+  isDarkMode: boolean,
+  data: {
+      type: 'categories';
+      categories: Array<string | string[]>;
+    }
+): (category: string | string[]) => Color
+```
+
+
+
+A `category` can be in the shape of a plain string or an array of strings. Numbers, MultiFieldKey, IP etc needs to be stringified.
+
+
+The `CategoricalColorMapping` React component has the following props:
+
+```tsx
+function CategoricalColorMapping(props: {
+  /** The initial color mapping model, usually coming from a the visualization saved object */
+  model: ColorMapping.Config;
+  /** A map of paletteId and palette configuration */
+  palettes: Map<string, ColorMapping.CategoricalPalette>;
+  /** A data description of what needs to be colored */
+  data: ColorMappingInputData;
+  /** Theme dark mode */
+  isDarkMode: boolean;
+  /** A map between original and formatted tokens used to handle special cases, like the Other bucket and the empty bucket */
+  specialTokens: Map<string, string>;
+  /** A function called at every change in the model */
+  onModelUpdate: (model: ColorMapping.Config) => void;
+})
+
+```
+
+the `onModelUpdate` callback is called everytime a change in the model is applied from within the component. Is not called when the `model` prop is updated.

packages/kbn-coloring/src/shared_components/color_mapping/categorical_color_mapping.test.tsx

@@ -0,0 +1,115 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import React from 'react';
+import { mount } from 'enzyme';
+import { CategoricalColorMapping, ColorMappingInputData } from './categorical_color_mapping';
+import { AVAILABLE_PALETTES } from './palettes';
+import { DEFAULT_COLOR_MAPPING_CONFIG } from './config/default_color_mapping';
+import { MULTI_FIELD_KEY_SEPARATOR } from '@kbn/data-plugin/common';
+
+const AUTO_ASSIGN_SWITCH = '[data-test-subj="lns-colorMapping-autoAssignSwitch"]';
+const ASSIGNMENTS_LIST = '[data-test-subj="lns-colorMapping-assignmentsList"]';
+const ASSIGNMENT_ITEM = (i: number) => `[data-test-subj="lns-colorMapping-assignmentsItem${i}"]`;
+
+describe('color mapping', () => {
+  it('load a default color mapping', () => {
+    const dataInput: ColorMappingInputData = {
+      type: 'categories',
+      categories: ['categoryA', 'categoryB'],
+    };
+    const onModelUpdateFn = jest.fn();
+    const component = mount(
+      <CategoricalColorMapping
+        data={dataInput}
+        isDarkMode={false}
+        model={{ ...DEFAULT_COLOR_MAPPING_CONFIG }}
+        palettes={AVAILABLE_PALETTES}
+        onModelUpdate={onModelUpdateFn}
+        specialTokens={new Map()}
+      />
+    );
+
+    expect(component.find(AUTO_ASSIGN_SWITCH).hostNodes().prop('aria-checked')).toEqual(true);
+    expect(component.find(ASSIGNMENTS_LIST).hostNodes().children().length).toEqual(
+      dataInput.categories.length
+    );
+    dataInput.categories.forEach((category, index) => {
+      const assignment = component.find(ASSIGNMENT_ITEM(index)).hostNodes();
+      expect(assignment.text()).toEqual(category);
+      expect(assignment.hasClass('euiComboBox-isDisabled')).toEqual(true);
+    });
+    expect(onModelUpdateFn).not.toBeCalled();
+  });
+
+  it('switch to manual assignments', () => {
+    const dataInput: ColorMappingInputData = {
+      type: 'categories',
+      categories: ['categoryA', 'categoryB'],
+    };
+    const onModelUpdateFn = jest.fn();
+    const component = mount(
+      <CategoricalColorMapping
+        data={dataInput}
+        isDarkMode={false}
+        model={{ ...DEFAULT_COLOR_MAPPING_CONFIG }}
+        palettes={AVAILABLE_PALETTES}
+        onModelUpdate={onModelUpdateFn}
+        specialTokens={new Map()}
+      />
+    );
+    component.find(AUTO_ASSIGN_SWITCH).hostNodes().simulate('click');
+    expect(onModelUpdateFn).toBeCalledTimes(1);
+    expect(component.find(AUTO_ASSIGN_SWITCH).hostNodes().prop('aria-checked')).toEqual(false);
+    expect(component.find(ASSIGNMENTS_LIST).hostNodes().children().length).toEqual(
+      dataInput.categories.length
+    );
+    dataInput.categories.forEach((category, index) => {
+      const assignment = component.find(ASSIGNMENT_ITEM(index)).hostNodes();
+      expect(assignment.text()).toEqual(category);
+      expect(assignment.hasClass('euiComboBox-isDisabled')).toEqual(false);
+    });
+  });
+
+  it('handle special tokens, multi-fields keys and non-trimmed whitespaces', () => {
+    const dataInput: ColorMappingInputData = {
+      type: 'categories',
+      categories: ['__other__', ['fieldA', 'fieldB'], '__empty__', '   with-whitespaces   '],
+    };
+    const onModelUpdateFn = jest.fn();
+    const component = mount(
+      <CategoricalColorMapping
+        data={dataInput}
+        isDarkMode={false}
+        model={{ ...DEFAULT_COLOR_MAPPING_CONFIG }}
+        palettes={AVAILABLE_PALETTES}
+        onModelUpdate={onModelUpdateFn}
+        specialTokens={
+          new Map([
+            ['__other__', 'Other'],
+            ['__empty__', '(Empty)'],
+          ])
+        }
+      />
+    );
+    expect(component.find(ASSIGNMENTS_LIST).hostNodes().children().length).toEqual(
+      dataInput.categories.length
+    );
+    const assignment1 = component.find(ASSIGNMENT_ITEM(0)).hostNodes();
+    expect(assignment1.text()).toEqual('Other');
+
+    const assignment2 = component.find(ASSIGNMENT_ITEM(1)).hostNodes();
+    expect(assignment2.text()).toEqual(`fieldA${MULTI_FIELD_KEY_SEPARATOR}fieldB`);
+
+    const assignment3 = component.find(ASSIGNMENT_ITEM(2)).hostNodes();
+    expect(assignment3.text()).toEqual('(Empty)');
+
+    const assignment4 = component.find(ASSIGNMENT_ITEM(3)).hostNodes();
+    expect(assignment4.text()).toEqual('   with-whitespaces   ');
+  });
+});

packages/kbn-coloring/src/shared_components/color_mapping/categorical_color_mapping.tsx

@@ -0,0 +1,97 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import React from 'react';
+import { Provider } from 'react-redux';
+import { type EnhancedStore, configureStore } from '@reduxjs/toolkit';
+import { isEqual } from 'lodash';
+import { colorMappingReducer, updateModel } from './state/color_mapping';
+import { Container } from './components/container/container';
+import { ColorMapping } from './config';
+import { uiReducer } from './state/ui';
+
+/**
+ * A configuration object that is required to populate correctly the visible categories
+ * or the ranges in the CategoricalColorMapping component
+ */
+export type ColorMappingInputData =
+  | {
+      type: 'categories';
+      /** an ORDERED array of categories rendered in the visualization  */
+      categories: Array<string | string[]>;
+    }
+  | {
+      type: 'ranges';
+      min: number;
+      max: number;
+      bins: number;
+    };
+
+/**
+ * The props of the CategoricalColorMapping component
+ */
+export interface ColorMappingProps {
+  /** The initial color mapping model, usually coming from a the visualization saved object */
+  model: ColorMapping.Config;
+  /** A map of paletteId and palette configuration */
+  palettes: Map<string, ColorMapping.CategoricalPalette>;
+  /** A data description of what needs to be colored */
+  data: ColorMappingInputData;
+  /** Theme dark mode */
+  isDarkMode: boolean;
+  /** A map between original and formatted tokens used to handle special cases, like the Other bucket and the empty bucket */
+  specialTokens: Map<string, string>;
+  /** A function called at every change in the model */
+  onModelUpdate: (model: ColorMapping.Config) => void;
+}
+
+/**
+ * The React component for mapping categorical values to colors
+ */
+export class CategoricalColorMapping extends React.Component<ColorMappingProps> {
+  store: EnhancedStore<{ colorMapping: ColorMapping.Config }>;
+  unsubscribe: () => void;
+  constructor(props: ColorMappingProps) {
+    super(props);
+    // configure the store at mount time
+    this.store = configureStore({
+      preloadedState: {
+        colorMapping: props.model,
+      },
+      reducer: {
+        colorMapping: colorMappingReducer,
+        ui: uiReducer,
+      },
+    });
+    // subscribe to store changes to update external tools
+    this.unsubscribe = this.store.subscribe(() => {
+      this.props.onModelUpdate(this.store.getState().colorMapping);
+    });
+  }
+  componentWillUnmount() {
+    this.unsubscribe();
+  }
+  componentDidUpdate(prevProps: Readonly<ColorMappingProps>) {
+    if (!isEqual(prevProps.model, this.props.model)) {
+      this.store.dispatch(updateModel(this.props.model));
+    }
+  }
+  render() {
+    const { palettes, data, isDarkMode, specialTokens } = this.props;
+    return (
+      <Provider store={this.store}>
+        <Container
+          palettes={palettes}
+          data={data}
+          isDarkMode={isDarkMode}
+          specialTokens={specialTokens}
+        />
+      </Provider>
+    );
+  }
+}