Welcome to the contribution tutorials and guidelines for d3plus 👋 There are two different places where you can contribute to this open source project:

1. Documentation and Examples on d3plus.org
2. Bugs and Features in the Source Code

D3plus users Storybook to build live examples that show the underlying @d3plus/react code and allows users to modify config settings in browser. The Storybook codebase is located in the docs folder, and all of the examples currently live in the docs/charts/ directory, grouped by their chart type (Bar Chart, Line Plot, etc).

Typically, they follow the following basic format:

export const NameOfExample = Template.bind({});
NameOfExample.args = {
  // config options go here
};
// The following line is optional, and is what allows UI 
// controls to be present underneath the source code.
NameOfExample.parameters = {controls: {include: [/* method list */]}};

When writing examples, please try to follow the following guidelines:

• The name of the Component you create will become the name in the UI, so in this case "NameOfExample" will become "Name Of Example" (more information on Storybook's auto-titles can be found here).
• Only include config methods that are pertanent to the example (ie. don't change things like the "legendPosition" because of personal preference).
• If possible, do not use external API links for things like "data" and "topojson". Wherever you can, either use a simple/small inline data Array or reference a static file added to the /static/data directory.
• When using accessor functions in your config, wrap them in the funcify helper function, which accepts 2 arguments: the Function itself, and a String representation of that Function. JavaScript does not have an ability to "stringify" Functions, which we need in order to show them in the code snippets, so this helper explicitly sets how they are to be displayed to the user. In most cases, the String representation should just be a copy of your Function surrounded by backticks (``).

When you have something ready for review or critique, submit a pull request.

If you are looking to contribute to the core source code of d3plus, start by cloning this monorepo:

git clone https://github.com/d3plus/d3plus.git

1. Install Node, if not already installed.

_{If on a Mac, we suggest using Homebrew to install packages on your machine. Once that's installed, you can install node (which includes npm) by running: brew install node}

2. Move into the newly cloned root directory, and install dependencies: pnpm install

And that's it! Your environment should be all set up and ready to start coding.

The codebase is split up into a series of smaller packages/modules, which allows users to install only the dependencies that they need. This repo uses pnpm workspaces to manage these packages, which lets them share common dependencies and scripts. Each package lives in the packages/<package_name> directory, and are released as scoped npm packages (ie. @d3plus/<package_name>).

Within each package directory, you will notice the following folder structure:

• 📂 dev/
• 📂 src/
• 📂 test/ (optional)
• 📄 index.js
• 📄 package.json
• 📄 README.md

All source code lives in the `src` directory, and adheres to a linting ruleset in the root of the repo (`.eslintrc`). The easiest way to follow the style guide is by installing a linter directly in your text editor, so that errors will be highlighted as you type. If your Pull Request does not match the project's linting style, it will not be merged.

### Running the Development Server

To start testing code live in a browser, with auto-compiling and hot reloading, type this into your shell:

```sh
pnpm --filter @d3plus/<package_name> run dev

If everything is set up correctly, your default browser will open http://localhost:4000/ and show the contents of the dev directory, including the umd directory which stores a compiled bundle (with dependencies) for you to use in your testing (this directory is in the .gitignore, and should never get pushed to the repo).

Most packages contain HTML files to copy/modify for testing, but here is the minimum boilerplate HTML that needs to be there:

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <script src="/umd/d3plus-<package_name>.full.js"></script>
  </head>
  <body>

  </body>
  <script>

    console.log(d3plus);

  </script>
</html>

The development server will recreate the umd directory any time the current package or any of it's dependent packages source files are modified. Once the rebuild has finished, your browser will hot reload (as well as when any dev file is changed).

All of the code documentation you see in the README.md file is generated automatically from the JSDoc formatted comments within each source file. To regenerate the documentation at any time, simply run:

pnpm --filter @d3plus/<package_name> run docs

This command is run automatically during the release process.

Any time you write a new feature for a module, if possible, you should also be write an accompanying test. D3plus let's you write functional tests using Mocha and JSDOM.

All tests need to be placed in the test directory, and the filenames should match up to the components in src with a suffix of -test.js. To run all tests, run:

pnpm --filter @d3plus/<package_name> test

This command will also test build errors and lint all files.

Here is an example of what a test file could look like:

import assert from "assert";
import it from "./jsdom.js"; // optional import, "it" is avaiable globally if not imported

it("example test title", () => {

  assert.strictEqual(true, true, "the truth test");

});

When you have something ready for review or critique, submit a pull request.