Skip to content

Commit 8f4b1dc

Browse files
SkyZeroZxSkyZeroZx
committed
docs: add @see references to Signal Forms
1 parent a720094 commit 8f4b1dc

22 files changed

Lines changed: 262 additions & 0 deletions

‎packages/forms/signals/compat/src/api/compat_form.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@ import {CompatFieldAdapter} from '../compat_field_adapter';
1515
/**
1616
* Options that may be specified when creating a compat form.
1717
*
18+
* @see [Top-down migration using compatForm](guide/forms/signals/migration#top-down-migration-using-compatform)
19+
*
1820
* @category interop
1921
* @publicApi 22.0
2022
*/
@@ -46,6 +48,8 @@ export type CompatFormOptions<TModel> = Omit<FormOptions<TModel>, 'adapter'>;
4648
* structure will match the shape of the model and any changes to the form data will be written to
4749
* the model.
4850
*
51+
* @see [Top-down migration using compatForm](guide/forms/signals/migration#top-down-migration-using-compatform)
52+
*
4953
* @category interop
5054
* @publicApi 22.0
5155
*/
@@ -80,6 +84,8 @@ export function compatForm<TModel>(model: WritableSignal<TModel>): FieldTree<TMo
8084
* When passing a schema, the form options can be passed as a third argument if needed.
8185
* 2. The form options (excluding adapter, since it's provided).
8286
*
87+
* @see [Top-down migration using compatForm](guide/forms/signals/migration#top-down-migration-using-compatform)
88+
*
8389
* @category interop
8490
* @publicApi 22.0
8591
*/
@@ -116,6 +122,8 @@ export function compatForm<TModel>(
116122
* When passing a schema, the form options can be passed as a third argument if needed.
117123
* @param options The form options (excluding adapter, since it's provided).
118124
*
125+
* @see [Top-down migration using compatForm](guide/forms/signals/migration#top-down-migration-using-compatform)
126+
*
119127
* @category interop
120128
* @publicApi 22.0
121129
*/

‎packages/forms/signals/compat/src/api/di.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ import type {SignalFormsConfig} from '../../../src/api/di';
1212
* A value that can be used for `SignalFormsConfig.classes` to automatically add
1313
* the `ng-*` status classes from reactive forms.
1414
*
15+
* @see [Automatic status classes](guide/forms/signals/migration#automatic-status-classes)
16+
*
1517
* @publicApi 22.0
1618
*/
1719
export const NG_STATUS_CLASSES: SignalFormsConfig['classes'] = {

‎packages/forms/signals/compat/src/signal_form_control/signal_form_control.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,8 @@ export type ValueUpdateOptions = {
7777
* </form>
7878
* ```
7979
*
80+
* @see [Binding SignalFormControl](guide/forms/signals/migration#binding-signalformcontrol)
81+
*
8082
* @publicApi 22.0
8183
*/
8284
export class SignalFormControl<T> extends AbstractControl {

‎packages/forms/signals/src/api/control.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ import type {DisabledReason} from './types';
1414
/**
1515
* The base set of properties shared by all form control contracts.
1616
*
17+
* @see [Custom form controls](guide/forms/signals/custom-controls)
18+
*
1719
* @category control
1820
* @publicApi 22.0
1921
*/
@@ -150,6 +152,8 @@ type FormUiControlImplementsFormFieldBindingOptions = Check<
150152
*
151153
* @template TValue The type of `FieldTree` that the implementing component can edit.
152154
*
155+
* @see [Custom form controls](guide/forms/signals/custom-controls)
156+
*
153157
* @category control
154158
* @publicApi 22.0
155159
*/
@@ -179,6 +183,8 @@ export interface FormValueControl<TValue> extends FormUiControl<TValue> {
179183
* implemented, but if they are will be kept in sync with the field state of the field bound to the
180184
* `Field` directive.
181185
*
186+
* @see [Custom form controls](guide/forms/signals/custom-controls)
187+
*
182188
* @category control
183189
* @publicApi 22.0
184190
*/

‎packages/forms/signals/src/api/di.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@ import {SIGNAL_FORMS_CONFIG} from '../field/di';
1313
/**
1414
* Configuration options for signal forms.
1515
*
16+
* @see [Automatic status classes](guide/forms/signals/migration#automatic-status-classes)
17+
*
1618
* @publicApi 22.0
1719
*/
1820
export interface SignalFormsConfig {
@@ -25,6 +27,8 @@ export interface SignalFormsConfig {
2527
/**
2628
* Provides configuration options for signal forms.
2729
*
30+
* @see [Automatic status classes](guide/forms/signals/migration#automatic-status-classes)
31+
*
2832
* @publicApi 22.0
2933
*/
3034
export function provideSignalFormsConfig(config: SignalFormsConfig): Provider[] {

‎packages/forms/signals/src/api/rules/debounce.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ import type {Debouncer, PathKind, SchemaPath, SchemaPathRules} from '../types';
2121
* @param config A debounce configuration, which can be either a debounce duration in milliseconds,
2222
* `'blur'` to debounce until the field is blurred, or a custom {@link Debouncer} function.
2323
*
24+
* @see [Debouncing form updates](guide/forms/signals/form-logic#delay-input-operations-with-debounce)
2425
* @see [Custom form controls](guide/forms/signals/custom-controls) for using `debounce('blur')` with
2526
* a custom `FormValueControl`.
2627
*

‎packages/forms/signals/src/api/rules/disabled.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,9 @@ import type {FieldContext, LogicFn, PathKind, SchemaPath, SchemaPathRules} from
2121
* @template TValue The type of value stored in the field the logic is bound to.
2222
* @template TPathKind The kind of path the logic is bound to (a root path, child path, or item of an array)
2323
*
24+
* @see [Disabled fields](guide/forms/signals/form-logic#prevent-field-updates-with-disabled)
25+
* @see [Availability state](guide/forms/signals/field-state-management#availability-state)
26+
*
2427
* @category logic
2528
* @publicApi 22.0
2629
*/

‎packages/forms/signals/src/api/rules/hidden.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,9 @@ import type {LogicFn, PathKind, SchemaPath, SchemaPathRules} from '../types';
2828
* @template TValue The type of value stored in the field the logic is bound to.
2929
* @template TPathKind The kind of path the logic is bound to (a root path, child path, or item of an array)
3030
*
31+
* @see [Hidden fields](guide/forms/signals/form-logic#configuring-hidden-state-on-fields)
32+
* @see [Availability state](guide/forms/signals/field-state-management#availability-state)
33+
*
3134
* @category logic
3235
* @publicApi 22.0
3336
*/

‎packages/forms/signals/src/api/rules/metadata.ts‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,9 @@ import type {FieldState, LogicFn, PathKind, SchemaPath, SchemaPathRules} from '.
2424
* @template TKey The type of metadata key.
2525
* @template TPathKind The kind of path the logic is bound to (a root path, child path, or item of an array)
2626
*
27+
* @see [Field metadata](guide/forms/signals/field-metadata)
28+
* @see [Setting values from a schema](guide/forms/signals/field-metadata#setting-values-from-a-schema)
29+
*
2730
* @category logic
2831
* @publicApi 22.0
2932
*/
@@ -55,6 +58,9 @@ export function metadata<
5558
*
5659
* @template TAcc The accumulated type of the reduce operation.
5760
* @template TItem The type of the individual items that are reduced over.
61+
*
62+
* @see [Combining contributions with reducers](guide/forms/signals/field-metadata#combining-contributions-with-reducers)
63+
*
5864
* @publicApi 22.0
5965
*/
6066
export interface MetadataReducer<TAcc, TItem> {
@@ -130,6 +136,8 @@ function override<T>(getInitial?: () => T): MetadataReducer<T | undefined, T> {
130136
/**
131137
* A symbol used to tag a `MetadataKey` as representing an asynchronous validation resource.
132138
*
139+
* @see [Async validation](guide/forms/signals/validation#async-validation)
140+
*
133141
* @category validation
134142
* @publicApi 22.0
135143
*/
@@ -145,6 +153,8 @@ export const IS_ASYNC_VALIDATION_RESOURCE: unique symbol = Symbol('IS_ASYNC_VALI
145153
* @template TWrite The type written to this key using the `metadata()` rule
146154
* @template TAcc The type of the reducer's accumulated value.
147155
*
156+
* @see [Field metadata](guide/forms/signals/field-metadata)
157+
*
148158
* @publicApi 22.0
149159
*/
150160
export class MetadataKey<TRead, TWrite, TAcc> {
@@ -164,6 +174,9 @@ export class MetadataKey<TRead, TWrite, TAcc> {
164174
* Represents metadata that is used to define a valid limit for a field.
165175
*
166176
* @template TLimit The type the limit value.
177+
*
178+
* @see [Validation constraints](guide/forms/signals/custom-controls#validation-constraints)
179+
*
167180
* @publicApi 22.0
168181
*/
169182
export type LimitKey<TLimit> = MetadataKey<
@@ -183,6 +196,8 @@ declare const LIMIT_SELECTION_KEY: unique symbol;
183196
* This indirection allows rules to bind a {@link LimitKey} of a specific limit type (e.g. `number`
184197
* or `Date`) matching the field's type to a generic {@link MetadataKey}.
185198
*
199+
* @see [Validation constraints](guide/forms/signals/custom-controls#validation-constraints)
200+
*
186201
* @publicApi 22.0
187202
*/
188203
export type LimitSelectionKey = MetadataKey<
@@ -198,6 +213,8 @@ export type LimitSelectionKey = MetadataKey<
198213
*
199214
* @template TKey The `MetadataKey` type
200215
*
216+
* @see [Field metadata](guide/forms/signals/field-metadata)
217+
*
201218
* @publicApi 22.0
202219
*/
203220
export type MetadataSetterType<TKey> =
@@ -209,6 +226,8 @@ export type MetadataSetterType<TKey> =
209226
*
210227
* @template TWrite The type written to this key using the `metadata()` rule
211228
*
229+
* @see [Creating a metadata key](guide/forms/signals/field-metadata#creating-a-metadata-key)
230+
*
212231
* @publicApi 22.0
213232
*/
214233
export function createMetadataKey<TWrite>(): MetadataKey<
@@ -223,6 +242,8 @@ export function createMetadataKey<TWrite>(): MetadataKey<
223242
* @template TWrite The type written to this key using the `metadata()` rule
224243
* @template TAcc The type of the reducer's accumulated value.
225244
*
245+
* @see [Creating a metadata key](guide/forms/signals/field-metadata#creating-a-metadata-key)
246+
*
226247
* @publicApi 22.0
227248
*/
228249
export function createMetadataKey<TWrite, TAcc>(
@@ -247,6 +268,8 @@ export function createMetadataKey<TWrite, TAcc>(
247268
* @template TRead The type read from the `FieldState` for this key
248269
* @template TWrite The type written to this key using the `metadata()` rule
249270
*
271+
* @see [Attaching lifecycle-aware objects with managed metadata](guide/forms/signals/field-metadata#attaching-lifecycle-aware-objects-with-managed-metadata)
272+
*
250273
* @publicApi 22.0
251274
*/
252275
export function createManagedMetadataKey<TRead, TWrite>(
@@ -265,6 +288,8 @@ export function createManagedMetadataKey<TRead, TWrite>(
265288
* @template TWrite The type written to this key using the `metadata()` rule
266289
* @template TAcc The type of the reducer's accumulated value.
267290
*
291+
* @see [Attaching lifecycle-aware objects with managed metadata](guide/forms/signals/field-metadata#attaching-lifecycle-aware-objects-with-managed-metadata)
292+
*
268293
* @publicApi 22.0
269294
*/
270295
export function createManagedMetadataKey<TRead, TWrite, TAcc>(
@@ -284,6 +309,8 @@ export function createManagedMetadataKey<TRead, TWrite, TAcc>(
284309
/**
285310
* Creates a {@link LimitSelectionKey}.
286311
*
312+
* @see [Validation constraints](guide/forms/signals/custom-controls#validation-constraints)
313+
*
287314
* @publicApi 22.0
288315
*/
289316
export function createLimitSelectionKey(): LimitSelectionKey {
@@ -293,6 +320,8 @@ export function createLimitSelectionKey(): LimitSelectionKey {
293320
/**
294321
* A {@link MetadataKey} representing whether the field is required.
295322
*
323+
* @see [Required validation](guide/forms/signals/validation#required)
324+
*
296325
* @category validation
297326
* @publicApi 22.0
298327
*/
@@ -306,6 +335,8 @@ export const REQUIRED: MetadataKey<Signal<boolean>, boolean, boolean> = createMe
306335
* This indirection allows different keys to be used for different types of values with their
307336
* own reducers, such as {@link MIN_DATE} and {@link MIN_NUMBER}.
308337
*
338+
* @see [Minimum and maximum validation](guide/forms/signals/validation#min-and-max)
339+
*
309340
* @category validation
310341
* @publicApi 22.0
311342
*/
@@ -314,6 +345,8 @@ export const MIN: LimitSelectionKey = createLimitSelectionKey();
314345
/**
315346
* A {@link MetadataKey} representing the minimum valid value of a date field.
316347
*
348+
* @see [Minimum and maximum validation](guide/forms/signals/validation#min-and-max)
349+
*
317350
* @category validation
318351
* @publicApi 22.0
319352
*/
@@ -322,6 +355,8 @@ export const MIN_DATE: LimitKey<Date> = createMetadataKey(MetadataReducer.max())
322355
/**
323356
* A {@link MetadataKey} representing the minimum valid value of a number field.
324357
*
358+
* @see [Minimum and maximum validation](guide/forms/signals/validation#min-and-max)
359+
*
325360
* @category validation
326361
* @publicApi 22.0
327362
*/
@@ -333,6 +368,8 @@ export const MIN_NUMBER: LimitKey<number> = createMetadataKey(MetadataReducer.ma
333368
* This indirection allows different keys to be used for different types of values with their
334369
* own reducers, such as {@link MAX_DATE} and {@link MAX_NUMBER}.
335370
*
371+
* @see [Minimum and maximum validation](guide/forms/signals/validation#min-and-max)
372+
*
336373
* @category validation
337374
* @publicApi 22.0
338375
*/
@@ -341,6 +378,8 @@ export const MAX: LimitSelectionKey = createLimitSelectionKey();
341378
/**
342379
* A {@link MetadataKey} representing the maximum valid value of a date field.
343380
*
381+
* @see [Minimum and maximum validation](guide/forms/signals/validation#min-and-max)
382+
*
344383
* @category validation
345384
* @publicApi 22.0
346385
*/
@@ -349,6 +388,8 @@ export const MAX_DATE: LimitKey<Date> = createMetadataKey(MetadataReducer.min())
349388
/**
350389
* A {@link MetadataKey} representing the maximum valid value of a number field.
351390
*
391+
* @see [Minimum and maximum validation](guide/forms/signals/validation#min-and-max)
392+
*
352393
* @category validation
353394
* @publicApi 22.0
354395
*/
@@ -357,6 +398,8 @@ export const MAX_NUMBER: LimitKey<number> = createMetadataKey(MetadataReducer.mi
357398
/**
358399
* A {@link MetadataKey} representing the min length of the field.
359400
*
401+
* @see [Minimum and maximum length validation](guide/forms/signals/validation#minlength-and-maxlength)
402+
*
360403
* @category validation
361404
* @publicApi 22.0
362405
*/
@@ -365,6 +408,8 @@ export const MIN_LENGTH: LimitKey<number> = createMetadataKey(MetadataReducer.ma
365408
/**
366409
* A {@link MetadataKey} representing the max length of the field.
367410
*
411+
* @see [Minimum and maximum length validation](guide/forms/signals/validation#minlength-and-maxlength)
412+
*
368413
* @category validation
369414
* @publicApi 22.0
370415
*/
@@ -373,6 +418,8 @@ export const MAX_LENGTH: LimitKey<number> = createMetadataKey(MetadataReducer.mi
373418
/**
374419
* A {@link MetadataKey} representing the patterns the field must match.
375420
*
421+
* @see [Pattern validation](guide/forms/signals/validation#pattern)
422+
*
376423
* @category validation
377424
* @publicApi 22.0
378425
*/

‎packages/forms/signals/src/api/rules/readonly.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,9 @@ import type {LogicFn, PathKind, SchemaPath, SchemaPathRules} from '../types';
2020
* @template TValue The type of value stored in the field the logic is bound to.
2121
* @template TPathKind The kind of path the logic is bound to (a root path, child path, or item of an array)
2222
*
23+
* @see [Readonly fields](guide/forms/signals/form-logic#display-uneditable-fields-with-readonly)
24+
* @see [Availability state](guide/forms/signals/field-state-management#availability-state)
25+
*
2326
* @category logic
2427
* @publicApi 22.0
2528
*/

0 commit comments

Comments
 (0)