ember-source 7.2.0-alpha.4 → 7.2.0

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

@@ -1,50 +1,97 @@
 declare module '@ember/-internals/glimmer/lib/helpers/each-in' {
     /**
-      The `{{#each}}` helper loops over elements in a collection. It is an extension
+      The `{{#each}}` keyword loops over elements in a collection. It is an extension
       of the base Handlebars `{{#each}}` helper.
 
       The default behavior of `{{#each}}` is to yield its inner block once for every
       item in an array passing the item as the first block parameter.
 
-      Assuming the `@developers` argument contains this array:
+      ```gjs {data-filename="app/components/developer-list.gjs"}
+      import Component from '@glimmer/component';
 
-      ```javascript
-      [{ name: 'Yehuda' },{ name: 'Tom' }, { name: 'Paul' }];
+      export default class DeveloperList extends Component {
+        developers = [
+          { name: 'Yehuda' },
+          { name: 'Tom' },
+          { name: 'Paul' },
+        ];
+
+        <template>
+          <ul>
+            {{#each this.developers as |person|}}
+              <li>Hello, {{person.name}}!</li>
+            {{/each}}
+          </ul>
+        </template>
+      }
       ```
 
-      ```handlebars
-      <ul>
-        {{#each @developers as |person|}}
-          <li>Hello, {{person.name}}!</li>
-        {{/each}}
-      </ul>
-      ```
+      The same rules apply to arrays of primitives:
+
+      ```app/components/developer-names.gjs
+      import Component from '@glimmer/component';
 
-      The same rules apply to arrays of primitives.
+      export default class DeveloperNames extends Component {
+        developerNames = ['Yehuda', 'Tom', 'Paul'];
 
-      ```javascript
-      ['Yehuda', 'Tom', 'Paul']
+        <template>
+          <ul>
+            {{#each this.developerNames as |name|}}
+              <li>Hello, {{name}}!</li>
+            {{/each}}
+          </ul>
+        </template>
+      }
       ```
 
-      ```handlebars
-      <ul>
-        {{#each @developerNames as |name|}}
-          <li>Hello, {{name}}!</li>
-        {{/each}}
-      </ul>
+      `{{#each}}` also supports native JavaScript [`Set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set)
+      values and other iterables:
+
+      ```gjs {data-filename="app/components/developer-set.gjs"}
+      import Component from '@glimmer/component';
+
+      export default class DeveloperSet extends Component {
+        developers = new Set([
+          { name: 'Yehuda' },
+          { name: 'Tom' },
+          { name: 'Paul' },
+        ]);
+
+        <template>
+          <ul>
+            {{#each this.developers as |person|}}
+              <li>Hello, {{person.name}}!</li>
+            {{/each}}
+          </ul>
+        </template>
+      }
       ```
 
-      During iteration, the index of each item in the array is provided as a second block
-      parameter.
+      During iteration, the index of each item in the array is provided as a second
+      block parameter:
 
-      ```handlebars
-      <ul>
-        {{#each @developers as |person index|}}
-          <li>Hello, {{person.name}}! You're number {{index}} in line</li>
-        {{/each}}
-      </ul>
+      ```app/components/developer-list-with-index.gjs
+      import Component from '@glimmer/component';
+
+      export default class DeveloperListWithIndex extends Component {
+        developers = [
+          { name: 'Yehuda' },
+          { name: 'Tom' },
+          { name: 'Paul' },
+        ];
+
+        <template>
+          <ul>
+            {{#each this.developers as |person index|}}
+              <li>Hello, {{person.name}}! You're number {{index}} in line</li>
+            {{/each}}
+          </ul>
+        </template>
+      }
       ```
 
+      `#each` is a keyword and does not need to be imported.
+
       ### Specifying Keys
 
       In order to improve rendering speed, Ember will try to reuse the DOM elements
@@ -59,30 +106,38 @@ declare module '@ember/-internals/glimmer/lib/helpers/each-in' {
       needed. However, in some rare cases, the objects' identities may change even
       though they represent the same underlying data.
 
-      For example:
-
-      ```javascript
-      people.map(person => {
-        return { ...person, type: 'developer' };
-      });
-      ```
+      For example, mapping over `people` produces a new array of new objects on each
+      render. Use `key` so Ember can match items across those renders:
 
-      In this case, each time the `people` array is `map`-ed over, it will produce
-      an new array with completely different objects between renders. In these cases,
-      you can help Ember determine how these objects related to each other with the
-      `key` option:
+      ```gjs {data-filename="app/components/mapped-developers.gjs"}
+      import Component from '@glimmer/component';
 
-      ```handlebars
-      <ul>
-        {{#each @developers key="name" as |person|}}
-          <li>Hello, {{person.name}}!</li>
-        {{/each}}
-      </ul>
+      export default class MappedDevelopers extends Component {
+        people = [
+          { name: 'Yehuda' },
+          { name: 'Tom' },
+          { name: 'Paul' },
+        ];
+
+        get developers() {
+          return this.people.map((person) => {
+            return { ...person, type: 'developer' };
+          });
+        }
+
+        <template>
+          <ul>
+            {{#each this.developers key="name" as |person|}}
+              <li>Hello, {{person.name}}!</li>
+            {{/each}}
+          </ul>
+        </template>
+      }
       ```
 
       By doing so, Ember will use the value of the property specified (`person.name`
       in the example) to find a "match" from the previous render. That is, if Ember
-      has previously seen an object from the `@developers` array with a matching
+      has previously seen an object from the `developers` array with a matching
       name, its DOM elements will be re-used.
 
       There are two special values for `key`:
@@ -95,49 +150,58 @@ declare module '@ember/-internals/glimmer/lib/helpers/each-in' {
       `{{#each}}` can have a matching `{{else}}`. The contents of this block will render
       if the collection is empty.
 
-      ```handlebars
-      <ul>
-        {{#each @developers as |person|}}
-          <li>{{person.name}} is available!</li>
-        {{else}}
-          <li>Sorry, nobody is available for this task.</li>
-        {{/each}}
-      </ul>
+      ```gjs {data-filename="app/components/available-developers.gjs"}
+      import Component from '@glimmer/component';
+
+      export default class AvailableDevelopers extends Component {
+        developers = [];
+
+        <template>
+          <ul>
+            {{#each this.developers as |person|}}
+              <li>{{person.name}} is available!</li>
+            {{else}}
+              <li>Sorry, nobody is available for this task.</li>
+            {{/each}}
+          </ul>
+        </template>
+      }
       ```
 
       @method each
-      @for Ember.Templates.helpers
+      @for Keywords
+      @static
+      @noimport
       @public
      */
     /**
-      The `{{each-in}}` helper loops over properties on an object.
+      The `{{#each-in}}` keyword loops over properties on an object, or entries in a
+      native JavaScript [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map).
 
       For example, given this component definition:
 
-      ```app/components/developer-details.js
+      ```gjs {data-filename="app/components/developer-details.gjs"}
       import Component from '@glimmer/component';
       import { tracked } from '@glimmer/tracking';
 
-      export default class extends Component {
+      export default class DeveloperDetails extends Component {
         @tracked developer = {
-          "name": "Shelly Sails",
-          "age": 42
+          name: 'Shelly Sails',
+          age: 42,
         };
+
+        <template>
+          <ul>
+            {{#each-in this.developer as |key value|}}
+              <li>{{key}}: {{value}}</li>
+            {{/each-in}}
+          </ul>
+        </template>
       }
       ```
 
       This template would display all properties on the `developer`
-      object in a list:
-
-      ```app/components/developer-details.hbs
-      <ul>
-        {{#each-in this.developer as |key value|}}
-          <li>{{key}}: {{value}}</li>
-        {{/each-in}}
-      </ul>
-      ```
-
-      Outputting their name and age:
+      object in a list, outputting their name and age:
 
       ```html
       <ul>
@@ -146,8 +210,55 @@ declare module '@ember/-internals/glimmer/lib/helpers/each-in' {
       </ul>
       ```
 
+      The same pattern works with a `Map`:
+
+      ```gjs {data-filename="app/components/developer-map.gjs"}
+      import Component from '@glimmer/component';
+
+      export default class DeveloperMap extends Component {
+        map = new Map([
+          ['name', 'Shelly Sails'],
+          ['age', 42],
+        ]);
+
+        <template>
+          <ul>
+            {{#each-in this.map as |key value|}}
+              <li>{{key}}: {{value}}</li>
+            {{/each-in}}
+          </ul>
+        </template>
+      }
+      ```
+
+      When a `Map` uses object keys, you can pass `key="@identity"` to explicitly
+      track entries across re-renders using the JavaScript identity of each key:
+
+      ```gjs {data-filename="app/components/object-keyed-map.gjs"}
+      import Component from '@glimmer/component';
+
+      export default class ObjectKeyedMap extends Component {
+        map = new Map([
+          [{ name: 'one' }, 'foo'],
+          [{ name: 'two' }, 'bar'],
+        ]);
+
+        <template>
+          <ul>
+            {{#each-in this.map key="@identity" as |key value|}}
+              <li>{{key.name}}: {{value}}</li>
+            {{/each-in}}
+          </ul>
+        </template>
+      }
+      ```
+
+      `#each-in` is a keyword and does not need to be imported.
+
       @method each-in
-      @for Ember.Templates.helpers
+      @static
+      @noimport
+      @for Keywords
       @public
       @since 2.1.0
     */

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

@@ -2,28 +2,6 @@ declare module '@ember/-internals/glimmer/lib/helpers/element' {
     /**
       @module @ember/helper
     */
-    /**
-      The `element` helper lets you dynamically set the tag name of an element.
-
-      ```handlebars
-      {{#let (element @tagName) as |Tag|}}
-        <Tag class="my-element">Hello</Tag>
-      {{/let}}
-      ```
-
-      When `@tagName` is `"h1"`, this renders `<h1 class="my-element">Hello</h1>`.
-
-      When `@tagName` is an empty string `""`, the block content is rendered without
-      a wrapping element.
-
-      Passing `null`, `undefined`, or non-string values will throw an assertion error.
-
-      Changing the tag name will tear down and recreate the element and its contents.
-
-      @method element
-      @for Ember.Templates.helpers
-      @public
-    */
     const _default: object;
     export default _default;
 }

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

@@ -1,75 +1,45 @@
 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
+      ```gjs {data-filename="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
+      @static
+      @for Keywords
       @public
     */
     const _default: object;

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
@@ -111,7 +107,9 @@ declare module '@ember/-internals/glimmer/lib/helpers/readonly' {
 
       @method readonly
       @param {Object} [attr] the read-only attribute.
-      @for Ember.Templates.helpers
+      @for Keywords
+      @noimport
+      @static
       @private
     */
     const _default: object;

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

@@ -1,6 +1,6 @@
 declare module '@ember/-internals/glimmer/lib/helpers/unbound' {
     /**
-    @module ember
+    @module @ember/helper
     */
     /**
       The `{{unbound}}` helper disconnects the one-way binding of a property,
@@ -24,9 +24,13 @@ declare module '@ember/-internals/glimmer/lib/helpers/unbound' {
 
       The `unbound` helper only accepts a single argument, and it return an
       unbound value.
+     
+     `unbound` is a template keyword and does not need to be imported.
 
       @method unbound
-      @for Ember.Templates.helpers
+      @static
+      @noimport
+      @for Keywords
       @public
     */
     const _default: object;

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

@@ -1,7 +1,4 @@
 declare module '@ember/-internals/glimmer/lib/helpers/unique-id' {
-    /**
-    @module ember
-    */
     const _default: object;
     export default _default;
     export function uniqueId(): string;

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

@@ -6,7 +6,6 @@ declare module '@ember/-internals/glimmer/lib/renderer' {
     import type { CurriedValue } from "@glimmer/runtime/lib/curried-value";
     import { clientBuilder } from "@glimmer/runtime/lib/vm/element-builder";
     import type { SimpleDocument, SimpleElement, SimpleNode } from "@simple-dom/interface";
-    import RSVP from "rsvp";
     import type Component from "@ember/-internals/glimmer/lib/component";
     import type ClassicComponent from "@ember/-internals/glimmer/lib/component";
     import { BOUNDS } from "@ember/-internals/glimmer/lib/component-managers/curly";
@@ -58,7 +57,7 @@ declare module '@ember/-internals/glimmer/lib/renderer' {
         destroy(): void;
     }
     export function _resetRenderers(): void;
-    export function renderSettled(): RSVP.Promise<void>;
+    export function renderSettled(): Promise<void>;
     interface ViewRegistry {
         [viewId: string]: unknown;
     }

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 }}
+      ```gjs {data-filename="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,21 +21,28 @@ 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.
       @param {Object} [model] Object that will be set as
                               the model of the engine.
-      @for Ember.Templates.helpers
+      @for Keywords
+      @static
+      @noimport
       @public
     */
     export const mountHelper: object;

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

@@ -1,26 +1,38 @@
 declare module '@ember/-internals/glimmer/lib/syntax/outlet' {
+    /**
+     @module @ember/helper
+     */
     /**
       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:
-
-      ```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>
+      application's `application.gjs` file:
 
-      <MyFooter />
+      ```gjs {data-filename="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
+      @for Keywords
+      @static
+      @noimport
       @public
     */
     export const outletHelper: object;

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.