diff --git a/packages/forms/signals/src/api/async.ts b/packages/forms/signals/src/api/async.ts index c2ae2e3eaeb..3648b0ec8f6 100644 --- a/packages/forms/signals/src/api/async.ts +++ b/packages/forms/signals/src/api/async.ts @@ -45,6 +45,7 @@ export type MapToErrorsFn { @@ -137,6 +139,7 @@ export interface HttpValidatorOptions( @@ -190,6 +193,7 @@ export function validateAsync( diff --git a/packages/forms/signals/src/api/control.ts b/packages/forms/signals/src/api/control.ts index 76798ff11c1..cb68c0c81ae 100644 --- a/packages/forms/signals/src/api/control.ts +++ b/packages/forms/signals/src/api/control.ts @@ -13,6 +13,7 @@ import {ValidationError, type WithOptionalField} from './validation_errors'; /** * The base set of properties shared by all form control contracts. * + * @category control * @experimental 21.0.0 */ export interface FormUiControl { @@ -112,6 +113,7 @@ export interface FormUiControl { * * @template TValue The type of `Field` that the implementing component can edit. * + * @category control * @experimental 21.0.0 */ export interface FormValueControl extends FormUiControl { @@ -140,6 +142,7 @@ 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 * `Control` directive. * + * @category control * @experimental 21.0.0 */ export interface FormCheckboxControl extends FormUiControl { diff --git a/packages/forms/signals/src/api/control_directive.ts b/packages/forms/signals/src/api/control_directive.ts index 3afba133b0c..6e3e842118b 100644 --- a/packages/forms/signals/src/api/control_directive.ts +++ b/packages/forms/signals/src/api/control_directive.ts @@ -56,6 +56,7 @@ import type {Field} from './types'; * forms `NgControl`. This is provided to improve interoperability with controls designed to work * with reactive forms. It should not be used by controls written for signal forms. * + * @category control * @experimental 21.0.0 */ @Directive({ diff --git a/packages/forms/signals/src/api/logic.ts b/packages/forms/signals/src/api/logic.ts index 86c255c7f16..29a5d743ae7 100644 --- a/packages/forms/signals/src/api/logic.ts +++ b/packages/forms/signals/src/api/logic.ts @@ -29,6 +29,7 @@ import type { * @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) * + * @category logic * @experimental 21.0.0 */ export function disabled( @@ -61,6 +62,7 @@ export function disabled( * @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) * + * @category logic * @experimental 21.0.0 */ export function readonly( @@ -90,6 +92,7 @@ export function readonly( * @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) * + * @category logic * @experimental 21.0.0 */ export function hidden( @@ -110,6 +113,7 @@ export function hidden( * @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) * + * @category logic * @experimental 21.0.0 */ export function validate( @@ -133,6 +137,7 @@ export function validate( * @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) * + * @category logic * @experimental 21.0.0 */ export function validateTree( @@ -157,6 +162,7 @@ export function validateTree * @template TPropItem The type of value the property aggregates over. * @template TPathKind The kind of path the logic is bound to (a root path, child path, or item of an array) * + * @category logic * @experimental 21.0.0 */ export function aggregateProperty( @@ -178,6 +184,7 @@ export function aggregateProperty( @@ -194,6 +201,7 @@ export function property( diff --git a/packages/forms/signals/src/api/property.ts b/packages/forms/signals/src/api/property.ts index 2641facace7..0a414b4bb62 100644 --- a/packages/forms/signals/src/api/property.ts +++ b/packages/forms/signals/src/api/property.ts @@ -10,6 +10,7 @@ * Represents a property that may be defined on a field when it is created using a `property` rule * in the schema. A particular `Property` can only be defined on a particular field **once**. * + * @category logic * @experimental 21.0.0 */ export class Property { @@ -143,6 +144,7 @@ export function andProperty(): AggregateProperty { /** * An aggregate property representing whether the field is required. * + * @category validation * @experimental 21.0.0 */ export const REQUIRED: AggregateProperty = orProperty(); @@ -150,6 +152,7 @@ export const REQUIRED: AggregateProperty = orProperty(); /** * An aggregate property representing the min value of the field. * + * @category validation * @experimental 21.0.0 */ export const MIN: AggregateProperty = maxProperty(); @@ -157,6 +160,7 @@ export const MIN: AggregateProperty = ma /** * An aggregate property representing the max value of the field. * + * @category validation * @experimental 21.0.0 */ export const MAX: AggregateProperty = minProperty(); @@ -164,6 +168,7 @@ export const MAX: AggregateProperty = mi /** * An aggregate property representing the min length of the field. * + * @category validation * @experimental 21.0.0 */ export const MIN_LENGTH: AggregateProperty = maxProperty(); @@ -171,6 +176,7 @@ export const MIN_LENGTH: AggregateProperty = minProperty(); @@ -178,6 +184,7 @@ export const MAX_LENGTH: AggregateProperty = listProperty(); diff --git a/packages/forms/signals/src/api/structure.ts b/packages/forms/signals/src/api/structure.ts index 0d0e632e7b8..45a905db48e 100644 --- a/packages/forms/signals/src/api/structure.ts +++ b/packages/forms/signals/src/api/structure.ts @@ -31,6 +31,7 @@ import {ValidationError, WithOptionalField} from './validation_errors'; /** * Options that may be specified when creating a form. * + * @category structure * @experimental 21.0.0 */ export interface FormOptions { @@ -94,6 +95,7 @@ function normalizeFormArgs( * @return A `Field` representing a form around the data model. * @template TValue The type of the data model. * + * @category structure * @experimental 21.0.0 */ export function form(model: WritableSignal): Field; @@ -140,6 +142,7 @@ export function form(model: WritableSignal): Field; * @return A `Field` representing a form around the data model * @template TValue The type of the data model. * + * @category structure * @experimental 21.0.0 */ export function form( @@ -187,6 +190,7 @@ export function form( * @return A `Field` representing a form around the data model. * @template TValue The type of the data model. * + * @category structure * @experimental 21.0.0 */ export function form( @@ -242,6 +246,7 @@ export function form(...args: any[]): Field { * element of the array. * @template TValue The data type of the item field to apply the schema to. * + * @category structure * @experimental 21.0.0 */ export function applyEach( @@ -272,6 +277,7 @@ 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. * + * @category structure * @experimental 21.0.0 */ export function apply( @@ -292,6 +298,7 @@ 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. * + * @category structure * @experimental 21.0.0 */ export function applyWhen( @@ -315,6 +322,7 @@ 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). * + * @category structure * @experimental 21.0.0 */ export function applyWhenValue( @@ -332,6 +340,7 @@ 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. * + * @category structure * @experimental 21.0.0 */ export function applyWhenValue( @@ -379,6 +388,7 @@ export function applyWhenValue( * errors. * @template TValue The data type of the field being submitted. * + * @category submission * @experimental 21.0.0 */ export async function submit( @@ -437,6 +447,7 @@ function setServerErrors( * @returns A schema object that implements the given logic. * @template TValue The value type of a `Field` that this schema binds to. * + * @category structure * @experimental 21.0.0 */ export function schema(fn: SchemaFn): Schema { diff --git a/packages/forms/signals/src/api/types.ts b/packages/forms/signals/src/api/types.ts index 722dad2246c..f198a43ec44 100644 --- a/packages/forms/signals/src/api/types.ts +++ b/packages/forms/signals/src/api/types.ts @@ -70,6 +70,7 @@ export type PathKind = PathKind.Root | PathKind.Child | PathKind.Item; /** * A status indicating whether a field is unsubmitted, submitted, or currently submitting. * + * @category submission * @experimental 21.0.0 */ export type SubmittedStatus = 'unsubmitted' | 'submitted' | 'submitting'; @@ -77,6 +78,7 @@ export type SubmittedStatus = 'unsubmitted' | 'submitted' | 'submitting'; /** * A reason for a field's disablement. * + * @category logic * @experimental 21.0.0 */ export interface DisabledReason { @@ -89,6 +91,7 @@ export interface DisabledReason { /** * The absence of an error which indicates a successful validation result. * + * @category validation * @experimental 21.0.0 */ export type ValidationSuccess = null | undefined | void; @@ -104,6 +107,7 @@ export type ValidationSuccess = null | undefined | void; * * @template E the type of error (defaults to {@link ValidationError}). * + * @category validation * @experimental 21.0.0 */ export type FieldValidationResult = @@ -121,6 +125,7 @@ export type FieldValidationResult = * * @template E the type of error (defaults to {@link ValidationError}). * + * @category validation * @experimental 21.0.0 */ export type TreeValidationResult = @@ -137,6 +142,7 @@ export type TreeValidationResult = * * @template E the type of error (defaults to {@link ValidationError}). * + * @category validation * @experimental 21.0.0 */ export type ValidationResult = @@ -152,6 +158,7 @@ export type ValidationResult = * * @template E the type of error (defaults to {@link ValidationError}). * + * @category validation * @experimental 21.0.0 */ export type AsyncValidationResult = @@ -168,6 +175,7 @@ export type AsyncValidationResult = * @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 * @experimental 21.0.0 */ export type Field = (() => FieldState< @@ -226,6 +234,7 @@ export type MaybeField = * Contains all of the state (e.g. value, statuses, etc.) associated with a `Field`, exposed as * signals. * + * @category structure * @experimental 21.0.0 */ export interface FieldState { @@ -367,6 +376,7 @@ export interface FieldState = { @@ -398,6 +408,7 @@ export type MaybeFieldPath = * * @template TValue The type of data stored in the form that this schema is attached to. * + * @category structure * @experimental 21.0.0 */ export type Schema = { @@ -410,6 +421,7 @@ export type Schema = { * @template TValue 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. * + * @category structure * @experimental 21.0.0 */ export type SchemaFn = ( @@ -422,6 +434,7 @@ export type SchemaFn = ( * @template TValue 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. * + * @category structure * @experimental 21.0.0 */ export type SchemaOrSchemaFn = @@ -436,6 +449,7 @@ export type SchemaOrSchemaFn * @template TReturn The type of the result returned by the logic function. * @template TPathKind The kind of path the logic is applied to (root field, child field, or item of an array) * + * @category structure * @experimental 21.0.0 */ export type LogicFn = ( @@ -449,6 +463,7 @@ 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) * + * @category validation * @experimental 21.0.0 */ export type FieldValidator = LogicFn< @@ -464,6 +479,7 @@ 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) * + * @category validation * @experimental 21.0.0 */ export type TreeValidator = LogicFn< @@ -480,6 +496,7 @@ export type TreeValidator = * @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) * + * @category validation * @experimental 21.0.0 */ export type Validator = LogicFn< @@ -492,6 +509,7 @@ 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`. * + * @category structure * @experimental 21.0.0 */ export type FieldContext< @@ -526,6 +544,7 @@ export interface RootFieldContext { /** * Field context that is available for all fields that are a child of another field. * + * @category structure * @experimental 21.0.0 */ export interface ChildFieldContext extends RootFieldContext { diff --git a/packages/forms/signals/src/api/validation_errors.ts b/packages/forms/signals/src/api/validation_errors.ts index 3e6b54798bc..cf29c6a2a2e 100644 --- a/packages/forms/signals/src/api/validation_errors.ts +++ b/packages/forms/signals/src/api/validation_errors.ts @@ -52,6 +52,7 @@ export function requiredError(options: WithField): Requi * Create a required error * @param options The optional validation error options * + * @category validation * @experimental 21.0.0 */ export function requiredError( @@ -68,6 +69,7 @@ export function requiredError( * @param min The min value constraint * @param options The validation error options * + * @category validation * @experimental 21.0.0 */ export function minError( @@ -79,6 +81,7 @@ export function minError( * @param min The min value constraint * @param options The optional validation error options * + * @category validation * @experimental 21.0.0 */ export function minError( @@ -97,6 +100,7 @@ export function minError( * @param max The max value constraint * @param options The validation error options * + * @category validation * @experimental 21.0.0 */ export function maxError( @@ -108,6 +112,7 @@ export function maxError( * @param max The max value constraint * @param options The optional validation error options * + * @category validation * @experimental 21.0.0 */ export function maxError( @@ -126,6 +131,7 @@ export function maxError( * @param minLength The minLength constraint * @param options The validation error options * + * @category validation * @experimental 21.0.0 */ export function minLengthError( @@ -137,6 +143,7 @@ export function minLengthError( * @param minLength The minLength constraint * @param options The optional validation error options * + * @category validation * @experimental 21.0.0 */ export function minLengthError( @@ -155,6 +162,7 @@ export function minLengthError( * @param maxLength The maxLength constraint * @param options The validation error options * + * @category validation * @experimental 21.0.0 */ export function maxLengthError( @@ -166,6 +174,7 @@ export function maxLengthError( * @param maxLength The maxLength constraint * @param options The optional validation error options * + * @category validation * @experimental 21.0.0 */ export function maxLengthError( @@ -184,6 +193,7 @@ export function maxLengthError( * @param pattern The violated pattern * @param options The validation error options * + * @category validation * @experimental 21.0.0 */ export function patternError( @@ -195,6 +205,7 @@ export function patternError( * @param pattern The violated pattern * @param options The optional validation error options * + * @category validation * @experimental 21.0.0 */ export function patternError( @@ -212,6 +223,7 @@ export function patternError( * Create an email format error associated with the target field * @param options The validation error options * + * @category validation * @experimental 21.0.0 */ export function emailError(options: WithField): EmailValidationError; @@ -219,6 +231,7 @@ export function emailError(options: WithField): EmailVal * Create an email format error * @param options The optional validation error options * + * @category validation * @experimental 21.0.0 */ export function emailError(options?: ValidationErrorOptions): WithoutField; @@ -233,6 +246,7 @@ export function emailError( * @param issue The standard schema issue * @param options The validation error options * + * @category validation * @experimental 21.0.0 */ export function standardSchemaError( @@ -244,6 +258,7 @@ export function standardSchemaError( * @param issue The standard schema issue * @param options The optional validation error options * + * @category validation * @experimental 21.0.0 */ export function standardSchemaError( @@ -261,6 +276,7 @@ export function standardSchemaError( * Create a custom error associated with the target field * @param obj The object to create an error from * + * @category validation * @experimental 21.0.0 */ export function customError>( @@ -270,6 +286,7 @@ export function customError>( * Create a custom error * @param obj The object to create an error from * + * @category validation * @experimental 21.0.0 */ export function customError>( @@ -286,6 +303,7 @@ export function customError>( * * Use the creation functions to create an instance (e.g. `requiredError`, `minError`, etc.). * + * @category validation * @experimental 21.0.0 */ export interface ValidationError { @@ -300,6 +318,7 @@ export interface ValidationError { /** * A custom error that may contain additional properties * + * @category validation * @experimental 21.0.0 */ export class CustomValidationError implements ValidationError { @@ -356,6 +375,7 @@ abstract class _NgValidationError implements ValidationError { /** * An error used to indicate that a required field is empty. * + * @category validation * @experimental 21.0.0 */ export class RequiredValidationError extends _NgValidationError { @@ -365,6 +385,7 @@ export class RequiredValidationError extends _NgValidationError { /** * An error used to indicate that a value is lower than the minimum allowed. * + * @category validation * @experimental 21.0.0 */ export class MinValidationError extends _NgValidationError { @@ -381,6 +402,7 @@ export class MinValidationError extends _NgValidationError { /** * An error used to indicate that a value is higher than the maximum allowed. * + * @category validation * @experimental 21.0.0 */ export class MaxValidationError extends _NgValidationError { @@ -397,6 +419,7 @@ export class MaxValidationError extends _NgValidationError { /** * An error used to indicate that a value is shorter than the minimum allowed length. * + * @category validation * @experimental 21.0.0 */ export class MinLengthValidationError extends _NgValidationError { @@ -413,6 +436,7 @@ export class MinLengthValidationError extends _NgValidationError { /** * An error used to indicate that a value is longer than the maximum allowed length. * + * @category validation * @experimental 21.0.0 */ export class MaxLengthValidationError extends _NgValidationError { @@ -429,6 +453,7 @@ export class MaxLengthValidationError extends _NgValidationError { /** * An error used to indicate that a value does not match the required pattern. * + * @category validation * @experimental 21.0.0 */ export class PatternValidationError extends _NgValidationError { @@ -445,6 +470,7 @@ export class PatternValidationError extends _NgValidationError { /** * An error used to indicate that a value is not a valid email. * + * @category validation * @experimental 21.0.0 */ export class EmailValidationError extends _NgValidationError { @@ -454,6 +480,7 @@ export class EmailValidationError extends _NgValidationError { /** * An error used to indicate an issue validating against a standard schema. * + * @category validation * @experimental 21.0.0 */ export class StandardSchemaValidationError extends _NgValidationError { @@ -489,6 +516,7 @@ export class StandardSchemaValidationError extends _NgValidationError { * } * ``` * + * @category validation * @experimental 21.0.0 */ export const NgValidationError: abstract new () => NgValidationError = _NgValidationError as any; diff --git a/packages/forms/signals/src/api/validators/email.ts b/packages/forms/signals/src/api/validators/email.ts index acf53201193..0f8e93f64a1 100644 --- a/packages/forms/signals/src/api/validators/email.ts +++ b/packages/forms/signals/src/api/validators/email.ts @@ -54,6 +54,7 @@ const EMAIL_REGEXP = * or a function that receives the `FieldContext` and returns custom validation error(s). * @template TPathKind The kind of path the logic is bound to (a root path, child path, or item of an array) * + * @category validation * @experimental 21.0.0 */ export function email( diff --git a/packages/forms/signals/src/api/validators/max.ts b/packages/forms/signals/src/api/validators/max.ts index f4d77af4afa..801668b6adb 100644 --- a/packages/forms/signals/src/api/validators/max.ts +++ b/packages/forms/signals/src/api/validators/max.ts @@ -26,6 +26,7 @@ import {BaseValidatorConfig, getOption, isEmpty} from './util'; * or a function that receives the `FieldContext` and returns custom validation error(s). * @template TPathKind The kind of path the logic is bound to (a root path, child path, or item of an array) * + * @category validation * @experimental 21.0.0 */ export function max( diff --git a/packages/forms/signals/src/api/validators/max_length.ts b/packages/forms/signals/src/api/validators/max_length.ts index 3867cc2626a..fcbe9051ee0 100644 --- a/packages/forms/signals/src/api/validators/max_length.ts +++ b/packages/forms/signals/src/api/validators/max_length.ts @@ -33,6 +33,7 @@ import { * @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) * + * @category validation * @experimental 21.0.0 */ export function maxLength< diff --git a/packages/forms/signals/src/api/validators/min.ts b/packages/forms/signals/src/api/validators/min.ts index bcc4d30c0be..fe99f380c19 100644 --- a/packages/forms/signals/src/api/validators/min.ts +++ b/packages/forms/signals/src/api/validators/min.ts @@ -26,6 +26,7 @@ import {BaseValidatorConfig, getOption, isEmpty} from './util'; * or a function that receives the `FieldContext` and returns custom validation error(s). * @template TPathKind The kind of path the logic is bound to (a root path, child path, or item of an array) * + * @category validation * @experimental 21.0.0 */ export function min( diff --git a/packages/forms/signals/src/api/validators/min_length.ts b/packages/forms/signals/src/api/validators/min_length.ts index 5c3cc6131d5..02342c66047 100644 --- a/packages/forms/signals/src/api/validators/min_length.ts +++ b/packages/forms/signals/src/api/validators/min_length.ts @@ -33,6 +33,7 @@ import { * @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) * + * @category validation * @experimental 21.0.0 */ export function minLength< diff --git a/packages/forms/signals/src/api/validators/pattern.ts b/packages/forms/signals/src/api/validators/pattern.ts index 40190298e75..50bcf8b26b3 100644 --- a/packages/forms/signals/src/api/validators/pattern.ts +++ b/packages/forms/signals/src/api/validators/pattern.ts @@ -25,6 +25,7 @@ import {BaseValidatorConfig, getOption, isEmpty} from './util'; * or a function that receives the `FieldContext` and returns custom validation error(s). * @template TPathKind The kind of path the logic is bound to (a root path, child path, or item of an array) * + * @category validation * @experimental 21.0.0 */ export function pattern( diff --git a/packages/forms/signals/src/api/validators/required.ts b/packages/forms/signals/src/api/validators/required.ts index 791975fe4b7..28cf72ba007 100644 --- a/packages/forms/signals/src/api/validators/required.ts +++ b/packages/forms/signals/src/api/validators/required.ts @@ -27,6 +27,7 @@ import {BaseValidatorConfig, getOption, isEmpty} from './util'; * @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) * + * @category validation * @experimental 21.0.0 */ export function required( diff --git a/packages/forms/signals/src/api/validators/standard_schema.ts b/packages/forms/signals/src/api/validators/standard_schema.ts index 9630f1983ee..4c488fbc1c6 100644 --- a/packages/forms/signals/src/api/validators/standard_schema.ts +++ b/packages/forms/signals/src/api/validators/standard_schema.ts @@ -52,6 +52,7 @@ export type IgnoreUnknownProperties = * or a partial of it. * @template TValue The type of value stored in the field being validated. * + * @category validation * @experimental 21.0.0 */ export function validateStandardSchema>(