refactor(ref): deprecate view-model.ref and introduce component.ref (#…

…1803) * chore(deps): upgrade ts to 5.1.6 [skip ci]
aurelia · Jul 18, 2023 · 97e8dad · 97e8dad
1 parent bf1ca4c
commit 97e8dad
Show file tree

Hide file tree

Showing 76 changed files with 1,368 additions and 635 deletions.
diff --git a/docs/user-docs/developer-guides/cheat-sheet.md b/docs/user-docs/developer-guides/cheat-sheet.md
@@ -454,9 +454,9 @@ export class BananaInBox {
 <form submit.trigger="$event.preventDefault()">
 <!-- Set this html element to the 'nameInput' property on the declaring component -->
 <input ref="nameInput">
-<!-- Set the view model of this <my-component> custom element
+<!-- Set the component instance of this <my-component> custom element
      to the 'myComponentViewModel' property on the declaring component -->
-<my-component view-model.ref="myComponentViewModel">
+<my-component component.ref="myComponentViewModel">
 <!-- Automatic two-way binding to an input (convention, equivalent to value.two-way) -->
 <input value.bind="name">
 <!-- Manual two-way binding to an input -->

diff --git a/docs/user-docs/developer-guides/migrating-to-aurelia-2/README.md b/docs/user-docs/developer-guides/migrating-to-aurelia-2/README.md
@@ -59,6 +59,11 @@ interface IAurelia {
 
 Parent container and resources can be specified through this config.
 
+### View model ref binding (view-model.ref="...")
+
+In v2, in order to get a reference to the underlying component view model, use `component.ref` instead of view-model.ref
+This is to make terminologies consistent as we are moving towards component oriented terms.
+
 ### Call binding (some-prop.call="...")
 
 The call binding no longer assigns properties of the first argument pass to the call to the calling override context. This is unreasonably dynamic and could result in hard-to-understand templates.
@@ -135,7 +140,7 @@ Change it to:
   ```
 
 - In Aurelia 2, all bindings are passed through to the underlying custom element
-composition, so `view-model.ref` no longer means getting a reference to the composer, but the composed view model instead.
+composition, so `component.ref` (`view-model.ref` in v1) no longer means getting a reference to the composer, but the composed view model instead.
 
 Read more about dynamic composition in v2 in this [dynamic composition doc](../../getting-to-know-aurelia/dynamic-composition.md) and [dynamic ui composition doc](../../app-basics/dynamic-ui-composition.md).
 

diff --git a/docs/user-docs/developer-guides/migrating-to-aurelia-2/side-by-side-comparison.md b/docs/user-docs/developer-guides/migrating-to-aurelia-2/side-by-side-comparison.md
@@ -533,12 +533,13 @@ export class MyApp {
 | one-time  | **✓**         |             |
 | bind      | **✓**         |             |
 
-### Referencing DOM Elements
+### References
 
-| Name | Aurelia 1 & 2 | Description |
-| ---- | ------------- | ----------- |
-| ref  | **✓**         |             |
-| view-model.ref  | **✓**         |             |
+| Name | Aurelia 1 | Aurelia 2 | Description |
+| ---- | - | - |
+| ref  | **✓** | **✓** | |
+| view-model.ref  | **✓** | **✓** | deprecated in v2 |
+| component.ref | **✗** | **✓** | Not in v1 |
 
 ### Passing Function References
 

diff --git a/docs/user-docs/getting-to-know-aurelia/dynamic-composition.md b/docs/user-docs/getting-to-know-aurelia/dynamic-composition.md
@@ -83,13 +83,13 @@ export class MyComponent {
 
 ## Accessing the view model
 
-In some scenarios, you may want to access the view model of the component being rendered using `<au-compose>` we can achieve this by adding the `view-model.ref` binding to our compose element.
+In some scenarios, you may want to access the view model of the component being rendered using `<au-compose>` we can achieve this by adding the `component.ref`(known as `view-model.ref` in v1) binding to our compose element.
 
 ```html
-<au-compose view-model.ref="myCompose"></au-compose>
+<au-compose component.ref="myCompose"></au-compose>
 ```
 
-This will work as though it were a `view-model.ref` binding on a standard custom element.
+This will work as though it were a `component.ref` binding on a standard custom element.
 
 ## Passing props through
 
@@ -155,7 +155,7 @@ If you still want a view supporting a dynamically loaded module, you can create
 
 The above value converter will load the URL and return the text response. For view models, something similar can be achieved where an object or class can be returned.
 
-3. In Aurelia 2, all bindings are transferred to the underlying custom element composition. Therefore, `view-model.ref` no longer signifies obtaining a reference to the composer, but rather to the composed view model.
+3. In Aurelia 2, all bindings are transferred to the underlying custom element composition. Therefore, `component.ref` no longer signifies obtaining a reference to the composer, but rather to the composed view model.
 ### Scope breaking changes
 
 By default, when composing, the outer scope will not be inherited. The parent scope will only be inherited when it is not a custom element being composed. This means the outer scope will be used when composing only a view or plain object as the view model.

diff --git a/docs/user-docs/templates/template-syntax.md b/docs/user-docs/templates/template-syntax.md
@@ -298,9 +298,9 @@ export class MyApp {
 
 The `ref` attribute has several qualifiers you can use in conjunction with custom elements and attributes:
 
-* `view-model.ref="expression"`: create a reference to a custom element's view-model
-* `custom-attribute.ref="expression"`: create a reference to a custom attribute's view-model
-* `controller.ref="expression"`: create a reference to a custom element's controller instance
+* `component.ref="expression"`: create a reference to a custom element's component instance(view-model). This is known as `view-model.ref` in v1.
+* `custom-attribute.ref="expression"`: create a reference to a custom attribute's component instance (view-model).
+* `controller.ref="expression"`: create a reference to a custom element's controller instance.
 
 {% hint style="info" %}
 Template references are a great way to reference elements inside view models for use with third-party libraries. They negate the need to query for elements using Javascript APIs.

diff --git a/examples/base-url/package.json b/examples/base-url/package.json
@@ -28,7 +28,7 @@
     "rimraf": "^3.0.2",
     "style-loader": "^3.3.1",
     "ts-loader": "^9.3.0",
-    "typescript": "5.0.2",
+    "typescript": "5.1.6",
     "url-loader": "^4.1.1",
     "webpack": "^5.72.0",
     "webpack-bundle-analyzer": "^4.5.0",

diff --git a/examples/doc-example/package.json b/examples/doc-example/package.json
@@ -24,7 +24,7 @@
     "rimraf": "^3.0.0",
     "style-loader": "^3.3.1",
     "ts-loader": "^9.3.0",
-    "typescript": "5.0.2",
+    "typescript": "5.1.6",
     "webpack": "^5.72.0",
     "webpack-cli": "^4.9.2",
     "webpack-dev-server": "^4.8.1"

diff --git a/examples/jit-webpack-conventions-ts/package.json b/examples/jit-webpack-conventions-ts/package.json
@@ -31,6 +31,6 @@
     "@aurelia/webpack-loader": "dev",
     "ts-loader": "^9.3.0",
     "@types/node": "^14.18.14",
-    "typescript": "5.0.2"
+    "typescript": "5.1.6"
   }
 }
diff --git a/examples/jit-webpack-vanilla-ts/package.json b/examples/jit-webpack-vanilla-ts/package.json
@@ -29,7 +29,7 @@
     "html-webpack-plugin": "^5.5.0",
     "rimraf": "^3.0.0",
     "ts-loader": "^9.3.0",
-    "typescript": "5.0.2",
+    "typescript": "5.1.6",
     "webpack-cli": "^4.9.2",
     "webpack": "^5.72.0"
   }

diff --git a/examples/lazy-loading-config/package.json b/examples/lazy-loading-config/package.json
@@ -28,7 +28,7 @@
     "rimraf": "^3.0.2",
     "style-loader": "^3.3.1",
     "ts-loader": "^9.3.0",
-    "typescript": "5.0.2",
+    "typescript": "5.1.6",
     "url-loader": "^4.1.1",
     "webpack": "^5.72.0",
     "webpack-bundle-analyzer": "^4.5.0",

diff --git a/examples/navigation-skeleton/package.json b/examples/navigation-skeleton/package.json
@@ -32,7 +32,7 @@
     "rimraf": "^3.0.0",
     "style-loader": "^3.3.1",
     "ts-loader": "^9.3.0",
-    "typescript": "5.0.2",
+    "typescript": "5.1.6",
     "url-loader": "^4.1.1",
     "webpack": "^5.72.0",
     "webpack-cli": "^4.9.2",

diff --git a/examples/realworld-advanced/package.json b/examples/realworld-advanced/package.json
@@ -24,7 +24,7 @@
     "rimraf": "^3.0.0",
     "style-loader": "^3.3.1",
     "ts-loader": "^9.3.0",
-    "typescript": "5.0.2",
+    "typescript": "5.1.6",
     "webpack": "^5.72.0",
     "webpack-cli": "^4.9.2",
     "webpack-dev-server": "^4.8.1"

diff --git a/examples/realworld-conventions/package.json b/examples/realworld-conventions/package.json
@@ -24,7 +24,7 @@
     "rimraf": "^3.0.0",
     "style-loader": "^3.3.1",
     "ts-loader": "^9.3.0",
-    "typescript": "5.0.2",
+    "typescript": "5.1.6",
     "webpack": "^5.72.0",
     "webpack-cli": "^4.9.2",
     "webpack-dev-server": "^4.8.1"

diff --git a/examples/realworld/package.json b/examples/realworld/package.json
@@ -24,7 +24,7 @@
     "rimraf": "^3.0.0",
     "style-loader": "^3.3.1",
     "ts-loader": "^9.3.0",
-    "typescript": "5.0.2",
+    "typescript": "5.1.6",
     "webpack": "^5.72.0",
     "webpack-cli": "^4.9.2",
     "webpack-dev-server": "^4.8.1"

diff --git a/examples/router-animation/package.json b/examples/router-animation/package.json
@@ -41,6 +41,6 @@
     "webpack-bundle-analyzer": "^4.5.0",
     "html-webpack-plugin": "^5.5.0",
     "ts-loader": "^9.3.0",
-    "typescript": "5.0.2"
+    "typescript": "5.1.6"
   }
 }
diff --git a/examples/validation-with-router/package.json b/examples/validation-with-router/package.json
@@ -23,7 +23,7 @@
     "html-webpack-plugin": "^5.5.0",
     "rimraf": "^3.0.0",
     "ts-loader": "^9.3.0",
-    "typescript": "5.0.2",
+    "typescript": "5.1.6",
     "webpack": "^5.72.0",
     "webpack-cli": "^4.9.2",
     "webpack-dev-server": "^4.8.1"