ember-source 6.12.0 → 7.0.0-beta.1

package/dist/prod/packages/@ember/helper/index.js

@@ -0,0 +1,489 @@
+import { c as helperCapabilities } from '../../shared-chunks/api-Co-k4HVs.js';
+import '../../shared-chunks/capabilities-DGmQ_mz4.js';
+import '../../@glimmer/validator/index.js';
+import '../../shared-chunks/reference-BNqcwZWH.js';
+import { setHelperManager as setHelperManager$1 } from '../../@glimmer/manager/index.js';
+import '../../shared-chunks/fragment-EpVz5Xuc.js';
+import { h as array$1, j as concat$1, m as fn$1, n as get$1, o as hash$1 } from '../../shared-chunks/on-CrTl7JQU.js';
+import '../../shared-chunks/constants-b-2IVErl.js';
+import { i as invokeHelper$1 } from '../../shared-chunks/invoke-DxL00a1D.js';
+import '../../shared-chunks/index-CSVCFS_p.js';
+import { u as uniqueId$1 } from '../../shared-chunks/index-DZLHQAlb.js';
+import '../-internals/container/index.js';
+import '../../shared-chunks/super-Cm_a_cLQ.js';
+import '../-internals/environment/index.js';
+import '../runloop/index.js';
+
+/**
+@module @ember/helper
+*/
+
+/**
+  `capabilities` returns a capabilities configuration which can be used to modify
+  the behavior of the manager. Manager capabilities _must_ be provided using the
+  `capabilities` function, as the underlying implementation can change over time.
+
+  The first argument to capabilities is a version string, which is the version of
+  Ember that the capabilities were defined in. Ember can add new versions at any
+  time, and these may have entirely different behaviors, but it will not remove
+  old versions until the next major version.
+
+  ```js
+  capabilities('3.23');
+  ```
+
+  The second argument is an object of capabilities and boolean values indicating
+  whether they are enabled or disabled.
+
+  ```js
+  capabilities('3.23', {
+    hasValue: true,
+    hasDestructor: true,
+  });
+  ```
+
+  If no value is specified, then the default value will be used.
+
+  ### `3.23` capabilities
+
+  #### `hasDestroyable`
+
+  - Default value: false
+
+  Determines if the helper has a destroyable to include in the destructor
+  hierarchy. If enabled, the `getDestroyable` hook will be called, and its result
+  will be associated with the destroyable parent block.
+
+  #### `hasValue`
+
+  - Default value: false
+
+  Determines if the helper has a value which can be used externally. The helper's
+  `getValue` hook will be run whenever the value of the helper is accessed if this
+  capability is enabled.
+
+  @method capabilities
+  @for @ember/helper
+  @static
+  @param {String} managerApiVersion The version of capabilities that are being used
+  @param options The capabilities values
+  @return {Capabilities} The capabilities object instance
+  @public
+*/
+const capabilities = helperCapabilities;
+
+/**
+  Sets the helper manager for an object or function.
+
+  ```js
+  setHelperManager((owner) => new ClassHelperManager(owner), Helper)
+  ```
+
+  When a value is used as a helper in a template, the helper manager is looked up
+  on the object by walking up its prototype chain and finding the first helper
+  manager. This manager then receives the value and can create and manage an
+  instance of a helper from it. This provides a layer of indirection that allows
+  users to design high-level helper APIs, without Ember needing to worry about the
+  details. High-level APIs can be experimented with and iterated on while the
+  core of Ember helpers remains stable, and new APIs can be introduced gradually
+  over time to existing code bases.
+
+  `setHelperManager` receives two arguments:
+
+  1. A factory function, which receives the `owner` and returns an instance of a
+    helper manager.
+  2. A helper definition, which is the object or function to associate the factory function with.
+
+  The first time the object is looked up, the factory function will be called to
+  create the helper manager. It will be cached, and in subsequent lookups the
+  cached helper manager will be used instead.
+
+  Only one helper manager is guaranteed to exist per `owner` and per usage of
+  `setHelperManager`, so many helpers will end up using the same instance of the
+  helper manager. As such, you should only store state that is related to the
+  manager itself. If you want to store state specific to a particular helper
+  definition, you should assign a unique helper manager to that helper. In
+  general, most managers should either be stateless, or only have the `owner` they
+  were created with as state.
+
+  Helper managers must fulfill the following interface (This example uses
+  [TypeScript interfaces](https://www.typescriptlang.org/docs/handbook/interfaces.html)
+  for precision, you do not need to write helper managers using TypeScript):
+
+  ```ts
+  interface HelperManager<HelperStateBucket> {
+    capabilities: HelperCapabilities;
+
+    createHelper(definition: HelperDefinition, args: TemplateArgs): HelperStateBucket;
+
+    getValue?(bucket: HelperStateBucket): unknown;
+
+    runEffect?(bucket: HelperStateBucket): void;
+
+    getDestroyable?(bucket: HelperStateBucket): object;
+  }
+  ```
+
+  The capabilities property _must_ be provided using the `capabilities()` function
+  imported from the same module as `setHelperManager`:
+
+  ```js
+  import { capabilities } from '@ember/helper';
+
+  class MyHelperManager {
+    capabilities = capabilities('3.21.0', { hasValue: true });
+
+    // ...snip...
+  }
+  ```
+
+  Below is a description of each of the methods on the interface and their
+  functions.
+
+  #### `createHelper`
+
+  `createHelper` is a required hook on the HelperManager interface. The hook is
+  passed the definition of the helper that is currently being created, and is
+  expected to return a _state bucket_. This state bucket is what represents the
+  current state of the helper, and will be passed to the other lifecycle hooks at
+  appropriate times. It is not necessarily related to the definition of the
+  helper itself - for instance, you could return an object _containing_ an
+  instance of the helper:
+
+  ```js
+  class MyManager {
+    createHelper(Definition, args) {
+      return {
+        instance: new Definition(args);
+      };
+    }
+  }
+  ```
+
+  This allows the manager to store metadata that it doesn't want to expose to the
+  user.
+
+  This hook is _not_ autotracked - changes to tracked values used within this hook
+  will _not_ result in a call to any of the other lifecycle hooks. This is because
+  it is unclear what should happen if it invalidates, and rather than make a
+  decision at this point, the initial API is aiming to allow as much expressivity
+  as possible. This could change in the future with changes to capabilities and
+  their behaviors.
+
+  If users do want to autotrack some values used during construction, they can
+  either create the instance of the helper in `runEffect` or `getValue`, or they
+  can use the `cache` API to autotrack the `createHelper` hook themselves. This
+  provides maximum flexibility and expressiveness to manager authors.
+
+  This hook has the following timing semantics:
+
+  **Always**
+  - called as discovered during DOM construction
+  - called in definition order in the template
+
+  #### `getValue`
+
+  `getValue` is an optional hook that should return the value of the helper. This
+  is the value that is returned from the helper and passed into the template.
+
+  This hook is called when the value is requested from the helper (e.g. when the
+  template is rendering and the helper value is needed). The hook is autotracked,
+  and will rerun whenever any tracked values used inside of it are updated.
+  Otherwise it does not rerun.
+
+  > Note: This means that arguments which are not _consumed_ within the hook will
+  > not trigger updates.
+
+  This hook is only called for helpers with the `hasValue` capability enabled.
+  This hook has the following timing semantics:
+
+  **Always**
+  - called the first time the helper value is requested
+  - called after autotracked state has changed
+
+  **Never**
+  - called if the `hasValue` capability is disabled
+
+  #### `runEffect`
+
+  `runEffect` is an optional hook that should run the effect that the helper is
+  applying, setting it up or updating it.
+
+  This hook is scheduled to be called some time after render and prior to paint.
+  There is not a guaranteed, 1-to-1 relationship between a render pass and this
+  hook firing. For instance, multiple render passes could occur, and the hook may
+  only trigger once. It may also never trigger if it was dirtied in one render
+  pass and then destroyed in the next.
+
+  The hook is autotracked, and will rerun whenever any tracked values used inside
+  of it are updated. Otherwise it does not rerun.
+
+  The hook is also run during a time period where state mutations are _disabled_
+  in Ember. Any tracked state mutation will throw an error during this time,
+  including changes to tracked properties, changes made using `set`, updates
+  to computed properties, etc. This is meant to prevent infinite rerenders and
+  other antipatterns.
+
+  This hook is only called for helpers with the `hasScheduledEffect` capability
+  enabled. This hook is also not called in SSR currently, though this could be
+  added as a capability in the future. It has the following timing semantics:
+
+  **Always**
+  - called after the helper was first created, if the helper has not been
+    destroyed since creation
+  - called after autotracked state has changed, if the helper has not been
+    destroyed during render
+
+  **Never**
+  - called if the `hasScheduledEffect` capability is disabled
+  - called in SSR
+
+  #### `getDestroyable`
+
+  `getDestroyable` is an optional hook that users can use to register a
+  destroyable object for the helper. This destroyable will be registered to the
+  containing block or template parent, and will be destroyed when it is destroyed.
+  See the [Destroyables RFC](https://github.com/emberjs/rfcs/blob/master/text/0580-destroyables.md)
+  for more details.
+
+  `getDestroyable` is only called if the `hasDestroyable` capability is enabled.
+
+  This hook has the following timing semantics:
+
+  **Always**
+  - called immediately after the `createHelper` hook is called
+
+  **Never**
+  - called if the `hasDestroyable` capability is disabled
+
+  @method setHelperManager
+  @for @ember/helper
+  @static
+  @param {Function} factory A factory function which receives an optional owner, and returns a helper manager
+  @param {object} definition The definition to associate the manager factory with
+  @return {object} The definition passed into setHelperManager
+  @public
+*/
+const setHelperManager = setHelperManager$1;
+
+/**
+  The `invokeHelper` function can be used to create a helper instance in
+  JavaScript.
+
+  To access a helper's value you have to use `getValue` from
+  `@glimmer/tracking/primitives/cache`.
+
+  ```js
+  // app/components/data-loader.js
+  import Component from '@glimmer/component';
+  import { getValue } from '@glimmer/tracking/primitives/cache';
+  import Helper from '@ember/component/helper';
+  import { invokeHelper } from '@ember/helper';
+
+  class PlusOne extends Helper {
+    compute([number]) {
+      return number + 1;
+    }
+  }
+
+  export default class PlusOneComponent extends Component {
+    plusOne = invokeHelper(this, PlusOne, () => {
+      return {
+        positional: [this.args.number],
+      };
+    });
+
+    get value() {
+      return getValue(this.plusOne);
+    }
+  }
+  ```
+  ```js
+  {{this.value}}
+  ```
+
+  It receives three arguments:
+
+  * `context`: The parent context of the helper. When the parent is torn down and
+    removed, the helper will be as well.
+  * `definition`: The definition of the helper.
+  * `computeArgs`: An optional function that produces the arguments to the helper.
+    The function receives the parent context as an argument, and must return an
+    object with a `positional` property that is an array and/or a `named`
+    property that is an object.
+
+  And it returns a Cache instance that contains the most recent value of the
+  helper. You can access the helper using `getValue()` like any other cache. The
+  cache is also destroyable, and using the `destroy()` function on it will cause
+  the helper to be torn down.
+
+  Note that using `getValue()` on helpers that have scheduled effects will not
+  trigger the effect early. Effects will continue to run at their scheduled time.
+
+  @method invokeHelper
+  @for @ember/helper
+  @static
+  @param {object} context The parent context of the helper
+  @param {object} definition The helper definition
+  @param {Function} computeArgs An optional function that produces args
+  @returns
+  @public
+*/
+const invokeHelper = invokeHelper$1;
+
+// SAFETY: we need to provide interfaces that Glint can declaration-merge with
+// to provide appropriate completions. In each case, the imported item is
+// currently typed only as `object`, and we are replacing it with a similarly
+// low-information interface type: these are empty objects which are simply able
+// to be distinguished so that Glint can provide the relevant extensions.
+/* eslint-disable @typescript-eslint/no-empty-object-type */
+
+/**
+ * Using the `{{hash}}` helper, you can pass objects directly from the template
+ * 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).
+ */
+const hash = hash$1;
+/**
+ * Using the `{{array}}` helper, you can pass arrays directly from the template
+ * as an argument to your components.
+ *
+ * ```js
+ * import { array } from '@ember/helper';
+ *
+ * <template>
+ *   <ul>
+ *   {{#each (array 'Tom Dale' 'Yehuda Katz' @anotherPerson) as |person|}}
+ *     <li>{{person}}</li>
+ *   {{/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).
+ * ```
+ */
+const array = array$1;
+/**
+ * The `{{concat}}` helper makes it easy to dynamically send a number of
+ * parameters to a component or helper as a single parameter in the format of a
+ * concatenated string.
+ *
+ * For example:
+ *
+ * ```js
+ * import { concat } from '@ember/helper';
+ *
+ * <template>
+ *   {{get @foo (concat "item" @index)}}
+ * </template>
+ * ```
+ *
+ * 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).
+ */
+const concat = concat$1;
+/**
+ * The `{{get}}` helper makes it easy to dynamically look up a property on an
+ * object or an element in an array. The second argument to `{{get}}` can be a
+ * string or a number, depending on the object being accessed.
+ *
+ * To access a property on an object with a string key:
+ *
+ * ```js
+ * import { get } from '@ember/helper';
+ *
+ * <template>
+ *   {{get @someObject "objectKey"}}
+ * </template>
+ * ```
+ *
+ * To access the first element in an array:
+ *
+ * ```js
+ * import { get } from '@ember/helper';
+ *
+ * <template>
+ *   {{get @someArray 0}}
+ * </template>
+ * ```
+ *
+ * To access a property on an object with a dynamic key:
+ *
+ * ```js
+ * import { get } from '@ember/helper';
+ *
+ * <template>
+ *   {{get @address @field}}
+ * </template>
+ * ```
+ *
+ * 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).
+ */
+const get = get$1;
+/**
+ * `{{fn}}` is a helper that receives a function and some arguments, and returns
+ * a new function that combines. This allows you to pass parameters along to
+ * functions in your templates:
+ *
+ * ```js
+ * import { fn } from '@ember/helper';
+ *
+ * function showAlert(message) {
+ *   alert(`The message is: '${message}'`);
+ * }
+ *
+ * <template>
+ *   <button type="button" {{on "click" (fn showAlert "Hello!")}}>
+ *     Click me!
+ *   </button>
+ * </template>
+ * ```
+ */
+const fn = fn$1;
+/**
+ * Use the {{uniqueId}} helper to generate a unique ID string suitable for use as
+ * an ID attribute in the DOM.
+ *
+ * Each invocation of {{uniqueId}} will return a new, unique ID string.
+ * You can use the `let` helper to create an ID that can be reused within a template.
+ *
+ * ```js
+ * import { uniqueId } from '@ember/helper';
+ *
+ * <template>
+ *   {{#let (uniqueId) as |emailId|}}
+ *     <label for={{emailId}}>Email address</label>
+ *     <input id={{emailId}} type="email" />
+ *   {{/let}}
+ * </template>
+ * ```
+ */
+const uniqueId = uniqueId$1;
+
+/* eslint-enable @typescript-eslint/no-empty-object-type */
+
+export { array, capabilities, concat, fn, get, hash, invokeHelper, setHelperManager, uniqueId };