add FAQ page, update Options page, handle bad clouds using recursion, bug fixes

chrisrzhou · chrisrzhou · commit efebe826b2a0 · 2019-03-16T23:18:20.000-07:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,18 +3,30 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [1.0.5](https://github.com/chrisrzhou/react-wordcloud/compare/v1.0.4...v1.0.5) (2019-03-16)
+
+### New:
+
+- Added `FAQ` page explaining common 'bugs', and updated `Options` page with more examples
+- Handled recursive attempts to layout 'bad' clouds. Provide a console warning when max attempts have been made to layout 'bad' clouds.
+- Changed default `minSize` and `options.fontSizes` value to make things less buggy.
+
+### Bug fixes:
+
+- Fixed a bug where `rotationAngles` was mutated.
+
 ## [1.0.4](https://github.com/chrisrzhou/react-wordcloud/compare/v1.0.3...v1.0.4) (2019-03-16)
 
 Improve and simplify React hooks code after detailed understanding of: https://overreacted.io/a-complete-guide-to-useeffect/
 
-Bug fixes:
+### Bug fixes:
 
 - Handle words that don't fit in the boundary of the SVG by applying a font-size scale factor
 - Handle large number of words
 
 ## [1.0.3](https://github.com/chrisrzhou/react-wordcloud/compare/v1.0.2...v1.0.3) (2019-03-14)
 
-Bug fixes:
+### Bug fixes:
 
 - https://github.com/chrisrzhou/react-wordcloud/issues/5
 - https://github.com/chrisrzhou/react-wordcloud/issues/11
diff --git a/README.md b/README.md
@@ -79,3 +79,9 @@ Features supported:
 - Various NLP methods (stopwords, ngrams)
 - Wordcloud configurations
 - Export/save/share wordclouds
+
+## Donate
+
+My projects will always be (ads-)free. I constantly learn from the community, so these projects are a way of giving back to the community. If you liked this project or find it useful, feel free to buy me a cup of coffee ☕️ through a small donation!
+
+[![paypal](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.me/chrisrzhou/5)
diff --git a/docs/faq.mdx b/docs/faq.mdx
@@ -0,0 +1,36 @@
+---
+name: FAQ
+route: /faq
+---
+
+import { Playground } from "docz";
+import ReactWordcloud from "./../src";
+
+# FAQ
+
+## Why are some words dropped?
+
+`ReactWordcloud` applies a limit that can be controlled by the `maxWords` prop. This is set to `100` by default. You can raise the limit but be careful that this could affect performance.
+
+## Why is the most frequent word is not showing up?
+
+This issue happens when the most frequent word is also the **longest** word. For a given wordcloud size, if the longest and most frequent word does not fit in the wordcloud SVG container, the `d3-cloud` algorithm drops them out. This is a known issue discussed in: https://github.com/jasondavies/d3-cloud/issues/36
+
+`react-wordcloud` tries to solve this issue by recursively rendering the wordcloud if it detects that words have been dropped out. Each recursion would decrease the applied font-size by a scale factor. The recursion will bail out after some maximum attempts is reached, and a console warning will be thrown to the user informating that the words cannot be rendered in the wordcloud. The following example below demonstrates this scenario:
+
+<Playground>
+  <ReactWordcloud
+    size={[200, 200]}
+    words={[
+      { text: "this_is_a_long_word_and_also_the_most_frequent", value: 45 },
+      { text: "some_word", value: 35 },
+      { text: "another_word", value: 20 }
+    ]}
+  />
+</Playground>
+
+If you see this console warning, it is recommended that you address it in the following few common ways:
+
+- Increase the wordcloud size (either using the `size` prop or the parent container).
+- Reduce the `options.fontSizes` values.
+- Avoid rendering long words at vertical angles (i.e. 90 degrees). Browser heights are more limited than widths, and the long words may not fit within the wordcloud height. You can control rotation angles using `rotationAngles` and `rotations` in the `options` props.
diff --git a/docs/usage/options.mdx b/docs/usage/options.mdx
@@ -12,6 +12,65 @@ import words from "./words";
 
 You can customize many visual and layout properties of `ReactWordcloud` by using the `options` prop.
 
+## Colors
+
+`ReactWordcloud` will randomnly apply colors from an array of color hex codes.
+
+<Playground>
+  <ReactWordcloud
+    options={{
+      colors: ["#1f77b4", "#9467bd", "#8c564b"]
+    }}
+    words={words}
+  />
+</Playground>
+
+## Font Styles
+
+Configure wordfont styles using the `fontFamily`, `fontSizes`, `fontStyle`, `fontWeight` options.
+
+<Playground>
+  <ReactWordcloud
+    options={{
+      fontFamily: "courier new",
+      fontSizes: [10, 20],
+      fontStyle: "italic",
+      fontWeight: "bold"
+    }}
+    words={words}
+  />
+</Playground>
+
+## Rotations
+
+By default `ReactWordcloud` will apply random rotations if the `rotations` option is not specified. If `rotations` option is specified, it will use evenly-divided angles from the `rotationAngles` option based on the `rotations` value. The following example demonstrates using rotation angles of `0`, `45` and `90` degrees (i.e. `rotations = 3` and `rotationAngles=[0, 90]`).
+
+<Playground>
+  <ReactWordcloud
+    options={{
+      rotations: 3,
+      rotationAngles: [0, 90]
+    }}
+    words={words}
+  />
+</Playground>
+
+## Layout
+
+Configure the wordcloud layout by using the `scale`, `spiral` options.
+
+<Playground>
+  <ReactWordcloud
+    options={{
+      scale: "log",
+      spiral: "rectangular"
+    }}
+    words={words}
+  />
+</Playground>
+
+## Interactive
+
 Use the code editor to edit and play around with some of these options!
 
 <Playground>
@@ -27,13 +86,13 @@ Use the code editor to edit and play around with some of these options!
         "#8c564b"
       ],
       enableTooltip: true,
-      fontFamily: "times new roman",
-      fontSizes: [5, 40],
+      fontFamily: "impact",
+      fontSizes: [5, 60],
       fontStyle: "normal",
       fontWeight: "normal",
       padding: 1,
       rotations: 3,
-      rotationAngles: [-90, 90],
+      rotationAngles: [0, 90],
       scale: "sqrt",
       spiral: "archimedean",
       transitionDuration: 1000
diff --git a/docs/usage/transitions.mdx b/docs/usage/transitions.mdx
@@ -19,7 +19,7 @@ import words from "./words";
     const [wordsFlag, toggleWordsFlag] = useState(false);
     const updatedOptions = optionsFlag
       ? defaultOptions
-      : { ...defaultOptions, fontFamily: "times new roman" };
+      : { ...defaultOptions, fontFamily: "impact" };
     const updatedWords = wordsFlag ? words : words.slice(0, 50);
     return (
       <>
diff --git a/doczrc.js b/doczrc.js
@@ -8,6 +8,7 @@ export default {
       menu: ['Props', 'Basic', 'Size', 'Callbacks', 'Transitions', 'Options'],
     },
     'Wordcloud Generator',
+    'FAQ',
     'CHANGELOG',
     { name: 'Github', href: 'https://github.com/chrisrzhou/react-wordcloud' },
   ],
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "react-wordcloud",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Simple React + D3 wordcloud component with powerful features.",
   "main": "dist/index.js",
   "module": "dist/index.module.js",
diff --git a/src/index.tsx b/src/index.tsx
@@ -11,6 +11,9 @@ const { useEffect } = React;
 
 const d3 = { cloud: d3Cloud };
 
+const MAX_LAYOUT_ATTEMPTS = 10;
+const SHRINK_FACTOR = 0.95;
+
 export const defaultCallbacks: Callbacks = {
   getWordTooltip: ({ text, value }: Word) => `${text} (${value})`,
 };
@@ -19,7 +22,7 @@ export const defaultOptions: Options = {
   colors: getDefaultColors(),
   enableTooltip: true,
   fontFamily: 'times new roman',
-  fontSizes: [5, 40],
+  fontSizes: [4, 32],
   fontStyle: 'normal',
   fontWeight: 'normal',
   padding: 1,
@@ -77,7 +80,6 @@ function Wordcloud({
 
   // render viz
   useEffect(() => {
-    const layout = d3.cloud();
     const mergedCallbacks = { ...defaultCallbacks, ...callbacks };
     const mergedOptions = { ...defaultOptions, ...options };
 
@@ -93,57 +95,61 @@ function Wordcloud({
         spiral,
         scale,
       } = mergedOptions;
-      const ctx = document.createElement('canvas').getContext('2d');
-      ctx.font = `${fontSizes[1]}px ${fontFamily}`;
-
-      if (rotations !== undefined) {
-        layout.rotate(() => rotate(rotations, rotationAngles));
-      }
 
       const sortedWords = words
         .concat()
         .sort((x, y) => descending(x.value, y.value))
         .slice(0, maxWords);
 
-      layout
+      const layout = d3
+        .cloud()
         .size(size)
         .padding(padding)
         .words(sortedWords)
+        .rotate(() => {
+          if (rotations === undefined) {
+            // default rotation algorithm
+            return (~~(Math.random() * 6) - 3) * 30;
+          } else {
+            return rotate(rotations, rotationAngles);
+          }
+        })
         .spiral(spiral)
         .text(getText)
         .font(fontFamily)
         .fontStyle(fontStyle)
         .fontWeight(fontWeight);
 
-      const draw = (fontSizes: MinMaxPair): void => {
+      const draw = (fontSizes: MinMaxPair, attempts: number = 1): void => {
         layout
           .fontSize((word: Word) => {
-            const fontScale = getFontScale(words, fontSizes, scale);
+            const fontScale = getFontScale(sortedWords, fontSizes, scale);
             return fontScale(word.value);
           })
-          .on('end', () => {
-            // For each word, we derive the x/y width projections based on the
-            // rotation angle.  Calculate the scale factor of the respective
-            // width projections against the svg container width and height.
-            // Apply a universal font-size scaling (maximum value = 1) in render
-            let widthX = 0;
-            let widthY = 0;
-            sortedWords.forEach(word => {
-              const wordWidth = ctx.measureText(word.text).width * 1.1;
-              const angle = (word.rotate / 180) * Math.PI;
-              widthX = Math.max(wordWidth * Math.cos(angle), widthX);
-              widthY = Math.max(wordWidth * Math.sin(angle), widthY);
-            });
-            const scaleFactorX = size[0] / widthX;
-            const scaleFactorY = size[1] / widthY;
-            const scaleFactor = Math.min(1, scaleFactorX, scaleFactorY);
-            render(
-              selection,
-              sortedWords,
-              mergedOptions,
-              mergedCallbacks,
-              scaleFactor,
-            );
+          .on('end', (computedWords: Word[]) => {
+            if (
+              sortedWords.length !== computedWords.length &&
+              attempts <= MAX_LAYOUT_ATTEMPTS
+            ) {
+              // KNOWN ISSUE: Unable to render long words with high frequency.
+              // (https://github.com/jasondavies/d3-cloud/issues/36)
+              // Recursively layout and decrease font-sizes by a SHRINK_FACTOR.
+              // Bail out with a warning message after MAX_LAYOUT_ATTEMPTS.
+              if (attempts === MAX_LAYOUT_ATTEMPTS) {
+                console.warn(
+                  `Unable to layout ${sortedWords.length -
+                    computedWords.length} word(s) after ${attempts} attempts.  Consider: (1) Increasing the container/component size. (2) Lowering the max font size. (3) Limiting the rotation angles.`,
+                );
+              }
+              const minFontSize = Math.max(fontSizes[0] * SHRINK_FACTOR, 1);
+              const maxFontSize = Math.max(
+                fontSizes[1] * SHRINK_FACTOR,
+                minFontSize,
+              );
+              draw([minFontSize, maxFontSize], attempts + 1);
+            } else {
+              render(selection, computedWords, mergedOptions, mergedCallbacks);
+            }
           })
           .start();
       };
@@ -157,7 +163,7 @@ function Wordcloud({
 Wordcloud.defaultProps = {
   callbacks: defaultCallbacks,
   maxWords: 100,
-  minSize: [200, 150],
+  minSize: [300, 300],
   options: defaultOptions,
 };
 
diff --git a/src/render.ts b/src/render.ts
@@ -11,7 +11,6 @@ export default function render(
   words: Word[],
   options: Options,
   callbacks: Callbacks,
-  scaleFactor: number,
 ): void {
   const {
     getWordColor,
@@ -22,7 +21,6 @@ export default function render(
   } = callbacks;
   const { colors, enableTooltip, fontStyle, fontWeight } = options;
   const { fontFamily, transitionDuration } = options;
-  const scaledFontSize = getFontSize(scaleFactor);
 
   function getFill(word: Word): string {
     return getWordColor ? getWordColor(word) : choose(colors);
@@ -63,7 +61,7 @@ export default function render(
     .attr('transform', 'translate(0, 0) rotate(0)')
     .transition()
     .duration(transitionDuration)
-    .attr('font-size', scaledFontSize)
+    .attr('font-size', getFontSize)
     .attr('transform', getTransform)
     .text(getText);
 
@@ -73,7 +71,7 @@ export default function render(
     .duration(transitionDuration)
     .attr('fill', getFill)
     .attr('font-family', fontFamily)
-    .attr('font-size', scaledFontSize)
+    .attr('font-size', getFontSize)
     .attr('transform', getTransform)
     .text(getText);
 
diff --git a/src/utils.ts b/src/utils.ts
@@ -22,10 +22,10 @@ export function getFontScale(
   const maxSize = d3.max(words, (word: Word) => word.value);
   const Scales = {
     [Scale.Linear]: d3.scaleLinear,
-    [Scale.Log]: d3.scaleLinear,
-    [Scale.Sqrt]: d3.scaleLinear,
+    [Scale.Log]: d3.scaleLog,
+    [Scale.Sqrt]: d3.scaleSqrt,
   };
-  const fontScale = Scales[scale]()
+  const fontScale = (Scales[scale] || d3.scaleLinear)()
     .domain([minSize, maxSize])
     .range(fontSizes);
   return fontScale;
@@ -35,10 +35,8 @@ export function getText(word: Word): string {
   return word.text;
 }
 
-export function getFontSize(scaleFactor: number): (word: Word) => string {
-  return function(word: Word): string {
-    return `${word.size * scaleFactor}px`;
-  };
+export function getFontSize(word: Word): string {
+  return `${word.size}px`;
 }
 
 export function getTransform(word: Word): string {
@@ -56,7 +54,7 @@ export function rotate(rotations: number, rotationAngles: MinMaxPair): number {
   if (rotations === 1) {
     angles = [rotationAngles[0]];
   } else {
-    angles = rotationAngles;
+    angles = [...rotationAngles];
     const increment = (rotationAngles[1] - rotationAngles[0]) / (rotations - 1);
     let angle = rotationAngles[0] + increment;
     while (angle < rotationAngles[1]) {

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "react-wordcloud",`
`3`		`- "version": "1.0.4",`
	`3`	`+ "version": "1.0.5",`
`4`	`4`	`"description": "Simple React + D3 wordcloud component with powerful features.",`
`5`	`5`	`"main": "dist/index.js",`
`6`	`6`	`"module": "dist/index.module.js",`