README.md

@hatchifyjs/react

@hatchifyjs/react is an NPM package that takes your schemas and provides:

• React components to create data grids and navigation
• React hooks for interacting with your JSON:API backend
• TypeScript types

In this Document

• Setup and Use
  • Basic Setup
  • React Components Setup
  • Customizing the MUI theme
• Exports
  • createJsonapiClient - Creates a new JSON:API rest client using the defined schemas
  • hatchifyReact - Constructs a hatchedReact app instance with custom components,helper functions, and type definitions
  • HatchifyProvider - A component that hosts and provides access to Hatchify-related state
• hatchedReact
  • components
  • state
  • model

Setup and Use

Basic Setup

To set up the components and hooks, you first need to:

1. Import [createJsonapiClient] and [hatchifyReact] from @hatchifyjs/react
2. Create a jsonapiClient with a schema
3. Pass jsonapiClient to hatchifyReact

This will create a hatchedReact object where you can access hooks and components as follows:

import {
  hatchifyReact,
  createJsonapiClient,
} from "@hatchifyjs/react"

const Schemas = {Todo: { ... }}

const hatchedReact = hatchifyReact(createJsonapiClient("/api", Schemas));

hatchedReact.model.Todo.useList
hatchedReact.components.Todo.DataGrid

React Components Setup

Hatchify's components are currently used to:

• Provide a navigation utility to tab through different schemas
• Build filterable, paginated, and sortable grids.

Accessing Components

The Navigation component is "all-schemas" aware and is available directly on hatchedReact as follows:

const hatchedReact = hatchifyReact(createJsonapiClient("/api", schemas))
const Navigation = hatchedReact.Navigation

The grid components (ex: DataGrid) are available on the .components for their specific schema type as follows:

const hatchedReact = hatchifyReact(createJsonapiClient("/api", schemas))
hatchedReact.components.Todo.DataGrid

Component Provider Dependencies

Hatchify uses MaterialUI for design components. For example, Hatchify's Navigation component uses MaterialUI's <Tabs> component "under the hood". You must provide these components to Hatchify. The way to do this is by providing your MaterialUI ThemeProvider.

Similarly, Hatchify has its own provider - HatchifyProvider. HatchifyProvider provides components specific to the data being displayed. For example, you can swap out globally how you want to display dates (See HatchifyProvider's documentation for more details).

You must provide both a MaterialUI and Hatchify provider for Hatchify's components to work. This is typically done in your application's root. See the example below how to do this:

import {
  hatchifyReact,
  createJsonapiClient,
  HatchifyProvider,          // Hatchify's provider
} from "@hatchifyjs/react"
import {
  createTheme,
  ThemeProvider
} from "@mui/material"       // Material's provider

import * as Schemas from "../schemas.js"

const hatchedReact = hatchifyReact( createJsonapiClient("/api", Schemas) )

const App: React.FC = () => {

  // MaterialUI's ThemeProvider must be outside the HatchifyProvider:
  return (
    <ThemeProvider theme={createTheme()}>
      <HatchifyProvider>
        <HATCHIFY.COMPONENTS.HERE/>
      </HatchifyProvider>
    </ThemeProvider>
  )
}

export default App

Customizing the MUI theme

@hatchifyjs/react uses Material-UI components under the hood. This means that you can use the MUI components directly in your app. For example, you can use the ThemeProvider and createTheme from MUI to customize the look and feel of your app.

const App: React.FC = () => {
  const todoState = hatchedReact.state.Todo.useDataGridState({
    include: ["user"],
  }) // 👀

  return (
    <ThemeProvider theme={createTheme()}>
      <HatchifyProvider>
        <List {...todoState}>
          <TodoEmptyList>No records to display</TodoEmptyList>
        </List>
      </HatchifyProvider>
    </ThemeProvider>
  )
}

Exports

import { createJsonapiClient, hatchifyReact, HatchifyProvider } from "@hatchifyjs/react"

createJsonapiClient

createJsonapiClient(baseUrl: string, schemaMap: Schemas) is a constructor function that creates a new JSON:API rest client from the defined schemas. It accepts a base url, and schema set. For more documentation see here.

import { createJsonapiClient } from "@hatchifyjs/react"

const schemas = { ... }

const jsonClientInstance = createJsonapiClient("/api", Schemas)

Parameters createJsonapiClient takes two arguments baseUrl and schemaMap baseUrl is a string that references the base url for the rest client schemaMap is a collection of Hatchify Schemas

Returns Returns a JSON:API rest client instance object

hatchifyReact

hatchifyReact(createJsonapiClient("/api", Schemas)) is a Function that initializes the HatchifyApp object from the JSON:API rest client. Inside of the returned object you will find components, model, state, and Everything.

import { createJsonapiClient, hatchifyReact } from "@hatchifyjs/react"

const schemas = { ... }

const hatchedReact = hatchifyReact(createJsonapiClient("/api", Schemas))

HatchifyProvider

HatchifyProvider must wrap your application for you to use hatchify components. The HatchifyProvider also provides a way to override the default renders for each type of attribute and relationship. This is done by passing an optional defaultDisplayComponents object to the provider as a prop. In the example below, rather than rendering the text "true" or "false" for a boolean, all booleans in Hatchify components will render as "✅" or "❌".

import { HatchifyProvider, hatchifyReact, createJsonapiClient } from "@hatchifyjs/react"
import { boolean, string } from "@hatchifyjs/core"
import type { PartialSchema } from "@hatchifyjs/core"

const schemas = {
  Todo: {
    name: "Todo",
    attributes: {
      name: string(),
      complete: boolean(),
    },
  },
} satisfies Record<string, PartialSchema>

const hatchedReact = hatchifyReact(createJsonapiClient("/api", Schemas))

const DataGrid = hatchedReact.components.Todo.DataGrid

function MyCustomBoolean({ value }: { value: boolean }) {
  return value ? "✅" : "❌"
}

function App() {
  return (
    <HatchifyProvider
      defaultDisplayComponents={{
        Boolean: MyCustomBoolean,
      }}
    >
      <DataGrid />
    </HatchifyProvider>
  )
}

Props

Name	Type	Description
defaultDisplayComponents	Partial<DefaultDisplayComponents>	An object that is keyed by type and contains a component to render the value of that type.

Types

@hatchifyjs/react provides a number of types to assist with app customization.

Type	Description
DataGridState	The return type of the useDataGridState hook. Can be used if you are extending the functionality of useDataGridState.
CreateType	This can be used to type data that will be used to create a record for a given schema.
UpdateType	This can be used to type data that will be used to update a record for a given schema.
HatchifyApp	The return type of the object that is generated by hatchifyReact.
RecordType	The type of a record for a given schema.

Learn more about the available types here.

hatchedReact

hatchedReact is the instantiated HatchifyReact App that is returned by the [hatchifyReact] constructor function. It provides:

• components - a set of components for each of the defined schemas to be used in the app.
• model - a set of hooks and promises for each of the defined schemas
• state - contains hooks that can be used when customizing components provided by hatchify

The following show some of the methods available given a Todo and User schema:

model

The model is a set of hooks and promises for each of the defined schemas. These get used under the hood in the Hatchify components, but are available for use in situations where customization is needed.

• createOne
• deleteOne
• findAll
• findOne
• updateOne
• useAll
• useCreateOne
• useDeleteOne
• useOne
• useUpdateOne

Learn more about the available hooks and promises here.

state

The state is a set of hooks for each of the defined schemas. These get used under the hood in the Hatchify components, but are available for use in situations where customization is needed. The state object holds a record of schemas each with their own useDataGridState hook.

const todoState = hatchedReact.state.Todo.useDataGridState({
  include: ["approvedBy"],
  fields: ["name"],
})

Learn more about the return type here.

components

hatchifyReact provides a set of components for each of the defined schemas. These components include:

• DataGrid
  • DataGrid.Column
  • DataGrid.Empty
• Filters
• List
• Pagination

Learn more about the available components here.

import {HatchifyProvider} from "@hatchifyjs/react"

// Define Schemas
const schemas = { ...Todo }

// Create the Hatched React App instance
const hatchedReact = hatchifyReact(createJsonapiClient("/api", Schemas))

const TodoDataGrid = hatchedReact.components.Todo.DataGrid

const App() {
  return (
    <HatchifyProvider>
      <TodoDataGrid>
        <TodoDataGrid.Empty>No TodoDataGrid.todos found!</TodoDataGrid.Empty>
        <TodoDataGrid.Column
          label="Actions"
          renderDataValue={() =>
            <button
              onClick={({ record }) => console.log(record)}>
                Log Todo
            </button>
          }
        />
      </TodoDataGrid>
    </ HatchifyProvider>
  )
}

Types

DefaultDisplayComponents

DefaultDisplayComponents is an object that is keyed by type and contains a component to render the value of that type. This is used to override the default renders for each type of attribute and relationship.

Name	Type	Description
Boolean	React.ComponentType<{ value: boolean }>	A component that will be used to render boolean values.
Date	React.ComponentType<{ step?: StringStep | number, value: string }>	A component that will be used to render date values.
Number	React.ComponentType<{ value: number }>	A component that will be used to render number values.
String	React.ComponentType<{ value: string }>	A component that will be used to render string values.
Relationship	React.ComponentType<{ id: string, label: string, [field]: any }>	A component that will be used to render relationship values.