@visa/charts-types
v0.6.5
Published
Types for charts lib
Downloads
151
Readme
Types
A collection of common prop types used across the VCC ecosystem.
Charts that leverage these types:
- @visa/bar-chart
- @visa/clustered-bar-chart
- @visa/stacked-bar-chart
- @visa/line-chart
- @visa/pie-chart
- @visa/scatter-plot
- @visa/heat-map
- @visa/circle-packing
- @visa/parallel-plot
- @visa/dumbbell-plot
- @visa/world-map
Default Values
Default values for all of these types can be found the propDefaultValues file in our utils but are also outlined in the tables below.
API Contents
# Accessibility <>
# IAccessibilityType
Used by every chart. Specifies a robust set of settings that make VCC data experiences more accessible.
Description props are used to explain the chart to a user who cannot see it and should be carefully considered early in the design process. In addition, it is always best to provide explanations of the chart's context, purpose, summaries, statistics in visual, textual form for people with cognitive impairment/disability. In cases where this information is provided outside of the chart, it does not need to be provided to these props.
Note that some of these props are required by chart accessibility validation and will throw warnings until the default values are changed (such as elementsAreInterface). The prop for disableValidation should be set to true before an application's production build and deployment process but only if the chart is considered accessible (validation can slow down the chart's lifecycle performance significantly).
| Name (accessibility.) | Type | Default Value(s) | Description |
| ---------------------------- | ---------------------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| longDescription | string | '' | Use this to add a helpful description of the chart. |
| executiveSummary | string | '' | Use this to describe the biggest takeaway of the chart. |
| purpose | string | '' | Use this to describe the purpose of this particular chart. |
| contextExplanation | string | '' | Use this to explain any controls or content on your page that affect or are affected by this chart. |
| title | string | '' | Gives the chart an alternate title to be used by screen readers. |
| elementDescriptionAccessor | string | '' | Optional key used to add an additional description to any element, from your data. |
| statisticalNotes | string | '' | Use this to provide any statistical explanations, such as trends, clusters, patterns, or outliers. |
| structureNotes | string | '' | Use this to describe special visual features of the chart, such as sorting, color grouping, etc. |
| includeDataKeyNames | boolean | false | If true, includes data key names in voice over description of each element. EG "Year over year growth: 5.6%" instead of just "5.6%" |
| hideDataTableButton | boolean | false | If true, hides the data table button (but it is still available to screen reader users). |
| disableValidation | boolean | false | If true, disables validations of accessibility props for this chart. Validation is intended to be used during development; upon completion, validation should be disabled. |
| elementsAreInterface | any/boolean | null | Defaults to null. Set to true if interacting with the elements in this chart affects your application. Otherwise, must be set to false. |
| onChangeFunc | function | undefined | Custom event listener (changeFunc) that enables dev to control accessibility page experience when chart data updates. |
| showSmallLabels | boolean | false | Defaults to false. Set to true if you would like to display labels on small elements that are likely to overlap. Note, this could impact accessibility of your graphic. |
| hideStrokes | boolean | false | Defaults to false. Set to true if you would like to remove automated stroke outlines from the chart, note, this could impact accessibility of your graphic. |
| hideTextures | boolean | false | Defaults to false. Set to true if you would like to remove textures from the chart, note, this could impact accessibility of your graphic. |
| keyboardNavConfig | IKeyConfig | { disabled: false } | Defaults disabled to false. May be set to true if accessibility.elementsAreInterface = false and suppressEvents = true. This will disable keyboard navigation and simplify chart instructions for screen reader users. |
| showExperimentalTextures | boolean | false | Defaults to false. Set to true if you would like leverage our textures which are still undergoing research and development. |
# Basic Props <>
# IBoxModelType
Used by every chart for both the padding and margin props.
| Name | Type | Default Value(s) | Description |
| -------- | ------ | ---------------- | ------------------------------------------------------- |
| top | number | height * 0.01 | Sets the top margin/padding for the chart container. |
| bottom | number | height * 0.01 | Sets the bottom margin/padding for the chart container. |
| left | number | width * 0.01 | Sets the top margin/padding for the chart container. |
| right | number | width * 0.01 | Sets the top margin/padding for the chart container. |
# ISubTitleType
Used by every chart for to declare subtitles as a simple string, or as an object that allows certain text to be highlighted.
| Name | Type | Default Value(s) | Description |
| ------------------- | ------------------------------------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| text | string | ‘’ | Text of the subtitle. |
| keywordsHighlight | IKeywordsHighlightType[] | '' | Configuration used to create highlighted words in the subtitle, an array of objects which includes text, mode, color and index keys. See IKeywordsHighlightType definition below for additional details. |
# IKeywordsHighlightType
Used when keywordsHighlight is declared in a subtitle.
| Name (keywordsHighlight.) | Type | Default Value(s) | Description |
| ------------------------- | ---------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| text | string | '' | A string of one or multiple words in the subtitle text to be given the highlight treatment |
| color | string | '' | HEX code color string to apply to the highlight treatment. |
| mode | 'text' or 'background' | 'background' | 'text' will highlight the text itself with the provided color, using ensureTextContrast utility to ensure text contrast. 'background' will highlight the background-color of the created span with the provided color. |
| index | number | | If provided, highlight treatment is provided to the specific instance of the text within the sub-title. Otherwise, all instances of the provided string will be given highlight treatment. |
# Dumbbell Specific <>
# IBarStyleType
Dumbbell plot only. Sets props for dumbbell's bar.
| Name (barStyle.) | Type | Default Value(s) | Description |
| ---------------- | ------ | ---------------- | -------------------------------------------------------------------------------------------- |
| colorRule | string | 'default' | Sets the color rule for the dumbbell bar (options are 'greaterValue', 'focus' or 'default'). |
| opacity | number | 1 | Sets the opacity of the dumbbell bar. |
| width | number | 1 | Sets the width of the dumbbell bar. |
# IDifferenceLabelType
Dumbbell plot only. Adjusts settings for the difference label (label between dumbbell markers).
| Name | Type | Default Value(s) | Description |
| ------------- | ------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| calculation | string | 'difference' | Sets the calculation used in the difference label. Accepts 'difference' or 'middle'. |
| visible | boolean | true | Toggles the visibility (opacity) of the difference labels. |
| placement | string | 'left' | Sets the placement of the data label. Accepts 'top', 'bottom', 'left', and 'right'. |
| format | string | '0[.][0][0]a' | Sets the formatting for the data labels, EG %b, refer to d3-time-format and numeral.js. |
# IFocusStyleType
Dumbbell plot only. Sets props for focus marker. sizeFromBar will override marker style props, but only for markers that match the focusMarker.key.
| Name (focusMarker.) | Type | Default Value(s) | Description |
| ------------------- | ------ | ---------------- | -------------------------------------------- |
| key | string | '' | Key used to determine which marker to focus. |
| sizeFromBar | number | 12 | Sets the size of the focus marker. |
# IMarkerStyleType
Dumbbell plot only. Sets props for dumbbell's markers. Focus marker's sizeFromBar will override this prop's sizeFromBar, but only for markers that match the focusMarker.key.
| Name (marker.) | Type | Default Value(s) | Description |
| -------------- | ------- | ---------------- | ---------------------------------------- |
| type | string | 'dot' | Sets the shape type of dumbbell markers. |
| sizeFromBar | number | 8 | Sets the size of the marker. |
| visible | boolean | true | Sets the visibility of dumbbell markers. |
# Interactivity <>
# IHoverStyleType
Sets the color and stroke width for elements when they match the hoverHighlight and interactionKeys props. See chart-level documentation for how to handle hover interactivity.
| Name | Type | Default Value(s) | Description |
| ------------- | ------ | ---------------- | -------------------------------------------------------------------------------------------- |
| color | string | '' | Sets the color of the hovered element (requires hoverHighlight to be valid and sent). |
| strokeWidth | number | 2 | Sets the stroke width of the hovered element (requires hoverHighlight to be valid and sent). |
# IClickStyleType
Sets the color and stroke width for elements when they match the clickHighlight and interactionKeys props. See chart-level documentation for how to handle click interactivity.
| Name | Type | Default Value(s) | Description |
| ------------- | ------ | ---------------- | -------------------------------------------------------------------------------------------- |
| color | string | '' | Sets the color of the clicked element (requires clickHighlight to be valid and sent). |
| strokeWidth | number | 2 | Sets the stroke width of the clicked element (requires clickHighlight to be valid and sent). |
# Labels and Legend <>
# IDataLabelType
Used by every chart. Specifies label values, visibility, placement, and format of data labels.
| Name | Type | Default Value(s) | Description |
| --------------- | ------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| labelAccessor | string | '' | Key used to determine label's property. |
| visible | boolean | true | Toggles the visibility (opacity) of the data labels. |
| placement | string | 'top' (vertical), 'right' (horizontal) | Sets the placement of the data label. Examples of values are 'top', 'bottom' for vertical layout and 'left', 'right', 'top-right' for horizontal layout. |
| format | string | '0[.][0][0]a' | Sets the formatting for the data lables, EG %b, refer to d3-time-format and numeral.js. |
# ILegendType
Specifies visibility, interactivity, format, label values, and type of chart legends. Only charts that have groupAccessor or seriesAccessor passed as the only value in interactionKeys can set interactive to true. The various styles allowed for type differ for each chart.
| Name | Type | Default Value(s) | Description |
| ------------- | -------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| visible | boolean | true | Toggles the visibility (opacity/display) of the legend. |
| interactive | boolean | false | Toggles the interactivity of the legend. |
| format | string | '' | Sets the formatting for the legend lables, EG %b, refer to d3-time-format and numeral.js. |
| labels | string[] | '' | An array that sets each label in the legend, in order. Passing empty string will populate legend labels directly from data values. |
| type | string | 'bar' | Sets the type of the legend, forced to 'bar' in bar-chart. |
# ISeriesLabelType
Used in Line Chart, Parallel plot, and Dumbbell plot. Specifies label content and placement for series labels.
| Name | Type | Default Value(s) | Description |
| ----------- | -------- | ---------------- | ----------------------------------------------------------------- |
| label | string[] | [] | An array which determines the labels for each line, in order. |
| visible | boolean | true | Toggles the visibility (opacity) of the series labels. |
| placement | string | 'right' | Sets the placement of the series label, accepts 'left' or 'right' |
# ITooltipLabelType
Used by every chart to set the label values, titles, and formatting within a tooltip.
| Name | Type | Default Value(s) | Description |
| --------------- | -------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| labelAccessor | string[] | [] | An array that determines which property of the data is displayed in the tooltip. |
| labelTitle | string[] | [] | An array that sets the title for each data property in the tooltip. |
| format | string | '' | Sets the formatting for the data properties in the tooltip, EG %b, refer to d3-time-format and numeral.js. |
# Reference Lines <>
# IReferenceStyleType
Note: The referenceLines and Style props are currently deprecated and will ultimately be fully replaced by the annotation prop. For the time being, this prop will work, but will not pass accessibility requirements. Use at your own risk or migrate to annotations.
| Name | Type | Default Value(s) | Description |
| ------------- | ------ | ---------------- | ----------------------------------------------------------------------- |
| color | string | 'pri_grey' | Sets the color of the reference line. |
| strokeWidth | number | 1 | Sets the stroke width of the reference line. |
| opacity | number | 1 | Sets the opacity of the reference line. |
| dashed | string | '' | Sets the dash array property of the path element of the reference line. |
# Secondary Lines <>
# ISecondaryLinesType
Used in Line Chart and Parallel plot. Specifies styling overrides meant to de-emphasize secondary lines (reduce cognitive load of non-essential lines). Secondary lines are matched according to strings of seriesAccessor values passed into secondaryLines.keys.
| Name (secondaryLines.) | Type | Default Value(s) | Description |
| ---------------------- | -------- | ---------------- | -------------------------------------------------------- |
| keys | string[] | [] | Assign keys of secondary lines. |
| showDataLabel | boolean | true | Sets the visibility of data labels on secondary lines. |
| showSeriesLabel | boolean | true | Sets the visibility of series labels on secondary lines. |
| opacity | number | 1 | Sets the opacity of secondary lines. |
# World Map Specific <>
# IMapMarkerStyleType
World Map only. Adjusts the settings and style of the markers being placed on the map.
| Name (markerStyle.) | Type | Default Value(s) | Description |
| ------------------- | -------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| visible | boolean | false | Sets the visibility of map markers. |
| fill | boolean | true | Sets whether to color markers with either a, ordinal() (based on groupAccessor), or quantize() (based on valueAccessor) color scale. |
| blend | boolean | false | Sets whether to apply mix-blend-mode multiply (true), or normal (false). |
| color | string | base_grey | Sets the color of the marker if fill is false. |
| strokeWidth | string | 1px | Sets the stroke-width of the marker (currently requires Npx notation.) |
| opacity | number | 0.8 | Sets the opacity of the marker. |
| radius | number | 5 | Sets the radius of the marker, if radiusRange is falsy/empty string. |
| radiusRange | number[] | '' | Sets the size of the marker through a value based scale, currently leverages d3.scalePow().exponent(0.5) for marking scaling approach. |
# ICountryStyleType
World Map only. Adjusts the settings and style of the map's country features.
| Name (countryStyle.) | Type | Default Value(s) | Description |
| -------------------- | ------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| fill | boolean | true | Sets whether to color country features with either a, ordinal() (based on groupAccessor), or quantize() (based on valueAccessor) color scale. |
| opacity | number | 0.8 | Sets the opacity of the country features. |
| color | string | base_grey | Sets the color of the country features if fill is false. |
| strokeWidth | string | 1px | Sets the stroke-width of the country features (currently requires Npx notation.) |
# X and Y Axis <>
# IAxisType
Used by most charts to customize the x and y axis. Only charts that plot dates (like Line Chart) can use the unit property. Only Parallel Plot uses yAxis.scales and yAxis.onlyTickExtents.
| Name (xAxis./yAxis.) | Type | Default Value(s) | Description |
| ----------------------- | ------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| visible | boolean | true | Toggles the visibility of the axis. |
| gridVisible | boolean | true | Toggles the visibility of the axis grid. |
| label | string | 'X Axis' | Sets the label for the axis. |
| placement | string | 'top' (x), 'left' (y) | Sets the axis placement for x 'top' or 'bottom' and for y 'left', or 'right'. |
| format | string | '' or '%b %y' or '0[.][0][0]a' | Sets the formatting for axis elements, EG %b, refer to d3-time-format and numeral.js. |
| tickInterval | number | 1 | Can be used to reduce the frequency of axis ticks. This number sets the interval of axis ticks that are shown. |
| unit | string | '' or 'month' | Sets the unit of padding for the axis when accessor is a date. |
| yAxis.scales | string | undefined or 'preNormalized' | Sets the type of scales used in y axis for parallel plot. |
| yAxis.onlyTickExtents | boolean | true | Hides yAxis ticks between min/max for parallel plot. |