[terra-graphs-docs] Update reflow docs (#353)

packages/terra-graphs-docs/CHANGELOG.md

@@ -2,9 +2,13 @@
 
 ## Unreleased
 
+* Added
+  * Added new _Reflow_ documentation page and reflow examples.
+
 * Changed
   * Moved the _Getting Started_ page to the top level.
   * Renamed _Core Configuration_ to _Core Concepts_.
+  * Added `src` to the published files list for rendering example code correctly.
 
 ## 1.9.3 - (April 9, 2024)
 

packages/terra-graphs-docs/package.json

@@ -30,6 +30,7 @@
   "files": [
     "docs",
     "lib",
+    "src",
     "CHANGELOG.md",
     "LICENSE",
     "NOTICE"

packages/terra-graphs-docs/src/terra-dev-site/graph/CoreConcepts.b/Reflow.e.graph.mdx

@@ -0,0 +1,16 @@
+import BasicReflowExample from './examples/reflow/BasicReflowExample';
+import PanningExample from './examples/reflow/PanningExample';
+
+
+# Reflow
+
+Reflow can be used to dynamically update a graph.
+
+## Overview
+
+<BasicReflowExample/>
+
+## Examples
+
+### Panning
+<PanningExample/>

packages/terra-graphs-docs/src/terra-dev-site/graph/CoreConcepts.b/examples/reflow/BasicReflowExample.jsx

@@ -0,0 +1,97 @@
+import React, { useState } from 'react';
+
+import Button from 'terra-button';
+
+import Carbon from '@cerner/carbon-graphs';
+
+//  graph configuration object
+
+const graphConfig = {
+  bindTo: '#basic-reflow-example',
+  axis: {
+    x: {
+      label: 'x-axis',
+      lowerLimit: 80,
+      upperLimit: 280,
+      rangeRounding: false,
+    },
+    y: {
+      label: 'y-axis',
+      lowerLimit: -5,
+      upperLimit: 20,
+    },
+  },
+  allowCalibration: true,
+};
+
+//  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
+let graph;
+const BasicReflowExample = () => {
+  const [allowCalibrationStatus, SetAllowCalibrationStatus] = useState(graphConfig.allowCalibration.toString());
+
+  React.useEffect(() => {
+    graph = Carbon.api.graph(graphConfig);
+    graph.loadContent(Carbon.api.line(dataset1));
+  }, []);
+
+  const handleClickToggleCalibration = () => {
+    graph.config.allowCalibration = !graph.config.allowCalibration;
+    SetAllowCalibrationStatus(graph.config.allowCalibration.toString());
+
+    graph.reflowMultipleDatasets();
+  };
+
+  const handleClickUpdateLimits = () => {
+    graph.config.axis.y.domain.lowerLimit = -52;
+    graph.config.axis.y.domain.upperLimit = 52;
+
+    graph.reflowMultipleDatasets();
+  };
+
+  const handleClickReset = () => {
+    graph.config.axis.y.domain.lowerLimit = 0;
+    graph.config.axis.y.domain.upperLimit = 20;
+
+    graph.reflowMultipleDatasets();
+  };
+
+  return (
+    <>
+      <Button text="Toggle Calibration" onClick={handleClickToggleCalibration} />
+      <Button text="Update Axis Limits" onClick={handleClickUpdateLimits} />
+      <Button text="Reset" onClick={handleClickReset} />
+      <div>
+        AllowCalibration:
+        {allowCalibrationStatus}
+      </div>
+      <div id="basic-reflow-example" />
+    </>
+  );
+};
+
+export default BasicReflowExample;

packages/terra-graphs-docs/src/terra-dev-site/graph/CoreConcepts.b/examples/reflow/PanningExample.jsx

@@ -0,0 +1,111 @@
+import React from 'react';
+
+import Button from 'terra-button';
+import { IconLeft, IconRight } from 'terra-icon';
+
+import Carbon from '@cerner/carbon-graphs';
+
+//  graph configuration object
+
+const graphConfig = {
+  bindTo: '#panning-example',
+  axis: {
+    x: {
+      label: 'x-axis',
+      lowerLimit: 80,
+      upperLimit: 280,
+      rangeRounding: false,
+    },
+    y: {
+      label: 'y-axis',
+      lowerLimit: -5,
+      upperLimit: 20,
+    },
+  },
+  panning: {
+    enabled: true,
+  },
+};
+
+//  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
+let graph;
+const panningFactor = 10;
+
+const PanningExample = () => {
+  React.useEffect(() => {
+    graph = Carbon.api.graph(graphConfig);
+    graph.loadContent(Carbon.api.line(dataset1));
+  }, []);
+
+  const reducer = (panState, action) => {
+    let newLowerLimit = graph.config.axis.x.lowerLimit;
+    let newUpperLimit = graph.config.axis.x.upperLimit;
+
+    switch (action.type) {
+      case 'panLeft':
+        newLowerLimit = graph.config.axis.x.lowerLimit - panningFactor;
+        newUpperLimit = graph.config.axis.x.upperLimit - panningFactor;
+        break;
+      case 'panRight':
+        newLowerLimit = graph.config.axis.x.lowerLimit + panningFactor;
+        newUpperLimit = graph.config.axis.x.upperLimit + panningFactor;
+        break;
+      default:
+        return {
+          newLowerLimit,
+          newUpperLimit,
+        };
+    }
+
+    return {
+      newLowerLimit,
+      newUpperLimit,
+    };
+  };
+
+  const [panState, dispatch] = React.useReducer(reducer, panningFactor);
+
+  React.useLayoutEffect(() => {
+    if (!graph) { return; }
+
+    graph.config.axis.x.lowerLimit = panState.newLowerLimit;
+    graph.config.axis.x.upperLimit = panState.newUpperLimit;
+
+    graph.reflowMultipleDatasets();
+  }, [panState]);
+
+  return (
+    <>
+      <Button icon={<IconLeft />} isIconOnly onClick={() => dispatch({ type: 'panLeft' })} />
+      <Button icon={<IconRight />} isIconOnly onClick={() => dispatch({ type: 'panRight' })} />
+      <div id="panning-example" />
+    </>
+  );
+};
+
+export default PanningExample;