Hilma Forms Devtools

Installation

Make sure you already have @hilma/forms installed, with version 2.4.0 or higher :upside_down_face:

npm i @hilma/forms-devtools

Usage

import React from 'react';
import { FormProvider, FormTextInput, FormPassword, FormSubmitButton } from '@hilma/forms';
import { FormsDevtools } from '@hilma/forms-devtools';

const MyLoginForm: React.FC = () => {
    return <FormProvider
        initialValues={{
            username: "",
            password: "",
            confirmPassword: "",
        }}
        onSubmit={(values) => {
            // ...
        }}
    >
        <FormTextInput name="username" {/*...*/} />
        <FormPassword name="password" {/*...*/} />
        <FormPassword name="confirmPassword" {/*...*/} />

        <FormSubmitButton>Submit</FormSubmitButton>

        <FormsDevtools />
    </FormProvider>
}

export default MyLoginForm;

The main usage of the package is the FormsDevtools component, which is a comfortable and useful way to view the state of a @hilma/forms Form.

Additionally, the package exports the FormsListener and FieldListener components, which are a more application-practical way to listen-in to changes in a Form.

API

FormsDevtools

Displays a devtools panel (or a floating button to open it). Inspired by ReactQueryDevtools (from @tanstack/react-query-devtools).

Must be wrapped by a FormProvider; shows the details (values, errors, etc) of the wrapping FormProvider, as well as a minimal interface to edit or update the values.

Props

| Prop | Type | Default | Explanation | | | ------------------ | ------------------------------------ | --------------- | ---------------------------------------------------------------------------------- | --- | | initialOpen | boolean | false | Whether the devtools panel starts as open or closed. | | buttonPosition | Corner (exported from the package) | "bottom-left" | Where the button that opens the devtools panel should be located. | | noEditor | boolean | false | When set to true, the sidebar editor in the devtools panel will not be rendered. |

FormsListener

Must be wrapped by a FormProvider; listens in on the wrapping FormProvider, and can trigger listener callbacks and/or log the new details (values, errors, or touched).

Props

| Prop | Type | Default | Explanation | | ------------------- | ---------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | log | Category \| Category[] \| "all" \| undefined | undefined | What to log the changes of, if anything. | | label | string | "NO-LABEL" | Used in the console.logs caused by the log prop. | | onValueChange | (values: T, helpers: FormikHelpers<T>) => void | | A callback to trigger whenever the form's values change. | | onErrorChange | (errors: FormikErrors<T>, helpers: FormikHelpers<T>) => void | | A callback to trigger whenever the form's errors change. | | onTouchedChange | (touched: FormikTouched<T>, helpers: FormikHelpers<T>) => void | | A callback to trigger whenever the form's touched change. | | skipFirstRender | boolean | false | Whether the component should skip the first render when logging/triggering callbacks. Note: When React.StrictMode is set, there will still be logging/function triggering once on application mount. |

FieldListener

Must be wrapped by a FormProvider; listens in on a specific field within the wrapping FormProvider, and can trigger listener callbacks and/or log the field's new details (its value, error, or touched).

Props

| Prop | Type | Default | Explanation | | ------------------- | --------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name* | string \| { _key: string } | | The field to listen in on the changes of. | | log | Category \| Category[] \| "all" \| undefined | undefined | What to log the changes of, if anything. | | onValueChange | (value: T, helpers: FieldHelperProps<T>) => void | | A callback to trigger whenever field.value changes. | | onErrorChange | (errors: string \| undefined, helpers: FieldHelperProps<T>) => void | | A callback to trigger whenever meta.error changes. | | onTouchedChange | (touched: boolean, helpers: FieldHelperProps<T>) => void | | A callback to trigger whenever the form's touched change. | | skipFirstRender | boolean | false | Whether the component should skip the first render when logging/triggering callbacks. Note: When React.StrictMode is set, there will still be logging/function triggering once on application mount. |