From bbbcf8fc7fa680cace276ca04e166fff253a360a Mon Sep 17 00:00:00 2001 From: SkyZeroZx <73321943+SkyZeroZx@users.noreply.github.com> Date: Tue, 30 Jun 2026 21:53:07 -0500 Subject: [PATCH] docs: add `@see` references to Signal Forms --- .../signals/compat/src/api/compat_form.ts | 8 +++ packages/forms/signals/compat/src/api/di.ts | 2 + .../signal_form_control.ts | 2 + packages/forms/signals/src/api/control.ts | 6 ++ packages/forms/signals/src/api/di.ts | 4 ++ .../forms/signals/src/api/rules/debounce.ts | 1 + .../forms/signals/src/api/rules/disabled.ts | 3 + .../forms/signals/src/api/rules/hidden.ts | 3 + .../forms/signals/src/api/rules/metadata.ts | 47 +++++++++++++ .../forms/signals/src/api/rules/readonly.ts | 3 + .../api/rules/validation/standard_schema.ts | 10 +++ .../src/api/rules/validation/validate.ts | 2 + .../api/rules/validation/validate_async.ts | 4 ++ .../src/api/rules/validation/validate_http.ts | 4 ++ .../src/api/rules/validation/validate_tree.ts | 3 + .../api/rules/validation/validation_errors.ts | 66 +++++++++++++++++++ packages/forms/signals/src/api/structure.ts | 22 +++++++ .../signals/src/api/transformed_value.ts | 8 +++ packages/forms/signals/src/api/types.ts | 55 ++++++++++++++++ .../forms/signals/src/directive/form_field.ts | 5 ++ .../forms/signals/src/directive/form_root.ts | 2 + .../forms/signals/src/webmcp/registration.ts | 2 + 22 files changed, 262 insertions(+) diff --git a/packages/forms/signals/compat/src/api/compat_form.ts b/packages/forms/signals/compat/src/api/compat_form.ts index 430c4b8c31d..e5d33a98f95 100644 --- a/packages/forms/signals/compat/src/api/compat_form.ts +++ b/packages/forms/signals/compat/src/api/compat_form.ts @@ -15,6 +15,8 @@ import {CompatFieldAdapter} from '../compat_field_adapter'; /** * Options that may be specified when creating a compat form. * + * @see [Top-down migration using compatForm](guide/forms/signals/migration#top-down-migration-using-compatform) + * * @category interop * @publicApi 22.0 */ @@ -46,6 +48,8 @@ export type CompatFormOptions = Omit, 'adapter'>; * structure will match the shape of the model and any changes to the form data will be written to * the model. * + * @see [Top-down migration using compatForm](guide/forms/signals/migration#top-down-migration-using-compatform) + * * @category interop * @publicApi 22.0 */ @@ -80,6 +84,8 @@ export function compatForm(model: WritableSignal): FieldTree( * When passing a schema, the form options can be passed as a third argument if needed. * @param options The form options (excluding adapter, since it's provided). * + * @see [Top-down migration using compatForm](guide/forms/signals/migration#top-down-migration-using-compatform) + * * @category interop * @publicApi 22.0 */ diff --git a/packages/forms/signals/compat/src/api/di.ts b/packages/forms/signals/compat/src/api/di.ts index a9a36a7755c..e20152b91a9 100644 --- a/packages/forms/signals/compat/src/api/di.ts +++ b/packages/forms/signals/compat/src/api/di.ts @@ -12,6 +12,8 @@ import type {SignalFormsConfig} from '../../../src/api/di'; * A value that can be used for `SignalFormsConfig.classes` to automatically add * the `ng-*` status classes from reactive forms. * + * @see [Automatic status classes](guide/forms/signals/migration#automatic-status-classes) + * * @publicApi 22.0 */ export const NG_STATUS_CLASSES: SignalFormsConfig['classes'] = { diff --git a/packages/forms/signals/compat/src/signal_form_control/signal_form_control.ts b/packages/forms/signals/compat/src/signal_form_control/signal_form_control.ts index 4cb86b518e9..d48f1b947f4 100644 --- a/packages/forms/signals/compat/src/signal_form_control/signal_form_control.ts +++ b/packages/forms/signals/compat/src/signal_form_control/signal_form_control.ts @@ -77,6 +77,8 @@ export type ValueUpdateOptions = { * * ``` * + * @see [Binding SignalFormControl](guide/forms/signals/migration#binding-signalformcontrol) + * * @publicApi 22.0 */ export class SignalFormControl extends AbstractControl { diff --git a/packages/forms/signals/src/api/control.ts b/packages/forms/signals/src/api/control.ts index 8fe73db8c7b..3605f6e9d2f 100644 --- a/packages/forms/signals/src/api/control.ts +++ b/packages/forms/signals/src/api/control.ts @@ -14,6 +14,8 @@ import type {DisabledReason} from './types'; /** * The base set of properties shared by all form control contracts. * + * @see [Custom form controls](guide/forms/signals/custom-controls) + * * @category control * @publicApi 22.0 */ @@ -150,6 +152,8 @@ type FormUiControlImplementsFormFieldBindingOptions = Check< * * @template TValue The type of `FieldTree` that the implementing component can edit. * + * @see [Custom form controls](guide/forms/signals/custom-controls) + * * @category control * @publicApi 22.0 */ @@ -179,6 +183,8 @@ export interface FormValueControl extends FormUiControl { * implemented, but if they are will be kept in sync with the field state of the field bound to the * `Field` directive. * + * @see [Custom form controls](guide/forms/signals/custom-controls) + * * @category control * @publicApi 22.0 */ diff --git a/packages/forms/signals/src/api/di.ts b/packages/forms/signals/src/api/di.ts index 2ad32e7e3d0..66292fd7ebc 100644 --- a/packages/forms/signals/src/api/di.ts +++ b/packages/forms/signals/src/api/di.ts @@ -13,6 +13,8 @@ import {SIGNAL_FORMS_CONFIG} from '../field/di'; /** * Configuration options for signal forms. * + * @see [Automatic status classes](guide/forms/signals/migration#automatic-status-classes) + * * @publicApi 22.0 */ export interface SignalFormsConfig { @@ -25,6 +27,8 @@ export interface SignalFormsConfig { /** * Provides configuration options for signal forms. * + * @see [Automatic status classes](guide/forms/signals/migration#automatic-status-classes) + * * @publicApi 22.0 */ export function provideSignalFormsConfig(config: SignalFormsConfig): Provider[] { diff --git a/packages/forms/signals/src/api/rules/debounce.ts b/packages/forms/signals/src/api/rules/debounce.ts index 5bde1515562..414e6bf195e 100644 --- a/packages/forms/signals/src/api/rules/debounce.ts +++ b/packages/forms/signals/src/api/rules/debounce.ts @@ -21,6 +21,7 @@ import type {Debouncer, PathKind, SchemaPath, SchemaPathRules} from '../types'; * @param config A debounce configuration, which can be either a debounce duration in milliseconds, * `'blur'` to debounce until the field is blurred, or a custom {@link Debouncer} function. * + * @see [Debouncing form updates](guide/forms/signals/form-logic#delay-input-operations-with-debounce) * @see [Custom form controls](guide/forms/signals/custom-controls) for using `debounce('blur')` with * a custom `FormValueControl`. * diff --git a/packages/forms/signals/src/api/rules/disabled.ts b/packages/forms/signals/src/api/rules/disabled.ts index 1ebb1abed09..e3c9143f316 100644 --- a/packages/forms/signals/src/api/rules/disabled.ts +++ b/packages/forms/signals/src/api/rules/disabled.ts @@ -21,6 +21,9 @@ import type {FieldContext, LogicFn, PathKind, SchemaPath, SchemaPathRules} from * @template TValue The type of value stored in the field the logic is bound to. * @template TPathKind The kind of path the logic is bound to (a root path, child path, or item of an array) * + * @see [Disabled fields](guide/forms/signals/form-logic#prevent-field-updates-with-disabled) + * @see [Availability state](guide/forms/signals/field-state-management#availability-state) + * * @category logic * @publicApi 22.0 */ diff --git a/packages/forms/signals/src/api/rules/hidden.ts b/packages/forms/signals/src/api/rules/hidden.ts index 5624133cc9a..767aeaf26fe 100644 --- a/packages/forms/signals/src/api/rules/hidden.ts +++ b/packages/forms/signals/src/api/rules/hidden.ts @@ -28,6 +28,9 @@ import type {LogicFn, PathKind, SchemaPath, SchemaPathRules} from '../types'; * @template TValue The type of value stored in the field the logic is bound to. * @template TPathKind The kind of path the logic is bound to (a root path, child path, or item of an array) * + * @see [Hidden fields](guide/forms/signals/form-logic#configuring-hidden-state-on-fields) + * @see [Availability state](guide/forms/signals/field-state-management#availability-state) + * * @category logic * @publicApi 22.0 */ diff --git a/packages/forms/signals/src/api/rules/metadata.ts b/packages/forms/signals/src/api/rules/metadata.ts index caac4e4a183..9bef9e12426 100644 --- a/packages/forms/signals/src/api/rules/metadata.ts +++ b/packages/forms/signals/src/api/rules/metadata.ts @@ -24,6 +24,9 @@ import type {FieldState, LogicFn, PathKind, SchemaPath, SchemaPathRules} from '. * @template TKey The type of metadata key. * @template TPathKind The kind of path the logic is bound to (a root path, child path, or item of an array) * + * @see [Field metadata](guide/forms/signals/field-metadata) + * @see [Setting values from a schema](guide/forms/signals/field-metadata#setting-values-from-a-schema) + * * @category logic * @publicApi 22.0 */ @@ -55,6 +58,9 @@ export function metadata< * * @template TAcc The accumulated type of the reduce operation. * @template TItem The type of the individual items that are reduced over. + * + * @see [Combining contributions with reducers](guide/forms/signals/field-metadata#combining-contributions-with-reducers) + * * @publicApi 22.0 */ export interface MetadataReducer { @@ -130,6 +136,8 @@ function override(getInitial?: () => T): MetadataReducer { /** * A symbol used to tag a `MetadataKey` as representing an asynchronous validation resource. * + * @see [Async validation](guide/forms/signals/validation#async-validation) + * * @category validation * @publicApi 22.0 */ @@ -145,6 +153,8 @@ export const IS_ASYNC_VALIDATION_RESOURCE: unique symbol = Symbol('IS_ASYNC_VALI * @template TWrite The type written to this key using the `metadata()` rule * @template TAcc The type of the reducer's accumulated value. * + * @see [Field metadata](guide/forms/signals/field-metadata) + * * @publicApi 22.0 */ export class MetadataKey { @@ -164,6 +174,9 @@ export class MetadataKey { * Represents metadata that is used to define a valid limit for a field. * * @template TLimit The type the limit value. + * + * @see [Validation constraints](guide/forms/signals/custom-controls#validation-constraints) + * * @publicApi 22.0 */ export type LimitKey = MetadataKey< @@ -183,6 +196,8 @@ declare const LIMIT_SELECTION_KEY: unique symbol; * This indirection allows rules to bind a {@link LimitKey} of a specific limit type (e.g. `number` * or `Date`) matching the field's type to a generic {@link MetadataKey}. * + * @see [Validation constraints](guide/forms/signals/custom-controls#validation-constraints) + * * @publicApi 22.0 */ export type LimitSelectionKey = MetadataKey< @@ -198,6 +213,8 @@ export type LimitSelectionKey = MetadataKey< * * @template TKey The `MetadataKey` type * + * @see [Field metadata](guide/forms/signals/field-metadata) + * * @publicApi 22.0 */ export type MetadataSetterType = @@ -209,6 +226,8 @@ export type MetadataSetterType = * * @template TWrite The type written to this key using the `metadata()` rule * + * @see [Creating a metadata key](guide/forms/signals/field-metadata#creating-a-metadata-key) + * * @publicApi 22.0 */ export function createMetadataKey(): MetadataKey< @@ -223,6 +242,8 @@ export function createMetadataKey(): MetadataKey< * @template TWrite The type written to this key using the `metadata()` rule * @template TAcc The type of the reducer's accumulated value. * + * @see [Creating a metadata key](guide/forms/signals/field-metadata#creating-a-metadata-key) + * * @publicApi 22.0 */ export function createMetadataKey( @@ -247,6 +268,8 @@ export function createMetadataKey( * @template TRead The type read from the `FieldState` for this key * @template TWrite The type written to this key using the `metadata()` rule * + * @see [Attaching lifecycle-aware objects with managed metadata](guide/forms/signals/field-metadata#attaching-lifecycle-aware-objects-with-managed-metadata) + * * @publicApi 22.0 */ export function createManagedMetadataKey( @@ -265,6 +288,8 @@ export function createManagedMetadataKey( * @template TWrite The type written to this key using the `metadata()` rule * @template TAcc The type of the reducer's accumulated value. * + * @see [Attaching lifecycle-aware objects with managed metadata](guide/forms/signals/field-metadata#attaching-lifecycle-aware-objects-with-managed-metadata) + * * @publicApi 22.0 */ export function createManagedMetadataKey( @@ -284,6 +309,8 @@ export function createManagedMetadataKey( /** * Creates a {@link LimitSelectionKey}. * + * @see [Validation constraints](guide/forms/signals/custom-controls#validation-constraints) + * * @publicApi 22.0 */ export function createLimitSelectionKey(): LimitSelectionKey { @@ -293,6 +320,8 @@ export function createLimitSelectionKey(): LimitSelectionKey { /** * A {@link MetadataKey} representing whether the field is required. * + * @see [Required validation](guide/forms/signals/validation#required) + * * @category validation * @publicApi 22.0 */ @@ -306,6 +335,8 @@ export const REQUIRED: MetadataKey, boolean, boolean> = createMe * This indirection allows different keys to be used for different types of values with their * own reducers, such as {@link MIN_DATE} and {@link MIN_NUMBER}. * + * @see [Minimum and maximum validation](guide/forms/signals/validation#min-and-max) + * * @category validation * @publicApi 22.0 */ @@ -314,6 +345,8 @@ export const MIN: LimitSelectionKey = createLimitSelectionKey(); /** * A {@link MetadataKey} representing the minimum valid value of a date field. * + * @see [Minimum and maximum validation](guide/forms/signals/validation#min-and-max) + * * @category validation * @publicApi 22.0 */ @@ -322,6 +355,8 @@ export const MIN_DATE: LimitKey = createMetadataKey(MetadataReducer.max()) /** * A {@link MetadataKey} representing the minimum valid value of a number field. * + * @see [Minimum and maximum validation](guide/forms/signals/validation#min-and-max) + * * @category validation * @publicApi 22.0 */ @@ -333,6 +368,8 @@ export const MIN_NUMBER: LimitKey = createMetadataKey(MetadataReducer.ma * This indirection allows different keys to be used for different types of values with their * own reducers, such as {@link MAX_DATE} and {@link MAX_NUMBER}. * + * @see [Minimum and maximum validation](guide/forms/signals/validation#min-and-max) + * * @category validation * @publicApi 22.0 */ @@ -341,6 +378,8 @@ export const MAX: LimitSelectionKey = createLimitSelectionKey(); /** * A {@link MetadataKey} representing the maximum valid value of a date field. * + * @see [Minimum and maximum validation](guide/forms/signals/validation#min-and-max) + * * @category validation * @publicApi 22.0 */ @@ -349,6 +388,8 @@ export const MAX_DATE: LimitKey = createMetadataKey(MetadataReducer.min()) /** * A {@link MetadataKey} representing the maximum valid value of a number field. * + * @see [Minimum and maximum validation](guide/forms/signals/validation#min-and-max) + * * @category validation * @publicApi 22.0 */ @@ -357,6 +398,8 @@ export const MAX_NUMBER: LimitKey = createMetadataKey(MetadataReducer.mi /** * A {@link MetadataKey} representing the min length of the field. * + * @see [Minimum and maximum length validation](guide/forms/signals/validation#minlength-and-maxlength) + * * @category validation * @publicApi 22.0 */ @@ -365,6 +408,8 @@ export const MIN_LENGTH: LimitKey = createMetadataKey(MetadataReducer.ma /** * A {@link MetadataKey} representing the max length of the field. * + * @see [Minimum and maximum length validation](guide/forms/signals/validation#minlength-and-maxlength) + * * @category validation * @publicApi 22.0 */ @@ -373,6 +418,8 @@ export const MAX_LENGTH: LimitKey = createMetadataKey(MetadataReducer.mi /** * A {@link MetadataKey} representing the patterns the field must match. * + * @see [Pattern validation](guide/forms/signals/validation#pattern) + * * @category validation * @publicApi 22.0 */ diff --git a/packages/forms/signals/src/api/rules/readonly.ts b/packages/forms/signals/src/api/rules/readonly.ts index e1f653009a5..b390f13b38d 100644 --- a/packages/forms/signals/src/api/rules/readonly.ts +++ b/packages/forms/signals/src/api/rules/readonly.ts @@ -20,6 +20,9 @@ import type {LogicFn, PathKind, SchemaPath, SchemaPathRules} from '../types'; * @template TValue The type of value stored in the field the logic is bound to. * @template TPathKind The kind of path the logic is bound to (a root path, child path, or item of an array) * + * @see [Readonly fields](guide/forms/signals/form-logic#display-uneditable-fields-with-readonly) + * @see [Availability state](guide/forms/signals/field-state-management#availability-state) + * * @category logic * @publicApi 22.0 */ diff --git a/packages/forms/signals/src/api/rules/validation/standard_schema.ts b/packages/forms/signals/src/api/rules/validation/standard_schema.ts index b1466c8be9c..cc158fbb09f 100644 --- a/packages/forms/signals/src/api/rules/validation/standard_schema.ts +++ b/packages/forms/signals/src/api/rules/validation/standard_schema.ts @@ -26,6 +26,8 @@ import { * i.e. `{[key: string]: unknown}`. It allows specific string keys to pass through, even if their * value is `unknown`, e.g. `{key: unknown}`. * + * @see [Integration with schema validation libraries](guide/forms/signals/validation#integration-with-schema-validation-libraries) + * * @publicApi 22.0 */ export type RemoveStringIndexUnknownKey = string extends K @@ -39,6 +41,8 @@ export type RemoveStringIndexUnknownKey = string extends K * We use this on the `TSchema` type in `validateStandardSchema` in order to accommodate Zod's * `looseObject` which includes `{[key: string]: unknown}` as part of the type. * + * @see [Integration with schema validation libraries](guide/forms/signals/validation#integration-with-schema-validation-libraries) + * * @publicApi 22.0 */ export type IgnoreUnknownProperties = @@ -125,6 +129,8 @@ export function validateStandardSchema = T & {fieldTree: ReadonlyFieldTree}; @@ -30,6 +32,8 @@ export type WithFieldTree = T & {fieldTree: ReadonlyFieldTree}; * A type that allows the given type `T` to optionally have a `field` property. * @template T The type to optionally add a `field` to. * + * @see [Validation errors](guide/forms/signals/validation#validation-errors) + * * @publicApi 22.0 */ export type WithOptionalFieldTree = Omit & { @@ -40,6 +44,8 @@ export type WithOptionalFieldTree = Omit & { * A type that ensures the given type `T` does not have a `field` property. * @template T The type to remove the `field` from. * + * @see [Validation errors](guide/forms/signals/validation#validation-errors) + * * @publicApi 22.0 */ export type WithoutFieldTree = T & {fieldTree: never}; @@ -48,6 +54,8 @@ export type WithoutFieldTree = T & {fieldTree: never}; * Create a required error associated with the target field * @param options The validation error options * + * @see [Required validation](guide/forms/signals/validation#required) + * * @publicApi 22.0 */ export function requiredError( @@ -57,6 +65,8 @@ export function requiredError( * Create a required error * @param options The optional validation error options * + * @see [Required validation](guide/forms/signals/validation#required) + * * @category validation * @publicApi 22.0 */ @@ -74,6 +84,8 @@ export function requiredError( * @param min The min value constraint * @param options The validation error options * + * @see [Minimum and maximum validation](guide/forms/signals/validation#min-and-max) + * * @category validation * @publicApi 22.0 */ @@ -86,6 +98,8 @@ export function minError( * @param min The min value constraint * @param options The optional validation error options * + * @see [Minimum and maximum validation](guide/forms/signals/validation#min-and-max) + * * @category validation * @publicApi 22.0 */ @@ -105,6 +119,8 @@ export function minError( * @param minDate The min date constraint * @param options The validation error options * + * @see [Minimum and maximum validation](guide/forms/signals/validation#min-and-max) + * * @category validation * @publicApi 22.0 */ @@ -117,6 +133,8 @@ export function minDateError( * @param minDate The min date constraint * @param options The optional validation error options * + * @see [Minimum and maximum validation](guide/forms/signals/validation#min-and-max) + * * @category validation * @publicApi 22.0 */ @@ -136,6 +154,8 @@ export function minDateError( * @param max The max value constraint * @param options The validation error options * + * @see [Minimum and maximum validation](guide/forms/signals/validation#min-and-max) + * * @category validation * @publicApi 22.0 */ @@ -148,6 +168,8 @@ export function maxError( * @param max The max value constraint * @param options The optional validation error options * + * @see [Minimum and maximum validation](guide/forms/signals/validation#min-and-max) + * * @category validation * @publicApi 22.0 */ @@ -167,6 +189,8 @@ export function maxError( * @param maxDate The max date constraint * @param options The validation error options * + * @see [Minimum and maximum validation](guide/forms/signals/validation#min-and-max) + * * @category validation * @publicApi 22.0 */ @@ -179,6 +203,8 @@ export function maxDateError( * @param maxDate The max date constraint * @param options The optional validation error options * + * @see [Minimum and maximum validation](guide/forms/signals/validation#min-and-max) + * * @category validation * @publicApi 22.0 */ @@ -198,6 +224,8 @@ export function maxDateError( * @param minLength The minLength constraint * @param options The validation error options * + * @see [Minimum and maximum length validation](guide/forms/signals/validation#minlength-and-maxlength) + * * @category validation * @publicApi 22.0 */ @@ -210,6 +238,8 @@ export function minLengthError( * @param minLength The minLength constraint * @param options The optional validation error options * + * @see [Minimum and maximum length validation](guide/forms/signals/validation#minlength-and-maxlength) + * * @category validation * @publicApi 22.0 */ @@ -229,6 +259,8 @@ export function minLengthError( * @param maxLength The maxLength constraint * @param options The validation error options * + * @see [Minimum and maximum length validation](guide/forms/signals/validation#minlength-and-maxlength) + * * @category validation * @publicApi 22.0 */ @@ -241,6 +273,8 @@ export function maxLengthError( * @param maxLength The maxLength constraint * @param options The optional validation error options * + * @see [Minimum and maximum length validation](guide/forms/signals/validation#minlength-and-maxlength) + * * @category validation * @publicApi 22.0 */ @@ -260,6 +294,8 @@ export function maxLengthError( * @param pattern The violated pattern * @param options The validation error options * + * @see [Pattern validation](guide/forms/signals/validation#pattern) + * * @category validation * @publicApi 22.0 */ @@ -272,6 +308,8 @@ export function patternError( * @param pattern The violated pattern * @param options The optional validation error options * + * @see [Pattern validation](guide/forms/signals/validation#pattern) + * * @category validation * @publicApi 22.0 */ @@ -290,6 +328,8 @@ export function patternError( * Create an email format error associated with the target field * @param options The validation error options * + * @see [Email validation](guide/forms/signals/validation#email) + * * @category validation * @publicApi 22.0 */ @@ -298,6 +338,8 @@ export function emailError(options: WithFieldTree): Emai * Create an email format error * @param options The optional validation error options * + * @see [Email validation](guide/forms/signals/validation#email) + * * @category validation * @publicApi 22.0 */ @@ -383,6 +425,8 @@ export declare namespace ValidationError { * Internal version of `NgValidationError`, we create this separately so we can change its type on * the exported version to a type union of the possible sub-classes. * + * @see [Signal Form Validation Errors](guide/forms/signals/validation#validation-errors) + * * @publicApi 22.0 */ export abstract class BaseNgValidationError implements ValidationError { @@ -408,6 +452,8 @@ export abstract class BaseNgValidationError implements ValidationError { /** * An error used to indicate that a required field is empty. * + * @see [Required validation](guide/forms/signals/validation#required) + * * @category validation * @publicApi 22.0 */ @@ -418,6 +464,8 @@ export class RequiredValidationError extends BaseNgValidationError { /** * An error used to indicate that a value is lower than the minimum allowed. * + * @see [Minimum and maximum validation](guide/forms/signals/validation#min-and-max) + * * @category validation * @publicApi 22.0 */ @@ -435,6 +483,8 @@ export class MinValidationError extends BaseNgValidationError { /** * An error used to indicate that a date value is earlier than the minimum allowed. * + * @see [Minimum and maximum validation](guide/forms/signals/validation#min-and-max) + * * @category validation * @publicApi 22.0 */ @@ -452,6 +502,8 @@ export class MinDateValidationError extends BaseNgValidationError { /** * An error used to indicate that a value is higher than the maximum allowed. * + * @see [Minimum and maximum validation](guide/forms/signals/validation#min-and-max) + * * @category validation * @publicApi 22.0 */ @@ -469,6 +521,8 @@ export class MaxValidationError extends BaseNgValidationError { /** * An error used to indicate that a date value is later than the maximum allowed. * + * @see [Minimum and maximum validation](guide/forms/signals/validation#min-and-max) + * * @category validation * @publicApi 22.0 */ @@ -486,6 +540,8 @@ export class MaxDateValidationError extends BaseNgValidationError { /** * An error used to indicate that a value is shorter than the minimum allowed length. * + * @see [Minimum and maximum length validation](guide/forms/signals/validation#minlength-and-maxlength) + * * @category validation * @publicApi 22.0 */ @@ -503,6 +559,8 @@ export class MinLengthValidationError extends BaseNgValidationError { /** * An error used to indicate that a value is longer than the maximum allowed length. * + * @see [Minimum and maximum length validation](guide/forms/signals/validation#minlength-and-maxlength) + * * @category validation * @publicApi 22.0 */ @@ -520,6 +578,8 @@ export class MaxLengthValidationError extends BaseNgValidationError { /** * An error used to indicate that a value does not match the required pattern. * + * @see [Pattern validation](guide/forms/signals/validation#pattern) + * * @category validation * @publicApi 22.0 */ @@ -537,6 +597,8 @@ export class PatternValidationError extends BaseNgValidationError { /** * An error used to indicate that a value is not a valid email. * + * @see [Email validation](guide/forms/signals/validation#email) + * * @category validation * @publicApi 22.0 */ @@ -547,6 +609,8 @@ export class EmailValidationError extends BaseNgValidationError { /** * An error used to indicate that a value entered in a native input does not parse. * + * @see [Value transformation](guide/forms/signals/custom-controls#value-transformation) + * * @category validation * @publicApi 22.0 */ @@ -576,6 +640,8 @@ export class NativeInputParseError extends BaseNgValidationError { * } * ``` * + * @see [Signal Form Validation Errors](guide/forms/signals/validation#validation-errors) + * * @category validation * @publicApi 22.0 */ diff --git a/packages/forms/signals/src/api/structure.ts b/packages/forms/signals/src/api/structure.ts index 63d85595f84..65c823920e8 100644 --- a/packages/forms/signals/src/api/structure.ts +++ b/packages/forms/signals/src/api/structure.ts @@ -43,6 +43,8 @@ import type { /** * Options that may be specified when creating a form. * + * @see [Signal Forms setup](guide/forms/signals/overview#setup) + * * @category structure * @publicApi 22.0 */ @@ -96,6 +98,8 @@ export interface FormOptions { * @return A `FieldTree` representing a form around the data model. * @template TModel The type of the data model. * + * @see [Creating models](guide/forms/signals/models#creating-models) + * * @category structure * @publicApi 22.0 */ @@ -143,6 +147,8 @@ export function form(model: WritableSignal): FieldTree; * @return A `FieldTree` representing a form around the data model * @template TValue The type of the data model. * + * @see [Creating models](guide/forms/signals/models#creating-models) + * * @category structure * @publicApi 22.0 */ @@ -191,6 +197,8 @@ export function form( * @return A `FieldTree` representing a form around the data model. * @template TModel The type of the data model. * + * @see [Creating models](guide/forms/signals/models#creating-models) + * * @category structure * @publicApi 22.0 */ @@ -258,6 +266,8 @@ export function form(...args: any[]): FieldTree { * element of the array. * @template TValue The data type of the item field to apply the schema to. * + * @see [Array items with applyEach](guide/forms/signals/schemas#array-items-with-applyeach) + * * @category structure * @publicApi 22.0 */ @@ -297,6 +307,8 @@ export function applyEach( * @param schema The schema to apply to the property * @template TValue The data type of the field to apply the schema to. * + * @see [Using the schema with apply](guide/forms/signals/schemas#using-the-schema-with-apply) + * * @category structure * @publicApi 22.0 */ @@ -318,6 +330,8 @@ export function apply( * @param schema The schema to apply to the field when the `logic` function returns `true`. * @template TValue The data type of the field to apply the schema to. * + * @see [Conditional schemas with applyWhen](guide/forms/signals/schemas#conditional-schemas-with-applywhen) + * * @category structure * @publicApi 22.0 */ @@ -342,6 +356,8 @@ export function applyWhen( * @template TValue The data type of the field to apply the schema to. * @template TNarrowed The data type of the schema (a narrowed type of TValue). * + * @see [Type-narrowing with applyWhenValue](guide/forms/signals/schemas#type-narrowing-with-applywhenvalue) + * * @category structure * @publicApi 22.0 */ @@ -360,6 +376,8 @@ export function applyWhenValue( * @param schema The schema to apply to the field when `predicate` returns `true`. * @template TValue The data type of the field to apply the schema to. * + * @see [Type-narrowing with applyWhenValue](guide/forms/signals/schemas#type-narrowing-with-applywhenvalue) + * * @category structure * @publicApi 22.0 */ @@ -414,6 +432,8 @@ export function applyWhenValue( * @returns Whether the submission was successful. * @template TModel The data type of the field being submitted. * + * @see [Form submission](guide/forms/signals/form-submission) + * * @category submission * @publicApi 22.0 */ @@ -481,6 +501,8 @@ export async function submit( * @returns A schema object that implements the given logic. * @template TValue The value type of a `FieldTree` that this schema binds to. * + * @see [Create reusable schemas with schema](guide/forms/signals/schemas#create-reusable-schemas-with-schema) + * * @category structure * @publicApi 22.0 */ diff --git a/packages/forms/signals/src/api/transformed_value.ts b/packages/forms/signals/src/api/transformed_value.ts index daa5fd9251c..5249d3380b5 100644 --- a/packages/forms/signals/src/api/transformed_value.ts +++ b/packages/forms/signals/src/api/transformed_value.ts @@ -35,6 +35,8 @@ export interface ParseResult { /** * Options for `transformedValue`. * + * @see [Value transformation](guide/forms/signals/custom-controls#value-transformation) + * * @publicApi 22.0 */ export interface TransformedValueOptions { @@ -57,6 +59,8 @@ export interface TransformedValueOptions { * A writable signal representing a "raw" UI value that is synchronized with a model signal * via parse/format transformations. * + * @see [Value transformation](guide/forms/signals/custom-controls#value-transformation) + * * @category control * @publicApi 22.0 */ @@ -110,6 +114,10 @@ export interface TransformedValueSignal extends WritableSignal { * }); * } * ``` + * + * @see [Value transformation](guide/forms/signals/custom-controls#value-transformation) + * + */ export function transformedValue( value: ModelSignal, diff --git a/packages/forms/signals/src/api/types.ts b/packages/forms/signals/src/api/types.ts index 33fdf7aa1bf..d30d6be019c 100644 --- a/packages/forms/signals/src/api/types.ts +++ b/packages/forms/signals/src/api/types.ts @@ -19,6 +19,8 @@ declare const ɵɵTYPE: unique symbol; /** * Options that can be specified when submitting a form. * + * @see [Form submission](guide/forms/signals/form-submission) + * * @publicApi 22.0 */ export interface FormSubmitOptions { @@ -60,6 +62,8 @@ export interface FormSubmitOptions { /** * Options for the `markAsTouched` method. * + * @see [Touched state](guide/forms/signals/field-state-management#touched-state) + * * @publicApi 22.0 */ export interface MarkAsTouchedOptions { @@ -115,6 +119,8 @@ export declare namespace PathKind { /** * A reason for a field's disablement. * + * @see [Disabled reasons](guide/forms/signals/form-logic#disabled-reasons) + * * @category logic * @publicApi 22.0 */ @@ -128,6 +134,8 @@ export interface DisabledReason { /** * The absence of an error which indicates a successful validation result. * + * @see [Validation basics](guide/forms/signals/validation#validation-basics) + * * @category types * @publicApi 22.0 */ @@ -144,6 +152,8 @@ export type ValidationSuccess = null | undefined | void; * * @template E the type of error (defaults to {@link ValidationError}). * + * @see [Validation errors](guide/forms/signals/validation#validation-errors) + * * @category types * @publicApi 22.0 */ @@ -161,6 +171,8 @@ export type TreeValidationResult< * * @template E the type of error (defaults to {@link ValidationError}). * + * @see [Validation errors](guide/forms/signals/validation#validation-errors) + * * @category types * @publicApi 22.0 */ @@ -177,6 +189,8 @@ export type ValidationResult = * * @template E the type of error (defaults to {@link ValidationError}). * + * @see [Async validation](guide/forms/signals/validation#async-validation) + * * @category types * @publicApi 22.0 */ @@ -190,6 +204,8 @@ export type AsyncValidationResult = * @template TValue The type of the value stored in the field. * @template TKey The type of the property key which this field resides under in its parent. * + * @see [Accessing field state](guide/forms/signals/field-state-management#accessing-field-state) + * * @category types * @publicApi 22.0 */ @@ -308,6 +324,7 @@ export type MaybeFieldTree< * @template TValue The type of the data which the field is wrapped around. * @template TKey The type of the property key which this field resides under in its parent. * + * * @category structure * @publicApi 22.0 */ @@ -493,6 +510,8 @@ export interface ReadonlyFieldState = @@ -737,6 +774,8 @@ export type SchemaPathTree = * @template TValue The type of the data which the field is wrapped around. * @template TPathKind The kind of path (root field, child field, or item of an array) * + * @see [Schemas and schema composability](guide/forms/signals/schemas) + * * @publicApi 22.0 */ export type MaybeSchemaPathTree = @@ -781,6 +820,8 @@ export type MaybeSchemaPathTree = { * @template TModel Data type. * @template TPathKind The kind of path this schema function can be bound to. * + * @see [Schemas and schema composability](guide/forms/signals/schemas) + * * @category types * @publicApi 22.0 */ @@ -819,6 +862,8 @@ export type SchemaFn = ( * @template TModel The type of data stored in the form that this schema function is attached to. * @template TPathKind The kind of path this schema function can be bound to. * + * @see [Schemas and schema composability](guide/forms/signals/schemas) + * * @category types * @publicApi 22.0 */ @@ -848,6 +893,8 @@ export type LogicFn * @template TValue The type of value stored in the field being validated * @template TPathKind The kind of path being validated (root field, child field, or item of an array) * + * @see [Custom validation rules](guide/forms/signals/validation#using-validate) + * * @category validation * @publicApi 22.0 */ @@ -864,6 +911,8 @@ export type FieldValidator = * @template TValue The type of value stored in the field being validated * @template TPathKind The kind of path being validated (root field, child field, or item of an array) * + * @see [Custom validation rules](guide/forms/signals/validation#using-validatetree) + * * @category types * @publicApi 22.0 */ @@ -894,6 +943,8 @@ export type Validator = Logi * Provides access to the state of the current field as well as functions that can be used to look * up state of other fields based on a `FieldPath`. * + * @see [Understanding the field context](guide/forms/signals/cross-field-logic#understanding-the-field-context) + * * @category types * @publicApi 22.0 */ @@ -909,6 +960,8 @@ export type FieldContext< /** * The base field context that is available for all fields. * + * @see [Understanding the field context](guide/forms/signals/cross-field-logic#understanding-the-field-context) + * * @publicApi 22.0 */ export interface RootFieldContext { @@ -981,6 +1034,8 @@ export type ItemType = T extends ReadonlyArray ? T[number * @template TValue The type of value stored in the field. * @template TPathKind The kind of path the debouncer is applied to (root field, child field, or item of an array). * + * @see [Debouncing form updates](guide/forms/signals/form-logic#delay-input-operations-with-debounce) + * * @publicApi 22.0 */ export type Debouncer = ( diff --git a/packages/forms/signals/src/directive/form_field.ts b/packages/forms/signals/src/directive/form_field.ts index 1ad94637242..a0fb42edfa6 100644 --- a/packages/forms/signals/src/directive/form_field.ts +++ b/packages/forms/signals/src/directive/form_field.ts @@ -71,6 +71,8 @@ export interface FormFieldBindingOptions { /** * Lightweight DI token provided by the {@link FormField} directive. * + * @see [Custom form controls](guide/forms/signals/custom-controls) + * * @category control * @publicApi 22.0 */ @@ -95,6 +97,9 @@ export const FORM_FIELD = new InjectionToken>( * forms. * * @category control + * + * @see [How the FormField directive works](guide/forms/signals/custom-controls#how-the-formfield-directive-works) + * * @publicApi 22.0 */ @Directive({ diff --git a/packages/forms/signals/src/directive/form_root.ts b/packages/forms/signals/src/directive/form_root.ts index aec667aa260..6e759b7b8c5 100644 --- a/packages/forms/signals/src/directive/form_root.ts +++ b/packages/forms/signals/src/directive/form_root.ts @@ -28,6 +28,8 @@ import {FieldNode} from '../field/node'; * * ``` * + * @see [Setting up form submission with FormRoot](guide/forms/signals/form-submission#setting-up-form-submission-with-formroot) + * * @publicApi 22.0 */ @Directive({ diff --git a/packages/forms/signals/src/webmcp/registration.ts b/packages/forms/signals/src/webmcp/registration.ts index 8e74b7cf5ec..6ba653d8072 100644 --- a/packages/forms/signals/src/webmcp/registration.ts +++ b/packages/forms/signals/src/webmcp/registration.ts @@ -137,6 +137,8 @@ function inferSchemaFromFieldNode(node: FieldNode): JsonSchemaForInference | und * Creates a provider that configures all signal forms with `experimentalWebMcpTool` * to be registered as WebMCP tools. * + * @see [Implicit tools in Signal Forms](ai/webmcp#implicit-tools-in-signal-forms) + * * @experimental */ export function provideExperimentalWebMcpForms(): EnvironmentProviders {