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

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

@@ -1,7 +1,7 @@
 declare module '@ember/-internals/glimmer/lib/component-managers/outlet' {
     import type { InternalOwner } from "@ember/-internals/owner";
     import type { Nullable } from "@ember/-internals/utility-types";
-    import EngineInstance from "@ember/engine/instance";
+    import type EngineInstance from "@ember/engine/instance";
     import type { CompilableProgram, ComponentDefinition, CustomRenderNode, Destroyable, Environment, InternalComponentCapabilities, VMArguments, WithCreateInstance, WithCustomDebugRenderTree } from "@glimmer/interfaces";
     import type { Reference } from "@glimmer/reference/lib/reference";
     import type { DynamicScope } from "@ember/-internals/glimmer/lib/renderer";

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

@@ -168,6 +168,12 @@ declare module '@ember/-internals/glimmer/lib/component' {
       API documentation for Template-only or Glimmer components, it is [available
       here](/ember/release/modules/@glimmer%2Fcomponent).
 
+      Note: Prior to Ember 6.8, by default, components were authored in paired `.hbs` and `.js`
+      files. This is still supported, but the default authoring format is now `.gjs` or "template tag".
+      The documentation for `@ember/component` still refers to the older authoring format. To read about
+      the new authoring format, see the
+      [Glimmer Component API documentation](/ember/release/modules/@glimmer%2Fcomponent).
+        
       ## Defining a Classic Component
 
       If you want to customize the component in order to handle events, transform
@@ -194,7 +200,7 @@ declare module '@ember/-internals/glimmer/lib/component' {
 
       And then use it in the component's template:
 
-      ```app/templates/components/person-profile.hbs
+      ```app/components/person-profile.hbs
       <h1>{{this.displayName}}</h1>
       {{yield}}
       ```
@@ -582,7 +588,7 @@ declare module '@ember/-internals/glimmer/lib/component' {
       The `layout` property should be set to the default export of a template
       module, which is the name of a template file without the `.hbs` extension.
 
-      ```app/templates/components/person-profile.hbs
+      ```app/components/person-profile.hbs
       <h1>Person's Title</h1>
       <div class='details'>{{yield}}</div>
       ```

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

@@ -26,17 +26,7 @@ declare module '@ember/-internals/glimmer/lib/glimmer-tracking-docs' {
       property changes, any templates that used that property, directly or
       indirectly, will rerender. For instance, consider this component:
 
-      ```handlebars
-      <div>Count: {{this.count}}</div>
-      <div>Times Ten: {{this.timesTen}}</div>
-      <div>
-        <button {{on "click" this.plusOne}}>
-          Plus One
-        </button>
-      </div>
-      ```
-
-      ```javascript
+      ```gjs
       import Component from '@glimmer/component';
       import { tracked } from '@glimmer/tracking';
       import { action } from '@ember/object';
@@ -52,6 +42,16 @@ declare module '@ember/-internals/glimmer/lib/glimmer-tracking-docs' {
         plusOne() {
           this.count += 1;
         }
+        
+        <template>
+          <div>Count: {{this.count}}</div>
+          <div>Times Ten: {{this.timesTen}}</div>
+          <div>
+            <button {{on "click" this.plusOne}}>
+              Plus One
+            </button>
+          </div>
+        </template>
       }
       ```
 
@@ -61,7 +61,7 @@ declare module '@ember/-internals/glimmer/lib/glimmer-tracking-docs' {
       will cause a rerender when updated - this includes through method calls and
       other means:
 
-      ```javascript
+      ```gjs
       import Component from '@glimmer/component';
       import { tracked } from '@glimmer/tracking';
 

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

@@ -0,0 +1,10 @@
+declare module '@ember/-internals/glimmer/lib/helper-brand' {
+    /**
+     * The brand for classic (class-based) helpers lives in its own module so that
+     * code which only needs to *detect* classic helpers (e.g. the resolver) does
+     * not have to import the classic `Helper` base class (and with it the classic
+     * object model: `EmberObject`, `Mixin`, meta, etc.).
+     */
+    export const IS_CLASSIC_HELPER: unique symbol;
+    export function isClassicHelper(obj: object): boolean;
+}

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

@@ -4,6 +4,8 @@ declare module '@ember/-internals/glimmer/lib/helper' {
     */
     import { FrameworkObject } from "@ember/object/-internals";
     import type { DirtyableTag } from "@glimmer/interfaces";
+    import { IS_CLASSIC_HELPER } from "@ember/-internals/glimmer/lib/helper-brand";
+    export { isClassicHelper } from "@ember/-internals/glimmer/lib/helper-brand";
     const RECOMPUTE_TAG: unique symbol;
     type GetOr<T, K, Else> = K extends keyof T ? T[K] : Else;
     type Args<S> = GetOr<S, "Args", {}>;
@@ -20,7 +22,6 @@ declare module '@ember/-internals/glimmer/lib/helper' {
         destroy(): void;
         [RECOMPUTE_TAG]: DirtyableTag;
     }
-    const IS_CLASSIC_HELPER: unique symbol;
     export interface SimpleHelper<S> {
         compute: (positional: Positional<S>, named: Named<S>) => Return<S>;
     }
@@ -29,20 +30,32 @@ declare module '@ember/-internals/glimmer/lib/helper' {
       Ember Helpers are functions that can compute values, and are used in templates.
       For example, this code calls a helper named `format-currency`:
 
-      ```app/templates/application.hbs
-      <Cost @cents={{230}} />
+      ```app/templates/application.gjs
+      import Cost from '../components/cost';
+
+      <template>
+        <Cost @cents={{230}} />
+      </template>
       ```
 
-      ```app/components/cost.hbs
-      <div>{{format-currency @cents currency="$"}}</div>
+      ```app/components/cost.gjs
+      import formatCurrency from '../helpers/format-currency';
+
+      <template>
+        <div>{{formatCurrency @cents currency="$"}}</div>
+      </template>
       ```
 
       Additionally a helper can be called as a nested helper.
       In this example, we show the formatted currency value if the `showMoney`
       named argument is truthy.
 
-      ```handlebars
-      {{if @showMoney (format-currency @cents currency="$")}}
+      ```gjs
+      import formatCurrency from '../helpers/format-currency';
+
+      <template>
+        {{if @showMoney (formatCurrency @cents currency="$")}}
+      </template>
       ```
 
       Helpers defined using a class must provide a `compute` function. For example:
@@ -128,8 +141,6 @@ declare module '@ember/-internals/glimmer/lib/helper' {
         */
         recompute(): void;
     }
-    export function isClassicHelper(obj: object): boolean;
-    export const CLASSIC_HELPER_MANAGER: import("@glimmer/interfaces").Helper<object> | import("@glimmer/manager").CustomHelperManager<object>;
     /**
      * The type of a function-based helper.
      *
@@ -169,5 +180,4 @@ declare module '@ember/-internals/glimmer/lib/helper' {
         Return: R;
     }>;
     export function helper<S>(helperFn: (positional: Positional<S>, named: Named<S>) => Return<S>): FunctionBasedHelper<S>;
-    export {};
 }

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

@@ -15,7 +15,7 @@ declare module '@ember/-internals/glimmer/lib/helpers/array' {
        ```
         or
        ```handlebars
-       {{my-component people=(array
+       {{yield people=(array
          'Tom Dale'
          'Yehuda Katz'
          this.myOtherPerson)
@@ -29,6 +29,8 @@ declare module '@ember/-internals/glimmer/lib/helpers/array' {
        ```
 
        Where the 3rd item in the array is bound to updates of the `myOtherPerson` property.
+     
+       The `array` helper is built-in keyword and does not need to be imported as of v7.1.0.
 
        @method array
        @for @ember/helper

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