gridora v0.1.1

Gridora

'Gridora' is a React based Grid component that is designed for data visualization and editor usecases. The name 'Gridora' is inspired from 'Ghidorah', the King of Monsters (from the Godzilla Universe) as depicted below.

Source: https://www.deviantart.com/eatalllot/art/King-Ghidorah-583185889

All Hail, King Gridora!

How to Use (101)

Enough monkey business, back to the real thing. Gridora can be used in any existing React project or you can use the webpacked bundle to include Gridora with all its dependencies.

Below is how it looks in its natural habitat (and default styles) -

Install the package

npm install --save @visualbi/gridora

Flexibility by Design

The design principle for Gridora revolves around 'Keep it simple, silly'. The component promotes extensibility instead of inbuilt-features to keep it light and customizable for different usecases. The idea is that the component will provide provisions and default behaviour and it is left to the end-user (developer) to build features around it.

Some of the most important concepts to understand with using Gridora are -

1. Controlled Component / Stateless: Gridora does not manage state at all instead promotes the developer to manage the state externally and on any change pass the updated properties. Internally Gridora uses Memoization and multiple optimizations to minimize re-rendering.

2. Custom Rendering: The component supports passing custom React components as Cell Renderer (View) and optionally you can provide Active Cell Renderer (Input) too for each column. If you dont provide then the default renderers (label and textbox) get rendered.

3. Cell State: Each cell can have its own state that you can pass as a Map to the component, CellStates have a set of inbuilt properties and you can extend it with your own properties and use it in your custom renderers (active or view)

4. CSS Classes: The CSS is completely customizable, you can override easily by adding specific rules to the different classNames. Class names have been kept semantic in nature and hierarchical for easier understanding.

5. Limited Dependencies: Any dependency used within Gridora are minimal in nature and have < 10 kb impact in filesize. This helps us keep the component as light weight as possible for embedded use and faster performance.

Supported Features

Below are the features that are supported today, more will be added over the course of time and as requests come up.

Fixed Columns Rendering

You can fix the columns that you pass to the cols property by including the fixed property and Gridora will automatically fix these columns and manage the scroll behaviour horizontally and vertically.

Note: We are assuming you are smart enough to realize that you cannot have fixed columns in between, so make sure you set this property only to the columns at the start of your cols definition, else all hell will break loose!

To let you in on the secret, Gridora renders two Grids - one for Fixed Columns and the other for Scrollable Columns and then synchronizes the scroll between the two and the header (like Magic, I know right).

Hierarchical Rendering

Gridora in all its glory, supports hierarchical rendering of columns. By passing a simple hierarchical true property to the column and including a number based level in your rows definition will show create the hierarchy in the rows.

The concept of the level property is simple, pass the level property in the same order as rendering of the rows, this restriction gives us a big optimization bump.

In a simple example, refer the screenshot above and the corresponding level shown in the bracket below -

 Net Profit (0)
    Revenue (1)
       Copper Sold (2)
         Mill Throughput (3)
         Change in Stock (3)
         ...
    Total Cost (1)
         Production Cost (2)
              ...
         Realisation Cost (2)

Note: We are again assuming that you will be nice and only make one column as hierarchical. Don't trumpify the feature :pray:

Inbuilt Virtualization

Gridora's row and columns rendering is completely virtualized using react-window (freaking amazing library). So only the columns and rows that are visible (and some overscan horizontally and vertically) are actually rendered on the DOM. When the user starts scrolling, virtualization kicks in and does its work.

This way you can pass a large dataset and need not worry about crashing the browser or frustrating the user.

Active Cell, Columns and Rows

Using the above mentioned Cell State concept and events, Gridora supports Cell, Row and Column Selection. Based on the selection some callback methods are also added to listen to the selection events.

Custom Cell Renderers

Pass any React component that you want for a cell, Gridora passes the cell value, cell state and key as props to this component. For each col you can pass a cell renderer for view time and an active cell renderer for input time (both are optional and mutually exclusive)

Nested Columns Rendering

You can pass an array of different colGroups to the Gridora, this lets it render a hierarchy of columns in the Grid Header. The catch here is that the order of the colGroups and the cols inside each group should be exactly in the order of their rendering.

Commit / Reject Change of Cell Value

For any cell value that gets changed using the callback functions you can choose to accept the change or reject the change.

Primitive Validation

There is a primitive validation support for cells, and it can be used in the onGridChange events when Gridora passes the errors, validated values and the raw values. This validation can also be used to show errors in the cells.

Ref Support

Gridora supports two refs, you can pass the primary ref property to get access to the methods exposed by the component itself and activeCellRef to get access to the current active cell instance. We recommend using React.createRef() it is cleaner and error-free.

Keyboard Support

Below keyboard behaviours are currently supported -

• You can use arrow keys to navigate between the cells, this moves the active cell selection
• You can use Enter to accept an input change in the cells
• You can use Esc to reject an input change in the cells
• You can use F2 to edit the active cell.

Advanced Examples

You can refer to the Storybook included in this repository to see how to use Gridora for advanced usecases. Their corresponding guides will also be updated in this repository.

To run storybook, follow below commands

git clone https://github.com/visualbis/gridora.git
cd gridora
npm install

# Start storybook
npm run storybook

Development Usage

To run Gridora in development, fork this repository and use the below commands to get started

npm install

# TBD