feat(tooltip): composable tooltips - phase 1

[nickofthyme]

Summary

Redesigns tooltip styles and adds composable tooltip components for users to develop custom tooltip configurations. Adds the option for header and tooltip on the default tooltip that provides the tooltip items for contextual headers and footers.

BREAKING CHANGES: Settings.tooltip is deprecated in favor of the new Tooltip spec. Type changes related to TooltipProps, TooltipSettings and others see #1725. Changes to tooltip styles from dark to light theme. The Annotation tooltip class .echAnnotation used to target the icon, but now refers to the tooltip itself similar to .echTooltip and now .echAnnotation__marker refers to the icon itself.

 const tooltipProps = {...};
 <Chart>
-  <Settings tooltip={tooltipProps} />
+  <Tooltip {...tooltipProps} />
 </Chart>

Details

Demo the tooltip in storybook here.

This pr decouples the existing tooltip components into exported atomic elements to make it easier to compose a tooltip as a list or table while maintaining styles. Cleans-up and simplifies tooltip logic and styles to reuse the same composable components.

New Tooltip Spec

The Settings.tooltip option is now deprecated in favor of the new Tooltip spec. All options are the same such that Settings.tooltip can be spread over the Tooltip option, such as...

 const tooltipProps = {...};
 <Chart>
-  <Settings tooltip={tooltipProps} />
+  <Tooltip {...tooltipProps} />
 </Chart>

New components

Tooltip components

• TooltipWrapper - Used as wrapper around content (i.e. .echTooltip)
• TooltipHeader
• TooltipMetricRow
• TooltipFooter

Tabular Tooltip components

• TooltipTable
• TooltipTableHeader
• TooltipTableBody
• TooltipTableFooter
• TooltipTableRow
• TooltipTableCell
• TooltipTableColorCell

Tooltip portal ref changes

These changes improve and simplify the internal ref logic related to the tooltip and portals. The main api change is that now the anchor prop on the TooltipPortal allows for passing a ref (i.e. PortalAnchorRef) being an actual dom element ref or passing an indirect ref and position (i.e. PositionedPortalAnchorRef) which will be used to create an pseudo-ref to place tooltip.

 <TooltipPortal
   scope="MainTooltip"
-  anchor={{
-    position,
-    ref: chartRef.current,
-  }}
+  anchor={
+    anchorRef ?? {
+      position,
+      appendRef: chartRef,
+    }
+  }
 />

Type changes

Added types

The PropsOrChildrenWithProps type allows for simple type to defined a union between rendering props which includes children (i.e. PropsWithChildren) or render props that exclude children (i.e. PropsWithoutChildren). This enables a flexible component that can be used in either case and split the props respective of the usage.

type TooltipTableProps = PropsOrChildrenWithProps<
  { // properties only when children is not defined
    columns: TooltipTableColumn[];
    items: TooltipValue[];
  },
  { // properties only when children is defined
    dir: string;
  },
  { // shared properties
    maxHeight?: CSSProperties['maxHeight'];
  }
>;

<TooltipTable columns={columns} items={items} />
// or
<TooltipTable dir="lrt">Some children</TooltipTable>

Note: When children is passed columns and items are not permitted, only dir and vise versa. Then maxHeight is shared and permitted for either case.

Adds TooltipTableColumn to define the columns for generating a tabular tooltip.

Changed types

• TooltipSettings - Used to unionize the string tooltip type and the TooltipProps object. This is no longer needed and is deprecated to be removed soon.
• TooltipValue - Now accepts Datum and SeriesIdentifier generics to narrow type for different chart types.
• TooltipProps - To maintain naming conventions for all spec props to be exported as <Spec>Props name. The old TooltipProps type was used to define all tooltip settings. The new TooltipProps type defines to props of the new Tooltip spec which overlaps all previous values, so should be minimal impact.
• XYChartSeriesIdentifier - Adds xAccessor string

Issues

related to #615

Checklist

• The proper chart type label has been added (e.g. :xy, :partition)
• The proper feature labels have been added (e.g. :interactions, :axis)
• The :theme label has been added and the @elastic/eui-design team has been pinged when there are Theme API changes
• All related issues have been linked (i.e. closes #123, fixes #123)
• New public API exports have been added to packages/charts/src/index.ts
• Unit tests have been added or updated to match the most common scenarios
• The proper documentation and/or storybook story has been added or updated
• The code has been checked for cross-browser compatibility (Chrome, Firefox, Safari, Edge)
• Visual changes have been tested with all available themes including dark, light, eui-dark & eui-light

[nickofthyme]

buildkite update vrt

[nickofthyme]

@markov00 I updated the things we talked about this morning, namely:

• Remove hideColor global option
• Add tooltip table column types which include color, text, number and custom.
• Improved the generic typings to pass-through all the goodness!

Additionally, I added the option for a header and/or footer on the default tooltip in . This would enable something like...

<Tooltip header={(items) => items.find(({ isHighlighted }) => isHighlighted)?.label ?? null} />

---

I still want to look at renaming some of the properties in the column types (i.e. renderCell). Will look at this tomorrow but feel free to add your ideas! 👍🏼

[nickofthyme]

buildkite update vrt

[markov00]

It looks great, I've left a few minor comments, but code-wise looks perfect.