ember-source 5.6.0-alpha.6 → 5.6.0-beta.2

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

@@ -1 +1,149 @@
-declare module '@ember/-internals/glimmer/lib/helpers/component' {}
+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 `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:
+
+      ```app/templates/application.hbs
+      <LiveUpdatingChart />
+      ```
+
+      or
+
+      ```app/templates/application.hbs
+      {{live-updating-chart}}
+      ```
+
+      ### Block Form
+
+      Using the block form of this helper is similar to using the block form
+      of a component. Given the following application template:
+
+      ```app/templates/application.hbs
+      {{#component this.infographicComponentName}}
+        Last update: {{this.lastUpdateTimestamp}}
+      {{/component}}
+      ```
+
+      The following controller code:
+
+      ```app/controllers/application.js
+      import Controller from '@ember/controller';
+      import { computed } from '@ember/object';
+      import { tracked } from '@glimmer/tracking';
+
+      export default class ApplicationController extends Controller {
+        @tracked isMarketOpen = 'live-updating-chart'
+
+        get lastUpdateTimestamp() {
+          return new Date();
+        }
+
+        get infographicComponentName() {
+          return this.isMarketOpen ? 'live-updating-chart' : 'market-close-summary';
+        }
+      }
+      ```
+
+      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
+      @public
+    */
+  export {};
+}

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

@@ -1 +1,28 @@
-declare module '@ember/-internals/glimmer/lib/helpers/concat' {}
+declare module '@ember/-internals/glimmer/lib/helpers/concat' {
+  /**
+    @module ember
+    */
+  /**
+      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
+      @for @ember/helper
+      @since 1.13.0
+    */
+  export {};
+}

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

@@ -1 +1,73 @@
-declare module '@ember/-internals/glimmer/lib/helpers/fn' {}
+declare module '@ember/-internals/glimmer/lib/helpers/fn' {
+  /**
+    @module ember
+    */
+  /**
+      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 {
+        @action
+        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 `@action` to ensure that `handleSelected` is
+      properly bound to the `items-list`, but let's explore what happens if we
+      left out `@action`:
+
+      ```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 `@action` or other means) before passing into `fn`!
+
+      See also [partial application](https://en.wikipedia.org/wiki/Partial_application).
+
+      @method fn
+      @for @ember/helper
+      @public
+      @since 3.11.0
+    */
+  export {};
+}

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

@@ -1 +1,100 @@
-declare module '@ember/-internals/glimmer/lib/helpers/get' {}
+declare module '@ember/-internals/glimmer/lib/helpers/get' {
+  /**
+    @module ember
+    */
+  /**
+      Dynamically look up a property on an object or an element in an array.
+      The second argument to `{{get}}` should have a string or number 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 name and preferred coding language 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'
+
+        @action
+        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.
+
+      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`:
+
+      ```handlebars
+      {{get this.names 0}}
+      ```
+
+      Array element access also works with a dynamic second argument:
+
+      ```handlebars
+      {{get this.names @index}}
+      ```
+
+      @public
+      @method get
+      @for @ember/helper
+      @since 2.1.0
+     */
+  export {};
+}

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

@@ -1 +1,44 @@
-declare module '@ember/-internals/glimmer/lib/helpers/hash' {}
+declare module '@ember/-internals/glimmer/lib/helpers/hash' {
+  /**
+    @module ember
+    */
+  /**
+       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
+       @for @ember/helper
+       @param {Object} options
+       @return {Object} Hash
+       @since 2.3.0
+       @public
+     */
+  export {};
+}

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

@@ -1 +1,43 @@
-declare module '@ember/-internals/glimmer/lib/helpers/helper' {}
+declare module '@ember/-internals/glimmer/lib/helpers/helper' {
+  /**
+     @module ember
+     */
+  /**
+     Use the `{{helper}}` helper to create contextual helper so
+     that it can be passed around as first-class values in templates.
+
+     ```handlebars
+     {{#let (helper "join-words" "foo" "bar" separator=" ") as |foo-bar|}}
+
+       {{!-- this is equivalent to invoking `{{join-words "foo" "bar" separator=" "}}` --}}
+       {{foo-bar}}
+
+       {{!-- this will pass the helper itself into the component, instead of invoking it now --}}
+       <MyComponent @helper={{helper foo-bar "baz"}} />
+
+       {{!-- this will yield the helper itself ("contextual helper"), instead of invoking it now --}}
+       {{yield foo-bar}}
+     {{/let}}
+     ```
+
+     ### Arguments
+
+     The `{{helper}}` helper works similarly to the [`{{component}}`](./component?anchor=component) and
+     [`{{modifier}}`](./modifier?anchor=modifier) helper:
+
+     * When passed a string (e.g. `(helper "foo")`) as the first argument,
+       it will produce an opaque, internal "helper definition" object
+       that can be passed around and invoked elsewhere.
+
+     * Any additional positional and/or named arguments (a.k.a. params and hash)
+       will be stored ("curried") inside the definition object, such that, when invoked,
+       these arguments will be passed along to the referenced helper.
+
+
+     @method helper
+     @for Ember.Templates.helpers
+     @public
+     @since 3.27.0
+     */
+  export {};
+}

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

@@ -1 +1,182 @@
-declare module '@ember/-internals/glimmer/lib/helpers/if-unless' {}
+declare module '@ember/-internals/glimmer/lib/helpers/if-unless' {
+  /**
+    @module ember
+    */
+  /**
+      The `if` helper allows you to conditionally render one of two branches,
+      depending on the "truthiness" of a property.
+      For example the following values are all falsey: `false`, `undefined`, `null`, `""`, `0`, `NaN` or an empty array.
+
+      This helper has two forms, block and inline.
+
+      ## Block form
+
+      You can use the block form of `if` to conditionally render a section of the template.
+
+      To use it, pass the conditional value to the `if` helper,
+      using the block form to wrap the section of template you want to conditionally render.
+      Like so:
+
+      ```app/templates/application.hbs
+      <Weather />
+      ```
+
+      ```app/components/weather.hbs
+      {{! will not render because greeting is undefined}}
+      {{#if @isRaining}}
+        Yes, grab an umbrella!
+      {{/if}}
+      ```
+
+      You can also define what to show if the property is falsey by using
+      the `else` helper.
+
+      ```app/components/weather.hbs
+      {{#if @isRaining}}
+        Yes, grab an umbrella!
+      {{else}}
+        No, it's lovely outside!
+      {{/if}}
+      ```
+
+      You are also able to combine `else` and `if` helpers to create more complex
+      conditional logic.
+
+      For the following template:
+
+       ```app/components/weather.hbs
+      {{#if @isRaining}}
+        Yes, grab an umbrella!
+      {{else if @isCold}}
+        Grab a coat, it's chilly!
+      {{else}}
+        No, it's lovely outside!
+      {{/if}}
+      ```
+
+      If you call it by saying `isCold` is true:
+
+      ```app/templates/application.hbs
+      <Weather @isCold={{true}} />
+      ```
+
+      Then `Grab a coat, it's chilly!` will be rendered.
+
+      ## Inline form
+
+      The inline `if` helper conditionally renders a single property or string.
+
+      In this form, the `if` helper receives three arguments, the conditional value,
+      the value to render when truthy, and the value to render when falsey.
+
+      For example, if `useLongGreeting` is truthy, the following:
+
+      ```app/templates/application.hbs
+      <Greeting @useLongGreeting={{true}} />
+      ```
+
+      ```app/components/greeting.hbs
+      {{if @useLongGreeting "Hello" "Hi"}} Alex
+      ```
+
+      Will render:
+
+      ```html
+      Hello Alex
+      ```
+
+      One detail to keep in mind is that both branches of the `if` helper will be evaluated,
+      so if you have `{{if condition "foo" (expensive-operation "bar")`,
+      `expensive-operation` will always calculate.
+
+      @method if
+      @for Ember.Templates.helpers
+      @public
+    */
+  /**
+      The `unless` helper is the inverse of the `if` helper. It displays if a value
+      is falsey ("not true" or "is false"). Example values that will display with
+      `unless`: `false`, `undefined`, `null`, `""`, `0`, `NaN` or an empty array.
+
+      ## Inline form
+
+      The inline `unless` helper conditionally renders a single property or string.
+      This helper acts like a ternary operator. If the first property is falsy,
+      the second argument will be displayed, otherwise, the third argument will be
+      displayed
+
+      For example, if you pass a falsey `useLongGreeting` to the `Greeting` component:
+
+      ```app/templates/application.hbs
+      <Greeting @useLongGreeting={{false}} />
+      ```
+
+      ```app/components/greeting.hbs
+      {{unless @useLongGreeting "Hi" "Hello"}} Ben
+      ```
+
+      Then it will display:
+
+      ```html
+      Hi Ben
+      ```
+
+      ## Block form
+
+      Like the `if` helper, the `unless` helper also has a block form.
+
+      The following will not render anything:
+
+      ```app/templates/application.hbs
+      <Greeting />
+      ```
+
+      ```app/components/greeting.hbs
+      {{#unless @greeting}}
+        No greeting was found. Why not set one?
+      {{/unless}}
+      ```
+
+      You can also use an `else` helper with the `unless` block. The
+      `else` will display if the value is truthy.
+
+      If you have the following component:
+
+      ```app/components/logged-in.hbs
+      {{#unless @userData}}
+        Please login.
+      {{else}}
+        Welcome back!
+      {{/unless}}
+      ```
+
+      Calling it with a truthy `userData`:
+
+      ```app/templates/application.hbs
+      <LoggedIn @userData={{hash username="Zoey"}} />
+      ```
+
+      Will render:
+
+      ```html
+      Welcome back!
+      ```
+
+      and calling it with a falsey `userData`:
+
+      ```app/templates/application.hbs
+      <LoggedIn @userData={{false}} />
+      ```
+
+      Will render:
+
+      ```html
+      Please login.
+      ```
+
+      @method unless
+      @for Ember.Templates.helpers
+      @public
+    */
+  export {};
+}

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

@@ -1 +1,19 @@
-declare module '@ember/-internals/glimmer/lib/helpers/log' {}
+declare module '@ember/-internals/glimmer/lib/helpers/log' {
+  /**
+    @module ember
+    */
+  /**
+      `log` allows you to output the value of variables in the current rendering
+      context. `log` also accepts primitive types such as strings or numbers.
+
+      ```handlebars
+      {{log "myVariable:" myVariable }}
+      ```
+
+      @method log
+      @for Ember.Templates.helpers
+      @param {Array} params
+      @public
+    */
+  export {};
+}

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

@@ -1 +1,42 @@
-declare module '@ember/-internals/glimmer/lib/helpers/modifier' {}
+declare module '@ember/-internals/glimmer/lib/helpers/modifier' {
+  /**
+     @module ember
+     */
+  /**
+     Use the `{{modifier}}` helper to create contextual modifier so
+     that it can be passed around as first-class values in templates.
+
+     ```handlebars
+     {{#let (modifier "click-outside" click=this.submit) as |on-click-outside|}}
+
+       {{!-- this is equivalent to `<MyComponent {{click-outside click=this.submit}} />` --}}
+       <MyComponent {{on-click-outside}} />
+
+       {{!-- this will pass the modifier itself into the component, instead of invoking it now --}}
+       <MyComponent @modifier={{modifier on-click-outside "extra" "args"}} />
+
+       {{!-- this will yield the modifier itself ("contextual modifier"), instead of invoking it now --}}
+       {{yield on-click-outside}}
+     {{/let}}
+     ```
+
+     ### Arguments
+
+     The `{{modifier}}` helper works similarly to the [`{{component}}`](./component?anchor=component) and
+     [`{{helper}}`](./helper?anchor=helper) helper:
+
+     * When passed a string (e.g. `(modifier "foo")`) as the first argument,
+       it will produce an opaque, internal "modifier definition" object
+       that can be passed around and invoked elsewhere.
+
+     * Any additional positional and/or named arguments (a.k.a. params and hash)
+       will be stored ("curried") inside the definition object, such that, when invoked,
+       these arguments will be passed along to the referenced modifier.
+
+     @method modifier
+     @for Ember.Templates.helpers
+     @public
+     @since 3.27.0
+     */
+  export {};
+}