diff --git a/packages/core/src/authoring/model/model.ts b/packages/core/src/authoring/model/model.ts index 5db20a81147404..ef7467faf8f303 100644 --- a/packages/core/src/authoring/model/model.ts +++ b/packages/core/src/authoring/model/model.ts @@ -31,72 +31,74 @@ export function modelRequiredFunction(): ModelSignal { * The function exposes an API for also declaring required models via the * `model.required` function. * - * @usageNotes - * Initialize a model in your directive or component by declaring a - * class field and initializing it with the `model()` or `model.required()` - * function. - * - * ```ts - * @Directive({..}) - * export class MyDir { - * firstName = model(); // string|undefined - * lastName = model.required(); // string - * age = model(0); // number - * } - * ``` - * * @developerPreview */ export interface ModelFunction { /** - * Initializes a model with an initial value. If no explicit value - * is specified, Angular will use `undefined`. - * - * Consider using `model.required` for models that don't need an - * initial value. - * - * @developerPreview + * Initializes a model of type `T` with an initial value of `undefined`. + * Angular will implicitly use `undefined` as initial value. */ (): ModelSignal; + /** Initializes a model of type `T` with the given initial value. */ (initialValue: T, opts?: ModelOptions): ModelSignal; - /** - * Initializes a required model. - * - * Users of your directive/component need to bind to the input side of the model. - * If unset, a compile time error will be reported. - * - * @developerPreview - */ - required(opts?: ModelOptions): ModelSignal; + required: { + /** + * Initializes a required model. + * + * Users of your directive/component need to bind to the input side of the model. + * If unset, a compile time error will be reported. + */ + (opts?: ModelOptions): ModelSignal; + }; } /** - * `model` declares a writeable signal that is exposed as an input/output pair on the containing - * directive. The input name is taken either from the class member or from the `alias` option. + * `model` declares a writeable signal that is exposed as an input/output + * pair on the containing directive. + * + * The input name is taken either from the class member or from the `alias` option. * The output name is generated by taking the input name and appending `Change`. * - * Initializes a model with an initial value. If no explicit value - * is specified, Angular will use `undefined`. + * @usageNotes * - * Consider using `model.required` for models that don't need an - * initial value. + * To use `model()`, import the function from `@angular/core`. * - * @usageNotes - * Initialize a model in your directive or component by declaring a - * class field and initializing it with the `model()` or `model.required()` - * function. + * ``` + * import {model} from '@angular/core`; + * ``` + * + * Inside your component, introduce a new class member and initialize + * it with a call to `model` or `model.required`. * * ```ts - * @Directive({..}) + * @Directive({ + * ... + * }) * export class MyDir { - * firstName = model(); // string|undefined - * lastName = model.required(); // string - * age = model(0); // number + * firstName = model(); // ModelSignal + * lastName = model.required(); // ModelSignal + * age = model(0); // ModelSignal + * } + * ``` + * + * Inside your component template, you can display the value of a `model` + * by calling the signal. + * + * ```html + * {{firstName()}} + * ``` + * + * Updating the `model` is equivalent to updating a writable signal. + * + * ```ts + * updateName(newFirstName: string): void { + * this.firstName.set(newFirstName); * } * ``` * * @developerPreview + * @initializerApiFunction */ export const model: ModelFunction = (() => { // Note: This may be considered a side-effect, but nothing will depend on