ember-source 4.10.0-beta.2 → 4.11.0-alpha.2

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

@@ -0,0 +1,72 @@
+declare module '@ember/-internals/glimmer/lib/helpers/fn.d.ts' {
+  /**
+  @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.Templates.helpers
+    @public
+    @since 3.11.0
+  */
+}

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

@@ -0,0 +1,99 @@
+declare module '@ember/-internals/glimmer/lib/helpers/get.d.ts' {
+  /**
+  @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.Templates.helpers
+    @since 2.1.0
+   */
+}

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

@@ -0,0 +1,43 @@
+declare module '@ember/-internals/glimmer/lib/helpers/hash.d.ts' {
+  /**
+  @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.Templates.helpers
+     @param {Object} options
+     @return {Object} Hash
+     @since 2.3.0
+     @public
+   */
+}

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

@@ -0,0 +1,42 @@
+declare module '@ember/-internals/glimmer/lib/helpers/helper.d.ts' {
+  /**
+   @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
+   */
+}

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

@@ -0,0 +1,181 @@
+declare module '@ember/-internals/glimmer/lib/helpers/if-unless.d.ts' {
+  /**
+  @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
+  */
+}

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

@@ -0,0 +1,5 @@
+declare module '@ember/-internals/glimmer/lib/helpers/internal-helper.d.ts' {
+  import type { InternalOwner } from '@ember/-internals/owner';
+  import type { Helper, HelperDefinitionState } from '@glimmer/interfaces';
+  export function internalHelper(helper: Helper<InternalOwner>): HelperDefinitionState;
+}

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

@@ -0,0 +1,18 @@
+declare module '@ember/-internals/glimmer/lib/helpers/log.d.ts' {
+  /**
+  @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
+  */
+}

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

@@ -0,0 +1,41 @@
+declare module '@ember/-internals/glimmer/lib/helpers/modifier.d.ts' {
+  /**
+   @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
+   */
+}

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

@@ -0,0 +1,77 @@
+declare module '@ember/-internals/glimmer/lib/helpers/mut.d.ts' {
+  /**
+    The `mut` helper lets you __clearly specify__ that a child `Component` can update the
+    (mutable) value passed to it, which will __change the value of the parent component__.
+
+    To specify that a parameter is mutable, when invoking the child `Component`:
+
+    ```handlebars
+    <MyChild @childClickCount={{fn (mut totalClicks)}} />
+    ```
+
+     or
+
+    ```handlebars
+    {{my-child childClickCount=(mut totalClicks)}}
+    ```
+
+    The child `Component` can then modify the parent's value just by modifying its own
+    property:
+
+    ```javascript
+    // my-child.js
+    export default Component.extend({
+      click() {
+        this.incrementProperty('childClickCount');
+      }
+    });
+    ```
+
+    Note that for curly components (`{{my-component}}`) the bindings are already mutable,
+    making the `mut` unnecessary.
+
+    Additionally, the `mut` helper can be combined with the `fn` helper to
+    mutate a value. For example:
+
+    ```handlebars
+    <MyChild @childClickCount={{this.totalClicks}} @click-count-change={{fn (mut totalClicks))}} />
+    ```
+
+    or
+
+    ```handlebars
+    {{my-child childClickCount=totalClicks click-count-change=(fn (mut totalClicks))}}
+    ```
+
+    The child `Component` would invoke the function with the new click value:
+
+    ```javascript
+    // my-child.js
+    export default Component.extend({
+      click() {
+        this.get('click-count-change')(this.get('childClickCount') + 1);
+      }
+    });
+    ```
+
+    The `mut` helper changes the `totalClicks` value to what was provided as the `fn` argument.
+
+    The `mut` helper, when used with `fn`, will return a function that
+    sets the value passed to `mut` to its first argument. As an example, we can create a
+    button that increments a value passing the value directly to the `fn`:
+
+    ```handlebars
+    {{! inc helper is not provided by Ember }}
+    <button onclick={{fn (mut count) (inc count)}}>
+      Increment count
+    </button>
+    ```
+
+    @method mut
+    @param {Object} [attr] the "two-way" attribute that can be modified.
+    @for Ember.Templates.helpers
+    @public
+  */
+  const _default: object;
+  export default _default;
+}

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

@@ -0,0 +1,19 @@
+declare module '@ember/-internals/glimmer/lib/helpers/page-title.d.ts' {
+  /**
+  @module ember
+  */
+  /**
+    `page-title` allows you to set the title of any page in your application and
+    append additional titles for each route. For complete documentation, see
+    https://github.com/ember-cli/ember-page-title.
+
+    ```handlebars
+    {{page-title "My Page Title" }}
+    ```
+
+    @method page-title
+    @for Ember.Templates.helpers
+    @param {String} param
+    @public
+  */
+}