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

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

@@ -0,0 +1,268 @@
+declare module '@ember/-internals/glimmer/lib/helpers/action.d.ts' {
+  export const ACTIONS: WeakSet<object>;
+  /**
+    The `{{action}}` helper provides a way to pass triggers for behavior (usually
+    just a function) between components, and into components from controllers.
+
+    ### Passing functions with the action helper
+
+    There are three contexts an action helper can be used in. The first two
+    contexts to discuss are attribute context, and Handlebars value context.
+
+    ```handlebars
+    {{! An example of attribute context }}
+    <div onclick={{action "save"}}></div>
+    {{! Examples of Handlebars value context }}
+    {{input on-input=(action "save")}}
+    {{yield (action "refreshData") andAnotherParam}}
+    ```
+
+    In these contexts,
+    the helper is called a "closure action" helper. Its behavior is simple:
+    If passed a function name, read that function off the `actions` property
+    of the current context. Once that function is read, or immediately if a function was
+    passed, create a closure over that function and any arguments.
+    The resulting value of an action helper used this way is simply a function.
+
+    For example, in the attribute context:
+
+    ```handlebars
+    {{! An example of attribute context }}
+    <div onclick={{action "save"}}></div>
+    ```
+
+    The resulting template render logic would be:
+
+    ```js
+    var div = document.createElement('div');
+    var actionFunction = (function(context){
+      return function() {
+        return context.actions.save.apply(context, arguments);
+      };
+    })(context);
+    div.onclick = actionFunction;
+    ```
+
+    Thus when the div is clicked, the action on that context is called.
+    Because the `actionFunction` is just a function, closure actions can be
+    passed between components and still execute in the correct context.
+
+    Here is an example action handler on a component:
+
+    ```app/components/my-component.js
+    import Component from '@glimmer/component';
+    import { action } from '@ember/object';
+
+    export default class extends Component {
+      @action
+      save() {
+        this.model.save();
+      }
+    }
+    ```
+
+    Actions are always looked up on the `actions` property of the current context.
+    This avoids collisions in the naming of common actions, such as `destroy`.
+    Two options can be passed to the `action` helper when it is used in this way.
+
+    * `target=someProperty` will look to `someProperty` instead of the current
+      context for the `actions` hash. This can be useful when targeting a
+      service for actions.
+    * `value="target.value"` will read the path `target.value` off the first
+      argument to the action when it is called and rewrite the first argument
+      to be that value. This is useful when attaching actions to event listeners.
+
+    ### Invoking an action
+
+    Closure actions curry both their scope and any arguments. When invoked, any
+    additional arguments are added to the already curried list.
+    Actions are presented in JavaScript as callbacks, and are
+    invoked like any other JavaScript function.
+
+    For example
+
+    ```app/components/update-name.js
+    import Component from '@glimmer/component';
+    import { action } from '@ember/object';
+
+    export default class extends Component {
+      @action
+      setName(model, name) {
+        model.set('name', name);
+      }
+    }
+    ```
+
+    ```app/components/update-name.hbs
+    {{input on-input=(action (action 'setName' @model) value="target.value")}}
+    ```
+
+    The first argument (`@model`) was curried over, and the run-time argument (`event`)
+    becomes a second argument. Action calls can be nested this way because each simply
+    returns a function. Any function can be passed to the `{{action}}` helper, including
+    other actions.
+
+    Actions invoked with `sendAction` have the same currying behavior as demonstrated
+    with `on-input` above. For example:
+
+    ```app/components/my-input.js
+    import Component from '@glimmer/component';
+    import { action } from '@ember/object';
+
+    export default class extends Component {
+      @action
+      setName(model, name) {
+        model.set('name', name);
+      }
+    }
+    ```
+
+    ```handlebars
+    <MyInput @submit={{action 'setName' @model}} />
+    ```
+
+    or
+
+    ```handlebars
+    {{my-input submit=(action 'setName' @model)}}
+    ```
+
+    ```app/components/my-component.js
+    import Component from '@ember/component';
+
+    export default Component.extend({
+      click() {
+        // Note that model is not passed, it was curried in the template
+        this.submit('bob');
+      }
+    });
+    ```
+
+    ### Attaching actions to DOM elements
+
+    The third context of the `{{action}}` helper can be called "element space".
+    For example:
+
+    ```handlebars
+    {{! An example of element space }}
+    <div {{action "save"}}></div>
+    ```
+
+    Used this way, the `{{action}}` helper provides a useful shortcut for
+    registering an HTML element in a template for a single DOM event and
+    forwarding that interaction to the template's context (controller or component).
+    If the context of a template is a controller, actions used this way will
+    bubble to routes when the controller does not implement the specified action.
+    Once an action hits a route, it will bubble through the route hierarchy.
+
+    ### Event Propagation
+
+    `{{action}}` helpers called in element space can control event bubbling. Note
+    that the closure style actions cannot.
+
+    Events triggered through the action helper will automatically have
+    `.preventDefault()` called on them. You do not need to do so in your event
+    handlers. If you need to allow event propagation (to handle file inputs for
+    example) you can supply the `preventDefault=false` option to the `{{action}}` helper:
+
+    ```handlebars
+    <div {{action "sayHello" preventDefault=false}}>
+      <input type="file" />
+      <input type="checkbox" />
+    </div>
+    ```
+
+    To disable bubbling, pass `bubbles=false` to the helper:
+
+    ```handlebars
+    <button {{action 'edit' post bubbles=false}}>Edit</button>
+    ```
+
+    To disable bubbling with closure style actions you must create your own
+    wrapper helper that makes use of `event.stopPropagation()`:
+
+    ```handlebars
+    <div onclick={{disable-bubbling (action "sayHello")}}>Hello</div>
+    ```
+
+    ```app/helpers/disable-bubbling.js
+    import { helper } from '@ember/component/helper';
+
+    export function disableBubbling([action]) {
+      return function(event) {
+        event.stopPropagation();
+        return action(event);
+      };
+    }
+    export default helper(disableBubbling);
+    ```
+
+    If you need the default handler to trigger you should either register your
+    own event handler, or use event methods on your view class. See
+    ["Responding to Browser Events"](/ember/release/classes/Component)
+    in the documentation for `Component` for more information.
+
+    ### Specifying DOM event type
+
+    `{{action}}` helpers called in element space can specify an event type.
+    By default the `{{action}}` helper registers for DOM `click` events. You can
+    supply an `on` option to the helper to specify a different DOM event name:
+
+    ```handlebars
+    <div {{action "anActionName" on="doubleClick"}}>
+      click me
+    </div>
+    ```
+
+    See ["Event Names"](/ember/release/classes/Component) for a list of
+    acceptable DOM event names.
+
+    ### Specifying whitelisted modifier keys
+
+    `{{action}}` helpers called in element space can specify modifier keys.
+    By default the `{{action}}` helper will ignore click events with pressed modifier
+    keys. You can supply an `allowedKeys` option to specify which keys should not be ignored.
+
+    ```handlebars
+    <div {{action "anActionName" allowedKeys="alt"}}>
+      click me
+    </div>
+    ```
+
+    This way the action will fire when clicking with the alt key pressed down.
+    Alternatively, supply "any" to the `allowedKeys` option to accept any combination of modifier keys.
+
+    ```handlebars
+    <div {{action "anActionName" allowedKeys="any"}}>
+      click me with any key pressed
+    </div>
+    ```
+
+    ### Specifying a Target
+
+    A `target` option can be provided to the helper to change
+    which object will receive the method call. This option must be a path
+    to an object, accessible in the current context:
+
+    ```app/templates/application.hbs
+    <div {{action "anActionName" target=someService}}>
+      click me
+    </div>
+    ```
+
+    ```app/controllers/application.js
+    import Controller from '@ember/controller';
+    import { service } from '@ember/service';
+
+    export default class extends Controller {
+      @service someService;
+    }
+    ```
+
+    @method action
+    @for Ember.Templates.helpers
+    @public
+  */
+  const _default: object;
+  export default _default;
+}

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

@@ -0,0 +1,40 @@
+declare module '@ember/-internals/glimmer/lib/helpers/array.d.ts' {
+  /**
+  @module ember
+  */
+  /**
+     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
+     @for Ember.Templates.helpers
+     @param {Array} options
+     @return {Array} Array
+     @since 3.8.0
+     @public
+   */
+}

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

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

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

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

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

@@ -0,0 +1,160 @@
+declare module '@ember/-internals/glimmer/lib/helpers/each-in.d.ts' {
+  /**
+    The `{{#each}}` helper 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
+    item in an array passing the item as the first block parameter.
+
+    Assuming the `@developers` argument contains this array:
+
+    ```javascript
+    [{ name: 'Yehuda' },{ name: 'Tom' }, { name: 'Paul' }];
+    ```
+
+    ```handlebars
+    <ul>
+      {{#each @developers as |person|}}
+        <li>Hello, {{person.name}}!</li>
+      {{/each}}
+    </ul>
+    ```
+
+    The same rules apply to arrays of primitives.
+
+    ```javascript
+    ['Yehuda', 'Tom', 'Paul']
+    ```
+
+    ```handlebars
+    <ul>
+      {{#each @developerNames as |name|}}
+        <li>Hello, {{name}}!</li>
+      {{/each}}
+    </ul>
+    ```
+
+    During iteration, the index of each item in the array is provided as a second block
+    parameter.
+
+    ```handlebars
+    <ul>
+      {{#each @developers as |person index|}}
+        <li>Hello, {{person.name}}! You're number {{index}} in line</li>
+      {{/each}}
+    </ul>
+    ```
+
+    ### Specifying Keys
+
+    In order to improve rendering speed, Ember will try to reuse the DOM elements
+    where possible. Specifically, if the same item is present in the array both
+    before and after the change, its DOM output will be reused.
+
+    The `key` option is used to tell Ember how to determine if the items in the
+    array being iterated over with `{{#each}}` has changed between renders. By
+    default the item's object identity is used.
+
+    This is usually sufficient, so in most cases, the `key` option is simply not
+    needed. However, in some rare cases, the objects' identities may change even
+    though they represent the same underlying data.
+
+    For example:
+
+    ```javascript
+    people.map(person => {
+      return { ...person, type: 'developer' };
+    });
+    ```
+
+    In this case, each time the `people` array is `map`-ed over, it will produce
+    an new array with completely different objects between renders. In these cases,
+    you can help Ember determine how these objects related to each other with the
+    `key` option:
+
+    ```handlebars
+    <ul>
+      {{#each @developers key="name" as |person|}}
+        <li>Hello, {{person.name}}!</li>
+      {{/each}}
+    </ul>
+    ```
+
+    By doing so, Ember will use the value of the property specified (`person.name`
+    in the example) to find a "match" from the previous render. That is, if Ember
+    has previously seen an object from the `@developers` array with a matching
+    name, its DOM elements will be re-used.
+
+    There are two special values for `key`:
+
+      * `@index` - The index of the item in the array.
+      * `@identity` - The item in the array itself.
+
+    ### {{else}} condition
+
+    `{{#each}}` can have a matching `{{else}}`. The contents of this block will render
+    if the collection is empty.
+
+    ```handlebars
+    <ul>
+      {{#each @developers as |person|}}
+        <li>{{person.name}} is available!</li>
+      {{else}}
+        <li>Sorry, nobody is available for this task.</li>
+      {{/each}}
+    </ul>
+    ```
+
+    @method each
+    @for Ember.Templates.helpers
+    @public
+   */
+  /**
+    The `{{each-in}}` helper loops over properties on an object.
+
+    For example, given this component definition:
+
+    ```app/components/developer-details.js
+    import Component from '@glimmer/component';
+    import { tracked } from '@glimmer/tracking';
+
+    export default class extends Component {
+      @tracked developer = {
+        "name": "Shelly Sails",
+        "age": 42
+      };
+    }
+    ```
+
+    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:
+
+    ```html
+    <ul>
+      <li>name: Shelly Sails</li>
+      <li>age: 42</li>
+    </ul>
+    ```
+
+    @method each-in
+    @for Ember.Templates.helpers
+    @public
+    @since 2.1.0
+  */
+  export class EachInWrapper {
+      inner: unknown;
+      constructor(inner: unknown);
+  }
+  const _default: object;
+  export default _default;
+}