This repository has been archived by the owner on May 24, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 7
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[terra-graphs-docs] Update axes docs (#342)
- Loading branch information
Showing
13 changed files
with
508 additions
and
12 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
178 changes: 178 additions & 0 deletions
178
...terra-graphs-docs/src/terra-dev-site/graph/CoreConfiguration.b/Axes.b.graph.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,178 @@ | ||
| import AllowCalibrationXAxisDisabledExample from './examples/axes/AllowCalibrationXAxisDisabled?dev-site-example'; | ||
| import AllowCalibrationXAxisEnabledExample from './examples/axes/AllowCalibrationXAxisEnabled?dev-site-example'; | ||
|
|
||
| import RangeRoundingDisabledExample from './examples/axes/RangeRoundingYAxisDisabled?dev-site-example'; | ||
| import RangeRoundingEnabledExample from './examples/axes/RangeRoundingYAxisEnabled?dev-site-example'; | ||
|
|
||
| import XAxisOrientationTopExample from './examples/axes/XAxisOrientationTop?dev-site-example'; | ||
|
|
||
| import YAxisHiddenExample from './examples/axes/YAxisHidden?dev-site-example'; | ||
|
|
||
|
|
||
|
|
||
| # Axes | ||
|
|
||
| Any graph that inherits from `Graph` API will inherit the following `Axis` and `Tick` properties as well. | ||
|
|
||
| - [Structure](#structure) | ||
| - [Properties Summary](#properties-summary) | ||
| - [Properties Details](#properties-details) | ||
| - [allowCalibration](#allowCalibration) | ||
| - [label](#label) | ||
| - [orientation](#orientation) | ||
| - [rangeRounding](#rangerounding) | ||
| - [show](#show) | ||
| - [type](#type) | ||
| - [Notes](#notes) | ||
| - [X Axis Domain Padding](#x-axis-domain-padding) | ||
|
|
||
|
|
||
| ## Structure | ||
|
|
||
| ```json | ||
| axis: { | ||
| x: <x-axis object>, | ||
| y: <y-axis object>, | ||
| y2: <y2-axis object>, | ||
| } | ||
|
|
||
|
|
||
| axis: { | ||
| x: { | ||
| lowerLimit: <number> or <Date>, | ||
| upperLimit: <number> or <Date>, | ||
| label: <string>, | ||
| allowCalibration: <bool> | ||
| onLabelClick: <Function>, | ||
| orientation: <string> | ||
| rangeRounding: <bool>, | ||
| show: <boolean>, | ||
| suppressingTrailingZeros: <bool>, | ||
| ticks: <Ticks object>, | ||
| type: <string> | ||
| rotateAngle: <integer>, | ||
| }, | ||
| y: { | ||
| lowerLimit: <number> or <Date>, | ||
| upperLimit: <number> or <Date>, | ||
| label: <string>, | ||
| onLabelClick: <Function>, | ||
| padDomain: <bool>, | ||
| rangeRounding: <bool>, | ||
| show: <boolean>, | ||
| suppressingTrailingZeros: <bool>, | ||
| ticks: <Ticks object>, | ||
| type: <string> | ||
| }, | ||
| y2:{ | ||
| lowerLimit: <number> or <Date>, | ||
| upperLimit: <number> or <Date>, | ||
| label: <string>, | ||
| onLabelClick: <Function>, | ||
| padDomain: <bool>, | ||
| rangeRounding: <bool>, | ||
| show: <boolean>, | ||
| suppressingTrailingZeros: <bool>, | ||
| ticks: <Ticks object>, | ||
| type: <string> | ||
| } | ||
|
|
||
| } | ||
|
|
||
| ``` | ||
| ## Properties Summary | ||
|
|
||
| | Property Name | Type | Default | Required | Description | | ||
| | --------------------- | -------------- | ------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | lowerLimit | number or Date | - | yes | Lower bound for the axis. This is inclusive. | | ||
| | upperLimit | number or Date | - | yes | Upper bound for the axis. This is inclusive. | | ||
| | label | string | - | yes | Axis label value. Will not be rendered if nothing is provided. | | ||
| | allowCalibration | bool | `false` | no | See [allowCalibration](#allowCalibration). | | ||
| | onLabelClick | Function | `undefined` | no | Any action that can be performed when clicking on label. | | ||
| | orientation | Function | BOTTOM (for x-axis) | no | See [orientation](#orientation). | | ||
| | padDomain | boolean | `true` | no | Toggle for disabling the padding (only for Y and Y2 axes). | | ||
| | rangeRounding | boolean | `true` | no | Toggle for range rounding. | | ||
| | show | boolean | `true` | no | Toggle for showing the axis. | | ||
| | suppressTrailingZeros | boolean | `false` | no | Toggle to suppress tick values's trailing zeros when default d3 tick formatting is used. For X axis, this property works only when X axis type is set to AXIS_TYPE.DEFAULT. Specifying `~` in the tick format takes precedence over `suppressTrailingZeros` property. | | ||
| | ticks | object | `null` | no | See [Ticks](./Ticks). | | ||
| | type | string | `AXIS_TYPE.DEFAULT` | no | See [type](#type). Normal number value or time-based. Only for x-axis. | | ||
| | tickLabelsRotation | integer | - | no | Sets the rotation of the x-axis tick labels to `0º` or `-45º`. Accepted values: 0 or -45. Only for x-axis. | | ||
|
|
||
| ## Properties Details | ||
|
|
||
| - ### `allowCalibration` | ||
| Set calibration for the axis. | ||
| If `true`, then the axis upper and lower limits will update to fit the entire graph on the x-axis. | ||
| This feature can _not_ be used in conjunction with panning. | ||
| If panning is enabled then this property will be ignored if it is `true`. | ||
|
|
||
| NOTE: This property is only implemented for the x-axis (`config.axis.x.allowCalibration`). | ||
| Refer to [`config.allowCalibration`](./graph-configuration-object/#allowcalibration) for calibrating the y-axes. | ||
|
|
||
| <AllowCalibrationXAxisDisabledExample/> | ||
| <AllowCalibrationXAxisEnabledExample/> | ||
|
|
||
|
|
||
| - ### `label` | ||
|
|
||
| Axis label value. Will not be rendered if nothing is provided. | ||
|
|
||
| - ### `orientation` | ||
|
|
||
| Sets the orientation for the x-axis. | ||
| Can be accessed through `AXES_ORIENTATION`. | ||
| Valid values are: | ||
| - `AXES_ORIENTATION.X.TOP` | ||
| - `AXES_ORIENTATION.X.BOTTOM` | ||
|
|
||
| <XAxisOrientationTopExample/> | ||
|
|
||
|
|
||
| - ### `rangeRounding` | ||
| `rangeRounding` property extends the domain so that it starts and ends on nice round values. | ||
| This method typically modifies the scale's domain, and may only extend the bounds to the nearest round value. | ||
| <RangeRoundingDisabledExample/> | ||
| <RangeRoundingEnabledExample/> | ||
|
|
||
|
|
||
| - ### `show` | ||
| Toggle for showing the axis ticks. | ||
| <YAxisHiddenExample/> | ||
|
|
||
|
|
||
| - ### `type` | ||
| Property to set the type of the axis. | ||
|
|
||
| | Constant | Value | | ||
| |-------------------------|----------------------------------------------------------------| | ||
| | `AXIS_TYPE.DEFAULT` | Numeric based x-axis. Will take a `<number>` for tick values. | | ||
| | `AXIS_TYPE.TIME_SERIES` | Timeseries based x-axis. Will take a `<Date>` for tick values. | | ||
|
|
||
|
|
||
| #### Notes: | ||
|
|
||
| - y2 axis is mandatory if **y2.show** is enabled. | ||
| - Ticks are mandatory for Bar graphs. | ||
| - `rangeRounding` property extends the domain so that it starts and ends on nice round values. This method typically modifies the scale’s domain, and may only extend the bounds to the nearest round value. | ||
| - `padDomain` property is only for Y and Y2 axes. | ||
| - `onLabelClick` property will override default onClick functionality provided by Carbon-graphs. | ||
| - For Bar Graphs, `padDomain` property will be overridden to false. | ||
|
|
||
| ## X Axis Domain Padding | ||
|
|
||
| Unlike Y Axis, X Axis can have different types of values as ticks namely numeric, datetime etc. By design, domain padding has not been provided for this reason. Consumers however who are more acquainted with their dataset can judge how much value padding is necessary and achieve similar results as Y Axis. | ||
|
|
||
| Example: | ||
|
|
||
| ```js | ||
| const padXAxisLimits = (extent) => { | ||
| const range = extent[1] - extent[0]; | ||
| return [extent[0] - range * 0.05, extent[1] + range * 0.05]; | ||
| }; | ||
|
|
||
| const datetime = padXAxisLimits( | ||
| d3.extent([ | ||
| /* Array containing all the datetime in RFC3339 format*/ | ||
| ]) | ||
| ); | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
59 changes: 59 additions & 0 deletions
59
.../terra-dev-site/graph/CoreConfiguration.b/examples/axes/AllowCalibrationXAxisDisabled.jsx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,59 @@ | ||
| import React from 'react'; | ||
| import Carbon from '@cerner/carbon-graphs'; | ||
|
|
||
| // graph configuration object | ||
|
|
||
| const graphConfig = { | ||
| bindTo: '#allow-calibration-x-axis-disabled-example', | ||
| axis: { | ||
| x: { | ||
| label: 'x-axis', | ||
| lowerLimit: 100, | ||
| upperLimit: 200, | ||
| // allowCalibration is true by default | ||
| // allowCalibration: false, | ||
| }, | ||
| y: { | ||
| label: 'y-axis', | ||
| lowerLimit: -5, | ||
| upperLimit: 20, | ||
| }, | ||
| }, | ||
| }; | ||
|
|
||
| // graph dataset | ||
|
|
||
| const dataset1 = { | ||
| key: 'uid_1', | ||
| label: { | ||
| display: 'Data Label 1', | ||
| }, | ||
| color: Carbon.helpers.COLORS.BLACK, | ||
| values: [ | ||
| { x: 87, y: -2 }, | ||
| { x: 95, y: 1 }, | ||
| { x: 103, y: -4 }, | ||
| { x: 109, y: -2 }, | ||
| { x: 128, y: 3 }, | ||
| { x: 145, y: 28 }, | ||
| { x: 151, y: 7 }, | ||
| { x: 164, y: 10 }, | ||
| { x: 177, y: 1 }, | ||
| { x: 192, y: 6 }, | ||
| { x: 203, y: -21 }, | ||
| { x: 209, y: -3 }, | ||
| { x: 246, y: 3 }, | ||
| ], | ||
| }; | ||
|
|
||
| // graph rendering | ||
|
|
||
| const AllowCalibrationDisabledExample = () => { | ||
| React.useEffect(() => { | ||
| const graph = Carbon.api.graph(graphConfig); | ||
| graph.loadContent(Carbon.api.line(dataset1)); | ||
| }, []); | ||
| return <div id="allow-calibration-x-axis-disabled-example" />; | ||
| }; | ||
|
|
||
| export default AllowCalibrationDisabledExample; |
58 changes: 58 additions & 0 deletions
58
...c/terra-dev-site/graph/CoreConfiguration.b/examples/axes/AllowCalibrationXAxisEnabled.jsx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,58 @@ | ||
| import React from 'react'; | ||
| import Carbon from '@cerner/carbon-graphs'; | ||
|
|
||
| // graph configuration object | ||
|
|
||
| const graphConfig = { | ||
| bindTo: '#allow-calibration-x-axis-enabled-example', | ||
| axis: { | ||
| x: { | ||
| label: 'x-axis', | ||
| lowerLimit: 100, | ||
| upperLimit: 200, | ||
| allowCalibration: true, | ||
| }, | ||
| y: { | ||
| label: 'y-axis', | ||
| lowerLimit: -5, | ||
| upperLimit: 20, | ||
| }, | ||
| }, | ||
| }; | ||
|
|
||
| // graph dataset | ||
|
|
||
| const dataset1 = { | ||
| key: 'uid_1', | ||
| label: { | ||
| display: 'Data Label 1', | ||
| }, | ||
| color: Carbon.helpers.COLORS.BLACK, | ||
| values: [ | ||
| { x: 87, y: -2 }, | ||
| { x: 95, y: 1 }, | ||
| { x: 103, y: -4 }, | ||
| { x: 109, y: -2 }, | ||
| { x: 128, y: 3 }, | ||
| { x: 145, y: 28 }, | ||
| { x: 151, y: 7 }, | ||
| { x: 164, y: 10 }, | ||
| { x: 177, y: 1 }, | ||
| { x: 192, y: 6 }, | ||
| { x: 203, y: -21 }, | ||
| { x: 209, y: -3 }, | ||
| { x: 246, y: 3 }, | ||
| ], | ||
| }; | ||
|
|
||
| // graph rendering | ||
|
|
||
| const AllowCalibrationEnabledExample = () => { | ||
| React.useEffect(() => { | ||
| const graph = Carbon.api.graph(graphConfig); | ||
| graph.loadContent(Carbon.api.line(dataset1)); | ||
| }, []); | ||
| return <div id="allow-calibration-x-axis-enabled-example" />; | ||
| }; | ||
|
|
||
| export default AllowCalibrationEnabledExample; |
Oops, something went wrong.