AnnotationsChart
The AnnotationsChart is a visualization tool designed to highlight significant
events or data points on a timeline or other graph types. It allows the user to
annotate specific moments with labels or markers, providing additional context
or insights directly within the chart. This chart can be used standalone or
integrated with other chart types, such HistogramChart or TimeseriesChart,
to enrich the data presentation by drawing attention to each event.
Import
import { AnnotationsChart } from '@dynatrace/strato-components-preview/charts';
Use cases
Size
By default, the chart will use all the available container size up to the
maximum height required to show all the tracks. This maximum height can be
changed by providing a value in the height prop of the AnnotationsChart. You
can set any css value to the height and if a number is passed to this prop
without any unit specified, it will be treated as px.
AnnotationsChart.Track
Tracks in the AnnotationsChart are horizontal bands that group related markers.
Each track can have a label, which is displayed on the left side, and can
represent a specific category of data.
Label width for tracks can be set by labelWidth property in AnnotationsChart
component
The track is able to provide prop values for the markers inside of it, like
color and symbol, which will be used as default values in case they are not
provided on the marker level.
AnnotationsChart.Marker
Markers are the individual data points or events within a track, which can
represent a single value or a range. Each marker can have a title, symbol,
and description to provide more context.
When the symbol is provided, it will be shown as marker content. As a
fallback, if no symbol is provided, the title will be chosen as content.
In the case no symbol or title are provided, no content will be shown.
Text Overflow
To deal with text longer than the width of the marker containing it, an option between 'expand' and 'truncate' could be chosen. When 'expand' is selected the width of the marker will try to expand to fit all the content within, only applying an ellipsis when the width in the track is not enough to fit all the content. When 'truncate' is selected the width of the marker will be respected and the content will be cropped to fit it. User can specify if this truncation should be made at the 'start', 'middle' or 'end' of the text with the option 'truncateMode'.
AnnotationsChart.Tooltip
It's possible to customize the tooltip by providing a custom HTML template.
To define the template, use a callback handler that receives the relevant marker data. This data includes both the current hovered marker and any overlapping markers that are close by, allowing the creation of a detailed and informative tooltip.
If no tooltip template is provided, then the default tooltip will be shown
instead. Optionally, tooltip can be opted out by setting hidden prop to true.
User actions
A user action is a creator-defined interaction with a given node in the hive.
Basic interactions include copying the node name and inspecting the underlying
data of it. In order to enable user actions, the ChartSeriesAction
subcomponent needs to be appended within the AnnotationsChart. More
subcomponents can be added within this component, for instance the
ChartSeriesAction.Item, where custom logic can be applied.
Chart states
Error state
The ErrorState subcomponent is responsible for handling errors in a graceful
manner, ultimately improving the overall user experience. Its primary function
is to catch any errors that may occur with the data and display a fallback UI
instead of crashing the entire application.
In case of an error thrown inside the chart, a predefined error message will be shown.
If you prefer to create your own error screen to preserve styles and information shown, you can create your own error state presenter.
EmptyState
The EmptyState subcomponent serves as a fallback when there is no data
available to display in a chart. Its purpose is to provide a user-friendly way
of informing the user about the current situation.
When no data is provided to the chart, a predefined empty state message will be displayed.
An empty state message can be customized using AnnotationsChart.ErrorState
subcomponent.
Loading
The AnnotationsChart is able to show the default loading indicator by setting
the loading prop to true.
X-axis
The AnnotationsChart component provides a AnnotationsChart.XAxis
subcomponent to configure chart's X-Axis and scale. The X-Axis is visible by
default. To hide it the hidden prop should be set to true.
To customize chart's min and max scale values, the min and max props can be
used. By default, chart's scale min and max are calculated from the data. Be
aware, that customizing the scale values may filter out some markers that are
outside of custom scale range.
Numerical x-axis
The numerical x-axis has additional configuration options, like scale,
formatter and unit.
The scale option can be used to choose between linear and logarithmic scale.
Take into account that the logarithmic scale just supports positive numbers
(excluding 0), so if negative or zero values are provided, the scale will fall
back to linear.
The formatter or unit props can be used to customise the formatting of the
x-axis ticks and the tooltip numerical data. If both properties are present, the
formatter will take precedence over unit.
Numbers to time conversion
The scale prop offers an additional option that allows for the conversion of
timestamps to dates. By setting the scale to time, all numeric data used in the
markers will be parsed as dates. Consequently, the min and max props of the
axis can accept both number and date types.
In case some invalid number that can't be converted to date is provided, it will be filtered out of the original dataset.
Multiple chart configuration
Given certain situations it can be helpful to share a common chart configuration
across several AnnotationsChart instances. To avoid repeating the same
configuration in all instances, the AnnotationsChartConfig provider can be
used. It accepts an object where the keys are either props of the
AnnotationsChart component, or the corresponding object representation of each
one of the AnnotationsChart subcomponents props. (AnnotationsChart.XAxis and
AnnotationsChart.Tooltip).
A specific configuration of a AnnotationsChart instance will take precedence
over the one specified in the AnnotationsChartConfig.