ember-source 7.1.0-alpha.4 → 7.1.0-alpha.5

package/dist/dev/packages/shared-chunks/hash-D3BENmhU.js

@@ -0,0 +1,192 @@
+import { a as createComputeRef, b as isInvokableRef, u as updateRef, v as valueForRef } from './reference-BoPB2LfI.js';
+import { f as reifyPositional, g as buildUntouchableThis, h as check, e as reifyNamed } from './untouchable-this-cH6_N2LJ.js';
+import { j as setInternalHelperManager } from './api-WvJPuo9z.js';
+
+function internalHelper(helper) {
+  return setInternalHelperManager(helper, {});
+}
+
+/**
+   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
+ */
+
+const array = internalHelper(({
+  positional
+}) => {
+  return createComputeRef(() => reifyPositional(positional), null, 'array');
+});
+
+const context = buildUntouchableThis('`fn` helper');
+
+/**
+  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
+*/
+const fn = internalHelper(({
+  positional
+}) => {
+  let callbackRef = check(positional[0]);
+  return createComputeRef(() => {
+    return (...invocationArgs) => {
+      let [fn, ...args] = reifyPositional(positional);
+      assertCallbackIsFn(callbackRef);
+      if (isInvokableRef(callbackRef)) {
+        let value = args.length > 0 ? args[0] : invocationArgs[0];
+        return void updateRef(callbackRef, value);
+      } else {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return -- @fixme
+        return fn.call(context, ...args, ...invocationArgs);
+      }
+    };
+  }, null, 'fn');
+});
+function assertCallbackIsFn(callbackRef) {
+  if (!(callbackRef && (isInvokableRef(callbackRef) || typeof valueForRef(callbackRef) === 'function'))) {
+    throw new Error(`You must pass a function as the \`fn\` helper's first argument, you passed ${callbackRef ? valueForRef(callbackRef) : callbackRef}. While rendering:\n\n${callbackRef?.debugLabel}`);
+  }
+}
+
+/**
+   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
+ */
+const hash = internalHelper(({
+  named
+}) => {
+  let ref = createComputeRef(() => {
+    return reifyNamed(named);
+  }, null, 'hash');
+
+  // Setup the children so that templates can bypass getting the value of
+  // the reference and treat children lazily
+  let children = new Map();
+  for (let name in named) {
+    children.set(name, named[name]);
+  }
+  ref.children = children;
+  return ref;
+});
+
+export { array as a, fn as f, hash as h, internalHelper as i };

package/dist/dev/packages/shared-chunks/helper-DlC4YesW.js

@@ -0,0 +1,314 @@
+import { setOwner } from '../@ember/-internals/owner/index.js';
+import { FrameworkObject } from '../@ember/object/-internals.js';
+import { g as getDebugName } from './get-debug-name-CSniHBsn.js';
+import '../@ember/debug/index.js';
+import { join } from '../@ember/runloop/index.js';
+import { a as getInternalHelperManager, i as helperCapabilities } from './api-WvJPuo9z.js';
+import { b as setHelperManager } from './api-AYt3zE12.js';
+import { m as createTag, D as DIRTY_TAG, k as consumeTag } from './cache-B7dqAS38.js';
+import { assert } from '../@ember/debug/lib/assert.js';
+
+/**
+@module @ember/component
+*/
+
+const RECOMPUTE_TAG = Symbol('RECOMPUTE_TAG');
+
+// Signature type utilities
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+
+// Implements Ember's `Factory` interface and tags it for narrowing/checking.
+
+const IS_CLASSIC_HELPER = Symbol('IS_CLASSIC_HELPER');
+
+// A zero-runtime-overhead private symbol to use in branding the component to
+// preserve its type parameter.
+
+/**
+  Ember Helpers are functions that can compute values, and are used in templates.
+  For example, this code calls a helper named `format-currency`:
+
+  ```app/templates/application.hbs
+  <Cost @cents={{230}} />
+  ```
+
+  ```app/components/cost.hbs
+  <div>{{format-currency @cents currency="$"}}</div>
+  ```
+
+  Additionally a helper can be called as a nested helper.
+  In this example, we show the formatted currency value if the `showMoney`
+  named argument is truthy.
+
+  ```handlebars
+  {{if @showMoney (format-currency @cents currency="$")}}
+  ```
+
+  Helpers defined using a class must provide a `compute` function. For example:
+
+  ```app/helpers/format-currency.js
+  import Helper from '@ember/component/helper';
+
+  export default class extends Helper {
+    compute([cents], { currency }) {
+      return `${currency}${cents * 0.01}`;
+    }
+  }
+  ```
+
+  Each time the input to a helper changes, the `compute` function will be
+  called again.
+
+  As instances, these helpers also have access to the container and will accept
+  injected dependencies.
+
+  Additionally, class helpers can call `recompute` to force a new computation.
+
+  @class Helper
+  @extends CoreObject
+  @public
+  @since 1.13.0
+*/
+// ESLint doesn't understand declaration merging.
+/* eslint-disable import/export */
+
+class Helper extends FrameworkObject {
+  static isHelperFactory = true;
+  static [IS_CLASSIC_HELPER] = true;
+
+  // `packages/ember/index.js` was setting `Helper.helper`. This seems like
+  // a bad idea and probably not something we want. We've moved that definition
+  // here, but it should definitely be reviewed and probably removed.
+  /** @deprecated */
+  static helper = helper;
+
+  // SAFETY: this is initialized in `init`, rather than `constructor`. It is
+  // safe to `declare` like this *if and only if* nothing uses the constructor
+  // directly in this class, since nothing else can run before `init`.
+
+  // SAFETY: this has no runtime existence whatsoever; it is a "phantom type"
+  // here to preserve the type param.
+
+  init(properties) {
+    super.init(properties);
+    this[RECOMPUTE_TAG] = createTag();
+    (!(this.compute) && assert('expected compute to be defined', this.compute));
+  }
+
+  /**
+    On a class-based helper, it may be useful to force a recomputation of that
+    helpers value. This is akin to `rerender` on a component.
+     In most cases, `recompute` is not needed because accessing tracked
+    properties in `compute` will automatically re-run the helper when
+    those properties change. Use `recompute` only when you need to
+    trigger a recomputation imperatively, for example in response to an
+    external event:
+     ```app/helpers/current-time.js
+    import Helper from '@ember/component/helper';
+     export default class CurrentTimeHelper extends Helper {
+      interval = null;
+       compute() {
+        return new Date().toLocaleTimeString();
+      }
+       constructor() {
+        super(...arguments);
+        this.interval = setInterval(() => this.recompute(), 1000);
+      }
+       willDestroy() {
+        super.willDestroy();
+        clearInterval(this.interval);
+      }
+    }
+    ```
+     @method recompute
+    @public
+    @since 1.13.0
+  */
+  recompute() {
+    join(() => DIRTY_TAG(this[RECOMPUTE_TAG]));
+  }
+}
+/* eslint-enable import/export */
+
+function isClassicHelper(obj) {
+  return obj[IS_CLASSIC_HELPER] === true;
+}
+class ClassicHelperManager {
+  capabilities = helperCapabilities('3.23', {
+    hasValue: true,
+    hasDestroyable: true
+  });
+  ownerInjection;
+  constructor(owner) {
+    let ownerInjection = {};
+    setOwner(ownerInjection, owner);
+    this.ownerInjection = ownerInjection;
+  }
+  createHelper(definition, args) {
+    let instance = isFactoryManager(definition) ? definition.create() : definition.create(this.ownerInjection);
+    (!(function (instance) {
+      if (instance !== null && typeof instance === 'object') {
+        let cast = instance;
+        return typeof cast.compute === 'function' && typeof cast.destroy === 'function';
+      }
+      return false;
+    }(instance)) && assert('expected HelperInstance', function (instance) {
+      if (instance !== null && typeof instance === 'object') {
+        let cast = instance;
+        return typeof cast.compute === 'function' && typeof cast.destroy === 'function';
+      }
+      return false;
+    }(instance)));
+    return {
+      instance,
+      args
+    };
+  }
+  getDestroyable({
+    instance
+  }) {
+    return instance;
+  }
+  getValue({
+    instance,
+    args
+  }) {
+    let {
+      positional,
+      named
+    } = args;
+    let ret = instance.compute(positional, named);
+    consumeTag(instance[RECOMPUTE_TAG]);
+    return ret;
+  }
+  getDebugName(definition) {
+    return getDebugName((definition.class || definition)['prototype']);
+  }
+}
+function isFactoryManager(obj) {
+  return obj != null && 'class' in obj;
+}
+setHelperManager(owner => {
+  return new ClassicHelperManager(owner);
+}, Helper);
+const CLASSIC_HELPER_MANAGER = getInternalHelperManager(Helper);
+
+///////////
+
+class Wrapper {
+  isHelperFactory = true;
+  constructor(compute) {
+    this.compute = compute;
+  }
+  create() {
+    // needs new instance or will leak containers
+    return {
+      compute: this.compute
+    };
+  }
+}
+class SimpleClassicHelperManager {
+  capabilities = helperCapabilities('3.23', {
+    hasValue: true
+  });
+  createHelper(definition, args) {
+    return () => definition.compute.call(null, args.positional, args.named);
+  }
+  getValue(fn) {
+    return fn();
+  }
+  getDebugName(definition) {
+    return getDebugName(definition.compute);
+  }
+}
+const SIMPLE_CLASSIC_HELPER_MANAGER = new SimpleClassicHelperManager();
+setHelperManager(() => SIMPLE_CLASSIC_HELPER_MANAGER, Wrapper.prototype);
+
+/*
+  Function-based helpers need to present with a constructor signature so that
+  type parameters can be preserved when `helper()` is passed a generic function
+  (this is particularly key for checking helper invocations with Glint).
+  Accordingly, we define an abstract class and declaration merge it with the
+  interface; this inherently provides an `abstract` constructor. Since it is
+  `abstract`, it is not callable, which is important since end users should not
+  be able to do `let myHelper = helper(someFn); new myHelper()`.
+ */
+
+/**
+ * The type of a function-based helper.
+ *
+ * @note This is *not* user-constructible: it is exported only so that the type
+ *   returned by the `helper` function can be named (and indeed can be exported
+ *   like `export default helper(...)` safely).
+ */
+// Making `FunctionBasedHelper` an alias this way allows callers to name it in
+// terms meaningful to *them*, while preserving the type behavior described on
+// the `abstract class FunctionBasedHelperInstance` below.
+
+// This abstract class -- specifically, its `protected abstract __concrete__`
+// member -- prevents subclasses from doing `class X extends helper(..)`, since
+// that is an error at runtime. While it is rare that people would type that, it
+// is not impossible and we use this to give them early signal via the types for
+// a behavior which will break (and in a somewhat inscrutable way!) at runtime.
+//
+// This is needful because we lie about what this actually is for Glint's sake:
+// a function-based helper returns a `Factory<SimpleHelper>`, which is designed
+// to be "opaque" from a consumer's POV, i.e. not user-callable or constructible
+// but only useable in a template (or via `invokeHelper()` which also treats it
+// as a fully opaque `object` from a type POV). But Glint needs a `Helper<S>` to
+// make it work the same way as class-based helpers. (Note that this does not
+// hold for plain functions as helpers, which it can handle distinctly.) This
+// signature thus makes it so that the item is usable *as* a `Helper` in Glint,
+// but without letting end users treat it as a helper class instance.
+
+/**
+  In many cases it is not necessary to use the full `Helper` class.
+  The `helper` method create pure-function helpers without instances.
+  For example:
+
+  ```app/helpers/format-currency.js
+  import { helper } from '@ember/component/helper';
+
+  export default helper(function([cents], {currency}) {
+    return `${currency}${cents * 0.01}`;
+  });
+  ```
+
+  @static
+  @param {Function} helper The helper function
+  @method helper
+  @for @ember/component/helper
+  @public
+  @since 1.13.0
+*/
+// This overload allows users to write types directly on the callback passed to
+// the `helper` function and infer the resulting type correctly.
+
+// This overload allows users to provide a `Signature` type explicitly at the
+// helper definition site, e.g. `helper<Sig>((pos, named) => {...})`. **Note:**
+// this overload must appear second, since TS' inference engine will not
+// correctly infer the type of `S` here from the types on the supplied callback.
+
+function helper(helperFn) {
+  // SAFETY: this is completely lies, in two ways:
+  //
+  // 1. `Wrapper` is a `Factory<SimpleHelper<S>>`, but from the perspective of
+  //    any external callers (i.e. Ember *users*), it is quite important that
+  //    the `Factory` relationship be hidden, because it is not public API for
+  //    an end user to call `.create()` on a helper created this way. Instead,
+  //    we provide them an `abstract new` signature (which means it cannot be
+  //    directly constructed by calling `new` on it) and which does not have the
+  //    `.create()` signature on it anymore.
+  //
+  // 2. The produced type here ends up being a subtype of `Helper`, which is not
+  //    strictly true. This is necessary for the sake of Glint, which provides
+  //    its information by way of a "declaration merge" with `Helper<S>` in the
+  //    case of items produced by `helper()`.
+  //
+  // Long-term, this entire construct can go away in favor of deprecating the
+  // `helper()` invocation in favor of using plain functions.
+  return new Wrapper(helperFn);
+}
+
+export { CLASSIC_HELPER_MANAGER as C, Helper as H, helper as h, isClassicHelper as i };