ember-source 7.2.0-alpha.4 → 7.2.0

package/types/stable/@ember/object/compat.d.ts

@@ -36,38 +36,6 @@ declare module '@ember/object/compat' {
       }
       ```
 
-      Classic Example:
-
-      ```js
-      import { tracked } from '@glimmer/tracking';
-      import { dependentKeyCompat } from '@ember/object/compat';
-      import EmberObject, { computed, observer, set } from '@ember/object';
-
-      const Person = EmberObject.extend({
-        firstName: tracked(),
-        lastName: tracked(),
-
-        fullName: dependentKeyCompat(function() {
-          return `${this.firstName} ${this.lastName}`;
-        }),
-      });
-
-      const Profile = EmberObject.extend({
-        person: null,
-
-        helloMessage: computed('person.fullName', function() {
-          return `Hello, ${this.person.fullName}!`;
-        }),
-
-        onNameUpdated: observer('person.fullName', function() {
-          console.log('person name updated!');
-        }),
-      });
-      ```
-
-      `dependentKeyCompat()` can receive a getter function or an object containing
-      `get`/`set` methods when used in classic classes, like computed properties.
-
       In general, only properties which you _expect_ to be watched by older,
       untracked clases should be marked as dependency compatible. The decorator is
       meant as an interop layer for parts of Ember's older classic APIs, and should

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/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
+       ```gjs {data-filename="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
+           ```gjs {data-filename="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"}} />
+          ```gjs {data-filename="app/templates/application.gjs"}
+          import CopyLink from '../components/copy-link';
+            
+          <template>
+            <CopyLink @author={{hash id="tomster" name="Tomster"}} />
+          </template>
           ```
       
-          ```app/components/copy-link.js
+          ```gjs {data-filename="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"}} />
+          ```gjs {data-filename="app/templates/application.gjs"}
+          import CopyLink from '../components/copy-link';
+      
+          <template>
+            <CopyLink @author={{hash id="tomster" name="Tomster"}} />
+          </template>
           ```
       
-          ```app/components/copy-link.js
+          ```gjs {data-filename="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
+           ```gjs {data-filename="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
+           ```gjs {data-filename="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
+          ```gjs {data-filename="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

@@ -1,36 +1,3 @@
 declare module '@glimmer/runtime/lib/helpers/array' {
-    /**
-       Use the `{{array}}` helper to create an array to pass as an option to your
-       components.
-
-       ```handlebars
-       <MyComponent @people={{array
-         'Tom Dale'
-         'Yehuda Katz'
-         this.myOtherPerson}}
-       />
-       ```
-        or
-       ```handlebars
-       {{my-component people=(array
-         'Tom Dale'
-         'Yehuda Katz'
-         this.myOtherPerson)
-       }}
-       ```
-
-       Would result in an object such as:
-
-       ```js
-       ['Tom Dale', 'Yehuda Katz', this.get('myOtherPerson')]
-       ```
-
-       Where the 3rd item in the array is bound to updates of the `myOtherPerson` property.
-
-       @method array
-       @param {Array} options
-       @return {Array} Array
-       @public
-     */
     export const array: object;
 }

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

@@ -1,23 +1,3 @@
 declare module '@glimmer/runtime/lib/helpers/concat' {
-    /**
-      Concatenates the given arguments into a string.
-
-      Example:
-
-      ```handlebars
-      {{some-component name=(concat firstName " " lastName)}}
-
-      {{! would pass name="<first name value> <last name value>" to the component}}
-      ```
-
-      or for angle bracket invocation, you actually don't need concat at all.
-
-      ```handlebars
-      <SomeComponent @name="{{firstName}} {{lastName}}" />
-      ```
-
-      @public
-      @method concat
-    */
     export const concat: object;
 }

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

@@ -1,67 +1,3 @@
 declare module '@glimmer/runtime/lib/helpers/fn' {
-    /**
-      The `fn` helper allows you to ensure a function that you are passing off
-      to another component, helper, or modifier has access to arguments that are
-      available in the template.
-
-      For example, if you have an `each` helper looping over a number of items, you
-      may need to pass a function that expects to receive the item as an argument
-      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-list.js
-      import Component from '@glimmer/component';
-      import { action } from '@ember/object';
-
-      export default class ItemsList extends Component {
-        handleSelected = (item) => {
-          // ...snip...
-        }
-      }
-      ```
-
-      In this case the `display-item` 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.
-
-      Let's take look at what that means in a couple circumstances:
-
-      - When invoked as `this.args.select()` the `handleSelected` function will
-        receive the `item` from the loop as its first and only argument.
-      - When invoked as `this.args.select('foo')` the `handleSelected` function
-        will receive the `item` from the loop as its first argument and the
-        string `'foo'` as its second argument.
-
-      In the example above, we used an arrow function to ensure that
-      `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
-      import Component from '@glimmer/component';
-
-      export default class ItemsList extends Component {
-        handleSelected(item) {
-          // ...snip...
-        }
-      }
-      ```
-
-      In this example, when `handleSelected` is invoked inside the `display-item`
-      component, it will **not** have access to the component instance. In other
-      words, it will have no `this` context, so please make sure your functions
-      are bound (via an arrow function or other means) before passing into `fn`!
-
-      See also [partial application](https://en.wikipedia.org/wiki/Partial_application).
-
-      @method fn
-      @public
-    */
     export const fn: object;
 }

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

@@ -1,80 +1,3 @@
 declare module '@glimmer/runtime/lib/helpers/get' {
-    /**
-      Dynamically look up a property on an object. The second argument to `{{get}}`
-      should have a string value, although it can be bound.
-
-      For example, these two usages are equivalent:
-
-      ```app/components/developer-detail.js
-      import Component from '@glimmer/component';
-      import { tracked } from '@glimmer/tracking';
-
-      export default class extends Component {
-        @tracked developer = {
-          name: "Sandi Metz",
-          language: "Ruby"
-        }
-      }
-      ```
-
-      ```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" />
-      ```
-
-      ```handlebars
-      {{get this.developer @factName}}
-      ```
-
-      For a more complex example, this template would allow the user to switch
-      between showing the user's height and weight with a click:
-
-      ```app/components/developer-detail.js
-      import Component from '@glimmer/component';
-      import { tracked } from '@glimmer/tracking';
-
-      export default class extends Component {
-        @tracked developer = {
-          name: "Sandi Metz",
-          language: "Ruby"
-        }
-
-        @tracked currentFact = 'name'
-
-        showFact = (fact) => {
-          this.currentFact = fact;
-        }
-      }
-      ```
-
-      ```app/components/developer-detail.js
-      {{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>
-      ```
-
-      Would allow the user to swap what fact is being displayed, and also edit
-      that fact via a two-way mutable binding.
-
-      @public
-      @method get
-     */
     export const get: object;
 }

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

@@ -1,39 +1,3 @@
 declare module '@glimmer/runtime/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
-       just yield a hash:
-
-       ```handlebars
-       {{yield (hash
-          name='Sarah'
-          title=office
-       )}}
-       ```
-
-       Would result in an object such as:
-
-       ```js
-       { name: 'Sarah', title: this.get('office') }
-       ```
-
-       Where the `title` is bound to updates of the `office` property.
-
-       Note that the hash is an empty object with no prototype chain, therefore
-       common methods like `toString` are not available in the resulting hash.
-       If you need to use such a method, you can use the `call` or `apply`
-       approach:
-
-       ```js
-       function toString(obj) {
-         return Object.prototype.toString.apply(obj);
-       }
-       ```
-
-       @method hash
-       @param {Object} options
-       @return {Object} Hash
-       @public
-     */
     export const hash: object;
 }

package/types/stable/@glimmer/syntax/lib/get-template-locals.d.ts

@@ -4,7 +4,7 @@ declare module '@glimmer/syntax/lib/get-template-locals' {
         includeHtmlElements?: boolean;
     }
     /**
-     * Parses and traverses a given handlebars html template to extract all template locals
+     * Parses and traverses a given template to extract all template locals
      * referenced that could possible come from the parent scope. Can exclude known keywords
      * optionally.
      */

package/types/stable/@glimmer/tracking/index.d.ts

@@ -20,17 +20,7 @@ declare module '@glimmer/tracking' {
       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';
@@ -46,6 +36,16 @@ declare module '@glimmer/tracking' {
         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>
       }
       ```
 
@@ -55,7 +55,7 @@ declare module '@glimmer/tracking' {
       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/index.d.ts

@@ -74,30 +74,16 @@
 /// <reference path="./@ember/-internals/glimmer/lib/helpers/-normalize-class.d.ts" />
 /// <reference path="./@ember/-internals/glimmer/lib/helpers/-resolve.d.ts" />
 /// <reference path="./@ember/-internals/glimmer/lib/helpers/-track-array.d.ts" />
-/// <reference path="./@ember/-internals/glimmer/lib/helpers/array.d.ts" />
-/// <reference path="./@ember/-internals/glimmer/lib/helpers/component.d.ts" />
-/// <reference path="./@ember/-internals/glimmer/lib/helpers/concat.d.ts" />
 /// <reference path="./@ember/-internals/glimmer/lib/helpers/each-in.d.ts" />
 /// <reference path="./@ember/-internals/glimmer/lib/helpers/element.d.ts" />
-/// <reference path="./@ember/-internals/glimmer/lib/helpers/fn.d.ts" />
-/// <reference path="./@ember/-internals/glimmer/lib/helpers/get.d.ts" />
-/// <reference path="./@ember/-internals/glimmer/lib/helpers/hash.d.ts" />
-/// <reference path="./@ember/-internals/glimmer/lib/helpers/helper.d.ts" />
-/// <reference path="./@ember/-internals/glimmer/lib/helpers/if-unless.d.ts" />
 /// <reference path="./@ember/-internals/glimmer/lib/helpers/internal-helper.d.ts" />
-/// <reference path="./@ember/-internals/glimmer/lib/helpers/log.d.ts" />
-/// <reference path="./@ember/-internals/glimmer/lib/helpers/modifier.d.ts" />
 /// <reference path="./@ember/-internals/glimmer/lib/helpers/mut.d.ts" />
-/// <reference path="./@ember/-internals/glimmer/lib/helpers/page-title.d.ts" />
 /// <reference path="./@ember/-internals/glimmer/lib/helpers/readonly.d.ts" />
 /// <reference path="./@ember/-internals/glimmer/lib/helpers/unbound.d.ts" />
 /// <reference path="./@ember/-internals/glimmer/lib/helpers/unique-id.d.ts" />
-/// <reference path="./@ember/-internals/glimmer/lib/modifiers/on.d.ts" />
 /// <reference path="./@ember/-internals/glimmer/lib/renderer.d.ts" />
 /// <reference path="./@ember/-internals/glimmer/lib/resolver.d.ts" />
 /// <reference path="./@ember/-internals/glimmer/lib/setup-registry.d.ts" />
-/// <reference path="./@ember/-internals/glimmer/lib/syntax/in-element.d.ts" />
-/// <reference path="./@ember/-internals/glimmer/lib/syntax/let.d.ts" />
 /// <reference path="./@ember/-internals/glimmer/lib/syntax/mount.d.ts" />
 /// <reference path="./@ember/-internals/glimmer/lib/syntax/outlet.d.ts" />
 /// <reference path="./@ember/-internals/glimmer/lib/template_registry.d.ts" />
@@ -187,6 +173,7 @@
 /// <reference path="./@ember/application/namespace.d.ts" />
 /// <reference path="./@ember/array/-internals.d.ts" />
 /// <reference path="./@ember/array/index.d.ts" />
+/// <reference path="./@ember/array/lib/is-array.d.ts" />
 /// <reference path="./@ember/array/lib/make-array.d.ts" />
 /// <reference path="./@ember/array/make.d.ts" />
 /// <reference path="./@ember/array/mutable.d.ts" />