Name	Name	Last commit message	Last commit date
parent directory ..
docs	docs
src	src
CHANGELOG.md	CHANGELOG.md
README.md	README.md
package.json	package.json
stencil.config.ts	stencil.config.ts
tsconfig.dev.json	tsconfig.dev.json
tsconfig.json	tsconfig.json
tsconfig.prod.json	tsconfig.prod.json
tslint.json	tslint.json
yarn.lock	yarn.lock

@visa/alluvial-diagram

<alluvial-diagram
    accessibility = {...}
    linkData={[{ group: 'Group 1', cat: 'Team 1 2018', target: 'Team 2 2019', value: 1234 },{links}]}
    nodeData={[{ did: 'Team 1 2018' },{nodes}]} // optional, allows you to join more data to nodes
    sourceAccessor={'cat'}
    targetAccessor={'target'}
    groupAccessor={'group'}
    nodeIDAccessor={'did'} // required if you pass nodeData
    valueAccessor={'value'}
/>

Jump To:

Installation Steps
Props Documentation

# Installation Steps

Using npm
```
$ npm i @visa/alluvial-diagram
```
Using yarn
```
$ yarn add @visa/alluvial-diagram
```

# Props Documentation

# Base Props <>

Name	Type	Default Value(s)	Description
`height`	number	400	Height in px of the chart container
`width`	number	400	Width in px of the chart container
`mainTitle`	string	'Alluvial Diagram Title'	The `dynamic` tag of title for the chart (or you can create your own separately). See `highestHeadingLevel` prop for how tags get assigned.
`subTitle`	string/ISubTitleType	'This is a subtitle'	The `dynamic` tag for a sub title for the chart (or you can create your own separately). See `highestHeadingLevel` prop for how tags get assigned.
`layout`	string	'horizontal'	Displays alluvial diagram vertically or horizontally. (`vertical` and `horizontal` are only valid inputs)

ISubTitleType Definition

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 Definition

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.

# Data Props <>

Name	Type	Default Value(s)	Description
`sourceAccessor`	string	'source'	Key used to determine link's source, must be a node.
`targetAccessor`	string	'target'	Key used to determine link's target, must be a node.
`nodeIDAccessor`	string	'id'	Key used to determine unique node identifiers. Requires nodeData to be populated.
`valueAccessor`	string	'value'	Key used to determine link (and ultimately node size).
`groupAccessor`	string	'group'	Key used to determine link's group or category.
`uniqueID`	string	`undefined`	ID used to identify chart (must be unique per chart), helpful for validation messages. Defaults to UUID v4 standard.
`linkData`	object[]	`undefined`	Data used to create chart links, an array of objects which includes keys that map to above accessors. We leverage d3-sankey for sankey generation, refer to requirements documented for that algorithm for additional data specifications.
`nodeData`	object[]	`undefined`	Optional. Data used to create chart nodes, an array of objects which includes keys that map to above accessors. We leverage d3-sankey for sankey generation, refer to requirements documented for that algorithm for additional data specifications.

# Accessibility Props <>

Name	Type	Default Value(s)	Description
`accessibility`	object (custom type)	IAccessibilityType	Manages messages and settings for chart accessibility, see object definition below.

IAccessibilityType Definition

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. Note: This prop is not currently enabled in this chart and has no effect on the alluvial diagram
`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. Note: This prop is not currently enabled in this chart and has no effect on the alluvial diagram
`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. Note: This prop is not currently enabled in this chart and has no effect on the alluvial diagram
`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. Note: This prop is not currently enabled in this chart and has no effect on the alluvial diagram

// accessibility = { ...accessibility, onChangeFunc: d => changeHandler(d)}
// example of setting updates on page based on changeFunc custom events
const changeHandler = d => {
  if (d.updated && (d.removed || d.added)) {
    let updates = 'The alluvial-diagram chart has ';
    if (d.removed) {
      updates += 'removed ' + d.removed + ' link' + (d.removed > 1 ? 's ' : ' ');
    }
    if (d.added) {
      updates += (d.removed ? 'and ' : '') + 'added ' + d.added + (d.removed ? '' : d.added > 1 ? ' links' : ' link');
    }
    setChartUpdates(updates);
  } else if (d.updated) {
    const newUpdate = "The chart's data has changed, but no links were removed or added.";
    setChartUpdates(
      newUpdate !== chartUpdates ? newUpdate : "The chart's data has changed again, but no links were removed or added."
    );
  }
};

# Localization Props <>

Name	Type	Default Value(s)	Description
`localization`	object (custom type)	ILocalizationType	Manages messages and settings for chart localization, see object definition below.

ILocalizationType Definition

Name (localization.)	Type	Default Value(s)	Description
`language`	string/object	en	Use this to add a language to a chart. This can be string value like `en` or valid translation object.
`numeralLocale`	string/object	US	Use this to add a numerical locale to a chart. This can be string value like `US` or valid numeralLocale object.
`overwrite`	boolean	false	Use this to describe the purpose of this particular chart.
`skipValidation`	boolean	false	If true, disables validations of localization props for this chart. Validation is intended to be used during development; upon completion, validation should be disabled.

# Annotation Props <>

Name	Type	Default Value(s)	Description
`annotations`	array[{annotations}]	[]	Adds annotations to the chart, see d3-svg-annotation by Susie Lu.

annotations object definition

annotations is an array of objects which needs to have the following properties within them. See the detailed api specifications from d3-svg-annotation, along with additional properties layered on top of that work, documented below.

Name	Type	Default Value(s)	Description
`accessibilityDescription`	string	`undefined`	Sets the accessibility description for the annotation for screen reader users.
`positionType`	string	`undefined`	Can be set to `node`, `source` or `target` and when a data object is passed, will return an annotation that is placed at the node, the link's source or the link's target.

# Event Props <>

Events in stencil.js dispatch Custom DOM events for other components to handle, we use Stencil's @Event() decorator to emit events (click, hover, mouseOut) from end user activity on our charts.

Name	Type	Default Value(s)	Description
`suppressEvents`	boolean	false	Suppresses and disables click, hover and mouseOut event emitters. Setting to true can increase performance for non-interactive charts.
`cursor`	string	'default'	Changes pointer type during mouse over on elements. Valid values are 'default' or 'pointer'.
`onClickEvent`	function	`undefined`	When clickEvent event occurs (e.g., mouse/keyboard click on chart geometry), this event handler will be called with the custom event object (e.g., e), containing data and target node at e.detail `{data: d, target: n}`. You will need to construct your own functionality of what actions to take within the callback.
`clickHighlight`	object[]	[]	Data used to track chart selections, an array of objects which includes keys that map to above accessors.
`clickStyle`	object (custom type)	IClickStyleType	Sets the styling of elements when they are selected, see object definition below.
`onHoverEvent`	function	`undefined`	When hoverEvent event occurs (e.g., mouse hover/keyboard focus on chart geometry), this event handler will be called with the custom event object (e.g., e), containing data and target node at e.detail `{data: d, target: n}`. You will need to construct your own functionality of what actions to take within the callback.
`onMouseOutEvent`	function	`undefined`	When mouseOutEvent event occurs (e.g., mouse/keyboard blur on chart geometry), this event handler will be called, and has no data object. You will need to construct your own functionality of what actions to take within the callback.
`hoverHighlight`	object	{}	Datum object used to track active chart element, the object should include keys that map to above accessors.
`hoverStyle`	object (custom type)	IHoverStyleType	Sets the styling of a elements when they are hovered/focused, see object definition below.
`interactionKeys`	string[]	[]	Sets the key names of data to interact with.
`hoverOpacity`	number	1	Sets opacity of inactive elements when hovering/focused on a chart geometry.
`onInitialLoadEvent`	function	`undefined`	When initalLoad event occurs (e.g., chart is mounted to window), this event handler will be called with the custom event object (e.g., e), containing the corresponding chartID at e.detail. You will need to construct your own functionality of what actions to take within the callback.
`onInitialLoadEndEvent`	function	`undefined`	When initalLoadEnd event occurs (e.g., chart has been mounted to window), this event handler will be called with the custom event object (e.g., e), containing the corresponding chartID at e.detail. You will need to construct your own functionality of what actions to take within the callback.
`onDrawStartEvent`	function	`undefined`	When drawStart event occurs (e.g., chart render function is called), this event handler will be called with the custom event object (e.g., e), containing the corresponding chartID at e.detail. You will need to construct your own functionality of what actions to take within the callback.
`onDrawEndEvent`	function	`undefined`	When drawEnd event occurs (e.g., chart's stencil lifecycle completes), this event handler will be called with the custom event object (e.g., e), containing the corresponding chartID at e.detail. You will need to construct your own functionality of what actions to take within the callback.
`onTransitionEndEvent`	function	`undefined`	When transitionEnd event occurs (e.g., chart geometry's transition lifecycle completes), this event handler will be called with the custom event object (e.g., e), containing the corresponding chartID at e.detail. You will need to construct your own functionality of what actions to take within the callback.

IClickStyleType Definition

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). Note: This prop is not currently enabled in this chart and has no effect on the alluvial diagram

IHoverStyleType Definition

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). Note: This prop is not currently enabled in this chart and has no effect on the alluvial diagram

// example of interactivity code
// note this only tracks a single click, you need your own logic to build the array of currnet selections made by user and then pass that result back to chart
//...
const clickHandler = evt => {
  const d = evt.detail.data; // data is located here
  const t = evt.detail.target; // chart mark/label clicked is located here
  this.currentClickedElement = [d]; // this is passed to clickHighlight prop
};

const hoverHandler = evt => {
  const d = evt.detail.data; // data is located here
  const t = evt.detail.target; // chart mark/label clicked is located here

  this.currentHoveredElement = d; // this is passed to hoverHighlight prop
};

const mouseOutHandler = evt => {
  this.currentHoveredElement = ''; // this is passed to hoverHighlight prop
};

// an example of calling these from within a stencil.js component
<alluvial-diagram
    accessibility = {...}
    linkData={[{ group: 'Group 1', cat: 'Team 1 2018', target: 'Team 2 2019', value: 1234 },{links}]}
    nodeData={[{ did: 'Team 1 2018' },{nodes}]} // optional, allows you to join more data to nodes
    sourceAccessor={'cat'}
    targetAccessor={'target'}
    groupAccessor={'group'}
    nodeIDAccessor={'did'} // required if you pass nodeData
    valueAccessor={'value'}
    interactionKeys={['group']}
    onClickEvent={this.onClickEvent}
    clickHighlight={this.currentClickedElement}
    clickStyle={this.clickStyle}
    onHoverEvent={this.onHoverEvent}
    onMouseOutEvent={this.onMouseOut}
    hoverHighlight={this.currentHoveredElement}
    hoverStyle={this.hoverStyle}
/>
//...

# Node Props <>

Name	Type	Default Value(s)	Description
`nodeConfig`	object (custom type)	INodeConfigType	Sets the configuration and styling properties of nodes in the alluvial, see object definition below.

INodeConfigType Definition

Name	Type	Default Value(s)	Description
`fill`	boolean	false	Toggles whether to categorically color nodes.
`width`	number	24 (from d3)	Width in px to set the nodes in the alluvial, leverages d3-sankey's node width.
`padding`	number	8 (from d3)	Spacing in px to add between nodes vertically, leverages d3-sankey's node padding.
`alignment`	string	'left'	Leverages d3-sankey's node alignment functionality, options are 'left', 'right', 'center', or 'justify' for horizontal and 'top', 'middle', 'bottom' and 'justify' for vertical.
`compare`	boolean	false	Toggles whether to vertically, bottom align nodes for easier horizontal comparison. The alignment is computed strictly based on node order.

# Link Props <>

Name	Type	Default Value(s)	Description
`linkConfig`	object (custom type)	ILinkConfigType	Sets the configuration and styling properties of links in the alluvial, see object definition below.

ILinkConfigType Definition

Name	Type	Default Value(s)	Description
`visible`	boolean	true	Toggles whether to horizontally space nodes and render links in between them. Passing false will remove links from the view and bring nodes closer together for easier comparison, we suggest also using nodeConfig.compare in this scenario.
`fillMode`	string	'none'	Determines how to color links in the alluvial, options are 'group' (requires groupAccessor), 'source', 'target', 'link', or, 'none'.
`opacity`	number	0.3	Sets opacity of links in the alluvial.

# Label Props <>

Name	Type	Default Value(s)	Description
`dataLabel`	object (custom type)	IDataLabelType	Controls visibility, styling and placement of data labels, see object definition below.
`dataKeyNames`	object	`undefined`	Object that contains mapping of data keys (e.g., accessors) and user friendly names of the data fields. This prop can be used to enable translation of data keys between languages, or just provide a meaningful name for data elements within a chart. The key:value pairs in this object will effect tooltips, data table, aria labels, axes, etc. Anywhere in chart where data key may be exposed to consumers.
`showTooltip`	boolean	true	Toggles whether to display the tooltip on hover/focus on chart geometries.
`tooltipLabel`	object (custom type)	ITooltipLabelType	Controls visibility, content and format of the chart tooltip, see object definition below.

IDataLabelType Definition

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'	Sets the placement of the data label. Examples of values are 'inside' and 'outside'. Placement option 'auto' leverages the resolveLabelCollision algorithm and places labels without overlaps in available space on the chart.
`format`	string	'0[.][0][0]a'	Sets the formatting for the data labels, EG %b, refer to d3-time-format and numeral.js.
`collisionHideOnly`	boolean	false	Toggles whether to run resolveLabelCollision algorithm and hide labels if collision is detected (vs hide and then place). This is overridden by placement being set to `auto`.
`collisionPlacement`	string	'auto'	Sets the placement of the data label when resolveLabelCollision algorithm is run (dataLabel.placement must be 'auto'). Examples of values are 'auto', 'outside' and 'inside'.

ITooltipLabelType Definition

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.

# Margin & Padding Props <>

Name	Type	Default Value(s)	Description
`margin`	object (custom type)	IBoxModelType	Margin between the subtitle and the chart area, or between the title and chart area if no subtitle is specified, see object definition below.
`padding`	object (custom type)	IBoxModelType	Padding between edge and the chart area, see object definition below.

IBoxModelType Definition

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.

# Style Props <>

Name	Type	Default Value(s)	Description
`colorPalette`	string	'single_blue'	Included color palettes can be found in our color utility. Overridden by colors.
`colors`	string[]	`undefined`	Accepts array of color strings or color values to customize colors beyond our palettes. Overridden by groupAccessor, colors assigned in order.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

alluvial-diagram

alluvial-diagram

README.md

@visa/alluvial-diagram

# Installation Steps

# Props Documentation

# Base Props <>

ISubTitleType Definition

IKeywordsHighlightType Definition

# Data Props <>

# Accessibility Props <>

IAccessibilityType Definition

# Localization Props <>

ILocalizationType Definition

# Annotation Props <>

annotations object definition

# Event Props <>

IClickStyleType Definition

IHoverStyleType Definition

# Node Props <>

INodeConfigType Definition

# Link Props <>

ILinkConfigType Definition

# Label Props <>

IDataLabelType Definition

ITooltipLabelType Definition

# Margin & Padding Props <>

IBoxModelType Definition

# Style Props <>

Files

alluvial-diagram

Directory actions

More options

Directory actions

More options

Latest commit

History

alluvial-diagram

Folders and files

parent directory

README.md

@visa/alluvial-diagram

# Installation Steps

# Props Documentation

# Base Props <>

ISubTitleType Definition

IKeywordsHighlightType Definition

# Data Props <>

# Accessibility Props <>

IAccessibilityType Definition

# Localization Props <>

ILocalizationType Definition

# Annotation Props <>

annotations object definition

# Event Props <>

IClickStyleType Definition

IHoverStyleType Definition

# Node Props <>

INodeConfigType Definition

# Link Props <>

ILinkConfigType Definition

# Label Props <>

IDataLabelType Definition

ITooltipLabelType Definition

# Margin & Padding Props <>

IBoxModelType Definition

# Style Props <>