ember-source 7.3.0-alpha.1 → 7.3.0-alpha.3

package/types/stable/@glimmer/tracking/index.d.ts

@@ -1,6 +1,7 @@
 declare module '@glimmer/tracking' {
     export { tracked } from "@ember/-internals/metal/lib/tracked";
     export { cached } from "@ember/-internals/metal/lib/cached";
+    export type { Reactive, ReadOnlyReactive, TrackedValue, } from "@glimmer/validator/lib/tracked-value";
     /**
       In order to tell Ember a value might change, we need to mark it as trackable.
       Trackable values are values that:
@@ -36,7 +37,7 @@ declare module '@glimmer/tracking' {
         plusOne() {
           this.count += 1;
         }
-        
+
         <template>
           <div>Count: {{this.count}}</div>
           <div>Times Ten: {{this.timesTen}}</div>
@@ -141,6 +142,74 @@ declare module '@glimmer/tracking' {
       });
       ```
 
+      Calling `tracked` with an initial value creates a standalone reactive
+      value, usable outside of classes:
+
+      ```js
+      import { tracked } from '@glimmer/tracking';
+
+      const count = tracked(0);
+
+      count.value;                // read the value, entangling with any tracking context
+      count.value = 1;            // write the value, notifying consumers
+      count.get();                // function shorthand for reading
+      count.set(2);               // function shorthand for writing
+      count.update((n) => n + 1); // write based on the current value, without entangling
+      count.freeze();             // prevent all future writes
+      ```
+
+      Reading `value` in a template (or in a getter used by a template) will
+      rerender just like a `@tracked` property:
+
+      ```gjs
+      import { tracked } from '@glimmer/tracking';
+      import { on } from '@ember/modifier';
+
+      const count = tracked(0);
+      const increment = () => count.value++;
+
+      <template>
+        Count is: {{count.value}}
+
+        <button {{on "click" increment}}>add one</button>
+      </template>
+      ```
+
+      This form accepts an options object containing an `equals` function, which
+      decides whether a written value should notify consumers (it defaults to
+      `Object.is`), and a `description` used for debugging:
+
+      ```js
+      const count = tracked(0, { equals: (a, b) => a === b });
+
+      count.value = 0; // does not notify consumers, the value did not change
+      ```
+
+      Note: when `tracked` is called with a single plain object whose keys are all
+      drawn from `value`, `initializer`, `equals`, and `description`, it is treated
+      as the configuration object for a decorator (or classic-class field), not as a
+      standalone value wrapping that object. To create a standalone reactive value
+      around such an object, pass it as an initial value and include a (possibly
+      empty) options argument: `tracked({ value: 5 }, {})`.
+
+      The `@tracked` decorator accepts the same options. By default, setting a
+      `@tracked` property always notifies consumers, even when setting the
+      property to the same value; passing `equals` opts in to equality-based
+      notification instead:
+
+      ```js
+      import { tracked } from '@glimmer/tracking';
+
+      class Counter {
+        @tracked({ equals: (a, b) => a === b }) count = 0;
+
+        noop = () => {
+          // does not notify consumers, the value did not change
+          this.count = this.count;
+        };
+      }
+      ```
+
       @method tracked
       @static
       @for @glimmer/tracking

package/types/stable/@glimmer/validator/index.d.ts

@@ -8,6 +8,7 @@ declare module '@glimmer/validator' {
     export { debug } from "@glimmer/validator/lib/debug";
     export { dirtyTagFor, tagFor, type TagMeta, tagMetaFor } from "@glimmer/validator/lib/meta";
     export { trackedData } from "@glimmer/validator/lib/tracked-data";
+    export { type Reactive, type ReadOnlyReactive, TrackedValue, trackedValue, } from "@glimmer/validator/lib/tracked-value";
     export { beginTrackFrame, beginUntrackFrame, type Cache, consumeTag, createCache, endTrackFrame, endUntrackFrame, getValue, isConst, isTracking, resetTracking, track, untrack, } from "@glimmer/validator/lib/tracking";
     export { ALLOW_CYCLES, bump, combine, COMPUTE, CONSTANT, CONSTANT_TAG, createTag, createUpdatableTag, CURRENT_TAG, CurrentTag, DIRTY_TAG as dirtyTag, INITIAL, isConstTag, type Revision, UPDATE_TAG as updateTag, validateTag, valueForTag, VOLATILE, VOLATILE_TAG, VolatileTag, } from "@glimmer/validator/lib/validators";
     export type { CombinatorTag, ConstantTag, DirtyableTag, Tag, UpdatableTag, } from "@glimmer/interfaces";

package/types/stable/@glimmer/validator/lib/tracked-value.d.ts

@@ -0,0 +1,58 @@
+declare module '@glimmer/validator/lib/tracked-value' {
+    import type { ReactiveOptions } from "@glimmer/validator/lib/collections/types";
+    /**
+     * A mutable reactive value.
+     *
+     * Reading `value` consumes the underlying tag (entangling with any active
+     * tracking frame), and writing `value` dirties it.
+     */
+    export interface Reactive<Value> {
+        value: Value;
+    }
+    /**
+     * A reactive value that can only be read.
+     */
+    export interface ReadOnlyReactive<Value> extends Reactive<Value> {
+        readonly value: Value;
+    }
+    export class TrackedValue<Value = unknown> implements Reactive<Value> {
+        #private;
+        constructor(value: Value, options: ReactiveOptions<Value>);
+        /**
+         * The underlying value.
+         *
+         * Reading entangles with the current tracking frame, and writing notifies
+         * consumers (unless the configured `equals` deems the new value equal to
+         * the current one).
+         */
+        get value(): Value;
+        set value(value: Value);
+        /**
+         * Function short-hand for reading `value`.
+         */
+        get: () => Value;
+        /**
+         * Function short-hand for assigning `value`.
+         *
+         * Returns `true` if the value changed (and consumers were notified),
+         * `false` if the new value was equal to the current one.
+         */
+        set: (value: Value) => boolean;
+        /**
+         * Update the value based on the current value, without consuming it.
+         */
+        update: (updater: (value: Value) => Value) => void;
+        /**
+         * Prevents further updates, making the TrackedValue behave as a
+         * ReadOnlyReactive.
+         */
+        freeze: () => void;
+    }
+    export function trackedValue<Value>(
+     value: Value,
+     options?: {
+         equals?: (a: Value, b: Value) => boolean;
+         description?: string;
+     }
+    ): TrackedValue<Value>;
+}

package/types/stable/index.d.ts

@@ -97,6 +97,7 @@
 /// <reference path="./@glimmer/validator/lib/validators.d.ts" />
 /// <reference path="./@glimmer/validator/lib/utils.d.ts" />
 /// <reference path="./@glimmer/validator/lib/tracking.d.ts" />
+/// <reference path="./@glimmer/validator/lib/tracked-value.d.ts" />
 /// <reference path="./@glimmer/validator/lib/tracked-data.d.ts" />
 /// <reference path="./@glimmer/validator/lib/meta.d.ts" />
 /// <reference path="./@glimmer/validator/lib/debug.d.ts" />

package/dist/dev/packages/shared-chunks/tracked-DEyf0T_X.js

@@ -1,148 +0,0 @@
-import { meta } from '../@ember/-internals/meta/lib/meta.js';
-import { isEmberArray } from '../@ember/array/-internals.js';
-import '../@ember/debug/index.js';
-import { c as consumeTag } from './cache-DGDPVCpC.js';
-import { d as dirtyTagFor, t as tagFor } from './meta-BqC7f9Ia.js';
-import { t as trackedData } from './tracked-data-DgqqRdYO.js';
-import { S as SELF_TAG, C as CHAIN_PASS_THROUGH } from './chain-tags-uWSImHzB.js';
-import { s as setClassicDecorator, i as isElementDescriptor, C as COMPUTED_SETTERS } from './decorator-B5Uh5NFI.js';
-import { assert } from '../@ember/debug/lib/assert.js';
-
-/**
-  @decorator
-  @private
-
-  Marks a property as tracked.
-
-  By default, a component's properties are expected to be static,
-  meaning you are not able to update them and have the template update accordingly.
-  Marking a property as tracked means that when that property changes,
-  a rerender of the component is scheduled so the template is kept up to date.
-
-  There are two usages for the `@tracked` decorator, shown below.
-
-  @example No dependencies
-
-  If you don't pass an argument to `@tracked`, only changes to that property
-  will be tracked:
-
-  ```typescript
-  import Component from '@glimmer/component';
-  import { tracked } from '@glimmer/tracking';
-
-  export default class MyComponent extends Component {
-    @tracked
-    remainingApples = 10
-  }
-  ```
-
-  When something changes the component's `remainingApples` property, the rerender
-  will be scheduled.
-
-  @example Dependents
-
-  In the case that you have a computed property that depends other
-  properties, you want to track both so that when one of the
-  dependents change, a rerender is scheduled.
-
-  In the following example we have two properties,
-  `eatenApples`, and `remainingApples`.
-
-  ```typescript
-  import Component from '@glimmer/component';
-  import { tracked } from '@glimmer/tracking';
-
-  const totalApples = 100;
-
-  export default class MyComponent extends Component {
-    @tracked
-    eatenApples = 0
-
-    get remainingApples() {
-      return totalApples - this.eatenApples;
-    }
-
-    increment() {
-      this.eatenApples = this.eatenApples + 1;
-    }
-  }
-  ```
-
-  @param dependencies Optional dependents to be tracked.
-*/
-
-function tracked(...args) {
-  (!(!(isElementDescriptor(args.slice(0, 3)) && args.length === 5 && args[4] === true)) && assert(`@tracked can only be used directly as a native decorator. If you're using tracked in classic classes, add parenthesis to call it like a function: tracked()`, !(isElementDescriptor(args.slice(0, 3)) && args.length === 5 && args[4] === true)));
-  if (!isElementDescriptor(args)) {
-    let propertyDesc = args[0];
-    (!(args.length === 0 || typeof propertyDesc === 'object' && propertyDesc !== null) && assert(`tracked() may only receive an options object containing 'value' or 'initializer', received ${propertyDesc}`, args.length === 0 || typeof propertyDesc === 'object' && propertyDesc !== null));
-    if (propertyDesc) {
-      let keys = Object.keys(propertyDesc);
-      (!(keys.length <= 1 && (keys[0] === undefined || keys[0] === 'value' || keys[0] === 'initializer')) && assert(`The options object passed to tracked() may only contain a 'value' or 'initializer' property, not both. Received: [${keys}]`, keys.length <= 1 && (keys[0] === undefined || keys[0] === 'value' || keys[0] === 'initializer')));
-      (!(!('initializer' in propertyDesc) || typeof propertyDesc.initializer === 'function') && assert(`The initializer passed to tracked must be a function. Received ${propertyDesc.initializer}`, !('initializer' in propertyDesc) || typeof propertyDesc.initializer === 'function'));
-    }
-    let initializer = propertyDesc ? propertyDesc.initializer : undefined;
-    let value = propertyDesc ? propertyDesc.value : undefined;
-    let decorator = function (target, key, _desc, _meta, isClassicDecorator) {
-      (!(isClassicDecorator) && assert(`You attempted to set a default value for ${key} with the @tracked({ value: 'default' }) syntax. You can only use this syntax with classic classes. For native classes, you can use class initializers: @tracked field = 'default';`, isClassicDecorator));
-      let fieldDesc = {
-        initializer: initializer || (() => value)
-      };
-      return descriptorForField([target, key, fieldDesc]);
-    };
-    setClassicDecorator(decorator);
-    return decorator;
-  }
-  return descriptorForField(args);
-}
-{
-  // Normally this isn't a classic decorator, but we want to throw a helpful
-  // error in development so we need it to treat it like one
-  setClassicDecorator(tracked);
-}
-function descriptorForField([target, key, desc]) {
-  (!(!desc || !desc.value && !desc.get && !desc.set) && assert(`You attempted to use @tracked on ${key}, but that element is not a class field. @tracked is only usable on class fields. Native getters and setters will autotrack add any tracked fields they encounter, so there is no need mark getters and setters with @tracked.`, !desc || !desc.value && !desc.get && !desc.set));
-  let {
-    getter,
-    setter
-  } = trackedData(key, desc ? desc.initializer : undefined);
-  function get() {
-    let value = getter(this);
-
-    // Add the tag of the returned value if it is an array, since arrays
-    // should always cause updates if they are consumed and then changed
-    if (Array.isArray(value) || isEmberArray(value)) {
-      consumeTag(tagFor(value, '[]'));
-    }
-    return value;
-  }
-  function set(newValue) {
-    setter(this, newValue);
-    dirtyTagFor(this, SELF_TAG);
-  }
-  let newDesc = {
-    enumerable: true,
-    configurable: true,
-    isTracked: true,
-    get,
-    set
-  };
-  COMPUTED_SETTERS.add(set);
-  meta(target).writeDescriptors(key, new TrackedDescriptor(get, set));
-  return newDesc;
-}
-class TrackedDescriptor {
-  constructor(_get, _set) {
-    this._get = _get;
-    this._set = _set;
-    CHAIN_PASS_THROUGH.add(this);
-  }
-  get(obj) {
-    return this._get.call(obj);
-  }
-  set(obj, _key, value) {
-    this._set.call(obj, value);
-  }
-}
-
-export { TrackedDescriptor as T, tracked as t };

package/dist/dev/packages/shared-chunks/tracked-data-DgqqRdYO.js

@@ -1,31 +0,0 @@
-import { d as dirtyTagFor, t as tagFor } from './meta-BqC7f9Ia.js';
-import { c as consumeTag } from './cache-DGDPVCpC.js';
-
-function trackedData(key, initializer) {
-  let values = new WeakMap();
-  let hasInitializer = typeof initializer === 'function';
-  function getter(self) {
-    consumeTag(tagFor(self, key));
-    let value;
-
-    // If the field has never been initialized, we should initialize it
-    if (hasInitializer && !values.has(self)) {
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- @fixme
-      value = initializer.call(self);
-      values.set(self, value);
-    } else {
-      value = values.get(self);
-    }
-    return value;
-  }
-  function setter(self, value) {
-    dirtyTagFor(self, key);
-    values.set(self, value);
-  }
-  return {
-    getter,
-    setter
-  };
-}
-
-export { trackedData as t };

package/dist/prod/packages/shared-chunks/tracked-B9380JtC.js

@@ -1,132 +0,0 @@
-import { meta } from '../@ember/-internals/meta/lib/meta.js';
-import { isEmberArray } from '../@ember/array/-internals.js';
-import { c as consumeTag } from './cache-CofLhaS4.js';
-import { d as dirtyTagFor, t as tagFor } from './meta-BJtIZDir.js';
-import { t as trackedData } from './tracked-data-CHq42QHb.js';
-import { C as CHAIN_PASS_THROUGH, S as SELF_TAG } from './chain-tags-B2J7DsxO.js';
-import { i as isElementDescriptor, s as setClassicDecorator, C as COMPUTED_SETTERS } from './decorator-9ikVwsjY.js';
-
-/**
-  @decorator
-  @private
-
-  Marks a property as tracked.
-
-  By default, a component's properties are expected to be static,
-  meaning you are not able to update them and have the template update accordingly.
-  Marking a property as tracked means that when that property changes,
-  a rerender of the component is scheduled so the template is kept up to date.
-
-  There are two usages for the `@tracked` decorator, shown below.
-
-  @example No dependencies
-
-  If you don't pass an argument to `@tracked`, only changes to that property
-  will be tracked:
-
-  ```typescript
-  import Component from '@glimmer/component';
-  import { tracked } from '@glimmer/tracking';
-
-  export default class MyComponent extends Component {
-    @tracked
-    remainingApples = 10
-  }
-  ```
-
-  When something changes the component's `remainingApples` property, the rerender
-  will be scheduled.
-
-  @example Dependents
-
-  In the case that you have a computed property that depends other
-  properties, you want to track both so that when one of the
-  dependents change, a rerender is scheduled.
-
-  In the following example we have two properties,
-  `eatenApples`, and `remainingApples`.
-
-  ```typescript
-  import Component from '@glimmer/component';
-  import { tracked } from '@glimmer/tracking';
-
-  const totalApples = 100;
-
-  export default class MyComponent extends Component {
-    @tracked
-    eatenApples = 0
-
-    get remainingApples() {
-      return totalApples - this.eatenApples;
-    }
-
-    increment() {
-      this.eatenApples = this.eatenApples + 1;
-    }
-  }
-  ```
-
-  @param dependencies Optional dependents to be tracked.
-*/
-
-function tracked(...args) {
-  if (!isElementDescriptor(args)) {
-    let propertyDesc = args[0];
-    let initializer = propertyDesc ? propertyDesc.initializer : undefined;
-    let value = propertyDesc ? propertyDesc.value : undefined;
-    let decorator = function (target, key, _desc, _meta, isClassicDecorator) {
-      let fieldDesc = {
-        initializer: initializer || (() => value)
-      };
-      return descriptorForField([target, key, fieldDesc]);
-    };
-    setClassicDecorator(decorator);
-    return decorator;
-  }
-  return descriptorForField(args);
-}
-function descriptorForField([target, key, desc]) {
-  let {
-    getter,
-    setter
-  } = trackedData(key, desc ? desc.initializer : undefined);
-  function get() {
-    let value = getter(this);
-
-    // Add the tag of the returned value if it is an array, since arrays
-    // should always cause updates if they are consumed and then changed
-    if (Array.isArray(value) || isEmberArray(value)) {
-      consumeTag(tagFor(value, '[]'));
-    }
-    return value;
-  }
-  function set(newValue) {
-    setter(this, newValue);
-    dirtyTagFor(this, SELF_TAG);
-  }
-  let newDesc = {
-    enumerable: true,
-    configurable: true,
-    isTracked: true,
-    get,
-    set
-  };
-  COMPUTED_SETTERS.add(set);
-  meta(target).writeDescriptors(key, new TrackedDescriptor(get, set));
-  return newDesc;
-}
-class TrackedDescriptor {
-  constructor(_get, _set) {
-    this._get = _get;
-    this._set = _set;
-    CHAIN_PASS_THROUGH.add(this);
-  }
-  get(obj) {
-    return this._get.call(obj);
-  }
-  set(obj, _key, value) {
-    this._set.call(obj, value);
-  }
-}
-
-export { TrackedDescriptor as T, tracked as t };

package/dist/prod/packages/shared-chunks/tracked-data-CHq42QHb.js

@@ -1,31 +0,0 @@
-import { d as dirtyTagFor, t as tagFor } from './meta-BJtIZDir.js';
-import { c as consumeTag } from './cache-CofLhaS4.js';
-
-function trackedData(key, initializer) {
-  let values = new WeakMap();
-  let hasInitializer = typeof initializer === 'function';
-  function getter(self) {
-    consumeTag(tagFor(self, key));
-    let value;
-
-    // If the field has never been initialized, we should initialize it
-    if (hasInitializer && !values.has(self)) {
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- @fixme
-      value = initializer.call(self);
-      values.set(self, value);
-    } else {
-      value = values.get(self);
-    }
-    return value;
-  }
-  function setter(self, value) {
-    dirtyTagFor(self, key);
-    values.set(self, value);
-  }
-  return {
-    getter,
-    setter
-  };
-}
-
-export { trackedData as t };