DEV Community: ReactGrid

Financial liquidity planner with ReactGrid and Chart.js

Patryk Eliasz — Mon, 08 Mar 2021 10:43:13 +0000

We made ReactGrid to compose your view with arbitrary cell order. In many components and tools in React ecosystem you have to keep the same data schema in all rows. Our component breaks out from the frame. You can add it to your project simply by running:

npm i @silevis/reactgrid

Even if you don't need it in your project right now, you can leave a ⭐ in our Github project.

Today we will show you how to build a liquidity planner - an app that provides a strategy for financial planning in a long term. Our app will provide entering, aggregating, and evaluating planned cash flows.

On the Internet, you can find many spreadsheets files that e.g. accountants and financial analysts use - one of them, as an inspiration, will be moved from spreadsheet to standalone, fully reactive React.js app. We also visualize common parameters that help in decision-making with the Chart.js library.

What is ReactGrid made for?

ReactGrid was designed to handle complex data displaying and editing in an arbitrary way. We depart from the rule of placing cells in the same order in every row - therefore you are able to add a spreadsheet-like experience to your React app.

Liquidity planner is one of the many cases, in which 90% of React data table components usage is insufficient to recreate the expected look and feel.

Planning app with ReactGrid

Before we start coding, we will talk about good practices that help to make predictable apps. Obviously, it's a good idea to apply them in all projects:

Separate the data from ReactGrid

The main concept of reactivity is updating your view every time your data changes. Very often we have no influence on the data structure, but we can map it to the structure that is the most convenient for us. Before the data becomes acceptable by ReactGrid or Chart.js we have to calculate a few variables in a repeatable way. This data lives only “for a moment” and should be independent from data and ReactGrid internal interfaces like Column and Row.

import * as React from "react";
import { ReactGrid, Row } from "@silevis/reactgrid";

const App = () => {
  const [rows, setRows] = React.useState<Row[]>(() => getReactGridRows());
  return (
    <ReactGrid
      rows={rows}
      ...{props}
    />
  );
};

Apply changes directly to the data

ReactGrid contains its own encapsulated state to manage many background functionalities, like virtual scrolling or rendering optimizations. This state is based on rows and columns - two necessary ReactGrid props. ReactGrid is read-only until you define your own changes handling function, but a good practice is to update data at its source. After that the cycle of reactivity concept is complete.

Be aware of updating data that is directly related with ReactGrid interfaces ⚠️

import * as React from "react";
import { ReactGrid, Row, CellChange } from "@silevis/reactgrid";

const App = () => {
  const [rows, setRows] = React.useState<Row[]>(() => getReactGridRows());

  const handleChanges = (changes: CellChange[]) => {
    changes.forEach((change) => {
      setRows(rows => [
        ...rows,
        // ...
      ])
    });
  };

  return (
    <ReactGrid
      rows={rows}
      onCellsChanged={handleChanges}
      {...props}
    />
  );
};

Use Typescript wherever it is possible

Typescript prevents us from possible bugs at runtime. We encourage you to use it, especially with ReactGrid. For cell templating reasons we introduced a few types of how the cell templating engine interfaces with ReactGrid. Thanks to this, you can safely transfer data between incompatible cells while interacting with them using the cell editor or, for example, pasting data from external sources or even other spreadsheets.

A concrete example will be shown in the next chapter, but for now, take a look at the tiny example of Typescript discriminating unions. Implemented in ReactGrid, CellChangeinterface type field allows you to ensure that the checked field on newCell really exists.

import { CellChange } from "@silevis/reactgrid";

const handleChanges = (changes: CellChange[]) => { // evaluates as `CellChange<CheckboxCell>[] | CellChange<Datecell>[] | ...`
  changes.forEach(change => {
    if (change.type === 'checkbox') {
      console.log(change.newCell.checked);
      console.log(change.previousCell.checked);
    }
    // ...
  });
};

Compose your cell styling and behavior

In most cases, you will use built-in cell templates like NumberCell or DateCell. ReactGrid allows you to style a cell and its behavior without introducing a new cell template, for example, "non-editable number cell with blue background". Instead, you can compose the functions as follows:

bottomLine(
  nonEditable(
    showZero(numberCell(yearlyGroupsDiff, "text-lg disabled font-bold"))
  )
)

Avoid merging metadata with cells

Since all of the cells have no idea where they are placed, it’s tempting to extend them with some metadata. By metadata we mean the data that was added to ReactGrid related interfaces (e.g. Row) by extending them with new attributes.

 /*
  * There should be no `isCollapsed` and `backgroundColor` metadata attributes
  */
const row: Row & { isCollapsed: boolean; backgroungColor?: "red" | "blue" } = {
  isCollapsed: true,
  backgroungColor: 'blue',
  rowId: 0,
  cells: [
    { type: "text", text: "John" },
    { type: "text", text: "Doe" }
  ]
};

You can also come across a similar situation that has arisen when some cells are related with each other - when building a tree list. Let’s have a look at the ChevronCell interface:

interface ChevronCell extends Cell {
  type: 'chevron';
  text: string;
  isExpanded?: boolean;
  hasChildren?: boolean;
  parentId?: Id;
  indent?: number;
}

Except for parentId (which can actually be a row, column, or another cell) you can only control its look. There is no place declaring tree structure, dependencies between cells, or other data. We recommend extracting this metadata. The easiest way is to move this logic into a separate React hook that will contain those variables/data/logic.

We will show you how to implement row toggling and working with tree-like structures in the next article.

What does this planner do?

We could debate financial issues for a long time, but there is not enough room for it so let's look at them in a nutshell. You can skip this chapter if you like.

You can place a new value only in light green cells (credit line, opening balance) or with white background (cash inflows and outflows). Grayed-out cells are read-only.

Two of them (opening balance and credit line) are just numbers. We merged types of cash flow into two. Each entry is called "group" and has its own title like "Travelling expenses" for outflow and "Sales" for inflow. Except for the title, all groups have an array of the amount of money spent/earned each month.

Groups are aggregated vertically (inflows and outflows separately) into a total inflow or outflow per month. The last column presents all of the totals in a calendar year.

"Cash in" and "Cash out" make up the "Total" row. This row and the other cells should update their content when sourcing data has changed or e.g. user typed a new value into the cell.

Some items remain to be explained (and it's the hardest thing to understand):

"Cumulative row" takes cash in the bank, adds "Cash in" and then subtracts "Cash out".
User can manipulate the value of a green cell "Cashbox/bank" and is called an "Opening balance". The rest of the cells in this row are filled automatically by moving already calculated value from the cumulative to the next month in the "Cashbox/bank".
these operations are repeated until all months are filled.

The last part is the "Credit line". Users can update it by typing it in. This variable is constant for all months and is used for calculating "Credit line overdraft" - in a nutshell - if the absolute value from "Cumulative" exceeds the given credit line, then the cell should display this result.

What about the chart? This part should give us an instant knowledge about the company's state of finance. In this case, we limit ourselves to display "Cashbox/bank" and "Credit Line Overdraft" as a line chart and cash inflow and outflow as bars.

Some examples

In the penultimate chapter, we discussed 5. tips for good app implementation with ReactGrid. We will not discuss every line of code, but only code fragments in terms of the above-mentioned tips on how to work with ReactGrid.

Separate the data from ReactGrid

App component named LiquidityPlanner has four React's useState hooks, each of them stores part of raw financial data. E. g. cashInflow is initiated with emptyInflows that comes from the rawData.ts file. This data has no connection with ReactGrid's interfaces and can be used directly by other components like charts.

const emptyMonthsValues: Values = [NaN, NaN, NaN, NaN, NaN, NaN, NaN, NaN, NaN, NaN, NaN, NaN];

export const inflows: CashInflow[] = [
  // ... 
  {
    title: "Other income",
    values: emptyMonthsValues
  }
  // ... 
];

Applying changes to the data

ReactGrid runs your changes handler function when you interact with the data displayed by the grid. Each change is applied by dispatching setCashInflow. To set updated inflows we used a technique called currying (more info), to apply particular change on desired groups (cashInflow).

import * as React from "react";
import { CellChange, NumberCell, ReactGrid } from "@silevis/reactgrid";

export const LiquidityPlanner: React.FC = () => {
  // ...
  const [cashInflow, setCashInflow] = React.useState(() => [...emptyInflows]);

  const handleChanges = (changes: CellChange[]) => {
    changes.forEach((change: CellChange<NumberCell>) => {
      // ...
      setCashInflow((cashInflow) => applyChange(change)(cashInflow));
      // ...
    });
  };

  return (
    <ReactGrid
      onCellsChanged={handleChanges}
      // ...
    />
  );
};

Implementing changes handling in this way closes the reactivity cycle, therefore our task of processing input data into outputs is fully repeatable and has no side effects.

Typescript + ReactGrid = ❤️

ReactGrid is built with Typescript and fully supports it. We also encourage you to use it in your projects. A real example from our app shows how we narrowed down the expected change object type exclusively to NumberCell, therefore you are sure that you are able to access only actually existing fields.

const handleChanges = (changes: CellChange[]) => {
  changes.forEach((change: CellChange<NumberCell>) => {
    if (change.rowId === CASHBOXBANK_ROW_ID && change.columnId === 1) {
      setOpeningBalance(change.newCell.value);
    }
    if (change.rowId === CREDITLINE_ROW_ID && change.columnId === 1) {
      setCreditLine(change.newCell.value);
    }
    // ...
  });
};

The other part is e. g. extending the set of built-in cell templates with your own. To be able to do it you have to pass the name of your custom Cell interface into a generic CellChange interface.

Of course, you are not obliged to move your project right now to Typescript, but we highly suggest using static typing.

Compose your cell styling and behavior

When you work with ReactGrid it's highly possible that you will need to achieve the same or similar behavior or styling on many cells. The solution is quite simple - small, reusable functions. Familiarity with documentation will definitely be useful.

export const textCell = (
  text: string,
  className = "",
  style?: CellStyle
): TextCell => ({ type: "text", text, className, style });

export const numberCell = (
  value: number,
  className = "",
  style?: CellStyle
): NumberCell => ({
  type: "number",
  value,
  className,
  style,
  format: numberFormat
});

export const nonEditable = (cell: DefaultCellTypes): DefaultCellTypes => ({
  ...cell,
  nonEditable: true
});

export const showZero = (cell: NumberCell): NumberCell => ({
  ...cell,
  nanToZero: true,
  hideZero: false
});

and the usage: a function that uses mentioned functions to fill up the cells array in a single row.

function getCashboxBankRow(title: string, cashboxBank: MonthlyValues): Row {
  return {
    rowId: CASHBOXBANK_ROW_ID,
    height: ROW_HEIGHT,
    cells: [
      nonEditable(textCell(title, "padding-left-lg")),
      ...months().map((_, idx) =>
        idx === 0
          ? numberCell(cashboxBank[idx], "light-green-bg")
          : nonEditable(showZero(numberCell(cashboxBank[idx], "disabled")))
      ),
      nonEditable(emptyTextCell)
    ]
  };
}

Live demo

We created a fully working liquidity planner example on codesandbox.io.
This sample runs with the ReactGrid MIT, we encourage you to visit a fully functional sample deployed at our website. There you can try extra features available only in the PRO version: fill handle, range selection, area copy/cut/paste. You can compare both versions here.

Summary

Liquidity planner is only one of many possible ReactGrid use cases when the standard data table is not enough.
The main purpose of this article was to show you five useful tips that help you start the ReactGrid project using good practices.

Don't forget to leave a ⭐ on our Github.

We encourage you to visit our official ReactGrid website,
where you will find the documentation and information what the PRO version of our component offers.

Bye 👋

How to build a table with concurrent horizontal and vertical sticky headers in pure CSS

Kamil Mysłek — Mon, 18 Jan 2021 13:35:59 +0000

While creating user interfaces, we often encounter the problem that there is more data in our tables than can be fitted in the visible viewport. To achieve
an excellent user experience on components like Gannt charts, data tables and spreadsheets, we often use the sticky CSS property on the header elements. This is a simple task when doing it only on one edge of the table.

But what if we want to display a huge table and therefore need sticky headers on more edges simultaneously? This is the exact problem we faced while building our ReactGrid and in this article we want to share the solution we have found.

In this guide, we will show you how to create the layout to achieve a native scroll behavior with sticky headers like those shown above without using any JavaScript.

What are the benefits of the proposed solution?

native support from modern browsers,
excellent user experience (intuitiveness, swiftness),
additional elements in the scrollable view do not affect the UX,
no JavaScript, only CSS and HTML,
works perfectly on touch devices,
avoids using z-index not to affect other elements on the website (needs z-index style values in Firefox with this solution).

You will learn how to place elements in the DOM and style them to achieve fully functional scrollable sticky panes using flexbox step by step. It's working and has been tested on the following browsers (remember, Firefox needs z-index style values).

Placing Elements in the DOM using FlexBox

The first and most important aspect is the correct order of the elements in the DOM because elements that appear later in the DOM will overlay other elements.

Let's imagine that we want to create a layout with sticky headers on each edge. Therefore we need to divide our surface into 9 panes. Of course, the same procedure also applies to a smaller number of sticky edges.

We place everything in two DIV tags. The first with overflow: auto CSS property to have a scrollable view. The second with the following CSS properties:

position: relative;
display: flex;
flex-wrap: wrap;
justify-content: flex-start;
align-items: flex-start.

The graphic above illustrates the proper DOM order of the elements. The first element should be the one in the center of the layout, let's call it "middle-center-pane". It's the only DIV element which has a relative position in its CSS styles. The next elements, in order from the least to the most important, are bottom-center-pane, middle-right-pane, top-center-pane and midlle-left-pane. These elements have sticky positions in CSS styles. The same situation applies to the elements located in the corners of the view. We placed them in the order: bottom-right-pane, bottom-left-pane, top-right-pane, top-left-pane.

Now we know in which order the panes should be placed to achieve the correct overlay behavior. However, we need more. For example, our top-left-pane is the last element in the DOM and will be rendered as the last one on the screen. What we need to do is to change the visual order of the elements. This can be achieved by using the CSS order property.

Let's use the illustration above and place an arrow to help us sort the elements in the right order. We need to go from the top left corner to the bottom right corner. This will make it easier for us to create a table to define the CSS flex order property for our sticky header elements.

We have created a solid basis to achieve the desired behavior. The panes are positioned in the right order and their overlay behavior is as expected. Now we need to set additional required CSS values for them. For our sticky header elements we should set position: sticky and the proper top, right, left and bottom CSS values.

Now we can set the size of the panes. First, we set the width and the height of the "scrollable-element". Of course, it needs to be smaller than the content, to display some scrollbars. Then, the width and the height of the "panes-wrapper" should be the sums of the widths and heights of containing panes.

If you have reached this step, your result might already be working as expected, but you have probably noticed that the bottom panes are covered by the top panes while scrolling. The same behavior also happens to the left and right panes. To avoid this overlay we need to add some margins to the panes, so that the bottom and top panes, and also the left and right panes push each other away.

At the beginning of the article it was mentioned that if you want to be compatible with Mozilla Firefox browser you need to set z-index CSS style to some elements. The table below shows the required z-index values.

Summary & example application

If you set all properties as shown in this article, you will be able to achieve the expected result. We also prepared a quick example which allows you to look at the whole implementation. Feel free to use our experience and save time while trying to achieve a satisfactory outcome or try our ReactGrid.

Have fun :)

How to integrate ReactGrid with Chart.js?

Patryk Eliasz — Tue, 12 Jan 2021 08:51:18 +0000

ReactGrid is a React.js component for displaying and editing data in a spreadsheet-like way. This guide shows you how to integrate it with the well-known pure Javascript library - Chart.js.

Why ReactGrid?

There are plenty of different data tables available on the Internet, which perform great if you want to display one object per row.
Each of these objects has to have exactly the same static properties, which are mapped to columns in the table.

ReactGrid was designed to be independent of your data model.
It doesn't care about your schema. You can render anything in any cell and thus you are able to display things the way you like it.

Unlike other grid components, ReactGrid also performs great on mobile devices or those with a touch capability and provides the same experience as on a desktop.

Before we get started let's list three main tasks:

displaying the collected data will be achieved with ReactGrid. To be reactive we will re-render the view only when the source data has changed. In this example, raw data comes from an audiometer - a device that is used for making hearing tests. In a nutshell, audiometer measures multiple hearing difficulties at many frequencies, and the audiogram is a way of visualizing such disorders.
visualize the collected data on the line chart using Chart.js and its React wrapper,
add a possibility to enter a new value and rerender the whole view with an updated state.

Let's code!

Initialize the project

Nothing simpler - just type one of the commands below into your terminal to initiate a React app with Typescript support.
'Create React App' will take care of all the necessary stuff.

Define useful interfaces and types

First, we need to declare a few interfaces and types that help us to keep everything in the right place and order.
In this particular example, we know all about the data that we want to process.
A good idea is to 'be as narrow' as possible.

Mark the columns and rows

Relying on those interfaces now we can introduce getColumns function.
In our app, we got a Line column, and after that, we got columns which are related to a particular frequency from 0Hz to 16000Hz.

The next stage is mapping all the rows. We make it in a similar way to previous examples.

Define the data

As we defined our data, it's time to define our data that we are working on. getData function returns an object whose each key must exist within the RowsMap interface. Each key of this object contains an array of Freq objects.

Map the data to ReactGrid

Now we are ready to generate rows that directly feed into ReactGrid. Each row contains the same amount of cells, but all of them can be arbitrarily placed in any order.

The main component - Audiogram

It is time to create the main component - Audiogram and wrap up already written code.
As you can see we stored our data inside React useState hook.
ReactGrid always expects two props - columns (they are constant and don’t change over time) and rows (they are calculated every time the Audiogram component is rerendered).

All that's left is to render the component with:

Apply changes with the cell editor

There are two things left to do:

Add a header row to mark the data (devices and all the frequencies);
Add possibility to edit data with ReactGrid's cell editor;

Adding the header row

To add it we have to create a short function called getHeaderRow. As an argument, it gets a column order (as keys of columns) and returns a row object that contains only a cell of the header type. We also added some green background to those cells.

Editing frequency values in cell editor

At this moment ReactGrid behaves as a read-only. To change that we updated the Audiogram component by adding our handler function called handleChanges. We expect that only NumberCell will be changed, therefore we marked the changes argument as CellChange<NumberCell>[]. Our task is to change data on the basis ReactGrid has been rendered.

Cell editor opens when it receives double-click action or the Enter key is pressed.
Then you can type a new value in and then commit the change. If we console.log(changes) we get an array of objects as shown below:

To change our raw data we have to find rowId where the change takes place.
Then loop over all frequency samples and apply a new value (change.newCell.value) to an appropriate cell or just return without changes.

Data visualization with Chart.js

Chart.js library delivers plenty of components to visualize data, but this time we focus on a single one - Line from react-chartjs-2 that we can use as a React component.

We have to create two functions:

getChartData - this function should return an object that contains two fields. The labels - which is an array of frequency title label and then datasets field to provide the data field which contains an array of values for each frequency. You can also style your line by setting for example a backgroundColor or pointRadius for a better experience.

getChartOptions - here we return an object that is compatible with ChartOptions interface. We want to disable legend, set the title, display, and adjust axes.

That's all! The job is done, now you can check the result below.

Summary

What you learned after completing this guide:

what is ReactGrid and how to do a fully functional app;
how you can use it in a reactive way;
why Typescript is also helpful in a small-scale project to avoid the most common mistakes.

As you see integrating ReactGrid with other libraries like Chart.js is not so hard. Of course, you don't need to start a Typescript project and make all data mappings to compose a predictable solution.

What is ReactGrid and why is it unique?

Patryk Eliasz — Mon, 11 Jan 2021 14:24:26 +0000

ReactGrid is a React component which enables you to add spreadsheet-like behavior to your app. It was created to satisfy a narrow group of recipients for whom other products are not an appropriate solution.

On the one hand there are data tables like Handsontable or ag-Grid. These render records row by row and offer various filtering, sorting and grouping methods. In 90% of the cases this functionality is fully sufficient.

Then there are Spreadsheet web components like KendoUI Spreadsheet or dhtmlx Spreadsheet which display regular Excel sheets in the browser. They are able to interpret formulas and offer rich editing features for the end-user.

ReactGrid places itself exactly in the middle between the two. It is not limited to a record-based model where each row has to have the same schema. The component enables you to create tables of any shape that look and feel like Excel-sheets. Additionally it integrates well with the data handling model provided by React.

When do you need ReactGrid in your app?

ReactGrid was created to solve the issues in which we, web developers, weren’t satisfied with the existing spreadsheet or data grid solutions. You must have wanted to present your data in a rather unusual way more than once, for example:

create a field that aggregates values only from selected places;
create an unusual combination of action and reaction;
display unstructured data, e.g. MongoDB documents;
sort or group data with an unusual structure together;
react to data changes in a way that is fully controlled by you;
transfer the solution implemented in the spreadsheet to a closed application.

Reactivity with arbitrary cell placement

To show the difference, we created a simple graph with two key aspects contained on the intersecting axes:

vertical — reactivity — a concept taken directly from React.js library. The opposite is imperative, you have full control over actions and their influence on the current view. In most cases you should follow the following pattern:

horizontal — arbitrary cell placement — opportunity to “Thinking in rows and columns”, each row has the same schema. Our component allows you to place any cell anywhere. We have focused on a fully controlled cell schema defined by our cell template engine. Templating is a powerful feature that allows you to define cell behavior based on its current and future data state.

We want to be (and we are) more reactive and cell-oriented. Breaking with the approach known from such alternatives as agGrid, Handsontable, it is necessary to handle events through self-implemented callbacks. Implementing a basic cell change event relies on your implementation. We prepared examples where you can just copy and paste predefined implementation.

ReactGrid’s content is rerendered only in case when visible data has changed or additional conditions such as a changed number of sticky rows and columns have appeared. Other examples might include handling scrolling (continuously following visible range for virtual scrolling), focusing cell, handling user actions like copying and pasting data. ReactGrid works perfectly even if you display a huge amount of cells — 10 000, 20 000, 100 000 is not a big deal.

Let’s talk about a simplified lifecycle based on ReactGrid. The component containing ReactGrid (AppComponent) has its data (it is a Single Point Of Truth for ReactGrid), which contains data on the basis of which the grid view will be generated.

The rendered view is ready to handle events coming from the user, e.g. changes committed in the cell editor. However, the component still behaves as read-only because a data update is required to change its contents. We can do this, for example, by implementing the onCellsChanged function (the example comes from the ReactGrid docs).

Touch devices friendly

ReactGrid works perfectly with modern web browsers. The same goes for their mobile counterparts along with touchscreens. With ReactGrid, a mobile-friendly spreadsheet-like component, you can use your app in the same fashion and experience the same productivity as on a desktop device. Let’s have a look at the basic mobile usage case — cell selection, fill handle… it just works on ReactGrid.

ReactGrid is NOT…

You may wonder why our product “does not have” many popular functionalities, such as grouping, sorting, filtering? This is not really a disadvantage, but a feature! By getting them, you immediately agree to the restrictions imposed by the selected library. Here you manage how you sort your data and how the user can do it. Nothing prevents any cell from being, for example, a filter.

What about formulas, toolbar, and coordinates? ReactGrid is a component in which we consciously implemented only the appearance and behavior known from typical spreadsheets, but without the implementation of the outer envelope. Our purpose was not to create the next Excel, but create whatever you like around it using component API.

Summary

In this short article, we showed three main principles which we developed ReactGrid with:

reactivity — handle every event and process data in your way;
arbitrary cell placement — forget about row schema and focus on cell,
mobile-friendly — the same experience no matter what device you use.

ReactGrid gives you the freedom to display and interact with your data to create a custom view with non-row-oriented data. We use it in our projects as a tool — not a complete solution. Therefore our experience shows that every solution resolved by ReactGrid is unique. We encouraging you to browse our website and Github repo.