feat: expose Specs types as part of the API

close #547

.playground/playground.tsx

@@ -8,6 +8,8 @@ import {
   LineAnnotation,
   RectAnnotation,
   AnnotationDomainTypes,
+  LineAnnotationDatum,
+  RectAnnotationDatum,
 } from '../src';
 import { SeededDataGenerator } from '../src/mocks/utils';
 
@@ -18,6 +20,8 @@ export class Playground extends React.Component<{}, { isSunburstShown: boolean }
       ...item,
       y1: item.y + 100,
     }));
+    const lineDatum: LineAnnotationDatum[] = [{ dataValue: 321321 }];
+    const rectDatum: RectAnnotationDatum[] = [{ coordinates: { x1: 100 } }];
 
     return (
       <>
@@ -43,8 +47,8 @@ export class Playground extends React.Component<{}, { isSunburstShown: boolean }
               splitSeriesAccessors={['g']}
               data={data}
             />
-            <LineAnnotation id="sss" dataValues={[{ dataValue: 321321 }]} domainType={AnnotationDomainTypes.XDomain} />
-            <RectAnnotation id="111" dataValues={[{ coordinates: { x1: 100 } }]} />
+            <LineAnnotation id="sss" dataValues={lineDatum} domainType={AnnotationDomainTypes.XDomain} />
+            <RectAnnotation id="111" dataValues={rectDatum} />
           </Chart>
         </div>
       </>

docs/1-Typesofchart/5-AnnotatingBars.mdx

@@ -13,11 +13,11 @@ import {
   ScaleType,
   Settings,
   timeFormatter,
+  Position,
 } from '../../src';
 import { Icon } from '../../src/components/icons/icon';
 import { KIBANA_METRICS } from '../../src/utils/data_samples/test_dataset_kibana';
 import { BandedAccessorType } from '../../src/utils/geometry';
-import { Position } from '../../src/chart_types/xy_chart/utils/specs';
 import { getChartRotationKnob, generateAnnotationData, arrayKnobs } from '../../docs/charts'
 
 <Meta title="Types of charts/Bar Charts/Annotating Bar Charts" />

integration/tests/mixed_stories.test.ts

@@ -1,5 +1,5 @@
 import { common } from '../page_objects';
-import { Fit } from '../../src/chart_types/xy_chart/utils/specs';
+import { Fit } from '../../src';
 
 describe('Mixed series stories', () => {
   describe('Fitting functions', () => {

src/chart_types/specs.ts

@@ -8,4 +8,6 @@ export {
   HistogramBarSeries,
 } from './xy_chart/specs';
 
+export * from './xy_chart/utils/specs';
+
 export { Partition } from './partition_chart/specs';

src/chart_types/xy_chart/utils/specs.ts

@@ -534,14 +534,29 @@ export const AnnotationDomainTypes = Object.freeze({
 
 export type AnnotationDomainType = $Values<typeof AnnotationDomainTypes>;
 
+/**
+ * The descriptive object of a line annotation
+ */
 export interface LineAnnotationDatum {
+  /**
+   * The value on the x or y axis accordingly to the domainType configured
+   */
   dataValue: any;
+  /**
+   * A textual description of the annotation
+   */
   details?: string;
+  /**
+   * An header of the annotation. If undefined, than the formatted dataValue will be used
+   */
   header?: string;
 }
 
-export type LineAnnotationSpec = BaseAnnotationSpec<LineAnnotationDatum, LineAnnotationStyle> & {
-  annotationType: typeof AnnotationTypes.Line;
+export type LineAnnotationSpec = BaseAnnotationSpec<
+  typeof AnnotationTypes.Line,
+  LineAnnotationDatum,
+  LineAnnotationStyle
+> & {
   domainType: AnnotationDomainType;
   /** Custom marker */
   marker?: JSX.Element;
@@ -565,18 +580,42 @@ export type LineAnnotationSpec = BaseAnnotationSpec<LineAnnotationDatum, LineAnn
   zIndex?: number;
 };
 
+/**
+ * The descriptive object of a rectangular annotation
+ */
 export interface RectAnnotationDatum {
+  /**
+   * The coordinates for the 4 rectangle points.
+   */
   coordinates: {
+    /**
+     * The minuimum value on the x axis. If undefined, the minuimum value of the x domain will be used.
+     */
     x0?: any;
+    /**
+     * The maximum value on the x axis. If undefined, the maximum value of the x domain will be used.
+     */
     x1?: any;
+    /**
+     * The minimum value on the y axis. If undefined, the minimum value of the y domain will be used.
+     */
     y0?: any;
+    /**
+     * The maximum value on the y axis. If undefined, the maximum value of the y domain will be used.
+     */
     y1?: any;
   };
+  /**
+   * A textual description of the annotation
+   */
   details?: string;
 }
 
-export type RectAnnotationSpec = BaseAnnotationSpec<RectAnnotationDatum, RectAnnotationStyle> & {
-  annotationType: typeof AnnotationTypes.Rectangle;
+export type RectAnnotationSpec = BaseAnnotationSpec<
+  typeof AnnotationTypes.Rectangle,
+  RectAnnotationDatum,
+  RectAnnotationStyle
+> & {
   /** Custom rendering function for tooltip */
   renderTooltip?: AnnotationTooltipFormatter;
   /** z-index of the annotation relative to other elements in the chart
@@ -586,24 +625,35 @@ export type RectAnnotationSpec = BaseAnnotationSpec<RectAnnotationDatum, RectAnn
 };
 
 export interface BaseAnnotationSpec<
+  T extends typeof AnnotationTypes.Rectangle | typeof AnnotationTypes.Line,
   D extends RectAnnotationDatum | LineAnnotationDatum,
   S extends RectAnnotationStyle | LineAnnotationStyle
 > extends Spec {
   chartType: ChartTypes;
   specType: typeof SpecTypes.Annotation;
-  /** Annotation type: line, rectangle, text */
-  annotationType: AnnotationType;
-  /** The ID of the axis group, generated via getGroupId method
+  /**
+   * Annotation type: line, rectangle, text
+   */
+  annotationType: T;
+  /**
+   * The ID of the axis group, generated via getGroupId method
    * @default __global__
    */
   groupId: GroupId; // defaults to __global__; needed for yDomain position
-  /** Data values defined with coordinates and details */
+  /**
+   * Data values defined with coordinates and details
+   */
   dataValues: D[];
-  /** Custom annotation style */
+  /**
+   * Custom annotation style
+   */
   style?: Partial<S>;
-  /** Toggles tooltip annotation visibility */
+  /**
+   * Toggles tooltip annotation visibility
+   */
   hideTooltips?: boolean;
-  /** z-index of the annotation relative to other elements in the chart
+  /**
+   * z-index of the annotation relative to other elements in the chart
    * Default specified per specific annotation spec.
    */
   zIndex?: number;

src/index.ts

@@ -1,41 +1,20 @@
+// polyfill for Path2D canvas
 import 'path2d-polyfill';
-export * from './specs';
+
+export { ChartTypes } from './chart_types';
 export { Chart } from './components/chart';
 export { ChartSize, ChartSizeArray, ChartSizeObject } from './utils/chart_size';
+
+// DEPRECATED: we will remove these types soon
 export { SpecId, GroupId, AxisId, AnnotationId, getAxisId, getGroupId, getSpecId, getAnnotationId } from './utils/ids';
-export { ScaleType } from './scales';
-export * from './utils/themes/theme';
-export { LIGHT_THEME } from './utils/themes/light_theme';
-export { DARK_THEME } from './utils/themes/dark_theme';
-export * from './utils/themes/theme_commons';
-export { RecursivePartial } from './utils/commons';
+
+// Everything related to the specs types and react-components
+export * from './specs';
 export { CurveType } from './utils/curves';
 export { timeFormatter, niceTimeFormatter, niceTimeFormatByDay } from './utils/data/formatters';
-export { DataGenerator } from './utils/data_generators/data_generator';
 export { SeriesCollectionValue } from './chart_types/xy_chart/utils/series';
-export { ChartTypes } from './chart_types';
 export { Datum, Position, Rendering, Rotation } from './utils/commons';
-export { TickFormatter } from './chart_types/xy_chart/utils/specs';
 export { SeriesIdentifier, XYChartSeriesIdentifier } from './chart_types/xy_chart/utils/series';
-export {
-  AnnotationDomainType,
-  AnnotationDomainTypes,
-  SeriesColorAccessor,
-  SeriesColorsArray,
-  SeriesColorAccessorFn,
-  HistogramModeAlignment,
-  HistogramModeAlignments,
-  LineAnnotationDatum,
-  LineAnnotationSpec,
-  RectAnnotationDatum,
-  RectAnnotationSpec,
-  SeriesTypes,
-  SeriesName,
-  SeriesNameFn,
-  SeriesNameAccessor,
-  SeriesNameConfig,
-  SeriesNameConfigOptions,
-} from './chart_types/xy_chart/utils/specs';
 export { AnnotationTooltipFormatter } from './chart_types/xy_chart/annotations/annotation_utils';
 export { GeometryValue } from './utils/geometry';
 export {
@@ -46,3 +25,16 @@ export {
 export { Layer as PartitionLayer } from './chart_types/partition_chart/specs/index';
 export { AccessorFn, IndexedAccessorFn } from './utils/accessor';
 export { SpecTypes } from './specs/settings';
+
+// scales
+export { ScaleType } from './scales';
+
+// theme
+export * from './utils/themes/theme';
+export * from './utils/themes/theme_commons';
+export { LIGHT_THEME } from './utils/themes/light_theme';
+export { DARK_THEME } from './utils/themes/dark_theme';
+
+// utilities
+export { RecursivePartial } from './utils/commons';
+export { DataGenerator } from './utils/data_generators/data_generator';

src/mocks/series/series_identifiers.ts

@@ -1,4 +1,4 @@
-import { BasicSeriesSpec } from '../../chart_types/xy_chart/utils/specs';
+import { BasicSeriesSpec } from '../../';
 import {
   SeriesCollectionValue,
   getSplittedSeries,

stories/annotations/rects/3_linear_line_chart.tsx

@@ -1,6 +1,6 @@
 import { boolean, select } from '@storybook/addon-knobs';
 import React from 'react';
-import { Axis, Chart, LineSeries, RectAnnotation, ScaleType, Settings } from '../../../src';
+import { Axis, Chart, LineSeries, RectAnnotation, ScaleType, Settings, RectAnnotationDatum } from '../../../src';
 import { getChartRotationKnob } from '../../utils/knobs';
 import { BandedAccessorType } from '../../../src/utils/geometry';
 import { Position } from '../../../src/utils/commons';
@@ -20,7 +20,7 @@ export const example = () => {
     'x0',
   );
 
-  const dataValues = [
+  const dataValues: RectAnnotationDatum[] = [
     {
       coordinates: {
         x0: 1,

stories/bar/23_bar_chart_2y2g.tsx

@@ -1,8 +1,7 @@
 import React from 'react';
 
-import { Axis, BarSeries, Chart, Position, ScaleType, Settings } from '../../src';
+import { Axis, BarSeries, Chart, Position, ScaleType, Settings, FilterPredicate } from '../../src';
 import * as TestDatasets from '../../src/utils/data_samples/test_dataset';
-import { FilterPredicate } from '../../src/chart_types/xy_chart/utils/specs';
 import { SB_SOURCE_PANEL } from '../utils/storybook';
 
 export const example = () => {

stories/bar/24_tooltip_visibility.tsx

@@ -1,8 +1,7 @@
 import React from 'react';
 
-import { Axis, BarSeries, Chart, Position, ScaleType, Settings } from '../../src';
+import { Axis, BarSeries, Chart, Position, ScaleType, Settings, FilterPredicate } from '../../src';
 import * as TestDatasets from '../../src/utils/data_samples/test_dataset';
-import { FilterPredicate } from '../../src/chart_types/xy_chart/utils/specs';
 import { SB_SOURCE_PANEL } from '../utils/storybook';
 
 export const example = () => {

stories/mixed/6_fitting.tsx

@@ -1,8 +1,19 @@
 import { select, number } from '@storybook/addon-knobs';
 import React from 'react';
 
-import { AreaSeries, Axis, Chart, CurveType, LineSeries, Position, ScaleType, Settings } from '../../src/';
-import { Fit, SeriesTypes } from '../../src/chart_types/xy_chart/utils/specs';
+import {
+  AreaSeries,
+  Axis,
+  Chart,
+  CurveType,
+  LineSeries,
+  Position,
+  ScaleType,
+  Settings,
+  Fit,
+  SeriesTypes,
+} from '../../src/';
+
 import { SB_KNOBS_PANEL } from '../utils/storybook';
 
 export const example = () => {

stories/stylings/13_custom_series_name.tsx

@@ -1,8 +1,7 @@
 import React from 'react';
 
-import { Axis, BarSeries, Chart, Position, ScaleType, Settings } from '../../src';
+import { Axis, BarSeries, Chart, Position, ScaleType, Settings, SeriesNameFn } from '../../src';
 import * as TestDatasets from '../../src/utils/data_samples/test_dataset';
-import { SeriesNameFn } from '../../src/chart_types/xy_chart/utils/specs';
 import { SB_SOURCE_PANEL } from '../utils/storybook';
 
 export const example = () => {

stories/stylings/13_custom_series_name_config.tsx

@@ -1,8 +1,7 @@
 import React from 'react';
 
-import { Axis, BarSeries, Chart, Position, ScaleType, Settings } from '../../src';
+import { Axis, BarSeries, Chart, Position, ScaleType, Settings, SeriesNameConfigOptions } from '../../src';
 import * as TestDatasets from '../../src/utils/data_samples/test_dataset';
-import { SeriesNameConfigOptions } from '../../src/chart_types/xy_chart/utils/specs';
 import { SB_SOURCE_PANEL } from '../utils/storybook';
 
 export const example = () => {

stories/stylings/14_custom_series_name_formatting.tsx

@@ -1,7 +1,6 @@
 import React from 'react';
 
-import { Axis, BarSeries, Chart, Position, ScaleType, Settings } from '../../src';
-import { SeriesNameFn } from '../../src/chart_types/xy_chart/utils/specs';
+import { Axis, BarSeries, Chart, Position, ScaleType, Settings, SeriesNameFn } from '../../src';
 import moment from 'moment';
 import { DateTime } from 'luxon';
 import { SB_SOURCE_PANEL } from '../utils/storybook';

stories/stylings/16_style_accessor.tsx

@@ -13,8 +13,9 @@ import {
   RecursivePartial,
   BarSeriesStyle,
   PointStyle,
+  BarStyleAccessor,
+  PointStyleAccessor,
 } from '../../src';
-import { BarStyleAccessor, PointStyleAccessor } from '../../src/chart_types/xy_chart/utils/specs';
 
 export const example = () => {
   const hasThreshold = boolean('threshold', true);