ember-source 7.3.0-alpha.5 → 7.4.0-alpha.1

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

@@ -6,45 +6,90 @@ declare module '@ember/-internals/glimmer/lib/helpers/each-in' {
       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' },
+        ];
 
-      ```handlebars
-      <ul>
-        {{#each @developers as |person|}}
-          <li>Hello, {{person.name}}!</li>
-        {{/each}}
-      </ul>
+        <template>
+          <ul>
+            {{#each this.developers as |person|}}
+              <li>Hello, {{person.name}}!</li>
+            {{/each}}
+          </ul>
+        </template>
+      }
       ```
 
-      The same rules apply to arrays of primitives.
+      The same rules apply to arrays of primitives:
+
+      ```gjs {data-filename="app/components/developer-names.gjs"}
+      import Component from '@glimmer/component';
+
+      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>
+      ```gjs {data-filename="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
@@ -61,71 +106,90 @@ 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:
+      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:
 
-      ```javascript
-      people.map(person => {
-        return { ...person, type: 'developer' };
-      });
-      ```
+      ```gjs {data-filename="app/components/mapped-developers.gjs"}
+      import Component from '@glimmer/component';
 
-      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:
+      export default class MappedDevelopers extends Component {
+        people = [
+          { name: 'Yehuda' },
+          { name: 'Tom' },
+          { name: 'Paul' },
+        ];
 
-      ```handlebars
-      <ul>
-        {{#each @developers key="name" as |person|}}
-          <li>Hello, {{person.name}}!</li>
-        {{/each}}
-      </ul>
+        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`:
 
+        * `@identity` - The item in the array itself. This is the default.
         * `@index` - The index of the item in the array.
-        * `@identity` - The item in the array itself.
 
       ### {{else}} condition
 
       `{{#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}}` keyword 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.gjs
+      ```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|}}
@@ -145,11 +209,80 @@ declare module '@ember/-internals/glimmer/lib/helpers/each-in' {
         <li>age: 42</li>
       </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.
 
+      ### Specifying Keys
+
+      Like `{{#each}}`, `{{#each-in}}` accepts a `key` option to decide which DOM
+      elements can be reused between renders. Since `{{#each-in}}` yields two block
+      params, the special values pick which one is used:
+
+        * `@identity` - The second block param: the property's value. This is the
+          default. Changing a value replaces that entry's DOM instead of updating it
+          in place.
+        * `@key` - The first block param: the property name, or for a `Map`, its key.
+
+      Any other string is a path, looked up on the value: `key="id"` keys each entry
+      by its `value.id`.
+
+      For example, `@key` keeps each entry's DOM as its score changes, so anything
+      stateful inside it — focus, a running transition, a component instance — survives
+      the update:
+
+      ```handlebars
+      {{#each-in this.scores key="@key" as |player score|}}
+        <PlayerScore @name={{player}} @score={{score}} />
+      {{/each-in}}
+      ```
+
       @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,30 +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.
-     
-      The `element` helper is built-in and does not need to be imported.
-
-      @method element
-      @for Ember.Templates.helpers
-      @public
-    */
     const _default: object;
     export default _default;
 }

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

@@ -16,7 +16,7 @@ declare module '@ember/-internals/glimmer/lib/helpers/mut' {
 
       The child `Component` would invoke the function with the new click count:
 
-      ```app/components/my-child.gjs
+      ```gjs {data-filename="app/components/my-child.gjs"}
       import Component from '@glimmer/component';
       import { action } from '@ember/object';
         
@@ -38,7 +38,8 @@ declare module '@ember/-internals/glimmer/lib/helpers/mut' {
 
       @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

@@ -107,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/syntax/mount.d.ts

@@ -6,7 +6,7 @@ declare module '@ember/-internals/glimmer/lib/syntax/mount' {
 
       For example, the following template mounts the `ember-chat` engine:
 
-      ```app/templates/application.gjs
+      ```gjs {data-filename="app/templates/application.gjs"}
       {{mount "ember-chat"}}
       ```
 
@@ -40,7 +40,9 @@ declare module '@ember/-internals/glimmer/lib/syntax/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,10 +1,13 @@
 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.gjs` file:
 
-      ```app/templates/application.gjs
+      ```gjs {data-filename="app/templates/application.gjs"}
       import MyHeader from '../components/my-header';
       import MyFooter from '../components/my-footer';
         
@@ -27,7 +30,9 @@ declare module '@ember/-internals/glimmer/lib/syntax/outlet' {
       `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;