npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@react-typed-forms/schemas

v13.3.1

Published

A simple abstraction on top of `@react-typed-forms/core` for defining JSON compatible schemas and rendering UIs for users to enter that data.

Downloads

1,153

Readme

React typed forms schemas

A simple abstraction on top of @react-typed-forms/core for defining JSON compatible schemas and rendering UIs for users to enter that data.

Install

npm install @react-typed-forms/schemas

Example

import { useControl } from "@react-typed-forms/core";
import React from "react";
import {
  buildSchema,
  createDefaultRenderers,
  createFormRenderer,
  defaultFormEditHooks,
  defaultTailwindTheme,
  defaultValueForFields,
  FormRenderer,
  intField,
  renderControl,
  stringField,
  useControlDefinitionForSchema,
} from "@react-typed-forms/schemas";

/** Define your form */
interface SimpleForm {
  firstName: string;
  lastName: string;
  yearOfBirth: number;
}

/* Build your schema fields. Importantly giving them Display Names for showing in a UI */
const simpleSchema = buildSchema<SimpleForm>({
  firstName: stringField("First Name"),
  lastName: stringField("Last Name", { required: true }),
  yearOfBirth: intField("Year of birth", { defaultValue: 1980 }),
});

/* Create a form renderer based on a simple tailwind css based theme */
const renderer: FormRenderer = createFormRenderer(
  [],
  createDefaultRenderers(defaultTailwindTheme),
);

export default function SimpleSchemasExample() {
  /* Create a `Control` for collecting the data, the schema fields can be used to get a default value */
  const data = useControl<SimpleForm>(() =>
    defaultValueForFields(simpleSchema),
  );

  /* Generate a ControlDefinition automatically from the schema */
  const controlDefinition = useControlDefinitionForSchema(simpleSchema);

  return (
    <div className="container my-4 max-w-2xl">
      {/* Render the ControlDefinition using `data` for the form state */}
      {renderControl(controlDefinition, data, {
        fields: simpleSchema,
        renderer,
        hooks: defaultFormEditHooks,
      })}
      <pre>{JSON.stringify(data.value, null, 2)}</pre>
    </div>
  );
}

This will produce this UI:

Schema Fields and Control Definitions

SchemaField

A SchemaField is a JSON object which describes the definition of a field inside the context of a JSON object. Each SchemaField must have a field name and a FieldType which will map to JSON. The following built in types are defined with these JSON mappings:

  • String - A JSON string
  • Bool - A JSON boolean
  • Int - A JSON number
  • Double - A JSON number
  • Date - A date stored as 'yyyy-MM-dd' in a JSON string
  • DateTime - A date and time stored in ISO8601 format in a JSON string
  • Compound - A JSON object with a list of SchemaField children

Each SchemaField can also be marked as a collection which means that it will be mapped to a JSON array of the defined FieldType.

Defining fields

While you can define a SchemaField as plain JSON, e.g.

[
  {
    "type": "String",
    "field": "firstName",
    "displayName": "First Name"
  },
  {
    "type": "String",
    "field": "lastName",
    "displayName": "Last Name",
    "required": true
  },
  {
    "type": "Int",
    "field": "yearOfBirth",
    "displayName": "Year of birth",
    "defaultValue": 1980
  }
]

However if you have existing types which you would like to define SchemaFields for the library contains a function called buildSchema a type safe way of generating fields for a type:

interface SimpleForm {
  firstName: string;
  lastName: string;
  yearOfBirth: number;
}

const simpleSchema = buildSchema<SimpleForm>({
  firstName: stringField("First Name"),
  lastName: stringField("Last Name", { required: true }),
  yearOfBirth: intField("Year of birth", { defaultValue: 1980 }),
});

Field options

Often a field only has a set of allowed values, e.g. a enum. SchemaField allows this to be modeled by providing an array of FieldOption:

export interface FieldOption {
  name: string;
  value: any;
}

For example you could only allow certain last names:

stringField('Last Name', { 
    required: true,
    options:[ 
        { name: "Smith", value: "smith" }, 
        { name: "Jones", value: "jones" }
    ]
});

ControlDefinition

A ControlDefinition is a JSON object which describes what should be rendered in a UI. Each ControlDefinition can be one of 4 distinct types:

  • DataControlDefinition - Points to a SchemaField in order to render a control for editing of data.
  • GroupedControlsDefinition - Contains an optional title and a list of ControlDefinition children which should be rendered as a group. Optionally can refer to a SchemaField with type Compound in order to capture nested data.
  • DisplayControlDefinition - Render readonly content, current text and HTML variants are defined.
  • ActionControlDefinition - Renders an action button, useful for hooking forms up with outside functionality.

If you don't care about the layout of the form that much you can generate the definition automatically by using useControlDefinitionForSchema().

TODO renderOptions, DataRenderType for choosing render style.

Form Renderer

The actual rendering of the UI is abstracted into an object which contains functions for rendering the various ControlDefinitions and various parts of the UI:

export interface FormRenderer {
  renderData: (props: DataRendererProps) => ReactElement;
  renderGroup: (props: GroupRendererProps) => ReactElement;
  renderDisplay: (props: DisplayRendererProps) => ReactElement;
  renderAction: (props: ActionRendererProps) => ReactElement;
  renderArray: (props: ArrayRendererProps) => ReactElement;
  renderLabel: (props: LabelRendererProps, elem: ReactElement) => ReactElement;
  renderVisibility: (visible: Visibility, elem: ReactElement) => ReactElement;
  renderAdornment: (props: AdornmentProps) => AdornmentRenderer;
}

The createFormRenderer function takes an array of RendererRegistration which allows for customising the rendering.

export type RendererRegistration =
  | DataRendererRegistration
  | GroupRendererRegistration
  | DisplayRendererRegistration
  | ActionRendererRegistration
  | LabelRendererRegistration
  | ArrayRendererRegistration
  | AdornmentRendererRegistration
  | VisibilityRendererRegistration;

Probably the most common customisation would be to add a DataRendererRegistration which will change the way a DataControlDefinition is rendered for a particular FieldType:

export interface DataRendererRegistration {
  type: "data";
  schemaType?: string | string[];
  renderType?: string | string[];
  options?: boolean;
  collection?: boolean;
  match?: (props: DataRendererProps) => boolean;
  render: (
    props: DataRendererProps,
    defaultLabel: (label?: Partial<LabelRendererProps>) => LabelRendererProps,
    renderers: FormRenderer,
  ) => ReactElement;
}
  • The schemaType field specifies which FieldType(s) should use this DataRendererRegistration, unspecified means allow any.
  • The renderType field specifies which DataRenderType this registration applies to.
  • The match function can be used if the matching logic is more complicated than provided by the other.
  • The render function does the actual rendering if the ControlDefinition/SchemaField matches the registration.

A good example of a custom DataRendererRegistration is the muiTextField which renders String fields using the FTextField wrapper of the @react-typed-forms/mui library:

export function muiTextfieldRenderer(
  variant?: "standard" | "outlined" | "filled",
): DataRendererRegistration {
  return {
    type: "data",
    schemaType: FieldType.String,
    renderType: DataRenderType.Standard,
    render: (r, makeLabel, { renderVisibility }) => {
      const { title, required } = makeLabel();
      return renderVisibility(
        r.visible,
        <FTextField
          variant={variant}
          required={required}
          fullWidth
          size="small"
          state={r.control}
          label={title}
        />,
      );
    },
  };
}

Changing the simple example above to use the following:

const renderer: FormRenderer = createFormRenderer(
    [muiTextFieldRenderer()], 
    createDefaultRenderer (defaultTailwindTheme));

This will produce this UI:

TODO

  • Label rendering
  • Visibility
  • Arrays
  • Display controls