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

package/dist/prod/packages/shared-chunks/tracked-value-CR6kx-73.js

@@ -0,0 +1,115 @@
+import { d as dirtyTagFor, t as tagFor } from './meta-BJtIZDir.js';
+import { c as consumeTag, b as createUpdatableTag, D as DIRTY_TAG } 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
+  };
+}
+
+/**
+ * A mutable reactive value.
+ *
+ * Reading `value` consumes the underlying tag (entangling with any active
+ * tracking frame), and writing `value` dirties it.
+ */
+
+/**
+ * A reactive value that can only be read.
+ */
+
+class TrackedValue {
+  #isFrozen = false;
+  #value;
+  #options;
+  #tag;
+  constructor(value, options) {
+    this.#value = value;
+    this.#options = options;
+    this.#tag = createUpdatableTag();
+  }
+
+  /**
+   * 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() {
+    consumeTag(this.#tag);
+    return this.#value;
+  }
+  set value(value) {
+    this.set(value);
+  }
+
+  /**
+   * Function short-hand for reading `value`.
+   */
+  get = () => {
+    return this.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 => {
+    if (this.#isFrozen) {
+      throw new Error(`Cannot update a frozen TrackedValue${this.#options.description ? ` (\`${this.#options.description}\`)` : ''}`);
+    }
+    if (this.#options.equals(this.#value, value)) {
+      return false;
+    }
+    this.#value = value;
+    DIRTY_TAG(this.#tag);
+    return true;
+  };
+
+  /**
+   * Update the value based on the current value, without consuming it.
+   */
+  update = updater => {
+    this.set(updater(this.#value));
+  };
+
+  /**
+   * Prevents further updates, making the TrackedValue behave as a
+   * ReadOnlyReactive.
+   */
+  freeze = () => {
+    this.#isFrozen = true;
+  };
+}
+function trackedValue(value, options) {
+  return new TrackedValue(value, {
+    equals: options?.equals ?? Object.is,
+    description: options?.description
+  });
+}
+
+export { TrackedValue as T, trackedData as a, trackedValue as t };

package/docs/data.json

@@ -3,7 +3,7 @@
     "name": "The Ember API",
     "description": "The Ember API: a framework for building ambitious web applications",
     "url": "https://emberjs.com/",
-    "version": "7.3.0-alpha.1"
+    "version": "7.3.0-alpha.3"
   },
   "files": {
     "node_modules/rsvp/lib/rsvp/promise/all.js": {
@@ -2532,6 +2532,13 @@
       "fors": {},
       "namespaces": {}
     },
+    "packages/@glimmer/validator/lib/tracked-value.ts": {
+      "name": "packages/@glimmer/validator/lib/tracked-value.ts",
+      "modules": {},
+      "classes": {},
+      "fors": {},
+      "namespaces": {}
+    },
     "packages/@glimmer/validator/lib/tracking.ts": {
       "name": "packages/@glimmer/validator/lib/tracking.ts",
       "modules": {},
@@ -2774,7 +2781,7 @@
       "namespaces": {},
       "tag": "module",
       "file": "packages/@glimmer/tracking/index.ts",
-      "line": 4,
+      "line": 10,
       "description": "In order to tell Ember a value might change, we need to mark it as trackable.\nTrackable values are values that:\n\n- Can change over their component’s lifetime and\n- Should cause Ember to rerender if and when they change\n\nWe can do this by marking the field with the `@tracked` decorator.",
       "access": "public",
       "tagname": ""
@@ -7896,7 +7903,7 @@
     {
       "file": "packages/@ember/-internals/glimmer/lib/glimmer-tracking-docs.ts",
       "line": 22,
-      "description": "Marks a property as tracked. By default, values that are rendered in Ember app\ntemplates are _static_, meaning that updates to them won't cause the\napplication to rerender. Marking a property as tracked means that when that\nproperty changes, any templates that used that property, directly or\nindirectly, will rerender. For instance, consider this component:\n\n```gjs\nimport Component from '@glimmer/component';\nimport { tracked } from '@glimmer/tracking';\nimport { action } from '@ember/object';\n\nexport default class CounterComponent extends Component {\n  @tracked count = 0;\n\n  get timesTen() {\n    return this.count * 10;\n  }\n\n  @action\n  plusOne() {\n    this.count += 1;\n  }\n  \n  <template>\n    <div>Count: {{this.count}}</div>\n    <div>Times Ten: {{this.timesTen}}</div>\n    <div>\n      <button {{on \"click\" this.plusOne}}>\n        Plus One\n      </button>\n    </div>\n  </template>\n}\n```\n\nBoth the `{{this.count}}` and the `{{this.timesTen}}` properties in the\ntemplate will update whenever the button is clicked. Any tracked properties\nthat are used in any way to calculate a value that is used in the template\nwill cause a rerender when updated - this includes through method calls and\nother means:\n\n```gjs\nimport Component from '@glimmer/component';\nimport { tracked } from '@glimmer/tracking';\n\nclass Entry {\n  @tracked name;\n  @tracked phoneNumber;\n\n  constructor(name, phoneNumber) {\n    this.name = name;\n    this.phoneNumber = phoneNumber;\n  }\n}\n\nexport default class PhoneBookComponent extends Component {\n  entries = [\n    new Entry('Pizza Palace', 5551234),\n    new Entry('1st Street Cleaners', 5554321),\n    new Entry('Plants R Us', 5552468),\n  ];\n\n  // Any usage of this property will update whenever any of the names in the\n  // entries arrays are updated\n  get names() {\n    return this.entries.map(e => e.name);\n  }\n\n  // Any usage of this property will update whenever any of the numbers in the\n  // entries arrays are updated\n  get numbers() {\n    return this.getFormattedNumbers();\n  }\n\n  getFormattedNumbers() {\n    return this.entries\n      .map(e => e.phoneNumber)\n      .map(number => {\n        let numberString = '' + number;\n\n        return numberString.slice(0, 3) + '-' + numberString.slice(3);\n      });\n  }\n}\n```\n\nIt's important to note that setting tracked properties will always trigger an\nupdate, even if the property is set to the same value as it was before.\n\n```js\nlet entry = new Entry('Pizza Palace', 5551234);\n\n// if entry was used when rendering, this would cause a rerender, even though\n// the name is being set to the same value as it was before\nentry.name = entry.name;\n```\n\n`tracked` can also be used with the classic Ember object model in a similar\nmanner to classic computed properties:\n\n```javascript\nimport EmberObject from '@ember/object';\nimport { tracked } from '@glimmer/tracking';\n\nconst Entry = EmberObject.extend({\n  name: tracked(),\n  phoneNumber: tracked()\n});\n```\n\nOften this is unnecessary, but to ensure robust auto-tracking behavior it is\nadvisable to mark tracked state appropriately wherever possible.\n\nThis form of `tracked` also accepts an optional configuration object\ncontaining either an initial `value` or an `initializer` function (but not\nboth).\n\n```javascript\nimport EmberObject from '@ember/object';\nimport { tracked } from '@glimmer/tracking';\n\nconst Entry = EmberObject.extend({\n  name: tracked({ value: 'Zoey' }),\n  favoriteSongs: tracked({\n    initializer: () => ['Raspberry Beret', 'Time After Time']\n  })\n});\n```",
+      "description": "Marks a property as tracked. By default, values that are rendered in Ember app\ntemplates are _static_, meaning that updates to them won't cause the\napplication to rerender. Marking a property as tracked means that when that\nproperty changes, any templates that used that property, directly or\nindirectly, will rerender. For instance, consider this component:\n\n```gjs\nimport Component from '@glimmer/component';\nimport { tracked } from '@glimmer/tracking';\nimport { action } from '@ember/object';\n\nexport default class CounterComponent extends Component {\n  @tracked count = 0;\n\n  get timesTen() {\n    return this.count * 10;\n  }\n\n  @action\n  plusOne() {\n    this.count += 1;\n  }\n  \n  <template>\n    <div>Count: {{this.count}}</div>\n    <div>Times Ten: {{this.timesTen}}</div>\n    <div>\n      <button {{on \"click\" this.plusOne}}>\n        Plus One\n      </button>\n    </div>\n  </template>\n}\n```\n\nBoth the `{{this.count}}` and the `{{this.timesTen}}` properties in the\ntemplate will update whenever the button is clicked. Any tracked properties\nthat are used in any way to calculate a value that is used in the template\nwill cause a rerender when updated - this includes through method calls and\nother means:\n\n```gjs\nimport Component from '@glimmer/component';\nimport { tracked } from '@glimmer/tracking';\n\nclass Entry {\n  @tracked name;\n  @tracked phoneNumber;\n\n  constructor(name, phoneNumber) {\n    this.name = name;\n    this.phoneNumber = phoneNumber;\n  }\n}\n\nexport default class PhoneBookComponent extends Component {\n  entries = [\n    new Entry('Pizza Palace', 5551234),\n    new Entry('1st Street Cleaners', 5554321),\n    new Entry('Plants R Us', 5552468),\n  ];\n\n  // Any usage of this property will update whenever any of the names in the\n  // entries arrays are updated\n  get names() {\n    return this.entries.map(e => e.name);\n  }\n\n  // Any usage of this property will update whenever any of the numbers in the\n  // entries arrays are updated\n  get numbers() {\n    return this.getFormattedNumbers();\n  }\n\n  getFormattedNumbers() {\n    return this.entries\n      .map(e => e.phoneNumber)\n      .map(number => {\n        let numberString = '' + number;\n\n        return numberString.slice(0, 3) + '-' + numberString.slice(3);\n      });\n  }\n}\n```\n\nIt's important to note that setting tracked properties will always trigger an\nupdate, even if the property is set to the same value as it was before.\n\n```js\nlet entry = new Entry('Pizza Palace', 5551234);\n\n// if entry was used when rendering, this would cause a rerender, even though\n// the name is being set to the same value as it was before\nentry.name = entry.name;\n```\n\n`tracked` can also be used with the classic Ember object model in a similar\nmanner to classic computed properties:\n\n```javascript\nimport EmberObject from '@ember/object';\nimport { tracked } from '@glimmer/tracking';\n\nconst Entry = EmberObject.extend({\n  name: tracked(),\n  phoneNumber: tracked()\n});\n```\n\nOften this is unnecessary, but to ensure robust auto-tracking behavior it is\nadvisable to mark tracked state appropriately wherever possible.\n\nThis form of `tracked` also accepts an optional configuration object\ncontaining either an initial `value` or an `initializer` function (but not\nboth).\n\n```javascript\nimport EmberObject from '@ember/object';\nimport { tracked } from '@glimmer/tracking';\n\nconst Entry = EmberObject.extend({\n  name: tracked({ value: 'Zoey' }),\n  favoriteSongs: tracked({\n    initializer: () => ['Raspberry Beret', 'Time After Time']\n  })\n});\n```\n\nCalling `tracked` with an initial value creates a standalone reactive\nvalue, usable outside of classes:\n\n```js\nimport { tracked } from '@glimmer/tracking';\n\nconst count = tracked(0);\n\ncount.value;                // read the value, entangling with any tracking context\ncount.value = 1;            // write the value, notifying consumers\ncount.get();                // function shorthand for reading\ncount.set(2);               // function shorthand for writing\ncount.update((n) => n + 1); // write based on the current value, without entangling\ncount.freeze();             // prevent all future writes\n```\n\nReading `value` in a template (or in a getter used by a template) will\nrerender just like a `@tracked` property:\n\n```gjs\nimport { tracked } from '@glimmer/tracking';\nimport { on } from '@ember/modifier';\n\nconst count = tracked(0);\nconst increment = () => count.value++;\n\n<template>\n  Count is: {{count.value}}\n\n  <button {{on \"click\" increment}}>add one</button>\n</template>\n```\n\nThis form accepts an options object containing an `equals` function, which\ndecides whether a written value should notify consumers (it defaults to\n`Object.is`), and a `description` used for debugging:\n\n```js\nconst count = tracked(0, { equals: (a, b) => a === b });\n\ncount.value = 0; // does not notify consumers, the value did not change\n```\n\nNote: when `tracked` is called with a single plain object whose keys are all\ndrawn from `value`, `initializer`, `equals`, and `description`, it is treated\nas the configuration object for a decorator (or classic-class field), not as a\nstandalone value wrapping that object. To create a standalone reactive value\naround such an object, pass it as an initial value and include a (possibly\nempty) options argument: `tracked({ value: 5 }, {})`.\n\nThe `@tracked` decorator accepts the same options. By default, setting a\n`@tracked` property always notifies consumers, even when setting the\nproperty to the same value; passing `equals` opts in to equality-based\nnotification instead:\n\n```js\nimport { tracked } from '@glimmer/tracking';\n\nclass Counter {\n  @tracked({ equals: (a, b) => a === b }) count = 0;\n\n  noop = () => {\n    // does not notify consumers, the value did not change\n    this.count = this.count;\n  };\n}\n```",
       "itemtype": "method",
       "name": "tracked",
       "static": 1,
@@ -7907,7 +7914,7 @@
     },
     {
       "file": "packages/@ember/-internals/glimmer/lib/glimmer-tracking-docs.ts",
-      "line": 158,
+      "line": 226,
       "description": "Gives the getter a caching behavior. The return value of the getter\nwill be cached until any of the properties it is entangled with\nare invalidated. This is useful when a getter is expensive and\nused very often.\n\nFor instance, in this `GuestList` class, we have the `sortedGuests`\ngetter that sorts the guests alphabetically:\n\n```javascript\n  import { tracked } from '@glimmer/tracking';\n\n  class GuestList {\n    @tracked guests = ['Zoey', 'Tomster'];\n\n    get sortedGuests() {\n      return this.guests.slice().sort()\n    }\n  }\n```\n\nEvery time `sortedGuests` is accessed, a new array will be created and sorted,\nbecause JavaScript getters do not cache by default. When the guest list\nis small, like the one in the example, this is not a problem. However, if\nthe guest list were to grow very large, it would mean that we would be doing\na large amount of work each time we accessed `sortedGuests`. With `@cached`,\nwe can cache the value instead:\n\n```javascript\n  import { tracked, cached } from '@glimmer/tracking';\n\n  class GuestList {\n    @tracked guests = ['Zoey', 'Tomster'];\n\n    @cached\n    get sortedGuests() {\n      return this.guests.slice().sort()\n    }\n  }\n```\n\nNow the `sortedGuests` getter will be cached based on autotracking.\nIt will only rerun and create a new sorted array when the guests tracked\nproperty is updated.\n\n\n### Tradeoffs\n\nOveruse is discouraged.\n\nIn general, you should avoid using `@cached` unless you have confirmed that\nthe getter you are decorating is computationally expensive, since `@cached`\nadds a small amount of overhead to the getter.\nWhile the individual costs are small, a systematic use of the `@cached`\ndecorator can add up to a large impact overall in your app.\nMany getters and tracked properties are only accessed once during rendering,\nand then never rerendered, so adding `@cached` when unnecessary can\nnegatively impact performance.\n\nAlso, `@cached` may rerun even if the values themselves have not changed,\nsince tracked properties will always invalidate.\nFor example updating an integer value from `5` to an other `5` will trigger\na rerun of the cached properties building from this integer.\n\nAvoiding a cache invalidation in this case is not something that can\nbe achieved on the `@cached` decorator itself, but rather when updating\nthe underlying tracked values, by applying some diff checking mechanisms:\n\n```javascript\nif (nextValue !== this.trackedProp) {\n  this.trackedProp = nextValue;\n}\n```\n\nHere equal values won't update the property, therefore not triggering\nthe subsequent cache invalidations of the `@cached` properties who were\nusing this `trackedProp`.\n\nRemember that setting tracked data should only be done during initialization,\nor as the result of a user action. Setting tracked data during render\n(such as in a getter), is not supported.",
       "itemtype": "method",
       "name": "cached",
@@ -9157,7 +9164,7 @@
     },
     {
       "file": "packages/@ember/-internals/metal/lib/tracked.ts",
-      "line": 14,
+      "line": 15,
       "decorator": "",
       "access": "private",
       "tagname": "Marks a property as tracked.\n\nBy default, a component's properties are expected to be static,\nmeaning you are not able to update them and have the template update accordingly.\nMarking a property as tracked means that when that property changes,\na rerender of the component is scheduled so the template is kept up to date.\n\nThere are two usages for the `@tracked` decorator, shown below.",
@@ -9174,6 +9181,41 @@
       "class": "@ember/owner",
       "module": "@ember/object"
     },
+    {
+      "file": "packages/@ember/-internals/metal/lib/tracked.ts",
+      "line": 77,
+      "description": "Reactivity options for the standalone `tracked(value, options)` form.\n\n- `equals` decides whether writing a value notifies consumers; it defaults to\n  `Object.is`.\n- `description` is used in development for debugging.\n\n`equals` is a function-typed property (rather than method syntax) on purpose:\nthis keeps its parameters checked strictly, so passing an `equals` typed for\nthe wrong value type is a type error instead of being silently accepted.",
+      "class": "@ember/owner",
+      "module": "@ember/object"
+    },
+    {
+      "file": "packages/@ember/-internals/metal/lib/tracked.ts",
+      "line": 93,
+      "description": "Options for `tracked` used as a decorator, or as a field on a *classic* class\n(`EmberObject.extend({ foo: tracked({ value }) })`).\n\nAll properties are optional because this single shape backs several usages:\nclassic-field defaults (`tracked({ value })` / `tracked({ initializer })`) and\noptions-only native decorators (`@tracked({ equals })`). The mutually\nexclusive combinations (e.g. both `value` and `initializer`) and the\nclassic-only restriction on `value`/`initializer` are enforced at runtime via\nassertions rather than in the type, matching the runtime `isDecoratorOptions`\ncheck that accepts any object composed of these keys.\n\n- `value` / `initializer` supply a default value and are only valid on classic\n  classes; native classes use class field initializers instead.\n- `equals` / `description` configure reactivity, mirroring\n  {@link TrackedValueOptions}.",
+      "class": "@ember/owner",
+      "module": "@ember/object"
+    },
+    {
+      "file": "packages/@ember/-internals/metal/lib/tracked.ts",
+      "line": 124,
+      "description": "`tracked` as a decorator factory: `@tracked({ equals })`, or on classic\nclasses `tracked({ value })` / `tracked({ initializer })`.",
+      "class": "@ember/owner",
+      "module": "@ember/object"
+    },
+    {
+      "file": "packages/@ember/-internals/metal/lib/tracked.ts",
+      "line": 129,
+      "description": "`tracked` as a bare decorator: `@tracked foo = 1`.",
+      "class": "@ember/owner",
+      "module": "@ember/object"
+    },
+    {
+      "file": "packages/@ember/-internals/metal/lib/tracked.ts",
+      "line": 138,
+      "description": "`tracked` as a standalone reactive value, usable outside of classes:\n`const count = tracked(0)`.",
+      "class": "@ember/owner",
+      "module": "@ember/object"
+    },
     {
       "file": "packages/@ember/-internals/owner/index.ts",
       "line": 24,
@@ -24289,8 +24331,8 @@
     },
     {
       "file": "packages/@glimmer/tracking/index.ts",
-      "line": 17,
-      "description": "Marks a property as tracked. By default, values that are rendered in Ember app\ntemplates are _static_, meaning that updates to them won't cause the\napplication to rerender. Marking a property as tracked means that when that\nproperty changes, any templates that used that property, directly or\nindirectly, will rerender. For instance, consider this component:\n\n```gjs\nimport Component from '@glimmer/component';\nimport { tracked } from '@glimmer/tracking';\nimport { action } from '@ember/object';\n\nexport default class CounterComponent extends Component {\n  @tracked count = 0;\n\n  get timesTen() {\n    return this.count * 10;\n  }\n\n  @action\n  plusOne() {\n    this.count += 1;\n  }\n  \n  <template>\n    <div>Count: {{this.count}}</div>\n    <div>Times Ten: {{this.timesTen}}</div>\n    <div>\n      <button {{on \"click\" this.plusOne}}>\n        Plus One\n      </button>\n    </div>\n  </template>\n}\n```\n\nBoth the `{{this.count}}` and the `{{this.timesTen}}` properties in the\ntemplate will update whenever the button is clicked. Any tracked properties\nthat are used in any way to calculate a value that is used in the template\nwill cause a rerender when updated - this includes through method calls and\nother means:\n\n```gjs\nimport Component from '@glimmer/component';\nimport { tracked } from '@glimmer/tracking';\n\nclass Entry {\n  @tracked name;\n  @tracked phoneNumber;\n\n  constructor(name, phoneNumber) {\n    this.name = name;\n    this.phoneNumber = phoneNumber;\n  }\n}\n\nexport default class PhoneBookComponent extends Component {\n  entries = [\n    new Entry('Pizza Palace', 5551234),\n    new Entry('1st Street Cleaners', 5554321),\n    new Entry('Plants R Us', 5552468),\n  ];\n\n  // Any usage of this property will update whenever any of the names in the\n  // entries arrays are updated\n  get names() {\n    return this.entries.map(e => e.name);\n  }\n\n  // Any usage of this property will update whenever any of the numbers in the\n  // entries arrays are updated\n  get numbers() {\n    return this.getFormattedNumbers();\n  }\n\n  getFormattedNumbers() {\n    return this.entries\n      .map(e => e.phoneNumber)\n      .map(number => {\n        let numberString = '' + number;\n\n        return numberString.slice(0, 3) + '-' + numberString.slice(3);\n      });\n  }\n}\n```\n\nIt's important to note that setting tracked properties will always trigger an\nupdate, even if the property is set to the same value as it was before.\n\n```js\nlet entry = new Entry('Pizza Palace', 5551234);\n// if entry was used when rendering, this would cause a rerender, even though\n// the name is being set to the same value as it was before\nentry.name = entry.name;\n```\n\n`tracked` can also be used with the classic Ember object model in a similar\nmanner to classic computed properties:\n\n```javascript\nimport EmberObject from '@ember/object';\nimport { tracked } from '@glimmer/tracking';\n\nconst Entry = EmberObject.extend({\n  name: tracked(),\n  phoneNumber: tracked()\n});\n```\n\nOften this is unnecessary, but to ensure robust auto-tracking behavior it is\nadvisable to mark tracked state appropriately wherever possible.\nThis form of `tracked` also accepts an optional configuration object\ncontaining either an initial `value` or an `initializer` function (but not\nboth).\n\n```javascript\nimport EmberObject from '@ember/object';\nimport { tracked } from '@glimmer/tracking';\n\nconst Entry = EmberObject.extend({\n  name: tracked({ value: 'Zoey' }),\n  favoriteSongs: tracked({\n    initializer: () => ['Raspberry Beret', 'Time After Time']\n  })\n});\n```",
+      "line": 23,
+      "description": "Marks a property as tracked. By default, values that are rendered in Ember app\ntemplates are _static_, meaning that updates to them won't cause the\napplication to rerender. Marking a property as tracked means that when that\nproperty changes, any templates that used that property, directly or\nindirectly, will rerender. For instance, consider this component:\n\n```gjs\nimport Component from '@glimmer/component';\nimport { tracked } from '@glimmer/tracking';\nimport { action } from '@ember/object';\n\nexport default class CounterComponent extends Component {\n  @tracked count = 0;\n\n  get timesTen() {\n    return this.count * 10;\n  }\n\n  @action\n  plusOne() {\n    this.count += 1;\n  }\n\n  <template>\n    <div>Count: {{this.count}}</div>\n    <div>Times Ten: {{this.timesTen}}</div>\n    <div>\n      <button {{on \"click\" this.plusOne}}>\n        Plus One\n      </button>\n    </div>\n  </template>\n}\n```\n\nBoth the `{{this.count}}` and the `{{this.timesTen}}` properties in the\ntemplate will update whenever the button is clicked. Any tracked properties\nthat are used in any way to calculate a value that is used in the template\nwill cause a rerender when updated - this includes through method calls and\nother means:\n\n```gjs\nimport Component from '@glimmer/component';\nimport { tracked } from '@glimmer/tracking';\n\nclass Entry {\n  @tracked name;\n  @tracked phoneNumber;\n\n  constructor(name, phoneNumber) {\n    this.name = name;\n    this.phoneNumber = phoneNumber;\n  }\n}\n\nexport default class PhoneBookComponent extends Component {\n  entries = [\n    new Entry('Pizza Palace', 5551234),\n    new Entry('1st Street Cleaners', 5554321),\n    new Entry('Plants R Us', 5552468),\n  ];\n\n  // Any usage of this property will update whenever any of the names in the\n  // entries arrays are updated\n  get names() {\n    return this.entries.map(e => e.name);\n  }\n\n  // Any usage of this property will update whenever any of the numbers in the\n  // entries arrays are updated\n  get numbers() {\n    return this.getFormattedNumbers();\n  }\n\n  getFormattedNumbers() {\n    return this.entries\n      .map(e => e.phoneNumber)\n      .map(number => {\n        let numberString = '' + number;\n\n        return numberString.slice(0, 3) + '-' + numberString.slice(3);\n      });\n  }\n}\n```\n\nIt's important to note that setting tracked properties will always trigger an\nupdate, even if the property is set to the same value as it was before.\n\n```js\nlet entry = new Entry('Pizza Palace', 5551234);\n// if entry was used when rendering, this would cause a rerender, even though\n// the name is being set to the same value as it was before\nentry.name = entry.name;\n```\n\n`tracked` can also be used with the classic Ember object model in a similar\nmanner to classic computed properties:\n\n```javascript\nimport EmberObject from '@ember/object';\nimport { tracked } from '@glimmer/tracking';\n\nconst Entry = EmberObject.extend({\n  name: tracked(),\n  phoneNumber: tracked()\n});\n```\n\nOften this is unnecessary, but to ensure robust auto-tracking behavior it is\nadvisable to mark tracked state appropriately wherever possible.\nThis form of `tracked` also accepts an optional configuration object\ncontaining either an initial `value` or an `initializer` function (but not\nboth).\n\n```javascript\nimport EmberObject from '@ember/object';\nimport { tracked } from '@glimmer/tracking';\n\nconst Entry = EmberObject.extend({\n  name: tracked({ value: 'Zoey' }),\n  favoriteSongs: tracked({\n    initializer: () => ['Raspberry Beret', 'Time After Time']\n  })\n});\n```\n\nCalling `tracked` with an initial value creates a standalone reactive\nvalue, usable outside of classes:\n\n```js\nimport { tracked } from '@glimmer/tracking';\n\nconst count = tracked(0);\n\ncount.value;                // read the value, entangling with any tracking context\ncount.value = 1;            // write the value, notifying consumers\ncount.get();                // function shorthand for reading\ncount.set(2);               // function shorthand for writing\ncount.update((n) => n + 1); // write based on the current value, without entangling\ncount.freeze();             // prevent all future writes\n```\n\nReading `value` in a template (or in a getter used by a template) will\nrerender just like a `@tracked` property:\n\n```gjs\nimport { tracked } from '@glimmer/tracking';\nimport { on } from '@ember/modifier';\n\nconst count = tracked(0);\nconst increment = () => count.value++;\n\n<template>\n  Count is: {{count.value}}\n\n  <button {{on \"click\" increment}}>add one</button>\n</template>\n```\n\nThis form accepts an options object containing an `equals` function, which\ndecides whether a written value should notify consumers (it defaults to\n`Object.is`), and a `description` used for debugging:\n\n```js\nconst count = tracked(0, { equals: (a, b) => a === b });\n\ncount.value = 0; // does not notify consumers, the value did not change\n```\n\nNote: when `tracked` is called with a single plain object whose keys are all\ndrawn from `value`, `initializer`, `equals`, and `description`, it is treated\nas the configuration object for a decorator (or classic-class field), not as a\nstandalone value wrapping that object. To create a standalone reactive value\naround such an object, pass it as an initial value and include a (possibly\nempty) options argument: `tracked({ value: 5 }, {})`.\n\nThe `@tracked` decorator accepts the same options. By default, setting a\n`@tracked` property always notifies consumers, even when setting the\nproperty to the same value; passing `equals` opts in to equality-based\nnotification instead:\n\n```js\nimport { tracked } from '@glimmer/tracking';\n\nclass Counter {\n  @tracked({ equals: (a, b) => a === b }) count = 0;\n\n  noop = () => {\n    // does not notify consumers, the value did not change\n    this.count = this.count;\n  };\n}\n```",
       "itemtype": "method",
       "name": "tracked",
       "static": 1,
@@ -24301,7 +24343,7 @@
     },
     {
       "file": "packages/@glimmer/tracking/index.ts",
-      "line": 151,
+      "line": 225,
       "description": "The `@cached` decorator can be used on getters in order to cache the return\nvalue of the getter. This is useful when a getter is expensive and used very\noften. For instance, in this guest list class, we have the `sortedGuests`\ngetter that sorts the guests alphabetically:\n\n```js\nimport { tracked } from '@glimmer/tracking';\n\nclass GuestList {\n  @tracked guests = ['Zoey', 'Tomster'];\n\n  get sortedGuests() {\n    return this.guests.slice().sort()\n  }\n}\n```\n\nEvery time `sortedGuests` is accessed, a new array will be created and sorted,\nbecause JavaScript getters do not cache by default. When the guest list is\nsmall, like the one in the example, this is not a problem. However, if the guest\nlist were to grow very large, it would mean that we would be doing a large\namount of work each time we accessed `sortedGetters`. With `@cached`, we can\ncache the value instead:\n\n```js\nimport { tracked, cached } from '@glimmer/tracking';\n\nclass GuestList {\n  @tracked guests = ['Zoey', 'Tomster'];\n\n  @cached\n  get sortedGuests() {\n    return this.guests.slice().sort()\n  }\n}\n```\n\nNow the `sortedGuests` getter will be cached based on _autotracking_. It will\nonly rerun and create a new sorted array when the `guests` tracked property is\nupdated.\n\nIn general, you should avoid using `@cached` unless you have confirmed that the\ngetter you are decorating is computationally expensive. `@cached` adds a small\namount of overhead to the getter, making it more expensive. While this overhead\nis small, if `@cached` is overused it can add up to a large impact overall in\nyour app. Many getters and tracked properties are only accessed once, rendered,\nand then never rerendered, so adding `@cached` when it is unnecessary can\nnegatively impact performance.",
       "itemtype": "method",
       "name": "cached",
@@ -24415,6 +24457,55 @@
       "class": "TestAdapter",
       "module": "@glimmer/tracking"
     },
+    {
+      "file": "packages/@glimmer/validator/lib/tracked-value.ts",
+      "line": 8,
+      "description": "A mutable reactive value.\n\nReading `value` consumes the underlying tag (entangling with any active\ntracking frame), and writing `value` dirties it.",
+      "class": "TestAdapter",
+      "module": "@glimmer/tracking"
+    },
+    {
+      "file": "packages/@glimmer/validator/lib/tracked-value.ts",
+      "line": 18,
+      "description": "A reactive value that can only be read.",
+      "class": "TestAdapter",
+      "module": "@glimmer/tracking"
+    },
+    {
+      "file": "packages/@glimmer/validator/lib/tracked-value.ts",
+      "line": 37,
+      "description": "The underlying value.\n\nReading entangles with the current tracking frame, and writing notifies\nconsumers (unless the configured `equals` deems the new value equal to\nthe current one).",
+      "class": "TestAdapter",
+      "module": "@glimmer/tracking"
+    },
+    {
+      "file": "packages/@glimmer/validator/lib/tracked-value.ts",
+      "line": 54,
+      "description": "Function short-hand for reading `value`.",
+      "class": "TestAdapter",
+      "module": "@glimmer/tracking"
+    },
+    {
+      "file": "packages/@glimmer/validator/lib/tracked-value.ts",
+      "line": 61,
+      "description": "Function short-hand for assigning `value`.\n\nReturns `true` if the value changed (and consumers were notified),\n`false` if the new value was equal to the current one.",
+      "class": "TestAdapter",
+      "module": "@glimmer/tracking"
+    },
+    {
+      "file": "packages/@glimmer/validator/lib/tracked-value.ts",
+      "line": 87,
+      "description": "Update the value based on the current value, without consuming it.",
+      "class": "TestAdapter",
+      "module": "@glimmer/tracking"
+    },
+    {
+      "file": "packages/@glimmer/validator/lib/tracked-value.ts",
+      "line": 94,
+      "description": "Prevents further updates, making the TrackedValue behave as a\nReadOnlyReactive.",
+      "class": "TestAdapter",
+      "module": "@glimmer/tracking"
+    },
     {
       "file": "packages/@glimmer/validator/lib/tracking.ts",
       "line": 10,
@@ -24598,7 +24689,7 @@
     },
     {
       "message": "unknown tag: decorator",
-      "line": " packages/@ember/-internals/metal/lib/tracked.ts:14"
+      "line": " packages/@ember/-internals/metal/lib/tracked.ts:15"
     },
     {
       "message": "unknown tag: internal",
@@ -25110,7 +25201,27 @@
     },
     {
       "message": "Missing item type",
-      "line": " packages/@ember/-internals/metal/lib/tracked.ts:14"
+      "line": " packages/@ember/-internals/metal/lib/tracked.ts:15"
+    },
+    {
+      "message": "Missing item type\nReactivity options for the standalone `tracked(value, options)` form.\n\n- `equals` decides whether writing a value notifies consumers; it defaults to\n  `Object.is`.\n- `description` is used in development for debugging.\n\n`equals` is a function-typed property (rather than method syntax) on purpose:\nthis keeps its parameters checked strictly, so passing an `equals` typed for\nthe wrong value type is a type error instead of being silently accepted.",
+      "line": " packages/@ember/-internals/metal/lib/tracked.ts:77"
+    },
+    {
+      "message": "Missing item type\nOptions for `tracked` used as a decorator, or as a field on a *classic* class\n(`EmberObject.extend({ foo: tracked({ value }) })`).\n\nAll properties are optional because this single shape backs several usages:\nclassic-field defaults (`tracked({ value })` / `tracked({ initializer })`) and\noptions-only native decorators (`@tracked({ equals })`). The mutually\nexclusive combinations (e.g. both `value` and `initializer`) and the\nclassic-only restriction on `value`/`initializer` are enforced at runtime via\nassertions rather than in the type, matching the runtime `isDecoratorOptions`\ncheck that accepts any object composed of these keys.\n\n- `value` / `initializer` supply a default value and are only valid on classic\n  classes; native classes use class field initializers instead.\n- `equals` / `description` configure reactivity, mirroring\n  {@link TrackedValueOptions}.",
+      "line": " packages/@ember/-internals/metal/lib/tracked.ts:93"
+    },
+    {
+      "message": "Missing item type\n`tracked` as a decorator factory: `@tracked({ equals })`, or on classic\nclasses `tracked({ value })` / `tracked({ initializer })`.",
+      "line": " packages/@ember/-internals/metal/lib/tracked.ts:124"
+    },
+    {
+      "message": "Missing item type\n`tracked` as a bare decorator: `@tracked foo = 1`.",
+      "line": " packages/@ember/-internals/metal/lib/tracked.ts:129"
+    },
+    {
+      "message": "Missing item type\n`tracked` as a standalone reactive value, usable outside of classes:\n`const count = tracked(0)`.",
+      "line": " packages/@ember/-internals/metal/lib/tracked.ts:138"
     },
     {
       "message": "Missing item type\nA type registry for the DI system, which other participants in the DI system\ncan register themselves into with declaration merging. The contract for this\ntype is that its keys are the `Type` from a `FullName`, and each value for a\n`Type` is another registry whose keys are the `Name` from a `FullName`. The\nmechanic for providing a registry is [declaration merging][handbook].\n\n[handbook]: https://www.typescriptlang.org/docs/handbook/declaration-merging.html\n\nFor example, Ember's `@ember/service` module includes this set of definitions:\n\n```ts\nexport default class Service extends EmberObject {}\n\n// For concrete singleton classes to be merged into.\ninterface Registry extends Record<string, Service> {}\n\ndeclare module '@ember/owner' {\n  service: Registry;\n}\n```\n\nDeclarations of services can then include the registry:\n\n```ts\nimport Service from '@ember/service';\n\nexport default class Session extends Service {\n  login(username: string, password: string) {\n    // ...\n  }\n}\n\ndeclare module '@ember/service' {\n  interface Registry {\n    session: Session;\n  }\n}\n```\n\nThen users of the `Owner` API will be able to do things like this with strong\ntype safety guarantees:\n\n```ts\ngetOwner(this)?.lookup('service:session').login(\"hello\", \"1234abcd\");\n```",
@@ -27540,6 +27651,34 @@
       "message": "Missing item type\nCreates a global autotracking transaction. This will prevent any backflow\nin any `track` calls within the transaction, even if they are not\nexternally consumed.\n\n`runInAutotrackingTransaction` can be called within itself, and it will add\nonto the existing transaction if one exists.\n\nTODO: Only throw an error if the `track` is consumed.",
       "line": " packages/@glimmer/validator/lib/debug.ts:104"
     },
+    {
+      "message": "Missing item type\nA mutable reactive value.\n\nReading `value` consumes the underlying tag (entangling with any active\ntracking frame), and writing `value` dirties it.",
+      "line": " packages/@glimmer/validator/lib/tracked-value.ts:8"
+    },
+    {
+      "message": "Missing item type\nA reactive value that can only be read.",
+      "line": " packages/@glimmer/validator/lib/tracked-value.ts:18"
+    },
+    {
+      "message": "Missing item type\nThe underlying value.\n\nReading entangles with the current tracking frame, and writing notifies\nconsumers (unless the configured `equals` deems the new value equal to\nthe current one).",
+      "line": " packages/@glimmer/validator/lib/tracked-value.ts:37"
+    },
+    {
+      "message": "Missing item type\nFunction short-hand for reading `value`.",
+      "line": " packages/@glimmer/validator/lib/tracked-value.ts:54"
+    },
+    {
+      "message": "Missing item type\nFunction short-hand for assigning `value`.\n\nReturns `true` if the value changed (and consumers were notified),\n`false` if the new value was equal to the current one.",
+      "line": " packages/@glimmer/validator/lib/tracked-value.ts:61"
+    },
+    {
+      "message": "Missing item type\nUpdate the value based on the current value, without consuming it.",
+      "line": " packages/@glimmer/validator/lib/tracked-value.ts:87"
+    },
+    {
+      "message": "Missing item type\nPrevents further updates, making the TrackedValue behave as a\nReadOnlyReactive.",
+      "line": " packages/@glimmer/validator/lib/tracked-value.ts:94"
+    },
     {
       "message": "Missing item type\nAn object that that tracks @tracked properties that were consumed.",
       "line": " packages/@glimmer/validator/lib/tracking.ts:10"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ember-source",
-  "version": "7.3.0-alpha.1",
+  "version": "7.3.0-alpha.3",
   "description": "A JavaScript framework for creating ambitious web applications",
   "type": "module",
   "keywords": [
@@ -69,7 +69,6 @@
     "backburner.js": "^2.8.0",
     "broccoli-file-creator": "^2.1.1",
     "chalk": "^4.0.0",
-    "ember-cli-babel": "^8.3.1",
     "ember-cli-get-component-path-option": "^1.0.0",
     "ember-cli-normalize-entity-name": "^1.0.0",
     "ember-cli-path-utils": "^1.0.0",

package/types/stable/@ember/-internals/glimmer/lib/glimmer-tracking-docs.d.ts

@@ -149,6 +149,74 @@ declare module '@ember/-internals/glimmer/lib/glimmer-tracking-docs' {
       });
       ```
 
+      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/@ember/-internals/metal/lib/tracked.d.ts

@@ -1,4 +1,5 @@
 declare module '@ember/-internals/metal/lib/tracked' {
+    import { type TrackedValue } from "@glimmer/validator/lib/tracked-value";
     import type { ExtendedMethodDecorator, DecoratorPropertyDescriptor } from "@ember/-internals/metal/lib/decorator";
     /**
       @decorator
@@ -62,14 +63,59 @@ declare module '@ember/-internals/metal/lib/tracked' {
 
       @param dependencies Optional dependents to be tracked.
     */
-    export function tracked(
-      propertyDesc: {
-          value: any;
-          initializer: () => any;
-      }
-    ): ExtendedMethodDecorator;
+    /**
+     * Reactivity options for the standalone `tracked(value, options)` form.
+     *
+     * - `equals` decides whether writing a value notifies consumers; it defaults to
+     *   `Object.is`.
+     * - `description` is used in development for debugging.
+     *
+     * `equals` is a function-typed property (rather than method syntax) on purpose:
+     * this keeps its parameters checked strictly, so passing an `equals` typed for
+     * the wrong value type is a type error instead of being silently accepted.
+     */
+    interface TrackedValueOptions<Value> {
+        equals?: (a: Value, b: Value) => boolean;
+        description?: string;
+    }
+    /**
+     * Options for `tracked` used as a decorator, or as a field on a *classic* class
+     * (`EmberObject.extend({ foo: tracked({ value }) })`).
+     *
+     * All properties are optional because this single shape backs several usages:
+     * classic-field defaults (`tracked({ value })` / `tracked({ initializer })`) and
+     * options-only native decorators (`@tracked({ equals })`). The mutually
+     * exclusive combinations (e.g. both `value` and `initializer`) and the
+     * classic-only restriction on `value`/`initializer` are enforced at runtime via
+     * assertions rather than in the type, matching the runtime `isDecoratorOptions`
+     * check that accepts any object composed of these keys.
+     *
+     * - `value` / `initializer` supply a default value and are only valid on classic
+     *   classes; native classes use class field initializers instead.
+     * - `equals` / `description` configure reactivity, mirroring
+     *   {@link TrackedValueOptions}.
+     */
+    interface TrackedDecoratorOptions {
+        value?: any;
+        initializer?: () => any;
+        equals?(a: any, b: any): boolean;
+        description?: string;
+    }
+    /**
+     * `tracked` as a decorator factory: `@tracked({ equals })`, or on classic
+     * classes `tracked({ value })` / `tracked({ initializer })`.
+     */
+    export function tracked(propertyDesc: TrackedDecoratorOptions): ExtendedMethodDecorator;
+    /**
+     * `tracked` as a bare decorator: `@tracked foo = 1`.
+     */
     export function tracked(target: object, key: string): void;
     export function tracked(target: object, key: string, desc: DecoratorPropertyDescriptor): DecoratorPropertyDescriptor;
+    /**
+     * `tracked` as a standalone reactive value, usable outside of classes:
+     * `const count = tracked(0)`.
+     */
+    export function tracked<Value>(initialValue: Value, options?: TrackedValueOptions<Value>): TrackedValue<Value>;
     export class TrackedDescriptor {
         private _get;
         private _set;
@@ -77,4 +123,5 @@ declare module '@ember/-internals/metal/lib/tracked' {
         get(obj: object): unknown;
         set(obj: object, _key: string, value: unknown): void;
     }
+    export {};
 }