docs: use when in signal forms rule examples

cexbrayat · leonsenft · commit 9a7dedced687 · 2026-05-15T12:16:50.000-07:00
Update the Signal Forms guides to match df54e6a, which introduced the consistent {when: ...} form for these rules.
diff --git a/adev/src/content/guide/forms/signals/designing-your-form-model.md b/adev/src/content/guide/forms/signals/designing-your-form-model.md
@@ -211,9 +211,9 @@ interface BillPayFormModel {
 
 const billPaySchema = schema<BillPayFormModel>((billPay) => {
   // Hide credit card details when user has selected a method other than credit card.
-  hidden(billPay.method.card, ({valueOf}) => valueOf(billPay.method.type) !== 'card');
+  hidden(billPay.method.card, {when: ({valueOf}) => valueOf(billPay.method.type) !== 'card'});
   // Hide bank account details when user has selected a method other than bank account.
-  hidden(billPay.method.bank, ({valueOf}) => valueOf(billPay.method.type) !== 'bank');
+  hidden(billPay.method.bank, {when: ({valueOf}) => valueOf(billPay.method.type) !== 'bank'});
 });
 ```
 
@@ -358,7 +358,7 @@ class MyForm {
 
   protected readonly myForm = form(this.formModel, (root) => {
     // Disable the entire form when the resource is loading.
-    disabled(root, () => this.domainModelResource.isLoading());
+    disabled(root, {when: () => this.domainModelResource.isLoading()});
   });
 }
 ```
diff --git a/adev/src/content/guide/forms/signals/field-state-management.md b/adev/src/content/guide/forms/signals/field-state-management.md
@@ -222,8 +222,8 @@ Availability state signals control whether fields are interactive, editable, or
 The `disabled()` signal indicates whether a field accepts user input. Disabled fields appear in the UI but users cannot interact with them.
 
 ```angular-ts
-import { Component, signal } from '@angular/core'
-import { form, FormField, disabled } from '@angular/forms/signals'
+import {Component, signal} from '@angular/core';
+import {form, FormField, disabled} from '@angular/forms/signals';
 
 @Component({
   selector: 'app-order',
@@ -236,25 +236,25 @@ import { form, FormField, disabled } from '@angular/forms/signals'
     @if (orderForm.couponCode().disabled()) {
       <p class="info">Coupon code is only available for orders over $50</p>
     }
-  `
+  `,
 })
 export class Order {
   orderModel = signal({
     total: 25,
-    couponCode: ''
-  })
+    couponCode: '',
+  });
 
-  orderForm = form(this.orderModel, schemaPath => {
-    disabled(schemaPath.couponCode, ({valueOf}) => valueOf(schemaPath.total) < 50)
-  })
+  orderForm = form(this.orderModel, (schemaPath) => {
+    disabled(schemaPath.couponCode, {when: ({valueOf}) => valueOf(schemaPath.total) < 50});
+  });
 }
 ```
 
 In this example, we use `valueOf(schemaPath.total)` to check the value of the `total` field to determine whether `couponCode` should be disabled.
 
 NOTE: The schema callback parameter (`schemaPath` in these examples) is a `SchemaPathTree` object that provides paths to all fields in your form. You can name this parameter anything you like.
 
-When defining rules like `disabled()`, `hidden()`, or `readonly()`, the logic callback receives a `FieldContext` object that is typically destructured (such as `({valueOf})`). Two methods commonly used in validation rules are:
+When defining rules like `disabled()`, `hidden()`, or `readonly()`, the `when` function receives a `FieldContext` object that is typically destructured (such as `({valueOf})`). Two methods commonly used in validation rules are:
 
 - `valueOf(schemaPath.otherField)` - Read the value of another field in the form
 - `value()` - A signal containing the value of the field the rule is applied to
@@ -293,7 +293,7 @@ export class Profile {
   });
 
   profileForm = form(this.profileModel, (schemaPath) => {
-    hidden(schemaPath.publicUrl, ({valueOf}) => !valueOf(schemaPath.isPublic));
+    hidden(schemaPath.publicUrl, {when: ({valueOf}) => !valueOf(schemaPath.isPublic)});
   });
 }
 ```
@@ -440,7 +440,7 @@ const orderModel = signal({
 });
 
 const orderForm = form(orderModel, (schemaPath) => {
-  hidden(schemaPath.shippingAddress, ({valueOf}) => !valueOf(schemaPath.requiresShipping));
+  hidden(schemaPath.shippingAddress, {when: ({valueOf}) => !valueOf(schemaPath.requiresShipping)});
 });
 ```
 
@@ -517,7 +517,9 @@ export class Order {
   });
 
   orderForm = form(this.orderModel, (schemaPath) => {
-    hidden(schemaPath.shippingAddress, ({valueOf}) => !valueOf(schemaPath.requiresShipping));
+    hidden(schemaPath.shippingAddress, {
+      when: ({valueOf}) => !valueOf(schemaPath.requiresShipping),
+    });
   });
 }
 ```
diff --git a/adev/src/content/guide/forms/signals/form-logic.md b/adev/src/content/guide/forms/signals/form-logic.md
@@ -14,12 +14,12 @@ Use rules when field behavior depends on other field values or needs to update r
 
 ## How rules work
 
-Rules bind reactive logic to specific fields in your form. Most rules accept a reactive logic function as an optional argument. The reactive logic function automatically recomputes whenever the signals it references change, just like a `computed`.
+Rules bind reactive logic to specific fields in your form. Most conditional rules accept an options object with a `when` function. The `when` function automatically recomputes whenever the signals it references change, just like a `computed`.
 
 ```ts
 const orderForm = form(this.orderModel, (schemaPath) => {
-  disabled(schemaPath.couponCode, ({valueOf}) => valueOf(schemaPath.total) < 50);
-  //~~~~~~ ~~~~~~~~~~~~~~~~~~~~~  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+  disabled(schemaPath.couponCode, {when: ({valueOf}) => valueOf(schemaPath.total) < 50});
+  //~~~~~~ ~~~~~~~~~~~~~~~~~~~~~  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   //rule     path                   reactive logic function
 });
 ```
@@ -70,7 +70,7 @@ export class Settings {
 
 ### Conditional disabling
 
-To disable a field based on conditions, provide a reactive logic function that returns `true` (disabled) or `false` (enabled):
+To disable a field based on conditions, provide a `when` function that returns `true` (disabled) or `false` (enabled):
 
 ```angular-ts
 import {Component, signal} from '@angular/core';
@@ -98,7 +98,7 @@ export class Order {
   });
 
   orderForm = form(this.orderModel, (schemaPath) => {
-    disabled(schemaPath.couponCode, ({valueOf}) => valueOf(schemaPath.total) < 50);
+    disabled(schemaPath.couponCode, {when: ({valueOf}) => valueOf(schemaPath.total) < 50});
   });
 }
 ```
@@ -143,14 +143,15 @@ export class Order {
   });
 
   orderForm = form(this.orderModel, (schemaPath) => {
-    disabled(schemaPath.couponCode, ({valueOf}) =>
-      valueOf(schemaPath.total) < 50 ? 'Order must be $50 or more to use a coupon' : false,
-    );
+    disabled(schemaPath.couponCode, {
+      when: ({valueOf}) =>
+        valueOf(schemaPath.total) < 50 ? 'Order must be $50 or more to use a coupon' : false,
+    });
   });
 }
 ```
 
-The reactive logic function returns:
+The `when` function returns:
 
 - A **string** to disable the field with a reason
 - `false` to enable the field (not just any falsy value - use `false` explicitly)
@@ -163,12 +164,13 @@ You can also call `disabled()` multiple times on the same field, and all of the
 
 ```angular-ts
 orderForm = form(this.orderModel, (schemaPath) => {
-  disabled(schemaPath.promoCode, ({valueOf}) =>
-    !valueOf(schemaPath.hasAccount) ? 'You must have an account to use promo codes' : false,
-  );
-  disabled(schemaPath.promoCode, ({valueOf}) =>
-    valueOf(schemaPath.total) < 25 ? 'Order must be at least $25' : false,
-  );
+  disabled(schemaPath.promoCode, {
+    when: ({valueOf}) =>
+      !valueOf(schemaPath.hasAccount) ? 'You must have an account to use promo codes' : false,
+  });
+  disabled(schemaPath.promoCode, {
+    when: ({valueOf}) => (valueOf(schemaPath.total) < 25 ? 'Order must be at least $25' : false),
+  });
 });
 ```
 
@@ -184,7 +186,7 @@ NOTE: Like disabled fields, hidden fields also skip validation. See the [Validat
 
 ### Basic field hiding
 
-Use `hidden()` with a reactive logic function that returns `true` (hidden) or `false` (visible):
+Use `hidden()` with a `when` function that returns `true` (hidden) or `false` (visible):
 
 ```angular-ts
 import {Component, signal} from '@angular/core';
@@ -214,7 +216,7 @@ export class Profile {
   });
 
   profileForm = form(this.profileModel, (schemaPath) => {
-    hidden(schemaPath.publicUrl, ({valueOf}) => !valueOf(schemaPath.isPublic));
+    hidden(schemaPath.publicUrl, {when: ({valueOf}) => !valueOf(schemaPath.isPublic)});
   });
 }
 ```
@@ -264,7 +266,7 @@ The `[FormField]` directive automatically binds the `readonly` attribute based o
 
 ### Conditional readonly
 
-To make a field readonly based on conditions, provide a reactive logic function:
+To make a field readonly based on conditions, provide a `when` function:
 
 ```angular-ts
 import {Component, signal} from '@angular/core';
@@ -292,7 +294,7 @@ export class Document {
   });
 
   documentForm = form(this.documentModel, (schemaPath) => {
-    readonly(schemaPath.title, ({valueOf}) => valueOf(schemaPath.isLocked));
+    readonly(schemaPath.title, {when: ({valueOf}) => valueOf(schemaPath.isLocked)});
   });
 }
 ```
@@ -580,10 +582,12 @@ export class Promo {
   });
 
   promoForm = form(this.promoModel, (schemaPath) => {
-    disabled(schemaPath.promoCode, ({valueOf}) =>
-      !valueOf(schemaPath.hasAccount) ? 'You must have an account' : false,
-    );
-    hidden(schemaPath.promoCode, ({valueOf}) => valueOf(schemaPath.subscriptionType) === 'free');
+    disabled(schemaPath.promoCode, {
+      when: ({valueOf}) => (!valueOf(schemaPath.hasAccount) ? 'You must have an account' : false),
+    });
+    hidden(schemaPath.promoCode, {
+      when: ({valueOf}) => valueOf(schemaPath.subscriptionType) === 'free',
+    });
     debounce(schemaPath.promoCode, 300);
     metadata(schemaPath.promoCode, PLACEHOLDER, () => 'Enter promo code');
   });
diff --git a/adev/src/content/guide/forms/signals/migration.md b/adev/src/content/guide/forms/signals/migration.md
@@ -347,7 +347,7 @@ export class UserProfile {
 
   readonly emailControl = new SignalFormControl('', (p) => {
     // The control becomes disabled whenever isLoading is true
-    disabled(p, () => this.isLoading());
+    disabled(p, {when: () => this.isLoading()});
   });
 
   async saveData() {
diff --git a/adev/src/content/guide/forms/signals/schemas.md b/adev/src/content/guide/forms/signals/schemas.md
@@ -4,13 +4,13 @@ Signal Forms uses a two-layer architecture to separate _how your form is structu
 
 When you pass a schema function to `form()`, that function _runs once_ during form creation. Its job is to set up the form's logic tree by declaring which fields have validation, which fields are disabled, and which fields depend on other fields. This is the **structural layer** of your form.
 
-Inside a schema function, you call rule functions such as `disabled()` and `validate()`. These rule functions accept reactive logic that recomputes whenever the signals they reference change. Other rules like `required()` accept optional configuration, including a `when` function that conditionally activates the rule. Together, these form the **behavioral layer** of your form during runtime.
+Inside a schema function, you call rule functions such as `disabled()` and `validate()`. These rule functions accept reactive logic that recomputes whenever the signals they reference change. Conditional rules like `disabled()` and `required()` accept optional configuration, including a `when` function that activates the rule. Together, these form the **behavioral layer** of your form during runtime.
 
 ```ts
 contactForm = form(this.contactModel, (schemaPath) => {
   // Schema function: runs ONCE during form creation
   required(schemaPath.name);
-  disabled(schemaPath.couponCode, ({valueOf}) => valueOf(schemaPath.total) < 50);
+  disabled(schemaPath.couponCode, {when: ({valueOf}) => valueOf(schemaPath.total) < 50});
   //  ^^^ Reactive logic: recomputes when total changes
 });
 ```
