ember-source 7.2.0-alpha.4 → 7.2.0-beta.1

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

@@ -3,143 +3,87 @@ declare module '@ember/-internals/glimmer/lib/helpers/component' {
       @module ember
     */
     /**
-      The `{{component}}` helper lets you add instances of `Component` to a
-      template. See [Component](/ember/release/classes/Component) for
-      additional information on how a `Component` functions.
-      `{{component}}`'s primary use is for cases where you want to dynamically
-      change which type of component is rendered as the state of your application
-      changes. This helper has three modes: inline, block, and nested.
-
-      ### Inline Form
-
-      Given the following template:
-
-      ```app/application.hbs
-      {{component this.infographicComponentName}}
-      ```
-
-      And the following application code:
-
-      ```app/controllers/application.js
-      import Controller from '@ember/controller';
-      import { tracked } from '@glimmer/tracking';
-
-      export default class ApplicationController extends Controller {
-        @tracked isMarketOpen = 'live-updating-chart'
-
-        get infographicComponentName() {
-          return this.isMarketOpen ? 'live-updating-chart' : 'market-close-summary';
-        }
-      }
-      ```
+      The `component` helper is used to package a Component with initial arguments.
+      The included arguments can then be merged during the final invocation.
 
-      The `live-updating-chart` component will be appended when `isMarketOpen` is
-      `true`, and the `market-close-summary` component will be appended when
-      `isMarketOpen` is `false`. If the value changes while the app is running,
-      the component will be automatically swapped out accordingly.
-      Note: You should not use this helper when you are consistently rendering the same
-      component. In that case, use standard component syntax, for example:
+      See [Component](/ember/release/modules/@glimmer%2Fcomponent/) for
+      additional information on how a `Component` functions.
 
-      ```app/templates/application.hbs
-      <LiveUpdatingChart />
-      ```
+      This is similar to the concept of Partial Application.
+        
+      For example, given a `FullName` component:
+      
+      ```app/components/full-name.gjs
+      import MyInputComponent from './my-input-component';
+      
+      <template>
+        {{yield (component MyInputComponent value=@model.name placeholder="Username")}}
+      </template>
+      ```
+      
+      The yielded component can be invoked by the calling component.
+      See the following snippet:
+      
+      ```app/components/person-form.gjs
+      import FullName from './full-name';
+        
+      <template>
+        <FullName @model={{@model}} as |Field|>
+          <Field />
+        </FullName>
+      </template>
+      ```
+      
+      Which will output an input whose value is already bound to `@model.name` and `placeholder`
+      is "Username".
+        
+      Any arguments passed at the invocation site of the component will override those applied via
+      the `component` helper. For example, if the invocation site of the component is:
 
-      or
+      ```app/components/person-form.gjs
+      import FullName from './full-name';
 
-      ```app/templates/application.hbs
-      {{live-updating-chart}}
+      <template>
+        <FullName @model={{@model}} as |Field|>
+          <Field @placeholder="Your name" />
+        </FullName>
+      </template>
       ```
 
-      ### Block Form
-
-      Using the block form of this helper is similar to using the block form
-      of a component. Given the following application template:
+      The output will be an input whose value is bound to `@model.name` and `placeholder`
+      is "Your name".
+        
+      The `component` helper is built-in and does not need to be imported.
+        
+      Prior to Strict Mode aka "Template Tag" or gjs, the component helper was also used to invoke
+      components dynamically. This is no longer necessary, and they can be directly invoked, as above.
 
-      ```app/templates/application.hbs
-      {{#component this.infographicComponentName}}
-        Last update: {{this.lastUpdateTimestamp}}
-      {{/component}}
-      ```
-
-      The following controller code:
+      ### Dynamic Component Invocation
 
-      ```app/controllers/application.js
-      import Controller from '@ember/controller';
-      import { computed } from '@ember/object';
+      ```app/templates/application.gjs
+      import Component from '@glimmer/component';
       import { tracked } from '@glimmer/tracking';
+      import { component } from '@ember/helper';
+      import LiveUpdatingChart from '../components/live-updating-chart';
+      import MarketCloseSummary from '../components/market-close-summary';
 
-      export default class ApplicationController extends Controller {
-        @tracked isMarketOpen = 'live-updating-chart'
+      export default class Application extends Component {
+        @tracked isMarketOpen = false;
 
-        get lastUpdateTimestamp() {
-          return new Date();
+        get infographicComponent() {
+          return this.isMarketOpen ? LiveUpdatingChart : MarketCloseSummary;
         }
 
-        get infographicComponentName() {
-          return this.isMarketOpen ? 'live-updating-chart' : 'market-close-summary';
-        }
+        <template>
+          {{!-- The component can be invoked directly --}}
+          <this.infographicComponent />
+        
+          {{!-- The component helper here is no longer necessary --}}
+          {{component this.infographicComponentName}}
+        </template>
       }
       ```
 
-      And the following component template:
-
-      ```app/templates/components/live-updating-chart.hbs
-      {{! chart }}
-      {{yield}}
-      ```
-
-      The `Last Update: {{this.lastUpdateTimestamp}}` will be rendered in place of the `{{yield}}`.
-
-      ### Nested Usage
-
-      The `component` helper can be used to package a component path with initial attrs.
-      The included attrs can then be merged during the final invocation.
-      For example, given a `person-form` component with the following template:
-
-      ```app/templates/components/person-form.hbs
-      {{yield (hash
-        nameInput=(component "my-input-component" value=@model.name placeholder="First Name")
-      )}}
-      ```
-
-      When yielding the component via the `hash` helper, the component is invoked directly.
-      See the following snippet:
-
-      ```
-      <PersonForm as |form|>
-        <form.nameInput @placeholder="Username" />
-      </PersonForm>
-      ```
-
-      or
-      ```
-      {{#person-form as |form|}}
-        {{form.nameInput placeholder="Username"}}
-      {{/person-form}}
-      ```
-
-      Which outputs an input whose value is already bound to `model.name` and `placeholder`
-      is "Username".
-
-      When yielding the component without the `hash` helper use the `component` helper.
-      For example, below is a `full-name` component template:
-
-      ```handlebars
-      {{yield (component "my-input-component" value=@model.name placeholder="Name")}}
-      ```
-
-      ```
-      <FullName as |field|>
-        {{component field placeholder="Full name"}}
-      </FullName>
-      ```
-      or
-      ```
-      {{#full-name as |field|}}
-        {{component field placeholder="Full name"}}
-      {{/full-name}}
-      ```
-
       @method component
       @since 1.11.0
       @for Ember.Templates.helpers

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

@@ -7,13 +7,17 @@ declare module '@ember/-internals/glimmer/lib/helpers/concat' {
 
       Example:
 
-      ```handlebars
-      {{some-component name=(concat firstName " " lastName)}}
+      ```gjs
+      import { concat } from '@ember/helper';
+        
+      <template>
+        {{yield (concat firstName " " lastName)}}
 
-      {{! would pass name="<first name value> <last name value>" to the component}}
+        {{! would yield name="<first name value> <last name value>" to the component}}
+      </template>
       ```
 
-      or for angle bracket invocation, you actually don't need concat at all.
+      For invocation of components, you don't need concat at all.
 
       ```handlebars
       <SomeComponent @name="{{firstName}} {{lastName}}" />

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

@@ -1,6 +1,6 @@
 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
@@ -44,6 +44,8 @@ declare module '@ember/-internals/glimmer/lib/helpers/each-in' {
         {{/each}}
       </ul>
       ```
+        
+      `#each` is a keyword and does not need to be imported.
 
       ### Specifying Keys
 
@@ -110,11 +112,11 @@ declare module '@ember/-internals/glimmer/lib/helpers/each-in' {
       @public
      */
     /**
-      The `{{each-in}}` helper loops over properties on an object.
+      The `{{#each-in}}` keyword loops over properties on an object.
 
       For example, given this component definition:
 
-      ```app/components/developer-details.js
+      ```app/components/developer-details.gjs
       import Component from '@glimmer/component';
       import { tracked } from '@glimmer/tracking';
 
@@ -123,21 +125,19 @@ declare module '@ember/-internals/glimmer/lib/helpers/each-in' {
           "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>
@@ -145,6 +145,8 @@ declare module '@ember/-internals/glimmer/lib/helpers/each-in' {
         <li>age: 42</li>
       </ul>
       ```
+     
+      `#each-in` is a keyword and does not need to be imported.
 
       @method each-in
       @for Ember.Templates.helpers

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

@@ -19,6 +19,8 @@ declare module '@ember/-internals/glimmer/lib/helpers/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

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

@@ -12,13 +12,15 @@ declare module '@ember/-internals/glimmer/lib/helpers/fn' {
       to a component invoked within the loop. Here's how you could use the `fn`
       helper to pass both the function and its arguments together:
 
-        ```app/templates/components/items-listing.hbs
-      {{#each @items as |item|}}
-        <DisplayItem @item=item @select={{fn this.handleSelected item}} />
-      {{/each}}
+      ```app/components/items-listing.gjs
+      <template>
+        {{#each @items as |item|}}
+          <DisplayItem @item=item @select={{fn this.handleSelected item}} />
+        {{/each}}
+      </template>
       ```
 
-      ```app/components/items-list.js
+      ```app/components/items-list.gjs
       import Component from '@glimmer/component';
       import { action } from '@ember/object';
 
@@ -30,7 +32,7 @@ declare module '@ember/-internals/glimmer/lib/helpers/fn' {
       }
       ```
 
-      In this case the `display-item` component will receive a normal function
+      In this case the `DisplayItem` component will receive a normal function
       that it can invoke. When it invokes the function, the `handleSelected`
       function will receive the `item` and any arguments passed, thanks to the
       `fn` helper.
@@ -47,7 +49,7 @@ declare module '@ember/-internals/glimmer/lib/helpers/fn' {
       properly bound to the `items-list`, but let's explore what happens if we
       left out `@action`:
 
-      ```app/components/items-list.js
+      ```app/components/items-list.gjs
       import Component from '@glimmer/component';
 
       export default class ItemsList extends Component {
@@ -63,6 +65,8 @@ declare module '@ember/-internals/glimmer/lib/helpers/fn' {
       are bound (via `@action` or other means) before passing into `fn`!
 
       See also [partial application](https://en.wikipedia.org/wiki/Partial_application).
+     
+      `fn` is built-in and does not need to be imported.
 
       @method fn
       @for @ember/helper

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

@@ -9,28 +9,33 @@ declare module '@ember/-internals/glimmer/lib/helpers/get' {
 
       For example, these two usages are equivalent:
 
-      ```app/components/developer-detail.js
+      ```app/components/developer-detail.gjs
       import Component from '@glimmer/component';
       import { tracked } from '@glimmer/tracking';
+      import { get } from '@ember/object';
 
       export default class extends Component {
         @tracked developer = {
           name: "Sandi Metz",
           language: "Ruby"
         }
+        
+        <template>
+          {{this.developer.name}}
+          {{get this.developer "name"}}
+        </template>
       }
       ```
-
-      ```handlebars
-      {{this.developer.name}}
-      {{get this.developer "name"}}
-      ```
-
+        
       If there were several facts about a person, the `{{get}}` helper can dynamically
       pick one:
 
-      ```app/templates/application.hbs
-      <DeveloperDetail @factName="language" />
+      ```app/templates/application.gjs
+      import DeveloperDetail from '../components/developer-detail';
+      
+      <template>
+        <DeveloperDetail @factName="language" />
+      </template
       ```
 
       ```handlebars
@@ -40,9 +45,10 @@ declare module '@ember/-internals/glimmer/lib/helpers/get' {
       For a more complex example, this template would allow the user to switch
       between showing the user's name and preferred coding language with a click:
 
-      ```app/components/developer-detail.js
+      ```app/components/developer-detail.gjs
       import Component from '@glimmer/component';
       import { tracked } from '@glimmer/tracking';
+      import { get } from '@ember/object';
 
       export default class extends Component {
         @tracked developer = {
@@ -56,28 +62,16 @@ declare module '@ember/-internals/glimmer/lib/helpers/get' {
         showFact(fact) {
           this.currentFact = fact;
         }
-      }
-      ```
-
-      ```app/components/developer-detail.js
-      {{get this.developer this.currentFact}}
+        
+        <template>
+          {{get this.developer this.currentFact}}
 
-      <button {{on 'click' (fn this.showFact "name")}}>Show name</button>
-      <button {{on 'click' (fn this.showFact "language")}}>Show language</button>
-      ```
-
-      The `{{get}}` helper can also respect mutable values itself. For example:
-
-      ```app/components/developer-detail.js
-      <Input @value={{mut (get this.person this.currentFact)}} />
-
-      <button {{on 'click' (fn this.showFact "name")}}>Show name</button>
-      <button {{on 'click' (fn this.showFact "language")}}>Show language</button>
+          <button {{on 'click' (fn this.showFact "name")}}>Show name</button>
+          <button {{on 'click' (fn this.showFact "language")}}>Show language</button>
+        </template>
+      }
       ```
 
-      Would allow the user to swap what fact is being displayed, and also edit
-      that fact via a two-way mutable binding.
-
       The `{{get}}` helper can also be used for array element access via index.
       This would display the value of the first element in the array `this.names`:
 

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

@@ -4,7 +4,7 @@ declare module '@ember/-internals/glimmer/lib/helpers/hash' {
     */
     /**
        Use the `{{hash}}` helper to create a hash to pass as an option to your
-       components. This is specially useful for contextual components where you can
+       components. This is especially useful for contextual components where you can
        just yield a hash:
 
        ```handlebars
@@ -32,6 +32,8 @@ declare module '@ember/-internals/glimmer/lib/helpers/hash' {
          return Object.prototype.toString.apply(obj);
        }
        ```
+     
+       The `hash` helper is a built-in keyword and does not need to be imported as of v7.1.0.
 
        @method hash
        @for @ember/helper