The `debounce()` rule allows developers to control when changes to a
form control are synchronized to the form model.
This feature necessitated some changes to `FieldState`:
* `controlValue` is a new signal property that represents the current
value of a form field as it appears in its corresponding control.
* `value` conceptually remains unchanged; however, its value may lag
behind that of `controlValue` if a `debounce()` rule is applied.
The `debounce()` rule essentially manages when changes to `controlValue` are
synchronized to `value`. The intent is that an expensive or slow
validation rule can react to the debounced `value`, rather than a more
frequently changing `controlValue`.
Directly updating `value` immediately updates `controlValue`, and cancels any
pending debounced updates.
When multiple `debounce()` rules are applied to the same field, the last
currently active rule is used to debounce an update. These rules are
applied to child fields as well, unless they override them with their
own rule.
Currently we maintain the pathKeys internally, but do not expose them
through the `FieldContext`, this PR updates the `FieldContext` to expose
this property.
When we set the `value` on a `<select>` element we're really just
setting the selected `<option>`. It treats the selected option as the
source of truth, rather than the actual value. This means that if
options are added or removed or their value changes, the `<select>` may
wind up with a different `value` than what's in our model.
This PR resolves this issue by adding a `MutationObserver` to the select
that is used to resync its value to the model whenever the options may
have changed.
For each field state property, check if it has changed since the last
time it was checked before writing it the corresponding form control
property.
The `pattern` and `required` properties of the field state now return a
default value rather than `undefined` if not defined by metadata.
In some cases the logic order was not preserved properly when using `apply`. In particular this occurs when some logic is registered on a child of the root, followed by an apply to the root, followed by further logic registered on a child. In this case the final registered logic wound up running before the applied logic.
This happened because `FieldPathNode` for a child path was caching its `LogicNodeBuilder` at creation time. This meant that if the parent's `LogicNodeBuilder` changed (e.g., due to an `apply` call), the child would still be using the old one.
This commit fixes the issue by dynamically resolving the `LogicNodeBuilder` for a child path whenever it is accessed.
This commit changes arrays in a parent array to be tracked the same way
as primitive values like strings and numbers. This is necessary because
the tracking key symbol used to maintain identity for objects in an
array does not survive the array spread operation:
```
return {...oldValue} // tracking symbol preserved ✅
return [...oldValue] // tracking symbol lost ❌
```
The directive implemnetation might set CVA values during the template evaluation. Since the template is a reactive context we need to untrack when setting the CVA values to prevent writing to signals in a reactive context.
fixes#64614
PR Close#64618
Renames the field state related to metadata to reflect the new
"metadata" name. In particular:
- `property(...)` is renamed to `metadata(...)`
- `hasProperty(...)` is renamed to `hasMetadata(...)`
PR Close#64603
Renames logic functions related to metadata to align with the new
"metadata" name. Notably:
- `property(...)` => `metadata(...)`
- `aggregateProperty(...)` => `aggregateMetadata(...)`
PR Close#64603
Prior to this change, `FieldState` defined a signal for each built-in
property. This unfortunately meant that the `Field` directive had no way
of knowing which property had actually been defined in the schema, and
would thus attempt to propagate them all to the bound form control. This
meant that the default values of these signals would override the
default or template defined values of these control properties.
Now these properties are `undefined` by default, and only initialized if
defined in the schema. Thus the `Field` directive will not attempt to
bind any properties that aren't explicitly managed by the schema.
PR Close#64446
Note that unlike the other built-in properties, `pattern` is not
propagated to native controls so the lack of symmetry with other
property tests is intentional.
PR Close#64446
Add support for interoperability between signal forms and reactive forms that
commit effccffde0 had removed.
A signal forms field can once again be bound to any element or component with a
`ControlValueAccessor`.
PR Close#64471
When a directive injects a `ViewContainerRef`, the runtime inserts a container that was throwing off the logic that recognizes native controls.
These changes switch to check if the node is a native control through the `TNode`. This also makes it a bit less prone to breaking during SSR.
Fixes#64362.
PR Close#64368
Caches information about the kind of form control that a `TNode`
represents in `TNodeFlags`. This avoids redundant computations on
subsequent template create and update passes.
Renames the `INVALID_CONTROL_HOST` error code to
`INVALID_FIELD_DIRECTIVE_HOST` for clarity and adds a test for it.
PR Close#64351
Renames the control directive and the input that users set to bind a
field to a UI control.
Previously users would do:
```
<input [control]="someField">
```
Now users will do:
```
<input [filed]="someField">
```
PR Close#64300
Fix a bug where the min property of a form field was not correctly
propagated to custom controls. Also ensure that min and max are only
bound to native input elements that support them.
PR Close#63884
Fix several typos caught by the added test cases:
* `disabled` attribute for native controls
* `readonly` property for custom controls
Note that the `name` test cases have been marked `pending()` due to
https://github.com/angular/angular/issues/63882.
PR Close#63884
Move most of the implementation of the `Control` directive into core
framework instructions. This allows field state changes to be propagated
to their corresponding UI controls directly during execution of a
template update block, instead of relying on `effect()`s to synchronize
each change later during the update (and too late in the case of
required inputs).
* Define a private API in `@angular/core` for signal forms to implement:
* `ɵControl` for the `Control` directive.
* `ɵFieldState` for the control's associated `FieldState`.
* Emit specialized instructions when compiling a `[control]` binding:
* `ɵɵcontrolCreate` sets up the `ɵControl` directive if present,
determines whether it's bound to a native control element or a
custom control component, and adds the appropriate event listeners
to notify the `ɵFieldState` of UI changes.
* `ɵɵcontrol` propagates changes from `ɵFieldState` properties to their
corresponding UI control properties (in additional to binding the `control`
property itself).
PR Close#63773
There are two primary reasons for this renaming:
1. It better reflects the actual nature of the proxy object, namely that
the form is represented as a tree, and that this object is used for
navigating the tree structure (while `FieldState` is used for getting
the state at a particular point in the structure).
2. This frees up the name `Field` to be used for the directive that
binds a `FieldTree` to a UI control.
PR Close#64214
Adds additional handling for input types that handle numbers:
- number
- range
- datetime-local
As well as input types that handle dates:
- date
- month
- week
- time
- *not* datetime-local which does not allow setting valueAsDate
This PR allows binding either a `Field<string>` or `Field<number>` to
the number type inputs and a `Field<string>`, `Field<numebr>`, or
`Field<Date | null>` to the date type inputs. Binding uses the
corresponding `.value`, `.valueAsNumber`, or `.valueAsDate` according to
the type of the `Field`.
When reading new values out of the input, the `Control` directive will
read the property that aligns with the type of the existing value in the
`Field` and write back the same type.
PR Close#63585
This allows passing errors and disabled reasons that did not originate
from `@angular/forms/signals` in case the the control is being used
separately from the forms system
PR Close#63455
Removes custom handling of emptiness in several of the validators and
replaces it with a common `isEmpty` check. The common empty check
considered the following values to be empty: `null`, `undefined`, `''`,
`false`, `NaN`
Generally most validators should treat an empty value as valid. This
aligns with both the behavior or native HTML validators and reactive
forms validators.
As an example, consider an optional email field. If the email validator
considered empty string to be an invalid email, there would be no way
for the user to not enter it.
There are several exceptions to this rule:
- `required` whose entire purpose is to ensure that the field is *not*
empty
- `validateStandardSchema` which should subject all values including
empty ones to the specified standard schema. It is up to the schema to
decide whether an empty value is valid or not
- `validate`/`validateAsync` which leaves it up to the user's custom
validation logic to decide if an empty value is valid.
PR Close#63456
