feat: small multiples for XY charts (alpha) (#793)

The commit adds a first alpha version of the SmallMultiple chart configuration as requested in #500
Two main components are used to describe the small multiples:
- `<GroupBy />` is a generic component that allows the specification of a group by operation and sorting order. The `by` prop request a function with two arguments, the spec and the datum. It's called for each spec and for each data point available in the data array of a spec. It should return a unique value used to group the data points into multiple series.
- `<SmallMultiples />` component with two main optional props: `splitVertically` or `splitHorizontally` where you can specify the `id` of a `GroupBy` operator to render vertically (one below the other) or horizontally (one aside the other) the series defined by that group operation. A preliminary style configuration can be used to configure inner and outer padding in percentage for the vertical or horizontal charts.

close #500 

Co-authored-by: Nick Partridge <nick.ryan.partridge@gmail.com>

api/charts.api.md

@@ -773,6 +773,28 @@ export interface GroupBrushExtent {
     groupId: GroupId;
 }
 
+// @alpha (undocumented)
+export const GroupBy: React.FunctionComponent<GroupByProps>;
+
+// @alpha (undocumented)
+export type GroupByAccessor = (spec: Spec, datum: any) => string | number;
+
+// @alpha (undocumented)
+export type GroupByProps = Pick<GroupBySpec, 'id' | 'by' | 'sort'>;
+
+// Warning: (ae-forgotten-export) The symbol "Predicate" needs to be exported by the entry point index.d.ts
+//
+// @alpha (undocumented)
+export type GroupBySort = Predicate;
+
+// @alpha (undocumented)
+export interface GroupBySpec extends Spec {
+    // (undocumented)
+    by: GroupByAccessor;
+    // (undocumented)
+    sort: GroupBySort;
+}
+
 // @public (undocumented)
 export type GroupId = string;
 
@@ -935,8 +957,6 @@ export interface HeatmapSpec extends Spec {
     xAccessor: Accessor | AccessorFn;
     // (undocumented)
     xScaleType: SeriesScales['xScaleType'];
-    // Warning: (ae-forgotten-export) The symbol "Predicate" needs to be exported by the entry point index.d.ts
-    //
     // (undocumented)
     xSortPredicate: Predicate;
     // (undocumented)
@@ -1635,6 +1655,25 @@ export interface SimplePadding {
     outer: number;
 }
 
+// @alpha (undocumented)
+export const SmallMultiples: React.FunctionComponent<SmallMultiplesProps>;
+
+// @alpha (undocumented)
+export type SmallMultiplesProps = Partial<Omit<SmallMultiplesSpec, 'id' | 'chatType' | 'specType'>>;
+
+// @alpha (undocumented)
+export interface SmallMultiplesSpec extends Spec {
+    // (undocumented)
+    splitHorizontally?: string;
+    // (undocumented)
+    splitVertically?: string;
+    // (undocumented)
+    style?: {
+        verticalPanelPadding?: [number, number];
+        horizontalPanelPadding?: [number, number];
+    };
+}
+
 // Warning: (ae-missing-release-tag) "Spec" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public (undocumented)
@@ -1655,6 +1694,8 @@ export const SpecTypes: Readonly<{
     Axis: "axis";
     Annotation: "annotation";
     Settings: "settings";
+    IndexOrder: "index_order";
+    SmallMultiples: "small_multiples";
 }>;
 
 // @public (undocumented)
@@ -1871,6 +1912,10 @@ export interface XYChartSeriesIdentifier extends SeriesIdentifier {
     // (undocumented)
     seriesKeys: (string | number)[];
     // (undocumented)
+    smHorizontalAccessorValue?: string | number;
+    // (undocumented)
+    smVerticalAccessorValue?: string | number;
+    // (undocumented)
     splitAccessors: Map<string | number, string | number>;
     // (undocumented)
     yAccessor: string | number;

src/chart_types/xy_chart/annotations/line/dimensions.integration.test.ts

@@ -17,6 +17,7 @@
  * under the License.
  */
 
+import { MockAnnotationLineProps } from '../../../../mocks/annotations/annotations';
 import { MockSeriesSpec, MockAnnotationSpec, MockGlobalSpec } from '../../../../mocks/specs';
 import { MockStore } from '../../../../mocks/store';
 import { ScaleType } from '../../../../scales/constants';
@@ -51,14 +52,15 @@ function expectAnnotationAtPosition(
   MockStore.addSpecs([settings, ...specs, annotation], store);
   const annotations = computeAnnotationDimensionsSelector(store.getState());
   expect(annotations.get(annotation.id)).toEqual([
-    {
+    MockAnnotationLineProps.default({
       details: { detailsText: undefined, headerText: `${indexPosition}` },
       linePathPoints: {
-        start: { x1: expectedLinePosition, y1: 0 },
-        end: { x2: expectedLinePosition, y2: 100 },
+        x1: expectedLinePosition,
+        y1: 0,
+        x2: expectedLinePosition,
+        y2: 100,
       },
-      marker: undefined,
-    },
+    }),
   ]);
 }
 
@@ -144,14 +146,15 @@ describe('Render vertical line annotation within', () => {
     MockStore.addSpecs([settings, spec, annotation], store);
     const annotations = computeAnnotationDimensionsSelector(store.getState());
     expect(annotations.get(annotation.id)).toEqual([
-      {
+      MockAnnotationLineProps.default({
         linePathPoints: {
-          start: { x1: 95, y1: 0 },
-          end: { x2: 95, y2: 100 },
+          x1: 95,
+          y1: 0,
+          x2: 95,
+          y2: 100,
         },
         details: { detailsText: 'foo', headerText: '9.5' },
-        marker: undefined,
-      },
+      }),
     ]);
   });
 });