ember-source 7.1.0-beta.1 → 7.1.0

package/types/stable/@ember/-internals/glimmer/lib/helpers/if-unless.d.ts

@@ -17,26 +17,34 @@ declare module '@ember/-internals/glimmer/lib/helpers/if-unless' {
       using the block form to wrap the section of template you want to conditionally render.
       Like so:
 
-      ```app/templates/application.hbs
-      <Weather />
+      ```app/templates/application.gjs
+      import Weather from '../components/weather';
+        
+      <template>
+        <Weather />
+      </template>
       ```
 
-      ```app/components/weather.hbs
-      {{! will not render because greeting is undefined}}
-      {{#if @isRaining}}
-        Yes, grab an umbrella!
-      {{/if}}
+      ```app/components/weather.gjs
+      <template>
+        {{! will not render because greeting is undefined}}
+        {{#if @isRaining}}
+          Yes, grab an umbrella!
+        {{/if}}
+      </template>
       ```
 
       You can also define what to show if the property is falsey by using
       the `else` helper.
 
-      ```app/components/weather.hbs
-      {{#if @isRaining}}
-        Yes, grab an umbrella!
-      {{else}}
-        No, it's lovely outside!
-      {{/if}}
+      ```app/components/weather.gjs
+      <template>
+        {{#if @isRaining}}
+          Yes, grab an umbrella!
+        {{else}}
+          No, it's lovely outside!
+        {{/if}}
+      </template>
       ```
 
       You are also able to combine `else` and `if` helpers to create more complex
@@ -44,20 +52,26 @@ declare module '@ember/-internals/glimmer/lib/helpers/if-unless' {
 
       For the following template:
 
-       ```app/components/weather.hbs
-      {{#if @isRaining}}
-        Yes, grab an umbrella!
-      {{else if @isCold}}
-        Grab a coat, it's chilly!
-      {{else}}
-        No, it's lovely outside!
-      {{/if}}
+       ```app/components/weather.gjs
+      <template>
+        {{#if @isRaining}}
+          Yes, grab an umbrella!
+        {{else if @isCold}}
+          Grab a coat, it's chilly!
+        {{else}}
+          No, it's lovely outside!
+        {{/if}}
+      </template>
       ```
 
       If you call it by saying `isCold` is true:
 
-      ```app/templates/application.hbs
-      <Weather @isCold={{true}} />
+      ```app/templates/application.gjs
+      import Weather from '../components/weather';
+        
+      <template>
+        <Weather @isCold={{true}} />
+      </template>
       ```
 
       Then `Grab a coat, it's chilly!` will be rendered.
@@ -71,12 +85,18 @@ declare module '@ember/-internals/glimmer/lib/helpers/if-unless' {
 
       For example, if `useLongGreeting` is truthy, the following:
 
-      ```app/templates/application.hbs
-      <Greeting @useLongGreeting={{true}} />
+      ```app/templates/application.gjs
+      import Greeting from '../components/greeting';
+      
+      <template>
+        <Greeting @useLongGreeting={{true}} />
+      <template>
       ```
 
-      ```app/components/greeting.hbs
-      {{if @useLongGreeting "Hello" "Hi"}} Alex
+      ```app/components/greeting.gjs
+      <template>
+        {{if @useLongGreeting "Hello" "Hi"}} Alex
+      <template>
       ```
 
       Will render:
@@ -88,7 +108,9 @@ declare module '@ember/-internals/glimmer/lib/helpers/if-unless' {
       One detail to keep in mind is that both branches of the `if` helper will be evaluated,
       so if you have `{{if condition "foo" (expensive-operation "bar")`,
       `expensive-operation` will always calculate.
-
+     
+      `if` is built-in and does not need to be imported.
+     
       @method if
       @for Ember.Templates.helpers
       @public
@@ -107,12 +129,18 @@ declare module '@ember/-internals/glimmer/lib/helpers/if-unless' {
 
       For example, if you pass a falsey `useLongGreeting` to the `Greeting` component:
 
-      ```app/templates/application.hbs
-      <Greeting @useLongGreeting={{false}} />
+      ```app/templates/application.gjs
+      import Greeting from '../components/greeting';
+        
+      <template>
+        <Greeting @useLongGreeting={{false}} />
+      </template>
       ```
 
-      ```app/components/greeting.hbs
-      {{unless @useLongGreeting "Hi" "Hello"}} Ben
+      ```app/components/greeting.gjs
+      <template>
+        {{unless @useLongGreeting "Hi" "Hello"}} Ben
+      </template>
       ```
 
       Then it will display:
@@ -127,14 +155,20 @@ declare module '@ember/-internals/glimmer/lib/helpers/if-unless' {
 
       The following will not render anything:
 
-      ```app/templates/application.hbs
-      <Greeting />
+      ```app/templates/application.gjs
+      import Greeting from '../components/greeting';
+        
+      <template>
+        <Greeting />
+      </template>
       ```
 
-      ```app/components/greeting.hbs
-      {{#unless @greeting}}
-        No greeting was found. Why not set one?
-      {{/unless}}
+      ```app/components/greeting.gjs
+      <template>
+        {{#unless @greeting}}
+          No greeting was found. Why not set one?
+        {{/unless}}
+      </template>
       ```
 
       You can also use an `else` helper with the `unless` block. The
@@ -142,18 +176,24 @@ declare module '@ember/-internals/glimmer/lib/helpers/if-unless' {
 
       If you have the following component:
 
-      ```app/components/logged-in.hbs
-      {{#unless @userData}}
-        Please login.
-      {{else}}
-        Welcome back!
-      {{/unless}}
+      ```app/components/logged-in.gjs
+      <template>
+        {{#unless @userData}}
+          Please login.
+        {{else}}
+          Welcome back!
+        {{/unless}}
+      </template>
       ```
 
       Calling it with a truthy `userData`:
 
-      ```app/templates/application.hbs
-      <LoggedIn @userData={{hash username="Zoey"}} />
+      ```app/templates/application.gjs
+      import LoggedIn from '../components/logged-in';
+        
+      <template>
+        <LoggedIn @userData={{hash username="Zoey"}} />
+      </template>
       ```
 
       Will render:
@@ -164,8 +204,12 @@ declare module '@ember/-internals/glimmer/lib/helpers/if-unless' {
 
       and calling it with a falsey `userData`:
 
-      ```app/templates/application.hbs
-      <LoggedIn @userData={{false}} />
+      ```app/templates/application.gjs
+      import LoggedIn from '../components/logged-in';
+
+      <template>
+        <LoggedIn @userData={{false}} />
+      </template>
       ```
 
       Will render:
@@ -173,7 +217,9 @@ declare module '@ember/-internals/glimmer/lib/helpers/if-unless' {
       ```html
       Please login.
       ```
-
+     
+      `unless` is built-in and does not need to be imported.
+     
       @method unless
       @for Ember.Templates.helpers
       @public

package/types/stable/@ember/-internals/glimmer/lib/helpers/mut.d.ts

@@ -1,72 +1,41 @@
 declare module '@ember/-internals/glimmer/lib/helpers/mut' {
     /**
-      The `mut` helper lets you __clearly specify__ that a child `Component` can update the
-      (mutable) value passed to it, which will __change the value of the parent component__.
+      The `mut` helper is a shortcut for updating for args.
+        
+      However, defining update functions on your backing class is preferable to using `mut`.
+        
+      More directly: Don't use `mut`.
 
-      To specify that a parameter is mutable, when invoking the child `Component`:
-
-      ```handlebars
-      <MyChild @childClickCount={{fn (mut totalClicks)}} />
-      ```
-
-       or
-
-      ```handlebars
-      {{my-child childClickCount=(mut totalClicks)}}
-      ```
-
-      The child `Component` can then modify the parent's value just by modifying its own
-      property:
-
-      ```javascript
-      // my-child.js
-      export default class MyChild extends Component {
-        click() {
-          this.incrementProperty('childClickCount');
-        }
-      }
-      ```
-
-      Note that for curly components (`{{my-component}}`) the bindings are already mutable,
-      making the `mut` unnecessary.
-
-      Additionally, the `mut` helper can be combined with the `fn` helper to
-      mutate a value. For example:
-
-      ```handlebars
-      <MyChild @childClickCount={{this.totalClicks}} @click-count-change={{fn (mut totalClicks))}} />
-      ```
-
-      or
+      The `mut` helper, when used with `fn`, will return a function that
+      sets the value passed to `mut` to its first argument. As an example, we can create a
+      button that increments a value passing the value directly to the `fn`:
 
       ```handlebars
-      {{my-child childClickCount=totalClicks click-count-change=(fn (mut totalClicks))}}
+      <MyChild @childClickCount={{this.totalClicks}} @clickCountChange={{fn (mut this.totalClicks)}} />
       ```
 
-      The child `Component` would invoke the function with the new click value:
+      The child `Component` would invoke the function with the new click count:
 
-      ```javascript
-      // my-child.js
+      ```app/components/my-child.gjs
+      import Component from '@glimmer/component';
+      import { action } from '@ember/object';
+        
       export default class MyChild extends Component {
-        click() {
-          this.get('click-count-change')(this.get('childClickCount') + 1);
+        @action
+        update() {
+          this.args.clickCountChange(this.args.childClickCount + 1);
         }
+        
+        <template>
+          <button {{on "click" this.update}}>
+            Click me!
+          </button>
+        </template>
       }
       ```
 
       The `mut` helper changes the `totalClicks` value to what was provided as the `fn` argument.
 
-      The `mut` helper, when used with `fn`, will return a function that
-      sets the value passed to `mut` to its first argument. As an example, we can create a
-      button that increments a value passing the value directly to the `fn`:
-
-      ```handlebars
-      {{! inc helper is not provided by Ember }}
-      <button onclick={{fn (mut count) (inc count)}}>
-        Increment count
-      </button>
-      ```
-
       @method mut
       @param {Object} [attr] the "two-way" attribute that can be modified.
       @for Ember.Templates.helpers

package/types/stable/@ember/-internals/glimmer/lib/helpers/page-title.d.ts

@@ -7,8 +7,12 @@ declare module '@ember/-internals/glimmer/lib/helpers/page-title' {
       append additional titles for each route. For complete documentation, see
       https://github.com/ember-cli/ember-page-title.
 
-      ```handlebars
-      {{page-title "My Page Title" }}
+      ```gjs
+      import pageTitle from 'ember-page-title/helpers/page-title';
+      
+      <template>
+        {{pageTitle "My Page Title" }}
+      </template>
       ```
 
       @method page-title

package/types/stable/@ember/-internals/glimmer/lib/helpers/readonly.d.ts

@@ -2,6 +2,10 @@ declare module '@ember/-internals/glimmer/lib/helpers/readonly' {
     /**
       The `readonly` helper let's you specify that a binding is one-way only,
       instead of two-way.
+      
+      This is a vestigial helper from the days of `@ember/component` and does not apply to
+      components extending from `@glimmer/component`.
+        
       When you pass a `readonly` binding from an outer context (e.g. parent component),
       to to an inner context (e.g. child component), you are saying that changing that
       property in the inner context does not change the value in the outer context.
@@ -14,14 +18,6 @@ declare module '@ember/-internals/glimmer/lib/helpers/readonly' {
       }
       ```
 
-      ```app/templates/components/my-parent.hbs
-      {{log totalClicks}} // -> 3
-      <MyChild @childClickCount={{readonly totalClicks}} />
-      ```
-      ```
-      {{my-child childClickCount=(readonly totalClicks)}}
-      ```
-
       Now, when you update `childClickCount`:
 
       ```app/components/my-child.js

package/types/stable/@ember/-internals/glimmer/lib/modifiers/on.d.ts

@@ -10,20 +10,20 @@ declare module '@ember/-internals/glimmer/lib/modifiers/on' {
       For example, if you'd like to run a function on your component when a `<button>`
       in the components template is clicked you might do something like:
 
-      ```app/components/like-post.hbs
-      <button {{on 'click' this.saveLike}}>Like this post!</button>
-      ```
-
-      ```app/components/like-post.js
+      ```app/components/like-post.gjs
       import Component from '@glimmer/component';
       import { action } from '@ember/object';
 
-      export default class LikePostComponent extends Component {
+      export default class LikePost extends Component {
         @action
         saveLike() {
           // someone likes your post!
           // better send a request off to your server...
         }
+        
+        <template>
+          <button {{on 'click' this.saveLike}}>Like this post!</button>
+        </template>
       }
       ```
 
@@ -58,7 +58,7 @@ declare module '@ember/-internals/glimmer/lib/modifiers/on' {
       For example, in our example case above if you'd like to pass in the post that
       was being liked when the button is clicked you could do something like:
 
-      ```app/components/like-post.hbs
+      ```hbs
       <button {{on 'click' (fn this.saveLike @post)}}>Like this post!</button>
       ```
 
@@ -68,13 +68,13 @@ declare module '@ember/-internals/glimmer/lib/modifiers/on' {
       ### Function Context
 
       In the example above, we used `@action` to ensure that `likePost` is
-      properly bound to the `items-list`, but let's explore what happens if we
+      properly bound to the `LikePost` Component, but let's explore what happens if we
       left out `@action`:
 
-      ```app/components/like-post.js
+      ```app/components/like-post.gjs
       import Component from '@glimmer/component';
 
-      export default class LikePostComponent extends Component {
+      export default class LikePost extends Component {
         saveLike() {
           // ...snip...
         }

package/types/stable/@ember/-internals/glimmer/lib/syntax/in-element.d.ts

@@ -39,6 +39,8 @@ declare module '@ember/-internals/glimmer/lib/syntax/in-element' {
          {{/in-element}}
          ```
 
+     `in-element` is built-in and does not need to be imported.
+     
      @method in-element
      @for Ember.Templates.helpers
      @public

package/types/stable/@ember/-internals/glimmer/lib/syntax/let.d.ts

@@ -32,21 +32,9 @@ declare module '@ember/-internals/glimmer/lib/syntax/let' {
           <MyPost @title={{title}} @content={{content}} @options={{options}} />
         {{/let}}
       ```
-     or
-      ```handlebars
-        {{#let
-            (concat post.title ' | The Ember.js Blog')
-            post.content
-            (hash
-              theme="high-contrast"
-              enableComments=true
-            )
-            as |title content options|
-        }}
-          {{my-post title=title content=content options=options}}
-        {{/let}}
-      ```
 
+     `let` is built-in and does not need to be imported.
+     
       @method let
       @for Ember.Templates.helpers
       @public

package/types/stable/@ember/-internals/glimmer/lib/syntax/mount.d.ts

@@ -6,15 +6,14 @@ declare module '@ember/-internals/glimmer/lib/syntax/mount' {
 
       For example, the following template mounts the `ember-chat` engine:
 
-      ```handlebars
-      {{! application.hbs }}
+      ```app/templates/application.gjs
       {{mount "ember-chat"}}
       ```
 
       Additionally, you can also pass in a `model` argument that will be
       set as the engines model. This can be an existing object:
 
-      ```
+      ```hbs
       <div>
         {{mount 'admin' model=userSettings}}
       </div>
@@ -22,15 +21,20 @@ declare module '@ember/-internals/glimmer/lib/syntax/mount' {
 
       Or an inline `hash`, and you can even pass components:
 
+      ```gjs
+      import SignInButton from '../components/sign-in-button';
+      <template>
+        <div>
+          <h1>Application template!</h1>
+          {{mount 'admin' model=(hash
+              title='Secret Admin'
+              signInButton=SignInButton
+          )}}
+        </div>
+      </template>
       ```
-      <div>
-        <h1>Application template!</h1>
-        {{mount 'admin' model=(hash
-            title='Secret Admin'
-            signInButton=(component 'sign-in-button')
-        )}}
-      </div>
-      ```
+     
+     `mount` is built-in and does not need to be imported.
 
       @method mount
       @param {String} name Name of the engine to mount.

package/types/stable/@ember/-internals/glimmer/lib/syntax/outlet.d.ts

@@ -2,23 +2,30 @@ declare module '@ember/-internals/glimmer/lib/syntax/outlet' {
     /**
       The `{{outlet}}` helper lets you specify where a child route will render in
       your template. An important use of the `{{outlet}}` helper is in your
-      application's `application.hbs` file:
+      application's `application.gjs` file:
 
-      ```app/templates/application.hbs
-      <MyHeader />
-
-      <div class="my-dynamic-content">
-        <!-- this content will change based on the current route, which depends on the current URL -->
-        {{outlet}}
-      </div>
-
-      <MyFooter />
+      ```app/templates/application.gjs
+      import MyHeader from '../components/my-header';
+      import MyFooter from '../components/my-footer';
+        
+      <template>
+        <MyHeader />
+      
+        <div class="my-dynamic-content">
+          <!-- this content will change based on the current route, which depends on the current URL -->
+          {{outlet}}
+        </div>
+      
+        <MyFooter />
+      </template>
       ```
 
       See the [routing guide](https://guides.emberjs.com/release/routing/rendering-a-template/) for more
       information on how your `route` interacts with the `{{outlet}}` helper.
       Note: Your content __will not render__ if there isn't an `{{outlet}}` for it.
 
+      `outlet` is built-in and does not need to be imported.
+     
       @method outlet
       @for Ember.Templates.helpers
       @public

package/types/stable/@ember/-internals/runtime/lib/mixins/target_action_support.d.ts

@@ -5,7 +5,7 @@ declare module '@ember/-internals/runtime/lib/mixins/target_action_support' {
     import Mixin from "@ember/object/mixin";
     /**
     `TargetActionSupport` is a mixin that can be included in a class
-    to add a `triggerAction` method with semantics similar to the Handlebars
+    to add a `triggerAction` method with semantics similar to the
     `{{action}}` helper. In normal Ember usage, the `{{action}}` helper is
     usually the best choice. This mixin is most often useful when you are
     doing more complex event handling in Components.

package/types/stable/@ember/array/index.d.ts

@@ -1274,6 +1274,10 @@ declare module '@ember/array' {
     /**
       Creates an `NativeArray` from an Array-like object.
       Does not modify the original object's contents.
+        
+      This exists primarily for historic reasons and should not be used
+      in new code. Prefer native [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)
+      or [trackedArray](/ember/release/functions/@ember%2Freactive%2Fcollections/trackedArray).
 
       Example
 

package/types/stable/@ember/controller/index.d.ts

@@ -25,7 +25,7 @@ declare module '@ember/controller' {
         /**
           The object to which actions from the view should be sent.
       
-          For example, when a Handlebars template uses the `{{action}}` helper,
+          For example, when a template uses the `{{action}}` helper,
           it will attempt to send the action to the view's controller's `target`.
       
           By default, the value of the target property is set to the router, and

package/types/stable/@ember/helper/index.d.ts

@@ -322,18 +322,12 @@ declare module '@ember/helper' {
      * as an argument to your components.
      *
      * ```
-     * import { hash } from '@ember/helper';
-     *
      * <template>
      *   {{#each-in (hash givenName='Jen' familyName='Weber') as |key value|}}
      *     <p>{{key}}: {{value}}</p>
      *   {{/each-in}}
      * </template>
      * ```
-     *
-     * **NOTE:** this example uses the experimental `<template>` feature, which is
-     * the only place you need to import `hash` to use it (it is a built-in when
-     * writing standalone `.hbs` files).
      */
     export const hash: HashHelper;
     export interface HashHelper extends Opaque<"helper:hash"> {
@@ -343,7 +337,6 @@ declare module '@ember/helper' {
      * as an argument to your components.
      *
      * ```js
-     * import { array } from '@ember/helper';
      *
      * <template>
      *   <ul>
@@ -352,10 +345,6 @@ declare module '@ember/helper' {
      *   {{/each}}
      *   </ul>
      * </template>
-     *
-     * **NOTE:** this example uses the experimental `<template>` feature, which is
-     * the only place you need to import `array` to use it (it is a built-in when
-     * writing standalone `.hbs` files).
      * ```
      */
     export const array: ArrayHelper;
@@ -378,10 +367,6 @@ declare module '@ember/helper' {
      *
      * This will display the result of `@foo.item1` when `index` is `1`, and
      * `this.foo.item2` when `index` is `2`, etc.
-     *
-     * **NOTE:** this example uses the experimental `<template>` feature, which is
-     * the only place you need to import `concat` to use it (it is a built-in when
-     * writing standalone `.hbs` files).
      */
     export const concat: ConcatHelper;
     export interface ConcatHelper extends Opaque<"helper:concat"> {
@@ -423,10 +408,6 @@ declare module '@ember/helper' {
      *
      * This will display the result of `@foo.item1` when `index` is `1`, and
      * `this.foo.item2` when `index` is `2`, etc.
-     *
-     * **NOTE:** this example uses the experimental `<template>` feature, which is
-     * the only place you need to import `concat` to use it (it is a built-in when
-     * writing standalone `.hbs` files).
      */
     export const get: GetHelper;
     export interface GetHelper extends Opaque<"helper:get"> {

package/types/stable/@ember/object/index.d.ts

@@ -55,9 +55,10 @@ declare module '@ember/object' {
       });
       ```
 
-      Also available as `Function.prototype.observes` if prototype extensions are
-      enabled.
-
+      While observers are still supported, there are [plans to deprecate them](https://github.com/emberjs/rfcs/pull/1115)
+      See the [in-progress deprecation guide](https://github.com/ember-learn/deprecation-app/pull/1407)
+      for guidance on how to avoid using observers.
+     
       @method observer
       @for @ember/object
       @param {String} propertyNames*

package/types/stable/@ember/object/observable.d.ts

@@ -307,6 +307,10 @@ declare module '@ember/object/observable' {
           only a sender and key value as parameters or, if you aren't interested in
           any of these values, to write an observer that has no parameters at all.
       
+          While observers are still supported, there are [plans to deprecate them](https://github.com/emberjs/rfcs/pull/1115)
+          See the [in-progress deprecation guide](https://github.com/ember-learn/deprecation-app/pull/1407)
+          for guidance on how to avoid using observers.
+      
           @method addObserver
           @param {String} key The key to observe
           @param {Object} target The target object to invoke

package/types/stable/@ember/routing/route.d.ts

@@ -821,7 +821,7 @@ declare module '@ember/routing/route' {
       
           Note that for routes with dynamic segments, this hook is not always
           executed. If the route is entered through a transition (e.g. when
-          using the `link-to` Handlebars helper or the `transitionTo` method
+          using the `link-to` helper or the `transitionTo` method
           of routes), and a model context is already provided this hook
           is not called.