Forem: Keyur Paralkar

Adding Rows & Columns

Keyur Paralkar — Sun, 01 Mar 2026 16:03:04 +0000

Introduction

In the previous blogpost, we build a table editor that used xstate’s state machine. We managed to build a schema driven architecture where schema was the source of truth for rendering things on the table-editor.

This blog post continues the same architecture and focuses on building a feature that will help to add a row and column into the table.

Addition of Row/Column

Our table editor in the current state, is just a basic table that loads some defaults. Now let us try to make it interactive by introducing addition of row and column.

The experience we are targeting should be such that it requires minimal effort for the user to add a row or a column into the table. I really liked notion’s UX of addition row and column:

Based on the similar lines we will also be building a similar UX for our table-editor. I have already implemented it and here is how it looks:

Here are the things we need to achieve this:

Change in state machine for addition of row/column
Handler UI around the right and bottom of the table editor.

💡

If you are a first time reader, I would highly recommend to please go through the first blogpost of this series that talks about how the xstate machine & the schema.

Let us first start by understand the things we need to change in state machine.

State Machine changes

Conceptually, adding a row/column can be reduced to four deterministic steps:

User clicks the row/column handlebar → Send Row/Column addition event to machine → Machine Updates Schema → UI renders new schema

These four steps are all it takes to build this feature. Let’s dive deeper into each of these steps.

User clicks the row/column handlerbar

This is basically building the UI for the user to interact with. We will look at in depth in the next section.

Send Row/Column addition event to machine & Schema update

My thought process here is to introduce entities to table. Entities are nothing but objects that impact the table editor’s state. There can be multiple types of entities:

Table Entities: They deal with structural changes to the editor's state like add, removing, resizing, etc of rows & columns
Cell entities: They deal with the structural changes related to cell

In case of this feature we are trying to add an entity i.e. row/column. So I introduced a new event named: add.table.entities. This event will be watched when you are in the ready state of the machine.

So now our state machine’s states will look:

state: {
 init: {
            always: {
                actions: ["initTable"],
                target: "ready",
            },
        },

        ready: {
            on: {
                "add.table.entities": {
                    target: "addingTableEntities",
                },
            },
        },
}

When the user interacts with the handlebars they will send the machine these events in the following manner:

const handleAddColumn = () => {
    send({
        type: "add.table.entities",
        payload: {
            type: "col",
        },
    });
};

const handleAddRow = () => {
    send({
        type: "add.table.entities",
        payload: {
            type: "row",
        },
    });
};

While sending the event we tell what type of entity we are trying to add here it is row / col.

When the machine receives this event, it transitions to addingTableEntities. This is another state that will have the following responsibilities:

Deciding the the type of entity to add.
Add the entity
Return back to the ready state.

{
        /**
         * The task of this state is to initialize the table with default no. of rows and columns
         * which is passed as an input to this machine
         */
        init: {
            always: {
                actions: ["initTable"],
                target: "ready",
            },
        },

        ready: {
            on: {
                "add.table.entities": {
                    target: "addingTableEntities",
                },
            },
        },

        /**
         * Entities are objects that impact the table editor's state.
         * There are multiple types of entities:
         * - Table entities - They deal with structural changes to the editor's state like add, removing, resizing, etc rows & cols.
         * - Cell entities - They deal with the structural changes related to cell
         */
        addingTableEntities: {
            initial: "decideOp",
            states: {
                decideOp: {
                    always: [
                        {
                            guard: "isAddingRow",
                            target: "addingRow",
                        },
                        {
                            target: "addingCol",
                        },
                    ],
                },
                addingRow: {
                    always: {
                        actions: ["addRow"],
                        target: "complete",
                    },
                },

                addingCol: {
                    always: {
                        actions: ["addCol"],
                        target: "complete",
                    },
                },

                complete: {
                    type: "final",
                },
            },
            onDone: {
                target: "#table-editor-machine.ready",
            },
        },
    }

addingTableEntities is a compound state which means having child states. Let me explain to you what the addingTableEntities state is doing:

When this state becomes active from the add.table.entities event, it imimediately gets into the decideOp initial state.
When in decideOp, we determine if its a row addition operation by checking the guard:

  guards: {
        isAddingRow: ({ event }) => event.payload.type === "row",
    },

If true, it transitions to addingRow state else fallbacks to the addingCol state.

Both addingRow / addingCol are exactly the same eventless transition states. They both point to the same target state: complete. They just differ by actions: addRow / addCol. Both of these actions only do the following thing: Update the schema by appending a new row/column into the rowOrder/colOrder and their property configs rowsById/colsById:

  addRow: assign({
            schema: ({ context }) => {
                const { schema } = context;

                return produce(schema, (draftSchema) => {
                    const len = draftSchema.rowOrder.length;

                    draftSchema.rowOrder.push(String(len));

                    draftSchema.rowsById[len] = {
                        id: String(len),
                        style: {
                            height: 20,
                        },
                    };

                    draftSchema?.rowOrder?.forEach((rO) => {
                        /**
                         * Use the colOrder from original context rather than draftContext
                         * because rowOrder is the one that is getting changed and colOrder remains unchanged.
                         */
                        schema?.colOrder?.forEach((cO) => {
                            const cellKey =
                                `${rO}:${cO}` as keyof MachineContext["schema"]["cells"];

                            draftSchema.cells[cellKey] = {
                                kind: "empty",
                                value: "",
                            };
                        });
                    });
                });
            },
        }),
        addCol: assign({
            schema: ({ context }) => {
                const { schema } = context;

                return produce(schema, (draftSchema) => {
                    const len = draftSchema.colOrder.length;

                    draftSchema.colOrder.push(String(len));

                    draftSchema.colsById[len] = {
                        id: String(len),
                        name: "",
                        style: {
                            width: 100,
                        },
                    };

                    schema?.rowOrder?.forEach((rO) => {
                        /**
                         * Use the rowOrder from original context rather than draftContext
                         * because colOrder is the one that is getting changed and colOrder remains unchanged.
                         */
                        draftSchema?.colOrder?.forEach((cO) => {
                            const cellKey =
                                `${rO}:${cO}` as keyof MachineContext["schema"]["cells"];

                            draftSchema.cells[cellKey] = {
                                kind: "empty",
                                value: "",
                            };
                        });
                    });
                });
            },
        }),

The last state is the complete state with the type: :"final". This tells the machine that the operation has completed and no further transitions should occur within this branch. Once this state is reached we transition to the parent state from the child state i.e. complete state → addingTableEntities state.
Now our aim is to get back to the ready state when reach the complete state. Since complete state is of type: :"final", and when it is reached it fires the onDone state done event.

  onDone: {
                target: "#table-editor-machine.ready",
            },

In this transition we tell to redirect us to the ready state of the machine.

Once this transition is done the schema gets updated and the table-editor component picks up the new values and renders the same.

You might wonder — why not directly handle add.table.entities with an action inside ready? Because I want structural mutations to be explicit states, not invisible side-effects.

By introducing addingTableEntities as a compound state:

Structural transitions become traceable
Future logic can hook into this state
The machine remains extensible

Now let us look at those UI handlebars that we were talking about in the earlier section.

Handler-bars UI around the table editor

The last piece of the code, is to create the UI that facilitates this addition of row and column. At the start of the blog we decided to make use of the notion’s user experience of having handle bars to the right and bottom of the table editor. We will be doing the same thing.

This piece of code add these handles to the main table-editor component hence here is the updated table-editor component:

const TableEditor = ({ defaultColumns, defaultRows }: TableEditorProps) => {
    const [_, send, actorRef] = useMachine(TableEditorMachine, {
        input: {
            defaultColumns,
            defaultRows,
        },
    });

    const {
        rowOrder,
        colOrder,
        getCellKey,
        getCellProperties,
        getColumnProperties,
        getRowProperties,
    } = useGetTableProperties({
        actorRef,
    });

    const handleAddColumn = () => {
        send({
            type: "add.table.entities",
            payload: {
                type: "col",
            },
        });
    };

    const handleAddRow = () => {
        send({
            type: "add.table.entities",
            payload: {
                type: "row",
            },
        });
    };

    return (
        <div className="inline-block relative">
            <table>
                <thead>
                    <GridRow>
                        {colOrder?.map((c) => {
                            const { key, ...rest } = getColumnProperties(c);

                            return (
                                <GridHeader key={key} className="border" {...rest}>
                                    {c}
                                </GridHeader>
                            );
                        })}
                    </GridRow>
                </thead>
                <tbody>
                    {rowOrder?.map((r) => {
                        const { key, ...rest } = getRowProperties(r);

                        return (
                            <GridRow key={r} {...rest}>
                                {colOrder?.map((c) => {
                                    const cellKey = getCellKey(r, c);
                                    const { key, value, ...rest } = getCellProperties(cellKey);

                                    return (
                                        <GridCell key={key} className="border" {...rest}>
                                            {value}
                                        </GridCell>
                                    );
                                })}
                            </GridRow>
                        );
                    })}
                </tbody>
            </table>

            {/** Handle bars for add rows/columns */}
            <div
                id="table-handlebar-col"
                className="transition-all opacity-0 hover:opacity-100 hover:bg-gray-300/30 rounded h-full w-5 absolute top-0 left-full ml-2 flex flex-col justify-center items-center cursor-pointer"
                onClick={handleAddColumn}
            >
                <span className="text-gray-600 select-none">+</span>
            </div>
            <div
                id="table-handlebar-row"
                className="transition-all opacity-0 hover:opacity-100 hover:bg-gray-300/30 rounded h-6 w-full absolute left-0 mt-2 flex justify-center items-center cursor-pointer"
                onClick={handleAddRow}
            >
                <span className="text-gray-600 select-none">+</span>
            </div>
        </div>
    );
};

Here is how our new handlebars will look like:

In the next article, we’ll tackle one of the hardest problems in table editors: selection.

And this is where things start to get interesting.

Hope you like my blog post.

You can follow me on twitter, github, and linkedIn.

Building a Production-Grade Table Editor with React and XState

Keyur Paralkar — Sun, 22 Feb 2026 13:36:06 +0000

Introduction

Table editors look simple.

Add rows. Edit cells. Resize columns.

But once you add undo/redo, reordering, grouping, and consistent UI feedback — the logic becomes chaotic.

In this series, we’ll build a production-grade table editor using a state machine approach with XState.

What

Have you ever used SaaS products that have a great table editing and viewing experience. Let me give you some examples:

Clay

Notion

Google Sheets

They are just easy to navigate, put your data and you are done. It just feels natural and provides consistent feedback on every operation we do in these tables.

So in this blogpost series we will be looking at how to create your own table editor which provides an experience like these products. Especially we will try to implement features like:

Row and column addition and deletion
Re-ordering of columns and rows
Re-sizing of rows and columns
Grouping Rows and columns
Table editing experience.
Undo - redo operations
etc….

Why

This series is not about competing with existing table libraries. It’s about understanding how production-grade data editors are architected.

When you understand the underlying model — schema normalization, state orchestration, transactional updates — you can design better systems everywhere else.

Prerequisites

To understand this blogpost series you need some basic understanding of the following:

How

We won’t be building all these features in this blogpost itself. That would be foolish 😀. We will start by a simple setting up of the project + designing the basic architecture of our table-editor component.

Here are the things we need:

A simple react vite project. You can follow the vite’s official guide to setup your first react project with typescript template here
Install the xState library by following the instructions here.

Architecture

The architecture of our table-editor can be understood in the following parts:

Schema
State Machine
Editor Component

The Schema

We don’t want a complex web of useStates to manage the actual state of our component. We want it to be clear, precise, reliable and robust. To achieve this we need a reliable architecture that will scale better with the new feature. We achieve this with the help of schema.

A schema is nothing but a big JS Object that acts as a single source of truth for the table editor. This would be the source of whatever you see and happens to the table editor. For example, if you try to add a column or row then first it will be updated in the schema → And then all the subscribed components would derive their states from the schema’s current state.

Why to choose this pattern:

Represents the current state of the table.
Provides better developer experience.
Makes the table robust.
Errors can be caught pretty easily
Scalable

So let us start first by looking at the schema with actual values in it:

{
    colOrder: [cId1, cId2],
    rowOrder: [rId1, rId2],

    colsById: {
        cId1: {
            id: "cId1",
            name: "col 1",
            style: {...}
        },
        cId2: {
            id: "cId2",
            name: "col 2",
            style: {...}
        }
    },
    rowsById: {
        rId1: {
            id: "rId1",
            name: "row 1",
            style: {...}
        },
        rId2: {
            id: "rId2",
            name: "row 2",
            style: {...}
        }
    },

    cells: {
        "rId1:cId1": {
            kind: "empty",
            value: ""
        },
        "rId1:cId2": {
            kind: "empty",
            value: ""
        },

        "rId2:cId1": {
            kind: "empty",
            value: ""
        },
        "rId2:cId2": {
            kind: "empty",
            value: ""
        },
    }
}

Above represents a 2x2 table i.e. with 2 rows and 2 columns. The picture will be much clearer when we look at the typescript schema for the same:

import type { CSSProperties } from "react";

export type Row = {
    id: string;
    style?: Partial<CSSProperties>;
};

export type Column = {
    id: string;
    name: string;
    style?: Partial<CSSProperties>;
};

export type RowId = string;
export type ColumnId = string;

export type CellKey = `${RowId}:${ColumnId}`;

type CellValue =
    | {
            kind: "text";
            value: string;
      }
    | {
            kind: "number";
            value: number;
      }
    | {
            kind: "empty";
            value: "";
      };

type CellMeta = {
    style?: Omit<Partial<CSSProperties>, "width" | "height">;
};

type Cell = CellValue & CellMeta;

export type Schema = {
    colOrder: Array<ColumnId>;
    rowOrder: Array<RowId>;

    colsById: Record<ColumnId, Column>;
    rowsById: Record<RowId, Row>;

    cells: Record<CellKey, Cell>;
};

A schema is represented above typescript types. Let me briefly describe these types for your:

Every schema is composed of the following properties:
- colOrder - These are the orders that user sees on the UI for columns. From the above example, when this order is = [cId1, cId2] that means that cId1 appears before cId2.
- rowOrder - This is exactly similar to that of the colOrder but for rows.
- colsById - This is a object where key is the column’s id and value is the properties that define that column. So this is an object which provides all the information about a column when you query it by id.
  
  Every value is of type Column which defines the structure of the given column. A single Column can have the following properties: id name and style. Thus defining the characteristics of a column.
- rowsById - Exactly similar to colsById but for rows.
- cells - This is again an object which can be used to get the properties of each individual cell. If you want to get information about a cell you should query it by CellKey
  
  CellKey is represented by <row-id>:<col-id>. Every CellKey represents a Cell which defines the characteristics just as the above Column and Row types. Please have a look at them above in the TS types.

Now the question arises as to why we did we design schema with this approach?

This schema is normalized.
It separates structure from order.
It prevents expensive array traversal.
It scales to thousands of rows.

The Schema is designed in this way to provide maximum scaleability and maintainability with the help of separation of concerns. This is achieved by keeping the order related stuff that the user would see in the separate array i.e. rowOrder colOrder and information about each of this row and column in the rowsById and colsById.

Now changing the order would simply mean changing the position of row ids in the rowOrder array.

If you want to update the characteristics of a specific row then you can do so by changing the row’s value from the rowsById mapping.

Let me explain you this by an example:

Consider that the above schema would have been represented in the following manner:

Schema = {
    rows: Array<Row>;
    columns: Array<Column>;
    ...
}

If you wanted to change the position of a row, then you need to do the following things:
- First find the row.
- Take the row
- Put it at the correct place that you want
- re-index the id property of the entire array.
Now also consider that you wanted to change the background color of the row:
- Again we find the row
- Update the background property in the styles

But with the current i.e. the split approach:

It simplifies updates
It avoids unnecessary object recreation
It enables partial updates
It keeps reordering separate from mutation

Think of this schema like a normalized database:

rowOrder is the index
rowsById is the table
cells is a join table between rows and columns

Now that we have a normalized data model, we need a way to orchestrate how it changes over time.

That’s where state machines come in.

State Machine

State machine is a model that will help you organise complex state logic that you have in your component, app etc. It does that by defining:

States
Events
Transitions
Side effects

Instead of scattering logic across multiple useState hooks, we centralize behavior inside a predictable model.

For our table editor, we’ll use Stately’s library XState to orchestrate the editor logic.

Machine Overview

The flow of our table editor is quite simple. There are two of states to it:

init
ready

Conceptually, it looks like this:

What Happens During Initialization?

It enters into the init state
It generates the initial schema based on input (defaultRows, defaultColumns) i.e. the defaults we pass to the machine
It transitions to ready.

Here is a quick look at how our table will look like with this state machine when loaded with defaults: rows = 4 & cols = 3 :

The Machine Definition

Here is the actual XState state machine that wraps the above logical flow:

const TableEditorMachine = setup({
    types: {
        context: {} as MachineContext,
        input: {} as MachineInput,
    },
    actions: {
        initTable: assign({
            schema: ({ context }) => {
                const {
                    defaults: { columns, rows },
                    schema,
                } = context;

                return produce(schema, (draftSchema) => {
                    /**
                     * This is where the magic happens:
                     * - We create a rowOrder and ColumnOrder by filling it with ids. At the current moment they can be indices
                     * - Then we fill up the colsByID and rowsById objects
                     * - Then we fill up cells with empty states
                     */

                    draftSchema.rowOrder = new Array(rows)
                        .fill(0)
                        .map((_, i) => String(i));
                    draftSchema.colOrder = new Array(columns)
                        .fill(0)
                        .map((_, i) => String(i));

                    draftSchema.rowsById = draftSchema.rowOrder.reduce(
                        (acc, curr) => {
                            acc[curr] = {
                                id: curr,
                                style: {
                                    height: 20,
                                },
                            };

                            return acc;
                        },
                        {} as MachineContext["schema"]["rowsById"],
                    );

                    draftSchema.colsById = draftSchema.colOrder.reduce(
                        (acc, curr) => {
                            acc[curr] = {
                                id: curr,
                                name: "",
                                style: {
                                    width: 100,
                                },
                            };

                            return acc;
                        },
                        {} as MachineContext["schema"]["colsById"],
                    );

                    /**
                     * We define cells as well:
                     */
                    draftSchema?.rowOrder?.forEach((rO) => {
                        draftSchema?.colOrder?.forEach((cO) => {
                            const cellKey =
                                `${rO}:${cO}` as keyof MachineContext["schema"]["cells"];

                            draftSchema.cells[cellKey] = {
                                kind: "empty",
                                value: "",
                            };
                        });
                    });
                });
            },
        }),
    },
}).createMachine({
    id: "table-editor-machine",
    context: ({ input }) => ({
        defaults: {
            rows: input.defaultRows,
            columns: input.defaultColumns,
        },
        schema: {
            rowOrder: [],
            colOrder: [],

            colsById: {},
            rowsById: {},

            cells: {},
        },
    }),

    initial: "init",
    states: {
        /**
         * The task of this state is to initialize the table with default no. of rows and columns
         * which is passed as an input to this machine
         */
        init: {
            always: {
                actions: ["initTable"],
                target: "ready",
            },
        },

        ready: {
        },
    },
});

What this machine is doing

Let’s break this machine down clearly:

The machine accepts input:

context: ({ input }) => ({
    defaults: {
        rows: input.defaultRows,
        columns: input.defaultColumns,
    },
    ...
})

This ensures that the machine is initialized with the required inputs. These inputs will be used to generate the defaults in the schema.

The init State Performs an Eventless Transition:

init: {
            always: {
                actions: ["initTable"],
                target: "ready",
            },
        },

Here no event is required.
Execute the action initTable
On action complete move to ready state.

initTable action builds the entire schema with defaults by doing the following:
- Creates ordered row IDs
- Creates ordered column IDs
- Populates rowsById
- Populates colsById
- Generates every cell key (rowId:colId)
All mutations above are handled with immutably using produce (Immer).

The important thing to note here is that: The schema is generated **inside the machine**, not inside React. This means that:

Initialization logic is centralized.
It is testable.
It is deterministic.
It is independent from rendering.

Why this matters and what it means?

Even though our machine is small, this structure gives us:

A predictable lifecycle
A single place for orchestration
A scalable foundation for future features

When we add:

Row insertion
Column resizing
Undo/redo
Reordering
Grouping

We won’t mutate React state directly. Rather we will send events to this machine. That’s the real power of this approach. The machine owns orchestration. React only renders.

React becomes a rendering layer. The machine becomes the source of truth.

Now that we know how the machine works and the importance of this approach, let us understand how can you hook this with your react code.

Table Editor

Before we start hooking the machine let us first create these building blocks to create a table: td th tr :

td:

import type { CSSProperties, PropsWithChildren } from "react";

type GridCellProps = PropsWithChildren & {
    className?: string;
    style?: CSSProperties;
};

const GridCell = ({ children, className, style }: GridCellProps) => {
    return (
        <td className={className} style={style}>
            {children}
        </td>
    );
};

export default GridCell;

th:

import type { CSSProperties, PropsWithChildren } from "react";

type GridHeaderProps = PropsWithChildren & {
    className?: string;
    style?: CSSProperties;
};

const GridHeader = ({ children, className, ...rest }: GridHeaderProps) => {
    return (
        <th className={className} {...rest}>
            {children}
        </th>
    );
};

export default GridHeader;

tr:

import type { CSSProperties, PropsWithChildren } from "react";

type GridRowProps = PropsWithChildren & {
    className?: string;
    style?: CSSProperties;
};

const GridRow = ({ children, className, style }: GridRowProps) => {
    return (
        <tr className={className} style={style}>
            {children}
        </tr>
    );
};

export default GridRow;

You can even use any component library you want, just make sure to pass the props correctly.

Here is a custom hook that will help us to get table properties from our machine:

type UseGetTablePropertiesProps = {
    actorRef: ActorRefFrom<typeof TableEditorMachine>;
};

/**
 * A hook that provides helper functions for extracting properties from entities like col, row and cells
 */
export const useGetTableProperties = ({
    actorRef,
}: UseGetTablePropertiesProps) => {
    const { colOrder, colsById, rowOrder, rowsById, cells } = useSelector(
        actorRef,
        (s) => s.context.schema,
    );

    const getColumnProperties = (colId: ColumnId) => {
        const columnProps = colsById[colId];

        const { id, name, style } = columnProps;

        return {
            id,
            key: `col-${id}`,
            "data-col-name": name,
            style,
        };
    };

    const getRowProperties = (rowId: RowId) => {
        const rowProps = rowsById[rowId];

        const { id, style } = rowProps;

        return {
            id,
            key: `row-${id}`,
            style,
        };
    };

    const getCellKey = (rowId: RowId, colId: ColumnId): CellKey =>
        `${rowId}:${colId}`;

    const getCellProperties = (cellKey: CellKey) => {
        const cellProps = cells[cellKey];

        const { kind, value, style } = cellProps;

        return {
            id: cellKey,
            key: cellKey,
            kind,
            value,
            style,
        };
    };

    return {
        colOrder,
        colsById,
        rowOrder,
        rowsById,
        cells,
        getCellKey,
        getCellProperties,
        getColumnProperties,
        getRowProperties,
    };
};

Let me describe this hook briefly:

It takes input as actorRef which is a reference to our state machine.
Now to access the context that we had in our machine we use the XState’s useSelector hook to get all the properties we need. You can get all the information you need from the machine. You just need to tell the selector that you need information via this piece of code: (s) => s.context.schema. Since this is the information that we need i.e. source of truth to render the UI.
This hook exposes other helper functions: getColumnProperties getRowProperties and getCellKey getCellProperties and other variables. The functions here provides you the meta data about a row, column or a cell via providing them row, col and cell id. This makes it easier in the rendering part to render the UI elements.

useSelector ensures that the component only re-renders when the selected part of the machine changes.

Now let us create a table-editor component that will hook all of the above things:

const TableEditor = ({ defaultColumns, defaultRows }: TableEditorProps) => {
    const [_, send, actorRef] = useMachine(TableEditorMachine, {
        input: {
            defaultColumns,
            defaultRows,
        },
    });

    const {
        rowOrder,
        colOrder,
        getCellKey,
        getCellProperties,
        getColumnProperties,
        getRowProperties,
    } = useGetTableProperties({
        actorRef,
    });

    return (
        <div className="inline-block relative">
            <table>
                <thead>
                    <GridRow>
                        {colOrder?.map((c) => {
                            const { key, ...rest } = getColumnProperties(c);

                            return (
                                <GridHeader key={key} className="border" {...rest}>
                                    {c}
                                </GridHeader>
                            );
                        })}
                    </GridRow>
                </thead>
                <tbody>
                    {rowOrder?.map((r) => {
                        const { key, ...rest } = getRowProperties(r);

                        return (
                            <GridRow key={r} {...rest}>
                                {colOrder?.map((c) => {
                                    const cellKey = getCellKey(r, c);
                                    const { key, value, ...rest } = getCellProperties(cellKey);

                                    return (
                                        <GridCell key={key} className="border" {...rest}>
                                            {value}
                                        </GridCell>
                                    );
                                })}
                            </GridRow>
                        );
                    })}
                </tbody>
            </table>
        </div>
    );
};

This is a pretty simple component and it does the following things:

Makes use of useMachine that takes our machine TableEditorMachine as the input. In this hook we also pass the arguments which acts as an input to our machine i.e. defaultColumns and defaultRows
We pass the machine’s reference actorRef to the our custom hook useGetTableProperties to get the table properties.
Lastly we loop over the row and column order and use the building blocks that we created to render each table property.

In the next article, we’ll implement row and column insertion — not as ad-hoc mutations, but as state machine transitions.

Hope you like my blog post.

You can follow me on twitter, github, and linkedIn.

Hey folks, I wrote about website localization and its importance. Do give it a read!

Keyur Paralkar — Sun, 15 Dec 2024 08:19:29 +0000

What is Website Localization?

Keyur Paralkar ・ Nov 25

#webdev #beginners #react #learning

What is Website Localization?

Keyur Paralkar — Mon, 25 Nov 2024 17:44:11 +0000

Introduction

Have you ever seen some advertisements that are catered around your current trends? For example, Spotify understanding the current trends of the youth and displaying ads like this classic: group of friends always plan a long trip but it always remain in the chats 😀

Spotify ads

Or you might have seen google’s sign in page in different languages:

Google Sign-in page in English

Google Sign-in page in German

Here is another example of the famous brand: IKEA. They use localization heavily to create unique experience. For example, IKEA’s main idea was to sell furniture which can be assembled at home with their instruction manual. This is a good approach in most of the countries but in China assembling the furniture is considered to be an opposite symbol. They prefer furniture to be assembled by some handyman or a third party service.

IKEA was left to either provide assembly service as well or leave the China market. IKEA took the first approach and introduced assembly service specific to China. This helped them to increase their market hold there by multiple folds.

You can see this experience on IKEA’s website, here is a quick look of India and China version of the website

Ikea showing no assembly service option for India region

Assembly service option at the bottom left for China region

This example was inspired from here. You can read more about Ikea’s localization strategies on the same.

All these examples you see are focused on improving the user’s experience. It takes a lot of research and understanding of the user’s region to come up with this user experience. But websites like these makes use you of concept called as website localization to achieve the same.

So in this blogpost, we will be exploring website localisation, how it differs from translation and its multiple use cases.

So without any further ado, let us get started!!

What is Website Localisation?

Website localisation is a method/a way to make sure the website adapts to the user’s location so that the experience is enhanced.

Adaption of a website based on user’s location can mean a lot of things like:

Making sure the website’s content is aligned correctly i.e. LTR or RTL.
Making sure the images, audio and videos are appropriate as per the user’s region.
Making sure the text is translated according to the user’s location.

Combining all the ways of adaption, website try to create a personalised experience for the user which make them feel familiar and isn’t hard to navigate.

Is Website localisation same as text translation ?

We can say that text translation is a part of localisation i.e. localisation is a super set of text translation.

Website localisation includes adapting the website’s content as per the user’s region. But translation is converting the text to the language which is native at the user’s location.

It is important to note that text translation should also cater to the user’s dialect to provide an optimum experience. We will talk more about this in the coming sections.

Use Cases of Website Localization

Website localisation is highly useful for businesses who are trying to have a global reach. By global reach, we mean that they want to expand to other countries so that they can increase their business.

The examples of such business are everywhere from e-commerce, food industries, pharmaceutical to automobile industries. With the help of localisation it helps these businesses to expand further and show their capabilities on how they cater the needs of their customers.

I feel website localisation is very important for businesses mentioned above because:

It tells that the company fosters user empathy.
It makes sure that user are comfortable and they feel safe while browsing their websites.
Provides correct interpretation of what the user needs.

Let us look at a couple of ways through which localisation has helped businesses empathise more towards users:

Text Translation

Often not people think that website localisation is nothing but text translation. But yeah that being partially true website localisation is much more than that. As we saw above that it is a super set of text translation.

Text translation is the key aspect of website localisation. People think that, why should we manually translate a website were we already have google translate that will help us to do that on the fly. While that being true in some cases, the translation provided cannot be always correct.

The translation provided by these app should make sure that they also match the dialect of the user location.

For example, google translate can make mistakes, such as:

"Take a hike" vs. "Haz una caminata": In English, "take a hike" is often used as a rude dismissal, while in Spanish, "haz una caminata" simply means "take a walk."
"Y'all" - A common Southern American English term, it can be challenging to translate accurately, often resulting in awkward or incorrect phrases.
"Mate" - A common Australian and British term for friend, it can be misinterpreted in other cultures.

So text translation which involves professional translation services can recognize idioms and find equivalent phrases in the target language to maintain the same tone.

Text translated by these apps can also contract or expand the text space. This in turn affects the spacing and layout on the page. So it becomes beneficial to have custom translation placed on the website to avoid such scenarios. Here is a quick example of IKEA’s language change section differs in text sizes when language is changed from english to arabic.

Text Expansion in English

Similar text in the Arabic text is smaller:

Text Contraction in Arabic

Content Relevance And Placement

Another key aspect of website localisation is the making sure the content is relevant and placed correctly on the website.

Content Relevance

If you have observed food chains such as McDonald’s or KFC, they have different menus for different countries. They make sure that menu are created in such a way that the items available, are as per the local traditions and adhere to the culture neutral zone.

For example, In US you would find a big mac burger made out beef patty, it’s equivalent in India is Maharaja Mac burger with a chicken patty.

The Maharaja Mac

The Big Mac

Content Placement

Another important factor on websites is the content placement. Let us look at this via examples,

Websites needs to make sure that their content caters for users from all the regions. A person from a middle eastern region, would generally prefer their text to be placed in right to left format instead of left to right.

Here is a look at how the IKEA’s website looks like for an arabic region as compared to the India version of the website:

IKEA website of middle east region in Arabic language

IKEA website of Indian region in English language

As you can see in the above images that text is preferred in right to left format for Arabic region as compared to the India version. Another keen example of content placement in this scenario is the placement of the language change button(highlighted in green) and the tablist(highlighted in blue). If you see, for Arabic region both the button and tablist starts from right which isn’t the case for Indian region of the site.

These minute details creates a thoughtful user experience for a variety of regions. Thus content placement is one of the important aspects of the website localization.

Hyperlocalisation

It is a kind of localisation that is very specific to the user’s needs and most of the time it caters to user’s preferences. This helps the websites create a deeper and personalized impact with the user. We can consider hyperlocalisation to be an advanced version of website localisation which focuses much on content relevance.

A classic example that I found here is with Spotify. They shared this ad which targeted the users from Mumbai who can related to being stuck in a heavy traffic:

Spotify's Audience Targeting to achieve Hyperlocalization

There are a lot of examples on hyperlocalization, some of them we saw in the introduction section of the blog. Hence it is important for products that revolve around user’s bevhavior to have hyper-localization.

How can this be achieved?

There are many products out there such as Lokalize, Crowdin, Weglot, Adobe Target, etc can be used to achieve these experiences. Diving into the details and the general working of these products is out of scope of this blog post. But do give these products a try.

Summary

In this blogpost, we learned various aspects of website localization including it’s definition and how it differs from text translation. We also delved into various use cases which achieve website localization and how they create an impactful user experience.

So that’s all folks!. Hope you like my blog post.

You can follow me on twitter, github, and linkedIn.

Master TypeScript: Let's Do Math In Type System

Keyur Paralkar — Sun, 28 Jul 2024 10:28:10 +0000

Introduction

In our day to day lives we do Mathematical operations without any hassle and worry. Because we have all the tools we need like, numbers and the operators. Like 5 + 2 = 7, here we know that 5, 2, and 7 are numbers and what we are essentially doing is adding because of the operator +.

Now, just imagine you don’t know what the numbers mean or their actual interpretation. You also don’t know the meaning of the + symbol, but you still want to add two numbers. It's like a toddler trying to do this!

I welcome you to the world of TypeScript where you cannot do all these stuffs. TypeScript does understand numbers but doesn’t have the understanding of what numbers represent and how big they are, what exactly are mathematical operations.

So in this blogpost, I will be explaining you folks, how to do the exact same thing and try to make it more humane.

Prerequisites

Who is this blog post not for?

Let me tell you the hard truth upfront: this blog post is one of those rare cases where you might not need it. The purpose of this post is to understand the marvelous concepts used to implement such things in TypeScript.

I love TypeScript, and for fun, I am trying to dig into this!

What are we building?

In TypeScript you cannot do any arithmetic operation like the above 5+2 which is equal to 7. You can represent numbers in typescript like 5 or 2 but you cannot do anything with them.

In this blogpost we will be building typescript generic utilities that will help you to implement the arithmetic operations:

Addition
Subtraction
Multiplication
Division

After going through this blogpost, you will be able to achieve the following in TYPES!!!

type addResult = Add<5, 2> // 7
type subRes = Sub<50, 3>; // 47
type mulRes = Mul<2,10>; // 20
type divRes = Div<10, 2>; // 5

The Basics

Every good code that is implemented is based on a good foundation. In this section we will talk about the foundation of implementing the above generic utilities.

There are two main thing that we need to understand:

Recursion
And Tail Recursion

These concepts are really important and drive the entire thought process about these generic arithmetic utilities in TypeScript.

So let us start off by understanding recursion.

What is Recursion?

Recursion is the way through which you can perform certain action by calling the same action. In terms of real life example, recursion can look like this:

Recursion in real life

If you hold a mirror in front of a mirror then you see an endless mirror within mirrors.

In the similar way, recursion in programming is a way for a function to achieve the results by calling it self. To explain this further let me give you a classic yet simple example,

const sum1ToN = (num: number) => {
    if(num === 0){
        return 0;
    }
    return num + sum1ToN(num - 1)
}

This function will return the sum of all the numbers from 1 to N.

To give you guys a quick look let us see what happens from call stack perspective(I know this is a bit off the route but trust me this will help us understand the later section of the blogpost):

If you execute sum1ToN(4). This is what happens

4 + sum1ToN(3)

4 + 3 + sum1ToN(2)

4 + 3 + 2 + sum1ToN(1)

4 + 3 + 2 + 1 + sum1ToN(0) // <-------

4 + 3 + 2 + 1

4 + 3 + 3

4 + 6

10

In the call stack, numbers are unraveled until num = 0. Once all numbers are spread out, reverse addition occurs, consuming more of the call stack. For example, when num was 4, it took 8 stacks to finish. Imagine if num is 100.

This unpacking method in recursion is inefficient because the last statement in sum1ToN performs two operations: unpacking the number and calling the next number in recursion. The program must remember the previous steps.

But why study this? What does recursion have to do with efficiency?

Find out in the next section.

Limitations in TypeScript

All the arithmetic generic utilities that we are going to build involves heavy recursion to achieve the results. Next, the typescript has limitation on its call stack size. Following are the TypeScript limits of the call stack:

If it is a normal statement in TS then recursion limit is 100.
If it is inside a conditional statement then limit is below 1000.

Hence, if we go with the above normal recursion methods to implement our utilities then it would fill up these limits easily even with small numbers like 200 or so if the utilities are not implemented correctly.

The aim of our utilities would be that they should take inputs less 1000.

You can read more about these TS limits in this PR: https://github.com/microsoft/TypeScript/pull/45711

What is Tail Recursion?

There is a way out to this normal recursion technique where you can do these calculations efficiently by reducing the call stack sizes. This method is called as tail recursion. I am not going to go in-depth about tail recursion in this post but I will help you understand how it affects the call stack.

So tail recursion is a technique in which the last statement of the recursive function just calls the function it self and doesn’t do any further calculations combined with it.

For example, in the above sum1ToN function the last statement num + sum1ToN(num -1) should not be present in the tail recursion method according to its definition.

If we cannot do combined operation as the last call in our recursive function then how are we going to achieve results? Its simple, just make use of accumulator to remember the addition of the already visited numbers. Below is the quick look of tail recursion version of sum1ToN:

const sum1ToN = (num: number, acc: number = 0) => {
    if(num === 0)
        return acc;

    return sum1ToN(num - 1, acc + num);
}

Here, we introduce the second argument acc to the function with a default value of 0. This way, the program doesn’t need to remember previous calls. In our case, while unpacking the numbers in the call stack, we are also performing the calculations in the accumulator as shown below:

sum1ToN(3, 0 + 4)
sum1ToN(2, 0 + 4 + 3)
sum1ToN(1, 0 + 4 + 3 + 2)
sum1ToN(0, 0 + 4 + 3 + 2 + 1) // finally the acc is returned

See how the call stack got reduced!!! we don’t need to go through all the next steps of addition because we are doing addition while we are doing the unpacking of the numbers. Isn’t this great 🙂

💡 NOTE Even though this technique is efficient still at some point in our utilities we hit the above mentioned limits.

You can find out more about tail recursion in the below detailed and fantastic videos:

Let us dive into the implementation

In this section we will be implementing the following arithmetic utilities which look like below:

type Add<A extends number, B extends number> = [
  ...GetRange<A>,
  ...GetRange<B>,
]["length"];

type Sub<
  A extends number,
  B extends number,
  Num1 extends Array<number> = GetRange<A>,
  Num2 extends Array<number> = GetRange<B>,
> = Num2 extends [...Num1, ...infer R] // A < B; res = -ve
  ? `-${R["length"]}`
  : Num1 extends [...Num2, ...infer T] // A > B; res = +ve
  ? T["length"]
  : 0;

 type Mul<
  A extends number,
  B extends number,
  Counter = 0,
  Acc extends Array<number> = [],
  Num1 extends Array<number> = GetRange<A>,
> = B extends Counter
  ? Acc["length"]
  : Mul<A, B, Inc<number & Counter>, [...Acc, ...Num1]>;

type Div<
  N extends number,
  D extends number,
  Acc extends Array<number> = [],
  ReducedN extends number = GetRange<N> extends [...GetRange<D>, ...infer T] ? T["length"] : 0,
> = N extends 0 
    ? Acc['length']
    : Div<ReducedN, D, [...Acc, 0]>;

I know these generic might look way difficult but trust me they are easy to understand. I will break down each and every part of these generic utilities so that you guys can grasp the concept behind it.

So without further ado, let us start by implementing our first utility Add.

Add

In terms of arithmetic this is a no brainer, Add utility will just add two numbers. There are couple of things that you need to understand before we start off with the implementation:

We cannot do addition or any arithmetic operation of that sort. So to by-pass this we convert each input number into a tuple of numbers. For example, a number 4 will be represented as a tuple of four 0s i.e. [0, 0, 0, 0].
We will need an utility to generate tuples out of the input numbers
Numbers greater than 1000 cannot be used because we might reach the TS stack limit discussed above.

So here is how our Add utility will look like:

 type Add<A extends number, B extends number> = [
  ...GetRange<A>,
  ...GetRange<B>,
]["length"];

Before we jump into the implementation, let us understand what the GetRange utility is:

/**
 * Generates a tuple of 0s for the specified number
 */
type GetRange<
  N extends number,
  Acc extends Array<number> = [],
> = Acc["length"] extends N ? Acc : GetRange<N, [0, ...Acc]>;

This utility will generate a tuple filled with 0s equal to number passed as input. So indeed it will do something like below:

type res = GetRange<4> // res = [0, 0, 0, 0]

GetRange flowchart

The GetRange utility works in the following manner:

It takes input number for which the tuple range needs to be created which is N.
It also makes use of accumulator Acc which stores the actual range in each step of recursion.
Its a simple recursion where we check if the length of Acc equals to the number N then we stop the recursion and return the Acc.
If not, we again call the GetRange<N, [0, ...Acc]> which passes updated Acc to the GetRange with an addition of 0 and the previous values of Acc by destructing it an array like this [0, ...Acc].

Taking a closer look at this utility, we can see that we are using the Tail recursion mechanism, since the last statement in the recursion is only the recursive call to the function and no other operation. And also we are making use of accumulator Acc.

Now let us re-visit our Add utility. In this utility we simple destructure the tuples from GetRange<A> and GetRange<B> inside an array. Finally we return the length of this array:

Add flowchart

type Add<A extends number, B extends number> = [
  ...GetRange<A>,
  ...GetRange<B>,
]["length"];

type sum1 = Add<10, 5>; // 15

Subtract

Here is how the subtraction utility will look like in TypeScript:

/**
 * Substracts two numbers
 */
type Sub<
  A extends number,
  B extends number,
  Num1 extends Array<number> = GetRange<A>,
  Num2 extends Array<number> = GetRange<B>,
> = Num2 extends [...Num1, ...infer R] // A < B; res = -ve
  ? `-${R["length"]}`
  : Num1 extends [...Num2, ...infer T] // A > B; res = +ve
  ? T["length"]
  : 0;

The output of this utility is either string when the output is a negative or a number when output is positive.

type subRes = Sub<50, 3>; // subRes = 47

type subRes = Sub<3, 50>; // subRes = "-47"

To understand this utility take a look at this flowchart:

Sub flowchart

Let us go through it step by step:

Sub take 2 mandatory inputs which are A and B. It also has 2 default parameters Num1 and Num2 with the default value of GetRange's of A and B.
Throughout the utility we make we make use of Num1 and Num2 because it makes easier for comparison as we will see in the next steps.
It’s easier to compare the array’s with the help of variadic tuple feature of TypeScript. We first compare that if B is greater than A , if it is then our output would be negative i.e. A-B = -res
We do that by comparing Num2 tuple with an destructured tuple of Num1 and a variadic element R. Here R represents the left over 0s from Num2 which in our case is the result.
If this is the case then we return a string -R's length.

You can imagine this calculation in this way:

Sub<2,3, Num1=[0,0], Num2=[0,0,0]>

// Inside Sub this is what happens when A < B:

Sub<2,3, Num1=[0,0], Num2=[0,0,0]> = 

[0, 0, 0] extends [...[0,0], ...infer R] // Here R's value becomes [0]

? `-[0]['length']` // -1

Similarly if A is greater than B then the output will be positive and the result of the residue is stored in T in this case which is a Tuple whose length we return as the output.

Multiplication

The Multiplication utility is a bit different than the Add and Sub. Here is how it looks like:

/**
 * Multiplies two numbers
 */
type Mul<
  A extends number,
  B extends number,
  Counter = 0,
  Acc extends Array<number> = [],
  Num1 extends Array<number> = GetRange<A>,
> = B extends Counter
  ? Acc["length"]
  : Mul<A, B, Inc<number & Counter>, [...Acc, ...Num1]>;

This utility works on the following principle:

Consider an example of Mul<2,3>, to generate an output of 6 we should add number 2 three times to get the value as 6.
So in this utility the first number, is the input that will be repeatedly added with itself B number of times which is our second input to Mul.

Here is what happens inside the utility:

Mul utility flowchart

The utility takes 2 mandatory number based inputs A and B. It takes 3 optional parameters Counter Acc and Num1 with it’s respective default values mentioned in the utility.
Since we are add A to itself B number of times therefore we need to check if we have actually done that or not. To do that we compare B with the Counter, if it matches then we return the length of the Acc i.e. Accumulator which keeps track of this addition.
Or else we again call Mul with A B, with an incremented Counter with the help of Inc utility and finally we pass a tuple with desctructure value of Acc and Num1.
The last parameter to Mul in the recursive call is important because it stores the actual results.
The Incremented counter value is also important because it helps to stop the recursion.
Here is how the Inc utility looks like, it is pretty straight forward hence not going to explain:

/**
 * Utility to increment the number
 */
type Inc<N extends number> = [0, ...GetRange<N>]["length"];

Division

Similar to multiplication utility, in Division we try to reduce the numerator by denominator till the numerator becomes 0. While this is happening we maintain the count of no. of times numerator was reduced.

For this utility we are apply the following constraints:

The numerator should be greater than the denominator.
Numerator should be perfectly divisble by the denominator.

We are going to keep these constraints to our Div utility because implementing use cases such as not divisble numbers, floating point numbers, negative numbers, recurring decimal digits etc makes the utility too complicated and is out of scope of this blog post.

Here is how the utility will look like:

/**
 * Divides two numbers
 */
type Div<
  N extends number,
  D extends number,
  Acc extends Array<number> = [],
  ReducedN extends number = GetRange<N> extends [...GetRange<D>, ...infer T] ? T["length"] : 0,
> = N extends 0 
    ? Acc['length']
    : Div<ReducedN, D, [...Acc, 0]>;

Inside the utility following things happen:

Div utility flowchart

There are 2 mandatory inputs N and D which stands for Numerator and Denominator.
Next, we have 2 optional inputs Acc and ReducedN with their respective default values.
Acc is the accumulator tuple that we use to keep a count of number of times we subtracted D from N.
ReducedN has a default value GetRange<N> extends [...GetRange<D>, ...infer T] ? T["length"] : 0 which compares the N tuple with a tuple of D and a varidiac element T. This value is nothing but subtraction of D from N. You can refer to the Sub utility for this to understand the logic.
Next, inside the actual utility we check that if N has been exhausted completely i.e. N is equal to 0. If it is then we return the length of the Acc or else we again call the Div with ReducedN as N, with same D as the denominator, and with an incremented Acc by appending 0 to it.

Limitation

The purpose of these utilities is to understand different concepts and the power of typescript. Below are some of the uses cases that are purposely not implemented since it would overcomplicate stuff and would be out of scope of this blog post:

For Add utility, we didn’t consider addition of negative numbers or combination of negative and positive numbers. This also leads to connectivity between Sub utility as well. This limitation also applies to Mul and Div
For all the utilities, operations related floating point numbers is not considered.
Due to call stack limitation of TS we cannot do operations on numbers more than 999.

Summary

I know this blogpost isn’t going to be that fruitful in real life use cases but take a look at what are the things we learned from it today:

We understood recursion and Tail recursion
How does tail recursion helps in optimizing the code by reducing the call stack consumption.
We saw how Typescript interprets numbers and also saw that we cannot do arithematic operations
We learned Typescript’s limitation of its call stack size.
We learned how we can interpret numbers in the form of tuple like GetRange and Inc.
Lastly, we saw how we can leverage the above technique to create Add Sub Mul and Div utilities.

So that’s all folks!. Hope you like my blog post.

You can follow me on twitter, github, and linkedIn.

Mastering TypeScript: Implementing Push, Pop, Shift, and Unshift in Tuples

Keyur Paralkar — Tue, 18 Jun 2024 02:05:50 +0000

Introduction

So, here's a wild thought! What if I told you that we can use JS array functions like pop, push, shift, unshift with Typescript tuple type? You might be like, why…why would we even need that? Isn't TS already hard enough? Who on earth would want to make it even more complex?

Look, I did warn you that this is a bit out there. I've kinda become a Typescript fanatic recently and I love digging into some bizarre TS stuff. Plus, it's not just for kicks. It also helps us understand a few crucial TS concepts that can come in handy when crafting your own utilities.

So let me grab your attention and share with you what we are gonna be doing.

💡 NOTE: This blog post is totally inspired by Typescript challenges here: https://github.com/type-challenges/type-challenges?tab=readme-ov-file The utilities mentioned in this blog were part of these challenges.

What are we gonna do

Its simple we are building typescript utility generics that does same operations as functions of an Array like push pop etc.

Here are some examples,

type Pop<T extends unknown[]> = T extends [...infer H, unknown] ? H : []
type Shift<T extends unknown[]> = T extends [unknown, ...infer T] ? T : []
type Push<T extends unknown[], I extends unknown> = [...T, I]
type Unshift<T extends unknown[], I extends unknown> = [I, ...T] 

type popRes = Pop<[3, 2, 1]>
type shiftRes = Shift<[3, 2, 1]>
type pushRes = Push<[3,2,1], 0>
type unshiftRes = Unshift<[3,2,1], 4>

Getting Started

Before we dive into the implementation of these utilities we first need to understand couple of basic things in TypeScript:

1. Tuple Types

A tuple type is similar to an Array type which has known types at the specified index position. A typical example of tuple would like below:

type TupleType = [number, boolean];

Here TupleType is a tuple type with number type being at position 0 and boolean type at position 1. Analogous to Javascript arrays, if you try to index tuple type out of its bounds we will get an error

type res = TupleType[2] // <------ Tuple type 'TupleType' of length '2' has no element at index '2'

For more information on typescript tuple type read its documentation here: TS Tuple Types

2. Variadic Tuples

Variadic tuples were introduced in Typescript via this PR. According to the PR, variadic tuples are:

The ability for tuple types to have spreads of generic types that can be replaced with actual elements through type instantiation

Some examples of variadic tuples are as follows:

type WrapWithStringAndBool<T extends Array<unknown>> = [string, ...T, boolean];

type res = WrapWithStringAndBool<[1,2,3,4]> // <-- [string, 1, 2, 3, 4, boolean]

If you checkout the above example, we have WrapWithStringAndBool generic that accepts an array of unknowns and returns a tuple with string and boolean tupes at the first and the last position in the tuple.

Here the ...T is the variadic element which acts as a placeholder for values from the input T.

Variadic tuples has a lot to offer and is a great piece of feature. I would like recommend to go through its rules and examples mentioned in this PR.

3. Conditional Types

Every developer knows the if else block that helps you to write conditional code. In the similar way, Typescript conditional types take the following format: condition ? trueBranch : falseBranch. This is very much similar to the ternary operator in JS.

For a type to become conditional, the condition part should consist of extends keyword:

Type extends OtherType ? trueBranch : falseBranch

Were Type if matches with OtherType then trueBranch is executed or else the falseBranch.

Conditional Types can also be used to narrow the types to provide specific types. Consider the following example from Typescript cheatsheet:

type Bird = { legs: 2 };
type Dog = { legs: 4 };
type Ant = { legs: 6 };
type Wolf = { legs: 4 };

type HasFourLegs<Animal> = Animal extends { legs: 4 } ? Animal : never;

type Animals = Bird | Dog | Ant | Wolf;

type FourLegs = HasFourLegs<Animals>; // <--- Dog | Wolf

Here we have 4 types Bird Dog Ant and Wolf with their respective legs property. Next, we have built HasFourLegs. It does the following thing:

It compares Animal object with { legs: 4 } object with the help of extends keyword.
If they are equal, Animal is returned or else nothing is returned.

In the last line we make use of HasFourLegs by passing it the Animals union type. A thing to note here is that, when an Union type is provided to the left side of the extends keyword then all the values of Union are distributed such that each value is tested against the object { legs: 4 }. You can read more about the distributive nature of unions over here.

4. Inferring Within Conditional Types

Conditional types can also be used to infer types when we do comparison with the help of infer keyword. For example, consider the TS utility ReturnType. This utility returns the return type of the function that is being passed to it. Internally it works in the following ways:

type GetReturnType<T extends (...args: any[]) => any> = T extends (...args: any[]) => infer R ? R : never;

type res = GetReturnType<() => number> // <--- number

In the trueBranch of the above example if you closely observe that we make use of infer R. Here we tell TS like while comparing if T matches the format to the right of extends then place the return type of function in R.

When we pass () => number to the GetReturnType a number is returned since it matches the format to the right of extends keyword in the generic.

Now that we are clear with our basics, let us start with writing our first utility. Pop

Pop

In Javascript a pop function would remove the last element of an array. To build this in Typescript, we do the following:

type Pop<T extends unknown[]> = T extends [...infer H, unknown] ? H : []

Let me example what is happening here:

We tell TS that Pop is going to be our generic with parameter T which can be an array of unknowns.
Next, with the help of this: T extends [...infer H, unknown] we tell TS that the first N-1 elements of the tuple/array T should be inferred with H and the Nth i.e. the last element should be inferred as unknown.
If the Tuple T matches this pattern then H is returned or else we return an empty array.

Shift

Javascript array’s has another built-in function that helps you to remove its first element. This is an in-place operation that affects the original array. The returned value by this function is an array’s first element. Here is a quick look of this function:

let x = [1, 2, 3, 4];
const firstElement = x.shift();

firstElement // <----- 1
x // <----- [2, 3, 4]

Similar to shift function, we can create a generic utility in Typescript that removes the first element from a tuple type. Here is how it’s the utility will look like:

type Shift<T extends unknown[]> = T extends [unknown, ...infer R] ? R : []

The Shift utility here expects it’s input to be an tuple. In this case, since we don’t exactly know the types inside the tuple hence we extend input T as unkown[]

To the right hand side, we have:

We are making using of conditional types, were we check if T matches the following pattern [unknown, ...infer R].
- We can also identify the things that we learned in the getting started section.
- We make use of extends keyword to create a conditional types.
- We also make use of variadic tuple types, where in the right side tuple of extends we have a inferential variadic element R
If the condition is met we return R which is the remaining element of the tuple.

Push & Unshift

Similar to Javascript’s push built-in function that appends a new element to the array, we can also create a similar utility:

type Push<T extends unknown[], I extends unknown> = [...T, I]

This is one of the simplest utility from all. The key aspect of this Utility is that,

We make use of destructing of tuple concept with ...T inside a new tuple.
To this tuple at the end we add I
Together this utility would return a new tuple type that combines the elements from T and adds I at the end.

Here is the result for the same:

type res = Push<[1,2,3], 4>

res // <----- [1, 2, 3, 4]

Similar to this we have Unshift as well:

type Unshift<T extends unknown[], I extends unknown> = [I, ...T]

Summary

In this blog post, we covered:

Tuple Types
Conditional Types
Variadic Tuple Types
Conditionally Inferred Types

Lastly, we explored the Push, Pop, Shift, and Unshift generic utilities in TypeScript, which are analogous to their JavaScript counterparts.

Thanks a lot for reading my blogpost.

You can follow me on twitter, github, and linkedIn.

Mastering Mapped Types in TypeScript and it's Practical Applications

Keyur Paralkar — Tue, 04 Jun 2024 07:28:52 +0000

Introduction

When I was new to typescript, I used to write basic interfaces and object types. I didn’t you use to pay much attention towards the reason of these types and nor use to think it from scabality perspective.

I later on decided to level up myself in the TS game. So I started with the typescript challenges where I began with easy problems then went on to the complex ones. The challenges are well structured so that you can learn the basics. But what helped me the most was to analyze the solution of other folks on Github Issues and Michgan Typescript’s youtube channel. This increased my understand of Typescript by 10x.

These challenges has inspired me to write code that is:

Scalable
Structured
Typesafe
Less error prone

I started to understand Typescript in a deeper way. All these challenges has inspired me to write this blog post about mapped types in Typescript. So in this blogpost, I am going to talk about Mapped typescript type in brief and explains its real-life applications in detail.

💡 NOTE: These application of mapped types can be found in the challenges of typescript shared above.

What are Mapped Types in Typescript?

Mapped types in TS is nothing but a way through which you can traverse the properties of the typescript object type and modify them as you require.

To quote the TS cheatsheet:

Mapped Types acts like a map statement for the type system, allowing an input to change the structure of the new type

Consider the following the following type:

type Vehicle = {
    type: 'Car',
    noOfWheels: 4,
    color: 'white'
}

Now imagine that you need to generate a new type from the Vehicle type such that all the parameters are optional. Here mapped types can be used to effectively get this requirement right like below:

type Car = {
    [P in keyof Vehicle]?: Vehicle[P] 
}

This would generate all the properties that are optional. This is a simple use case but mapped types can do a lot more exciting stuffs. You can read how you can modify the properties in the mapped typed in this section of the TS docs: https://www.typescriptlang.org/docs/handbook/2/mapped-types.html#mapping-modifiers

With this understanding of mapped types, let us start with some real life uses cases

Usecase #1: OmitByType

If you are a typescript dev then you most certainly have used this TS utility called Omit. It helps you to construct a new type from the existing type by removing the keys mentioned in the second parameter of Omit.

Take a look at our Vehicle example with Omit utility:

type Vehicle = {
    type: 'Car',
    noOfWheels: 4,
    color: 'white'
}

// Let us Omit noOfWheels

type OmmitedVehicle = Omit<Vehicle, 'noOfWheels'>

/* 
type OmmitedVehicle = {
    type: 'Car',
    color: 'white'
} 
*/

Here we are removing the property noOfWheels from Vehicle i.e. we are removing properties based on a property name. What if we wanted to remove a property based on the type we pass as second argument to Omit

For example, we would like to remove all the properties from Vehicle who’s values are string i.e. remove type and color property.

At this moment TS doesn’t have any such utility to Omit by Type. But we can build this easily with the help of Mapped types and Generics

Let us first define what we want here. We want are utility to:

It should accept 2nd argument that tells the properties to remove based on type.
Traverse through each property of the type
If the value of the property is equal to the 2nd argument it should exclude it

But before we start our implementation we should take a look at how the original Omit utility type works:

type Omit<T, U> = {
  [K in keyof T as Exclude<K, U>]: T[K]
}

It first traverses through each key of the T type with the help of:

K in keyof T

In terms of our Vehicle example, K here is the property name that the mapped type will traverse i.e. type noOfWheels color. Next, with the help of as clause we remap the key such that we exclude the key K if it matches the 2nd parameter of the Omit Utility. Again if you see the internal working of the Exclude utility provided by TS it is as follows:

type Exclude<T, U> = T extends U ? never : T

This means that if T and U matches then it returns never or else it returns the type T. This also means that on the match of both the type we don’t want to return anything which is never. This becomes useful in the Omit case as follows:

If key K in the above mapped type matches with the 2nd parameter i.e. U then we should not include it in the mapped type. This case can be visualised as follows:

type Vehicle = {
    type: 'Car',
    noOfWheels: 4,
    color: 'white'
}

type OmmitedVehicle = Omit<Vehicle, 'noOfWheels'>

/*
Internally this happens:

type OmittedVehicle = {

}

which truns into: 

type OmittedVehicle = {

}

and a key in mapped type that is mapped to never becomes excluded from the mapping.
Ideally this would return a blank object like `{}`
*/

So this gives a new type constructed by omitting properties by name. Getting this understanding was important so that you can easily grasp the concept of our utility: OmitByType. Here is the utility:

type OmitByType<Type, DataType> = {
  [K in keyof Type as Exclude<K, Type[K] extends DataType ? K : never>]: Type[K]
}

Just watch this utility type carefully. Isn’t it pretty similar to the original Omit type. Yes, indeed it is but there is a small change which is in the Exclude’s 2nd parameter:

Type[K] extends DataType ? K : never

Earlier in the Omit type we directly put U as the 2nd parameter to exclude. But here we are doing the following things:

Since we are accepting the type to omit is DataType in our OmitByType utility, we compare it with the current property’s value. Here the current property is Type[K]
If it matches with DataType we pass this property K to the exclude or else we return never.

Things will get clearer when do the dry run. For the dry run let us again take the Vehicle example from above:


type Vehicle = {
    type: 'Car',
    noOfWheels: 4,
    color: 'white'
}

type OmitByType<Type, DataType> = {
  [K in keyof Type as Exclude<K, Type[K] extends DataType ? K : never>]: Type[K]
}

type OmittedCarByType = OmitByType<Vehicle, string>

For the above give code the dry run will look like below:

Key	Value	Value Type	Condition Check (Value Type extends string?)	Exclude	Action
type	'Car'	string	Yes	Exclude type	Exclude type
noOfWheels	4	number	No	Include noOfWheels	Include noOfWheels
color	'white'	string	Yes	Exclude color	Exclude color

This utility type was a solution to the following typescript challenge: https://github.com/type-challenges/type-challenges/blob/main/questions/02852-medium-omitbytype/README.md

Usecase #2: PartialByKeys

This utility is again very similar to the Omit utility. PartialByKeys will take second argument as union of keys that needs to be made partial/optional in the Type argument T.

Here is how this utility will look like:

type Flatten<T> = {
  [K in keyof T]: T[K]
}

type PartialByKeys<T extends {}, K extends keyof T = keyof T> = [K] extends [''] ? Partial<T> : Flatten<Omit<T, K> & Partial<Pick<T, K>>>

Let me simplify this a bit and explain you guys the working of it:

Here we have created a generic utility called PartialByKeys that take in two arguments T and k. T is expected to be of type object and K is expected to be of keys of T and is initialised with keys of T object type.
Next, we first check that if Keys K are blank or not. If it is then we should return an object type who’s all the keys are optional.
- Notice this syntax here that is used:
```
[K] extends ['']
```
- The purpose of using square bracket here is because we don’t want to have distributed conditional types.
If K keys are not blank then we should return a new object type with the specified keys as optional/partial.
- Here we do a clever trick by separating out the keys that are not needed to be partial we keep it with the help of Omit<T, K>
- The ones which we want to make partial we first construct a new object type with the keys that needs to be partial. We do that with the help of Pick.
```
Pick<T, K>
```
- Next me this entire pick partial with the help of Partial<Pick<T, K>>.
- Lastly we combine these both objects into one.
- Quick note: We also make use of Flatten utility so that you can get a clear type annotation instead of a messed up partial + Pick keys

Here is the Dry run of this Utility with the Vehicle example:

Key	Value	Included in Omit?	Included in Partial>?	Final Inclusion	Optional?
type	'Car'	Yes	No	Yes	No
noOfWheels	4	Yes	No	Yes	No
color	'white'	No	Yes	Yes	Yes

Usecase #3: PickByType

In PickByType, we pick all the properties of object type who’s value matches with the type specified in the utility as the second argument.

Here is how PickByType looks like:

type PickByType<T, U> = {
  [P in keyof T as T[P] extends U ? P : never]: T[P]
}

The only thing that differentiates this with OmitByType is the way we make use of the as clause. Here we make use of as clause such that only the keys will be shown who value of T[P] matches with U i.e. second parameter.

Here is the dry run of this utility on the Vehicle type:

Key	Value	Value Type	Matches string?	Include Key in Result?
type	'Car'	string	Yes	Yes
noOfWheels	4	number	No	No
color	'white'	string	Yes	Yes

Summary

At first typescript might look crazy difficult to understand, to follow and might look like some wizardry. But trust me it gets simpler when you learn the basics and start practicing.

So in this blog post we learned about Mapped types and its crazy ass use cases. We also learned some internal workings of the existing TS utility types such as Omit and Exclude.

Thanks a lot for reading my blogpost.

You can follow me on twitter, github, and linkedIn.

How to Simplify Your Code with TypeScript Discriminated Union Types

Keyur Paralkar — Sun, 26 May 2024 07:40:45 +0000

Introduction

This will be my first time writing about TS. There are multiple tutorials out there which explain the concept of discriminated unions in an outstanding way. But I will I try my best to explain here my understanding about the concept and how I approached it.

In this blogpost, we are going to learn about discriminated union types. We will also look at how it is an excellent concept that makes developer’s life less miserable. You will also get to see some realtime examples.

What are discriminated Union Types?

Let me be a good dev and explain this concept by explaining the problem and then the solution.

Problem Statement

An interface or a type can represent multiple states. And based on these states the other properties in the interface can differ. For example,

A network response has the following structure

// For successful request
{
    "status": '200',
    "payload": {...}
}

// For failure in request
{
    "status": '400',
    "error": {...}
}

As you can see, based on the status property the rest/some of the properties might be present or may note be present.

A general shape interface can have multiple properties that might not be present in all the shapes:

{
    "type": 'Circle',
    "radius": 50
}

{
    "type": 'Square',
    "sideLength": 10
}

Now their interfaces will look something like below:

Now suppose for the Response interface we want to write a utility function that logs the response in different format like below:

Both of these blocks will have access to the successPayload and errorPayload i.e. we know that type 200 means a successful request and we want only to get successPayload and nothing else. Similar is the case for the type 400

The mental model for the types we have is a mapping of status state i.e. type value with the rest of the parameters.

As you can see this is a very common problem that all the developers face. To resolve this and tell typescript to distinguish between different values of types we need to make use of Discriminated union types of typescript.

Discriminated Union Types

This is a nice little feature that Typescript provides that helps the TS itself to distinguish between which rest of the parameters to choose based on a common property between them. Let us restructure our above example of NetworkResponse interface:

Now if we try use the displayNetworkResponse function we won’t get any type errors.

Realtime Use case

I have always faced this issue while using the React’s Context APIs where I have my actions ready with me and each and every action would have a different payload property. But when I am building my reducer function I don’t get the narrowed typing based on the action case I am in inside the switch case. Let me demonstrate this with an example.

Suppose you have these set of actions with you:

These are simple actions like adding and removing a TODO from a list

Next, we define the action creators or the functions that dispatch the action like below:

import { ACTIONS } from "./actions";

export const addTodo = (id: number, text: string) =>
  ({
    type: ACTIONS.ADD_TODO,
    payload: {
      id,
      text,
    },
  });

export const removeTodo = (id: number) =>
  ({
    type: ACTIONS.REMOVE_TODO,
    payload: {
      id,
    },
  });

As we see here the payload attribute of both the actions is different. For ADD_TODO action the payload attribute consists of id and text and for REMOVE_TODO action we just pass an id attribute.

Now let us define our reducer function like below:

import { ACTIONS } from "./actions";

export const reducer = (state, action) => {
  switch (action.type) {
    case ACTIONS.ADD_TODO: {
      const { payload } = action;

      payload.text;
    }

    case ACTIONS.REMOVE_TODO: {
      const { payload } = action;

      payload.id;
    }
  }
};

In both the action cases TS is not able to decide the types for the payload. It will display typings as follows:

const payload: {
    id: number;
    text: string;
} | {
    id: number;
}

But this is not what we want. We expect that when the ADD_TODO action is being used as the payload attribute then it should consists of id and text attribute and for REMOVE_TODO we expect that it should consists of only the id attribute. How can typescript know this mapping? Discriminated Union Types to the rescue.

We need to return the ActionTypes type from the actions file like below:

ActionTypes here is a type that will be a union of return type of addTodo and removeTodo function. Here the common property to discriminated will be the type property in both function’s return type. Now making use of this type inside the reducer function like below, helps us to achieve what we wanted:

Now if you check the payload attribute in each section then we are able to see that payload types are getting changed based on the action type.

So this is the magic of Discriminated Union Types.

Summary

I feel discriminated union type is the most underrated feature for typescript. I believe every developer should use it to have better type narrowing that will help to write better and predictable code.

Thanks a lot for reading my blogpost.

You can follow me on twitter, github, and linkedIn.

Build a Realtime Collaborative Whiteboard with Supabase & React

Keyur Paralkar — Sat, 11 May 2024 17:34:21 +0000

Have you guys every tried to use figma or miro? If you have used it then I am pretty sure you might have seen this feature where all of a sudden you start to see multiple cursors on your figma file or miro board. If you haven’t seen this ever yet, here is the quick video of what I am talking about.

Figma's Realtime Experience

Miro's Realtime Experience

Isn’t it sleek. I mean just look at it, it looks so cool. Can you imagine how they must have build this feature? What did it take to build this to provide such a good dynamic user experience? Bye bye screen share, just follow that persons cursor and here to the audio in the meeting and you are good to go.

I just love this feature. So I set out on a quest on understanding the feature and what would it take to build such a feature. I must say it was really a pain to understand it TBH but things got way easier later. So let us dive deeper into the understanding and implementing this project.

The What?

We are trying to build sticky notes board application, in which we are able to see multiple cursors and sticky notes as a status of what other users are doing on the same website. In this project every user has the information about all the other users, like where their cursor is moving, what they are typing, which note they are dragging etc.

To give you guys an idea here is the video that shows the application in action:

Realtime App in action

Prerequisites

To get the most out of this blog post, I highly recommend that you guys be familiar with the below topics:

The Why?

So I know and this question might have arrived to you as to why are we doing this. We are doing this because:

To gain insights on how innovative UX works.
Understand some critical UX decisions

Some backstory

So before we dive into the implementation, I would like to share a few things about this project(my personal exp.). During this project I studying a ton about webRTC. I started studying webRTC from scratch, like what is webRTC? how is the connection formed? how the data transfer takes place.

I took this decision of choosing webRTC because I thought each client needs information about every other client connected over the network/room. So isn’t this same as the video conferencing apps like Microsoft Teams, Zoom, Google Meet etc. In these apps, every client knows about every other client and they share the stream of data directly with the help of webRTC(that’s what I thought). But it turns out it’s not that simple, this would create a mesh kind of a network and would be resource intensive over the network. So there are better protocols/patterns to handle such cases like SFU(Selective Forwarding Unit).

Ok I went too back, but you guys get the point right. So I though it’s just a simple project. rather than having multiple streams of video shared between each other I just need to replace it with the cursor position of every other client. How hard can it be right? actually its very hard.

I tried to first implement the webRTC full mesh pattern just to understand how every client would share their stream with others. But managing the connection i.e. offer negotiation in webrtc got way tricky when more than 2 clients came in so I dropped the idea.

So instead, I pivoted and moved on to what supabase’s realtime DB does. I actually used it in this project. Yeah, so that was the backstory but let’s continue.

The How?

This is the part where we understand the implementation of the entire project. I have used the following tech stack:

For Frontend - React.js and Vite
For Backend - Supabase

Before getting into the frontend, let us understand what the backend is and how it helps us to achieve our results.

💡 NOTE: This blog post is not going to be a step-by-step guide but rather a walk through to the codebase along with the detailed explanation of the concepts/architecture

Enter Supabase

Supabase is a backend as a service visual platform that allows you to create postgres DB with minimum code. Their documentation is so good that it feels like home and you can get your project online in no matter of time.

So this cool low-code no-code platform provides a realtime feature that lets you do a bunch of stuffs:

Listen to updates to the DB inserts, updates and any other changes
Update your frontend state globally with Presence API
You can also broadcast your changes to all the connected clients.

Out of these 3 we are going to make use of the Presence API.

Requirements

So let us look at the things we need to build our Sticky notes board app:

We need a way to have a live cursor feel i.e. my screen should also show where other folks are moving their cursors
We also need a way to let my screen know that what others are doing like, adding a note and moving the note
If any of the folks closes their browser window, then my screen shouldn’t contain changes from the guy who left.

All of these requirements can be achieved using the Supabase’s Presence API. It is the perfect recipe to achieve our thing.

Before we start going in depth on this API we first need to understand what channels are.

Channels:
- This is the basic building block of the realtime feature.
- Channel is where all the clients connect to. Imagine that Channel is nothing but a room where all the people can join in.
- Whenever a new client comes in, we need to make sure that it connects to this room/channel.
- You can find details regarding the same here

Now let us understand the Presence API. It is an API that helps you share your current client state with all the other clients. It does that with the help of the track function. So a typical track function call will look like below:

const channel = client.channel('room1'); // creates a channel 'room1' 

channel.track({
    clientId: '123',
    color: 'red'
})

Each channel has a common pool of states for all the clients. Now if a user, suddenly closes his tab i.e. if the client is removed from the channel then this state is also updated. We will look at the details of the other events like join leave and sync of the presence API in the later section of this blog post.

Now that we know the presence API, so let us start off our journey to understanding the project architecture.

Project Setup

A little detour here, I would like to talk about the frontend tooling/project environment here. From the frontend standpoint I am using Vite to create the project scaffoldings. I have used a typescript template of Vite since the project is build with typescript.

yarn create vite --template react-ts

Make use of the above command to create a Vite project with react based typescript template.

From the backend standpoint, I am making use of supabase’s local setup. I won’t be covering that in this blog post because supabase guide has done a pretty nice job at explaining it here.

Other libraries used are as follows:

Supabase-js: This is the client side wrapper of supabase. You can read more about it here
Nonoid: A library that helps you to generate unique string ids. Read the full documentation here

Project Architecture

So we are all set from the project setup standpoint. So let us now understand by how the flow of the application would be:

Whenever a new tab is opened with our project on our browser that means we need to create a new client instance of supabase. So we start by creating a client.
Next, we create a channel so that the client gets added to that channel
We listen for the sync and leave events of the Presence API
On update of user activity we need to pass this data to all the other clients
If the browser window is closed, we need to make sure that all the clients won’t contain data related to the removed client.

Project Architecture

After gaining this knowledge of the application flow we are in a good state to understand the implementation details. As I mentioned earlier since this is not going to be a step-by-step code walkthrough but an in depth core understanding blog post.

Now let us familiarise ourselves with the repository structure:

There are 3 files that we need to carefully look at:

App.tsx - The driver program where entire logic resides
component/Cursor.tsx - An SVG cursor component to show the pointer of the other clients
component/StickyNote.tsx - A component to show the stickynote that is editable.

We will go through each and every file to understand the application flow:

NOTE: I would highly recommend to open each file while you are reading the details of each file structure. In that way you won’t get lost.

App.tsx

Refer to this component while reading the below section.

This file will get loaded as soon as the browser tab hits our project URL. So according to the flow we should instantiate a supabase client which we do it like below:
```
const clientA = createClient(SUPABASE_URL, SUPABASE_KEY);
```
- You can read more about createClient function here: https://supabase.com/docs/reference/javascript/initializing
Once the client is instantiated, we expect that it should create a channel like below:
```
const channel = clientA.channel("room-1");
```
- For a new client it will check that the channel with room-1 exists or not. If it exists, it joins the channel or else create one.
On mount of our main app here: , we expect the client to subscribe to the presence API’s sync and leave events. To do this we first create the event handlers that listen to these events like below:

useEffect(() => {
            channel.on("presence", { event: "sync" }, () => {
                const newState = channel.presenceState<Clients>();

                // code to manage the state once other client updates
        }, []);

useEffect(() => {
            channel.on<{ clientId: string }>(
                "presence",
                { event: "leave" },
                ({ leftPresences }) => {
                    // code to manage the state when any user leaves
                }
            );
        }, [removeClient]);

Upon adding these event handlers we then subscribe them along like below:

useEffect(() => {
            if (isFirstRender.current) {
                subsChannel.current = channel.subscribe();
                isFirstRender.current = false;
            }
        }, []);

This effect will execute on mount of the component. We also need to make sure that we don’t accidentally call the subscribe method more than once or else supabase will throw an error. This issue won’t happen in production but in strict mode i.e. in development mode this effect would run twice. That’s the react’s way to make sure that things are predictable.

So to avoid this, I added a ref isFirstRender. It gets set to false when the effect runs the second time in strict mode.

There is one thing to take note of and that is the structure of the data that we are syncing between all the clients. It is as follows:

    export enum EventTypes {
        MOVE_MOUSE = "move-mouse",
        MOVE_NOTE = "move-note",
        ADD_NOTE = "add-note",
        ADD_NOTE_TEXT = "add-note-text",
    }

    export type Note = {
        x: number;
        y: number;
        content: string;
    };

    type Payload = {
        eventType: EventTypes;
        x: number;
        y: number;
        color: string;
        notes: Array<Note>;
    };

    export type Clients = Record<string, Payload>;

These are the typescript types but they translate to something like below:

    {
      "W3lf6J4shQUfE-DTkILBb": {
        "color": "rgb(15%, 30%, 40%)",
        "eventType": "move-mouse",
        "x": 829,
        "y": 235,
        "notes": [
          {
            "content": "This is note from client W3lf",
            "x": 202,
            "y": 350
          }
        ]
      },
      "JRlR_3qHr7B2bad2HVvWE": {
        "color": "rgb(94%, 30%, 40%)",
        "eventType": "move-mouse",
        "x": 16,
        "y": 65,
        "notes": [
          {
            "content": "This note from client JRIR",
            "x": 198,
            "y": 729
          }
        ]
      }
    }

This would be a typical state that each client will hold. We also tell each client to hold the states of all the other clients as well which happens in the newClients state variable.

Now let us understand how each client get synced with all the other clients. Each client has 3 points where they update their own state:
- When the mouse move happens,
- When the note is added &
- When the sticky note is moved.
- When the sticky note is edited
Whenever any of these scenarios happen we call their respective event handlers. So as you expect,
- For the mouse move we would use onMouseMove ,
- When note is added we use onClick of the button present on the screen,
- For editing of sticky note, the onChange event of sticky note component is used.
- And finally when the note is moved we use onMouseMove of the StickyNote component.
And for all these scenarios they update their states with the help of channel.track function. It is a presence API function that send the update to all the other clients connected to the channel. You can read more about this function here.

Now to make our scenarios work, we make use of the following event handlers:

const handleMouseMove = (event: React.MouseEvent<HTMLDivElement>) => {
            throttledChannelTrack({
                [CURRENT_CLIENT_ID]: {
                    ...newClients[CURRENT_CLIENT_ID],
                    eventType: EventTypes.MOVE_MOUSE,
                    color: randomColor,
                    x: event.clientX,
                    y: event.clientY,
                },
            });
        };

        const handleNoteAddition = () => {
            const currentClient = newClients[CURRENT_CLIENT_ID];

            // We want to add notes immediately, hence not using throttled version of track():
            subsChannel.current?.track?.({
                [CURRENT_CLIENT_ID]: {
                    ...currentClient,
                    eventType: EventTypes.ADD_NOTE,
                    notes: currentClient.notes
                        ? [...currentClient.notes, DEFAULT_NOTE]
                        : [DEFAULT_NOTE],
                },
            });
        };

        const handleNoteMouseMove = (currentNote: Note, noteIndex: number) => {
            const currentClient = newClients[CURRENT_CLIENT_ID];

            const notes = currentClient.notes;
            notes[noteIndex] = currentNote;

            throttledChannelTrack({
                [CURRENT_CLIENT_ID]: {
                    ...currentClient,
                    eventType: EventTypes.MOVE_NOTE,
                    notes,
                },
            });
        };

Notice the throttledChannelTrack function. It is a throttle function, used only for frequently happening events such as mouse move and sticky note moves. For scenarios like note addition we directly make use of the channel.track function.

CURRENT_CLIENT_ID is the random unique string Id generated by nanoid that gets generated whenever the client is opened on the brower’s tab.

It’s nice to observe that on each track call we update the current client’s state and also keep its existing state as well.

Once the track function is called, then immediately the presence API’s sync event handler gets executed. It is the general working of the API that whenever a track call happens sync event handler gets executed. So now if the current client does any of the above scenarios, it will call the track function with the above payload and execute the sync event handler.

In our case, we need to make sure that we do the following things when this event handler executes:

- Capture the `presenceState` from the channel. This is a state that the channel maintains that consists of all the latest updates(presence events) made from all the other clients.
- Iterate through all the presence events and update the `newClients` state with all these presence events.
- What we are doing here is, all the presence event is nothing but each client’s own state from all the other clients. We are just capturing all the other clients state into the current client and updating it in a state variable called `newClients`.
- In this way, we keep track of other clients:

useEffect(() => {
            channel.on("presence", { event: "sync" }, () => {
                const newState = channel.presenceState<Clients>();

                const presenceValues: Clients = {};

                Object.keys(newState).forEach((stateId) => {
                    const presenceValue = newState[stateId][0];
                    const clientId = Object.keys(presenceValue)[0];

                    presenceValues[clientId] = presenceValue[clientId];
                });

                setNewClients((preValue) => {
                    const updatedClients = Object.keys(presenceValues).reduce<Clients>(
                        (acc, curr) => {
                            acc[curr] = {
                                ...preValue[curr],
                                ...presenceValues[curr],
                            };
                            return acc;
                        },
                        {}
                    );

                    return updatedClients;
                });
            });
        }, []);

One last thing that I would like to discuss here, is the updating the UI whenever a client is removed. We don’t want our UI to get cluttered from the sticky notes from the clients who have left the channel. Have a look at this video to get clear understanding of what I am saying:
- This is pretty easy to achieve. We just need to add an event handler for the leave event of the presence API and update the newClients state variable with the current sync state between the clients. Here is the code for it:

useEffect(() => {
                channel.on<{ clientId: string }>(
                    "presence",
                    { event: "leave" },
                    ({ leftPresences }) => {
                        const { clientId } = leftPresences[0];
                        removeClient(clientId);
                    }
                );
            }, [removeClient]);

That’s it for the entire application logic. Let us now take a brief look on the UI components. UI components are pretty straight forward. They would taken a bunch of props and display it in a good manner.

Cursor.tsx

Refer to this component while reading this component

This component would take in the x and y coordinates and the name of the client and show them in a good nelly welly way. Have a look at the below cursor image:

Custom Cursor

A quick thing to note about this component is that, it will render all the cursors expect for the current client/browser window. This is a UI descision that I took. I took this decision because we don’t want to show another pointer apart from the current pointer that we see i.e. the actual one.

StickyNote.tsx

Refer to this component while reading this component

This component simply renders all the notes in that are stored in the newClients state variable. It takes in the x and y coordinate of the current note and the content inside it.

One important thing about this sticky note is that even for the current client we show it’s note. This makes sense right because we want to know and see that we added a sticky note and it should appear on the screen hence this decision.
This component add a bit of jazz to the entire flow. What it would do is, it will highlight the notes from the other clients onto your screen. Your current sticky notes won’t be highlighted. In this way, we make clear distinction as to which note belongs to whom. Have a look at this small video/gif:

Sticky Notes Component

You can even see that the color of the cursor matches with the highlights of the sticky notes for the clients that are external to the current clients.

Summary

This project gave me good learnings. Below are some of them:

Use a callback function with the setter to update state variables effectively, avoiding infinite renders caused by placing state updates in useEffect hooks triggered by dependency changes.
Avoid initializing state variables with props to prevent potential issues where subsequent prop changes are not reflected. Instead, update the state when props change to ensure accurate data representation.

Overall in this blog we looked at:

Why are we doing this project
Understood the backstory
Project Architecture
Presence API
UI components: Cursor and Sticky notes
Hiding the cursors and highlighting sticky notes for better user experience.

The entire codebase for this project can be found here

Thank you for reading!

Follow me on twitter, github, and linkedIn.

Rendering a Million Rows in React by Drawing

Keyur Paralkar — Sat, 23 Mar 2024 13:28:23 +0000

Introduction

A couple of weeks ago, I stumbled upon a challenge known as the one billion row challenge. I found it intriguing from two perspectives:

What would happen if I attempted this challenge on the front end?
Can I accomplish it?

I don’t believe we can render billions of rows onto a table, but I do think we can handle a million. That’s correct. After reading about the aforementioned challenge, I embarked on a small mini-project to render a million rows in React.

Let me provide you with a detailed account of what happened, how it happened, and why 🙂

Prerequisites

I recommend you folks to go through the below topics to have a better grasp of the topic:

The What?

What we are trying to build is a component that will help us to render a million rows in a ReactJs App. We make use of several techniques that are being used by other products such as google sheets and glide data grid app to achieve it.

The Why?

I explained why I did this in the above introduction section but there are more reasons for it.

I think everyone might have encountered a scenario where they use virtualization to render only the rows in the table's viewport. This is a pretty common use case i.e. to render a lot of data via this technique.

But this technique can get slightly frisky/risky when you set the window size to be large i.e. 150 to 250 rows that need to be viewed in a single go. This tells the virtualization algorithm for these many rows to do this:

Remove all the DOM elements in the viewport
Then add the next set of 150+ DOM elements.

While doing this on scroll this operation can get pretty expensive and can bog the main thread leading to a laggy user experience.

Apart from this I also explored other tools and libraries such as:

They have done a pretty good job of rendering a million rows.

Now you know these reasons, so let us understand the uncommon way to solve this common problem.

💡 NOTE: This is a blog to explain all the key concepts required to build this project. You can have a look at the entire code in this repository.

The How?

To implement this, we will be taking the approach of drawing instead of rendering a table. In this, we will draw every data row with the help of the canvas element.

Canvas HTML element is the go-to element for any drawing stuff. Its context APIs provide many functions that can help you to draw any shape that you like.

Now we know what are we going to use, therefore let us understand the implementation steps. The implementation is divided into 3 simple parts:

Loading the Data
Initializing the Canvases
Drawing the data on a scroll

We will go into every step and understand them. To keep this blog simple, I will try to explain all the above steps visually and will keep the coding part to a minimum.

I expect that you guys can go through the code and have a look at it from the above note section.

Initializing the Project

I make use of the Reactjs project starter kit: Vite.js. It will help you to create scaffoldings for your project

I have made use of the typescript template, to do the same follow this tutorial: https://vitejs.dev/guide/#scaffolding-your-first-vite-project

Next, please refer to the repository which contains the full code for the project to familiarize yourself.

Loading the Data

UI for loading the data

This step involves the creation of a couple of buttons that download the data from the remote source. So on the UI, we have 4 buttons that download the same data with different numbers of rows i.e. 100, 0.5M, 1M, and 2M rows respectively.

At the click of a button, the data is downloaded and parsed into an array of objects with the help of papa-parse library.

Understanding the DOM structure

Before we jump into the next steps, I would like to take a step back here and explain the DOM structure of the table that we are going to draw.

It will just look like a normal table, like below:

Table UI

It just feels like a normal table with a header and rows and scrollbars.

This image of the table is divided into the following parts such that each part represents that DOM element in the project:

header-canvas - It is the canvas element on which we draw the table’s header.
target-canvas - It is the canvas element on which the table’s actual rows are drawn
scrollbar-container - It is a div element that provides the dummy scrollbar to the main-container
main-container - A div element that wraps both the header-canvas, target-canvas, and the scrollbar-container

To give the exact overview of these elements here is the gif:

DOM Structure Disassembled

You can look at the DOM structure from a code standpoint here.

Initializing the Canvases

Now that we got to know what is what, let us dive into the step of initializing both canvases. We do the following steps to initialize:

Whenever the component is mounted we initialize a web worker like below:

/**
     * On component mount, initialze the worker.
     */
    useEffect(() => {
        if (window.Worker) {
            // Refer to the Vite's Query Suffix syntax for loading your custom worker: https://vitejs.dev/guide/features.html#import-with-query-suffixes
            const worker = new CustomWorker();
            workerRef.current = worker;
        }
    }, []);

Next, when the CSV data is available we run the effect that updates the header-canvas and then pass on the target-canvas to the webworker:

/**
     * This effect runs when the downloaded data becomes available.
     * It has the following purpose:
     * 1. Draw the table header on #header-canvas
     * 2. Transfer the control to the worker
     */
    useEffect(() => {
        const canvas = canvasRef.current;
        const headerCanvas = headerCanvasRef.current;

        if (headerCanvas) {
            const headerContext = headerCanvas.getContext("2d");
            const { width, height } = DEFAULT_CELL_DIMS;
            const colNames = CustomerDataColumns;

            if (headerContext) {
                headerContext.strokeStyle = "white";
                headerContext.font = "bold 18px serif";

                for (let i = 0; i < DEFAULT_COLUMN_LENGTH; i++) {
                    headerContext.fillStyle = "#242424";
                    headerContext.fillRect(i * width, 0, width, height);
                    headerContext.fillStyle = "white";
                    headerContext.strokeRect(i * width, 0, width, height);
                    headerContext.fillText(colNames[i], i * width + 20, height - 10);
                }
            }
        }

        /**
         * We transfer two things here:
         * 1. We convert our #canvas that draws the actual table to an offscreen canvas
         * 2. We use the transfer the above canvas to the worker via postMessage
         */
        if (workerRef.current && csvData && canvas) {
            const mainOffscreenCanvas = canvas.transferControlToOffscreen();
            workerRef.current.postMessage(
                {
                    type: "generate-data-draw",
                    targetCanvas: mainOffscreenCanvas,
                    csvData,
                },
                [mainOffscreenCanvas]
            );
        }
    }, [csvData]);

A thing to note here is that we convert the target-canvas into an offscreencanvas. An offscreen canvas is similar to a canvas element but it is decoupled from the DOM. You can even create the canvas with the new keyword and pass it on to the worker.

The fun fact about offscreen canvas is that, it is also available inside the worker’s context. In this way, it also allows to use of the canvas’s context API from the worker.

In our case, we converted the target-canvas to an offscreen canvas with the help of transferControlToOffscreen function(read here). By this, If I try to draw a rect with fillRect function of the context API from the worker , then it appears here on the main canvas which is present in the DOM.

To read more about the offscreen canvas API, read here.

Pictorial Summary of What we are doing in this Step.

Big Brain Time

Buckle up, guys!! because in this section there is going to be a lot of understanding and grasping of the concepts so that you can understand the codebase in the project.

This section will talk about the entire mechanism of drawing the data onto the target-canvas while you are scrolling.

Understanding the `Scrollbar-container`

So first let us understand our special container i.e. the scrollbar-container that we talked about in the above section.

So a normal div element will have scrollbars if it has its width and height property to be set to x px i.e. static values along with its children’s height exceeding this parent height.

But let me ask you guys a question: Have you ever encountered a scenario where you don’t have any overflowing content inside the div but still want the scrollbars?

There are a couple of solutions like: using custom scrollbar libraries such as simplebar, or OverlayScrollbars. So even though u make use of these libs there is still a scenario of by how much height you want to scroll your container i.e. having a custom scrollable height to your div.

But how would we achieve such functionality? It’s way simpler than you think. I learned this trick when I was exploring the Google Sheets which had 0.5M rows.

In google-sheets, they have a div element of width equal to 1px but the height of this div is equal to the rows*rowHeight. In Google Sheets, this div was placed inside its parent container. This helped them to achieve the a custom scrollable height with the content is overflowing.

So I used the same approach of using this dummy div, with width = 1px and height = rows*rowHeight. And this is what the scrollbar-container comprises off.

Here is the pictorial representation of the scrollbar-container:

Scrollbar container

It should be noted that this div is an hidden div i.e. visibility: hidden.

You can take a look at this scrollbar-container in the codebase here.

Understanding the Drawing Mechanism

Now we have come to the main part which is the drawing mechanism. Before we jump into this I would like to say that all the drawing onto the target-canvas happens from the worker thread. Remember we talked about initializing a worker whenever the component mounts? This is the same worker we are talking about. You can find the worker being initialized in the codebase here.

The entire drawing mechanism a.k.a the worker code can be found here.

So now we understand the it is the worker’s responsibility to draw the rows on the target-canvas therefore let us dig into its mechanism.

I would like to explain this mechanism with the help of three different approaches:

Approach 1

In this approach, once the entire data is loaded onto the memory we directly draw it onto our target-canvas.

Approach 1

What will happen in this case? Any guesses?

You guessed it right, all the 1M rows would get drawn onto the target-canvas overwriting the previously drawn pixels and giving us the overwritten image like below:

Approach 1

So as you can see the canvas is redrawn on itself leading to a distorted image. Hence this approach is bad and should not be taken.

Approach 2

In this approach, rather than drawing the entire data all at once, we draw a chunk of data onto the target-canvas. We can take a chunk size to be equal to the number of rows that can fit on the canvas.

Here is the visual representation of drawing a chunk on the canvas:

Approach 2

We do this as we scroll down the data and draw each chunk of rows. But there are certain things to consider before taking this approach:

To draw a row you need to draw all the cells in it equivalent to the number of columns.
Also, to draw each cell you need to:
- First, clear the canvas with that cell area with clearRect.
- Then to draw the cell we use [strokeRect](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/strokeRect) function
- Lastly, to fill the data in it we make use of the fillRect function.
All these steps happen for every cell that we draw, it is going to happen for every row and every chunk as you scroll down through the data.
This is a very expensive operation.

There is another approach that I used to achieve this without degrading the performance. Let us look into that.

Approach 3

In this approach, we make use of the offscreen canvas API. So the algorithm is as follows:

Each offscreen canvas will consist of 100 rows draw onto them from the CSV data.
These canvases are created based on the scroll position. So based on the scrollTop position, we calculate the number of rows we have scrolled off.
Based on this number we calculate the range of rows that we need to draw on the canvas. For example, if scrollTop = 150, then we select rows from 100 to 200 and draw them onto the newly created offscreen canvas.
We also generate another offscreen canvas, that draws the next set of 100 rows. From the above example, the next canvas will contain rows from 200 to 300.
We store all these canvases during the scroll in a global state in the worker which you can take a look here.
Once the canvases are ready we simply take the chunk of the current offscreen canvas and draw it as an image onto the target-canvas. Here the chunk size is the size equal to the number of rows that can fit inside the target-canvas.
When I say we take a chunk from the current offscreen canvas by that I mean we copy the chunk from that offscreen canvas as an image and draw it onto the target-canvas with the help of drawImage function. This operation is called bliting. You can find more information about it here.

To understand this visually, here is a small animation that will make things clearer:

Approach 3

The blue animation that you see here is the scenario where your scroll bar position intersects between the two offscreen canvases. For example, if you have completed drawing the entire 1st offscreen canvas on target-canvas then for the remaining portion of the target-canvas you will need to paint it with the exact number of rows in the next offscreen canvas.

This creates an experience of continuous data visibility while scrolling thus giving consistent experience.

So with this approach 3, you will be able to scroll normally with the mouse-wheel/touch-pad or while you are dragging the scroll bar to the bottom.

Summary

So that’s it, folks. In this blog, we learned:

How an uncommon solution like drawing on canvas solves the most common problem.
The mechanism of understanding the infinite scrolling container.
We saw how the canvas is initialized.
We also saw, the DOM structure of the component
We saw how the component gets initialized and how the control gets transferred to the worker.
Finally, we saw different approaches of drawing on the canvas when you are scrolling fast.

The entire codebase for this project can be found here: https://github.com/keyurparalkar/render-million-rows

Thank you for reading!

Follow me on twitter, github, and linkedIn.

Recursive elements in React

Keyur Paralkar — Mon, 04 Mar 2024 10:36:51 +0000

Introduction

A couple of days back I was wondering how components like these are built:

Tree Component

JSON to HTML Elements

A common thing between these components is that there is a definitive pattern that gets repeated. For example, when you click on a title in the tree component, it expands. When you click on the inner title it expands and so on.

In the world of programming, to deal with these kinds of repetitive patterns we either use loops or recursions.

Everyone deals with them differently depending on their usecase. For this blogpost, I will use recursion to implement these components.

Prerequisites

I would highly recommend going through the below topics before reading this blog post:

What is Recursion?

Saul's Magic

As Sual Goodmen said, ‘Let’s just say I know a guy, who knows a guy, who knows another guy’. Recursion is similar to what he is trying to say.

From Wikipedia,

💡 **Recursion is a method of solving a computational problem where the solution depends on solutions to smaller instances of the same problem.

In laymen terms, a problem is divided into a subproblem and the solution of that is passed down to the next subproblem. This goes on till the base condition is met where base condition stops this drill down.

Let us consider a classic example of finding a factorial of a number:

So, in this function, n is just the number we're finding the factorial for. The function keeps calling itself with n - 1 until it hits 0. When it does, it just returns 1. This is what we call the base case of the recursion. The return value gets multiplied with the current n and is sent back up to the previous stack frame (which is the last time we called the function with n+1). This cycle keeps on going until we get back to the very first function call (the original n), and bam! We get our final factorial.

Why is Recursion?

There are a couple of advantages to using recursion that I have in mind:

Simplicity and Readability
Reduced Redundancy
Divide and Conquer

You can read more about the advantages in this blog post: Recursion

Let's talk about Recursive React Elements

From the definition of recursion explained above we know that a recursive function needs a base condition that helps it to get out of the recursion state. Similar to this function, we will make use of this concept in react to create recursive elements.

Here is a visual example of a recursive element:

Tree Component

This recursive tree is a component based on an object that has repetitive nested children. For example, the above tree component is based on the following JSON structure:

The component that you see above is a tree component. Let us recognize some key parameters in this component from the definition of recursion:

Recursive state: Here the recursive state is the name or fields that are getting repeated one key within another.

As you can see this object has an id name and children properties. Again the children's property is an array of tree i.e. object with id name and children properties. And this goes on and on.
Base condition: In this example, the base/end case is when there are no elements to print out.

We will be building an interactive component that will help us to visualize this object in the form of a tree. So without further ado! let us get started.

Building the recursive element

What we are trying to implement is a tree that is interactive like we saw in the above section:

We build this component out of the following tags:
- ul - to wrap all the list children
- li - to present each element in the list of children
- details - to make each li tag interactive. This will help it to open and close the li tag.
- summary - This will help to give the heading to the li tag.
So the structure is like this: ul wraps all li and each li has details and summary.

Representation of Tree with the above elements

Let us call this component a RecursiveTree and create the component file for the same. Paste the below code in it:

Let me explain what’s going on here:

We have a styled component: StyledUnorderedList that has the following styles:

We loop over all the children's elements with the map function that wraps each item with the CustomDetails component:

This CustomDetails component looks like below:

The purpose of this component is to provide modified/additional functionalities apart from the existing details HTML element. Here are the additional functionalities that it provides:
- You can provide icons that can be rendered in front of each element in the tree.
  - For that, you need to provide an array of two icons. The first one is the open icon and the second is the close icon.
  - It is to be noted that I made use of react-icons icon library.
- Interactive change of icon when the detail’s tag gets toggled.
The component above is pretty self-explanatory and you can get a jest of out of it by a glance.
Let us test out this component. Render this component as below and see the output:

Tree with no custom icon field in the JSON object

You can also pass your desired icons in the tree config like below:

Tree with custom icon field in the JSON object

Caveat: Event bubbling

One thing I struggled with during the implementation of this component was the toggle interaction that happened at deeper levels of the tree where getting bubble i.e. the toggle event was getting applied from the target element to all the parent elements that had event handlers that catch this toggle event.

To avoid this scenario, I made use of the e.stopPropogation function to stop the event from bubbling.

To better explain the problem here are the visualized representations of the same:

No event bubbling

With Event bubbling

It took me a small bit of time to understand the issue at hand but after careful debugging, I was able to resolve it.

So to provide a better interactivity in the recursive elements make sure that the events don’t get bubbled up (if that’s the desired behaviour you want).

Bonus Element!!

So this was fun. So before closing up, I would also like to share another example. This example is of recursively adding components based on a JSON config. I will just place the code below along with its output for reference.

You get the following out:

JSON to HTML Elements

Summary

To summarize, we learned a couple of things here:

What is recursion?
What are recursive react elements?
Building the RecursiveTree component
Caveats
Bonus Element

The entire code for this tutorial can be found here.

Thank you for reading!

Follow me on twitter, github, and linkedIn.

How I build a YouTube Video Player with ReactJS: Add chapters to the video

Keyur Paralkar — Wed, 21 Feb 2024 11:08:15 +0000

Introduction

If you are into online learning/education or an unboxing video of a gadget on youtube, etc. Then I am pretty sure you might have come across this thing here:

Youtube’s progress bar gets split up into multiple mini sliders. Video source

The progress bar is broken into sections and each section describes what it represents. This is mostly done by the video's author so that viewers can quickly get a gist of what they will be learning in this section or the next few minutes.

These quick gist of each section are called chapters. In this article, we will be looking at how to implement them.

So without further ado, let us get started.

Prerequisites

What are VTTs? My previous Blog post, MDN
Project Architecture: Previous Post: In depth or you can read the summary
Slider component: Previous post: How I build a YouTube Video Player with ReactJS: Build the Seekbar control
Understanding of track element.
Understanding of Javascript’s map function, editing element attributes.
React: useImperativeHandle hook

The What?

So this broken time bar/seek bar/ progress bar that you see on the video is nothing but chapters. This is a very common feature that you get to see on YouTube.

We already have built the seek bar in our previous blog posts and with some tweaks to the existing Slider component we can achieve this functionality.

The Why?

We are building this component because it:

Tells the user what is happening in the given time frame.
Gives a quick reference to the content the user is looking for with the help of chapter text below the frame snapshot.
Provides a better User experience.

The How?

Before we get started with the implementation let us have a quick overview of what the steps are:

Generate VTT for chapters
Load the VTT into the video with the help of track element.
Extract chapters from the track element.
Update the Slider component for the chapter logic
Display the chapters in the tooltip

There isn’t much jargon here if you have gone through the previous article. If not, I would highly recommend going through it from the prerequisites section.

💡 NOTE: The implementation of chapter fill css-variable was inspired from the https://www.vidstack.io/

Generating VTT for chapters

Web video text track is a file format that has time-based data. Meaning, that it contains text that needs to be shown on the video along with the information of when this text needs to be shown(nth second).

Since we want the users to know from which second to which second the chapter starts and ends we will write a VTT file like the one below:



WEBVTT

00:00:00.000 --> 00:00:15.000
Chapter 1

00:00:15.000 --> 00:00:42.000
Chapter 2

00:00:42.000 --> 00:00:48.000
Chapter 3

00:00:48.000 --> 00:01:01.000
Chapter 4

00:01:01.000 --> 00:01:09.000
Chapter 5

This tells us that, from the 0th to the 15th second there would be text that corresponds to Chapter 1 and so on.

Load the VTT into the video

Next, to load the VTT into the video we make use of the [track element.](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/track) We update the Video.tsx like below:

Here we added a track element with kind attribute of chapters. In the src attribute make sure that you place the location/url of the chapter’s vtt file that we generated above.

Extracting chapters from the `track` element

Now that we have track element in place let us make use of it to extract the chapters into our code. What we want here is that we need these chapters when the video is loaded completely.

To do that, we already have a useEffect in the Video.tsx file that hydrates the store with some parameters. We make use of this same effect to capture the chapters. Copy and paste below useEffect :

Here we make use of the video element’s loadeddata event to hydrate the store. The code is pretty self-explanatory but I would like to explain the part of the chapter here:

In line 12, we make use of trackChaptersRef which is being passed to the track element. From this, we access the track object.
In line 13, we get all the cues in the track.
On the next line, we make use of the map function to return an array of objects that consists of:
- index
- name of the chapter, start and end time
- percentageTime: This represents what percentage of time this chapter contributes to out of the total video duration.

I know this hydration of chapter object with additional fields doesn’t make any sense right now but it will when we get into the changes of the slider component. We will discuss this in the next section.

Update the Slider component for the chapter logic

Folks, take a cup of coffee now since this will be a long section. I will try my best to make it interesting 🙂.

Before proceeding further, I would highly recommend going through this Slider component implement article.

Here is the outline of the steps that we will be doing to achieve the chapter functionality:

Split the Slider component into multiple mini-slider components
Handling Slider fill across the multiple mini-sliders
Handling mouse moves on hover, click and drag.
Updating the overall slider on playback
Styling the slider

Split the Slider component into multiple mini-slider components

Ok so hear me out:

Chapters on Slider is nothing but a bunch of mini sliders.

From this what I mean is, in this functionality, we won’t have a single slider of width 100%. But instead, we will have mini sliders of length equal to the width of percentageTime. This state is the derived state that we computed when we loaded the video component in the above section.

We got the jest of what we are doing, now let us start with the implementation.

The first thing that we need to do is, extend our Slider component such that it accepts chapters as a prop:
- Let us update the SliderProps interface:
- Update the render method of the slider component such that when chapters are enabled we map over them and create multiple sliders:
- We also maintain references to all these mini sliders with the help of chapterRefs. It is an array ref that holds the reference to these elements. We do this in this line: ```

ref={(el: HTMLDivElement) => el && (chapterRefs.current[index] = el)}

    - Quick thing to note here, We have created a StyleChapterContainer. It may look like this:
      
  


- It accepts a prop as `$width` that defines the width of this mini - slider component.





Now pass the chapters to the slider component via the seekbar component as follows:





Once this is hooked the output will look like below




  
  
  Handling filling logic on mouse move and click events


The above logic needs to be handled for the following scenarios:


While clicking and,
While dragging the slider


Here is the pictorial representation of these scenarios:


While Clicking:


<p>

<figure>

<img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/erymo9rbzpjls48q4cw5.gif" alt="Click interaction on sliders with chapters" />

  <figcaption>Click interaction on sliders with chapters</figcaption>

</figure>

</p>


While dragging:


<p>

<figure>

<img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/g8ryc9ia89pw6gc3bvo6.gif" alt="Drag interaction on sliders with chapters" />

  <figcaption>Drag interaction on sliders with chapters</figcaption>

</figure>

</p>

<aside>

💡 NOTE: I would like to remind you guys that to go through this blogpost: How I build a YouTube Video Player with ReactJS: Build the Seekbar control before proceeding further. Because it contains a lot of jargon which is better explained there.

</aside>

So here we go, below is the handleClick event handler that takes care of fill the chapters on click:


  


Below is the explanation for the same:


This part right here calculates all the chapter's width and with the help of the current --slider-fill value we get the current chapter index:



  



Next, we get the previous and the next chapter elements:



  



Next, we fill all the previous chapters before the current chapter:



  



A thing to note here, we track the fill of each slider element with the help of the CSS variable: --chapter-fill.
We also need to update our StyledSliderFill component such that whenever chapters exist we make use of the —chapter-fill CSS variable.



  



Next, we summon all the chapter fill values below:



  


Then, to fill the current chapter we make use of the computeCurrentWidthFromPointerPos utility function and then finally set its value to the current chapter’s --chapter-fill.


  



For scenarios of clicking from right to left direction i.e. going back in video, we fill the next chapter to 0 from the current chapter:



  


Similarly, we make use of the handleMouseMove function that handles the filling of chapters during the mousemove event i.e. when we are dragging the slider knob:


  


This is the same function we used to update the --slider-pointer CSS variable in the previous blog posts. The purpose of this function from the chapters point of view is as follows:


Update the chapter fill of the respective elements
Add a data-chapter-dragging attribute


I would like you guys to go through the comments in the above code block to understand the functionality. 

Just a quick note: The purpose of adding data-chapter-dragging attribute is to use it in styling which we will look into in the later section.

  
  
  Updating the slider position on playback


There is one more scenario left that we need to cover which is handling the playback mechanism across multiple sliders. Now to do this we need a mechanism that will help us to update the --chapter-fill CSS variable of each chapter whenever the current duration of the video changes.

This is a simple task. We just need to expose a function that updates this chapter fill for the given chapter with the help of [useImperativeHandle hook](https://react.dev/reference/react/useImperativeHandle).

The first thing is to update the useImperativeHandle hook in the Slider component:


  


We introduced a new function here: updateChapterFill which accepts the current chapter’s index and the percentage completion of that chapter. 

Next, we consume this function via refs in the Seekbar component like below:


  


Inside the Seekbar component, we access the currentTime and the chapters from the player context. 

Then we make use of the useEffect that updates on currentTime and isSeeking. Along with updating the slider-fill it also updates the chapter fill with the help of updateChapterFill.

We do some simple calculations and get the currentChapterFillWidth by dividing the currentTime by the total chapter duration. 

lastly, we pass this to our update function.

This is how our functionality will look like when during playback:

<p>

<figure>

<img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/whuawmq3nm8u8ucmy6nd.gif" alt="Chapter fill on video playback" />

  <figcaption>Chapter fill on video playback</figcaption>

</figure>

</p>

  
  
  Styling the chapter sliders


One last thing that is pending is adding a small styling effect that will give better UX feedback. The style that I am talking about is increasing the width of the slider whenever we are dragging the slider like below:

<p>

<figure>

<img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/iyb08j2kbzjpj4tt56qy.gif" alt="Emphasising chapters on drag" />

  <figcaption>Emphasising chapters on drag</figcaption>

</figure>

</p>

To do this we make use of the data-chapter-dragging attribute that we add in the handleMouseMove function. We use this attribute in StyledContainer of the Slider component:


  


We make sure that whenever we are dragging i.e. whenever the container has the data-dragging attribute only then check for any child div that has data-chapter-dragging attribute. If it has then we update the height of the slider/container by 8px.

  
  
  Summary


So to summarize we achieved the following things in this blogpost:


We understand the reason why are we doing this feature.
We saw how to get the chapter's data into the video via the track element.
And lastly, we saw the changes that we need to make to the slider component to achieve the desired chapter UX.


The entire code for this tutorial can be found here.

Thank you for reading!

Follow me on twitter, github, and linkedIn.