bubble-balls/README.md

This is d3 wrapper which makes the process of creating draggable and divided into groups amazing bubble charts much easier. You can use relative units to scale the bubbles to fit the screen width. Want to rescale the bubbles to fit the container? No probl

# Demo

https://benjamindickens.github.io/bubble-balls-demo/

# Installation

```bash
npm install bubble-balls
```

# Initialization

###### HTML

1) Add a container to your page with "balls" class.

```bash
<div class="balls"></div>
```

2) If you intend to **use relative** units you have to add another element inside with "balls-unit-example" class.

```bash
<div class="balls">
    <div class="balls-unit-example"></div> 
</div>
```

###### JS

3) Initialize the app in your js file and pass data with default set up or modify it manually with the option object.

```bash
import Balls from "bubble-balls";

new Balls(".balls", data, options)

```

###### Notes

Unfortunately right now you can't use absolutely the same data object for different instances on one page.

# Options

###### data for balls

You can set styles right away for each ball like this 

```bash
{
id: 1,
title: "Paris",
color: "royalblue",
background: "white",
borderColor: "royalblue",
}
```

or width image as a background

```bash
{
id: 4,
title: "Paris"
img: "/images/pages/home/values/common/bg-big.svg",
color: "yellow",
background: "gray",
borderColor: "yellow",
borderWidth: 5,
}
```

###### measurement units

1) Choose a measurement unit you are going to use in your app.

```bash
measurementUnit.name: "px" / "em" / "rem" || default: "px";
```

2) If the value you set is relative you also need to specify it in css for further calculation. It has to be equal to 10px.

Example with rem:
```bash
html {
  font-size: 0.69vw; //1440
}

.balls-unit-example {
  width: 1rem; //1rem ~ 10px at 1440 resolution of screen
}

```

###### on

Here you can add your custom functions.

```bash
on: {
      mouseover: () => { your code ...} || default: null,
      mouseout: func || default: null,
      afterInit: func || default: null,
    }
```

###### titlePropertyName
To specify what propery you are going to use for titles of balls.

```bash
titlePropertyName: "string" || default: "title"; 
```

###### imgPropertyName
To specify what propery you are going to use for titles of balls.

```bash
imgPropertyName = "string" || default: "img";
```


###### groupParam
Property name you use to divide babbles into groups for example by "country"

```bash
groupParam: {
    name: "string" || default: null,
};
```

###### radiusParam
Set property name to specify calculation radius of balls with dynamic scale by d3

```bash
radiusParam: {
    name: "string" || null,
    min: 'number' || this.measurementUnit.name === "px" ? 40 : 4,
};
```

###### draggable
To disable drag effect on balls set it to false.

```bash
draggable = "boolean" || default: true;
```

###### defaultStyles
You can modify default styles

```bash
defaultStyles: {
    color: "color" || default: "#000000",
    background: "color" || default: "#FFFFFF",
    borderColor: "color" || default: "#000000" ,
    borderWidth: "px" || default: 2,
}
```

###### groupsStyles
You can pass array width style objects. Those will apply to groups follow their indexe. ANother way is to specify styles for cirtain group by its group index or name if it sets.

```bash
groupsStyles: [
              {
               color: "royalblue",
               background: "white",
               borderColor: "royalblue",
               borderWidth: 0,
              },
               
               or with group name 
               
              {
               groupName: index of group or group name you specify 1,10, "General Motors"
               color: "yellow",
               background: "red",
               borderColor: "yellow",
               borderWidth: 5,
              },
              ] || default: null;
```

###### dynamicFontSize
Recalculate a font size of a title to fit a container and set min possible font.

```bash
dynamicFontSize: {
    init: options?.dynamicFontSize?.init || true,
    min: "number" || default: 10 or 1 if (measurementUnit.name !== "px" ),
};
```

###### forces
Specify forces applied to the balls 

```bash
forces: {
    collisionMultiplier: "number" || default: 1.2, //create space between balls
};
```

###### dimensions
```bash
dimensions: {
    padding: "number" || default : this.measurementUnit.name === "px" ? 10 : 1, //padding on edges of the container to avoid overlaping.
    defaultRadius: "number" || default : this.measurementUnit.name === "px" ? 60 : 6, //default value if a radius property is not set and radiusParam not specify as well
    cols: numbers || default : 1, // specify how many columns for different group the container has it will add forces point
};
```

###### breakpoint

The value of @media (in pixels).

```bash
breakpoint: number || default: 667;
```