docs(website): new website

reactchartjs · Nov 11, 2021 · 46b35c9 · 46b35c9
1 parent 054e2de
commit 46b35c9
Show file tree

Hide file tree

Showing 58 changed files with 10,750 additions and 245 deletions.
diff --git a/.editorconfig b/.editorconfig
@@ -9,11 +9,3 @@ trim_trailing_whitespace = true
 insert_final_newline = true
 indent_style = space
 indent_size = 2
-
-[*.json]
-indent_style = space
-indent_size = 2
-
-[*.md]
-trim_trailing_whitespace = false
-indent_style = tab
diff --git a/README.md b/README.md
@@ -1,17 +1,17 @@
 <div align="center">
-	
+
 <h1>React components for <a href="https://www.chartjs.org">Chart.js</a> 📊📈</h1>
-	
+
 Simple yet flexible charts for your React app
-	
+
 [![version](https://img.shields.io/npm/v/react-chartjs-2.svg)](https://www.npmjs.com/package/react-chartjs-2)
 [![downloads](https://img.shields.io/npm/dm/react-chartjs-2.svg)](https://www.npmjs.com/package/react-chartjs-2)
 [![license](https://shields.io/badge/license-MIT-green)](http://opensource.org/licenses/MIT)
 
 <br />
 <a href="#quickstart">Quickstart</a>
 <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
-<a href="#examples">Examples</a>
+<a href="#docs">Docs</a>
 <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
 <a href="https://slack.cube.dev/?ref=eco-react-chartjs">Slack</a>
 <br />
@@ -38,239 +38,14 @@ import { Doughnut } from 'react-chartjs-2';
 
 Need an API to fetch data? Consider [Cube](https://cube.dev/?ref=eco-react-chartjs), an open-source API for data apps.
 
-## Examples
-
-Please see [live examples](https://reactchartjs.github.io/react-chartjs-2/) or their [source code](example).
-
-## Configure
-
-### Chart props
-
-```js
-  id?: string;
-  className?: string;
-  height?: number;
-  width?: number;
-  redraw?: boolean;
-  type: Chart.ChartType
-  data: Chart.ChartData | (canvas: HTMLCanvasElement | null) => Chart.ChartData;
-  options?: Chart.ChartOptions;
-  fallbackContent?: React.ReactNode;
-  plugins?: Chart.Plugin[];
-  getDatasetAtEvent?: (dataset: Chart.InteractionItem[], event: React.MouseEvent<HTMLCanvasElement>) => void;
-  getElementAtEvent?: (element: Chart.InteractionItem[], event: React.MouseEvent<HTMLCanvasElement>) => void;
-  getElementsAtEvent?: (elements: Chart.InteractionItem[], event: React.MouseEvent<HTMLCanvasElement>) => void;
-```
-
-In TypeScript, you can import chart props types like this:
-
-```ts
-import type { ChartProps } from 'react-chartjs-2';
-```
-
-#### id
-
-Type `string`
-Default: `undefined`
-
-ID attribute applied to the rendered canvas
-
-#### className
-
-Type `string`
-Default: `undefined`
-
-class attribute applied to the rendered canvas
-
-#### height
-
-Type: `number`
-Default: `150`
-
-Height attribute applied to the rendered canvas
-
-#### width
-
-Type: `number`
-Default: `300`
-
-Width attribute applied to the rendered canvas
-
-#### redraw
-
-Type: `boolean`
-Default: `false`
-
-If true, will tear down and redraw chart on all updates
-
-#### type
-
-Type: `'bar' | 'line' | 'scatter' | 'bubble' | 'pie' | 'doughnut' | 'polarArea' | 'radar'`
-
-Chart.js chart type (required only on ChartComponent)
-
-#### data (required)
-
-Type: `Chart.ChartData | (canvas: HTMLCanvasElement | null) => Chart.ChartData`
-
-The data object that is passed into the Chart.js chart ([more info](https://www.chartjs.org/docs/latest/getting-started/)).
-
-This can also be a function, that receives a canvas element and returns the data object.
-
-```tsx
-const data = canvas => {
-    const ctx = canvas.getContext('2d');
-    const g = ctx.createLinearGradient(...);
-
-    return {
-        datasets: [{
-            backgroundColor: g,
-            // ...the rest
-        }],
-    };
-}
-```
-
-#### options
-
-Type: `Chart.ChartOptions`
-
-The options object that is passed into the Chart.js chart ([more info](https://www.chartjs.org/docs/latest/general/options.html))
-
-### fallbackContent
-
-Type: `React.ReactNode`
-
-A fallback for when the canvas cannot be rendered. Can be used for accessible chart descriptions ([more info](https://www.chartjs.org/docs/latest/general/accessibility.html))
-
-#### plugins
-
-Type: `Chart.PluginServiceRegistrationOptions[]`
-
-The plugins array that is passed into the Chart.js chart ([more info](https://www.chartjs.org/docs/latest/developers/plugins.html))
-
-#### getDatasetAtEvent
-
-Type: `(dataset: Array<{}>, event: React.MouseEvent<HTMLCanvasElement>) => void`
-Default: `undefined`
-
-Proxy for Chart.js `getDatasetAtEvent`. Calls with dataset and triggering event
-
-#### getElementAtEvent
-
-Type: `(element: [{}], event: React.MouseEvent<HTMLCanvasElement>) => void`
-Default: `undefined`
-
-Proxy for Chart.js `getElementAtEvent`. Calls with single element array and triggering event
-
-#### getElementsAtEvent
-
-Type: `(elements: Array<{}>, event: React.MouseEvent<HTMLCanvasElement>) => void`
-Default: `undefined`
-
-Proxy for Chart.js `getElementsAtEvent`. Calls with element array and triggering event
-
-## FAQ
-
-### Why doesn't my chart maintain it's width/height?
-
-In order for Chart.js to obey the custom size you need to set `maintainAspectRatio` to false
-
-```tsx
-<Bar
-	data={data}
-	width={100}
-	height={50}
-	options={{ maintainAspectRatio: false }}
-/>
-```
-
-### How do I access my chart's instance?
-
-The Chart.js instance can be accessed by placing a ref to the element as:
-
-```tsx
-const App => {
-  const ref = useRef();
-
-  return <Doughnut ref={ref} data={data} options={options} />;
-};
-```
-
-### How do I access the canvas context?
-
-The canvas node and hence context can be accessed within the data function.
-This approach is useful when you want to keep your components pure.
-
-```tsx
-render() {
-  const data = (canvas) => {
-    const ctx = canvas.getContext('2d')
-    const gradient = ctx.createLinearGradient(0,0,100,0);
-
-    return {
-      backgroundColor: gradient
-      // ...the rest
-    }
-  }
-
-  return <Line data={data} />;
-}
-```
-
-## Additional Information
-
-### Defaults
-
-Chart.js defaults can be set by importing the `defaults` object:
-
-```tsx
-import { defaults } from 'react-chartjs-2';
-
-// Disable animating charts by default.
-defaults.animation = false;
-```
-
-If you want to bulk set properties, try using the [lodash.merge](https://lodash.com/docs/#merge) function. This function will do a deep recursive merge preserving previously set values that you don't want to update.
-
-````tsx
-import { defaults } from 'react-chartjs-2';
-import merge from 'lodash.merge';
-
-merge(defaults, {
-	animation: false,
-  line: {
-    borderColor: '#F85F73',
-  }
-});
-``` -->
-
-<!-- ### Chart.js object
-
-You can access the internal Chart.js object to register plugins or extend charts like this:
-
-```JavaScript
-import { Chart } from 'react-chartjs-2';
-
-componentWillMount() {
-  Chart.register({
-    afterDraw: function (chart, easing) {
-      // Plugin code.
-    }
-  });
-}
-````
-
-### Working with Multiple Datasets
-
-You will find that any event which causes the chart to re-render, such as hover tooltips, etc., will cause the first dataset to be copied over to other datasets, causing your lines and bars to merge together. This is because to track changes in the dataset series, the library needs a `key` to be specified - if none is found, it can't tell the difference between the datasets while updating. To get around this issue, you can take these two approaches:
-
-1. Add a `label` property on each dataset. By default, this library uses the `label` property as the key to distinguish datasets.
-2. Specify a different property to be used as a key by passing a `datasetKeyProvider` prop to your chart component, which would return a unique string value for each dataset.
-
-## Development
+# Docs
 
-**NOTE:** The source code for the component is in `src`. A transpiled CommonJS version (generated with Babel) is available in `dist` for use with node.js, browserify and webpack. A UMD bundle is also built to `dist`, which can be included without the need for any build system.
+- [Migration to v4](https://react-chartjs-2.netlify.app/docs/migration-to-v4)
+- [Working with datasets](https://react-chartjs-2.netlify.app/docs/working-with-datasets)
+- [Working with events](https://react-chartjs-2.netlify.app/docs/events)
+- [FAQ](https://react-chartjs-2.netlify.app/faq)
+- [Components](https://react-chartjs-2.netlify.app/components)
+- [Examples](https://react-chartjs-2.netlify.app/examples)
 
 ## License
 

diff --git a/src/types.ts b/src/types.ts
@@ -13,13 +13,41 @@ export interface ChartProps<
   TData = DefaultDataPoint<TType>,
   TLabel = unknown
 > extends CanvasHTMLAttributes<HTMLCanvasElement> {
+  /**
+   * Chart.js chart type
+   */
   type: TType;
+  /**
+   * The data object that is passed into the Chart.js chart
+   * @see https://www.chartjs.org/docs/latest/getting-started/
+   */
   data: ChartData<TType, TData, TLabel>;
+  /**
+   * The options object that is passed into the Chart.js chart
+   * @see https://www.chartjs.org/docs/latest/general/options.html
+   * @default {}
+   */
   options?: ChartOptions<TType>;
+  /**
+   * The plugins array that is passed into the Chart.js chart
+   * @see https://www.chartjs.org/docs/latest/developers/plugins.html
+   * @default []
+   */
   plugins?: Plugin<TType>[];
+  /**
+   * Teardown and redraw chart on everu update
+   * @default false
+   */
   redraw?: boolean;
+  /**
+   * Key name to identificate dataset
+   * @default 'label'
+   */
   datasetIdKey?: string;
   /**
+   * A fallback for when the canvas cannot be rendered. Can be used for accessible chart descriptions
+   * @see https://www.chartjs.org/docs/latest/general/accessibility.html
+   * @default null
    * @todo Replace with `children` prop.
    */
   fallbackContent?: ReactNode;

diff --git a/src/utils.ts b/src/utils.ts
@@ -124,7 +124,7 @@ export function getElementAtEvent(
 }
 
 /**
- * Get dataset element with dataset from mouse click event
+ * Get all dataset elements from mouse click event
  * @param chart - Chart.js instance
  * @param event - Mouse click event
  * @returns Dataset

diff --git a/website/.gitignore b/website/.gitignore
@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
diff --git a/website/README.md b/website/README.md
@@ -0,0 +1,33 @@
+# Website
+
+This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+```
+$ GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
diff --git a/website/babel.config.js b/website/babel.config.js
@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};