add minimal documentation to components #34

medialab · Oct 25, 2021 · e22be1b · e22be1b
1 parent 55e3b6d
commit e22be1b
Show file tree

Hide file tree

Showing 54 changed files with 856 additions and 332 deletions.
diff --git a/src/components/BarChart/HorizontalBarChart.js b/src/components/BarChart/HorizontalBarChart.js
@@ -194,9 +194,6 @@ const HorizontalBarChart = ({
     const yScale = scaleLinear().domain(yDomain).range([height - margins.bottom, margins.top]).nice();
     const yStackScale = yScale.copy().range([0, height - margins.bottom - margins.top]);
 
-
-
-  // let { values: xAxisValues } = axisPropsFromTickScale(xScale);
   const xAxisValues = xTickSpan ? range(xDomain[0], xDomain[xDomain.length - 1], xTickSpan) : xValues;
   let { values: yAxisValues } = axisPropsFromTickScale(yScale, 10);
 

diff --git a/src/components/BarChart/VerticalBarChart.js b/src/components/BarChart/VerticalBarChart.js
@@ -195,7 +195,7 @@ const VerticalBarChart = ({
         return 1 * multiplier;
       })
     ])
-  , [data, y.field, autoSort, sortYAscending, sortYField, sortYType, sortXAscending, sortXField, sortXType, color.field, colorModalities]);
+  , [data, y, autoSort, sortYAscending, sortYField, sortYType, sortXAscending, sortXField, sortXType, color, colorModalities]);
 
   const xDomain = initialXDomain || layout === 'stack' ?
     // stack -> max = max sum for a given x modality

diff --git a/src/components/BoatsIllustration/BoatsIllustration.js b/src/components/BoatsIllustration/BoatsIllustration.js
@@ -10,6 +10,12 @@ import './BoatsIllustration.scss';
 const PASS_DURATION = 100000;
 const UPDATE_RATE = 4000;
 
+/**
+ * Returns a boat hull shape
+ * @param {number} width
+ * @param {number} height
+ * @returns  {React.ReactElement} - React component
+ */
 const Hull = ({
   width,
   height,
@@ -25,6 +31,14 @@ const Hull = ({
 
 }
 
+/**
+ * Returns a boat sail shape
+ * @param {number} width
+ * @param {number} height
+ * @param {number} sailSpeed - period in miliseconds
+ * @param {number} distance - factor in [0,1]
+ * @returns  {React.ReactElement} - React component
+ */
 const Sail = ({
   width,
   height,
@@ -62,6 +76,14 @@ const Sail = ({
   )
 }
 
+/**
+ * Returns a boat matt shape
+ * @param {number} width
+ * @param {number} height
+ * @param {number} sailSpeed - period in miliseconds
+ * @param {number} distance - factor in [0,1]
+ * @returns  {React.ReactElement} - React component
+ */
 const Matt = ({
   width,
   height,
@@ -87,6 +109,13 @@ const Matt = ({
   )
 }
 
+/**
+ * Returns a boat shape
+ * @param {number} x
+ * @param {number} height
+ * @param {number} distance - factor in [0,1]
+ * @returns  {React.ReactElement} - React component
+ */
 const Boat = ({
   x,
   height,
@@ -159,6 +188,13 @@ const Boat = ({
   )
 }
 
+/**
+ * Returns a bird shape
+ * @param {number} boatHeight
+ * @param {number} containerHeight
+ * @param {number} distance - factor in [0,1]
+ * @returns  {React.ReactElement} - React component
+ */
 const Bird = ({
   boatHeight,
   containerHeight,
@@ -207,6 +243,16 @@ const Bird = ({
   )
 }
 
+/**
+ * Returns a moving boat + optional birds
+ * @param {number} containerHeight
+ * @param {number} containerWidth
+ * @param {boolean} rightToLeft
+ * @param {number} startAt - starting point in pixels
+ * @param {number} size - factor for defining height relative to container height
+ * @param {number} distance - factor in [0,1]
+ * @returns  {React.ReactElement} - React component
+ */
 const MovingBoat = ({
   containerHeight,
   containerWidth,
@@ -274,6 +320,12 @@ const MovingBoat = ({
 }
 
 
+/**
+ * Returns moving boats
+ * @param {number} width
+ * @param {number} height
+ * @returns  {React.ReactElement} - React component
+ */
 const BoatsIllustration = ({
   width: inputWidth = 1200,
   height: inputHeight = 100,

diff --git a/src/components/BoatsIllustration/BoatsIllustration.scss b/src/components/BoatsIllustration/BoatsIllustration.scss
@@ -1,17 +1,15 @@
-
-
-
 .BoatsIllustration {
   .boat {
     line {
       stroke: grey;
     }
-    polygon, path {
+    polygon,
+    path {
       fill: lightgrey;
     }
 
     .sail {
-      opacity: .9;
+      opacity: 0.9;
     }
 
     .hull {
@@ -21,4 +19,4 @@
   .bird {
     fill: grey;
   }
-}
+}
diff --git a/src/components/Caller/Caller.js b/src/components/Caller/Caller.js
@@ -5,18 +5,28 @@ import {v4 as genId} from 'uuid';
 
 import {VisualizationControlContext} from '../../helpers/contexts';
 
+/**
+ * Visulization caller to place in contents
+ * @param {string} id - visualization id used by visualization context to map caller with a specific vis
+ * @param {object} props - visualization parameters passed as payload to visualization context
+ * @returns  {React.ReactElement} - React component
+ */
 const Caller = ({id: visualizationId, ...props}) => {
   const ref = useRef(null);
+  // we differentiate caller id and visualization id as their rel can theoretically be n-1
   const [id] = useState(genId());
   const {
+    // used to define whether caller is active
     activeVisualization,
     onBlockClick,
+    // callbacks used to register/unregister visualization data & HTML ref in upstream state
     onRegisterVisualization,
     onUnregisterVisualization,
   } = useContext(VisualizationControlContext);
 
+  // register vis on caller's mount, unregister it on unmount
   useEffect(() => {
-    // on wrappe dans un setTimeout pour avoir une ref non-nulle vers le composant
+    // we wrap callback in a setTimeout in order to have a non-null ref to the HTML element
     setTimeout(() => {
       let payload = {...props};
       payload = {
@@ -43,6 +53,7 @@ const Caller = ({id: visualizationId, ...props}) => {
       className={cx("Caller", {
         'is-active': activeVisualization && id === activeVisualization.id, 
         'is-clearfix': !visualizationId,
+        // currently is-hidden and is-devmode are logically symetrical, but this can be useful to differentiate the 2 in dev
         'is-hidden': process.env.NODE_ENV !== 'development',
         'is-devmode': process.env.NODE_ENV === 'development',
       })}

diff --git a/src/components/CircularAlluvialChart/CircularAlluvialChart.js b/src/components/CircularAlluvialChart/CircularAlluvialChart.js
@@ -14,51 +14,29 @@ import { min } from 'd3-array';
 import { uniq } from 'lodash-es';
 import { cartesian2Polar, fixSvgDimension, trimText } from '../../helpers/misc';
 import ReactTooltip from 'react-tooltip';
-import { useSpring, animated } from 'react-spring'
 
-const colorSchemes = [colorScheme1, colorScheme2, colorScheme3];
+import {G, Text, Line, Circle, Rect, Path} from './animatedPrimities';
 
-const G =({children, className, onClick, ...inputProps})  => {
-  const props = useSpring(inputProps);
-  return (
-    <animated.g className={className} onClick={onClick} {...props}>
-      {children}
-    </animated.g>
-  )
-}
-const Text =({children, onClick, className, style, ...inputProps})  => {
-  const props = useSpring(inputProps);
-  return (
-    <animated.text className={className} onClick={onClick} style={style} {...props}>
-      {children}
-    </animated.text>
-  )
-}
-const Line = ({style, className, onClick, ...inputProps}) => {
-  const props = useSpring(inputProps);
-  return (
-    <animated.line className={className} onClick={onClick} style={style} {...props} />
-  )
-}
-const Circle = ({style, className, onClick, ...inputProps}) => {
-  const props = useSpring(inputProps);
-  return (
-    <animated.circle className={className} onClick={onClick} style={style} {...props} />
-  )
-}
-const Rect = ({style, className, onClick, ...inputProps}) => {
-  const props = useSpring(inputProps);
-  return (
-    <animated.rect className={className} onClick={onClick} style={style} {...props} />
-  )
-}
-const Path = ({style, className, onClick, ...inputProps}) => {
-  const props = useSpring(inputProps);
-  return (
-    <animated.path className={className} onClick={onClick} style={style} {...props} />
-  )
-}
+const colorSchemes = [colorScheme1, colorScheme2, colorScheme3];
 
+/**
+ * Renders a circular alluvial diagram (duh)
+ * @param {array} data
+ * @param {string} sumBy - field in data to use to quantify flows
+ * @param {array} steps - arrow of steps in the form: {field: [string], labels: {fr: [string], en: [string]}, filters: [{key: [string], value: [string]}]}
+ * @param {number} width
+ * @param {number} height
+ * @param {array} filters - objects in the form {key, value} to highlight some flows in the vis
+ * @param {boolean} debug
+ * @param {string} title
+ * @param {object} colorsPalettes
+ * @param {boolean} centerHorizontalLabels
+ * @param {boolean} displaceHorizontalLabels - avoid labels overlap (at the cost of invadint the center of the vis)
+ * @param {object} tooltips - tooltips of nested functions in the form {node: {fr: [fn], en: [fn]}, flow: {fr: [fn], en: [fn]}}
+ * @param {string} lang - enum ['fr', 'en']
+ * @param {string} align - enum ['left', 'center']
+ * @returns {React.ReactElement} - React component
+ */
 const CircularAlluvialChart = ({
   data: inputData = [],
   sumBy,
@@ -403,17 +381,6 @@ const CircularAlluvialChart = ({
                                         data-for="alluvial-tooltip"
                                         data-tip={tContent}
                                       >
-                                        {/* <Path 
-                                    d={`
-                                    M ${x1} ${y1} 
-                                    Q ${controlPoint1AX} ${controlPoint1AY}, ${x2} ${y2} 
-                                    L ${x3} ${y3}
-                                    Q ${controlPoint2AX} ${controlPoint2AY}, ${x4} ${y4} 
-                                    Z
-                                    `.trim().replace(/\n/g, ' ')}
-                                    title={'Valeur : ' + flow.valueAbs}
-                                    style={{fill: colorScales[step.field][node.id]}}
-                                  /> */}
                                         <Path
                                           d={`
                                     M ${x1} ${y1} 
@@ -555,7 +522,6 @@ const CircularAlluvialChart = ({
                             labelX = displaceLabels + minTextWidth;
                           }
                           displaceLabels = labelX;
-                          // console.groupEnd('test');
                         }
                         const labelY = orientation === 'vertical' ? y + actualHeight / 2 : y + displaceText;
                         const [labelMain, labelSecondary] = trimText(node.id, 20);

diff --git a/src/components/CircularAlluvialChart/CircularAlluvialChart.scss b/src/components/CircularAlluvialChart/CircularAlluvialChart.scss
@@ -142,4 +142,4 @@
       opacity: 1;
     }
   }
-}
+}
diff --git a/src/components/CircularAlluvialChart/LinearAlluvialChart.js b/src/components/CircularAlluvialChart/LinearAlluvialChart.js
@@ -6,6 +6,16 @@ import {prepareAlluvialData} from './utils';
 
 import './CircularAlluvialChart.scss';
 
+/**
+ * Returns a linear alluvial chart component
+ * @param {array<object>} data
+ * @param {string} sumBy
+ * @param {array} steps
+ * @param {number} width
+ * @param {number} height
+ * @param {array<object>} filters
+ * @returns {React.ReactElement} - React component
+ */
 const LinearAlluvialChart = ({
   data : inputData = [],
   sumBy,

diff --git a/src/components/CircularAlluvialChart/animatedPrimities.js b/src/components/CircularAlluvialChart/animatedPrimities.js
@@ -0,0 +1,43 @@
+import { useSpring, animated } from 'react-spring'
+
+
+export const G =({children, className, onClick, ...inputProps})  => {
+  const props = useSpring(inputProps);
+  return (
+    <animated.g className={className} onClick={onClick} {...props}>
+      {children}
+    </animated.g>
+  )
+}
+export const Text =({children, onClick, className, style, ...inputProps})  => {
+  const props = useSpring(inputProps);
+  return (
+    <animated.text className={className} onClick={onClick} style={style} {...props}>
+      {children}
+    </animated.text>
+  )
+}
+export const Line = ({style, className, onClick, ...inputProps}) => {
+  const props = useSpring(inputProps);
+  return (
+    <animated.line className={className} onClick={onClick} style={style} {...props} />
+  )
+}
+export const Circle = ({style, className, onClick, ...inputProps}) => {
+  const props = useSpring(inputProps);
+  return (
+    <animated.circle className={className} onClick={onClick} style={style} {...props} />
+  )
+}
+export const Rect = ({style, className, onClick, ...inputProps}) => {
+  const props = useSpring(inputProps);
+  return (
+    <animated.rect className={className} onClick={onClick} style={style} {...props} />
+  )
+}
+export const Path = ({style, className, onClick, ...inputProps}) => {
+  const props = useSpring(inputProps);
+  return (
+    <animated.path className={className} onClick={onClick} style={style} {...props} />
+  )
+}
diff --git a/src/components/CitationWidget/CitationWidget.js b/src/components/CitationWidget/CitationWidget.js
@@ -21,6 +21,12 @@ const CONTENTS = {
   }
 }
 
+
+/**
+ * Description
+ * @param {string} lang
+ * @returns {React.ReactElement} - React component
+ */
 const CitationWidget = ({
   lang = 'fr',
 }) => {
@@ -93,6 +99,7 @@ const CitationWidget = ({
               </ul>
               : null
           }
+          {/* disabled: copy on click (gadget) */}
           {/* <div className="copy-link-container">
             <span onClick={handleCopyClick}>{copyClicked ? messages.citationCopied[lang] : messages.copyCitation[lang]}</span>
           </div> */}

diff --git a/src/components/DataProvider/DataProvider.js b/src/components/DataProvider/DataProvider.js
@@ -2,6 +2,12 @@ import { useEffect, useState } from "react";
 import { csvParse } from 'd3-dsv';
 import get from 'axios';
 
+/**
+ * Fetches data and provides it to children (used for tests)
+ * @param {string} data
+ * @param {function} children
+ * @returns {React.ReactElement} - React component
+ */
 const DataProvider = ({
   data: dataFilename,
   children
-Original file line number
+Diff line change
@@ Expand Up / @@ -142,4 +142,4 @@ @@
           opacity: 1;
         }
       }
-    }
+    }