feat(core): add support for model inputs (#54252)

crisbeto · thePunderWoman · commit 702ab28b4c07 · 2024-02-07T16:36:09.000Z
Adds support for model inputs in the framework. `model()` returns a writable signal that implicitly defines a input/output pair that can be used either in two-way bindings to keep two values in sync or by binding individually to the input and output. When the value of the `model` changes, it will emit an event with the current value. Furthermore, these changes expand two-way bindings to accept `WritableSignal`. This will make it easier to transition existing code to signals in a backwards-compatible way. Example: ```ts @directive({ selector: 'counter', standalone: true, host: { '(click)': 'increment()', } }) export class Counter { value = model(0); increment(): void { this.value.update(current => current + 1); } } @component({ template: `<counter [(value)]="count"/> The current count is: {{count()}}`, }) class App { count = signal(0); } ``` PR Close #54252
diff --git a/goldens/public-api/core/errors.md b/goldens/public-api/core/errors.md
@@ -125,6 +125,8 @@ export const enum RuntimeErrorCode {
     // (undocumented)
     REQUIRED_QUERY_NO_VALUE = -951,
     // (undocumented)
+    REQUIRED_MODEL_NO_VALUE = -952,
+    // (undocumented)
     RUNTIME_DEPS_INVALID_IMPORTED_TYPE = 1000,
     // (undocumented)
     RUNTIME_DEPS_ORPHAN_COMPONENT = 1001,
diff --git a/goldens/public-api/core/index.md b/goldens/public-api/core/index.md
@@ -1075,6 +1075,32 @@ export enum MissingTranslationStrategy {
     Warning = 1
 }
 
+// @public
+export const model: ModelFunction;
+
+// @public
+export interface ModelFunction {
+    <T>(): ModelSignal<T | undefined>;
+    // (undocumented)
+    <T>(initialValue: T, opts?: ModelOptions): ModelSignal<T>;
+    required<T>(opts?: ModelOptions): ModelSignal<T>;
+}
+
+// @public
+export interface ModelOptions {
+    alias?: string;
+}
+
+// @public
+export interface ModelSignal<T> extends WritableSignal<T> {
+    // (undocumented)
+    [ɵINPUT_SIGNAL_BRAND_READ_TYPE]: T;
+    // (undocumented)
+    [ɵINPUT_SIGNAL_BRAND_WRITE_TYPE]: T;
+    // (undocumented)
+    [SIGNAL]: ModelSignalNode<T>;
+}
+
 // @public @deprecated
 export class ModuleWithComponentFactories<T> {
     constructor(ngModuleFactory: NgModuleFactory<T>, componentFactories: ComponentFactory<any>[]);
diff --git a/packages/core/src/authoring.ts b/packages/core/src/authoring.ts
@@ -6,12 +6,13 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-// Note: `input` is exported in `core.ts` due to:
+// Note: `input` and `model` are exported in `core.ts` due to:
 // https://docs.google.com/document/d/1RXb1wYwsbJotO1KBgSDsAtKpduGmIHod9ADxuXcAvV4/edit?tab=t.0.
 
 export {InputFunction} from './authoring/input/input';
 export {InputOptions, InputOptionsWithoutTransform, InputOptionsWithTransform, InputSignal, InputSignalWithTransform, ɵINPUT_SIGNAL_BRAND_WRITE_TYPE} from './authoring/input/input_signal';
 export {ɵUnwrapDirectiveSignalInputs} from './authoring/input/input_type_checking';
 export {ModelFunction} from './authoring/model/model';
+export {ModelOptions, ModelSignal} from './authoring/model/model_signal';
 export {output as ɵoutput, OutputEmitter as ɵOutputEmitter, OutputOptions as ɵOutputOptions} from './authoring/output';
 export {ContentChildFunction, ViewChildFunction} from './authoring/queries';
diff --git a/packages/core/src/core.ts b/packages/core/src/core.ts
@@ -13,14 +13,12 @@
  */
 
 export * from './authoring';
-// Input and query authoring functions are exported separately as this file is exempted from
+// Authoring functions are exported separately as this file is exempted from
 // JSCompiler's conformance requirement for inferred const exports. See:
 // https://docs.google.com/document/d/1RXb1wYwsbJotO1KBgSDsAtKpduGmIHod9ADxuXcAvV4/edit?tab=t.0
 export {input} from './authoring/input/input';
 export {contentChild, contentChildren, viewChild, viewChildren} from './authoring/queries';
-
-// TODO(crisbeto): export as a public API
-// export {model} from './authoring/model/model';
+export {model} from './authoring/model/model';
 
 export * from './metadata';
 export * from './version';
diff --git a/packages/core/test/bundling/defer/bundle.golden_symbols.json b/packages/core/test/bundling/defer/bundle.golden_symbols.json
@@ -1556,6 +1556,15 @@
   {
     "name": "init_misc_utils"
   },
+  {
+    "name": "init_model"
+  },
+  {
+    "name": "init_model_signal"
+  },
+  {
+    "name": "init_model_signal_node"
+  },
   {
     "name": "init_module"
   },
diff --git a/packages/core/test/bundling/forms_template_driven/bundle.golden_symbols.json b/packages/core/test/bundling/forms_template_driven/bundle.golden_symbols.json
@@ -881,6 +881,9 @@
   {
     "name": "diPublicInInjector"
   },
+  {
+    "name": "elementPropertyInternal"
+  },
   {
     "name": "enterDI"
   },
@@ -1289,6 +1292,9 @@
   {
     "name": "isReadableStreamLike"
   },
+  {
+    "name": "isSignal"
+  },
   {
     "name": "isStylingMatch"
   },
@@ -1331,6 +1337,9 @@
   {
     "name": "leaveViewLight"
   },
+  {
+    "name": "listenerInternal"
+  },
   {
     "name": "lookupTokenUsingModuleInjector"
   },

Original file line number	Diff line number	Diff line change
`@@ -881,6 +881,9 @@`
`881`	`881`	`{`
`882`	`882`	`"name": "diPublicInInjector"`
`883`	`883`	`},`
	`884`	`+ {`
	`885`	`+ "name": "elementPropertyInternal"`
	`886`	`+ },`
`884`	`887`	`{`
`885`	`888`	`"name": "enterDI"`
`886`	`889`	`},`
`@@ -1289,6 +1292,9 @@`
`1289`	`1292`	`{`
`1290`	`1293`	`"name": "isReadableStreamLike"`
`1291`	`1294`	`},`
	`1295`	`+ {`
	`1296`	`+ "name": "isSignal"`
	`1297`	`+ },`
`1292`	`1298`	`{`
`1293`	`1299`	`"name": "isStylingMatch"`
`1294`	`1300`	`},`
`@@ -1331,6 +1337,9 @@`
`1331`	`1337`	`{`
`1332`	`1338`	`"name": "leaveViewLight"`
`1333`	`1339`	`},`
	`1340`	`+ {`
	`1341`	`+ "name": "listenerInternal"`
	`1342`	`+ },`
`1334`	`1343`	`{`
`1335`	`1344`	`"name": "lookupTokenUsingModuleInjector"`
`1336`	`1345`	`},`