[Angular] Improve template integration

[flensrocker]

Hi,

I'm new to TanStack Form and just started playing around with it. I use Angular as my framework.

It seems there is "a lot of" boilerplate needed in the template to connect a field to an input.
Is it correct to assume, that this is (almost) always needed?

<input
  [name]="fullName.api.name"
  [value]="fullName.api.state.value"
  (blur)="fullName.api.handleBlur()"
  (input)="fullName.api.handleChange($any($event).target.value)"
/>

If so, Angular supports handling this with a directive, for example

import { Directive, inject } from '@angular/core';
import { TanStackField } from '@tanstack/angular-form';

@Directive({
  selector: 'input[tanstackFieldInput]',
  host: {
    '[name]': 'field.api.name',
    '[value]': 'field.api.state.value',
    '(input)': 'field.api.handleChange($event.target.value)',
    '(blur)': 'field.api.handleBlur()',
  },
})
export class TanStackFieldInput {
  protected readonly field = inject(TanStackField);
}

Usage would then be:

<input tanstackFieldInput />

And it would use the TanStackField of the ng-container (from the "Quick Start" example).

If there's interest in developing the integration of TanStack Form in Angular in a more "Angular way" (maybe like the FormGroupDirective, FormControlNameDirective style), I can try to do some research in this direction.

My goal is to have the least amount of "code" inside the template.

BTW: the class is called TanStackField, but its selector [tanstackField] (lowercase "s"). Is this on purpose? Or would be [tanStackField] a better selector? (it can be [tanstackField], [tanStackField] for compatibility)

[LeCarbonator]

Hi!

Reducing boilerplate is one of the ongoing projects at this time. React already has an implementation using useAppForm. Vue and Solid.js are in development in their respective PRs ( #1455 , #1453 ).

If you want to contribute for the Angular implementation, I'm sure your effort will be greatly appreciated!

As someone who has never programmed with Angular, I can't give proper feedback for your suggestion. However, I can give you reference points to consider for the Angular implementation based on what the React version did:

• In the React adapter, the 'wrapper' to reduce boilerplate is referred to as AppForm. It's part of the Form Composition section of the guide.
• The components themselves are very flexible. You define the behaviour of field.state.value, field.handleChange, field.handleBlur etc. inside to avoid having to repeat it outside.
• The field components are accessible after creating a hook and passing them as parameter. They are called using <field.CustomComponent/>.
• The form components are very similar, but they access and manage field-unspecific things (submit buttons, navigation blockers etc.).

The entire AppForm lives inside the React adapter. There are no form core changes as of v1.11.2 .

The directive sounds like an interesting approach. If you think it combines flexibility with reducing boilerplate, it is definitely worth looking into.

[flensrocker]

Hi!

Seems we are a perfect match, because I never did React. 😎
But I have some clues how it looks like.

I will dig into what you mentioned. I'm curious what we will discover.

Thank you!

[flensrocker]

Ok, I undestand the "Form Composition" as documentation to how to create own functions (hooks) to create reusable forms with custom content, so one don't have to repeat a lot.

I will try to create a minimal example (maybe with Angular Material), so we have something to talk about and if my thoughts are going into the right direction.

[LeCarbonator]

Ok, I undestand the "Form Composition" as documentation to how to create own functions (hooks) to create reusable forms with custom content, so one don't have to repeat a lot.

I will try to create a minimal example (maybe with Angular Material), so we have something to talk about and if my thoughts are going into the right direction.

Sounds good! @crutchcorn will probably also want to hear about the example

[flensrocker]

He's the reason I'm here, because I meet him last Friday at some kind of online user group, where he introduced me to TanStack Form. 😃

[crutchcorn]

Hey @flensrocker, glad to see you here!

I'd love to give some thoughts on your proposed API design, as well as the three major options I investigated for our Angular adapter.

Concerns on your proposal

Per our philosophy doc, I see two major problems with the proposed API:

1. It's not type safe (you can allow an input with a value of a number be assigned to this directive, which would set a string

2. It's not portable and would require us to have many APIs in the end. Any library that doesn't accept the specific input and blur events wouldn't work with this directive. As such, we'd have to add library support one-by-one

As such - despite good intentions and a good idea broadly - I'm not sure this specific API suites our needs.

Other explored options

As mentioned earlier, we explored many alternative APIs to make this work the way we think would be ideal with our engineering philosophy.

1a) Alternative tanstackField ControlValueAccessor directive

To solve some of the problems of input binding, we could use a ControlValueAccessor as outlined by Angular as the de-facto way to support binding even third-party inputs' values and such.

This might allow our code to look like this:

import { Component } from '@angular/core'
import { TanStackField, injectForm } from '@tanstack/angular-form'

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [TanStackField],
  template: `
    <form (submit)="handleSubmit($event)">
      <div>
        <ng-container
          [tanstackField]="form"
          name="fullName"
          #fullName="field"
        >
          <label [for]="fullName.api.name">First Name:</label>
          <input
            [name]="fullName.api.name"
            [formControl]="fullName.control"
          />
        </ng-container>
      </div>
      <button type="submit">Submit</button>
    </form>
  `,
})
export class AppComponent {
  form = injectForm({
    defaultValues: {
      fullName: '',
    },
    onSubmit({ value }) {
      // Do something with form data
      console.log(value)
    },
  })

  handleSubmit(event: SubmitEvent) {
    event.preventDefault()
    event.stopPropagation()
    this.form.handleSubmit()
  }
}

However, following private conversations with @alxhub it became clear that this API would not work either:

Generally this isn't a pattern that's possible to implement from user-space. A directive isn't normally allowed to write to the inputs of a component that it's sitting on (it isn't even allowed to know what component it's sitting on in the first place).

Alex provided great insights into some of the potential future options we'd have with a different control system via Signal Forms, but that it too was a series of unknowns to integrate with their future plans.

In regards to withForm

While the following APIs wouldn't enable shorter fields, themselves, we might be able to allow you to move form code to different components akin to our React withForm. Let's explore two more APIs we've looked at:

1b) withForm Component Decorator

The first option we looked at to enable our withForm feature into Angular was to reach for a component decorator. After all, decorators allow us to transform classes and add props, et al.

What if we could add the required fields to a Component via this decorator like so:

import { Component, input } from '@angular/core'
import { WithForm } from '@tanstack/angular-form'

@WithForm({
  // These values are only used for type-checking, and are not used at runtime
  // This allows you to `...formOpts` from `formOptions` without needing to redeclare the options
  defaultValues: {
    firstName: 'John',
    lastName: 'Doe',
  },
})
@Component({
  selector: 'app-sub-form',
  // ...
})
export class SubFormComponent {
    title = input<string>('Child Form');
    
    // `form` is an implicit prop that can be accessed on the class and is properly typed now
}

However, this idea does not work since, per TypeScript's docs, decorators don't change TS types of a class:

Note that the decorator does not change the TypeScript type

2b) WithForm base component class

OK, so if not a decorator, what if we used a base class to provide the form property?

import { Component, input } from '@angular/core'
import { WithForm } from '@tanstack/angular-form'

@Component({
  selector: 'app-sub-form',
  // ...
})
export class SubFormComponent extends WithForm {
    title = input<string>('Child Form');
    
    // `form` is an implicit prop from WithForm that can be accessed on the class and is properly typed now
}

This might work, but we need a way to pass properties so that we can infer the form input type:

function WithForm<T>(props: { defaultValues: T }) {
  return class WithFormImpl {
    form!: T;

    test = input<TName>();
  };
}

If we try this POC, we find disappointing results:

@Component({
  template: '',
})
class WithFormImpl<T> {
  form = input.required<T>();
}

function WithForm<T>(_props: { defaultValues: T }) {
  return WithFormImpl<T>;
}

@Component({
  selector: 'app-test',
  template: `
    <p>{{form().firstName}}</p>
  `,
})
export class Test extends WithForm({
  defaultValues: { firstName: 'one' },
}) {}

@Component({
  selector: 'app-root',
  imports: [Test],
  template: `
    <app-test [form]="{firstName: 'test'}"/>
  `,
})
class App {}

✘ [ERROR] NG8002: Can't bind to 'form' since it isn't a known property of 'app-test'.
1. If 'app-test' is an Angular component and it has 'form' input, then verify that it is included in the '@Component.imports' of this component.
2. If 'app-test' is a Web Component then add 'CUSTOM_ELEMENTS_SCHEMA' to the '@Component.schemas' of this component to suppress this message.
3. To allow any property add 'NO_ERRORS_SCHEMA' to the '@Component.schemas' of this component. [plugin angular-compiler]

    src/main.ts:29:14:
      29 │     <app-test [form]="{firstName: 'test'}"/>

---

What I find interesting, however, is that if I add:

schemas: [NO_ERRORS_SCHEMA],

To App it works at runtime.

I've reached out to the Angular team to see if this is a bug or a hard limitation in the Angular compiler.

[flensrocker]

Hey Corbin, thank you for your reply!

This was my intention: just drop some code to trigger the discussion... 😎

Designing APIs which are (more or less) unified across frameworks is hard, especially, when they're so different like React and Angular. I will read your explored options to get a feeling for all this (waving hands).

The least thing I can do is contribute "opinions" - I have a lot of them, so willing to share... 😂
Give me some time to think about this stuff, and be sure, typesafety is something I cannot live without. So when you said on Friday "TypeScript is gonna be TypeScripting" I know exactly, what you mean - but typing the things like they should is such a better DX for the users of an API, that I don't want to live without it.

👍

[flensrocker]

For those who are interested: @crutchcorn and I had a little session to explore this idea. You can find the draft at #1541

That was fun!