TypeScript

LyteNyte Grid offers first-class TypeScript support. This guide outlines best practices for extending LyteNyte Grid's column and API interfaces and avoiding errors through proper type checking.

Main Grid Types

There are five primary types to know about when working with LyteNyte Grid:

• Grid.GridSpec: A generic type constraint used by other LyteNyte Grid interfaces.
• Grid.Props: The interface that describes the props that the <Grid /> component accepts.
• Grid.Column: The base interface for a column in LyteNyte Grid.
• Grid.API: The base interface that describes the LyteNyte Grid API.
• RowSource: The base interface for a row data source that you can provide to the grid. All row data sources extend this base type.

You do not need to memorize these types. Understanding how these types fit together will help you get the most out of TypeScript and LyteNyte Grid.

Grid Specification

Grid.GridSpec is one of the five primary grid types that developers typically define. It’s a type constraint used by other grid types, and LyteNyte Grid never reads it at runtime.

Grid specification has four optional type parameters and four optional properties. Each property extends the grid’s type in a specific way. The base definition is as follows:

1
export interface GridSpec<
2
  Data = unknown,
3
  ColExt extends Record<string, any> = object,
4
  Source extends RowSource<Data> = RowSource,
5
  Ext extends Record<string, any> = object,
6
> {
7
  readonly data?: Data;
8
  readonly column?: ColExt;
9
  readonly source?: Source;
10
  readonly api?: Ext;
11
}

Specification Parameters and Properties

The four optional properties for Grid.GridSpec include:

1. Data Property: LyteNyte Grid interfaces use this property to infer the structure of the row data items provided to the grid.

2. Column Property: An extension of the base column definition provided by LyteNyte Grid. Use this property to add additional column properties that are specific to your application.

3. Source Property: The row data source used by the grid. LyteNyte Grid uses this property to provide type completions for API methods that are specific to each row source.

4. API Property: An extension of the base grid API that adds custom properties and methods specific to your application.

The four optional type parameters for Grid.GridSpec include:

1. Data Type: Describes the shape of the row data that the grid receives. For example, if the row data is a number[], define the grid spec like this:

   1
   interface GridSpec {
   2
     readonly data: number[];
   3
   }

2. ColExt Type: Describes additional properties you want to add to columns. LyteNyte Grid combines these additional properties with the base Grid.Column type. For example, the code below shows two equivalent definitions:

   1
   interface GridSpec {
   2
     readonly column: { readonly sort?: "asc" | "desc" | null };
   3
   }
   4
   
   5
   type ColumnWithSort = Grid.Column<GridSpec>;
   6
   
   7
   interface ColumnWithSort extends Grid.Column {
   8
     readonly sort?: "asc" | "desc" | null;
   9
   }

   Info

   The GridSpec approach is recommended because it keeps column extensions and row data typing in one place.

3. Source Type: Describes the row data source you provide. Each row data source shares common capabilities, but each source type also adds source-specific capabilities and functions.

   The source property exposes those capabilities through the grid types. The code below shows an example using the RowSourceServer type from the server row data source:

   1
   interface GridSpec {
   2
     readonly source: RowSourceServer;
   3
   }

4. Ext Type: Describes the API extensions that you provide through the apiExtension property on the grid. Use Ext to add user-defined functions and state to the grid’s API. When you type Ext on the grid spec, you extend the API type.

   LyteNyte Grid also extends the API type with the provided Source type, so the final API type is the combination: Grid.API & Source & Ext.

   The code below shows an example that adds a notifyUser method to LyteNyte Grid’s API:

   1
   interface GridSpec {
   2
     readonly api: { notifyUser: (msg: string) => void };
   3
   }

Combining Specification Types and Properties

You can combine all properties to create a full set of specified grid types. In the example below, each part of the GridSpec is defined and used with the main types used by LyteNyte Grid:

1
interface GridSpec {
2
  readonly data: number[];
3
  readonly column: { readonly sort?: "asc" | "desc" | null };
4
  readonly source: RowSourceServer;
5
  readonly api: { notifyUser: (msg: string) => void };
6
}
7

8
type Props = Grid.Props<GridSpec>;
9
type Column = Grid.Column<GridSpec>;
10
type API = Grid.API<GridSpec>;

After defining these types, you can derive property-specific types. For example, define renderer types as follows:

1
type CellRenderer = Required<Grid.Column<GridSpec>>["cellRenderer"];
2
type HeaderRenderer = Required<Grid.Column<GridSpec>>["headerRenderer"];

Namespace and Component

The Grid export in LyteNyte Grid is both the root component and a type namespace. The namespace contains all the types used by LyteNyte Grid’s publicly exposed functions and components. This means the following code is valid:

1
function GridWrapper<K extends Grid.GridSpec>(props: Grid.Props<K>) {
2
  return <Grid {...props} />;
3
}

This guide does not cover the details of why this works in TypeScript, but you do not need to actively think about it. TypeScript does not allow Grid itself to be used as a type, so TypeScript prevents misuse in places where a type is expected. For example, this code fails type checking:

1
type MyGrid = Grid;

Component and T Namespaces

The Grid namespace has two sub-namespaces for types that are less frequently used:

• Grid.T: Defines auxiliary types used by the various functions and renderers of LyteNyte Grid, for example Grid.T.HeaderParams.
• Grid.Component: Defines the props for the various headless component parts that make up the grid.

The Grid.T namespace is most useful when defining custom components. For example, the following two cell renderer definitions are equivalent. The method you choose is developer preference.

1
interface Spec {
2
  readonly data: number[];
3
}
4

5
export const MyCell: Grid.Column<Spec>["Cell"] = (props) => {
6
  // my component definition
7
};
8

9
export function MyCell2(props: Grid.T.CellRendererParams<Spec>) {
10
  // my component definition
11
}

Next Steps

• Getting Started: Get started with LyteNyte Grid, a modern React data grid designed for enterprise-scale data challenges.
• Grid Reactivity: Learn how LyteNyte Grid enables declarative reactivity.
• API Extensions: Extend LyteNyte Grid's base API with custom functions and state.