virtuslab-open-source / formts Goto Github PK

consider adding built-in support for debouncing validation (useful for async validators) if this is not easy to to in userland currently.

add example with debounced async validation

from POC:

      /**
       * Will set the array field value to its copy with the item added at the end.
       * Will run field validation with `change` trigger.
       * Will set `isTouched` to `true`.
       */
      pushItem: (item: E) => void;

      /**
       * Will set the array field value to its copy with the item at index `i` removed.
       * Will run field validation with `change` trigger.
       * Will set `isTouched` to `true`.
       */
      removeItem: (i: number) => void;

• basic form handle impl (values, isTouched, reset, getSubmitHandler)

example:

  const [, form] = useFormts({ Schema });

  const values = form.values
  const onSubmit = form.getSubmitHandler((values) => console.log(values));
  form.reset()

Check if validator API can be simplified

FormHandle.isSubmitting not being set to true while Promise received from submit onSuccess callback is processing

memoizing all possible expensive computations when validator is created and storing them in dictionary should help with perf

submitting should set touched of every field to true. Otherwise submitting does not reveal errors, if they are only visible for touched fields.

touchField is always triggered when setting a new value, but for the same field in 99% sets touched: true when already touched: true.

Add a check before setting touched to skip setting the same value

Currently, automatic versioning only jumps by minor version regardless of the git history.
Maybe smth needs to be done to standard-version configuration

consider using https://typedoc.org/ and running it as part of deploy_master pipeline to generate docs based on types and JSDocs comments. Add/Improve JSDocs if needed

• try implementing createFormSchema and createFormValidator functions using builder pattern for better developer experience
• consider extracting fields decoder container to top-level export

research and implement new version of API that allows for context-based hook usage and minimizing rerenders after atom-based implementation is ready

• initializing internal state based on the schema and hook config

add ready to use validation functions base on https://codesandbox.io/s/formts-poc-3ryqv?file=/formts/src/validators/validators.ts

figure out a good way to expose the validators to the user:

• export under a namespace
• export from a subpath eg. import { required } from '@virtuslab/formts/validators // that would be nice
• export as a separate package (would require transition to monorepo)

this causes some problem in edge causes which can lead to returned initial values being initialised to illegal type (related to objects inside arrays)

current behaviour:

rules function receives values of fields listed in dependencies array, if present

target behaviour

rules function always receives all form values, regardless of dependencies array. dependencies purpose remains to specify other fields which trigger rerun of validation for given fields. This means that user will be able to use fields which do not trigger validation. Documentation and examples will need to be updated accordingly to make this behaviour obvious.

get rid of root property for accessing non-primitive descriptor and simplify types

• useFormts returning field of type FieldHandleSchema - object containing field handles for all form fields
• first version of fieldHandle providing: id, value, isTouched, setValue, handleBlur

example:

  const [fields] = useFormts({ Schema });

  const emailField = (
        <input
          value={fields.email.value}
          onChange={e => fields.email.setValue(e.target.value)}
          onBlur={fields.email.handleBlur}
        />
  )

for example given the Schema:

const Schema = createFormSchema(
  fields => ({
    array: fields.array(
      fields.object({
        foo: fields.string(),
        bar: fields.string(),
      })
    ),
  }),
);

it should be possible to attach validators to every array.foo and array.bar fields

• allow for using values of other fields inside validation function for any given field using dependencies option
• trigger validation of all dependent field when given field value changes (consider how validation triggers should work in such case)

Transformation API for declarative mapping and filtering of field values

• createFormTransformer function (analogous to createFormValidator)
• built-in transformers (see https://codesandbox.io/s/formts-poc-3ryqv?file=/formts/src/transformers/transformers.ts)
• support for transformation triggers
• running transformation as part of field setValue function

setup examples directory (either app indexing all examples or 1 app per example)

• field decoders: bool, number, string, choice, array, instanceOf
• FormSchema type
• flat fields schema creator function

built-in errors are awkward to use. Consider alternative approach where each built-in validation rule accepts exact error to be used.

benefits:

• easier usage of built-in validators in combination with string errors
• should work great in combination with unionize for error <=> error message decoupling
• withError helper can be removed
• all built-in error types are gone, together with associated problems with their naming

add codesandbox examples covering more advanced topics and features

make the lib truly view-layer agnostic by allowing usage outside of react or even without react altogether.
set stage for possible integration with other UI frameworks than react.

generic type T in setFieldValue: <T>(field: GenericFieldDescriptor<T, Err>, value: T) => void; is sometimes expanded by value but it should be restricted by field

not technically a bug, since we provide field.touched that can be used to hide errors, but can be annoying.

when FieldDescriptor of array or object field is passed into validate function then all of its children should be validated recursively so that in order to validate the whole form we need to validate top-level fields

Create cashe for atoms per path to share between rerenders and usages of useField.

• setup CI (TravisCI or CircleCI)
• setup publishing to public NPM registry under @virtuslab/formts
• require passing check on CI before merging in a PR
• automatic NPM release and CHANGELOG.MD update after merging a PR to master

Simplify binding to onChange function of various inputs by taking the responsibility of extracting value from event automatically using available runtime information - field type and input type

optionally also add parseEvent function for extracting value from event without passing it to setValue

reset method for rolling back value to initial value, clearing touched flag and errors. Should propagate down on composite fields

• object field decoder that composes other decoders into an object
• support object fields in createFormSchema function

basic implementation of:

• createFormValidator function
• built-in validators
• holding errors state
• reflecting isValid and errors in formHandle and fieldHandle

example:

const validator = createForm.validator(Schema, (validate) => [
  validate({
    field: Schema.userName,
    rules: () => [required()]
  }),
  validate({
    field: Schema.email,
    rules: () => [
      required(),
      (email) => (/someregex/.test(email) ? null : "Invalid email address!")
    ]
  })
]);

out of scope:

• async validation
• validation dependencies

make sure that invoking setValue for a field with no validation or only sync validation does not cause 2 re-renders

util function for composing multiple validation rules into one that runs all in paralel (rather than one after another until error is found)

placeholder for ideas/discussion

currently in order to use provided validation rules one has to import all as namespace.
this is not convenient and prevents tree-shaking of individual validation rule functions.

import { validators } from "@virtuslab/formts";

change the build config so that this is possible instead:

import { required, minLength } from "@virtuslab/formts/validators";

current solution:

• fields.number() corresponds to type number | "" to represent empty input value as ""
• fields.date() corresponds to type Date | null to represent lack of date
• fields.choice() can accept "" to represent empty select input
• other fields do not have dedicated type representing lack of value

this can be confusing and require additional casting of form state to domain models on submit.
research better solution

change/blur events of direct and indirect object and array field children should cause root validators to run

research & implement the most appropriate way to generate /dist folder to make the lib consumable for widest possible audience.

Research & implement custom implementation of atoms as better alternative to form state management than plain React reducer & context

see POC: https://codesandbox.io/s/lens-based-form-poc-ydrhh?file=/src/state.tss

required by #51

ideally this would only change if there are any async validation rules for the field, but for MVP any implementation should be good enough

Replace usage of React useReducer hook with atom based state.

This should allow for subscribing to just the required piece of form state for each hook.

requires #59

method for setting/clearing touched state on a field. Should propagate down on composite fields

Add runtime check to all hooks that passed FormSchema or FieldDescriptors matches the schema used in FormController