feat: add series name settings

[nickofthyme]

Summary

Related to #537 (interim fix)

BREAKING CHANGE:
Remove customSubSeriesName prop on series specs in favor of cleaner api using just the name prop on SeriesSpec. The types SeriesStringPredicate, SubSeriesStringPredicate have been removed.

The name prop is defined below...

type SeriesNameAccessor = string | SeriesNameFn | SeriesNameConfigOptions;
// where

export interface SeriesSpec extends Spec {
  ...
  /**
   * The name of the spec. Also a mechanism to provide custom series names.
   */
  name?: SeriesNameAccessor;
  ...
}

This original function type definition is the same

type SeriesName = string | number | null;
type SeriesNameFn = (series: SeriesIdentifier, isTooltip: boolean) => SeriesName;

However the SeriesStringPredicate is now a union type between SeriesNameFn and the new getSeriesNameFromOptions type defined below.

export interface SeriesNameConfig {
  /**
   * accessor key (i.e. `yAccessors` and `seriesSplitAccessors`)
   */
  accessor: string | number;
  /**
   * Accessor value (i.e. values from `seriesSplitAccessors`)
   */
  value?: string | number;
  /**
   * New name for Accessor value
   *
   * If not provided, the original value will be used
   */
  name?: string | number;
  /**
   * Sort order of label, overrides order listed in array.
   *
   * lower values - front most
   * higher values - end most
   */
  sortIndex?: number;
}
export interface SeriesNameConfigOptions {
  /**
   * Array of accessor naming configs to replace series names
   *
   * Only provided configs will be included
   * (i.e. if you only provide a single mapping for `yAccessor`, all other series accessor labels will be ignored)
   *
   * The order of configs is the order in which the resulting labels will
   * be joined, if no `sortIndex` is specified.
   *
   * If no values are found for a giving mapping in a series, the mapping will be ignored.
   */
  names?: SeriesNameConfig[];
  /**
   * Delimiter to join values/labels
   *
   * @default ' - '
   */
  delimiter?: string;
}

Note: The order of the names array is used to join the names

Mappings Examples

const data = [
  {
    x: 0,
    y1: 'speed',
    y2: 'acceleration',
    g: 'ferrari',
  },
  {
    x: 1,
    y1: 'speed',
    y2: 'acceleration',
    g: 'porsche',
  },
]

Replace yAccessors

<LineSeries
  data={data}
  xAccessor="x"
  yAccessors={['speed', 'acceleration']}
  splitSeriesAccessors={['g']}
  customSubSeriesName={{
    names: [
      {
        accessor: 'g',
        value: 'ferrari',
      },
      {
        accessor: 'g',
        value: 'porsche',
      },
      {
        accessor: 'speed',
        name: 'm/s',
      },
      {
        value: 'acceleration',
        name: 'm/s/s',
      },
    ],
  }}
/>

Default names	Custom mapped Names
ferrari - speed	ferrari - m/s
ferrari - acceleration	ferrari - m/s/s
porsche - speed	porsche - m/s
porsche - acceleration	porsche - m/s/s

Replace splitAccessors and reorder with delimiter

<LineSeries
  data={data}
  xAccessor="x"
  yAccessors={['speed', 'acceleration']}
  splitSeriesAccessors={['g']}
  customSubSeriesName={{
    names: [
      {
        accessor: 'speed',
      },
      {
        accessor: 'acceleration',
      },
      {
        accessor: 'g',
        value: 'ferrari',
        name: 'Ferrari',
      },
      {
        accessor: 'g',
        value: 'porsche',
        name: 'Porsche',
      },
    ],
    delimiter: ' : ',
  }}
/>

Default names	Custom mapped Names
ferrari - speed	speed : Ferrari
ferrari - acceleration	acceleration : Ferrari
porsche - speed	speed : Porsche
porsche - acceleration	acceleration : Porsche

Single series

<LineSeries
  data={data}
  xAccessor="x"
  yAccessors={['speed']}
  splitSeriesAccessors={['g']}
  customSubSeriesName={{
    names: [
      {
        accessor: 'g',
        value: 'ferrari',
        name: 'Ferrari',
      },
      {
        accessor: 'g',
        value: 'porsche',
        name: 'Porsche',
      },
      // This name be excluded from the name if not in the array
      // {
      //   accessor: 'speed',
      // },
    ],
  }}
/>

Default names	Custom mapped Names
ferrari	Ferrari
porsche	Porsche

See test cases for more examples

Checklist

• Any consumer-facing exports were added to src/index.ts (and stories only import from ../src except for test data & storybook)
• Proper documentation or storybook story was added for features that require explanation or tutorials
• Unit tests were updated or added to match the most common scenarios
• Each commit follows the convention

[codecov-io]

Codecov Report

Merging #539 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #539   +/-   ##
=======================================
  Coverage   71.83%   71.83%           
=======================================
  Files         212      212           
  Lines        6142     6142           
  Branches     1181     1181           
=======================================
  Hits         4412     4412           
  Misses       1711     1711           
  Partials       19       19

Impacted Files	Coverage Δ
src/chart_types/xy_chart/utils/series.ts	98.87% <ø> (ø)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 264980d...9a6828e. Read the comment docs.

[markov00]

Hi @nickofthyme I've few doubts on this PR because the same effect can be achieved with the available props like the following:

customSeriesLabel={(args) => {
    return args.seriesKeys.join(' ~~ ');
}}

or

customSeriesLabel={(args) => {
    return args.seriesKeys.slice(0, args.seriesKeys.length -1).join(' ~~ ');
}}

Users are always a bit reluctant to use Maps object (I remember most of them commenting on a simplified version) that could be in fact achieved with a simple object {a: 'apple'}

One other way we could think about this feature: what if we provide a set of utility function for this cases?
like:

function fullSeries(delimiter: string = ' - ') {
  return (args) => {
      return args.seriesKeys.join(delimiter);
  }
}

function simpleSeries(delimiter: string = ' - ') {
  return (args) => {
      return args.seriesKeys.slice(0, args.seriesKeys.length -1).join(delimiter);
  }
}

this will allow much more configurability and doesn't pollute the, already polluted, set of props we have in the chart components.

What do you think?

[markov00]

Thanks Nick for that, seems everything fine except few small typos.
I've added few nit commits that can be ignored but i think it's useful if the discuss them

[markov00]

Everything looks good, I've left few minor comments and one major related to the accessor type that should be resolved

[markov00]

Everything LGTM, I've left few small comments

[markov00]

jenkins test this