feat(core): add ability to transform input values

[crisbeto]

According to the HTML specification most attributes are defined as strings, however some can be interpreted as different types like booleans or numbers. In the HTML standard, boolean attributes are considered true if they are present on a DOM node and false if they are omitted. Common examples of boolean attributes are disabled on interactive elements like <button> or checked on <input type="checkbox">. Another example of an attribute that is defined as a string, but interpreted as a different type is the value attribute of <input type="number"> which logs a warning and ignores the value if it can't be parsed as a number.

Historically, authoring Angular inputs that match the native behavior in a type-safe way has been difficult for developers, because Angular interprets all static attributes as strings. While some recent TypeScript versions made this easier by allowing setters and getters to have different types, supporting this pattern still requires a lot of boilerplate and additional properties to be declared. For example, currently developers have to write something like this to have a disabled input that behaves like the native one:

import {Directive, Input} from '@angular/core';

@Directive({selector: 'mat-checkbox'})
export class MatCheckbox {
  @Input()
  get disabled() {
    return this._disabled;
  }
  set disabled(value: any) {
    this._disabled = typeof value === 'boolean' ? value : (value != null && value !== 'false');
  }
  private _disabled = false;
}

This feature aims to address the issue by introducing a transform property on inputs. If an input has a transform function, any values set through the template will be passed through the function before being assigned to the directive instance. The example from above can be rewritten to the following:

import {Directive, Input, booleanAttribute} from '@angular/core';

@Directive({selector: 'mat-checkbox'})
export class MatCheckbox {
  @Input({transform: booleanAttribute}) disabled: boolean = false;
}

These changes also add the booleanAttribute and numberAttribute utilities to @angular/core since they're common enough to be useful for most projects.

Fixes #8968.
Fixes #14761.

[alfaproject]

Shouldn't you keep these properties sorted because of *morphism? (or at least in the same order as other usages)

[crisbeto]

I'm not sure if that makes a difference. My understanding is that only the shape of the object matters (e.g. it has the same set of properties).

[ajafff]

actually the order in which you add the properties is relevant and that also applies to object literals

[AndrewKushnir]

Looks great! 👍

[AndrewKushnir]

Reviewed-for: public-api

[ajafff]

Since there is no documentation yet, here are a few things I observed, which might be good to know for others interested in this change:

• there's a test to ensure that this inside of the transform function is the directive instance. this is currently not reflected in the type of the Input#transform option
• it looks like transform is called before comparing with the previous transformed values, so that the directive is not marked dirty if the transform function returns the same value for different input values. but there's no test for that

[crisbeto]

@ajafff

there's a test to ensure that this inside of the transform function is the directive instance. this is currently not reflected in the type of the Input#transform option

There's no way to get the this type in a decorator so that's why it isn't reflected. It would be up to the consumer to specify it.

it looks like transform is called before comparing with the previous transformed values, so that the directive is not marked dirty if the transform function returns the same value for different input values. but there's no test for that

This is incorrect, the directive will be marked as dirty, however ngOnChanges won't fire if the transform function returns the same value. This is difficult to fix, because we run change detection on a per-binding level, e.g. any time the expression in [someInput]="expr" changes, rather than per directive input. Fixing it would require a large (and likely breaking) refactor in the change detection system and would lead to higher memory usage since we would have to store more information. It's worth noting that setters have the same problem at the moment.

[dylhunn]

reviewed-for: fw-core, fw-forms, public-api

[ajafff]

@crisbeto

There's no way to get the this type in a decorator so that's why it isn't reflected. It would be up to the consumer to specify it.

That's not correct. The following solution works with experimentalDecorators. Not sure if/how it would work with ES decorators. Also not sure how breaking this would be. And it probably won't work with the proposed/upcoming signal inputs.

// @experimentalDecorators: true
declare function Input<This extends object, In, K extends keyof This>(
    transform: (this: This, v: In) => This[K] // provide 'this' in contextual type, ensure return type matches
): (target: This, key: K) => void;

https://www.typescriptlang.org/play?experimentalDecorators=true#code/CYUwxgNghgTiAEAzArgOzAFwJYHtXwElUAHZDAHgBUALLAZ3hAA8MRVgGcAjAK3AwA0hVEIDSjFmw7wA1iACeORPBr0AfAAoAUPF3wMMKKjqIcMALYAueBoy0611XSEA3a0QCU8ALxqV9gG1RAF0tD2tbWABzEAxHeyE5eWtRL194FxwsYABuLS1IKDoGAGF4AG8dPSgfeABGPL14AAEiUgwNFHRsPBs3eDoDLFQor0qmprt6ADoa73gAZhz4AHoV+AB3MxkGHmRBpGGQKon4OAxkGHwAahdGvQBfDxP4LlqAJjz8prX4MDM4JgIPIBtQcBsGEZGDAYGZ4FhlAByKZ0RHwYiwKDmWIgGDwYA4EB0VDI+DmKAYMDUF6tEhkTpoTC4fC2ezWcpMayDGDDKIPVzWVDIcxcXFjF5Nc6XfB3F5PF5gD5fH7rf4w-jA0HgyH4XGwvEGIwmMzY4D6eTEBAEokkjBkilU9Gwy0wDAgt2WmlteldJm9DT9bm88WnXRSq4Ze66eVNM3zT5aB5AA

the directive will be marked as dirty, however ngOnChanges won't fire if the transform function returns the same value.

I see. I mixed up DirectiveDef#setInput() which is used here and ComponentRef#setInput()

[crisbeto]

@ajafff that's an interesting approach, but it doesn't appear to work with arrow functions. Either way, I'll keep the type annotations as they are and we an iterate over it once the feature is merged.

[dylhunn]

This PR was merged into the repository by commit 68017d4.

[CodyTolene]

Excited to test this ❤️

[flobacher]

Great!
Would be awesome if this would work in combiniation with the directive-composition api, so one can transform inputs before the are provided to the host-directive... I just tested this.. the transform works, but is applied after the input value is passed on to the host-directive..

[angular-automatic-lock-bot]

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}