Reference lines and reference areas

hughess commented 1 year ago

Description

This PR adds reference lines and areas to charts.

For now, these are separate components: ReferenceLine and ReferenceArea, which are used by inserting them into a slot within a chart. For example:

<LineChart
   data={sales_data}
   x=date
   y=sales
>
   <ReferenceLine yVal=120 label="Target"/>
</LineChart>

These can be applied by hardcoding values (e.g., if you want a horizontal line at y=50) or with a dataset (e.g., you have a table of events or time ranges you want to include in a chart to add context to the viz).

Reference Line

Props

Required:

x or y

Optional:

data
label
color
lineType
lineColor
labelColor
lineWidth
showValueInLabel
labelTextOutline
labelBackground

<LineChart 
    data={daily_complaints} 
    x=date 
    y=number_of_complaints 
    title="Complaint Calls to Austin 311"
>
    <ReferenceLine yVal=2500 label=Threshold/>
</LineChart>

Reference Area

Props

Required:

At least one of x1, x2, y1, y2

Optional:

data
label
color
opacity
labelColor
border
borderColor
borderType
borderWidth
labelPosition

<LineChart 
    data={daily_complaints} 
    x=date 
    y=number_of_complaints 
    title="Complaint Calls to Austin 311"
>
    <ReferenceArea data={annotate} xMin=start_date xMax=end_date label=label/>
</LineChart>

Use Cases

This opens up some pretty exciting use cases for adding relevant context to data viz.

To Do

~~Add lineType prop to reference line (dashed, solid, etc)~~
~~Formatted label numbers~~
~~How to treat label when no label is supplied (show value or nothing?)~~
~~Fix gridline z level - histogram issue~~
~~Fix tooltip hover issue by setting markLine and markArea to silent~~
~~Work in composable charts?~~
~~Open slots on all XY chart types~~
~~Naming - highlight area?~~
~~Switch yVal to y?~~
~~Switch yMin to y0 or y1?~~
~~Default label positions (swapXY, chart types, etc.)~~
~~Error handling~~
~~Styling for labels - add white outline to text? Inherit colour of area background for that outline?~~
~~Add docs~~
~~Add note to docs for gridline overlap issue with reference area label~~
~~Add note to docs about continuous axis bar charts - reference area doesn't cover bar by default~~

Deferred for future upgrades

Reference area should cover full bar width area rather than stopping at midpoint of bar. This is fixed in Echarts v5.4.2, so an upgrade of that dependency will be required. Unclear if this will require the mark series to be bar rather than line as it is now
- This fix works only for categorical axes
Shorthand for using in normal chart props
Colours - offer presets or a default opacity level?
- It would be nice to be able to use color=red in ReferenceArea and have it produce a faded red/pink background with a darker red label
Label word breaking/overflow behaviour
Control over value formatting in label
Legend options for reference area

Issues to be solved

Label rotation for vertical reference lines (see echarts issue here: https://github.com/apache/echarts/issues/13153)
For reference areas, label z level should be different than area z level
- Area should be behind gridlines, but label should be in front of them
- Open echarts issues for this here:
  - https://github.com/apache/echarts/issues/18597
  - https://github.com/apache/echarts/issues/18608

Error Handling

Implemented using the ErrorChart component.

Covers these scenarios:

Checklist

[x] For UI or styling changes, I have added a screenshot or gif showing before & after
[x] I have added a changeset

changeset-bot[bot] commented 1 year ago

🦋 Changeset detected

Latest commit: d6a8405f64d6f8a786218df4d0f1cdf51f0f596c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

| Name | Type | | ------------------------- | ----- | | @evidence-dev/preprocess | Minor | | @evidence-dev/components | Minor | | @evidence-dev/evidence | Major | | evidence-test-environment | Patch |

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel[bot] commented 1 year ago

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
evidence-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	May 18, 2023 5:17pm

netlify[bot] commented 1 year ago

Deploy Preview for evidence-development-workspace ready!

Name	Link
Latest commit	d6a8405f64d6f8a786218df4d0f1cdf51f0f596c
Latest deploy log	https://app.netlify.com/sites/evidence-development-workspace/deploys/64665d88f17eef000800c1b8
Deploy Preview	https://deploy-preview-858--evidence-development-workspace.netlify.app
Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

hughess commented 1 year ago

The last outstanding issue that may need to be tackled before merging is the default styling of labels. The basic labels look fine, but when a label is overtop of lines/bars/etc it doesn't look right.

Options are adding a white outline on the text or adding a background colour to the label (either full opacity or with some transparency).

Given the number of permutations here, it might be worth merging with a small white text outline as a starting point, and spending time to solve this in a more general sense once we have a bit of user feedback.

hughess commented 1 year ago

Update: I've added a white text outline by default on reference line labels, but have also included a prop for labelBackground which if set to true, will include a white semi-transparent background behind the label

hughess commented 1 year ago

Thanks @archiewood.

What were you trying to achieve with reference line?
- I recently added in labelPosition for reference line, so that might help some of the issues there
Agree on the prop names. Think I'll switch back to yMin and yMax for ref area
Preset colours are now included to override the CSS colour names. It includes:
- red
- green
- yellow
- blue
- grey
I've set the default area label position to top left, but mostly because of the x-axis case (e.g., date range). I agree if it's y-based, it should probably be right centre
Good idea on hideValue
Agreed on shorthand within the component. I think better to tackle that in the next version - there might be a way to get reference area into that strategy as well
Line might need to be thicker - especially when there's a lot of data on a chart
- Unrelated, but I'm also wondering if our bars are too spaced out on the bar chart - looks visually overwhelming. Might also just be the high contrast between the blue and the white background

I think I want more precisions on target line label than the axis. Should I be able to configure this?

What do you mean by precisions?

archiewood commented 1 year ago

I was trying to achieve two lines where the labels didn't overlap

By more precision (typo), here I meant I wanted the format to show $3,800 not $4k.

hughess commented 1 year ago

Ahh that's a great point. Do you think a good solution to that might be a format override prop like valueFmt or similar?

archiewood commented 1 year ago

Yes I think so. Or accept the format function as I tried and failed to do

hughess commented 1 year ago

I've added value format control to the list of future improvements.

Just pushed some simplification to the props and label positions

hughess commented 1 year ago

Ran into 2 last issues on this:

Text Borders

Using a text border on the labels causes an issue with rendering in Safari. This is an echarts bug - I've opened an issue here: https://github.com/apache/echarts/issues/18609

For now, leaving any text borders out, in favour of a faded white background

Bar Charts with Numeric or Date x-axis

Using a reference area on a bar chart where the x-axis is numeric or date, the are will only go to the specific point on the x-axis and will not cover the entire bar:

This is because the area is lined up to the exact point on the axis.

There are 2 possible workarounds:

1. Add extra padding to the dates to be used to create the area.

For example, this chart is set with xMin='2020-12-15' and xMax='2021-07-15'

2. Change x-axis type to category

This is not ideal, as it then removes automatic formatting of the x-axis labels. I would say this is not a viable workaround

Other Alternatives

There are a couple of ways to work around this on our side by extracting and adjusting the coordinates from echarts. These may be worth doing if the above workaround isn't intuitive.

archiewood commented 1 year ago

@hughess as discussed I think we should probably leave the behaviour as is for numeric axes highlighting.

It's kind of a difficult problem as barcharts are sort of a discrete chart type, but are often used in a continuous setting (eg dates, numeric ranges).

Given the workarounds exist (workaround 1 in particular), I think until we are clear on what users need here, leaving as is makes sense

hughess commented 1 year ago

There are only 2 things blocking this PR from merging:

Format test failing, but this is only for markdown pages - @ItsMeBrianD wanted to double check that this is okay
Docs - since this includes docs changes, assume we should wait until we're close to release?

archiewood commented 1 year ago

Removed formatting checks for markdown files in the example project +page.md files.

evidence-dev / evidence