@lit/form - A new package for forms?

[UserGalileo]

Hi everyone!

I love what's being done with Lit Labs: Router, SSR, Motion... All of these packages aim to enrich the Developer Experience by providing tools to build not only reusable components and design systems, but also fully featured applications with Lit. And I think it's great that the team is investigating on what would be needed for a framework: #2462.

There's really one thing that I miss from other frameworks/libraries: utilities for forms. I'm used to work with Angular which has a great Forms API, but I think solutions like React Hook Form would be more relevant since it has a smaller API, I think that would be ideal for Lit.

3rd party solutions already exist or are being developed, one example for all is @vaadin/form from their Fusion framework (renamed to Hilla, link). I'm not 100% sold on their implementation but it's definitely a useful and interesting package, and perhaps the most mature I've found.

Personally, I think a 1st party library in the spirit of Lit (lightweight, with best practices, progressive enhancement...) would be awesome and would make adopting Lit for complex applications significantly easier and more appealing for many.

List of features

This is a partial summary of features that I'd love/expect:

• 2-way binding between Model and View
• Field states (dirty, touched, blurred...)
• Field disabled states
• Methods to change all of the above (setField, patchValue, enable, disable, setDirty...)
• Listener for fields and whole form
• Configuration options (eg. updateOn input vs blur)
• Dynamic forms (arrays) with a separate Controller with methods to move/insert/push/remove...
• A <form> substitute (or directive?) to intercept submissions and handle async tasks with fetch (could allow Progressive Enhancement similar to Remix)
• Validation:
  • Synchronous and Asynchronous validators with pending state
  • Cross-field validations
  • Dynamic validators (setValidators(...))
  • Schema validation (eg. yup)
  • a11y best practices (eg. automatic HTML attributes for required, minlength...)
  • Listener for fields validity state

And I'm sure there'd be more, we could take inspiration by Angular Forms, React Hook Form, Formik, etc...

Examples

In my mind I imagine something like this (which is something I'm working on in my spare time as a POC):

A Controller for a group of fields with some configuration. Types would be completely optional, but to be preferred.

form = new Form<User>(this, {
  defaultValues: {
    name: 'Michele',
    surname: 'Stieven',
    gender: 'M',
    agreement: false,
    options: [],
  },
  updateValueOn: 'input',
});

This controller would contain a factory for a Directive to be used on the template, which would work with every native HTML control and eventually custom controls:

<form @submit=${this.submit}>
  <input type="text" ${this.form.bind('name')}>
  <input type="text" ${this.form.bind('surname')}>
  <select ${this.form.bind('gender')}>
    <option value="">-</option>
    <option value="M">M</option>
    <option value="F">F</option>
  </select>
  <select multiple ${this.form.bind('options')}>
    <option value="one">1</option>
    <option value="two">2</option>
  </select>
  <input type="checkbox" ${this.form.bind('agreement')}>
  <button type="button" @click=${() => this.form.reset()}>reset</button>
  <button>submit</button>
</form>

I'm not sure I would allow nested properties (eg. bind('address.street')) because the idea is to support custom controls and their value could be of any non-primitive type, so it'd be unclear whether address.street is supposed to be used as a field key or not. But I'm brainstorming.

The value inside the Controller would be the Single Source of Truth for the form, and the Directive would 2-way bind to that automatically. The Controller would keep informations and methods about the form, examples:

// Properties
this.form.value // Does not contain disabled fields
this.form.rawValue // Does contain disabled fields
this.form.dirtyFields
this.form.touchedFields
this.form.blurredFields
this.form.disabledFields

// Methods
this.form.setField(key, value);
this.form.patchValue(partialFormValue);
this.form.reset(key?);
this.form.setDirty(key, isDirty);
this.form.setTouched(key, isTouched);
this.form.setBlurred(key, isBlurred);
this.form.disable(key);
this.form.enable(key);
this.form.valueChanges(key?): Observable
...

And eventually, a derived Controller (or the same one, de gustibus) for Validations. I would keep validators on the Controller side (not the Directive) because the model would be the source of truth, not the controls in the template (which may disappear temporarily or there may be multiple controls for the same field).

validation = new Validation(this.form, {
  validators: {
    name: [Validators.required],
    surname: [Validators.required],
  },
  asyncValidators: {
    name: [forbidden],
  },
  // Cross-field validation
  groupValidators: [...],
  groupAsyncValidators: [...],
  // Other options
  alwaysRunAsyncValidators: true,
});

this.validation.errorsSync; // Record<keyof T, any[]>
this.validation.errorsAsync; // Record<keyof T, any[]>
this.validation.getState(key?); // 'VALID' | 'INVALID' | 'PENDING'
this.validation.statusChanges(key?): Observable
...

---

I think overall it'd be a fairly simple API but a really helpful one. Would it be interesting to add something like this to Lit as a separate package? Obviously mine is just an example so don't take my API seriously. I'm sure there'd be a lot that the Lit team could take care of with regards to best practices and a11y that I don't even think of.

[UserGalileo]

In order to demonstrate how this could work, I've created a really simple POC with some of those features which you can see here: https://stackblitz.com/edit/vitejs-vite-lnwwol?file=src/my-element.ts

It's not tested or anything, just a "train on thought code" to see if it worked at all :)

I've also tried implementing some sort of validation with both synchronous and asynchronous validations and it seems to be working quite fine but I haven't included it in this demo since I feel that would be far more a personal preference and I wanted to keep the main example clean.

[web-padawan]

FYI we have form support in Vaadin as part of @vaadin/form package. Here you can find some documentation.

[UserGalileo]

Yep, in fact that's the only one I mentioned and linked :P As I said I'm not 100% convinced by the "flavour" (but it's just me, a personal preference), hopefully my demo will clarify what's in my mind :)

[UserGalileo]

Another flavour: a-la Angular (Reactive Forms)

With a different API (more verbose) we could have any type of nested forms without too much trouble. This is another version which would be heavily inspired by Angular Forms (and the new RFC for Strictly Typed Forms), and it'd be indeed more "complete".

There would be 3 types: FormControl (single control), FormGroup (a record of controls) and FormArray (an array of controls or groups).

Example:

form = new FormGroup(this, {
  user: new FormGroup(this, {
    name: new FormControl(this, { defaultValue: 'Michele' }),
    surname: new FormControl(this, { defaultValue: 'Stieven' }),
    gender: new FormControl<'M' | 'F'>(this, { defaultValue: 'M' }),
  }),
  agreement: new FormControl(this, { defaultValue: false }),
  phones: new FormArray<FormControl<string>>(this),
  addresses: new FormArray<FormGroup<{
    street: FormControl<string>
    nr: FormControl<string>
  }>>(this)
});

Which could be made easier to write with a helper, a FormBuilder (again, a-la Angular):

fb = new FormBuilder(this);

form = this.fb.group({
  user: this.fb.group({
    name: this.fb.control('Michele'),
    surname: this.fb.control('Stieven'),
    gender: this.fb.control<'M' | 'F'>('M'),
  }),
  agreement: this.fb.control(false),
  phones: this.fb.array<FormControl<string>>(),
  addresses: this.fb.array<FormGroup<{
    street: FormControl<string>
    nr: FormControl<string>
  }>>()
});

Typings would be inferred by the structure provided by the user, in this case we'd have:

// Group type
FormGroup<{
  user: FormGroup<{
      name: FormControl<string>;
      surname: FormControl<string>;
      gender: FormControl<"M" | "F">;
  }>;
  agreement: FormControl<boolean>;
  phones: FormArray<FormControl<string>>;
  addresses: FormArray<FormGroup<{
    street: FormControl<string>
    nr: FormControl<string>
  }>>;
}>

// Value type, auto-generated
const value: {
  user: {
      name: string;
      surname: string;
      gender: "M" | "F";
  }>;
  agreement: boolean;
  phones: Array<string>;
  addresses: Array<{
    street: string;
    nr: string;
  }>;
} = this.form.value;

Bindings would also be done with an Element Directive, with full type-safety:

html`
<!-- Bind to a standalone control -->
<input type="text" ${this.control.bind()}>

<!-- Bind to a control of a group -->
<input type="text" ${this.form.bind('agreement')}>

<!-- Nested groups -->
<input type="text" ${this.form.bind('user.name')}>

<!-- Array bindings -->
${this.form.get('phones').controls.map(c => html`
  <input type="text" ${c.bind()}>
`)}

<!-- Arrays of groups -->
${this.form.get('addresses').controls.map(c => html`
  <input type="text" ${c.bind('street')}>
  <input type="text" ${c.bind('nr')}>
`)}

`

Each one of these 3 types would implement an AbstractControl, so they'd have these properties:

interface AbstractControl {
  value: any;
  reset(key?: any): void;
  set(value: any): void;
  enable(key?: any): void;
  disable(key?: any): void;
  valueChanges(): Observable<any>;
  disabledChanges(): Observable<boolean>;
  isDirty(): boolean;
  isTouched(): boolean;
  isBlurred(): boolean;
  isDisabled(): boolean;
}

With additions:

FormGroup:

• rawValue has all fields, value strips disabled ones
• get(key) to retrieve a control
• patch(value) with a partial object

FormArray:

• get(index) to retrieve a control
• insertAt(index, control)
• append(control)
• prepend(control)
• removeAt(index)
• pop()
• swap(indexA, indexB)
• move(from, to)

Doable?

Yes: I've got another POC ready if you're curious (not touching Validation yet, not tested or anything, you may find it broken cause I'm playing with it :P), so it's definitely doable. In my POC I got this working with approximately 700 lines of code.

[UserGalileo]

Demo with Validation (synchronous & asynchronous validators, for both Controls, Arrays and Groups).

These are pretty much Angular's Reactive Forms, some features are obviously missing but yeah, this is pretty much it. I was surprised at how cool this is with Lit, feels like home :P And I expected it to be much more difficult to achieve but this seems to work quite decently!

If something like this not appealing for the Lit team I think this would be a great idea for a 3rd party library :)

[Christian24]

@UserGalileo I just started working on something similar last night. I would be very interested in making a library that handles this well happen.

My version works more like Formik: https://formik.org/docs/overview#the-gist

The idea being all validation can be handled by yup: https://github.com/jquense/yup

My POC is very early, so nothing to show yet other than some dirty code :)

[yorrd]

we have a similar implementation that's biased towards our ORM and provides some shortcuts. How do you propose using custom elements as fields? We provide an interface which guarantees that each field throws certain value changed events. In this case only native browser elements would be supported?

[Christian24]

Well you can always extend the list of possible FieldAccessors to include any control you want: https://stackblitz.com/edit/vitejs-vite-gnpvy1?file=src/form/field-accessors.ts

In our current implementation we have an adapter for every custom element we use.

[UserGalileo]

I think having a Custom Element which behaves as a native control should already be possible without the package knowing it's a custom element: https://twitter.com/claviska/status/1480908354969079817

But I think in my example I may let the developer specify a different Accessor to the bind directive on the template just in case :)

[UserGalileo]

After some time playing around with code, I think I've come to the conclusion that the 2 solutions are fundamentally divergent and that the first one would be much more in the spirit of Lit, while the second one (a-la Angular) would be suitable for a 3rd party library.

The first solution assumes a flat structure: this is not only more simple but to me it seems more pointed towards the standards for forms. In pure HTML, if I'm not mistaken, there's no way to send a nested value when you submit a form. So sending something like this would not be possible:

{
  user: {
    name: 'mario',
    surname: 'rossi',
  }
}

Instead, it should be sent like this:

<input type="text" name="user.name" >
<input type="text" name="user.surname" >

{
  "user.name": "mario",
  "user.surname": "rossi"
}

In practice, it's the template names that count, not the model. If I'm correct, this means that the first solution would be the only one to support Progressive Enhancement if we ever have some custom <form> tag which uses fetch or a native submission if JS is not available (speaking of the framework discussion, a-la Remix). Also that would force us to have mandatory name attributes (which could be automatically assigned by the directive since it's a flat structure, they'd be unique), which would not be needed for the second solution.

Having a nested structure would imply using JavaScript to send whatever we want, at that point we're free but this introduces opinions. Examples about disabled fields:

• do we want to send them anyway? A lot of people use the disabled property just to stop interaction (some form controls such as select don't have a readonly attribute) but want to send them anyway. And therefore, should they be validated?
• what if all of the controls inside a FormGroup are disabled? Should we skip the nested object completely or send an empty object?

This is why I think there should be an official package, surely the Lit team could make decisions which are as close as possible to how the browser behaves (or will behave in the future), there are things a lot of us don't even know about.

The second solution however, being a more opinionated one and assuming an ajax submission, would be free to diverge from standards.

Any thoughts? :)

[drk-mtr]

Good to see people are exploring this! I fully agree - as a newcomer this is one of the first friction points I hit when making an app with lit.

I'm not experienced with dev myself, and I'm biased towards the needs of boring line-of-business apps that are very form-heavy because that's mostly what I work on. I'm comfortable with a library that's on the more "fully featured" end of the scale for solving this problem, purely because it's where so much time is spent on the sort of projects I work on. The PoCs you've shared above look like a really nice way to achieve this - think I'd lean toward the more Angular-style approach but that may be familiarity bias.

Re. nesting - appreciate the arguments above and I don't know anything about emerging standards - however the ability to nest if needed might make it easier to fit the shape of the submission to match existing APIs for some use cases?

[UserGalileo]

I agree, I'm used to Angular forms and nesting really comes in handy. Btw I'm doing some experiments here, at the moment I really like it but I don't have much time to go on with the experiment and there are questions that I feel I can't fully answer on my own (validators, native validation attributes, disabled fields, optional controls...), but this should demonstrate the utility of something like this :)

You can just clone the repo and run npm i, npm run dev to see the demo working:

form = this.fb.group({
    user: this.fb.group({
      name: this.fb.control('Michele', [V.required, V.minLength(2)]),
      surname: this.fb.control('Stieven'),
      gender: this.fb.control<'M' | 'F'>('M'),
    }, {
      asyncValidators: [CV.forbiddenCredentials('mario', 'rossi')] 
    }),
    agreement: this.fb.control(false),
    counter: this.fb.control(1),
    phones: this.fb.array<FormControl<string>>([], [CV.allRequired]),
    addresses: this.fb.array<FormGroup<{
      street: FormControl<string>,
      nr: FormControl<string>
    }>>(),
  }, {
    validators: [CV.sameLength('phones', 'addresses')]
  });

[drk-mtr]

I haven't had a chance to play with this properly but it looks great, thanks for sharing.

[Christian24]

I forgot to reply here ;)

Well I prefer the Angular style as well, because it allows for typings. I have a prototype similar to @UserGalileo, but it is very specific to our existing internal component library (for example every component already has some validation logic builtin like HTMLInputElement).

My main goal was to handle initial values, reset and validation. A couple things I have learnt:

• At first my idea was to read the initial values from the control, however this leads to a multitude of problems:
  • the initial value could always be undefined.
  • What happens if the control isn't rendered or you forgot the directive to bind it?
  • Value could always be undefinedwhich makes the end result harder to work with.

So I settled with always providing initial values when initializing a control.

• If the initial value is false, Typescript infers a type of false. I had to write a custom type to get around this.
• I didn't use ReactiveControllers, because my directive does update automatically because it is subscribed to changes. I felt triggering an update of the control wasn't necessary. Maybe I missed something, but so far my dumb implementation works fine. Also I kinda wanted to force developers to subscribe to the observable so they implement a @state()property like they usually do. I am not sure I am happy with that design decision yet, especially since it kinda forces people to adopt rxjs, but yeah.
• I find nesting to be hugely important because this allows for composed elements to be part of the form as well. Very often we create our own small custom elements to encapsulate a group of fields, so I created a base class FormGroupAssociatedElement which has a property formGroup: FormGroup and automatically provides the directive to an abstract renderContent method. This allows something similar to [formGroup] binding in Angular, which I found to be very helpful. I could have used a custom ControlValueAccessor as well, but I feel this would lead to a lot of boilerplate.
• I wrote my own formArray directive which works similarly to repeat. I feel this greatly simplifies rendering of FormArrays and reduces boilerplate.
• All opinionated code of of enabledValue, disabledValue etc. turned out to be not super useful. Granted, we do have an existing code base and properties of our elements like disabled, max, min etc. change quite frequently based on changes to properties. I feel the shape of a form is much more dictated by the composition of controls than the data the backend expects. Therefore mapping is always necessary. And that mapping does depend on a property we have in our component / rendering code today, so disabled state is not important for us. Your experience might be different. All I am saying is I removed all opinions except two due to complexity (both implementation wise and to explain to developers), because in the end I think at least my colleagues seemed to be more interested in the raw data and "select what they need accordingly". The two opinions I still have though are:
  • controls with no connected directive do not participate in validation (meaning their validation method is not called)
  • when controls are reconnected they do reset to their initial value. We have a couple controls that only show when a certain option is selected an having those controls hold the previous values is weird then. The initial values are always empty in our case, which is why this works for us.
    As I said you might feel different about these, but they work for us at the moment.
• What is the initial value for an empty number input? I settled on undefined, so the type of that field is number | undefined.
• A little bit of a philosophical one at the end, but what about existing event bindings you have in templates? Is this still valid or should you rather read the value from the instance of the FormControl?. I don't know if this matters in the end, but the question definitely popped into my head, because suddenly that existing event binding still feels "lit native", but at the same time you might be creating a shadow copy of the data of your control. Is this okay? Is this bad? I haven't reached a real conclusion here yet, but it is an interesting question.

I hope I didn't forget anything, but that's what I have learnt so far. I would love to drive the discussion forward, but at the same time I fear the idea of an official @lit/form package is not gaining much traction...

[drk-mtr]

At first my idea was to read the initial values from the control, however this leads to a multitude of problems: [...] So I settled with always providing initial values when initializing a control.

I can't find the thread now, but I think the Angular team came to the same conclusion as part of their move towards properly typed forms (and probably wished they had forced initialisation in the first place).

One thing that might be worth considering - a forms library could potentially use the HTMLElement.attachInternals() API in order to listen on the parent form element, which could keep the template code clean. This might be a silly idea as it'd probably create problems around nesting, I haven't had a chance to look into it more deeply.

[Christian24]

At first my idea was to read the initial values from the control, however this leads to a multitude of problems: [...] So I settled with always providing initial values when initializing a control.

I can't find the thread now, but I think the Angular team came to the same conclusion as part of their move towards properly typed forms (and probably wished they had forced initialisation in the first place).

Yep, initialization is a cool thing, especially since it allows, helps to infer types as well, plus you have a single source of truth. Sometimes, you need to explicitly set the type though, think about a number input with no value. It would be undefined, but the value you would want the field to have would be undefined | number. :)

One thing that might be worth considering - a forms library could potentially use the HTMLElement.attachInternals() API in order to listen on the parent form element, which could keep the template code clean. This might be a silly idea as it'd probably create problems around nesting, I haven't had a chance to look into it more deeply.

Interesting idea. However, in practice I don't really see much a of problem with bloating template code too much, because forms are quite repetitive, so you would probably define a new control for these anyway (think about names or addresses for example). For cases like this I have created a simple base class that has a property called formGroup and its render method already gets passed the formControl directive. It is a bit inspired by how Angular handles those things. :)

[justinfagnani]

Since we have a new RFC Process does someone here want to draft an RFC for a @lit-labs/forms package?

If we need some higher-bandwidth discussion to get consensus on an API style before the RFC, we could host a call just on forms.

[Christian24]

I can look into it for sure. @UserGalileo what do you think?

[Christian24]

I have started writing it: https://github.com/Christian24/rfcs-forms/blob/main/rfcs/0000-rfc-forms.md It is EXTREMELY hazy by design, because I really want people to be able to discuss it openly and rip into it ;) Much more interested in having a solution supported by the lit community than having exactly this solution.

However, given the learnings @UserGalileo and myself already have made, I try to incorporate them into the RFC as well.

Sadly, not sure if I get the RFC much further for Wednesday's call. I will try to attend, but uncertain, because work might have other plans ;)

[Christian24]

The RFC is available: lit/rfcs#8

[justinfagnani]

Thanks you!!

[UserGalileo]

Thank you @Christian24 ! I'll leave some comments here and there in my spare time ;)

[jitendraP-ashutec]

I didn't found @lit-labs/forms package in npm ? does you have published it for user?

[drk-mtr]

No there is no @lit-labs/forms package. You can have a play with UserGalileo's prototype as shared above if you want.

[jitendraP-ashutec]

Ok, Thanks @drk-mtr

[jitendraP-ashutec]

@UserGalileo does input type radio will work ? Does any one has idea how I can extend it so its support radio button ?

[danduh]

Hi all. How can we know the status of @lit-labs/forms? How to participate? How can we help?
Thanks

[Christian24]

You can follow progress here: lit/rfcs#8 However, since the idea seemed to not resonate well with the community, I would consider further development unlikely.

[justinfagnani]

I think there's still a possibility, and sorry for disappearing from that PR!

However, for those of us on the team without experience with a similar forms library, I think we're going to need motivate the proposal with a more fundamental problem/goals/solution framing so we have a clearer starting point for understanding why the package does what it does. I'll try to bring that feedback back to the RFC PR!

[augustjk]

Here's an rough attempt at an adapter for https://final-form.org/ with a reactive controller and directive:
https://lit.dev/playground/#gist=08b866474027f36eaa0d1863a61c7065

I'm curious if people would find something like this useful.

It's not meant to say we don't need a separate forms package but the scope of the package as proposed in the RFC is pretty huge and using an existing library could be a low cost way to provide something useful while discussions happen around the RFC.