feat: add minInterval option for custom xDomain

[emmacunningham]

Summary

This PR introduces a feature to allow the user to specify a custom domain minInterval. This is needed for the Discover chart replacement because currently when we auto compute the minInterval, if a series only contains two data points, the computed minInterval may be larger than what we expect. For example, see the following from Discover (top is elastic-charts implementation, bottom is current Kibana implementation):

This happens because the two data points have a difference larger than the desired minInterval, thus we need a way to be able to specify a custom minInterval for the xDomain. Doing so, produces the following:

Users can now specify a minInterval on a DomainRange which will be used to set the minInterval on the xDomain. The possible combinations of props are:

• min, max, minInterval
• min, minInterval (no max)
• max, minInterval (no min)
• minInterval (no domainRange)

So it is still not valid for the user to define an empty object for the domainRange.

I've added a sample payload from Kibana Discover so you can locally test this without running Kibana. Notice that without setting the minInterval, the bars equally split the available width; when we specify a custom minInterval, then the bars are able to display for the small interval provided.

N.B.: There's a separate issue with the axis ticks that I've observed even when using the computed minInterval which you can see in the storybook example above; am addressing this in a separate PR.

Checklist

Use strikethroughs to remove checklist items you don't feel are applicable to this PR.

• Any consumer-facing exports were added to src/index.ts (and stories only import from ../src except for test data & storybook)
• This was checked for cross-browser compatibility, including a check against IE11
• 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 #240 into master will increase coverage by <.01%.
The diff coverage is 100%.

@@            Coverage Diff             @@
##           master     #240      +/-   ##
==========================================
+ Coverage   97.75%   97.76%   +<.01%     
==========================================
  Files          36       36              
  Lines        2626     2635       +9     
  Branches      587      592       +5     
==========================================
+ Hits         2567     2576       +9     
  Misses         52       52              
  Partials        7        7

Impacted Files	Coverage Δ
src/lib/series/specs.ts	100% <ø> (ø)	⬆️
src/lib/series/domains/x_domain.ts	100% <100%> (ø)	⬆️

---

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 ff7340a...ad51d74. Read the comment docs.

[markov00]

I've added few comments, we can have a discussion on that

[markov00]

can you please add the jsdocs to documents the meaning of minInterval? It's important to stress that this should be the minimum interval available between data. If for example we are visualizing yearly data from 2016 to 2019 and we the consumer compute the first interval an error will occur: 2016 is a leap year this the interval is greater then the minComputedInterval of 365 days.

[markov00]

For a datum with monthly aggregation they should provide 28 days as the minInterval.
It's worth also having a look at the current data_histogram intervals https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-datehistogram-aggregation.html because with time intervals there is always a distinction between calendar intervals and fixed intervals.

[markov00]

I would also suggest to check if there is a better way to specify that interval. In particular, for Time domains.
I'd like to avoid pushing the consumer to compute that minInterval in millis manually and rather accept also some data_histogram intervals values like 1D or 1M or similar. This facilitate the use of the library and enables the consumer to just specify a simple interval.
Keep also an eye on this deprecation: elastic/kibana#27410

[emmacunningham]

@markov00

See comment explaining minInterval with warnings about certain kinds of timeseries intervals here: 9de618a

It would certainly be possible to extend the type of minInterval to accept either a raw number which would match the same units as the raw datum or a shorthand for intervals specific to a certain unit that we internally use to compute the actual minInterval of a domain. We could do something like:

interface DomainMinInterval {
  minInterval?: number | TimeInterval;
}

And then TimeInterval could be defined either as just a string that we parse ourselves or an interface with explicit unit: string and length: number where valid units are restricted to a certain set of strings.

However, this seems to potentially duplicate efforts because on the Kibana side, we are already using @elastic/datemath and parseInterval (note that parseInterval is not a part of @elastic/datemath and is instead a function defined within Kibana) to transform the returned interval from Elasticsearch (a separate issue is that it seems the Discover query still uses the deprecated interval field instead of calendar_interval or fixed_interval). That is, in the Discover data, we get back chartData.ordered.interval which is a moment duration which requires no additional parsing or transformation and is passed directly in as the value of minInterval:

    // Note: this is using the deprecated `interval` field; see above
    const xInterval = chartData.ordered.interval; 

    const xDomain = {
      domainRange: {
        min: domainMin,
        max: domainMax,
      },
      minInterval: xInterval,
    };

So for developer users of elastic-charts in Kibana, they should already have the ability to directly pass in correctly formatted custom minInterval values given the tools that exist within Kibana.

If we want to support more custom time interval shorthands within elastic-charts itself, that seems to me to be an additional enhancement to consider outside of this PR (the functionality exposed by this PR is needed for the Discover replacement, which does not need support for interval shorthands; and any other app within Kibana should be able to use the parseInterval helper to get the milliseconds value) because we may want to consider how to avoid duplication of efforts between our own internal parser and Kibana's. (One small difference that may be an issue is that Kibana is using moment while elastic-charts using luxon which uses slightly different strings to define patterns.)

[markov00]

Thanks @emmacunningham for the clarification. Yes let's keep it like it is for the moment

[markov00]

Code LGTM!

[markov00]

🎉 This PR is included in version 6.2.0 🎉

The release is available on:

• GitHub release
• npm package (@latest dist-tag)

Your semantic-release bot 📦🚀