xstate-form

[jaetask]

Hi all,

I'm writing a UI independent composable form library on top of xstate. The idea is to solve forms for the masses and allow anyone with custom requirements to be able to roll their own functionality where needed. For this reason, almost everything is an actor that can be composed together to make forms. i.e. text(), select(), checkbox(), submit() all create state machines for those form field types.

When used like this, any UI library can consume the same xstate-form library and provide state machine functionality. See React example, which could easily be Vue, Svelte etc.

Code

library: https://github.com/jaetask/xstate-form
example: https://github.com/jaetask/example-forms
you'll need to npm link xstate-form as I've not published yet.

Example

Here's a quick example of building a form

import { text, submit } from 'fields';

export const buildMachine = (): any => {
  return form({
    fields: {
      username: text('username'),
      password: text('password'),
      // ...
      submitForm: submit('submitForm'),
    },
    initialValues: {
      username: 'jaetask',
    },
  });
};

Currently, these are the only supported fields, I thought this was a good place to stop and get feedback/input.

Context

context: {
  initialValues,
  touched: {},
  errors: {},
  values: {},
  schema: undefined,
},

Touched

Each machine knows when it's dirty and we can use this when validating.

Errors

I am going to integrate Yup and populate context.errors in the same way that formik does. Although I'm considering another error state on the field itself, so after validation is run every component will either be in validation.validated or validation.invalidated states. This is still open to debate.

Values

All values are stored here, in a single level, I suspect I'll need some kind of flattening method for getting/setting arrays of items

Development

I am really enjoying this project and would love to donate it to the cause, (happy to move into davidkpiano/repo if required). Also, if this grabs anyones attention and you want to get involved, then ping me. Forms have been on my mind since the first day I saw xstate and after a few iterations, I think this is a good route to go down.

In time, most of the action & message creators will accept optionable params to configure the machines as required.

Form

The main form looks like this.

export const form = ({
  fields = {},
  initialValues = {},
  additionalStates = {},
  resetting = resettingState(),
  submitting = submittingState(),
  submitted = submittedState(),
}): any => {
  return {
    id: 'xstateForm',
    initial: 'form',
    context: {
      initialValues,
      touched: {},
      errors: {},
      values: {},
      schema: undefined,
    },
    states: {
      form: {
        type: 'parallel',
        states: fields,
        on: {
          SUBMIT: 'submitting',
          RESET: 'resetting',
        },
      },
      resetting,
      submitting,
      submitted,
      ...additionalStates, // users may want to add `retrying` or other states to the top level machine
    },
  };
};

React example

function App() {
  const [state, send] = useMachine(formMachine, { devTools: true });
  return (
    <div className="app">
      <main>
        <form
          onSubmit={(e) => {
            e.preventDefault();
            send("SUBMIT");
          }}
        >
          <div className="field">
            <label for="username">Name:</label>
            <TextInput
              name="username"
              send={send}
              value={state.context.values.username}
            />
          </div>
          <div className="field">
            <label for="password">Password:</label>
            <TextInput
              name="password"
              send={send}
              value={state.context.values.password}
            />
          </div>
          <div className="buttons">
            <button name="resetForm" onClick={() => send(actions.reset())}>
              Reset
            </button>
            <button
              type="submit"
              name="submitForm"
              onClick={() => send("SUBMIT")}
            >
              Submit
            </button>
          </div>
        </form>
      </main>
    </div>
  );
}

TextInput

Shows how any UI library can send the required events at the correct times

const TextInput = ({ name, value = "", send }) => (
  <input
    type="text"
    name={name}
    value={value}
    className="textInput"
    onFocus={() => {
      send(actions.focus(name));
    }}
    onBlur={() => {
      send(actions.blur(name));
    }}
    onChange={(e) => {
      send(actions.change(name, e.target.value));
    }}
  />
);

[jaetask]

Text fields now have visibility, fields lose focus when hidden (they do not regain it automatically when making visible), you could chain a visible() action for that.

[jaetask]

Playing with the idea of a Formik style interface via a useFormMachine hook. It extends useMachine to also provide form specific helper functions that can be deconstructed off the result.

const {
  state,
  send,
  fieldValue,
  isFieldDisabled,
  isFieldVisible,
} = useFormMachine(formMachine, { devTools: true });

The values of which are always inline with the current state, so components could be rendered like this.

<table>
  <tbody>
    <tr>
      <td className="field">
        <label for="username">Name:</label>
      </td>
      <td>
        <TextInput
          disabled={isFieldDisabled("username")}
          name="username"
          send={send}
          value={fieldValue("username")}
          visible={isFieldVisible("username")}
        />
      </td>
      <td>
        <TextControl
          disabled={isFieldDisabled("username")}
          matches={state.matches}
          name="username"
          send={send}
          visible={isFieldVisible("username")}
        />
      </td>
    </tr>
  </tbody>
</table>

I like this idea, it's clean and allows us to provide the same set of utility functions as formik, for isDirty and the likes. it also hides the inner workings of the forms context,users shouldn't have to care about paths like form.${name}.visible.visible or form.${name}.enable.disabled we could hide all of this in accessor functions.

Example app

all pushed into the repos above, will add unit tests for visibility

[tomByrer]

I haven't use Formik so I can't draw from that. But I do like your idea.

I like the idea of a button showing the status of the form, like MUI's Loading Button.

I'm building a Radio Button Group myself, but it is very domain-specific: a quiz form that will show in the Radio Button if the selection is correct or not. (falls in your 20% edge case).

[jaetask]

Hi all,

I'm closing this discussion as it's being discussed in the discord and directly in the issues tracker

Nice one