[terra-graphs-docs] Update axes docs

packages/terra-graphs-docs/CHANGELOG.md

@@ -4,6 +4,7 @@
 
 * Changed
   * Updated core-configuration/graph-config-object documentation and examples.
+  * Updated core-configuration/axes documentation and examples.
   * Optimized published package size by removing unecessary files.
   * Moved Core Configuration documentation up one level out of its subfolder.
   * Updated documentation to use new named export. 

packages/terra-graphs-docs/src/terra-dev-site/graph/CoreConfiguration.b/Axes.b.graph.mdx

@@ -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*/
+    ])
+);
+```

packages/terra-graphs-docs/src/terra-dev-site/graph/CoreConfiguration.b/GraphConfigurationObject.1.graph.mdx → packages/terra-graphs-docs/src/terra-dev-site/graph/CoreConfiguration.b/GraphConfigurationObject.a.graph.mdx

@@ -30,7 +30,7 @@ It is required for the following graphs:
 - [Paired Result](../paired-result-graph/about)
 - [Scatter](../scatter-graph/about)
 
-Without a dataset, the above graphs will render as follows:
+Without a dataset, the above graphs will render as:
 
 <NoDataGeneralExample />
 
@@ -108,7 +108,7 @@ const graphConfig = {
 - ### `allowCalibration`
   **type:** boolean
 
-The `allowCalibration` prop allows the y-axes to be automatically updated based on the dataset.
+The `allowCalibration` prop allows the y-axes to be automatically updated based on the dataset. For calibrating the x-axis, see [`axis.x.allowCalibration`](./axes#allowcalibration).
 <AllowCalibrationDisabledExample/>
 
 When enabled, the maximum and minimum points of the dataset are used to determine the new limits, regardless of if the datapoints are visible in the viewport.

packages/terra-graphs-docs/src/terra-dev-site/graph/CoreConfiguration.b/examples/AllowCalibrationDisabled.jsx

@@ -7,13 +7,11 @@ const graphConfig = {
   bindTo: '#allow-calibration-disabled-example',
   axis: {
     x: {
-      show: true,
       label: 'x-axis',
       lowerLimit: 80,
       upperLimit: 280,
     },
     y: {
-      show: true,
       label: 'y-axis',
       lowerLimit: -5,
       upperLimit: 20,

packages/terra-graphs-docs/src/terra-dev-site/graph/CoreConfiguration.b/examples/AllowCalibrationEnabled.jsx

@@ -27,13 +27,11 @@ const graphConfig2 = {
   bindTo: '#allow-calibration-enabled-example2',
   axis: {
     x: {
-      show: true,
       label: 'x-axis',
       lowerLimit: 80,
       upperLimit: 130,
     },
     y: {
-      show: true,
       label: 'y-axis',
       lowerLimit: -5,
       upperLimit: 20,
@@ -70,7 +68,7 @@ const dataset1 = {
 
 // graph rendering
 
-const NoDataGeneralExample = () => {
+const AllowCalibrationEnabledExample = () => {
   React.useEffect(() => {
     const graph1 = Carbon.api.graph(graphConfig1);
     graph1.loadContent(Carbon.api.line(dataset1));
@@ -87,4 +85,4 @@ const NoDataGeneralExample = () => {
   );
 };
 
-export default NoDataGeneralExample;
+export default AllowCalibrationEnabledExample;

packages/terra-graphs-docs/src/terra-dev-site/graph/CoreConfiguration.b/examples/GraphWithCustomLegendDom.jsx

@@ -9,13 +9,11 @@ const graphConfig = {
   bindLegendTo: '#custom-legend-node',
   axis: {
     x: {
-      show: true,
       label: 'x axis',
       lowerLimit: 80,
       upperLimit: 280,
     },
     y: {
-      show: true,
       label: 'y axis',
       lowerLimit: -18,
       upperLimit: 18,

packages/terra-graphs-docs/src/terra-dev-site/graph/CoreConfiguration.b/examples/GraphWithNoData.jsx

@@ -8,13 +8,11 @@ const graphConfig = {
   bindLegendTo: null,
   axis: {
     x: {
-      show: true,
       label: 'x axis',
       lowerLimit: 80,
       upperLimit: 280,
     },
     y: {
-      show: true,
       label: 'y axis',
       lowerLimit: -18,
       upperLimit: 18,

packages/terra-graphs-docs/src/terra-dev-site/graph/CoreConfiguration.b/examples/axes/AllowCalibrationXAxisDisabled.jsx

@@ -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;

packages/terra-graphs-docs/src/terra-dev-site/graph/CoreConfiguration.b/examples/axes/AllowCalibrationXAxisEnabled.jsx

@@ -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;