v1.2.0 (#37)

* update docs

* swap eslint for xo

* fix xo lint errors and convert ts->js

* add husky, split `*.d.ts` from source code, add home page

* update husky

* add doc for common issues, add remaining types

* fix build

* use spaces over tabs...

* cleanup

* finalize v1.2.0

* add netlify.toml

Author: chrisrzhou

.babelrc

@@ -5,7 +5,7 @@ root = true
 charset = utf-8
 end_of_line = lf
 indent_size = 2
-indent_style = space
+indent_style = tab
 insert_final_newline = true
 max_line_length = 80
 trim_trailing_whitespace = true

.editorconfig

@@ -1,5 +1,3 @@
-# Third party
-**/node_modules
-
-# Build
-dist/
+node_modules
+dist
+optimized-d3-cloud.js

.eslintignore

@@ -2,7 +2,7 @@
 node_modules
 
 # logs
-*.log*
+*.log
 
 # files and IDE
 .DS_STORE
@@ -11,5 +11,5 @@ node_modules
 *.swo
 
 # project
-dist
 .docz
+dist

.eslintrc.js

@@ -1,2 +1,3 @@
+docs/
 public/
 node_modules/

.gitignore

@@ -1,7 +1,24 @@
-# Change Log
+# Changelog
 
-All notable changes to this project will be documented in this file.
-See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+## [1.2.0](https://github.com/chrisrzhou/react-wordcloud/compare/v1.1.1...v1.2.0) (2020-03-07)
+
+This release is largely internal refactoring and updating dependencies, as well as 'de-typescripting' the codebase
+
+### API additions:
+
+- Improve rendering performance for larger clouds and multiple cloud instances with the `options.enableOptimizations` flag.
+
+### Small Typescript breaking changes:
+
+- `Spiral` and `Scale` enums are removed in favor of whitelisted string values. As part of moving to ambient declarations, these enums will not materialize in the compiled code.
+
+### Internal code changes:
+
+- Update underlying dependencies via `yarn upgrade --latest`. Remove a ton of unneeded dependencies and correctly move `@types/*` deps to `devDependencies`.
+- Remove custom `eslint`, `prettier` config and use `xo` for a simpler linting setup.
+- Add `husky` pre-push hook.
+- Update and improve documentation with `[email protected]`. Improved various doc pages (`Common Issues`) and added the `Optimizations` and `Home` page
+- Take the approach in various projects (e.g. [three](https://github.com/mrdoob/three.js/)) to "de-typescript" the codebase and use `*.d.ts` files for typing in development. Continue to expose Typescript types to consumers.
 
 ## [1.1.1](https://github.com/chrisrzhou/react-wordcloud/compare/v1.1.0...v1.1.1) (2019-09-27)
 
@@ -16,7 +33,7 @@ See [Conventional Commits](https://conventionalcommits.org) for commit guideline
 - Simplify typed code.
 - Expose `MouseEvent` object in `onWordClick`, `onWordMouseOut` and `onWordMouseOver` callbacks.
 
-**Minor Typescript API Changes**
+### Minor Typescript API Changes
 
 - Exported Typescript types for component props have been changed slightly due to refactoring.
 
@@ -38,28 +55,28 @@ Fix emitted types.
 
 ## [1.0.5](https://github.com/chrisrzhou/react-wordcloud/compare/v1.0.4...v1.0.5) (2019-03-16)
 
-### New:
+### 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:
+### 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

.npmignore

@@ -10,67 +10,44 @@ Simple React + D3 wordcloud component with powerful features. Uses the [`d3-clou
 yarn add react-wordcloud
 ```
 
-Note that `react-wordcloud` requires `react^16.10.0` as a peer dependency.
+Note that `react-wordcloud` requires `react^16.13.0` as a peer dependency.
 
 ## Examples
 
-### Documented Examples
-
 View all documented examples and gallery of `react-wordcloud` applications at https://react-wordcloud.netlify.com/.
 
-### Local Examples
-
 You can also run the examples locally:
 
 ```bash
 git clone [email protected]:chrisrzhou/react-wordcloud
 cd react-wordcloud && yarn && yarn dev
 ```
 
-### Basic Example (no props)
+### Codesandbox examples
+
+#### No props
 
 [![Edit react-wordcloud-simple](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/bgov9)
 
-### Responsive Example
+#### Responsive
 
 [![Edit react-wordcloud-simple](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/55sb8)
 
-### Configurable Options Example
+#### Configurable Options
 
 [![Edit react-wordcloud-interactive](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/fnk8w)
 
-### Callbacks Example
+#### Callbacks
 
 [![Edit react-wordcloud-interactive](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/4lecp)
 
-## Development
-
-### Main Dependencies
-
-- `react`
-- `d3`
-- `d3-cloud`
-- `tippy.js`
-
-### Codebase Overview
-
-- `index.tsx`: Pure React code that exposes an interface of props.
-- `render.ts`: Pure D3 code to render wordcloud given a valid D3 selection and other data.
-- `hooks.ts`: React hooks to construct and resize a responsive SVG container.
-- `types.ts`: Typescript types.
-- `utils.ts`: Various simple functions to compute derived data.
-
-The code is written in `typescript`, linted with `eslint` + `prettier`, and bundled with `rollup`. Examples and documentations are built with `docz`.
-
-Feel free to contribute by submitting a pull request.
-
 ## Wordcloud Generator
 
 Create wordclouds using this wordcloud generator: https://wordcloud-generator.netlify.com/
 
 Features supported:
 
 - Edit and Upload text inputs
-- Various NLP methods (stopwords, ngrams)
+- Various NLP features (stopwords, ngrams)
 - Wordcloud configurations
 - Export/save/share wordclouds

.prettierrc.js

@@ -0,0 +1,72 @@
+---
+name: Common Issues
+route: /common-issues
+---
+
+import { Playground } from "docz";
+import { useMemo, useState } from "react";
+
+import ReactWordcloud from "../src";
+import words from "./words";
+
+# Common Issues
+
+## Re-rendering issues
+
+It is a common scenario that 
+`react-wordcloud` will unintentionally re-render (i.e. grow from the center) when the `size`, `callbacks`, `options` props are updated.  Note that `react-wordcloud` is **unopinionated** about this rendering behavior since this is the default React behavior, namely that changes in props will re-render the component.
+
+You should instead try to define these props statically (e.g. outside of the component) or memoize them accordingly. The comparison example below shows how to avoid this issue with `useMemo`.
+
+<Playground>
+  {() => {
+    const [iteration, setIteration] = useState(0);
+    const size = [600, 300];  // this creates a new array when state updates
+    const memoizedSize = useMemo(() => [600, 300], []);  // memoized. You can also simply just define the size variable itself outside of the componenet
+    return (
+      <div>
+        <button onClick={() => setIteration(iteration + 1)}>
+          Click to re-render
+        </button>
+        <h3>Will re-render because the "size" prop is always recreated</h3>
+        <ReactWordcloud size={size} words={words} />
+        <h3>Will not re-render because the "size" prop is memoized</h3>
+        <ReactWordcloud size={memoizedSize} words={words} />
+      </div>
+    );
+  }}
+</Playground>
+
+## Performance issues
+
+Performance issues in the underlying `d3-cloud` layout can be encountered in these common situations:
+
+- Multiple instances of `react-wordcloud`.
+- Large `words` data.
+- High `maxWords` prop.
+- Large `fontSizes` with small `size` prop (or parent container size).
+
+The `options.enableOptimizations` flag can be uesd to solve the first two performance problems. For the other problems, you will have to experiment and pick ideal options to configure your wordclouds.
+
+## Dropped Words
+
+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: [#36](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 informing 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: 60 },
+      { text: "some_word", value: 30 },
+      { text: "another_word", value: 20 },
+    ]}
+  />
+</Playground>
+
+If you see this console warning, it is recommended that you address it in the following 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.