defenUntil() + fix legacy FLD support

Fixes #19380

Author: brandonkelly

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Release Notes for Craft CMS 6
 
+## Unreleased
+
+- Fixed a JavaScript error that occurred on non-Inertial pages that rendered field layout designers. ([#19380]())
+
 ## 6.0.0-alpha.16 - 2026-08-05
 
 - Fixed a bug where Yii-style migrations could be required twice. ([#19376](https://github.com/craftcms/cms/pull/19376))

packages/craftcms-garnish/src/utils/index.ts

@@ -75,6 +75,7 @@ export {
   isArray,
   isPlainObject,
   isTextNode,
+  deferUntil,
   log,
   handleActivatingKeypress,
 } from './misc';

packages/craftcms-garnish/src/utils/misc.ts

@@ -72,6 +72,48 @@ export function log(msg: unknown): void {
   }
 }
 
+/**
+ * Resolves once `test()` returns a truthy value, calling it again every
+ * `delay` milliseconds in the meantime.
+ *
+ * `test` may return a promise; its resolved value is awaited before being
+ * checked for truthiness, and the next call isn’t scheduled until it settles.
+ * A rejection/throw from `test()` propagates, rejecting the returned promise.
+ *
+ * @param test A function to call repeatedly until it returns (or resolves to) a truthy value.
+ * @param delay The interval, in milliseconds, between calls (default `100`).
+ * @param signal An optional `AbortSignal`. If already aborted, or aborted while
+ * waiting for the next call, the returned promise rejects with `signal.reason`
+ * instead of continuing to poll — use this to stop polling once a caller (e.g.
+ * an owning class' `destroy()`) no longer cares about the result.
+ * @returns A promise that resolves with `test()`’s truthy return value.
+ */
+export async function deferUntil<T>(
+  test: () => T | Promise<T>,
+  delay = 100,
+  signal?: AbortSignal
+): Promise<T> {
+  if (signal?.aborted) {
+    throw signal.reason;
+  }
+  const result = await test();
+  if (result) {
+    return result;
+  }
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(resolve, delay);
+    signal?.addEventListener(
+      'abort',
+      () => {
+        clearTimeout(timer);
+        reject(signal.reason);
+      },
+      {once: true}
+    );
+  });
+  return deferUntil(test, delay, signal);
+}
+
 /**
  * Space/Enter → preventDefault + callback.
  * @deprecated The `activate` event should be used instead.

packages/craftcms-garnish/tests/utils.test.ts

@@ -1,6 +1,12 @@
 import {describe, expect, it} from 'vite-plus/test';
 
-import {getDist, within, isString, isTextNode} from '../src/utils/misc';
+import {
+  getDist,
+  within,
+  isString,
+  isTextNode,
+  deferUntil,
+} from '../src/utils/misc';
 import {getInputPostVal, getPostData, findInputs} from '../src/utils/forms';
 import {hasAttr, nearestSibling, closestRegistered} from '../src/utils/dom';
 
@@ -21,6 +27,52 @@ describe('misc utils', () => {
     expect(isTextNode(document.createTextNode('x'))).toBe(true);
     expect(isTextNode(document.createElement('div'))).toBe(false);
   });
+  it('deferUntil resolves immediately if test() is already truthy', async () => {
+    const test = () => 'ready';
+    expect(await deferUntil(test)).toBe('ready');
+  });
+  it('deferUntil polls test() at the given interval until it’s truthy', async () => {
+    let calls = 0;
+    const test = () => (++calls >= 3 ? calls : false);
+    expect(await deferUntil(test, 5)).toBe(3);
+    expect(calls).toBe(3);
+  });
+  it('deferUntil awaits an async test() before checking truthiness', async () => {
+    let calls = 0;
+    const test = async () => {
+      calls++;
+      return calls >= 2;
+    };
+    expect(await deferUntil(test, 5)).toBe(true);
+    expect(calls).toBe(2);
+  });
+  it('deferUntil rejects if test() throws', async () => {
+    const test = () => {
+      throw new Error('nope');
+    };
+    await expect(deferUntil(test, 5)).rejects.toThrow('nope');
+  });
+  it('deferUntil rejects immediately if the signal is already aborted', async () => {
+    const controller = new AbortController();
+    controller.abort(new Error('cancelled'));
+    const test = () => true;
+    await expect(deferUntil(test, 5, controller.signal)).rejects.toThrow(
+      'cancelled'
+    );
+  });
+  it('deferUntil rejects if the signal aborts while waiting to poll again', async () => {
+    const controller = new AbortController();
+    const test = () => false;
+    const promise = deferUntil(test, 20, controller.signal);
+    setTimeout(() => controller.abort(new Error('cancelled')), 5);
+    await expect(promise).rejects.toThrow('cancelled');
+  });
+  it('deferUntil stops polling once truthy, even with a signal attached', async () => {
+    const controller = new AbortController();
+    let calls = 0;
+    const test = () => (++calls >= 2 ? calls : false);
+    expect(await deferUntil(test, 5, controller.signal)).toBe(2);
+  });
 });
 
 describe('dom utils', () => {

resources/js/modules/field-layout-designer/field-layout-designer.ts

@@ -1,5 +1,6 @@
 import {
   Base,
+  deferUntil,
   ESC_KEY,
   type GarnishEvent,
   hasAttr,
@@ -111,6 +112,13 @@ export class FieldLayoutDesigner extends Base<FieldLayoutDesignerSettings> {
     if (this.settings!.readOnly) {
       this.$fieldLibrary.setAttribute('tabindex', '-1');
     }
+
+    deferUntil(() => !!Craft?.Grid).then(() => {
+      this.deferredInit();
+    });
+  }
+
+  deferredInit(): void {
     // Set up the layout grids — Craft.Grid is a jQuery seam.
     this.tabGrid = new Craft.Grid($(this.$tabContainer), {
       itemSelector: '.fld-tab',

resources/js/modules/matrix/matrix-entry.ts

@@ -7,7 +7,7 @@
  * `elements/update-field-layout` driven by a `Craft.FormObserver`.
  */
 
-import {Base, getInputPostVal, hasAttr} from '@craftcms/garnish';
+import {Base, deferUntil, getInputPostVal, hasAttr} from '@craftcms/garnish';
 import {t} from '@craftcms/ui';
 import {escapeHtml} from '@craftcms/ui/utilities/escapeHtml';
 import {animationDuration, MatrixInput} from './matrix-input';
@@ -189,11 +189,11 @@ export class MatrixEntry extends Base {
     this.visibleLayoutElements = this.dataJson('visible-layout-elements');
     this.staticLayoutElements = this.dataJson('static-layout-elements');
 
-    setTimeout(() => {
+    deferUntil(() => !!craft().FormObserver).then(() => {
       this.formObserver = new (craft().FormObserver)(container, (data) => {
         this.updateFieldLayout(data);
       });
-    }, 1);
+    });
   }
 
   /** Reads a JSON-ish data attribute the way jQuery `.data()` did. */

resources/js/modules/matrix/matrix-input.ts

@@ -17,6 +17,7 @@ import {
   Base,
   DragSort,
   type GarnishBaseSettings,
+  deferUntil,
   firstFocusableElement,
   prefersReducedMotion,
   scrollContainerToElement,
@@ -136,6 +137,8 @@ export class MatrixInput extends Base<MatrixInputSettings> {
   entrySelect: LegacySelect | null = null;
 
   elementEditor: LegacyElementEditor | null = null;
+  /** Aborts the after-init `elementEditor` lookup on `destroy()`. */
+  private elementEditorController: AbortController | null = null;
 
   addingEntry = false;
 
@@ -288,26 +291,41 @@ export class MatrixInput extends Base<MatrixInputSettings> {
 
     this.updateAddEntryBtn();
 
-    setTimeout(() => {
-      this.elementEditor = this.form
-        ? ((jqData(this.form, 'elementEditor') as LegacyElementEditor) ?? null)
-        : null;
-
-      if (this.elementEditor) {
-        this.elementEditor.on('update', () => {
-          this.settings!.ownerId = this.elementEditor!.getDraftElementId(
-            this.settings!.ownerId
-          ) as MatrixInputSettings['ownerId'];
-        });
-      }
+    // The owner's element editor boots after this input does; keep checking
+    // until it's attached (legacy parity: the poll interval mirrors the old
+    // fixed delay, but retries instead of gambling on a single check).
+    const finishInit = (elementEditor: LegacyElementEditor | null): void => {
+      this.elementEditor = elementEditor;
+      this.elementEditor?.on('update', () => {
+        this.settings!.ownerId = this.elementEditor!.getDraftElementId(
+          this.settings!.ownerId
+        ) as MatrixInputSettings['ownerId'];
+      });
 
       this.trigger('afterInit');
 
       const defaultEntries = this.settings!.addDefaultEntries;
       if (defaultEntries && defaultEntries.count > 0) {
         void this.addDefaultEntries(defaultEntries.type, defaultEntries.count);
       }
-    }, 100);
+    };
+
+    this.elementEditorController = new AbortController();
+
+    const form = this.form;
+    if (form) {
+      deferUntil(
+        () => jqData(form, 'elementEditor') as LegacyElementEditor | undefined,
+        100,
+        this.elementEditorController.signal
+      )
+        .then((elementEditor) => finishInit(elementEditor ?? null))
+        .catch(() => {
+          // Destroyed before the editor showed up — nothing left to do.
+        });
+    } else {
+      finishInit(null);
+    }
 
     // If this field is nested within something that's deletable, be ready to
     // handle that
@@ -698,6 +716,9 @@ export class MatrixInput extends Base<MatrixInputSettings> {
   }
 
   override destroy(): void {
+    this.elementEditorController?.abort();
+    this.elementEditorController = null;
+
     this.entrySort?.destroy();
     this.entrySelect?.destroy();
     this.entrySort = null;

resources/js/modules/nested-element-manager/nested-element-manager.ts

@@ -2,6 +2,7 @@ import {
   Base,
   DragSort,
   Select,
+  deferUntil,
   firstFocusableElement,
   hasAttr,
   isCtrlKeyPressed,
@@ -175,7 +176,8 @@ export class NestedElementManager extends Base<NestedElementManagerSettings> {
   #activateBound: any[] = [];
   /** Teardown callbacks for per-card native listeners (delete items, …). */
   #disposers: Array<() => void> = [];
-  #afterInitTimeout: ReturnType<typeof setTimeout> | null = null;
+  /** Aborts the after-init `elementEditor` lookup on `destroy()`. */
+  #afterInitController: AbortController | null = null;
 
   constructor(
     container: HTMLElement | string,
@@ -235,28 +237,39 @@ export class NestedElementManager extends Base<NestedElementManagerSettings> {
       this.#initCreateButton();
     }
 
-    // The owner's element editor boots after this manager does; look it up a
-    // beat later (legacy parity, including the delay).
-    this.#afterInitTimeout = setTimeout(() => {
-      this.elementEditor = $(this.container)
-        .closest('form')
-        .data('elementEditor');
-
-      if (this.elementEditor) {
-        this.elementEditor.on('update', () => {
-          this.settings.ownerId = this.elementEditor.getDraftElementId(
-            this.settings.ownerId
-          );
+    // The owner's element editor boots after this manager does; keep checking
+    // until it's attached (legacy parity: the poll interval mirrors the old
+    // fixed delay, but retries instead of gambling on a single check).
+    const $form = $(this.container).closest('form');
+    this.#afterInitController = new AbortController();
+
+    if ($form.length) {
+      deferUntil(
+        () => $form.data('elementEditor'),
+        100,
+        this.#afterInitController.signal
+      )
+        .then((elementEditor) => {
+          this.elementEditor = elementEditor;
+          this.elementEditor.on('update', () => {
+            this.settings.ownerId = this.elementEditor.getDraftElementId(
+              this.settings.ownerId
+            );
+
+            if (this.elementIndex) {
+              this.elementIndex.settings.criteria[this.settings.ownerIdParam!] =
+                this.settings.ownerId;
+            }
+          });
 
-          if (this.elementIndex) {
-            this.elementIndex.settings.criteria[this.settings.ownerIdParam!] =
-              this.settings.ownerId;
-          }
+          this.trigger('afterInit');
+        })
+        .catch(() => {
+          // Destroyed before the editor showed up — nothing left to do.
         });
-      }
-
+    } else {
       this.trigger('afterInit');
-    }, 100);
+    }
 
     // NOTE: `Craft.cp` has no unregister API for this; the callback holds this
     // instance until the page unloads (legacy parity — see README).
@@ -1355,10 +1368,8 @@ export class NestedElementManager extends Base<NestedElementManagerSettings> {
   // --- Teardown ---------------------------------------------------------------
 
   override destroy(): void {
-    if (this.#afterInitTimeout !== null) {
-      clearTimeout(this.#afterInitTimeout);
-      this.#afterInitTimeout = null;
-    }
+    this.#afterInitController?.abort();
+    this.#afterInitController = null;
 
     for (const $bound of this.#activateBound) {
       $bound.off('activate');