@nebula.js/sn-grid-chart/README.md

A grid from two dimensions with symbols of varying size based on a measure.

# @nebula.js/sn-grid-chart

The grid chart uses symbols of varying size sorted in a grid to visualize a measure across two dimensions.
The measure is the metric that determines the size of the symbol in each crossing.

## Requirements

Requires `@nebula.js/stardust` version `1.2.0` or later.

## Installing

If you use npm: `npm install @nebula.js/sn-grid-chart`. You can also load through the script tag directly from [https://unpkg.com](https://unpkg.com/@nebula.js/sn-grid-chart).

## Usage

```js
import { embed } from '@nebula.js/stardust';
import gridChart from '@nebula.js/sn-grid-chart';

// 'app' is an enigma app model
const nuked = embed(app, {
  types: [
    {
      // register grid chart
      name: 'sn-grid-chart',
      load: () => Promise.resolve(gridChart),
    },
  ],
});

// Rendering a simple grid chart
nuked.render({
  element: document.querySelector('.grid'),
  type: 'sn-grid-chart',
  fields: ['Country', 'Year', '=Sum(Population)'],
  properties: {
    title: 'The historical populations of some European countries',
  },
});
```

## More examples

### Change symbol size and shape

The size and shape of the symbols can be modified.

```js
// Rendering a grid chart with customized symbols
nuked.render({
  element: document.querySelector('.grid'),
  type: 'sn-grid-chart',
  // fields: ['Country', 'Year', '=Sum(Population)'],
  properties: {
    title: 'The historical populations of some European countries',
    dataPoint: {
      rangeBubbleSizes: [0.25, 0.85],
      symbol: 'star',
    },
  },
});
```

### Customize the look of the chart

You can color the symbol by measure and add a legend to show more
information about the measure. The axis titles can be hidden
and the gridlines can be shown to further improve the look.

```js
// Rendering a customized grid chart
nuked.render({
  element: document.querySelector('.grid'),
  type: 'sn-grid-chart',

  // Define all `fields` in `properties`
  properties: {
    title: 'The historical populations of some European countries',
    qHyperCubeDef: {
      qDimensions: [
        {
          qDef: { qFieldDefs: ['Country'] },
        },
        {
          qDef: { qFieldDefs: ['Year'] },

          qAttributeExpressions: [
            {
              qExpression: 'Sum(Population)',
              id: 'colorByAlternative',
            },
          ],
        },
      ],
      qMeasures: [
        {
          qDef: {
            qDef: 'Sum(Population)',
          },
        },
      ],
      qMode: 'T',
      qAlwaysFullyExpanded: true,
    },
    color: {
      auto: false,
      mode: 'byMeasure',
      measureScheme: 'dg',
      reverseScheme: true,
    },
    legend: {
      show: true,
      dock: 'auto',
      showTitle: true,
    },
    xAxis: {
      show: 'label',
      dock: 'near',
      gridLines: true,
    },
    yAxis: {
      show: 'label',
      dock: 'near',
      gridLines: true,
    },
  },
});
```

## Grid chart plugins

A plugin can be passed into a grid chart to add or modify its capability
or visual appearance.
A plugin needs to be defined before it can be rendered together with the chart.

```js
// Step 1: define the plugin

// Modifying the look of the existing point component
const pointPlugin = {
  info: {
    name: 'point-plugin',
    type: 'component-definition',
  },
  fn: ({ layout, keys }) => {
    const componentDefinition = {
      type: 'point',

      // Provide the same name as the exisiting point component to override it
      key: keys.COMPONENT.POINT,
      settings: {
        strokeWidth: '2px',
        stroke: 'dimgray',

        // Using data property 'd' and layout as input for helper functions
        size: (d) => getSizeInLogarithmScale(d, layout),
        fill: (d) => getColorBasedOnMedian(d),
      },
    };
    return componentDefinition;
  },
};

// Step 2: passing the plugin definition into the render function

// Rendering a grid chart with plugins
nuked.render({
  element: document.getElementById('object'),
  type: 'sn-grid-chart',
  fields: ['Country', 'Year', '=Sum(Population)'],
  plugins: [pointPlugin],
  properties: {
    title: 'The historical population of some European countries',
    xAxis: { show: 'labels', gridLines: true },
    yAxis: { show: 'labels', gridLines: true },
  },
});
```

The plugin definition is an object, with two properties `info` and `fn`.
The `fn` returns a `picasso.js` component. To build this component,
some important chart internals are passed into the argument object of `fn`.

```js
// Structure of the argument object of fn
const pluginArgs = {
  layout,
  keys: {
    SCALE: {
      X,
      Y,
    },
    COMPONENT: {
      X_AXIS,
      Y_AXIS,
      POINT,
    },
    COLLECTION: {
      MAIN,
    },
  },
};
```

With plugins, you can either add new components or modify existing components
of the grid chart.

### Add new components

The new component can be a standard Picasso component
or a custom Picasso component. Here we demo a custom component
which add labels next to the grid bubbles.

```js
// Implementing a custom labels plugin, so that we can use it later
const labelsPluginDefinition = {
  info: {
    componentName: 'custom-labels-plugin',
    name: 'custom-labels-plugin',
    type: 'custom-component',
  },
  fn: () => {
    const implementation = {
      require: ['chart', 'renderer'],
      render() {
        const { items } = this.chart.component('point-component').data;
        const scale = this.chart.scales();
        const { width, height } = this.rect;
        const labels = items.map((item) => ({
          type: 'text',
          text: item.size.label,
          x: (scale.x(item.x.value) + scale.x.bandwidth() * 0.5) * width,
          y: (scale.y(item.y.value) + scale.y.bandwidth() * 0.2) * height,
          anchor: 'middle',
          fill: 'dimgray',
        }));
        return labels;
      },
    };
    return implementation;
  },
};

// Using the labels plugin, defined above
const labelsPlugin = {
  info: {
    name: 'labels',
    type: 'component-definition',
  },
  fn: ({ keys }) => {
    const componentDefinition = {
      // The type has to match with the componentName of the labels plugin definition above
      type: 'custom-labels-plugin',
      key: 'my-labels',
    };
    return componentDefinition;
  },
};
```

### Modify existing components

As an example, the positions and the appearance of the axes can be
modified completely by plugins.

To overide an existing component, `fn` should returns a `picasso.js` component
that has the same `key` as the existing component (`keys.COMPONENT.X_AXIS` in
this example)

```js
// Modifying the look and the position of the x-axis
const xAxisPlugin = {
  info: {
    name: 'x-axis-plugin',
    type: 'component-definition',
  },
  fn: ({ keys, layout }) => {
    const componentDefinition = {
      type: 'axis',

      // Provide the same name as the exisiting x-axis component to override it
      key: keys.COMPONENT.X_AXIS,
      layout: { dock: 'top' },
      settings: {
        labels: {
          fontFamily: 'Cambria, serif',
          fontSize: '15px',
          fill: 'dimgray',
        },
        line: { stroke: 'gray' },
      },
    };
    return componentDefinition;
  },
};

// y-axis plugin can be defined with similar code
// ...
```

### Plugins disclaimer

- The plugins API is still experimental.
- We can not guarantee our charts to be compatible with all different settings, especially when modifying existing components.