Skip to content

Commit 2fe9ba3

Browse files
kategenglerkategengler
authored
Merge pull request #20961 from NullVoxPopuli/nvp/reactive-docs
2 parents 593d7fc + 7fdcf0f commit 2fe9ba3

File tree

2 files changed

+270
-8
lines changed

2 files changed

+270
-8
lines changed

‎packages/@ember/reactive/index.ts

Lines changed: 263 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,263 @@
1-
export {
2-
trackedArray,
3-
trackedObject,
4-
trackedWeakSet,
5-
trackedSet,
6-
trackedMap,
7-
trackedWeakMap,
8-
} from '@glimmer/validator';
1+
/**
2+
* The `@ember/reactive` package contains common reactive utilities
3+
* for tracking values and creating reactive data structures.
4+
*
5+
* @module @ember/reactive
6+
* @public
7+
*/
8+
9+
/**
10+
* A utility for creating tracked arrays, copying the original data so that
11+
* mutations to the tracked data don't mutate the original untracked data.
12+
*
13+
* `trackedArray` can be used in templates and in JavaScript via import.
14+
* All property accesses entangle with that property, all property sets dirty
15+
* that property, and changes to the collection only render what changed
16+
* without causing unneeded renders.
17+
*
18+
* See [MDN for more information](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)
19+
*
20+
* @example
21+
* ```javascript
22+
* import { trackedArray } from '@ember/reactive';
23+
* import { on } from '@ember/modifier';
24+
* import { fn } from '@ember/helper';
25+
*
26+
* const nonTrackedArray = [1, 2, 3];
27+
* const addTo = (arr) => arr.push(Math.random());
28+
*
29+
* <template>
30+
* {{#let (trackedArray nonTrackedArray) as |arr|}}
31+
* {{#each arr as |datum|}}
32+
* {{datum}}
33+
* {{/each}}
34+
*
35+
* <button {{on 'click' (fn addTo arr)}}>Add Item</button>
36+
* {{/let}}
37+
* </template>
38+
* ```
39+
*
40+
* @method trackedArray
41+
* @static
42+
* @for @ember/reactive
43+
* @param {Array} [data] The initial array data to track
44+
* @param {Object} [options] Optional configuration
45+
* @param {Function} [options.equals] Custom equality function (defaults to Object.is)
46+
* @param {String} [options.description] Description for debugging purposes
47+
* @returns {Array} A tracked array that updates reactively
48+
* @public
49+
*/
50+
export { trackedArray } from '@glimmer/validator';
51+
52+
/**
53+
* A utility for creating tracked objects, copying the original data so that
54+
* mutations to the tracked data don't mutate the original untracked data.
55+
*
56+
* `trackedObject` can be used in templates and in JavaScript via import.
57+
* All property accesses entangle with that property, all property sets dirty
58+
* that property, and changes to the collection only render what changed
59+
* without causing unneeded renders.
60+
*
61+
* See [MDN for more information](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
62+
*
63+
* @example
64+
* ```gjs
65+
* import { trackedObject } from '@ember/reactive';
66+
* import { on } from '@ember/modifier';
67+
* import { fn } from '@ember/helper';
68+
*
69+
* const nonTrackedObject = { a: 1 };
70+
* const addTo = (obj) => obj[Math.random()] = Math.random();
71+
*
72+
* <template>
73+
* {{#let (trackedObject nonTrackedObject) as |obj|}}
74+
* {{#each-in obj as |key value|}}
75+
* {{key}} => {{value}}<br>
76+
* {{/each-in}}
77+
*
78+
* <button {{on 'click' (fn addTo obj)}}>Add Pair</button>
79+
* {{/let}}
80+
* </template>
81+
* ```
82+
*
83+
* @method trackedObject
84+
* @static
85+
* @for @ember/reactive
86+
* @param {Object} [data] The initial object data to track
87+
* @param {Object} [options] Optional configuration
88+
* @param {Function} [options.equals] Custom equality function (defaults to Object.is)
89+
* @param {String} [options.description] Description for debugging purposes
90+
* @returns {Object} A tracked object that updates reactively
91+
* @public
92+
*/
93+
export { trackedObject } from '@glimmer/validator';
94+
95+
/**
96+
* A utility for creating tracked sets, copying the original data so that
97+
* mutations to the tracked data don't mutate the original untracked data.
98+
*
99+
* `trackedSet` can be used in templates and in JavaScript via import.
100+
* All property accesses entangle with that property, all property sets dirty
101+
* that property, and changes to the collection only render what changed
102+
* without causing unneeded renders.
103+
*
104+
* See [MDN for more information](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set)
105+
*
106+
* @example
107+
* ```gjs
108+
* import { trackedSet } from '@ember/reactive';
109+
* import { on } from '@ember/modifier';
110+
* import { fn } from '@ember/helper';
111+
*
112+
* const nonTrackedSet = new Set();
113+
* nonTrackedSet.add(1);
114+
* const addTo = (set) => set.add(Math.random());
115+
*
116+
* <template>
117+
* {{#let (trackedSet nonTrackedSet) as |set|}}
118+
* {{#each set as |value|}}
119+
* {{value}}<br>
120+
* {{/each}}
121+
*
122+
* <button {{on 'click' (fn addTo set)}}>Add</button>
123+
* {{/let}}
124+
* </template>
125+
* ```
126+
*
127+
* @method trackedSet
128+
* @static
129+
* @for @ember/reactive
130+
* @param {Set} [data] The initial Set data to track
131+
* @param {Object} [options] Optional configuration
132+
* @param {Function} [options.equals] Custom equality function (defaults to Object.is)
133+
* @param {String} [options.description] Description for debugging purposes
134+
* @returns {Set} A tracked Set that updates reactively
135+
* @public
136+
*/
137+
export { trackedSet } from '@glimmer/validator';
138+
139+
/**
140+
* A utility for creating tracked weak sets, copying the original data so that
141+
* mutations to the tracked data don't mutate the original untracked data.
142+
*
143+
* `trackedWeakSet` can be used in templates and in JavaScript via import.
144+
* All property accesses entangle with that property, all property sets dirty
145+
* that property, and changes to the collection only render what changed
146+
* without causing unneeded renders.
147+
*
148+
* WeakSets hold weak references to their values, allowing garbage collection
149+
* when objects are no longer referenced elsewhere.
150+
*
151+
* See [MDN for more information](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet)
152+
*
153+
* @example
154+
* ```gjs
155+
* import { trackedWeakSet } from '@ember/reactive';
156+
* import { on } from '@ember/modifier';
157+
* import { fn } from '@ember/helper';
158+
*
159+
* const nonTrackedWeakSet = new WeakSet();
160+
*
161+
* <template>
162+
* {{#let (trackedWeakSet nonTrackedWeakSet) as |weakSet|}}
163+
* {{log weakSet}}
164+
* {{/let}}
165+
* </template>
166+
* ```
167+
*
168+
* @method trackedWeakSet
169+
* @static
170+
* @for @ember/reactive
171+
* @param {WeakSet} [data] The initial WeakSet data to track
172+
* @param {Object} [options] Optional configuration
173+
* @param {Function} [options.equals] Custom equality function (defaults to Object.is)
174+
* @param {String} [options.description] Description for debugging purposes
175+
* @returns {WeakSet} A tracked WeakSet that updates reactively
176+
* @public
177+
*/
178+
export { trackedWeakSet } from '@glimmer/validator';
179+
180+
/**
181+
* A utility for creating tracked maps, copying the original data so that
182+
* mutations to the tracked data don't mutate the original untracked data.
183+
*
184+
* `trackedMap` can be used in templates and in JavaScript via import.
185+
* All property accesses entangle with that property, all property sets dirty
186+
* that property, and changes to the collection only render what changed
187+
* without causing unneeded renders.
188+
*
189+
* See [MDN for more information](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)
190+
*
191+
* @example
192+
* ```gjs
193+
* import { trackedMap } from '@ember/reactive';
194+
* import { on } from '@ember/modifier';
195+
* import { fn } from '@ember/helper';
196+
*
197+
* const nonTrackedMap = new Map();
198+
* nonTrackedMap.set('a', 1);
199+
* const addTo = (map) => map.set(Math.random(), Math.random());
200+
*
201+
* <template>
202+
* {{#let (trackedMap nonTrackedMap) as |map|}}
203+
* {{#each-in map as |key value|}}
204+
* {{key}} => {{value}}<br>
205+
* {{/each-in}}
206+
*
207+
* <button {{on 'click' (fn addTo map)}}>Add Pair</button>
208+
* {{/let}}
209+
* </template>
210+
* ```
211+
*
212+
* @method trackedMap
213+
* @static
214+
* @for @ember/reactive
215+
* @param {Map} [data] The initial Map data to track
216+
* @param {Object} [options] Optional configuration
217+
* @param {Function} [options.equals] Custom equality function (defaults to Object.is)
218+
* @param {String} [options.description] Description for debugging purposes
219+
* @returns {Map} A tracked Map that updates reactively
220+
* @public
221+
*/
222+
export { trackedMap } from '@glimmer/validator';
223+
224+
/**
225+
* A utility for creating tracked weak maps, copying the original data so that
226+
* mutations to the tracked data don't mutate the original untracked data.
227+
*
228+
* `trackedWeakMap` can be used in templates and in JavaScript via import.
229+
* All property accesses entangle with that property, all property sets dirty
230+
* that property, and changes to the collection only render what changed
231+
* without causing unneeded renders.
232+
*
233+
* WeakMaps hold weak references to their keys, allowing garbage collection
234+
* when key objects are no longer referenced elsewhere.
235+
*
236+
* See [MDN for more information](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap)
237+
*
238+
* @example
239+
* ```gjs
240+
* import { trackedWeakMap } from '@ember/reactive';
241+
* import { on } from '@ember/modifier';
242+
* import { fn } from '@ember/helper';
243+
*
244+
* const nonTrackedWeakMap = new WeakMap();
245+
*
246+
* <template>
247+
* {{#let (trackedWeakMap nonTrackedWeakMap) as |weakMap|}}
248+
* {{log weakMap}}
249+
* {{/let}}
250+
* </template>
251+
* ```
252+
*
253+
* @method trackedWeakMap
254+
* @static
255+
* @for @ember/reactive
256+
* @param {WeakMap} [data] The initial WeakMap data to track
257+
* @param {Object} [options] Optional configuration
258+
* @param {Function} [options.equals] Custom equality function (defaults to Object.is)
259+
* @param {String} [options.description] Description for debugging purposes
260+
* @returns {WeakMap} A tracked WeakMap that updates reactively
261+
* @public
262+
*/
263+
export { trackedWeakMap } from '@glimmer/validator';

‎tests/docs/expected.js

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -506,6 +506,12 @@ module.exports = {
506506
'toString',
507507
'toHTML',
508508
'tracked',
509+
"trackedArray",
510+
"trackedMap",
511+
"trackedObject",
512+
"trackedSet",
513+
"trackedWeakMap",
514+
"trackedWeakSet",
509515
'transitionTo',
510516
'transitionToRoute',
511517
'trigger',
@@ -627,6 +633,7 @@ module.exports = {
627633
'@ember/object/promise-proxy-mixin',
628634
'@ember/object/proxy',
629635
'@ember/owner',
636+
'@ember/reactive',
630637
'@ember/renderer',
631638
'@ember/routing',
632639
'@ember/routing/hash-location',

0 commit comments

Comments
 (0)