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

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

@@ -4,39 +4,12 @@ declare module '@ember/array' {
     import MutableEnumerable from "@ember/enumerable/mutable";
     import Observable from "@ember/object/observable";
     import type { MethodNamesOf, MethodParams, MethodReturns } from "@ember/-internals/utility-types";
+    import isArray from "@ember/array/lib/is-array";
     export { default as makeArray } from "@ember/array/make";
     export type EmberArrayLike<T> = EmberArray<T> | NativeArray<T>;
     export function uniqBy<T>(array: T[] | EmberArray<T>, keyOrFunc?: string | ((item: T) => unknown)): T[] | EmberArray<T>;
     export function removeAt<T, A extends T[] | MutableArray<T>>(array: A, index: number, len?: number): A;
-    /**
-      Returns true if the passed object is an array or Array-like.
-
-      Objects are considered Array-like if any of the following are true:
-
-        - the object is a native Array
-        - the object has an objectAt property
-        - the object is an Object, and has a length property
-
-      Unlike `typeOf` this method returns true even if the passed object is
-      not formally an array but appears to be array-like (i.e. implements `Array`)
-
-      ```javascript
-      import { isArray } from '@ember/array';
-      import ArrayProxy from '@ember/array/proxy';
-
-      isArray();                                      // false
-      isArray([]);                                    // true
-      isArray(ArrayProxy.create({ content: [] }));    // true
-      ```
-
-      @method isArray
-      @static
-      @for @ember/array
-      @param {Object} obj The object to test
-      @return {Boolean} true if the passed object is an array or Array-like
-      @public
-    */
-    export function isArray(obj: unknown): obj is ArrayLike<unknown> | EmberArray<unknown>;
+    export { isArray };
     /**
       This mixin implements Observer-friendly Array-like behavior. It is not a
       concrete implementation, but it can be used up by other classes that want
@@ -1274,6 +1247,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/array/lib/is-array.d.ts

@@ -0,0 +1,35 @@
+declare module '@ember/array/lib/is-array' {
+    import type EmberArray from "@ember/array";
+    /**
+     @module @ember/array
+    */
+    /**
+      Returns true if the passed object is an array or Array-like.
+
+      Objects are considered Array-like if any of the following are true:
+
+        - the object is a native Array
+        - the object has an objectAt property
+        - the object is an Object, and has a length property
+
+      Unlike `typeOf` this method returns true even if the passed object is
+      not formally an array but appears to be array-like (i.e. implements `Array`)
+
+      ```javascript
+      import { isArray } from '@ember/array';
+      import ArrayProxy from '@ember/array/proxy';
+
+      isArray();                                      // false
+      isArray([]);                                    // true
+      isArray(ArrayProxy.create({ content: [] }));    // true
+      ```
+
+      @method isArray
+      @static
+      @for @ember/array
+      @param {Object} obj The object to test
+      @return {Boolean} true if the passed object is an array or Array-like
+      @public
+    */
+    export default function isArray(obj: unknown): obj is ArrayLike<unknown> | EmberArray<unknown>;
+}

package/types/stable/@ember/component/template-only.d.ts

@@ -14,9 +14,7 @@ declare module '@ember/component/template-only' {
 
       Addons may want to use this method directly to ensure that a template-only component is treated consistently in all Ember versions (Ember versions
       before 4.0 have a "template-only-glimmer-components" optional feature that causes a standalone `.hbs` file to be interpreted differently).
-
-      @example
-
+        
       ```js
       import templateOnly from '@ember/component/template-only';
 

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/reactive/collections.d.ts

@@ -16,7 +16,6 @@ declare module '@ember/reactive/collections' {
      *
      * See [MDN for more information](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)
      *
-     * @example
      * ```javascript
      * import { trackedArray } from '@ember/reactive/collections';
      * import { on } from '@ember/modifier';
@@ -58,7 +57,6 @@ declare module '@ember/reactive/collections' {
      *
      * See [MDN for more information](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
      *
-     * @example
      * ```gjs
      * import { trackedObject } from '@ember/reactive/collections';
      * import { on } from '@ember/modifier';
@@ -100,7 +98,6 @@ declare module '@ember/reactive/collections' {
      *
      * See [MDN for more information](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set)
      *
-     * @example
      * ```gjs
      * import { trackedSet } from '@ember/reactive/collections';
      * import { on } from '@ember/modifier';
@@ -146,7 +143,6 @@ declare module '@ember/reactive/collections' {
      *
      * See [MDN for more information](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet)
      *
-     * @example
      * ```gjs
      * import { trackedWeakSet } from '@ember/reactive/collections';
      * import { on } from '@ember/modifier';
@@ -183,7 +179,6 @@ declare module '@ember/reactive/collections' {
      *
      * See [MDN for more information](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)
      *
-     * @example
      * ```gjs
      * import { trackedMap } from '@ember/reactive/collections';
      * import { on } from '@ember/modifier';
@@ -229,7 +224,6 @@ declare module '@ember/reactive/collections' {
      *
      * See [MDN for more information](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap)
      *
-     * @example
      * ```gjs
      * import { trackedWeakMap } from '@ember/reactive/collections';
      * import { on } from '@ember/modifier';

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

@@ -59,7 +59,7 @@ declare module '@ember/renderer' {
       @returns {Promise<void>} a promise which fulfills when rendering has completed
       @public
     */
-    export { renderSettled } from "@ember/-internals/glimmer/lib/renderer";
+    export { renderSettled } from "@ember/-internals/glimmer/lib/base-renderer";
     /**
      * Render a component into a DOM element.
      *
@@ -76,5 +76,5 @@ declare module '@ember/renderer' {
      * @param {Object} [options.args] Optionally pass args in to the component. These may be reactive as long as it is an object or object-like
      * @public
      */
-    export { renderComponent } from "@ember/-internals/glimmer/lib/renderer";
+    export { renderComponent } from "@ember/-internals/glimmer/lib/base-renderer";
 }

package/types/stable/@ember/routing/lib/generate_controller.d.ts

@@ -1,6 +1,6 @@
 declare module '@ember/routing/lib/generate_controller' {
     import type { InternalFactory, default as Owner } from "@ember/-internals/owner";
-    import Controller from "@ember/controller";
+    import type Controller from "@ember/controller";
     /**
      @module @ember/routing
     */

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.
       
@@ -948,7 +948,7 @@ declare module '@ember/routing/route' {
           the framework will use it.
           If it is not defined, a basic `Controller` instance would be used.
       
-          @example Behavior of a basic Controller
+          Example Behavior of a basic Controller
       
           ```app/routes/post.js
           import Route from '@ember/routing/route';

package/types/stable/@ember/routing/router-service.d.ts

@@ -17,7 +17,7 @@ declare module '@ember/routing/router-service' {
        In this example, the Router service is injected into a component to initiate a transition
        to a dedicated route:
 
-       ```app/components/example.js
+       ```app/components/example.gjs
        import Component from '@glimmer/component';
        import { action } from '@ember/object';
        import { service } from '@ember/service';
@@ -58,7 +58,7 @@ declare module '@ember/routing/router-service' {
            specific model from a Component in the first action, and in the second we trigger
            a query-params only transition.
       
-           ```app/components/example.js
+           ```app/components/example.gjs
            import Component from '@glimmer/component';
            import { action } from '@ember/object';
            import { service } from '@ember/service';
@@ -137,11 +137,15 @@ declare module '@ember/routing/router-service' {
           In this example, the URL for the `author.books` route for a given author
           is copied to the clipboard.
       
-          ```app/templates/application.hbs
-          <CopyLink @author={{hash id="tomster" name="Tomster"}} />
+          ```app/templates/application.gjs
+          import CopyLink from '../components/copy-link';
+            
+          <template>
+            <CopyLink @author={{hash id="tomster" name="Tomster"}} />
+          </template>
           ```
       
-          ```app/components/copy-link.js
+          ```app/components/copy-link.gjs
           import Component from '@glimmer/component';
           import { service } from '@ember/service';
           import { action } from '@ember/object';
@@ -164,11 +168,15 @@ declare module '@ember/routing/router-service' {
           Just like with `transitionTo` and `replaceWith`, `urlFor` can also handle
           query parameters.
       
-          ```app/templates/application.hbs
-          <CopyLink @author={{hash id="tomster" name="Tomster"}} />
+          ```app/templates/application.gjs
+          import CopyLink from '../components/copy-link';
+      
+          <template>
+            <CopyLink @author={{hash id="tomster" name="Tomster"}} />
+          </template>
           ```
       
-          ```app/components/copy-link.js
+          ```app/components/copy-link.gjs
           import Component from '@glimmer/component';
           import { service } from '@ember/service';
           import { action } from '@ember/object';
@@ -206,7 +214,7 @@ declare module '@ember/routing/router-service' {
       
            In the following example, `isActive` will return `true` if the current route is `/posts`.
       
-           ```app/components/posts.js
+           ```app/components/posts.gjs
            import Component from '@glimmer/component';
            import { service } from '@ember/service';
       
@@ -222,7 +230,7 @@ declare module '@ember/routing/router-service' {
            The next example includes a dynamic segment, and will return `true` if the current route is `/posts/1`,
            assuming the post has an id of 1:
       
-           ```app/components/posts.js
+           ```app/components/posts.gjs
            import Component from '@glimmer/component';
            import { service } from '@ember/service';
       
@@ -257,7 +265,7 @@ declare module '@ember/routing/router-service' {
            In the following example `recognize` is used to verify if a path belongs to our
            application before transitioning to it.
       
-           ```
+           ```js
            import Component from '@ember/component';
            import { service } from '@ember/service';
       
@@ -568,7 +576,7 @@ declare module '@ember/routing/router-service' {
           and doesn't change the active route).
       
           Usage example:
-          ```app/components/header.js
+          ```app/components/header.gjs
             import Component from '@glimmer/component';
             import { service } from '@ember/service';
             import { notEmpty } from '@ember/object/computed';

package/types/stable/@glimmer/runtime/lib/component/template-only.d.ts

@@ -25,8 +25,6 @@ declare module '@glimmer/runtime/lib/component/template-only' {
       to use these semantics for its templates but cannot be certain it will only be consumed by applications that have enabled the
       `template-only-glimmer-components` optional feature.
 
-      @example
-
       ```js
       import { templateOnlyComponent } from '@glimmer/runtime';
 

package/types/stable/@glimmer/runtime/lib/dom/sanitized-values.d.ts

@@ -1,5 +1,5 @@
 declare module '@glimmer/runtime/lib/dom/sanitized-values' {
-    import type { SimpleElement } from "@glimmer/interfaces";
-    export function requiresSanitization(tagName: string, attribute: string): boolean;
+    import type { Nullable, SimpleElement } from "@glimmer/interfaces";
+    export function requiresSanitization(tagName: Nullable<string>, attribute: string): boolean;
     export function sanitizeAttributeValue(element: SimpleElement, attribute: string, value: unknown): unknown;
 }

package/types/stable/@glimmer/runtime/lib/helpers/array.d.ts

@@ -12,7 +12,7 @@ declare module '@glimmer/runtime/lib/helpers/array' {
        ```
         or
        ```handlebars
-       {{my-component people=(array
+       {{yield people=(array
          'Tom Dale'
          'Yehuda Katz'
          this.myOtherPerson)

package/types/stable/@glimmer/runtime/lib/helpers/concat.d.ts

@@ -4,10 +4,15 @@ declare module '@glimmer/runtime/lib/helpers/concat' {
 
       Example:
 
-      ```handlebars
-      {{some-component name=(concat firstName " " lastName)}}
 
-      {{! would pass name="<first name value> <last name value>" to the component}}
+      ```gjs
+      import { concat } from '@ember/helper';
+
+      <template>
+      {{yield (concat firstName " " lastName)}}
+
+      {{! 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.

package/types/stable/@glimmer/runtime/lib/helpers/fn.d.ts

@@ -9,13 +9,17 @@ declare module '@glimmer/runtime/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
+      import DisplayItem from './display-item';
+        
+      <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';
 
@@ -26,7 +30,7 @@ declare module '@glimmer/runtime/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.
@@ -43,7 +47,7 @@ declare module '@glimmer/runtime/lib/helpers/fn' {
       `handleSelected` is properly bound to the `items-list`, but let's explore what
       happens if we left out the arrow function:
 
-      ```app/components/items-list.js
+      ```app/components/items-list.gjs
       import Component from '@glimmer/component';
 
       export default class ItemsList extends Component {
@@ -60,6 +64,8 @@ declare module '@glimmer/runtime/lib/helpers/fn' {
 
       See also [partial application](https://en.wikipedia.org/wiki/Partial_application).
 
+      `fn` is built-in and does not require any additional imports.
+     
       @method fn
       @public
     */