ember-primitives 0.58.0 → 0.59.0

package/declarations/components/incremental-each.d.ts

@@ -20,7 +20,7 @@ export interface Signature<T = unknown> {
          */
         items: readonly T[];
         /**
-         * How many items to add per idle callback.
+         * How many items to add per animation frame.
          *
          * Larger batches add more items per chunk; smaller batches yield to
          * the browser more often.
@@ -38,6 +38,58 @@ export interface Signature<T = unknown> {
          * ```
          */
         batchSize?: number;
+        /**
+         * Controls how the initial batch is committed.
+         *
+         * - `"sync"` (default): the first `@batchSize` items render in the
+         *   same render pass as mount / `@items` change. The user sees
+         *   content on the very first paint, and the rest of the list
+         *   fills in one batch per animation frame. This is the right
+         *   default for most lists — even a perceived "empty for one
+         *   frame" is worse than rendering a few extra items synchronously.
+         * - `"lazy"`: even the first batch waits for an animation frame, so
+         *   the initial paint is empty and content arrives one batch per
+         *   frame. Use this when the first batch itself would be expensive
+         *   enough to block the first paint, and you'd rather show an
+         *   empty container than delay it.
+         *
+         * Default: `"sync"`.
+         *
+         * ```gjs
+         * import { IncrementalEach } from 'ember-primitives';
+         *
+         * <template>
+         *   <IncrementalEach @items={{this.rows}} @initial="lazy" as |row|>
+         *     <my-row @row={{row}} />
+         *   </IncrementalEach>
+         * </template>
+         * ```
+         */
+        initial?: "sync" | "lazy";
+        /**
+         * Called once with no arguments when every item in `@items` has
+         * been committed to the DOM. Fires after the final batch lands;
+         * does not fire on intermediate batches.
+         *
+         * Fires again on a fresh swap (new `@items` identity) once that
+         * new collection finishes rendering. An empty `@items` array
+         * does not fire the callback.
+         *
+         * Useful for marking the list as ready for screenshot tests,
+         * dismissing a loading indicator, or measuring how long the
+         * whole render took.
+         *
+         * ```gjs
+         * import { IncrementalEach } from 'ember-primitives';
+         *
+         * <template>
+         *   <IncrementalEach @items={{this.rows}} @onDone={{this.handleDone}} as |row|>
+         *     <my-row @row={{row}} />
+         *   </IncrementalEach>
+         * </template>
+         * ```
+         */
+        onDone?: () => void;
     };
     Blocks: {
         /**
@@ -58,18 +110,28 @@ export interface Signature<T = unknown> {
     };
 }
 /**
- * A drop-in replacement for `{{#each}}` that renders a large collection a
- * batch at a time during the browser's idle periods, instead of all at once.
+ * A drop-in replacement for `{{#each}}` that renders a large collection
+ * a batch at a time on each animation frame, instead of all at once.
  *
  * Every item ends up in the DOM, so browser find (Ctrl+F / Cmd+F), anchor
  * links, screen readers, print, and SEO all work against the full list.
  * Yielding the main thread between batches keeps the page responsive while
  * the rest of the list is filling in.
  *
+ * By default the first batch lands synchronously, so the user sees content
+ * on the very first paint. Pass `@initial="lazy"` to defer the first batch
+ * to an animation frame as well.
+ *
  * Intended for non-scrollable containers, or anywhere a virtual/windowed
  * list does not apply (variable item heights, lists that grow the page,
  * surfaces that need every row indexable).
  *
+ * Do not nest one `<IncrementalEach>` inside another. Each level adds an
+ * animation-frame delay before its content paints; nesting compounds those
+ * delays, so inner rows appear to flicker in with missing sub-content.
+ * If you have nested loops, only the outermost one should be
+ * `<IncrementalEach>`; leave deeper loops as plain `{{#each}}`.
+ *
  * @example
  * ```gjs
  * import { IncrementalEach } from 'ember-primitives';
@@ -86,6 +148,15 @@ export interface Signature<T = unknown> {
 export declare class IncrementalEach<T = unknown> extends Component<Signature<T>> {
     #private;
     constructor(owner: Owner, args: Signature<T>["Args"]);
-    get visible(): readonly T[];
+    get i(): number;
+    get bucketed(): {
+        isReady: () => boolean;
+        items: {
+            value: T;
+            index: number;
+        }[];
+    }[];
+    tick: () => void;
+    checkDone: () => void;
 }
 //# sourceMappingURL=incremental-each.d.ts.map

package/declarations/components/incremental-each.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"incremental-each.d.ts","sourceRoot":"","sources":["../../src/components/incremental-each.gts"],"names":[],"mappings":"AA6MA,OAAO,SAAS,MAAM,oBAAoB,CAAC;AAO3C,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAMtC,MAAM,WAAW,SAAS,CAAC,CAAC,GAAG,OAAO;IACpC,IAAI,EAAE;QACJ;;;;;;;;;;;;;;;WAeG;QACH,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;QAEpB;;;;;;;;;;;;;;;;;WAiBG;QACH,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,MAAM,EAAE;QACN;;;;;;;;;;;;;WAaG;QACH,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;KACnC,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,eAAe,CAAC,CAAC,GAAG,OAAO,CAAE,SAAQ,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;;gBAe3D,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IA0BpD,IAAI,OAAO,IAAI,SAAS,CAAC,EAAE,CAc1B;CAyDF"}
+{"version":3,"file":"incremental-each.d.ts","sourceRoot":"","sources":["../../src/components/incremental-each.gts"],"names":[],"mappings":"AAoSA,OAAO,SAAS,MAAM,oBAAoB,CAAC;AAQ3C,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAiBtC,MAAM,WAAW,SAAS,CAAC,CAAC,GAAG,OAAO;IACpC,IAAI,EAAE;QACJ;;;;;;;;;;;;;;;WAeG;QACH,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;QAEpB;;;;;;;;;;;;;;;;;WAiBG;QACH,SAAS,CAAC,EAAE,MAAM,CAAC;QAEnB;;;;;;;;;;;;;;;;;;;;;;;;;;WA0BG;QACH,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QAE1B;;;;;;;;;;;;;;;;;;;;;;WAsBG;QACH,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;KACrB,CAAC;IACF,MAAM,EAAE;QACN;;;;;;;;;;;;;WAaG;QACH,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;KACnC,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBAAa,eAAe,CAAC,CAAC,GAAG,OAAO,CAAE,SAAQ,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;;gBAM3D,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAsCpD,IAAI,CAAC,WAEJ;IAED,IACI,QAAQ;;;;;;QAWX;IA2BD,IAAI,aAIF;IAEF,SAAS,aAYP;CA4BH"}

package/dist/components/incremental-each.js

@@ -1,26 +1,46 @@
 import Component from '@glimmer/component';
+import { cached } from '@glimmer/tracking';
 import { assert } from '@ember/debug';
 import { registerDestructor, isDestroyed, isDestroying } from '@ember/destroyable';
 import { buildWaiter } from '@ember/test-waiters';
 import { cell } from 'ember-resources';
 import { precompileTemplate } from '@ember/template-compilation';
 import { setComponentTemplate } from '@ember/component';
+import { n } from 'decorator-transforms/runtime';
 
 const DEFAULT_BATCH_SIZE = 50;
+const DEFAULT_INITIAL = "sync";
 const waiter = buildWaiter("ember-primitives:incremental-each");
+function chunk(arr, size) {
+  const out = [];
+  for (let i = 0; i < arr.length; i += size) {
+    out.push(arr.slice(i, i + size));
+  }
+  return out;
+}
 /**
- * A drop-in replacement for `{{#each}}` that renders a large collection a
- * batch at a time during the browser's idle periods, instead of all at once.
+ * A drop-in replacement for `{{#each}}` that renders a large collection
+ * a batch at a time on each animation frame, instead of all at once.
  *
  * Every item ends up in the DOM, so browser find (Ctrl+F / Cmd+F), anchor
  * links, screen readers, print, and SEO all work against the full list.
  * Yielding the main thread between batches keeps the page responsive while
  * the rest of the list is filling in.
  *
+ * By default the first batch lands synchronously, so the user sees content
+ * on the very first paint. Pass `@initial="lazy"` to defer the first batch
+ * to an animation frame as well.
+ *
  * Intended for non-scrollable containers, or anywhere a virtual/windowed
  * list does not apply (variable item heights, lists that grow the page,
  * surfaces that need every row indexable).
  *
+ * Do not nest one `<IncrementalEach>` inside another. Each level adds an
+ * animation-frame delay before its content paints; nesting compounds those
+ * delays, so inner rows appear to flicker in with missing sub-content.
+ * If you have nested loops, only the outermost one should be
+ * `<IncrementalEach>`; leave deeper loops as plain `{{#each}}`.
+ *
  * @example
  * ```gjs
  * import { IncrementalEach } from 'ember-primitives';
@@ -35,82 +55,94 @@ const waiter = buildWaiter("ember-primitives:incremental-each");
  * ```
  */
 class IncrementalEach extends Component {
-  // How many items have been committed to the DOM so far. Bumped one
-  // batch at a time by the idle callback. Wrapped in a `cell` because
-  // `@tracked` doesn't compose with `#`-private fields under this
-  // codebase's decorator transform.
   #count = cell(0);
-  // Plain field so identity checks don't add a render-time dependency
-  // on top of `args.items`.
   #itemsRef = null;
-  #idleHandle = null;
   #waiterToken = null;
+  #doneFor = null;
   constructor(owner, args) {
     super(owner, args);
-    registerDestructor(this, () => this.#cancel());
+    registerDestructor(this, () => this.#endWaiter());
   }
-  get #batchSize() {
-    const requested = this.args.batchSize ?? DEFAULT_BATCH_SIZE;
-    assert(`<IncrementalEach> @batchSize must be a positive number, got ${requested}`, requested > 0);
-    return requested;
-  }
-  // The items that should currently be rendered. `@cached` keeps the
-  // returned slice stable across renders that don't change `#count` or
-  // `args.items`, so Glimmer's `{{#each}}` doesn't see a fresh array on
-  // every render and we only slice once per batch landing. This is
-  // also where scheduling is driven from: `@items` identity changes
-  // reset `#count` to zero, and missing items queue the next idle
-  // callback. Autotrack stays consistent because the only synchronous
-  // write here (`#count = 0`) happens before `#count` is read.
+  // Reset progress and (re)open the test-waiter when `@items` identity
+  // changes, so a swap restarts at the first batch, `@onDone` can fire
+  // again for the new collection, and `await settled()` knows to wait
+  // until `checkDone` closes the waiter. Mutating from a getter is safe
+  // here because the writes happen before any consumer reads them in
+  // the same render pass.
   /* eslint-disable ember/no-side-effects */
-  get visible() {
-    const items = this.args.items ?? [];
+  get #items() {
+    const items = this.args.items;
+    assert(`@items must be an array`, items);
     if (items !== this.#itemsRef) {
       this.#itemsRef = items;
-      this.#cancel();
       this.#count.current = 0;
+      this.#endWaiter();
+      if (items.length > 0) {
+        this.#waiterToken = waiter.beginAsync();
+      }
     }
-    if (this.#count.current < items.length && this.#idleHandle === null) {
-      this.#scheduleNextBatch();
-    }
-    return items.slice(0, this.#count.current);
+    return items;
   }
-  /* eslint-enable ember/no-side-effects */
-  #scheduleNextBatch() {
-    // Defensive: if a batch is already pending, drop it before
-    // queueing a new one. The `visible` getter already guards on
-    // `#idleHandle === null`, but a future caller might not.
-    this.#cancel();
-    this.#waiterToken = waiter.beginAsync();
-    // The `timeout` cap ensures forward progress even when the host
-    // is CPU-bound and the browser never reports a free idle slot.
-    // In normal use this is a no-op because real idle time arrives
-    // far sooner.
-    this.#idleHandle = requestIdleCallback(() => {
-      this.#idleHandle = null;
-      if (isDestroyed(this) || isDestroying(this)) return;
-      const items = this.args.items ?? [];
-      this.#count.current = Math.min(this.#count.current + this.#batchSize, items.length);
-      this.#endWaiter();
-    }, {
-      timeout: 100
+  /* eslint-enable ember/no-side-effects */ // `"sync"` keeps bucket 0 visible at count=0 (`i = 0 >= 0`); `"lazy"`
+  // starts one step behind so even bucket 0 needs a tick.
+  get #start() {
+    return this.#initial === "sync" ? 0 : -1;
+  }
+  get i() {
+    return this.#start + this.#count.current;
+  }
+  get bucketed() {
+    const size = this.#batchSize;
+    return chunk(this.#items, size).map((items, b) => {
+      const start = b * size;
+      return {
+        isReady: () => this.i >= b,
+        items: items.map((value, j) => ({
+          value,
+          index: start + j
+        }))
+      };
     });
   }
-  #cancel() {
-    if (this.#idleHandle !== null) {
-      cancelIdleCallback(this.#idleHandle);
-      this.#idleHandle = null;
-    }
-    this.#endWaiter();
+  static {
+    n(this.prototype, "bucketed", [cached]);
   }
-  #endWaiter() {
-    if (this.#waiterToken !== null) {
-      waiter.endAsync(this.#waiterToken);
-      this.#waiterToken = null;
+  get #batchSize() {
+    const requested = this.args.batchSize ?? DEFAULT_BATCH_SIZE;
+    assert(`<IncrementalEach> @batchSize must be a positive number, got ${requested}`, requested > 0);
+    return requested;
+  }
+  get #initial() {
+    const requested = this.args.initial ?? DEFAULT_INITIAL;
+    assert(`<IncrementalEach> @initial must be "sync" or "lazy", got ${requested}`, requested === "sync" || requested === "lazy");
+    return requested;
+  }
+  // `#items` is read before `#count` so the count-reset inside `#items`
+  // (on `@items` swap) lands before this read of count this render —
+  // otherwise tracked-value backtracking asserts.
+  tick = () => {
+    if (this.#items.length > this.#count.current) {
+      requestIdleCallback(() => this.#count.current++, {
+        timeout: 10
+      });
     }
+  };
+  checkDone = () => {
+    const bucketed = this.bucketed;
+    if (this.#doneFor === bucketed) return;
+    if (this.i < bucketed.length - 1) return;
+    this.#doneFor = bucketed;
+    queueMicrotask(() => {
+      if (isDestroyed(this) || isDestroying(this)) return;
+      this.args.onDone?.();
+      this.#endWaiter();
+    });
+  };
+  #endWaiter() {
+    if (this.#waiterToken) waiter.endAsync(this.#waiterToken);
   }
   static {
-    setComponentTemplate(precompileTemplate("{{#each this.visible as |item index|}}\n  {{yield item index}}\n{{/each}}", {
+    setComponentTemplate(precompileTemplate("{{(this.tick)}}{{#each this.bucketed as |bucket|}}{{#if (bucket.isReady)}}{{#each bucket.items as |entry|}}{{yield entry.value entry.index}}{{/each}}{{(this.checkDone)}}{{/if}}{{/each}}", {
       strictMode: true
     }), this);
   }

package/dist/components/incremental-each.js.map

@@ -1 +1 @@
-{"version":3,"file":"incremental-each.js","sources":["../../src/components/incremental-each.gts"],"sourcesContent":["import Component from \"@glimmer/component\";\nimport { assert } from \"@ember/debug\";\nimport { isDestroyed, isDestroying, registerDestructor } from \"@ember/destroyable\";\nimport { buildWaiter } from \"@ember/test-waiters\";\n\nimport { cell } from \"ember-resources\";\n\nimport type Owner from \"@ember/owner\";\n\nconst DEFAULT_BATCH_SIZE = 50;\n\nconst waiter = buildWaiter(\"ember-primitives:incremental-each\");\n\nexport interface Signature<T = unknown> {\n  Args: {\n    /**\n     * The collection of items to render.\n     *\n     * Replacing the array (new identity) restarts rendering from the\n     * first batch.\n     *\n     * ```gjs\n     * import { IncrementalEach } from 'ember-primitives';\n     *\n     * <template>\n     *   <IncrementalEach @items={{this.rows}} as |row|>\n     *     <my-row @row={{row}} />\n     *   </IncrementalEach>\n     * </template>\n     * ```\n     */\n    items: readonly T[];\n\n    /**\n     * How many items to add per idle callback.\n     *\n     * Larger batches add more items per chunk; smaller batches yield to\n     * the browser more often.\n     *\n     * Default: 50. Must be positive; `0` or less asserts in development.\n     *\n     * ```gjs\n     * import { IncrementalEach } from 'ember-primitives';\n     *\n     * <template>\n     *   <IncrementalEach @items={{this.rows}} @batchSize={{100}} as |row|>\n     *     <my-row @row={{row}} />\n     *   </IncrementalEach>\n     * </template>\n     * ```\n     */\n    batchSize?: number;\n  };\n  Blocks: {\n    /**\n     * Yielded for each rendered item, with the index in the original\n     * `@items` array.\n     *\n     * ```gjs\n     * import { IncrementalEach } from 'ember-primitives';\n     *\n     * <template>\n     *   <IncrementalEach @items={{this.rows}} as |row index|>\n     *     {{index}}: {{row.label}}\n     *   </IncrementalEach>\n     * </template>\n     * ```\n     */\n    default: [item: T, index: number];\n  };\n}\n\n/**\n * A drop-in replacement for `{{#each}}` that renders a large collection a\n * batch at a time during the browser's idle periods, instead of all at once.\n *\n * Every item ends up in the DOM, so browser find (Ctrl+F / Cmd+F), anchor\n * links, screen readers, print, and SEO all work against the full list.\n * Yielding the main thread between batches keeps the page responsive while\n * the rest of the list is filling in.\n *\n * Intended for non-scrollable containers, or anywhere a virtual/windowed\n * list does not apply (variable item heights, lists that grow the page,\n * surfaces that need every row indexable).\n *\n * @example\n * ```gjs\n * import { IncrementalEach } from 'ember-primitives';\n *\n * <template>\n *   <ul>\n *     <IncrementalEach @items={{this.rows}} @batchSize={{100}} as |row index|>\n *       <li>{{index}}: {{row.label}}</li>\n *     </IncrementalEach>\n *   </ul>\n * </template>\n * ```\n */\nexport class IncrementalEach<T = unknown> extends Component<Signature<T>> {\n  // How many items have been committed to the DOM so far. Bumped one\n  // batch at a time by the idle callback. Wrapped in a `cell` because\n  // `@tracked` doesn't compose with `#`-private fields under this\n  // codebase's decorator transform.\n  #count = cell(0);\n\n  // Plain field so identity checks don't add a render-time dependency\n  // on top of `args.items`.\n  #itemsRef: readonly T[] | null = null;\n\n  #idleHandle: number | null = null;\n\n  #waiterToken: unknown = null;\n\n  constructor(owner: Owner, args: Signature<T>[\"Args\"]) {\n    super(owner, args);\n\n    registerDestructor(this, () => this.#cancel());\n  }\n\n  get #batchSize(): number {\n    const requested = this.args.batchSize ?? DEFAULT_BATCH_SIZE;\n\n    assert(\n      `<IncrementalEach> @batchSize must be a positive number, got ${requested}`,\n      requested > 0,\n    );\n\n    return requested;\n  }\n\n  // The items that should currently be rendered. `@cached` keeps the\n  // returned slice stable across renders that don't change `#count` or\n  // `args.items`, so Glimmer's `{{#each}}` doesn't see a fresh array on\n  // every render and we only slice once per batch landing. This is\n  // also where scheduling is driven from: `@items` identity changes\n  // reset `#count` to zero, and missing items queue the next idle\n  // callback. Autotrack stays consistent because the only synchronous\n  // write here (`#count = 0`) happens before `#count` is read.\n  /* eslint-disable ember/no-side-effects */\n  get visible(): readonly T[] {\n    const items = this.args.items ?? [];\n\n    if (items !== this.#itemsRef) {\n      this.#itemsRef = items;\n      this.#cancel();\n      this.#count.current = 0;\n    }\n\n    if (this.#count.current < items.length && this.#idleHandle === null) {\n      this.#scheduleNextBatch();\n    }\n\n    return items.slice(0, this.#count.current);\n  }\n  /* eslint-enable ember/no-side-effects */\n\n  #scheduleNextBatch() {\n    // Defensive: if a batch is already pending, drop it before\n    // queueing a new one. The `visible` getter already guards on\n    // `#idleHandle === null`, but a future caller might not.\n    this.#cancel();\n\n    this.#waiterToken = waiter.beginAsync();\n\n    // The `timeout` cap ensures forward progress even when the host\n    // is CPU-bound and the browser never reports a free idle slot.\n    // In normal use this is a no-op because real idle time arrives\n    // far sooner.\n    this.#idleHandle = requestIdleCallback(\n      () => {\n        this.#idleHandle = null;\n\n        if (isDestroyed(this) || isDestroying(this)) return;\n\n        const items = this.args.items ?? [];\n\n        this.#count.current = Math.min(this.#count.current + this.#batchSize, items.length);\n        this.#endWaiter();\n      },\n      { timeout: 100 },\n    );\n  }\n\n  #cancel() {\n    if (this.#idleHandle !== null) {\n      cancelIdleCallback(this.#idleHandle);\n      this.#idleHandle = null;\n    }\n\n    this.#endWaiter();\n  }\n\n  #endWaiter() {\n    if (this.#waiterToken !== null) {\n      waiter.endAsync(this.#waiterToken);\n      this.#waiterToken = null;\n    }\n  }\n\n  <template>\n    {{#each this.visible as |item index|}}\n      {{yield item index}}\n    {{/each}}\n  </template>\n}\n"],"names":["DEFAULT_BATCH_SIZE","waiter","buildWaiter","IncrementalEach","Component","cell","constructor","owner","args","registerDestructor","#batchSize","requested","batchSize","assert","visible","items","current","length","slice","#scheduleNextBatch","beginAsync","requestIdleCallback","isDestroyed","isDestroying","Math","min","timeout","#cancel","cancelIdleCallback","#endWaiter","endAsync","setComponentTemplate","precompileTemplate","strictMode"],"mappings":"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"}
+{"version":3,"file":"incremental-each.js","sources":["../../src/components/incremental-each.gts"],"sourcesContent":["import Component from \"@glimmer/component\";\nimport { cached } from \"@glimmer/tracking\";\nimport { assert } from \"@ember/debug\";\nimport { isDestroyed, isDestroying, registerDestructor } from \"@ember/destroyable\";\nimport { buildWaiter } from \"@ember/test-waiters\";\n\nimport { cell } from \"ember-resources\";\n\nimport type Owner from \"@ember/owner\";\n\nconst DEFAULT_BATCH_SIZE = 50;\nconst DEFAULT_INITIAL = \"sync\";\n\nconst waiter = buildWaiter(\"ember-primitives:incremental-each\");\n\nfunction chunk<T>(arr: readonly T[], size: number): T[][] {\n  const out: T[][] = [];\n\n  for (let i = 0; i < arr.length; i += size) {\n    out.push(arr.slice(i, i + size));\n  }\n\n  return out;\n}\n\nexport interface Signature<T = unknown> {\n  Args: {\n    /**\n     * The collection of items to render.\n     *\n     * Replacing the array (new identity) restarts rendering from the\n     * first batch.\n     *\n     * ```gjs\n     * import { IncrementalEach } from 'ember-primitives';\n     *\n     * <template>\n     *   <IncrementalEach @items={{this.rows}} as |row|>\n     *     <my-row @row={{row}} />\n     *   </IncrementalEach>\n     * </template>\n     * ```\n     */\n    items: readonly T[];\n\n    /**\n     * How many items to add per animation frame.\n     *\n     * Larger batches add more items per chunk; smaller batches yield to\n     * the browser more often.\n     *\n     * Default: 50. Must be positive; `0` or less asserts in development.\n     *\n     * ```gjs\n     * import { IncrementalEach } from 'ember-primitives';\n     *\n     * <template>\n     *   <IncrementalEach @items={{this.rows}} @batchSize={{100}} as |row|>\n     *     <my-row @row={{row}} />\n     *   </IncrementalEach>\n     * </template>\n     * ```\n     */\n    batchSize?: number;\n\n    /**\n     * Controls how the initial batch is committed.\n     *\n     * - `\"sync\"` (default): the first `@batchSize` items render in the\n     *   same render pass as mount / `@items` change. The user sees\n     *   content on the very first paint, and the rest of the list\n     *   fills in one batch per animation frame. This is the right\n     *   default for most lists — even a perceived \"empty for one\n     *   frame\" is worse than rendering a few extra items synchronously.\n     * - `\"lazy\"`: even the first batch waits for an animation frame, so\n     *   the initial paint is empty and content arrives one batch per\n     *   frame. Use this when the first batch itself would be expensive\n     *   enough to block the first paint, and you'd rather show an\n     *   empty container than delay it.\n     *\n     * Default: `\"sync\"`.\n     *\n     * ```gjs\n     * import { IncrementalEach } from 'ember-primitives';\n     *\n     * <template>\n     *   <IncrementalEach @items={{this.rows}} @initial=\"lazy\" as |row|>\n     *     <my-row @row={{row}} />\n     *   </IncrementalEach>\n     * </template>\n     * ```\n     */\n    initial?: \"sync\" | \"lazy\";\n\n    /**\n     * Called once with no arguments when every item in `@items` has\n     * been committed to the DOM. Fires after the final batch lands;\n     * does not fire on intermediate batches.\n     *\n     * Fires again on a fresh swap (new `@items` identity) once that\n     * new collection finishes rendering. An empty `@items` array\n     * does not fire the callback.\n     *\n     * Useful for marking the list as ready for screenshot tests,\n     * dismissing a loading indicator, or measuring how long the\n     * whole render took.\n     *\n     * ```gjs\n     * import { IncrementalEach } from 'ember-primitives';\n     *\n     * <template>\n     *   <IncrementalEach @items={{this.rows}} @onDone={{this.handleDone}} as |row|>\n     *     <my-row @row={{row}} />\n     *   </IncrementalEach>\n     * </template>\n     * ```\n     */\n    onDone?: () => void;\n  };\n  Blocks: {\n    /**\n     * Yielded for each rendered item, with the index in the original\n     * `@items` array.\n     *\n     * ```gjs\n     * import { IncrementalEach } from 'ember-primitives';\n     *\n     * <template>\n     *   <IncrementalEach @items={{this.rows}} as |row index|>\n     *     {{index}}: {{row.label}}\n     *   </IncrementalEach>\n     * </template>\n     * ```\n     */\n    default: [item: T, index: number];\n  };\n}\n\n/**\n * A drop-in replacement for `{{#each}}` that renders a large collection\n * a batch at a time on each animation frame, instead of all at once.\n *\n * Every item ends up in the DOM, so browser find (Ctrl+F / Cmd+F), anchor\n * links, screen readers, print, and SEO all work against the full list.\n * Yielding the main thread between batches keeps the page responsive while\n * the rest of the list is filling in.\n *\n * By default the first batch lands synchronously, so the user sees content\n * on the very first paint. Pass `@initial=\"lazy\"` to defer the first batch\n * to an animation frame as well.\n *\n * Intended for non-scrollable containers, or anywhere a virtual/windowed\n * list does not apply (variable item heights, lists that grow the page,\n * surfaces that need every row indexable).\n *\n * Do not nest one `<IncrementalEach>` inside another. Each level adds an\n * animation-frame delay before its content paints; nesting compounds those\n * delays, so inner rows appear to flicker in with missing sub-content.\n * If you have nested loops, only the outermost one should be\n * `<IncrementalEach>`; leave deeper loops as plain `{{#each}}`.\n *\n * @example\n * ```gjs\n * import { IncrementalEach } from 'ember-primitives';\n *\n * <template>\n *   <ul>\n *     <IncrementalEach @items={{this.rows}} @batchSize={{100}} as |row index|>\n *       <li>{{index}}: {{row.label}}</li>\n *     </IncrementalEach>\n *   </ul>\n * </template>\n * ```\n */\nexport class IncrementalEach<T = unknown> extends Component<Signature<T>> {\n  #count = cell(0);\n  #itemsRef: readonly T[] | null = null;\n  #waiterToken: unknown = null;\n  #doneFor: object | null = null;\n\n  constructor(owner: Owner, args: Signature<T>[\"Args\"]) {\n    super(owner, args);\n\n    registerDestructor(this, () => this.#endWaiter());\n  }\n\n  // Reset progress and (re)open the test-waiter when `@items` identity\n  // changes, so a swap restarts at the first batch, `@onDone` can fire\n  // again for the new collection, and `await settled()` knows to wait\n  // until `checkDone` closes the waiter. Mutating from a getter is safe\n  // here because the writes happen before any consumer reads them in\n  // the same render pass.\n  /* eslint-disable ember/no-side-effects */\n  get #items(): readonly T[] {\n    const items = this.args.items;\n\n    assert(`@items must be an array`, items);\n\n    if (items !== this.#itemsRef) {\n      this.#itemsRef = items;\n      this.#count.current = 0;\n      this.#endWaiter();\n\n      if (items.length > 0) {\n        this.#waiterToken = waiter.beginAsync();\n      }\n    }\n\n    return items;\n  }\n  /* eslint-enable ember/no-side-effects */\n\n  // `\"sync\"` keeps bucket 0 visible at count=0 (`i = 0 >= 0`); `\"lazy\"`\n  // starts one step behind so even bucket 0 needs a tick.\n  get #start() {\n    return this.#initial === \"sync\" ? 0 : -1;\n  }\n\n  get i() {\n    return this.#start + this.#count.current;\n  }\n\n  @cached\n  get bucketed() {\n    const size = this.#batchSize;\n\n    return chunk(this.#items, size).map((items, b) => {\n      const start = b * size;\n\n      return {\n        isReady: () => this.i >= b,\n        items: items.map((value, j) => ({ value, index: start + j })),\n      };\n    });\n  }\n\n  get #batchSize(): number {\n    const requested = this.args.batchSize ?? DEFAULT_BATCH_SIZE;\n\n    assert(\n      `<IncrementalEach> @batchSize must be a positive number, got ${requested}`,\n      requested > 0,\n    );\n\n    return requested;\n  }\n\n  get #initial(): \"sync\" | \"lazy\" {\n    const requested = this.args.initial ?? DEFAULT_INITIAL;\n\n    assert(\n      `<IncrementalEach> @initial must be \"sync\" or \"lazy\", got ${requested}`,\n      requested === \"sync\" || requested === \"lazy\",\n    );\n\n    return requested;\n  }\n\n  // `#items` is read before `#count` so the count-reset inside `#items`\n  // (on `@items` swap) lands before this read of count this render —\n  // otherwise tracked-value backtracking asserts.\n  tick = () => {\n    if (this.#items.length > this.#count.current) {\n      requestIdleCallback(() => this.#count.current++, { timeout: 10 });\n    }\n  };\n\n  checkDone = () => {\n    const bucketed = this.bucketed;\n\n    if (this.#doneFor === bucketed) return;\n    if (this.i < bucketed.length - 1) return;\n\n    this.#doneFor = bucketed;\n    queueMicrotask(() => {\n      if (isDestroyed(this) || isDestroying(this)) return;\n      this.args.onDone?.();\n      this.#endWaiter();\n    });\n  };\n\n  #endWaiter() {\n    if (this.#waiterToken) waiter.endAsync(this.#waiterToken);\n  }\n\n  <template>\n    {{(this.tick)}}{{#each this.bucketed as |bucket|}}{{#if (bucket.isReady)}}{{#each\n          bucket.items\n          as |entry|\n        }}{{yield entry.value entry.index}}{{/each}}{{(this.checkDone)}}{{/if}}{{/each}}\n  </template>\n}\n"],"names":["DEFAULT_BATCH_SIZE","DEFAULT_INITIAL","waiter","buildWaiter","chunk","arr","size","out","i","length","push","slice","IncrementalEach","Component","cell","constructor","owner","args","registerDestructor","#items","items","assert","current","beginAsync","#start","bucketed","map","b","start","isReady","value","j","index","n","prototype","cached","#batchSize","requested","batchSize","#initial","initial","tick","requestIdleCallback","timeout","checkDone","queueMicrotask","isDestroyed","isDestroying","onDone","#endWaiter","endAsync","setComponentTemplate","precompileTemplate","strictMode"],"mappings":";;;;;;;;;;AAUA,MAAMA,kBAAA,GAAqB,EAAA;AAC3B,MAAMC,eAAA,GAAkB,MAAA;AAExB,MAAMC,SAASC,WAAA,CAAY,mCAAA,CAAA;AAE3B,SAASC,MAASC,GAAiB,EAAEC,IAAY,EAAG;EAClD,MAAMC,MAAa,EAAE;AAErB,EAAA,KAAK,IAAIC,IAAI,CAAA,EAAGA,CAAA,GAAIH,IAAII,MAAM,EAAED,KAAKF,IAAA,EAAM;AACzCC,IAAAA,GAAA,CAAIG,IAAI,CAACL,GAAA,CAAIM,KAAK,CAACH,GAAGA,CAAA,GAAIF,IAAA,CAAA,CAAA;AAC5B,EAAA;AAEA,EAAA,OAAOC,GAAA;AACT;AAmHA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCC;AACM,MAAMK,eAAA,SAAqCC,UAAoB;AACpE,EAAA,MAAM,GAAGC,IAAA,CAAK,CAAA,CAAA;EACd,SAAS,GAAwB,IAAA;EACjC,YAAY,GAAY,IAAA;EACxB,QAAQ,GAAkB,IAAA;AAE1BC,EAAAA,WAAAA,CAAYC,KAAY,EAAEC,IAA0B,EAAE;AACpD,IAAA,KAAK,CAACD,KAAA,EAAOC,IAAA,CAAA;IAEbC,kBAAA,CAAmB,IAAI,EAAE,MAAM,IAAI,CAAC,UAAU,EAAA,CAAA;AAChD,EAAA;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;EACA,IAAI,MAAMC,GAAa;AACrB,IAAA,MAAMC,KAAA,GAAQ,IAAI,CAACH,IAAI,CAACG,KAAK;AAE7BC,IAAAA,MAAA,CAAO,CAAA,uBAAA,CAAyB,EAAED,KAAA,CAAA;AAElC,IAAA,IAAIA,KAAA,KAAU,IAAI,CAAC,SAAS,EAAE;AAC5B,MAAA,IAAI,CAAC,SAAS,GAAGA,KAAA;AACjB,MAAA,IAAI,CAAC,MAAM,CAACE,OAAO,GAAG,CAAA;AACtB,MAAA,IAAI,CAAC,UAAU,EAAA;AAEf,MAAA,IAAIF,KAAA,CAAMX,MAAM,GAAG,CAAA,EAAG;QACpB,IAAI,CAAC,YAAY,GAAGP,OAAOqB,UAAU,EAAA;AACvC,MAAA;AACF,IAAA;AAEA,IAAA,OAAOH,KAAA;AACT,EAAA;;AAIA;EACA,IAAI,MAAMI,GAAA;IACR,OAAO,IAAI,CAAC,QAAQ,KAAK,MAAA,GAAS,IAAI,EAAC;AACzC,EAAA;EAEA,IAAIhB,CAAAA,GAAI;IACN,OAAO,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAACc,OAAO;AAC1C,EAAA;EAEA,IACIG,QAAAA,GAAW;AACb,IAAA,MAAMnB,IAAA,GAAO,IAAI,CAAC,UAAU;AAE5B,IAAA,OAAOF,KAAA,CAAM,IAAI,CAAC,MAAM,EAAEE,IAAA,CAAA,CAAMoB,GAAG,CAAC,CAACN,KAAA,EAAOO,CAAA,KAAA;AAC1C,MAAA,MAAMC,QAAQD,CAAA,GAAIrB,IAAA;MAElB,OAAO;AACLuB,QAAAA,OAAA,EAASA,MAAM,IAAI,CAACrB,CAAC,IAAImB,CAAA;QACzBP,KAAA,EAAOA,MAAMM,GAAG,CAAC,CAACI,KAAA,EAAOC,OAAO;UAAED,KAAA;UAAOE,KAAA,EAAOJ,KAAA,GAAQG;AAAE,SAAC,CAAA;OAC7D;AACF,IAAA,CAAA,CAAA;AACF,EAAA;AAAA,EAAA;IAAAE,CAAA,CAAA,IAAA,CAAAC,SAAA,EAAA,UAAA,EAAA,CAZCC,MAAA,CAAA,CAAA;AAAA;EAcD,IAAI,UAAUC,GAAU;IACtB,MAAMC,YAAY,IAAI,CAACpB,IAAI,CAACqB,SAAS,IAAItC,kBAAA;IAEzCqB,MAAA,CACE,+DAA+DgB,SAAA,CAAA,CAAW,EAC1EA,SAAA,GAAY,CAAA,CAAA;AAGd,IAAA,OAAOA,SAAA;AACT,EAAA;EAEA,IAAI,QAAQE,GAAa;IACvB,MAAMF,YAAY,IAAI,CAACpB,IAAI,CAACuB,OAAO,IAAIvC,eAAA;AAEvCoB,IAAAA,MAAA,CACE,CAAA,yDAAA,EAA4DgB,SAAA,CAAA,CAAW,EACvEA,SAAA,KAAc,UAAUA,SAAA,KAAc,MAAA,CAAA;AAGxC,IAAA,OAAOA,SAAA;AACT,EAAA;AAEA;AACA;AACA;EACAI,IAAA,GAAOA,MAAA;AACL,IAAA,IAAI,IAAI,CAAC,MAAM,CAAChC,MAAM,GAAG,IAAI,CAAC,MAAM,CAACa,OAAO,EAAE;MAC5CoB,mBAAA,CAAoB,MAAM,IAAI,CAAC,MAAM,CAACpB,OAAO,EAAA,EAAI;AAAEqB,QAAAA,OAAA,EAAS;AAAG,OAAA,CAAA;AACjE,IAAA;EACF,CAAA;EAEAC,SAAA,GAAYA,MAAA;AACV,IAAA,MAAMnB,QAAA,GAAW,IAAI,CAACA,QAAQ;AAE9B,IAAA,IAAI,IAAI,CAAC,QAAQ,KAAKA,QAAA,EAAU;IAChC,IAAI,IAAI,CAACjB,CAAC,GAAGiB,QAAA,CAAShB,MAAM,GAAG,CAAA,EAAG;AAElC,IAAA,IAAI,CAAC,QAAQ,GAAGgB,QAAA;AAChBoB,IAAAA,cAAA,CAAe,MAAA;MACb,IAAIC,WAAA,CAAY,IAAI,CAAA,IAAKC,YAAA,CAAa,IAAI,CAAA,EAAG;AAC7C,MAAA,IAAI,CAAC9B,IAAI,CAAC+B,MAAM,IAAA;AAChB,MAAA,IAAI,CAAC,UAAU,EAAA;AACjB,IAAA,CAAA,CAAA;EACF,CAAA;EAEA,UAAUC,GAAA;AACR,IAAA,IAAI,IAAI,CAAC,YAAY,EAAE/C,MAAA,CAAOgD,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAA;AAC1D,EAAA;AAEA,EAAA;IAAAC,oBAAA,CAAAC,kBAAA,CAAA,2LAAA,EAKA;MAAAC,UAAA,EAAA;KAAU,CAAA,EAAV,IAAW,CAAA;AAAD;AACZ;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ember-primitives",
-  "version": "0.58.0",
+  "version": "0.59.0",
   "description": "Making apps easier to build",
   "keywords": [
     "ember-addon"

package/src/components/incremental-each.gts

@@ -1,4 +1,5 @@
 import Component from "@glimmer/component";
+import { cached } from "@glimmer/tracking";
 import { assert } from "@ember/debug";
 import { isDestroyed, isDestroying, registerDestructor } from "@ember/destroyable";
 import { buildWaiter } from "@ember/test-waiters";
@@ -8,9 +9,20 @@ import { cell } from "ember-resources";
 import type Owner from "@ember/owner";
 
 const DEFAULT_BATCH_SIZE = 50;
+const DEFAULT_INITIAL = "sync";
 
 const waiter = buildWaiter("ember-primitives:incremental-each");
 
+function chunk<T>(arr: readonly T[], size: number): T[][] {
+  const out: T[][] = [];
+
+  for (let i = 0; i < arr.length; i += size) {
+    out.push(arr.slice(i, i + size));
+  }
+
+  return out;
+}
+
 export interface Signature<T = unknown> {
   Args: {
     /**
@@ -32,7 +44,7 @@ export interface Signature<T = unknown> {
     items: readonly T[];
 
     /**
-     * How many items to add per idle callback.
+     * How many items to add per animation frame.
      *
      * Larger batches add more items per chunk; smaller batches yield to
      * the browser more often.
@@ -50,6 +62,60 @@ export interface Signature<T = unknown> {
      * ```
      */
     batchSize?: number;
+
+    /**
+     * Controls how the initial batch is committed.
+     *
+     * - `"sync"` (default): the first `@batchSize` items render in the
+     *   same render pass as mount / `@items` change. The user sees
+     *   content on the very first paint, and the rest of the list
+     *   fills in one batch per animation frame. This is the right
+     *   default for most lists — even a perceived "empty for one
+     *   frame" is worse than rendering a few extra items synchronously.
+     * - `"lazy"`: even the first batch waits for an animation frame, so
+     *   the initial paint is empty and content arrives one batch per
+     *   frame. Use this when the first batch itself would be expensive
+     *   enough to block the first paint, and you'd rather show an
+     *   empty container than delay it.
+     *
+     * Default: `"sync"`.
+     *
+     * ```gjs
+     * import { IncrementalEach } from 'ember-primitives';
+     *
+     * <template>
+     *   <IncrementalEach @items={{this.rows}} @initial="lazy" as |row|>
+     *     <my-row @row={{row}} />
+     *   </IncrementalEach>
+     * </template>
+     * ```
+     */
+    initial?: "sync" | "lazy";
+
+    /**
+     * Called once with no arguments when every item in `@items` has
+     * been committed to the DOM. Fires after the final batch lands;
+     * does not fire on intermediate batches.
+     *
+     * Fires again on a fresh swap (new `@items` identity) once that
+     * new collection finishes rendering. An empty `@items` array
+     * does not fire the callback.
+     *
+     * Useful for marking the list as ready for screenshot tests,
+     * dismissing a loading indicator, or measuring how long the
+     * whole render took.
+     *
+     * ```gjs
+     * import { IncrementalEach } from 'ember-primitives';
+     *
+     * <template>
+     *   <IncrementalEach @items={{this.rows}} @onDone={{this.handleDone}} as |row|>
+     *     <my-row @row={{row}} />
+     *   </IncrementalEach>
+     * </template>
+     * ```
+     */
+    onDone?: () => void;
   };
   Blocks: {
     /**
@@ -71,18 +137,28 @@ export interface Signature<T = unknown> {
 }
 
 /**
- * A drop-in replacement for `{{#each}}` that renders a large collection a
- * batch at a time during the browser's idle periods, instead of all at once.
+ * A drop-in replacement for `{{#each}}` that renders a large collection
+ * a batch at a time on each animation frame, instead of all at once.
  *
  * Every item ends up in the DOM, so browser find (Ctrl+F / Cmd+F), anchor
  * links, screen readers, print, and SEO all work against the full list.
  * Yielding the main thread between batches keeps the page responsive while
  * the rest of the list is filling in.
  *
+ * By default the first batch lands synchronously, so the user sees content
+ * on the very first paint. Pass `@initial="lazy"` to defer the first batch
+ * to an animation frame as well.
+ *
  * Intended for non-scrollable containers, or anywhere a virtual/windowed
  * list does not apply (variable item heights, lists that grow the page,
  * surfaces that need every row indexable).
  *
+ * Do not nest one `<IncrementalEach>` inside another. Each level adds an
+ * animation-frame delay before its content paints; nesting compounds those
+ * delays, so inner rows appear to flicker in with missing sub-content.
+ * If you have nested loops, only the outermost one should be
+ * `<IncrementalEach>`; leave deeper loops as plain `{{#each}}`.
+ *
  * @example
  * ```gjs
  * import { IncrementalEach } from 'ember-primitives';
@@ -97,109 +173,120 @@ export interface Signature<T = unknown> {
  * ```
  */
 export class IncrementalEach<T = unknown> extends Component<Signature<T>> {
-  // How many items have been committed to the DOM so far. Bumped one
-  // batch at a time by the idle callback. Wrapped in a `cell` because
-  // `@tracked` doesn't compose with `#`-private fields under this
-  // codebase's decorator transform.
   #count = cell(0);
-
-  // Plain field so identity checks don't add a render-time dependency
-  // on top of `args.items`.
   #itemsRef: readonly T[] | null = null;
-
-  #idleHandle: number | null = null;
-
   #waiterToken: unknown = null;
+  #doneFor: object | null = null;
 
   constructor(owner: Owner, args: Signature<T>["Args"]) {
     super(owner, args);
 
-    registerDestructor(this, () => this.#cancel());
+    registerDestructor(this, () => this.#endWaiter());
   }
 
-  get #batchSize(): number {
-    const requested = this.args.batchSize ?? DEFAULT_BATCH_SIZE;
-
-    assert(
-      `<IncrementalEach> @batchSize must be a positive number, got ${requested}`,
-      requested > 0,
-    );
-
-    return requested;
-  }
-
-  // The items that should currently be rendered. `@cached` keeps the
-  // returned slice stable across renders that don't change `#count` or
-  // `args.items`, so Glimmer's `{{#each}}` doesn't see a fresh array on
-  // every render and we only slice once per batch landing. This is
-  // also where scheduling is driven from: `@items` identity changes
-  // reset `#count` to zero, and missing items queue the next idle
-  // callback. Autotrack stays consistent because the only synchronous
-  // write here (`#count = 0`) happens before `#count` is read.
+  // Reset progress and (re)open the test-waiter when `@items` identity
+  // changes, so a swap restarts at the first batch, `@onDone` can fire
+  // again for the new collection, and `await settled()` knows to wait
+  // until `checkDone` closes the waiter. Mutating from a getter is safe
+  // here because the writes happen before any consumer reads them in
+  // the same render pass.
   /* eslint-disable ember/no-side-effects */
-  get visible(): readonly T[] {
-    const items = this.args.items ?? [];
+  get #items(): readonly T[] {
+    const items = this.args.items;
+
+    assert(`@items must be an array`, items);
 
     if (items !== this.#itemsRef) {
       this.#itemsRef = items;
-      this.#cancel();
       this.#count.current = 0;
-    }
+      this.#endWaiter();
 
-    if (this.#count.current < items.length && this.#idleHandle === null) {
-      this.#scheduleNextBatch();
+      if (items.length > 0) {
+        this.#waiterToken = waiter.beginAsync();
+      }
     }
 
-    return items.slice(0, this.#count.current);
+    return items;
   }
   /* eslint-enable ember/no-side-effects */
 
-  #scheduleNextBatch() {
-    // Defensive: if a batch is already pending, drop it before
-    // queueing a new one. The `visible` getter already guards on
-    // `#idleHandle === null`, but a future caller might not.
-    this.#cancel();
+  // `"sync"` keeps bucket 0 visible at count=0 (`i = 0 >= 0`); `"lazy"`
+  // starts one step behind so even bucket 0 needs a tick.
+  get #start() {
+    return this.#initial === "sync" ? 0 : -1;
+  }
 
-    this.#waiterToken = waiter.beginAsync();
+  get i() {
+    return this.#start + this.#count.current;
+  }
 
-    // The `timeout` cap ensures forward progress even when the host
-    // is CPU-bound and the browser never reports a free idle slot.
-    // In normal use this is a no-op because real idle time arrives
-    // far sooner.
-    this.#idleHandle = requestIdleCallback(
-      () => {
-        this.#idleHandle = null;
+  @cached
+  get bucketed() {
+    const size = this.#batchSize;
 
-        if (isDestroyed(this) || isDestroying(this)) return;
+    return chunk(this.#items, size).map((items, b) => {
+      const start = b * size;
 
-        const items = this.args.items ?? [];
+      return {
+        isReady: () => this.i >= b,
+        items: items.map((value, j) => ({ value, index: start + j })),
+      };
+    });
+  }
+
+  get #batchSize(): number {
+    const requested = this.args.batchSize ?? DEFAULT_BATCH_SIZE;
 
-        this.#count.current = Math.min(this.#count.current + this.#batchSize, items.length);
-        this.#endWaiter();
-      },
-      { timeout: 100 },
+    assert(
+      `<IncrementalEach> @batchSize must be a positive number, got ${requested}`,
+      requested > 0,
     );
+
+    return requested;
   }
 
-  #cancel() {
-    if (this.#idleHandle !== null) {
-      cancelIdleCallback(this.#idleHandle);
-      this.#idleHandle = null;
-    }
+  get #initial(): "sync" | "lazy" {
+    const requested = this.args.initial ?? DEFAULT_INITIAL;
+
+    assert(
+      `<IncrementalEach> @initial must be "sync" or "lazy", got ${requested}`,
+      requested === "sync" || requested === "lazy",
+    );
 
-    this.#endWaiter();
+    return requested;
   }
 
-  #endWaiter() {
-    if (this.#waiterToken !== null) {
-      waiter.endAsync(this.#waiterToken);
-      this.#waiterToken = null;
+  // `#items` is read before `#count` so the count-reset inside `#items`
+  // (on `@items` swap) lands before this read of count this render —
+  // otherwise tracked-value backtracking asserts.
+  tick = () => {
+    if (this.#items.length > this.#count.current) {
+      requestIdleCallback(() => this.#count.current++, { timeout: 10 });
     }
+  };
+
+  checkDone = () => {
+    const bucketed = this.bucketed;
+
+    if (this.#doneFor === bucketed) return;
+    if (this.i < bucketed.length - 1) return;
+
+    this.#doneFor = bucketed;
+    queueMicrotask(() => {
+      if (isDestroyed(this) || isDestroying(this)) return;
+      this.args.onDone?.();
+      this.#endWaiter();
+    });
+  };
+
+  #endWaiter() {
+    if (this.#waiterToken) waiter.endAsync(this.#waiterToken);
   }
 
   <template>
-    {{#each this.visible as |item index|}}
-      {{yield item index}}
-    {{/each}}
+    {{(this.tick)}}{{#each this.bucketed as |bucket|}}{{#if (bucket.isReady)}}{{#each
+          bucket.items
+          as |entry|
+        }}{{yield entry.value entry.index}}{{/each}}{{(this.checkDone)}}{{/if}}{{/each}}
   </template>
 }